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

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

@@ -0,0 +1,106 @@
+// @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.
+// v3 canonical(2026-05-01):≥ 2 stories(UsageGuidance + CompositionRules)取代原
+// escape rationale,對齊 Polaris/Material/Ant 共識 internal primitive 仍應教 consumer pattern。
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+
+const meta: Meta = {
+  title: 'Design System/Internal/SelectMenu/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 SelectMenu 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="單選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">議題狀態欄位擇一指派(單選)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">數百人組織選負責人,輸入過濾(搜尋)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">工單同時貼多個標籤(多選)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選 + 搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">大量標籤庫中過濾並複選(多選 + 搜尋)</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <div className="prose prose-sm max-w-prose">
+          <p>SelectMenu 是 Internal primitive,被 Select / Combobox / PeoplePicker 消費。直接使用前先確認:</p>
+          <ul>
+            <li>結果寫回 form value(讀取已選)→ 透過 Select / Combobox 等 user-facing 元件消費,不直接用 SelectMenu</li>
+            <li>結果觸發某個 action(non-form)→ 用 Command 而不是 SelectMenu</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <div className="prose prose-sm max-w-prose">
+          <p>SelectMenu vs Command — 兩者都 keyboard-navigable + 搜尋,但 mental model 不同:</p>
+          <ul>
+            <li><strong>SelectMenu(本元件)</strong>—form-input dropdown;結果寫回 form value(read selected)</li>
+            <li><strong>Command</strong>—命令面板;結果是執行某 action(non-form)</li>
+          </ul>
+          <p className="text-fg-muted">判斷:結果回 form value → SelectMenu;結果觸發 action → Command。</p>
+        </div>
+      </Section>
+    </div>
+  ),
+}
+
+// ── CompositionRules — SelectMenu 三個 consumer pattern(對齊 Material Select / Polaris Combobox idiom)──────
+
+export const CompositionRules: Story = {
+  name: '組合規則',
+  render: () => (
+    <div>
+      <Section title="Pattern 1 — Select(static 單選 dropdown)">
+        <div className="prose prose-sm max-w-prose">
+          <p>已知選項清單 + 單選回 form → <LinkTo kind="Design System/Components/Select/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Select</span></LinkTo>(內部 SelectMenu + cmdk + MenuItem)。對齊 Material <code>Select</code> / Ant <code>Select</code> idiom。</p>
+          <ul>
+            <li>典型場景:Country picker / Status selector / Priority dropdown</li>
+            <li>判斷:選項 ≤ 20 + 不需搜尋 → Select(可選 searchable mode 啟用搜尋)</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="Pattern 2 — Combobox(多選 + 搜尋 + 可建立新值)">
+        <div className="prose prose-sm max-w-prose">
+          <p>多選 + 大量選項需搜尋 + 可創新 tag → <LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Combobox</span></LinkTo>。對齊 GitHub Label picker / Linear Multi-assignee / Notion Multi-select idiom。</p>
+          <ul>
+            <li>典型場景:Tag picker / Multi-assignee / Filter chips multi-value</li>
+            <li>單行模式自動接 OverflowIndicator(`+N`)避免 tag wrap</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="Pattern 3 — PeoplePicker(人員選擇 + Avatar 渲染)">
+        <div className="prose prose-sm max-w-prose">
+          <p>選人員(單 / 多)+ 渲染 avatar + 名稱 + role → <LinkTo kind="Design System/Components/PeoplePicker/展示" name="單人"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">PeoplePicker</span></LinkTo>。對齊 Slack mention / Linear assignee / Asana people-search idiom。</p>
+          <ul>
+            <li>典型場景:Task assignee / Document collaborator / Workspace member invite</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="禁止 — App code 直接消費 SelectMenu">
+        <div className="prose prose-sm max-w-prose">
+          <p>不可直接 <code>import &#123; SelectMenu &#125; from '@/design-system/...'</code> 在 app — 必透過 Select / Combobox / PeoplePicker 三個 user-facing wrapper 之一。如有特殊 dropdown 需求(這 3 個都不對),回 DS 開新 wrapper 而不是繞過抽象層。</p>
+        </div>
+      </Section>
+    </div>
+  ),
+}

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

@@ -1,6 +1,6 @@
 ---
 component: SelectMenu
-family: 4
+family: composite # 2026-07-14 修自我矛盾:原 Phase-1 mechanical 填 4,與 body「Layout Family:非上述 family — composite / multi-section」矛盾;Family 4 是 trigger 側 field control(Select / Combobox)的事
 variants: {}
 sizes: {}
 traits:
@@ -9,10 +9,10 @@ traits:
 benchmark:
   - Polaris Listbox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Listbox
   - Radix Select primitive: github.com/radix-ui/primitives/tree/main/packages/react/select
+  - MUI Material Select (controlled/uncontrolled API): mui.com/material-ui/api/select/
+  - Ant Design DatePicker (value/defaultValue API): ant.design/components/date-picker
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # SelectMenu 設計原則
 
 ## 定位
@@ -27,14 +27,14 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `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:187-191`),不在 controlled-only 範圍。
 
 **為什麼**:
 - 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
 - Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
-- 世界級對照:Ant Design DatePicker / Material MUI Select 皆支援 dual-mode;我們選 controlled-only 對齊狀態一致性優先 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- value 軸由外層選值元件持有；SelectMenu 不再建立第二份可漂移的 selection state，因此刻意不開 uncontrolled fallback
 
-**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
+**若未來 value 軸要改 dual-mode**:DS 已有 `useControllable` helper(open 軸與 Select 皆已消費),另需測試 controlled↔uncontrolled switch 場景,屬 major API 擴充。
 
 ---
 
@@ -52,9 +52,11 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 
 ### 消費者
 
-- `../PeoplePicker/people-picker.tsx` — 人員選擇（永遠 searchable）
-- `../Select/select.tsx` — `searchable` 模式會切換到 SelectMenu 浮層
-- `../Combobox/combobox.tsx` — `searchable` 模式會切換到 SelectMenu 浮層
+- `../Select/select.tsx` — `searchable` 模式會切換到 SelectMenu 浮層（直接 import）
+- `../Combobox/combobox.tsx` — `searchable` 模式會切換到 SelectMenu 浮層（直接 import）
+- `../PeoplePicker/people-picker.tsx` — 人員選擇（永遠 searchable;**間接消費** — wrap Select / Combobox,不直接 import SelectMenu,見 `people-picker.spec.md`「實作基礎」）
+
+**常見誤解**:(1)「要下拉浮層就 import SelectMenu」— internal primitive,一律經 Select / Combobox / PeoplePicker 消費(見上表);(2)「SelectMenu = DropdownMenu」— SelectMenu 是**選值**(值留在 field),DropdownMenu 是**執行動作**(點完即關)— 分界 SSOT 見 `dropdown-menu.spec.md`「與 SelectMenu 的區別」。
 
 ---
 
@@ -63,7 +65,7 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 ```
 Popover（浮動容器，handle 展開 / 定位）
   └─ Command（cmdk — 搜尋 + 鍵盤導覽）
-       ├─ CommandInput（搜尋框，選項 > 5 時顯示）
+       ├─ 搜尋框（`CommandPrimitive.Input` raw cmdk + 自建 icon/min-h wrapper，非 DS `CommandInput`；searchable 模式時顯示；選項 > 5 時建議開啟）
        ├─ CommandList（捲動區）
        │    └─ CommandGroup（分組標題）
        │         └─ MenuItem（選項 row，消費 item-layout）
@@ -72,24 +74,24 @@ Popover（浮動容器，handle 展開 / 定位）
 
 **定位**:SelectMenu 的 `sideOffset` 與 `align` 直接走 Popover canonical——`sideOffset=8` / `align` 跟隨 trigger 位置(見 `../Popover/popover.spec.md`「Align 對齊 canonical(跨浮層 SSOT)」)。SelectMenu 不自訂浮層定位規則。
 
-**視覺 vs 語意**(2026-04-20 精緻化):SelectMenu 的 **width 預設跟 trigger(input)同寬**(Radix trigger-width),此時 `start` / `center` / `end` 三種 align 呈現視覺完全相同(popover 正好跟 input 貼合,左右邊緣對齊無差異)。但當 consumer 傳 `minWidth` 大於 input 寬度(例:長 option label 要空間展示)、或 option 內容撐開導致 popover 寬於 trigger,**align 的視覺差異立刻顯現**——此時嚴格照 structured overlay canonical(trigger 在左 → start / 中 → center / 右 → end)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**視覺 vs 語意**(2026-04-20 精緻化):SelectMenu 的預設 `min-width = max(trigger width, 240px)`；trigger ≥ 240px 時與 trigger 同寬，較窄 trigger 會擴至 240px。寬度相等時 `start` / `end` 兩種 align 呈現視覺相同；popover 寬於 trigger 時，align 差異才會顯現，並嚴格遵守 structured overlay canonical(trigger 在左 → start / 右 → end)。(SelectMenu `align` prop 僅暴露 `'start' | 'end'`,不開放底層的 `center`。)
 
-換言之 SelectMenu **永遠照 canonical**,只是大多數情況 width=trigger-width 讓 canonical 視覺上被 mask,一旦 popover 突破 trigger 寬度 canonical 立刻生效。規則沒例外,只是呈現條件。
+換言之 SelectMenu **永遠照 canonical**；只有 trigger ≥ 240px 且未再提高 `minWidth` 時，等寬會讓 align 差異被視覺遮蔽。一旦 popover 寬於 trigger，canonical 立即顯現。
 
 ---
 
 ## 單選 vs 多選
 
-透過 `value` / `onValueChange` 的類型決定：
+透過 `multiple` prop 決定（`value` 型別只被 normalize 成內部 `selectedValues`，不參與模式判斷）：
 
-- **單選**：`value: string | null`，選中後立即關閉浮層
-- **多選**：`value: string[]`，選中不關閉，可繼續選（footer 可顯示全選 checkbox）
+- **單選**（`multiple={false}`，預設）：`value: string | null`，選中後立即關閉浮層
+- **多選**（`multiple={true}`）：`value: string[]`，選中不關閉，可繼續選（footer 可顯示全選 checkbox）
 
 ---
 
 ## Creatable（建立新選項）
 
-透過 `onCreate` prop 啟用。搜尋無結果時顯示「建立 "xxx"」提示（`Plus` icon + 使用者輸入的字）。
+透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」,`select-menu.tsx:164`;顯示/隱藏判斷 `:261-266`,render `:471-495`)——完全同名時自動隱藏,防重複建立。
 
 **何時啟用**：
 - Tag input 允許使用者建立新 tag
@@ -118,10 +120,11 @@ Popover（浮動容器，handle 展開 / 定位）
 
 ## Empty state
 
-搜尋無結果時顯示 `Empty` 元件，可透過 `emptyText` 自訂訊息（預設「無符合的選項」）。
+搜尋無結果時顯示 `Empty` 元件，可透過 `emptyText` 自訂訊息（預設「沒有符合的選項」）。
 
-- **Creatable 時**：即使搜尋無結果，仍顯示「建立 "xxx"」讓使用者補建選項
+- **Creatable 時**：即使搜尋無結果，仍顯示 create row 讓使用者補建選項（顯示條件見「Creatable」段）
 - **非 creatable**：顯示 emptyText 提示使用者修改搜尋詞
+- **SR 播報**（2026-07-05 D4）：empty 結果經 visually-hidden `role="status"` + `aria-live="polite"` live region 播報（cmdk CommandEmpty 是 `role="presentation"`，SR 使用者原本聽不到 0 結果）；loading 則由畫面內具 `aria-label="載入選項中"` 的 `role="status"` wrapper 播報，避免雙重 announcement。SSOT 在 SelectMenu 一處，Select / Combobox / PeoplePicker 全體受益。
 
 ---
 
@@ -130,12 +133,12 @@ Popover（浮動容器，handle 展開 / 定位）
 非同步載入選項時，consumer 透過 `loading={true}` 控制：
 
 - **Trigger 不變**：dropdown 隨時可開（user 看 chevron 不會被 disable）
-- **Dropdown 開啟時**：options 替換為 panel-center `<Empty icon={<CircularProgress size={48}/>} description={loadingText}/>` compose 視覺
-- **CircularProgress 預設 24px**，但在 Empty wrapper 內 48px（取代 Empty 的 48px Avatar icon slot）
+- **Dropdown 開啟時**（2026-07-04 Q3 拍板措辭修訂）：spinner 只在**無可顯示選項時**佔 empty slot，渲 panel-center `<div role="status" aria-label="載入選項中" className="flex items-center justify-center py-6"><CircularProgress size={48}/></div>`（cmdk `CommandEmpty` 機制）；**已有 options 時保留顯示不清空**，避免背景更新期間抹掉仍可用的 stale results
+- **CircularProgress** 使用 48px;named status wrapper own `py-6` 與置中，不經 Empty，避免把「正在載入」誤表達成「確定沒有」及 phantom icon gap
 
-對齊 MUI Autocomplete `loadingText` dropdown-body + Ant Select loading idiom + DS `empty.spec.md:182`「全頁 loading = Empty + CircularProgress compose」SSOT。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+本行為對齊 DS `empty.spec.md`「禁止事項」spinner-only loading 不用 Empty 的 SSOT（SelectMenu loading 用法 canonical row 見 `empty.spec.md`「現有消費者」表）。
 
-**消費**：Select / Combobox / PeoplePicker forward `loading` prop 到 SelectMenu，本元件不需 consumer 直接知道 Empty + CircularProgress 組合（封裝在內）。
+**消費**：Select / Combobox forward `loading` prop 到 SelectMenu（PeoplePicker 尚未暴露 / 轉發 `loading`，見 `people-picker.spec.md`「邊界案例」），本元件封裝 named status + CircularProgress 組合。
 
 ---
 
@@ -153,18 +156,24 @@ 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。
-- **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留「建立 "xxx"」row。
+- **Loading**:已 codify(見「Loading」段),`loading=true` 且無可顯示選項時 empty slot 渲 panel-center named status + CircularProgress 48px(stale options 保留)。
+- **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留 create row(可鍵盤選取)。
+- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:261-266`);選取既有選項為唯一路徑。
 - **Dark mode**:走 Popover / MenuItem semantic token 自動 adapt。
 - **Density**:row height 由 `MenuItem` SSOT 控(sm/md/lg);SelectMenu 不獨立 own density。
+- **大量選項(> 100)**:建議上游分頁 / 搜尋收斂或考慮 windowing(對齊 Ant Select / MUI Autocomplete 慣例);本元件無虛擬化。
 
 ---
 
 ## 為何無 ColorMatrix
 
-SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
+SelectMenu 是**多區塊 composite primitive**,色彩全數消費 DS semantic token、不新增 token;但 2026-07-05 D4 後互動色的 **owner 分層**如下(修正舊述「視覺完全繼承內層 primitive」):
+
+- **surface / border / elevation**:`PopoverContent` 自設 `bg-surface-raised` + `border-border` + `--elevation-200`(`select-menu.tsx:308-320`)。
+- **hover / selected 互動 bg**:owner 是**外層 cmdk `CommandItem`** —— 鍵盤 cursor base `bg-neutral-hover`(command.tsx `data-[selected=true]`)+ 單選 persistent selected `bg-neutral-selected`;**選中 × 疊加走 `item-anatomy.spec.md`「選中 × 互動疊加」格(2026-08-11)**:滑鼠 hover 釘住不變、鍵盤反白(非 :hover)深一階 `bg-neutral-selected-focus`(鏡射 DropdownMenu 同格)。
+- **內層 `MenuItem`**:強制 `!bg-transparent` 純視覺排版(`select-menu.tsx:460` 選項列 / `:489` create 列),不 own 互動 bg。
 
-- **無 ColorMatrix**:視覺完全繼承既有 DS primitive 的 token(`MenuItem` row / `Command` search / `Empty` layout / `Popover` surface),無自己的 bg / border / hover 決策。色彩漂移由 primitive layer 控制——SelectMenu 層級若加 ColorMatrix 會重複 MenuItem / Popover 的矩陣。
+**無 ColorMatrix 的理由不變**:上述全是既有 token family(`neutral-hover / neutral-selected / neutral-selected-focus`,與 DropdownMenu / MenuItem 同組),SelectMenu 不擁有獨立色彩決策;加 ColorMatrix 只會重複 MenuItem / DropdownMenu / Popover 的矩陣。
 
 對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix` / `StateBehavior`,額外追加元件特有的 `ModeMatrix`(single / multi / searchable / creatable / grouped 等功能組合矩陣,這是 SelectMenu 真正的決策面向——取代 ColorMatrix)。
 
@@ -172,11 +181,12 @@ SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
 
 ## shadcn passthrough 例外說明
 
-SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**不套 `forwardRef` / `...props` spread`**,同 PeoplePicker 理由:
+SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:151-154` rationale):
 
 - **沒有單一 DOM root 可 ref**:trigger / search input / list / content portal 各自 DOM tree 離散
 - **`...props` spread 目標不明**:composite 的 root wrapper 只是 control 容器,spread 到那裡 consumer 無從預期作用
-- **API 邊界明確**:SelectMenu 暴露「選值」語意(value / onChange / options / mode),不暴露 DOM 細節
+- **API 邊界明確**:SelectMenu 暴露「選值」語意(value / onValueChange / options / mode),不暴露 DOM 細節
+- **`className` 合併到 PopoverContent**(contextually 最接近 user-facing surface)
 
 `displayName = 'SelectMenu'` 保留。若 consumer 需要 DOM-level 控制(custom trigger / portal / search input ref),改用底層 Popover + Command 自組。
 
@@ -184,6 +194,10 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 ---
 
+## Option schema 增項紀錄
+
+- `iconClassName?`(2026-07-08):option icon 染色通道(status 類彩色選項;WM 戰役——原窄 schema 逼 consumer 手刻 bare trigger)。disabled 色仍勝出(menu-item.tsx 順序保證)。
+
 ## 相關
 
 - `../Menu/menu-item.spec.md` — 選項 row 的 item-layout 共用規則（SelectMenu 消費 MenuItem）
@@ -197,18 +211,20 @@ 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`(= `searchAriaLabel`,default「搜尋選項」,僅 searchable 時傳)，與可見 `searchPlaceholder` 分離；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 行為**:
 
 - Tab — focus trigger
-- Enter / Space / ↓ — 開啟 menu
-- ↑/↓ — 導覽 options
+- 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 — 選擇
 - 字母鍵 — 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 開啟時 focus 第一 option / 選中項;關閉時 focus 回 trigger。
+**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。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -218,3 +234,6 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 - `command.spec.md`
 - `dropdown-menu.spec.md`
+- `menu-item.spec.md`
+- `popover.spec.md`
+- `select.spec.md`

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

@@ -0,0 +1,143 @@
+// @story-history: isInputLike trait — SelectMenu(internal,Select/Combobox 觸發)的 error state 由 Select.stories.tsx + Combobox.stories.tsx WithError 覆蓋(SelectMenu 是 internal popover surface,不直接 own input state)。AllSizes 同理 retired(anatomy auto-compile SizeMatrix owns)per F migration 2026-05-15。
+import type { Meta, StoryObj } from '@storybook/react'
+import React, { useState } from 'react'
+import { Select } from '@/design-system/components/Select/select'
+import { Combobox } from '@/design-system/components/Combobox/combobox'
+
+const meta: Meta = {
+  title: 'Design System/Internal/SelectMenu/展示',
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+// ── 單選（Select 觸發）──
+
+const statusOptions = [
+  { value: 'in_stock', label: 'In stock' },
+  { value: 'low_stock', label: 'Low stock' },
+  { value: 'out_of_stock', label: 'Out of stock' },
+]
+
+const SingleSelectDemo = () => {
+  const [value, setValue] = useState<string>('in_stock')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-muted">Select 作為觸發點，點擊開啟 SelectMenu</p>
+      <Select options={statusOptions} value={value} onChange={setValue} aria-label="狀態(SelectMenu single-select demo)" />
+    </div>
+  )
+}
+
+export const SingleSelect: StoryObj = {
+  name: '單選',
+  render: () => <SingleSelectDemo />,
+}
+
+// ── 單選 + 搜尋 ──
+
+const countries = [
+  { value: 'tw', label: '台灣' }, { value: 'jp', label: '日本' },
+  { value: 'us', label: '美國' }, { value: 'gb', label: '英國' },
+  { value: 'de', label: '德國' }, { value: 'fr', label: '法國' },
+  { value: 'kr', label: '韓國' }, { value: 'sg', label: '新加坡' },
+  { value: 'au', label: '澳洲' }, { value: 'ca', label: '加拿大' },
+]
+
+const SearchableDemo = () => {
+  const [value, setValue] = useState<string>('')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-muted">searchable — 觸發點變 input，打字即篩選</p>
+      <Select options={countries} value={value} onChange={setValue} searchable clearable placeholder="選擇國家…" />
+    </div>
+  )
+}
+
+export const Searchable: StoryObj = {
+  name: '搜尋',
+  render: () => <SearchableDemo />,
+}
+
+// ── 多選 ──
+
+const categoryOptions = [
+  { value: 'electronics', label: 'Electronics' },
+  { value: 'furniture', label: 'Furniture' },
+  { value: 'food', label: 'Food' },
+  { value: 'lifestyle', label: 'Lifestyle' },
+]
+
+const MultiSelectDemo = () => {
+  const [value, setValue] = useState<string[]>(['electronics'])
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <p className="text-caption text-fg-muted">Combobox — checkbox 多選，浮層不關閉</p>
+      <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="商品分類(SelectMenu multi-select demo)" />
+    </div>
+  )
+}
+
+export const MultiSelect: StoryObj = {
+  name: '多選',
+  render: () => <MultiSelectDemo />,
+}
+
+// ── 多選 + 搜尋 ──
+
+const MultiSearchDemo = () => {
+  const [value, setValue] = useState<string[]>([])
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <p className="text-caption text-fg-muted">searchable — 浮層內搜尋框，關鍵字保留可連續勾選</p>
+      <Combobox options={countries} value={value} onChange={setValue} searchable aria-label="國家(SelectMenu multi-select + search demo)" />
+    </div>
+  )
+}
+
+export const MultiSearchable: StoryObj = {
+  name: '多選 + 搜尋',
+  render: () => <MultiSearchDemo />,
+}
+
+// @story-history: 原 Clearable(可清除)retired 2026-07-17(Dim 25 earn-existence)—
+//   該 story 實際 render `<Select clearable>`,clearable 是 Select trigger/field state 的 API(spec
+//   L45/L53/L160 明定 trigger state 由外層 Select/Combobox own,SelectMenu 本身無此 prop),
+//   且 Select.stories.tsx「可清除」已 own 此 canonical。SelectMenu 展示層只保留浮層自身能力
+//   (搜尋 / 多選 / creatable / 選項狀態),不重演 wrapper 的 field feature。principles 頁對應 LinkTo 同步移除。
+// @story-history: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
+// @story-history: 原 States(edit/readonly/disabled/error 觸發器狀態)retired 2026-06-11 —
+//   trigger field state 由 Select.stories.tsx「四模式」owns(SelectMenu 是 internal popover surface,
+//   不 own input state,見檔頭 rationale)。本層改示範浮層自己 own 的選項狀態。
+// ── 選項狀態(浮層內)──
+
+const assigneeOptions = [
+  { value: 'ada', label: 'Ada Chen', description: 'Design Engineer' },
+  { value: 'ben', label: 'Ben Liu', description: 'Frontend' },
+  { value: 'cindy', label: 'Cindy Wang', description: '休假中,暫不可指派', disabled: true },
+  { value: 'derek', label: 'Derek Kao', description: 'Backend' },
+]
+
+const OptionStatesDemo = () => {
+  const [value, setValue] = React.useState<string>('ada')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-secondary">
+        浮層內選項狀態 — 已選中(勾選標記)、disabled(休假成員不可選)、搜尋無結果(輸入不存在的名字)
+      </p>
+      <Select
+        options={assigneeOptions}
+        value={value}
+        onChange={setValue}
+        searchable
+        placeholder="指派負責人…"
+        aria-label="指派負責人(SelectMenu option-states demo)"
+      />
+    </div>
+  )
+}
+
+export const OptionStates: StoryObj = {
+  name: '選項狀態',
+  render: () => <OptionStatesDemo />,
+}