actual-css 0.5.0 → 0.7.0

package/docs/pages/utilities/overflow.md

@@ -4,13 +4,20 @@ Explicit overflow handling for content that may exceed its container.
 
 ## Class reference
 
-| Class              | Kind    | Description                                                           |
-|--------------------|---------|-----------------------------------------------------------------------|
-| `.overflow-auto`   | Utility | Enables scrolling when content exceeds the container.                 |
-| `.overflow-hidden` | Utility | Clips overflowing content. Optional layer.                            |
-| `.overflow-clip`   | Utility | Clips overflowing content without a scroll container. Optional layer. |
-| `.overflow-x-auto` | Utility | Horizontal scrolling only. Optional layer.                            |
-| `.overflow-y-auto` | Utility | Vertical scrolling only. Optional layer.                              |
+Base utilities:
+
+| Class            | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `.overflow-auto` | Enables scrolling when content exceeds the container. |
+
+Extra utilities:
+
+| Class              | Description                                           |
+| ------------------ | ----------------------------------------------------- |
+| `.overflow-hidden` | Clips overflowing content.                            |
+| `.overflow-clip`   | Clips overflowing content without a scroll container. |
+| `.overflow-x-auto` | Horizontal scrolling only.                            |
+| `.overflow-y-auto` | Vertical scrolling only.                              |
 
 Use `.overflow-auto` when content may overflow its container, especially tables and code-like regions.
 

package/docs/pages/utilities/overview.md

@@ -7,6 +7,28 @@ Utilities are a small escape hatch for common single-purpose needs. They should
 - Keep utility names stable, boring, and few.
 - Utilities should use logical properties where relevant.
 
+## Two layers
+
+Utilities ship in two modules, and the split is about **naming and curation**,
+not about opting in. Importing `actual-css/css/utilities` — or
+`actual.full.css` — gives you both.
+
+| Module    | Import                           | Naming                             |
+| --------- | -------------------------------- | ---------------------------------- |
+| **Base**  | `actual-css/css/utilities/base`  | Compact names, frequent operations |
+| **Extra** | `actual-css/css/utilities/extra` | Explicit property/value names      |
+
+Base is the curated set, and it is where a short name is allowed: `.px`, `.py`,
+`.mbs`, `.gap-none`. Extra spells out the property and the value — `.gap-sm`,
+`.overflow-x-auto`, `.justify-content-center` — and never gives a base utility
+a second spelling.
+
+Reach for base first. Extra exists so an explicit one-off does not have to
+become a new short name, which is the pressure that grows a utility surface.
+
+Extra utilities are concentrated in flex, overflow and spacing; those pages
+list the two layers as separate tables. Every other utility page is base only.
+
 ## Non-Goals
 
 > Utilities deliberately excluded to keep the surface small and intentional.

package/docs/pages/utilities/shape.md

@@ -5,7 +5,7 @@ Rare shape utilities for cases that must be perfectly round or square.
 ## Class reference
 
 | Class     | Kind    | Description                                         |
-|-----------|---------|-----------------------------------------------------|
+| --------- | ------- | --------------------------------------------------- |
 | `.circle` | Utility | Forces a perfectly round shape via `--radius-full`. |
 
 Shape utilities should be rare because shape is mostly theme-level.

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

@@ -4,13 +4,13 @@ Small layout corrections for controls, labels, and compact rails.
 
 ## Class reference
 
-| Class                     | Kind    | Description                                                               |
-|---------------------------|---------|---------------------------------------------------------------------------|
-| `.fit`                    | Utility | Shrinks a control or element to its content width.                        |
-| `.text-nowrap`            | Utility | Keeps text on one line.                                                   |
-| `.truncate`               | Utility | Ellipsizes overflowing single-line text.                                  |
-| `.scroller`               | Utility | Theme-aware scrollbar density and colour for scroll containers. Optional layer. |
-| `.scroller.stable-gutter` | Variant | Reserves scrollbar gutter space so layout does not shift. Optional layer. |
+| Class                     | Kind    | Description                               |
+| ------------------------- | ------- | ----------------------------------------- |
+| `.fit`                    | Utility | Shrinks an element to its content width.  |
+| `.text-nowrap`            | Utility | Keeps text on one line.                   |
+| `.truncate`               | Utility | Ellipsizes overflowing single-line text.  |
+| `.scroller`               | Layout  | Theme-aware scrollbar density and colour. |
+| `.scroller.stable-gutter` | Variant | Reserves inline-axis scrollbar gutter.    |
 
 Use `.fit` when a control or element should shrink to its content instead of filling the available inline space.
 
@@ -78,7 +78,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` is not imported by `actual.css`. Import it explicitly when a project wants Actual CSS scrollbar chrome instead of the native OS default:
+`.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:
 
 ```css
 @import "actual-css/css/layout/scroller";

package/docs/pages/utilities/spacing.md

@@ -4,25 +4,32 @@ Semantic step helpers for gap, padding, and margin — the most common inline-st
 
 ## Class reference
 
-| Class                       | Kind    | Description                                                   |
-|-----------------------------|---------|---------------------------------------------------------------|
-| `.gap-none`                 | Utility | `gap: 0` on the element itself.                               |
-| `.py`                       | Utility | Block (vertical) padding at the current density step.         |
-| `.px`                       | Utility | Inline (horizontal) padding at the current density step.      |
-| `.mbs`                      | Utility | Block-start margin at the current density step.               |
-| `.mbe`                      | Utility | Block-end margin at the current density step.                 |
-| `.gap-sm`                   | Utility | `gap: var(--space-20)` — denser row rhythm. Optional layer.   |
-| `.gap-md`                   | Utility | `gap: var(--space-40)` — default row rhythm. Optional layer.  |
-| `.gap-lg`                   | Utility | `gap: var(--space-50)` — roomier row rhythm. Optional layer.  |
-| `.padding-context`          | Utility | All-side padding at the current density step. Optional layer. |
-| `.gap-context`              | Utility | `gap: var(--gap)`. Optional layer.                            |
-| `.row-gap-context`          | Utility | `row-gap: var(--gap)`. Optional layer.                        |
-| `.column-gap-context`       | Utility | `column-gap: var(--gap)`. Optional layer.                     |
-| `.margin-inline-auto`       | Utility | Horizontally centers a block. Optional layer.                 |
-| `.margin-inline-start-auto` | Utility | Pushes a block toward the inline end. Optional layer.         |
-| `.margin-inline-end-auto`   | Utility | Pushes a block toward the inline start. Optional layer.       |
-| `.margin-block-start-auto`  | Utility | Pushes content toward the block end. Optional layer.          |
-| `.margin-block-end-auto`    | Utility | Pushes content toward the block start. Optional layer.        |
+Base utilities:
+
+| Class       | Description                                              |
+| ----------- | -------------------------------------------------------- |
+| `.gap-none` | `gap: 0` on the element itself.                          |
+| `.py`       | Block (vertical) padding at the current density step.    |
+| `.px`       | Inline (horizontal) padding at the current density step. |
+| `.mbs`      | Block-start margin at the current density step.          |
+| `.mbe`      | Block-end margin at the current density step.            |
+
+Extra utilities:
+
+| Class                       | Description                                   |
+| --------------------------- | --------------------------------------------- |
+| `.gap-sm`                   | `gap: var(--space-20)` — denser row rhythm.   |
+| `.gap-md`                   | `gap: var(--space-40)` — default row rhythm.  |
+| `.gap-lg`                   | `gap: var(--space-50)` — roomier row rhythm.  |
+| `.padding-context`          | All-side padding at the current density step. |
+| `.gap-context`              | `gap: var(--gap)`.                            |
+| `.row-gap-context`          | `row-gap: var(--gap)`.                        |
+| `.column-gap-context`       | `column-gap: var(--gap)`.                     |
+| `.margin-inline-auto`       | Horizontally centers a block.                 |
+| `.margin-inline-start-auto` | Pushes a block toward the inline end.         |
+| `.margin-inline-end-auto`   | Pushes a block toward the inline start.       |
+| `.margin-block-start-auto`  | Pushes content toward the block end.          |
+| `.margin-block-end-auto`    | Pushes content toward the block start.        |
 
 Spacing helpers follow the density context. The default step is
 `--space-40` (1rem); the `.sm` context tightens it to `--space-20` (0.5rem)

package/docs/pages/utilities/text.md

@@ -5,7 +5,7 @@ Lightweight helpers for muted or secondary text without a full color scale.
 ## Class reference
 
 | Class           | Kind    | Description                                              |
-|-----------------|---------|----------------------------------------------------------|
+| --------------- | ------- | -------------------------------------------------------- |
 | `.muted`        | Utility | Secondary text color.                                    |
 | `.text-start`   | Utility | Logical start-aligned text; sets `--text-align`.         |
 | `.text-center`  | Utility | Centered text; sets `--text-align`.                      |

package/llms.txt

@@ -16,19 +16,37 @@ Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [m
 - `actual-css/full` — the complete framework: core plus every component, form, layout, typography, effect, and utility family.
 - `actual-css/js` — the enhancement loader only; it discovers `data-enhance` markers and loads enhancers on demand.
 - `actual-css/js/full` — the complete runtime with all built-in enhancers pre-registered.
-- `actual-css/reserved-classes.json` — machine-readable list of every class name the framework can generate. Use it to validate class usage in HTML (an "unknown class" checker) instead of guessing names from other frameworks.
+- `actual-css/reserved-classes.json` — machine-readable list of the framework-owned class namespace. Use it to check whether a class belongs to Actual CSS and to validate claimed framework classes; application-specific classes are expected to exist outside this manifest.
 - Individual families and modules are importable separately (`actual-css/css/components`, `actual-css/css/layout/grid`, `actual-css/js/dialog`, …); see [README](README.md) and [Modular imports](docs/pages/guides/modular-import.md).
 
+Forms are the one family with two aggregate entrypoints:
+`actual-css/css/forms` is the native-control baseline; use
+`actual-css/css/forms/all` for the complete forms family.
+
 The composition guides in [README](README.md) and [Progressive Enhancements](docs/pages/enhancements/overview.md)
 show supported CSS modules and individual enhancer imports without duplicating
 the full export list here.
 
 Presentation (`class`) and behavior (`data-enhance`) are separate layers.
-Behaviour primitives (`enhance`, `floating`, `surface`, `keys`, `menu`, `focus`,
-`events`) are independently importable for building custom widgets.
-See [enhancement contract](docs/design-notes/enhancement-contract.md) and
+Behaviour primitives are independently importable for building custom widgets,
+including `enhance`, `surface`, `floating`, `focus-group`, `keys`, `input`,
+`command`, `menu`, `focus`, `escape`, and `events`. See
+[enhancement contract](docs/design-notes/enhancement-contract.md) and
 [widget primitives](docs/design-notes/widget-primitives.md).
 
+## Choosing a page shell
+
+Before choosing a content layout, choose the page shell:
+
+- Normal scrolling page, marketing/editorial site, or ordinary application page
+  → semantic landmarks; optionally `.app-shell` and `.navbar`.
+- Persistent topbar + independently scrolling main + adaptive bottom/side
+  primary navigation → `.app-layout`.
+
+Do not choose `.app-layout` merely because the product is an application. Its
+viewport-sized shell, internal scrolling, and adaptive navigation are one
+combined contract. See [layout choices](docs/pages/layout/choosing.md).
+
 ## Choosing a layout primitive
 
 Pick from the relationship between children, not the number of children in one mockup:
@@ -41,6 +59,11 @@ Pick from the relationship between children, not the number of children in one m
 - Explicit region placement on a shared 12-column canvas → `.column-layout`
 - Vertical flow → `.stack`; wrapping inline items → `.cluster`
 
+`.container-query` establishes the framework's shared
+`actual-container / inline-size` container for components that explicitly
+respond to allocated space; it is not a general prerequisite for responsive
+layouts.
+
 Use `--grid-columns` on `.grid` for exact track templates that do not match a
 built-in layout contract: arbitrary structural counts (seven calendar days),
 asymmetric fractional tracks, or mixed intrinsic/flexible tracks. See

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "actual-css",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.1",
   "license": "MIT",
   "author": "Thomas <thomas@lekoala.be>",
   "repository": {
@@ -58,7 +58,6 @@
     "./js/parse-config": "./src/js/parse-config.js",
     "./js/events": "./src/js/events.js",
     "./js/filter": "./src/js/filter.js",
-    "./js/floating": "./src/js/floating.js",
     "./js/flyout": "./src/js/flyout.js",
     "./js/focus": "./src/js/focus.js",
     "./js/focus-group": "./src/js/focus-group.js",
@@ -115,6 +114,7 @@
     "build:docs": "bun run build:themes && bun scripts/build-docs.js",
     "watch:docs": "bun run build:themes && bun scripts/build-docs.js --watch",
     "check:docs": "bun scripts/check-docs.js",
+    "format:docs": "bun scripts/format-doc-tables.js",
     "check:doc-classes": "bun scripts/check-doc-classes.js",
     "check:compat": "bun scripts/check-compat.js",
     "check:css-api": "bun scripts/check-css-api.js",
@@ -136,11 +136,14 @@
     "check:sync": "bun scripts/check-sync.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: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 check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:size",
+    "build:all": "bun run lint && bun run build:dist && bun run build:js && 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 check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:size",
     "prepublishOnly": "bun run build:all"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5",
     "happy-dom": "^20.11"
+  },
+  "dependencies": {
+    "@lekoala/floating": "^0.1.0"
   }
 }

package/scripts/reserved-classes.json

@@ -75,7 +75,6 @@
   "column-start-8",
   "column-start-9",
   "compact",
-  "complete",
   "container-query",
   "cursor-pointer",
   "danger",
@@ -243,7 +242,11 @@
   "stack",
   "start",
   "status-bar",
+  "step-complete",
+  "step-label",
   "steps",
+  "steps-horizontal",
+  "steps-vertical",
   "sticky",
   "stretch",
   "subtle",

package/src/css/components/fab.css

@@ -1,14 +1,17 @@
 /*
  * Fixed floating action placement and a native-details speed dial.
- * Button owns the action's size, shape, and intent; FAB only owns placement.
+ * Button owns the trigger's size, shape, and intent; FAB owns placement and
+ * the speed dial's structural open/close markers (--icon-plus / --icon-close).
  *
  * Public hooks:
  * --fab-offset
  * --fab-gap
+ * --fab-icon-size
  */
 .fab {
   --fab-offset: var(--space-40);
   --fab-gap: var(--space-20);
+  --fab-icon-size: 1.5rem;
 
   position: fixed;
   z-index: var(--z-menu);
@@ -17,6 +20,9 @@
 }
 
 .fab > summary {
+  /* Centers the toggle markers: the summary is the markers' positioned
+     context, not just the app-button class. */
+  position: relative;
   list-style: none;
   cursor: pointer;
 }
@@ -25,11 +31,35 @@
   display: none;
 }
 
-/* A lone decorative plus can communicate the open/close state without
-   requiring a second icon or JavaScript-managed content. */
-.fab > summary > [aria-hidden="true"]:only-child {
-  display: inline-block;
-  transition: transform var(--duration);
+/* The speed dial trigger is an icon-only toggle. FAB owns both structural
+   markers: masked pseudo-elements swap the shared plus (closed) and close
+   (open) glyphs at the same size, so the two states never drift apart. */
+.fab > summary::before,
+.fab > summary::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  inline-size: var(--fab-icon-size);
+  block-size: var(--fab-icon-size);
+  background: currentColor;
+  opacity: 0;
+  transform: scale(0.8);
+  transition:
+    opacity var(--duration),
+    transform var(--duration);
+}
+
+.fab > summary::before {
+  -webkit-mask: var(--icon-plus) center / contain no-repeat;
+  mask: var(--icon-plus) center / contain no-repeat;
+  opacity: 1;
+  transform: none;
+}
+
+.fab > summary::after {
+  -webkit-mask: var(--icon-close) center / contain no-repeat;
+  mask: var(--icon-close) center / contain no-repeat;
 }
 
 .fab-actions {
@@ -87,8 +117,14 @@
   transition-delay: 0s;
 }
 
-.fab[open] > summary > [aria-hidden="true"]:only-child {
-  transform: rotate(45deg);
+.fab[open] > summary::before {
+  opacity: 0;
+  transform: scale(0.8);
+}
+
+.fab[open] > summary::after {
+  opacity: 1;
+  transform: none;
 }
 
 @media print {

package/src/css/components/flyout.css

@@ -79,12 +79,50 @@
   transition: opacity var(--duration-fast) ease;
 }
 
-.flyout.is-open:not(.is-sheet) {
+/* Native popovers enter the top layer with UA geometry that conflicts with
+   anchored positioning. The reset is gated on real Popover support because an
+   attribute selector matches whether or not the engine implements Popover:
+   without it the UA neither hides nor promotes the element, so an ungated
+   reset would strand a permanently visible panel at inset: auto. Popover is
+   not part of Actual's Minimal contract — engines inside the Minimal range
+   may lack it — so the gate is about the capability, not the floor. Kept
+   scoped to Actual surfaces so bare [popover] elements retain their platform
+   presentation. */
+@supports selector(:popover-open) {
+  .flyout[popover] {
+    position: fixed;
+    inset: auto;
+    margin: 0;
+  }
+
+  /* A presentation class may own its *visible* display type, but must not
+     override the platform's hidden state. The UA closes a popover with
+     display: none, and an author declaration beats the UA origin whatever the
+     specificity — so .flyout's own display: grid would leave a closed popover
+     painted at its static position. Restoring both properties here also gives
+     the native path the exit target the runtime path already has in
+     .flyout[hidden]: without an opacity to animate, the overlay/display
+     allow-discrete transition below would hold a fully opaque panel in the top
+     layer and then snap it away. */
+  .flyout[popover]:not(:popover-open) {
+    display: none;
+    opacity: 0;
+  }
+}
+
+/* compat-ok: :popover-open rides in a forgiving :is(), where an engine without
+   Popover discards just that member and .is-open alone keeps driving the open
+   state. This is a property of the forgiving list, not of the pseudo-class: in
+   a plain selector list an unsupported member would invalidate the whole rule.
+   Keep it inside :is()/:where() or gate it. */
+.flyout:is(.is-open, :popover-open):not(.is-sheet) {
   inset: auto;
 }
 
+/* compat-ok: forgiving :is() again, and @starting-style is itself unsupported
+   across part of the Minimal range, so the rule simply does not exist there. */
 @starting-style {
-  .flyout.is-open {
+  .flyout:is(.is-open, :popover-open) {
     opacity: 0;
   }
 }
@@ -123,16 +161,23 @@
   translate: 0 var(--space-30);
 }
 
+/* compat-ok: forgiving :is() inside @starting-style, as above. */
 @starting-style {
-  .flyout.is-sheet.is-open {
+  .flyout.is-sheet:is(.is-open, :popover-open) {
     translate: 0 var(--space-30);
   }
 }
 
+/* display keeps the exit transition alive for the [hidden] path; overlay does
+   the same for the native popover path, where hidePopover() would otherwise
+   drop the panel out of the top layer on the first frame and let a parent
+   overflow or a dialog clip the fade. An engine that cannot transition either
+   property ignores it and the exit is instant. */
 @supports (transition-behavior: allow-discrete) {
   .flyout {
     transition:
       opacity var(--duration-fast) ease,
+      overlay var(--duration-fast) allow-discrete,
       display var(--duration-fast) allow-discrete;
   }
 
@@ -140,6 +185,7 @@
     transition:
       opacity var(--duration-fast) ease,
       translate var(--duration-fast) ease,
+      overlay var(--duration-fast) allow-discrete,
       display var(--duration-fast) allow-discrete;
   }
 }

package/src/css/components/join.css

@@ -63,6 +63,13 @@
   border-end-start-radius: var(--join-es);
 }
 
+/* A square icon button has an explicit block size, which otherwise prevents
+   align-items: stretch from matching a taller labelled sibling. The button's
+   existing min-block-size keeps the standalone square-size invariant intact. */
+.join > .btn.icon-only {
+  block-size: auto;
+}
+
 .join > :first-child {
   --join-ss: var(--join-radius);
   --join-es: var(--join-radius);

package/src/css/components/list.css

@@ -33,7 +33,9 @@
 .list > li > .list-item {
   display: grid;
   grid-template-columns: auto minmax(0, 1fr) auto;
-  align-items: center;
+  /* Regions align to the first line, so leading, title, and trailing controls
+     share one horizontal line while supporting text wraps beneath. */
+  align-items: start;
   gap: var(--list-item-gap);
   min-block-size: var(--list-item-min-size);
   padding-block: var(--list-item-pad-block);

package/src/css/components/menu.css

@@ -75,30 +75,36 @@
 /* Checkable menu items are one command with one accessible state. Their
    indicator is generated so authors do not add a second interactive input. */
 .menu-item:is([role="menuitemcheckbox"], [role="menuitemradio"])::before {
-  display: grid;
+  content: "";
+  display: block;
   flex: 0 0 var(--menu-item-icon-size);
   inline-size: var(--menu-item-icon-size);
-  place-items: center;
-}
-
-.menu-item[role="menuitemcheckbox"]::before {
-  content: "";
+  block-size: var(--menu-item-icon-size);
 }
 
 .menu-item[role="menuitemcheckbox"][aria-checked="true"]::before {
-  content: "✓";
+  background: currentColor;
+  -webkit-mask: var(--icon-check) center / contain no-repeat;
+  mask: var(--icon-check) center / contain no-repeat;
 }
 
 .menu-item[role="menuitemcheckbox"][aria-checked="mixed"]::before {
-  content: "−";
+  background:
+    linear-gradient(currentColor 0 0) center / 60% max(var(--border-width), 0.125em) no-repeat;
 }
 
 .menu-item[role="menuitemradio"]::before {
-  content: "○";
+  background: radial-gradient(circle, transparent 0 46%, currentColor 48% 58%, transparent 60%);
 }
 
 .menu-item[role="menuitemradio"][aria-checked="true"]::before {
-  content: "●";
+  background: radial-gradient(
+    circle,
+    currentColor 0 25%,
+    transparent 27% 46%,
+    currentColor 48% 58%,
+    transparent 60%
+  );
 }
 
 .menu-item:focus-visible {