@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -1,12 +1,17 @@
+/**
+ * @internal — DS-internal 單元(per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Select / Combobox wrap 消費,end-user app 請用 wrapper 元件。
+ */
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 import * as React from 'react'
 import { Plus, Search } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { useControllable } from '@/design-system/hooks/use-controllable'
 import type { AvatarData } from '@/design-system/components/Avatar/avatar'
 import { Popover, PopoverContent, PopoverTrigger } from '@/design-system/components/Popover/popover'
 import { Command, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator } from '@/design-system/components/Command/command'
-import { Command as CommandPrimitive } from 'cmdk'
+import { Command as CommandPrimitive, useCommandState } from 'cmdk'
 import { MenuItem, MenuFooter } from '@/design-system/components/Menu/menu-item'
 import { Empty } from '@/design-system/components/Empty/empty'
 import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
@@ -26,7 +31,7 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
  * ── 架構 ──
  *   Popover（浮動容器）
  *     └── Command（cmdk，搜尋 + 鍵盤導覽）
- *           ├── CommandInput（搜尋框）
+ *           ├── CommandPrimitive.Input（搜尋框,raw cmdk + 自建 icon/min-h wrapper,非 DS CommandInput）
  *           ├── CommandList（選項列表）
  *           │     └── CommandGroup → MenuItem
  *           └── Footer（多選全選）
@@ -39,6 +44,8 @@ export interface SelectMenuOption {
   label: string
   description?: string
   icon?: LucideIcon
+  /** icon 染色 className(2026-07-08:status 類彩色 option;M30 primitive schema 擴充) */
+  iconClassName?: string
   avatar?: AvatarData
   disabled?: boolean
   group?: string
@@ -74,17 +81,32 @@ export interface SelectMenuProps {
   onCreate?: (value: string) => void
   /** creatable 的 label 格式，預設 '直接使用「{query}」' */
   createLabel?: (query: string) => string
+  /**
+   * 受控搜尋字串(2026-07-18 決策11:讓 consumer 用**外部搜尋**(如 Select 的 trigger 內嵌 input)
+   * 驅動 creatable create-row 顯隱)。傳入 = 受控(SelectMenu 不自管 search、close 不 reset,由
+   * parent 負責);不傳 = 內部 uncontrolled(既有行為,零影響)。搭配 `searchable=false` +
+   * `creatable` 時,SelectMenu 不畫自己的 input,但 create-row 仍依此 search 顯示。
+   */
+  search?: string
+  /** 受控搜尋變更通知(選配;SelectMenu 內部無 input 時通常由 parent 單向驅動,不需此) */
+  onSearchChange?: (value: string) => void
 
   /** 觸發元件（asChild） */
   children: React.ReactNode
   /** 搜尋框 placeholder */
   searchPlaceholder?: string
+  /** 搜尋框 accessible name；與可見 placeholder 分離。 */
+  searchAriaLabel?: string
   /** 空選項提示 */
   emptyText?: string
-  /** Loading 狀態(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)
-   *  true → render `<Empty icon={<CircularProgress size={48}/>} description={loadingText} />` 取代 options;
-   *  trigger 不變,user 隨時可開 dropdown。對齊 MUI Autocomplete `loadingText` dropdown-body + Ant Select
-   *  loading idiom + DS 既有 `empty.spec.md:182` 「全頁 loading = Empty + CircularProgress compose」SSOT。
+  /** 載入中狀態的無障礙文案(i18n:consumer 換語言時覆寫) */
+  loadingText?: string
+  /** 多選 footer 全選列文字(2026-07-05 D4:原「全部」字面 hardcode,無法覆寫也無法 i18n) */
+  selectAllLabel?: string
+  /** Loading 狀態(2026-05-15 audit B fix;2026-07-04 Q3 拍板措辭修訂)
+   *  true → 無可顯示選項時 empty slot(cmdk CommandEmpty)渲可命名的
+   *  `role="status"` wrapper + 48px CircularProgress；已有 options 時保留顯示不清空
+   *  (MUI Autocomplete「only if there are no suggestions」共識)。trigger 不變,user 隨時可開 dropdown。
    */
   loading?: boolean
 
@@ -110,14 +132,43 @@ export interface SelectMenuProps {
   onOpenAutoFocus?: (e: Event) => void
 
   /**
-   * Popover 內容容器的 DOM id。Combobox / 自定 trigger 用 `aria-controls` 指向此 id 時,
-   * 需傳入相同 id 讓 AT 能找到對應的 listbox。
+   * Popover 內容容器的 DOM id(set 在 PopoverContent 外層 div,**非** cmdk 內層 `role="listbox"` 本身)。
+   * Combobox / 自定 trigger 用 `aria-controls` 指向此 id 時,指向的是 **popover 容器(listbox 的 ancestor)**——
+   * AT 經此容器可定位到內部 cmdk listbox(cmdk List 自帶 auto-generated `role="listbox"` id)。
    */
   contentId?: string
 
+  /**
+   * 浮層 accessible name(2026-07-17 Dim 10 a11y 修)。Radix Popover 的 content 為
+   * `role="dialog"` 但無自動命名機制 → 無 aria-label 時 dialog 無 accessible name。
+   * 預設「選項清單」讓 SR 使用者知道浮層用途;consumer(Combobox / Select / PeoplePicker)
+   * 可傳更 contextual 的名(如欄位名)。SSOT 放此一處 → 全 SelectMenu consumer 受益。
+   */
+  'aria-label'?: string
+
   className?: string
 }
 
+// ── SR live status(2026-07-05 D4:empty / loading 空狀態對 SR 不可感知修)──
+// cmdk CommandEmpty 渲染為 role="presentation" div、cmdk 全鏈無 aria-live,且 DOM focus 停在
+// combobox input(aria-activedescendant 虛擬焦點)→ SR 使用者搜尋到 0 結果或 loading 佔位時
+// 聽不到任何播報(loading spinner 的 CircularProgress 無 label 時更是 aria-hidden)。
+// 補 visually-hidden polite live region,鏡射 CommandEmpty 的無結果文字。Loading 改由可見
+// spinner 的 `role="status"` + `aria-label` 直接宣告，避免同一狀態重複播報。
+// cmdk Empty 只在 filtered.count === 0 渲染。對齊 react-select A11yText /
+// APG combobox no-results 播報 + empty.spec.md「動態 filter no-results 容器需 aria-live="polite"」。
+// SSOT 放 SelectMenu 一處 → Select / Combobox / PeoplePicker 全體受益。
+function SelectMenuLiveStatus({ loading, emptyText }: { loading: boolean; emptyText: string }) {
+  const filteredCount = useCommandState((state) => state.filtered.count)
+  return (
+    <div role="status" aria-live="polite" className="sr-only">
+      {filteredCount === 0
+        ? (loading ? null : emptyText)
+        : null}
+    </div>
+  )
+}
+
 // shadcn canonical:forwardRef + displayName 統一。SelectMenu 是 Popover + Command
 // composite,自身無 DOM host(trigger 由 consumer 以 asChild children 提供),ref 簽名
 // 保留但不附著(consumer 想取 trigger DOM 直接在 children 上自己 ref)。className 合併到
@@ -132,9 +183,14 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
   creatable = false,
   onCreate,
   createLabel = (q) => `直接使用「${q}」`,
+  search: controlledSearch,
+  onSearchChange,
   children,
   searchPlaceholder = '搜尋…', // i18n-allow: DS default; consumer override via searchPlaceholder prop
+  searchAriaLabel = '搜尋選項', // i18n-allow: DS default; consumer override via searchAriaLabel prop
   emptyText = '沒有符合的選項', // i18n-allow: DS default; consumer override via emptyText prop
+  loadingText = '載入選項中', // i18n-allow: DS default; consumer override via loadingText prop
+  selectAllLabel = '全部', // i18n-allow: DS default; consumer override via selectAllLabel prop
   loading = false,
   size = 'md',
   align = 'start',
@@ -146,13 +202,31 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
   renderLabel,
   onOpenAutoFocus,
   contentId,
+  'aria-label': ariaLabel = '選項清單', // i18n-allow: DS default; consumer override via aria-label prop
   className,
 }, _ref) {
   // ── State ──
-  const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false)
-  const open = controlledOpen ?? internalOpen
-  const setOpen = controlledOnOpenChange ?? setInternalOpen
-  const [search, setSearch] = React.useState('')
+  // 2026-06-11 R2 bug fix:原手寫 `setOpen = controlledOnOpenChange ?? setInternalOpen` 在
+  // uncontrolled + onOpenChange listener 場景(傳 onOpenChange 不傳 open)會讓 listener 蓋掉
+  // internal setter → menu 開不了。改消費 DS 既有 useControllable(select.tsx 同 canonical):
+  // uncontrolled 時 internal state 為準、onOpenChange 僅通知。
+  const [open, setOpen] = useControllable<boolean>({
+    value: controlledOpen,
+    defaultValue: defaultOpen ?? false,
+    onChange: controlledOnOpenChange,
+  })
+  // search:選配受控(決策11)。傳 `search` prop = 受控(parent 驅動,如 Select trigger input);
+  // 不傳 = 內部 uncontrolled(既有行為)。setSearch 同步內部 + 通知 onSearchChange。
+  const isSearchControlled = controlledSearch !== undefined
+  const [internalSearch, setInternalSearch] = React.useState('')
+  const search = isSearchControlled ? controlledSearch : internalSearch
+  const setSearch = React.useCallback(
+    (next: string) => {
+      if (!isSearchControlled) setInternalSearch(next)
+      onSearchChange?.(next)
+    },
+    [isSearchControlled, onSearchChange],
+  )
 
   // ── Value helpers ──
   const selectedValues = React.useMemo<string[]>(() => {
@@ -165,6 +239,12 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
     [selectedValues]
   )
 
+  // 2026-07-05 P2:單選已選 option — 供 cmdk defaultValue 定 cursor 起點(見下方 <Command>)
+  const selectedOption = React.useMemo(
+    () => (!multiple ? options.find((o) => o.value === selectedValues[0]) : undefined),
+    [multiple, options, selectedValues]
+  )
+
   const handleSelect = React.useCallback(
     (optionValue: string) => {
       if (multiple) {
@@ -236,10 +316,23 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
     return grouped
   }, [groups, options])
 
-  // ── Reset search on close ──
+  // ── Reset search on close(僅 uncontrolled;受控時由 parent 負責 reset)──
   React.useEffect(() => {
-    if (!open) setSearch('')
-  }, [open])
+    if (!open && !isSearchControlled) setInternalSearch('')
+  }, [open, isSearchControlled])
+
+  // 2026-06-01 Select/Combobox #15(user 拍板 A):非搜尋時開選單把 focus 移到 cmdk-root,
+  // 讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效。原 PopoverContent default autofocus 找 body
+  // input/button,非搜尋無 input + 選項是 role=option div → focus 落在 content wrapper,cmdk 的 keydown
+  // handler 綁在 cmdk-root 收不到事件 → 桌機鍵盤導覽不可達(WAI-ARIA combobox 違反)。
+  // **純鍵盤路由**:滑鼠點擊路徑完全不碰;cmdk active-option highlight 是 cmdk 內部 state(非 DOM focus
+  // 驅動)故視覺不變。selector miss 時 root=null → no-op fallback(無回歸)。
+  // SSOT 在 SelectMenu → Select / Combobox / 所有 non-searchable SelectMenu consumer 自動受益。
+  const handleNonSearchableAutoFocus = React.useCallback((e: Event) => {
+    e.preventDefault()
+    const root = (e.currentTarget as HTMLElement).querySelector<HTMLElement>('[cmdk-root]')
+    root?.focus({ preventScroll: true })
+  }, [])
 
   // RowSizeProvider 讓 PopoverContent 子樹內任何 <ItemIcon> / <ItemAvatar> /
   // <ItemInlineAction> 都自動讀到對的 size,跟 SidebarProvider / TreeView 同一條規則。
@@ -251,6 +344,8 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
       <RowSizeProvider value={size}>
       <PopoverContent
         id={contentId}
+        // 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 同寬」
         // canonical(spec L72)。minWidth = max(trigger-width, 240px sensible-min)— 對齊 shadcn / Material / Ant
         // select dropdown 共識(2026-05-04 D1 verify SelectMenu spec implementation)。
@@ -264,7 +359,7 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
         }}
         align={align}
         sideOffset={OVERLAY_SIDE_OFFSET}
-        onOpenAutoFocus={onOpenAutoFocus}
+        onOpenAutoFocus={onOpenAutoFocus ?? (!searchable ? handleNonSearchableAutoFocus : undefined)}
         // **2026-05-07 v15.16 nested portal fix**:Tag dismiss inside trigger
         // 區的 OverflowIndicator HoverCard popup(獨立 Radix portal,DOM 不在
         // PopoverContent 內)— Radix DismissableLayer document-level outside
@@ -291,7 +386,23 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
           }
         }}
       >
-        <Command shouldFilter={searchable} className="bg-transparent">
+        <Command
+          shouldFilter={searchable}
+          // 2026-07-06 cursor 起點修:單選已有值時 cmdk virtual focus 落在已選項而非第一項。
+          // cmdk 1.1.1 初始 state 取 defaultValue、item mount 的 selectFirstItem 有
+          // `state.value ||` guard 不覆蓋(dist source 驗證);Popover 關閉即 unmount(無
+          // forceMount)→ 每次開啟 remount 重新生效。需搭配下方 CommandItem value={opt.value}。
+          defaultValue={selectedOption?.value}
+          // 2026-07-06 A11y:combobox accessible name。2026-07-14 修正註解(cmdk 1.1.1 dist 實證):
+          // cmdk **無條件**渲 sr-only <label htmlFor={inputId}>(dist/index.mjs
+          // `createElement("label",{htmlFor:U.inputId,id:U.labelId,...},b)` — label prop 只決定
+          // 文字內容,不決定 label 元素是否渲染)。故 non-searchable 時「空 label + htmlFor 指向
+          // 不存在的 input」仍存在(upstream cmdk 限制;空 label 無 accessible name,不產生朗讀
+          // 內容)。僅 searchable(真的有 input)時傳內容 = 避免 non-searchable 帶 search
+          // placeholder 的 accessible name 卻無對應 input;真要消除 orphan label 需 upstream 修。
+          label={searchable ? searchAriaLabel : undefined}
+          className="bg-transparent"
+        >
           {searchable && (
             <div className={cn(
               'flex items-center gap-2 px-3 py-1 border-b border-divider',
@@ -318,41 +429,84 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
               user 過濾出 < minRows 個 match 時 list 底下空一片(eg. 打 'c' 出 2 個 match
               卻撐高到 3 row 容量,1 row 留白)。 Fix:只有 empty state 才需要 minHeight 撐
               起 placeholder 視覺;有 results 時 CommandList 自然 fit content。 */}
-          <CommandList className="relative">
+          {/* aria-busy(2026-07-04):loading 時標注 listbox 忙碌——兌現 select.spec.md「Loading」段
+              「+ aria-busy」承諾(cmdk List 本身即 role="listbox" 容器,wrapper forward props)。 */}
+          <CommandList
+            className="relative"
+            aria-busy={loading || undefined}
+            // 2026-07-06 A11y:cmdk List 的 aria-label 由其 `label` prop 渲染(內部 spread 後 override,
+            // 直接傳 aria-label 會被 cmdk default "Suggestions" 蓋掉 silent 失效)— 必走 label prop。
+            label="選項" // i18n-allow: DS default; listbox accessible name
+          >
             <CommandEmpty
               className="flex items-center justify-center"
               style={{ minHeight: getMenuListMinHeight(size, minRows) }}
             >
               {loading
-                ? <Empty icon={<CircularProgress size={48}/>} className="py-6" />
+                ? (
+                    <div role="status" aria-label={loadingText} className="flex items-center justify-center py-6">
+                      <CircularProgress size={48} />
+                    </div>
+                  )
                 : <Empty description={emptyText} className="py-6" />}
             </CommandEmpty>
 
             {groupedOptions.map((group, gi) => (
               <React.Fragment key={group.key}>
                 {gi > 0 && <CommandSeparator />}
-                <CommandGroup className="p-0 py-2">
-                  {group.label && (
-                    <MenuItem size={size} header>{group.label}</MenuItem>
-                  )}
+                <CommandGroup
+                  className="p-0 py-2 [&_[cmdk-group-heading]]:p-0"
+                  // 2026-07-06 A11y:群組標題走 cmdk `heading`(自動產 cmdk-group-heading id,選項容器
+                  // role="group" + aria-labelledby 指向之)取代手刻 child row(原本 AT 不可感知;
+                  // aria-label fallback 對 role="presentation" group 無效)。[&_[cmdk-group-heading]]:p-0
+                  // 中和 command.tsx base 的 px-3 py-1.5(tailwind-merge p-0 勝);字級 / 顏色由 MenuItem
+                  // header 自帶(text-body leading-compact + font-medium + text-fg-muted),視覺不變。
+                  heading={group.label ? <MenuItem size={size} header>{group.label}</MenuItem> : undefined}
+                >
                   {group.options.map((opt) => (
                     <CommandItem
                       key={opt.value}
-                      value={opt.label}
-                      keywords={opt.description ? [opt.description] : undefined}
+                      // 2026-07-06 識別值修:cmdk 以 value 當 item identity + selection state。原用
+                      // opt.label → 重複 label 時雙亮 + Enter 選錯;改唯一的 opt.value,label 移入
+                      // keywords 保搜尋照樣命中(cmdk filter 對 value + keywords 計分)。
+                      value={opt.value}
+                      keywords={opt.description ? [opt.label, opt.description] : [opt.label]}
                       disabled={opt.disabled}
                       onSelect={() => handleSelect(opt.value)}
-                      className="p-0 rounded-none data-[selected=true]:bg-transparent"
+                      // 2026-07-05 D4 P0 修:原 data-[selected=true]:bg-transparent 蓋掉 command.tsx base
+                      // 的 data-[selected=true]:bg-neutral-hover = cmdk virtual focus(aria-activedescendant)
+                      // 鍵盤 cursor 唯一視覺通道被抹掉 → 方向鍵移動畫面零變化(影響 Select/Combobox/PeoplePicker
+                      // 全家)。鏡射 DropdownMenu wrapper pattern:互動 bg 單一 owner 在外層 CommandItem
+                      //(base highlight 恢復;persistent selection 上移;selected×cursor 加深一階 —
+                      // 對齊本日 DropdownMenu Q2 決策),內層 MenuItem 全透明。
+                      className={cn(
+                        'p-0 rounded-none',
+                        // 2026-08-11 user 拍板糾正 D4 實作縫(SSOT = item-anatomy「選中 × 互動疊加」):
+                        // cmdk 反白訊號滑鼠也觸發,深化本應僅限鍵盤(D4 原意即「鍵盤 cursor」)。
+                        // 滑鼠 hover 選中項 → 釘住 bg-neutral-selected 不變(滑鼠自有游標,不需底色指位);
+                        // 鍵盤反白(data-selected 且非 :hover)→ -focus 深一階(游標可見,WCAG 2.4.7)。
+                        // not-hover 編譯為 :not(*:hover) + @media not (hover:hover)(POC 已驗),
+                        // 深化 (0,3,0) > 釘住 (0,2,0),與 CSS 順序無關;token 從借用的 -active 歸位 -focus。
+                        !multiple && isSelected(opt.value) && 'bg-neutral-selected data-[selected=true]:bg-neutral-selected data-[selected=true]:not-hover:bg-neutral-selected-focus',
+                      )}
                     >
                       <MenuItem
                         size={size}
                         startIcon={opt.icon}
+                        startIconClassName={opt.iconClassName}
                         avatar={opt.avatar}
                         description={opt.description}
                         checkbox={multiple}
                         checked={isSelected(opt.value)}
                         selected={!multiple && isSelected(opt.value)}
                         disabled={opt.disabled}
+                        // 2026-07-05 D4:巢狀 role 修 — MenuItem 預設 role="option" + aria-selected(persistent
+                        // selection)巢狀在 cmdk CommandItem(本身 role="option" + aria-selected=cursor)內,
+                        // AT 讀到 option 包 option 且內外 aria-selected 語意相反 → 朗讀錯亂。鏡射 DropdownMenu
+                        // canonical(dropdown-menu.tsx「Pure visual — Radix parent handles role/aria」):
+                        // 內層純視覺 role="presentation",cmdk CommandItem 是唯一 option 節點。
+                        role="presentation"
+                        className="!bg-transparent hover:!bg-transparent"
                       >
                         {renderLabel ? renderLabel(opt) : opt.label}
                       </MenuItem>
@@ -368,14 +522,20 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
                 <CommandSeparator />
                 <CommandGroup className="p-0 py-2">
                   <CommandItem
-                    value={search}
+                    // 2026-07-06:`__create__` 前綴防 identity 撞名 — 選項 row 改用 opt.value 識別後,
+                    // search 恰等於某 option.value 時裸 search 會與該 row 同 value(cmdk 雙亮 + Enter
+                    // 選錯)。value 含 search 子字串,cmdk filter 照樣命中;onSelect closure 讀 search
+                    // 不受影響。
+                    value={`__create__${search}`}
                     onSelect={() => {
                       onCreate?.(search.trim())
                       setSearch('')
                     }}
-                    className="p-0 rounded-none data-[selected=true]:bg-transparent"
+                    className="p-0 rounded-none"
                   >
-                    <MenuItem size={size} startIcon={Plus}>
+                    {/* 2026-07-05 D4:同上方選項 row 的巢狀 role 修 — creatable row 同樣是
+                        MenuItem 巢狀在 cmdk CommandItem(option)內,內層純視覺 role="presentation"。 */}
+                    <MenuItem size={size} startIcon={Plus} role="presentation" className="!bg-transparent hover:!bg-transparent">
                       {createLabel(search.trim())}
                     </MenuItem>
                   </CommandItem>
@@ -384,18 +544,38 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
             )}
           </CommandList>
 
+          {/* SR 播報 empty / loading 空狀態(見 SelectMenuLiveStatus docblock,2026-07-05 D4) */}
+          <SelectMenuLiveStatus loading={loading} emptyText={emptyText} />
+
           {/* Multi-select footer: Select All
               - 沒有選項時不顯示(selectableOptions.length === 0)
               - 搜尋有文字時不顯示(search 非空 = 使用者在找特定項目,「全選」沒意義) */}
           {multiple && selectableOptions.length > 0 && !search && (
             <MenuFooter>
+              {/* 2026-07-05 D4:全選列鍵盤可達修 — 原裸 MenuItem(div 預設 role="option" 無 tabIndex)
+                  位於 CommandList 之外:cmdk 方向鍵只導覽 [cmdk-item]、Tab 也到不了 div → 鍵盤使用者
+                  完全無法操作全選(WCAG 2.1.1),且該 role="option" 無 listbox 祖先(orphan,axe
+                  aria-required-parent)。改真實 focusable checkbox 語意:tabIndex=0 + role="checkbox" +
+                  aria-checked(indeterminate → "mixed")+ Enter / Space 觸發;preventDefault 讓 cmdk root
+                  onKeyDown(源碼檢查 e.defaultPrevented)不會再對 active option 重複觸發 Enter。
+                  aria-selected 顯式蓋回 undefined(MenuItem 內建 aria-selected 對 role="checkbox" 無效)。 */}
               <MenuItem
                 size={size}
                 checkbox
                 checked={allState}
                 onClick={handleSelectAll}
+                role="checkbox"
+                aria-checked={allState === 'indeterminate' ? 'mixed' : allState}
+                aria-selected={undefined}
+                tabIndex={0}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault()
+                    handleSelectAll()
+                  }
+                }}
               >
-                全部
+                {selectAllLabel}
               </MenuItem>
             </MenuFooter>
           )}
@@ -412,19 +592,82 @@ SelectMenu.displayName = 'SelectMenu'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const selectMenuMeta = {
   component: 'SelectMenu',
-  family: 4,
+  // 2026-07-14 修 family 自我矛盾:原 Phase-1 mechanical 填 4(Field control),與 spec body
+  // 「Layout Family:非上述 family — composite / multi-section」矛盾。SelectMenu 是 Popover +
+  // Command composite overlay(trigger 由 consumer Select / Combobox own,Family 4 是 trigger
+  // 側 field control 的事);對齊 DS composite 慣例(Accordion / Command / Popover meta 皆
+  // family: null + spec frontmatter composite)。
+  family: null, // non-family composite / overlay(對齊 spec frontmatter composite)
   variants: {
 
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 單選 option 持續選中(bg-neutral-selected);'active' 保留 — cmdk virtual-focus on
+  // selected(鍵盤反白,非 hover)走 bg-neutral-selected-focus(2026-08-11 token 歸位:-active 回歸按壓專屬)。
+  states: ['default', 'hover', 'active', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-surface-raised', 'bg-transparent'],
+    bg: ['bg-neutral-selected', 'bg-neutral-selected-focus', 'bg-surface-raised', 'bg-transparent'],
     fg: ['text-fg-muted'],
     ring: [],
   },
 } 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
+}
+
 export { SelectMenu }

package/src/components/SelectionControl/boolean-value.tsx

@@ -0,0 +1,39 @@
+// @internal — boolean 值展示符號 SSOT(view / readonly 態);consumer 用 Checkbox / Switch 不直用。
+// ── 消費的 SSOT ──
+// - lucide-react Check / X(DS icon canonical:成功/勾 = Check、關閉/否 = X,見 ui-development.md「Icon canonical」)
+// - components/Field/field-context.ts(FieldSize 型別 → icon 尺寸對齊 value 文字)
+// - tokens/color:text-foreground(展示值中性色,同 readonly value / 空值 canonical)
+//
+// 世界級對照(M22,2026-07-09 本 session 查證):read-only boolean 顯示 = 勾/叉 icon,中性色(非紅綠):
+//   MUI X DataGrid boolean cell = Check / Close(X)icon,default 中性色(非 red/green)
+//   Refine(Ant)BooleanField https://refine.dev/docs/ui-integrations/ant-design/components/fields/boolean-field/ = 勾 / 叉
+//   React-admin BooleanField https://marmelab.com/react-admin/BooleanField.html = TrueIcon / FalseIcon(預設 勾 / 叉)
+// 為何中性色不用紅叉綠勾:false = 「否」值本身,非「錯誤 / 被拒」;error / warning 是另一條 error token 通道,
+// 不靠此 glyph 表達。true/false 對稱同色 = MUI/React-admin 共識。
+import { Check, X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import type { FieldSize } from '@/design-system/components/Field/field-context'
+
+// icon 尺寸對齊 value 文字(fieldDisplayTextClass:sm/md → text-body 14px、lg → text-body-lg 16px)。
+const booleanIconSize: Record<FieldSize, string> = {
+  sm: 'size-3.5', // 14px
+  md: 'size-3.5', // 14px
+  lg: 'size-4', //   16px
+}
+
+/**
+ * BooleanValueIcon — boolean 值的展示符號(true = Check 勾 / false = X 叉),中性 `text-foreground` 色。
+ * Checkbox / Switch 的 view + readonly 態、DataTable boolean cell(經 Checkbox)全消費此 SSOT。
+ */
+export function BooleanValueIcon({
+  checked,
+  size = 'md',
+  className,
+}: {
+  checked: boolean
+  size?: FieldSize
+  className?: string
+}) {
+  const Icon = checked ? Check : X
+  return <Icon aria-hidden className={cn(booleanIconSize[size], 'text-foreground', className)} />
+}

package/src/components/SelectionControl/index.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './boolean-value'
+export * from './selection-item'