actual-css 0.3.0 → 0.4.0

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

@@ -4,6 +4,9 @@
  * Base form is unstyled chrome that takes its surrounding color. Add .pill for
  * the bordered rounded shape, and combine with an intent class (.primary,
  * .success, etc.) to tint the text, border, and background.
+ *
+ * Public hooks:
+ * --overline-radius
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
@@ -12,7 +15,6 @@
 }
 
 .overline {
-  align-self: flex-start;
   color: var(--text-muted);
   font-size: var(--font-size-sm);
   font-weight: var(--font-weight-medium);
@@ -21,14 +23,18 @@
 }
 
 .overline.pill {
+  --overline-radius: var(--radius-full);
+
   display: inline-flex;
   align-items: center;
   gap: 0.5em;
   padding-inline: 0.6em;
   padding-block: 0.25em;
+  inline-size: fit-content;
+  max-inline-size: 100%;
   color: var(--intent, var(--text-muted));
   border: var(--border-width) solid var(--border);
-  border-radius: var(--radius-full);
+  border-radius: var(--overline-radius);
   background: var(--surface);
 }
 
@@ -36,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 });
+}

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";
 
@@ -274,7 +275,9 @@ export function retainSurface(panel) {
     released = true;
     entry.count--;
     if (entry.count <= 0) {
-      disconnectSurface(panel, { restore: false });
+      // A released retainer may leave a mounted panel whose original parent
+      // either still needs it back or has disappeared along with the trigger.
+      disconnectSurface(panel);
       surfaceRetainers.delete(panel);
     }
   };
@@ -416,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";
 }

package/src/js/tooltip.js

@@ -14,9 +14,9 @@
  *             treated as a tooltip trigger.
  *
  * Sharing:    an explicit tooltip may be referenced by several triggers. The
- *             tooltip element is wired once (floating listeners + tracking);
- *             each trigger only registers itself and the wiring is torn down
- *             when the last trigger leaves the DOM.
+ *             tooltip element is wired once; each trigger only registers
+ *             itself. Positional tracking runs only while the tip is visible,
+ *             and all wiring is torn down when the last trigger leaves the DOM.
  *
  * Lazy:       tooltip elements are created (shorthand) or wired (explicit) on
  *             first mouseover / focusin. No page-load scan, no DOM overhead
@@ -28,6 +28,7 @@
  */
 
 import enhance from "./enhance.js";
+import { registerEscapeDismissal } from "./escape.js";
 import { autoUpdate, reposition } from "./floating.js";
 import { CLASSES } from "./selectors.js";
 
@@ -39,7 +40,9 @@ const HIDE_DELAY_MS = 100;
  * @property {Set<Element>} refs Triggers that currently reference this tip.
  * @property {Element | null} activeRef Trigger that last showed this tip.
  * @property {AbortController} controller Tip-level event listener cleanup.
- * @property {() => void} stopTracking Floating-position cleanup.
+ * @property {(() => void) | null} stopTracking Floating-position cleanup while visible.
+ * @property {(() => void) | null} unregisterEscape Escape-stack cleanup while visible and dismissable.
+ * @property {Element | null} escapeRef Trigger represented by the current Escape-stack entry.
  * @property {boolean} generated True when the tip was created from data-tooltip text.
  * @property {{ parent: Node, next: ChildNode | null } | null} mount Original DOM position for explicit tips moved into a dialog/body root.
  * @property {ReturnType<typeof setTimeout> | null} timer Pending delayed show.
@@ -52,7 +55,7 @@ const HIDE_DELAY_MS = 100;
 let uid = 0;
 const triggerStates = new WeakMap(); // trigger -> { tip, cleanup }
 /** @type {WeakMap<Element, TooltipState>} */
-const tipStates = new WeakMap(); // tip -> { refs, activeRef, controller, untrack, generated, mount, timer }
+const tipStates = new WeakMap(); // tip -> { refs, activeRef, controller, stopTracking, generated, mount, timer }
 
 function mountTip(tip, trigger) {
   const root = trigger.closest("dialog") || trigger.ownerDocument.body;
@@ -140,6 +143,50 @@ function repositionTip(ref, tip) {
   });
 }
 
+function updateTrackedTip(tip, state) {
+  const ref = state.activeRef;
+  if (!ref) return;
+
+  const alwaysVisible = isAlwaysVisible(ref);
+  // Reveal before measuring: an always-visible tooltip may currently be
+  // hidden because its trigger was outside the positioning boundary.
+  if (alwaysVisible) tip.hidden = false;
+  if (tip.hidden || repositionTip(ref, tip)) {
+    syncEscapeDismissal(tip, state);
+    return;
+  }
+
+  if (alwaysVisible) tip.hidden = true;
+  else hideTip(tip, true);
+}
+
+function startTracking(tip, state) {
+  if (state.stopTracking) return;
+
+  state.stopTracking = autoUpdate(tip, () => updateTrackedTip(tip, state));
+}
+
+function stopTracking(state) {
+  state?.stopTracking?.();
+  if (state) state.stopTracking = null;
+}
+
+function syncEscapeDismissal(tip, state) {
+  const ref = state.activeRef;
+  const dismissable = !tip.hidden && !isAlwaysVisible(ref);
+  // Position tracking calls this after every successful update. Preserve the
+  // current entry so a scroll/resize tick cannot reorder the LIFO stack.
+  if (dismissable && state.unregisterEscape && state.escapeRef === ref) return;
+
+  state.unregisterEscape?.();
+  state.unregisterEscape = null;
+  state.escapeRef = null;
+  if (!dismissable) return;
+
+  state.unregisterEscape = registerEscapeDismissal(tip, () => hideTip(tip, true));
+  state.escapeRef = ref;
+}
+
 function hideTip(tip, force = false) {
   const state = tipStates.get(tip);
   if (!force && isAlwaysVisible(state?.activeRef)) return;
@@ -152,6 +199,12 @@ function hideTip(tip, force = false) {
     state.hideTimer = null;
   }
   tip.hidden = true;
+  state?.unregisterEscape?.();
+  if (state) {
+    state.unregisterEscape = null;
+    state.escapeRef = null;
+  }
+  stopTracking(state);
 }
 
 function clearHide(tip) {
@@ -185,12 +238,9 @@ function wireTip(tip, options = {}) {
     refs: new Set(),
     activeRef: null,
     controller,
-    stopTracking: autoUpdate(tip, () => {
-      if (isAlwaysVisible(state.activeRef)) tip.hidden = false;
-      if (!tip.hidden && state.activeRef) {
-        if (!repositionTip(state.activeRef, tip)) hideTip(tip, true);
-      }
-    }),
+    stopTracking: null,
+    unregisterEscape: null,
+    escapeRef: null,
     generated: options.generated === true,
     mount: options.mount || null,
     timer: null,
@@ -217,17 +267,6 @@ function wireTip(tip, options = {}) {
     { signal: controller.signal },
   );
 
-  tip.ownerDocument.addEventListener(
-    "keydown",
-    (event) => {
-      if (event.key !== "Escape" || event.ctrlKey || event.altKey || event.shiftKey) return;
-      if (tip.hidden) return;
-      event.preventDefault();
-      hideTip(tip);
-    },
-    { signal: controller.signal },
-  );
-
   tipStates.set(tip, state);
   return state;
 }
@@ -308,7 +347,7 @@ function ensureTip(trigger) {
 
     hideTip(tip, true);
     state.controller.abort();
-    state.stopTracking();
+    stopTracking(state);
     tipStates.delete(tip);
     if (state.generated) tip.remove();
     else restoreTip(tip, state);
@@ -328,12 +367,14 @@ function show(tip, ref, immediate = false) {
   if (!state) return;
 
   state.activeRef = ref;
+  syncEscapeDismissal(tip, state);
   clearHide(tip);
   if (state.timer) clearTimeout(state.timer);
   const reveal = () => {
     state.timer = null;
     tip.hidden = false;
-    repositionTip(ref, tip);
+    startTracking(tip, state);
+    updateTrackedTip(tip, state);
   };
 
   if (immediate) reveal();

package/src/js/validation.js

@@ -391,7 +391,7 @@ export class FormValidator {
   static setErrors(form, errors) {
     if (!isFormElement(form)) return;
     for (const [name, message] of Object.entries(errors)) {
-      const found = form.elements[name];
+      const found = form.elements.namedItem(name);
       if (!found) continue;
       if (found instanceof Element) {
         FormValidator.setFieldError(found, message);