actual-css 0.2.0 → 0.3.0

package/src/js/flyout.js

@@ -1,51 +1,54 @@
-/*
- * Flyout trigger — trigger adapter over the shared action-surface runtime.
- *
- * App menus keep roving focus and menuitem activation. Nav panels reuse the
- * same surface lifecycle without menu semantics.
- */
-
-import enhance, { registerEnhancement } from "./enhance.js";
+import { registerEnhancement } from "./enhance.js";
 import { focusFirstDescendant } from "./focus.js";
-import { focusFirstMenuItem, focusLastMenuItem, getMenuItems } from "./menu.js";
-import { closeSurface, isSurfaceOpen, openSurface, prepareSurface } from "./surface.js";
+import { connectMenu, focusFirstMenuItem, focusLastMenuItem } from "./menu.js";
+import { closeSurface, isSurfaceOpen, openSurface, retainSurface } from "./surface.js";
 
-// trigger -> { flyout, controller }
+const panelRefs = new WeakMap();
 const triggerMap = new WeakMap();
-const FLYOUT_SELECTOR = '[data-enhance~="flyout"]';
-const FLYOUT_TRIGGER_SELECTOR = "[aria-controls][aria-expanded]";
 
-function openFlyout(flyout, trigger) {
-  openSurface(flyout, { trigger, source: trigger });
+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 flyoutFor(trigger) {
-  const flyoutId = trigger.getAttribute("aria-controls");
-  const flyout = flyoutId && trigger.ownerDocument.getElementById(flyoutId);
-  return flyout?.matches(FLYOUT_SELECTOR) ? flyout : null;
+function readFlyoutOptions(panel) {
+  const opts = { autoClose: "true" };
+  const ds = panel.dataset;
+  if (ds.flyoutPlacement) opts.placement = ds.flyoutPlacement;
+  if (ds.flyoutDistance != null) {
+    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;
 }
 
-function isMenuFlyout(flyout) {
-  return flyout.matches("menu");
+function panelFor(trigger) {
+  const id = trigger.getAttribute("aria-controls");
+  return id ? trigger.ownerDocument.getElementById(id) : null;
 }
 
-function resolveCurrentFlyout(trigger, state) {
-  if (state.flyout?.isConnected) return state.flyout;
-
-  const flyout = flyoutFor(trigger);
-  if (!flyout) return null;
+function isMenuFlyout(panel) {
+  return panel.matches("menu") || panel.classList.contains("menu");
+}
 
-  state.flyout = flyout;
-  prepareSurface(flyout);
-  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(flyout)) {
-    trigger.setAttribute("aria-haspopup", "menu");
-  }
-  return flyout;
+function openFlyout(panel, trigger) {
+  return openSurface(panel, {
+    trigger,
+    source: trigger,
+    ...readFlyoutOptions(panel),
+  });
 }
 
 function openAndFocusPanel(flyout, trigger) {
-  if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
-  focusFirstDescendant(flyout);
+  if (!isSurfaceOpen(flyout) && !openFlyout(flyout, trigger)) return false;
+  return focusFirstDescendant(flyout);
 }
 
 function onTriggerClick(e) {
@@ -53,35 +56,34 @@ function onTriggerClick(e) {
   const state = triggerMap.get(trigger);
   if (!state) return;
   e.stopPropagation();
-  const flyout = resolveCurrentFlyout(trigger, state);
-  if (!flyout) return;
-  if (isSurfaceOpen(flyout)) closeSurface(flyout);
-  else openFlyout(flyout, trigger);
+  const panel = resolvePanel(trigger, state);
+  if (!panel) return;
+  if (isSurfaceOpen(panel)) closeSurface(panel);
+  else openFlyout(panel, trigger);
 }
 
 function onTriggerKeydown(e) {
   const trigger = e.currentTarget;
   const state = triggerMap.get(trigger);
   if (!state) return;
-  const flyout = resolveCurrentFlyout(trigger, state);
-  if (!flyout) return;
-  const items = getMenuItems(flyout);
-  const isActionList = items.length > 0;
+  const panel = resolvePanel(trigger, state);
+  if (!panel) return;
+  const isActionList = isMenuFlyout(panel);
 
   if (!isActionList) {
     switch (e.key) {
       case "ArrowDown":
         e.preventDefault();
-        openAndFocusPanel(flyout, trigger);
+        openAndFocusPanel(panel, trigger);
         break;
       case "Enter":
       case " ":
         e.preventDefault();
-        if (isSurfaceOpen(flyout)) closeSurface(flyout);
-        else openAndFocusPanel(flyout, trigger);
+        if (isSurfaceOpen(panel)) closeSurface(panel);
+        else openAndFocusPanel(panel, trigger);
         break;
       case "Tab":
-        if (isSurfaceOpen(flyout) && !e.shiftKey && focusFirstDescendant(flyout)) {
+        if (isSurfaceOpen(panel) && !e.shiftKey && focusFirstDescendant(panel)) {
           e.preventDefault();
         }
         break;
@@ -92,89 +94,104 @@ function onTriggerKeydown(e) {
   switch (e.key) {
     case "ArrowDown":
       e.preventDefault();
-      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
-      focusFirstMenuItem(flyout);
+      if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
+      focusFirstMenuItem(panel);
       break;
     case "ArrowUp":
       e.preventDefault();
-      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
-      focusLastMenuItem(flyout);
+      if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
+      focusLastMenuItem(panel);
       break;
     case "Home":
       e.preventDefault();
-      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
-      focusFirstMenuItem(flyout);
+      if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
+      focusFirstMenuItem(panel);
       break;
     case "End":
       e.preventDefault();
-      if (!isSurfaceOpen(flyout)) openFlyout(flyout, trigger);
-      focusLastMenuItem(flyout);
+      if (!isSurfaceOpen(panel) && !openFlyout(panel, trigger)) break;
+      focusLastMenuItem(panel);
       break;
     case "Enter":
     case " ":
       e.preventDefault();
-      if (!isSurfaceOpen(flyout)) {
-        openFlyout(flyout, trigger);
-        focusFirstMenuItem(flyout);
+      if (!isSurfaceOpen(panel)) {
+        if (openFlyout(panel, trigger)) focusFirstMenuItem(panel);
       } else {
-        closeSurface(flyout);
+        closeSurface(panel);
       }
       break;
     case "Tab":
-      if (isSurfaceOpen(flyout)) closeSurface(flyout);
+      if (isSurfaceOpen(panel)) closeSurface(panel);
       break;
   }
 }
 
 function connectTrigger(trigger) {
   if (triggerMap.has(trigger)) return;
-  const flyout = flyoutFor(trigger);
-  if (!flyout) return;
 
   const controller = new AbortController();
-  triggerMap.set(trigger, { flyout, controller });
+  const state = { panel: null, controller, releaseMenu: null };
+  triggerMap.set(trigger, state);
+
+  resolvePanel(trigger, state);
 
-  prepareSurface(flyout);
   if (!trigger.hasAttribute("aria-expanded")) {
     trigger.setAttribute("aria-expanded", "false");
   }
-  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(flyout)) {
-    trigger.setAttribute("aria-haspopup", "menu");
-  }
 
   trigger.addEventListener("click", onTriggerClick, { signal: controller.signal });
   trigger.addEventListener("keydown", onTriggerKeydown, { signal: controller.signal });
 }
 
+function resolvePanel(trigger, state) {
+  if (state.panel?.isConnected) return state.panel;
+
+  const panel = panelFor(trigger);
+  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);
+  state.panel = panel;
+
+  if (isMenuFlyout(panel)) {
+    state.releaseMenu = connectMenu(panel, {
+      close: (menu) => closeSurface(menu),
+    });
+  }
+  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(panel)) {
+    trigger.setAttribute("aria-haspopup", "menu");
+  }
+
+  return panel;
+}
+
 function disconnectTrigger(trigger) {
   const state = triggerMap.get(trigger);
   if (!state) return;
+  state.releaseMenu?.();
   state.controller.abort();
-  if (state.flyout?.isConnected && isSurfaceOpen(state.flyout)) {
-    closeSurface(state.flyout, { restoreFocus: false });
+  if (state.panel?.isConnected && isSurfaceOpen(state.panel)) {
+    closeSurface(state.panel, { restoreFocus: false });
   }
   triggerMap.delete(trigger);
-}
 
-function connectFlyout(flyout) {
-  if (!flyout.id) return;
-  const triggers = flyout.ownerDocument.querySelectorAll(
-    `${FLYOUT_TRIGGER_SELECTOR}[aria-controls="${CSS.escape(flyout.id)}"]`,
-  );
-  for (const trigger of triggers) {
-    if (!triggerMap.has(trigger)) connectTrigger(trigger);
+  const panelEntry = state.panel ? panelRefs.get(state.panel) : undefined;
+  if (panelEntry) {
+    panelEntry.triggers.delete(trigger);
+    if (panelEntry.triggers.size === 0) {
+      panelEntry.release();
+      panelRefs.delete(state.panel);
+    }
   }
 }
 
-enhance({
-  [FLYOUT_TRIGGER_SELECTOR]: (trigger) => {
-    connectTrigger(trigger);
-    return () => disconnectTrigger(trigger);
-  },
-});
-
-registerEnhancement("flyout", (flyout) => {
-  connectFlyout(flyout);
-  // Surface owns its own teardown; the marker enhancer in surface.js
-  // calls disconnectSurface(el, { restore: false }) on sweep.
+registerEnhancement("flyout", (trigger) => {
+  connectTrigger(trigger);
+  return () => disconnectTrigger(trigger);
 });

package/src/js/focus-group.js

@@ -0,0 +1,116 @@
+import { itemForKey } from "./keys.js";
+
+const ORIENTATIONS = new Set(["horizontal", "vertical"]);
+
+function restoreTabIndex(item, value) {
+  if (value == null) item.removeAttribute("tabindex");
+  else item.setAttribute("tabindex", value);
+}
+
+export function connectFocusGroup(root, opts = {}) {
+  if (!root?.addEventListener || !root?.contains) {
+    throw new TypeError("connectFocusGroup() requires a root element.");
+  }
+  if (typeof opts.getItems !== "function") {
+    throw new TypeError("connectFocusGroup() requires getItems().");
+  }
+
+  const orientation = opts.orientation || "horizontal";
+  if (!ORIENTATIONS.has(orientation)) {
+    throw new TypeError(`Invalid focus-group orientation: ${orientation}`);
+  }
+
+  const controller = new AbortController();
+  const externalSignal = opts.signal || null;
+  const originalTabIndex = new Map();
+  let remembered = null;
+  let disconnected = false;
+
+  function getItems() {
+    const seen = new Set();
+    return [...(opts.getItems() || [])].filter((item) => {
+      if (typeof item?.focus !== "function" || !root.contains(item) || seen.has(item)) return false;
+      seen.add(item);
+      return true;
+    });
+  }
+
+  function restore(item) {
+    if (!originalTabIndex.has(item)) return;
+    restoreTabIndex(item, originalTabIndex.get(item));
+    originalTabIndex.delete(item);
+  }
+
+  function sync(preferred = remembered) {
+    if (disconnected) return [];
+
+    const items = getItems();
+    const itemSet = new Set(items);
+    for (const item of originalTabIndex.keys()) {
+      if (!itemSet.has(item)) restore(item);
+    }
+
+    const active = root.ownerDocument.activeElement;
+    const target =
+      (itemSet.has(preferred) && preferred) ||
+      (itemSet.has(active) && active) ||
+      items.find((item) => item.tabIndex === 0) ||
+      items[0] ||
+      null;
+
+    for (const item of items) {
+      if (!originalTabIndex.has(item)) {
+        originalTabIndex.set(item, item.getAttribute("tabindex"));
+      }
+      const tabIndex = item === target ? 0 : -1;
+      item.tabIndex = tabIndex;
+    }
+    remembered = target;
+    return items;
+  }
+
+  function onFocusIn(event) {
+    const items = getItems();
+    if (items.includes(event.target)) sync(event.target);
+  }
+
+  function onKeydown(event) {
+    const items = sync();
+    const current = root.ownerDocument.activeElement;
+    if (!items.includes(current)) return;
+
+    const style = root.ownerDocument.defaultView?.getComputedStyle?.(root);
+    const direction = style?.direction === "rtl" ? "rtl" : "ltr";
+    const target = itemForKey(items, current, event.key, {
+      orientation,
+      wrap: opts.wrap === true,
+      direction,
+    });
+    if (!target) return;
+
+    event.preventDefault();
+    sync(target);
+    target.focus();
+  }
+
+  root.addEventListener("focusin", onFocusIn, { signal: controller.signal });
+  root.addEventListener("keydown", onKeydown, { signal: controller.signal });
+
+  sync();
+
+  function disconnect() {
+    if (disconnected) return;
+    disconnected = true;
+    externalSignal?.removeEventListener("abort", disconnect);
+    controller.abort();
+    for (const item of originalTabIndex.keys()) restore(item);
+    remembered = null;
+  }
+
+  if (externalSignal) {
+    if (externalSignal.aborted) disconnect();
+    else externalSignal.addEventListener("abort", disconnect, { once: true });
+  }
+
+  return { sync, disconnect };
+}

package/src/js/focus.js

@@ -12,7 +12,12 @@ const FOCUSABLE_SELECTOR = [
 export function isElementVisible(el) {
   if (!el || el.hidden) return false;
   if (typeof el.checkVisibility === "function") return el.checkVisibility();
-  return el.getClientRects().length > 0;
+  if (el.getClientRects().length === 0) return false;
+  // checkVisibility() covers visibility:hidden; without it, read the
+  // computed direction of the cascade so a hidden element is not focusable.
+  const style = el.ownerDocument?.defaultView?.getComputedStyle?.(el);
+  if (!style) return true;
+  return style.visibility !== "hidden" && style.visibility !== "collapse";
 }
 
 function isFocusable(el) {

package/src/js/index.js

@@ -14,8 +14,7 @@
 import "./flyout.js";
 import "./context-menu.js";
 import "./dialog.js";
-// Legacy <dialog> shim for browsers below Baseline 2023; omit in custom builds.
-import "./dialog-fallback.js";
+import "./dismiss.js";
 import "./tab.js";
 import "./tooltip.js";
 import "./scrollspy.js";
@@ -24,3 +23,6 @@ import "./mask.js";
 import "./password.js";
 import "./validation.js";
 import "./status.js";
+import { watchEnhancementManifests } from "./enhancement-loader.js";
+
+watchEnhancementManifests();

package/src/js/input.js

@@ -7,7 +7,7 @@ export function selectionStart(el) {
 }
 
 export function setCaret(el, position) {
-  if (document.activeElement !== el) return;
+  if (el.ownerDocument.activeElement !== el) return;
   if (typeof el.setSelectionRange !== "function") return;
   try {
     el.setSelectionRange(position, position);

package/src/js/keys.js

@@ -28,3 +28,30 @@ export function nextItem(items, current, delta, opts = {}) {
   const wrapped = ((next % items.length) + items.length) % items.length;
   return items[wrapped];
 }
+
+export function itemForKey(items, current, key, opts = {}) {
+  const orientation = opts.orientation || "horizontal";
+  const wrap = opts.wrap === true;
+  const direction = opts.direction || "ltr";
+
+  switch (key) {
+    case "Home":
+      return firstItem(items);
+    case "End":
+      return lastItem(items);
+    case "ArrowRight":
+      if (orientation !== "horizontal") return null;
+      return nextItem(items, current, direction === "rtl" ? -1 : 1, { wrap });
+    case "ArrowLeft":
+      if (orientation !== "horizontal") return null;
+      return nextItem(items, current, direction === "rtl" ? 1 : -1, { wrap });
+    case "ArrowDown":
+      if (orientation !== "vertical") return null;
+      return nextItem(items, current, 1, { wrap });
+    case "ArrowUp":
+      if (orientation !== "vertical") return null;
+      return nextItem(items, current, -1, { wrap });
+    default:
+      return null;
+  }
+}

package/src/js/mask.js

@@ -55,21 +55,22 @@ function rawMaskChars(value, mask) {
   return parseMaskValue(value, mask).raw;
 }
 
-function appendFollowingLiterals(mask, start) {
+function appendFollowingLiterals(pattern, start) {
   let out = "";
-  for (let i = start; i < mask.length && !isToken(mask[i]); i++) {
-    out += mask[i];
+  for (let i = start; i < pattern.length && !isToken(pattern[i]); i++) {
+    out += pattern[i];
   }
   return out;
 }
 
 function formatRaw(raw, mask, inputType = "") {
   const autoLiteral = inputType.startsWith("insert");
+  const pattern = [...mask];
   let rawIndex = 0;
   let out = "";
 
-  for (let i = 0; i < mask.length; i++) {
-    const token = mask[i];
+  for (let i = 0; i < pattern.length; i++) {
+    const token = pattern[i];
 
     if (!isToken(token)) {
       if (rawIndex < raw.length) out += token;
@@ -89,7 +90,7 @@ function formatRaw(raw, mask, inputType = "") {
     if (!matched) break;
 
     if (autoLiteral && rawIndex >= raw.length) {
-      out += appendFollowingLiterals(mask, i + 1);
+      out += appendFollowingLiterals(pattern, i + 1);
       break;
     }
   }

package/src/js/menu.js

@@ -1,15 +1,9 @@
 import { isElementVisible } from "./focus.js";
-import { firstItem, lastItem, nextItem } from "./keys.js";
-
-const MENU_ITEM = 'button, a, [role="menuitem"]';
-// Mirrors the item contract in flyout.css: an item sits directly in the surface,
-// or directly in any of its <li> — bare list, or grouped section > ul > li.
-// `:scope li` must stay a *descendant* combinator for that second form; the
-// grouped flyouts in docs/ui.md lose roving focus with `:scope > li`.
-// Scoping is what keeps a neighbouring surface's items out: this selector only
-// ever runs against one surface, and hasMenuItem() resolves the clicked item
-// through this list rather than through a global closest().
-const MENU_ITEM_SELECTOR = `:scope > :is(${MENU_ITEM}), :scope li > :is(${MENU_ITEM})`;
+import { connectFocusGroup } from "./focus-group.js";
+import { firstItem, itemForKey, lastItem } from "./keys.js";
+
+const MENU_ITEM_SELECTOR = ":scope > li > .menu-item";
+const MENU_ITEM_ROLES = new Set(["menuitem", "menuitemcheckbox", "menuitemradio"]);
 
 function isUsableMenuItem(item) {
   return (
@@ -25,7 +19,7 @@ export function getMenuItems(menu) {
 }
 
 function isAriaMenuItem(item) {
-  return item.getAttribute("role") === "menuitem";
+  return MENU_ITEM_ROLES.has(item.getAttribute("role"));
 }
 
 function activateCurrentItem(menu) {
@@ -40,9 +34,13 @@ export function hasMenuItems(menu) {
   return getMenuItems(menu).length > 0;
 }
 
+function getMenuItem(menu, target) {
+  const item = target?.closest?.(".menu-item");
+  return item?.parentElement?.parentElement === menu ? item : null;
+}
+
 export function hasMenuItem(menu, target) {
-  const item = target?.closest?.(MENU_ITEM);
-  return !!item && getMenuItems(menu).includes(item);
+  return !!getMenuItem(menu, target);
 }
 
 export function focusFirstMenuItem(menu) {
@@ -53,28 +51,22 @@ export function focusLastMenuItem(menu) {
   lastItem(getMenuItems(menu))?.focus();
 }
 
-export function onMenuKeydown(e, { close }) {
+export function onMenuKeydown(e, { close, navigate = true }) {
   const menu = e.currentTarget;
-  const items = getMenuItems(menu);
-  if (!items.length) return;
+  if (navigate) {
+    const items = getMenuItems(menu);
+    const target = itemForKey(items, menu.ownerDocument.activeElement, e.key, {
+      orientation: "vertical",
+      wrap: true,
+    });
+    if (target) {
+      e.preventDefault();
+      target.focus();
+      return;
+    }
+  }
 
   switch (e.key) {
-    case "ArrowDown":
-      e.preventDefault();
-      nextItem(items, menu.ownerDocument.activeElement, 1, { wrap: true })?.focus();
-      break;
-    case "ArrowUp":
-      e.preventDefault();
-      nextItem(items, menu.ownerDocument.activeElement, -1, { wrap: true })?.focus();
-      break;
-    case "Home":
-      e.preventDefault();
-      firstItem(items)?.focus();
-      break;
-    case "End":
-      e.preventDefault();
-      lastItem(items)?.focus();
-      break;
     case "Tab":
       close(menu);
       break;
@@ -82,8 +74,69 @@ export function onMenuKeydown(e, { close }) {
     case " ":
       if (activateCurrentItem(menu)) {
         e.preventDefault();
-        close(menu);
       }
       break;
   }
 }
+
+// Menu wiring is a shared, ref-counted resource: a menu may be retained by
+// several triggers (or by flyout and context-menu at once), so the listeners
+// and their AbortController belong to the menu, not to any single caller.
+// Each retain returns a release(); the wiring is torn down on the last one.
+const menuConnections = new WeakMap();
+
+export function connectMenu(menu, { close }) {
+  let entry = menuConnections.get(menu);
+
+  if (!entry) {
+    const controller = new AbortController();
+    const focusGroup = menu.matches('[role="menu"]')
+      ? connectFocusGroup(menu, {
+          getItems: () => getMenuItems(menu).filter(isAriaMenuItem),
+          orientation: "vertical",
+          wrap: true,
+          signal: controller.signal,
+        })
+      : null;
+    menu.addEventListener(
+      "keydown",
+      (event) =>
+        onMenuKeydown(event, {
+          close: () => close(menu),
+          navigate: !focusGroup,
+        }),
+      { signal: controller.signal },
+    );
+    menu.addEventListener(
+      "click",
+      (event) => {
+        const item = getMenuItem(menu, event.target);
+        if (!item) return;
+
+        if (item.matches(":disabled, [aria-disabled='true']")) {
+          event.preventDefault();
+          // A disabled command must not reach the surface-level inside-click
+          // policy and dismiss the menu as if it had been activated.
+          event.stopPropagation();
+          return;
+        }
+      },
+      { signal: controller.signal },
+    );
+    entry = { count: 0, controller, focusGroup };
+    menuConnections.set(menu, entry);
+  }
+
+  entry.count++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    entry.count--;
+    if (entry.count <= 0) {
+      entry.focusGroup?.disconnect();
+      entry.controller.abort();
+      menuConnections.delete(menu);
+    }
+  };
+}