actual-css 0.6.0 → 0.8.0

package/src/js/enhance.js

@@ -146,8 +146,6 @@ function createRegistry(root) {
     if (hasRemoval) sweepDisconnected();
   });
 
-  observer.observe(root, { childList: true, subtree: true });
-
   return {
     add(enhancers) {
       const selectors = Object.keys(enhancers).filter(isValidSelector);
@@ -164,6 +162,9 @@ function createRegistry(root) {
         selectorString: selectors.join(","),
       };
       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;
@@ -201,6 +202,37 @@ export function hasEnhancement(el, name) {
   return el.matches(enhancementSelector(name));
 }
 
+/**
+ * Apply a named opt-in once; presentation selectors remain application-owned.
+ * @param {string} name
+ * @param {string} selector
+ * @param {Document | Element | DocumentFragment} [root] Query scope, excluding itself.
+ * @returns {Element[]} Matched descendants.
+ */
+export function applyEnhancement(name, selector, root) {
+  if (typeof document === "undefined") return [];
+
+  enhancementSelector(name);
+  root ??= document.documentElement;
+  const elements = [...root.querySelectorAll(selector)];
+
+  for (const el of elements) {
+    if (hasEnhancement(el, name)) continue;
+    const tokens = el.getAttribute("data-enhance");
+    el.setAttribute("data-enhance", tokens ? `${tokens} ${name}` : name);
+  }
+  // Refresh the scope once per owner; parentNode stops at shadow boundaries.
+  // A Document scope can own registrations, but its default root —
+  // documentElement — is a descendant the ancestor walk never reaches.
+  for (let owner = root; owner; owner = owner.parentNode) {
+    ownedNames.get(owner)?.get(name)?.refresh(root);
+    if (owner === root && owner.nodeType === DOCUMENT_NODE) {
+      ownedNames.get(owner.documentElement)?.get(name)?.refresh(root);
+    }
+  }
+  return elements;
+}
+
 export function registerEnhancement(name, init, root) {
   if (typeof document === "undefined") return noopRuntime();
 

package/src/js/enhancement-loader.js

@@ -29,51 +29,45 @@ const styleLoads = new Map();
 
 let moduleImporter = (url) => import(url);
 
-export function loadScript(url) {
+function loadAsset(url, loads, kind) {
   const absoluteUrl = new URL(url, document.baseURI).href;
 
-  if (!scriptLoads.has(absoluteUrl)) {
-    scriptLoads.set(
-      absoluteUrl,
-      new Promise((resolve, reject) => {
-        const script = document.createElement("script");
-        script.src = absoluteUrl;
-        script.onload = resolve;
-        script.onerror = () => {
-          scriptLoads.delete(absoluteUrl);
-          script.remove();
-          reject(new Error(`Unable to load script: ${absoluteUrl}`));
-        };
-        document.head.append(script);
-      }),
-    );
+  if (!loads.has(absoluteUrl)) {
+    const pending = new Promise((resolve, reject) => {
+      const element = document.createElement(kind === "script" ? "script" : "link");
+      if (kind === "script") {
+        element.src = absoluteUrl;
+      } else {
+        element.rel = "stylesheet";
+        element.href = absoluteUrl;
+      }
+      element.onload = resolve;
+      element.onerror = () => {
+        element.remove();
+        reject(new Error(`Unable to load ${kind}: ${absoluteUrl}`));
+      };
+      document.head.append(element);
+    });
+
+    // The DOM clears the failed element; the cache evicts the rejected
+    // promise. The guard keeps a finished load from wiping out a newer one.
+    // A catch never runs synchronously, so the eviction always lands after
+    // the `set` above, even when the transport rejects during append.
+    loads.set(absoluteUrl, pending);
+    pending.catch(() => {
+      if (loads.get(absoluteUrl) === pending) loads.delete(absoluteUrl);
+    });
   }
 
-  return scriptLoads.get(absoluteUrl);
+  return loads.get(absoluteUrl);
 }
 
-export function loadStyle(url) {
-  const absoluteUrl = new URL(url, document.baseURI).href;
-
-  if (!styleLoads.has(absoluteUrl)) {
-    styleLoads.set(
-      absoluteUrl,
-      new Promise((resolve, reject) => {
-        const link = document.createElement("link");
-        link.rel = "stylesheet";
-        link.href = absoluteUrl;
-        link.onload = resolve;
-        link.onerror = () => {
-          styleLoads.delete(absoluteUrl);
-          link.remove();
-          reject(new Error(`Unable to load style: ${absoluteUrl}`));
-        };
-        document.head.append(link);
-      }),
-    );
-  }
+export function loadScript(url) {
+  return loadAsset(url, scriptLoads, "script");
+}
 
-  return styleLoads.get(absoluteUrl);
+export function loadStyle(url) {
+  return loadAsset(url, styleLoads, "style");
 }
 
 function makeInit(name, connect) {
@@ -177,8 +171,7 @@ export function loadEnhancement(name, url) {
   return promise;
 }
 
-async function loadManifest(manifest) {
-  const entries = Object.entries(manifest);
+async function loadManifest(entries) {
   const results = await Promise.allSettled(
     entries.map(([name, url]) => loadEnhancement(name, url)),
   );
@@ -239,7 +232,7 @@ export async function loadEnhancements(scope = document) {
     }
   }
 
-  const result = await loadManifest(Object.fromEntries(manifest));
+  const result = await loadManifest([...manifest]);
 
   if (result.failed.length === 0) {
     for (const block of blocks) block.remove();
@@ -250,7 +243,7 @@ export async function loadEnhancements(scope = document) {
 
 async function loadManifestBlock(block) {
   const entries = parseManifestEntries(block.textContent);
-  const result = await loadManifest(Object.fromEntries(entries));
+  const result = await loadManifest(entries);
 
   for (const failure of result.failed) {
     console.error(`Enhancement "${failure.name}" failed to load:`, failure.error);
@@ -286,7 +279,7 @@ export async function loadResponse(response) {
     throw new TypeError("Enhance-Modules header must be a JSON object.");
   }
 
-  return loadManifest(manifest);
+  return loadManifest(Object.entries(manifest));
 }
 
 export function __setModuleImporter(fn) {

package/src/js/events.js

@@ -1,9 +1,6 @@
 export const ACTUAL_EVENT_PREFIX = "actual";
 
 export const EVENTS = {
-  reposition: `${ACTUAL_EVENT_PREFIX}:reposition`,
-  hide: `${ACTUAL_EVENT_PREFIX}:hide`,
-  outOfView: `${ACTUAL_EVENT_PREFIX}:out-of-view`,
   // Cancelable: dispatched by a surface before it opens.
   // detail: { surface, options }
   surfaceOpen: `${ACTUAL_EVENT_PREFIX}:surface-open`,

package/src/js/filter.js

@@ -62,7 +62,6 @@ function filterSlug(value, event) {
   const slug = normalizeText(value)
     .toLowerCase()
     .replace(/[^\p{L}\p{N}]+/gu, "-")
-    .replace(/-{2,}/g, "-")
     .replace(/^-+/, "");
 
   return keepTrailingSeparator ? slug : slug.replace(/-+$/, "");

package/src/js/floating-space.js

@@ -0,0 +1,42 @@
+/*
+ * The coordinate space and CSS positioning scheme are one decision. Keeping
+ * them in one value prevents a caller from writing document coordinates to a
+ * fixed box, or viewport coordinates to an absolute one.
+ *
+ * An open top-layer element with position: absolute uses the initial
+ * containing block, so only the anchor determines the correct mode.
+ */
+const VIEWPORT_ANCHORED = "dialog:modal, :popover-open";
+
+function isViewportAnchored(anchor) {
+  const win = anchor?.ownerDocument?.defaultView;
+  if (!win) return true;
+
+  // Modal dialogs and open popovers are viewport-anchored without computing
+  // position: fixed, so the ancestor walk below cannot identify them.
+  try {
+    if (anchor.closest(VIEWPORT_ANCHORED)) return true;
+  } catch {
+    /* An engine without :modal / :popover-open: the walk is all there is. */
+  }
+
+  for (let el = anchor; el; el = el.parentElement) {
+    const { position } = win.getComputedStyle(el);
+    // Resolve sticky once even while unstuck: changing mode when it sticks
+    // would jump the floating element between coordinate systems mid-scroll.
+    if (position === "fixed" || position === "sticky") return true;
+  }
+  return false;
+}
+
+/**
+ * @param {Element | null | undefined} anchor
+ * @returns {{ space: "viewport" | "document", position: "fixed" | "absolute" }}
+ */
+export function positionModeFor(anchor) {
+  const space = isViewportAnchored(anchor) ? "viewport" : "document";
+  return {
+    space,
+    position: space === "document" ? "absolute" : "fixed",
+  };
+}

package/src/js/flyout.js

@@ -3,15 +3,8 @@ import { focusFirstDescendant } from "./focus.js";
 import { connectMenu, focusFirstMenuItem, focusLastMenuItem } from "./menu.js";
 import { closeSurface, isSurfaceOpen, openSurface, retainSurface } from "./surface.js";
 
-const panelRefs = new WeakMap();
 const triggerMap = new WeakMap();
 
-function normalizeBreakpoint(raw) {
-  const BREAKPOINTS = { sm: 640, md: 768, lg: 1024 };
-  const value = Number.parseInt(BREAKPOINTS[raw] || raw, 10);
-  return Number.isFinite(value) ? value : undefined;
-}
-
 function readFlyoutOptions(panel) {
   const opts = { autoClose: "true" };
   const ds = panel.dataset;
@@ -20,11 +13,6 @@ function readFlyoutOptions(panel) {
     const d = Number.parseFloat(ds.flyoutDistance);
     if (Number.isFinite(d)) opts.distance = d;
   }
-  if (ds.flyoutMobile) opts.mobile = ds.flyoutMobile;
-  if (ds.flyoutBreakpoint) {
-    const bp = normalizeBreakpoint(ds.flyoutBreakpoint);
-    if (bp != null) opts.breakpoint = bp;
-  }
   if (ds.flyoutAutoClose) opts.autoClose = ds.flyoutAutoClose;
   return opts;
 }
@@ -93,20 +81,12 @@ function onTriggerKeydown(e) {
 
   switch (e.key) {
     case "ArrowDown":
-      e.preventDefault();
-      if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
-      focusFirstMenuItem(panel);
-      break;
-    case "ArrowUp":
-      e.preventDefault();
-      if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
-      focusLastMenuItem(panel);
-      break;
     case "Home":
       e.preventDefault();
       if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
       focusFirstMenuItem(panel);
       break;
+    case "ArrowUp":
     case "End":
       e.preventDefault();
       if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
@@ -131,7 +111,7 @@ function connectTrigger(trigger) {
   if (triggerMap.has(trigger)) return;
 
   const controller = new AbortController();
-  const state = { panel: null, controller, releaseMenu: null };
+  const state = { panel: null, controller, releaseMenu: null, releaseSurface: null };
   triggerMap.set(trigger, state);
 
   resolvePanel(trigger, state);
@@ -144,38 +124,23 @@ function connectTrigger(trigger) {
   trigger.addEventListener("keydown", onTriggerKeydown, { signal: controller.signal });
 }
 
-function releasePanelReference(trigger, state) {
+function releasePanelReference(state) {
   state.releaseMenu?.();
   state.releaseMenu = null;
-
-  const panel = state.panel;
+  state.releaseSurface?.();
+  state.releaseSurface = null;
   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);
+  releasePanelReference(state);
   if (!panel) return null;
 
-  let panelEntry = panelRefs.get(panel);
-  if (!panelEntry) {
-    const release = retainSurface(panel);
-    panelEntry = { triggers: new Set(), release };
-    panelRefs.set(panel, panelEntry);
-  }
-  panelEntry.triggers.add(trigger);
+  // Surface retention owns the shared lifetime across all triggers and consumers.
+  state.releaseSurface = retainSurface(panel);
   state.panel = panel;
 
   if (isMenuFlyout(panel)) {
@@ -197,7 +162,7 @@ function disconnectTrigger(trigger) {
   if (state.panel?.isConnected && isSurfaceOpen(state.panel)) {
     closeSurface(state.panel, { restoreFocus: false });
   }
-  releasePanelReference(trigger, state);
+  releasePanelReference(state);
   triggerMap.delete(trigger);
 }
 

package/src/js/focus-group.js

@@ -1,3 +1,10 @@
+/*
+ * Focus group — one remembered tab stop and Arrow/Home/End navigation for a
+ * composite widget. The consumer supplies getItems(); the controller only
+ * updates tabindex and focus, never activation or ARIA. sync() re-reads the
+ * candidate list; the primitive does not observe the subtree.
+ */
+
 import { itemForKey } from "./keys.js";
 
 const ORIENTATIONS = new Set(["horizontal", "vertical"]);

package/src/js/focus.js

@@ -9,6 +9,12 @@ const FOCUSABLE_SELECTOR = [
   "[tabindex]",
 ].join(",");
 
+/*
+ * The branch below checkVisibility() is not dead code: checkVisibility() is
+ * Safari 17.4 and the floor is Safari 17, so it is the branch that runs at the
+ * bottom of the supported range — where it also decides whether a closed
+ * popover's contents are reachable. Measured there; do not drop it.
+ */
 export function isElementVisible(el) {
   if (!el || el.hidden) return false;
   if (typeof el.checkVisibility === "function") return el.checkVisibility();

package/src/js/menu.js

@@ -1,3 +1,13 @@
+/*
+ * Menu — the shared `.menu > li > .menu-item` vocabulary and wiring.
+ *
+ * getMenuItems() filters to usable items; onMenuKeydown() adds directional
+ * navigation and activation; connectMenu() owns the ref-counted listeners a
+ * menu shares across its triggers. Wiring is per menu, not per trigger, so a
+ * menu retained by several triggers (or by flyout and context-menu at once)
+ * tears down only when the last one releases it.
+ */
+
 import { isElementVisible } from "./focus.js";
 import { connectFocusGroup } from "./focus-group.js";
 import { firstItem, itemForKey, lastItem } from "./keys.js";
@@ -134,7 +144,6 @@ export function connectMenu(menu, { close }) {
     released = true;
     entry.count--;
     if (entry.count <= 0) {
-      entry.focusGroup?.disconnect();
       entry.controller.abort();
       menuConnections.delete(menu);
     }

package/src/js/selectors.js

@@ -1,11 +1,11 @@
 /*
  * Selectors — the state-class vocabulary the runtime writes.
  *
- * This file no longer lists discovery selectors: behavior discovery moved
- * to data-enhance tokens in 0.2. What remains are the class names modules
- * write as state (is-open, was-validated, …) and validation's two read-side
- * presentation adapters (field, fieldError). To run this runtime against a
- * different CSS framework, edit this file (or alias it in a bundler).
+ * The file lists the class names modules write as state (is-open,
+ * was-validated, …) and validation's two read-side presentation adapters
+ * (field, fieldError). Behavior discovery is not listed here: it uses
+ * data-enhance tokens. To run this runtime against a different CSS
+ * framework, edit this file (or alias it in a bundler).
  *
  * data-* attributes and ARIA are not listed: they are each module's own
  * behavior API, not CSS vocabulary, so they stay framework-neutral by
@@ -27,10 +27,6 @@ export const CLASSES = {
   // surface.js — state class on the open flyout/menu/dialog surface.
   // status.js writes the same class on the status bar while a message shows.
   open: "is-open",
-  // surface.js — state class while the surface renders as a mobile sheet.
-  sheet: "is-sheet",
-  // surface.js — class name written on the generated sheet backdrop.
-  backdrop: "surface-backdrop",
   // dialog.js — transient class for the "can't dismiss" shake animation.
   static: "is-static",
   // dialog.js — written on <html> while any modal dialog is open.

package/src/js/status.js

@@ -31,6 +31,12 @@
  *   - Any other code, without importing this module: dispatch `actual:status`
  *     directly — `detail: { message, intent, duration }`, or `{}` to clear.
  *
+ * A message originating inside an open dialog temporarily mounts the singleton
+ * bar in that dialog. Content outside a modal dialog is inert and cannot sit
+ * above its top layer, so this keeps both the visual feedback and live region
+ * in the active subtree. Programmatic callers pass the originating element as
+ * `options.source`; event and command entry points propagate it automatically.
+ *
  * The element contract is `[data-status][role="status"]`. Both are required:
  * "status" is a generic domain word, so `role="status"` keeps the
  * document-wide lookup from matching an unrelated app element that happens to
@@ -52,6 +58,7 @@ import { waitForTransitions } from "./transition.js";
 const STATUS_SELECTOR = '[data-status][role="status"]';
 const STATUS_CLASSES_ATTR = "statusClasses";
 const VIEWPORT_OFFSET_PROPERTY = "--status-viewport-offset";
+const DEFAULT_DURATION_MS = 3000;
 
 let statusTimer;
 // Bumped by every show and every clear. A deferred exit cleanup only runs when
@@ -59,12 +66,39 @@ let statusTimer;
 // never emptied by the previous message's cleanup.
 let statusGeneration = 0;
 let viewportTracker = null;
+const statusHomes = new WeakMap();
 
 function statusTarget() {
   if (typeof document === "undefined") return null;
   return document.querySelector(STATUS_SELECTOR);
 }
 
+function restoreStatusTarget(target) {
+  const home = statusHomes.get(target);
+  if (!home) return;
+
+  const parent = home.parent?.isConnected ? home.parent : target.ownerDocument?.body;
+  if (parent) {
+    const reference = home.nextSibling?.parentNode === parent ? home.nextSibling : null;
+    parent.insertBefore(target, reference);
+  }
+  statusHomes.delete(target);
+}
+
+function mountStatusTarget(target, source) {
+  const dialog = source?.closest?.("dialog[open]");
+  if (!dialog || dialog.ownerDocument !== target.ownerDocument) {
+    restoreStatusTarget(target);
+    return;
+  }
+  if (dialog.contains(target)) return;
+
+  if (!statusHomes.has(target)) {
+    statusHomes.set(target, { parent: target.parentNode, nextSibling: target.nextSibling });
+  }
+  dialog.append(target);
+}
+
 // The bar is fixed to the layout viewport, so the mobile software keyboard
 // covers it. visualViewport reports the occluded band; the CSS adds it to the
 // bottom inset. Tracking runs only while a message is on screen.
@@ -118,10 +152,10 @@ export function status(message, options = {}) {
   const target = statusTarget();
   if (!target || message == null) return;
 
-  // A live region with nothing to announce is not a message. `:empty` used to
-  // absorb this case for free; now that the open state is explicit, an empty
-  // message has to mean "close" or it would open a blank pill. This also keeps
-  // status(await response.text()) from leaving a stale message on screen.
+  // A live region with nothing to announce is not a message. The open state
+  // is explicit, so an empty message has to mean "close" or it would open a
+  // blank pill. This also keeps status(await response.text()) from leaving a
+  // stale message on screen.
   if (message === "") {
     status.clear();
     return;
@@ -130,6 +164,8 @@ export function status(message, options = {}) {
   clearTimeout(statusTimer);
   statusGeneration++;
 
+  mountStatusTarget(target, options.source);
+
   clearIntentClasses(target);
   const intent = intentClasses(options.intent);
   if (intent.length) {
@@ -144,7 +180,7 @@ export function status(message, options = {}) {
   trackViewport(target);
 
   if (options.duration !== false) {
-    statusTimer = setTimeout(() => status.clear(), options.duration ?? 3000);
+    statusTimer = setTimeout(() => status.clear(), options.duration ?? DEFAULT_DURATION_MS);
   }
 }
 
@@ -168,6 +204,7 @@ status.clear = function clear() {
     target.textContent = "";
     clearIntentClasses(target);
     releaseViewport();
+    restoreStatusTarget(target);
   });
 };
 
@@ -198,7 +235,7 @@ function connectStatusTrigger(trigger, target) {
 if (typeof document !== "undefined") {
   document.addEventListener(EVENTS.invalid, (event) => {
     const message = event.detail?.message;
-    if (message) status(message, { intent: "danger" });
+    if (message) status(message, { intent: "danger", source: event.target });
   });
 
   // Public contract: any code can trigger the status bar this way, without
@@ -209,7 +246,7 @@ if (typeof document !== "undefined") {
     // paths end in the same exit, so a detail that lost its message never
     // strands a stale one on screen.
     if (message != null) {
-      status(message, { intent, duration });
+      status(message, { intent, duration, source: event.target });
     } else {
       status.clear();
     }