actual-css 0.3.1 → 0.4.0

package/src/css/layout/frame.css

@@ -0,0 +1,19 @@
+/*
+ * Media frame with a fixed ratio.
+ *
+ * Public hooks:
+ * --frame-ratio
+ *
+ * Child contract: direct media children (img/video/iframe/canvas/svg) are
+ * sized to fill the frame.
+ */
+.frame {
+  overflow: hidden;
+  aspect-ratio: var(--frame-ratio, 16 / 9);
+}
+
+.frame > :where(img, video, iframe, canvas, svg) {
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}

package/src/css/layout/grid.css

@@ -0,0 +1,141 @@
+/*
+ * Responsive equal-width grids.
+ *
+ * .grid is space-driven: it fits as many tracks as --grid-min allows.
+ * .grid-N is count-driven: it declares a structural density of N and collapses
+ * through natural divisors of N (see the subdivision block below).
+ *
+ * Public hooks:
+ * --grid-min
+ * --grid-columns
+ *
+ * Internal:
+ * --grid-count
+ *
+ * Child contract: each direct child is a grid item placed in the tracks the
+ * recipe generates.
+ */
+
+/* --grid-columns replaces the intrinsic auto-fit template: once set, the
+   grid no longer collapses on its own — the author owns narrow-container
+   collapse. Prefer .sidebar-layout for content + aside layouts; reserve
+   --grid-columns for exact custom track templates. */
+
+/* Recipe:
+   - collection whose item width is the contract -> .grid, tune --grid-min
+   - collection whose column density is the contract -> .grid-2/3/4/6
+   - balanced subdivision of that density -> wrap it in .container-query
+   - peer regions that switch as a group -> .switcher
+   - content + aside -> .sidebar-layout
+   - exact custom track templates -> --grid-columns with an explicit collapse
+     rule of your own */
+.grid {
+  display: grid;
+  gap: var(--gap);
+  grid-template-columns: var(
+      --grid-columns,
+      repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr))
+    );
+}
+
+/* Structural density presets. The baseline is an auto-fill grid bounded at N
+   tracks: responsive and overflow-safe on its own, so a preset used without a
+   query container is never a trap — it simply reaches its balanced states less
+   precisely. auto-fill rather than auto-fit keeps item width stable when a
+   partial final page holds fewer items than the grid's capacity.
+
+   --grid-min is deliberately NOT read here. The subdivision below runs on
+   @container thresholds, which cannot resolve a custom property, so a hook
+   honored in the baseline would fall silent the moment a query container is
+   added. Item width is .grid's contract; column density is .grid-N's. */
+:where(.grid-2, .grid-3, .grid-4, .grid-6) {
+  display: grid;
+  gap: var(--gap);
+  grid-template-columns: repeat(
+      auto-fill,
+      minmax(
+        min(
+          100%,
+          max(16rem, calc((100% - (var(--grid-count) - 1) * var(--gap)) / var(--grid-count)))
+        ),
+        1fr
+      )
+    );
+}
+
+.grid-2 {
+  --grid-count: 2;
+}
+.grid-3 {
+  --grid-count: 3;
+}
+.grid-4 {
+  --grid-count: 4;
+}
+.grid-6 {
+  --grid-count: 6;
+}
+
+/* Grid items keep an automatic minimum inline size (min-content), which can
+   overflow a track sized minmax(0, 1fr). Layout primitives remove that
+   intrinsic floor so their overflow-safe track sizing holds; authors only
+   need .min-inline-size-0 outside primitives that do not already remove this
+   floor. */
+:where(.grid, .grid-2, .grid-3, .grid-4, .grid-6) > * {
+  min-inline-size: 0;
+}
+
+/* Balanced subdivision, opted into by an ancestor query container.
+ *
+ *   .grid-2   2 -> 1
+ *   .grid-3   3 -> 1
+ *   .grid-4   4 -> 2 -> 1
+ *   .grid-6   6 -> 3 -> 2 -> 1
+ *
+ * Every state is a divisor of N, so all items keep the same width and no
+ * state produces a visibly uneven split such as 5 + 1 or 4 + 2. Intermediate
+ * counts are skipped on purpose: do not "complete" these chains with the
+ * missing integers, and do not replace them with an unbounded auto-fit.
+ *
+ * The query container must be an ancestor. An element cannot query its own
+ * size without taking inline-size containment, which destroys its intrinsic
+ * inline contribution and collapses it inside .cluster, .topbar, floats, and
+ * any shrink-to-fit box. See docs/design-notes/grid.md.
+ *
+ * Three shared thresholds, not one calibrated per preset: 28rem opens the
+ * first horizontal density, 48rem opens three columns, 64rem opens the dense
+ * 4 and 6. N already carries the author's statement about item size, so
+ * tuning every step to land the same item width would erase that signal —
+ * .grid-6 at 64rem gives ~161px per tile, which is the point of choosing it.
+ * Probed with the content each preset targets: large cards for .grid-2 down
+ * to stats, avatars, and thumbnails for .grid-6.
+ *
+ * Ascending min-width only: the last matching step wins by cascade order.
+ */
+@supports (container-type: inline-size) {
+  .container-query :where(.grid-2, .grid-3, .grid-4, .grid-6) {
+    grid-template-columns: 1fr;
+  }
+
+  @container (min-width: 28rem) {
+    .container-query :where(.grid-2, .grid-4, .grid-6) {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+
+  @container (min-width: 48rem) {
+    .container-query :where(.grid-3, .grid-6) {
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+  }
+
+  @container (min-width: 64rem) {
+    .container-query :where(.grid-4) {
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+
+    .container-query :where(.grid-6) {
+      grid-template-columns: repeat(6, minmax(0, 1fr));
+    }
+  }
+}

package/src/css/layout/index.css

@@ -0,0 +1,42 @@
+/*
+ * Layout — composition primitives. Readable cascade order: container-query
+ * first (a local opt-in, unrelated to the primitives), then the primitives.
+ *
+ * Selection:
+ * .stack          vertical flow
+ * .cluster        wrapping inline group
+ * .center         centered content column
+ * .frame          fixed-ratio media frame
+ * .app-shell      full-height application shell
+ * .media          fixed media + flexible content
+ * .switcher       peer regions: all horizontal or all stacked
+ * .sidebar-layout main content + secondary aside
+ * .grid           responsive collection; item width is the contract
+ * .grid-N         structural density of N; wrap in .container-query for
+ *                 balanced subdivision (in grid.css)
+ * .column-layout  explicit 12-column region composition; the author owns
+ *                 narrow-container recomposition
+ * .scroller       theme-aware scrollbar density and colour
+ * .scroll-snap    snap rails
+ * .scroll-target  anchor scroll offset for sticky headers
+ * .topbar         sticky app-shell top bar
+ * .measure        readable content measure cap
+ *
+ * Prefer these compositions over viewport breakpoint utilities.
+ */
+@import "./container-query.css";
+@import "./stack.css";
+@import "./cluster.css";
+@import "./center.css";
+@import "./frame.css";
+@import "./app-shell.css";
+@import "./media.css";
+@import "./switcher.css";
+@import "./sidebar-layout.css";
+@import "./grid.css";
+@import "./column-layout.css";
+@import "./scroller.css";
+@import "./scroll-snap.css";
+@import "./scroll-target.css";
+@import "./topbar.css";
+@import "./measure.css";

package/src/css/layout/measure.css

@@ -0,0 +1,9 @@
+/* Readable content measure. Composes with .center for centering or with
+   margin-inline: auto for a one-off centered block.
+ *
+ * Public hooks:
+ * --measure
+ */
+.measure {
+  max-inline-size: var(--measure, 70ch);
+}

package/src/css/layout/media.css

@@ -0,0 +1,10 @@
+/* Media object: fixed-width leading element (avatar, icon, image) + flexible
+   trailing content. Replaces the repeated "auto minmax(0, 1fr)" pattern in
+   author cards, comments, meta rows, and similar compositions.
+   Child contract: exactly two direct children (leading media + content). */
+.media {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: var(--gap);
+  align-items: start;
+}

package/src/css/layout/scroll-target.css

@@ -0,0 +1,15 @@
+/* Anchor scroll offset. A #hash link or scrollIntoView() places the target
+ * flush at the scroll container's start edge, which hides it behind a sticky
+ * header (.topbar) or underlaps it; scroll-margin reserves space on the
+ * target itself so the browser stops early.
+ *
+ * Apply to the elements that are link targets: <section id="...">, headings,
+ * etc. The scrollspy enhancer only reads ids — this offset is what actually
+ * shapes where the page lands, and the two are independent.
+ *
+ * Public hooks:
+ * --scroll-target-offset
+ */
+.scroll-target {
+  scroll-margin-block-start: var(--scroll-target-offset, var(--space-60));
+}

package/src/css/layout/scroller.css

@@ -0,0 +1,41 @@
+/*
+ * Scroller — optional scrollbar treatment for overflow regions.
+ *
+ * Apply to any scroll container (.overflow-auto, sidebars, long tables). Only
+ * the standard properties are used: the engine keeps drawing the scrollbar,
+ * this hands it the theme's density and colour. No ::-webkit-scrollbar chrome —
+ * rebuilding a thumb by hand means re-implementing the hover, the corner and
+ * the light/dark adaptation that color-scheme already gives for free, and the
+ * two never match anyway.
+ *
+ * Above the capability floor: scrollbar-color lands in Chromium 121 and
+ * Safari 18.2, the floor is Chromium 99 / Safari 15.4. Older engines ignore
+ * both declarations and draw their native scrollbar — the intended fallback,
+ * not a broken state.
+ *
+ * Styles the scrollbar only; it does not create the overflow. Pair it with
+ * .overflow-auto or a component that already scrolls.
+ *
+ * Public hooks:
+ * --scroller-track
+ * --scroller-thumb
+ */
+.scroller {
+  --scroller-track: transparent;
+  --scroller-thumb: var(--border);
+
+  scrollbar-color: var(--scroller-thumb) var(--scroller-track);
+  scrollbar-width: thin;
+}
+
+/* Opt-in gutter: reserves space so the layout does not shift when
+   the scrollbar appears. Use alongside a known-overflow container. */
+.scroller.stable-gutter {
+  scrollbar-gutter: stable;
+}
+
+@supports (color: color-mix(in oklch, red, white)) {
+  .scroller {
+    --scroller-thumb: color-mix(in oklch, var(--text-muted), transparent 55%);
+  }
+}

package/src/css/layout/sidebar-layout.css

@@ -0,0 +1,31 @@
+/*
+ * Main content + secondary region.
+ *
+ * The children wrap according to the space allocated to this layout, without
+ * an ancestor opt-in or viewport threshold. The large growth ratio lets the
+ * main region reclaim the full row when the aside wraps instead of remaining
+ * at its minimum viable width.
+ *
+ * Public hooks:
+ * --sidebar-content-min
+ * --sidebar-layout-size
+ *
+ * Child contract: the first and last direct children carry the sizing roles.
+ */
+.sidebar-layout {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gap);
+  align-items: flex-start;
+}
+
+.sidebar-layout > :first-child {
+  flex-basis: 0;
+  flex-grow: 999;
+  min-inline-size: min(100%, var(--sidebar-content-min, 30rem));
+}
+
+.sidebar-layout > :last-child {
+  flex-basis: var(--sidebar-layout-size, 18rem);
+  flex-grow: 1;
+}

package/src/css/layout/stack.css

@@ -0,0 +1,21 @@
+/* Vertical flow. .stack owns the block axis only: block margins reset, inline
+   margins stay free (self-centering children via margin-inline: auto keep
+   working).
+   Child contract: direct children become flex items; margins reset, spacing
+   comes from --gap.
+
+   --gap is inherited, so a container that composes other primitives sets its
+   own rhythm on the `gap` property, not on the token: setting --gap on a
+   region re-spaces every nested stack, cluster and grid at any depth. Setting
+   the token stays correct on the element that consumes it, and .sm/.lg set it
+   deliberately so a density context reaches nested layouts. See
+   docs/pages/layout/stack.md. */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap);
+}
+
+.stack > * {
+  margin-block: 0;
+}

package/src/css/layout/switcher.css

@@ -0,0 +1,23 @@
+/*
+ * Peer regions that switch as a group.
+ *
+ * All children sit side by side when they all fit; otherwise every child
+ * stacks. Unlike .grid, this recipe cannot create a partial row such as two
+ * items plus one orphan.
+ *
+ * Public hooks:
+ * --switcher-threshold
+ *
+ * Child contract: every direct child is a peer; the flex-basis applies to all.
+ */
+.switcher {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gap);
+}
+
+.switcher > * {
+  flex-basis: calc((var(--switcher-threshold, 40rem) - 100%) * 999);
+  flex-grow: 1;
+  min-inline-size: 0;
+}

package/src/css/{optional/layout-extra.css → layout/topbar.css}

@@ -1,23 +1,3 @@
-/*
- * Additional layout primitives not included in the core bundle.
- *
- * Import this file explicitly when a project needs these patterns.
- *
- * Public hooks:
- * --switcher-threshold
- */
-.switcher {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--gap);
-}
-
-.switcher > * {
-  flex-basis: calc((var(--switcher-threshold, 40rem) - 100%) * 999);
-  flex-grow: 1;
-  min-inline-size: 0;
-}
-
 /*
  * Sticky, frosted top bar shell for app/dashboard shells (persistent
  * sidebar + topbar layouts). Owns positioning, stacking, and the frosted

package/src/css/typography/index.css

@@ -0,0 +1,5 @@
+/* Typography — prose scope and typographic treatments. */
+@import "./prose.css";
+@import "./lead.css";
+@import "./overline.css";
+@import "./fluid.css";

package/src/css/typography/lead.css

@@ -0,0 +1,7 @@
+/* Lead paragraph: a slightly larger, more relaxed reading-introduction text.
+   Non-fluid and always available — use .text-lead from the optional fluid
+   module for marketing/display surfaces. */
+.lead {
+  font-size: 1.125em;
+  line-height: var(--line-height-relaxed);
+}

package/src/css/{components → typography}/overline.css

@@ -42,7 +42,7 @@
    keeps a readable bordered pill everywhere else. */
 @supports (color: color-mix(in oklch, red, white)) {
   .overline.pill {
-    border-color: color-mix(in oklch, var(--intent, var(--border)) 35%, var(--border));
-    background: color-mix(in oklch, var(--intent, transparent) 6%, var(--surface));
+    border-color: color-mix(in oklab, var(--intent, var(--border)) 35%, var(--border));
+    background: color-mix(in oklab, var(--intent, transparent) 6%, var(--surface));
   }
 }

package/src/css/{prose.css → typography/prose.css}

@@ -14,6 +14,7 @@
  * --prose-h2
  * --prose-h3
  * --prose-h4
+ * --link
  */
 
 .prose {
@@ -29,19 +30,23 @@
   --prose-h4: 1.125rem;
 
   max-inline-size: var(--prose-measure);
-  color: var(--text);
   font-size: var(--prose-size);
   line-height: var(--prose-line-height);
   overflow-wrap: break-word;
 }
 
-.prose :where(p, ul, ol, dl, blockquote, pre, table, figure) {
-  margin-block: var(--prose-flow) 0;
+/* Vertical rhythm belongs to the direct block that participates in the
+   document, so it must not be injected into the internals of a nested
+   component (e.g. a .table-wrap around a .table would trap the margin). */
+.prose > * + * {
+  margin-block-start: var(--prose-flow);
 }
 
+/* Heading hierarchy remains low-specificity and contextual: a surface may
+   remap --heading without prose repainting it with the root text color. */
 .prose :where(h1, h2, h3, h4, h5, h6) {
   margin-block: 1.5em 0;
-  color: var(--text);
+  color: var(--heading, var(--text));
   font-weight: var(--font-weight-strong);
   line-height: var(--prose-heading-line-height);
 }
@@ -54,48 +59,71 @@
   margin-block-start: 0;
 }
 
-.prose h1 {
+/* Element recipes are wrapped in :where() so every .prose rule is 0-1-0.
+   An explicit component/util class can therefore override prose defaults
+   regardless of the underlying element — a .btn or .alert link must not be
+   reshaped just because it lives inside authored content. */
+.prose :where(h1) {
   font-size: var(--prose-h1);
 }
 
-.prose h2 {
+.prose :where(h2) {
   font-size: var(--prose-h2);
 }
 
-.prose h3 {
+.prose :where(h3) {
   font-size: var(--prose-h3);
 }
 
-.prose h4 {
+.prose :where(h4) {
   font-size: var(--prose-h4);
 }
 
-.prose a {
-  color: var(--primary);
+/* Link ink defaults to --primary. --link is an optional escape hatch: a
+   theme whose primary is too light or too vivid to read as inline text sets
+   it without having to restate the rule. */
+.prose :where(a) {
+  color: var(--link, var(--primary));
   text-decoration-line: underline;
   text-decoration-thickness: 0.08em;
   text-underline-offset: 0.18em;
 }
 
-.prose a:hover {
+.prose :where(a:hover) {
   text-decoration-thickness: 0.12em;
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  .prose a:hover {
-    color: color-mix(in oklch, var(--primary), var(--text) 15%);
+  .prose :where(a:hover) {
+    color: color-mix(in oklab, var(--link, var(--primary)), var(--text) 15%);
   }
 }
 
+/* Rich-text descendants are intentional here. Components and application UI
+   belong outside the prose boundary. */
 .prose :where(ul, ol) {
   padding-inline-start: 1.5em;
 }
 
-.prose li + li {
+.prose :where(li + li) {
   margin-block-start: 0.35em;
 }
 
-.prose code {
+/* Description lists keep document flow: a valid <dl> may pair several <dt>
+   with one <dd> or the reverse, so no grid layout is imposed here. */
+.prose :where(dt) {
+  font-weight: var(--font-weight-strong);
+}
+
+.prose :where(dd) {
+  margin-inline-start: 1.5em;
+}
+
+.prose :where(dd + dt) {
+  margin-block-start: 0.75em;
+}
+
+.prose :where(code) {
   padding: 0.15em 0.3em;
   border-radius: var(--radius-sm);
   background: var(--surface-subtle);
@@ -104,7 +132,8 @@
 }
 
 /* Visual twin of .key (components/key.css) — keep the two recipes in sync. */
-.prose kbd {
+/* @sync key-recipe */
+.prose :where(kbd) {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -123,8 +152,9 @@
   white-space: nowrap;
   vertical-align: 0.08em;
 }
+/* @sync key-recipe */
 
-.prose pre {
+.prose :where(pre) {
   overflow-x: auto;
   padding: 1em;
   border: var(--border-width) solid var(--border);
@@ -132,53 +162,38 @@
   background: var(--surface-subtle);
 }
 
-.prose pre code {
+.prose :where(pre) :where(code) {
   padding: 0;
   background: transparent;
 }
 
-.prose blockquote {
+.prose :where(blockquote) {
   padding-inline-start: 1em;
   border-inline-start: var(--border-width) solid var(--border);
   color: var(--text-muted);
 }
 
-.prose figure {
+.prose :where(figure) {
   margin-inline: 0;
 }
 
-.prose figcaption {
+.prose :where(figcaption) {
   margin-block-start: 0.5em;
   color: var(--text-muted);
   font-size: 0.875em;
 }
 
-.prose table {
+.prose :where(table) {
   inline-size: 100%;
   border-collapse: collapse;
 }
 
-.prose th,
-.prose td {
+.prose :where(th, td) {
   padding: 0.5em;
   border-block-end: var(--border-width) solid var(--border);
   text-align: start;
 }
 
-/* Lead paragraph: a slightly larger, more relaxed reading-introduction text.
-   Non-fluid and always available — use .text-lead from the optional fluid
-   module for marketing/display surfaces. */
-.lead {
-  font-size: 1.125em;
-  line-height: var(--line-height-relaxed);
-}
-
-/* Readable content measure. Composes with .center for centering or with
-   margin-inline: auto for a one-off centered block. */
-.measure {
-  max-inline-size: var(--prose-measure, 70ch);
-}
-
 .prose.sm {
   --prose-size: 0.9375rem;
   --prose-h1: 1.75rem;

package/src/css/{utilities.css → utilities/base.css}

@@ -12,6 +12,8 @@
   margin: -1px;
   overflow: hidden;
   clip: rect(0, 0, 0, 0);
+  /* clip alone is legacy-only; clip-path is the modern hiding mechanism. */
+  clip-path: inset(50%);
   white-space: nowrap;
   border: 0;
 }

package/src/css/utilities/index.css

@@ -0,0 +1,3 @@
+/* Utilities — small, single-purpose escape hatches. */
+@import "./base.css";
+@import "./extra.css";

package/src/js/escape.js

@@ -0,0 +1,36 @@
+/*
+ * Per-document LIFO dismissal for transient UI that closes on Escape.
+ * Consumers register only while visible, so the topmost dismissable UI owns
+ * one key press and pinned or hidden UI never consumes it.
+ */
+
+const dismissableStacks = new WeakMap();
+
+export function registerEscapeDismissal(element, dismiss) {
+  const doc = element.ownerDocument;
+  let stack = dismissableStacks.get(doc);
+  if (!stack) {
+    stack = [];
+    dismissableStacks.set(doc, stack);
+    doc.addEventListener("keydown", onDocumentEscape);
+  }
+
+  const entry = { element, dismiss };
+  stack.push(entry);
+
+  return () => {
+    const index = stack.indexOf(entry);
+    if (index >= 0) stack.splice(index, 1);
+  };
+}
+
+function onDocumentEscape(event) {
+  if (event.key !== "Escape" || event.ctrlKey || event.altKey || event.shiftKey) return;
+
+  const stack = dismissableStacks.get(event.currentTarget);
+  const entry = stack.at(-1);
+  if (!entry) return;
+
+  event.preventDefault();
+  entry.dismiss({ restoreFocus: true });
+}