@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/src/components/DropdownMenu/dropdown-menu-keyboard.ts

@@ -0,0 +1,255 @@
+/**
+ * @internal — DropdownMenu 的鍵盤接線:選單開著按 Tab、子選單裡按 Esc(2026-09-25 user 拍板,待辦總帳 B10 / B11)。
+ * 不進 barrel(只有 dropdown-menu.tsx 消費)。
+ *
+ * 2026-09-26 從 dropdown-menu.tsx 拆出(該檔 879 行,超過 `scripts/code-quality-audit.mjs` 的 800 行上限;
+ * 待辦總帳〇節「dropdown-menu.tsx 879 行超過 800 行上限,拆檔」)。拆法:dropdown-menu.tsx 只留視覺層,
+ * 開關狀態 / 觸發點登記 / Tab / Esc 全部住這裡;「從觸發點算下一站」合併進 `lib/focus-after-trigger.ts`(與 SelectMenu 共用一份)。
+ *
+ * 規則住所 = `ds-canonical/references/keyboard-model-canonical.md`「彈出框開著時的 Tab 與 Esc」,本檔只做機械落地:
+ *   Tab / Shift+Tab:收起全部層,從「開啟者」往下 / 往上走一站(= 在開啟者上按 Tab)。
+ *     Radix 預設把 Tab 擋掉(@radix-ui/react-menu@2.1.16 dist/index.mjs:305;上游 menu.tsx:570-572
+ *     https://github.com/radix-ui/primitives/blob/f7ecd5ab16f5e1e820eb5786a1419a98a2d594ae/packages/react/menu/src/menu.tsx#L570-L572)。
+ *   子選單 Esc:只關這一層、焦點回上一層那一項(= ←)。Radix 預設關整棵(menu.tsx:1262-1266
+ *     https://github.com/radix-ui/primitives/blob/f7ecd5ab16f5e1e820eb5786a1419a98a2d594ae/packages/react/menu/src/menu.tsx#L1262-L1266)。
+ * user 原話(逐字,附條件同意):選單 Tab「你確定這個符合我們一致的設計語言且不違背世界級的設計就這樣做」;
+ * 子選單 Esc「你確定這符合我們一致的設計語言且不違背世界級的設計就這樣做」。
+ */
+import * as React from 'react'
+import { flushSync } from 'react-dom'
+import { focusFromTrigger } from '@/design-system/lib/focus-after-trigger'
+
+/** 能拿焦點的元素(判斷「觸發點本身能不能當開啟者」用) */
+const FOCUSABLE = 'a[href], area[href], button, input, select, textarea, iframe, summary, [contenteditable]:not([contenteditable="false"]), [tabindex]'
+
+/** 選單各層(含收合動畫中還掛著的那層)不是頁面上的一站 */
+const isInsideMenu = (el: HTMLElement) => !!el.closest('[data-radix-menu-content]')
+
+function assignRef<T>(ref: React.ForwardedRef<T>, value: T | null) {
+  if (typeof ref === 'function') ref(value)
+  else if (ref) ref.current = value
+}
+
+/**
+ * 選單的「開啟者」—— Tab 離開時從它算下一站。
+ * 觸發點自己能聚焦 → 就是它(一般情況)。觸發點只是透明錨點(AgentFab 右鍵選單:錨點是蓋在按鈕上、aria-hidden 的 span)→
+ * 改找「宣告 `aria-controls` 指向本選單」的可聚焦元素(ARIA 的 menu button 關係本來就是這樣寫);再不行才找包住觸發點的可聚焦祖先。
+ */
+function menuOpener(trigger: HTMLElement | null, content: HTMLElement | null): HTMLElement | null {
+  if (!trigger) return null
+  if (trigger.matches(FOCUSABLE) && !trigger.matches(':disabled')) return trigger
+  const id = content?.id
+  if (id) {
+    const owner = Array.from(trigger.ownerDocument.querySelectorAll<HTMLElement>('[aria-controls]')).find(
+      (el) => el !== trigger && (el.getAttribute('aria-controls') ?? '').split(/\s+/).includes(id) && el.matches(FOCUSABLE),
+    )
+    if (owner) return owner
+  }
+  return trigger.parentElement?.closest<HTMLElement>(FOCUSABLE) ?? null
+}
+
+/** 整個選單(根)共用的鍵盤狀態:誰是觸發點、根內容是哪個元素、這次關閉是不是 Tab 走掉的 */
+export interface DropdownMenuKeyboard {
+  closeAll: () => void
+  triggerRef: React.MutableRefObject<HTMLElement | null>
+  contentRef: React.MutableRefObject<HTMLElement | null>
+  /** 這次關閉是 Tab 離開 → 焦點已由使用者帶走,關閉時不再自動聚焦(不還觸發點、也不呼叫 consumer 的 onCloseAutoFocus) */
+  tabbedOutRef: React.MutableRefObject<boolean>
+}
+const DropdownMenuKeyboardContext = React.createContext<DropdownMenuKeyboard | null>(null)
+
+/** 每一層(根 / 每個子選單)各一份:「關掉這一層」。子選單已在收合動畫中時,再按 Esc 交給上一層。 */
+export interface DropdownMenuLevel {
+  closeLevel: () => void
+  triggerRef: React.MutableRefObject<HTMLElement | null>
+}
+const DropdownMenuLevelContext = React.createContext<DropdownMenuLevel | null>(null)
+
+/**
+ * 選單開著按 Tab(B11):收起全部層,焦點從開啟者往下 / 往上走一站;頁面上已沒有下一站 → 留在開啟者(X20)。
+ * 只處理「焦點就在這一層」按下的 Tab;子層的 Tab 由子層處理,冒泡到上層時已 defaultPrevented。
+ */
+function handleMenuTab(event: React.KeyboardEvent<HTMLElement>, keyboard: DropdownMenuKeyboard | null) {
+  if (!keyboard || event.key !== 'Tab' || event.defaultPrevented) return
+  if (event.altKey || event.ctrlKey || event.metaKey) return
+  if ((event.target as Element).closest('[data-radix-menu-content]') !== event.currentTarget) return
+  const opener = menuOpener(keyboard.triggerRef.current, keyboard.contentRef.current)
+  if (!opener) return // 找不到開啟者 → 留給 Radix 預設(不動),總比把焦點丟到頁尾好
+  event.preventDefault()
+  keyboard.tabbedOutRef.current = true
+  // 先同步關掉:modal 選單的 FocusScope 焦點鎖要先解除,否則 focus() 會被拉回選單裡
+  flushSync(() => keyboard.closeAll())
+  focusFromTrigger(opener, event.shiftKey, isInsideMenu)
+}
+
+/** 開關狀態由 DS 這一層擁有、受控地交給 Radix:Tab 離開(B11)與子選單 Esc 傳到根(B10)都要從 DS 這一側關掉選單 */
+function useOwnedOpenState(open: boolean | undefined, defaultOpen: boolean | undefined, onOpenChange?: (open: boolean) => void) {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen ?? false)
+  const resolvedOpen = open ?? uncontrolledOpen
+  const setOpen = React.useCallback(
+    (nextOpen: boolean) => {
+      if (open === undefined) setUncontrolledOpen(nextOpen)
+      onOpenChange?.(nextOpen)
+    },
+    [onOpenChange, open],
+  )
+  return [resolvedOpen, setOpen] as const
+}
+
+export interface OpenStateProps {
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+/** 根:開關狀態 + 鍵盤狀態 + 根這一層的「關掉這一層」(交給 `DropdownMenuKeyboardProvider` 包住 Radix Root)。 */
+export function useDropdownMenuRootKeyboard({ open, defaultOpen, onOpenChange }: OpenStateProps) {
+  const [resolvedOpen, setOpen] = useOwnedOpenState(open, defaultOpen, onOpenChange)
+  const triggerRef = React.useRef<HTMLElement | null>(null)
+  const contentRef = React.useRef<HTMLElement | null>(null)
+  const tabbedOutRef = React.useRef(false)
+  const handleOpenChange = React.useCallback(
+    (nextOpen: boolean) => {
+      if (nextOpen) tabbedOutRef.current = false
+      setOpen(nextOpen)
+    },
+    [setOpen],
+  )
+  const keyboard = React.useMemo<DropdownMenuKeyboard>(
+    () => ({ closeAll: () => handleOpenChange(false), triggerRef, contentRef, tabbedOutRef }),
+    [handleOpenChange],
+  )
+  const level = React.useMemo<DropdownMenuLevel>(
+    () => ({ closeLevel: () => handleOpenChange(false), triggerRef }),
+    [handleOpenChange],
+  )
+  return { resolvedOpen, handleOpenChange, keyboard, level }
+}
+
+/** 子選單:開關狀態 + 「關掉這一層」(B10:Esc 只關最內層、焦點回上一層那一項)。 */
+export function useDropdownMenuSubKeyboard({ open, defaultOpen, onOpenChange }: OpenStateProps) {
+  const [resolvedOpen, handleOpenChange] = useOwnedOpenState(open, defaultOpen, onOpenChange)
+  const parent = React.useContext(DropdownMenuLevelContext)
+  const triggerRef = React.useRef<HTMLElement | null>(null)
+  const level = React.useMemo<DropdownMenuLevel>(
+    () => ({
+      closeLevel: () => {
+        // 這一層已經在收合動畫中(Radix 的 DismissableLayer 還掛著、仍是最上層)→ 這次 Esc 屬於上一層
+        if (!resolvedOpen) {
+          parent?.closeLevel()
+          return
+        }
+        // 與 Radix 子選單的 ← 同一組動作(上游 menu.tsx:1271-1274 onOpenChange(false) + trigger.focus())
+        handleOpenChange(false)
+        triggerRef.current?.focus()
+      },
+      triggerRef,
+    }),
+    [handleOpenChange, parent, resolvedOpen],
+  )
+  return { resolvedOpen, handleOpenChange, level }
+}
+
+/** 根用:鍵盤狀態 + 根這一層(`useDropdownMenuRootKeyboard` 的回傳值原樣傳進來) */
+export function DropdownMenuKeyboardProvider({ keyboard, level, children }: {
+  keyboard: DropdownMenuKeyboard
+  level: DropdownMenuLevel
+  children: React.ReactNode
+}) {
+  return React.createElement(
+    DropdownMenuKeyboardContext.Provider,
+    { value: keyboard },
+    React.createElement(DropdownMenuLevelContext.Provider, { value: level }, children),
+  )
+}
+
+/** 子選單用:這一層(`useDropdownMenuSubKeyboard` 的回傳值原樣傳進來) */
+export function DropdownMenuLevelProvider({ level, children }: { level: DropdownMenuLevel; children: React.ReactNode }) {
+  return React.createElement(DropdownMenuLevelContext.Provider, { value: level }, children)
+}
+
+/** 觸發點:記下它,選單開著按 Tab 時從它算下一站(B11) */
+export function useMenuTriggerRef<T extends HTMLElement>(ref: React.ForwardedRef<T>) {
+  const keyboard = React.useContext(DropdownMenuKeyboardContext)
+  return React.useCallback(
+    (node: T | null) => {
+      if (keyboard) keyboard.triggerRef.current = node
+      assignRef(ref, node)
+    },
+    [keyboard, ref],
+  )
+}
+
+/** 子選單觸發項:記下它,子選單按 Esc 只關這一層時焦點回到它(B10) */
+export function useSubMenuTriggerRef<T extends HTMLElement>(ref: React.ForwardedRef<T>) {
+  const level = React.useContext(DropdownMenuLevelContext)
+  return React.useCallback(
+    (node: T | null) => {
+      if (level) level.triggerRef.current = node
+      assignRef(ref, node)
+    },
+    [level, ref],
+  )
+}
+
+/**
+ * 根內容:記下它(觸發點是透明錨點時靠它的 id 找開啟者)、接上 Tab、Tab 離開時擋掉關閉後的自動聚焦。
+ * Focus return on close 的其餘情形不 override —— 用 Radix 內建 default(close 時 focus 還 trigger;
+ * outside-interaction 例外由 Radix `hasInteractedOutsideRef` 自管;W3C APG menubar「Escape: …return focus to the element…
+ * from which the menu was opened」)。唯一例外是 Tab 離開:焦點已由使用者帶到下一站,沒有「關閉後自動聚焦」這回事 →
+ * 擋掉 Radix 的還觸發點,也不轉給 consumer 的 onCloseAutoFocus(否則像「還焦點給編輯器」的 consumer 會把焦點拉回去,X21)。
+ */
+export function useMenuContentKeyboard<T extends HTMLElement>(
+  ref: React.ForwardedRef<T>,
+  onKeyDown: React.KeyboardEventHandler<T> | undefined,
+  onCloseAutoFocus: ((event: Event) => void) | undefined,
+) {
+  const keyboard = React.useContext(DropdownMenuKeyboardContext)
+  const setRef = React.useCallback(
+    (node: T | null) => {
+      if (keyboard) keyboard.contentRef.current = node
+      assignRef(ref, node)
+    },
+    [keyboard, ref],
+  )
+  return {
+    ref: setRef,
+    onKeyDown: (event: React.KeyboardEvent<T>) => {
+      onKeyDown?.(event)
+      handleMenuTab(event, keyboard)
+    },
+    onCloseAutoFocus: (event: Event) => {
+      if (keyboard?.tabbedOutRef.current) {
+        keyboard.tabbedOutRef.current = false
+        event.preventDefault()
+        return
+      }
+      onCloseAutoFocus?.(event)
+    },
+  }
+}
+
+/**
+ * 子選單內容:Tab 同樣收起全部層、從根的開啟者往下走(W3C「close all menus and submenus」);
+ * Esc 只關這一層、焦點回上一層那一項(B10)。preventDefault 讓 Radix 的 rootContext.onClose() 不跑
+ *(composeEventHandlers 見 defaultPrevented 就跳過內建 handler);consumer 自己 preventDefault = 不關,照 Radix 慣例。
+ */
+export function useSubMenuContentKeyboard<T extends HTMLElement>(
+  onKeyDown: React.KeyboardEventHandler<T> | undefined,
+  onEscapeKeyDown: ((event: KeyboardEvent) => void) | undefined,
+) {
+  const keyboard = React.useContext(DropdownMenuKeyboardContext)
+  const level = React.useContext(DropdownMenuLevelContext)
+  return {
+    onKeyDown: (event: React.KeyboardEvent<T>) => {
+      onKeyDown?.(event)
+      handleMenuTab(event, keyboard)
+    },
+    onEscapeKeyDown: (event: KeyboardEvent) => {
+      onEscapeKeyDown?.(event)
+      if (event.defaultPrevented || !level) return
+      event.preventDefault()
+      level.closeLevel()
+    },
+  }
+}

package/src/components/DropdownMenu/dropdown-menu.anatomy.stories.tsx

@@ -8,6 +8,7 @@ import {
   DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent,
 } from './dropdown-menu'
 import { Button } from '@/design-system/components/Button/button'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 
 const meta: Meta = {
   title: 'Design System/Components/DropdownMenu/設計規格',
@@ -123,18 +124,6 @@ const TokenAnnotation = ({ colors }: { colors: ColorSpec }) => (
   </div>
 )
 
-const Tab = ({ active, onClick, disabled, children }: { active: boolean; onClick: () => void; disabled?: boolean; children: React.ReactNode }) => {
-  if (disabled) return <span className="px-2.5 py-1 text-[12px] font-mono rounded-md text-fg-disabled bg-neutral-hover cursor-not-allowed">{children}</span>
-  return (
-    <button type="button" onClick={onClick}
-      className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
-        active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
-      }`}>
-      {children}
-    </button>
-  )
-}
-
 const PropRow = ({ label, dot, children }: { label: string; dot?: string; children: React.ReactNode }) => (
   <div className="flex items-start gap-3 py-2 border-b border-divider last:border-b-0">
     <span className="text-[11px] text-fg-muted font-medium w-[72px] shrink-0 pt-0.5 flex items-center gap-1.5">
@@ -316,33 +305,35 @@ const InspectorInner = () => {
 
   return (
     <div className="flex flex-col gap-6">
-      {/* Controls */}
+      {/* Controls — 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項;
+          取代手刻 Tab:它靜止借 neutral-hover、hover 借 neutral-active,是 color.spec.md 成對 token 的錯配) */}
       <div className="flex flex-col gap-2.5">
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Size</span>
-          <div className="flex gap-1.5">
-            {(['sm', 'md', 'lg'] as const).map((sz) => <Tab key={sz} active={size === sz} onClick={() => setSize(sz)}>{sz}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Size" value={size} onValueChange={(v) => setSize(v as SizeKey)}>
+            {(['sm', 'md', 'lg'] as const).map((sz) => <SegmentedControlItem key={sz} value={sz}>{sz}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Item</span>
-          <div className="flex gap-1.5">
-            {(['item', 'checkbox', 'subTrigger'] as const).map((m) => <Tab key={m} active={itemMode === m} onClick={() => setItemMode(m)}>{m}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Item" value={itemMode} onValueChange={(v) => setItemMode(v as ItemMode)}>
+            {(['item', 'checkbox', 'subTrigger'] as const).map((m) => <SegmentedControlItem key={m} value={m}>{m}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Danger</span>
-          <div className="flex gap-1.5">
-            <Tab active={!danger} onClick={() => setDanger(false)}>off</Tab>
-            <Tab active={danger && canDanger} onClick={() => setDanger(true)} disabled={!canDanger}>on</Tab>
-          </div>
+          {/* 停用項用元件自身 disabled(segmented-control.spec.md「disabled」);停用項不得是當前值 → value 取 hasDanger */}
+          <SegmentedControl size="sm" aria-label="Danger" value={hasDanger ? 'on' : 'off'} onValueChange={(v) => setDanger(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={!canDanger}>on</SegmentedControlItem>
+          </SegmentedControl>
           {!canDanger && <span className="text-[11px] text-fg-muted">僅限 Item</span>}
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">State</span>
-          <div className="flex gap-1.5">
-            {STATES.map((st) => <Tab key={st} active={state === st} onClick={() => setState(st)}>{st}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="State" value={state} onValueChange={(v) => setState(v as StateKey)}>
+            {STATES.map((st) => <SegmentedControlItem key={st} value={st}>{st}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
       </div>
 
@@ -486,7 +477,9 @@ const ItemPreview = ({ size, danger, state, icon: Icon, label, shortcut }: {
   const textClass = danger ? 'text-error' : state === 'disabled' ? 'text-fg-disabled' : ''
   const fontClass = size === 'lg' ? 'text-body-lg' : 'text-body'
   return (
+    // aria-disabled:靜態預覽畫的是「停用中的項目」,明告 inactive 才不會被 axe 當一般文字誤報 color-contrast(2026-09-29,待辦總帳 OE21;三個 Preview 同修)
     <div className={`flex items-start gap-2 px-3 ${fontClass} leading-compact ${bgClass} ${textClass}`}
+      aria-disabled={state === 'disabled' || undefined}
       style={{ paddingTop: `calc((var(--field-height-${size}) - 1lh) / 2)`, paddingBottom: `calc((var(--field-height-${size}) - 1lh) / 2)` }}>
       <div className="h-[1lh] flex items-center shrink-0"><Icon size={iconPx} /></div>
       <span>{label}</span>
@@ -505,6 +498,7 @@ const SubTriggerPreview = ({ size, state, icon: Icon, label, triggerValue }: {
   const fontClass = size === 'lg' ? 'text-body-lg' : 'text-body'
   return (
     <div className={`flex items-start gap-2 px-3 ${fontClass} leading-compact ${bgClass} ${textClass}`}
+      aria-disabled={state === 'disabled' || undefined}
       style={{ paddingTop: `calc((var(--field-height-${size}) - 1lh) / 2)`, paddingBottom: `calc((var(--field-height-${size}) - 1lh) / 2)` }}>
       <div className="h-[1lh] flex items-center shrink-0"><Icon size={iconPx} /></div>
       <span>{label}</span>
@@ -527,6 +521,7 @@ const CheckboxPreview = ({ size, label, checked, state }: {
   const checkboxPx = SIZE_SPECS[size].icon
   return (
     <div className={`flex items-start gap-2 px-3 ${fontClass} leading-compact ${bgClass} ${textClass}`}
+      aria-disabled={state === 'disabled' || undefined}
       style={{ paddingTop: `calc((var(--field-height-${size}) - 1lh) / 2)`, paddingBottom: `calc((var(--field-height-${size}) - 1lh) / 2)` }}>
       <div className="h-[1lh] flex items-center shrink-0">
         <div className={`rounded border flex items-center justify-center shrink-0 ${isCheckedVisual ? 'bg-primary border-primary' : 'border-border'}`}
@@ -577,7 +572,9 @@ export const ColorMatrix = {
                   const isCheckboxSelected = type === 'checkbox' && st === 'active/selected'
                   return (
                     <td key={st} className="p-3 border-b border-divider align-top min-w-[160px]">
+                      {/* aria-disabled:disabled 那一格畫的是停用中的項目,明告 inactive 才不會被 axe 當一般文字誤報 color-contrast(2026-09-29,待辦總帳 OE21) */}
                       <div className="rounded px-3 py-1.5 text-body leading-compact border border-border flex items-center gap-2"
+                        aria-disabled={st === 'disabled' || undefined}
                         style={{
                           backgroundColor: `var(${ITEM_TOKEN_MAP[type][st].bg})`,
                           color: `var(${ITEM_TOKEN_MAP[type][st].text})`,
@@ -619,6 +616,7 @@ export const ColorMatrix = {
                 {STATES.map((st) => (
                   <td key={st} className="p-3 border-b border-divider align-top min-w-[160px]">
                     <div className="rounded px-3 py-1.5 text-body leading-compact border border-border flex items-center gap-2"
+                      aria-disabled={st === 'disabled' || undefined}
                       style={{
                         backgroundColor: `var(${DANGER_ITEM_MAP[st].bg})`,
                         color: `var(${DANGER_ITEM_MAP[st].text})`,
@@ -847,8 +845,8 @@ const StateBehaviorInner = () => {
           <AnimationFrame label="closing" state="closing" desc="animate-out,~150ms duration" />
         </div>
         <div className="text-caption text-fg-muted pt-2 border-t border-divider">
-          觸發 `close` 的路徑:(a) 點擊 item(auto close)/ (b) Esc / (c) 外部點擊(onPointerDownOutside)/ (d) blur。
-          Trigger 會回到 focused 狀態,保留鍵盤流程。
+          觸發 `close` 的路徑:(a) 點擊 item(auto close)/ (b) Esc / (c) 外部點擊(onPointerDownOutside)/ (d) blur / (e) Tab / Shift+Tab。
+          (a)(b) 焦點回到 Trigger,保留鍵盤流程;(c) 焦點留在點的地方;(e) 焦點從 Trigger 往下 / 往上走一站(2026-09-25,spec「鍵盤操作」)。
         </div>
       </div>
 
@@ -856,7 +854,7 @@ const StateBehaviorInner = () => {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">行為 2:Submenu 展開(hover/focus 延遲 + sideways slide)</span>
         <Desc>
-          SubTrigger hover 約 100ms 自動展開 submenu 向右側滑入。Submenu 是獨立 floating layer——與 parent 共存,parent 不 close。鍵盤用 ArrowRight 展開 / ArrowLeft 收起；本 DS 為 LTR-only。
+          SubTrigger hover 約 100ms 自動展開 submenu 向右側滑入。Submenu 是獨立 floating layer——與 parent 共存,parent 不 close。鍵盤用 ArrowRight 展開 / ArrowLeft 或 Esc 收起這一層(2026-09-25 起 Esc 只關一層);本 DS 為 LTR-only。
         </Desc>
         <div className="flex gap-6 items-start">
           <div className="flex items-center justify-center px-6 py-8 rounded-lg bg-canvas border border-divider min-w-[280px]">
@@ -885,7 +883,7 @@ const StateBehaviorInner = () => {
               ChevronRight suffix 是 SubTrigger 的視覺 affordance(消費 item-anatomy row 主檔,不自刻)。
             </div>
             <div className="pt-1 border-t border-divider">
-              鍵盤:焦點在 SubTrigger 時 ArrowRight 展開、ArrowLeft 回 parent。
+              鍵盤:焦點在 SubTrigger 時 ArrowRight 展開;在子選單裡 ArrowLeft 或 Esc 只收這一層、焦點回 SubTrigger。
             </div>
           </div>
         </div>
@@ -943,9 +941,10 @@ const StateBehaviorInner = () => {
           <li>`DropdownMenuItem` 點擊即 close——這是「action 觸發即完成」語意。</li>
           <li>`DropdownMenuCheckboxItem` 點擊不 close——每次勾選即時生效(onCheckedChange 即時 fire),menu 保持開啟只為讓使用者連續多選。</li>
           <li>`DropdownMenuSub` 永遠右側滑入,parent menu 保持展開——提供 breadcrumb 式認知流,使用者知道自己在哪層。</li>
-          <li>Escape close 整個選單(含所有展開子層;Radix root close)。ArrowLeft 才逐層收合(焦點回 SubTrigger)。</li>
+          <li>Escape 一次只關焦點所在的那一層:子選單 → 焦點回上一層那一項(與 ArrowLeft 同);主選單 → 焦點回 trigger。每按一次少一層(2026-09-25 起;原本 Radix 預設一次全關,待辦總帳 B10)。</li>
+          <li>選單開著按 Tab / Shift+Tab:一次收起全部層,焦點從 trigger 往下 / 往上走一站(2026-09-25 起;原本 Radix 預設擋掉 Tab,待辦總帳 B11)。</li>
           <li>Portal render 到 body,`z-50` 確保不被 parent overflow 截斷。</li>
-          <li>Focus trap:menu open 時鍵盤焦點進入 menu,close 時自動 restore 到 trigger。</li>
+          <li>焦點不鎖在選單裡(預設非 modal):open 時鍵盤焦點進入 menu;Esc / 選了項目 → 回 trigger,點外面 → 留在點的地方,Tab → 下一站。</li>
         </ul>
       </div>
     </div>
@@ -964,7 +963,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"無障礙能力沿用 Radix 選單元件的內建支援,涵蓋語意角色、選單導覽與焦點管理,設計師與工程師不需額外設定。\n\n鍵盤操作:\n\n- Tab — 將焦點移到觸發按鈕\n- Enter / Space / 向下鍵 — 開啟選單\n- 向上鍵 / 向下鍵 — 在選項之間移動\n- Home / End — 跳到第一項 / 最後一項(PageUp / PageDown 同)\n- 輸入首字 — 跳到標籤符合的選項\n- Enter / Space — 選擇目前的選項\n- Esc — 關閉整個選單(含子選單;逐層收合用左方向鍵)\n\n焦點管理:選單開啟時焦點會進入選單,關閉後自動回到原本的觸發按鈕;目前導覽到的選項會以明顯的 highlight 底色標示,鍵盤使用者隨時看得到自己在哪一項。\n\n驗證:鍵盤可完整操作(不需滑鼠),文字對比達 WCAG AA;在 Storybook 無障礙檢查面板上應為零項嚴重問題。"}</p>
+      <p className="whitespace-pre-line">{"無障礙能力沿用 Radix 選單元件的內建支援,涵蓋語意角色、選單導覽與焦點管理(Tab 與子選單的 Esc 兩鍵由本元件改寫,見下),設計師與工程師不需額外設定。\n\n鍵盤操作:\n\n- Tab — 將焦點移到觸發按鈕\n- Enter / Space / 向下鍵 — 開啟選單\n- 向上鍵 / 向下鍵 — 在選項之間移動\n- Home / End — 跳到第一項 / 最後一項(PageUp / PageDown 同)\n- 輸入首字 — 跳到標籤符合的選項\n- Enter / Space — 選擇目前的選項\n- Esc — 只關目前所在的那一層:在子選單裡回到上一層打開它的那一項(同左方向鍵),在主選單裡回到觸發按鈕\n- Tab / Shift+Tab(選單開著時)— 一次收起全部層,焦點從觸發按鈕往下 / 往上走一站\n\n焦點管理:選單開啟時焦點會進入選單;按 Esc 或選了項目,焦點回到觸發按鈕;點外面,焦點留在點的地方;按 Tab,焦點到下一站。鍵盤導覽到的選項畫焦點框(滑鼠移過的選項才上底色),鍵盤使用者隨時看得到自己在哪一項。\n\n驗證:鍵盤可完整操作(不需滑鼠),文字對比達 WCAG AA;在 Storybook 無障礙檢查面板上應為零項嚴重問題。"}</p>
       <p className="mt-4 text-fg-muted">完整 ARIA 細節參考 <a className="text-primary hover:text-primary-hover" href="https://www.radix-ui.com/primitives/docs/components/dropdown-menu#accessibility" target="_blank" rel="noreferrer">Radix Accessibility 文件</a>。</p>
     </div>
   ),

package/src/components/DropdownMenu/dropdown-menu.spec.md

@@ -176,7 +176,7 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 
 ## 鍵盤操作
 
-由 Radix DropdownMenu 提供：
+由 Radix DropdownMenu 提供;**`Tab` / `Shift+Tab` 與子選單裡的 `Escape` 兩處由本元件改寫**(2026-09-25,來歷見下一節):
 
 | 按鍵 | 行為 |
 |---|---|
@@ -184,10 +184,22 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 | `Home` / `End` | 跳到第一／最後一個 item（`PageUp` / `PageDown` 同） |
 | 首字 typeahead | 打字元自動跳到 **label 符合**的 item——children 為字串時元件自動 forward `textValue`,description / badge / shortcut 不進比對;複雜 children(非純字串)由 consumer 顯式給 `textValue` |
 | `Enter` / `Space` | 執行目前焦點的動作 |
-| `Escape` | 關閉整個選單（含所有展開子層；Radix root close）。逐層收合用 `←` |
+| `Tab` / `Shift+Tab` | **收起全部層(含子選單),焦點從開啟選單的那顆鈕往下 / 往上走一站** —— 效果等於在觸發鈕上按 `Tab` / `Shift+Tab`。選單內容掛在頁面最末端,所以下一站一律從觸發鈕算,不從選單項算。觸發鈕在對話框或面板裡時,照那個框的規則在框內繞圈;頁面上已經沒有下一站時,焦點留在觸發鈕 |
+| `Escape` | **只關焦點所在的那一層**:在主選單 → 關選單、焦點回觸發鈕;在子選單 → 只關這一層、焦點回上一層打開它的那一項(與 `←` 同效果)。**每按一次少一層** |
 | `→` | 展開子選單 |
 | `←` | 收合子選單，焦點回到 SubTrigger |
 
+**關閉之後焦點去哪**(全 DS 規則住在 `ds-canonical/references/keyboard-model-canonical.md`「彈出框開著時的 Tab 與 Esc」,本表只是本元件的落地):
+`Escape` 或選了項目 → 回觸發鈕;點外面 → 留在點的地方(非 modal 預設,Radix `hasInteractedOutsideRef`);`Tab` → 已經走到下一站,不再拉回觸發鈕,也不呼叫 consumer 的 `onCloseAutoFocus`。
+
+### `Tab` 與子選單 `Escape` 的來歷(2026-09-25)
+
+**user 原話(逐字,附條件同意)**:選單 Tab:「你確定這個符合我們一致的設計語言且不違背世界級的設計就這樣做」;子選單 Esc:「你確定這符合我們一致的設計語言且不違背世界級的設計就這樣做」;追問:「看最後是怎樣定義，選單類應該要一致吧？這樣才符合世界級的設計？」。條件(世界級 + DS 一致)的查證是 **AI 研究**(待辦總帳 `governance/planning/2026-09-25-interaction-and-hover-remediation.md` B10 / B11);Tab 那一題 user 可在預覽否決。
+
+- **子選單 `Escape` 只關一層**:W3C「Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent `menuitem`, from which the menu was opened」(https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/menubar/menu-and-menubar-pattern.html#L153 );同派:Adobe React Aria(https://github.com/adobe/react-spectrum/blob/956ecbcb8803f0d0d5d5d973bb169d70c52aea02/packages/react-aria/src/menu/useSubmenuTrigger.ts#L161-L171 )、Fluent(https://github.com/microsoft/fluentui/blob/d27922755bebae866d9ffe86b7da44c27ec801ee/packages/react-components/react-menu/library/src/components/Menu/Menu.cy.tsx#L952-L964 )、GitHub Primer 測試「closes top menu on escape or left arrow key press」(https://github.com/primer/react/blob/f2c075a5d4d0b51a279c39effa18226ad909929d/packages/react/src/ActionMenu/ActionMenu.test.tsx#L626-L649 )、VS Code(https://github.com/microsoft/vscode/blob/2ec783d855253a817b5787fb48bc6c3d8d31c0c5/src/vs/base/browser/ui/menu/menu.ts#L953-L957 )、Windows 桌面選單(https://github.com/microsoft/microsoft-ui-xaml/blob/258a2e9b0852b69c98162e6daf9906ec8fe5161a/dxaml/xcp/dxaml/lib/MenuFlyoutPresenter_Partial.cpp#L232-L235 )、Chrome(https://github.com/chromium/chromium/blob/c53fe9e04b2856967d1f2f716b99b0911251e521/ui/views/controls/menu/menu_controller.cc#L2155-L2167 )、Firefox「Pressing Escape hides one level of menus only.」(https://github.com/mozilla-firefox/firefox/blob/0a5c5bffebd796cedba281419efd2f8f3cc7c85d/layout/xul/nsXULPopupManager.cpp#L2642-L2648 )。有一手資料的 9 家裡唯一例外是本元件的底層 Radix(子選單 Esc 呼叫 `rootContext.onClose()` 關整棵,https://github.com/radix-ui/primitives/blob/f7ecd5ab16f5e1e820eb5786a1419a98a2d594ae/packages/react/menu/src/menu.tsx#L1262-L1266 ),本元件改寫它。DS 內部:對話框、側滑面板、AI 面板早已寫明 Esc 只關最上層 / 最內層(`../Dialog/dialog.spec.md`、`../Sheet/sheet.spec.md`、`../AgentPanel/agent-panel.spec.md`),子選單原本是全 DS 唯一例外。
+- **`Tab` 收起並往下走**:W3C「When focus is on a `menuitem` in a `menu` or `menubar`, move focus out of the `menu` or `menubar`, and close all menus and submenus.」(https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/menubar/menu-and-menubar-pattern.html#L82 );Fluent 測試「should be able to tab to next element after the root trigger」(https://github.com/microsoft/fluentui/blob/d27922755bebae866d9ffe86b7da44c27ec801ee/packages/react-components/react-menu/library/src/components/Menu/Menu.cy.tsx#L579 );Primer「When Tab or Shift+Tab is pressed, the menu should close and the focus should naturally move to the next item」(https://github.com/primer/react/blob/f2c075a5d4d0b51a279c39effa18226ad909929d/packages/react/src/hooks/useMenuKeyboardNavigation.ts#L29-L30 )。**世界級在這題不一致**:Radix(「menus should not be navigated using tab key so we prevent it」,https://github.com/radix-ui/primitives/blob/f7ecd5ab16f5e1e820eb5786a1419a98a2d594ae/packages/react/menu/src/menu.tsx#L570-L572 )、Adobe React Aria(測試「contains focus within the menu」,https://github.com/adobe/react-spectrum/blob/956ecbcb8803f0d0d5d5d973bb169d70c52aea02/packages/react-aria-components/test/Menu.test.tsx#L1842-L1877 )、VS Code(「Stop tab navigation of menus」,https://github.com/microsoft/vscode/blob/2ec783d855253a817b5787fb48bc6c3d8d31c0c5/src/vs/base/browser/ui/menu/menu.ts#L132-L139 )是「按了不動」那一派。本 DS 採 W3C 這一派,理由是 DS 自己的鍵盤分工「Tab 換區、方向鍵在區裡走、Esc 退一步」(`ds-canonical/references/keyboard-model-canonical.md`)——選單是一個區,Tab 就該離開它(AI 推導,條件查證見待辦總帳 B11)。
+- **實作**:`dropdown-menu-keyboard.ts` 的 `handleMenuTab`(`Content` / `SubContent` 的 `onKeyDown`)與子選單的 `closeLevel`(`SubContent` 的 `onEscapeKeyDown`);2026-09-26 從 `dropdown-menu.tsx` 拆出(該檔 879 行超過 800 行上限),`dropdown-menu.tsx` 只留視覺層。「從觸發點算下一站」與 SelectMenu 共用一份 `../../lib/focus-after-trigger.ts`(2026-09-26 兩份合一,待辦總帳〇節「按鍵規則合併」)。觸發點是透明錨點時(AgentFab 右鍵選單),以「宣告 `aria-controls` 指向本選單的可聚焦元素」為開啟者。觸發點本身不在 Tab 路上時(例:樹 / 側欄列上 `tabIndex=-1` 的選單鈕),以它在文件裡的位置為起點往下 / 往上走 —— 從列上選單鈕打開的選單按 `Tab`,會直接離開那一整串。
+
 ---
 
 ## 破壞性動作
@@ -237,14 +249,15 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 
 **Keyboard 行為**:
 
-- Tab — focus trigger
+- Tab — 選單關著:把焦點移到觸發鈕(觸發鈕本身是一站)
 - Enter / Space / ↓ — 開啟
 - ↑/↓ — 導覽 items（Home/End 跳首尾項，PageUp/PageDown 同）
 - 首字 typeahead — 打字元自動跳到 label 符合的 item(比對 `textValue`,見「鍵盤操作」表)
 - Enter / Space — 選擇目前焦點的選項
-- Esc — 關閉
+- Tab / Shift+Tab — 選單開著:收起全部層,焦點從觸發鈕往下 / 往上走一站(2026-09-25 起,見「鍵盤操作」)
+- Esc — 只關焦點所在的那一層(子選單 → 回上一層那一項;主選單 → 回觸發鈕)
 
-**Focus**:Radix primitive 自管 focus trap / restoration。反白(Radix `data-highlighted`)是**唯一的游標**,依**反白來歷**分流(owner = `ds-canonical/references/focus-canonical.md` 規則一「兩類元件」+ 規則二,user 2026-09-09 拍板「都要畫框,不上底色」):**滑鼠移過搬走反白** = hover → `bg-neutral-hover`、無框;**鍵盤搬走反白** = 游標 → 畫框 `focus-ring-inset`(內描邊,列撐滿選單寬)、不上底色,而且滑鼠停留列的 hover 底色一起消失(四種項目上都沒有 `hover:` 樣式;滑鼠停著不算搶,2026-09-09 下午 user 三問、Radix Menu 原始碼證實 `onPointerMove → item.focus()` 就是搶 —— https://github.com/radix-ui/primitives/blob/main/packages/react/menu/src/menu.tsx)。來歷由 `hooks/use-input-modality.ts` 的 `useCursorMover` + 各項目 `onPointerMoveCapture → markPointerGrab` 判(本元件刻意用 `data-highlighted` + 模態而非瀏覽器 `:focus-visible`,因 Radix 對 hover 做程式化 focus、各瀏覽器 `:focus-visible` 行為不一 — 見 dropdown-menu.tsx docblock「Hover / highlight canonical」)。2026-09-09 之前鍵盤導覽到的未選中項只有底色不畫框 —— AI 推導自 Radix 慣例,已撤回。**Trigger focus 指示**:Trigger 走全域 `:focus-visible` 外描邊(`styles/base.css`,幾何 SSOT = focus-canonical「框怎麼畫」);asChild 場景由子元件(通常 Button)同樣走全域外描邊。
+**Focus**:預設非 modal —— 焦點不鎖在選單裡(`Tab` 會離開,見上)。開啟時焦點進選單;關閉時 `Esc` / 選了項目 → 回觸發鈕,點外面 → 留在點的地方,`Tab` → 下一站(本元件 `onCloseAutoFocus` 在 Tab 離開時擋掉還觸發鈕)。反白(Radix `data-highlighted`)是**唯一的游標**,依**反白來歷**分流(owner = `ds-canonical/references/focus-canonical.md` 規則一「兩類元件」+ 規則二,user 2026-09-09 拍板「都要畫框,不上底色」):**滑鼠移過搬走反白** = hover → `bg-neutral-hover`、無框;**鍵盤搬走反白** = 游標 → 畫框 `focus-ring-inset`(內描邊,列撐滿選單寬)、不上底色,而且滑鼠停留列的 hover 底色一起消失(四種項目上都沒有 `hover:` 樣式;滑鼠停著不算搶,2026-09-09 下午 user 三問、Radix Menu 原始碼證實 `onPointerMove → item.focus()` 就是搶 —— https://github.com/radix-ui/primitives/blob/main/packages/react/menu/src/menu.tsx)。來歷由 `hooks/use-input-modality.ts` 的 `useCursorMover` + 各項目 `onPointerMoveCapture → markPointerGrab` 判(本元件刻意用 `data-highlighted` + 模態而非瀏覽器 `:focus-visible`,因 Radix 對 hover 做程式化 focus、各瀏覽器 `:focus-visible` 行為不一 — 見 dropdown-menu.tsx docblock「Hover / highlight canonical」)。2026-09-09 之前鍵盤導覽到的未選中項只有底色不畫框 —— AI 推導自 Radix 慣例,已撤回。**Trigger focus 指示**:Trigger 走全域 `:focus-visible` 外描邊(`styles/base.css`,幾何 SSOT = focus-canonical「框怎麼畫」);asChild 場景由子元件(通常 Button)同樣走全域外描邊。
 
 **ARIA composite scroll wrapper**:`DropdownMenuContent` 的 viewport-aware body 仍消費 `ScrollArea`,但 viewport 傳 `viewportTabIndex={null}` 完全省略 generic wrapper 的 `tabindex`。`role="menu"` 內的 focus owner 是 Radix roving-focus `menuitem*` family；額外 `div[tabindex]` 會破壞 required-children 結構。群組 Label 是正常可讀文字,使用 `fg-secondary`(非低對比的 `fg-muted`)。
 

package/src/components/DropdownMenu/dropdown-menu.stories.tsx

@@ -1,7 +1,7 @@
 // @story-history: isOverlay OpenSnapshot / hasInteractiveStates Disabled 由 anatomy.stories.tsx StateBehavior + Inspector auto-compile owns(2026-05-15 F-migration);showcase 展示真實多選 / 角色切換 / Checkbox 整合情境。
 import type { Meta, StoryObj } from '@storybook/react'
 import { useState } from 'react'
-import { Mail, Settings, User, LogOut, Trash2, Copy, Pencil, ExternalLink, Moon, Sun, Monitor, ChevronDown, FileText } from 'lucide-react'
+import { Mail, Settings, User, LogOut, Trash2, Copy, Pencil, ExternalLink, Moon, Sun, Monitor, ChevronDown, FileText, FolderInput, Link, Share2, UserPlus } from 'lucide-react'
 import {
   DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
   DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem,
@@ -145,6 +145,63 @@ export const SubMenu: StoryObj = {
   render: () => <SubMenuDemo />,
 }
 
+// ── 多層子選單:Esc 一次只關一層、Tab 收起全部往下走(2026-09-25,待辦總帳 B10 / B11)──
+// 情境:工作項目頁首的工具列「指派給我 / 更多動作 / 分享」,更多動作 → 移動到 → 專案 → 欄位,共三層。
+// 觸發鈕前後各一顆真按鈕,Tab / Shift+Tab 的落點看得見也量得到(dropdown-menu-keyboard-invariant 的量測對象)。
+// @overlay-open-skip: 本則教的是鍵盤開關行為(每按一次 Esc 少一層、Tab 收起往下走),要從「關著」開始操作;
+//   浮層開著的視覺快照由同檔 OpenSnapshot(defaultOpen)負責。
+const MOVE_TARGETS = [
+  { project: '行動 App 改版', columns: ['待辦', '進行中', '完成'] },
+  { project: '官網重構', columns: ['待辦', '設計審查', '完成'] },
+] as const
+
+const NestedSubMenuDemo = () => (
+  <div className="flex items-center gap-2">
+    <Button variant="tertiary" startIcon={UserPlus}>指派給我</Button>
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="tertiary" endIcon={ChevronDown}>更多動作</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuItem startIcon={Link}>複製連結</DropdownMenuItem>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger startIcon={FolderInput}>移動到</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            {MOVE_TARGETS.map(({ project, columns }) => (
+              <DropdownMenuSub key={project}>
+                <DropdownMenuSubTrigger>{project}</DropdownMenuSubTrigger>
+                <DropdownMenuSubContent>
+                  {columns.map((column) => (
+                    <DropdownMenuItem key={column}>{column}</DropdownMenuItem>
+                  ))}
+                </DropdownMenuSubContent>
+              </DropdownMenuSub>
+            ))}
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem startIcon={Trash2} className="text-error">刪除</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+    <Button variant="tertiary" startIcon={Share2}>分享</Button>
+  </div>
+)
+
+export const NestedSubMenu: StoryObj = {
+  name: '多層子選單',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '用鍵盤從「更多動作」一路按 → 開到第三層(移動到 → 專案 → 欄位)。' +
+          '按 Esc 每次只關最內層的那一層,焦點回到上一層打開它的那一項(跟 ← 一樣);三層要按三次才全部關掉、回到「更多動作」。' +
+          '選單開著時按 Tab,不論在第幾層都一次收起全部,焦點落在「分享」;按 Shift+Tab 則落在「指派給我」。',
+      },
+    },
+  },
+  render: () => <NestedSubMenuDemo />,
+}
+
 // ── Checkbox Items ──
 
 const CheckboxDemo = () => {