actual-css 0.3.1 → 0.4.0

package/docs/design-notes/grid.md

@@ -0,0 +1,612 @@
+# Grid Responsiveness and Balanced Subdivision
+
+## Status
+
+Design note for Actual CSS 0.4.
+
+This document explains the intended behavior of `.grid` and `.grid-N`, the alternatives considered, and the CSS constraints that prevent a single mechanism from satisfying every use case.
+
+The goal is to preserve these decisions so future changes do not accidentally reintroduce previously rejected approaches.
+
+## Problem
+
+Actual CSS exposes two related but distinct grid use cases:
+
+* a free collection that should adapt naturally to available space;
+* a structured collection where a known column density should collapse through visually balanced subdivisions.
+
+These goals are not equivalent.
+
+A generic intrinsic grid can efficiently fill available space, but it does not know whether the resulting number of columns produces a balanced distribution for the number of items.
+
+Conversely, a structurally balanced grid can preserve predictable subdivisions, but CSS cannot make it fully autonomous without introducing other layout constraints.
+
+The distinction matters most when resizing a collection.
+
+For six items, a purely space-driven grid may naturally move through:
+
+```text
+6 → 5 → 4 → 3 → 2 → 1
+```
+
+This maximizes use of available space, but produces layouts such as:
+
+```text
+5 + 1
+4 + 2
+```
+
+Actual's structural grid use case instead prefers:
+
+```text
+6 → 3 → 2 → 1
+```
+
+Every state is a natural subdivision of six and every item has the same width.
+
+## Core principle
+
+Actual distinguishes **space-driven grids** from **count-driven grids**.
+
+### `.grid`: space-driven collection
+
+`.grid` is an intrinsic responsive collection.
+
+Its behavior is driven by:
+
+* the width of its containing block;
+* `--grid-min`;
+* the number of tracks that can fit.
+
+A typical implementation uses `auto-fit`.
+
+The browser is free to choose any number of columns that satisfies the minimum item width.
+
+No guarantee is made about balanced final rows.
+
+Conceptually:
+
+```text
+available space
+      ↓
+how many items fit?
+      ↓
+auto-fit
+```
+
+This is appropriate for collections where filling available space is more important than preserving a particular structural rhythm.
+
+### `.grid-N`: count-driven structural grid
+
+`.grid-2`, `.grid-3`, `.grid-4`, and `.grid-6` express a preferred structural density.
+
+Their responsive progression should favor natural divisors of that density.
+
+The intended chains are:
+
+```text
+.grid-2   2 → 1
+.grid-3   3 → 1
+.grid-4   4 → 2 → 1
+.grid-6   6 → 3 → 2 → 1
+```
+
+This deliberately skips intermediate column counts that would create visibly uneven subdivisions.
+
+For example, `.grid-6` should not pass through five or four columns simply because five or four tracks happen to fit.
+
+The defining property of `.grid-N` is therefore not merely:
+
+> at most N columns
+
+It is:
+
+> a structural density of N columns that collapses through balanced subdivisions of N.
+
+## Equal-width items are an invariant
+
+Actual does not attempt to repair an incomplete row by stretching individual items, changing their span independently, or making the last card wider than its peers.
+
+At every responsive state, all direct items in a structural grid should have the same width.
+
+Layouts such as this are intentionally avoided:
+
+```text
+[A][B][C]
+[   D   ][E]
+```
+
+The grid may contain an incomplete final row when its item count is incompatible with the selected density, but the items themselves remain regular.
+
+Visual consistency of the grid is more important than artificially filling every pixel.
+
+## Item count and structural density are different inputs
+
+A structural density does not imply that CSS knows the actual number of items.
+
+For example, `.grid-6` describes the sequence:
+
+```text
+6 → 3 → 2 → 1
+```
+
+but it does not guarantee a balanced final row for an arbitrary number of children.
+
+With eight items, six columns still produce:
+
+```text
+6 + 2
+```
+
+and three columns produce:
+
+```text
+3 + 3 + 2
+```
+
+CSS is not inferring the child count and selecting an optimal divisor of that count.
+
+The contract is narrower:
+
+> `.grid-N` provides balanced subdivisions of the declared structural density N.
+
+This works particularly well when collection sizes are naturally compatible with that density.
+
+For paginated collections, the server knows the page size and should choose a page size that works well with the expected presentation densities.
+
+A partial final page is normal. CSS should not contain pagination heuristics intended to disguise a poor full-page item count.
+
+## Why `auto-fit` alone is insufficient
+
+`auto-fit` answers a spatial question:
+
+> How many tracks of this minimum size fit in the available width?
+
+It does not answer:
+
+> Which number of tracks produces the most balanced subdivision?
+
+For six items, if five columns fit, `auto-fit` may use five columns.
+
+That behavior is correct for an intrinsic collection and incorrect for the structural-grid contract.
+
+Therefore `.grid-N` cannot simply be implemented as `.grid` with a maximum column count if balanced subdivision remains a goal.
+
+## Why `auto-fill` does not solve subdivision
+
+`auto-fill` differs from `auto-fit` mainly in its treatment of empty tracks.
+
+This matters when fewer items exist than the available grid capacity.
+
+For example, with a four-column capacity and three items:
+
+```text
+auto-fit
+[A      ][B      ][C      ]
+
+auto-fill
+[A][B][C][ ]
+```
+
+`auto-fill` can therefore preserve card width on a partial final page instead of expanding the remaining items.
+
+That is useful behavior for catalogue-like layouts.
+
+However, it does not solve the subdivision problem.
+
+With six items and enough room for four columns, both mechanisms can still produce:
+
+```text
+[A][B][C][D]
+[E][F]
+```
+
+Neither `auto-fit` nor `auto-fill` understands that three columns would form the more balanced `3 + 3` subdivision.
+
+`auto-fill` is therefore not a replacement for the `.grid-N` responsive model.
+
+## Historical implementation in 0.3.1
+
+Actual CSS 0.3.1 already distinguished intrinsic grids from structural grids.
+
+The structural presets changed their column count using container queries.
+
+This allowed responsive behavior to depend on the size of the grid's local layout context rather than on the viewport.
+
+The important architectural property was:
+
+```text
+query container
+      ↓
+.grid-N
+```
+
+The grid itself remained an ordinary grid item and therefore retained its normal intrinsic sizing behavior.
+
+The main drawback was ergonomic: responsive structural grids depended on an explicit ancestor establishing the query container.
+
+The requirement looked like an implementation detail in markup, which motivated attempts to make `.grid-N` autonomous in 0.4.
+
+The behavior was worth preserving; the mechanism was the part under investigation.
+
+## Demoted, not rejected: bounded intrinsic grids
+
+One proposed 0.4 design implemented `.grid-N` as an intrinsic `auto-fit` or
+`auto-fill` grid capped at N columns.
+
+This removed breakpoints and container-query requirements.
+
+It cannot be the whole answer, because it optimizes for available space:
+
+```text
+6 -> 5 -> 4 -> 3 -> 2 -> 1
+```
+
+where a structural grid is expected to optimize for subdivision:
+
+```text
+6 -> 3 -> 2 -> 1
+```
+
+The mechanism therefore answers a different question than the one `.grid-N`
+asks.
+
+It is nevertheless the right **baseline**. Bounded at N, using `auto-fill`, it
+is responsive, overflow-safe, and equal-width at every state, and it needs
+nothing above Actual's Minimal floor. Adopting it as the unenhanced behavior of
+`.grid-N` is what makes the query container an opt-in for precision rather than
+a prerequisite for responsiveness. This is the single most important difference
+from 0.3.1, where a preset used without a wrapper stayed frozen at N columns
+and was a genuine trap.
+
+## Rejected approach: `smart-grid` item-count heuristics
+
+Another direction attempted to choose intermediate column counts that avoided orphan rows.
+
+For a collection containing `itemCount` items and `c` columns, a one-item final row appears when:
+
+```text
+itemCount mod c = 1
+```
+
+This observation is useful, but it is not a suitable basis for a generic grid class.
+
+The undesirable column counts depend on the actual number of items, not only on the declared grid density.
+
+A fixed `.grid-4` class cannot know whether three columns are desirable:
+
+* for ten items, three columns produces `3 + 3 + 3 + 1`;
+* for twelve items, three columns produces a perfect `3 + 3 + 3 + 3`.
+
+Hard-coding `.grid-4` to skip three columns would encode the answer for one item count and penalize another.
+
+More importantly, avoiding a singleton is weaker than balanced subdivision.
+
+For six items, four columns gives `4 + 2`. There is no singleton, but `3 + 3` is still structurally preferable.
+
+Actual therefore does not attempt to infer an optimal layout from item count in CSS.
+
+## Rejected approach: make `.grid-N` its own query container
+
+A promising prototype used:
+
+```css
+.grid-N {
+  container-type: inline-size;
+}
+```
+
+and kept a fixed internal track count.
+
+Instead of changing `grid-template-columns` on the container, container queries changed `grid-column: span ...` on its children.
+
+For a six-track grid:
+
+```text
+span 1 → 6 columns
+span 2 → 3 columns
+span 3 → 2 columns
+span 6 → 1 column
+```
+
+This successfully produced:
+
+```text
+6 → 3 → 2 → 1
+```
+
+without requiring an external query-container wrapper.
+
+It also guaranteed equal-width items.
+
+Technically, the mechanism is valid: descendants can query the dimensions of their ancestor query container.
+
+However, the solution has a serious side effect.
+
+### Inline-size containment changes intrinsic sizing
+
+`container-type: inline-size` introduces inline-size containment.
+
+The contents of the grid no longer contribute normally to the grid's intrinsic inline size.
+
+Probes showed the following behavior:
+
+| Context                         | Observed grid width |
+| ------------------------------- | ------------------: |
+| normal block                    |              1192px |
+| parent grid `auto` track        |               992px |
+| parent grid `min-content` track |                48px |
+| flex item with `flex: 0 1 auto` |                48px |
+| `width: fit-content`            |                48px |
+| float                           |                48px |
+| inline-block                    |                 0px |
+
+The self-container therefore works when the grid already receives a definite or stretched width, but can collapse almost completely in shrink-to-fit or intrinsic-sizing contexts.
+
+This is not merely an artificial CSS edge case.
+
+Actual's own composition primitives can create such contexts.
+
+For example:
+
+```html
+<div class="cluster">
+  <div class="grid-4">...</div>
+</div>
+```
+
+`.cluster` is a wrapping flex row whose children retain normal `flex: 0 1 auto` sizing.
+
+A self-contained `.grid-4` can therefore exhibit exactly the collapse observed in the probe.
+
+Similar intrinsic-sizing concerns exist when a structural grid participates in auto-sized tracks or other shrink-to-fit compositions.
+
+### Why this approach is rejected
+
+Making `.grid-N` its own query container removes an explicit wrapper at the cost of changing the fundamental sizing behavior of the primitive.
+
+That trade-off is not acceptable for a composable layout library.
+
+Attempts to compensate with `contain-intrinsic-size`, special rules for `.cluster`, or other context-specific fixes would add complexity and create coupling between otherwise independent primitives.
+
+The self-container approach is therefore rejected.
+
+## Why an external query container is not merely a workaround
+
+A size container query cannot make an element react to its own size without applying containment to that element.
+
+Placing the query container on an ancestor preserves the intrinsic sizing behavior of `.grid-N` while still allowing the grid to react to local available space.
+
+The relationship is:
+
+```text
+.container-query
+        ↓ observes local available width
+.grid-N
+        ↓ changes structural subdivision
+items
+```
+
+The extra ancestor is therefore not accidental ceremony.
+
+It represents a real boundary imposed by the CSS containment model.
+
+Actual should not hide that boundary if hiding it requires changing the sizing semantics of the grid.
+
+## Out of scope: explicit per-region placement
+
+Editorial or application layouts that need arbitrary per-region spans and starts
+are outside the `.grid` / `.grid-N` collection contract. Both primitives lay out
+uniform peers; neither expresses "this region occupies seven units starting at
+the third".
+
+That case is answered by `.column-layout`, an opt-in twelve-column coordinate
+system with no automatic responsive behavior. See `column-layout.md`. It also
+narrows `--grid-columns` to its intended role: track templates whose sizes carry
+meaning, rather than a stand-in for a coordinate system.
+
+## Progressive enhancement
+
+Container queries are newer than Actual's Minimal browser baseline.
+
+Structural grids must therefore have a usable fallback without them.
+
+The fallback should remain structurally valid and readable. It does not need to reproduce the full responsive subdivision behavior.
+
+Modern browsers may enhance the grid when it is placed inside a query container.
+
+This follows Actual's general compatibility rule:
+
+> Modern CSS should not raise the Minimal baseline when a progressive fallback is possible at low cost.
+
+## Relationship with `--grid-min`
+
+`--grid-min` belongs naturally to `.grid`.
+
+It expresses the minimum desirable width of an item in a space-driven collection.
+
+Structural `.grid-N` presets are different: their behavior is driven by a known count and a predefined subdivision sequence.
+
+Trying to derive their container-query thresholds from `--grid-min` is not currently practical because size container-query conditions cannot use arbitrary custom-property values as their thresholds.
+
+The APIs should therefore remain conceptually separate:
+
+```text
+.grid
+    input: --grid-min
+    strategy: available-space driven
+
+.grid-N
+    input: structural density N
+    strategy: divisor-driven subdivision
+```
+
+The fact that both produce CSS Grid layouts does not mean they require the same responsive algorithm.
+
+## Supported structural densities
+
+The current useful presets are:
+
+```text
+2 → 1
+3 → 1
+4 → 2 → 1
+6 → 3 → 2 → 1
+```
+
+Not every integer necessarily deserves a preset.
+
+For example, five has only trivial divisors:
+
+```text
+5 → 1
+```
+
+Adding `.grid-5` would either produce an abrupt transition or require introducing non-divisor heuristics such as `5 → 2 → 1`.
+
+Actual should not add structural presets merely to complete a numerical sequence.
+
+New presets should have a clear layout use case and a defensible subdivision chain.
+
+## Thresholds are visual design decisions
+
+The subdivision chain can be derived from the structural density.
+
+The width thresholds at which transitions occur cannot.
+
+Values such as:
+
+```text
+28rem
+48rem
+64rem
+```
+
+must be validated against realistic Actual content rather than inherited mechanically from historical breakpoints.
+
+Before changing structural-grid thresholds, probes should verify:
+
+* realistic cards rather than empty boxes;
+* narrow parent inside a wide viewport;
+* every expected subdivision state;
+* equal item widths;
+* full and partial rows;
+* interaction with common Actual composition primitives;
+* fallback behavior without container-query support.
+
+The viewport itself should not determine the result; the relevant local container should.
+
+## API guidance
+
+Use `.grid` when the number of columns should emerge naturally from available space.
+
+Use `.grid-N` when the declared density and its balanced subdivisions are part of the intended composition.
+
+Use structural grids for uniform peer items. They are not intended as editorial grids with arbitrary per-item spans.
+
+Do not use CSS layout heuristics to compensate for a pagination size that produces undesirable full-page distributions when the server already knows the item count.
+
+## Decision
+
+Actual keeps two different grid contracts.
+
+```text
+.grid
+    intrinsic
+    space-driven
+    auto-fit
+    configurable through --grid-min
+    no guarantee of balanced rows
+
+.grid-N
+    structural
+    count-driven
+    equal-width items
+    responsive through natural subdivisions of N
+    local-container driven when enhanced
+```
+
+A structural grid must not become its own inline-size query container, because doing so breaks intrinsic and shrink-to-fit composition.
+
+If local responsive subdivision requires a size container query, that query container must remain outside the structural grid.
+
+The explicit container boundary is preferable to hidden containment side effects.
+
+The guiding principle is:
+
+> `.grid` optimizes for available space. `.grid-N` optimizes for balanced subdivision.
+
+Future grid changes should preserve that distinction unless the public contract itself is intentionally reconsidered.
+
+## Resolution
+
+`.grid-N` is a bounded `auto-fill` grid by default, and a divisor-chain grid
+inside a query container.
+
+```text
+.grid                      space-driven, auto-fit, --grid-min
+.grid-N                    count-driven baseline, auto-fill bounded at N,
+                           may pass through non-divisor column counts
+.container-query .grid-N   balanced subdivision, N -> divisors of N -> 1
+```
+
+The whole enhancement lives inside `@supports (container-type: inline-size)`.
+Browsers below the floor get the baseline whether or not a wrapper is present,
+which removes the parallel `@media` block 0.3.1 had to maintain in lockstep
+with its container thresholds.
+
+### `--grid-min` is not a `.grid-N` hook
+
+`@container` thresholds cannot resolve a custom property. A hook honored in the
+baseline would therefore fall silent the moment an author added a query
+container — exactly the kind of hidden, position-dependent contract this
+redesign set out to remove. The baseline hard-codes `16rem` instead.
+
+The resulting API split is the clearer one anyway: item width is `.grid`'s
+contract, column density is `.grid-N`'s.
+
+### Thresholds
+
+Three shared steps, not one calibrated per preset:
+
+```text
+28rem   first horizontal density   .grid-2, .grid-4, .grid-6 -> 2 columns
+48rem   three columns              .grid-3, .grid-6 -> 3 columns
+64rem   dense densities            .grid-4 -> 4, .grid-6 -> 6
+```
+
+An earlier draft tuned each final step so that every preset landed an item
+around 240px, which put `.grid-6` at 80rem or 96rem. That was the wrong
+optimization, and worth recording so it is not re-derived.
+
+Calibrating every preset to the same item width erases the information N
+carries. An author does not reach for `.grid-N` to say *I have N things*; they
+say *my content suits this density*. `.grid-6` should reach six columns early
+precisely because choosing it is a statement that the items are compact. At
+96rem an item is back to `.grid`'s 16rem default, and the preset has no reason
+to exist.
+
+The right probe is therefore each preset against the content it targets, not
+one specimen across all of them:
+
+| Preset    | Probed with                        | Item at its final step | Result |
+| --------- | ---------------------------------- | ---------------------- | ------ |
+| `.grid-2` | large card, summary, action        | 218px @ 28rem          | clean  |
+| `.grid-3` | standard card                      | 248px @ 48rem          | clean  |
+| `.grid-4` | compact card, stat                 | 247px @ 64rem          | clean  |
+| `.grid-6` | stat, avatar, thumbnail, icon tile | 161px @ 64rem          | clean  |
+
+161px is small for a card with a heading and a paragraph — and that is the
+point. A preset that needs 250px per item is `.grid-4`, not `.grid-6`.
+
+The framework does not guess appropriate item size. The author states it by
+choosing a density; the framework then guarantees a clean structural collapse
+of that density.
+
+### Why there is no `.grid-5`
+
+The divisors of five are five and one, so the chain would be `5 -> 1` with no
+intermediate state. The system exposes densities that subdivide well, not every
+integer. Proposals to give `.grid-5` a hand-picked `5 -> 2 -> 1` chain are
+covered by the rejected `smart-grid` section above: those steps encode an
+assumption about item count that the class cannot verify.

package/docs/design-notes/naming.md

@@ -37,3 +37,18 @@ Actual CSS is intended for new projects. Existing projects with class collisions
 - Shared runtime primitives may have public JavaScript APIs without becoming author-facing CSS or HTML vocabulary. Do not introduce `.surface` or `data-surface-*`; components keep their feature-specific author APIs (`data-flyout-*`, `data-context-menu-*`, CSS `.flyout`, `.menu`, …).
 - `data-enhance` is the one un-namespaced attribute — it carries *opt-in* for any feature, not *configuration* for one feature. Feature-namespaced attributes carry configuration.
 - Custom events use the `actual:*` namespace.
+
+## Utilities
+
+Utilities ship in two layers that follow the same class grammar.
+
+- **Base utilities** are a curated set of common ergonomic shortcuts
+  (`.overflow-auto`, `.gap-none`, `.text-nowrap`, `.px`, `.py`).
+- **Optional utilities** use explicit property/value names
+  (`.overflow-hidden`, `.gap-sm`, `.white-space-normal`).
+
+Base utilities may use compact names for a small set of frequent operations
+(`.px`, `.py`, `.mbs`, `.mbe`). Extra utilities use explicit property/value
+names and must not duplicate an operation already provided by base. The two
+sets may cover the same CSS property, but must not expose competing names for
+the same declaration.

package/docs/design-notes/widget-primitives.md

@@ -7,6 +7,7 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 | Need | Primitive | Import |
 |------|-----------|--------|
 | Opt-in discovery + lifecycle + cleanup | `enhance`, `registerEnhancement` | `actual-css/js/enhance` |
+| Per-document LIFO Escape dismissal | `escape` (`registerEscapeDismissal`) | `actual-css/js/escape` |
 | Positioning, flip/shift, `--available-height`, `data-placement` | `floating` (`track`, `reposition`, `repositionAt`) | `actual-css/js/floating` |
 | Open/close, sheet on mobile, backdrop, outside-click, Escape, focus restore | `surface` | `actual-css/js/surface` |
 | Directional item lookup, edges, wrapping, RTL | `keys` (`itemForKey`, `firstItem`, `lastItem`, `nextItem`) | `actual-css/js/keys` |

package/docs/navigation.json

@@ -5,7 +5,8 @@
       "slug": "guides",
       "pages": [
         "introduction",
-        "optional-components",
+        "integrating-actual-css",
+        "modular-import",
         "progressive-enhancement",
         "bootstrap",
         "tailwind"
@@ -21,15 +22,18 @@
       "slug": "layout",
       "pages": [
         "overview",
+        "choosing",
         "stack",
         "cluster",
         "grid",
+        "column-layout",
         "center",
         "sidebar-layout",
         "media",
         "switcher",
         "topbar",
         "scroll-snap",
+        "scroll-target",
         "frame",
         "app-shell",
         "list"