Preferences: theme options list and the opacity option (#8876) (#9807)

* claim: #8876

* claim: #8876

* Theme options: persist per-theme values and expose preferences contracts

* Restore selected theme mode after stopping a followed theme

* claim: #8876

* Preferences: render theme options and apply readable panel opacity

* Use floating-point scale expectation in theme preferences scenario

* Keep panel opacity colour construction inside theme tokens

* Complete theme options translations in Arabic Hebrew and Vietnamese

* Let standalone theme sliders fill their option cells
This commit is contained in:
Nathan Dane
2026-10-31 04:01:29 +00:00
committed by GitHub
parent 849bb392d2
commit d7cba9e96d
22 changed files with 2719 additions and 51 deletions
+35 -6
View File
@@ -294,10 +294,27 @@ vision modes still apply on top of any theme.
#### Theme-file options and overlays
Theme authors can add `options` and `overlays` to `solidcraft-theme/1`. This is a file-format
and resolver API; this version has no controls for changing or saving option values. Import
uses the declared defaults. Existing files need no changes, and **Export…** still writes a
complete snapshot of the resolved colours, radii, borders and icon palette.
Theme authors can add `options` and `overlays` to `solidcraft-theme/1`. Offered options appear
below the theme cards in Interface, with the theme's name. Switches, sliders, segmented choices
and dropdowns apply immediately and are saved per theme, including a followed theme file.
**Reset** appears when an offered value differs from its default and restores that theme's
defaults through the same preference update path. Cancel retains its existing behaviour of
restoring the Preferences window's opening snapshot. Themes with no offered options add no
options block or badge. Existing theme files need no changes or appearance changes.
Options flow left to right into two columns. A parent and its child occupy one cell; turning
the parent off disables its child without forgetting the child's value. Choices with four or
five values and long labels take a full row; choices with more than five values use a dropdown.
The first ten non-advanced top-level entries appear before **More · N**; advanced entries and
overflow always appear inside it. Section labels appear only above six top-level entries.
Help is available on hover. A registered behaviour unavailable on the current device stays
disabled in its place with a reason; unimplemented standard behaviours and their children
are absent. Theme cards show an Options badge only when the theme offers controls.
**Export…** preserves the authored definitions and overlays for a theme that declares them.
Older themes still export a complete token snapshot. The resolver API clamps numeric values;
invalid saved preference values instead fall back to the theme's defaults, retaining the raw
saved values for compatibility.
For example, add these two keys alongside a theme's `colors`:
@@ -336,7 +353,8 @@ For example, add these two keys alongside a theme's `colors`:
```
A file can declare up to 16 options. Each `id` is unique and matches
`[a-z][a-z0-9_]{0,31}`. Every option has a `type` and `default`:
`[a-z][a-z0-9_]{0,31}`. Every option has a `type` and a `default` (opacity may omit its
default to use 100):
- `bool`: the default is `true` or `false`.
- `choice`: `values` contains 2 to 12 entries, each with a unique `id` in the same syntax
@@ -369,10 +387,21 @@ A theme declares these with their required type and a default; it may also narro
presentation text, `step` (fixed at 1 for standard ranges), unit and parent. A wrong type or
bounds outside the standard range are import errors. Declaring `tab_fade_ms` also requires
declaring its boolean parent, `tab_colours`. Custom options cannot redefine reserved ids.
These declarations alone do not change opacity, blur or tab behaviour in this version.
Only `opacity` currently has a registered standard behaviour. `blur`, `tab_colours` and
`tab_fade_ms` remain absent from the list until their behaviours are registered.
The resolver exposes declared standard options in the order `opacity`, `blur`, `tab_colours`,
each immediately followed by its child, then custom options in declared order.
Opacity scales only these floating surface fill tokens: `panel`, `panel_header`, `dialog_bg`,
`dialog_body`, `dialog_footer`, `overlay` and `nav_tip`. Scaling is applied after matching
overlays. All other tokens, including text, icons, borders, controls, viewport and document
colours, retain their resolved values. At 100%, with the implicit 100% default, or without
offered opacity, every token is exactly the original resolved value. The supported range is
40–100%; the theme may narrow it. To keep normal text at 4.5:1 against a panel over black and
white viewport extremes, each fill's actual alpha rises as necessary. This also protects
against background overrides and busy models. A theme whose authored foreground and opaque
fill already fail contrast receives full alpha; opacity never rewrites the theme's text colours.
Up to 32 overlays apply in file order, after the base palette and the theme's own value tables.
Later matching entries win by key. Every overlay has one `when`: `{"opt":"id","eq":value}`
for an exact, correctly typed comparison, or `gte`, `lte`, or both for inclusive range bounds.
+21 -3
View File
@@ -397,7 +397,7 @@ no box selection.
| `ui.home` | `open?`: bool; `sample?`: index | the start page: show or hide it, open a built-in sample (once built); returns `open` and the recent designs |
| `ui.shortcut` | `command`, `key?`, `slot?`, `replace?` | a command's keys (`key`: the first, shown in menus; `keys`: all), or rebinds it: `key` becomes its only key, or with `slot` replaces its key there (one past the last adds a key, `""` there removes that key); `""` without `slot` clears them; key names are case-insensitive and modifiers are normalized (`shift+ctrl+t` becomes `Ctrl+Shift+T`); unknown and reserved keys are refused; a key another command uses is refused unless `replace` |
| `ui.help` | `item?`: `about`, `updates` (checks for updates and shows the result), `shortcuts` (read only), `report` (opens a report draft for review), `crashes` (the Crash Reports window) | the version, commit, build date and diagnostic text |
| `ui.prefs` | any of the [`ui.prefs` settings](#uiprefs-settings) below; also `open`, `button` and `stand_up` (listed there) | sets preferences (kept between runs), returns them all plus `dialog` (the open page or null), `apply_enabled` (whether the dialog's Apply has a change to keep), `dark`, `viewport_dark` (whether the 3D view is dark), `stand_up_offer` (the offered bodies, or null), `stand_up_note` (whether that offer is the note), `theme_followed` and `theme_follow_error` |
| `ui.prefs` | any of the [`ui.prefs` settings](#uiprefs-settings) below; also `open`, `button` and `stand_up` (listed there) | sets preferences (kept between runs), returns them all plus `dialog` (the open page or null), `apply_enabled` (whether the dialog's Apply has a change to keep), `dark`, `viewport_dark` (whether the 3D view is dark), `stand_up_offer` (the offered bodies, or null), `stand_up_note` (whether that offer is the note), `theme_followed`, `theme_follow_error`, `theme_option_defs`, `theme_option_values` and `theme_option_notices` |
| `ui.capture` | `action?`: `capture`, `revert`, `cancel` | answers the Capture Position question (asked when a command starts or the design is saved while components were moved without capturing); without `action`, what waits |
| `ui.window` | `action`: minimize, maximize, restore, toggle, close | what the title bar's caption buttons do (on Windows and Linux the application bar is the title bar); close asks about unsaved designs first |
| `ui.agent_cursor` | `show` (bool), `speed`: a number from 1 to 5 (times the normal speed) or `"instant"` (no animation: the command runs at once and the pointer jumps to where it acted), `follow_camera` (bool); all optional | the settings. While the cursor is shown, `engine.execute` first glides to the command's toolbar button and to each pick, then runs and replies; later requests wait their turn. The pointer shows the command's localized name, including commands inside a closed toolbar group; an animated batch names each command it visits. It also follows the pointer input sent with `ui.move`, `ui.click`, `ui.drag` and `ui.scroll`, as each event reaches the app, and a press leaves a ripple. `"animate": false` on a call skips it |
@@ -487,10 +487,11 @@ One setting per line, sorted by name. A change that adds a setting adds its own
- `status_bar` (default false: a thin bar along the window's bottom edge, below History, handle `status:bar`: what is being edited (`status:editing`), the open sketch's state in its colour (`status:sketch`) and the design's units (`status:units`, a click opens the Units menu, whose rows run `document.units`); the sketch's state then leaves the view's top-left corner, #7243)
- `step_values` (default false: Up/Down and the wheel step a plain number in a focused value field)
- `theme` (`dark`, `light`, `system` or a theme file's id: a built-in one such as `gruvbox-dark`, or an imported one; the reply's `theme_ids` lists them)
- `theme_export: true` (the reply's `theme_file` is the theme on now as a complete file; see [colour themes](book/src/guide/ui-tour.md#colour-themes))
- `theme_export: true` (the reply's `theme_file` is the active theme, including a followed file; themes with options retain their authored definitions, defaults and overlays, while older themes keep the complete snapshot shape; saved option values are excluded; see [colour themes](book/src/guide/ui-tour.md#colour-themes))
- `theme_follow` (desktop only, default `""`: a `solidcraft-theme/1` file's path to follow as the theme, reloaded within about a second whenever it changes and when the window gains the focus; the file is read at once, and a file that doesn't read keeps the last good theme; `""` stops following, as does setting `theme`; in the browser it is an error; the launch flag `--theme-file PATH` follows a file for one run without saving it; the reply's `theme_followed` is the path followed now or null, and `theme_follow_error` why its last read was not applied, or null)
- `theme_import` (a `solidcraft-theme/1` file's JSON or text: adds the theme and turns it on; the reply's `theme_imported` is its id)
- `theme_remove` (an imported theme's id)
- `theme_options` (default `{}`): a map of theme id to option-id/value map, merged per theme; `{"theme_options":{"my-theme":{"enabled":true,"amount":5}}}` changes those options, `null` resets one option, and an empty map resets that theme. Unknown themes or option ids, wrong types, unknown choices and out-of-range numbers refuse the entire call and name the key, before imports, removals, dialogs or other preference effects occur.
- `theme_remove` (an imported theme's id; also removes its saved option values)
- `timeline_origin_bodies` (default false: the History on the left or under the browser starts with the active component's Bodies folder and the Origin, the browser's rows with their eyes, folds and menus; the bottom History is unchanged)
- `toast_place` (`corner` (default: notices and offers stack in one column in the view's bottom-right corner, each 360 points wide, buttons right-aligned with the main action right-most, #7893), `centre` (at the bottom centre above the view toolbar, each as wide as its text, as before))
- `trackpad_pan` (default true: two-finger scroll pans, except Touchpad always zooms; pinch zooms)
@@ -506,6 +507,23 @@ One setting per line, sorted by name. A change that adds a setting adds its own
- `zoom_stop_at_model` (default false: the 3D mouse and navigation bridge stop zoom at the surface in the middle of the view; drag-zoom holds its press point; independent of `zoom_to_cursor`)
- `zoom_to_cursor`
Theme option values persist per theme, including a followed file's own id, through the same
preference store in the browser and on desktop. Switching themes restores their saved values;
Interface's Restore Defaults clears them. Preference exports and settings profiles carry values;
`theme_export` carries the author's defaults. Saved entries that no longer fit a definition remain
stored and use the default with a notice; unknown ids have a notice and no effective value.
For the active theme, `theme_option_defs` lists the declared options in `ordered_options` order:
`id`, `type`, `default`, type-specific `min`, `max`, `step`, `unit` or choice `values` (each with
`id` and `label`), `parent`, `advanced`, `section`, `label`, `help`, `standard` and `available`.
Labels, help and choice labels use the current language with English fallback. Unavailable
definitions include `reason`; standard options currently have `available: false` and
`reason: "not implemented"`. `theme_option_values` contains the effective values, including
defaults and values of inactive children. `theme_option_notices` contains `{id, kind}` entries,
where `kind` is `unknown_option`, `wrong_type`, `unknown_choice`, `non_finite` or `out_of_range`.
Without an active theme file these fields are `[]`, `{}` and `[]`. Portable input
and output schema types live in `solidcraft_engine::schema::ui_prefs` (`PrefsParams`, `PrefsReply`).
Other `ui.prefs` parameters:
- `open` (a page: General, Interface, Design, Navigation, Keyboard Shortcuts, Sketch, Graphics, AI, Plugins; Shortcuts, Assistant and Sketch & selection are aliases, and the former Selection page opens Sketch) opens the Preferences dialog there
+28
View File
@@ -156,6 +156,34 @@ four workspace choices without opening another viewport. Scale, palette, autosav
and live-axis specimens share tokens and the gallery; live bars show actual calibrated
input and introduce no repaint timer.
`theme_options_list` renders generic `ThemeOptionRow` definitions without standard-option
branches. Its pure `preferences_layout::layout` packs measured narrow/composite/wide entries
in order, with ten non-advanced top-level cells before More. A composite retains its child in
one cell; advanced descendants move the entire cell under More. Packing and allocation share
measured localized label/readout widths, the form gutter and a compact slider minimum; short
composites can share a row with narrow entries. A composite takes a full row when needed and
stacks its controls only if they exceed that entire row's width. `theme_options_badge` paints
inside an existing theme card and is called only for offered options. The small registry in
`theme_options.rs` supplies standard label/help catalog ids, availability and behaviour;
only opacity is registered today. Missing providers are absent; unavailable registered
providers keep their controls and show their translated reason. Callers submit list edits
and Reset through the existing atomic preference merge/control path.
The scoped `i18n::resolved_labels` adapter keeps theme language-map text and fallback labels
verbatim through shared controls, while stable catalog messages continue to translate.
Review fixtures are in `crates/ui-egui/tests/fixtures/theme-options.json`, keyed by
`light-0/1/3/6/12` and `dark-0/1/3/6/12`. Each value is a complete importable theme file:
pass it as `ui.prefs` `theme_import` together with `open: "Interface"`. The 12-entry files
include a four-choice wide row, Shadow/Softness composite, six-choice dropdown, an advanced
entry and overflow. More contains two top-level entries. Set
`theme_options: {"options-dark-12": {"opacity": 60}}` (or the selected fixture's id) to
compare with 100 on a busy model. Reset uses `prefs:theme_options_reset`; More uses
`prefs:theme_options_more`; controls and cells publish `prefs:theme_option:<id>` and
`prefs:theme_option_cell:<id>`. Unavailable-provider specimens are internal to the existing
`prefs::tests::theme_options_provider_registry_filters_unknown_and_retains_unavailable` test;
they are never installed in the live registry or exposed as preferences. The manager captures
and reviews live-app screenshot evidence separately from the headless harness tests.
## Elements
`aspect_grid` composes three-column `AspectTile` choices with token-sized aspect glyphs,