actual-css 0.2.0 → 0.3.1

package/docs/pages/layout/grid.md

@@ -0,0 +1,142 @@
+# Grid
+
+Responsive equal-width item grids with a tunable minimum item width.
+
+```html demo
+<section class="grid">
+  <article class="card">
+    <h3>Starter</h3>
+    <p>For small projects.</p>
+  </article>
+  <article class="card">
+    <h3>Team</h3>
+    <p>For shared products.</p>
+  </article>
+  <article class="card">
+    <h3>Scale</h3>
+    <p>For larger systems.</p>
+  </article>
+</section>
+```
+
+Tune the minimum item width with `--grid-min`.
+
+```css
+.pricing-grid {
+  --grid-min: 20rem;
+}
+```
+
+Or replace the responsive template entirely with `--grid-columns` for a
+custom or asymmetric layout. Because this overrides the intrinsic
+`auto-fit/minmax` algorithm, you own any narrow-container collapse:
+
+```css
+.feature-grid {
+  --grid-columns: minmax(0, 2fr) minmax(0, 1fr);
+}
+
+@container (width < 40rem) {
+  .feature-grid {
+    --grid-columns: 1fr;
+  }
+}
+```
+
+`--grid-columns` applies to `.grid` only. The `.grid-2`, `.grid-3`,
+`.grid-4`, and `.grid-6` presets retain their fixed-column contracts.
+
+## Fixed columns
+
+Predictable 2/3/4/6-column grids. Full count by default; wrap in `.container-query` to make the column count collapse on narrow wrappers.
+
+Use `.grid-2`, `.grid-3`, `.grid-4`, and `.grid-6` when the column count matters more than the item minimum width — for example, when a row should always read as "three items side by side", or when an empty cell should not stretch to fill space. Unlike `.grid`, the columns are fixed; if you have only two items in a `.grid-3`, the third cell stays empty rather than redistributing.
+
+A `.grid-2/3/4/6` without a wrapper is a **fixed grid** (always at its full column count); with a `.container-query` wrapper, it's a **responsive grid** (the column count collapses on narrow wrappers). The wrapper is the query container; the grid itself is a plain block grid.
+
+```html demo
+<div class="container-query">
+  <div class="grid-3">
+    <article class="card">
+      <h3>Starter</h3>
+      <p>For small projects.</p>
+    </article>
+    <article class="card">
+      <h3>Team</h3>
+      <p>For shared products.</p>
+    </article>
+    <article class="card">
+      <h3>Scale</h3>
+      <p>For larger systems.</p>
+    </article>
+  </div>
+</div>
+```
+
+A `grid-4` demo:
+
+```html demo
+<div class="container-query">
+  <div class="grid-4">
+    <article class="card">
+      <h3>Starter</h3>
+      <p>For small projects.</p>
+    </article>
+    <article class="card">
+      <h3>Team</h3>
+      <p>For shared products.</p>
+    </article>
+    <article class="card">
+      <h3>Scale</h3>
+      <p>For larger systems.</p>
+    </article>
+    <article class="card">
+      <h3>Enterprise</h3>
+      <p>Contact us.</p>
+    </article>
+  </div>
+</div>
+```
+
+A `grid-6` demo for compact items:
+
+```html demo
+<div class="container-query">
+  <div class="grid-6">
+    <article class="card compact">
+      <span class="muted">Open</span>
+      <strong>18</strong>
+    </article>
+    <article class="card compact">
+      <span class="muted">Queued</span>
+      <strong>7</strong>
+    </article>
+    <article class="card compact">
+      <span class="muted">Blocked</span>
+      <strong>2</strong>
+    </article>
+    <article class="card compact">
+      <span class="muted">Shipped</span>
+      <strong>41</strong>
+    </article>
+    <article class="card compact">
+      <span class="muted">Owners</span>
+      <strong>6</strong>
+    </article>
+    <article class="card compact">
+      <span class="muted">SLA</span>
+      <strong>99%</strong>
+    </article>
+  </div>
+</div>
+```
+
+## Behavior
+
+- Without `.container-query`: `.grid-2` is always 2 cols, `.grid-3` is always 3 cols, `.grid-4` is always 4 cols, and `.grid-6` is always 6 cols.
+- With `.container-query`: `.grid-2`, `.grid-3`, and `.grid-4` collapse to one column on a narrow wrapper (under 28rem). `.grid-3` and `.grid-4` step through 2 columns between 28rem and 48rem. `.grid-6` starts at 2 columns under 28rem, steps through 3 columns between 28rem and 64rem, then returns to 6 columns.
+- The intermediate 2-col step is useful for lists of items divisible by both 2 and 3 (or 4) — a 12-item list reads as 12 lines, then 6 lines of 2, then 4 lines of 3 (or 3 lines of 4), depending on the grid.
+- `.grid-6` is for compact items such as stats, shortcut tiles, swatches, avatar summaries, and small settings cards. It does not collapse to one column by default. If item width matters more than an exact six-column rhythm, prefer `.grid` with a smaller `--grid-min`.
+- The wrapper is the query container, so the same class behaves differently in a narrow sidebar than in a wide main area. No viewport breakpoints are involved.
+
+Do not add `.row`, `.col-6`, `.offset-2`, or other fixed grid-system classes unless the project later proves it needs a formal grid system.

package/docs/pages/layout/list.md

@@ -0,0 +1,41 @@
+# List
+
+Lists stay native by default. Compose visual list rows from existing primitives.
+
+Use `.list-reset` only when markers are not part of the content. Combine `.stack`, `.media`, `.cluster`, spacing helpers, and local styles for application-style rows.
+
+```html demo
+<figure class="stack">
+  <figcaption><strong>Most played songs this week</strong></figcaption>
+
+  <ul class="list-reset stack gap-none">
+    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
+      <div class="avatar">
+        <img src="https://i.pravatar.cc/48?img=5" alt="Dio Lupa" />
+      </div>
+      <div class="cluster">
+        <div class="stack grow" style="--gap: var(--space-10)">
+          <strong>Dio Lupa</strong>
+          <span class="muted">Remaining Reason</span>
+        </div>
+        <span class="muted">3:45</span>
+      </div>
+    </li>
+
+    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
+      <div class="avatar">
+        <img src="https://i.pravatar.cc/48?img=10" alt="Astral Planes" />
+      </div>
+      <div class="cluster">
+        <div class="stack grow" style="--gap: var(--space-10)">
+          <strong>Astral Planes</strong>
+          <span class="muted">Neon Drift</span>
+        </div>
+        <span class="muted">4:12</span>
+      </div>
+    </li>
+  </ul>
+</figure>
+```
+
+Keep semantic lists unstyled when the markers carry meaning.

package/docs/pages/layout/media.md

@@ -0,0 +1,28 @@
+# Media Object
+
+Fixed-width leading element (avatar, icon, image) paired with flexible trailing content.
+
+`.media` is the media object: a grid with `auto minmax(0, 1fr)` columns. Use it for author cards, comments, meta rows, and any composition that pairs a small leading element with a flexible content block. The trailing column takes the remaining space and never overflows.
+
+Give `.media` exactly two children. Trailing metadata or actions go inside the content column — nest a `.cluster` and put `.grow` on the flexible part — never as additional children, which silently wrap onto a second grid row.
+
+Add `.items-center` to align the leading element with short trailing content. For multi-line content, the default `align-items: start` is more comfortable.
+
+```html demo
+<article class="card media">
+  <span class="avatar"><abbr>AM</abbr></span>
+  <div class="stack gap-none">
+    <strong>Ada Meridian</strong>
+    <p class="muted">Senior designer working on design systems.</p>
+  </div>
+</article>
+```
+
+```html demo
+<div class="media items-center">
+  <span class="avatar"><abbr>AM</abbr></span>
+  <span>Ada Meridian</span>
+</div>
+```
+
+The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule.

package/docs/pages/layout/overview.md

@@ -0,0 +1,37 @@
+# Layout Overview
+
+Layout provides a small set of composable building blocks for common page, app, and content structure. It is not a utility-first framework and it is not a twelve-column grid system.
+
+- Layout classes compose components; components do not own page spacing.
+- Use custom properties to tune a layout instance.
+- Prefer intrinsic and container-friendly behavior over breakpoint-heavy APIs.
+- Keep class names semantic enough to remember and generic enough to reuse.
+- Add a new layout primitive only when a pattern appears often and is awkward to express with existing primitives.
+
+## Spacing tokens
+
+Layout shares the global spacing surface and exposes a small set of gap and rhythm tokens.
+
+```css
+:root {
+  --gap: 0.75rem;
+  --space-10: 0.25rem;
+  --space-20: 0.5rem;
+  --space-30: 0.75rem;
+  --space-40: 1rem;
+  --space-50: 1.5rem;
+  --space-60: 2rem;
+}
+```
+
+Most layout primitives read `--gap` and allow local overrides.
+
+```css
+.settings-form {
+  --gap: var(--space-50);
+}
+```
+
+Prefer a local custom property over adding many one-off utility classes. Use inline styles only for demos, prototypes, or truly dynamic values.
+
+There are no `.gap-sm` / `.gap-md` / `.gap-lg` density variants on the core layout primitives; set `--gap` locally when only spacing should change. The optional `utilities-extra.css` layer ships those gap utilities for row/column containers.

package/docs/pages/layout/scroll-snap.md

@@ -0,0 +1,54 @@
+# Scroll Snap
+
+Horizontal rails that stay useful without JavaScript and snap in modern browsers.
+
+> **Optional** — import `actual-css/css/optional/scroll-snap` or `actual-css/css/optional/index`.
+
+Use `.scroll-snap` for a niche row of items that should scroll horizontally, such as card rails, media strips, overflow tabs, or a simple touch-friendly carousel baseline. Scrolling only appears when the items are wider than the container; set `--scroll-snap-item-size` for card rails.
+
+```html demo
+<section class="stack" aria-labelledby="featured-title">
+  <h2 id="featured-title">Featured articles</h2>
+
+  <ul class="scroll-snap list-reset" style="--scroll-snap-item-size: min(85%, 18rem)">
+    <li class="card">Article one</li>
+    <li class="card">Article two</li>
+    <li class="card">Article three</li>
+    <li class="card">Article four</li>
+    <li class="card">Article five</li>
+  </ul>
+</section>
+```
+
+The baseline is flex layout plus `overflow-x: auto`, so older browsers still get a usable horizontal scroll area. Browsers with scroll snap support add `scroll-snap-type` and item alignment.
+
+Items snap to the inline start edge by default. Use `data-snap="center"` for visual rails where centered cards are the better fit.
+
+```html demo
+<div class="scroll-snap" data-snap="center" style="--scroll-snap-item-size: min(85%, 18rem)">
+  <article class="card">One</article>
+  <article class="card">Two</article>
+  <article class="card">Three</article>
+  <article class="card">Four</article>
+  <article class="card">Five</article>
+</div>
+```
+
+## CSS hooks
+
+- `--scroll-snap-item-size` — item `flex` basis; set it for card rails.
+- `--scroll-snap-gap` — space between items.
+- `--scroll-snap-padding` — inline scroll padding, so a snapped item does not sit
+  flush against the container edge. Not declared; falls back to `--scroll-snap-gap`.
+- `--scroll-snap-align` — item snap alignment. Prefer `data-snap="center"`
+  over setting this directly.
+
+Keep scrollbars visible by default. If a product deliberately hides them, make that choice explicit with `data-scrollbar="hidden"`.
+
+```html
+<div class="scroll-snap" data-scrollbar="hidden">
+  ...
+</div>
+```
+
+`.scroll-snap` is not a full interactive carousel. For previous/next controls, pagination, active state, mouse drag, looping, autoplay, or robust accessibility behavior, use a dedicated carousel library such as Swiper and compose it with Actual components.

package/docs/pages/layout/sidebar-layout.md

@@ -0,0 +1,27 @@
+# Sidebar Layout
+
+Two-column layout where one side has a preferred width and the other takes the remaining space.
+
+Use `.sidebar-layout` for two-column layouts where the aside should align to the top of the content, stay sticky, or keep a predictable declared width.
+
+Wrap it in `.container-query` to make the switch depend on the container width. Below 64rem the columns stack; at and above it the aside takes `--sidebar-layout-size` and the content takes the remaining space. Older browsers use the viewport fallback.
+
+```html demo
+<div class="container-query">
+  <div class="sidebar-layout" style="--sidebar-layout-size: 18rem">
+    <article class="stack">
+      <h1>Long-form article</h1>
+      <p>Article body that benefits from a sticky table of contents.</p>
+    </article>
+
+    <aside class="stack">
+      <h3>On this page</h3>
+      <ol class="list-reset">
+        <li><a class="link-muted" href="#">Section</a></li>
+      </ol>
+    </aside>
+  </div>
+</div>
+```
+
+Tune the side width with `--sidebar-layout-size`.

package/docs/pages/layout/stack.md

@@ -0,0 +1,55 @@
+# Stack
+
+Vertical flow with consistent spacing, ideal for forms, card content, and content blocks.
+
+```html demo
+<section class="stack">
+  <h2>Account</h2>
+  <p class="muted">Manage profile and billing settings.</p>
+  <form>
+    <label class="field">
+      <span class="field-label">Email</span>
+      <input class="input" type="email" placeholder="you@example.com" />
+    </label>
+  </form>
+</section>
+```
+
+Use stack for forms, card content, modal bodies, side panels, and documentation blocks.
+
+Like `.cluster`, stack owns its children's block-axis spacing: direct-child
+block margins are reset, so vertical rhythm always comes from `--gap`. Inline
+margins stay free — for example `margin-inline: auto` on a child centers it
+without fighting the primitive.
+
+## Grouping items tightly
+
+Stack spacing is a `--gap` between every direct child; the primitive cannot
+tighten two specific children by itself. To group a few items into one unit
+(a title and its description), nest a `.stack gap-none`:
+
+```html demo
+<div class="stack">
+  <div class="stack gap-none">
+    <strong>Ada Meridian</strong>
+    <span class="muted">Senior designer working on design systems.</span>
+  </div>
+  <span class="badge success soft">Active</span>
+</div>
+```
+
+The outer stack keeps its rhythm between groups; the inner `gap-none` unit owns
+the tight pairing.
+
+For a one-off adjacency — pull a single child closer to its neighbour without
+adding a wrapper — the escape hatch is app CSS. `gap` and `margin-block` are
+additive, so a negative block margin on the child cancels the following gap:
+
+```css
+.stack > .profile-row {
+  margin-block-end: calc(var(--gap) * -1);
+}
+```
+
+The stack resets child block margins to zero, so this re-adds a margin on that
+one child only; the rest of the stack keeps its rhythm.

package/docs/pages/layout/switcher.md

@@ -0,0 +1,36 @@
+# Switcher
+
+Row that becomes a column when space gets tight, useful for small sets of panels.
+
+> **Optional** — import `actual-css/css/optional/layout-extra` or `actual-css/css/optional/index`.
+
+Use `.switcher` for rows that should become columns when space gets tight.
+
+```html demo
+<section class="switcher">
+  <article class="card">
+    <h3>Profile</h3>
+    <p>Personal details and preferences.</p>
+  </article>
+  <article class="card">
+    <h3>Security</h3>
+    <p>Password and login settings.</p>
+  </article>
+  <article class="card">
+    <h3>Billing</h3>
+    <p>Invoices and payment methods.</p>
+  </article>
+</section>
+```
+
+This is useful for small sets of panels, not large card collections. Use `.grid` for repeatable collections.
+
+## CSS hooks
+
+- `--switcher-threshold` — container width at which the row becomes a column.
+
+```css
+.settings-panels {
+  --switcher-threshold: 55rem;
+}
+```

package/docs/pages/layout/topbar.md

@@ -0,0 +1,23 @@
+# Topbar
+
+Sticky, frosted top bar shell for app/dashboard layouts with a persistent sidebar.
+
+> **Optional** — import `actual-css/css/optional/layout-extra` or `actual-css/css/optional/index`.
+
+Use `.topbar` for the structural shell of an app-shell header: sticky positioning, stacking, and a frosted background. Row content — search, breadcrumb, actions — stays local to the page.
+
+```html demo
+<header class="topbar">
+  <button class="btn neutral ghost" type="button" aria-label="Open navigation">
+    <i class="ti ti-menu-2" aria-hidden="true"></i>
+  </button>
+  <ol class="breadcrumb" aria-label="Breadcrumb">
+    <li><a href="#">Overview</a></li>
+    <li aria-current="page">Accounts</li>
+  </ol>
+  <div class="grow"></div>
+  <span class="avatar sm"><abbr>LW</abbr></span>
+</header>
+```
+
+This is for the app-shell topbar specifically — a structural need that recurs unchanged across app UIs regardless of brand. It is not for marketing or editorial site headers, which are one-off visual identity per page.

package/docs/pages/patterns/actions.md

@@ -0,0 +1,52 @@
+# Actions
+
+Use `.actions` for a semantic list of actions.
+
+It removes native list chrome and provides a baseline row layout (`display: flex`, wrap, shared gap). Compose with layout primitives only when you need a different direction or distribution.
+
+```html demo
+<div class="stack">
+  <menu class="actions cluster">
+    <li><button class="btn primary" type="button">Save</button></li>
+    <li><button class="btn outline" type="button">Cancel</button></li>
+  </menu>
+
+  <menu class="actions stack">
+    <li><a class="btn primary" href="/billing">Update billing</a></li>
+    <li><a href="/support">Contact support</a></li>
+  </menu>
+</div>
+```
+
+Use `.actions` for:
+
+- dialog actions
+- alert actions
+- card actions
+- toolbar actions
+- form submit/cancel groups
+
+Use layout primitives for contextual spacing.
+
+```html demo
+<div class="alert warning stack">
+  <p>Your billing method has expired.</p>
+
+  <menu class="actions cluster">
+    <li><a class="btn danger sm" href="/billing">Update billing</a></li>
+    <li><a href="/support">Contact support</a></li>
+  </menu>
+</div>
+```
+
+Prefer composition over making each component reimplement action-list layout.
+
+```css
+/* Avoid */
+.alert > menu {
+  display: flex;
+  gap: var(--space-20);
+  padding: 0;
+  list-style: none;
+}
+```

package/docs/pages/patterns/code-block.md

@@ -0,0 +1,36 @@
+# Code Block With Copy Button
+
+A self-contained copy-button recipe composed from `.btn`, a `pre > code` block, and the `enhance()` lifecycle.
+
+```html
+<div class="code-block">
+  <pre><code>npm install actual-css</code></pre>
+  <button class="btn sm ghost" data-copy>Copy</button>
+</div>
+```
+
+```css
+.code-block { position: relative; }
+.code-block > [data-copy] {
+  position: absolute;
+  inset-block-start: var(--space-20);
+  inset-inline-end: var(--space-20);
+}
+```
+
+```js
+import enhance from "actual-css/js/enhance";
+
+enhance({
+  "[data-copy]": (button) => {
+    const controller = new AbortController();
+    button.addEventListener("click", async () => {
+      const code = button.closest(".code-block")?.querySelector("code");
+      if (code) await navigator.clipboard.writeText(code.textContent);
+    }, { signal: controller.signal });
+    return () => controller.abort();
+  },
+});
+```
+
+No core JS, no syntax highlighter — the recipe is the documentation.

package/docs/pages/patterns/exclusive-accordion.md

@@ -0,0 +1,16 @@
+# Exclusive Accordion
+
+Browsers that support the `name` attribute on `<details>` get native exclusive accordions — no JS engine needed. Omit `name` to allow several open at once.
+
+```html demo
+<details name="faq" open>
+  <summary>What is this?</summary>
+  <p>A CSS framework.</p>
+</details>
+<details name="faq">
+  <summary>Does it need JS?</summary>
+  <p>Only the progressive enhancers you import.</p>
+</details>
+```
+
+Not shipping an accordion JS engine is a design decision, not a gap.

package/docs/pages/patterns/hierarchical-nav.md

@@ -0,0 +1,26 @@
+# Hierarchical Scrollable Nav
+
+App shell with a collapsible nav tree. Uses existing primitives only — no treeview component.
+
+```html demo
+<aside>
+  <nav class="nav-list scroller" data-enhance="scrollspy" aria-label="Docs">
+    <details open>
+      <summary>Getting started</summary>
+      <a class="nav-link" href="#intro">Introduction</a>
+      <a class="nav-link" href="#install">Installation</a>
+    </details>
+    <details>
+      <summary>Components</summary>
+      <a class="nav-link" href="#alert">Alert</a>
+      <a class="nav-link" href="#badge">Badge</a>
+    </details>
+  </nav>
+</aside>
+```
+
+- `.nav-list` + `.nav-link`: Actual's nav chrome
+- Native `<details>`: exclusive accordion with `<details name>` (no JS engine)
+- `data-enhance="scrollspy"`: scroll-driven `aria-current`
+- `.scroller`: thin, theme-aware scrollbar
+- No `.nav-heading` / `.nav-sublist` classes — the existing primitives are enough

package/docs/pages/patterns/icon-input.md

@@ -0,0 +1,25 @@
+# Icon Input
+
+Use `.input-icon` for a search or filter input with a leading icon.
+
+```html demo
+<label class="input-icon">
+  <i class="ti ti-search" aria-hidden="true"></i>
+  <input class="input" type="search" placeholder="Search accounts, invoices, notes" aria-label="Search">
+</label>
+```
+
+It positions the wrapper's first child absolutely inside a relative container and grows the input's start padding to clear it. `pointer-events: none` on the icon keeps clicks passing through to the input underneath. It is icon-library agnostic — an `<i>` webfont icon, an inline `<svg>`, or a `<span>` all work as the wrapper's first child.
+
+The icon keeps a fixed `--input-icon-size` (1.25rem); density contexts shrink the control geometry around it, not the pictogram. Apply the density class to the wrapper and to the input so the control height follows:
+
+```html demo
+<div class="stack">
+  <label class="input-icon sm">
+    <i class="ti ti-search" aria-hidden="true"></i>
+    <input class="input sm" type="search" aria-label="Search">
+  </label>
+</div>
+```
+
+Trailing icons are supported too: an icon that follows the input is positioned at the end and the input grows its end padding. It stays decorative — `pointer-events: none` means an interactive trailing control such as a clear button is not covered by this class.

package/docs/pages/patterns/intent-nesting.md

@@ -0,0 +1,3 @@
+# Intent Nesting
+
+Intent on an ancestor must not tint nested components, and a local intent inside an intent-carrying ancestor must win. Both directions are verified in `tests/css-audit.test.js` and the kitchen-sink demo template. Intent classes only expose `--intent` and `--intent-fg`; each consuming component opens a local intent boundary in a `:where()` block that resets exactly the tokens it consumes to initial. Parent intents do not leak into nested components, and a local intent class still wins because it has higher specificity than `:where()`.