actual-css 0.1.0 → 0.3.0

package/src/js/surface.js

@@ -1,17 +1,49 @@
+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();
+
+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();
+
+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;
+
+  let reaper = reapers.get(root);
+  if (!reaper) {
+    reaper = enhance(
+      { [`[${SURFACE_MARKER}]`]: (el) => () => disconnectSurface(el, { restore: false }) },
+      root,
+    );
+    reapers.set(root, reaper);
+  }
+  return reaper;
+}
 
 function waitForAnimations(...elements) {
   const animations = elements
@@ -52,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
   );
 }
 
@@ -120,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");
@@ -140,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 = {
@@ -159,93 +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);
 
-  const controller = new AbortController();
+  ensureDocumentClick(menu);
   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(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;
 }
@@ -255,6 +253,31 @@ export function prepareSurface(menu) {
   menu.style.position = "fixed";
   menu.hidden = true;
   syncExpanded(menu, false);
+  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) {
+      disconnectSurface(panel, { restore: false });
+      surfaceRetainers.delete(panel);
+    }
+  };
 }
 
 export function openSurface(menu, opts = {}) {
@@ -269,7 +292,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;
@@ -280,10 +303,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;
@@ -293,10 +319,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;
 }
 
@@ -317,6 +349,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 });
@@ -332,27 +367,86 @@ export function closeSurface(menu, opts = {}) {
   });
 }
 
-export function disconnectSurface(menu) {
+export function disconnectSurface(menu, { restore = true } = {}) {
   if (!menu) return;
+  if (!restore) mountedSurfaces.delete(menu);
   closeSurface(menu);
   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);
 }
 
-// Global outside-click listener runs at import time; keep SSR imports inert.
-if (typeof document !== "undefined") {
-  document.addEventListener("click", (e) => {
-    for (const menu of openSurfaces) {
-      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;
+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) 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);
+  }
+}
+
+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";
 }

package/src/js/tab.js

@@ -1,7 +1,7 @@
 /*
  * Tabs — in-place panel switcher using real tab semantics.
  *
- * Tab list:  .tabs[role="tablist"]
+ * Tab list:  [data-enhance="tabs"] with role="tablist"
  * Tab:       [role="tab"]  with aria-selected, aria-controls, id, tabindex
  * Panel:     [role="tabpanel"]  with id matching aria-controls
  *
@@ -9,20 +9,24 @@
  *            ArrowUp/Down for aria-orientation="vertical"
  *            ArrowDown (focus selected panel)
  *
- * Self-registers via enhance: injected tablists wire automatically.
+ * Self-registers via registerEnhancement: injected tablists wire automatically.
  * The tab→panel map is rebuilt from the live tablist on each interaction,
  * so tabs added after connect are picked up with no extra work.
  * Cleanup is the AbortController.abort() returned to enhance.
  */
 
-import enhance from "./enhance.js";
-import { firstItem, lastItem, nextItem } from "./keys.js";
-import { CLASSES } from "./selectors.js";
+import { registerEnhancement } from "./enhance.js";
+import { itemForKey } from "./keys.js";
 
-const TABLIST_SELECTOR = `.${CLASSES.tabs}[role="tablist"]`;
+const TABLIST_SELECTOR = '[data-enhance~="tabs"]';
 
+// A tablist owns only the tabs directly beneath it, not those of a nested
+// tablist. Filtering by closest owner keeps the outer list from operating on
+// (and re-reacting to events from) tabs that belong to an inner list.
 function tabsOf(list) {
-  return [...list.querySelectorAll('[role="tab"]')];
+  return [...list.querySelectorAll('[role="tab"]')].filter(
+    (tab) => tab.closest(TABLIST_SELECTOR) === list,
+  );
 }
 
 function panelsOf(tabs) {
@@ -36,7 +40,7 @@ function panelsOf(tabs) {
 
 function panelFor(tab) {
   const panelId = tab.getAttribute("aria-controls");
-  return panelId ? document.getElementById(panelId) : null;
+  return panelId ? tab.ownerDocument.getElementById(panelId) : null;
 }
 
 function isTabDisabled(tab) {
@@ -90,68 +94,46 @@ function initialize(list) {
 }
 
 function onKeydown(e) {
+  const list = e.currentTarget;
   const tab = e.target.closest('[role="tab"]');
-  if (!tab) return;
-  const list = tab.closest(TABLIST_SELECTOR);
-  if (!list) return;
+  if (!tab || tab.closest(TABLIST_SELECTOR) !== list) return;
 
   const tabs = activatableTabs(list);
   if (!tabs.length || !tabs.includes(tab)) return;
   const isVertical = list.getAttribute("aria-orientation") === "vertical";
-  let next;
 
-  switch (e.key) {
-    case "ArrowRight":
-      if (isVertical) break;
-      e.preventDefault();
-      next = nextItem(tabs, tab, 1, { wrap: true });
-      if (next) activateAndFocus(next);
-      break;
-    case "ArrowLeft":
-      if (isVertical) break;
-      e.preventDefault();
-      next = nextItem(tabs, tab, -1, { wrap: true });
-      if (next) activateAndFocus(next);
-      break;
-    case "ArrowDown":
-      if (!isVertical) {
-        e.preventDefault();
-        const panel = panelFor(tab);
-        if (panel) {
-          makePanelFocusable(panel);
-          panel.focus();
-        }
-        break;
-      }
-      e.preventDefault();
-      next = nextItem(tabs, tab, 1, { wrap: true });
-      if (next) activateAndFocus(next);
-      break;
-    case "ArrowUp":
-      if (!isVertical) break;
-      e.preventDefault();
-      next = nextItem(tabs, tab, -1, { wrap: true });
-      if (next) activateAndFocus(next);
-      break;
-    case "Home":
-      e.preventDefault();
-      activateAndFocus(firstItem(tabs));
-      break;
-    case "End":
-      e.preventDefault();
-      activateAndFocus(lastItem(tabs));
-      break;
-    case "Enter":
-    case " ":
+  if (e.key === "ArrowDown" && !isVertical) {
+    const panel = panelFor(tab);
+    if (panel) {
       e.preventDefault();
-      activate(tab);
-      break;
+      makePanelFocusable(panel);
+      panel.focus();
+    }
+    return;
+  }
+
+  if (e.key === "Enter" || e.key === " ") {
+    e.preventDefault();
+    activate(tab);
+    return;
   }
+
+  const direction = list.ownerDocument.defaultView?.getComputedStyle(list).direction || "ltr";
+  const target = itemForKey(tabs, tab, e.key, {
+    orientation: isVertical ? "vertical" : "horizontal",
+    wrap: true,
+    direction,
+  });
+  if (!target) return;
+
+  e.preventDefault();
+  activateAndFocus(target);
 }
 
 function onClick(e) {
+  const list = e.currentTarget;
   const tab = e.target.closest('[role="tab"]');
-  if (!tab) return;
+  if (!tab || tab.closest(TABLIST_SELECTOR) !== list) return;
   if (isTabDisabled(tab)) {
     e.preventDefault();
     return;
@@ -162,12 +144,10 @@ function onClick(e) {
   tab.focus();
 }
 
-enhance({
-  [TABLIST_SELECTOR]: (list) => {
-    const controller = new AbortController();
-    initialize(list);
-    list.addEventListener("click", onClick, { signal: controller.signal });
-    list.addEventListener("keydown", onKeydown, { signal: controller.signal });
-    return () => controller.abort();
-  },
+registerEnhancement("tabs", (list) => {
+  const controller = new AbortController();
+  initialize(list);
+  list.addEventListener("click", onClick, { signal: controller.signal });
+  list.addEventListener("keydown", onKeydown, { signal: controller.signal });
+  return () => controller.abort();
 });