actual-css 0.2.0 → 0.3.1

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

@@ -0,0 +1,187 @@
+# Sticky Actions
+
+> Use `.form-actions sticky` when long forms need reachable submit actions while scrolling.
+
+## Inside the form
+
+The `<form>` is the bounding parent. The sticky stays pinned to the viewport bottom while the form is taller than the viewport, then releases when the form's bottom edge reaches it.
+
+Scroll the page to see the actions stay reachable.
+
+```html demo
+<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">
+        <label class="choice">
+          <input class="radio" type="radio" name="theme" value="light" checked />
+          <span>Light</span>
+        </label>
+        <label class="choice">
+          <input class="radio" type="radio" name="theme" value="dark" />
+          <span>Dark</span>
+        </label>
+        <label class="choice">
+          <input class="radio" type="radio" name="theme" value="auto" />
+          <span>System</span>
+        </label>
+      </div>
+    </fieldset>
+
+    <label class="choice">
+      <input class="check" type="checkbox" />
+      <span>Email notifications</span>
+    </label>
+  </div>
+
+  <div class="form-actions sticky">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary">Save changes</button>
+  </div>
+</form>
+```
+
+## Detached from the form
+
+For a sticky page footer, dialog footer, or card footer, detach the actions and connect the submit button with the `form` attribute. The bounding parent becomes the wrapper that holds both the form and the actions.
+
+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">
+        <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>
+```
+
+## CSS hooks
+
+- `--z-sticky` — layering token, defaults to `10`.
+- `--form-actions-sticky-padding` — inner padding, defaults to `--space-30`.
+- `--form-actions-sticky-inline-offset` — full-bleed escape hatch for sticky actions inside padded containers. Set this on the page, not the form.
+
+```css
+.settings-page {
+  --form-actions-sticky-inline-offset: var(--space-40);
+}
+```
+
+A sticky footer can cover the last field on short pages. That is a page-layout concern, not a framework concern. Add bottom padding to the page or scroll container if needed.

package/docs/pages/forms/switch.md

@@ -0,0 +1,31 @@
+# Switches
+
+> Toggle controls that share a native checkbox at the markup level, with a switch visual.
+
+- The API is `class="switch"`. Use `role="switch"` for ARIA correctness.
+- The visual state tracks the native `checked` attribute. No JavaScript is required.
+- For strict ARIA correctness, keep `aria-checked` in sync. This is an enhancement, not the baseline.
+
+```html demo
+<!-- Default: native state, no JS required. -->
+<input class="switch" type="checkbox" role="switch" checked />
+```
+
+```html demo
+<!-- Enhancement: keep aria-checked in sync. -->
+<input class="switch"
+       type="checkbox"
+       role="switch"
+       aria-checked="true"
+       checked
+       onchange="this.setAttribute('aria-checked', this.checked)" />
+```
+
+## CSS hooks
+
+- `--switch-width` — track width.
+- `--switch-block-size` — track height.
+- `--switch-knob-margin` — inset between knob and track.
+
+Knob size and travel distance are derived from these three; set the three rather
+than the derived values. Prefer `.sm` / `.lg`, which change `--control-size`.

package/docs/pages/forms/validation.md

@@ -0,0 +1,241 @@
+# Validation
+
+> Inline error feedback that respects assistive technology and form state.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.field-error` | Composition | Canonical inline error message; shown while the field is invalid. |
+| `.field-help` | Composition | Canonical helper text; carries supporting copy before and after validation. |
+| `.field.danger` | Modifier | Manual invalid marking on the field wrapper. |
+| `.needs-validation` | Modifier | Opt-in class for the validation enhancer and `:user-invalid` styling. |
+| `.was-validated` | Modifier | Added to the form by the enhancer after the first submit attempt. |
+| `.status-bar` | Component | Optional status element that shows `data-validation-message` on invalid submit. |
+
+- `.field-error` is the canonical error message. It is wired to `aria-invalid="true"` via the input, so the visual border and the assistive-tech announcement move together.
+- `.field-help` is the canonical helper text. It carries supporting copy before and after validation.
+- Set `aria-invalid="true"` on the input. The `.field-error` element is linked via `aria-describedby`.
+- `role="alert"` on `.field-error` is only required when the message is inserted dynamically. Static messages do not need it.
+
+```html demo
+<form novalidate>
+  <div class="stack">
+    <label class="field">
+      <span class="field-label">Email</span>
+      <input class="input" type="email"
+             value="jane@"
+             aria-invalid="true"
+             aria-describedby="email-error" />
+      <span class="field-error" id="email-error" role="alert">
+        Enter a valid email address
+      </span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Username</span>
+      <input class="input" type="text" value="janedoe" aria-describedby="username-help" />
+      <span class="field-help" id="username-help">
+        Username is available.
+      </span>
+    </label>
+  </div>
+</form>
+```
+
+## Optional JavaScript enhancer
+
+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 default runtime (`actual-css/js`) 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.
+
+```html demo
+<form class="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>
+      <input class="input" type="password" name="password" id="password" required
+             minlength="8" maxlength="128"
+             aria-describedby="password-error" />
+      <span class="field-error" id="password-error">Enter a password.</span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Confirm password</span>
+      <input class="input" type="password" name="confirm" required
+             data-validation-rules="same #password"
+             aria-describedby="confirm-error" />
+      <span class="field-error" id="confirm-error" role="alert">Passwords must match.</span>
+    </label>
+  </div>
+
+  <div class="form-actions">
+    <button class="btn primary" type="submit">Submit</button>
+    <button class="btn neutral outline" type="reset">Reset</button>
+  </div>
+</form>
+```
+
+On blur, the enhancer sets `aria-invalid="true"` on the invalid field so visual and assistive-tech state move together. On submit, it adds `.was-validated` to the form and marks every invalid field. When the form is invalid it prevents submission, focuses the first invalid field, and dispatches a bubbling `actual:invalid` event with `{ form, firstInvalid, message }`. On reset, it clears all validation state — `.was-validated`, `aria-invalid`, `.field.danger`, and custom-validity messages — which native reset alone would leave behind.
+
+The status bar (`actual-css/js/status`) auto-wires to that event: import it and add one status element, and the form's `data-validation-message` appears automatically on invalid submit — no manual listener.
+
+```html demo
+<form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
+  <div class="stack">
+    <label class="field">
+      <span class="field-label">Email</span>
+      <input class="input" type="email" name="email" required
+             aria-describedby="demo-email-error" />
+      <span class="field-error" id="demo-email-error" role="alert">
+        Enter a valid email.
+      </span>
+    </label>
+
+    <label class="field">
+      <span class="field-label">Quantity</span>
+      <input class="input" name="quantity" inputmode="numeric" required
+             data-validation-rules="digits"
+             aria-describedby="demo-quantity-error" />
+      <span class="field-error" id="demo-quantity-error" role="alert">
+        Use digits only.
+      </span>
+    </label>
+
+    <div class="field">
+      <label class="choice">
+        <input class="check" type="checkbox" name="terms" required
+               aria-describedby="demo-terms-error" />
+        <span>
+          <span class="field-label">Accept the terms</span>
+        </span>
+      </label>
+      <span class="field-error" id="demo-terms-error" role="alert">
+        Required before continuing.
+      </span>
+    </div>
+
+    <div class="field">
+      <label class="choice">
+        <input class="switch" type="checkbox" role="switch" name="confirm" required
+               aria-describedby="demo-confirm-error" />
+        <span>
+          <span class="field-label">Confirm setup</span>
+        </span>
+      </label>
+      <span class="field-error" id="demo-confirm-error" role="alert">
+        Switch this on to submit.
+      </span>
+    </div>
+    <div class="form-actions">
+      <button class="btn primary" type="submit">Submit</button>
+      <button class="btn neutral outline" type="reset">Reset</button>
+    </div>
+  </div>
+</form>
+
+<div class="status-bar" data-status role="status" aria-live="polite" aria-atomic="true"></div>
+```
+
+If you prefer to handle the summary yourself, listen for `actual:invalid` instead of importing the status module:
+
+```js
+document.addEventListener("actual:invalid", (event) => {
+  const { firstInvalid, message } = event.detail;
+  // e.g. scroll to firstInvalid, or route message to your own surface
+});
+```
+
+### Built-in custom rules
+
+Custom rules live in `data-validation-rules` as a comma-separated list; each rule may take space-separated options. The enhancer registers a few defaults:
+
+- `same <selector>` — Value must equal the value of the element matched by `<selector>` (scoped to the field's form).
+- `number` — Value is empty or a valid `Number`.
+- `digits` — Value is empty or ASCII digits only.
+- `alnum` — Value is empty or letters and digits only.
+- `date` — Value is a valid date in `yyyy-mm-dd`, `dd/mm/yyyy`, `mm/dd/yyyy`, `dd.mm.yyyy`, `mm.dd.yyyy`, `dd-mm-yyyy`, or `mm-dd-yyyy` shape; rejects non-existent dates like `2026-02-29`. ISO remains the recommended wire format because servers can parse it without guessing.
+
+Add your own with `FormValidator.registerRule(name, (value, el, ...opts) => boolean)`. The built-in rules treat empty values as valid so optional fields stay optional; custom rules should do the same when that behavior is wanted.
+
+The `date` rule pairs naturally with `data-mask` — the mask structures input, the rule validates meaning. Same rule, different formats:
+
+```html demo
+<form class="stack needs-validation" data-enhance="validation" novalidate>
+  <label class="field">
+    <span class="field-label">Date (ISO)</span>
+    <input class="input" name="date-iso"
+           data-mask="9999-99-99"
+           data-validation-rules="date"
+           inputmode="numeric"
+           autocomplete="off"
+           placeholder="yyyy-mm-dd"
+           aria-describedby="date-iso-help date-iso-error"
+           required />
+    <span class="field-help" id="date-iso-help">
+      yyyy-mm-dd format.
+    </span>
+    <span class="field-error" id="date-iso-error">
+      Enter a valid date.
+    </span>
+  </label>
+
+  <label class="field">
+    <span class="field-label">Date (European)</span>
+    <input class="input" name="date-eu"
+           data-mask="99/99/9999"
+           data-validation-rules="date"
+           inputmode="numeric"
+           autocomplete="off"
+           placeholder="dd/mm/yyyy"
+           aria-describedby="date-eu-help date-eu-error"
+           required />
+    <span class="field-help" id="date-eu-help">
+      dd/mm/yyyy format.
+    </span>
+    <span class="field-error" id="date-eu-error">
+      Enter a valid date.
+    </span>
+  </label>
+
+  <div class="form-actions">
+    <button class="btn primary" type="submit">Submit</button>
+    <button class="btn neutral outline" type="reset">Reset</button>
+  </div>
+</form>
+```
+
+Custom rules only run when the field has a value. Empty fields skip all custom rules — `required` is the sole gatekeeper for empty values. A custom date rule for a stricter app-specific format could look like:
+
+```js
+FormValidator.registerRule("iso-date", (value) => {
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value));
+});
+```
+
+### Server and AJAX validation
+
+The enhancer never makes network calls. After a valid client submit, your own `form[data-ajax]` flow (see the JavaScript docs) performs the request and maps server errors back onto fields through the public API:
+
+```js
+import { FormValidator } from "actual-css/js/validation";
+
+// server responded with field errors
+FormValidator.setErrors(form, { email: "Already taken" });
+
+// clear a single field once fixed
+FormValidator.clearFieldError(form.elements.email);
+```
+
+`setErrors` resolves each name to a field, sets `aria-invalid`, the field's `.field-error` text, and `setCustomValidity` so the next submit stays blocked until corrected.
+
+### State coverage
+
+Invalid visuals converge across the three ways a field can be flagged:
+`aria-invalid="true"`, `.needs-validation.was-validated :invalid`, and
+`:user-invalid`. Each sets the danger border, and a checked or indeterminate
+`.check`, `.radio`, or `.switch` also flips its fill to danger so border and
+fill signal together. Choice cards surface the same invalid state on the card
+border. The exact selector coverage is asserted by `tests/validation.test.js`.

package/docs/{mental-model.md → pages/foundations/philosophy.md}

@@ -1,4 +1,6 @@
-# Mental model
+# Philosophy
+
+How components, intents, variants, and density compose — and what each layer is responsible for.
 
 ## Components
 
@@ -8,7 +10,7 @@ Components are semantic boxes: `.btn`, `.badge`, `.alert`, `.card`, `.avatar`, e
 
 `.primary`, `.secondary`, `.success`, `.warning`, `.danger` do not style elements directly. They only expose `--intent` and `--intent-fg`. Components and variants decide how to consume them.
 
-```html
+```html demo
 <button class="btn primary">Primary</button>
 <span class="badge success">Success</span>
 ```
@@ -26,48 +28,61 @@ Custom intents need no framework support — define `--intent` and `--intent-fg`
 }
 ```
 
-```html
+```html demo
 <button class="btn tertiary">Tertiary</button>
 <span class="badge tertiary">Tertiary</span>
 ```
 
 ## Variants
 
-`.solid`, `.soft`, `.outline` define the visual treatment by setting `--ui-bg`, `--ui-fg`, `--ui-border` (and optionally `--ui-hover-bg`). Components consume these tokens with sensible fallbacks.
+`.solid`, `.soft`, `.outline` define the visual treatment by setting `--ui-bg`, `--ui-fg`, `--ui-border`. Components consume these tokens with sensible fallbacks. Interactive components also set a `--ui-hover-bg` recipe that their hover rule reads.
 
-`.btn` and `.badge` default to `.solid`. `.alert` defaults to `.soft`.
+`.btn` defaults to `.solid`; `.badge` and `.alert` default to `.soft`.
 
 `.ghost` and `.link` are button-only variants.
 
-```html
+```html demo
 <button class="btn soft primary">Soft primary</button>
 <span class="badge outline success">Outline success</span>
 <div class="alert solid warning">Solid warning</div>
 ```
 
-## Sizes
+## Density
+
+`.sm` and `.lg` establish inherited density tokens. Density adjusts how much
+space UI consumes — spacing and component geometry — not how large its content
+is: typography and icon size never change. Components opt into the density
+dimensions that make sense for them. The same modifiers can also be applied
+directly to a component for local density.
 
-`.sm` and `.lg` are contextual modifiers. They set inherited size tokens (`--control-size`, `--variant-font-size`, etc.) that components opt into.
+As inherited contexts, one class tightens or loosens the whole subtree:
 
-```html
+```html demo
 <div class="sm">
-  <button class="btn">Small button</button>
-  <span class="badge">Small badge</span>
+  <button class="btn">Compact button</button>
+  <input class="input">
+  <span class="badge">Compact badge</span>
 </div>
 ```
 
-Works locally too:
+The same class on a component is local density, not a second meaning:
 
-```html
-<button class="btn sm">Small button</button>
-<span class="badge lg">Large badge</span>
+```html demo
+<button class="btn sm">Compact button</button>
+<span class="badge lg">Spacious badge</span>
 ```
 
-Components with bespoke sizing (`.avatar`, `.spinner`) define local `.sm`/`.lg` instead.
+This is not "`.sm` sometimes means density and sometimes size": `.sm` always
+establishes the same density tokens — only the scope changes. The density
+tokens are `--gap`, `--density-space`, `--control-size`, and
+`--density-compact-size`. Components consume the dimensions that make sense
+for them and opt out of the rest.
+
+Components with bespoke sizing (`.avatar`, `.spinner`) define local `.sm`/`.lg`
+instead of consuming the shared tokens.
 
 ## Child semantics
 
 When using a component, child elements follow the semantic pattern of that component. For example, `.avatar` accepts `<img>`, `<picture>`, text content, an empty `.badge` for status dots, and can be a `<button>` or `<a>`.
 
-No child classes like `.avatar-img` are needed.
-
+No child classes like `.avatar-img` are needed.

package/docs/pages/foundations/theming.md

@@ -0,0 +1,99 @@
+# Theming
+
+Find the right lever when you want to change how a component or layout looks, without knowing in advance which custom property to use.
+
+This is a problem-oriented index. It maps common intents to the public hooks and primitives that express them, then points to the canonical section. It is not a catalogue of every variable — the CSS source remains canonical for exact defaults and fallback chains. See the tokens page, Public surface section, for the public/internal rule.
+
+## I want to…
+
+### Split / spread / put two items apart / one left, one right
+
+Use `.cluster` with `--cluster-justify: space-between`. There is no separate `.split` or `.spread` primitive.
+
+→ Layout · Cluster
+
+### Align cluster items / top-align a toolbar row
+
+Set `--cluster-align`.
+
+→ Layout · Cluster
+
+### Change spacing without changing control size
+
+Set `--gap` locally on the layout primitive. The optional `utilities-extra.css` layer ships `.gap-sm` / `.gap-md` / `.gap-lg` for row/column containers.
+
+→ Layout
+
+### Custom or asymmetric grid columns
+
+Set `--grid-columns` on `.grid`. Use `--grid-min` to tune the responsive item width.
+
+→ Layout · Grid
+
+### Rounded card / change a card's radius
+
+Set `--card-radius`. `--card-pad` also drives `.bleed` offsets.
+
+→ Components · Card
+
+### Wider or narrower modal / dialog
+
+Set `--modal-size`.
+
+→ Components · Dialog
+
+### Resize a drawer or sidebar panel
+
+Set `--drawer-size` for drawers, `--sidebar-layout-size` for sidebars.
+
+→ Components · Drawer · Layout · Sidebar layout
+
+### Right- or center-align form actions
+
+Set `--form-actions-justify` (and `--form-actions-align`).
+
+→ Forms · Form actions
+
+### Customize a switch's size
+
+Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob size and travel are derived from them. Prefer `.sm` / `.lg` first.
+
+→ Forms · Switch
+
+### Dim disabled controls
+
+Set `--disabled-opacity`. All disabled-prone components — buttons, tabs, menu items, badges, avatars, choice cards, native inputs, and range sliders — read it for their dimmed state.
+
+### Loading / busy overlay on a container
+
+Use `aria-busy="true"` with a direct last-child `.spinner`; tint the overlay with `--busy-overlay-bg`.
+
+→ Components · Card
+
+### Set card-rail item width in a scroll-snap row
+
+Set `--scroll-snap-item-size`.
+
+→ Layout · Scroll snap
+
+### Resize an avatar or its stack
+
+Set `--avatar-size` / `--avatar-radius`; tune overlap with `--avatar-stack-overlap` and `--avatar-stack-ring`.
+
+→ Components · Avatar
+
+### Make an inverted / contrasting surface
+
+Apply `.inverted` to create one contrasting surface context. It paints a bare
+block (`<header class="inverted">`, `<section class="inverted">`) with
+`--surface-solid` and `--surface`; contextual content and transparent treatments
+follow that foreground. Apply it directly to a component that consumes the
+shared `--ui-*` contract when that component itself is the contrasting surface.
+
+Surface-owning descendants keep their own component surface and establish a new
+foreground context. Use `data-theme="dark"`, `data-theme="light"`, or a named
+theme instead when an entire subtree — including forms, states, and nested
+surfaces — must use another palette. More specific component states or explicit
+surface variants (`.card.subtle`) still take precedence.
+
+→ Components · Card · Foundations · Tokens (theme contract)