@cyberskill/design 1.1.1 → 1.3.8

package/components/navigation/Menu.jsx

@@ -1,25 +1,72 @@
 import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
 
 /** CyberSkill Menu — dropdown. Provide a `trigger` element; compose MenuItem children. */
-export function Menu({ trigger, children, align = "start", open: controlledOpen, onOpenChange, className }) {
+export function Menu({ trigger, children, align = "start", open: controlledOpen, onOpenChange, lang, className }) {
   const [uOpen, setUOpen] = React.useState(false);
   const open = controlledOpen != null ? controlledOpen : uOpen;
   const set = (v) => { onOpenChange ? onOpenChange(v) : setUOpen(v); };
-  const ref = React.useRef(null);
+  const [ref, L] = useLang(lang);
+  const t = makeT("Menu", L);
+  const triggerRef = React.useRef(null);
+  const listRef = React.useRef(null);
+
   React.useEffect(() => {
     if (!open) return;
+    const items = () => listRef.current
+      ? [...listRef.current.querySelectorAll('[role="menuitem"]:not([disabled])')]
+      : [];
+    // FIND-040 — move focus into the menu on open.
+    const first = items()[0];
+    if (first && first.focus) first.focus();
+
     const onDoc = (e) => { if (ref.current && !ref.current.contains(e.target)) set(false); };
-    const onKey = (e) => { if (e.key === "Escape") set(false); };
+    const onKey = (e) => {
+      const opts = items();
+      if (e.key === "Escape") {
+        e.preventDefault();
+        set(false);
+        const el = triggerRef.current;
+        if (el && el.focus) el.focus();
+        return;
+      }
+      if (!opts.length) return;
+      const active = document.activeElement;
+      const idx = opts.indexOf(active);
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        (opts[idx < 0 ? 0 : Math.min(opts.length - 1, idx + 1)] || opts[0]).focus();
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        (opts[idx < 0 ? opts.length - 1 : Math.max(0, idx - 1)] || opts[0]).focus();
+      } else if (e.key === "Home") {
+        e.preventDefault();
+        opts[0].focus();
+      } else if (e.key === "End") {
+        e.preventDefault();
+        opts[opts.length - 1].focus();
+      }
+    };
     document.addEventListener("mousedown", onDoc);
     document.addEventListener("keydown", onKey);
-    return () => { document.removeEventListener("mousedown", onDoc); document.removeEventListener("keydown", onKey); };
+    return () => {
+      document.removeEventListener("mousedown", onDoc);
+      document.removeEventListener("keydown", onKey);
+    };
   }, [open]);
+
   const toggle = () => set(!open);
   // ARIA attrs must live on the interactive trigger (button), not a wrapping <span>
   // — axe aria-allowed-attr flags aria-haspopup/aria-expanded on generic elements.
   const triggerNode = React.isValidElement(trigger)
     ? React.cloneElement(trigger, {
+        ref: (node) => {
+          triggerRef.current = node;
+          const r = trigger.ref;
+          if (typeof r === "function") r(node);
+          else if (r && typeof r === "object") r.current = node;
+        },
         "aria-haspopup": "menu",
         "aria-expanded": open,
         onClick: (e) => {
@@ -27,12 +74,19 @@ export function Menu({ trigger, children, align = "start", open: controlledOpen,
           if (!e.defaultPrevented) toggle();
         },
       })
-    : <button type="button" aria-haspopup="menu" aria-expanded={open} onClick={toggle}>{trigger}</button>;
+    : <button type="button" ref={triggerRef} aria-haspopup="menu" aria-expanded={open} onClick={toggle}>{trigger}</button>;
   return (
     <div className={cx("cs-menu", className)} ref={ref}>
       {triggerNode}
       {open ? (
-        <div className={cx("cs-menu__list", align === "end" && "cs-menu__list--end")} role="menu">{children}</div>
+        <div
+          ref={listRef}
+          className={cx("cs-menu__list", align === "end" && "cs-menu__list--end")}
+          role="menu"
+          aria-label={t("menu")}
+        >
+          {children}
+        </div>
       ) : null}
     </div>
   );

package/components/navigation/Steps.d.ts

@@ -8,6 +8,8 @@ export interface StepItem { title: ReactNode; body?: ReactNode; n?: ReactNode; }
 export interface StepsProps {
   steps: StepItem[];
   current?: number;
+  /** "en" | "vi" — else resolved from the nearest [lang] ancestor (vi default). */
+  lang?: string;
   className?: string;
 }
 export function Steps(props: StepsProps): React.ReactElement;

package/components/navigation/Steps.jsx

@@ -1,14 +1,17 @@
 import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
 
 /** CyberSkill Steps — horizontal progress stepper. Steps before `current` are done, `current` is active. */
-export function Steps({ steps = [], current = 0, className }) {
+export function Steps({ steps = [], current = 0, lang, className }) {
+  const [ref, L] = useLang(lang);
+  const t = makeT("Steps", L);
   return (
-    <div className={cx("cs-steps", className)}>
+    <div ref={ref} className={cx("cs-steps", className)} role="list" aria-label={t("label")}>
       {steps.map((s, i) => {
         const state = i < current ? "done" : i === current ? "active" : "todo";
         return (
-          <div key={i} className={cx("cs-step", `cs-step--${state}`)}>
+          <div key={i} className={cx("cs-step", `cs-step--${state}`)} role="listitem">
             <span className="cs-step__marker">{state === "done" ? "✓" : s.n || i + 1}</span>
             <span className="cs-step__title">{s.title}</span>
             {s.body ? <span className="cs-step__body">{s.body}</span> : null}

package/components/navigation/Tabs.d.ts

@@ -11,6 +11,8 @@ export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "o
   tabs: TabItem[];
   value?: string;
   onChange?: (value: string) => void;
+  /** "en" | "vi" — else resolved from the nearest [lang] ancestor (vi default). */
+  lang?: string;
 }
 export function Tabs(props: TabsProps): React.ReactElement;
 

package/components/navigation/Tabs.jsx

@@ -1,10 +1,13 @@
 import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
 
 /** CyberSkill Tabs — data-driven tablist, controlled by value/onChange. Ochre underline on active. */
-export function Tabs({ tabs = [], value, onChange, className, ...props }) {
+export function Tabs({ tabs = [], value, onChange, lang, className, "aria-label": ariaLabel, ...props }) {
+  const [ref, L] = useLang(lang);
+  const t = makeT("Tabs", L);
   const refs = React.useRef([]);
-  const idx = Math.max(0, tabs.findIndex((t) => t.value === value));
+  const idx = Math.max(0, tabs.findIndex((tab) => tab.value === value));
   const key = (e, i) => {
     let n = null;
     if (e.key === "ArrowRight") n = (i + 1) % tabs.length;
@@ -17,7 +20,7 @@ export function Tabs({ tabs = [], value, onChange, className, ...props }) {
     const b = refs.current[n]; if (b) b.focus();
   };
   return (
-    <div role="tablist" className={cx("cs-tabs", className)} {...props}>
+    <div ref={ref} role="tablist" aria-label={ariaLabel ?? t("list")} className={cx("cs-tabs", className)} {...props}>
       {tabs.map((t, i) => (
         <button key={t.value} type="button" role="tab" aria-selected={value === t.value} tabIndex={i === idx ? 0 : -1}
           ref={(el) => (refs.current[i] = el)} onKeyDown={(e) => key(e, i)}

package/components/navigation/Toolbar.d.ts

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 
-/** Horizontal action bar (role=toolbar). Items after `overflowAfter` collapse
- *  into a "⋯" menu (bilingual aria). "-" renders a separator. */
+/** Horizontal action bar (APG toolbar: arrow-key roving among controls).
+ *  Items after `overflowAfter` collapse into a ⋯ menubutton + popup menu
+ *  (bilingual aria). "-" renders a separator. */
 export type ToolbarItem = { label?: ReactNode; icon?: ReactNode; onSelect?: () => void } | "-";
 export interface ToolbarProps {
   items: ToolbarItem[];

package/components/navigation/Toolbar.jsx

@@ -2,31 +2,138 @@ import React from "react";
 import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
 
-/** CyberSkill Toolbar — horizontal action bar; overflow items collapse into a "⋯" menu. items: {label,icon,onSelect} or "-". */
+/** CyberSkill Toolbar — horizontal action bar (APG toolbar arrows); overflow items collapse into a menubutton + popup menu. items: {label,icon,onSelect} or "-". */
 export function Toolbar({ items = [], overflowAfter, label, lang, className }) {
   const [open, setOpen] = React.useState(false);
+  const [focusIdx, setFocusIdx] = React.useState(0);
   const wrap = React.useRef(null);
+  const btnRefs = React.useRef([]);
+  const menuRefs = React.useRef([]);
   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 !== "-");
+  const hasMore = tail.length > 0;
+
+  // Controllable tab stops: head action buttons + optional ⋯ menubutton (separators skipped).
+  const controlMeta = [];
+  head.forEach((it, i) => {
+    if (it !== "-") controlMeta.push({ kind: "head", headIndex: i });
+  });
+  if (hasMore) controlMeta.push({ kind: "more" });
+
   React.useEffect(() => {
     if (!open) return;
     const d = (e) => { if (wrap.current && !wrap.current.contains(e.target)) setOpen(false); };
     document.addEventListener("mousedown", d);
     return () => document.removeEventListener("mousedown", d);
   }, [open]);
+
+  React.useEffect(() => {
+    if (focusIdx >= controlMeta.length) setFocusIdx(Math.max(0, controlMeta.length - 1));
+  }, [focusIdx, controlMeta.length]);
+
+  const focusControl = (i) => {
+    const next = Math.max(0, Math.min(controlMeta.length - 1, i));
+    setFocusIdx(next);
+    requestAnimationFrame(() => {
+      const el = btnRefs.current[next];
+      if (el) el.focus();
+    });
+  };
+
+  const onToolbarKeyDown = (e, i) => {
+    if (e.nativeEvent.isComposing || e.keyCode === 229) return;
+    if (e.key === "ArrowRight") { e.preventDefault(); focusControl(i + 1); }
+    else if (e.key === "ArrowLeft") { e.preventDefault(); focusControl(i - 1); }
+    else if (e.key === "Home") { e.preventDefault(); focusControl(0); }
+    else if (e.key === "End") { e.preventDefault(); focusControl(controlMeta.length - 1); }
+    else if (e.key === "Escape" && open) { e.preventDefault(); setOpen(false); }
+  };
+
+  const onMenuKeyDown = (e, i) => {
+    if (e.nativeEvent.isComposing || e.keyCode === 229) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      const n = Math.min(tail.length - 1, i + 1);
+      const el = menuRefs.current[n]; if (el) el.focus();
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      const n = Math.max(0, i - 1);
+      const el = menuRefs.current[n]; if (el) el.focus();
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      setOpen(false);
+      const moreIdx = controlMeta.findIndex((c) => c.kind === "more");
+      if (moreIdx >= 0) focusControl(moreIdx);
+    } else if (e.key === "Home") {
+      e.preventDefault();
+      const el = menuRefs.current[0]; if (el) el.focus();
+    } else if (e.key === "End") {
+      e.preventDefault();
+      const el = menuRefs.current[tail.length - 1]; if (el) el.focus();
+    }
+  };
+
+  let controlI = 0;
   return (
-    <div ref={(el) => { wrap.current = el; ref.current = el; }} className={cx("cs-toolbar", className)} role="toolbar" aria-label={label}>
-      {head.map((it, i) => it === "-"
-        ? <span key={i} className="cs-toolbar__sep" aria-hidden="true" />
-        : <button key={i} type="button" className="cs-toolbar__btn" onClick={() => it.onSelect && it.onSelect()}>{it.icon}{it.label ? <span>{it.label}</span> : null}</button>)}
-      {tail.length ? (
-        <span className="cs-toolbar__more">
-          <button type="button" className="cs-toolbar__btn" aria-haspopup="menu" aria-expanded={open} aria-label={t("more")} onClick={() => setOpen((o) => !o)}>⋯</button>
-          {open ? <span className="cs-menu__list" role="menu">{tail.map((it, i) => <button key={i} type="button" role="menuitem" className="cs-menu__item" onClick={() => { setOpen(false); it.onSelect && it.onSelect(); }}>{it.label}</button>)}</span> : null}
-        </span>
-      ) : null}
+    <div ref={(el) => { wrap.current = el; ref.current = el; }} className={cx("cs-toolbar", className)} role="toolbar" aria-label={label} aria-orientation="horizontal">
+      {head.map((it, i) => {
+        if (it === "-") return <span key={"sep-" + i} className="cs-toolbar__sep" aria-hidden="true" />;
+        const ci = controlI++;
+        return (
+          <button
+            key={"btn-" + i}
+            type="button"
+            className="cs-toolbar__btn"
+            tabIndex={ci === focusIdx ? 0 : -1}
+            ref={(el) => { btnRefs.current[ci] = el; }}
+            onFocus={() => setFocusIdx(ci)}
+            onKeyDown={(e) => onToolbarKeyDown(e, ci)}
+            onClick={() => it.onSelect && it.onSelect()}
+          >{it.icon}{it.label ? <span>{it.label}</span> : null}</button>
+        );
+      })}
+      {hasMore ? (() => {
+        const ci = controlI++;
+        return (
+          <span className="cs-toolbar__more">
+            <button
+              type="button"
+              className="cs-toolbar__btn"
+              aria-haspopup="menu"
+              aria-expanded={open}
+              aria-label={t("more")}
+              tabIndex={ci === focusIdx ? 0 : -1}
+              ref={(el) => { btnRefs.current[ci] = el; }}
+              onFocus={() => setFocusIdx(ci)}
+              onKeyDown={(e) => {
+                onToolbarKeyDown(e, ci);
+                if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") {
+                  if (!open) { e.preventDefault(); setOpen(true); requestAnimationFrame(() => { const el = menuRefs.current[0]; if (el) el.focus(); }); }
+                }
+              }}
+              onClick={() => setOpen((o) => !o)}
+            >⋯</button>
+            {open ? (
+              <span className="cs-menu__list" role="menu">
+                {tail.map((it, i) => (
+                  <button
+                    key={i}
+                    type="button"
+                    role="menuitem"
+                    className="cs-menu__item"
+                    ref={(el) => { menuRefs.current[i] = el; }}
+                    onKeyDown={(e) => onMenuKeyDown(e, i)}
+                    onClick={() => { setOpen(false); it.onSelect && it.onSelect(); }}
+                  >{it.label}</button>
+                ))}
+              </span>
+            ) : null}
+          </span>
+        );
+      })() : null}
     </div>
   );
 }

package/components/navigation/Toolbar.prompt.md

@@ -1,4 +1,4 @@
-**Toolbar** — action bar with "⋯" overflow menu and "-" separators.
+**Toolbar** — action bar with APG arrow navigation, "⋯" overflow menubutton + popup menu, and "-" separators. Escape closes the overflow menu.
 
 ```jsx
 <Toolbar label="Editor" overflowAfter={3} items={[{icon:<Icon name="edit" size="sm"/>,label:"Edit"},"-",{label:"Share"},{label:"Export"},{label:"Archive"}]}/>

package/components/navigation/navigation.card.html

@@ -11,9 +11,9 @@
   .lbl { font: 600 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .09em; color: var(--cs-color-text-muted); margin-bottom: 10px; }
   .row { display: flex; align-items: center; gap: 20px; flex-wrap: wrap; }
 </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/navigation/shell.card.html

@@ -13,9 +13,9 @@
   .frame .cs-cmdk-scrim { position: absolute; padding-top: 14px; }
   .frame .cs-cmdk { inline-size: 100%; box-shadow: 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/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/ContextMenu.d.ts

@@ -5,6 +5,8 @@ export type ContextMenuItem = { label: ReactNode; onSelect?: () => void; danger?
 export interface ContextMenuProps {
   items: ContextMenuItem[];
   children?: ReactNode;
+  /** "en" | "vi" — else resolved from the nearest [lang] ancestor (vi default). */
+  lang?: string;
   className?: string;
 }
 export function ContextMenu(props: ContextMenuProps): React.ReactElement;

package/components/overlays/ContextMenu.jsx

@@ -1,9 +1,12 @@
 import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
 import { cx } from "../_utils/cx.js";
 
 /** CyberSkill ContextMenu — right-click menu scoped to its children. items: {label,onSelect,danger} or "-" separator. */
-export function ContextMenu({ items = [], children, className }) {
+export function ContextMenu({ items = [], children, lang, className }) {
   const [pos, setPos] = React.useState(null);
+  const [ref, L] = useLang(lang);
+  const t = makeT("ContextMenu", L);
   React.useEffect(() => {
     if (!pos) return;
     const close = () => setPos(null);
@@ -13,11 +16,11 @@ export function ContextMenu({ items = [], children, className }) {
     return () => { document.removeEventListener("click", close); document.removeEventListener("keydown", k); };
   }, [pos]);
   return (
-    <div className={cx("cs-ctxmenu-zone", className)}
+    <div ref={ref} className={cx("cs-ctxmenu-zone", className)}
       onContextMenu={(e) => { e.preventDefault(); const r = e.currentTarget.getBoundingClientRect(); setPos({ x: e.clientX - r.left, y: e.clientY - r.top }); }}>
       {children}
       {pos ? (
-        <div className="cs-menu__list" role="menu" style={{ position: "absolute", insetInlineStart: pos.x, insetBlockStart: pos.y }}>
+        <div className="cs-menu__list" role="menu" aria-label={t("menu")} style={{ position: "absolute", insetInlineStart: pos.x, insetBlockStart: pos.y }}>
           {items.map((it, i) => it === "-"
             ? <div key={i} className="cs-menu__sep" />
             : <button key={i} type="button" role="menuitem" className={cx("cs-menu__item", it.danger && "cs-menu__item--danger")} onClick={() => { setPos(null); it.onSelect && it.onSelect(); }}>{it.label}</button>)}

package/components/overlays/Drawer.d.ts

@@ -13,6 +13,8 @@ export interface DrawerProps {
   side?: "right" | "left";
   children?: ReactNode;
   actions?: ReactNode;
+  /** "en" | "vi" — else resolved from the nearest [lang] ancestor (vi default). */
+  lang?: string;
   className?: string;
 }
 export function Drawer(props: DrawerProps): React.ReactElement | null;

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;