actual-css 0.11.0 → 0.12.0

package/docs/pages/components/meter.md

@@ -70,6 +70,8 @@ marker to that background rather than to the neutral intent.
 
 ### Hooks
 
+- `--meter-track` — track color; raise it when the meter sits on a
+  `--surface-subtle` card, where the default track would disappear.
 - `--bar-height` — bar thickness, shared with `.progress`.
 - `--meter-value` — relative weight of a direct child in a segmented meter.
 

package/docs/pages/components/navbar.md

@@ -1,10 +1,10 @@
 # Navbar
 
-> Horizontal top-level navigation bar with a brand, an inline link list, and a vertical nav-list for drawers.
+> Horizontal top-level navigation bar with a brand, an inline `.cluster` link list, and a vertical `.nav-list` for drawers.
 
 - Use `.navbar` for the horizontal bar shell.
 - `.navbar-brand` is the brand link at the inline start.
-- `.navbar-nav` is the horizontal link list; its items are `.nav-link`.
+- Horizontal links live in a `.cluster`; its items are `.nav-link`.
 - `.nav-list` is the shared vertical navigation list, reused by `.drawer` for stacked links.
 - Mark the current page with `aria-current="page"` on the active `.nav-link`.
 - Presence is the contract: set `aria-current` on the current link and remove
@@ -15,9 +15,9 @@ For a public or normally scrolling page, `.navbar` belongs inside the semantic
 site header. Do not use `.topbar` or `.app-layout` unless the page actually has
 the specialized persistent application-shell behavior those APIs describe.
 
-`.navbar-nav` and `.nav-list` are mutually exclusive: `.navbar-nav` is a horizontal
-flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
-`.nav-list` (vertical) — pick one per container.
+Horizontal navbar links use a `.cluster`. Use `.nav-list` when the navigation
+becomes a full-width vertical list. The two are distinct contracts, so pick one
+per container.
 
 `.navbar` stays the horizontal bar for a site or webapp header with a brand and
 normal document scrolling. `.app-nav` is not merely a stacked-icon flavour of it:
@@ -32,7 +32,6 @@ icons. See [App Navigation](app-navigation.md).
 | --------------- | ----------- | ----------------------------------------------------- |
 | `.navbar`       | Component   | Horizontal bar shell.                                 |
 | `.navbar-brand` | Composition | Brand link at the inline start.                       |
-| `.navbar-nav`   | Composition | Horizontal link list.                                 |
 | `.nav-link`     | Component   | A link item; current page via `aria-current="page"`.  |
 | `.nav-list`     | Component   | Shared vertical navigation list, reused by `.drawer`. |
 
@@ -41,7 +40,7 @@ icons. See [App Navigation](app-navigation.md).
 ```html demo
 <nav class="navbar" aria-label="Main">
   <a class="navbar-brand" href="/">Actual CSS</a>
-  <ul class="navbar-nav">
+  <ul class="cluster">
     <li><a class="nav-link" href="/docs" aria-current="page">Docs</a></li>
     <li><a class="nav-link" href="/components">Components</a></li>
     <li><a class="nav-link" href="/examples">Examples</a></li>
@@ -70,7 +69,7 @@ accessible name.
 ```html demo
 <nav class="navbar" aria-label="Main">
   <a class="navbar-brand" href="/">Actual CSS</a>
-  <ul class="navbar-nav">
+  <ul class="cluster">
     <li><a class="nav-link" href="/" aria-current="page">Home</a></li>
     <li><a class="nav-link" href="/docs">Docs</a></li>
   </ul>
@@ -99,7 +98,7 @@ accessible name.
   </header>
 
   <nav>
-    <ul class="nav-list stack">
+    <ul class="nav-list">
       <li><a class="nav-link" href="#" aria-current="page">Home</a></li>
       <li><a class="nav-link" href="#">Docs</a></li>
       <li><a class="nav-link" href="#">Components</a></li>

package/docs/pages/components/table.md

@@ -101,9 +101,9 @@ table width before the wrapper scrolls horizontally.
 ## Compact tables
 
 `.compact` lowers cell padding and establishes compact density for controls or
-spacing helpers inside cells. Font size and icons stay unchanged; the framework's
-denser font width may apply when the typeface supports it. It is the
-same vocabulary as `.card.compact`.
+spacing helpers inside cells. The text stays as set; a data-heavy table that
+also wants condensed type sets `font-stretch` on itself. It is the same
+vocabulary as `.card.compact`.
 
 ```html demo
 <div class="table-wrap">

package/docs/pages/enhancements/flyout.md

@@ -322,7 +322,7 @@ can be multi-column with `<section>` / `<ul>` groups.
 
 ```html demo
 <nav aria-label="Main navigation">
-  <ul class="list-reset cluster">
+  <ul class="cluster">
     <li class="flyout-trigger">
       <button class="btn ghost"
               type="button"
@@ -373,7 +373,7 @@ a separate `dialog.drawer` when the content needs a modal mobile presentation.
 
 ```html demo
 <nav aria-label="Product navigation">
-  <ul class="list-reset cluster">
+  <ul class="cluster">
     <li class="flyout-trigger">
       <button class="btn ghost"
               type="button"

package/docs/pages/enhancements/scrollspy.md

@@ -26,7 +26,7 @@ or style `[aria-current]` yourself.
 
 ```html demo
 <nav class="scrollspy" data-enhance="scrollspy" aria-label="Page sections">
-  <ol class="nav-list stack">
+  <ol class="nav-list">
     <li><a class="nav-link" href="#overview" aria-current="location">Overview</a></li>
     <li><a class="nav-link" href="#tokens">Tokens</a></li>
     <li><a class="nav-link" href="#components">Components</a></li>

package/docs/pages/enhancements/status-bar.md

@@ -31,14 +31,14 @@ fails to submit shows its `data-validation-message` in the status bar with the
 stays optional.
 
 ```html demo
-<form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
+<form class="stack needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
   <label class="field">
     <span class="field-label">Email</span>
     <input class="input" type="email" name="email" required
            aria-describedby="sb-email-error" />
     <span class="field-error" id="sb-email-error" role="alert">Enter a valid email.</span>
   </label>
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
   </div>
 </form>

package/docs/pages/examples/overview.md

@@ -14,7 +14,7 @@ rest show it composed, isolated, or under stress.
 
 ### Start here
 
-- [Visual guide](../../demo/templates/visual-guide.html) - seventeen illustrated figures on the spacing scale, the layout primitives, and density versus local size
+- [Visual guide](../../demo/templates/visual-guide.html) - twenty illustrated figures on the spacing scale, the layout primitives, and rhythm versus density versus local size
 - [Color guide](../../demo/templates/color-guide.html) - theming principles measured live on `ocean` and `sunset`, in light and dark, as `data-theme` islands
 - [Kitchen sink](../../demo/templates/kitchen-sink.html) - one-screen test bed for themes, scopes, variants and interactions
 
@@ -28,6 +28,7 @@ Whole pages, composed the way a real product would.
 - [Marketing](../../demo/templates/marketing.html) - landing page with typography and fluid type
 - [Blog](../../demo/templates/blog.html) - article page with prose
 - [Settings modal](../../demo/templates/settings-modal.html) - two-pane preferences dialog, with the local CSS it needs audited rule by rule
+- [Modal patterns](../../demo/templates/modal-patterns.html) - eight application modals, each the modal surface plus the smallest application CSS it needs
 - [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and a local segmented tab treatment
 - [Card compositions](../../demo/templates/card-compositions.html) - editorial, team, sign-in and horizontal cards composed from existing primitives
 - [Register form](../../demo/templates/register-form.html) - registration page with choice cards, masks, the password toggle, `tel-prefix` validation, an OTP verification dialog, and status feedback
@@ -59,6 +60,7 @@ extension points.
 
 - [Data grid](../../demo/templates/data-grid.html) - an external data grid component themed with Actual tokens (sort, filter, search, selection)
 - [Combobox](../../demo/templates/combobox.html) - an external combobox themed with Actual tokens (search, tags, autocomplete)
+- [Date fields](../../demo/templates/date-fields.html) - a native date input, a masked text field and an external date picker on Actual tokens, side by side
 
 ## Sites
 

package/docs/pages/forms/date-picker.md

@@ -0,0 +1,90 @@
+# Date picker
+
+> A JavaScript date picker is not shipped by the framework — the native `<input type="date">` stays the baseline. Use `data-mask` for a fixed text shape, or theme an external picker with Actual tokens.
+
+The native control is the default: a real calendar, no JavaScript, and an ISO
+`yyyy-mm-dd` value whatever the platform displays. Reach for an external picker
+only when the product needs a shape the native control cannot express — a month
+grid for a range, a typed constraint, a styled calendar.
+
+**Related terms:** date field, datepicker, calendar, native date, date input, masked date, input mask, date range.
+
+## Native baseline
+
+```html demo
+<label class="field">
+  <span class="field-label">Start date</span>
+  <input class="input" type="date" />
+</label>
+```
+
+## Masked text field
+
+`data-mask` structures a plain text field to a fixed shape and the `date` rule
+validates meaning. The mask enforces shape, not validity, so `2026-13-40` needs
+the rule (or server validation).
+
+```html demo
+<label class="field">
+  <span class="field-label">Date</span>
+  <input class="input" data-mask="9999-99-99" inputmode="numeric" autocomplete="off" placeholder="yyyy-mm-dd" />
+</label>
+```
+
+## Theme bridge
+
+The [date fields template](../../demo/templates/date-fields.html) puts the native
+control, the masked field and
+[`@lekoala/date-picker`](https://github.com/lekoala/date-picker) side by side, the
+picker skinned entirely with Actual tokens.
+
+```html
+<label class="field">
+  <span class="field-label">Booking date</span>
+  <date-picker value="2026-09-25" open-on-focus="false">
+    <input class="input" name="date">
+  </date-picker>
+</label>
+```
+
+```css
+date-picker,
+date-calendar {
+  --dp-bg: var(--surface-raised);
+  --dp-fg: var(--text);
+  --dp-muted: var(--text-muted);
+  --dp-border: var(--border);
+  --dp-hover: var(--surface-subtle);
+  --dp-accent: var(--primary);
+  --dp-accent-fg: var(--primary-fg);
+  --dp-radius: var(--radius);
+  /* Trigger glyph on the select chevron axis. */
+  --dp-picker-button-size: calc(var(--control-pad-x) * 2 + 1em + var(--border-width) * 2);
+}
+
+.dp-calendar-header :where(button, select, input):focus-visible {
+  border-color: var(--dp-border);
+  outline: var(--focus-ring-width) solid var(--focus);
+  outline-offset: calc(var(--focus-ring-width) * -1);
+  box-shadow: none;
+}
+
+.dp-picker-button:focus-visible,
+.dp-day:focus-visible {
+  outline-color: var(--focus);
+}
+```
+
+The field is a plain `.input`, so the core inset focus outline already outranks
+the library's halo; the calendar's own controls paint a `--dp-accent` halo, so
+the two focus rules map them onto the core outline. The calendar popup is its own
+element, so the `--dp-*` map is declared on `date-picker`/`date-calendar` rather
+than inherited from a wrapper.
+As with the combobox, the bridge stays in docs/demo — it is a recipe, not package
+API, and pins no widget version.
+
+## Which one?
+
+- A plain date the platform can collect: native `<input type="date">`.
+- A fixed text format that must survive as typed text: `data-mask` plus the `date` rule.
+- A calendar, range, or constraint the native control cannot express: an external picker on the token bridge.

package/docs/pages/forms/detached-actions.md

@@ -5,12 +5,12 @@
 The simplest case stays inside the form.
 
 ```html
-<form novalidate>
+<form class="stack" novalidate>
   <div class="stack">
     <!-- fields -->
   </div>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button type="button" class="btn outline">Cancel</button>
     <button type="submit" class="btn primary">Save changes</button>
   </div>
@@ -20,40 +20,47 @@ The simplest case stays inside the form.
 For sticky page footers, dialog footers, card footers, and split layouts, detach the actions and connect the submit button with `form="<id>"`.
 
 ```html
-<form id="profile-form" novalidate>
-  <div class="stack">
-    <!-- long form fields -->
-  </div>
-</form>
+<div class="stack">
+  <form id="profile-form" novalidate>
+    <div class="stack">
+      <!-- long form fields -->
+    </div>
+  </form>
 
-<footer class="form-actions">
-  <button type="button" class="btn outline">Cancel</button>
-  <button type="submit" class="btn primary" form="profile-form">
-    Save changes
-  </button>
-</footer>
+  <footer class="cluster form-actions">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary" form="profile-form">
+      Save changes
+    </button>
+  </footer>
+</div>
 ```
 
+The wrapper that holds the form and its detached actions owns the distance
+between them: give it `.stack`.
+
 For multiple submit intents, pair the `form` attribute with `formaction`. The form has one action; each submit button can override it.
 
 ```html
-<form id="article-form"
-      action="/articles/publish"
-      method="post">
-  <!-- fields -->
-</form>
+<div class="stack">
+  <form id="article-form"
+        action="/articles/publish"
+        method="post">
+    <!-- fields -->
+  </form>
 
-<div class="form-actions">
-  <button type="submit"
-          class="btn outline"
-          form="article-form"
-          formaction="/articles/draft">
-    Save draft
-  </button>
-  <button type="submit"
-          class="btn primary"
-          form="article-form">
-    Publish
-  </button>
+  <div class="cluster form-actions">
+    <button type="submit"
+            class="btn outline"
+            form="article-form"
+            formaction="/articles/draft">
+      Save draft
+    </button>
+    <button type="submit"
+            class="btn primary"
+            form="article-form">
+      Publish
+    </button>
+  </div>
 </div>
 ```

package/docs/pages/forms/form-actions.md

@@ -1,20 +1,25 @@
 # Form Actions
 
-> `.form-actions` is a class-only flex row that closes a form. It may live
-> inside or outside the `<form>` (see Detached Actions) and has an opt-in
+> `.form-actions` is the role of the `.cluster` row that closes a form. It may
+> live inside or outside the `<form>` (see Detached Actions) and has an opt-in
 > sticky variant (see Sticky Actions).
 
-The default layout is a wrapping flex row: items are centered on the cross
-axis and start-aligned on the main axis, with a default top margin that
-separates the actions from the fields above.
+`.cluster` owns the row: flex, wrap and gap. `.form-actions` adds the alignment
+policy for form actions and the sticky behaviour. The space before the row
+belongs to the parent layout: put `.stack` on the form.
 
-```html
-<form novalidate>
-  <div class="stack">
-    <!-- fields -->
-  </div>
+`.form-actions` refines `.cluster` with alignment rules of equal specificity,
+so it wins on import order. In a modular build, import `layout/cluster` before
+`forms/form-actions`; the family entries and the full bundle already do.
+
+```html demo
+<form class="stack" novalidate>
+  <label class="field">
+    <span class="field-label">Project name</span>
+    <input class="input" type="text" value="Atlas" />
+  </label>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button type="button" class="btn outline">Cancel</button>
     <button type="submit" class="btn primary">Save changes</button>
   </div>
@@ -23,34 +28,62 @@ separates the actions from the fields above.
 
 ## CSS hooks
 
-The three layout hooks are unset by default and fall back to the values below.
+- `--form-actions-justify` — main-axis distribution (`justify-content`).
+- `--form-actions-align` — cross-axis alignment (`align-items`).
 
-- `--form-actions-align` — `center` — cross-axis alignment (`align-items`).
-- `--form-actions-justify` — `flex-start` — main-axis distribution (`justify-content`).
-- `--form-actions-margin-block-start` — `var(--space-50)` — top margin separating actions from the form.
+Both are inherited role hooks: set them on a page or container to align every
+form action row inside it, without touching other clusters. Below, the
+container right-aligns the form actions while the tag row, also a `.cluster`,
+keeps its start alignment.
 
-### Common arrangements
+```html demo
+<section class="stack" style="--form-actions-justify: flex-end">
+  <div class="cluster">
+    <span class="badge">Draft</span>
+    <span class="badge">Internal</span>
+  </div>
 
-Right-align the submit on wide rows:
+  <form class="stack" novalidate>
+    <label class="field">
+      <span class="field-label">Release title</span>
+      <input class="input" type="text" value="Autumn update" />
+    </label>
 
-```css
-.form-actions {
-  --form-actions-justify: flex-end;
-}
+    <div class="cluster form-actions">
+      <button type="button" class="btn outline">Cancel</button>
+      <button type="submit" class="btn primary">Publish</button>
+    </div>
+  </form>
+</section>
 ```
 
-Stretch each action to fill the full row width:
+In application CSS, the same policy is one declaration on the region:
 
 ```css
-.form-actions {
-  --form-actions-align: stretch;
+.checkout {
+  --form-actions-justify: flex-end;
 }
 ```
 
-Because the hooks are inherited custom properties, set them on a page or
-container to apply one arrangement to every `.form-actions` inside it.
+On a form action row, `--cluster-justify` and `--cluster-align` have no effect;
+use the hooks above, or a `.justify-content-*` / `.items-*` utility on one row.
+A split pair keeps the dismissive action at the leading edge and the committing
+one at the trailing edge:
+
+```html demo
+<form class="stack" novalidate>
+  <label class="field">
+    <span class="field-label">Display name</span>
+    <input class="input" type="text" value="Jane Doe" />
+  </label>
+
+  <div class="cluster form-actions justify-content-space-between">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary">Save</button>
+  </div>
+</form>
+```
 
 > The sticky variant adds `--form-actions-sticky-block-offset`,
 > `--form-actions-sticky-padding`, and `--form-actions-sticky-inline-offset` —
-> see Sticky Actions. `.form-actions` is class-only and works inside or
-> outside the form — see Detached Actions.
+> see Sticky Actions.

package/docs/pages/forms/input-policy.md

@@ -124,7 +124,7 @@ of the value and never rewrites it.
     </span>
   </label>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>

package/docs/pages/forms/overview.md

@@ -10,6 +10,7 @@
 - `.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).
+- A date is native `<input type="date">` first; use `data-mask` for a fixed text shape, or theme an external picker — see [date picker](date-picker.md) and the [date fields template](../../demo/templates/date-fields.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.
@@ -33,7 +34,7 @@
 | `.field-error`  | Composition | Inline error message, shown while invalid.    |
 | `.field-group`  | Composition | `<fieldset>` with a tunable legend gutter.    |
 | `.choice`       | Composition | Choice-label layout around an inline control. |
-| `.form-actions` | Composition | Class-only flex row that closes a form.       |
+| `.form-actions` | Composition | Role of the `.cluster` row closing a form.    |
 
 `.input` shares the text-control recipe with `.textarea` and `.select`, and
 `.select` also has an opt-in enhanced picker. `.field-label` works on a
@@ -46,7 +47,7 @@
 A full form using the control classes, field wrappers, and form actions:
 
 ```html demo
-<form novalidate>
+<form class="stack" novalidate>
   <div class="stack">
 
     <label class="field">
@@ -101,7 +102,7 @@ A full form using the control classes, field wrappers, and form actions:
 
     <fieldset class="field-group">
       <legend class="field-label">Availability</legend>
-      <div class="stack compact">
+      <div class="stack tight">
         <label class="choice">
           <input class="radio" type="radio" name="availability" value="available" checked />
           <span>Available for work</span>
@@ -161,7 +162,7 @@ A full form using the control classes, field wrappers, and form actions:
 
   </div>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button type="button" class="btn outline">Cancel</button>
     <button type="submit" class="btn primary">Save changes</button>
   </div>
@@ -185,7 +186,7 @@ it a stronger fill.
 - `.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"`.
 - `.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.
+- `.form-actions` is the role of a `.cluster` row (`class="cluster form-actions"`) and carries no outer margin: `.stack` on the form spaces it from the fields. 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.
 
 ## Optional automatic required marks