@smwb/ui-react 2.8.0 → 2.9.0

package/AI_LESS_OVERRIDES.md

@@ -2,6 +2,8 @@
   AUDIENCE: AI agent (not human). Dense, exact, copy-paste ready.
   TOPIC: compile-time customization of @smwb/ui-react via Less overrides.
   Companion: AI_THEMING.md (runtime CSS vars + component props).
+  SCOPE: documents BOTH @smwb/ui-react and @smwb/ui-solid — ui-solid ships
+  no AI_*.md of its own, so nothing here is React-specific.
 -->
 
 # AI_LESS_OVERRIDES — Less override mechanism
@@ -45,10 +47,10 @@ hook is `theme.config`.
 
 ```less
 // theme.config  (consumer)
-@smui-spacing-unit: 8px;          // double every gap/padding/margin
-@smui-radius-md:    2px;          // sharper corners library-wide
-@primaryColor:      @md-teal-500; // pull brand from the MD palette
-@cardPadding:       @smui-space-xxl;
+@smui-spacing-unit: 8px; // double every gap/padding/margin
+@smui-radius-md: 2px; // sharper corners library-wide
+@primaryColor: @md-teal-500; // pull brand from the MD palette
+@cardPadding: @smui-space-xxl;
 ```
 
 `site.variables.less` (`@smwb/ui-styles/less/site/globals/site.variables.less`)
@@ -57,17 +59,17 @@ first-party theming.
 
 ## Token catalog (authoritative files)
 
-| Layer | File | Tokens |
-|---|---|---|
-| MD palette | `@smwb/ui-styles/less/foundation/palette.less` | `@md-<color>-<shade>` |
-| Spacing | `@smwb/ui-styles/less/foundation/spacing.less` | `@smui-spacing-unit`, `@smui-space-*` + mixins |
-| Radius | `@smwb/ui-styles/less/foundation/radius.less` | `@smui-radius-*` |
-| Elevation | `@smwb/ui-styles/less/foundation/elevation.less` | `@smui-elevation-*` + mixin |
-| Breakpoints | `@smwb/ui-styles/less/foundation/breakpoints.less` | `@smui-bp-*`, `@xs..@xl` + media mixins |
-| Control sizing | `@smwb/ui-styles/less/foundation/sizing.less` | `@smui-control-*`, `@smui-selection-*`, `@smui-icon-*` |
-| Semantic colors + per-component vars | `@smwb/ui-styles/less/default/globals/default.variables.less` | `@primaryColor`, `@secondaryColor`, `@errorColor`, … and component vars |
-| Dark theme vars | same file, `*Dark` suffixed | e.g. `@primaryColorDark` |
-| Runtime exposure | `@smwb/ui-styles/less/variables.less` | `:root { --smui-* }` |
+| Layer                                | File                                                          | Tokens                                                                                                                                                                                                                                                          |
+| ------------------------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| MD palette                           | `@smwb/ui-styles/less/foundation/palette.less`                | `@md-<color>-<shade>`                                                                                                                                                                                                                                           |
+| Spacing                              | `@smwb/ui-styles/less/foundation/spacing.less`                | `@smui-spacing-unit`, `@smui-space-*` + mixins                                                                                                                                                                                                                  |
+| Radius                               | `@smwb/ui-styles/less/foundation/radius.less`                 | `@smui-radius-*`                                                                                                                                                                                                                                                |
+| Elevation                            | `@smwb/ui-styles/less/foundation/elevation.less`              | `@smui-elevation-*` + mixin                                                                                                                                                                                                                                     |
+| Breakpoints                          | `@smwb/ui-styles/less/foundation/breakpoints.less`            | `@smui-bp-*`, `@xs..@xl` + media mixins                                                                                                                                                                                                                         |
+| Control sizing                       | `@smwb/ui-styles/less/foundation/sizing.less`                 | `@smui-control-h-*` (consumed — see "Control sizing" below), `@smui-control-font-sm/lg` (TextField/SelectField), `@smui-selection-*` (checkbox/radio box edges); `@smui-control-px-*`, `@smui-icon-*`, `@smui-control-font-md` reserved (defined, not consumed) |
+| Semantic colors + per-component vars | `@smwb/ui-styles/less/default/globals/default.variables.less` | `@primaryColor`, `@secondaryColor`, `@errorColor`, … and component vars                                                                                                                                                                                         |
+| Dark theme vars                      | same file, `*Dark` suffixed                                   | e.g. `@primaryColorDark`                                                                                                                                                                                                                                        |
+| Runtime exposure                     | `@smwb/ui-styles/less/variables.less`                         | `:root { --smui-* }`                                                                                                                                                                                                                                            |
 
 To enumerate any group exactly, grep the source (always current):
 
@@ -120,10 +122,69 @@ Detached-ruleset mixins:
 
 ### Control sizing (`foundation/sizing.less`)
 
-`@smui-control-h-sm|md|lg` (32/40/48), `@smui-control-px-sm|md|lg`,
-`@smui-control-font-sm|md|lg`, `@smui-selection-sm|md|lg` (16/18/22),
-`@smui-icon-sm|md|lg` (18/20/24). Component `size` props map to
-`*_size-sm|md|lg` classes that read these.
+`@smui-control-h-sm|md|lg` (32/40/48) are the control heights. Wired
+consumers read them uniformly as
+`min-height: var(--smui-control-h-<step>, @smui-control-h-<step>);`:
+
+| Component              | Selector wired to the token                                                                                                                    | Step         |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| Button                 | `.smwb-button.smwb-small` / `.smwb-medium` / `.smwb-large`                                                                                     | sm/md/lg     |
+| TextField (outlined)   | `.smwb-text-field__input:not(.smwb-text-field__input--inline)` (base = md); `.smwb-text-field_size-small` / `_size-large` variants of the same | md / sm / lg |
+| SelectField (outlined) | `.smwb-select-field:not(.smwb-select-field--inline)` (base = md); the same under `.smwb-text-field_size-small` / `_size-large` ancestors       | md / sm / lg |
+| Chip                   | base `.smwb-chip`                                                                                                                              | sm           |
+| Checkbox               | `.smwb-checkbox_size-small` / `-medium` / `-large` (row)                                                                                       | sm/md/lg     |
+| RadioButton            | `.smwb-radio_size-small` / `-medium` / `-large` (row)                                                                                          | sm/md/lg     |
+| Toggle                 | `.smwb-toggle__wrapper:has(.smwb-toggle_size-small)` / `-medium` / `-large` (row — the size class rides the switch, `:has()` reaches the row)  | sm/md/lg     |
+
+ButtonGroup forwards `size` to Button and inherits. The class
+conventions: Button and exempt FloatingButton use
+`.smwb-small|medium|large`; exempt Avatar emits a third convention,
+`smwb-avatar_${size}` (`avatar.tsx`), and reads none of the tokens;
+TextField/SelectField/Chip and the selection controls use
+`*_size-small|large` — TextField's medium emits no class
+(base rule = md), Chip has no `large`, Checkbox/RadioButton/Toggle emit
+all three.
+
+**Variant exemptions (wired components that do NOT read the tokens):**
+`--filled` TextField keeps `content-box`, its padding summing with
+`min-height: 0` (the shrunk resting label needs the 23px top
+padding); `--filled` SelectField only resets `min-height: 0` and keeps
+its own padding — `.smwb-select-field` is `border-box` in both
+variants; `--inline` TextField/SelectField are excluded by the
+`:not(--inline)` guard; RadioButton's md box is a hardcoded 20px — off
+the 16/18/22 `@smui-selection-*` scale (its sm/lg boxes DO read
+`@smui-selection-sm/lg`); Chip `_size-small` is a constant 24px, below
+the scale; the Toggle switch geometry (track, thumb) is not scaled.
+
+**Component exemptions (not wired, do not add without a design
+decision):** FloatingButton (Material FAB diameters 56/48/40, extended
+48/40/34, are their own scale), Avatar (identity badge 24/40/56, not a
+control), Pagination (own item scale 32/26), ProgressIndicator
+(indicator diameter 28px), StatusDot (decorative dot, and `_size-sm` is
+a different suffix), Slider (`size` scales track thickness/thumb
+diameter), Modal (`size` is dialog width), Rating (`size?: number` is a
+pixel value), DatePicker/TimePicker/DateTimePicker (compose TextField +
+Button, so they inherit the tokens).
+
+**Reserved (defined, NOT consumed — do not claim otherwise):**
+`@smui-control-px-*` and `@smui-icon-*` have no readers anywhere;
+`@smui-control-font-md` is unconsumed (`-sm`/`-lg` are read by the
+TextField/SelectField sm/lg rules); `@smui-selection-*` is read only by
+the checkbox box edges (all three steps) and the radio sm/lg box edges —
+Toggle reads none.
+
+**Default deltas (accepted breaking changes — never "restore" these by
+hardcoding heights):** Button sm/md/lg grew ≈27.5/33/38.5 → 32/40/48;
+outlined TextField sm/md/lg shrank 40/56/55 → 32/40/48 (SelectField
+40/56/56 → 32/40/48, border-box: the padding calc adds up to the token
+exactly); Checkbox/RadioButton/Toggle rows previously had no
+`min-height` — md rows are now floored at 40px.
+
+This mapping is machine-enforced:
+`packages/styles/scripts/check-control-heights.mjs` (in
+`@smwb/ui-styles`' `lint`, gating CI) re-renders `components.less` with
+`@smui-control-h-md: 44px` and asserts exactly the wired selectors
+above change. Editing either side without the other fails the lint cube.
 
 ### Semantic colors (`default.variables.less`)
 
@@ -151,7 +212,9 @@ grep -nE '^@[a-z][A-Za-z0-9]+:' @smwb/ui-styles/less/default/globals/default.var
 @smui-spacing-unit: 6px;
 
 // 2. Flatter corners everywhere
-@smui-radius-md: 2px; @smui-radius-lg: 4px; @smui-radius-xl: 6px;
+@smui-radius-md: 2px;
+@smui-radius-lg: 4px;
+@smui-radius-xl: 6px;
 
 // 3. Rebrand from the MD palette (cascades to all primary usages)
 @primaryColor: @md-indigo-600;
@@ -159,7 +222,7 @@ grep -nE '^@[a-z][A-Za-z0-9]+:' @smwb/ui-styles/less/default/globals/default.var
 
 // 4. Retune ONE component without touching others
 @cardPadding: @smui-space-xxl;
-@tooltipBg:   @md-blueGrey-800;
+@tooltipBg: @md-blueGrey-800;
 
 // 5. Soften elevation globally
 @smui-elevation-2: @smui-elevation-1;

package/AI_THEMING.md

@@ -3,6 +3,8 @@
   TOPIC: changing component appearance in @smwb/ui-react — at runtime
   (CSS custom properties) and via component props.
   Companion: AI_LESS_OVERRIDES.md (compile-time Less tokens).
+  SCOPE: documents BOTH @smwb/ui-react and @smwb/ui-solid — ui-solid ships
+  no AI_*.md of its own, so nothing here is React-specific.
 -->
 
 # AI_THEMING — change component appearance
@@ -40,8 +42,14 @@ shared sheet (`tokens.entry.less`), at zero specificity:
   `:root` or any subtree (cascades):
 
 ```css
-:root { --smui-primaryColor: #00695c; --smui-radius-md: 2px; }
-.dense-area { --smui-space-md: 8px; --smui-space-lg: 12px; }
+:root {
+  --smui-primaryColor: #00695c;
+  --smui-radius-md: 2px;
+}
+.dense-area {
+  --smui-space-md: 8px;
+  --smui-space-lg: 12px;
+}
 ```
 
 - **Precedence**: against the per-component CSS a `:root` override
@@ -62,17 +70,26 @@ Groups exposed: `--smui-primaryColor*`, full semantic set
 surface/text (`--smui-surfaceBackground`, `--smui-onSurfaceColor`,
 `--smui-dividerColor`, …), per-component (`--smui-tooltipBg`,
 `--smui-menuTextColor`, `--smui-tableBorderColor`, …), spacing
-(`--smui-space-*`, `--smui-spacing-unit`), `--smui-radius-*`,
+(`--smui-space-*`, `--smui-spacing-unit`), control heights
+(`--smui-control-h-sm|md|lg` — read by the wired controls listed in
+AI_LESS_OVERRIDES "Control sizing"; the exempt components and the
+`--filled`/`--inline` variants do NOT respond), `--smui-radius-*`,
 `--smui-elevation-*`, `--smui-bp-*`.
 
 ## 2. Component props (appearance)
 
 Standardized vocabulary (rollout in progress across the library):
 
-- `size?: "small" | "medium" | "large"` — control density. Emits
-  `*_size-sm|md|lg`, reads `@smui-control-*` (see AI_LESS_OVERRIDES).
+- `size?: "small" | "medium" | "large"` — control density. Emits the
+  component's size class; on wired components (Button, TextField,
+  SelectField, Chip, Checkbox, RadioButton, Toggle — the exact
+  selectors and exemptions are in AI_LESS_OVERRIDES "Control sizing")
+  the wired rule reads `@smui-control-h-*` at compile time and
+  `--smui-control-h-*` at runtime (for Chip that is the base
+  `.smwb-chip` rule — its `_size-small` class pins 24px and does not
+  read the token).
 - `color?: "primary" | "secondary" | "error" | "success" | "warning"
-  | "info"` — semantic color, resolves through `--smui-<name>Color*`.
+| "info"` — semantic color, resolves through `--smui-<name>Color*`.
 - `variant?: …` — structural style; component-specific values.
 
 Authoritative per-component prop surface = the exported `*Props`
@@ -85,24 +102,24 @@ grep -nE 'export interface .*Props|size\?|color\?|variant\?' \
 
 Representative current values:
 
-| Component | variant | color | size | other appearance props |
-|---|---|---|---|---|
-| Button | contained\|text\|outlined | (colorTheme:primary) | small\|medium\|large | `fullWidth`, `icon`, `iconProps` |
-| FloatingButton | default\|extended | primary\|secondary\|error\|success\|warning\|info | small\|medium\|large | `type` |
-| Chip | filled\|outlined | — | — | `icon`, `deleteIcon`, `selected` |
-| TextField | outlined\|filled | — | — | `startAdornment`, `endAdornment`, `inline`, `fullWidth` |
-| SelectField | outlined\|filled | — | — | `chips`, `search`, `endAdornment`, `optionRenderer` |
-| Card | filled\|elevated\|outlined | — | — | `disabled` |
-| Avatar | circular\|rounded\|square | (`color` = bg of fallback) | small\|medium\|large \| px | — |
-| Badge | inside\|outside | primary\|success\|danger | — | `vertical`, `horizontal` |
-| Skeleton | text\|circular\|rounded\|rectangular | — | (`width`/`height`) | `animation` |
-| Pagination | — | — | small\|medium | `showFirstButton`, `showLastButton` |
-| Message | outlined\|filled\|left-accent | (`type`: success/error/warning/info) | — | `onClose` |
-| Modal | — | — | small\|large\|fullscreen | `backdrop`, `animation` |
-| ProgressIndicator | circular\|linear | — | — | `type` det/indet, `progressValue` |
-| Divider | fullWidth\|inset\|middle | — | — | `orientation`, `textAlign` |
-| Slider | continuous\|discrete | — | — | `withTicks`, `valueField` |
-| Tabs/Tab | — | — | — | `scrollable`, `stacked`, `icon` |
+| Component         | variant                              | color                                             | size                       | other appearance props                                  |
+| ----------------- | ------------------------------------ | ------------------------------------------------- | -------------------------- | ------------------------------------------------------- |
+| Button            | contained\|text\|outlined            | (colorTheme:primary)                              | small\|medium\|large       | `fullWidth`, `icon`, `iconProps`                        |
+| FloatingButton    | default\|extended                    | primary\|secondary\|error\|success\|warning\|info | small\|medium\|large       | `type`                                                  |
+| Chip              | filled\|outlined                     | —                                                 | —                          | `icon`, `deleteIcon`, `selected`                        |
+| TextField         | outlined\|filled                     | —                                                 | —                          | `startAdornment`, `endAdornment`, `inline`, `fullWidth` |
+| SelectField       | outlined\|filled                     | —                                                 | —                          | `chips`, `search`, `endAdornment`, `optionRenderer`     |
+| Card              | filled\|elevated\|outlined           | —                                                 | —                          | `disabled`                                              |
+| Avatar            | circular\|rounded\|square            | (`color` = bg of fallback)                        | small\|medium\|large \| px | —                                                       |
+| Badge             | inside\|outside                      | primary\|success\|danger                          | —                          | `vertical`, `horizontal`                                |
+| Skeleton          | text\|circular\|rounded\|rectangular | —                                                 | (`width`/`height`)         | `animation`                                             |
+| Pagination        | —                                    | —                                                 | small\|medium              | `showFirstButton`, `showLastButton`                     |
+| Message           | outlined\|filled\|left-accent        | (`type`: success/error/warning/info)              | —                          | `onClose`                                               |
+| Modal             | —                                    | —                                                 | small\|large\|fullscreen   | `backdrop`, `animation`                                 |
+| ProgressIndicator | circular\|linear                     | —                                                 | —                          | `type` det/indet, `progressValue`                       |
+| Divider           | fullWidth\|inset\|middle             | —                                                 | —                          | `orientation`, `textAlign`                              |
+| Slider            | continuous\|discrete                 | —                                                 | —                          | `withTicks`, `valueField`                               |
+| Tabs/Tab          | —                                    | —                                                 | —                          | `scrollable`, `stacked`, `icon`                         |
 
 (The exported `*Props` interface is the source of truth; this table is
 a navigational summary, not exhaustive.)
@@ -133,20 +150,47 @@ grep -oE 'var\(--smui-[a-zA-Z0-9-]+' @smwb/ui-styles/less/components/<name>/<nam
 
 ```css
 /* B. Tooltip: dark slate, at runtime, no rebuild */
-:root { --smui-tooltipBg: #37474f; --smui-tooltipTextColor: #fff; }
+:root {
+  --smui-tooltipBg: #37474f;
+  --smui-tooltipTextColor: #fff;
+}
 ```
 
 ```tsx
 // C. FloatingButton: semantic color + size via props
-<FloatingButton color="success" size="large" variant="extended">Save</FloatingButton>
+<FloatingButton color="success" size="large" variant="extended">
+  Save
+</FloatingButton>
 ```
 
 ```css
 /* D. Scope a denser theme to a region (runtime, cascades) */
-.compact { --smui-space-md: 8px; --smui-space-lg: 12px;
-           --smui-control-h-md: 32px; }
+.compact {
+  --smui-space-md: 8px;
+  --smui-space-lg: 12px;
+  --smui-control-h-md: 32px;
+}
 ```
 
+> Recipe D is live for control heights: `--smui-control-h-sm|md|lg` are
+> declared in the `.smui-tokens-light()` mixin ONLY (`variables.less`)
+> — density is theme-independent, and the light `:root` block applies
+> under `data-theme="dark"` too (same precedent as `--smui-space-*` /
+> `--smui-radius-*`); re-declaring them in the dark mixin would add a
+> higher-specificity `:root[data-theme="dark"]` copy that silently
+> resets a consumer's global `:root` density override in dark mode —
+> and read via
+> `var(--smui-control-h-*, @smui-control-h-*)` by Button, TextField,
+> SelectField, Chip, Checkbox, RadioButton and Toggle (exact selectors
+> and the machine-checked list: AI_LESS_OVERRIDES "Control sizing"). So
+> density is overridable BOTH at compile time (`@smui-control-h-md` in
+> `theme.config`, see AI_LESS_OVERRIDES) and at runtime per subtree as
+> above. Exempt and do not expect a response: `--filled` and `--inline`
+> TextField/SelectField, FloatingButton, Avatar, Pagination,
+> ProgressIndicator, StatusDot, Slider, Modal, Rating. The pickers
+> (DatePicker/TimePicker/DateTimePicker) have no wiring of their own —
+> they inherit through their inner TextField + Button.
+
 ```less
 // E. Whole-library rebrand (compile-time) — see AI_LESS_OVERRIDES recipes
 @primaryColor: @md-deepPurple-600;