actual-css 0.9.2 → 0.11.0

package/src/js/enhance.js

@@ -1,27 +1,29 @@
 /*
  * Enhance — DOM lifecycle engine for behavioral enhancers.
  *
- * One MutationObserver per root watches DOM insertions/removals. Multiple calls
- * to enhance() share that observer while keeping separate teardown handles.
+ * One MutationObserver per root watches DOM insertions/removals and serves
+ * every enhance() and registerEnhancement() record on that root, each with
+ * its own teardown handle. A record pairs a discovery query with
+ * selector-keyed initialisers: enhance() queries its own selectors; a named
+ * enhancement keys `[data-enhance~="name"]` behind the shared
+ * `[data-enhance]` query, so any number of named behaviors cost the root a
+ * single discovery gate.
  *
  * Sweep (not removedNodes scanning) is the key design choice: it reasons
  * about final state after a batch, so a moved element (removed then
  * reinserted in the same batch) survives without a spurious disconnect.
  *
- * Attribute changes are intentionally not observed. Call refresh(node) after
- * adding a behavior attribute to an already-connected element. Behavior
- * attributes are setup-time contracts, not live enable/disable switches.
+ * Attribute changes are intentionally not observed. The owner of a handle
+ * calls refresh(node) after adding a behavior attribute to an
+ * already-connected element; for a data-enhance token, applyEnhancement()
+ * does it. The built-in data-* behaviors (mask, filter, context menu, …)
+ * keep their handle private, so for them insert the element with the
+ * attribute already set. Behavior attributes are setup-time contracts, not
+ * live enable/disable switches.
  *
- * enhancers: { [selector]: (el) => cleanup | void }
- * Returns: { refresh, disconnect }
- *
- * Enhancement tokens — the data-enhance layer on top of enhance().
- *
- * enhancementSelector("tabs") returns [data-enhance~="tabs"], the generic
- * opt-in for root-controller behaviors. registerEnhancement() owns a name per
- * root — a second registration for the same name on the same root throws, and
- * disconnect() releases ownership. Third-party behaviors register exactly
- * like built-in ones.
+ * registerEnhancement() owns a name per root — a second registration for the
+ * same name on the same root throws, and disconnect() releases ownership.
+ * Third-party behaviors register exactly like built-in ones.
  *
  * See docs/design-notes/enhancement-contract.md.
  */
@@ -35,6 +37,8 @@ const ELEMENT_NODE = 1;
 const DOCUMENT_NODE = 9;
 const DOCUMENT_FRAGMENT_NODE = 11;
 
+const ENHANCEMENT_NAME = /^[a-z][a-z0-9-]*$/;
+
 function noopRuntime() {
   return {
     refresh() {},
@@ -52,50 +56,30 @@ function canScan(node) {
 
 function createRegistry(root) {
   const records = new Set();
-  let selectorString = "";
-
-  function isValidSelector(selector) {
-    try {
-      root.querySelector?.(selector);
-      if (root.nodeType === ELEMENT_NODE) root.matches(selector);
-      return true;
-    } catch (error) {
-      console.error(`Invalid enhancer selector "${selector}"`, error);
-      return false;
-    }
-  }
-
-  function updateSelectorString() {
-    selectorString = [...records].flatMap((record) => record.selectors).join(",");
-  }
+  let discovery = "";
 
   function start(record, el) {
-    if (el?.nodeType !== ELEMENT_NODE) return;
     let active = record.instances.get(el);
-
-    for (const selector of record.selectors) {
-      if (!el.matches(selector)) continue;
-      if (active?.has(selector)) continue;
+    for (const key of record.keys) {
+      if (active?.has(key) || !el.matches(key)) continue;
 
       let cleanup;
       try {
-        cleanup = record.enhancers[selector](el);
+        cleanup = record.enhancers[key](el);
       } catch (error) {
-        console.error(`Enhancer failed for selector "${selector}"`, error);
+        console.error(`Enhancer "${key}" failed`, error);
         continue;
       }
       if (!active) {
         active = new Map();
         record.instances.set(el, active);
       }
-      active.set(selector, typeof cleanup === "function" ? cleanup : null);
+      active.set(key, typeof cleanup === "function" ? cleanup : null);
     }
   }
 
   function stop(record, el) {
-    const active = record.instances.get(el);
-    if (!active) return;
-    for (const cleanup of active.values()) {
+    for (const cleanup of record.instances.get(el)?.values() ?? []) {
       try {
         cleanup?.();
       } catch (error) {
@@ -105,24 +89,13 @@ function createRegistry(root) {
     record.instances.delete(el);
   }
 
-  function scanFor(record, node) {
-    if (!canScan(node)) return;
-    if (node.nodeType === ELEMENT_NODE) start(record, node);
-    if (record.selectorString) {
-      node.querySelectorAll?.(record.selectorString).forEach((el) => {
-        start(record, el);
-      });
-    }
-  }
-
-  function scan(node) {
-    if (!canScan(node) || !selectorString) return;
-    if (node.nodeType === ELEMENT_NODE) {
-      for (const record of records) start(record, node);
-    }
-    node.querySelectorAll?.(selectorString).forEach((el) => {
-      for (const record of records) start(record, el);
-    });
+  function scan(node, targets, selector) {
+    if (!canScan(node) || !selector) return;
+    const visit = (el) => {
+      for (const record of targets) start(record, el);
+    };
+    if (node.nodeType === ELEMENT_NODE) visit(node);
+    node.querySelectorAll(selector).forEach(visit);
   }
 
   function sweepDisconnected() {
@@ -133,11 +106,16 @@ function createRegistry(root) {
     }
   }
 
+  function updateDiscovery() {
+    // Named records all share `[data-enhance]`; the Set collapses them.
+    discovery = [...new Set(Array.from(records, (record) => record.query))].join(",");
+  }
+
   const observer = new MutationObserver((mutationRecords) => {
     let hasRemoval = false;
     for (const mutationRecord of mutationRecords) {
       for (const node of mutationRecord.addedNodes) {
-        scan(node);
+        scan(node, records, discovery);
       }
       if (mutationRecord.removedNodes.length > 0) {
         hasRemoval = true;
@@ -147,61 +125,52 @@ function createRegistry(root) {
   });
 
   return {
-    add(enhancers) {
-      const selectors = Object.keys(enhancers).filter(isValidSelector);
-      if (!selectors.length) return null;
-      const validEnhancers = Object.fromEntries(
-        selectors.map((selector) => [selector, enhancers[selector]]),
-      );
-
-      const record = {
-        disconnected: false,
-        enhancers: validEnhancers,
-        instances: new Map(),
-        selectors,
-        selectorString: selectors.join(","),
-      };
+    add(spec) {
+      const record = { ...spec, disconnected: false, instances: new Map() };
       records.add(record);
       // Observe only once there is a record to act on; an enhance() call with
       // no valid selector must not leave an idle observer behind.
       if (records.size === 1) observer.observe(root, { childList: true, subtree: true });
-      updateSelectorString();
-      scanFor(record, root);
-      return record;
-    },
-    refresh(record, node) {
-      if (record.disconnected) return;
-      scanFor(record, node);
-    },
-    remove(record) {
-      if (record.disconnected) return;
-      record.disconnected = true;
-      for (const el of Array.from(record.instances.keys())) {
-        stop(record, el);
-      }
-      records.delete(record);
-      updateSelectorString();
-      if (records.size === 0) {
-        observer.disconnect();
-        registries.delete(root);
-      }
+      updateDiscovery();
+      scan(root, [record], record.query);
+
+      return {
+        refresh(node) {
+          if (!record.disconnected) scan(node, [record], record.query);
+        },
+        disconnect() {
+          if (record.disconnected) return;
+          record.disconnected = true;
+          for (const el of Array.from(record.instances.keys())) stop(record, el);
+          records.delete(record);
+          updateDiscovery();
+          if (records.size) return;
+          observer.disconnect();
+          registries.delete(root);
+        },
+      };
     },
   };
 }
 
-const ENHANCEMENT_NAME = /^[a-z][a-z0-9-]*$/;
+function registryFor(root) {
+  let registry = registries.get(root);
+  if (!registry) {
+    registry = createRegistry(root);
+    registries.set(root, registry);
+  }
+  return registry;
+}
 
-export function enhancementSelector(name) {
+// The name check is what keeps the interpolation safe: a quote or space in a
+// name would otherwise break or widen the selector.
+function enhancementSelector(name) {
   if (!ENHANCEMENT_NAME.test(name)) {
     throw new TypeError(`Invalid enhancement name: ${name}`);
   }
   return `[data-enhance~="${name}"]`;
 }
 
-export function hasEnhancement(el, name) {
-  return el.matches(enhancementSelector(name));
-}
-
 /**
  * Apply a named opt-in once; presentation selectors remain application-owned.
  * @param {string} name
@@ -212,12 +181,12 @@ export function hasEnhancement(el, name) {
 export function applyEnhancement(name, selector, root) {
   if (typeof document === "undefined") return [];
 
-  enhancementSelector(name);
+  const enhanced = enhancementSelector(name);
   root ??= document.documentElement;
   const elements = [...root.querySelectorAll(selector)];
 
   for (const el of elements) {
-    if (hasEnhancement(el, name)) continue;
+    if (el.matches(enhanced)) continue;
     const tokens = el.getAttribute("data-enhance");
     el.setAttribute("data-enhance", tokens ? `${tokens} ${name}` : name);
   }
@@ -236,7 +205,7 @@ export function applyEnhancement(name, selector, root) {
 export function registerEnhancement(name, init, root) {
   if (typeof document === "undefined") return noopRuntime();
 
-  enhancementSelector(name);
+  const selector = enhancementSelector(name);
   if (typeof init !== "function") {
     throw new TypeError("registerEnhancement() requires a function init.");
   }
@@ -251,7 +220,11 @@ export function registerEnhancement(name, init, root) {
     throw new Error(`Enhancement "${name}" is already registered on this root.`);
   }
 
-  const runtime = enhance({ [enhancementSelector(name)]: init }, root);
+  const runtime = registryFor(root).add({
+    keys: [selector],
+    enhancers: { [selector]: init },
+    query: "[data-enhance]",
+  });
   names.set(name, runtime);
 
   return {
@@ -264,34 +237,26 @@ export function registerEnhancement(name, init, root) {
   };
 }
 
-function registryFor(root) {
-  let registry = registries.get(root);
-  if (!registry) {
-    registry = createRegistry(root);
-    registries.set(root, registry);
-  }
-  return registry;
-}
-
 /**
  * @param {Record<string, (el: Element) => (() => void) | void>} enhancers
  * @param {Document | Element | DocumentFragment} [root]
  * @returns {{ refresh: (node: Node) => void, disconnect: () => void }}
  */
 export default function enhance(enhancers, root) {
-  if (typeof document === "undefined") {
-    return noopRuntime();
-  }
+  if (typeof document === "undefined") return noopRuntime();
 
   root ??= document.documentElement;
-  const registry = registryFor(root);
-  const record = registry.add(enhancers);
-  if (!record) return noopRuntime();
+  const keys = Object.keys(enhancers).filter((selector) => {
+    try {
+      root.querySelector?.(selector);
+      if (root.nodeType === ELEMENT_NODE) root.matches(selector);
+      return true;
+    } catch (error) {
+      console.error(`Invalid enhancer selector "${selector}"`, error);
+      return false;
+    }
+  });
+  if (!keys.length) return noopRuntime();
 
-  return {
-    refresh: (node) => registry.refresh(record, node),
-    disconnect: () => {
-      registry.remove(record);
-    },
-  };
+  return registryFor(root).add({ keys, enhancers, query: keys.join(",") });
 }

package/src/js/escape.js

@@ -30,6 +30,7 @@ function onDocumentEscape(event) {
   if (
     event.defaultPrevented ||
     event.key !== "Escape" ||
+    event.isComposing ||
     event.ctrlKey ||
     event.altKey ||
     event.shiftKey ||

package/src/js/flyout.js

@@ -1,5 +1,6 @@
 import { registerEnhancement } from "./enhance.js";
 import { focusFirstDescendant } from "./focus.js";
+import { shouldIgnoreKey } from "./keys.js";
 import { connectMenu, focusFirstMenuItem, focusLastMenuItem } from "./menu.js";
 import { closeSurface, isSurfaceOpen, openSurface, retainSurface } from "./surface.js";
 
@@ -26,6 +27,13 @@ function isMenuFlyout(panel) {
   return panel.matches("menu") || panel.classList.contains("menu");
 }
 
+// ARIA-wise only [role="menu"] is a menu: <menu> carries the implicit list
+// role and .menu is a visual class. aria-haspopup="menu" must follow the
+// role, not the tag or class.
+function isAriaMenu(panel) {
+  return panel.getAttribute("role") === "menu";
+}
+
 function openFlyout(panel, trigger) {
   return openSurface(panel, {
     trigger,
@@ -57,6 +65,7 @@ function onTriggerClick(e) {
 
 function onTriggerKeydown(e) {
   const trigger = e.currentTarget;
+  if (shouldIgnoreKey(e)) return;
   const state = triggerMap.get(trigger);
   if (!state) return;
   const panel = resolvePanel(trigger, state);
@@ -153,7 +162,7 @@ function resolvePanel(trigger, state) {
       close: (menu) => closeSurface(menu),
     });
   }
-  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(panel)) {
+  if (!trigger.hasAttribute("aria-haspopup") && isAriaMenu(panel)) {
     trigger.setAttribute("aria-haspopup", "menu");
   }
 

package/src/js/focus-group.js

@@ -5,7 +5,7 @@
  * candidate list; the primitive does not observe the subtree.
  */
 
-import { itemForKey } from "./keys.js";
+import { itemForKey, shouldIgnoreKey } from "./keys.js";
 
 const ORIENTATIONS = new Set(["horizontal", "vertical"]);
 
@@ -82,6 +82,7 @@ export function connectFocusGroup(root, opts = {}) {
   }
 
   function onKeydown(event) {
+    if (shouldIgnoreKey(event)) return;
     const items = sync();
     const current = root.ownerDocument.activeElement;
     if (!items.includes(current)) return;

package/src/js/full.js

@@ -21,6 +21,7 @@ import "./scrollspy.js";
 import "./filter.js";
 import "./mask.js";
 import "./password.js";
+import "./range.js";
 import "./validation.js";
 import "./status.js";
 import "./index.js";

package/src/js/keys.js

@@ -5,6 +5,20 @@
  * centralize item lookup, edge handling, and optional wrapping.
  */
 
+// Shared guard for roving-focus key handlers. Composition (IME) and
+// ctrl/alt/meta-modified keys belong to the input method or the browser
+// (Alt+Arrow = history navigation) and must never be claimed by a widget.
+// Shift is deliberately excluded: Shift+Tab carries focus semantics that
+// callers handle themselves.
+export function shouldIgnoreKey(event) {
+  return (
+    event?.isComposing === true ||
+    event?.ctrlKey === true ||
+    event?.altKey === true ||
+    event?.metaKey === true
+  );
+}
+
 export function firstItem(items) {
   return items[0] || null;
 }

package/src/js/menu.js

@@ -10,7 +10,7 @@
 
 import { isElementVisible } from "./focus.js";
 import { connectFocusGroup } from "./focus-group.js";
-import { firstItem, itemForKey, lastItem } from "./keys.js";
+import { firstItem, itemForKey, lastItem, shouldIgnoreKey } from "./keys.js";
 
 const MENU_ITEM_SELECTOR = ":scope > li > .menu-item";
 const MENU_ITEM_ROLES = new Set(["menuitem", "menuitemcheckbox", "menuitemradio"]);
@@ -62,6 +62,7 @@ export function focusLastMenuItem(menu) {
 }
 
 export function onMenuKeydown(e, { close, navigate = true }) {
+  if (shouldIgnoreKey(e)) return;
   const menu = e.currentTarget;
   if (navigate) {
     const items = getMenuItems(menu);

package/src/js/password.js

@@ -74,14 +74,7 @@ function watchSubmitRoot(input) {
 
 registerCommands(PASSWORD_COMMANDS, {
   resolve: resolvePasswordInput,
-  prepare: (trigger, input) => {
-    trigger.setAttribute("aria-controls", input.id);
-    if (!trigger.hasAttribute("aria-pressed")) {
-      trigger.setAttribute("aria-pressed", "false");
-    }
-  },
-  handle: (event, _trigger, input) => {
-    event.preventDefault();
+  handle: (_event, _trigger, input) => {
     const reveal = input.type === "password";
     if (reveal) watchSubmitRoot(input);
     setRevealed(input, reveal);

package/src/js/range.js

@@ -0,0 +1,151 @@
+/*
+ * Range — fill share and named-value semantics for range inputs.
+ *
+ * The `range` enhancement token is the opt-in; it stays independent from
+ * the `.range` presentation class:
+ *
+ *   <input class="range" data-enhance="range" type="range" min="0" max="100">
+ *
+ * Every opted-in input gets `--range-progress`, the fill share the track
+ * gradient in range.css reads. Without this module the variable stays at
+ * its `0%` default and the track renders plain — the control is fully
+ * usable, only unfilled.
+ *
+ * When the input references a datalist whose option carries a `label`, the
+ * module also sets `aria-valuetext` (the announced value when the numeric
+ * value really means a text, e.g. `2` means "High") and mirrors the label
+ * into each associated `<output for="…">`. Those writes are owned: when a
+ * later value has no label, the module restores the pre-existing
+ * `aria-valuetext` (or removes the attribute if it was absent) and each
+ * output's original text — but only where the current value is still the
+ * module's own last write, so author state is never destroyed.
+ * Options without a label leave author-written `aria-valuetext` and outputs
+ * untouched.
+ *
+ *   <output for="effort">High</output>
+ *   <input data-enhance="range" type="range" id="effort" min="0" max="3" list="effort-levels" aria-label="Effort">
+ */
+
+import { registerEnhancement } from "./enhance.js";
+
+const RANGE_SELECTOR = 'input[type="range"]';
+
+// Writes this module owns per input: for the valuetext and each output,
+// the value before the first write (original) and the last value written
+// (last). A later unlabeled value restores an entry only when its current
+// value is still the module's last write — author state, whether present
+// from the start or written since, is never destroyed. Entries live on the
+// node, not the tree, so a disconnected output is still restored.
+const owned = new WeakMap();
+
+function toFinite(value, fallback) {
+  // Absent min/max read back as "" (Number("") is 0, not missing).
+  if (value === "" || value === null || value === undefined) return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function labelFor(input) {
+  const listId = input.getAttribute("list");
+  if (!listId) return undefined;
+  const list = input.getRootNode().getElementById?.(listId);
+  if (!list) return undefined;
+  const option = [...(list.options ?? [])].find((entry) => entry.value === input.value);
+  const label = option?.label ?? option?.getAttribute?.("label") ?? "";
+  return label ? label : undefined;
+}
+
+function outputsFor(input) {
+  if (!input.id) return [];
+  const root = input.getRootNode();
+  if (typeof root.querySelectorAll !== "function") return [];
+  return [...root.querySelectorAll(`output[for~="${CSS.escape(input.id)}"]`)];
+}
+
+function syncRange(input) {
+  const min = toFinite(input.min, 0);
+  const max = toFinite(input.max, 100);
+  const value = toFinite(input.value, min);
+  const share = max > min ? ((value - min) / (max - min)) * 100 : 0;
+  const clamped = Math.min(100, Math.max(0, share));
+  input.style.setProperty("--range-progress", `${clamped}%`);
+
+  const label = labelFor(input);
+  if (label === undefined) {
+    releaseOwned(input);
+    return;
+  }
+  const record = owned.get(input) ?? { aria: null, outputs: new Map() };
+  if (!record.aria) {
+    record.aria = { original: input.getAttribute("aria-valuetext"), last: label };
+  } else {
+    record.aria.last = label;
+  }
+  input.setAttribute("aria-valuetext", label);
+  for (const output of outputsFor(input)) {
+    const entry = record.outputs.get(output) ?? { original: output.textContent, last: label };
+    entry.last = label;
+    record.outputs.set(output, entry);
+    output.textContent = label;
+  }
+  owned.set(input, record);
+}
+
+function releaseOwned(input) {
+  const record = owned.get(input);
+  if (!record) return;
+  // Restore only what this module wrote: an author may have set its own
+  // value since, and that state is not ours to destroy. A null original
+  // means the attribute was absent before the first write.
+  if (record.aria && input.getAttribute("aria-valuetext") === record.aria.last) {
+    if (record.aria.original === null) {
+      input.removeAttribute("aria-valuetext");
+    } else {
+      input.setAttribute("aria-valuetext", record.aria.original);
+    }
+  }
+  for (const [output, entry] of record.outputs) {
+    if (output.textContent === entry.last) output.textContent = entry.original;
+  }
+  owned.delete(input);
+}
+
+// Private on purpose: `owned` holds one record per input, so a second,
+// independent connection would restore and drop state the enhancement still
+// owns. The lifecycle is the only caller. A programmatic value change goes
+// through dispatchInput() from ./input.js, which every listener sees.
+function connectRange(input) {
+  const controller = new AbortController();
+  syncRange(input);
+  input.addEventListener("input", () => syncRange(input), {
+    signal: controller.signal,
+  });
+  // Listen on the root so form="…" and moves between forms keep working.
+  input.getRootNode().addEventListener(
+    "reset",
+    (event) => {
+      if (event.target !== input.form) return;
+      // Reset fires before native values change. A new task also lets later
+      // listeners cancel it; a microtask can run before the native reset.
+      setTimeout(() => {
+        if (
+          !controller.signal.aborted &&
+          !event.defaultPrevented &&
+          input.isConnected &&
+          input.form === event.target
+        ) {
+          syncRange(input);
+        }
+      }, 0);
+    },
+    { capture: true, signal: controller.signal },
+  );
+  return () => {
+    releaseOwned(input);
+    controller.abort();
+  };
+}
+
+registerEnhancement("range", (input) =>
+  input.matches(RANGE_SELECTOR) ? connectRange(input) : undefined,
+);

package/src/js/scrollspy.js

@@ -154,11 +154,10 @@ function setupNav(nav) {
     measure();
   }
 
-  // The scroll root (custom container or the document viewport) is resolved
-  // once at connect and is stable for the lifetime of the connection; measure
-  // still re-reads the current root element so a replaced *element* under a
-  // stable container is handled, but swapping the container itself is out of
-  // contract (re-inject the nav or call refreshScrollspy after such a move).
+  // The scroll root is resolved once when the enhancement connects, and the
+  // scroll listener stays on it. Changing data-scrollspy-root or replacing its
+  // target is outside the connection contract; recreate the enhancement with
+  // the new markup. refreshScrollspy() only rebuilds the link->section map.
   const scrollTarget = rootFor(nav) ?? nav.ownerDocument.defaultView;
   scrollTarget?.addEventListener("scroll", () => schedule(), {
     passive: true,