actual-css 0.2.0 → 0.3.0

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

@@ -0,0 +1,115 @@
+# Sizing And Wrapping
+
+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 | Quiet custom scrollbar chrome for scroll containers. Optional layer. |
+| `.scroller.stable-gutter` | Variant | Reserves scrollbar gutter space so layout does not shift. Optional layer. |
+
+Use `.fit` when a control or element should shrink to its content instead of filling the available inline space.
+
+```html demo
+<select class="select fit" aria-label="Theme">
+  <option>System</option>
+  <option>Light</option>
+  <option>Dark</option>
+</select>
+```
+
+Use `.text-nowrap` to keep text on one line inside a cell or label. To stop a
+layout primitive from wrapping — for example to force a `.cluster` onto a single
+row — set `--cluster-wrap: nowrap`.
+
+```html demo
+<div class="cluster sm" style="--cluster-wrap: nowrap;">
+  <select class="select sm fit" aria-label="Segment">
+    <option>All segments</option>
+  </select>
+  <button class="btn sm outline" type="button">Filter</button>
+</div>
+```
+
+Use `.truncate` on the flexible item that should ellipsize inside a constrained row.
+
+```html demo
+<header class="cluster" style="--cluster-wrap: nowrap;">
+  <strong class="truncate">A long account name that should not push actions away</strong>
+  <button class="btn sm ghost" type="button">Open</button>
+</header>
+```
+
+```css
+.fit {
+  inline-size: fit-content;
+  max-inline-size: 100%;
+}
+
+.text-nowrap {
+  white-space: nowrap;
+}
+
+.truncate {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+```
+
+## 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.
+
+`scroller` is not imported by `actual.css`. Import it explicitly when a project wants Actual CSS scrollbar chrome instead of the native OS default:
+
+```css
+@import "actual-css/css/optional/scroller";
+```
+
+```html demo
+<div class="overflow-auto scroller" style="max-block-size: 12rem">
+  <div class="stack">
+    <p>Scrollable content keeps the native scrollbar but makes it quieter.</p>
+    <p>Long content can keep flowing without forcing every component to invent its own scrollbar rules.</p>
+    <p>The utility exposes local custom properties for one-off tuning.</p>
+  </div>
+</div>
+```
+
+```css
+.scroller {
+  --scroller-size: 0.625rem;
+  --scroller-padding: 0.125rem;
+  --scroller-track: transparent;
+  --scroller-thumb: var(--border);
+  --scroller-thumb-hover: var(--text-muted);
+
+  scrollbar-color: var(--scroller-thumb) var(--scroller-track);
+  scrollbar-width: thin;
+}
+```
+
+Customize locally when a scroll surface needs more contrast:
+
+```html
+<div class="overflow-auto scroller"
+     style="--scroller-thumb: var(--text-muted); --scroller-thumb-hover: var(--text)">
+  ...
+</div>
+```
+
+For rounded scroll containers, keep the thumb visually away from the edge by tuning `--scroller-padding` rather than adding extra wrappers or masking pseudo-elements.
+
+## CSS hooks
+
+- `--scroller-size` — scrollbar thickness.
+- `--scroller-padding` — inset between the thumb and the track edge.
+- `--scroller-track` — scrollbar track color.
+- `--scroller-thumb` — scrollbar thumb color.
+- `--scroller-thumb-hover` — scrollbar thumb color on hover.

package/docs/pages/utilities/spacing.md

@@ -0,0 +1,79 @@
+# Spacing Helpers
+
+Semantic step helpers for gap, padding, and margin — the most common inline-style escape hatches.
+
+## 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. |
+
+Spacing helpers follow the density context. The default step is
+`--space-40` (1rem); the `.sm` context tightens it to `--space-20` (0.5rem)
+and the `.lg` context loosens it to `--space-50` (1.5rem). All helpers read
+`--density-space` and map to logical properties (`padding-block`,
+`margin-block-end`, etc.) for writing-direction safety.
+
+## Gap
+
+Override the default gap from layout primitives (`.stack`, `.cluster`, `.grid`):
+
+```html demo
+<ul class="cluster">
+  <li><a href="/about" class="btn ghost">About</a></li>
+  <li><a href="/contact" class="btn ghost">Contact</a></li>
+</ul>
+```
+
+- `.gap-none` → `gap: 0`
+
+`.gap-none` sets the element's own gap directly and does not change `--gap`
+for nested layouts. For a denser or roomier rhythm, use the `.sm` / `.lg`
+density contexts or override `--gap` on the layout instance.
+
+## Padding
+
+Block (vertical) and inline (horizontal) padding. Values respond to the density context.
+
+```html demo
+<section role="tabpanel" class="py">
+  Panel content with breathing room above and below.
+</section>
+```
+
+- `.py` → `padding-block: var(--density-space)`
+- `.px` → `padding-inline: var(--density-space)`
+
+## Margin
+
+Block-start and block-end margin for giving elements room:
+
+```html demo
+<h2 class="mbs">A section heading with space above</h2>
+```
+
+- `.mbs` → `margin-block-start: var(--density-space)`
+- `.mbe` → `margin-block-end: var(--density-space)`
+
+No `mbs-none` / `mbe-none` — use `margin: 0` via `.list-reset` for lists, or a layout primitive that already resets margins (`.stack > *`).
+
+## CSS hooks
+
+- `--density-space` — the step every padding and margin helper reads; `.sm` sets it to `--space-20`, default to `--space-40`, `.lg` to `--space-50`.
+- `--gap` — base gap of layout primitives; read by the optional `.gap-context`, `.row-gap-context`, and `.column-gap-context` helpers.

package/docs/pages/utilities/text.md

@@ -0,0 +1,43 @@
+# Text Helpers
+
+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`. |
+| `.text-end` | Utility | Logical end-aligned text; sets `--text-align`. |
+| `.text-balance` | Utility | Balanced line wrapping (`text-wrap: balance`). |
+| `.text-pretty` | Utility | Pretty line wrapping (`text-wrap: pretty`). |
+| `.lead` | Utility | Slightly larger, relaxed reading-introduction paragraph. |
+
+## Muted
+
+Use `.muted` for secondary text when no semantic element already carries the meaning.
+
+```html demo
+<p class="muted">Last updated June 12, 2026.</p>
+```
+
+```css
+.muted {
+  color: var(--text-muted);
+}
+```
+
+Do not create a full text color utility scale. Intent colors belong to components and state, not arbitrary text decoration.
+
+## Text alignment
+
+Use `.text-start`, `.text-center`, or `.text-end` when a component or layout primitive does not already set alignment. These use logical properties so they follow the writing direction.
+
+## Text wrap
+
+`.text-balance` and `.text-pretty` opt elements outside `.prose` into balanced or pretty text wrapping. They are safe progressive enhancements: browsers that do not support a `text-wrap` value ignore that declaration and keep normal wrapping.
+
+## Lead
+
+`.lead` is a slightly larger, more relaxed reading-introduction paragraph (`1.125em`, `--line-height-relaxed`). Use it for introductory text in editorial surfaces. For fluid headline sizing, use `src/css/optional/typography-fluid.css`.

package/llms.txt

@@ -6,15 +6,15 @@ Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [m
 
 ## Documentation
 
-- [Docs index](docs/README.md): the maintained map of user docs and design notes.
+- [Documentation source](docs/pages/): the docs pages, generated into `site/` by `bun run build:docs` (start at `site/index.html`).
 
 ## Package Entrypoints
 
 `package.json#exports` is the canonical package surface. Use `actual-css` for the
 full CSS framework and `actual-css/js` for the complete runtime. The composition
-guides in [README](README.md) and [JavaScript](docs/javascript.md) show supported
-CSS modules and individual enhancer imports without duplicating the full export
-list here.
+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.
 
 In 0.2, presentation (`class`) and behavior (`data-enhance`) are separate layers.
 Behaviour primitives (`enhance`, `floating`, `surface`, `keys`, `menu`, `focus`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.3.14",
@@ -31,6 +31,7 @@
     "./css/layer": "./src/css/actual.layer.css",
     "./css/components": "./src/css/components/index.css",
     "./css/forms": "./src/css/forms/index.css",
+    "./css/optional": "./dist/optional.min.css",
     "./css/themes": null,
     "./css/themes/*": null,
     "./css/*": "./src/css/*.css",
@@ -38,13 +39,16 @@
     "./js/command": "./src/js/command.js",
     "./js/context-menu": "./src/js/context-menu.js",
     "./js/dialog": "./src/js/dialog.js",
-    "./js/dialog-fallback": "./src/js/dialog-fallback.js",
+    "./js/dismiss": "./src/js/dismiss.js",
     "./js/enhance": "./src/js/enhance.js",
+    "./js/enhancement-loader": "./src/js/enhancement-loader.js",
+    "./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",
     "./js/input": "./src/js/input.js",
     "./js/keys": "./src/js/keys.js",
     "./js/mask": "./src/js/mask.js",
@@ -66,10 +70,11 @@
   "sideEffects": true,
   "files": [
     "dist",
-    "!dist/actual-themes.min.css",
-    "!dist/actual-themes.min.css.map",
-    "src/css",
-    "!src/css/themes",
+    "src/css/*.css",
+    "src/css/components",
+    "src/css/forms",
+    "src/css/optional",
+    "src/css/themes",
     "src/js",
     "docs",
     "CHANGELOG.md",
@@ -78,13 +83,16 @@
     "README.md"
   ],
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.14"
   },
   "scripts": {
     "lint": "biome check",
     "lint:fix": "biome check --write",
-    "build:demo": "bun scripts/build-demo.js",
-    "watch:demo": "bun scripts/build-demo.js --watch",
+    "build:docs": "bun scripts/build-docs.js",
+    "watch:docs": "bun scripts/build-docs.js --watch",
+    "check:docs": "bun scripts/check-docs.js",
+    "check:compat": "bun scripts/check-compat.js",
+    "check:css-api": "bun scripts/check-css-api.js",
     "build:dist": "bun scripts/build-dist.js",
     "build:js": "bun scripts/build-js.js",
     "build:size": "bun scripts/build-size.js",
@@ -94,14 +102,14 @@
     "check:templates": "bun scripts/check-templates.js",
     "shot:forced": "bun scripts/forced-colors-shot.js",
     "shot:page": "bun scripts/page-shot.js",
+    "probe": "bun scripts/probe.js",
     "check:sync": "bun scripts/check-sync.js",
     "test": "bun test",
-    "build:all": "bun run build:demo && bun run build:dist && bun run check:enhance && bun run check:reserved && bun run check:sync && bun run check:links && bun run check:templates && bun run test && bun run build:js && bun run build:size",
+    "build:all": "bun run build:dist && bun run build:js && bun run build:docs && bun run check:docs && bun run check:compat && bun run check:css-api && bun run check:enhance && 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",
-    "prismjs": "^1.30"
+    "happy-dom": "^20.11"
   }
 }

package/src/css/actual.css

@@ -1,5 +1,4 @@
 @import "./reset.css";
-@import "./dialog-fallback.css";
 @import "./tokens.css";
 @import "./theme.css";
 @import "./base.css";
@@ -15,3 +14,15 @@
 @import "./components/join.css";
 @import "./focus.css";
 @import "./print.css";
+
+/*
+ * NOTE: The 'optional/' directory contains layout and utility extensions
+ * (such as optional grids, split, visual effects, and extra utility classes
+ * like .gap-sm, .flex-nowrap, .shadow-sm, etc.). These are intentionally not
+ * bundled here. Two entry points ship them:
+ *
+ *   actual-css/css/optional/index   optional layer only
+ *   actual-css/css/actual.full      core + optional
+ *
+ * Import one of these paths in your project when you need them.
+ */

package/src/css/base.css

@@ -17,10 +17,8 @@ a {
   text-underline-offset: 0.18em;
 }
 
-@media (hover: hover) {
-  a:hover {
-    text-decoration-thickness: 0.12em;
-  }
+a:hover {
+  text-decoration-thickness: 0.12em;
 }
 
 /* Global heading chrome: color (--heading or inherit), a tight line-height,
@@ -46,7 +44,7 @@ hgroup > * {
 hr {
   border: 0;
   border-block-start: var(--border-width) solid var(--border);
-  margin-block: var(--space-6);
+  margin-block: var(--space-60);
 }
 
 code,

package/src/css/components/accordion.css

@@ -4,9 +4,14 @@
  * Keeps the clickable summary affordance aligned and usable without JavaScript
  * or demo styles. Decorative palettes and custom markers belong outside the
  * base component.
+ *
+ * Public hooks:
+ * --accordion-radius
+ * --accordion-marker-color
  */
 .accordion {
   --accordion-radius: var(--radius);
+  --accordion-marker-color: var(--text-muted);
 
   border: var(--border-width) solid var(--border);
   border-radius: var(--accordion-radius);
@@ -20,14 +25,18 @@
 .accordion summary {
   display: flex;
   align-items: center;
-  gap: var(--space-3);
+  gap: var(--space-30);
   cursor: pointer;
   list-style: none;
-  padding: var(--space-4);
+  padding: var(--space-40);
   color: var(--text);
   font-weight: var(--font-weight-bold);
 }
 
+.accordion summary:hover {
+  color: var(--primary);
+}
+
 .accordion summary::-webkit-details-marker {
   display: none;
 }
@@ -38,15 +47,9 @@
   margin-inline-start: auto;
   inline-size: 1rem;
   block-size: 1rem;
-  background-color: var(--text-muted);
-  -webkit-mask-image: var(--icon-chevron-mask);
-  mask-image: var(--icon-chevron-mask);
-  -webkit-mask-repeat: no-repeat;
-  mask-repeat: no-repeat;
-  -webkit-mask-size: contain;
-  mask-size: contain;
-  -webkit-mask-position: center;
-  mask-position: center;
+  background-color: var(--accordion-marker-color);
+  -webkit-mask: var(--icon-chevron) center / contain no-repeat;
+  mask: var(--icon-chevron) center / contain no-repeat;
   transition: transform var(--duration);
 }
 
@@ -55,14 +58,14 @@
 }
 
 .accordion details > summary + * {
-  padding-block: 0 var(--space-4);
-  padding-inline: var(--space-4);
+  padding-block: 0 var(--space-40);
+  padding-inline: var(--space-40);
   color: var(--text-muted);
   margin-block: 0;
 }
 
 .accordion details[open] > summary + * {
-  padding-block-start: var(--space-1);
+  padding-block-start: var(--space-10);
 }
 
 .accordion details > summary + * > :first-child {
@@ -77,21 +80,6 @@
 
 @media (forced-colors: active) {
   .accordion {
-    border-color: ButtonText;
-    background: Canvas;
-    color: CanvasText;
-  }
-
-  .accordion > details + details {
-    border-block-start-color: ButtonText;
-  }
-
-  .accordion summary {
-    color: CanvasText;
-  }
-
-  .accordion summary::after {
-    background-color: ButtonText;
-    forced-color-adjust: none;
+    --accordion-marker-color: CanvasText;
   }
 }

package/src/css/components/actions.css

@@ -3,9 +3,12 @@
  *
  * Composes with .btn (or any inline element) and feeds layout via the shared
  * --gap token.
+ *
+ * Internal:
+ * --gap (local value for the shared gap token)
  */
 .actions {
-  --gap: var(--space-2);
+  --gap: var(--space-20);
 
   display: flex;
   flex-wrap: wrap;