actual-css 0.11.1 → 0.12.0

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
 
@@ -60,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

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

@@ -1,6 +1,6 @@
 # Sticky Actions
 
-> Use `.form-actions sticky` when long forms need reachable submit actions while scrolling.
+> Use `.cluster.form-actions.sticky` when long forms need reachable submit actions while scrolling.
 
 ## Inside the form
 
@@ -8,8 +8,8 @@ The `<form>` is the bounding parent. The sticky stays pinned to the viewport bot
 
 Scroll the page to see the actions stay reachable.
 
-```html demo
-<form novalidate>
+```html demo sticky
+<form class="stack" novalidate>
   <div class="stack">
     <label class="field">
       <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
@@ -57,7 +57,7 @@ Scroll the page to see the actions stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack compact">
+      <div class="stack tight">
         <label class="choice">
           <input class="radio" type="radio" name="theme" value="light" checked />
           <span>Light</span>
@@ -79,7 +79,7 @@ Scroll the page to see the actions stay reachable.
     </label>
   </div>
 
-  <div class="form-actions sticky">
+  <div class="cluster form-actions sticky">
     <button type="button" class="btn outline">Cancel</button>
     <button type="submit" class="btn primary">Save changes</button>
   </div>
@@ -92,84 +92,86 @@ For a sticky page footer, dialog footer, or card footer, detach the actions and
 
 Scroll the page to see the detached footer stay reachable.
 
-```html demo
-<form id="account-form" novalidate>
-  <div class="stack">
-    <label class="field">
-      <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
-      <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Email <span class="required-mark" aria-hidden="true">*</span></span>
-      <input class="input" type="email" autocomplete="email" required />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Phone</span>
-      <input class="input" type="tel" autocomplete="tel" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Bio</span>
-      <textarea class="textarea" rows="4" placeholder="Tell us about yourself…"></textarea>
-    </label>
-
-    <label class="field">
-      <span class="field-label">Website</span>
-      <input class="input" type="url" autocomplete="url" placeholder="https://example.com" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Language</span>
-      <select class="select">
-        <option>English</option>
-        <option>Français</option>
-        <option>Deutsch</option>
-      </select>
-    </label>
-
-    <label class="field">
-      <span class="field-label">Experience level</span>
-      <input class="range" type="range" min="0" max="10" value="5" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Profile picture</span>
-      <input class="file" type="file" accept="image/*" />
-    </label>
-
-    <fieldset class="field-group">
-      <legend class="field-label">Theme</legend>
-      <div class="stack compact">
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="light" checked />
-          <span>Light</span>
-        </label>
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="dark" />
-          <span>Dark</span>
-        </label>
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="auto" />
-          <span>System</span>
-        </label>
-      </div>
-    </fieldset>
-
-    <label class="choice">
-      <input class="check" type="checkbox" />
-      <span>Email notifications</span>
-    </label>
-  </div>
-</form>
-
-<footer class="form-actions sticky">
-  <button type="button" class="btn outline">Cancel</button>
-  <button type="submit" class="btn primary" form="account-form">
-    Save changes
-  </button>
-</footer>
+```html demo sticky
+<div class="stack">
+  <form id="account-form" novalidate>
+    <div class="stack">
+      <label class="field">
+        <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
+        <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Email <span class="required-mark" aria-hidden="true">*</span></span>
+        <input class="input" type="email" autocomplete="email" required />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Phone</span>
+        <input class="input" type="tel" autocomplete="tel" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Bio</span>
+        <textarea class="textarea" rows="4" placeholder="Tell us about yourself…"></textarea>
+      </label>
+
+      <label class="field">
+        <span class="field-label">Website</span>
+        <input class="input" type="url" autocomplete="url" placeholder="https://example.com" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Language</span>
+        <select class="select">
+          <option>English</option>
+          <option>Français</option>
+          <option>Deutsch</option>
+        </select>
+      </label>
+
+      <label class="field">
+        <span class="field-label">Experience level</span>
+        <input class="range" type="range" min="0" max="10" value="5" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Profile picture</span>
+        <input class="file" type="file" accept="image/*" />
+      </label>
+
+      <fieldset class="field-group">
+        <legend class="field-label">Theme</legend>
+        <div class="stack tight">
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="light" checked />
+            <span>Light</span>
+          </label>
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="dark" />
+            <span>Dark</span>
+          </label>
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="auto" />
+            <span>System</span>
+          </label>
+        </div>
+      </fieldset>
+
+      <label class="choice">
+        <input class="check" type="checkbox" />
+        <span>Email notifications</span>
+      </label>
+    </div>
+  </form>
+
+  <footer class="cluster form-actions sticky">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary" form="account-form">
+      Save changes
+    </button>
+  </footer>
+</div>
 ```
 
 ## CSS hooks

package/docs/pages/forms/validation.md

@@ -62,7 +62,7 @@ there is no init call. To opt in forms you cannot mark up, call
 `actual-css/js/enhance`.
 
 ```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.">
   <div class="stack">
     <label class="field">
       <span class="field-label">Password</span>
@@ -81,7 +81,7 @@ there is no init call. To opt in forms you cannot mark up, call
     </label>
   </div>
 
-  <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>
@@ -139,7 +139,7 @@ The status bar (`actual-css/js/status`) auto-wires to that event: import it and
         Switch this on to submit.
       </span>
     </div>
-    <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>
@@ -197,7 +197,7 @@ Add your own with `FormValidator.registerRule(name, (value, el, ...opts) => bool
     <span class="field-error" id="attachment-error">Choose a .pdf or .csv file.</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>
@@ -246,7 +246,7 @@ The `date` rule pairs naturally with `data-mask` — the mask structures input,
     </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>