actual-css 0.12.0 → 0.13.0

package/docs/pages/guides/progressive-enhancement.md

@@ -63,11 +63,30 @@ handle, and cleanup happens per element when an element leaves the DOM.
 
 ## The full runtime
 
-Loading `dist/actual.full.js` as a plain `<script>` (no `type="module"`, no
-bundler, no `import`) gets the full runtime. Static HTML that needs to trigger
-something from its own inline `<script>` dispatches the module's public event
-instead of calling into a global — `actual:status` for the status bar, for
-example:
+Import `actual-css/js/full` to enable the full runtime:
+
+```js
+import "actual-css/js/full";
+```
+
+The same entrypoint exposes the public enhancement API from the same runtime
+instance, for adopters that extend the runtime they already run:
+
+```js
+import { applyEnhancement, enhance, registerEnhancement } from "actual-css/js/full";
+
+registerEnhancement("autosubmit", (form) => {
+  // ...
+});
+```
+
+For anything beyond that extension API, keep using `actual-css/js/*`.
+
+The same entrypoint produces the `dist/actual.full.js` standalone for a
+classic `<script>`, where no global API is exposed. Static HTML that needs to
+trigger something from its own inline `<script>` dispatches the module's
+public event instead of calling into a global — `actual:status` for the
+status bar, for example:
 
 ```html
 <script src="actual.full.js"></script>
@@ -110,8 +129,7 @@ needed.
 The JS is designed to run on its own, without Actual's stylesheet.
 
 - **`data-enhance` tokens** register named behaviors. The runtime discovers
-  components through `data-enhance="tabs"`, `data-enhance="flyout"`,
-  `data-enhance="range"`, `data-enhance="scrollspy"`, and
+  components through `data-enhance="tabs"`, `data-enhance="flyout"`, `data-enhance="range"`, `data-enhance="scrollspy"`, and
   `data-enhance="validation"` — no Actual presentation class needed.
   Self-describing attributes (`data-mask`, `data-tooltip`,
   `data-context-menu`) stay framework-neutral by construction.

package/docs/pages/guides/upgrading.md

@@ -1,12 +1,90 @@
-# Upgrading to 0.12
+# Upgrading
 
 Each step below is a search for a removed class or hook and its replacement.
 The [changelog](https://github.com/lekoala/actual-css/blob/master/CHANGELOG.md)
-lists every change; this page keeps the ones that need an edit.
+lists every change; this page keeps the ones that need an edit. Apply the
+sections in order when skipping a release.
 
 **Related terms:** migration, breaking changes, update, version.
 
-## Action rows
+## 0.12 to 0.13
+
+### Layout hooks stop at each layout
+
+`--cluster-justify`, `--cluster-align` and `--cluster-wrap` are reset on every
+`.cluster`, and `--grid-columns` and `--grid-min` on every `.grid`. A value set
+on an ancestor, including an outer cluster or grid, no longer reaches the
+layout inside it. Search application CSS and inline styles for these hooks on
+anything but the layout itself, then set them on the row or grid, or select it:
+
+```css
+.toolbar > .cluster {
+  --cluster-justify: space-between;
+}
+```
+
+`--gap` still inherits, so a density context keeps reaching every nested
+layout.
+
+### Avatar stacks
+
+`.avatar-stack` no longer takes its size from a child `.avatar.sm` or
+`.avatar.lg`. Move the size class to the stack and drop it from its avatars:
+
+```html
+<div class="avatar-stack sm" role="group" aria-label="Team members">
+  <div class="avatar" role="img" aria-label="John Doe">…</div>
+</div>
+```
+
+### Focus outline
+
+`--focus-outline` has no default value any more. Search application CSS for
+`var(--focus-outline)` and write the generic line instead:
+
+```css
+outline: var(--focus-ring-width) solid var(--focus-outline-color);
+```
+
+Setting `--focus-outline` still replaces the generic line.
+
+### List rows
+
+`.list-item` regions center on the row. For rows with long supporting text,
+add `.items-start` to the row or to the `.list` to keep them top-aligned.
+
+### Step rows
+
+`.steps-horizontal` budgets each step from its marker instead of `7rem`, so a
+row fits narrower widths before it scrolls. To keep the previous budget on a
+row, set `--step-min: 7rem` on it.
+
+### Current links and rows
+
+`.nav-link` shows its current state only for `aria-current="page"` or
+`aria-current="location"`, and `a.list-item` only for `aria-current="page"` or
+`aria-current="true"`. Search markup for other values on these classes and
+use the matching one.
+
+### Tabs
+
+`data-enhance="tabs"` only wires an element that also carries
+`role="tablist"`. Search markup for the token and add the role where it is
+missing; the console names each list it skipped.
+
+### Rendering changes without an edit
+
+- A horizontal `.tabs` strip never wraps: a strip that does not fit scrolls
+  horizontally, with no scrollbar and faded edges.
+- `.breadcrumb` never wraps either: a trail that does not fit truncates its
+  labels with an ellipsis, ancestors first. Ancestor labels need an `<a>` or
+  `<span>`.
+- The focus reserve of a scrolling dialog or drawer body no longer grows with
+  `--border-width`: 1px narrower under `prefers-contrast: more`.
+
+## 0.11 to 0.12
+
+### Action rows
 
 `.actions`, `.navbar-nav` and the layout of `.form-actions` are gone. A row of
 actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
@@ -27,12 +105,11 @@ actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
   `gap: var(--space-10)` on that row in application CSS.
 - `.form-actions` has no top margin and no `--form-actions-margin-block-start`:
   put `.stack` on the form. `--form-actions-justify` and `--form-actions-align`
-  still apply. In a modular build, import `layout/cluster` before
-  `forms/form-actions`.
+  still apply. In a modular build, also import `layout/cluster`.
 - `.justify-content-*` aligns only its own element and no longer reaches a
   nested `.cluster`. Put the utility on the row it should align.
 
-## Dialogs
+### Dialogs
 
 - `.dialog-confirmation` is removed. Compose `.media` with `.dialog-icon`, then
   a `<footer class="bleed background-subtle cluster justify-content-space-between">`;
@@ -46,7 +123,7 @@ actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
   `.dialog-confirmation` used 1.5rem. Set `--modal-pad: var(--space-50)` on
   the dialog to keep the roomier treatment.
 
-## Cards
+### Cards
 
 The layout of a `.card` header or footer row is a zero-specificity default: any
 author rule that targets the slot replaces it, not only a `.media`, `.cluster`,
@@ -54,7 +131,7 @@ author rule that targets the slot replaces it, not only a `.media`, `.cluster`,
 element rules such as `header { … }` or `footer { … }`, which now win over the
 card's slot row.
 
-## Themes and density
+### Themes and density
 
 - A theme sets `--control-pad-x-sm`, `--control-pad-x-md` and
   `--control-pad-x-lg` instead of `--control-pad-x`. Used as a nested island,
@@ -63,7 +140,7 @@ card's slot row.
 - `--font-width-dense` is removed, and `.compact` no longer condenses type: set
   `font-stretch` on the element that should render condensed.
 
-## Rendering changes without an edit
+### Rendering changes without an edit
 
 These need no markup change; compare the affected screens.
 

package/docs/pages/layout/center.md

@@ -15,7 +15,8 @@ Constrain readable content and center it in the viewport, with width and padding
 </main>
 ```
 
-Tune width and side padding with local variables.
+Tune width and side padding with `--center-size` and `--center-pad`. Both
+inherit: set them on `:root` for the site's content width, or on one region.
 
 ```css
 .docs-page {

package/docs/pages/layout/cluster.md

@@ -61,11 +61,15 @@ separate `.split` or `.spread` primitive; this is the same relationship.
 </div>
 ```
 
+Once the row wraps, `space-between` puts an item alone on its line at the
+start. To keep the end item on the end edge when it wraps, add
+`.margin-inline-start-auto` to it.
+
 To align a row to its top edge instead of centering it — useful when one item
-wraps to several lines — set `--cluster-align`.
+wraps to several lines — set `--cluster-align` on the cluster itself.
 
 ```css
-.filters {
+.cluster.filters {
   --cluster-align: start;
   --cluster-justify: space-between;
 }
@@ -74,8 +78,11 @@ wraps to several lines — set `--cluster-align`.
 The optional utility layer ships `.justify-content-start`, `.justify-content-center`,
 `.justify-content-end` and `.justify-content-space-between`. They set
 `justify-content` on that one row only; a nested `.cluster` keeps its own
-alignment. `--cluster-justify` is inherited, so setting it on a region reaches
-nested clusters too. See the utilities page.
+alignment. The `--cluster-*` hooks behave the same way: each cluster resets
+them, so a value applies to the cluster it is set on and never to a nested
+one. To align nested rows, select them (`.toolbar > .cluster`). `--gap` keeps
+inheriting, so a density context still reaches every nested cluster. See the
+utilities page.
 
 ## Controls inside a wrapping cluster
 

package/docs/pages/layout/grid.md

@@ -172,3 +172,5 @@ stacked, prefer `.switcher`.
 - `--grid-min` tunes the minimum item width of the intrinsic `.grid` recipe.
   It does not apply to `.grid-N`.
 - `--grid-columns` replaces that recipe with an author-owned template.
+
+Both stop at a nested `.grid`: set them on the grid itself.

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

@@ -47,3 +47,6 @@ When the layout stacks (narrow space), the aside stays on top.
 
 - `--sidebar-layout-size` sets the aside's preferred width.
 - `--sidebar-content-min` sets the main region's minimum viable width.
+
+The regions read both, so they also reach the regions of a nested
+`.sidebar-layout`; set them on the nested layout to give it its own sizes.

package/docs/pages/layout/switcher.md

@@ -18,3 +18,5 @@ independently.
 ### Hooks
 
 - `--switcher-threshold` controls the space needed before all peers share a row.
+  The children read it, so it also reaches the children of a nested
+  switcher; set it on the nested switcher to give it its own threshold.

package/docs/pages/layout/topbar.md

@@ -11,10 +11,12 @@ Use `.topbar` for the structural shell of an app-shell header: sticky positionin
   <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>
+  <nav aria-label="Breadcrumb">
+    <ol class="breadcrumb">
+      <li><a href="#">Overview</a></li>
+      <li aria-current="page">Accounts</li>
+    </ol>
+  </nav>
   <div class="grow"></div>
   <span class="avatar sm"><abbr>LW</abbr></span>
 </header>

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

@@ -42,6 +42,22 @@ For a round disc, add the `.circle` utility — it supplies the `border-radius`:
 }
 ```
 
+## Webfont glyphs
+
+An icon font draws nothing measurable until it loads, so a button or nav link
+shifts when the glyph arrives. Reserve a `1em` square on the icon library's
+class in application CSS; it follows the surrounding font size:
+
+```css
+.ti {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  inline-size: 1em;
+  block-size: 1em;
+}
+```
+
 ## Reuse the existing icon slots
 
 Several components already embody this slot — reach for them before composing
@@ -55,7 +71,7 @@ your own:
 ```html demo
 <div class="media">
   <span class="avatar primary"><abbr>AM</abbr></span>
-  <div class="stack">
+  <div class="stack gap-none">
     <strong>Ada Meridian</strong>
     <span class="muted">Senior designer.</span>
   </div>

package/docs/pages/utilities/flex.md

@@ -80,7 +80,7 @@ These helpers work by setting a custom property that participating components re
 so they also apply inside a component's own grid anatomy rather than only on plain
 flex containers:
 
-- `.items-start` / `.items-center` / `.items-end` / `.items-baseline` set `--items-align`, read by `.alert` and `.card`.
+- `.items-start` / `.items-center` / `.items-end` / `.items-baseline` set `--items-align`, read by `.alert`, `.card` and `.list-item`.
 - `.text-start` / `.text-center` / `.text-end` set `--text-align`, read by `.table` cells.
 
 `.justify-content-*` and `.flex-wrap` / `.flex-nowrap` (utilities/extra) set the property

package/docs/pages/utilities/sizing-wrapping.md

@@ -66,11 +66,10 @@ Use `.truncate` on the flexible item that should ellipsize inside a constrained
 
 ## Scroller
 
-Use `.scroller` to apply optional framework scrollbar treatment to a scroll container. It styles the scrollbar only; pair it with `.overflow-auto` or a component that already creates overflow.
+Use `.scroller` to apply optional framework overflow treatment to a scroll container: a quieter scrollbar. It does not create overflow; pair it with `.overflow-auto` or a component that already creates overflow.
 
-The utility is two standard declarations and nothing else — the engine keeps
-drawing the scrollbar, `.scroller` only hands it a density and a colour that
-follow the theme. There is no `::-webkit-scrollbar` chrome: rebuilding a thumb
+The engine keeps drawing the scrollbar; `.scroller` only hands it a density
+and a colour that follow the theme. There is no `::-webkit-scrollbar` chrome: rebuilding a thumb
 by hand means re-implementing the hover, the corner and the light/dark
 adaptation that `color-scheme` already provides, and the hand-built version
 never quite matches the native one anyway.
@@ -80,6 +79,9 @@ above the capability floor. An engine that knows neither ignores both
 declarations and draws its native scrollbar — the intended fallback, not a
 broken state.
 
+`.scroller` does not apply to touch screens, where the native overlay scrollbar
+stays: it hides at rest, where a styled bar would stay visible.
+
 `.scroller` is a layout primitive, so it comes with `actual.full.css` and with
 `actual-css/css/layout` like `.stack` or `.cluster`. A project importing module
 by module reaches it directly:
@@ -102,9 +104,13 @@ by module reaches it directly:
 .scroller {
   --scroller-track: transparent;
   --scroller-thumb: var(--border);
+}
 
-  scrollbar-color: var(--scroller-thumb) var(--scroller-track);
-  scrollbar-width: thin;
+@media not all and (pointer: coarse) {
+  .scroller {
+    scrollbar-color: var(--scroller-thumb) var(--scroller-track);
+    scrollbar-width: thin;
+  }
 }
 ```
 
@@ -120,6 +126,45 @@ Thickness is not a hook: `scrollbar-width` takes `thin` or `auto`, not a length.
 Hover is left to the engine — it varies by platform, and matching it by hand was
 the part of a custom scrollbar that never held up.
 
+### One-row strips
+
+Components that never wrap scroll horizontally when they do not fit: `.tabs`,
+`.steps-horizontal`, and `.table-wrap`. (`.breadcrumb` truncates its labels
+instead; see [Breadcrumb](../components/breadcrumb.md). `.pagination` wraps.)
+In supporting browsers, a strip that loads on a current link tab or step starts
+scrolled to it; elsewhere it starts at its first item.
+
+`.tabs` hides its scrollbar and fades its edges instead: selecting the clipped
+tab scrolls it into view. The others leave the scrollbar to the engine, so an
+OS-default horizontal scrollbar can sit under a short strip, and on touch
+screens it overlays the strip and hides at rest, leaving a clipped item as the
+cue that the strip continues. Put `.scroller` on the strip itself — the element
+that scrolls — for a thin, theme-coloured bar under a mouse; touch keeps the
+overlay. These strips have no edge fade (overflow shadow, scroll hint): the
+clipped item and the scrollbar already say there is more. Keyboard focus stops
+an item with its focus line inside the strip.
+
+```html
+<ol class="steps steps-horizontal scroller">
+```
+
+There is no class that hides the scrollbar: on a strip whose items do not
+scroll it themselves, it is the only visible scroll control for a mouse without
+a horizontal wheel. Apply `.scroller` to every such strip of a page, or to
+none, so the bars stay consistent.
+
+A strip keeps scrolling inside a flex or grid row, such as a label and link
+tabs on one `.cluster`: a `<nav>` directly around `.tabs` shrinks with the row
+(and around `.breadcrumb`, which then truncates). Any other wrapper needs
+`min-inline-size: 0`, or the row pushes the whole page into scrolling.
+
+```html
+<div class="cluster">
+  <span>Sections</span>
+  <nav aria-label="Account sections"><ul class="tabs">…</ul></nav>
+</div>
+```
+
 ## CSS hooks
 
 - `--scroller-track` — scrollbar track color.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.2",
@@ -112,7 +112,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "lint": "biome check",
+    "hooks:install": "bun scripts/install-hooks.js",
+    "lint": "biome check --reporter concise",
     "lint:fix": "biome check --write",
     "build:docs": "bun run build:themes && bun scripts/build-docs.js",
     "watch:docs": "bun run build:themes && bun scripts/build-docs.js --watch",
@@ -139,7 +140,6 @@
     "check:catalog": "bun scripts/check-catalog.js",
     "check:links": "bun scripts/check-doc-links.js",
     "check:templates": "bun scripts/check-templates.js",
-    "check:markup": "bun scripts/check-markup.js",
     "shot:crop": "bun scripts/shot-crop.js",
     "shot:forced": "bun scripts/forced-colors-shot.js",
     "shot:multi": "bun scripts/multi-shot.js",
@@ -152,11 +152,11 @@
     "release:notes": "bun scripts/release-notes.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",
-    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:size && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run generate:catalog && bun run check:catalog && bun run check:sync && bun run check:links && bun run check:templates && bun run check:markup && bun run test",
+    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:size && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run generate:catalog && bun run check:catalog && bun run check:sync && bun run check:links && bun run check:templates && bun run test",
     "prepublishOnly": "bun run build:all"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.12",
+    "@biomejs/biome": "^2.5.15",
     "happy-dom": "^20.14.0"
   },
   "dependencies": {

package/src/cli/actual-css.js

@@ -12,7 +12,7 @@ function usage() {
     "",
     "  -o, --out FILE   write the bundle to FILE / the export to DIR (required)",
     "      --minify     collapse comments and whitespace",
-    "      --theme FILE read this [data-theme] file instead of the default theme",
+    "      --theme FILE read this theme file ([data-theme] or :root) over the default",
     "      --name NAME  the data-theme name, when the file declares several",
     "  -h, --help       show this message",
     "      --version    print the actual-css version",

package/src/css/components/alert.css

@@ -107,10 +107,11 @@
   }
 }
 
-/* Decorative leading icon — use .alert-icon on the icon element. */
+/* Decorative leading icon — use .alert-icon on the icon element. display and
+   vertical-align are the no-:has() layout (Degraded tier: the icon sits inline
+   before the text); the grid anatomy below replaces them. */
 .alert > .alert-icon {
   display: inline-block;
-  flex: none;
   inline-size: var(--alert-icon-size);
   block-size: var(--alert-icon-size);
   font-size: var(--alert-icon-size);
@@ -142,45 +143,44 @@
 
 /* Grid anatomy — activated by a leading icon, a trailing dismiss button, or
    both. Icon and dismiss are pinned to the outer columns; anything else (the
-   message content) flows into the remaining text column. */
-@supports selector(.alert:has(> *)) {
-  .alert:has(> .alert-icon, > .close) {
-    display: grid;
-    grid-template-columns: minmax(0, 1fr);
-    align-items: var(--items-align, start);
-    column-gap: var(--space-30);
-  }
-
-  .alert:has(> .alert-icon) {
-    grid-template-columns: auto minmax(0, 1fr);
-  }
+   message content) flows into the remaining text column. Without :has(), the
+   grid rules drop together and the alert keeps ordinary block flow. */
+.alert:has(> .alert-icon, > .close) {
+  display: grid;
+  /* No grid-template-columns: the icon and close branches below always set
+     it, since one of them is what matched. */
+  align-items: var(--items-align, start);
+  column-gap: var(--space-30);
+}
 
-  .alert:has(> .alert-icon) > .alert-icon {
-    grid-column: 1;
-    grid-row: 1 / -1;
-    display: inline-grid;
-    place-items: center;
-    margin-block-start: 0.125em;
-  }
+.alert:has(> .alert-icon) {
+  grid-template-columns: auto minmax(0, 1fr);
+}
 
-  .alert:has(> .alert-icon) > :not(.alert-icon, .close) {
-    grid-column: 2;
-  }
+.alert:has(> .alert-icon) > .alert-icon {
+  grid-column: 1;
+  grid-row: 1 / -1;
+  display: inline-grid;
+  place-items: center;
+  margin-block-start: 0.125em;
+}
 
-  .alert:has(> .close) {
-    grid-template-columns: minmax(0, 1fr) auto;
-  }
+.alert:has(> .alert-icon) > :not(.alert-icon, .close) {
+  grid-column: 2;
+}
 
-  .alert:has(> .alert-icon):has(> .close) {
-    grid-template-columns: auto minmax(0, 1fr) auto;
-  }
+.alert:has(> .close) {
+  grid-template-columns: minmax(0, 1fr) auto;
+}
 
-  .alert:has(> .close) > .close {
-    grid-column: -2 / -1;
-    grid-row: 1;
-  }
+.alert:has(> .alert-icon):has(> .close) {
+  grid-template-columns: auto minmax(0, 1fr) auto;
 }
 
+.alert:has(> .close) > .close {
+  grid-column: -2 / -1;
+  grid-row: 1;
+}
 /* Links */
 .alert :where(a:not(.btn)) {
   color: inherit;

package/src/css/components/avatar.css

@@ -11,13 +11,13 @@
  * --avatar-size
  * --avatar-radius
  * --avatar-font-size
+ * --avatar-bg
  * --avatar-stack-size
  * --avatar-stack-font-size
  * --avatar-stack-overlap
  * --avatar-stack-ring
  *
  * Internal:
- * --avatar-bg
  * --avatar-fg
  * --avatar-status-translate-x
  */
@@ -95,16 +95,13 @@
 
 .avatar > img,
 .avatar > picture > img {
+  display: block;
   inline-size: 100%;
   block-size: 100%;
   object-fit: cover;
   border-radius: inherit;
 }
 
-.avatar > picture > img {
-  display: block;
-}
-
 button.avatar {
   appearance: none;
   cursor: pointer;
@@ -198,19 +195,6 @@ a.avatar[aria-disabled="true"] {
   --avatar-stack-font-size: var(--font-size-lg);
 }
 
-/* Infer the stack scale from its avatars. Progressive: without :has() the
-   explicit .avatar-stack.sm/.lg classes and the default size still size the
-   group, only the inference is lost. */
-.avatar-stack:has(> .avatar.sm) {
-  --avatar-stack-size: 1.75rem;
-  --avatar-stack-font-size: var(--font-size-xs);
-}
-
-.avatar-stack:has(> .avatar.lg) {
-  --avatar-stack-size: 3rem;
-  --avatar-stack-font-size: var(--font-size-lg);
-}
-
 /* Overlapping avatars hide their neighbour: a translucent fill (--surface-subtle
    on a glass palette) would show the next avatar's edge through it, most of all
    when hover raises one above the other. The fill is layered over the opaque

package/src/css/components/badge.css

@@ -137,7 +137,6 @@
   --badge-size: var(--badge-dot-size);
   --badge-bg: var(--intent, var(--neutral));
   --badge-fg: var(--intent-fg, var(--neutral-fg));
-  --badge-border: transparent;
   padding: 0;
   border: 0;
   inline-size: var(--badge-size);