@qijenchen/design-system 0.1.0-beta.80 → 0.1.0-beta.82

package/src/components/Select/select.tsx

@@ -10,7 +10,7 @@ import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY, nakedCellRowModeAli
 import { Tag } from '@/design-system/components/Tag/tag'
 import { ItemInlineAction, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
-import { SelectMenu, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
+import { SelectMenu, forwardKeyToListbox, useActiveDescendant, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
 import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
 import { useControllable } from '@/design-system/hooks/use-controllable'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
@@ -78,9 +78,10 @@ export interface SelectProps
   startIcon?: LucideIcon
   /** 啟用搜尋（desktop 時 field 變 input，打字即篩選） */
   searchable?: boolean
-  /** Loading state(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)。
-   *  Forward 給 SelectMenu primitive SSOT;dropdown 開啟時取代 options 顯 CircularProgress + loadingText。
-   *  Trigger 不變(chevron 保留 user 隨時可點開)。對齊 Field family loading SSOT + Empty 元件 `<Empty icon={CircularProgress}/>` compose。*/
+  /** Loading state(2026-05-15 audit B fix;2026-07-04 Q3 拍板措辭修訂)。
+   *  Forward 給 SelectMenu primitive SSOT;spinner 只在**無可顯示選項時**佔 empty slot(cmdk CommandEmpty
+   *  機制)— 已有 stale options 時保留顯示不清空(對齊 MUI Autocomplete「only if there are no suggestions」)。
+   *  Trigger 不變(chevron 保留 user 隨時可點開)。*/
   loading?: boolean
 
   /** Menu list 最小列數(空狀態 / 選項少時的視覺一致 reserve)。預設 3 — 選項 < 3 時顯式縮(如 And/Or 兩選項) */
@@ -112,6 +113,11 @@ export interface SelectProps
    * (avatar + name)而非純文字 label。對齊 PeoplePicker = Select wrapper SSOT。
    */
   selectedItemRenderer?: (selectedOpt: SelectOption) => React.ReactNode
+  /** 搜尋無結果提示(2026-07-04 Q4 拍板接線 — 原 spec 宣稱可覆寫但 prop 從未轉發)。
+   *  Forward 給 SelectMenu primitive SSOT(default 在 SelectMenu 層「沒有符合的選項」);
+   *  僅 Custom path(searchable dropdown)生效,Native path 無搜尋空狀態。
+   *  對齊 MUI noOptionsText / Ant notFoundContent / Polaris emptyState 三家公開覆寫點共識。 */
+  emptyText?: string
 }
 
 // ── Icon / size helpers ─────────────────────────────────────────────────────
@@ -172,6 +178,9 @@ function CustomSelectTriggerContent({
   search,
   setSearch,
   inputRef,
+  activeDescendantId,
+  ariaLabel,
+  labelId,
   selectedItemRenderer,
 }: {
   searchable: boolean
@@ -188,6 +197,9 @@ function CustomSelectTriggerContent({
   search: string
   setSearch: (v: string) => void
   inputRef: React.RefObject<HTMLInputElement | null>
+  activeDescendantId?: string
+  ariaLabel?: string
+  labelId?: string
   selectedItemRenderer?: (selectedOpt: SelectOption) => React.ReactNode
 }): React.ReactNode {
   // Searchable + open: 顯示搜尋 input
@@ -198,8 +210,12 @@ function CustomSelectTriggerContent({
   // - sibling `<span aria-hidden pointer-events-none absolute inset-0 truncate>` 在 search='' 且
   //   有 selectedLabel 時 overlay 顯該人名(memory aid,truncate-with-ellipsis 可控)
   // 對齊 spec.md §B row 4「open + inline-search + 選 1 人 → input cursor + placeholder = 該人名 + ellipsis」。
-  // a11y guard(per codex Q2 reply):input aria-label / accessible name 來自 field/label/aria-label,
-  // **不**依賴 placeholder 當 label;overlay span aria-hidden + pointer-events-none。
+  // a11y(2026-07-05 backlog 補接):搜尋 input 是 open 時實際聚焦的元素,accessible name 必接在
+  // input 本身(原 codex Q2 guard 註解宣稱「來自 field/label/aria-label」,但接線全在外層 trigger
+  // div,焦點所在的 input 無 name)— aria-labelledby 接 FieldLabel labelId、consumer aria-label
+  // 優先(對齊 trigger div 同款 guard),兩者皆無時 fallback aria-label「搜尋選項」(對齊
+  // combobox.tsx searchAriaLabel canonical default);**不**依賴 placeholder 當 label;overlay
+  // span aria-hidden + pointer-events-none。APG「combobox role 移到 input 本身」屬中期重構另案。
   if (searchable && open) {
     const triggerEmptyPlaceholder = placeholder || '搜尋…' // i18n-allow: DS fallback
     const showSelectedOverlay = !search && selectedLabel
@@ -210,6 +226,11 @@ function CustomSelectTriggerContent({
           ref={inputRef as React.RefObject<HTMLInputElement>}
           value={search}
           onChange={(e) => setSearch(e.target.value)}
+          // a11y(2026-07-05 D4):cmdk active item id(useActiveDescendant)→ SR 播報方向鍵導覽中的 option
+          aria-activedescendant={activeDescendantId}
+          // accessible name:aria-labelledby(Field label)> consumer aria-label > DS default(accname 優先序)
+          aria-label={ariaLabel ?? '搜尋選項'} // i18n-allow: DS default(對齊 combobox.tsx searchAriaLabel canonical)
+          aria-labelledby={ariaLabel ? undefined : labelId}
           // Native placeholder 限 trigger empty hint(無 selectedLabel 時);若已 selected,留空交給 overlay span
           placeholder={showSelectedOverlay ? '' : triggerEmptyPlaceholder}
           className={cn(bareInputStyles, 'cursor-text')}
@@ -362,7 +383,11 @@ function ReadonlyDisplay({
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
-  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, ...props }, ref) => {
+  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp,
+    // 2026-07-04:Custom-path-only props 顯式 destructure 丟棄(不 spread 到原生 <select> 消 React
+    // unknown-prop warning);各 prop docblock 已註「僅 Custom path 生效」語意
+    searchable: _searchable, groups: _groups, loading: _loading, minRows: _minRows, emptyText: _emptyText, defaultOpen: _defaultOpen, onOpenChange: _onOpenChange, selectedItemRenderer: _selectedItemRenderer,
+    ...props }, ref) => {
     const fieldCtx = useFieldContext()
     const error = useResolvedFieldInvalid(errorProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
@@ -407,7 +432,8 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
         {...props}
       >
         {placeholder && <option value="" disabled>{placeholder}</option>}
-        {options.map(opt => <option key={opt.value} value={opt.value}>{opt.label}</option>)}
+        {/* disabled forward(2026-07-04):對齊桌機 path menuOptions disabled forward — 觸控原生 option 同樣不可選(spec「disabled 選項」邊界案例) */}
+        {options.map(opt => <option key={opt.value} value={opt.value} disabled={opt.disabled}>{opt.label}</option>)}
       </select>
     )
 
@@ -427,8 +453,8 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
 
     if (!isTextDisplay) {
       return (
-        <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value && tagPadding[size], 'relative',
-          error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
+        <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }), value && tagPadding[size], 'relative',
+          className)}
           style={{ paddingRight: 'var(--field-px)' }} data-field-mode="edit" data-error={error ? '' : undefined}>
           {value ? <Tag size={size} color={nativeTagVariant} className="shrink-0 relative z-10 pointer-events-none">{label}</Tag> : <span className="text-fg-muted">{placeholder ?? '選擇...'}</span>}
           {selectEl}
@@ -440,8 +466,8 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
     }
 
     return (
-      <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
-        error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
+      <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
+        className)}
         data-field-mode="edit" data-error={error ? '' : undefined}>
         {StartIcon && <ItemPrefix><StartIcon size={iconSize} className="text-fg-muted pointer-events-none" aria-hidden /></ItemPrefix>}
         {!StartIcon && SelectedOptIcon && value && <ItemPrefix><SelectedOptIcon size={iconSize} className="pointer-events-none" aria-hidden /></ItemPrefix>}
@@ -458,7 +484,7 @@ NativeSelect.displayName = 'NativeSelect'
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
-  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, searchable = false, loading, minRows, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, 'aria-label': ariaLabel }, ref) => {
+  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = 'plain', startIcon: StartIcon, searchable = false, loading, minRows, emptyText, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, 'aria-label': ariaLabel }, ref) => {
     const fieldCtx = useFieldContext()
     const error = useResolvedFieldInvalid(errorProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
@@ -482,6 +508,12 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     const [open, setOpen] = React.useState(defaultOpen)
     const [search, setSearch] = React.useState('')
     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 穩定)。
+    const listboxId = React.useId()
+    // a11y(2026-07-05 D4):追蹤 cmdk active item id → searchable trigger input 綁 aria-activedescendant
+    // (機制詳 select-menu.tsx useActiveDescendant docblock;必在 early return 前呼叫 — React #310 hook 順序)。
+    const activeOptionId = useActiveDescendant(listboxId, open)
 
     // 關閉時清搜尋
     React.useEffect(() => { if (!open) setSearch('') }, [open])
@@ -569,6 +601,9 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         search={search}
         setSearch={setSearch}
         inputRef={inputRef}
+        activeDescendantId={activeOptionId}
+        ariaLabel={ariaLabel}
+        labelId={fieldCtx?.labelId}
         selectedItemRenderer={selectedItemRenderer}
       />
     )
@@ -582,20 +617,22 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         role="combobox"
         aria-expanded={open}
         aria-haspopup="listbox"
+        aria-controls={listboxId}
         aria-label={ariaLabel}
+        // a11y(2026-07-04):div-based role=combobox 的 <label for> 無效,接 FieldLabel labelId
+        // (field-context.ts labelId jsDoc 明文);consumer aria-label 優先(對齊 slider.tsx:166 guard canonical)。
+        aria-labelledby={ariaLabel ? undefined : fieldCtx?.labelId}
         aria-invalid={error || undefined}
         aria-required={fieldCtx?.required || undefined}
         aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
         aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
         tabIndex={0}
         className={cn(
-          fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
+          fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
           !isTextDisplay && value && !searchable && tagPadding[size],
           // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
-          // state machine `data-[state=open]:border-border-hover`(灰深)處理 open;若 trigger focused
-          // (Radix focus on open),focus-within:!border-primary 強制勝出顯藍。focus dominates everything
-          // 全 DS 一致(Material/Polaris/Ant 共識),改 Field default 一處全 control 自動跟動。
-          error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'],
+          // state machine `data-[state=open]:border-border-hover`(灰深)處理 open。
+          // 2026-07-04 Q1:error border 同樣收進 fieldWrapperStyles error variant(error 勝 focus 色)。
           'cursor-pointer',
           className,
         )}
@@ -603,6 +640,9 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         data-field-mode="edit"
         data-error={error ? '' : undefined}
         onKeyDown={(e) => {
+          // 2026-07-05 D4 P0:open 後 ArrowUp/Down/Enter 轉送 cmdk root(見 select-menu.tsx
+          // forwardKeyToListbox docblock — 原「open 後不攔讓方向鍵導覽」在跨 DOM 子樹機制上不成立)
+          if (open && forwardKeyToListbox(listboxId, e)) return
           if (e.key === 'Enter' || e.key === ' ') {
             // 2026-06-11 P0 a11y(R2 deep-audit):原 guard `!searchable` 連「關閉時的鍵盤開啟」一起擋
             // → searchable Select / PeoplePicker single 鍵盤打不開(WCAG 2.1.1)。原意只是開啟後
@@ -628,10 +668,12 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         onValueChange={handleValueChange}
         searchable={false}
         loading={loading}
+        emptyText={emptyText}
         size={size}
         minRows={minRows}
         open={open}
         onOpenChange={(o) => { setOpen(o); onOpenChange?.(o) }}
+        contentId={listboxId}
         renderLabel={renderLabel}
         onOpenAutoFocus={searchable ? (e) => { e.preventDefault(); inputRef.current?.focus() } : undefined}
       >
@@ -668,7 +710,8 @@ export const selectMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — trigger 走 Field chrome、menu row 走 MenuItem(其 meta 無 active)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: ['text-fg-disabled', 'text-fg-muted'],

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

@@ -806,7 +806,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- 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- 字母鍵 — 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>
     </div>
   ),
 }

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

@@ -13,7 +13,7 @@ type Story = StoryObj
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

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

@@ -29,14 +29,14 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式:value 軸走 `value` + `onValueChange`(型別宣告 optional、無 runtime 強制,但 internal 消費者 Select / Combobox / PeoplePicker 一律傳入),不支援 `defaultValue` uncontrolled fallback。
+本元件刻意採 **controlled-only** 模式——**scope 限 value 軸**:value 軸走 `value` + `onValueChange`(型別宣告 optional、無 runtime 強制,但 internal 消費者 Select / Combobox / PeoplePicker 一律傳入),不支援 `defaultValue` uncontrolled fallback。open 軸自 2026-06-11 R2 起走 `useControllable` dual-mode(`open` + `defaultOpen` + `onOpenChange`,`select-menu.tsx:162-166`),不在 controlled-only 範圍。
 
 **為什麼**:
 - 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
 - Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
 - 世界級對照:Ant Design DatePicker(`value`「To set date」+ `defaultValue`「To set default date」,ant.design/components/date-picker)/ Material MUI Select(`value` controlled + `defaultValue`「Use when the component is not controlled」,mui.com/material-ui/api/select/)/ Radix Select(「Can be controlled or uncontrolled」`value`+`defaultValue`,radix-ui.com/primitives/docs/components/select)皆支援 dual-mode;我們選 controlled-only 對齊狀態一致性優先 <!-- @benchmark-cited: 2026-05-30 WebFetch 三家 API 實證 value+defaultValue dual-mode(MUI Select API / Ant DatePicker API / Radix Select),URL inline -->
 
-**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
+**若未來 value 軸要改 dual-mode**:DS 已有 `useControllable` helper(open 軸與 Select 皆已消費),另需測試 controlled↔uncontrolled switch 場景,屬 major API 擴充。
 
 ---
 
@@ -93,7 +93,7 @@ Popover（浮動容器，handle 展開 / 定位）
 
 ## Creatable（建立新選項）
 
-透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」;`select-menu.tsx:219-224`)——完全同名時自動隱藏,防重複建立。
+透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」;`select-menu.tsx:230-235`)——完全同名時自動隱藏,防重複建立。
 
 **何時啟用**：
 - Tag input 允許使用者建立新 tag
@@ -126,6 +126,7 @@ Popover（浮動容器，handle 展開 / 定位）
 
 - **Creatable 時**：即使搜尋無結果，仍顯示 create row 讓使用者補建選項（顯示條件見「Creatable」段）
 - **非 creatable**：顯示 emptyText 提示使用者修改搜尋詞
+- **SR 播報**（2026-07-05 D4）：empty / loading 空狀態同步經 visually-hidden `role="status"` + `aria-live="polite"` live region 播報（cmdk CommandEmpty 是 `role="presentation"`，SR 使用者原本聽不到 0 結果；對齊 `empty.spec.md`「動態 filter no-results 容器需 `aria-live="polite"`」+ react-select A11yText）。SSOT 在 SelectMenu 一處，Select / Combobox / PeoplePicker 全體受益。
 
 ---
 
@@ -134,7 +135,7 @@ Popover（浮動容器，handle 展開 / 定位）
 非同步載入選項時，consumer 透過 `loading={true}` 控制：
 
 - **Trigger 不變**：dropdown 隨時可開（user 看 chevron 不會被 disable）
-- **Dropdown 開啟時**：options 替換為 panel-center `<Empty icon={<CircularProgress size={48}/>} className="py-6"/>` compose 視覺（純 spinner，無 description）
+- **Dropdown 開啟時**（2026-07-04 Q3 拍板措辭修訂）：spinner 只在**無可顯示選項時**佔 empty slot，渲 panel-center `<Empty icon={<CircularProgress size={48}/>} className="py-6"/>`（cmdk `CommandEmpty` 機制）；**已有 options 時保留顯示不清空**（MUI Autocomplete 官方「only if there are no suggestions to show」共識）
 - **CircularProgress 預設 24px**，但在 Empty wrapper 內 48px（取代 Empty 的 48px Avatar icon slot）
 
 對齊 MUI Autocomplete loading dropdown-body + Ant Select loading idiom + DS `empty.spec.md`「禁止事項」段「loading 用 Empty + CircularProgress compose」SSOT（SelectMenu loading 用法 canonical row 見 `empty.spec.md`「現有消費者」表）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
@@ -157,11 +158,12 @@ Popover（浮動容器，handle 展開 / 定位）
 
 - **Disabled option**:individual MenuItem 透過 `disabled?: boolean` 控制(SelectMenu primitive option contract)。視覺繼承 `MenuItem` SSOT:text → `text-fg-disabled`(M24)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onChange、鍵盤導覽自動 skip。
 - **Disabled trigger**:trigger 由 consumer(Select / Combobox / PeoplePicker)的 `disabled` prop own,本元件不獨立 disable trigger。
-- **Loading**:已 codify(見「Loading」段),`loading=true` 時 dropdown body 切 panel-center Empty + CircularProgress 48px。
+- **Loading**:已 codify(見「Loading」段),`loading=true` 且無可顯示選項時 empty slot 渲 panel-center Empty + CircularProgress 48px(stale options 保留)。
 - **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留 create row(可鍵盤選取)。
-- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:219-224`);選取既有選項為唯一路徑。
+- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:230-235`);選取既有選項為唯一路徑。
 - **Dark mode**:走 Popover / MenuItem semantic token 自動 adapt。
 - **Density**:row height 由 `MenuItem` SSOT 控(sm/md/lg);SelectMenu 不獨立 own density。
+- **大量選項(> 100)**:建議上游分頁 / 搜尋收斂或考慮 windowing(對齊 Ant Select / MUI Autocomplete 慣例);本元件無虛擬化。
 
 ---
 
@@ -177,7 +179,7 @@ SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
 
 ## shadcn passthrough 例外說明
 
-SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:122-126` rationale):
+SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:127-130` rationale):
 
 - **沒有單一 DOM root 可 ref**:trigger / search input / list / content portal 各自 DOM tree 離散
 - **`...props` spread 目標不明**:composite 的 root wrapper 只是 control 容器,spread 到那裡 consumer 無從預期作用
@@ -203,7 +205,7 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 ## A11y 預設
 
-**ARIA / Pattern**:基於 `cmdk` library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。
+**ARIA / Pattern**:基於 `cmdk` library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。選項 row 的內層 `MenuItem` 傳 `role="presentation"`(cmdk CommandItem 是唯一 option 節點,避免 option 巢狀 option + 內外 `aria-selected` 語意相反;鏡射 DropdownMenu canonical,2026-07-05 D4)。分組標題走 cmdk `CommandGroup heading`(自動產 `cmdk-group-heading` id,選項容器 `role="group"` + `aria-labelledby` 指向之,AT 可感知);combobox accessible name 來自 `Command label`(= `searchPlaceholder`,僅 searchable 時傳),listbox 容器經 cmdk `List label` 預設「選項」取代 cmdk 內建英文 "Suggestions"(2026-07-06)。多選 footer 全選列為 `role="checkbox"` + `aria-checked`(indeterminate → `"mixed"`)。空狀態 / loading 經 visually-hidden `role="status"` + `aria-live="polite"` live region 對 SR 播報(cmdk CommandEmpty 是 `role="presentation"`,SR 原本聽不到;2026-07-05 D4)。
 
 **Keyboard 行為**:
 
@@ -212,6 +214,8 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 - ↑/↓ — 導覽 options(menu 開啟後)
 - Enter — 選擇
 - 字母鍵 — type-ahead 過濾(search 模式)
+- Tab(menu 開啟 + multi 模式)— DOM focus 移到 footer 全選列(`tabIndex=0`;全選列在 CommandList 之外、非 cmdk-item,cmdk 方向鍵導覽不涵蓋,故走 DOM focus。2026-07-05 D4 鍵盤可達修)
+- Enter / Space(focus 在全選列)— 切換全選 / 全清(handler `preventDefault`,cmdk root onKeyDown 檢查 defaultPrevented 故不會重複觸發 active option)
 - 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。