actual-css 0.3.1 → 0.4.0

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

@@ -0,0 +1,206 @@
+# Column Layout
+
+`.column-layout` is an explicit twelve-column composition canvas. Place regions
+with `.column-span-N` and `.column-start-N`.
+
+Reach for it when the placement of each region **is** the design. If the regions
+are a collection, a known density, peers that switch together, or a main region
+with an aside, one of the other primitives already says so — and says it with
+intrinsic responsive behavior this one does not have.
+
+```html demo
+<div class="column-layout">
+  <main class="column-span-8 card">Main — 8 columns</main>
+  <aside class="column-span-4 card">Aside — 4 columns</aside>
+</div>
+```
+
+Neither child names a start line, so grid auto-placement flows the aside into
+columns 9 through 12.
+
+## Spans
+
+A span declares how many of the twelve units a region occupies.
+
+```html demo
+<div class="column-layout">
+  <div class="column-span-3 card">3</div>
+  <div class="column-span-6 card">6</div>
+  <div class="column-span-3 card">3</div>
+</div>
+```
+
+A child with no placement class spans the whole canvas, so a heading can share
+the canvas with placed regions without carrying a class.
+
+```html demo
+<div class="column-layout">
+  <h3>Full canvas — no class needed</h3>
+  <div class="column-span-4 card">4</div>
+  <div class="column-span-4 card">4</div>
+  <div class="column-span-4 card">4</div>
+</div>
+```
+
+Regions that do not fit wrap to the next row, as any grid does. Two
+`.column-span-8` regions need sixteen units, so the second moves down.
+
+## Starts
+
+A start declares the line a region begins on. This replaces margin-based
+offsets and is direction-independent: line 1 is the inline start, so the
+placement flips with `dir="rtl"` on its own.
+
+```html demo
+<div class="column-layout">
+  <article class="column-span-10 column-start-2 card">
+    Columns 2 through 11
+  </article>
+</div>
+```
+
+Used without a span, a start runs to the end of the canvas.
+
+```html demo
+<div class="column-layout">
+  <aside class="column-start-9 card">Columns 9 through 12</aside>
+</div>
+```
+
+Keep a combined placement inside the canvas: `S + N - 1 <= 12`. So
+`.column-start-9 .column-span-4` is valid and `.column-start-10 .column-span-4`
+is not. Exceeding the canvas adds a thirteenth, content-sized column, and every
+other region shrinks with it — the failure is canvas-wide, not local to the
+region you got wrong.
+
+## Cross-section alignment
+
+The canvas is shared across sibling sections, so regions in different sections
+can line up on the same columns — something a collection or a sidebar cannot
+guarantee. This is the case no other primitive can replace.
+
+```html demo
+<div class="stack">
+  <div class="column-layout">
+    <h3 class="column-span-8 column-start-3">Feature title</h3>
+    <p class="muted column-span-8 column-start-3">Kicker aligned to the same line.</p>
+  </div>
+
+  <div class="column-layout">
+    <p class="column-span-8 column-start-3">
+      Body copy starts on the same column as the title above and spans the same
+      eight columns.
+    </p>
+    <aside class="column-span-2 column-start-11 card">Inline note</aside>
+  </div>
+</div>
+```
+
+Both sections name the same `column-start-3` / `column-span-8`, so their content
+shares a left edge and an alignment gutter without a wrapping grid.
+
+## The responsive contract
+
+`.column-layout` has **no automatic collapse**. The canvas stays twelve columns
+at every width, and the application owns narrow-container behavior.
+
+This is deliberate. `8 + 4` and `3 + 9` do not become unusable at the same
+width, a centered article may only need wider gutters, and a dashboard may want
+three regions to become two before stacking. A single framework threshold would
+be wrong more often than right, and a hidden one would have to be undone rather
+than extended.
+
+The simplest recomposition stacks everything:
+
+```css
+@container (width < 40rem) {
+  .profile-layout > * {
+    grid-column: 1 / -1;
+  }
+}
+```
+
+A coordinate system is more useful when you keep it through an intermediate
+state:
+
+```css
+@container (width < 48rem) {
+  .profile-main {
+    grid-column: 1 / span 6;
+  }
+
+  .profile-aside {
+    grid-column: 7 / span 6;
+  }
+}
+
+@container (width < 32rem) {
+  .profile-main,
+  .profile-aside {
+    grid-column: 1 / -1;
+  }
+}
+```
+
+```html
+<div class="container-query">
+  <div class="column-layout profile-layout">
+    <main class="column-span-8 profile-main">...</main>
+    <aside class="column-span-4 column-start-9 profile-aside">...</aside>
+  </div>
+</div>
+```
+
+The `.container-query` wrapper here enables **your** `@container` rules, not a
+hidden framework behavior. Remove your rules and the wrapper stops mattering.
+This is the opposite of a primitive whose responsive contract depends on a
+wrapper someone else has to remember.
+
+Placement classes carry zero specificity, so a single-class rule of your own
+wins without `!important` and without having to undo a framework declaration
+first.
+
+## Narrow containers
+
+Twelve columns is a wide-context tool. With the default `--gap`, a 279px
+container spends 132px on its eleven gaps and leaves about 12px per unit — a
+`.column-span-4` region is 84px wide.
+
+The framework guarantees the canvas itself never overflows its container: the
+tracks are `minmax(0, 1fr)` and every child gets `min-inline-size: 0`, so item
+boxes stay inside their tracks. It does not guarantee that content inside a
+narrow span stays readable, or that an unbreakable word will not paint outside
+its track. Define a narrow representation where the composition needs one.
+
+## Scope
+
+The primitive is horizontal only. There are no `.row-span-*`, `.area-*`, or
+`.order-*` classes, and no breakpoint variants such as `md-column-span-6` —
+those would move responsive strategy back into markup. For genuinely
+two-dimensional placement, use CSS Grid directly on your own class:
+
+```css
+.dashboard-summary {
+  grid-row: 1 / span 2;
+}
+```
+
+The column count is fixed at twelve and is not configurable. Twelve is what
+makes the vocabulary shared and lets `6 + 6`, `4 + 4 + 4`, `3 + 3 + 3 + 3`,
+`8 + 4`, and `2 + 8 + 2` all land on the same canvas. For a track system whose
+sizes carry meaning rather than twelve interchangeable units, use
+`--grid-columns` on `.grid`.
+
+Unlike `.grid-N`, the track template does not read `--gap`, so the gap
+utilities are exact here at every width.
+
+A region carrying a placement class must generate a box. `display: contents`
+removes that box and promotes its descendants to grid items, which leaves the
+placement with nothing to apply to.
+
+### Classes
+
+- `.column-layout` establishes the twelve-column canvas.
+- `.column-span-1` … `.column-span-12` set the width in canvas units.
+- `.column-start-1` … `.column-start-12` set the starting line, running to the
+  canvas end unless a span refines it.

package/docs/pages/layout/frame.md

@@ -27,4 +27,9 @@ Use local variables for common ratios.
 .avatar-preview {
   --frame-ratio: 1;
 }
-```
+```
+
+`overflow: hidden` is what makes the frame a media frame: it clips the media to
+the ratio and its corners. Floating decorations (badges, live dots, captions
+that overhang) therefore cannot live inside the frame — they are clipped too.
+Place them in a sibling or wrapper around the frame instead.

package/docs/pages/layout/grid.md

@@ -1,25 +1,26 @@
 # Grid
 
-Responsive equal-width item grids with a tunable minimum item width.
+Two contracts sit behind these classes. Pick by asking what determines the
+column count.
+
+- The **item width** is what matters — use `.grid` and tune `--grid-min`.
+- The **column density** is what matters — use `.grid-2`, `.grid-3`, `.grid-4`,
+  or `.grid-6`.
+
+## Space-driven collection
+
+`.grid` fits as many columns as the available inline space permits. Incomplete
+final rows are part of the contract.
 
 ```html demo
 <section class="grid">
-  <article class="card">
-    <h3>Starter</h3>
-    <p>For small projects.</p>
-  </article>
-  <article class="card">
-    <h3>Team</h3>
-    <p>For shared products.</p>
-  </article>
-  <article class="card">
-    <h3>Scale</h3>
-    <p>For larger systems.</p>
-  </article>
+  <article class="card"><h3>Starter</h3><p>For small projects.</p></article>
+  <article class="card"><h3>Team</h3><p>For shared products.</p></article>
+  <article class="card"><h3>Scale</h3><p>For larger systems.</p></article>
 </section>
 ```
 
-Tune the minimum item width with `--grid-min`.
+Tune the item minimum with `--grid-min`.
 
 ```css
 .pricing-grid {
@@ -27,116 +28,113 @@ Tune the minimum item width with `--grid-min`.
 }
 ```
 
-Or replace the responsive template entirely with `--grid-columns` for a
-custom or asymmetric layout. Because this overrides the intrinsic
-`auto-fit/minmax` algorithm, you own any narrow-container collapse:
+## Count-driven density
 
-```css
-.feature-grid {
-  --grid-columns: minmax(0, 2fr) minmax(0, 1fr);
-}
+`.grid-N` declares a structural density of N columns. It is responsive on its
+own: it never exceeds N columns, never overflows, and every item keeps the same
+width.
 
-@container (width < 40rem) {
-  .feature-grid {
-    --grid-columns: 1fr;
-  }
-}
+```html demo
+<div class="grid-4">
+  <div class="card">Exercitation</div>
+  <div class="card">Amet mollit</div>
+  <div class="card">Aute cillum</div>
+  <div class="card">Duis non </div>
+</div>
 ```
 
-`--grid-columns` applies to `.grid` only. The `.grid-2`, `.grid-3`,
-`.grid-4`, and `.grid-6` presets retain their fixed-column contracts.
+`--grid-min` does not apply here. Item width is `.grid`'s contract; column
+density is `.grid-N`'s. Choose the preset that suits your item size:
 
-## Fixed columns
+| Item                              | Preset               |
+|-----------------------------------|----------------------|
+| large card                        | `.grid-2`            |
+| card with a heading and a summary | `.grid-3`, `.grid-4` |
+| compact tile, stat, avatar        | `.grid-6`            |
 
-Predictable 2/3/4/6-column grids. Full count by default; wrap in `.container-query` to make the column count collapse on narrow wrappers.
+## Balanced subdivision
 
-Use `.grid-2`, `.grid-3`, `.grid-4`, and `.grid-6` when the column count matters more than the item minimum width — for example, when a row should always read as "three items side by side", or when an empty cell should not stretch to fill space. Unlike `.grid`, the columns are fixed; if you have only two items in a `.grid-3`, the third cell stays empty rather than redistributing.
+Left alone, a preset collapses one column at a time, so a six-item `.grid-6`
+can pass through five columns — five items and a lone sixth. Wrap it in
+`.container-query` and it only ever enters a **divisor of N**:
 
-A `.grid-2/3/4/6` without a wrapper is a **fixed grid** (always at its full column count); with a `.container-query` wrapper, it's a **responsive grid** (the column count collapses on narrow wrappers). The wrapper is the query container; the grid itself is a plain block grid.
+```text
+.grid-2   2 → 1
+.grid-3   3 → 1
+.grid-4   4 → 2 → 1
+.grid-6   6 → 3 → 2 → 1
+```
+
+Every state splits the collection evenly, and all items keep the same width.
 
 ```html demo
 <div class="container-query">
-  <div class="grid-3">
-    <article class="card">
-      <h3>Starter</h3>
-      <p>For small projects.</p>
-    </article>
-    <article class="card">
-      <h3>Team</h3>
-      <p>For shared products.</p>
-    </article>
-    <article class="card">
-      <h3>Scale</h3>
-      <p>For larger systems.</p>
-    </article>
+  <div class="grid-6">
+    <div class="card">1</div>
+    <div class="card">2</div>
+    <div class="card">3</div>
+    <div class="card">4</div>
+    <div class="card">5</div>
+    <div class="card">6</div>
   </div>
 </div>
 ```
 
-A `grid-4` demo:
+The wrapper is an opt-in for precision, never a prerequisite for responsive
+behavior — forgetting it costs you the exact chain, nothing else. It has to be
+an ancestor: an element cannot query its own size without taking inline-size
+containment, which would collapse the grid inside a `.cluster`, a float, or any
+shrink-to-fit box. Put `.container-query` on a normal block-level wrapper for
+the same reason.
 
-```html demo
+The chain balances the **declared density**, not your actual item count. Eight
+items in `.grid-6` still give `6 + 2`. For a paginated collection, choose a page
+size that suits the density — 12, 20, and 24 divide well. A partial final page
+is normal.
+
+## Exact templates
+
+`--grid-columns` replaces `.grid`'s intrinsic recipe. Use it for exact track
+templates that do not match a built-in layout contract: arbitrary structural
+counts such as seven calendar days, asymmetric fractional tracks, or mixed
+intrinsic/flexible tracks. Once set, the application owns narrow-container
+behavior.
+
+```css
+/* Semantic count not represented by .grid-N */
+--grid-columns: repeat(7, minmax(0, 1fr));
+
+/* Meaningful asymmetric ratio */
+--grid-columns: 2fr 1fr 1fr 1fr;
+
+/* Intrinsic trailing control */
+--grid-columns: repeat(4, minmax(0, 1fr)) auto;
+```
+
+```html
 <div class="container-query">
-  <div class="grid-4">
-    <article class="card">
-      <h3>Starter</h3>
-      <p>For small projects.</p>
-    </article>
-    <article class="card">
-      <h3>Team</h3>
-      <p>For shared products.</p>
-    </article>
-    <article class="card">
-      <h3>Scale</h3>
-      <p>For larger systems.</p>
-    </article>
-    <article class="card">
-      <h3>Enterprise</h3>
-      <p>Contact us.</p>
-    </article>
-  </div>
+  <div class="editorial-grid grid">...</div>
 </div>
 ```
 
-A `grid-6` demo for compact items:
+```css
+.editorial-grid {
+  --grid-columns: minmax(0, 2fr) minmax(0, 1fr);
+}
 
-```html demo
-<div class="container-query">
-  <div class="grid-6">
-    <article class="card compact">
-      <span class="muted">Open</span>
-      <strong>18</strong>
-    </article>
-    <article class="card compact">
-      <span class="muted">Queued</span>
-      <strong>7</strong>
-    </article>
-    <article class="card compact">
-      <span class="muted">Blocked</span>
-      <strong>2</strong>
-    </article>
-    <article class="card compact">
-      <span class="muted">Shipped</span>
-      <strong>41</strong>
-    </article>
-    <article class="card compact">
-      <span class="muted">Owners</span>
-      <strong>6</strong>
-    </article>
-    <article class="card compact">
-      <span class="muted">SLA</span>
-      <strong>99%</strong>
-    </article>
-  </div>
-</div>
+@container (width < 40rem) {
+  .editorial-grid {
+    --grid-columns: 1fr;
+  }
+}
 ```
 
-## Behavior
+For an ordinary main region plus an aside, prefer `.sidebar-layout`. When a
+small group of peer regions must be either entirely horizontal or entirely
+stacked, prefer `.switcher`.
 
-- Without `.container-query`: `.grid-2` is always 2 cols, `.grid-3` is always 3 cols, `.grid-4` is always 4 cols, and `.grid-6` is always 6 cols.
-- With `.container-query`: `.grid-2`, `.grid-3`, and `.grid-4` collapse to one column on a narrow wrapper (under 28rem). `.grid-3` and `.grid-4` step through 2 columns between 28rem and 48rem. `.grid-6` starts at 2 columns under 28rem, steps through 3 columns between 28rem and 64rem, then returns to 6 columns.
-- The intermediate 2-col step is useful for lists of items divisible by both 2 and 3 (or 4) — a 12-item list reads as 12 lines, then 6 lines of 2, then 4 lines of 3 (or 3 lines of 4), depending on the grid.
-- `.grid-6` is for compact items such as stats, shortcut tiles, swatches, avatar summaries, and small settings cards. It does not collapse to one column by default. If item width matters more than an exact six-column rhythm, prefer `.grid` with a smaller `--grid-min`.
-- The wrapper is the query container, so the same class behaves differently in a narrow sidebar than in a wide main area. No viewport breakpoints are involved.
+### Hooks
 
-Do not add `.row`, `.col-6`, `.offset-2`, or other fixed grid-system classes unless the project later proves it needs a formal grid system.
+- `--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.

package/docs/pages/layout/list.md

@@ -38,4 +38,4 @@ Use `.list-reset` only when markers are not part of the content. Combine `.stack
 </figure>
 ```
 
-Keep semantic lists unstyled when the markers carry meaning.
+Keep semantic lists unstyled when the markers carry meaning.

package/docs/pages/layout/media.md

@@ -25,4 +25,4 @@ Add `.items-center` to align the leading element with short trailing content. Fo
 </div>
 ```
 
-The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule.
+The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule.

package/docs/pages/layout/overview.md

@@ -1,6 +1,6 @@
 # Layout Overview
 
-Layout provides a small set of composable building blocks for common page, app, and content structure. It is not a utility-first framework and it is not a twelve-column grid system.
+Layout provides a small set of composable building blocks for common page, app, and content structure. It is not a utility-first framework, and the twelve-column canvas it does ship (`.column-layout`) is an opt-in vocabulary for deliberate composition rather than the default way to build a page.
 
 - Layout classes compose components; components do not own page spacing.
 - Use custom properties to tune a layout instance.
@@ -8,6 +8,19 @@ Layout provides a small set of composable building blocks for common page, app,
 - Keep class names semantic enough to remember and generic enough to reuse.
 - Add a new layout primitive only when a pattern appears often and is awkward to express with existing primitives.
 
+See [Choosing a layout](./choosing.md) for the distinctions between responsive
+collections, fixed structural grids, all-or-nothing peer regions, sidebars, and
+explicit column placement.
+
+## Child contract
+
+Layout primitives operate on the boxes generated by their direct children.
+Applying `display: contents` to a participating child removes that box and
+promotes its descendants into the parent layout, bypassing the sizing or
+placement assigned to the child. The layout contracts below are expressed
+against direct children — keep those children as real boxes unless you intend
+that bypass.
+
 ## Spacing tokens
 
 Layout shares the global spacing surface and exposes a small set of gap and rhythm tokens.
@@ -34,4 +47,4 @@ Most layout primitives read `--gap` and allow local overrides.
 
 Prefer a local custom property over adding many one-off utility classes. Use inline styles only for demos, prototypes, or truly dynamic values.
 
-There are no `.gap-sm` / `.gap-md` / `.gap-lg` density variants on the core layout primitives; set `--gap` locally when only spacing should change. The optional `utilities-extra.css` layer ships those gap utilities for row/column containers.
+There are no `.gap-sm` / `.gap-md` / `.gap-lg` density variants on the core layout primitives; set `--gap` locally when only spacing should change. The extra utilities (`src/css/utilities/extra.css`) ship those gap utilities for row/column containers.

package/docs/pages/layout/scroll-snap.md

@@ -2,7 +2,7 @@
 
 Horizontal rails that stay useful without JavaScript and snap in modern browsers.
 
-> **Optional** — import `actual-css/css/optional/scroll-snap` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/layout/scroll-snap` or `actual-css/css/layout`.
 
 Use `.scroll-snap` for a niche row of items that should scroll horizontally, such as card rails, media strips, overflow tabs, or a simple touch-friendly carousel baseline. Scrolling only appears when the items are wider than the container; set `--scroll-snap-item-size` for card rails.
 
@@ -51,4 +51,4 @@ Keep scrollbars visible by default. If a product deliberately hides them, make t
 </div>
 ```
 
-`.scroll-snap` is not a full interactive carousel. For previous/next controls, pagination, active state, mouse drag, looping, autoplay, or robust accessibility behavior, use a dedicated carousel library such as Swiper and compose it with Actual components.
+`.scroll-snap` is not a full interactive carousel. For previous/next controls, pagination, active state, mouse drag, looping, autoplay, or robust accessibility behavior, use a dedicated carousel library such as Swiper and compose it with Actual components.

package/docs/pages/layout/scroll-target.md

@@ -0,0 +1,45 @@
+# Scroll Target
+
+Anchor scroll offset: keep `#hash` and `scrollIntoView()` targets clear of sticky headers.
+
+> **Module** — import `actual-css/css/layout/scroll-target` or `actual-css/css/layout`.
+
+A hash link or scripted scroll places the target flush at the scroll container's start edge. Under a sticky header such as `.topbar`, the heading you jumped to lands underneath it. Add `.scroll-target` to the elements that are link targets — sections, headings — and the browser stops early, reserving space above them.
+
+```html demo
+<nav class="cluster" aria-label="Sections" style="margin-block-end: var(--space-30)">
+  <a class="btn neutral sm" href="#st-alpha">Alpha</a>
+  <a class="btn neutral sm" href="#st-beta">Beta</a>
+  <a class="btn neutral sm" href="#st-gamma">Gamma</a>
+</nav>
+<div class="overflow-auto" style="block-size: 10rem; border: var(--border-width) solid var(--border); border-radius: var(--radius)">
+  <section id="st-alpha" class="scroll-target" style="padding: var(--space-30)">
+    <h3>Alpha</h3>
+    <p>The first section. Followed by enough content to make the container scroll.</p>
+  </section>
+  <section id="st-beta" class="scroll-target" style="padding: var(--space-30)">
+    <h3>Beta</h3>
+    <p>The second section. Its top edge stops below the container edge.</p>
+  </section>
+  <section id="st-gamma" class="scroll-target" style="padding: var(--space-30)">
+    <h3>Gamma</h3>
+    <p>The last section.</p>
+  </section>
+</div>
+```
+
+The offset is a plain `scroll-margin-block-start`, so it works in every scroll container — the viewport, a sidebar, an overflow region — and composes with the scrollspy enhancer. Scrollspy only decides which link is active; this offset decides where the page actually lands when the link is followed.
+
+## CSS hooks
+
+- `--scroll-target-offset` — space kept above the target after scrolling. Set it
+  once on `:root` (or on the sticky header's height) in applications with a
+  fixed header:
+
+```css
+:root {
+  --scroll-target-offset: 5rem;
+}
+```
+
+Deliberately no `[id]` global rule: making the offset explicit per target keeps plain ids (modals, form fields, skip links) untouched.

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

@@ -1,27 +1,28 @@
 # Sidebar Layout
 
-Two-column layout where one side has a preferred width and the other takes the remaining space.
-
-Use `.sidebar-layout` for two-column layouts where the aside should align to the top of the content, stay sticky, or keep a predictable declared width.
-
-Wrap it in `.container-query` to make the switch depend on the container width. Below 64rem the columns stack; at and above it the aside takes `--sidebar-layout-size` and the content takes the remaining space. Older browsers use the viewport fallback.
+Use `.sidebar-layout` for a main region followed by a secondary region. It
+switches intrinsically according to its own available width: the regions sit
+side by side when the main minimum, preferred aside width, and gap fit; they
+otherwise stack. No `.container-query` ancestor is required.
 
 ```html demo
-<div class="container-query">
-  <div class="sidebar-layout" style="--sidebar-layout-size: 18rem">
-    <article class="stack">
-      <h1>Long-form article</h1>
-      <p>Article body that benefits from a sticky table of contents.</p>
-    </article>
+<div class="sidebar-layout">
+  <article class="stack">
+    <h1>Long-form article</h1>
+    <p>Article body that benefits from a related table of contents.</p>
+  </article>
 
-    <aside class="stack">
-      <h3>On this page</h3>
-      <ol class="list-reset">
-        <li><a class="link-muted" href="#">Section</a></li>
-      </ol>
-    </aside>
-  </div>
+  <aside class="stack">
+    <h3>On this page</h3>
+    <ol class="list-reset"><li><a class="link-muted" href="#">Section</a></li></ol>
+  </aside>
 </div>
 ```
 
-Tune the side width with `--sidebar-layout-size`.
+The first child is the flexible main region and the last child is the aside.
+Use a custom `.grid` template only when an exact editorial ratio is structural.
+
+### Hooks
+
+- `--sidebar-layout-size` sets the aside's preferred width.
+- `--sidebar-content-min` sets the main region's minimum viable width.