@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/src/components/Combobox/combobox.spec.md

@@ -0,0 +1,180 @@
+---
+component: Combobox
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design AutoComplete: github.com/ant-design/ant-design/tree/master/components/auto-complete
+  - MUI Autocomplete: github.com/mui/material-ui/tree/master/packages/mui-material/src/Autocomplete
+  - Polaris Combobox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Combobox
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Combobox 設計原則
+
+## 定位
+
+Combobox 是**多選下拉**的輸入與顯示元件。選中值以 Tag 陣列呈現，支援單行溢出與多行換行兩種版面。底層走原生 `<select>`（配合 Tag 疊層 overlay）。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 Combobox 特有的原則。
+
+**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-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。
+
+---
+
+## 何時用
+
+- **多選場景**（使用者可選 0 個或多個）：Tag、分類、協作成員、通知訂閱
+- **選項數 6+**（少於 6 且 2-5 可見的多選，用 Checkbox stack 更有效）
+- **空間受限**：Table cell、toolbar filter、窄欄位 Form
+- **需要搜尋或大量選項**：searchable 後可處理 50+ 選項
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 單選 | `Select` | Combobox 永遠多選；單選場景強迫使用者每次手動清除再選新的 |
+| 2-5 個選項且全部可見 | Checkbox stack（`SelectionItem` 垂直排列）| 全可見 + 掃視快 + 支援描述文字 |
+| 階層結構（父/子節點）| `TreeView` | Combobox 是平面選項，沒有層級概念 |
+| 布林群組（多個獨立 on/off） | 多個 `Switch` | 每個開關是獨立功能，不是「從清單選」 |
+
+### 與 Checkbox stack 的分界
+
+兩者都能「2-5 個選項裡多選」，判斷與 Select vs RadioGroup 同構（詳見 `../Select/select.spec.md`「與 RadioGroup 的分界」），核心三角度：
+
+- **Progressive disclosure 成本**：Combobox 藏（多一次點擊），Checkbox stack 全露
+- **視覺重量**：Combobox O(1)，Checkbox stack O(n) 每個選項各一行
+- **評估深度**：Checkbox stack 適合「需要仔細讀選項 / 連帶 description」（權限授予、條款勾選），Combobox 適合「label 自帶語意、快速添加」（tag、分類）
+
+**Fallback**：表單中法律 / 權限類多選一律 Checkbox stack（完整閱讀優先，見 `../Checkbox/checkbox.spec.md`「Clamp 政策」）；Tag / 分類 / 協作成員用 Combobox。
+
+---
+
+## 版面模式（`wrap` prop）
+
+| 模式 | 行為 | 適用場景 |
+|------|------|---------|
+| 單行（預設） | 固定高度，溢出的 Tag 隱藏，顯示 +N 指示器 | Table cell、空間受限的 Form |
+| 多行（`wrap`） | 高度隨內容展開，Tag 自然換行 | 空間充裕的 Form |
+
+### 單行溢出
+
+- 以量測為基礎：計算可用寬度，依序放入 Tag，放不下的隱藏
+- 溢出指示器 `+N` 顯示被隱藏的數量
+- Hover 溢出指示器時，popover 顯示完整的隱藏 Tag 清單
+
+---
+
+## Tag 操作
+
+### 個別移除
+
+每個 Tag 有 dismiss 按鈕（X），點擊移除該選項。
+
+### 全部清除
+
+`clearable` 在有值時顯示 clear all 按鈕，一次清除所有選項。位於最右側，ChevronDown 左邊。
+
+### 新增選擇
+
+原生 `<select>` 只顯示**未選中**的選項——已選中的不重複出現在下拉。
+
+### Search input 最小寬度 `min-w-[60px]`（documented constant）
+
+多選時 tag 跟 search input 共擠在 `fieldWrapperStyles` 內；input 以 `flex-1 min-w-[60px]` 確保**最少 60px 可打字空間**。低於 60px 會讓 search 輸入變得無法用（使用者看不到自己打什麼）。這是 Combobox 專用 layout 常數，非跨元件 token。
+
+---
+
+## readonly / disabled 的 Tag
+
+- 沒有 dismiss 按鈕——不可操作
+- 沒有 ChevronDown——不可新增
+- 沒有 clear 按鈕——不可清除
+- 溢出行為與 edit 模式相同（+N 指示器）
+
+---
+
+## 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 不變,user 隨時可開。對齊 MUI Autocomplete `loadingText` + Ant AutoComplete loading idiom。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 邊界案例
+
+- **Disabled**:Field SSOT own(`Field/field-controls.spec.md`)。trigger / tag dismiss / 搜尋 input 全部 disabled,token 走 M24 state precedence(`text-fg-disabled`);已選 Tag 的 dismiss X 自動隱藏(見「readonly / disabled 的 Tag」段)。
+- **Loading**:已 codify(見「Loading」段)。
+- **Empty(no search results)**:dropdown body 內,非 creatable 時渲 `emptyText`(預設「無符合的選項」);creatable 時保留「建立 "xxx"」row 引導用戶補建選項(由 SelectMenu primitive own,Combobox forward `onCreate`)。
+- **Empty(no value selected)**:multi mode `value=[]` 時 trigger 顯 placeholder(如「請選擇」);empty state 不渲 tag 區。
+- **Dark mode / density**:走 Field + SelectMenu SSOT 自動 adapt。
+
+## 驗證時機
+
+走 Field SSOT(`Field/form-validation.spec.md`)。Combobox 為 form control,validation 行為:
+
+- `required` + `value=[] / null` → submit 時 trigger error,`aria-invalid="true"` + error border
+- `errorMessage` prop 由 Field wrapper 顯示於下方
+- multi mode 可附 `min` / `max` selected count 限制(consumer 自驗,Combobox 不獨立 own validation rules)
+- Validation timing:預設 onBlur + onSubmit,onChange 不立即 validate(避免邊選邊紅)
+
+---
+
+## 禁止事項
+
+- ❌ 不在已選中的選項上再顯示 dismiss 以外的互動——Tag 只能被移除，不能被編輯或重新排序
+- ❌ 溢出指示器 `+N` 不可省略——使用者需要知道有多少被隱藏的項目
+- ❌ 不自建 dropdown——使用原生 `<select>` 保證無障礙
+- ❌ 單選場景用 Combobox——使用者每次需手動清除再選新的，改用 `Select`
+- ❌ 法律 / 權限類多選用 Combobox——完整閱讀優先，改用 Checkbox stack（見 Checkbox spec「Clamp 政策」）
+
+---
+
+## A11y 預設
+
+### 鍵盤可達性的 delegation 設計
+
+Combobox 內部結構有多個 `<div>` / `<Tag>` 帶 `onClick`（tag 容器、ChevronDown 區域、搜尋輸入 wrapper 等）——**這些是 mouse 優化的 click-path delegation，不是鍵盤介面**。鍵盤路徑由**隱藏的 native `<select>`** 處理（tab-focusable，Enter/Space 開啟，arrow 導覽，Esc 關閉）。
+
+**設計取捨**:
+- ✅ **好處**: 保留原生 `<select>` 的完整 a11y（包含 mobile screen reader + 語音輸入 + 所有 OS-level 整合）
+- ⚠️ **後果**: 非 button 元素帶 `onClick` 是 mouse-only 互動,鍵盤使用者不經過它們——但他們也不需要（native select 路徑涵蓋所有功能）
+
+**為什麼不 role="button" + tabIndex**: 若每個 click target 都加 `role="button" tabIndex={0}` 會**偷走 native select 的 tab focus**,反而破壞鍵盤體驗。"單一 native tab stop + 多個 mouse click surface" 是 world-class 混合 control 的 canonical pattern（Material / Atlassian / GitHub issue filter 共識）。
+
+**結論**: Combobox 多處 `onClick` 在非 button 元素上**是經過評估的 acceptable a11y 模式**,不是需要修復的 bug。
+
+---
+
+## 相關
+
+- `../Select/select.spec.md` — 單選對應元件；「與 RadioGroup 的分界」是 Combobox vs Checkbox stack 的 framework 來源
+- `../Checkbox/checkbox.spec.md` — Checkbox stack（多選全可見場景）
+- `../TreeView/tree-view.spec.md` — 階層式選擇
+- `../Switch/switch.spec.md` — 布林開關群組
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `overflow-indicator.spec.md`
+- `people-picker.spec.md`
+- `select-menu.spec.md`
+- `tag.spec.md`

package/src/components/Combobox/combobox.tsx

@@ -29,8 +29,8 @@ const tagPadding: Record<string, string> = {
  * SelectMenuOption(primitive SSOT)** — 避免重蹈先前 PeoplePicker 改壞的 wrapper schema drift。
  *
  * Why `extends SelectMenuOption`(per user 「全盤檢查避免下次又改壞或是偏移」要求):
- *   原 `interface SelectOption { value: string; label: string }` 是 weak schema,跟 Select 的
- *   `SelectOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
+ *   原 `interface ComboboxOption { value: string; label: string }` 是 weak schema,跟 Select 的
+ *   `ComboboxOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
  *   各 export,consumer import 到哪個版本看 import path)→ schema drift。
  *   PeoplePicker multi-mode 走 Combobox 路徑,dropdown menu rows lose avatar / description —
  *   user 看到「single mode 有 avatar / multi mode 沒 avatar」inconsistency。
@@ -42,7 +42,7 @@ const tagPadding: Record<string, string> = {
  * 對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown 的 wrapper-vs-primitive
  * schema-extension idiom。Hook `check_wrapper_primitive_schema_drift.sh`(M30 機械強制)。
  */
-export interface SelectOption extends SelectMenuOption {
+export interface ComboboxOption extends SelectMenuOption {
   // (no wrapper-only fields yet — kept for future扩 + same-name SSOT cross-wrapper)
 }
 
@@ -322,7 +322,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
 function ComboboxTagStack({
   value, options, tagSize = 'md', wrap = false, containerRef: externalRef, disabled = false,
 }: {
-  value?: string[] | null; options?: SelectOption[]; tagSize?: 'sm' | 'md' | 'lg'
+  value?: string[] | null; options?: ComboboxOption[]; tagSize?: 'sm' | 'md' | 'lg'
   wrap?: boolean; containerRef?: React.RefObject<HTMLDivElement | null>; disabled?: boolean
 }) {
   const ownRef = React.useRef<HTMLDivElement>(null)
@@ -367,7 +367,7 @@ export interface ComboboxProps {
   variant?: FieldVariant
   error?: boolean
   size?: 'sm' | 'md' | 'lg'
-  options: SelectOption[]
+  options: ComboboxOption[]
   value?: string[]
   onChange?: (value: string[]) => void
   placeholder?: string
@@ -674,7 +674,7 @@ function CustomCombobox({
     [searchable, searchIn, search, options]
   )
 
-  // 轉換 SelectOption → SelectMenuOption
+  // 轉換 ComboboxOption → SelectMenuOption
   // 2026-05-10 post-Issue-4 follow-up:forward 全 SelectMenuOption surface(avatar / description /
   // disabled / icon / group)— 修先前 PeoplePicker multi-mode dropdown 漏 avatar drift bug。
   const menuOptions: SelectMenuOption[] = React.useMemo(

package/src/components/Combobox/index.ts

@@ -0,0 +1,5 @@
+// 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 './combobox'

package/src/components/Command/command.spec.md

@@ -0,0 +1,171 @@
+---
+component: Command
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInternal
+benchmark:
+  - cmdk (shadcn Command base): github.com/pacocoursey/cmdk
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Command 設計原則
+
+## 定位
+
+Command 是**搜尋 + 鍵盤導覽的指令清單**——提供搜尋框、分組選項、鍵盤導覽、空狀態。多用於浮層選單內部（SelectMenu）或 Command Palette（Cmd+K）。
+
+**實作基礎**：shadcn passthrough——基於 cmdk + Radix Dialog（Command Palette 模式）。本 DS 保留 shadcn 原結構 + 橋接 DS token 和 Empty / MenuItem primitive。
+
+**分類**：Internal primitive——由 SelectMenu 消費（Select / Combobox / PeoplePicker 透過 SelectMenu 使用）。App 不直接使用 Command；若要 Command Palette 類 UX,組合 Popover + Command 即可。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **SelectMenu 內部搜尋**：Select / Combobox / PeoplePicker 的 searchable 模式底層
+- **Command Palette（Cmd+K）**：全局跨頁搜尋、快速動作入口
+- **需要搜尋過濾 + 鍵盤導覽的選項清單**
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 不需要搜尋的短選項清單（< 6 項）| `DropdownMenu` | DropdownMenu 是操作選單，不含搜尋 |
+| 表單內的單選下拉 | `Select` | Select 自動判斷是否切到 SelectMenu 模式 |
+| 表單內的多選下拉 | `Combobox` | 同上 |
+| 人員選擇 | `PeoplePicker` | 專用人員選擇器（內部會消費 Command）|
+
+---
+
+## 消費者
+
+Command 通常由 `SelectMenu` 或自訂 Command Palette 元件消費——直接使用 Command 很少見，除非建立全新的搜尋清單 UI。
+
+---
+
+## 與 DropdownMenu 的分界
+
+**本節是 SSOT**——DropdownMenu / SelectMenu spec 反向引用此節。
+
+- **DropdownMenu**：**操作選單**——選完觸發動作（複製 / 刪除 / 匯出），選單關閉，選項通常 < 10 項
+- **Command**：**搜尋選值**——有 search input + 大量選項導覽，適合超過 10 項或需要鍵盤搜尋過濾的場景
+
+**判斷法**：問「選項數量 > 10 且使用者需要搜尋嗎？」
+
+- 是 → **Command / SelectMenu**
+- 否（少量、固定清單） → **DropdownMenu**
+
+## 與 SelectMenu 的分界
+
+- **SelectMenu**：Select / Combobox / PeoplePicker 的 searchable 浮層（**由 Field 觸發**,帶有 input field + 選中值回填）
+- **獨立 Command Palette**（Cmd+K）：也用 Command 但**不在 Field 觸發**——透過全域快捷鍵開啟,用於跨頁面搜尋 / 快速動作入口
+
+兩者底層都消費 Command。Field 場景用 SelectMenu（已處理 input binding）；非 Field 場景（Cmd+K）自組 Popover + Command。
+
+---
+
+## 禁止事項
+
+- ❌ **不在短選單（< 6 項）用 Command**：多此一舉增加認知負擔,改用 DropdownMenu 或 RadioGroup
+- ❌ **Command 不當 form input**：它是選值浮層而非輸入框——表單內選值請用 Select / Combobox,它們會自動決定是否啟用 Command 模式
+- ❌ **Command 搜尋框不是 Field Control**：不對齊 Field size token（不配對 `--field-height-md`）——它是浮層內的搜尋輸入,走 Command 自身的尺寸規格
+- ❌ **不把 Command 直接貼進頁面**：Command 是浮層內容,必須搭配 Popover / Dialog container——若要 inline 搜尋清單用 Input + 自訂 list
+
+---
+
+## A11y 預設
+
+cmdk 自動處理：
+
+- **List 語意**：`role="listbox"` + `aria-activedescendant` 指向目前 highlight 項
+- **搜尋框**：`role="combobox"` + `aria-expanded` / `aria-controls` 指向 list
+- **鍵盤導覽**：↑ / ↓ 移動 highlight、Enter 選取、Esc 關閉（或清空搜尋）
+- **空狀態**：`<CommandEmpty>` 自動帶 `role="presentation"`,不干擾 screen reader 的 list 朗讀
+
+Consumer 無需額外處理 a11y,保留 cmdk 原結構 + 使用 `<CommandInput>` / `<CommandList>` / `<CommandItem>` 即可。
+
+---
+
+## 邊界案例
+
+- **Disabled item**:`<CommandItem disabled>` 透過 cmdk 內建支援,視覺繼承 MenuItem SSOT(`text-fg-disabled` + `aria-disabled=true` + 鍵盤導覽自動 skip + Enter 不觸發 onSelect)。
+- **Loading**:Command 本身非 async surface。async option fetch 應由 consumer(SelectMenu / Cmd+K palette)在外層處理 — 將 `<CommandList>` body 切換為 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md:182` SSOT)。Command primitive 不獨立 own loading prop。
+- **Empty(no results)**:`<CommandEmpty>` 自動偵測 search filter result = 0 時渲;consumer 必傳 fallback 文案(預設 cmdk 不渲)。
+- **Dark mode / density**:走 MenuItem + Input + Empty SSOT 自動 adapt;Command 不獨立 own density(由 consumer SelectMenu 控)。
+
+---
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+Command 是 **internal primitive**(SelectMenu 底層消費,app 不直接使用,見本 spec「分類」段),結構規格完全繼承既有 primitive:
+
+- **無 Inspector**:Command 無自己的決策性 prop(variant / size / severity),behavior 全部由 cmdk library 處理。該讓消費者 inspect 的是 **SelectMenu**(公開消費入口),不是 Command 本身。
+- **無 ColorMatrix**:Command 的視覺(`CommandItem` / `CommandGroup` / `CommandInput` / `CommandEmpty`)全部繼承既有 DS primitive 的 token(MenuItem row / Input field / Empty layout),無自己的色彩決策——色彩漂移由 primitive layer 控制。
+- **無 SizeMatrix**:Command 搜尋框與 list items 的尺寸由 **Menu block tier**(consumer SelectMenu 決定 compact / reading),Command 自身無 size prop(見本 spec「禁止事項」:Command 搜尋框不對齊 Field size token)。
+- **無 StateBehavior**:Command item 的 selected / hover / disabled 走 MenuItem primitive state(`patterns/element-anatomy/item-anatomy.spec.md`);Command 層級僅處理 search 過濾與鍵盤導覽,那是 cmdk behavior 不是視覺 state。
+
+對應 anatomy story:保留 `Overview`(展示 internal primitive 的 API surface——CommandInput / CommandList / CommandGroup / CommandItem / CommandEmpty)。深度視覺 / 尺寸對照請查 SelectMenu(consumer)與 MenuItem(item primitive)的 anatomy。
+
+---
+
+## 世界級對照
+
+對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁短選單用 Command」+「禁直接 app 使用」是本 spec 的 binary strict rule,以下為支撐 rationale。
+
+### Cmd-K palette 結構哲學
+
+| 維度 | 本 DS | Linear | Raycast | VS Code Quick Pick | macOS Spotlight | Notion Cmd+K | Slack Cmd+K |
+|------|-------|--------|---------|--------------------|-----------------|--------------|--------------|
+| Layout | **單欄 + grouped sections** | 單欄 + group | 單欄 + group + secondary action panel | 單欄 + multi-mode prefix(`> ` 命令 / `: ` 行)| 全螢幕 + multi-pane(blur background)| 單欄 + inline page preview | 單欄 + 切 tab(Search / Nav / Settings)|
+| Search input 位置 | **頂端** always visible | 頂端 always | 頂端 always | 頂端 always | 中央 hero | 頂端 always | 頂端 always |
+| 視覺 surface | Popover overlay | Popover overlay | Standalone window | inline overlay(top-center)| Full-screen(blur)| Popover overlay | Popover overlay |
+| 觸發 shortcut | **Cmd+K**(Apple)/ Ctrl+K(Windows) | Cmd+K | Hotkey(default Option+Space)| Cmd+P / Cmd+Shift+P | Cmd+Space | Cmd+P / Cmd+/ | Cmd+K |
+| Empty state | `<CommandEmpty>` + 文案 | inline 「No results」 | inline 「No matching commands」 | inline 「No results」 | hides list | inline 「No results」 | inline 「No matches」 |
+| 多 mode | 無(單一搜尋語意)| 無(單一)| 無 | 有(prefix mode `>` `:` `@`)| 有(隱式 routing)| 無 | 有(tab)|
+
+### Primitive vs Consumer 分層
+
+| DS | 本 DS | cmdk lib | Radix UI | shadcn/ui | Material UI |
+|----|-------|----------|----------|-----------|--------------|
+| Internal primitive 命名 | **Command** | cmdk | (無此 primitive,用 `<Combobox>` + filter)| Command | `<Autocomplete>` 一體 |
+| Consumer wrapper 命名 | SelectMenu / Popover+Command(Cmd+K) | (consumer 自包)| Combobox | Combobox / Custom Cmd+K | Autocomplete |
+| 是否 app 直接用 | **禁(必透過 SelectMenu / Popover wrapper)**| 開放 | 開放 | 開放 | 開放 |
+
+## 設計哲學
+
+四個關鍵決策,各自有世界級先例支撐:
+
+**(1) 單欄 + grouped sections(non-multi-pane)— 對齊 Linear / Raycast / VS Code / Notion 多家共識** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+macOS Spotlight 的 multi-pane / blur background 適合 system-level launcher(全 OS 範圍 routing),但 disruptive — 不適合 inline 元件場景(SelectMenu 內嵌 Cmd-K 模式)。Linear / Raycast / VS Code 共識「單欄 + group」適合 productivity tool 內嵌使用,且 cmdk lib(shadcn/Vercel)default 結構符合此哲學。
+
+捨棄 multi-pane 的代價是「無 inline preview 直觀度」(Spotlight 可預覽檔案內容),但 DS 場景是命令清單非檔案 browser,接受。
+
+**(2) Search input always visible at top — 對齊 Linear / Raycast / Notion / VS Code 共識** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+input always visible 提示使用者「這是 search-driven」,對齊 input-first mental model。捨「only on focus 才出現 input」(節省垂直空間)的代價是「無法 list 看完再搜尋」,但 Cmd-K 場景 default 預期 search,不是 list browse。
+
+**(3) Cmd+K(Apple)/ Ctrl+K(Windows)為觸發 shortcut — 對齊 Linear / Notion / Vercel / Slack / GitHub 共識** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+Cmd-K 已成 productivity tool 的 universal idiom(Linear 推廣後 Notion / Vercel / Stripe / Slack 統一),使用者跨 app 預期一致。捨棄 Raycast 的 Option+Space(global launcher conflict)/ Spotlight Cmd+Space(macOS 內建衝突)/ VS Code Cmd+P(file-only,跟 Cmd+Shift+P 命令分流)的差異化代價接受 — 對齊主流 idiom 比差異化重要。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**(4) Internal primitive 哲學 — app 不直接用 Command,必透過 SelectMenu / Popover+Command wrapper**
+
+cmdk / shadcn / Radix 默認開放 app 直接消費 primitive — 但本 DS 走 Material `<Autocomplete>` 一體 / Polaris 一體封裝哲學,把 search + popover + value-binding 包進 SelectMenu(form context)或 Popover+Command wrapper(global Cmd+K)。
+
+捨棄「app code 直接 import Command 客製」的代價是「自由度受限」(無法在 app 內客製 cmdk filter logic),但 DS 一致性更重要 — 若 SelectMenu / Popover+Command 不夠用,回 DS 開新 wrapper 而不是繞過抽象層(對齊 SSOT 消費 canonical M1)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 相關
+
+- `../SelectMenu/select-menu.spec.md` — 主要消費者（Select / Combobox / PeoplePicker 的 searchable 浮層）
+- `../DropdownMenu/dropdown-menu.spec.md` — 不需搜尋的操作選單
+- `../Popover/popover.spec.md` — Command Palette 的浮層容器
+- cmdk library — 底層搜尋與鍵盤導覽實作

package/src/components/Command/index.ts

@@ -0,0 +1,5 @@
+// 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 './command'