actual-css 0.1.0 → 0.3.0

package/docs/pages/enhancements/tooltip.md

@@ -0,0 +1,130 @@
+# Tooltip
+
+> Supplemental label for a trigger, shown on hover and focus, hidden on dismissal.
+
+Tooltips are supplemental: `data-tooltip` on the trigger wires a `.tooltip`
+element (`role="tooltip"`) that appears near the trigger. Position, placement,
+and arrow position are written by JavaScript; the element is shown and hidden
+with the `hidden` attribute.
+
+- Use `data-tooltip` on the trigger. With text (`data-tooltip="Help"`), the tooltip element is generated. Empty (`data-tooltip`) marks an explicit tooltip connected via `aria-describedby`.
+- Tooltips are supplemental. Do not put required information or interactive controls inside them.
+- Show on hover and focus. Hide on Escape, blur, pointer leave, or scroll when appropriate.
+- JavaScript can generate tooltip elements from `data-tooltip`.
+- Add `data-tooltip-click` to toggle it on click instead of hover/focus.
+- Add `data-tooltip-visible` to show it immediately and keep it visible while its trigger is in view.
+- Use `data-tooltip-placement` to set the preferred placement (default `top`).
+- The arrow inherits the tooltip background — custom gradients carry through automatically.
+- Avoid relying on the native `title` attribute as the primary implementation.
+
+```html demo
+<button class="btn ghost"
+        type="button"
+        data-tooltip
+        aria-describedby="tooltip-save"
+        aria-label="Save">
+  <i class="ti ti-device-floppy" aria-hidden="true"></i>
+</button>
+
+<div class="tooltip" role="tooltip" id="tooltip-save" hidden>
+  Save changes
+</div>
+```
+
+```html demo
+<button class="btn" type="button" data-tooltip="Save changes">
+  Save
+</button>
+```
+
+## Display modes
+
+Click tooltips stay open when the pointer leaves and close on a second click or
+Escape. They remain supplemental, non-interactive content; use a flyout when the
+floating content contains controls.
+
+```html demo
+<p class="cluster">
+  <button class="btn outline" type="button"
+          data-tooltip="Click again or press Escape to close"
+          data-tooltip-click>
+    Toggle on click
+  </button>
+
+  <button class="btn outline" type="button"
+          data-tooltip="Always visible while this trigger is in view"
+          data-tooltip-visible
+          data-tooltip-placement="bottom">
+    Always visible
+  </button>
+</p>
+```
+
+## HTML and long content
+
+The `data-tooltip="…"` shorthand is intentionally plain text. For trusted HTML,
+use an explicit tooltip referenced by `aria-describedby`. Keep its content
+non-interactive and concise; long content wraps up to the tooltip's
+viewport-aware maximum width.
+
+```html demo
+<button class="btn" type="button"
+        data-tooltip
+        aria-describedby="tip-rich-long"
+        data-tooltip-placement="bottom">
+  Long HTML tooltip
+</button>
+
+<div class="tooltip" role="tooltip" id="tip-rich-long" hidden>
+  <strong>Keyboard shortcut:</strong> press <kbd>Ctrl</kbd> + <kbd>K</kbd> to open search.
+  This longer explanation demonstrates wrapping when a supplemental label needs a little more context.
+</div>
+```
+
+## Positioning
+
+Set `data-tooltip-placement` to control where the tooltip appears relative to
+its trigger. The arrow follows the placement automatically.
+
+```html demo
+<p>
+  <button class="btn outline" type="button" data-tooltip="Above the button" data-tooltip-placement="top">Top</button>
+  <button class="btn outline" type="button" data-tooltip="To the right" data-tooltip-placement="right">Right</button>
+  <button class="btn outline" type="button" data-tooltip="Below the button" data-tooltip-placement="bottom">Bottom</button>
+  <button class="btn outline" type="button" data-tooltip="To the left" data-tooltip-placement="left">Left</button>
+</p>
+```
+
+## Custom styling
+
+Override `--tooltip-bg` and `--tooltip-fg` on the tooltip element to change the
+background and text color. The arrow picks up `background: inherit` so gradients
+and solid colors both work.
+
+```html demo
+<button class="btn primary" type="button"
+        data-tooltip
+        aria-describedby="tip-grad"
+        data-tooltip-placement="right">
+  Hover for gradient
+</button>
+
+<div class="tooltip" role="tooltip" id="tip-grad" hidden
+     style="background-color: #5b2d9e;
+            --tooltip-bg: linear-gradient(135deg, oklch(0.45 0.22 280), oklch(0.5 0.2 10));
+            --tooltip-fg: white;
+            padding: 0.4em 0.8em;
+            font-weight: var(--font-weight-medium);">
+  <strong>Custom gradient tooltip:</strong> the arrow matches the background, and this longer
+  sentence demonstrates how the tooltip wraps and flips when the preferred side lacks space.
+</div>
+```
+
+## CSS hooks
+
+- `--tooltip-bg` — bubble background (defaults to `var(--surface-solid)`); the arrow follows it.
+- `--tooltip-fg` — text color.
+- `--tooltip-arrow-size` — arrow size.
+
+`--arrow-x` and `--arrow-y` are written by the positioner at runtime, not set by
+the author. See the JavaScript runtime documentation.

package/docs/pages/examples/overview.md

@@ -0,0 +1,41 @@
+# Examples
+
+> Real pages built with Actual CSS - an admin application and a set of standalone templates - to see the primitives, components, and patterns composed the way they are meant to be used.
+
+The examples live in the repository under `demo/` and load the shipped bundles
+from `dist/` (`actual.css`, `optional.css`, `actual-themes.min.css`,
+`actual.js`), referenced with stable URLs.
+
+## Admin application
+
+`demo/admini/` is a complete admin interface: application shell, navigation,
+tables, forms, dialogs, and feedback states.
+
+- [Dashboard](../../demo/admini/index.html) - app shell, navbar, stat cards, charts, recent activity
+- [Login](../../demo/admini/login.html) - centered auth card with social actions
+- [Forms](../../demo/admini/forms.html) - inputs, choice cards, validation, joined controls, sticky actions
+- [Tables](../../demo/admini/tables.html) - data tables, status badges, bulk actions
+- [Kanban](../../demo/admini/kanban.html) - drag-free column layout with cards
+- [Chat](../../demo/admini/chat.html) - conversation list, message thread, composer
+- [Calendar](../../demo/admini/calendar.html) - month grid with event cards
+- [Invoice](../../demo/admini/invoice.html) - structured document layout
+- [Profile](../../demo/admini/profile.html) - avatar, tabs, settings rows
+- [Settings](../../demo/admini/settings.html) - grouped settings with switches
+- [User grid](../../demo/admini/user-grid.html) - avatar grid, filters, pagination
+- [404](../../demo/admini/404.html) - empty state
+
+## Templates
+
+`demo/templates/` are standalone pages covering common page shapes.
+
+- [Kitchen sink](../../demo/templates/kitchen-sink.html) - every component and variant on one page
+- [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
+- [Dashboard](../../demo/templates/dashboard.html) - data-heavy overview page
+- [App](../../demo/templates/app.html) - application shell with sidebar
+- [Marketing](../../demo/templates/marketing.html) - landing page with typography and fluid type
+- [Blog](../../demo/templates/blog.html) - article page with prose
+- [Blocks](../../demo/templates/blocks.html) - layout building blocks
+- [Density](../../demo/templates/density.html) - compact control density
+
+> Note: the examples reference the repository's source files, so they open from
+> the checkout, not from a standalone copy of `site`.

package/docs/pages/forms/choice-cards.md

@@ -0,0 +1,102 @@
+# Choice Cards
+
+> Card-style radio and checkbox labels where the whole card acts as a clickable target.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.choice-card` | Component | Card-style `<label>` wrapping a native radio or checkbox; the whole card is the click target. |
+| `.primary` / `.secondary` | Intent | Intent accent for the selected state (supported on the card). |
+
+- Use `.choice-card` on a `<label>` wrapping a native `<input type="radio">` or `<input type="checkbox">`. The input is visually hidden; in browsers without `:has()` it stays visible so selection state never disappears.
+- Selected items show a primary border, subtle background tint, and a checkmark badge at the top-right corner — round for radio, rounded square for checkbox.
+- Pair with grid or flex utilities for group layout. The badge overhangs the top-right corner, so avoid `overflow: hidden` on the direct container.
+- Supports disabled, checked, focus-visible, and invalid states.
+
+```html demo
+<div class="grid-3">
+  <label class="choice-card">
+    <input type="radio" name="cpu" value="1" checked />
+    <strong>8-core CPU</strong>
+    <span class="muted">32 GB RAM</span>
+  </label>
+  <label class="choice-card">
+    <input type="radio" name="cpu" value="2" />
+    <strong>6-core CPU</strong>
+    <span class="muted">24 GB RAM</span>
+  </label>
+  <label class="choice-card">
+    <input type="radio" name="cpu" value="3" />
+    <strong>4-core CPU</strong>
+    <span class="muted">16 GB RAM</span>
+  </label>
+</div>
+```
+
+```html demo
+<fieldset class="field-group">
+  <legend class="field-label">Features</legend>
+  <div class="grid-3">
+    <label class="choice-card">
+      <input type="checkbox" name="features" value="wifi" checked />
+      <strong>WiFi</strong>
+      <span class="muted">Dual-band 2.4/5 GHz</span>
+    </label>
+    <label class="choice-card">
+      <input type="checkbox" name="features" value="bluetooth" />
+      <strong>Bluetooth</strong>
+      <span class="muted">5.3, low energy</span>
+    </label>
+    <label class="choice-card">
+      <input type="checkbox" name="features" value="nfc" disabled />
+      <strong>NFC</strong>
+      <span class="muted">Coming soon</span>
+    </label>
+  </div>
+</fieldset>
+```
+
+Validation follows the shared pattern: `aria-invalid="true"` on the input (set manually or by the `.needs-validation` enhancer) turns the card border to danger, and a `.field-error` inside a `.field` wrapper is shown.
+
+```html demo
+<fieldset class="field field-group">
+  <legend class="field-label">Plan</legend>
+  <div class="grid-3">
+    <label class="choice-card">
+      <input type="radio" name="plan" value="starter"
+             aria-invalid="true" aria-describedby="plan-error" />
+      <strong>Starter</strong>
+      <span class="muted">1 project</span>
+    </label>
+    <label class="choice-card">
+      <input type="radio" name="plan" value="pro"
+             aria-invalid="true" aria-describedby="plan-error" />
+      <strong>Pro</strong>
+      <span class="muted">Unlimited projects</span>
+    </label>
+    <label class="choice-card">
+      <input type="radio" name="plan" value="team"
+             aria-invalid="true" aria-describedby="plan-error" />
+      <strong>Team</strong>
+      <span class="muted">Unlimited + SSO</span>
+    </label>
+  </div>
+  <span class="field-error" id="plan-error" role="alert">
+    Choose a plan to continue.
+  </span>
+</fieldset>
+```
+
+Sizes follow the shared `.sm` and `.lg` modifiers. Intent classes (`.primary`, `.secondary`) are supported on the `.choice-card` element.
+
+## CSS hooks
+
+- `--choice-card-pad` — inner padding.
+- `--choice-card-radius` — corner radius.
+- `--choice-card-check-size` — size of the check indicator.
+
+Plain `.check` / `.radio` controls expose one hook:
+
+- `--choice-control-offset` — top offset that aligns the control with the first
+  line of a multi-line label.

package/docs/pages/forms/controls.md

@@ -0,0 +1,32 @@
+# Controls
+
+Native-only control chrome: the file input and color picker mostly defeat custom styling, so the framework stays out of the way and keeps them readable and theme-aware.
+
+## Color
+
+> Small, theme-aware chrome for the native color picker.
+
+Use `.color` on an `input[type="color"]` to give the native picker a control-sized
+box with the framework's border, radius, surface, disabled, and focus styles.
+The color dialog and selected-color swatch remain browser-native.
+
+```html demo
+<label class="field">
+  <span class="field-label">Accent color</span>
+  <input class="color" type="color" value="#6d5dfc" />
+</label>
+```
+
+## File
+
+Use `.file` on an `input[type="file"]` to keep the field native while theming the
+picker button with the framework's surface, border, radius, and hover states.
+The filename area stays muted.
+
+```html demo
+<label class="field">
+  <span class="field-label">Profile picture</span>
+  <input class="file" type="file" accept="image/*" aria-describedby="file-help" />
+  <span class="field-help" id="file-help">JPG, PNG or WebP — max 2 MB</span>
+</label>
+```

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

@@ -0,0 +1,59 @@
+# Detached Actions
+
+> `.form-actions` is class-only. It may live inside or outside the `<form>`. Use the native `form` attribute to connect a detached submit button to its form.
+
+The simplest case stays inside the form.
+
+```html
+<form novalidate>
+  <div class="stack">
+    <!-- fields -->
+  </div>
+
+  <div class="form-actions">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary">Save changes</button>
+  </div>
+</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>
+
+<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>
+```
+
+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="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>
+```

package/docs/pages/forms/floating-field.md

@@ -0,0 +1,88 @@
+# Floating labels
+
+> **Optional** — import `actual-css/css/optional/floating-field` or `actual-css/css/optional`.
+
+`.floating-field` turns a control and its label into a floating-label cell:
+the label rests inside the control and floats to the top when the control is
+focused or filled. It composes the existing `.field` layout and the text
+controls (`.input`, `.textarea`, `.select`) with zero JavaScript.
+
+The cell holds the control and its label only. Help and error messages stay in
+the surrounding `.field`, otherwise the resting label centers on the whole
+field instead of the control.
+
+```html demo
+<div class="field">
+  <label class="floating-field">
+    <input class="input" type="email" placeholder=" " aria-describedby="email-help" />
+    <span class="field-label">Email</span>
+  </label>
+  <span class="field-help" id="email-help">We'll never share your email.</span>
+</div>
+```
+
+Every `.input` and `.textarea` needs `placeholder=" "` so `:placeholder-shown`
+can detect emptiness — the space keeps the placeholder invisible while making
+the state detectable. `:autofill` is covered too, so a password manager that
+prefills a field still lifts the label.
+
+## Textarea
+
+A textarea's resting label aligns with the first text line instead of centering
+in the tall control.
+
+```html demo
+<div class="field">
+  <label class="floating-field">
+    <textarea class="textarea" rows="4" placeholder=" "></textarea>
+    <span class="field-label">Message</span>
+  </label>
+</div>
+```
+
+## Select and date/time inputs
+
+Selects have no `:placeholder-shown` signal, and date/time inputs render their
+placeholder inconsistently (Firefox shows none). These controls stay floated in
+every state, so their label always sits at the top.
+
+```html demo
+<div class="stack">
+  <label class="floating-field">
+    <select class="select">
+      <option value="">Choose a country</option>
+      <option>Belgium</option>
+      <option>France</option>
+      <option>Netherlands</option>
+    </select>
+    <span class="field-label">Country</span>
+  </label>
+
+  <label class="floating-field">
+    <input class="input" type="date" />
+    <span class="field-label">Start date</span>
+  </label>
+</div>
+```
+
+## Density
+
+The reserved headroom responds to control density through `--control-size`:
+`.sm` and `.lg` on the cell or an ancestor resize the control geometry and the
+label spacing with it. Typography is untouched, as everywhere in the framework.
+The floating label does add height — the headroom reserves a second vertical
+line on top of the control's minimum size.
+
+## CSS hooks
+
+- `--floating-pad-block-start` — headroom reserved above the control for the
+  floated label; defaults to half the control height plus one spacing step.
+
+Validation and focus come from the existing form contracts: the control's
+border and focus ring flip through `--form-invalid-border` and the shared
+control focus rules. Coloring the label itself on focus or invalid state is
+left to the surrounding recipe — the joined floating form in the
+[blocks demo](../../demo/templates/blocks.html) shows one such recipe.
+
+> Not currently compatible with `.input-icon`; use standard labels when an
+> embedded leading icon is required.

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

@@ -0,0 +1,56 @@
+# 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
+> 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.
+
+```html
+<form novalidate>
+  <div class="stack">
+    <!-- fields -->
+  </div>
+
+  <div class="form-actions">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary">Save changes</button>
+  </div>
+</form>
+```
+
+## CSS hooks
+
+The three layout hooks are unset by default and fall back to the values below.
+
+- `--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.
+
+### Common arrangements
+
+Right-align the submit on wide rows:
+
+```css
+.form-actions {
+  --form-actions-justify: flex-end;
+}
+```
+
+Stretch each action to fill the full row width:
+
+```css
+.form-actions {
+  --form-actions-align: stretch;
+}
+```
+
+Because the hooks are inherited custom properties, set them on a page or
+container to apply one arrangement to every `.form-actions` inside it.
+
+> 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.

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

@@ -0,0 +1,91 @@
+# Input Policy
+
+> Native input intent first. Actual's runtime filters values only when explicitly asked, and fixed-shape masks stay opt-in through `data-mask`.
+
+`inputmode` changes the virtual keyboard but does not constrain the value. Actual
+does not filter plain `inputmode` fields by default because numeric entry often
+needs temporary, signed, grouped, or locale-specific values while the user types.
+
+When the JavaScript runtime is loaded, Actual enhances `input[data-filter]`.
+Textareas are left alone.
+
+Add an explicit `data-filter` value when the field should enforce one of
+Actual's small built-in filters. Unsupported filter names are ignored. An
+empty `data-filter` never filters — `inputmode` is not read as a fallback,
+even when it is `numeric` or `decimal`. `data-filter="numeric"` /
+`data-filter="decimal"` are intentionally destructive (they rewrite the
+value as the user types), unlike `inputmode`, which only hints the virtual
+keyboard.
+
+```html demo
+<label class="field">
+  <span class="field-label">Quantity</span>
+  <input class="input" inputmode="numeric" data-filter="numeric" placeholder="42" />
+</label>
+```
+
+```html demo
+<label class="field">
+  <span class="field-label">Amount</span>
+  <input class="input" inputmode="decimal" data-filter="decimal" placeholder="12.34" />
+</label>
+```
+
+### Built-in filters
+
+The built-in filters are intentionally narrow. They are input helpers, not
+domain validation.
+
+- `numeric` — Keeps ASCII digits only: `0` through `9`.
+- `decimal` — Converts `,` to `.`, keeps ASCII digits, and keeps the first `.` separator.
+- `lower` — Converts the value with `toLocaleLowerCase()`.
+- `upper` — Converts the value with `toLocaleUpperCase()`.
+- `letters` — Keeps Unicode letters only. Digits, punctuation, symbols, and spaces are removed.
+- `slug` — Normalizes accents, lowercases text, turns runs of non-letter and non-digit characters into `-`, collapses repeated `-`, and trims edge separators.
+
+During direct typing, `slug` may keep a trailing `-` until the next character so
+words do not merge while the user is still entering text.
+
+Filters can be piped with `|` when a field needs more than one transform. They
+run from left to right.
+
+```html demo
+<label class="field">
+  <span class="field-label">Slug</span>
+  <input class="input" data-filter="lower|slug" autocomplete="off" placeholder="release-notes" />
+</label>
+```
+
+```html demo
+<label class="field">
+  <span class="field-label">Code</span>
+  <input class="input" data-filter="upper|letters" autocomplete="off" placeholder="ABC" />
+</label>
+```
+
+For signed numbers, locale formatting, currency rules, time ranges, or
+app-specific character policies, use application code. Those rules are domain
+policy, not a framework default. See the JavaScript docs for custom filter
+patterns built on `enhance()`.
+
+### Pattern mask
+
+Use `data-mask` when the input has a fixed shape. Tokens are `9` for a digit,
+`a` for a letter, and `*` for any character.
+
+```html demo
+<label class="field">
+  <span class="field-label">Reference</span>
+  <input class="input" data-mask="aaa-999" autocomplete="off" placeholder="abc-123" />
+</label>
+```
+
+```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>
+```
+
+Masks enforce shape, not domain validity. Use application validation when a date
+must reject impossible values such as `2026-13-40`.

package/docs/pages/forms/joined-controls.md

@@ -0,0 +1,37 @@
+# Joined Controls
+
+> Use `.join` when controls need to be visually joined into a single unit.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.join` | Composition | Visually joins adjacent controls into a single unit. |
+| `.join-addon` | Composition | Static prefix/suffix content such as currency symbols, units, or protocol text. |
+
+Add `.join` to the wrapper that groups the controls. Use `.join-addon` for static prefix/suffix content such as currency symbols, units, or protocol text. Action buttons inside the group should use `.btn`. The wrapper should still carry `role="group"` with a label for accessibility.
+
+When composing source files manually, import `components/join.css` after the controls it groups. `.join` writes child border-radius longhands directly so joined corners win at equal specificity.
+
+```html demo
+<div class="field">
+  <label class="field-label" id="amount-label" for="amount">Amount</label>
+  <div class="join" role="group" aria-labelledby="amount-label">
+    <span class="join-addon">$</span>
+    <input class="input" id="amount" name="amount" inputmode="decimal" />
+    <button class="btn outline" type="button">Clear</button>
+  </div>
+  <span class="field-help">Enter the invoice total before tax.</span>
+</div>
+```
+
+`.join` handles border-radius and border collapsing between adjacent children. It works with any direct child — `.input`, `.btn`, `.select`, or `.join-addon`.
+When an `.input`, `.textarea`, or `.select` receives keyboard-relevant focus,
+the focus ring surrounds the complete joined field. Attached buttons keep their
+own focus indicator when reached directly, so the actionable segment remains
+identifiable.
+
+## CSS hooks
+
+- `--join-radius` — outer corner radius of the joined group. The per-corner
+  values of each child are derived from it.