@cyberskill/design 1.1.1 → 1.3.8

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">

package/components/overlays/alertdialog.card.html

@@ -11,9 +11,9 @@
   .frame .cs-dialog-layer { position: absolute; }
   .frame .cs-dialog { top: 28px; }
 </style>
-<script src="https://unpkg.com/umd-react@19.2.8/dist/react.development.js" integrity="sha384-r22tQd8qRIHDPIkmdXZcVtvPi1Tj2x1QaW2tmFQHEvHscATUnHQ5siTyxWw5PMUs" crossorigin="anonymous"></script>
-<script src="https://unpkg.com/umd-react@19.2.8/dist/react-dom.development.js" integrity="sha384-gJZYmumEmwqVmX3JVsLZq+4QrxoPGh/BW47Rk7SqNPCPFpTGnRtvmeRPJ7//ZDPk" crossorigin="anonymous"></script>
-<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_vendor/react/react.production.min.js"></script>
+<script src="../../_vendor/react/react-dom.production.min.js"></script>
+<script src="../../_vendor/babel/babel.min.js"></script>
 <script src="../../_ds_bundle.js"></script>
 </head>
 <body>

package/components/overlays/overlays.card.html

@@ -11,9 +11,9 @@
   .frame { position: relative; overflow: hidden; height: 260px; border: 1px solid var(--cs-color-border-default); border-radius: var(--cs-radius-lg); background: var(--cs-color-surface-raised); }
   .frame .cs-drawer-scrim, .frame .cs-drawer { position: absolute; animation: none; }
 </style>
-<script src="https://unpkg.com/umd-react@19.2.8/dist/react.development.js" integrity="sha384-r22tQd8qRIHDPIkmdXZcVtvPi1Tj2x1QaW2tmFQHEvHscATUnHQ5siTyxWw5PMUs" crossorigin="anonymous"></script>
-<script src="https://unpkg.com/umd-react@19.2.8/dist/react-dom.development.js" integrity="sha384-gJZYmumEmwqVmX3JVsLZq+4QrxoPGh/BW47Rk7SqNPCPFpTGnRtvmeRPJ7//ZDPk" crossorigin="anonymous"></script>
-<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_vendor/react/react.production.min.js"></script>
+<script src="../../_vendor/react/react-dom.production.min.js"></script>
+<script src="../../_vendor/babel/babel.min.js"></script>
 <script src="../../_ds_bundle.js"></script>
 </head>
 <body>

package/components/textfield/textfield.card.html

@@ -9,9 +9,9 @@
   body { margin: 0; background: var(--cs-color-surface-page); padding: 22px 24px; }
   .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 18px 24px; max-width: 640px; }
 </style>
-<script src="https://unpkg.com/umd-react@19.2.8/dist/react.development.js" integrity="sha384-r22tQd8qRIHDPIkmdXZcVtvPi1Tj2x1QaW2tmFQHEvHscATUnHQ5siTyxWw5PMUs" crossorigin="anonymous"></script>
-<script src="https://unpkg.com/umd-react@19.2.8/dist/react-dom.development.js" integrity="sha384-gJZYmumEmwqVmX3JVsLZq+4QrxoPGh/BW47Rk7SqNPCPFpTGnRtvmeRPJ7//ZDPk" crossorigin="anonymous"></script>
-<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_vendor/react/react.production.min.js"></script>
+<script src="../../_vendor/react/react-dom.production.min.js"></script>
+<script src="../../_vendor/babel/babel.min.js"></script>
 <script src="../../_ds_bundle.js"></script>
 </head>
 <body>