@cyberskill/design 1.1.0 → 1.2.0

package/components/navigation/Toolbar.jsx

@@ -9,7 +9,8 @@ export function Toolbar({ items = [], overflowAfter, label, lang, className }) {
   const [ref, L] = useLang(lang);
   const t = makeT("Toolbar", L);
   const cut = overflowAfter != null ? overflowAfter : items.length;
-  const head = items.slice(0, cut), tail = items.filter((x) => x !== "-").slice(cut);
+  const head = items.slice(0, cut);
+  const tail = items.slice(cut).filter((x) => x !== "-");
   React.useEffect(() => {
     if (!open) return;
     const d = (e) => { if (wrap.current && !wrap.current.contains(e.target)) setOpen(false); };

package/components/overlays/AlertDialog.jsx

@@ -1,26 +1,12 @@
 import React from "react";
 import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
-
-const FOCUSABLE = [
-  'a[href]',
-  'area[href]',
-  'button:not([disabled])',
-  'input:not([disabled]):not([type="hidden"])',
-  'select:not([disabled])',
-  'textarea:not([disabled])',
-  'audio[controls]',
-  'video[controls]',
-  'summary',
-  'iframe',
-  '[contenteditable]:not([contenteditable="false"])',
-  '[tabindex]:not([tabindex="-1"])',
-].join(",");
+import { useOverlayLayer } from "./OverlayManager.jsx";
 
 /**
  * CyberSkill AlertDialog — first-class destructive/confirm modal (role=alertdialog).
  * Distinct from Popconfirm (inline bubble) and Dialog (general modal). Focus trap +
- * restore; bilingual confirm/cancel via the registry.
+ * restore via overlay manager; bilingual confirm/cancel via the registry.
  */
 export function AlertDialog({
   open,
@@ -53,40 +39,24 @@ export function AlertDialog({
     onOpenChange?.(next);
   };
   const destructive = (tone ?? variant) === "destructive";
-  const confirmRef = React.useRef(onConfirm); confirmRef.current = onConfirm;
-  const cancelRef = React.useRef(onCancel); cancelRef.current = onCancel;
+  const confirmRef = React.useRef(onConfirm);
+  confirmRef.current = onConfirm;
+  const cancelRef = React.useRef(onCancel);
+  cancelRef.current = onCancel;
+  const setOpenRef = React.useRef(setOpen);
+  setOpenRef.current = setOpen;
 
-  React.useEffect(() => {
-    if (!isOpen) return;
-    const prev = document.activeElement;
-    const prevOverflow = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    const focusables = () => (panel.current ? [...panel.current.querySelectorAll(FOCUSABLE)] : []);
-    // Prefer the confirm action for destructive prompts (WAI-ARIA alertdialog).
-    const preferred = panel.current?.querySelector(".cs-alert-dialog__confirm") || focusables()[0];
-    (preferred || panel.current)?.focus?.();
-    const k = (e) => {
-      if (e.key === "Escape") {
-        setOpen(false);
-        cancelRef.current?.();
-        return;
-      }
-      if (e.key !== "Tab" || !panel.current) return;
-      const f = focusables();
-      if (!f.length) { e.preventDefault(); panel.current.focus(); return; }
-      const a = f[0], z = f[f.length - 1];
-      const active = document.activeElement;
-      const inside = panel.current.contains(active);
-      if (e.shiftKey && (!inside || active === a)) { e.preventDefault(); z.focus(); }
-      else if (!e.shiftKey && (!inside || active === z)) { e.preventDefault(); a.focus(); }
-    };
-    document.addEventListener("keydown", k);
-    return () => {
-      document.removeEventListener("keydown", k);
-      document.body.style.overflow = prevOverflow;
-      if (prev && prev.focus) prev.focus();
-    };
-  }, [isOpen]);
+  useOverlayLayer({
+    open: isOpen,
+    kind: "modal",
+    trapFocus: true,
+    preferFocusSelector: ".cs-alert-dialog__confirm",
+    onEscape: () => {
+      setOpenRef.current(false);
+      cancelRef.current?.();
+    },
+    panelRef: panel,
+  });
 
   const cl = cancelLabel != null ? cancelLabel : t("cancel");
   const cf = confirmLabel != null ? confirmLabel : t("confirm");

package/components/overlays/Drawer.jsx

@@ -1,35 +1,39 @@
 import React from "react";
 import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
+import { useOverlayLayer } from "./OverlayManager.jsx";
 
 /** CyberSkill Drawer — slide-in side panel with scrim. side: right (default) | left. */
 export function Drawer({ open, onClose, title, side = "right", children, actions, lang, className }) {
   const [ref, L] = useLang(lang);
-  React.useEffect(() => {
-    if (!open) return;
-    const prev = document.activeElement;
-    const SEL = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
-    const p = ref.current;
-    const first = p ? p.querySelector(SEL) : null;
-    (first || p) && (first || p).focus();
-    const k = (e) => {
-      if (e.key === "Escape") { onClose && onClose(); return; }
-      if (e.key !== "Tab" || !ref.current) return;
-      const f = [...ref.current.querySelectorAll(SEL)];
-      if (!f.length) return;
-      const a = f[0], z = f[f.length - 1];
-      if (e.shiftKey && document.activeElement === a) { e.preventDefault(); z.focus(); }
-      else if (!e.shiftKey && document.activeElement === z) { e.preventDefault(); a.focus(); }
-    };
-    document.addEventListener("keydown", k);
-    return () => { document.removeEventListener("keydown", k); if (prev && prev.focus) prev.focus(); };
-  }, [open]);
+  const panel = React.useRef(null);
+  const closeRef = React.useRef(onClose);
+  closeRef.current = onClose;
+
+  useOverlayLayer({
+    open: !!open,
+    kind: "modal",
+    trapFocus: true,
+    onEscape: () => closeRef.current && closeRef.current(),
+    panelRef: panel,
+  });
+
   const t = makeT("Drawer", L);
   if (!open) return null;
   return (
     <>
       <div className="cs-drawer-scrim" onClick={onClose} aria-hidden="true" />
-      <aside ref={ref} tabIndex={-1} className={cx("cs-drawer", side === "left" && "cs-drawer--left", className)} role="dialog" aria-modal="true" aria-label={typeof title === "string" ? title : t("panel")}>
+      <aside
+        ref={(el) => {
+          panel.current = el;
+          ref.current = el;
+        }}
+        tabIndex={-1}
+        className={cx("cs-drawer", side === "left" && "cs-drawer--left", className)}
+        role="dialog"
+        aria-modal="true"
+        aria-label={typeof title === "string" ? title : t("panel")}
+      >
         <div className="cs-drawer__header">
           {title ? <h2 className="cs-drawer__title">{title}</h2> : null}
           <button type="button" className="cs-drawer__close" aria-label={t("close")} onClick={onClose}>

package/components/overlays/OverlayManager.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode, RefObject } from "react";
+
+export type OverlayLayerKind = "dropdown" | "popover" | "modal" | "toast" | "tour";
+
+export type OverlayLayerRegistration = {
+  id?: string;
+  kind: OverlayLayerKind;
+  trapFocus?: boolean;
+  lockScroll?: boolean;
+  onEscape?: () => void;
+  restoreEl?: HTMLElement | null;
+};
+
+export type OverlayManagerApi = {
+  register(layer: OverlayLayerRegistration): () => void;
+  top(): OverlayLayerRegistration | null;
+  readonly scrollLocked: boolean;
+  readonly depth: number;
+};
+
+export function getOverlayManager(): OverlayManagerApi;
+
+export function OverlayProvider(props: { children?: ReactNode }): JSX.Element;
+
+export function useOverlayLayer(opts: {
+  open: boolean;
+  kind?: OverlayLayerKind;
+  trapFocus?: boolean;
+  lockScroll?: boolean;
+  onEscape?: () => void;
+  panelRef?: RefObject<HTMLElement | null>;
+  preferFocusSelector?: string;
+}): { manager: OverlayManagerApi };
+
+export function attachFocusTrap(
+  panelEl: HTMLElement | null,
+  opts?: { handleEscape?: boolean; onEscape?: () => void }
+): () => void;
+
+export const focusableSelector: string;

package/components/overlays/OverlayManager.jsx

@@ -0,0 +1,214 @@
+import React from "react";
+
+/** Shared focusable selector for modal traps (Dialog / AlertDialog / Drawer / CommandPalette). */
+export const focusableSelector = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  'input:not([disabled]):not([type="hidden"])',
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "audio[controls]",
+  "video[controls]",
+  "summary",
+  "iframe",
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * Attach Tab wrap + Escape (optional) to a panel. Returns cleanup.
+ * Prefer registering Escape via the overlay manager so nested modals stack correctly.
+ */
+export function attachFocusTrap(panelEl, { handleEscape = false, onEscape } = {}) {
+  if (!panelEl) return () => {};
+  const focusables = () => [...panelEl.querySelectorAll(focusableSelector)];
+  const k = (e) => {
+    if (handleEscape && e.key === "Escape") {
+      onEscape && onEscape();
+      return;
+    }
+    if (e.key !== "Tab") return;
+    const f = focusables();
+    if (!f.length) {
+      e.preventDefault();
+      panelEl.focus();
+      return;
+    }
+    const a = f[0];
+    const z = f[f.length - 1];
+    const active = document.activeElement;
+    const inside = panelEl.contains(active);
+    if (e.shiftKey && (!inside || active === a)) {
+      e.preventDefault();
+      z.focus();
+    } else if (!e.shiftKey && (!inside || active === z)) {
+      e.preventDefault();
+      a.focus();
+    }
+  };
+  document.addEventListener("keydown", k);
+  return () => document.removeEventListener("keydown", k);
+}
+
+function createOverlayManager() {
+  const layers = [];
+  let prevOverflow = "";
+  let locked = false;
+  let escapeBound = false;
+
+  /** Innermost panel last — React child effects run before parents, so push-order alone is wrong. */
+  const resort = () => {
+    layers.sort((a, b) => {
+      const pa = a.panelEl;
+      const pb = b.panelEl;
+      if (pa && pb && pa !== pb) {
+        if (pa.contains(pb)) return -1; // a outer → below
+        if (pb.contains(pa)) return 1;
+      }
+      return (a.seq || 0) - (b.seq || 0);
+    });
+  };
+
+  const applyScroll = () => {
+    const need = layers.some((l) => l.kind === "modal" && l.lockScroll !== false);
+    if (need && !locked) {
+      prevOverflow = document.body.style.overflow;
+      document.body.style.overflow = "hidden";
+      locked = true;
+    } else if (!need && locked) {
+      document.body.style.overflow = prevOverflow;
+      locked = false;
+    }
+  };
+
+  const onDocEscape = (e) => {
+    if (e.key !== "Escape") return;
+    if (!layers.length) return;
+    resort();
+    const top = layers[layers.length - 1];
+    if (!top || typeof top.onEscape !== "function") return;
+    // Registered overlays (modals) always own Escape while on the stack.
+    // Menu/Popover/etc. are not registered here — they keep their own listeners.
+    e.preventDefault();
+    e.stopPropagation();
+    top.onEscape();
+  };
+
+  const ensureEscape = () => {
+    if (escapeBound) return;
+    escapeBound = true;
+    document.addEventListener("keydown", onDocEscape, true);
+  };
+
+  let seq = 0;
+  return {
+    register(layer) {
+      ensureEscape();
+      const id = layer.id || `cs-ov-${++seq}`;
+      const entry = { ...layer, id, seq: ++seq };
+      layers.push(entry);
+      resort();
+      applyScroll();
+      return () => {
+        resort();
+        const i = layers.findIndex((l) => l.id === id);
+        const wasTop = i === layers.length - 1;
+        if (i >= 0) layers.splice(i, 1);
+        applyScroll();
+        if (wasTop && entry.restoreEl && typeof entry.restoreEl.focus === "function") {
+          try {
+            entry.restoreEl.focus();
+          } catch {
+            /* ignore */
+          }
+        }
+      };
+    },
+    top() {
+      resort();
+      return layers[layers.length - 1] || null;
+    },
+    get scrollLocked() {
+      return locked;
+    },
+    get depth() {
+      return layers.length;
+    },
+  };
+}
+
+const defaultManager = createOverlayManager();
+const OverlayContext = React.createContext(null);
+
+/** Return the active manager (context or module singleton). */
+export function getOverlayManager() {
+  return defaultManager;
+}
+
+/**
+ * Optional provider — mounts `#cs-overlay-root` for portals and supplies a
+ * dedicated manager instance. When omitted, components use the module singleton.
+ */
+export function OverlayProvider({ children }) {
+  const api = React.useMemo(() => createOverlayManager(), []);
+  return (
+    <OverlayContext.Provider value={api}>
+      <div id="cs-overlay-root" data-cs-overlay-root="" />
+      {children}
+    </OverlayContext.Provider>
+  );
+}
+
+/**
+ * Register an overlay layer while `open` is true. Owns Escape (topmost only)
+ * and modal scroll-lock refcount. Tab trap is attached when `trapFocus` + `panelRef`.
+ */
+export function useOverlayLayer({
+  open,
+  kind = "modal",
+  trapFocus = false,
+  lockScroll,
+  onEscape,
+  panelRef,
+  preferFocusSelector,
+}) {
+  const ctx = React.useContext(OverlayContext);
+  const mgr = ctx || defaultManager;
+  const escapeRef = React.useRef(onEscape);
+  escapeRef.current = onEscape;
+
+  React.useLayoutEffect(() => {
+    if (!open) return undefined;
+    const restoreEl = typeof document !== "undefined" ? document.activeElement : null;
+    const panel = panelRef && panelRef.current;
+    const unregister = mgr.register({
+      kind,
+      lockScroll: lockScroll != null ? lockScroll : kind === "modal",
+      onEscape: () => escapeRef.current && escapeRef.current(),
+      restoreEl,
+      panelEl: panel || null,
+    });
+
+    // Only the innermost (top) layer should move focus / trap Tab — outer parents
+    // run layout effects after children and must not steal focus from nested alerts.
+    let detachTrap = () => {};
+    const top = mgr.top();
+    const isTop = top && top.panelEl === panel;
+    if (trapFocus && panel && isTop) {
+      const preferred =
+        (preferFocusSelector && panel.querySelector(preferFocusSelector)) ||
+        panel.querySelector(focusableSelector) ||
+        panel;
+      preferred && preferred.focus && preferred.focus();
+      detachTrap = attachFocusTrap(panel, { handleEscape: false });
+    }
+
+    return () => {
+      detachTrap();
+      unregister();
+    };
+  }, [open, kind, trapFocus, lockScroll, mgr, panelRef, preferFocusSelector]);
+
+  return { manager: mgr };
+}

package/components/overlays/OverlayManager.prompt.md

@@ -0,0 +1,12 @@
+**OverlayProvider / overlay manager** — single stack for modal Escape, scroll-lock
+refcount, and focus restore. Wrap product shells when nesting overlays; Dialog /
+AlertDialog / Drawer / CommandPalette already register via the module singleton
+when no provider is mounted.
+
+```jsx
+<OverlayProvider>
+  <App />
+</OverlayProvider>
+```
+
+See `docs/decisions/overlay-manager-design.md`.

package/components/overlays/Tour.jsx

@@ -6,30 +6,37 @@ import { cx } from "../_utils/cx.js";
 export function Tour({ steps = [], open, onClose, lang, className }) {
   const [i, setI] = React.useState(0);
   const [rect, setRect] = React.useState(null);
+  const [pop, setPop] = React.useState({ top: 80, left: 40 });
   const [ref, L] = useLang(lang);
   const t = makeT("Tour", L);
   React.useEffect(() => { if (open) setI(0); }, [open]);
   React.useEffect(() => {
-    if (!open || !steps[i]) return;
+    if (!open || !steps[i]) return undefined;
     const el = document.querySelector(steps[i].target);
     if (el) {
       const r = el.getBoundingClientRect();
-      setRect({ x: r.left - 6, y: r.top - 6, w: r.width + 12, h: r.height + 12 });
-    } else setRect(null);
+      const next = { x: r.left - 6, y: r.top - 6, w: r.width + 12, h: r.height + 12 };
+      setRect(next);
+      setPop({
+        top: Math.min(window.innerHeight - 170, next.y + next.h + 12),
+        left: Math.max(12, Math.min(window.innerWidth - 292, next.x)),
+      });
+    } else {
+      setRect(null);
+      setPop({ top: 80, left: 40 });
+    }
     const k = (e) => { if (e.key === "Escape") onClose && onClose(); };
     document.addEventListener("keydown", k);
     return () => document.removeEventListener("keydown", k);
-  }, [open, i, steps]);
+  }, [open, i, steps, onClose]);
   if (!open || !steps.length) return <span ref={ref} style={{ display: "none" }} />;
   const s = steps[i];
   const last = i === steps.length - 1;
-  const popTop = rect ? Math.min(window.innerHeight - 170, rect.y + rect.h + 12) : 80;
-  const popLeft = rect ? Math.max(12, Math.min(window.innerWidth - 292, rect.x)) : 40;
   return (
     <div ref={ref} className={cx("cs-tour", className)}>
       <div className="cs-tour__scrim" onClick={onClose} />
       {rect ? <div className="cs-tour__hole" style={{ left: rect.x, top: rect.y, width: rect.w, height: rect.h }} /> : null}
-      <div className="cs-tour__pop" role="dialog" aria-label={typeof s.title === "string" ? s.title : undefined} style={{ left: popLeft, top: popTop }}>
+      <div className="cs-tour__pop" role="dialog" aria-label={typeof s.title === "string" ? s.title : undefined} style={{ left: pop.left, top: pop.top }}>
         <b>{s.title}</b>
         {s.body ? <p>{s.body}</p> : null}
         <div className="cs-tour__bar">