{"id":37228366,"url":"https://github.com/mattdef/dampen","last_synced_at":"2026-01-31T12:03:22.945Z","repository":{"id":331994857,"uuid":"1126188552","full_name":"mattdef/dampen","owner":"mattdef","description":"A declarative UI framework for Rust with Iced backend, featuring hot-reload development and production code generation.","archived":false,"fork":false,"pushed_at":"2026-01-22T07:43:09.000Z","size":15943,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-22T10:21:03.651Z","etag":null,"topics":["framework","iced-rs","rust","ui-design"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattdef.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-Apache","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T10:41:55.000Z","updated_at":"2026-01-22T07:43:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mattdef/dampen","commit_stats":null,"previous_names":["mattdef/dampen"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/mattdef/dampen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattdef%2Fdampen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattdef%2Fdampen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattdef%2Fdampen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattdef%2Fdampen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattdef","download_url":"https://codeload.github.com/mattdef/dampen/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattdef%2Fdampen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28941934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T11:39:38.044Z","status":"ssl_error","status_checked_at":"2026-01-31T11:39:27.765Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","iced-rs","rust","ui-design"],"created_at":"2026-01-15T03:27:25.903Z","updated_at":"2026-01-31T12:03:22.939Z","avatar_url":"https://github.com/mattdef.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo_dampen.webp\" height=\"100\" alt=\"Dampen Logo\" /\u003e  \n\n# Dampen\n\n[![Crates.io](https://img.shields.io/crates/v/dampen-cli.svg)](https://crates.io/crates/dampen-cli)\n[![Documentation](https://docs.rs/dampen-core/badge.svg)](https://docs.rs/dampen-core)\n[![License: MIT/Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)\n[![Rust Version](https://img.shields.io/badge/rustc-1.88+-lightgray.svg)](https://rust-lang.org)\n\n**Declarative UI framework for Rust with Iced backend, hot reloading and advanced styling.**\n\nDampen allows you to define your user interface in XML and render it via Iced.\n\n\u003cimg src=\"assets/hot-reload-demo.gif\" width=\"850\" alt=\"Exemple\" /\u003e  \n\n\u003c/div\u003e\n\n---\n\n\u003e **⚠️ DEVELOPMENT STATUS**\n\u003e \n\u003e **Dampen is currently under active development and is NOT ready for production use.**\n\u003e \n\u003e The framework is functional and can be tested for experimentation, learning, and contributing to its development. However, the API is unstable and subject to breaking changes. Features may be incomplete, and there may be bugs or performance issues.\n\u003e \n\u003e **Use Dampen for:**\n\u003e - ✅ Experimentation and learning\n\u003e - ✅ Contributing to development\n\u003e - ✅ Testing and providing feedback\n\u003e - ✅ Prototype applications\n\u003e \n\u003e **Do NOT use Dampen for:**\n\u003e - ❌ Production applications\n\u003e - ❌ Mission-critical systems\n\u003e - ❌ Applications requiring API stability\n\u003e \n\u003e We welcome your feedback and contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) to get involved.\n\n---\n\n## Features\n\n- ✅ **Declarative XML definitions**\n- ✅ **Advanced styling system** (themes, classes, state styles)\n- ✅ **Responsive design** with breakpoints (mobile, tablet, desktop)\n- ✅ **Type-safe event handlers**\n- ✅ **Expression evaluation** in XML attributes\n- ✅ **Full Iced widget support** (text, buttons, inputs, layouts, etc.)\n- ✅ **Radio button groups** with single-selection behavior\n- ✅ **Data binding** with `#[derive(UiModel)]`\n- ✅ **CLI validation** tools for syntax checking\n- ✅ **Dual-mode architecture**: Hot-reload for development, codegen for production\n- ✅ **Hot-reload support**: See UI changes instantly without recompiling\n\n## Installation\n\n```bash\ncargo install dampen-cli\n```\n\n## Quick Start\n\n### Create a New Project\n\nUse the CLI command to scaffold a new Dampen project:\n\n```bash\n# Create a new project\ndampen new my-app\n\n# Navigate to the project\ncd my-app\n\n# Run the application\ndampen run\n```\n\n### Add New UI Windows\n\n**NEW!** Quickly scaffold new UI windows with the `dampen add` command:\n\n```bash\n# Add a settings window\ndampen add --ui settings\n\n# Add a window in custom directory\ndampen add --ui order_form --path \"src/ui/orders\"\n```\n\nThis creates:\n- `settings.rs` - Model, handlers, and AppState setup\n- `settings.dampen` - Basic UI layout with data binding example\n\nThen add to `src/ui/mod.rs`:\n```rust\npub mod settings;\n```\n\n**Benefits:**\n- ✅ Production-ready code in \u003c 1 second\n- ✅ Consistent structure across windows\n- ✅ Prevents accidental overwrites\n- ✅ Reduces manual boilerplate\n\nSee `dampen add --help` for more options.\n\n### Project Validation\n\n```bash\n# Validate XML syntax and widget names\ndampen check\n\n# Build the project\ndampen build\n\n# Inspect generated IR\ndampen inspect src/ui/window.dampen\n```\n\n## Advanced Features\n\n### Data Binding\n\n```rust\n#[derive(UiModel, Default, Serialize, Deserialize, Clone)]\nstruct Model {\n    count: i32,\n    name: String,\n    items: Vec\u003cTodoItem\u003e,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct TodoItem {\n    id: usize,\n    text: String,\n    completed: bool,\n}\n```\n\n### Advanced Theming System\n\nDefine themes in `src/ui/theme/theme.dampen` for complete application theming:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003cdampen version=\"1.0\"\u003e\n    \u003cthemes\u003e\n        \u003ctheme name=\"light\"\u003e\n            \u003cpalette\n                primary=\"#3498db\"\n                secondary=\"#2ecc71\"\n                success=\"#27ae60\"\n                warning=\"#f39c12\"\n                danger=\"#e74c3c\"\n                background=\"#ecf0f1\"\n                surface=\"#ffffff\"\n                text=\"#2c3e50\"\n                text_secondary=\"#7f8c8d\" /\u003e\n            \u003ctypography font_family=\"Inter, sans-serif\" font_size_base=\"16\" /\u003e\n            \u003cspacing unit=\"8\" /\u003e\n        \u003c/theme\u003e\n\n        \u003ctheme name=\"dark\" extends=\"light\"\u003e\n            \u003cpalette\n                background=\"#1a1a2e\"\n                surface=\"#16213e\"\n                text=\"#eaeaea\"\n                text_secondary=\"#a0a0a0\" /\u003e\n        \u003c/theme\u003e\n    \u003c/themes\u003e\n\n    \u003cdefault_theme name=\"light\" /\u003e\n    \u003cfollow_system enabled=\"true\" /\u003e\n\u003c/dampen\u003e\n```\n\n**Runtime Theme Switching:**\n```xml\n\u003cbutton label=\"Dark Mode\" on_click=\"set_theme('dark')\" /\u003e\n\u003cbutton label=\"Light Mode\" on_click=\"set_theme('light')\" /\u003e\n```\n\n**Theme Features:**\n- **Theme Inheritance** - Extend themes with `extends=\"base_theme\"`\n- **System Detection** - Auto-detect dark/light mode with `\u003cfollow_system enabled=\"true\" /\u003e`\n- **Hot-Reload** - Edit `theme.dampen` and see changes instantly in development\n- **Runtime Switching** - Switch themes without restarting\n\nSee [STYLING.md](docs/STYLING.md) for complete documentation.\n\n### Reusable Style Classes\n\n```xml\n\u003cstyles\u003e\n    \u003cstyle name=\"btn_primary\"\u003e\n        \u003cbase\n            background=\"#3498db\"\n            color=\"#ffffff\"\n            padding=\"8 16\"\n            border_radius=\"6\"\n            border_width=\"0\" /\u003e\n        \u003chover background=\"#5dade2\" /\u003e\n        \u003cactive background=\"#2874a6\" /\u003e\n        \u003cdisabled opacity=\"0.5\" /\u003e\n    \u003c/style\u003e\n    \n    \u003cstyle name=\"btn_danger\"\u003e\n        \u003cbase\n            background=\"#e74c3c\"\n            color=\"#ffffff\"\n            padding=\"8 16\"\n            border_radius=\"6\" /\u003e\n        \u003chover background=\"#ec7063\" /\u003e\n    \u003c/style\u003e\n\u003c/styles\u003e\n\n\u003cbutton class=\"btn_primary\" label=\"Submit\" on_click=\"submit\" /\u003e\n\u003cbutton class=\"btn_danger\" label=\"Delete\" on_click=\"delete\" /\u003e\n```\n\n### Available Widgets\n\n| Widget | Description |\n|--------|-------------|\n| `text` | Text display |\n| `button` | Interactive button |\n| `text_input` | Text input field |\n| `checkbox` | Checkbox |\n| `toggler` | Toggle switch |\n| `pick_list` | Dropdown list |\n| `radio` | Radio button |\n| `column` | Vertical layout |\n| `row` | Horizontal layout |\n| `scrollable` | Scrollable area |\n| `container` | Container |\n| `for` | Dynamic loop |\n| `grid` | Grid layout |\n| `progress_bar` | Progress bar |\n| `svg` | SVG image |\n| `tooltip` | Tooltip |\n\n## Dual-Mode Architecture\n\nDampen supports two compilation modes optimized for different use cases:\n\n### Interpreted Mode (Development)\n\n**Enabled by default in development builds**\n\n- ✅ **Fast iteration**: Hot-reload UI changes without recompiling\n- ✅ **Runtime parsing**: XML loaded and parsed at application startup\n- ✅ **Instant feedback**: See changes in \u003c300ms\n- ✅ **Debugging friendly**: Error overlays with detailed messages\n\n```bash\n# Development mode (automatic)\ndampen run\n\n# Debug build (interpreted)\ndampen build\n```\n\n**Hot-reload example:**\n\n```rust\nuse dampen_dev::watch_files;\n\nfn subscription(app: \u0026App) -\u003e Subscription\u003cMessage\u003e {\n    watch_files(vec![PathBuf::from(\"src/ui/window.dampen\")], \"xml\")\n        .map(|_| Message::ReloadUI)\n}\n```\n\n### Codegen Mode (Production)\n\n**Enabled with --release flag**\n\n- ✅ **Zero runtime overhead**: All XML parsed at compile time\n- ✅ **Optimal performance**: Direct widget construction\n- ✅ **Smaller binaries**: No runtime parser included\n- ✅ **Build-time validation**: Catch errors before deployment\n\n```bash\n# Release run (codegen)\ndampen run --release\n\n# Release build (codegen)\ndampen build --release\n\n# Alternative: release command (alias for build --release)\ndampen release\n```\n\n**How it works:**\n\n1. `build.rs` processes `.dampen` files at compile time\n2. Generated Rust code embedded via macros\n3. No runtime XML parsing required\n\n### Mode Selection\n\nMode selection is **automatic** based on `--release` flag:\n\n| CLI Command | Mode | Use Case |\n|-------------|------|----------|\n| `dampen new` | - | Create new project |\n| `dampen add` | - | Scaffold new UI window |\n| `dampen run` | Interpreted | Development with hot-reload |\n| `dampen run --release` | Codegen | Production testing |\n| `dampen build` | Interpreted | Debug builds |\n| `dampen build --release` | Codegen | Production builds (optimized) |\n| `dampen release` | Codegen | Alias for `build --release` |\n| `dampen test` | Interpreted | Fast test iteration |\n| `dampen check` | - | Validate XML syntax |\n\n**Advanced usage:**\n\n```bash\n# Enable additional features\ndampen release --features tokio,logging\n\n# Run tests in release mode\ndampen test --release\n\n# Verbose output\ndampen build -v\n```\n\n\u003e **Note**: By default, `dampen run` and `dampen build` use interpreted mode for fast development.\n\u003e Use `--release` flag to enable codegen mode for production builds.\n\n## Architecture\n\n### Crate Structure\n\n```\ncrates/\n├── dampen-core/           # XML parser, IR, traits (no Iced dependency)\n├── dampen-macros/         # Macros #[derive(UiModel)], #[dampen_ui]\n├── dampen-iced/           # Iced backend implementation\n├── dampen-dev/            # Development mode tooling for Dampen\n└── dampen-cli/            # Developer CLI (build, check, inspect)\n\n```\n\n### Core Principles\n\n1. **Declarative-First**: XML is the source of truth for UI structure\n2. **Type Safety**: No type erasure for messages/state\n3. **Production Mode**: Static code generation for deployments\n4. **Backend-Agnostic**: Core crate has no Iced dependency\n5. **Test-First**: TDD for all features\n\n\n## Examples\n\nSee the [examples/](examples/) directory for progressive demonstrations:\n\n| Example | Features |\n|---------|----------|\n| **hello-world** | Minimal static UI rendering |\n| **counter** | Interactive event handlers |\n| **todo-app** | Complete data binding with lists |\n| **styling** | Themes, classes, state styles |\n| **responsive** | Responsive design with breakpoints |\n| **settings** | Multiple views and navigation |\n| **widget-showcase** | Demonstration of all widgets |\n\n## CLI Commands\n\n```bash\n# Generate production code\ndampen build --ui ui --output src/ui_generated.rs\n\n# Validate UI files without running\ndampen check --ui ui\n\n# Inspect IR or generated code\ndampen inspect --file ui/main.dampen\ndampen inspect --file ui/main.dampen --codegen --handlers increment,decrement\n```\n\n## Documentation\n\n- **[API Documentation](https://docs.rs/dampen-core)** - Complete Rustdoc\n- **[XML Schema Reference](docs/XML_SCHEMA.md)** - Widgets and attributes\n- **[Styling Guide](docs/STYLING.md)** - Themes, classes, state styles\n- **[Examples](examples/README.md)** - Progressive example projects\n\n## Contributing\n\nWe welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help is appreciated.\n\n**Before contributing, please read our [Contributing Guide](docs/CONTRIBUTING.md)** which covers:\n\n- Code of conduct and community standards\n- Setting up your development environment\n- Coding standards and style guidelines\n- Testing requirements (TDD is mandatory)\n- Pull request process and commit message format\n- How to report issues and request features\n\n**Quick start for contributors:**\n\n```bash\n# Fork and clone the repository\ngit clone https://github.com/YOUR_USERNAME/dampen.git\ncd dampen\n\n# Build and test\ncargo build --workspace\ncargo test --workspace\ncargo clippy --workspace -- -D warnings\n\n# Try the examples\ndampen run -p hello-world\n```\n\nAll contributions must:\n- ✅ Pass all tests (`cargo test --workspace`)\n- ✅ Pass clippy lints (`cargo clippy --workspace -- -D warnings`)\n- ✅ Be properly formatted (`cargo fmt --all`)\n- ✅ Include tests for new functionality\n- ✅ Update documentation as needed\n\nSee [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for complete details.\n\n## License\n\nThis project is dual-licensed under Apache 2.0 or MIT, at your option.\n\n---\n\n**Built with ❤️ using Rust and Iced**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattdef%2Fdampen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattdef%2Fdampen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattdef%2Fdampen/lists"}