actual-css 0.2.0 → 0.3.1

package/docs/pages/components/navbar.md

@@ -0,0 +1,92 @@
+# Navbar
+
+> Horizontal top-level navigation bar with a brand, an inline link list, and a vertical nav-list for drawers.
+
+- Use `.navbar` for the horizontal bar shell.
+- `.navbar-brand` is the brand link at the inline start.
+- `.navbar-nav` is the horizontal link list; its items are `.nav-link`.
+- `.nav-list` is the shared vertical navigation list, reused by `.drawer` for stacked links.
+- Mark the current page with `aria-current="page"` on the active `.nav-link`.
+
+`.navbar-nav` and `.nav-list` are mutually exclusive: `.navbar-nav` is a horizontal
+flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
+`.nav-list` (vertical) — pick one per container.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.navbar` | Component | Horizontal bar shell. |
+| `.navbar-brand` | Composition | Brand link at the inline start. |
+| `.navbar-nav` | Composition | Horizontal link list. |
+| `.nav-link` | Component | A link item; current page via `aria-current="page"`. |
+| `.nav-list` | Component | Shared vertical navigation list, reused by `.drawer`. |
+
+## Basic usage
+
+```html demo
+<nav class="navbar" aria-label="Main">
+  <a class="navbar-brand" href="/">Actual CSS</a>
+  <ul class="navbar-nav">
+    <li><a class="nav-link" href="/docs" aria-current="page">Docs</a></li>
+    <li><a class="nav-link" href="/components">Components</a></li>
+    <li><a class="nav-link" href="/examples">Examples</a></li>
+  </ul>
+</nav>
+```
+
+For a vertical sidebar nav, use `.nav-list` inside the drawer or sidebar.
+
+## Responsive: navbar + drawer
+
+There is no collapse/toggler mechanism. For a responsive navigation, keep the
+horizontal `.navbar` for the desktop bar and compose the mobile experience from
+a `.drawer` with a vertical `.nav-list`, opened by a `command="show-modal"` /
+`commandfor` trigger.
+
+```html demo
+<nav class="navbar" aria-label="Main">
+  <a class="navbar-brand" href="/">Actual CSS</a>
+  <ul class="navbar-nav">
+    <li><a class="nav-link" href="/" aria-current="page">Home</a></li>
+    <li><a class="nav-link" href="/docs">Docs</a></li>
+  </ul>
+</nav>
+
+<button class="btn ghost"
+        type="button"
+        command="show-modal"
+        commandfor="site-nav"
+        aria-haspopup="dialog"
+        aria-controls="site-nav"
+        aria-label="Open menu">
+  <i class="ti ti-menu-2" aria-hidden="true"></i>
+</button>
+
+<dialog class="drawer"
+        id="site-nav"
+        aria-label="Main navigation"
+        closedby="any"
+        data-dialog-dismissible>
+  <header>
+    <strong>Menu</strong>
+    <form method="dialog">
+      <button class="drawer-close" type="submit" aria-label="Close navigation"></button>
+    </form>
+  </header>
+
+  <nav>
+    <ul class="nav-list stack">
+      <li><a href="#" aria-current="page">Home</a></li>
+      <li><a href="#">Docs</a></li>
+      <li><a href="#">Components</a></li>
+    </ul>
+  </nav>
+</dialog>
+```
+
+The drawer can be hidden until opened: give the `dialog` the `hidden` attribute
+in the HTML and let the command runtime manage it, or rely on the drawer being
+rendered only on the mobile layout. `command` and `commandfor` work without
+JavaScript, and the drawer follows the same `closedby` / `data-dialog-dismissible`
+rules as the [Drawer component](drawer.md).

package/docs/pages/components/pagination.md

@@ -0,0 +1,55 @@
+# Pagination
+
+> Navigation controls to move between pages of content.
+
+- Use a semantic `<nav>` landmark.
+- Put `.pagination` on the ordered list.
+- Use `aria-current="page"` for the current page.
+- Put `.sm` or `.lg` on `.pagination` to change the density of its controls.
+- Numeric links may use `aria-label="Page N"` for clearer screen reader output.
+- Prefer text labels for Previous and Next. Icon-only controls need an accessible name.
+- Page links can compose with `.btn` for button-like hit targets.
+- Truncated ranges are plain text with `.muted` and `aria-hidden="true"`, not `.btn` — they are decorative, not actionable.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.pagination` | Component | Ordered list of page controls. |
+| `.sm` / `.lg` | Size | Control density. |
+
+## Basic usage
+
+```html demo
+<nav aria-label="Pagination">
+  <ol class="pagination sm">
+    <li><a href="?page=2" class="btn outline" rel="prev">Previous</a></li>
+    <li><a href="?page=1" class="btn outline" aria-label="Page 1">1</a></li>
+    <li><a href="?page=2" class="btn outline" aria-label="Page 2">2</a></li>
+    <li><a href="?page=3" class="btn" aria-current="page" aria-label="Page 3">3</a></li>
+    <li><a href="?page=4" class="btn outline" aria-label="Page 4">4</a></li>
+    <li><a href="?page=5" class="btn outline" rel="next">Next</a></li>
+  </ol>
+</nav>
+```
+
+## Truncated ranges
+
+Truncated ranges are plain text (`<span class="muted" aria-hidden="true">`), not
+buttons — they are decorative, not actionable.
+
+```html demo
+<nav aria-label="Pagination">
+  <ol class="pagination sm">
+    <li><a href="?page=1" class="btn outline" rel="prev">Previous</a></li>
+    <li><a href="?page=1" class="btn outline" aria-label="Page 1">1</a></li>
+    <li><span class="muted" aria-hidden="true">…</span></li>
+    <li><a href="?page=7" class="btn outline" aria-label="Page 7">7</a></li>
+    <li><a href="?page=8" class="btn" aria-current="page" aria-label="Page 8">8</a></li>
+    <li><a href="?page=9" class="btn outline" aria-label="Page 9">9</a></li>
+    <li><span class="muted" aria-hidden="true">…</span></li>
+    <li><a href="?page=20" class="btn outline" aria-label="Page 20">20</a></li>
+    <li><a href="?page=9" class="btn outline" rel="next">Next</a></li>
+  </ol>
+</nav>
+```

package/docs/pages/components/progress.md

@@ -0,0 +1,29 @@
+# Progress
+
+> Indeterminate or determinate indicator of task completion.
+
+- Use native `<progress class="progress">`.
+- Shares meter styling DNA.
+- Supports indeterminate progress by omitting `value`.
+- Can be connected to a busy region with `aria-describedby`.
+- Never self-close `<progress>`.
+
+```html demo
+<div class="stack">
+  <progress class="progress" value="60" max="100"></progress>
+  <progress class="progress" value="30" max="100"></progress>
+  <progress class="progress" value="90" max="100"></progress>
+  <progress class="progress"></progress>
+
+  <section aria-busy="true" aria-describedby="upload-progress">
+    <h2>Uploading files</h2>
+    <progress class="progress" id="upload-progress" value="60" max="100">60%</progress>
+  </section>
+</div>
+```
+
+## CSS hooks
+
+- `--progress-track` — unfilled track color.
+- `--progress-value` — filled bar color. Prefer an intent class over setting this directly.
+- `--bar-height` — bar thickness, shared with `.meter`.

package/docs/pages/components/skeleton.md

@@ -0,0 +1,38 @@
+# Skeleton
+
+> Placeholder shapes for content that is loading.
+
+- Use `.skeleton` for loading placeholders.
+- Use `data-shape` for common placeholder forms: `text`, `title`, `avatar`, `box`.
+- Put `role="status"` and accessible text on the loading region, not on every placeholder.
+- Use layout utilities for placeholder arrangement.
+- Only relevant for simple placeholders - use more structural solutions like phantom-ui for complex cases.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.skeleton` | Component | Animated placeholder shape. |
+| `data-shape` | Modifier | Geometry presets: `text`, `title`, `avatar`, `box`. |
+
+## Basic usage
+
+```html demo
+<article class="card" role="status" aria-label="Loading profile">
+  <div class="cluster">
+    <div class="skeleton" data-shape="avatar" aria-hidden="true"></div>
+    <div class="stack grow">
+      <div class="skeleton" data-shape="title" aria-hidden="true"></div>
+      <div class="skeleton" data-shape="text" aria-hidden="true"></div>
+    </div>
+  </div>
+</article>
+```
+
+## CSS hooks
+
+- `--skeleton-track` — base placeholder color.
+- `--skeleton-highlight` — sweeping highlight color.
+- `--skeleton-radius` — corner radius; `data-shape` presets override it.
+- `--skeleton-size` — block size; `data-shape` presets override it.
+- `--skeleton-width` — inline size; `data-shape` presets override it.

package/docs/pages/components/spinner.md

@@ -0,0 +1,93 @@
+# Spinner
+
+> Loading indicator for actions or regions that may take noticeable time.
+
+- Most actions do not need a spinner. Use `disabled` alone for fast actions or to prevent duplicate submissions.
+- Use `aria-busy="true"` with a loading label for actions that are visibly in progress.
+- Add `.spinner` only when the operation may take long enough that users need explicit loading feedback.
+- The spinner uses `currentColor`, so it adapts to its context.
+- Decorative spinners should be `aria-hidden="true"`.
+- Use `role="status"` with accessible text when the loading state needs to be announced.
+- Put a direct last-child `.spinner` inside a busy region to show a centered loading overlay. In buttons, spinners remain inline.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.spinner` | Component | Circular loading indicator using `currentColor`. |
+| `.sm` / `.lg` | Size | Smaller (`0.75em`) or larger (`2rem`) spinner. |
+| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger` color. |
+
+## Basic usage
+
+```html demo
+<span class="spinner"></span>
+<span class="spinner sm primary"></span>
+<span class="spinner lg danger"></span>
+```
+
+In buttons, the spinner stays inline and inherits the button size.
+
+```html demo
+<button class="btn primary" type="submit" aria-busy="true" disabled>
+  <span class="spinner" aria-hidden="true"></span>
+  Saving…
+</button>
+```
+
+A direct last-child `.spinner` in a busy container becomes a centered overlay.
+
+```html demo
+<article class="card" aria-busy="true" aria-label="Loading card content">
+  <hgroup>
+    <h3>Card Title</h3>
+    <p class="muted">Card description goes here.</p>
+  </hgroup>
+
+  <p>This is the card content. It can contain any HTML.</p>
+
+  <footer class="cluster">
+    <button class="btn outline" disabled>Cancel</button>
+    <button class="btn" disabled>Save</button>
+  </footer>
+
+  <span class="spinner lg" aria-hidden="true"></span>
+</article>
+```
+
+Announce the loading state when it needs to be spoken.
+
+```html demo
+<div role="status">
+  <span class="spinner" aria-hidden="true"></span>
+  <span class="sr-only">Loading results</span>
+</div>
+```
+
+Size follows the font (`1em`); use `.sm` / `.lg` rather than sizing it directly.
+
+## Busy state
+
+A container-wide loading state that keeps the underlying content in place. It is
+driven by `aria-busy="true"` plus a direct last-child `.spinner` — there is no
+separate `.busy` class. The spinner is shown as a centered overlay over a faded
+surface; buttons keep their spinners inline instead (see Button).
+
+- Set `aria-busy="true"` on the container and add `<span class="spinner" aria-hidden="true"></span>` as its last direct child.
+- The overlay uses `--busy-overlay-bg`; an inverted surface (`.inverted`) already composes with it.
+- Decorative spinners stay `aria-hidden="true"`; announce progress on the region with `role="status"` and a label when needed.
+
+```html demo
+<article class="card" aria-busy="true" aria-label="Loading card content">
+  <h3>Card Title</h3>
+  <p>This is the card content.</p>
+  <span class="spinner" aria-hidden="true"></span>
+</article>
+```
+
+## CSS hooks
+
+- `--spinner-track` — the ring color.
+- `--spinner-value` — the moving gap; swap the two for an inverted spinner.
+- `--busy-overlay-bg` — background of the busy overlay. An inverted surface
+  (`.inverted`) overrides it to blend with its own surface.

package/docs/pages/components/table.md

@@ -0,0 +1,102 @@
+# Table
+
+> Data table with caption and scope attributes, and an accessible scroll region for wide content.
+
+- Use native `<table class="table">` inside a `.table-wrap` for surface, border, radius, and overflow.
+- Use `<caption>`, `scope="col"`, and `scope="row"` for accessibility.
+- Use `.text-end` for numeric columns and `.text-nowrap` for non-wrapping cells.
+- For wide tables, make the wrapper an accessible scroll region with `role="region"`, `aria-labelledby`, and `tabindex="0"`.
+- Tables stay content-first and neutral by default.
+- `.table` does not consume shared variants or intent colors (`--ui-bg` / `--intent`): a `.soft` + intent combo on a `<tr>` has no effect. To tint rows or headers, style them with a class of your own.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.table-wrap` | Component | Scroll container and outer chrome (surface, border, radius). |
+| `.table` | Component | The table itself; row and cell rules. |
+
+## Basic usage
+
+```html demo
+<div class="table-wrap">
+  <table class="table">
+    <caption>Team members</caption>
+    <thead>
+      <tr>
+        <th scope="col">Name</th>
+        <th scope="col">Email</th>
+        <th scope="col">Role</th>
+        <th scope="col">Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Alice Johnson</td>
+        <td>alice@example.com</td>
+        <td>Admin</td>
+        <td><span class="badge success soft">Active</span></td>
+      </tr>
+      <tr>
+        <td>Bob Smith</td>
+        <td>bob@example.com</td>
+        <td>Editor</td>
+        <td><span class="badge success soft">Active</span></td>
+      </tr>
+      <tr>
+        <td>Carol White</td>
+        <td>carol@example.com</td>
+        <td>Viewer</td>
+        <td><span class="badge secondary soft">Pending</span></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+## Accessible scroll region
+
+For wide tables, add `role="region"`, `aria-labelledby`, and `tabindex="0"` to
+the wrapper so keyboard users can scroll it. `--table-min` sets the minimum
+table width before the wrapper scrolls horizontally.
+
+```html demo
+<div class="table-wrap" role="region" aria-labelledby="revenue-table" tabindex="0">
+  <table class="table" style="--table-min: 64rem">
+    <caption id="revenue-table">Revenue by month</caption>
+    <thead>
+      <tr>
+        <th scope="col">Month</th>
+        <th scope="col">Plan</th>
+        <th scope="col" class="text-end">Revenue</th>
+        <th scope="col" class="text-end">Churn</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>March 2026</td>
+        <td>Team</td>
+        <td class="text-end text-nowrap">$42,128</td>
+        <td class="text-end text-nowrap">1.2%</td>
+      </tr>
+      <tr>
+        <td>April 2026</td>
+        <td>Team + Business</td>
+        <td class="text-end text-nowrap">$48,902</td>
+        <td class="text-end text-nowrap">0.9%</td>
+      </tr>
+      <tr>
+        <td>May 2026</td>
+        <td>Team + Business</td>
+        <td class="text-end text-nowrap">$53,470</td>
+        <td class="text-end text-nowrap">0.7%</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+## CSS hooks
+
+- `--table-cell-pad` — cell padding.
+- `--table-min` — minimum table width before `.table-wrap` scrolls horizontally.