actual-css 0.10.0 → 0.11.0

package/src/js/enhance.js

@@ -1,8 +1,13 @@
 /*
  * 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
@@ -16,16 +21,9 @@
  * 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.
  */
@@ -39,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() {},
@@ -56,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) {
@@ -109,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() {
@@ -137,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;
@@ -151,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
@@ -216,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);
   }
@@ -240,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.");
   }
@@ -255,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 {
@@ -268,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/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/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,

package/src/js/status.js

@@ -247,10 +247,6 @@ function resolveStatusTrigger(trigger) {
   return target && target === statusTarget() ? target : null;
 }
 
-function connectStatusTrigger(trigger, target) {
-  trigger.setAttribute("aria-controls", target.id);
-}
-
 if (typeof document !== "undefined") {
   document.addEventListener(EVENTS.invalid, (event) => {
     const message = event.detail?.message;
@@ -273,9 +269,7 @@ if (typeof document !== "undefined") {
 
   registerCommands(STATUS_SHOW_COMMANDS, {
     resolve: resolveStatusTrigger,
-    prepare: connectStatusTrigger,
-    handle: (event, trigger) => {
-      event.preventDefault();
+    handle: (_event, trigger) => {
       dispatchStatusEvent(trigger, {
         message: trigger.getAttribute("data-status-message"),
         intent: trigger.getAttribute("data-status-intent") ?? undefined,
@@ -286,9 +280,7 @@ if (typeof document !== "undefined") {
 
   registerCommands(STATUS_CLEAR_COMMANDS, {
     resolve: resolveStatusTrigger,
-    prepare: connectStatusTrigger,
-    handle: (event, trigger) => {
-      event.preventDefault();
+    handle: (_event, trigger) => {
       dispatchStatusEvent(trigger, {});
     },
   });

package/src/js/tooltip.js

@@ -29,7 +29,10 @@
  *             tooltips therefore keep their initial text; use an explicit
  *             tooltip when its content must update dynamically.
  *
- * Show:       hover + focus (150ms delay), click toggle, or always visible
+ * Show:       hover + keyboard focus (150ms delay), click toggle, or always
+ *             visible. Focus counts only when it matches :focus-visible, so
+ *             a pointer press, or focus handed back by a closing dialog after
+ *             a pointer close, shows nothing.
  * Hide:       focus leaving the trigger (focusout), pointer leave, Escape
  *
  * Geometry:   a trigger scrolled out of the positioning boundary takes its tip
@@ -519,6 +522,13 @@ function handleTriggerIntent(e) {
   )
     return;
 
+  // why: focus is a show intent only when it is keyboard focus. A pointer
+  // press focuses the trigger too, and a dialog or drawer closed with the
+  // pointer hands focus back to its invoker; neither asks for a label the
+  // user just acted on. :focus-visible is the browser's own modality verdict,
+  // the one the focus rings already follow, so Tab still shows the tip.
+  if (e.type === "focusin" && !e.target.matches(":focus-visible")) return;
+
   const tip = ensureTip(trigger);
   if (!tip) return;
 

package/src/js/validation.js

@@ -11,19 +11,20 @@
  * Opt in with data-enhance="validation". The .needs-validation class
  * remains valid for presentation-only (CSS :user-invalid feedback without
  * the JS behavior). Importing the module registers the behavior; there is
- * no init call.
+ * no init call. To opt existing forms in by selector, use
+ * applyEnhancement("validation", selector) so they join the enhance()
+ * lifecycle (inserted forms connect, removed forms tear down).
  *
  * The marker is a static, init-time contract. Removing the form from the
  * DOM tears down everything, including the managed novalidate attribute.
  */
 
-import { enhancementSelector, registerEnhancement } from "./enhance.js";
+import { registerEnhancement } from "./enhance.js";
 import { EVENTS } from "./events.js";
 import { CLASSES } from "./selectors.js";
 
 const NOVALIDATE = "novalidate";
 const WAS_VALIDATED_CLASS = CLASSES.wasValidated;
-const VALIDATION_SELECTOR = enhancementSelector("validation");
 const FIELD_CLASS = CLASSES.field;
 const DANGER_CLASS = CLASSES.danger;
 const MANAGED_NOVALIDATE_ATTR = "validationManagedNovalidate";
@@ -398,13 +399,6 @@ export class FormValidator {
     rules[name] = callback;
   }
 
-  static init(selector = `form${VALIDATION_SELECTOR}`) {
-    if (typeof document === "undefined") return;
-    for (const form of document.querySelectorAll(selector)) {
-      if (isFormElement(form)) connectForm(form);
-    }
-  }
-
   static setFieldError(el, message) {
     el.setCustomValidity(message || "invalid");
     el.dataset.validationErrors = "server";