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

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

@@ -0,0 +1,299 @@
+---
+component: Select
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Radix Select primitive: github.com/radix-ui/primitives/tree/main/packages/react/select
+  - Ant Design Select: github.com/ant-design/ant-design/tree/master/components/select
+  - MUI Select: github.com/mui/material-ui/tree/master/packages/mui-material/src/Select
+  - Polaris Select: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Select
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Select 設計原則
+
+## 定位
+
+Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個，選項收在 dropdown 內展開。底層走原生 `<select>`，透過 CSS 客製視覺。
+
+共用規則見 `field-controls.spec.md`。本文件只記錄 Select 特有的原則。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+---
+
+## Controlled / Uncontrolled dual-mode(Dim 26,2026-05-21 D3 audit ship)
+
+本元件支援 **dual-mode**:consumer 可選 controlled OR uncontrolled,對齊 React `<input>` / Radix Select / shadcn Select 共識。**互斥規則**:同時傳 `value` + `defaultValue` 走 controlled(value 勝),`defaultValue` 僅 first-mount 用。
+
+### Controlled 模式(consumer 自管 state)
+
+傳 `value` + `onChange`,Select **不**自管 state:
+
+```tsx
+const [country, setCountry] = useState('tw')
+<Select value={country} onChange={setCountry} options={...} />
+```
+
+**何時用**:Form library(react-hook-form / Formik)/ Redux / 跨元件 sync / server-state driven。
+
+### Uncontrolled 模式(Select 自管 state)
+
+不傳 `value`(可傳 `defaultValue` 設初始值),Select 內部 `useState`,變更時 fire `onChange` callback 通知 consumer:
+
+```tsx
+<Select defaultValue="tw" onChange={(v) => console.log('changed:', v)} options={...} />
+```
+
+**何時用**:純展示 / 一次性表單 submit / consumer 不需要 read 當前值。
+
+### 為什麼支援 dual-mode(非 controlled-only)
+
+- **React canonical**:`<input>` / `<select>` 原生兩模式並存,Radix / shadcn / MUI / Ant 共識 form-like primitive 必支援 dual-mode
+- **Consumer ergonomics**:簡單場景不該強制管 state(prototype / 一次性 form / a11y testing)
+- **互斥規則消除 ambiguity**:`value !== undefined` 為 controlled signal,decisive 不模糊
+
+### 歷史
+
+- **2026-05-21 前**:刻意 controlled-only,理由「內部狀態複雜易 race」
+- **2026-05-21 D3 audit**:per Phase A deep audit Dim 26 verify + user verbatim「決策三照妳建議」+「都給我做到好」→ 補 `defaultValue` + `useState` internal state + 互斥 signal。實作:`select.tsx:L443 isControlled = valueProp !== undefined` + `internalValue` state + `handleValueChange` 內 `if (!isControlled) setInternalValue(v)`
+
+---
+
+## 何時用
+
+- **表單中節省垂直空間**：create user 的 role、profile settings 的 timezone、product form 的 category
+- **Toolbar / filter 的選擇**：table 上方的 category filter、sort by、狀態篩選
+- **Table cell 的 inline edit**：Jira-style task 的 status / priority / assignee（見下文「即時 vs on-submit」）
+- **選項 label 自帶語意**：國家、類別、時區——使用者看 label 就知道要選什麼，不需要額外 description
+- **選項 10+ 且不需搜尋**：時區、國家這類使用者熟悉的清單，依賴 native select 的 type-to-jump 快速定位
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 2-5 個選項且選擇是「決策節點」 | `RadioGroup` | 使用者需要看到全部選項比較——見下「與 RadioGroup 的分界」 |
+| 2-5 個緊湊切換（filter / view mode） | `SegmentedControl` | 更 compact，跟 Button / Input 並排不違和。詳見 `segmented-control.spec.md` |
+| 選項需要多行描述或圖文並列 | `RadioGroup` | Select option 是單行純文字，無法承載複雜排版 |
+| 多選 | `Combobox` | Select 永遠單選 |
+| 布林切換（on / off） | `Switch` | 布林不需要「選一個」的心智模型 |
+
+---
+
+## 與 RadioGroup 的分界
+
+兩者都能「從 N 個選項中挑一個」，在 2-5 個選項的範圍內常被誤用互換。判斷**不是數量**，而是以下三個角度——**任何一個明確傾向哪邊就選哪邊**：
+
+### 1. Progressive disclosure 成本
+
+- **Select**：選項隱藏，使用者多一次點擊才看到。適合「label 本身就夠清楚」的場景（國家、類別、角色）——使用者已經知道自己要選什麼，只是需要一個 picker
+- **RadioGroup**：全部選項一次可見。適合「使用者需要看完所有選項才能決定」——付款方式、訂閱方案、票種，選擇本身是決策動作
+
+### 2. 視覺重量
+
+- **Select**：O(1)——永遠佔 field height 一格空間，無論 3 個或 300 個選項
+- **RadioGroup**：O(n)——每個選項各佔一行（block 模式），總高度隨選項數線性增加。超過 5 個 option 會開始主導 form 的視覺節奏
+
+### 3. 評估深度
+
+- **Select**：使用者已經知道要選什麼，label 只是確認。例：我知道我要選「Electronics」，dropdown 只是找到它的工具
+- **RadioGroup**：使用者需要仔細讀每個選項的 label（有時連帶 description 比較價格 / 權限 / 時長），評估才做選擇
+
+### Fallback heuristic
+
+- **表單中要節省垂直空間 / label 自帶語意 / 使用者熟悉選項 → Select**
+- **選擇本身是決策節點（使用者需要對比評估） → RadioGroup**
+- **灰色地帶時，問：「使用者看一眼 label 就能下決定嗎？」** 能 → Select；不能、需要閱讀 → RadioGroup
+
+### 情境對照表
+
+| 場景 | 選哪個 | 原因 |
+|------|-------|------|
+| 國家 / 時區選擇 | Select（可配 searchable） | label 自帶語意、使用者熟悉、選項數多 |
+| Table cell 的 status 切換 | Select | 空間受限、使用者熟悉 status 名 |
+| 類別（Electronics / Furniture / Food）| Select 或 RadioGroup | 看容器空間；3-4 個且在 form 中傾向 RadioGroup |
+| **付款方式**（信用卡 / 轉帳 / 現金）| RadioGroup | 決策節點、通常連帶手續費或處理時間 description |
+| **訂閱方案**（Basic / Pro / Enterprise）| RadioGroup | 決策節點、通常連帶價格比較與 feature list |
+| **票種**（成人 / 兒童 / 敬老）| RadioGroup | 決策節點、通常連帶價格 |
+| 使用者角色（Admin / Editor / Viewer）| Select 或 RadioGroup | 新手用 RadioGroup（要解釋權限）、熟悉使用者 Select |
+| 時區選擇 | Select + searchable | 選項 > 100 個、使用者記得時區名 |
+
+**本節是 Select vs RadioGroup 的 SSOT**，`radio-group.spec.md` 和 `checkbox.spec.md` 點回本節，不重複書寫。
+
+---
+
+## 即時 vs on-submit
+
+Select 的值套用時機是**由 onChange handler 的副作用決定**，不是 Select 本身的屬性——兩種場景都是正當用法：
+
+### 即時套用（change → API）
+
+選值一變就直接觸發外部動作，不經 form submit：
+
+- **Jira-style view/edit**：task 的 status / priority / assignee 欄位，改了立刻寫回 DB
+- **篩選器**：table 上方的 category / status filter，改了立刻篩 table
+- **即時設定**：notification preference、theme dropdown
+- **URL param 綁定**：改 value 立刻 push URL（deep-linkable）
+
+這類場景的 onChange 通常呼叫 mutation / API / setState 更新父層。**沒有「取消」的概念**——改了就是改了。
+
+### 隨 form 送出（change → local state → submit）
+
+選值先寫進 local state，等 form submit 才套用：
+
+- **建立 / 編輯表單**：create project 裡的 type、edit user 的 role
+- **對話框設定**：dialog 內的選項，按確認才生效
+- **精靈流程**：多步驟表單的中間選擇
+
+這類場景 onChange 只更新 React state，直到 submit handler 才送出。**有「取消」可回復**。
+
+### 設計規則
+
+- 即時場景：用 `aria-label` 或旁邊的 label 明確告知「這個改了會立刻套用」
+- on-submit 場景：搭配 `<Field>` 容器 + submit button，使用者清楚哪個動作觸發儲存
+- **不要讓使用者搞不清楚是哪種**——這是 DS 最常見的信任破壞點
+
+---
+
+## Searchable 開啟判斷
+
+`searchable` 啟用後 field 變 input，打字即篩選 options。判斷依以下順序：
+
+### 主判準：label 性質
+
+- ✅ **需要 searchable**：label 是獨特關鍵字 / 代碼 / 非自然語言，使用者**無法靠捲動快速定位**
+  - 產品代碼：`SKU-4837`、`ORDER-2024-001`
+  - 郵遞區號、機場代碼（TPE / NRT / JFK）
+  - 使用者 ID、專案 slug、ticket number
+  - 中文姓名（同姓大量集中，字母跳不動）
+- ❌ **不需要 searchable**：label 是流暢自然語言、品類名稱，native select 的 type-to-jump 就夠用
+  - `Electronics`、`Furniture`、`Food`
+  - `Draft` / `In progress` / `Done`
+  - 國家英文名（按首字母跳夠快）
+
+### 次要啟發：選項數量
+
+數量只是啟發，主判準永遠是 label 性質。
+
+- **< 10** + 自然語言 label → 不開
+- **10-50** → 往搜尋傾斜（但仍看 label 性質）
+- **> 50** → 幾乎必開
+
+### 為什麼不用純數量 threshold
+
+- 100 個 `a` / `b` / `c` / ... 不需要搜尋（native type-to-jump 直達）
+- 5 個 `SKU-4837` / `SKU-8210` / ... 需要搜尋（使用者記不起哪個代碼對應哪個產品）
+
+純量化規則會誤判這兩端。label 性質是唯一可靠的主判準。
+
+---
+
+## 顯示模式（`display` prop）
+
+| 模式 | 何時使用 |
+|------|---------|
+| `plain`（預設） | 選項語意靠文字表達（類別、國家、角色） |
+| `tag` | 選項有色彩語意，顏色加速掃視（狀態：紅黃綠） |
+
+**命名 rationale**(2026-05-01 從 `'text'` 改 `'plain'`):跨元件 prop value 衝突防避 — `Button variant="text"` 表「無 chrome 文字按鈕」,跟 Select.display 的「純文字呈現」是兩個不同概念,共用 `'text'` 字面值會造成 consumer 認知衝突(命名三 test 第 3 條)。改 `'plain'` 後語意專屬:plain = 樸素文字呈現,對立 tag = 用 Tag 元件呈現。
+
+### plain 模式
+
+- 原生 select 純文字 + ChevronDown
+- 可搭配 `startIcon`——**field-level leading indicator**(色 muted,對齊 `Input.startIcon` search-icon pattern;`Mail` / `Globe` / `Lock` / `Flag` 等提示「這個 field 的類型 / 屬性」,跟 selected value 變動無關)
+- **代表 value 的 icon(value-bound)走 `option.icon` per-option API**,Select 渲 selected 時 inherit fg-default(對齊 `MenuItem.startIcon` 跨元件 SSOT)
+- 兩 prop 不互斥:`startIcon` field-level 顯示時優先;unset 才落到 selected `option.icon` fallback(select.tsx:197/369 `SelectedIcon` path)
+- **icon kind canonical(2026-05-09 clarified)**:DS 兩種 icon 角色明確區分 — **value icon**(代表 label / 選中項)→ fg-default(MenuItem 內 / `option.icon`)/ **indicator icon**(field-level leading hint)→ muted(Input.startIcon / Select.startIcon)
+
+### tag 模式
+
+- Tag 元件呈現選中值 + 隱藏的原生 select overlay
+- Tag 設為 `pointer-events-none`，點擊穿透到底層 select
+- edit 模式：Tag + ChevronDown + 可選 clear
+- readonly / disabled：Tag 只顯示，無 ChevronDown
+
+---
+
+## Clearable
+
+`clearable` 在有值時顯示 clear 按鈕。
+
+- Clear 按鈕在 ChevronDown 左側
+- 清除後回到 placeholder 狀態
+- 只在 edit 模式顯示
+
+**何時開 clearable**：
+- 「無選擇」是有效狀態（選填欄位、可清除的 filter）→ 開
+- 必須有選擇（每個項目都必須有 status）→ 不開
+
+---
+
+## 常見誤解
+
+**誤解**：「Select 只用於表單送出，即時套用應該用別的元件」。
+**事實**：Select 的表單送出與即時套用都是正當用法。Jira、Linear、Notion 的 inline status dropdown 都是 Select + 即時 onChange。關鍵是 onChange 的副作用清楚，不是 Select 本身。
+
+**誤解**：「3-5 個選項一定要用 RadioGroup」。
+**事實**：看容器與決策性質，不看數量。Toolbar 的 3 個 filter 必須是 Select / SegmentedControl（RadioGroup 不符 toolbar 視覺）；form 中 3 個付款方式用 RadioGroup（決策節點）。見「與 RadioGroup 的分界」。
+
+**誤解**：「選項超過 N 個一定要開 searchable」。
+**事實**：主判準是 label 性質，不是數量。見「Searchable 開啟判斷」。
+
+---
+
+## Loading
+
+`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補):dropdown body 內取代 options 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(消費 既有 empty.spec.md:182 SSOT)+ `aria-busy`。Trigger 不變(chevron 保留,user 隨時可開)。對齊 MUI Autocomplete `loadingText` 雙層 + Ant Select loading,反 trigger spinner 派。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 禁止事項
+
+- ❌ `startIcon` 不可用於 tag 模式——Tag 本身已有視覺標記，startIcon 是冗餘的
+- ❌ 不自建 dropdown menu——使用原生 `<select>` 保證無障礙和行動裝置體驗
+- ❌ 讓使用者搞不清楚是即時還是 on-submit——用 label / 按鈕位置明確傳達
+- ❌ 把「決策節點」選擇塞進 Select（付款方式、訂閱方案）——使用者需要對比評估，用 RadioGroup
+
+---
+
+## 為何無 StateBehavior
+
+Select 是 **Field Controls family 成員**——互動狀態(focus / invalid / disabled / readonly)完全繼承 `../Field/field-controls.spec.md` SSOT「Mode 狀態」。dropdown 開啟時的 MenuItem hover / selected 狀態由 MenuItem primitive own(`patterns/element-anatomy/item-anatomy.spec.md`)。Select 層級無自有 state 行為。重寫 StateBehavior = 複製 Field Controls + MenuItem SSOT 內容,雙邊漂移風險。
+
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix`。Field-level state 見 Input `StateBehavior` + field-controls.spec.md;item-level state 見 MenuItem `ColorMatrix`。
+
+---
+
+## 相關
+
+- `segmented-control.spec.md` — 2-5 個緊湊互斥切換；「何時不用」的主要去處
+- `../Checkbox/checkbox.spec.md`（含 RadioGroup 設計原則）— RadioGroup 共用規則
+- `combobox.spec.md` — 多選的對應元件
+- `../Switch/switch.spec.md` — 布林切換
+- `../Field/field-controls.spec.md` — Select 作為 Field control 時的共用規則（mode、size、endAction）
+
+## A11y 預設
+
+**ARIA / Pattern**:native `<input>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- 字母鍵 — 輸入
+- Esc — 清空(若 clearable + 有值)
+
+**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `people-picker.spec.md`
+- `select-menu.spec.md`

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

@@ -0,0 +1,220 @@
+---
+component: SelectMenu
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - isInputLike
+  - isInternal
+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
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# SelectMenu 設計原則
+
+## 定位
+
+SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提供搜尋 + 鍵盤導覽 + 分組 + 可建立新選項，作為**選值類**元件的 internal primitive（不直接使用）。
+
+**實作基礎**：基於 cmdk（搜尋 / 鍵盤導覽）+ shadcn Popover（浮動容器）+ 消費 MenuItem primitive（item 佈局）。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## Controlled-only rationale(Dim 26)
+
+本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+
+**為什麼**:
+- 內部狀態複雜(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 -->
+
+**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
+
+---
+
+## 何時用 / 何時不用
+
+**SelectMenu 是 internal primitive**——不直接使用，透過外層選值元件消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| 人員選擇器（搜尋 + Avatar）| 用 `PeoplePicker`（內部消費 SelectMenu）|
+| 大量選項單選 + 搜尋 | 用 `Select` with `searchable`（內部會切換到 SelectMenu 模式）|
+| 大量選項多選 + 搜尋 | 用 `Combobox` with `searchable`（內部會切換到 SelectMenu 模式）|
+| 可建立新選項（creatable tag）| 用 `Combobox` + `creatable` prop |
+| 直接在 JSX 中用 `<SelectMenu>` | ❌ **禁止**——失去外層 Select / Combobox / PeoplePicker 的 Field 整合、trigger 行為、state 管理 |
+
+### 消費者
+
+- `../PeoplePicker/people-picker.tsx` — 人員選擇（永遠 searchable）
+- `../Select/select.tsx` — `searchable` 模式會切換到 SelectMenu 浮層
+- `../Combobox/combobox.tsx` — `searchable` 模式會切換到 SelectMenu 浮層
+
+---
+
+## 架構
+
+```
+Popover（浮動容器，handle 展開 / 定位）
+  └─ Command（cmdk — 搜尋 + 鍵盤導覽）
+       ├─ CommandInput（搜尋框，選項 > 5 時顯示）
+       ├─ CommandList（捲動區）
+       │    └─ CommandGroup（分組標題）
+       │         └─ MenuItem（選項 row，消費 item-layout）
+       └─ Footer（多選全選 checkbox，選填）
+```
+
+**定位**: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 -->
+
+換言之 SelectMenu **永遠照 canonical**,只是大多數情況 width=trigger-width 讓 canonical 視覺上被 mask,一旦 popover 突破 trigger 寬度 canonical 立刻生效。規則沒例外,只是呈現條件。
+
+---
+
+## 單選 vs 多選
+
+透過 `value` / `onValueChange` 的類型決定：
+
+- **單選**：`value: string | null`，選中後立即關閉浮層
+- **多選**：`value: string[]`，選中不關閉，可繼續選（footer 可顯示全選 checkbox）
+
+---
+
+## Creatable（建立新選項）
+
+透過 `onCreate` prop 啟用。搜尋無結果時顯示「建立 "xxx"」提示（`Plus` icon + 使用者輸入的字）。
+
+**何時啟用**：
+- Tag input 允許使用者建立新 tag
+- Assignee 選擇允許邀請外部人員
+- Label / category 自由建立
+
+**何時不啟用**：
+- 固定選項清單（狀態、類別、角色）
+- 需要後端驗證合法性的 value（避免建立無效選項）
+
+---
+
+## 分組（group）
+
+透過 `groups` prop 定義分組標籤，每個 option 的 `group` 欄位指向 group key。
+
+**何時使用**：
+- 選項明顯分兩個以上邏輯群組（「Recent」/「All」、「Your team」/「Others」）
+- 超過 10 個選項需要視覺分區降低認知負擔
+
+**何時不用**：
+- 選項少於 6 個（分組反而增加視覺雜訊）
+- 選項本質平行（沒有自然分組）
+
+---
+
+## Empty state
+
+搜尋無結果時顯示 `Empty` 元件，可透過 `emptyText` 自訂訊息（預設「無符合的選項」）。
+
+- **Creatable 時**：即使搜尋無結果，仍顯示「建立 "xxx"」讓使用者補建選項
+- **非 creatable**：顯示 emptyText 提示使用者修改搜尋詞
+
+---
+
+## Loading（2026-05-15 audit B fix, codify 2026-05-16 audit Dim 7+8）
+
+非同步載入選項時，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）
+
+對齊 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 -->
+
+**消費**：Select / Combobox / PeoplePicker forward `loading` prop 到 SelectMenu，本元件不需 consumer 直接知道 Empty + CircularProgress 組合（封裝在內）。
+
+---
+
+## 禁止事項
+
+- ❌ 直接在 JSX 用 `<SelectMenu>`——透過外層元件（Select / Combobox / PeoplePicker）消費
+- ❌ 跳過 SelectMenu 自建 Popover + Command 組合——會漂移出共用 layout 與 item-layout 規則
+- ❌ 不搭配 trigger / field 使用——SelectMenu 是浮層，一定需要觸發元件
+- ❌ 超過 50 個選項不開搜尋——純捲動會變低效
+- ❌ 分組少於 2 組——分組本身是視覺成本，只有一組等於沒分組
+
+---
+
+## 邊界案例
+
+- **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。
+- **Dark mode**:走 Popover / MenuItem semantic token 自動 adapt。
+- **Density**:row height 由 `MenuItem` SSOT 控(sm/md/lg);SelectMenu 不獨立 own density。
+
+---
+
+## 為何無 ColorMatrix
+
+SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
+
+- **無 ColorMatrix**:視覺完全繼承既有 DS primitive 的 token(`MenuItem` row / `Command` search / `Empty` layout / `Popover` surface),無自己的 bg / border / hover 決策。色彩漂移由 primitive layer 控制——SelectMenu 層級若加 ColorMatrix 會重複 MenuItem / Popover 的矩陣。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix` / `StateBehavior`,額外追加元件特有的 `ModeMatrix`(single / multi / searchable / creatable / grouped 等功能組合矩陣,這是 SelectMenu 真正的決策面向——取代 ColorMatrix)。
+
+---
+
+## shadcn passthrough 例外說明
+
+SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**不套 `forwardRef` / `...props` spread`**,同 PeoplePicker 理由:
+
+- **沒有單一 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 細節
+
+`displayName = 'SelectMenu'` 保留。若 consumer 需要 DOM-level 控制(custom trigger / portal / search input ref),改用底層 Popover + Command 自組。
+
+`asChild` 不支援(composite 非 Slot-compat)。
+
+---
+
+## 相關
+
+- `../Menu/menu-item.spec.md` — 選項 row 的 item-layout 共用規則（SelectMenu 消費 MenuItem）
+- `../Popover/popover.tsx` — 浮動容器（SelectMenu 消費）
+- `../Command/command.tsx` — cmdk 搜尋 + 鍵盤導覽（SelectMenu 消費）
+- `../Empty/empty.spec.md` — 搜尋無結果的 empty state
+- `../Select/select.spec.md` — 主要消費者之一（searchable 時切換到 SelectMenu）
+- `../Combobox/combobox.spec.md` — 主要消費者之一（searchable 多選時切換到 SelectMenu）
+- `../PeoplePicker/people-picker.spec.md` — 永遠使用 SelectMenu 的消費者
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — item-layout pattern（MenuItem 繼承）
+
+## A11y 預設
+
+**ARIA / Pattern**:基於 `cmdk` library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — focus trigger
+- Enter / Space / ↓ — 開啟 menu
+- ↑/↓ — 導覽 options
+- Enter — 選擇
+- 字母鍵 — type-ahead 過濾(search 模式)
+- Esc — 關閉
+
+**Focus**:menu 開啟時 focus 第一 option / 選中項;關閉時 focus 回 trigger。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `command.spec.md`
+- `dropdown-menu.spec.md`

package/src/components/SelectionControl/selection-item.spec.md

@@ -0,0 +1,128 @@
+---
+component: SelectionItem
+family: 2
+variants: {}
+sizes:
+  sm: {}
+  md: {}
+  lg: {}
+traits:
+  - hasSizes
+  - isStructural
+  - isInternal
+benchmark:
+  - Radix Checkbox primitive: github.com/radix-ui/primitives/tree/main/packages/react/checkbox
+  - Radix RadioGroup primitive: github.com/radix-ui/primitives/tree/main/packages/react/radio-group
+  - Polaris Checkbox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Checkbox
+---
+
+# SelectionItem 設計原則
+
+## 定位
+
+SelectionItem 是 **Checkbox 和 RadioGroup 共用的 item 佈局 primitive**——提供 control + optional prefix + content（label/description）+ optional suffix 的 4-slot 結構，並處理 padding 公式（`py = (field-height - 1lh) / 2`）讓單行高度對齊同 size 的 Input。
+
+> **關於資料夾命名**: `SelectionControl/` 是**概念群組**名稱（對齊 `Menu/` 包 `menu-item.tsx` / `Field/` 包 `field.tsx` 的專案慣例），其內包含主要 primitive `selection-item.tsx`。未來可能增加 `selection-indicator.tsx` 等相關 primitive 到同一資料夾。spec / file 以 main primitive 為準命名(見 `menu-item.spec.md` 先例)。
+
+**實作基礎**：自建 internal primitive——純視覺佈局 + padding 公式，無 external primitive base。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。SelectionItem 是 Family 2 的 SelectionItem variant：prefix 放 Checkbox/Radio indicator 而非 icon/avatar。
+
+---
+
+## 何時用 / 何時不用
+
+**SelectionControl 是 internal primitive**——不直接使用，透過 Checkbox / RadioGroup 消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| 建立一組 Checkbox 選項 | 用 `Checkbox`（內部消費 SelectionItem）|
+| 建立一組 Radio 選項 | 用 `RadioGroup` + `RadioGroupItem`（內部消費 SelectionItem）|
+| 直接用 `<SelectionItem>` | ❌ **禁止**——會失去 Checkbox / Radio 的 ARIA state、keyboard、form integration |
+
+---
+
+## 為什麼要獨立 primitive
+
+Checkbox 和 Radio 視覺幾乎完全一致（差異只在形狀 `rounded-md` vs `rounded-full` 和指示器 check icon vs filled dot），佈局邏輯（prefix / content / suffix 對齊、`py` padding 公式、clamp 政策、disabled 狀態處理）100% 共享。
+
+**不獨立**的話兩邊各自實作會漂移——某天改了 Checkbox 的 gap 或 clamp，Radio 會忘記同步。獨立成 SelectionItem 保證兩者視覺 / 行為永遠一致。
+
+---
+
+## 結構
+
+```
+[control]  [optional prefix (icon | avatar)]  [content: label + description]  [optional suffix]
+```
+
+- `flex items-start gap-2`：控件與 content 對齊第一行
+- 控件包在 `h-[1lh]` 容器中，跟第一行文字垂直置中
+- 多行 label 時，控件保持對齊第一行（不跳到中間）
+
+### 字體
+
+- `text-body` (sm/md) / `text-body-lg` (lg)——建立 `1lh` context 讓控件高度跟隨字體
+
+### Padding 公式
+
+`py = (field-height - 1lh) / 2`
+
+- 單行時總高度 = field-height（對齊同 size 的 Input）
+- 多行時 padding 不變，自然撐高
+- density 切換時 field-height 自動調整，padding 跟著算
+
+### Clamp 政策
+
+見 `../Checkbox/checkbox.spec.md`「Clamp 政策」——Label / Description 預設 `'none'`（完整閱讀優先），非「掃視優先」。
+
+---
+
+## 禁止事項
+
+- ❌ 直接在 JSX 用 `<SelectionItem>`——透過 Checkbox / Radio 消費
+- ❌ 在 Checkbox / Radio 之外複製 SelectionItem 邏輯——共用源頭一定是 SelectionControl
+- ❌ 改動 `py` padding 公式只針對某一 variant——Checkbox 和 Radio 必須同步
+
+---
+
+## 為何無 ColorMatrix / StateBehavior
+
+SelectionItem 是**純 layout primitive**,只處理 4-slot 結構 + padding 公式,無獨立色彩與互動狀態:
+
+- **無 ColorMatrix**:SelectionItem 本身**不設** bg / border color,也**不擁有** control 視覺(Checkbox 方框 / Radio 圓圈)——control 由 consumer 傳入(`control` prop 接 ReactNode)。色彩決策屬於 Checkbox / Radio 層級,其 `.anatomy.stories.tsx` 負責 ColorMatrix(如 Checkbox 的 unchecked / checked / indeterminate × default / hover / disabled 矩陣)。
+- **無 StateBehavior**:SelectionItem 只有 `disabled` 影響 label 顏色(`text-fg-disabled`),無 selected / checked / hover / active——這些狀態屬於傳入的 `control`。Disabled 行為在 `Inspector` 的 props 已足夠展示,不需獨立 story。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix`,額外追加元件特有的 `PrefixAlignment`(展示 24px 閾值下 icon/avatar 的 inline vs block 對齊行為——這是 SelectionItem 最重要的結構規則,取代 ColorMatrix)。
+
+---
+
+## 邊界案例
+
+- **Disabled**:`disabled` 影響 label 顏色(`text-fg-disabled`,M24);control(Checkbox 方框 / Radio 圓圈)的 disabled 視覺由 consumer control 自己 own。SelectionItem 不獨立 own control state。
+- **Loading**:SelectionItem 為 layout primitive 非 async surface;無 loading state。Group-level loading 由 consumer(CheckboxGroup / RadioGroup)在外層處理(Skeleton stack)。
+- **Empty**:label 必傳(internal API contract);無 label-empty 場景。若 `description` 缺,layout 自動收斂為單行。
+- **Dark mode / density**:走 semantic token 自動 adapt;`py` padding 公式對齊 `--field-height-{sm/md/lg}` density token。
+
+---
+
+## 相關
+
+- `../Checkbox/checkbox.spec.md` — 主要消費者之一，含 Clamp 政策 SSOT
+- `../RadioGroup/radio-group.spec.md` — 另一消費者
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — 4-slot 結構的 pattern 來源
+- `../../tokens/uiSize/uiSize.spec.md` — `--field-height-*` token
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- Space — toggle
+
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+