actual-css 0.3.1 → 0.4.1

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,52 @@
+/*
+ * 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 main region is first and the aside second by default
+ * (aside on the inline end). .reverse expects the aside first in the DOM, so
+ * visual, reading and keyboard order all agree — the role rules swap so the
+ * aside still takes its preferred width and the main still reclaims the row.
+ */
+.sidebar-layout {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gap);
+  align-items: flex-start;
+}
+
+/* Main region — flexible, reclaims the full row when the aside wraps. */
+.sidebar-layout > :first-child {
+  flex-basis: 0;
+  flex-grow: 999;
+  min-inline-size: min(100%, var(--sidebar-content-min, 30rem));
+}
+
+/* Aside region — preferred width, never forces content min-width. */
+.sidebar-layout > :last-child {
+  flex-basis: var(--sidebar-layout-size, 18rem);
+  flex-grow: 1;
+  min-inline-size: 0;
+}
+
+/* .reverse: the aside is first in the DOM and the main last, so each role
+   rule above would hit the wrong element. Swap the sizing per child; the
+   higher-specificity reverse rules outrank the positional defaults. */
+.sidebar-layout.reverse > :last-child {
+  flex-basis: 0;
+  flex-grow: 999;
+  min-inline-size: min(100%, var(--sidebar-content-min, 30rem));
+}
+
+.sidebar-layout.reverse > :first-child {
+  flex-basis: var(--sidebar-layout-size, 18rem);
+  flex-grow: 1;
+  min-inline-size: 0;
+}

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,27 @@
   --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-end: 0;
+}
+
+.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 +63,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 +136,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 +156,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 +166,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 });
+}

package/src/js/flyout.js

@@ -144,10 +144,29 @@ function connectTrigger(trigger) {
   trigger.addEventListener("keydown", onTriggerKeydown, { signal: controller.signal });
 }
 
-function resolvePanel(trigger, state) {
-  if (state.panel?.isConnected) return state.panel;
+function releasePanelReference(trigger, state) {
+  state.releaseMenu?.();
+  state.releaseMenu = null;
+
+  const panel = state.panel;
+  state.panel = null;
+  if (!panel) return;
+
+  const panelEntry = panelRefs.get(panel);
+  if (!panelEntry) return;
+
+  panelEntry.triggers.delete(trigger);
+  if (panelEntry.triggers.size === 0) {
+    panelEntry.release();
+    panelRefs.delete(panel);
+  }
+}
 
+function resolvePanel(trigger, state) {
   const panel = panelFor(trigger);
+  if (state.panel === panel && panel?.isConnected) return panel;
+
+  releasePanelReference(trigger, state);
   if (!panel) return null;
 
   let panelEntry = panelRefs.get(panel);
@@ -174,21 +193,12 @@ function resolvePanel(trigger, state) {
 function disconnectTrigger(trigger) {
   const state = triggerMap.get(trigger);
   if (!state) return;
-  state.releaseMenu?.();
   state.controller.abort();
   if (state.panel?.isConnected && isSurfaceOpen(state.panel)) {
     closeSurface(state.panel, { restoreFocus: false });
   }
+  releasePanelReference(trigger, state);
   triggerMap.delete(trigger);
-
-  const panelEntry = state.panel ? panelRefs.get(state.panel) : undefined;
-  if (panelEntry) {
-    panelEntry.triggers.delete(trigger);
-    if (panelEntry.triggers.size === 0) {
-      panelEntry.release();
-      panelRefs.delete(state.panel);
-    }
-  }
 }
 
 registerEnhancement("flyout", (trigger) => {

package/src/js/full.js

@@ -0,0 +1,26 @@
+/*
+ * Actual CSS - JavaScript runtime, full bundle entry.
+ *
+ * Each module self-registers via observer: importing this bundle enables
+ * common behaviors. No DOMContentLoaded ceremony, no init calls.
+ * Injected content wires automatically; removal cleans up automatically.
+ *
+ * A plain `<script src="actual.full.js"></script>` (no bundler, no import) still
+ * gets the full runtime, including declarative triggers like status's
+ * `command="--status"` and the `actual:status` event — no global needed to
+ * drive them from other inline scripts either.
+ */
+
+import "./flyout.js";
+import "./context-menu.js";
+import "./dialog.js";
+import "./dismiss.js";
+import "./tab.js";
+import "./tooltip.js";
+import "./scrollspy.js";
+import "./filter.js";
+import "./mask.js";
+import "./password.js";
+import "./validation.js";
+import "./status.js";
+import "./index.js";

package/src/js/index.js

@@ -1,28 +1,12 @@
 /*
- * Actual CSS - JavaScript runtime.
+ * Actual CSS - JavaScript runtime, core entry.
  *
- * Each module self-registers via observer: importing the default runtime
- * enables common behaviors. No DOMContentLoaded ceremony, no init calls.
- * Injected content wires automatically; removal cleans up automatically.
- *
- * A plain `<script src="actual.js"></script>` (no bundler, no import) still
- * gets the full runtime, including declarative triggers like status's
- * `command="--status"` and the `actual:status` event — no global needed to
- * drive them from other inline scripts either.
+ * This entry only starts the enhancement manifest loader. Built-in behaviors
+ * (dialogs, menus, tabs, validation, ...) ship in the full bundle entry
+ * (src/js/full.js). Use this module for pages that only need progressive
+ * enhancement via enhancement manifests.
  */
 
-import "./flyout.js";
-import "./context-menu.js";
-import "./dialog.js";
-import "./dismiss.js";
-import "./tab.js";
-import "./tooltip.js";
-import "./scrollspy.js";
-import "./filter.js";
-import "./mask.js";
-import "./password.js";
-import "./validation.js";
-import "./status.js";
 import { watchEnhancementManifests } from "./enhancement-loader.js";
 
 watchEnhancementManifests();

package/src/js/surface.js

@@ -1,4 +1,5 @@
 import enhance from "./enhance.js";
+import { registerEscapeDismissal } from "./escape.js";
 import { EVENTS } from "./events.js";
 import { autoUpdate, reposition, repositionAt } from "./floating.js";
 
@@ -418,37 +419,6 @@ function ensureDocumentClick(menu) {
   doc.addEventListener("click", onDocumentClick);
 }
 
-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 });
-}
-
 export function getSurfaceAutoClose(menu) {
   return surfaceMap.get(menu)?.autoClose ?? "outside";
 }