actual-css 0.9.0 → 0.9.1

package/src/css/forms/control.css

@@ -1,6 +1,8 @@
 /*
  * Text controls — input, textarea, select.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Neutral geometry and interaction states shared across all text-like
  * controls. select shares this base recipe; its chevron/appearance layer
  * lives in select.css. checkbox, radio, range, switch, and file have their

package/src/css/forms/floating-field.css

@@ -2,6 +2,8 @@
  * Floating labels — optional composition over the text controls
  * (.input, .textarea, .select) and .field-label.
  *
+ * Docs: docs/pages/forms/floating-field.md
+ *
  * The cell owns a control plus its label; the label overlays the control and
  * floats to the top when the control is focused or non-empty. Help and error
  * messages stay in the surrounding .field, not inside the cell, so the
@@ -43,7 +45,9 @@
 
 .floating-field > .field-label {
   position: absolute;
-  inset-inline-start: calc(var(--space-30) + var(--border-width));
+  /* Same start edge as the control's text: --control-pad-x owns that shared
+     geometry, so .sm/.lg keep label and value aligned. */
+  inset-inline-start: calc(var(--control-pad-x) + var(--border-width));
   color: var(--text-muted);
   font-size: var(--control-font-size);
   font-weight: var(--font-weight-normal);

package/src/css/forms/form-actions.css

@@ -1,6 +1,8 @@
 /*
  * Form actions — bottom form bar with sticky variant.
  *
+ * Docs: docs/pages/forms/form-actions.md
+ *
  * A flex cluster of buttons/actions that closes a form. The sticky variant
  * docks to the viewport bottom with a translucent blur where supported; at
  * rest it stays visually neutral so it does not double as a separator.

package/src/css/forms/form.css

@@ -1,6 +1,8 @@
 /*
  * Form layout and supporting text.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Individual controls keep their own files; .choice label layout lives in
  * choice.css; .form-actions lives in form-actions.css.
  *

package/src/css/forms/input-icon.css

@@ -1,6 +1,8 @@
 /*
  * Input Icon — decorative icon inside a relative wrapper, leading or trailing.
  *
+ * Docs: docs/pages/patterns/icon-input.md
+ *
  * Icon-library agnostic: detects position by DOM order. First child that is
  * not .input = leading icon; icon after .input = trailing. The icon follows
  * local typography; density contexts shrink the control geometry around it

package/src/css/forms/native.css

@@ -3,6 +3,8 @@
  * custom styling, so the framework stays out of the way and just keeps them
  * readable and theme-aware.
  *
+ * Docs: docs/pages/forms/controls.md
+ *
  * Range has its own custom-styled file (range.css) so the focus ring can
  * target the thumb pseudo-element rather than the rectangular CSS box.
  */

package/src/css/forms/otp.css

@@ -1,6 +1,8 @@
 /*
  * One-time code input with visual cells and one native input.
  *
+ * Docs: docs/pages/forms/otp.md
+ *
  * Add one direct span per accepted character. The cells determine the
  * component width; the overlaid input remains the only interactive control.
  *
@@ -129,4 +131,12 @@
   .needs-validation.was-validated .otp > input:invalid ~ span {
     --otp-cell-border: Mark;
   }
+
+  /* biome-ignore lint/style/noDescendingSpecificity: the :user-invalid route
+     mirrors the non-forced-colors block above and must come last — the three
+     invalid markers write the same value, so source order is inert. An engine
+     without the pseudo drops this rule alone. */
+  .needs-validation .otp > input:user-invalid ~ span {
+    --otp-cell-border: Mark;
+  }
 }

package/src/css/forms/range.css

@@ -2,6 +2,8 @@
  * Range slider — custom-styled so the focus ring always targets the
  * user-manipulated surface (the thumb) rather than the CSS box.
  *
+ * Docs: docs/pages/forms/range.md
+ *
  * appearance: none gives us full control over track and thumb; without it,
  * pseudo-element rules for ::-webkit-slider-thumb and ::-moz-range-thumb
  * are not reliably applied across browsers.

package/src/css/forms/select.css

@@ -2,6 +2,8 @@
  * Select — chevron and appearance layer on top of the shared text-control
  * recipe.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Base geometry and interaction states come from control.css (select shares
  * the --control-* tokens). This file only removes the native arrow and draws
  * the CSS chevron, so the picker (appearance: base-select) enhancement in

package/src/css/forms/switch.css

@@ -1,6 +1,8 @@
 /*
  * Switch controls for checkbox inputs with switch semantics.
  *
+ * Docs: docs/pages/forms/switch.md
+ *
  * The switch remains an input control, not a decorative toggle. Checked, hover,
  * focus-visible, and disabled states stay clear.
  *

package/src/css/forms/validation.css

@@ -1,6 +1,8 @@
 /*
  * Form validation states.
  *
+ * Docs: docs/pages/forms/validation.md
+ *
  * Imported by default through forms/index.css. Custom builds may omit this
  * file when an app wants to own validation styling completely.
  *

package/src/css/layout/app-layout.css

@@ -5,6 +5,8 @@
  * chrome available without fixed offsets. This is not a generic page wrapper
  * or a public-site layout; all three direct regions are part of the contract.
  *
+ * Docs: docs/pages/layout/app-layout.md
+ *
  * Public hook:
  * --app-nav-side-size
  */

package/src/css/layout/app-shell.css

@@ -1,4 +1,8 @@
-/* Full-height single-column document shell. */
+/*
+ * Full-height single-column document shell.
+ *
+ * Docs: docs/pages/layout/app-shell.md
+ */
 .app-shell {
   min-block-size: var(--viewport-block);
   display: flex;

package/src/css/layout/center.css

@@ -1,6 +1,8 @@
 /*
  * Centered content column with a maximum measure.
  *
+ * Docs: docs/pages/layout/center.md
+ *
  * Public hooks:
  * --center-size
  * --center-pad

package/src/css/layout/cluster.css

@@ -1,6 +1,8 @@
 /*
  * Inline group that wraps when space runs out.
  *
+ * Docs: docs/pages/layout/cluster.md
+ *
  * Public hooks:
  * --cluster-align
  * --cluster-justify

package/src/css/layout/column-layout.css

@@ -1,6 +1,8 @@
 /*
  * Explicit 12-column composition canvas.
  *
+ * Docs: docs/pages/layout/column-layout.md
+ *
  * Neither space-driven like .grid nor count-driven like .grid-N: this is a
  * coordinate system. The author places regions with .column-span-N /
  * .column-start-N and owns narrow-container recomposition. There is

package/src/css/layout/frame.css

@@ -1,6 +1,8 @@
 /*
  * Media frame with a fixed ratio.
  *
+ * Docs: docs/pages/layout/frame.md
+ *
  * Public hooks:
  * --frame-ratio
  *

package/src/css/layout/grid.css

@@ -1,6 +1,8 @@
 /*
  * Responsive equal-width grids.
  *
+ * Docs: docs/pages/layout/grid.md
+ *
  * .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.

package/src/css/layout/media.css

@@ -1,7 +1,8 @@
 /* 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). */
+   Child contract: exactly two direct children (leading media + content).
+   Docs: docs/pages/layout/media.md */
 .media {
   display: grid;
   grid-template-columns: auto minmax(0, 1fr);

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

@@ -2,6 +2,8 @@
  * Scroll snap — optional horizontal rails for niche card strips and simple
  * touch-friendly overflow areas.
  *
+ * Docs: docs/pages/layout/scroll-snap.md
+ *
  * This is not a full carousel. For previous/next controls, pagination,
  * active state, drag behavior, looping, or robust desktop mouse interaction,
  * use a dedicated carousel library.

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

@@ -3,6 +3,8 @@
  * header (.topbar) or underlaps it; scroll-margin reserves space on the
  * target itself so the browser stops early.
  *
+ * Docs: docs/pages/layout/scroll-target.md
+ *
  * 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.

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

@@ -1,6 +1,8 @@
 /*
  * Main content + secondary region.
  *
+ * Docs: docs/pages/layout/sidebar-layout.md
+ *
  * 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

package/src/css/layout/stack.css

@@ -9,7 +9,8 @@
    region re-spaces every nested stack, cluster and grid at any depth. Setting
    the token stays correct on the element that consumes it, and
    .compact/.spacious set it deliberately so a density context reaches nested layouts. See
-   docs/pages/layout/stack.md. */
+   docs/pages/layout/stack.md.
+   Docs: docs/pages/layout/stack.md */
 .stack {
   display: flex;
   flex-direction: column;

package/src/css/layout/switcher.css

@@ -1,6 +1,8 @@
 /*
  * Peer regions that switch as a group.
  *
+ * Docs: docs/pages/layout/switcher.md
+ *
  * 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.

package/src/css/layout/topbar.css

@@ -4,6 +4,8 @@
  * background only — row content (search, breadcrumb, actions) stays local
  * to the page.
  *
+ * Docs: docs/pages/layout/topbar.md
+ *
  * Not for marketing/editorial site headers — those are one-off visual
  * identity per page; see docs/pages/patterns/overview.md's Header Navigation
  * section. This is for the structural app-shell topbar, which recurs unchanged

package/src/css/typography/fluid.css

@@ -1,6 +1,8 @@
 /*
  * Optional fluid typography module.
  *
+ * Docs: docs/pages/foundations/typography.md
+ *
  * Part of the typography family (typography/index.css) and the full bundle; it
  * is not in the minimal core, so a core-only import adds it explicitly when
  * display, title, and lead sizes must scale with the viewport. Typical use

package/src/css/typography/lead.css

@@ -1,6 +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. */
+   module for marketing/display surfaces.
+   Docs: docs/pages/foundations/typography.md */
 .lead {
   font-size: 1.125em;
   line-height: var(--line-height-relaxed);

package/src/css/typography/overline.css

@@ -1,6 +1,8 @@
 /*
  * Overline — editorial small-cap label for section openers.
  *
+ * Docs: docs/pages/foundations/typography.md
+ *
  * 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.

package/src/css/typography/prose.css

@@ -1,6 +1,8 @@
 /*
  * Prose is the opt-in rich text scope for authored content.
  *
+ * Docs: docs/pages/foundations/typography.md
+ *
  * Global element styles stay mild so app UI is not shaped accidentally. Page
  * layout, forms, cards, navigation, and app tables remain outside this scope.
  *

package/src/css/utilities/base.css

@@ -143,7 +143,12 @@
   text-decoration: none;
 }
 
-.link-muted:hover,
+/* :focus-visible stays in its own rule: in a mixed selector list an engine
+   without it would drop the whole rule, taking the :hover styling with it. */
+.link-muted:hover {
+  color: var(--text);
+}
+
 .link-muted:focus-visible {
   color: var(--text);
 }

package/src/js/context-menu.js

@@ -48,7 +48,7 @@ function getContextScope(target) {
 }
 
 function getLongPressDelay(target, menu) {
-  const value = target.dataset.contextMenuLongPress ?? menu.dataset.contextMenuLongPress;
+  const value = target.dataset.contextMenuLongPress ?? menu?.dataset.contextMenuLongPress;
   if (value == null || value === "false" || value === "none") return null;
   if (value === "") return LONG_PRESS_MS;
 
@@ -147,21 +147,52 @@ function clearLongPress(state) {
   state.pointerId = null;
 }
 
-function connectContextTarget(target) {
-  if (contextMap.has(target)) return;
+function releaseMenuReference(target, state) {
+  const menu = state.menu;
+  // contextByMenu backs the exported contextFor(): a released menu must not
+  // keep reporting a target it no longer belongs to. The context check keeps
+  // a menu another target has since claimed.
+  if (menu && contextFor(menu)?.context === target) {
+    contextByMenu.delete(menu);
+  }
+  state.releaseMenu?.();
+  state.releaseMenu = null;
+  state.release?.();
+  state.release = null;
+  state.menu = null;
+}
+
+/*
+ * The menu is resolved per interaction, not once at connect: a target can be
+ * declared before its <menu> exists (streamed markup, late AJAX), and a
+ * same-id replacement must rewire to the live element. An unchanged menu
+ * costs a WeakMap read and a connection check; a changed one pays for
+ * releasing the old retain/menu wiring and acquiring the new.
+ */
+function resolveContextMenu(target, state) {
   const menu = menuFor(target);
-  if (!menu) return;
+  if (state.menu === menu && menu?.isConnected) return menu;
 
-  const release = retainSurface(menu);
-  const controller = new AbortController();
-  const releaseMenu = connectMenu(menu, {
+  releaseMenuReference(target, state);
+  if (!menu) return null;
+
+  state.release = retainSurface(menu);
+  state.menu = menu;
+  state.releaseMenu = connectMenu(menu, {
     close: (menu) => closeSurface(menu),
   });
+  return menu;
+}
+
+function connectContextTarget(target) {
+  if (contextMap.has(target)) return;
+
+  const controller = new AbortController();
   const state = {
     controller,
-    releaseMenu,
-    menu,
-    release,
+    releaseMenu: null,
+    menu: null,
+    release: null,
     timer: null,
     pointerId: null,
     startX: 0,
@@ -169,10 +200,15 @@ function connectContextTarget(target) {
     suppressClickUntil: 0,
   };
 
+  resolveContextMenu(target, state);
+
   target.addEventListener(
     "contextmenu",
     (e) => {
       if (shouldIgnoreNativeTarget(e.target)) return;
+      const menu = resolveContextMenu(target, state);
+      // Without a resolvable menu the native context menu stays the fallback.
+      if (!menu) return;
       e.preventDefault();
       e.stopPropagation();
       openContextMenu(target, menu, {
@@ -190,6 +226,8 @@ function connectContextTarget(target) {
     (e) => {
       if (e.key !== "ContextMenu" && !(e.shiftKey && e.key === "F10")) return;
       if (shouldIgnoreNativeTarget(e.target)) return;
+      const menu = resolveContextMenu(target, state);
+      if (!menu) return;
       e.preventDefault();
       openFromKeyboard(target, menu, e.target, target);
     },
@@ -199,7 +237,7 @@ function connectContextTarget(target) {
   target.addEventListener(
     "pointerdown",
     (e) => {
-      const delay = getLongPressDelay(target, menu);
+      const delay = getLongPressDelay(target, menuFor(target));
       if (e.pointerType !== "touch" || delay == null || shouldIgnoreNativeTarget(e.target)) {
         return;
       }
@@ -210,6 +248,8 @@ function connectContextTarget(target) {
       state.startY = e.clientY;
       state.timer = setTimeout(() => {
         state.timer = null;
+        const menu = resolveContextMenu(target, state);
+        if (!menu) return;
         state.suppressClickUntil = Date.now() + LONG_PRESS_CLICK_SUPPRESSION_MS;
         openContextMenu(target, menu, {
           x: state.startX,
@@ -268,6 +308,9 @@ function connectContextTarget(target) {
       )
         return;
 
+      const menu = resolveContextMenu(target, state);
+      if (!menu) return;
+
       e.preventDefault();
       e.stopPropagation();
 
@@ -294,12 +337,10 @@ function disconnectContextTarget(target) {
   if (!state) return;
   clearLongPress(state);
   state.controller.abort();
-  state.releaseMenu?.();
-  if (contextFor(state.menu)?.context === target) {
-    contextByMenu.delete(state.menu);
+  if (state.menu && contextFor(state.menu)?.context === target) {
     closeSurface(state.menu, { restoreFocus: false });
   }
-  state.release();
+  releaseMenuReference(target, state);
   contextMap.delete(target);
 }
 

package/src/js/enhancement-loader.js

@@ -1,10 +1,14 @@
 /*
  * enhancement-loader.js — Server-declared enhancement manifest loader.
  *
- * Reads <script type="application/json" data-enhance-modules"> blocks or
+ * Reads <script type="application/json" data-enhance-modules> blocks or
  * the Enhance-Modules HTTP header, dynamically imports the declared ES
  * module entrypoints, and registers them with the Actual lifecycle engine.
  *
+ * A manifest is trusted application configuration: every declared URL is
+ * imported and executed (or loaded as script/style), so manifests must be
+ * produced by the server — never built from untrusted input.
+ *
  * Manifests declare document-wide modules: dynamically loaded enhancements
  * always register on the default document root. A scope passed to
  * loadEnhancements() only limits where manifest blocks are looked up.

package/src/js/escape.js

@@ -25,7 +25,17 @@ export function registerEscapeDismissal(element, dismiss) {
 }
 
 function onDocumentEscape(event) {
-  if (event.key !== "Escape" || event.ctrlKey || event.altKey || event.shiftKey) return;
+  // A closer handler that consumed the key (defaultPrevented) keeps its
+  // claim; Escape with any modifier is not a dismissal.
+  if (
+    event.defaultPrevented ||
+    event.key !== "Escape" ||
+    event.ctrlKey ||
+    event.altKey ||
+    event.shiftKey ||
+    event.metaKey
+  )
+    return;
 
   const stack = dismissableStacks.get(event.currentTarget);
   const entry = stack.at(-1);

package/src/js/flyout.js

@@ -43,9 +43,14 @@ function onTriggerClick(e) {
   const trigger = e.currentTarget;
   const state = triggerMap.get(trigger);
   if (!state) return;
-  e.stopPropagation();
   const panel = resolvePanel(trigger, state);
   if (!panel) return;
+  // A link trigger is legal markup; the interaction is claimed only once a
+  // panel has actually resolved — an unresolved trigger still navigates and
+  // still bubbles. The stop is what keeps the document-level surface handler
+  // from closing the panel this same click just opened.
+  e.preventDefault();
+  e.stopPropagation();
   if (isSurfaceOpen(panel)) closeSurface(panel);
   else openFlyout(panel, trigger);
 }

package/src/js/focus.js

@@ -17,10 +17,15 @@ const FOCUSABLE_SELECTOR = [
  */
 export function isElementVisible(el) {
   if (!el || el.hidden) return false;
-  if (typeof el.checkVisibility === "function") return el.checkVisibility();
+  if (typeof el.checkVisibility === "function") {
+    // Bare checkVisibility() only tests for a layout box — visibility:hidden
+    // requires the option. Both names are passed because the engines that
+    // shipped first knew it as checkVisibilityCSS.
+    return el.checkVisibility({ visibilityProperty: true, checkVisibilityCSS: true });
+  }
   if (el.getClientRects().length === 0) return false;
-  // checkVisibility() covers visibility:hidden; without it, read the
-  // computed direction of the cascade so a hidden element is not focusable.
+  // The fallback reproduces the option's coverage through the computed style
+  // so a hidden element is not focusable.
   const style = el.ownerDocument?.defaultView?.getComputedStyle?.(el);
   if (!style) return true;
   return style.visibility !== "hidden" && style.visibility !== "collapse";

package/src/js/surface.js

@@ -152,9 +152,36 @@ function ensureSurfaceWired(menu) {
   };
 
   surfaceMap.set(menu, state);
+  menu.addEventListener(EVENTS.dismiss, onSurfaceDismiss);
   return state;
 }
 
+/*
+ * The generic `--dismiss` command hides its target by writing `hidden` — but
+ * on a surface the attribute is not the closed state, the popover transport
+ * is. Left alone it would strand the open lifecycle: the Escape entry, the
+ * position tracker and the is-open class would survive, and openSurface()
+ * would refuse to act on a panel that reads open. The surface therefore
+ * consumes the event to finalize its own lifecycle, rather than dismiss.js
+ * learning about surfaces. `hidden` comes back off once the transport state
+ * is clean; prepareSurface() also strips it on the next open.
+ * A dismissal bubbled from a nested target is not the surface's own.
+ */
+function onSurfaceDismiss(event) {
+  if (event.target !== event.currentTarget) return;
+  const menu = event.currentTarget;
+  // dismiss.js writes `hidden` before dispatching, and hiding an ancestor can
+  // already have dropped focus out of the surface — so the command's trigger,
+  // not activeElement, is the reliable witness of where the activation came
+  // from. A trigger inside the surface means focus was inside it and must be
+  // restored to the opener; a trigger outside keeps focus where it landed.
+  const trigger = event.detail?.trigger;
+  closeSurface(menu, {
+    restoreFocus: trigger ? menu.contains(trigger) : undefined,
+  });
+  menu.removeAttribute("hidden");
+}
+
 // Escape and positional tracking belong to the *open* surface, not to the
 // wiring. They start when the surface opens and stop when it closes, so a
 // closed surface never participates in the dismissable stack or in
@@ -341,6 +368,7 @@ export function closeSurface(menu, opts = {}) {
 export function disconnectSurface(menu) {
   if (!menu) return;
   closeSurface(menu);
+  menu.removeEventListener(EVENTS.dismiss, onSurfaceDismiss);
   const state = surfaceMap.get(menu);
   if (state) {
     state.unregisterEscape?.();

package/src/js/tooltip.js

@@ -24,7 +24,7 @@
  *             work automatically via bubbling delegated listeners.
  *
  * Show:       hover + focus (150ms delay), click toggle, or always visible
- * Hide:       blur, pointer leave, Escape
+ * Hide:       focus leaving the trigger (focusout), pointer leave, Escape
  *
  * Geometry:   a trigger scrolled out of the positioning boundary takes its tip
  *             down and keeps it tracked, so scrolling back brings the same tip
@@ -420,8 +420,12 @@ function ensureTip(trigger) {
     { signal: triggerController.signal },
   );
   trigger.addEventListener(
-    "blur",
-    () => {
+    // blur does not bubble: on a composite trigger (focusable children) the
+    // loss of focus is only observable through focusout. relatedTarget keeps
+    // a focus move between the trigger's own children from ending the tip.
+    "focusout",
+    (event) => {
+      if (event.relatedTarget && trigger.contains(event.relatedTarget)) return;
       state.focused = false;
       scheduleHide(tip);
     },
@@ -489,8 +493,10 @@ function handleTriggerIntent(e) {
   const trigger = e.target.closest?.(SEL);
   if (!trigger) return;
   if (isClickTrigger(trigger) || isAlwaysVisible(trigger)) return;
+  // A pointer or focus move between the trigger's own children is not a new
+  // intent: it must not restart the show delay or rewrite the intent flags.
   if (
-    e.type === "mouseover" &&
+    (e.type === "mouseover" || e.type === "focusin") &&
     e.relatedTarget instanceof Node &&
     trigger.contains(e.relatedTarget)
   )