actual-css 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,8 +1,114 @@
-# Changelog
+# Actual CSS Changelog
 
-All notable changes will be documented here.
+## [Unreleased]
+
+
+## [0.4.1] - 2026-08-25
+
+### Added
+
+* `indicator`, `rating`, and intrinsically responsive `steps` components.
+* `list` / `list-item` for repeated application rows with leading, content, and trailing regions.
+* `app-nav` and `app-layout` primitives for adaptive application shells.
+* `.sidebar-layout.reverse` to place the sidebar visually first while keeping main-content-first DOM order.
+* `icon-slot` documented pattern for predictable contained icon regions.
+* `check:doc-classes` guardrail for validating framework classes used in documentation.
+* New **Actual Tasks** mobile/application demo.
+* `docs-geometry` guardrail asserting the documentation shell can reach the structural-grid thresholds, read from `grid.css` rather than hard-coded.
+* `--width` on `shot:page` for captures at an exact layout viewport; the flag was previously accepted and silently ignored.
+
+### Changed
+
+* Improved card and prose vertical rhythm:
+  * bare cards now own direct-child spacing through `--card-gap`;
+  * direct child block margins are normalized;
+  * `.stack` and `.media` keep ownership when composed with `.card`;
+  * prose sibling rhythm is more deterministic.
+* `steps` now use one intrinsic responsive layout, filling available space and scrolling only when `--step-min` cannot be maintained.
+* Added `--step-marker-radius`, `--step-connector`, and `--step-complete-mark` customization hooks.
+* Improved `app-layout` / `app-nav` composition with framework-owned safe-area handling and automatic FAB/navigation avoidance.
+* Clarified that `app-layout` targets persistent application shells rather than regular document pages.
+* Simplified forced-colors support: native/system colors are preferred, with framework overrides limited to structural states that would otherwise disappear.
+* Expanded documentation around lists, application layouts, icon containment, and framework-vs-application CSS ownership.
+* Documented reference container sizes for `.grid-N`, including that the thresholds describe the query container's content box rather than the viewport.
+* Recorded why the framework exposes no global breakpoint scale: container width is not a monotonic function of viewport width, measured across a composition that reveals a sidebar as the viewport grows.
+
+### Fixed
+
+* Tooltip cleanup now follows enhancement-root membership correctly, including triggers moved outside the observed root while still connected.
+* Documentation home-page overflow and minimum-size issues.
+* Documentation demo previews could not reach the structural-grid thresholds. The article column capped every live preview at 45.9rem at any viewport width, so `.grid-3` demos rendered one column and `.grid-4` / `.grid-6` two — including on the page documenting `6 -> 3 -> 2 -> 1`. No framework CSS was involved or changed.
+* Invalid or misleading documentation class examples.
+* Steps sizing and narrow-container behavior.
+
+
+## [0.4.0] - 2026-08-22
+
+### Added
+
+* Modular CSS architecture with `core`, `layout`, `typography`, `forms`, `components`, `effects`, and `utilities` families, with family and individual-module imports.
+* `actual-css/full` / `actual.full.*` bundles for the complete CSS and JS framework.
+* `.column-layout` with `column-span-1…12` and `column-start-1…12` for explicit opt-in 12-column composition.
+* Intrinsic `.switcher` and `.sidebar-layout` layout recipes, plus explicit layout-selection guidance.
+* `.scroll-target` with `--scroll-target-offset` for hash links and `scrollIntoView()` below sticky UI.
+* Dedicated `typography/lead.css` and `layout/measure.css`; `.measure` exposes `--measure`.
+* Generated and published `reserved-classes.json` for the framework-owned class namespace.
+* Native `accent-color` theming for unstyled platform controls, recomputed across `[data-theme]` islands.
+* “Building with Actual CSS” integration guide covering theme tokens, layout selection, hooks, utilities, and application CSS.
+* Expanded build, architecture, compatibility, browser-layout, package, and generated-output guardrails, including real `npm pack` verification.
+* `brutalist` theme.
+* `--soft-fg-mix` for tuning soft foreground ink.
+* Optional `--link` override for prose link ink.
+* `check:color-space` guardrail for intent/context color interpolation.
+* Bundle tool.
+
+### Changed
+
+* The bare `actual-css` entrypoint is now the minimal core; use `actual-css/full` for all CSS families.
+* `actual-css/js` is now the enhancement loader only; use `actual-css/js/full` or `actual.full.js` for the complete pre-registered runtime.
+* `.grid` remains space-driven through `--grid-min`; `.grid-2/3/4/6` now express bounded structural density and degrade responsively.
+* `.container-query` optionally gives `.grid-N` balanced divisor-based subdivisions.
+* `--grid-columns` is the explicit escape hatch for exact custom tracks.
+* `.sidebar-layout` now uses intrinsic flex wrapping instead of a hidden breakpoint contract.
+* Grid primitives preserve overflow-safe track sizing.
+* `.card` is now a column flex container and direct footers can anchor to the bottom.
+* Focus is now a core invariant.
+* Focus rings follow each theme island's `--focus`.
+* `.prose` adds native description-list styling.
+* `.lead` and `.measure` are independent from `.prose`.
+* Utilities are split between compact framework shortcuts and optional property/value helpers.
+* Preset theme palettes are reference/demo material rather than package API.
+* `llms.txt` documents package splits, layout selection, the class manifest, and application-CSS integration.
+* Biome covers `src/`, `scripts/`, and `tests/`.
+* Intent/context color mixes use OKLab.
+* Documentation syntax highlighting uses its own local palette.
+* CI and browser diagnostics were updated for Bun 1.4 and verify committed generated output.
+
+### Fixed
+
+* Forced-colors and theme-island focus/state handling.
+* Grid child min-content overflow.
+* Drawer RTL behavior.
+* Badge typography token usage.
+* `.sr-only` legacy fallback.
+* `dim` and `indigo` shadows.
+* Vendor pseudo-element handling for color inputs and meters.
+* Tooltip Escape handling and LIFO dismissal.
+* OTP, switch, joined-control, floating-field, validation, and native color-control edge cases.
+* Flyout lifecycle cleanup.
+* Prose spacing and component focus regressions.
+* Compatibility checks matching feature names in CSS comments.
+* Navbar and status-bar guidance.
+
+### Breaking
+
+* `actual-css` now contains only the core. Use `actual-css/full` for the previous full-framework behavior.
+* `actual-css/js` / `actual.js` now contain only the enhancement loader. Use `actual-css/js/full` / `actual.full.js` for the previous complete runtime.
+* `.grid-N` no longer means a fixed N-column grid at every width.
+* `.sidebar-layout` no longer depends on `.container-query` or the old fixed breakpoint.
+* `.card` now establishes a column flex formatting context.
+* Direct imports of `typography/prose` no longer include `.lead` or `.measure`.
 
-This project follows Keep a Changelog and uses semver, including during 0.x.
 
 ## [0.3.1] - 2026-08-20
 

package/README.md

@@ -2,9 +2,11 @@
 
 Plain CSS component framework for new projects. Semantic classes, shared variants, small tokens, theme hooks, and progressive enhancement.
 
-Actual CSS claims a small set (see `reserved-classes.json`) of global class names. 
+Actual CSS claims a documented set of global class names; the package publishes
+it as [`actual-css/reserved-classes.json`](scripts/reserved-classes.json).
 
-For existing projects: cascade layers, import order, or an optional prefix transform.
+For existing projects: use cascade layers, import order, or your own build-time
+prefix transform.
 
 ## Install
 
@@ -15,38 +17,39 @@ npm install actual-css
 Import the full framework in your CSS:
 
 ```css
-@import "actual-css";
+@import "actual-css/full";
 ```
 
+`actual-css/full` ships every functional family. The bare `actual-css` entrypoint is the minimal core (reset, tokens, theme, base, intents, variants, focus, print).
+
 Or import only the pieces you use:
 
 ```css
-@import "actual-css/css/reset";
-@import "actual-css/css/base";
-@import "actual-css/css/tokens";
-@import "actual-css/css/theme";
-@import "actual-css/css/intents";
-@import "actual-css/css/variants";
+@import "actual-css/css";
 @import "actual-css/css/layout";
-@import "actual-css/css/grid";
 @import "actual-css/css/components/button";
 @import "actual-css/css/components/card";
 @import "actual-css/css/forms";
 @import "actual-css/css/components/flyout";
 @import "actual-css/css/utilities";
-@import "actual-css/css/components/join";
-/* Keep the focus baseline after components and controls. */
-@import "actual-css/css/focus";
 ```
 
-`focus` is the final interactive baseline in modular builds: older browsers
-retain a visible `:focus` outline, while browsers with `:focus-visible` avoid
-showing it for pointer focus.
+`actual-css/css` is the minimal core. Family manifests (`css/layout`,
+`css/components`, `css/typography`, `css/effects`, `css/utilities`) and
+their modules map one-to-one to `src/css/`; `css/forms` is the exception —
+it points at the native-controls base, with `css/forms/all` exposing the
+complete Forms family. See the
+[modular import guide](docs/pages/guides/modular-import.md) for the full map.
+
+For a flattened custom bundle, import the source entrypoints you want from
+`actual-css/css` and run `npx actual-css bundle src/app.css --out public/app.css --minify`.
+The CLI resolves package subpaths and relative files, then inlines them without
+transpiling modern CSS.
 
-You can also use the compiled file directly:
+You can also use the compiled full bundle directly:
 
 ```html
-<link rel="stylesheet" href="actual.min.css">
+<link rel="stylesheet" href="actual.full.min.css">
 ```
 
 ## Usage
@@ -96,14 +99,14 @@ Undocumented `is-*` classes are runtime internals.
 
 **Theme hooks** — public tokens for color, radius, shadow, motion, and typography. Reference presets in `src/css/themes/` are demo material, not default CSS or public package entrypoints.
 
-## Optional CSS
-
-```css
-@import "actual-css/css/layer";
-@import "actual-css/css/optional/index";
-```
+## Modular CSS
 
-Browse [`src/css/optional/`](src/css/optional/) for available modules such as custom scrollbars, scroll snap rails, extra utilities, and optional layout helpers.
+The family manifests are the module catalog: `core`, `layout`, `typography`,
+`forms`, `components`, `effects`, and `utilities` under `src/css/`, each with
+an `index.css` manifest and per-module files. Import a manifest to get the
+family, or a single file for one module. See the
+[modular import guide](docs/pages/guides/modular-import.md) for the full map
+of module names to import paths.
 
 ## JavaScript enhancers
 
@@ -114,7 +117,7 @@ Presentation (`class`) and behaviour (`data-enhance`) are separate layers — im
 Use the full module:
 
 ```html
-<script src="actual.js" type="module"></script>
+<script src="actual.full.js" type="module"></script>
 ```
 
 Or import only the enhancers you need:
@@ -127,18 +130,20 @@ import "actual-css/js/mask";
 import "actual-css/js/tooltip";
 ```
 
-The package does not maintain separate partial bundles. Modular entrypoints map to source files, so each project can compose the framework shape it needs. To customize the full runtime, comment the imports you do not want in `src/js/index.js` and rebuild the JavaScript bundle. JavaScript modules are safe to import during server-side rendering; outside a browser, registration is a no-op.
+The package does not maintain separate partial bundles. Modular entrypoints map to source files, so each project can compose the framework shape it needs. To customize the full runtime, comment the imports you do not want in `src/js/full.js` and rebuild the JavaScript bundle. JavaScript modules are safe to import during server-side rendering; outside a browser, registration is a no-op.
 
 For project-specific behavior, use `actual-css/js/enhance` and the small input helpers rather than patching built-in modules. See [Progressive Enhancements](docs/pages/enhancements/overview.md) for custom filters, textarea autogrow, ajax forms, and htmx-like patterns.
 
 ## Distribution
 
-* `dist/actual.css` — readable modern CSS.
-* `dist/actual.min.css` — the same CSS, minified for production.
+* `dist/actual.css` — readable core CSS.
+* `dist/actual.min.css` — the core, minified for production.
+* `dist/actual.full.css` — readable full-bundle CSS (every family).
+* `dist/actual.full.min.css` — the full bundle, minified for production.
 
 Modern syntax such as `light-dark()`, `color-mix()`, `@container`, `:has()`, `100dvh`, and `100vi` is preserved in the distributed files.
 
-Actual CSS does not currently ship a separate compatibility build. It is designed as progressive enhancement: modern features are guarded with `@supports` where needed, while older browsers still receive core layout, forms, and components.
+Actual CSS does not currently ship a separate compatibility build. It is designed as progressive enhancement: modern features are guarded with `@supports` where needed, while older browsers still receive the core styles and the layout, forms, and components.
 
 For more conservative fallbacks, import and compose the source entrypoints directly.