actual-css 0.2.0 → 0.3.1

package/src/js/parse-config.js

@@ -0,0 +1,47 @@
+/*
+ * parse-config.js — Configuration parsing for data-enhance-config.
+ *
+ * Strict JSON is parsed as-is, never rewritten. When strict JSON fails, a
+ * small, deliberate relax step accepts the ergonomic subset that is common in
+ * HTML attributes: unquoted keys and single-quoted strings. The relaxed
+ * subset is intentionally tiny and is NOT a second grammar — anything it
+ * cannot transform cleanly is rejected by the final JSON.parse. The root
+ * value must be an object; bare string values (other than true/false/null)
+ * stay invalid, and trailing commas are rejected.
+ */
+
+function relax(source) {
+  return source.replace(
+    /([a-zA-Z_$][\w$-]*)\s*:|'((?:\\'|[^'])*)'/g,
+    (_match, key, stringContent) => {
+      if (key) return `"${key}":`;
+      const unescaped = stringContent.replace(/\\'/g, "'");
+      const escaped = unescaped.replace(/"/g, '\\"');
+      return `"${escaped}"`;
+    },
+  );
+}
+
+export function parseConfig(source) {
+  if (source == null || typeof source !== "string") return {};
+  const str = source.trim();
+  if (str === "") return {};
+
+  let text = str;
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    const relaxed = relax(text);
+    text = relaxed.startsWith("{") ? relaxed : `{${relaxed}}`;
+    value = JSON.parse(text);
+  }
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("Enhancement config must be an object");
+  }
+
+  return value;
+}
+
+export default parseConfig;

package/src/js/password.js

@@ -93,6 +93,14 @@ if (typeof document !== "undefined") {
   document.addEventListener("submit", handleSubmit);
 
   window.addEventListener("pagehide", () => {
-    for (const input of revealed) setRevealed(input, false);
+    for (const input of revealed) {
+      // Opportunistic housekeeping: an input removed from the DOM before
+      // navigation no longer needs reverting and can leave the set.
+      if (!input.isConnected) {
+        revealed.delete(input);
+        continue;
+      }
+      setRevealed(input, false);
+    }
   });
 }

package/src/js/scrollspy.js

@@ -75,12 +75,15 @@ function measureRoot(nav, root) {
     };
   }
 
-  const html = nav.ownerDocument.documentElement;
+  // scrollingElement is the real scroll container in standards mode; fall
+  // back to documentElement (quirks mode, or older engines without it).
+  const doc = nav.ownerDocument;
+  const el = doc.scrollingElement || doc.documentElement;
   return {
     top: 0,
-    height: html.clientHeight,
-    scrollTop: html.scrollTop,
-    scrollHeight: html.scrollHeight,
+    height: el.clientHeight,
+    scrollTop: el.scrollTop,
+    scrollHeight: el.scrollHeight,
   };
 }
 
@@ -151,6 +154,11 @@ 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).
   const scrollTarget = rootFor(nav) ?? nav.ownerDocument.defaultView;
   scrollTarget?.addEventListener("scroll", () => schedule(), {
     passive: true,

package/src/js/selectors.js

@@ -32,13 +32,6 @@ export const CLASSES = {
   backdrop: "surface-backdrop",
   // dialog.js — transient class for the "can't dismiss" shake animation.
   static: "is-static",
-  // dialog-fallback.js — marker written on a dialog controlled by the legacy
-  // shim (browsers without native <dialog>); dialog-fallback.css keys its
-  // emulated dialog presentation on it.
-  dialogFallback: "dialog-fallback",
-  // dialog-fallback.js — state class on a shimmed dialog while it is open as
-  // a modal; carries the fixed positioning and simulated backdrop.
-  fallbackModal: "is-fallback-modal",
   // dialog.js — written on <html> while any modal dialog is open.
   modalOpen: "has-modal-open",
   // dialog.js — written on <html> when the viewport had a classic scrollbar

package/src/js/status.js

@@ -125,7 +125,9 @@ if (typeof document !== "undefined") {
   // importing this module. A message shows it; omitting one clears it.
   document.addEventListener(EVENTS.status, (event) => {
     const { message, intent, duration } = event.detail ?? {};
-    if (message) {
+    // `message != null` keeps "" (an intentional empty message) on the show
+    // path, consistent with status() itself; an absent message clears.
+    if (message != null) {
       status(message, { intent, duration });
     } else {
       status.clear();

package/src/js/surface.js

@@ -1,33 +1,35 @@
 import enhance from "./enhance.js";
 import { EVENTS } from "./events.js";
-import { reposition, repositionAt, track } from "./floating.js";
-import { hasMenuItem, onMenuKeydown } from "./menu.js";
+import { autoUpdate, reposition, repositionAt } from "./floating.js";
+
 import { CLASSES } from "./selectors.js";
 
-const DEFAULT_BREAKPOINT = 768;
-const BREAKPOINTS = {
-  sm: 640,
-  md: 768,
-  lg: 1024,
-};
 const openSurfaces = new Set();
 const surfaceMap = new WeakMap();
+const surfaceRetainers = new WeakMap();
 const mountedSurfaces = new WeakMap();
 const clickBoundDocuments = new WeakSet();
 
-// data-actual-surface is written by the runtime, never by an author, and never
-// selected on by CSS. It is namespaced because "data-surface" is a name an
-// application may already own. surface.js reaps its own surfaces so consumers
-// do not have to maintain panel-side lifecycle hooks.
 const SURFACE_MARKER = "data-actual-surface";
+const AUTO_CLOSE_VALUES = new Set(["true", "inside", "outside", "false"]);
+const SCROLL_KEYS = new Set([
+  "ArrowDown",
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "End",
+  "Home",
+  "PageDown",
+  "PageUp",
+  " ",
+]);
 const reapers = new WeakMap();
 
-// Registered lazily, per owning document, and never at import time: enhance()
-// binds its observer to the root it is given, so a module-scope
-// enhance() would watch whichever document existed when this module was first
-// imported. Surfaces in any other document (an iframe, or a fresh test
-// document) would then never be swept. Keyed by Document, so nothing is
-// retained once a document is gone.
+function normalizeAutoClose(value) {
+  const normalized = String(value ?? "outside");
+  return AUTO_CLOSE_VALUES.has(normalized) ? normalized : "true";
+}
+
 function reaperFor(menu) {
   const root = menu.ownerDocument?.documentElement;
   if (!root) return null;
@@ -82,45 +84,20 @@ function restoreSurface(menu) {
   mountedSurfaces.delete(menu);
 }
 
-function getBreakpoint(menu) {
-  const value = menu.dataset.flyoutBreakpoint || "";
-  const raw = Number.parseInt(BREAKPOINTS[value] || value, 10);
-  return Number.isFinite(raw) ? raw : DEFAULT_BREAKPOINT;
-}
-
-function getMobileMode(menu, mode) {
-  return mode || menu.dataset.flyoutMobile || "auto";
-}
-
-function getPlacement(menu, placement) {
-  return placement || menu.dataset.flyoutPlacement || "bottom-start";
-}
-
-function getDistance(menu, distance) {
-  if (distance != null) return distance;
-  const value = Number.parseFloat(menu.dataset.flyoutDistance);
-  return Number.isFinite(value) ? value : 4;
-}
-
-function getAutoCloseMode(menu, value) {
-  const mode = String(value ?? menu.dataset.flyoutAutoClose ?? "true").toLowerCase();
-  if (mode === "inside" || mode === "outside" || mode === "false") return mode;
-  return "true";
-}
-
-function shouldUseSheet(menu, mode) {
-  const mobile = getMobileMode(menu, mode);
+function shouldUseSheet(menu, state) {
+  const mobile = state.mobile || "auto";
   if (mobile === "none" || mobile === "anchored") return false;
   if (mobile === "sheet") return true;
 
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+  const view = menu.ownerDocument?.defaultView;
+  if (!view || typeof view.matchMedia !== "function") {
     return false;
   }
 
-  const breakpoint = getBreakpoint(menu);
+  const breakpoint = state.breakpoint ?? 768;
   return (
-    window.matchMedia("(pointer: coarse)").matches &&
-    window.matchMedia(`(max-width: ${breakpoint}px)`).matches
+    view.matchMedia("(pointer: coarse)").matches &&
+    view.matchMedia(`(max-width: ${breakpoint}px)`).matches
   );
 }
 
@@ -150,16 +127,13 @@ function ensureBackdrop(menu, state) {
   const backdrop = menu.ownerDocument.createElement("div");
   backdrop.className = CLASSES.backdrop;
   backdrop.hidden = false;
-  backdrop.addEventListener("click", () => {
-    closeSurface(menu);
-  });
 
   menu.before(backdrop);
   state.backdrop = backdrop;
 }
 
 function applyPresentation(menu, state) {
-  state.isSheet = shouldUseSheet(menu, state.mobile);
+  state.isSheet = shouldUseSheet(menu, state);
   if (state.isSheet) {
     menu.style.removeProperty("left");
     menu.style.removeProperty("top");
@@ -170,13 +144,13 @@ function applyPresentation(menu, state) {
 
 function positionSurface(menu) {
   const state = surfaceMap.get(menu);
-  if (!state || state.isSheet) return;
+  if (!state || state.isSheet) return true;
 
   if (state.trigger) {
     const triggerWidth = state.trigger.getBoundingClientRect().width;
-    menu.style.setProperty("--flyout-trigger-width", `${triggerWidth}px`);
+    menu.style.setProperty("--surface-anchor-width", `${triggerWidth}px`);
   } else {
-    menu.style.removeProperty("--flyout-trigger-width");
+    menu.style.removeProperty("--surface-anchor-width");
   }
 
   const opts = {
@@ -189,94 +163,87 @@ function positionSurface(menu) {
   };
 
   if (state.point) {
-    repositionAt(state.point.x, state.point.y, menu, opts);
-    return;
+    return repositionAt(state.point.x, state.point.y, menu, opts);
   }
 
   const anchor = state.trigger || state.source;
-  if (anchor) reposition(anchor, menu, opts);
+  if (anchor) return reposition(anchor, menu, opts);
+  return true;
 }
 
 function ensureSurfaceWired(menu) {
   if (surfaceMap.has(menu)) return surfaceMap.get(menu);
 
   ensureDocumentClick(menu);
-  const controller = new AbortController();
   const state = {
-    controller,
-    untrack: track(menu),
+    stopTracking: null,
+    stopScrollIntent: null,
+    unregisterEscape: null,
     backdrop: null,
     trigger: null,
     source: null,
     point: null,
     mobile: "auto",
+    breakpoint: 768,
     placement: "bottom-start",
     distance: 4,
     flip: true,
     shift: true,
     shiftPadding: 4,
-    autoClose: "true",
+    autoClose: "outside",
+    dismissOnScroll: false,
+    scrollIntentAt: null,
     isSheet: false,
     closeId: 0,
   };
 
-  menu.addEventListener(
-    EVENTS.reposition,
-    (e) => {
-      if (menu.hidden) return;
-      if (e.detail?.type === "scroll" && surfaceMap.get(menu)?.point) {
-        closeSurface(menu);
-        return;
-      }
-      const state = surfaceMap.get(menu);
-      if (!state) return;
-      applyPresentation(menu, state);
-      positionSurface(menu);
-    },
-    { signal: controller.signal },
-  );
-
-  menu.addEventListener(
-    EVENTS.hide,
-    (e) => {
-      if (!menu.hidden) closeSurface(menu, { restoreFocus: e.detail?.type === "escape" });
-    },
-    { signal: controller.signal },
-  );
-
-  menu.addEventListener(
-    EVENTS.outOfView,
-    () => {
-      if (!menu.hidden) closeSurface(menu);
-    },
-    { signal: controller.signal },
-  );
-
-  menu.addEventListener(
-    "keydown",
-    (e) => onMenuKeydown(e, { close: (target) => closeSurface(target) }),
-    { signal: controller.signal },
-  );
-
-  menu.addEventListener(
-    "click",
-    (e) => {
-      const state = surfaceMap.get(menu);
-      const disabledItem = e.target.closest?.(":disabled, [aria-disabled='true']");
-      if (disabledItem && menu.contains(disabledItem)) {
-        e.preventDefault();
-        return;
-      }
-      if (!state || state.autoClose === "outside" || state.autoClose === "false") return;
-      if (hasMenuItem(menu, e.target)) closeSurface(menu);
-    },
-    { signal: controller.signal },
-  );
-
   surfaceMap.set(menu, state);
   return state;
 }
 
+// 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
+// scroll/resize work. Reopening re-registers in the correct order.
+function startSurfaceResources(menu, state) {
+  state.unregisterEscape = registerEscapeDismissal(menu, (opts) => closeSurface(menu, opts));
+  if (state.dismissOnScroll) {
+    const controller = new AbortController();
+    const arm = (event) => {
+      state.scrollIntentAt = event.timeStamp;
+    };
+    const armExternalPointer = (event) => {
+      if (!menu.contains(event.target)) arm(event);
+    };
+    const armKey = (event) => {
+      if (!event.defaultPrevented && SCROLL_KEYS.has(event.key)) arm(event);
+    };
+    const captureOptions = { signal: controller.signal, capture: true };
+    const passiveCaptureOptions = { ...captureOptions, passive: true };
+    const doc = menu.ownerDocument;
+    doc.addEventListener("pointerdown", armExternalPointer, passiveCaptureOptions);
+    doc.addEventListener("touchmove", arm, passiveCaptureOptions);
+    doc.addEventListener("wheel", arm, passiveCaptureOptions);
+    doc.addEventListener("keydown", armKey, { signal: controller.signal });
+    state.stopScrollIntent = () => controller.abort();
+  }
+  state.stopTracking = autoUpdate(menu, ({ type, targets, timeStamp }) => {
+    if (menu.hidden) return;
+    if (
+      type === "scroll" &&
+      state.dismissOnScroll &&
+      state.scrollIntentAt != null &&
+      timeStamp >= state.scrollIntentAt &&
+      [...targets].some((target) => target !== menu && !menu.contains(target))
+    ) {
+      closeSurface(menu);
+      return;
+    }
+    applyPresentation(menu, state);
+    if (!positionSurface(menu)) closeSurface(menu);
+  });
+}
+
 export function isSurfaceOpen(menu) {
   return menu.classList.contains(CLASSES.open) && !menu.hidden;
 }
@@ -286,12 +253,35 @@ export function prepareSurface(menu) {
   menu.style.position = "fixed";
   menu.hidden = true;
   syncExpanded(menu, false);
-  // Both steps are idempotent, so they run unguarded: that also keeps the
-  // reaper correct if a surface is ever adopted into another document.
   menu.setAttribute(SURFACE_MARKER, "");
   reaperFor(menu)?.refresh(menu);
 }
 
+export function retainSurface(panel) {
+  if (!panel) return () => {};
+
+  let entry = surfaceRetainers.get(panel);
+  if (!entry) {
+    prepareSurface(panel);
+    entry = { count: 0 };
+    surfaceRetainers.set(panel, entry);
+  }
+  entry.count++;
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    entry.count--;
+    if (entry.count <= 0) {
+      // A released retainer may leave a mounted panel whose original parent
+      // either still needs it back or has disappeared along with the trigger.
+      disconnectSurface(panel);
+      surfaceRetainers.delete(panel);
+    }
+  };
+}
+
 export function openSurface(menu, opts = {}) {
   if (!menu?.isConnected) return false;
   if (isSurfaceOpen(menu)) return false;
@@ -304,7 +294,7 @@ export function openSurface(menu, opts = {}) {
   if (!menu.dispatchEvent(beforeOpen)) return false;
 
   for (const other of openSurfaces) {
-    if (other !== menu) closeSurface(other);
+    if (other !== menu && other.ownerDocument === menu.ownerDocument) closeSurface(other);
   }
 
   const anchor = opts.trigger || opts.source || null;
@@ -315,10 +305,13 @@ export function openSurface(menu, opts = {}) {
   state.source = opts.source || null;
   state.point =
     Number.isFinite(opts.x) && Number.isFinite(opts.y) ? { x: opts.x, y: opts.y } : null;
-  state.mobile = getMobileMode(menu, opts.mobile);
-  state.autoClose = getAutoCloseMode(menu, opts.autoClose);
-  state.placement = getPlacement(menu, opts.placement);
-  state.distance = getDistance(menu, opts.distance);
+  state.mobile = opts.mobile || "auto";
+  state.breakpoint = opts.breakpoint ?? 768;
+  state.autoClose = normalizeAutoClose(opts.autoClose);
+  state.dismissOnScroll = opts.dismissOnScroll === true;
+  state.scrollIntentAt = null;
+  state.placement = opts.placement || "bottom-start";
+  state.distance = opts.distance ?? 4;
   state.flip = opts.flip !== false;
   state.shift = opts.shift !== false;
   state.shiftPadding = opts.shiftPadding ?? 4;
@@ -328,10 +321,16 @@ export function openSurface(menu, opts = {}) {
 
   menu.classList.add(CLASSES.open);
   menu.hidden = false;
-  openSurfaces.add(menu);
   applyPresentation(menu, state);
   syncExpanded(menu, true);
-  positionSurface(menu);
+
+  if (!positionSurface(menu)) {
+    closeSurface(menu, { restoreFocus: false });
+    return false;
+  }
+
+  openSurfaces.add(menu);
+  startSurfaceResources(menu, state);
   return true;
 }
 
@@ -352,6 +351,9 @@ export function closeSurface(menu, opts = {}) {
   if (backdrop) backdrop.hidden = true;
   openSurfaces.delete(menu);
   syncExpanded(menu, false);
+  state?.unregisterEscape?.();
+  state?.stopScrollIntent?.();
+  state?.stopTracking?.();
 
   if (shouldRestoreFocus && state?.restoreFocusTo?.isConnected) {
     state.restoreFocusTo.focus({ preventScroll: true });
@@ -374,30 +376,79 @@ export function disconnectSurface(menu, { restore = true } = {}) {
   const state = surfaceMap.get(menu);
   if (state) {
     state.backdrop?.remove();
-    state.untrack();
-    state.controller.abort();
+    state.unregisterEscape?.();
+    state.stopScrollIntent?.();
+    state.stopTracking?.();
     surfaceMap.delete(menu);
   }
   restoreSurface(menu);
 }
 
 function onDocumentClick(e) {
+  const path = e.composedPath();
+
   for (const menu of openSurfaces) {
+    if (menu.ownerDocument !== e.currentTarget) continue;
     const state = surfaceMap.get(menu);
-    if (!state || state.autoClose === "inside" || state.autoClose === "false") continue;
-    if (menu.contains(e.target) || state?.trigger?.contains(e.target)) continue;
-    closeSurface(menu);
+    if (!state) continue;
+
+    const menuIndex = path.indexOf(menu);
+    const isInside = menuIndex >= 0;
+    const hasCloseTrigger =
+      isInside &&
+      path
+        .slice(0, menuIndex)
+        .some((node) => node instanceof Element && node.hasAttribute("data-flyout-close"));
+
+    if (hasCloseTrigger) {
+      closeSurface(menu);
+      continue;
+    }
+
+    const closesInside = state.autoClose === "true" || state.autoClose === "inside";
+    const closesOutside = state.autoClose === "true" || state.autoClose === "outside";
+    if ((isInside && closesInside) || (!isInside && closesOutside)) closeSurface(menu);
   }
 }
 
-// Bound per owning document on first use, not at import time — same reason as
-// reaperFor(): an import-time listener attaches to whichever document existed
-// then, and stays attached to it. Nothing can need this listener before a
-// surface has been wired, so binding here costs nothing and keeps SSR imports
-// inert without a typeof guard.
 function ensureDocumentClick(menu) {
   const doc = menu.ownerDocument;
   if (!doc || clickBoundDocuments.has(doc)) return;
   clickBoundDocuments.add(doc);
   doc.addEventListener("click", onDocumentClick);
 }
+
+const dismissableStacks = new WeakMap();
+
+export function registerEscapeDismissal(element, dismiss) {
+  const doc = element.ownerDocument;
+  let stack = dismissableStacks.get(doc);
+  if (!stack) {
+    stack = [];
+    dismissableStacks.set(doc, stack);
+    doc.addEventListener("keydown", onDocumentEscape);
+  }
+
+  const entry = { element, dismiss };
+  stack.push(entry);
+
+  return () => {
+    const index = stack.indexOf(entry);
+    if (index >= 0) stack.splice(index, 1);
+  };
+}
+
+function onDocumentEscape(event) {
+  if (event.key !== "Escape" || event.ctrlKey || event.altKey || event.shiftKey) return;
+
+  const stack = dismissableStacks.get(event.currentTarget);
+  const entry = stack.at(-1);
+  if (!entry) return;
+
+  event.preventDefault();
+  entry.dismiss({ restoreFocus: true });
+}
+
+export function getSurfaceAutoClose(menu) {
+  return surfaceMap.get(menu)?.autoClose ?? "outside";
+}