actual-css 0.10.0 → 0.11.0

package/docs/pages/forms/overview.md

@@ -10,6 +10,9 @@
 - `.field-group` and `.choice` provide layout without depending on parent scope.
 - Customizable select is progressive enhancement only — the native select remains the baseline.
 - Searchable selects, tags and autocomplete are a JavaScript widget concern; theme an external combobox with Actual tokens — see the [combobox template](../../demo/templates/combobox.html).
+- Formatted text (bold, lists, links) is a hosted-editor concern; the native textarea stays the baseline and an external engine is themed the same way — see the [rich-text template](../../demo/templates/rich-text.html) and the [composer template](../../demo/templates/composer.html) for the plain-text case.
+
+**Related terms:** form controls, select, custom select, dropdown, input, textarea, checkbox, radio.
 
 ## Class reference
 
@@ -181,7 +184,7 @@ it a stronger fill.
 - Use native `<optgroup>` and `disabled` options in `.select` controls when applicable; the customizable picker preserves both as a progressive enhancement.
 - `.choice` is the choice-label API. Use `.check` or `.radio` on the nested control. The control goes first, the label group second, so multi-line labels align the control with the first line.
 - For a switch, use `class="switch"` and `role="switch"`.
-- Core range controls stay native and are enhanced by `accent-color`. An optional richer range skin may come later if real projects need it.
+- `.range` skins the native range control (`appearance: none` track, thumb, and focus ring). Add `data-enhance="range"` for the fill share, named `datalist` values, and output sync.
 - `.form-actions` carries a default top margin. Override it with `--form-actions-margin-block-start`, `--form-actions-align`, or `--form-actions-justify`. It is class-only and may live inside or outside `<form>`. See Detached Actions below.
 - `.join` visually joins adjacent controls into a single unit. Use `.join-addon` for static prefix/suffix content. The container still carries `role="group"` for accessibility.
 

package/docs/pages/forms/range.md

@@ -12,14 +12,117 @@ rather than the CSS box.
 ```html demo
 <label class="field">
   <span class="field-label">Volume</span>
-  <input class="range" type="range" min="0" max="100" value="50" />
+  <input class="range" data-enhance="range" type="range" min="0" max="100" value="50" />
 </label>
 ```
 
-Actual deliberately does not emulate filled tracks, tick marks, value labels,
-or multi-thumb ranges. Those still require engine-specific pseudo-elements or a
-value duplicated out of the HTML into CSS. Prefer the platform as richer range
-styling becomes interoperable — see
+## Fill
+
+`data-enhance="range"` opts into the `actual-css/js/range` behavior. It writes
+`--range-progress`, the fill share the track gradient reads, and keeps it in
+sync on input and after a form reset, including inputs associated through
+`form="…"`. Without it the variable stays at its `0%` default and the track
+renders plain — the control stays fully usable without JavaScript. The fill
+follows the writing direction, and a bare `input[type="range"]` without the
+`.range` class can opt in the same way.
+
+## Named values
+
+A `datalist` is the source of truth for discrete named steps: positions plus
+names. Browsers render its ticks and labels inconsistently, so Actual never
+depends on their presentation — the enhancement only reads `option` values and
+their `label`. A matching label sets `aria-valuetext` on the input and mirrors
+into each `<output for="…">`. The output is the visible value, not the input's
+name — give the input its own accessible name, since `for` only declares the
+output's operands.
+
+```html demo
+<div class="field">
+  <output class="field-label" for="effort">High</output>
+  <input
+    class="range"
+    data-enhance="range"
+    id="effort"
+    type="range"
+    min="0"
+    max="3"
+    step="1"
+    value="2"
+    list="effort-levels"
+    aria-label="Effort"
+  />
+  <datalist id="effort-levels">
+    <option value="0" label="Minimal"></option>
+    <option value="1" label="Standard"></option>
+    <option value="2" label="High"></option>
+    <option value="3" label="Maximum"></option>
+  </datalist>
+</div>
+```
+
+`aria-valuetext` is the announced value when a number really means a text; keep
+it even if the visible `output` changes shape. An `output` is a live region,
+so verify with a screen reader that the two do not double-announce.
+
+## In a flyout
+
+The range stays an `input`, the flyout stays a flyout — together they read as
+a richer picker with no new component. `data-flyout-auto-close="outside"` keeps
+dragging the slider from closing the panel.
+
+```html demo
+<div class="flyout-trigger">
+  <button
+    class="btn outline"
+    type="button"
+    data-enhance="flyout"
+    aria-expanded="false"
+    aria-controls="effort-picker"
+  >
+    Reasoning effort
+  </button>
+
+  <div
+    class="flyout"
+    id="effort-picker"
+    data-flyout-auto-close="outside"
+    style="--flyout-inline-size: 16rem; --flyout-pad: var(--space-40)"
+    hidden
+  >
+    <div class="field">
+      <output class="field-label text-center" for="effort-flyout">High</output>
+
+      <input
+        class="range"
+        data-enhance="range"
+        id="effort-flyout"
+        type="range"
+        min="0"
+        max="3"
+        step="1"
+        value="2"
+        list="effort-flyout-levels"
+        aria-label="Reasoning effort"
+      >
+
+      <datalist id="effort-flyout-levels">
+        <option value="0" label="Minimal"></option>
+        <option value="1" label="Standard"></option>
+        <option value="2" label="High"></option>
+        <option value="3" label="Maximum"></option>
+      </datalist>
+    </div>
+
+    <div class="cluster" style="--cluster-justify: center">
+      <button class="btn primary sm" type="button" data-flyout-close>Done</button>
+    </div>
+  </div>
+</div>
+```
+
+Actual deliberately does not emulate tick marks or multi-thumb ranges. Ticks
+still need engine-specific pseudo-elements; the fill above is designed for
+deletion once `::slider-fill` is interoperable — see
 [Enhanced range controls](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/platform-alignment.md).
 
 ## CSS hooks
@@ -28,3 +131,5 @@ styling becomes interoperable — see
 - `--range-track-height` — track thickness.
 - `--range-thumb-bg` — thumb color. Defaults to the local intent, then `--primary`.
 - `--range-track-bg` — track color.
+- `--range-fill-bg` — filled portion color. Defaults to the local intent, then `--primary`.
+- `--range-progress` — fill share. Written by `actual-css/js/range`, never set by hand.

package/docs/pages/forms/rich-text.md

@@ -0,0 +1,110 @@
+# Rich text
+
+> A rich-text editor is not shipped by the framework — the native `<textarea>` stays the baseline. Enhance it with a dedicated engine, themed with Actual tokens.
+
+Use a `<textarea>` while editing text, and a hosted editing engine as soon as
+editing means a document (formatting, lists, links, mentions). The
+[rich-text template](../../demo/templates/rich-text.html) enhances a textarea
+with [@lekoala/rich-text](https://github.com/lekoala/rich-text) (Squire
+underneath): the package generates the toolbar with its roving tabindex,
+states, commands and lifecycle, while Actual maps its visual language onto the
+package's `--rt-*` tokens. No adapter, no compatibility layer.
+
+**Related terms:** rich text, richtext, WYSIWYG, HTML editor, formatted text, Squire, ProseMirror, Tiptap, text formatting, bold italic, mentions, slash commands.
+
+## Theme bridge
+
+The template loads the package JS and CSS from a CDN (`@0.2` caret range) and
+declares one editor per field — Actual never builds toolbar buttons or calls
+into the editing engine:
+
+```html
+<div class="field actual-rich-text">
+  <label class="field-label" for="note">Team note</label>
+  <rich-text id="note-editor">
+    <textarea class="textarea" id="note" name="note" required placeholder="Write a note…"></textarea>
+  </rich-text>
+  <span class="field-help">Bold, italic, lists, quotes and links.</span>
+</div>
+```
+
+```js
+editor.options = {
+  buttons, // Tabler icons as Nodes, never HTML strings
+  requestLink, // an Actual <dialog> replacing window.prompt()
+  suggestions, // static @people and /snippets providers
+};
+```
+
+The bridge maps tokens; it does not restyle the editor's internals:
+
+```css
+.actual-rich-text .rt-shell {
+  --rt-bg: var(--surface);
+  --rt-fg: var(--text);
+  --rt-border: var(--form-invalid-border, var(--control-border, var(--border)));
+  --rt-divider: var(--border);
+  --rt-focus: var(--form-invalid-border, var(--focus));
+  --rt-toolbar-bg: var(--surface-subtle);
+  --rt-button-pressed-bg: var(--state-selected);
+  --rt-link: var(--primary);
+  --rt-suggestion-bg: var(--surface-raised);
+  --rt-suggestion-shadow: var(--shadow-popout);
+}
+```
+
+The card in the template documents the full token map of this recipe. The
+suggestion popover is a child of `.rt-shell`, so it inherits the tokens like
+the rest of the editor. `--rt-border` paints only the field frame, so the
+invalid and hover hooks never reach the toolbar separators or the quote bar,
+which follow `--rt-divider`.
+
+## Bridge contract
+
+`@lekoala/rich-text` owns the editor UI semantics — progressive enhancement,
+sanitization, toolbar behaviour and keyboard, links, `@mentions`, `/`
+suggestions, form/reset/readonly/disabled integration, selection and undo
+lifecycle. Actual owns presentation and composer chrome — tokens, visual
+states, dialogs, attachments, send, `Ctrl/Cmd+Enter`.
+
+Formatting buttons stay local to the editor instance. The stateless `command`
+router never drives bold/italic: those depend on selection, schema and history,
+which only the engine knows. Reserve `command` for the chrome around the
+editor (attach, template, dictate, send).
+
+A rich composer reuses `.composer` and `.composer-actions` for the outer
+surface; the bridge only lifts the editor and toolbar into the composer grid
+with `display: contents` and grid areas. `composer.css` itself never knows
+about `.rt-*`. The plain-text [composer template](../../demo/templates/composer.html)
+stays the canonical pattern when editing means text, not a document.
+
+People lookup and templates are application concerns: the demo wires static
+arrays into the package's suggestion seam, and the composer buttons type
+`@`/`/` so the providers do the rest. Attachments stay composer-owned —
+logged, never serialized into the HTML.
+
+## Storage and sanitization
+
+The form submits limited HTML, not engine state: portable, readable,
+editor-independent, reversible. Sanitization is mandatory inside the package
+and not configurable; the client-side sanitizer is a UI boundary, not the
+persistence security boundary — sanitize again on the server before storing or
+rendering untrusted content. An editor holding only the empty block serializes
+to `""`, so native `required` keeps working.
+
+If the product later needs truly structural content (custom document nodes,
+annotations, collaboration), a schema-based engine becomes interesting — see
+the [rich-text design note](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/rich-text.md).
+
+## Baseline traps
+
+The textarea is the value owner and the no-JS fallback, holding raw HTML. Two
+details keep it honest:
+
+- Without the integration script the page remains a plain textarea — the link
+  dialog wiring and the suggestion providers only exist once the package
+  loads, and the composer falls back to plain-text send.
+- `required` cannot sit usefully on a hidden textarea: mirror validity with
+  `aria-invalid` on submit (the package emits `richtext:invalid` and focuses
+  the editor when it is the form's first invalid control), and let the bridge
+  re-own the danger hook from there.

package/docs/pages/forms/validation.md

@@ -55,7 +55,11 @@ Native validation first; the enhancer only adds state and focus behavior.
 
 Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the full runtime (`actual-css/js/full`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
 
-Opt in with the `.needs-validation` class. Importing the module registers the behavior; there is no init call.
+Opt in with `data-enhance="validation"` on the form; `.needs-validation` alone
+only enables the CSS feedback. Importing the module registers the behavior;
+there is no init call. To opt in forms you cannot mark up, call
+`applyEnhancement("validation", "form.needs-validation")` from
+`actual-css/js/enhance`.
 
 ```html demo
 <form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">

package/docs/pages/foundations/theming.md

@@ -122,9 +122,9 @@ application CSS and keep forms and intent ink out of it:
 
 ```css
 .site-band {
-  --heading: var(--surface);
+  --heading: var(--surface-solid-fg);
   background: var(--surface-solid);
-  color: var(--surface);
+  color: var(--surface-solid-fg);
 }
 ```
 
@@ -135,6 +135,49 @@ there: the theme contract keeps `--focus` at 3:1 on `--surface-solid`.
 
 → Foundations · Tokens (theme contract) · Examples · Contrast contexts
 
+### Scope a theme to one section / microtheme / theme island
+
+Any `data-theme` value is an island, not only `light` and `dark`:
+`<aside data-theme="promo">` paints its subtree with that theme, nested inside
+the page theme, without changing the markup. The same painting rule applies as
+for a dark section. A theme can change radius, typography, shadow and motion as
+well as color.
+
+→ Foundations · Tokens (theme contract)
+
+### Dark mode toggle / theme switcher / remember the user's choice
+
+Actual CSS ships the mechanism, not the control. Without `data-theme` the page
+follows the OS; `data-theme="light"` or `"dark"` on `<html>` forces a scheme,
+and removing the attribute returns to the OS. The switcher UI and where the
+choice is stored belong to the application; a page with no setting already
+follows the OS. Apply a stored choice from an inline script in `<head>` so the
+first paint does not flash the OS scheme. The demo's theme picker is an
+inspection tool, not a component to copy.
+
+### Force light or dark on a theme that has both / theme and color scheme
+
+With a single brand theme, `data-theme="light"` and `"dark"` already are that
+choice once you redefine them as your brand's two schemes (see the dark section
+above).
+
+A named theme that pairs both schemes through `light-dark()` follows the OS. To
+pin one scheme, set `color-scheme` on the element that carries `data-theme`,
+inline or in a rule more specific than the theme's own. `color-scheme` is the
+scheme axis and `data-theme` the design axis, so there is no separate
+`data-color-scheme` attribute.
+
+```html
+<html data-theme="ocean" style="color-scheme: dark">
+```
+
+On an ancestor it has no effect: the theme declares its own `color-scheme` on
+its boundary. Leave single-scheme themes (`color-scheme: dark` only) alone —
+their tokens have one value, so forcing the other scheme only flips native
+controls and scrollbars.
+
+→ Foundations · Tokens (theme contract)
+
 ### Replace the palette with my own brand
 
 Override the whole minimal recolor set (Tokens · Theme contract), not just
@@ -165,4 +208,7 @@ line. Use `.badge.soft` for a subtle badge. It is a visual theme, not a
 Bootstrap compatibility layer. The `gradient` example keeps a Bootstrap 4 style
 outer halo on focused fields, for comparison. The `material` example restyles
 fields as filled underlines with pill buttons — tokens plus three small rules,
-and `.join` still needs no adaptation.
+and `.join` still needs no adaptation. The `glass` example paints translucent
+surfaces over its own backdrop: it sets `--surface-opaque` and
+`--surface-solid-fg` to opaque values, raises `--soft-bg-mix` so soft fills stay
+light over glass, and adds the blur and an opaque busy veil as small rules.

package/docs/pages/foundations/tokens.md

@@ -76,18 +76,25 @@ Surface tokens describe the canvas and elevation model. Components should prefer
 }
 ```
 
-The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the dark inverse surface, used for accent areas).
+The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the inverse surface, used for accent areas).
+
+Surfaces are painted material and may be translucent. Two roles must stay opaque, so they have their own tokens, both defaulting to `--surface`:
+
+- `--surface-solid-fg` — the ink on `--surface-solid`: tooltips, the status bar, an inverse band.
+- `--surface-opaque` — an opaque neutral used where a component must hide or separate what is painted beneath it: the status-dot and avatar-stack rings, range-thumb and meter separators, step markers, the mask under an `.aura` child. It is not a surface fill; paint panels with `--surface-*`.
+
+A theme with translucent surfaces overrides both with opaque values.
 
 Use `*-fg` pairs only for solid backgrounds where the component controls both foreground and background. Do not require a foreground token for every surface token.
 
-Focus styling is outline-first. A global focus baseline applies `--focus-outline` and `--focus-outline-offset`: older browsers show it on `:focus`, while modern browsers limit it to `:focus-visible`. Components draw a solid `--focus-ring-width` line in `--focus`: inside the border box on text fields (`.input`, `.textarea`, `.select`), outside at `--focus-outline-offset` on actions (`.btn`, `.close`, choices, switches). The color never follows an intent or a local surface, so `--focus` must hold 3:1 against both `--surface` and `--surface-solid` — the page, fields and a solid band all rely on it. Under `forced-colors: active`, outlines map to the system focus color.
+Focus styling is outline-first. A global focus baseline applies `--focus-outline` and `--focus-outline-offset`: older browsers show it on `:focus`, while modern browsers limit it to `:focus-visible`. The baseline is a `currentColor` line, so text-like elements (links, `summary`, nav and menu items) follow whatever surface the application painted. Boxed components draw a solid `--focus-ring-width` line in `--focus`: inside the border box on text fields (`.input`, `.textarea`, `.select`), outside at `--focus-outline-offset` on actions (`.btn`, `.close`, choices, switches). The color never follows an intent or a local surface, so `--focus` must hold 3:1 against both `--surface` and `--surface-solid` — the page, fields and a solid band all rely on it. Both lines are `--focus-ring-width` wide. Under `forced-colors: active`, outlines map to the system focus color.
 
 ```css
 :root {
   --focus: hsl(268 30% 55%);
 
   --focus-outline-color: currentColor;
-  --focus-outline: calc(var(--border-width) * 2) solid var(--focus-outline-color);
+  --focus-outline: var(--focus-ring-width) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
   --focus-ring-width: 2px;
 }
@@ -381,7 +388,7 @@ A few cross-component helpers:
 ```css
 :root {
   --indicator-offset: 14.65%;      /* circle-aware inset */
-  --indicator-ring: var(--surface);
+  --indicator-ring: var(--surface-opaque);
   --backdrop-color: rgb(0 0 0);
   --backdrop-opacity: 0.45;
   --backdrop-fill: rgb(0 0 0 / var(--backdrop-opacity));
@@ -485,12 +492,15 @@ When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. A
 
 The default palette's hooks apply to `:root` and to the `light`/`dark` boundaries only. Any other `data-theme` value resets them to the derivation, whether the attribute sits on `<html>` or on a nested island.
 
+Contrast is measured between opaque colors. A translucent `--surface` has no ratio until it is composited over its backdrop, so `report:theme-contrast` refuses such a theme, and `.soft` mixes over it come out more opaque and more saturated than the surface. A translucent theme owns both: it measures against its real backdrop and replaces any recipe that does not hold there.
+
 Shape, shadow, motion, typography, and soft-variant mix tokens are optional knobs. Override them only when the theme actually changes that part of the system.
 
 A full theme can override:
 
 - intent colors and foreground pairs
 - surface, text, border, focus, and overlay colors
+- `--surface-opaque` and `--surface-solid-fg`, when surfaces are translucent
 - radius tokens
 - optional shadow, motion, typography, and soft-variant mix tokens
 
@@ -534,7 +544,7 @@ A minimal recolor theme (illustrative, not a shipped theme):
 }
 ```
 
-Several tokens are theme-derived aliases that reference other tokens — `--state-selected`/`--state-selected-fg`/`--state-disabled`, `--indicator-ring`, `--shadow`/`--shadow-popout`, `--heading`, and `--selection-bg`/`--selection-fg`. They are declared on `:root, [data-theme]` so they recompute on every theme boundary: a custom property resolves its `var()` references at computed-value time on the element that declares it, so an alias declared only on `:root` would be inherited as an already-resolved value and would not follow a `[data-theme]` island's overridden tokens. A theme that wants a distinct alias (e.g. a `--selection-bg` of its own) overrides it explicitly afterwards, which wins by cascade order.
+Several tokens are theme-derived aliases that reference other tokens — `--state-selected`/`--state-selected-fg`/`--state-disabled`, `--indicator-ring`, `--shadow`/`--shadow-popout`, `--heading`, `--selection-bg`/`--selection-fg`, and `--surface-opaque`/`--surface-solid-fg`. They are declared on `:root, [data-theme]` so they recompute on every theme boundary: a custom property resolves its `var()` references at computed-value time on the element that declares it, so an alias declared only on `:root` would be inherited as an already-resolved value and would not follow a `[data-theme]` island's overridden tokens. A theme that wants a distinct alias (e.g. a `--selection-bg` of its own) overrides it explicitly afterwards, which wins by cascade order.
 
 Without `data-theme`, the default theme advertises `color-scheme: light dark` and follows the user's OS preference in browsers that support `light-dark()`. Dark themes should set `color-scheme: dark`. Light themes should set `color-scheme: light`. Browsers without `light-dark()` receive the light fallback.
 

package/docs/pages/guides/bootstrap.md

@@ -18,7 +18,8 @@ For an incremental migration, use one of these approaches:
 
 * migrate isolated pages or application areas;
 * control precedence with cascade layers or import order;
-* use a project-side prefix transform for Actual while both frameworks coexist.
+* use a project-side prefix transform for Actual while both frameworks coexist,
+  renaming the runtime's state classes in `actual-css/js/selectors` as well.
 
 The layered import is the cleanest way to keep both stylesheets during the
 migration:

package/docs/pages/guides/introduction.md

@@ -52,7 +52,7 @@ optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resol
 to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.10/dist/actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.11/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map

package/docs/pages/guides/modular-import.md

@@ -94,7 +94,7 @@ cells, so they read as a list:
 - **Components** — `actual-css/css/components`
   buttons, surfaces, overlays, feedback, navigation, data and composed controls
 - **Effects** — `actual-css/css/effects`
-  aura
+  aura, shimmer
 - **Utilities** — `actual-css/css/utilities`
   base and extra utilities
 

package/docs/pages/guides/progressive-enhancement.md

@@ -92,6 +92,7 @@ example:
 | `actual-css/js/filter`             | Input value filtering on `data-filter`                      |
 | `actual-css/js/mask`               | Input masks on `data-mask`                                  |
 | `actual-css/js/password`           | Password reveal toggle                                      |
+| `actual-css/js/range`              | Range fill and named values (token `range`)                 |
 | `actual-css/js/validation`         | Form validation (token `validation`)                        |
 | `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`      |
 | `actual-css/js/enhancement-loader` | Declared enhancement manifests                              |
@@ -108,11 +109,12 @@ needed.
 
 The JS is designed to run on its own, without Actual's stylesheet.
 
-- **`data-enhance` tokens** register root-controller behaviors. The runtime
-  discovers components through `data-enhance="tabs"`, `data-enhance="flyout"`,
-  `data-enhance="scrollspy"`, and `data-enhance="validation"` — no Actual
-  presentation class needed. Self-describing attributes (`data-mask`,
-  `data-tooltip`, `data-context-menu`) stay framework-neutral by construction.
+- **`data-enhance` tokens** register named behaviors. The runtime discovers
+  components through `data-enhance="tabs"`, `data-enhance="flyout"`,
+  `data-enhance="range"`, `data-enhance="scrollspy"`, and
+  `data-enhance="validation"` — no Actual presentation class needed.
+  Self-describing attributes (`data-mask`, `data-tooltip`,
+  `data-context-menu`) stay framework-neutral by construction.
 - **`selectors.js`** lists the state classes the runtime *writes* (`is-open`,
   `was-validated`, …). Edit this file (or alias it in a bundler) to
   match a different CSS framework's state vocabulary. It is a read-side-only
@@ -326,7 +328,6 @@ import { registerCommands } from "actual-css/js/command";
 
 registerCommands("--toggle-hidden", {
   handle(event, trigger, target) {
-    event.preventDefault();
     target.hidden = !target.hidden;
     trigger.setAttribute("aria-expanded", String(!target.hidden));
   },
@@ -335,10 +336,10 @@ registerCommands("--toggle-hidden", {
 
 The default resolver `targetFor(trigger)` looks up `commandfor` by ID in the
 trigger's document or shadow root. Supply `resolve(trigger)` to validate or
-replace that lookup. An optional idempotent `prepare(trigger, target, command)`
-callback runs directly before `handle`; built-in behaviors use it for
-target-derived semantics. `commandSelector(commands)` builds the matching button
-selector. The returned handle has an idempotent `disconnect()` method for
+replace that lookup. Once a target resolves, the router cancels the click before
+`handle` runs, so the native `command` event is never dispatched for a routed
+command. Names must be a native keyword or start with `--`; anything else
+throws. `commandSelector(commands)` builds the matching button selector. The returned handle has an idempotent `disconnect()` method for
 applications that unload the module owning the command.
 
 ### Dismiss command
@@ -414,10 +415,8 @@ registerEnhancement("autosubmit", (form) => {
 <form data-enhance="validation autosubmit">
 ```
 
-`enhancementSelector(name)` returns the matching `[data-enhance~="name"]`
-selector (names must match `[a-z][a-z0-9-]*`), and `hasEnhancement(el, name)`
-tests it. No core module list is modified — the regression test in
-`tests/enhance.test.js` proves the shape.
+Names must match `[a-z][a-z0-9-]*`. To find opted-in elements from your own
+script, query `[data-enhance~="name"]`; styles keep using presentation classes.
 
 A name is owned once per root: a second `registerEnhancement("autosubmit", …)`
 on the same root throws, and `disconnect()` releases the name so it can be

package/docs/pages/guides/tailwind.md

@@ -17,9 +17,11 @@ If you finish the migration with a new `.mt-4`, `.flex`, `.bg-primary`, and `md:
 
 Tailwind and Actual can temporarily coexist, but some short class names overlap.
 
-Examples include layout and flex-related names such as `.grid`, `.grow`, and `.items-center`.
+The most dangerous is `.outline`: it is an Actual button variant (`.btn.outline`), and Tailwind's `outline` utility draws a real outline on it. Layer order does not save this one — the migration setup above puts Tailwind utilities over Actual on purpose.
 
-For a staged migration, use cascade layers, controlled import order, or a project-side Actual prefix transform where necessary.
+Other overlapping names: `.table`, `.sticky`, `.truncate`, `.prose`, `.sr-only`, plus layout names such as `.grid`, `.grow`, and `.items-center`.
+
+For a staged migration, use cascade layers, controlled import order, or a project-side Actual prefix transform where necessary. The transform lives in the consumer's own pipeline (a build-time rename on the Actual import), not in the Actual CLI, which only bundles. The JavaScript runtime writes state classes (`is-open`, `danger`, …): rename them in `actual-css/js/selectors` too, or flyouts and dialogs never open.
 
 The layered import is the cleanest way to keep both stylesheets during the
 migration:

package/llms.txt

@@ -30,9 +30,10 @@ show supported CSS modules and individual enhancer imports without duplicating
 the full export list here.
 
 Presentation (`class`) and behavior are separate layers. `data-enhance` takes
-four tokens only — `tabs`, `flyout`, `scrollspy`, `validation`; leaf behaviors
-use their own attribute (`data-tooltip`, `data-mask`, `data-filter`,
-`data-context-menu`) and `<dialog>` needs none. See
+five built-in tokens — `tabs`, `flyout`, `range`, `scrollspy`, `validation`.
+Leaf behaviors whose opt-in also carries configuration use their own attribute
+(`data-tooltip`, `data-mask`, `data-filter`, `data-context-menu`), and `<dialog>`
+needs none. See
 [when a token, when a data-*](docs/design-notes/enhancement-contract.md).
 
 Behaviour primitives are independently importable for building custom widgets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.2",
@@ -66,6 +66,7 @@
     "./js/mask": "./src/js/mask.js",
     "./js/menu": "./src/js/menu.js",
     "./js/password": "./src/js/password.js",
+    "./js/range": "./src/js/range.js",
     "./js/scrollspy": "./src/js/scrollspy.js",
     "./js/selectors": "./src/js/selectors.js",
     "./js/tab": "./src/js/tab.js",
@@ -138,12 +139,15 @@
     "check:links": "bun scripts/check-doc-links.js",
     "check:templates": "bun scripts/check-templates.js",
     "check:markup": "bun scripts/check-markup.js",
+    "shot:crop": "bun scripts/shot-crop.js",
     "shot:forced": "bun scripts/forced-colors-shot.js",
     "shot:multi": "bun scripts/multi-shot.js",
     "shot:page": "bun scripts/page-shot.js",
+    "shot:states": "bun scripts/shot-states.js",
     "probe": "bun scripts/probe.js",
     "serve": "bun scripts/serve.js",
     "check:sync": "bun scripts/check-sync.js",
+    "release": "bun scripts/release.js",
     "release:notes": "bun scripts/release-notes.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",

package/reserved-classes.json

@@ -203,6 +203,7 @@
   "separated",
   "shadow-context",
   "shadow-popout-context",
+  "shimmer",
   "sidebar-layout",
   "skeleton",
   "sm",

package/src/css/components/avatar.css

@@ -211,7 +211,7 @@ a.avatar[aria-disabled="true"] {
 }
 
 .avatar-stack > .avatar {
-  box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface);
+  box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface-opaque);
 }
 
 .avatar-stack > .avatar + .avatar {

package/src/css/components/flyout.css

@@ -14,6 +14,7 @@
  * Public hooks:
  * --flyout-inline-size
  * --flyout-max-inline-size
+ * --flyout-pad
  *
  * Internal:
  * --menu-item-size (derived from --control-size for menu rows)
@@ -66,7 +67,9 @@
   );
   overflow: auto;
   margin: 0;
-  padding: var(--space-10);
+  /* Tight by default for action menus, whose items carry their own padding.
+     Rich panels (forms, pickers) opt into dialog air per instance. */
+  padding: var(--flyout-pad, var(--space-10));
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
   background: var(--surface-raised);

package/src/css/components/meter.css

@@ -43,7 +43,7 @@
 }
 
 .meter:not(meter) > * + * {
-  border-inline-start: var(--border-width) solid var(--surface);
+  border-inline-start: var(--border-width) solid var(--surface-opaque);
 }
 
 .meter::-webkit-meter-bar {

package/src/css/components/pagination.css

@@ -3,8 +3,9 @@
  *
  * Docs: docs/pages/components/pagination.md
  *
- * Render .btn elements inside a .pagination list. The active page is marked
- * with aria-current="page"; .btn owns the active state styling.
+ * Render .btn.ghost elements inside a .pagination list. The active page is
+ * marked with aria-current="page"; .btn owns the active state styling, so the
+ * current page is the only filled item.
  *
  * Truncated ranges are plain text (`.muted`, `aria-hidden="true"`), not .btn
  * — they are decorative, not actionable. They still get the same box sizing

package/src/css/components/rating.css

@@ -56,7 +56,7 @@
 }
 
 .rating > input[type="radio"]:focus-visible {
-  outline: var(--focus-outline);
+  outline: var(--focus-ring-width) solid var(--focus);
   outline-offset: var(--focus-outline-offset);
   background: var(--rating-color);
 }