100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
|
|
# AGENTS.md — Theming repo guide for AI agents
|
|
|
|
This is a Makepad 2.0 demo of runtime theme swapping. Read this before
|
|
editing the codebase.
|
|
|
|
## What this repo is
|
|
|
|
A small desktop app that shows how to push Rust-side state (theme + i18n)
|
|
into a Makepad 2.0 `ScriptVm` and have the whole UI re-skin live. It is
|
|
**not** a Makepad Studio plugin — it's a standalone Cargo binary that
|
|
depends on `makepad-widgets` from git.
|
|
|
|
## Key files
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `src/main.rs` | `App` struct, `MatchEvent`, `AppMain`, and the `script_mod!` UI |
|
|
| `src/theme.rs` | `ThemeState` enum, system detection, JSON persistence |
|
|
| `src/i18n.rs` | `LanguageState` enum + `apply_to_vm` |
|
|
| `src/streem_theme/mod.rs` | The four theme palettes + `s_themes` slot |
|
|
| `src/streem_theme/{colors,shapes,typography}.rs` | Token vocabularies registered on the VM |
|
|
| `src/streem_i18n/mod.rs` | EN + SW string tables + `s_i18n` slot |
|
|
| `splash/theme_gallery.splash` | Standalone Splash script using the same palette |
|
|
|
|
## The runtime swap pattern
|
|
|
|
The Rust side never touches widget properties directly. Instead:
|
|
|
|
1. `ThemeState::apply_to_vm(vm)` reassigns `mod.streem_theme.s_themes` via
|
|
`script_eval!`.
|
|
2. `App::reload_ui_from_rust_state` re-runs `script_mod` and applies it
|
|
with `Apply::Reload`, which re-evaluates every `draw_bg.color:
|
|
color_bg` etc. in the tree.
|
|
3. `self.ui.redraw(cx)` triggers a repaint.
|
|
|
|
The same pattern is used for `LanguageState` → `mod.streem_i18n.s_i18n`.
|
|
|
|
## Common edits
|
|
|
|
### Add a new theme
|
|
|
|
1. Add a variant to `ThemeState` in `src/theme.rs`.
|
|
2. Add a palette to `mod.streem_theme` in `src/streem_theme/mod.rs`.
|
|
3. Add a `themes.<name>` alias in the same file.
|
|
4. Add a `Self::Variant => script_eval!(...)` arm in
|
|
`ThemeState::apply_to_vm`.
|
|
5. Update `ThemeState::toggled()` to include the new variant in the cycle.
|
|
6. Update the tests in `src/theme.rs`.
|
|
|
|
### Add a new i18n key
|
|
|
|
1. Add the key to both `en` and `sw` blocks in
|
|
`src/streem_i18n/mod.rs`.
|
|
2. Use it in the UI via `text: <key>` (with `use mod.streem_i18n.s_i18n.*`
|
|
at the top of the `script_mod!` block).
|
|
3. If the key name collides with a widget `:=` name, rename the i18n key
|
|
(prefix with `btn_`, `section_`, etc.).
|
|
|
|
### Change a theme color
|
|
|
|
Edit the palette in `src/streem_theme/mod.rs`. If the same color appears in
|
|
`splash/theme_gallery.splash`, update it there too.
|
|
|
|
## Gotchas
|
|
|
|
- **`script_mod!` blocks in submodule files must be registered.** The v0.1
|
|
bug was that `colors.rs`, `shapes.rs`, and `typography.rs` declared
|
|
`script_mod!` blocks but were never called from `AppMain::script_mod`.
|
|
v0.2 fixes this by giving each a `pub fn script_mod(vm)` that runs
|
|
`script_eval!`, called from the top-level `streem_theme::script_mod`.
|
|
- **`System` must be resolved before `apply_to_vm`.** The Splash side never
|
|
sees a `System` value — only the resolved `Light` or `Dark` palette.
|
|
- **`new_batch: true`** is required on any View with `show_bg: true` that
|
|
contains text children. Without it, text renders behind the background.
|
|
- **Default text color is white.** For light themes, set
|
|
`draw_text.color` to a dark color on every text widget.
|
|
- **Hex colors containing `e`** adjacent to digits need the `#x` prefix
|
|
inside `script_mod!` to avoid parse errors. E.g. `#x1E293B` not
|
|
`#1E293B`.
|
|
|
|
## Running
|
|
|
|
```sh
|
|
just run # or: cargo run
|
|
just test # runs the ThemeState and LanguageState unit tests
|
|
just ci # fmt-check + clippy + test (what CI runs)
|
|
```
|
|
|
|
The Makepad git dependency requires a recent Rust toolchain and, on Linux,
|
|
the usual X11/ALSA/pkg-config dev packages (see README).
|
|
|
|
## Splash reference
|
|
|
|
For the full Makepad 2.0 Splash scripting manual, see the `splash.md`
|
|
file in the Makepad monorepo at `tools/splash.md` or the Makepad docs.
|
|
The key rules: `height: Fit` on every container, `width: Fill` on the
|
|
root, `:=` for named children, no commas between properties.
|
|
|
|
|