actual-css 0.2.0 → 0.3.0

package/src/css/tokens.css

@@ -1,4 +1,21 @@
 :root {
+  /*
+   * Global framework tokens.
+   *
+   * Public: properties in the named groups below are public API (typography,
+   * spacing, shape, motion, focus, controls, viewport, z-index, icons) unless
+   * a group is explicitly marked Internal or Derived.
+   *
+   * Derived: "Theme-derived aliases" and "State tokens" reference intent and
+   * surface tokens and follow the theme; do not hard-code values into them.
+   * Internal: indicator offsets, --bar-height, --disabled-opacity and the
+   * like are consumed by components, not authored.
+   *
+   * Component-local hooks and internal state relays live with their
+   * components. See docs/pages/foundations/tokens.md for the public/internal
+   * token contract.
+   */
+
   /* Typography */
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
@@ -16,20 +33,22 @@
   --font-size-md: 1rem;
   --font-size-lg: 1.125rem;
 
-  /* Spacing */
+  /* Spacing — official steps are named in tens so the scale stays open for
+     application themes to intercalate intermediate values (--space-15,
+     --space-45…) without colliding with future framework steps. */
   --gap: 0.75rem;
-  --variant-space: var(--space-4);
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-3: 0.75rem;
-  --space-4: 1rem;
-  --space-5: 1.5rem;
-  --space-6: 2rem;
+  --density-space: var(--space-40);
+  --density-compact-size: 1.5rem;
+  --space-10: 0.25rem;
+  --space-20: 0.5rem;
+  --space-30: 0.75rem;
+  --space-40: 1rem;
+  --space-50: 1.5rem;
+  --space-60: 2rem;
 
   /* Shape */
   --border-width: 1px;
   --radius-full: 9999px;
-  --shadow-xs: 0 1px 2px rgb(0 0 0 / 0.04);
   --shadow: 0 1px 3px rgb(0 0 0 / 0.05), 0 4px 12px rgb(0 0 0 / 0.04);
   --shadow-popout: 0 0.25rem 0.75rem rgb(0 0 0 / 0.15);
 
@@ -53,7 +72,6 @@
      the circle-aware inset (1 - 1/√2) / 2 ≈ 14.65%; the ring surrounds the
      dot with the parent surface color. */
   --indicator-offset: 14.65%;
-  --indicator-ring: var(--surface);
 
   /* Shared backdrop — consumed by modal, drawer, and mobile flyout sheets. */
   --backdrop-color: rgb(0 0 0);
@@ -64,7 +82,8 @@
   --bar-height: 0.65rem;
 
   /* Controls — inputs and buttons share --control-size so heights always match.
-     .sm/.lg (variants.css) switch --control-size and --control-font-size. */
+     .sm/.lg (variants.css) switch --control-size; --control-font-size stays
+     at its baseline because density does not change typography. */
   --control-size-sm: 2rem;
   --control-size-md: 2.375rem;
   --control-size-lg: 2.75rem;
@@ -72,19 +91,38 @@
   --control-pad-x: 1em;
   --control-font-size: var(--font-size-md);
   --disabled-opacity: 0.65;
+}
+
+/* Theme-derived aliases. These reference intent/surface tokens, so they must
+   be re-declared on every theme boundary: a custom property resolves its
+   var() references at computed-value time on the element that declares it,
+   so an alias declared only on :root is inherited as an already-resolved
+   value and would not follow a [data-theme] island's overridden tokens.
+   Themes that want a distinct alias override it explicitly afterwards. */
+:root,
+[data-theme] {
+  /* State tokens — semantic colors for selected/pressed/current and disabled.
+     Components consume these instead of hard-wiring --primary/--text-subtle
+     so forced-colors can override them in one place. */
+  --state-selected: var(--primary);
+  --state-selected-fg: var(--primary-fg);
+  --state-disabled: var(--text-subtle);
+
+  /* Status dot ring — follows the island's surface. */
+  --indicator-ring: var(--surface);
+}
 
+:root {
   /* Variant tuning — themes may adjust generated soft surfaces without
      replacing the component rules. */
   --soft-bg-mix: 88%;
   --soft-border-mix: 65%;
   --soft-hover-alpha: 12%;
 
-  /* Shared icons */
-  --icon-chevron-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
-  --icon-check-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='20 6 9 17 4 12'/%3E%3C/svg%3E");
-  /* Native select uses background-image, which cannot inherit currentColor.
-     The stroke matches the default theme's text-subtle (hue 258 neutral). */
-  --icon-chevron-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%238a8594' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
+  /* Shared icon assets. Override these URLs when a strict CSP disallows data:. */
+  --icon-chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%238a8594' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E");
+  --icon-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='20 6 9 17 4 12'/%3E%3C/svg%3E");
+  --icon-close: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cline x1='6' y1='6' x2='18' y2='18'/%3E%3Cline x1='18' y1='6' x2='6' y2='18'/%3E%3C/svg%3E");
 
   /* Viewport size tokens — fallback vh/vw with dvh/vi enhancement.
      Consumed by full-viewport components (app-shell, drawer, modal, flyout).
@@ -93,13 +131,24 @@
   --viewport-block: 100vh;
   --viewport-inline: 100vw;
 
-  /* Layering */
+  /* Z-index scale — used ONLY by non-dialog overlays (see the layering
+     note below for the full model). Actual CSS reserves multiples of 10 for
+     framework layers; applications may use intermediate values for local
+     layering. */
   --z-sticky: 10;
   --z-menu: 20;
   --z-tooltip: 50;
   --z-status: 60;
 }
 
+@media (forced-colors: active) {
+  :root {
+    --state-selected: Highlight;
+    --state-selected-fg: HighlightText;
+    --state-disabled: GrayText;
+  }
+}
+
 @supports (block-size: 100dvh) {
   :root {
     --viewport-block: 100dvh;
@@ -113,12 +162,17 @@
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  :root {
-    --shadow-xs: 0 1px 2px color-mix(in oklch, var(--shadow-color) 4%, transparent);
+  :root,
+  [data-theme] {
+    /* Shadows derive from --shadow-color (theme.css) — re-declared on every
+       theme boundary so islands follow their own shadow-color. */
     --shadow:
       0 1px 3px color-mix(in oklch, var(--shadow-color) 5%, transparent),
       0 4px 12px color-mix(in oklch, var(--shadow-color) 4%, transparent);
     --shadow-popout: 0 0.25rem 0.75rem color-mix(in oklch, var(--shadow-color) 15%, transparent);
+  }
+
+  :root {
     --backdrop-fill: color-mix(
       in oklch,
       var(--backdrop-color) calc(var(--backdrop-opacity) * 100%),

package/src/css/utilities.css

@@ -30,7 +30,7 @@
   min-inline-size: 0;
 }
 
-.nowrap {
+.text-nowrap {
   white-space: nowrap;
 }
 
@@ -125,15 +125,13 @@
   text-decoration: none;
 }
 
-@media (hover: hover) {
-  .link-muted:hover {
-    color: var(--text);
-  }
+.link-muted:hover {
+  color: var(--text);
 }
 
 /* Spacing step helpers — semantic scale (sm / default / lg).
    Names map to logical properties for writing-direction safety. The default
-   step uses --space-4, which matches the framework's built-in padding on
+   step uses --space-40, which matches the framework's built-in padding on
    cards, dialogs, and form-actions. */
 
 /* Gap */
@@ -143,20 +141,20 @@
 
 /* Padding — block (vertical) */
 .py {
-  padding-block: var(--variant-space);
+  padding-block: var(--density-space);
 }
 
 /* Padding — inline (horizontal) */
 .px {
-  padding-inline: var(--variant-space);
+  padding-inline: var(--density-space);
 }
 
 /* Margin — block-start */
 .mbs {
-  margin-block-start: var(--variant-space);
+  margin-block-start: var(--density-space);
 }
 
 /* Margin — block-end */
 .mbe {
-  margin-block-end: var(--variant-space);
+  margin-block-end: var(--density-space);
 }

package/src/css/variants.css

@@ -2,15 +2,20 @@
  * Cross-cutting variant token mapping.
  *
  * Variant scope: .solid/.soft/.outline set --ui-* for components that opt into
- * shared variants. Component-specific defaults (.btn solid-by-default, .badge
- * solid-by-default, .alert soft-by-default) live with their components:
+ * shared variants. .inverted is a surface modifier, not a variant: it also
+ * paints the element directly (background/color/border-color) so it works on
+ * any block, competing with component surface treatments (.card.subtle).
+ * Component-specific defaults (.btn solid-by-default, .badge
+ * soft-by-default, .alert soft-by-default) live with their components:
  *   components/button.css — .btn default solid + .btn.ghost + .btn.link
- *   components/badge.css   — .badge default solid
- *   components/alert.css   — .alert default + .alert.solid/.alert.outline
+ *   components/badge.css   — .badge default soft
+ *   components/alert.css   — .alert default soft (consumes --ui-* directly)
  *
- * .sm/.lg set shared size tokens. Controls consume --control-*; non-control
- * components may consume --variant-* when the variant should affect their
- * local density. Compact components may consume --variant-compact-*.
+ * .sm/.lg set shared density tokens: spacing rhythm and geometry only.
+ * Density never changes typography — controls keep their font-size and
+ * content components keep theirs. Controls consume --control-size; non-control
+ * components may consume --density-* when the density context should affect
+ * their local rhythm. Compact components may consume --density-compact-size.
  * Components with bespoke sizing (spinner, avatar) define local .sm/.lg;
  * applying .sm/.lg to card, dialog, accordion, navbar, table is
  * a no-op.
@@ -36,27 +41,34 @@
   --ui-border: var(--intent, var(--border));
 }
 
+/* Inverse surface treatment. Components (e.g. .card) compose through --ui-*;
+   the direct background/color/border-color also make .inverted useful on a
+   generic element. --heading is set so global headings (var(--heading, inherit))
+   do not inherit an outside heading color onto the dark surface. */
+.inverted {
+  --ui-bg: var(--surface-solid);
+  --ui-fg: var(--surface);
+  --ui-border: transparent;
+
+  --heading: var(--surface);
+  --busy-overlay-bg: var(--surface-solid);
+
+  background: var(--ui-bg);
+  color: var(--ui-fg);
+  border-color: var(--ui-border);
+}
+
 .sm {
-  --gap: var(--space-2);
-  --variant-space: var(--space-2);
+  --gap: var(--space-20);
+  --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
-  --control-font-size: var(--font-size-sm);
-  --variant-font-size: var(--font-size-sm);
-  --variant-icon-size: 1rem;
-  --variant-pad-block: var(--space-3);
-  --variant-compact-size: 1.25rem;
-  --variant-compact-font-size: 0.75rem;
+  --density-compact-size: 1.25rem;
 }
 .lg {
-  --gap: var(--space-5);
-  --variant-space: var(--space-5);
+  --gap: var(--space-50);
+  --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
-  --control-font-size: var(--font-size-lg);
-  --variant-font-size: var(--font-size-lg);
-  --variant-icon-size: 1.5rem;
-  --variant-pad-block: var(--space-5);
-  --variant-compact-size: 1.875rem;
-  --variant-compact-font-size: var(--font-size-sm);
+  --density-compact-size: 1.875rem;
 }
 
 /* Modern color enhancement. Baseline variant values above remain usable
@@ -74,45 +86,5 @@
   }
 }
 
-/* Interactive hover recipe shared by .btn and .badge. Declared outside :hover
-   on purpose: --ui-hover-bg is only consumed inside their @media (hover: hover)
-   rules, so these values are inert until hovered. :is() carries real
-   specificity so the components' :where() intent boundaries
-   (--ui-hover-bg: initial) cannot override the recipe. The solid/soft overlay
-   darkening lives in the consuming components. */
-:is(.btn, a.badge, button.badge):is(.outline, .ghost) {
-  --ui-hover-bg: var(--surface-subtle);
-}
-
-@supports (color: color-mix(in oklch, red, white)) {
-  /* Solid has no literal class requirement: bare .btn/.badge default to solid,
-     so this must match anything that isn't one of the other variants rather
-     than an explicit .solid class. Stacks with the box-shadow overlay the
-     consuming components apply on top for extra depth. */
-  :is(.btn, a.badge, button.badge):not(:where(.soft, .outline, .ghost, .link)) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
-  }
-
-  /* Same recipe as the resting .soft bg with the surface share reduced by
-     --soft-hover-alpha: stays opaque, so it reads on any backdrop instead of
-     letting the container show through on hover. */
-  :is(.btn, a.badge, button.badge):is(.soft) {
-    --ui-hover-bg: color-mix(
-      in oklch,
-      var(--surface) calc(var(--soft-bg-mix) - var(--soft-hover-alpha)),
-      var(--intent, var(--neutral))
-    );
-  }
-
-  /* Mixed against the opaque --surface-subtle rather than transparent: a
-     transparent-based tint reads clean on light surfaces but goes muddy and
-     low-contrast on dark ones, since the same low alpha lands very
-     differently over a light vs. a near-black backdrop. */
-  :is(.btn, a.badge, button.badge):is(.outline) {
-    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
-  }
-
-  :is(.btn, a.badge, button.badge):is(.ghost) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--text)) 8%, transparent);
-  }
-}
+/* Interactive hover recipes live in the components that consume them:
+     components/button.css and components/badge.css. */

package/src/js/command.js

@@ -25,9 +25,7 @@ function commandNames(commands, caller) {
 // Native command keywords are ASCII case-insensitive. Custom commands keep
 // their exact spelling, as required by the command invoker contract.
 function commandKey(command) {
-  return command.startsWith("--")
-    ? command
-    : command.replace(/[A-Z]/g, (character) => character.toLowerCase());
+  return command.startsWith("--") ? command : command.toLowerCase();
 }
 
 /**

package/src/js/context-menu.js

@@ -1,17 +1,16 @@
 import enhance from "./enhance.js";
 import { EVENTS } from "./events.js";
-import { focusFirstMenuItem, hasMenuItems } from "./menu.js";
-import { closeSurface, isSurfaceOpen, openSurface, prepareSurface } from "./surface.js";
+import { connectMenu, focusFirstMenuItem, hasMenuItems } from "./menu.js";
+import { closeSurface, isSurfaceOpen, openSurface, retainSurface } from "./surface.js";
 
 const LONG_PRESS_MS = 450;
+const LONG_PRESS_CLICK_SUPPRESSION_MS = 750;
 const MOVE_TOLERANCE = 10;
 const CONTEXT_MENU_SELECTOR = 'menu, [role="menu"]';
 const CONTEXT_TARGET_SELECTOR = "[data-context-menu]";
 const contextMap = new WeakMap();
 const contextByMenu = new WeakMap();
 
-// Returns the detail from the last accepted `actual:context-menu` event for a
-// menu. This is intentionally optional: static menus need no application JS.
 export function contextFor(menu) {
   return contextByMenu.get(menu) || null;
 }
@@ -48,27 +47,29 @@ function getLongPressDelay(target, menu) {
   if (value === "") return LONG_PRESS_MS;
 
   const delay = Number.parseInt(value, 10);
-  return Number.isFinite(delay) ? delay : LONG_PRESS_MS;
+  return Number.isFinite(delay) ? Math.max(0, delay) : LONG_PRESS_MS;
+}
+
+function readPanelOptions(menu) {
+  const opts = { autoClose: "true" };
+  const ds = menu.dataset;
+  if (ds.flyoutMobile) opts.mobile = ds.flyoutMobile;
+  if (ds.flyoutAutoClose) opts.autoClose = ds.flyoutAutoClose;
+  return opts;
 }
 
 function focusMenuContainer(menu) {
   if (!menu.hasAttribute("tabindex")) {
     menu.tabIndex = -1;
   }
-  menu.focus();
+  // Moving the mounted menu into the surface root must not scroll the page.
+  // Genuine user scrolling is handled separately by the surface policy.
+  menu.focus({ preventScroll: true });
 }
 
-// Pointer-triggered opens (right-click, long-press) focus the menu container,
-// not the first item: a pointer-set focus ring is invisible (:focus-visible
-// doesn't match), so focusing "Open" makes the first ArrowDown look like it
-// skips to the second item. Focusing the container keeps the ring hidden and
-// lets keys.js's out-of-list fallback (indexOf === -1) land ArrowDown/ArrowUp
-// on the first/last item, matching native OS context menus. Keyboard-triggered
-// opens (openFromKeyboard) still focus the first item directly.
 function focusMenu(menu, mode) {
-  if (!hasMenuItems(menu)) return;
   if (mode === "first-item") {
-    focusFirstMenuItem(menu);
+    if (hasMenuItems(menu)) focusFirstMenuItem(menu);
   } else {
     focusMenuContainer(menu);
   }
@@ -101,9 +102,11 @@ function openContextMenu(context, menu, opts = {}) {
       y: opts.y,
       placement: opts.placement || "bottom-start",
       distance: opts.distance ?? 2,
-      mobile: opts.mobile || menu.dataset.flyoutMobile || "auto",
+      dismissOnScroll: true,
+      mobile: opts.mobile || "auto",
       scope: opts.scope || getContextScope(context),
       restoreFocusTo: opts.restoreFocusTo,
+      ...readPanelOptions(menu),
     })
   ) {
     focusMenu(menu, opts.focus);
@@ -137,11 +140,16 @@ function connectContextTarget(target) {
   const menu = menuFor(target);
   if (!menu) return;
 
-  prepareSurface(menu);
+  const release = retainSurface(menu);
   const controller = new AbortController();
+  const releaseMenu = connectMenu(menu, {
+    close: (menu) => closeSurface(menu),
+  });
   const state = {
     controller,
+    releaseMenu,
     menu,
+    release,
     timer: null,
     pointerId: null,
     startX: 0,
@@ -190,7 +198,7 @@ function connectContextTarget(target) {
       state.startY = e.clientY;
       state.timer = setTimeout(() => {
         state.timer = null;
-        state.suppressClickUntil = Date.now() + 750;
+        state.suppressClickUntil = Date.now() + LONG_PRESS_CLICK_SUPPRESSION_MS;
         openContextMenu(target, menu, {
           x: state.startX,
           y: state.startY,
@@ -238,6 +246,45 @@ function connectContextTarget(target) {
     { signal: controller.signal, capture: true },
   );
 
+  target.addEventListener(
+    "click",
+    (e) => {
+      const trigger = e.target.closest("[data-context-menu-trigger]");
+      if (
+        !trigger ||
+        trigger.getAttribute("aria-controls") !== target.getAttribute("data-context-menu")
+      )
+        return;
+
+      e.preventDefault();
+      e.stopPropagation();
+
+      if (isSurfaceOpen(menu)) {
+        closeSurface(menu);
+        return;
+      }
+
+      if (!requestContextMenu(target, menu, { origin: trigger, trigger: "button" })) return;
+
+      const rect = trigger.getBoundingClientRect();
+      if (
+        openSurface(menu, {
+          source: target,
+          x: rect.left,
+          y: rect.bottom,
+          placement: "bottom-start",
+          distance: 4,
+          dismissOnScroll: true,
+          restoreFocusTo: trigger,
+          ...readPanelOptions(menu),
+        })
+      ) {
+        focusMenuContainer(menu);
+      }
+    },
+    { signal: controller.signal },
+  );
+
   contextMap.set(target, state);
 }
 
@@ -246,33 +293,18 @@ function disconnectContextTarget(target) {
   if (!state) return;
   clearLongPress(state);
   state.controller.abort();
+  state.releaseMenu?.();
   if (contextFor(state.menu)?.context === target) {
     contextByMenu.delete(state.menu);
     closeSurface(state.menu, { restoreFocus: false });
   }
+  state.release();
   contextMap.delete(target);
 }
 
-function onSurfaceOpen(event) {
-  const options = event.detail?.options;
-  const trigger = options?.trigger;
-  const context = trigger?.closest?.(CONTEXT_TARGET_SELECTOR);
-  if (!context || menuFor(context) !== event.detail?.surface) return;
-  if (!requestContextMenu(context, event.detail.surface, { origin: trigger, trigger: "button" })) {
-    event.preventDefault();
-    return;
-  }
-  options.source = context;
-  options.restoreFocusTo = trigger;
-}
-
 enhance({
   [CONTEXT_TARGET_SELECTOR]: (target) => {
     connectContextTarget(target);
     return () => disconnectContextTarget(target);
   },
 });
-
-if (typeof document !== "undefined") {
-  document.addEventListener(EVENTS.surfaceOpen, onSurfaceOpen);
-}