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

package/src/components/Select/select.anatomy.stories.tsx

@@ -7,6 +7,7 @@ import type { Meta } from '@storybook/react'
 import { useState, useEffect } from 'react'
 import { Flag } from 'lucide-react'
 import { Select } from './select'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 
 const meta: Meta = {
   title: 'Design System/Components/Select/設計規格',
@@ -165,18 +166,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">
@@ -373,47 +362,49 @@ 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">Mode</span>
-          <div className="flex flex-wrap gap-1.5">
-            {MODES.map((m) => <Tab key={m} active={mode === m} onClick={() => setMode(m)}>{m}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Mode" value={mode} onValueChange={(v) => setMode(v as ModeKey)}>
+            {MODES.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">Display</span>
-          <div className="flex gap-1.5">
-            {DISPLAYS.map((d) => <Tab key={d} active={display === d} onClick={() => setDisplay(d)}>{d}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Display" value={display} onValueChange={(v) => setDisplay(v as DisplayKey)}>
+            {DISPLAYS.map((d) => <SegmentedControlItem key={d} value={d}>{d}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <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">
-            {SIZES.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)}>
+            {SIZES.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">Error</span>
-          <div className="flex gap-1.5">
-            <Tab active={!error} onClick={() => setError(false)}>off</Tab>
-            <Tab active={error} onClick={() => setError(true)} disabled={mode !== 'edit'}>on</Tab>
-          </div>
+          {/* 停用項用元件自身 disabled(segmented-control.spec.md「disabled」);停用項不得是當前值 → value 取實際生效值 */}
+          <SegmentedControl size="sm" aria-label="Error" value={error && mode === 'edit' ? 'on' : 'off'} onValueChange={(v) => setError(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={mode !== 'edit'}>on</SegmentedControlItem>
+          </SegmentedControl>
           {mode !== 'edit' && <span className="text-[11px] text-fg-muted">僅 edit 模式有效</span>}
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Clearable</span>
-          <div className="flex gap-1.5">
-            <Tab active={!clearable} onClick={() => setClearable(false)}>off</Tab>
-            <Tab active={clearable} onClick={() => setClearable(true)}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="Clearable" value={clearable ? 'on' : 'off'} onValueChange={(v) => setClearable(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on">on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">startIcon</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasStartIcon} onClick={() => setHasStartIcon(false)}>off</Tab>
-            <Tab active={hasStartIcon} onClick={() => setHasStartIcon(true)} disabled={display === 'tag'}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="startIcon" value={hasStartIcon && !isTag ? 'on' : 'off'} onValueChange={(v) => setHasStartIcon(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={isTag}>on</SegmentedControlItem>
+          </SegmentedControl>
           {display === 'tag' && <span className="text-[11px] text-fg-muted">tag 模式不支援 startIcon</span>}
         </div>
       </div>
@@ -835,7 +826,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">{"無障礙行為依裝置分兩條路徑:\n\n  ARIA / Pattern  :桌機(非觸控)觸發點是一個容器,標記  role=\"combobox\"  +  aria-expanded  /  aria-haspopup=\"listbox\" ,選項在浮層的 listbox 裡;searchable 模式時容器內另放一個可打字篩選的  <input> 。手機(觸控)改用瀏覽器原生的  <select>  element,直接取得作業系統內建的無障礙與 picker。Field wrapper 兩邊都補  aria-invalid  /  aria-required  /  aria-describedby  /  aria-errormessage ;手機原生  <select>  另由 FieldLabel 的  htmlFor  關聯取得 accessible name。\n\n  Keyboard 行為  :\n\n- Tab — 聚焦到觸發點\n- Enter / Space — 展開選單(searchable 模式則直接進入打字篩選)\n- ↑ / ↓ — 選單展開後在選項間移動\n- 字母鍵 — searchable 模式為打字篩選;手機原生 <select> 為平台內建 type-to-jump 逐字定位(桌機非 searchable combobox 無逐字定位)\n- Enter — 選定目前 highlight 的選項並關閉\n- Esc — 關閉選單(清除值走右側 clear 按鈕,非 Esc)\n\n  Focus  :DS focus 藍框( focus-within:!border-primary )由 Field wrapper 提供;手機原生  <select>  另有系統 focus ring。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+      <p className="whitespace-pre-line">{"無障礙行為依裝置分兩條路徑:\n\n  ARIA / Pattern  :桌機(非觸控)觸發點是一個容器,標記  role=\"combobox\"  +  aria-expanded  /  aria-haspopup=\"listbox\" ,選項在浮層的 listbox 裡;searchable 模式時容器內另放一個可打字篩選的  <input> 。手機(觸控)改用瀏覽器原生的  <select>  element,直接取得作業系統內建的無障礙與 picker。Field wrapper 兩邊都補  aria-invalid  /  aria-required  /  aria-describedby  /  aria-errormessage ;手機原生  <select>  另由 FieldLabel 的  htmlFor  關聯取得 accessible name。\n\n  Keyboard 行為  :\n\n- Tab — 聚焦到觸發點\n- Enter / Space — 展開選單(searchable 模式則直接進入打字篩選)\n- ↑ / ↓ — 選單展開後在選項間移動\n- 字母鍵 — searchable 模式為打字篩選;手機原生 <select> 為平台內建 type-to-jump 逐字定位(桌機非 searchable combobox 無逐字定位)\n- Enter — 選定目前 highlight 的選項並關閉\n- Tab / Shift+Tab(選單展開時)— 同樣選定目前 highlight 的選項並關閉,焦點走到觸發點的下一個 / 上一個可 Tab 元素(= 選單關著時按 Tab 會到的同一格;待辦總帳 B11,規則住 select-menu.spec.md「A11y 預設」)\n- Esc — 關閉選單、不選定(清除值走右側 clear 按鈕,非 Esc)\n\n  Focus  :DS focus 藍框( focus-within:!border-primary )由 Field wrapper 提供;手機原生  <select>  另有系統 focus ring。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
     </div>
   ),
 }

package/src/components/Select/select.spec.md

@@ -350,9 +350,10 @@ Select 是 **Field Controls family 成員**——互動狀態(focus / invalid /
 - Enter / Space — 展開選單(searchable 模式則直接進入打字篩選)
 - ↓ — 選單關閉時亦可直接展開(APG combobox 展開鍵,與 Combobox 同 pattern;展開後不攔,讓方向鍵導覽選單)
 - ↑ / ↓ — 選單展開後在選項間移動
-- Esc — 關閉選單(清除值走右側 clear 按鈕,非 Esc)
+- Tab / Shift+Tab(選單展開時,searchable 與否皆同)— 選定反白那一項 → 收起 → 焦點落到觸發點的下一個 / 上一個可 Tab 元素(= 選單關著時從觸發點按 Tab / Shift+Tab 會到的那一格;在對話框 / 小面板裡則只在那一層裡走、到邊緣繞回)。2026-09-25 前(實測):不可打字時 Tab 卡在浮層裡或落到頁面外、Shift+Tab 跳到頁尾,都不選定;可打字時 Tab 收起但不選定、Shift+Tab 停在觸發點本身且選單不關。W3C 出處與逐字規則見 `../SelectMenu/select-menu.spec.md`「A11y 預設」(單選那一條);來源 = 待辦總帳 B11
+- Esc — 關閉選單、不選定(清除值走右側 clear 按鈕,非 Esc)
 
-**Focus**:Field 家族的焦點指示 = 邊框轉主色,**不分開著關著、不分滑鼠鍵盤**(owner = `ds-canonical/references/focus-canonical.md` 規則二「Field 家族控件本身」列 + 「問題一之二」C 類;2026-09-10 第二次更正:上午先寫成「關閉時鍵盤模態再加全域外框」,下午依一致性收斂 —— Combobox 焦點留在輸入框本來就沒有外框,Select 類關閉後焦點回 wrapper 若再疊外框就是同一家族兩種長相)。**開啟時**焦點在搜尋輸入框(插入點控件)→ Field wrapper 邊框轉色;**關閉時**觸發器本身是焦點站(`tabIndex=0`,選完 / Esc 後 Radix 把焦點還給它)→ 同樣只有邊框轉色,全域 `:focus-visible` 外框由 `fieldWrapperStyles` 的 `focus-visible:outline-none` 抑制。手機原生 `<select>` 另有系統 focus ring。閘:`virtual-cursor-modality-invariant.mjs` G 段(Select / SelectMenu / PeoplePicker)、H 段(DatePicker / TimePicker / Combobox 觸發器)。
+**Focus**:Field 家族的焦點指示 = 邊框轉主色,**不分開著關著、不分滑鼠鍵盤**(owner = `ds-canonical/references/focus-canonical.md` 規則二「Field 家族控件本身」列 + 「問題一之二」C 類;2026-09-10 第二次更正:上午先寫成「關閉時鍵盤模態再加全域外框」,下午依一致性收斂 —— Combobox 焦點留在輸入框本來就沒有外框,Select 類關閉後焦點回 wrapper 若再疊外框就是同一家族兩種長相)。**開啟時**焦點在搜尋輸入框(插入點控件)→ Field wrapper 邊框轉色;**關閉時**觸發器本身是焦點站(`tabIndex=0`,選完 / Esc 後 Radix 把焦點還給它;按 Tab 收起時焦點直接走到下一格,不回觸發器)→ 同樣只有邊框轉色,全域 `:focus-visible` 外框由 `fieldWrapperStyles` 的 `focus-visible:outline-none` 抑制。手機原生 `<select>` 另有系統 focus ring。閘:`virtual-cursor-modality-invariant.mjs` G 段(Select / SelectMenu / PeoplePicker)、H 段(DatePicker / TimePicker / Combobox 觸發器)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -362,7 +363,7 @@ Select 是 **Field Controls family 成員**——互動狀態(focus / invalid /
 
 - `checkbox.spec.md`
 - `combobox.spec.md`
-- `command.spec.md`
 - `people-picker.spec.md`
 - `radio-group.spec.md`
 - `select-menu.spec.md`
+- `uiSize.spec.md`

package/src/components/Select/select.tsx

@@ -492,7 +492,8 @@ function ReadonlyDisplay({
   const tagVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
 
   return (
-    <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), value && tagPadding[sz], className)} style={{ paddingRight: 'var(--field-px)' }} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
+    // 停用:Tag 自帶 cursor-text,指到 tag 上會蓋掉外框的 cursor-not-allowed(2026-09-29 全站掃出)→ 整塊釘成禁止符號(同 Combobox 非 edit 分支)
+    <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), value && tagPadding[sz], resolvedMode === 'disabled' && '[&_*]:cursor-not-allowed', className)} style={{ paddingRight: 'var(--field-px)' }} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
       {value ? <Tag size={sz} color={tagVariant}>{label}</Tag> : <span className={emptyColorCls}>{emptyText}</span>}
       {showIndicator && <ItemSuffix className="pointer-events-none"><ChevronDown size={iconSize} className={cn('shrink-0', iconColor)} aria-hidden /></ItemSuffix>}
     </div>
@@ -660,7 +661,13 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
 
     const [open, setOpen] = React.useState(defaultOpen)
     const [search, setSearchState] = React.useState('')
-    const setSearch = React.useCallback((next: string) => { setSearchState(next); onSearchChange?.(next) }, [onSearchChange])
+    // onSearchChange 走 ref(同 agent-panel.tsx onModeChangeRef 的寫法):setSearch 身分因此穩定,下方「關閉時清搜尋」
+    // 的 effect 才能把 setSearch 列進相依而不多跑。若改成 useCallback 隨 onSearchChange 換身分,消費端傳 inline 箭頭函式
+    // (select.stories.tsx RemoteSearchDemo 就是)時,關著的每次 render 都會重發 onSearchChange('') → 消費端 setOptions([])
+    // 換新陣列 → 再 render → 再重發,無限更新;ref 讀的永遠是最新一版回呼,也沒有過期閉包。
+    const onSearchChangeRef = React.useRef(onSearchChange)
+    onSearchChangeRef.current = onSearchChange
+    const setSearch = React.useCallback((next: string) => { setSearchState(next); onSearchChangeRef.current?.(next) }, [])
     const inputRef = React.useRef<HTMLInputElement>(null)
     // a11y(2026-07-04):listbox 容器 id——trigger aria-controls 指向 SelectMenu PopoverContent
     // (對齊姊妹元件 combobox.tsx:677 既有 canonical;React.useId SSR/CSR 穩定)。
@@ -669,8 +676,8 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     // (機制詳 select-menu.tsx useActiveDescendant docblock;必在 early return 前呼叫 — React #310 hook 順序)。
     const activeOptionId = useActiveDescendant(listboxId, open)
 
-    // 關閉時清搜尋
-    React.useEffect(() => { if (!open) setSearch('') }, [open])
+    // 關閉時清搜尋(setSearch 身分穩定 → 這個 effect 實際只在 open 變動時跑,與列相依前的次數相同)
+    React.useEffect(() => { if (!open) setSearch('') }, [open, setSearch])
 
     // **React #310 fix(2026-05-04)**:所有 hooks 必在任何 early return 前 call,
     //   否則 disabled→edit 切換時 hook count 變動 → React 死亡。

package/src/components/SelectMenu/select-menu-keyboard.ts

@@ -0,0 +1,218 @@
+/**
+ * @internal — SelectMenu 的鍵盤橋接:觸發欄位與浮層清單分屬兩棵 DOM 子樹(浮層 portal 到 body 最後),
+ * 這裡收三件事,由 select-menu.tsx 轉出(Select / Combobox 既有 import 路徑不變):
+ *   1. `forwardKeyToListbox`  —— 觸發欄位內的輸入框把 ↑ ↓ Enter 轉送給 cmdk(2026-07-05 D4,原住 select-menu.tsx,原樣搬來)
+ *   2. `useActiveDescendant`  —— 觸發欄位輸入框的 aria-activedescendant(同上,原樣搬來)
+ *   3. `useSelectMenuPopupKeys` —— 開著按 Tab / Shift+Tab(2026-09-25 待辦總帳 B11)與不可打字單選的空白鍵(2026-09-26,L7)
+ * 2026-09-25 搬家理由(AI 推導):select-menu.tsx 已 799 行,加 3 會超過 `scripts/code-quality-audit.mjs` 的 800 行上限;
+ * 三者同一件事(跨子樹的鍵盤 / 焦點接線),與清單渲染無關。
+ * 2026-09-26:「從觸發欄位算下一站」與 DropdownMenu 合成一份 `lib/focus-after-trigger.ts`(待辦總帳〇節「按鍵規則合併」)。
+ */
+import * as React from 'react'
+import { flushSync } from 'react-dom'
+import { focusFromTrigger, tabbableOrder } from '@/design-system/lib/focus-after-trigger'
+import { isTextEntryElement } from '@/design-system/lib/roving-list-keyboard'
+
+/**
+ * 2026-07-05 D4 P0 修(searchable 鍵盤死路):trigger 內的裸 <input> 與 portal 內的 cmdk root
+ * 在不同 DOM 子樹 — 鍵盤事件永遠 bubble 不到 cmdk 的 ArrowUp/Down/Enter handler([cmdk-root]
+ * onKeyDown)→ searchable Select / PeoplePicker single / Combobox searchIn='trigger' 開啟後
+ * 只能 Esc。修法 = APG combobox-with-list:trigger input 把三鍵 re-dispatch 給 cmdk root
+ * (native KeyboardEvent bubbles 經 React root delegation 觸發 cmdk synthetic handler)。
+ * Home/End 刻意不轉送(文字輸入的 caret 語意優先,對齊 MUI/Ant Autocomplete)。
+ * aria-activedescendant 綁回 trigger input → 見下方 useActiveDescendant(2026-07-05 D4 補齊)。
+ */
+export function forwardKeyToListbox(contentId: string | undefined, e: React.KeyboardEvent): boolean {
+  if (!contentId) return false
+  if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp' && e.key !== 'Enter') return false
+  const root = document.getElementById(contentId)?.querySelector<HTMLElement>('[cmdk-root]')
+  if (!root) return false
+  e.preventDefault()
+  root.dispatchEvent(new KeyboardEvent('keydown', { key: e.key, bubbles: true, cancelable: true }))
+  return true
+}
+
+/**
+ * 2026-07-05 D4 補齊(APG combobox aria-activedescendant):追蹤 cmdk 目前 virtual-focus item
+ * 的 DOM id,供 trigger 端搜尋 input 綁 `aria-activedescendant` —— SR 才會在方向鍵導覽 /
+ * 打字過濾時播報 active option 名。機制:trigger 與 portal 內 cmdk 分屬不同 DOM 子樹,cmdk
+ * 只把 active id 綁在自己的 Command.Input / List(cmdk source:item 自帶 auto-generated id +
+ * `data-selected="true"` 標記 virtual focus)→ trigger 端用 MutationObserver 監聽 popover 容器
+ * (contentId = PopoverContent id)內 `data-selected` 屬性變化 + childList(打字過濾 re-render
+ * 換 item 節點),單一機制涵蓋全部更新路徑:開啟初始 auto-highlight / forwardKeyToListbox
+ * 方向鍵轉送 / 搜尋過濾後 cmdk 自動移 cursor / pointer hover。
+ * 關閉時清 undefined —— ARIA 要求 id 必指向存在於 DOM 的節點,不可留 stale id。
+ */
+export function useActiveDescendant(contentId: string | undefined, open: boolean): string | undefined {
+  const [activeId, setActiveId] = React.useState<string | undefined>(undefined)
+  React.useEffect(() => {
+    if (!open || !contentId) {
+      setActiveId(undefined)
+      return
+    }
+    // PopoverContent 與 trigger 同一個 React commit mount(open state 同批 render)→ effect 跑時已在 DOM
+    const container = document.getElementById(contentId)
+    if (!container) return
+    const read = () => {
+      setActiveId(container.querySelector<HTMLElement>('[cmdk-item][data-selected="true"]')?.id || undefined)
+    }
+    // 初始補讀:MutationObserver 只看「觀察開始後」的變化;cmdk 初始 auto-highlight(layout effect
+    // 排程)可能已 commit → rAF 讀當下狀態兜底,與 observer 互補、誰先到都不漏。
+    const raf = requestAnimationFrame(read)
+    const observer = new MutationObserver(read)
+    observer.observe(container, { subtree: true, childList: true, attributes: true, attributeFilter: ['data-selected'] })
+    return () => {
+      cancelAnimationFrame(raf)
+      observer.disconnect()
+    }
+  }, [open, contentId])
+  return activeId
+}
+
+// ── 開著按 Tab / Shift+Tab(2026-09-25 待辦總帳 B11;SSOT = select-menu.spec.md「A11y 預設」)─────────────
+//
+// 兩種浮層、兩條規則 —— W3C 下拉規範依「彈出的是什麼」分流:
+//
+// (1) 單選 = 清單型(listbox):選定反白那一項 → 收起 → 焦點落到觸發欄位的下一個(Shift:上一個)可 Tab 元素,
+//     也就是「關著時從觸發欄位按 Tab 會到的同一格」。
+//     W3C 單選下拉範例 Tab 列:「Sets the value to the content of the focused option in the listbox. / Closes the listbox. /
+//     Performs the default action, moving focus to the next focusable element.」
+//     https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/combobox-select-only.html#L187-L199
+//     Shift+Tab 同樣選定:該範例是在觸發欄位失焦時選定,不分方向
+//     https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/js/select-only.js#L249-L260
+//     Fluent 單選 `case 'Tab': !multiselect && activeOption && selectOption(e, activeOption);`(不分 Shift)
+//     https://github.com/microsoft/fluentui/blob/d27922755bebae866d9ffe86b7da44c27ec801ee/packages/react-components/react-combobox/library/src/utils/useTriggerSlot.ts#L198-L200
+//
+// (2) 多選 = 小面板型(dialog:面板裡有搜尋框 / 全選鈕,DOM 焦點會進到面板):Tab 留在面板裡繞圈,行為不變。
+//     W3C:dialog 型彈出「implements the keyboard interaction defined in the modal dialog pattern」
+//     https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/combobox-pattern.html#L391
+//     對話框「contain their tab sequence」
+//     https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/dialog-modal/dialog-modal-pattern.html#L29-L30
+//     這裡只補一個洞:焦點停在「程式落點」(cmdk 殼,tabIndex -1,不在 Tab 序裡)時,Shift+Tab 照 DOM 順序往前
+//     找到的是頁面最後一個元素(浮層掛在 body 最後)→ 跳出面板到頁尾(R15 實測 S-PAGE-END)。
+//
+// 為什麼自己算「下一格」,不把焦點先丟回觸發欄位再讓瀏覽器照走(AI 推導,2026-09-25):
+//   (a) 焦點在觸發欄位上停一下,欄位的截斷 tooltip 會因 focus 打開、又立刻因 blur 關閉 → 閃一下淡出動畫;
+//   (b) 觸發欄位在另一個小面板 / 對話框裡時,那一層的 Radix FocusScope 正被本浮層「暫停」
+//       (`@radix-ui/react-focus-scope` 1.1.7 dist:`if (focusScope.paused) return`),不會替我們繞回 ——
+//       交給瀏覽器照走,觸發欄位若是那一層的第一 / 最後一格,焦點就跑出去、把外層面板一起關掉。
+// 「下一格」的算法與選單同一份(lib/focus-after-trigger.ts):對話框 / 面板裡繞圈;頁面上已沒有下一格 → 留在觸發欄位(X20)。
+// 2026-09-26 之前這裡另有一份(不認正 tabindex、頁面邊緣交還瀏覽器 —— 會落在 Radix 關閉動畫期間仍掛著的隱形焦點護欄上)。
+
+/**
+ * 多選小面板:焦點在程式落點(不在 Tab 序裡)時,Tab / Shift+Tab 仍留在面板裡(規則 (2))。
+ * 焦點已在可 Tab 元素上 → 不插手:Radix FocusScope(`loop: true`,`@radix-ui/react-popover` 1.1.15 dist/index.mjs:225-226)
+ * 在邊緣自己繞回,中間交給瀏覽器照 DOM 順序走,本來就不會出面板。
+ */
+function keepTabInsidePanel(e: React.KeyboardEvent, content: HTMLElement | null) {
+  if (!content) return
+  const active = content.ownerDocument.activeElement as HTMLElement | null
+  if (!active || !content.contains(active)) return // 焦點不在面板裡(例:搜尋框在觸發欄位內)→ 不歸這裡管
+  const list = tabbableOrder(content)
+  if (list.includes(active)) return
+  e.preventDefault()
+  if (list.length === 0) return // 面板裡沒有可 Tab 的東西:焦點留在原地(仍不出面板)
+  const preceding = list.filter((el) => active.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING)
+  const following = list.filter((el) => active.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)
+  const target = e.shiftKey ? (preceding[preceding.length - 1] ?? list[list.length - 1]) : (following[0] ?? list[0])
+  target.focus()
+}
+
+interface SelectMenuPopupKeysParams {
+  open: boolean
+  multiple: boolean
+  /** cmdk 反白列的 `data-value`(cmdk 會 trim)→ 對應的可選選項值;不是可選選項(建立列 / disabled)回 undefined */
+  resolveOptionValue: (dataValue: string) => string | undefined
+  isSelected: (value: string) => boolean
+  /** 單選:選定 + 收起(SelectMenu `handleSelect`) */
+  commit: (value: string) => void
+  close: () => void
+}
+
+/** 焦點在文字輸入上(可打字搜尋的搜尋框):空白鍵是打字,不是選取(判準 = lib/roving-list-keyboard.ts `isTextEntryElement`,全 DS 一份) */
+const isTextEntryTarget = (target: EventTarget | null) => target instanceof Element && isTextEntryElement(target)
+
+/** 反白列(cmdk 的 data-selected)對應的可選選項值;建立列 / 停用 / 沒有反白 → undefined */
+function highlightedOptionValue(content: HTMLElement | null, resolve: (dataValue: string) => string | undefined) {
+  const dataValue = content
+    ?.querySelector<HTMLElement>('[cmdk-item][data-selected="true"]:not([data-disabled="true"])')
+    ?.getAttribute('data-value')
+  return dataValue == null ? undefined : resolve(dataValue)
+}
+
+/**
+ * 回傳:
+ * - `triggerRef` → PopoverTrigger;`contentRef` → PopoverContent
+ * - `onKeyDown`:掛在觸發欄位(可打字搜尋時焦點在欄位內的輸入框)與 cmdk 根(不可打字時焦點在浮層裡)兩處
+ * - `onCloseAutoFocus` → PopoverContent:Tab 收起時擋掉 Radix「關閉後把焦點還給觸發欄位」——那一步在 FocusScope 卸載
+ *   (關閉動畫結束後的 setTimeout 0)才跑,會把剛走到下一格的焦點搶回來(與 B11 點名的
+ *   `agent-panel-fab.tsx:702-705`「關選單時硬搶焦點」同一類)
+ */
+export function useSelectMenuPopupKeys(params: SelectMenuPopupKeysParams) {
+  const triggerRef = React.useRef<HTMLButtonElement>(null)
+  const contentRef = React.useRef<HTMLDivElement>(null)
+  const latest = React.useRef(params)
+  latest.current = params
+  const closedByTabRef = React.useRef(false)
+
+  // 重新開啟 = 新的一輪,舊的「由 Tab 收起」記號作廢
+  React.useEffect(() => {
+    if (params.open) closedByTabRef.current = false
+  }, [params.open])
+
+  const onKeyDown = React.useCallback((e: React.KeyboardEvent) => {
+    const p = latest.current
+    if (e.altKey || e.ctrlKey || e.metaKey) return
+    // IME 組字中不動(同 DataTable handleEditTab 的 isComposing / 229 守衛)
+    if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return
+    if (!p.open || e.defaultPrevented) return
+    const content = contentRef.current
+
+    // ── 不可打字的單選:空白鍵 = 選這一項(同 Enter)──
+    // 2026-09-26 待辦總帳〇節 L7 第 1 條,主線正本定義:「不能打字的選項清單,Enter 與空白鍵都是選這一項」;
+    // 同意 = 同檔「09-26 同意清單回覆」,user 逐字:「確保符合我們一致的設計語言且不違背世界級的設計且都有確保整個ds 是SSOT,避免漂移就照你建議做」。
+    // W3C 單選下拉範例「Listbox Popup」表的 Space 列,與 Enter 列逐字相同:「Sets the value to the content of the focused option
+    // in the listbox. / Closes the listbox. / Sets visual focus on the combobox.」
+    // (https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/combobox-select-only.html#L177-L186)。
+    // 可打字(焦點在搜尋框)時空白鍵是打字,不動;多選(面板)不在本條。cmdk 自己不處理空白鍵,所以不會重複觸發。
+    if (e.key === ' ') {
+      if (p.multiple || isTextEntryTarget(e.target)) return
+      e.preventDefault()
+      const value = highlightedOptionValue(content, p.resolveOptionValue)
+      // 與 Enter 同一個動作(cmdk Enter → CommandItem onSelect → handleSelect):選定 + 收起,焦點由 Radix 還給觸發欄位
+      if (value !== undefined) p.commit(value)
+      return
+    }
+    if (e.key !== 'Tab') return
+
+    // B11 多選(有全選):行為不變,Tab 留在面板裡;只修程式落點上 Shift+Tab 跳頁尾
+    if (p.multiple) {
+      keepTabInsidePanel(e, content)
+      return
+    }
+
+    // B11 單選:Tab / Shift+Tab = 選定反白那一項 + 收起 + 從觸發欄位往下 / 往上走
+    const value = highlightedOptionValue(content, p.resolveOptionValue)
+    const trigger = triggerRef.current
+    if (!trigger) return
+    e.preventDefault()
+    closedByTabRef.current = true
+    // flushSync:先讓收起生效(可打字搜尋的輸入框卸載、觸發欄位換回顯示值),再算「下一格」,
+    // 否則算到的會是即將消失的輸入框。已是目前值 → 不重發 onValueChange,只收起。
+    flushSync(() => {
+      if (value !== undefined && !p.isSelected(value)) p.commit(value)
+      else p.close()
+    })
+    // 下一格 = 觸發欄位關著時按同一個鍵會到的那一格(lib/focus-after-trigger.ts;與選單同一份)。
+    // 本浮層關閉動畫期間還在 DOM 裡,裡面的捲動區可 Tab → 排除。
+    focusFromTrigger(trigger, e.shiftKey, (el) => !!content?.contains(el))
+  }, [])
+
+  const onCloseAutoFocus = React.useCallback((e: Event) => {
+    if (!closedByTabRef.current) return
+    closedByTabRef.current = false
+    e.preventDefault()
+  }, [])
+
+  return { triggerRef, contentRef, onKeyDown, onCloseAutoFocus }
+}

package/src/components/SelectMenu/select-menu.anatomy.stories.tsx

@@ -10,6 +10,7 @@ import { useState } from 'react'
 import { Mail, Folder, Users, Settings } from 'lucide-react'
 import { SelectMenu, type SelectMenuOption, type SelectMenuGroupConfig } from './select-menu'
 import { Button } from '@/design-system/components/Button/button'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
 
 const meta: Meta = {
@@ -348,22 +349,10 @@ function SelectMenuInspector() {
       <div className="flex flex-col gap-6">
         <div>
           <H3>Size</H3>
-          <div className="flex gap-2">
-            {SIZES.map((s) => (
-              <button
-                key={s}
-                type="button"
-                onClick={() => setSize(s)}
-                className={`px-2.5 py-1 text-caption rounded-md font-mono cursor-pointer ${
-                  s === size
-                    ? 'bg-primary text-white'
-                    : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
-                }`}
-              >
-                {s}
-              </button>
-            ))}
-          </div>
+          {/* 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項);取代手刻 pill:它靜止借 neutral-hover、hover 借 neutral-active(color.spec.md 成對 token 錯配) */}
+          <SegmentedControl size="sm" aria-label="Size" value={size} onValueChange={(v) => setSize(v as SizeKey)}>
+            {SIZES.map((s) => <SegmentedControlItem key={s} value={s}>{s}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
 
         <div>
@@ -848,7 +837,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">{"詳 `select-menu.spec.md` 「A11y 預設」段。摘要:\n\n  ARIA / Pattern  :基於  cmdk  library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — focus trigger\n- Enter / Space — 開啟 menu(trigger 由 consumer 經 PopoverTrigger asChild 提供:Select / Combobox 的 trigger 是 role=\"combobox\" 容器自綁 Enter / Space handler;若 consumer 用 DS Button 則由 native click 觸發)\n- ↑/↓ — 導覽 options(menu 開啟後)\n- Enter — 選擇\n- 字母鍵 — type-ahead 過濾(search 模式)\n- Tab(menu 開啟 + multi 模式)— DOM focus 移到 footer 全選列(role=\"checkbox\" + aria-checked,tabIndex=0;在 cmdk 導覽範圍外故走 DOM focus,2026-07-05 D4 鍵盤可達修)\n- Enter / Space(focus 在全選列)— 切換全選 / 全清\n- Esc — 關閉\n\n  Focus  :menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(aria-activedescendant 高亮,非 DOM focus);searchable 時 DOM focus 給搜尋 input;非 searchable 時 DOM focus 移到 cmdk 的 [cmdk-root](Command 元素,見 handleNonSearchableAutoFocus),讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效;option 無 tabIndex,DOM focus 不落在 option 上。關閉時 focus 回 trigger。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+      <p className="whitespace-pre-line">{"詳 `select-menu.spec.md` 「A11y 預設」段。摘要:\n\n  ARIA / Pattern  :基於  cmdk  library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — focus trigger\n- Enter / Space — 開啟 menu(trigger 由 consumer 經 PopoverTrigger asChild 提供:Select / Combobox 的 trigger 是 role=\"combobox\" 容器自綁 Enter / Space handler;若 consumer 用 DS Button 則由 native click 觸發)\n- ↑/↓ — 導覽 options(menu 開啟後)\n- Enter — 選擇\n- Space(menu 開啟 + 單選、不可打字)— 與 Enter 相同:選定反白那一項、收起、焦點回觸發欄位(待辦總帳 L7)\n- 字母鍵 — type-ahead 過濾(search 模式)\n- Tab / Shift+Tab(menu 開啟 + 單選)— 選定反白那一項、收起,焦點走到觸發欄位的下一個 / 上一個可 Tab 元素(= 選單關著時按 Tab 會到的同一格;頁面上已沒有下一格時留在觸發欄位;待辦總帳 B11)\n- Tab / Shift+Tab(menu 開啟 + 多選)— 行為不變:在面板裡繞圈(浮層內搜尋框 → 清單 → footer 的全選按鈕 → 回第一格);全選是真的 <button>,天生在 Tab 序裡(2026-09-17 起取代原本的 role=\"checkbox\" 全選列)。觸發欄位因此宣告 aria-haspopup=\"dialog\"(焦點會進到面板),單選宣告 listbox\n- Enter / Space(focus 在全選按鈕)— 切換全選 / 全清(瀏覽器原生按鈕行為)\n- Esc — 關閉、不選定\n\n  Focus  :menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(aria-activedescendant 高亮,非 DOM focus);searchable 時 DOM focus 給搜尋 input;非 searchable 時 DOM focus 移到 cmdk 的 [cmdk-root](Command 元素,見 handleNonSearchableAutoFocus),讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效;option 無 tabIndex,DOM focus 不落在 option 上。選完 / Esc 關閉時 focus 回 trigger;單選按 Tab 收起時焦點直接走到下一格、不回 trigger。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
     </div>
   ),
 }

package/src/components/SelectMenu/select-menu.spec.md

@@ -436,16 +436,20 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 **Keyboard 行為**:
 
-- Tab — focus trigger
+- Tab — focus trigger(選單關著時)
 - Enter / Space — 開啟 menu(trigger 由 consumer 經 `PopoverTrigger asChild` 提供,開啟行為由 consumer trigger 負責:Select / Combobox 的 trigger 是 `role="combobox"` 容器,自綁 Enter / Space handler 觸發開啟;若 consumer 用 DS `<Button>`(native button)則由 native click 觸發)
 - ↑/↓ — 導覽 options(menu 開啟後)
-- Enter — 選擇
+- Enter — 選擇(不可打字的單選:Space 與 Enter 相同,見下方 Space 列)
 - 字母鍵 — type-ahead 過濾(search 模式)
-- Tab(menu 開啟 + multi 模式)— DOM focus 移到 footer 的全選按鈕(真的 `<button>`,天生在 Tab 序裡;它在 CommandList 之外、非 cmdk-item,cmdk 方向鍵導覽不涵蓋)
+- Tab / Shift+Tab(menu 開啟 + **單選**)— **選定反白那一項**(已是目前值就不重發 `onValueChange`;反白在建立列 / 沒有反白時只收起,Tab 不替使用者建立新選項)→ **收起** → 焦點落到**觸發欄位的下一個 / 上一個**可 Tab 元素,也就是「選單關著時從觸發欄位按 Tab / Shift+Tab 會到的同一格」;觸發欄位在對話框 / 小面板(`role="dialog"`)裡時只在那一層裡走、到邊緣繞回(那一層的 Tab 留在裡面,見 `../Popover/popover.spec.md`「A11y 預設」)。依據:W3C 單選下拉範例 Tab 列「Sets the value to the content of the focused option in the listbox. / Closes the listbox. / Performs the default action, moving focus to the next focusable element.」(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/combobox-select-only.html#L187-L199>),Shift+Tab 同樣選定 —— 該範例在觸發欄位失焦時選定、不分方向(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/js/select-only.js#L249-L260>);Fluent 單選 `case 'Tab': !multiselect && activeOption && selectOption(e, activeOption);`(<https://github.com/microsoft/fluentui/blob/d27922755bebae866d9ffe86b7da44c27ec801ee/packages/react-components/react-combobox/library/src/utils/useTriggerSlot.ts#L198-L200>)。來源:待辦總帳 `governance/planning/2026-09-25-interaction-and-hover-remediation.md` B11(user #25 附條件同意 + #32 一致性原則;單選下拉與選單一起改屬 AI 依一致性推導,user 可於預覽否決)。實作 `select-menu-keyboard.ts` `useSelectMenuPopupKeys`;「下一格」與選單同一份 `../../lib/focus-after-trigger.ts`(2026-09-26 兩份合一):頁面上已經沒有下一格時,焦點**留在觸發欄位**(與 `DropdownMenu` 同一句,`ds-canonical/references/keyboard-model-canonical.md`「彈出框開著時的 Tab 與 Esc」;2026-09-26 前這裡交還瀏覽器,會落在 Radix 關閉動畫期間仍掛在 `<body>` 首尾的隱形焦點護欄上)
+- Space(menu 開啟 + **單選、不可打字**)— **選這一項**,與 Enter 相同:選定反白那一項 → 收起 → 焦點回觸發欄位(2026-09-26 待辦總帳 L7 第 1 條,主線定義「不能打字的選項清單,Enter 與空白鍵都是選這一項」;同意 = 同帳〇節「09-26 同意清單回覆」)。依據:W3C 單選下拉範例「Listbox Popup」表 Space 列與 Enter 列逐字相同「Sets the value to the content of the focused option in the listbox. / Closes the listbox. / Sets visual focus on the combobox.」(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/combobox-select-only.html#L177-L186>)。可打字時空白鍵是打字,不選;多選(面板)不在本條。實作 `select-menu-keyboard.ts` `useSelectMenuPopupKeys`
+- Tab / Shift+Tab(menu 開啟 + **多選**)— **行為不變:Tab 在面板裡繞圈**(浮層內搜尋框 → 清單捲動區 → footer 的全選按鈕 → 回到第一格;全選按鈕是真的 `<button>`,天生在 Tab 序裡;它在 CommandList 之外、非 cmdk-item,cmdk 方向鍵導覽不涵蓋)。多選面板裡有搜尋框 / 全選鈕、DOM 焦點會進到面板,是 W3C 的 dialog 型彈出,照對話框規則把 Tab 留在裡面(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/combobox-pattern.html#L391>、<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/dialog-modal/dialog-modal-pattern.html#L29-L30>)。焦點停在開啟時的程式落點(`[cmdk-root]`,tabIndex -1)時也一樣留在面板裡 —— 2026-09-25 前這一格按 Shift+Tab 會照 DOM 順序跳到**頁尾**並關掉面板(浮層掛在 body 最後;R15 實測)。搜尋框在觸發欄位內(Combobox `searchIn='trigger'`)時焦點不在面板裡,Tab 照頁面順序離開、面板隨焦點離開而關
 - Enter / Space(focus 在全選按鈕)— 切換全選 / 全清。瀏覽器原生按鈕行為,不需自寫 handler;cmdk root 的 Enter 只對 `[cmdk-item]` 的反白項派送,不會重複觸發
 - Esc — 關閉
 
-**Focus**:menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(`aria-activedescendant` 高亮,非 DOM focus;cmdk listbox 模式);searchable 時 DOM focus 給搜尋 input,非 searchable 時 DOM focus 移到 cmdk 的 `[cmdk-root]`(`Command` 元素,見 `handleNonSearchableAutoFocus`),讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效。option 為 `role="option"` 無 tabIndex,DOM focus 不落在 option 上。關閉時 focus 回 trigger。
+**觸發欄位宣告的彈出型別**(owner = consumer trigger,Select / Combobox 各自宣告;2026-09-25 B11「多選下拉(有全選)行為不變、只改宣告」):宣告必須等於「開著時 Tab 怎麼走」—— Tab 收起、往頁面下一格走(清單型)= `aria-haspopup="listbox"`(Select / PeoplePicker 單選、Combobox `searchIn='trigger'`);Tab 在面板裡繞圈(對話框型,面板裡有搜尋框 / 全選鈕、DOM 焦點進到面板)= `aria-haspopup="dialog"`(Combobox `searchIn='menu'`、PeoplePicker 多選預設)。已知落差(未處理,另登記):不可打字的 Select 開啟時 DOM 焦點進到浮層的 cmdk 殼,而 W3C 單選下拉範例是焦點留在觸發欄位、由觸發欄位的 `aria-activedescendant` 指向選項(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/examples/js/select-only.js#L327-L328>)。W3C:popup 不是 listbox 時 `aria-haspopup` 要寫出型別(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/combobox/combobox-pattern.html#L410-L411>),dialog 型「DOM focus moves into the dialog」(同檔 #L395)。
+
+**Focus**:menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(`aria-activedescendant` 高亮,非 DOM focus;cmdk listbox 模式);searchable 時 DOM focus 給搜尋 input,非 searchable 時 DOM focus 移到 cmdk 的 `[cmdk-root]`(`Command` 元素,見 `handleNonSearchableAutoFocus`),讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效。option 為 `role="option"` 無 tabIndex,DOM focus 不落在 option 上。選完 / Esc 關閉時 focus 回 trigger;**單選按 Tab 收起時焦點走到下一格、不回 trigger**(Radix 關閉後「還焦點給 trigger」那一步由 `onCloseAutoFocus` 擋掉,否則關閉動畫結束後會把焦點搶回來)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -453,8 +457,12 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `combobox.spec.md`
 - `command.spec.md`
 - `dropdown-menu.spec.md`
+- `empty.spec.md`
+- `field-controls.spec.md`
 - `menu-item.spec.md`
+- `people-picker.spec.md`
 - `popover.spec.md`
 - `select.spec.md`

package/src/components/SelectMenu/select-menu.tsx

@@ -19,6 +19,8 @@ import { Button } from '@/design-system/components/Button/button'
 import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'
 import { RowSizeProvider } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { applySelectAll, clearSelection } from '@/design-system/lib/multi-select-ordering'
+// 觸發欄位 ↔ 清單的鍵盤橋接(方向鍵轉送 / aria-activedescendant / 開著按 Tab / 不可打字單選的空白鍵)住在 select-menu-keyboard.ts
+import { useSelectMenuPopupKeys } from '@/design-system/components/SelectMenu/select-menu-keyboard'
 
 /**
  * SelectMenu — Popover + Command 組成的完整下拉選單
@@ -475,16 +477,29 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
     root?.focus({ preventScroll: true })
   }, [])
 
+  // 開著按 Tab / Shift+Tab(2026-09-25 待辦總帳 B11;W3C / Fluent 出處與理由見 select-menu-keyboard.ts):
+  // 單選 = 選定反白那一項 + 收起 + 焦點從觸發欄位往下 / 往上走;多選(有全選的小面板)= Tab 留在面板裡,行為不變。
+  // 不可打字的單選:空白鍵 = 選這一項,同 Enter(2026-09-26 待辦總帳 L7;出處同檔)。
+  const popupKeys = useSelectMenuPopupKeys({
+    open, multiple, isSelected, commit: handleSelect, close: () => setOpen(false),
+    // 反白列的 data-value(cmdk 已 trim)→ 可選選項值;建立列 / disabled 不算 —— Tab 不替使用者建立新選項
+    resolveOptionValue: (dataValue) => visibleOptions.find((o) => !o.disabled && o.value.trim() === dataValue)?.value,
+  })
+
   // RowSizeProvider 讓 PopoverContent 子樹內任何 <ItemIcon> / <ItemAvatar> /
   // <ItemInlineAction> 都自動讀到對的 size,跟 SidebarProvider / TreeView 同一條規則。
   // (注:Popover 透過 Portal 渲染,context 仍然會跨 portal 傳遞——React context 是 tree-based
   // 不是 DOM-based,Portal 不影響 context propagation)
   return (
     <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>{children}</PopoverTrigger>
+      {/* B11:可打字搜尋時焦點在觸發欄位內的輸入框,Tab 規則要掛在這裡(不可打字時掛在下方 Command) */}
+      <PopoverTrigger asChild ref={popupKeys.triggerRef} onKeyDown={popupKeys.onKeyDown}>{children}</PopoverTrigger>
       <RowSizeProvider value={size}>
       <PopoverContent
+        ref={popupKeys.contentRef}
         id={contentId}
+        // B11:Tab 收起時不讓 Radix 在關閉動畫後把焦點搶回觸發欄位(焦點已走到下一格)
+        onCloseAutoFocus={popupKeys.onCloseAutoFocus}
         // 2026-07-17 Dim 10 a11y 修:role="dialog" 浮層 accessible name(Radix Popover 無自動命名)
         aria-label={ariaLabel}
         // w-auto override PopoverContent default w-72(rich-popover canonical)— SelectMenu 走「跟 trigger 同寬」
@@ -528,6 +543,8 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
         }}
       >
         <Command
+          // B11 / L7:不可打字時焦點在浮層裡(cmdk 殼 / 清單),Tab 與空白鍵的規則掛在這裡
+          onKeyDown={popupKeys.onKeyDown}
           shouldFilter={searchable && filterOption}
           // 2026-07-06 cursor 起點修:單選已有值時 cmdk virtual focus 落在已選項而非第一項。
           // cmdk 1.1.1 初始 state 取 defaultValue、item mount 的 selectFirstItem 有
@@ -740,60 +757,8 @@ export const selectMenuMeta = {
   },
 } as const
 
-/**
- * 2026-07-05 D4 P0 修(searchable 鍵盤死路):trigger 內的裸 <input> 與 portal 內的 cmdk root
- * 在不同 DOM 子樹 — 鍵盤事件永遠 bubble 不到 cmdk 的 ArrowUp/Down/Enter handler([cmdk-root]
- * onKeyDown)→ searchable Select / PeoplePicker single / Combobox searchIn='trigger' 開啟後
- * 只能 Esc。修法 = APG combobox-with-list:trigger input 把三鍵 re-dispatch 給 cmdk root
- * (native KeyboardEvent bubbles 經 React root delegation 觸發 cmdk synthetic handler)。
- * Home/End 刻意不轉送(文字輸入的 caret 語意優先,對齊 MUI/Ant Autocomplete)。
- * aria-activedescendant 綁回 trigger input → 見下方 useActiveDescendant(2026-07-05 D4 補齊)。
- */
-export function forwardKeyToListbox(contentId: string | undefined, e: React.KeyboardEvent): boolean {
-  if (!contentId) return false
-  if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp' && e.key !== 'Enter') return false
-  const root = document.getElementById(contentId)?.querySelector<HTMLElement>('[cmdk-root]')
-  if (!root) return false
-  e.preventDefault()
-  root.dispatchEvent(new KeyboardEvent('keydown', { key: e.key, bubbles: true, cancelable: true }))
-  return true
-}
-
-/**
- * 2026-07-05 D4 補齊(APG combobox aria-activedescendant):追蹤 cmdk 目前 virtual-focus item
- * 的 DOM id,供 trigger 端搜尋 input 綁 `aria-activedescendant` —— SR 才會在方向鍵導覽 /
- * 打字過濾時播報 active option 名。機制:trigger 與 portal 內 cmdk 分屬不同 DOM 子樹,cmdk
- * 只把 active id 綁在自己的 Command.Input / List(cmdk source:item 自帶 auto-generated id +
- * `data-selected="true"` 標記 virtual focus)→ trigger 端用 MutationObserver 監聽 popover 容器
- * (contentId = PopoverContent id)內 `data-selected` 屬性變化 + childList(打字過濾 re-render
- * 換 item 節點),單一機制涵蓋全部更新路徑:開啟初始 auto-highlight / forwardKeyToListbox
- * 方向鍵轉送 / 搜尋過濾後 cmdk 自動移 cursor / pointer hover。
- * 關閉時清 undefined —— ARIA 要求 id 必指向存在於 DOM 的節點,不可留 stale id。
- */
-export function useActiveDescendant(contentId: string | undefined, open: boolean): string | undefined {
-  const [activeId, setActiveId] = React.useState<string | undefined>(undefined)
-  React.useEffect(() => {
-    if (!open || !contentId) {
-      setActiveId(undefined)
-      return
-    }
-    // PopoverContent 與 trigger 同一個 React commit mount(open state 同批 render)→ effect 跑時已在 DOM
-    const container = document.getElementById(contentId)
-    if (!container) return
-    const read = () => {
-      setActiveId(container.querySelector<HTMLElement>('[cmdk-item][data-selected="true"]')?.id || undefined)
-    }
-    // 初始補讀:MutationObserver 只看「觀察開始後」的變化;cmdk 初始 auto-highlight(layout effect
-    // 排程)可能已 commit → rAF 讀當下狀態兜底,與 observer 互補、誰先到都不漏。
-    const raf = requestAnimationFrame(read)
-    const observer = new MutationObserver(read)
-    observer.observe(container, { subtree: true, childList: true, attributes: true, attributeFilter: ['data-selected'] })
-    return () => {
-      cancelAnimationFrame(raf)
-      observer.disconnect()
-    }
-  }, [open, contentId])
-  return activeId
-}
+// forwardKeyToListbox / useActiveDescendant 原樣搬到 select-menu-keyboard.ts(2026-09-25,與 B11 的 Tab 規則同住一個
+// 鍵盤模組;本檔已近 800 行上限)。從這裡轉出,Select / Combobox 既有的 import 路徑不變。
+export { forwardKeyToListbox, useActiveDescendant } from '@/design-system/components/SelectMenu/select-menu-keyboard'
 
 export { SelectMenu }