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

package/src/components/Combobox/combobox.principles.stories.tsx

@@ -0,0 +1,239 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Combobox } from './combobox'
+
+const meta: Meta = {
+  title: 'Design System/Components/Combobox/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── Options ───────────────────────────────────────────────────────────────────
+
+const categoryOptions = [
+  { value: 'electronics', label: 'Electronics' },
+  { value: 'furniture', label: 'Furniture' },
+  { value: 'food', label: 'Food' },
+  { value: 'lifestyle', label: 'Lifestyle' },
+  { value: 'clothing', label: 'Clothing' },
+  { value: 'books', label: 'Books' },
+  { value: 'sports', label: 'Sports' },
+]
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [tags, setTags] = React.useState(['electronics', 'food'])
+    return (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Combobox 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">四模式</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Combobox/展示" name="尺寸與 Button 對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Combobox/展示" name="單行 vs 換行"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單行 vs 換行</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Combobox/展示" name="搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Combobox/展示" name="DataTable 整合"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">DataTable 整合</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+        <Rule
+          title="Combobox 的 sweet spot — 多選 + 空間受限 + 選項數 6+"
+          note="Tag / 分類 / 協作成員 / 通知訂閱。使用者快速加選、移除，label 自帶語意不需描述"
+        >
+          <Combobox options={categoryOptions} value={tags} onChange={setTags} />
+        </Rule>
+
+        <Rule
+          title="❌ 單選:用 Select"
+          note="Combobox 永遠多選——單選塞進來使用者每次要手動先移除舊 Tag 再選新的，多餘的互動"
+        >
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} />
+          <Label warn>↑ 只選一個 electronics → 應該用 Select，一次點擊完成切換</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 2-5 個選項且需要全可見 + description:用 Checkbox stack"
+          note="權限授予、條款勾選、通知類型選擇——選項需要完整閱讀（含描述），決策後同意。Combobox 藏選項強迫多次點擊對比。完整對照見 select.spec.md「與 RadioGroup 的分界」(Combobox vs Checkbox stack 同構)"
+        >
+          <Combobox
+            options={[
+              { value: 'terms', label: '服務條款' },
+              { value: 'privacy', label: '隱私政策' },
+              { value: 'marketing', label: '行銷訊息' },
+            ]}
+            value={['terms']}
+            onChange={() => {}}
+          />
+          <Label warn>↑ 條款勾選是「完整閱讀後同意」→ 用 Checkbox stack 全露內容</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 階層結構（父/子節點）:用 TreeView"
+          note="Combobox 是平面選項。部門 / 權限 / 資料夾等樹狀結構需要 TreeView 的展開收合互動"
+        >
+          <Combobox
+            options={[
+              { value: 'eng', label: 'Engineering' },
+              { value: 'eng-fe', label: '— Frontend' },
+              { value: 'eng-be', label: '— Backend' },
+              { value: 'design', label: 'Design' },
+            ]}
+            value={['eng-fe']}
+            onChange={() => {}}
+          />
+          <Label warn>↑ 用縮排偽造階層 → 沒有展開收合、不能按父節點全選、破壞資料結構</Label>
+        </Rule>
+      </div>
+    </div>
+    )
+  },
+}
+
+export const WrapRule: Story = {
+  name: 'Wrap 模式選擇',
+  render: () => {
+    const [single, setSingle] = React.useState(['electronics', 'food', 'lifestyle', 'clothing', 'books'])
+    const [wrapped, setWrapped] = React.useState(['electronics', 'food', 'lifestyle', 'clothing', 'books'])
+    return (
+      <div>
+        <Rule
+          title="單行（預設）— Table cell、空間受限的 Form"
+          note="固定高度，與 Input / Select 等欄位並排對齊。多於可見寬度的 Tag 以 +N 指示器代替，hover 可看完整清單"
+        >
+          <Combobox options={categoryOptions} value={single} onChange={setSingle} />
+          <Label>↑ 單行：高度固定，超出的 Tag → +N</Label>
+        </Rule>
+
+        <Rule
+          title="多行 wrap — 空間充裕的 Form"
+          note="高度隨選中數量展開，每個 Tag 都完整可見。適合填答型表單——使用者一眼看到所有選項，不需 hover 溢出指示器"
+        >
+          <Combobox wrap options={categoryOptions} value={wrapped} onChange={setWrapped} />
+          <Label>↑ 多行：完整展開，無溢出</Label>
+        </Rule>
+
+        <Rule
+          title="❌ Table cell 不用 wrap"
+          note="多行會破壞 row 高度一致性，讓 table 變得不規則。Table cell 永遠用單行，使用者需要完整清單時 hover +N"
+        >
+          <div className="border border-border rounded-lg overflow-hidden w-full max-w-md">
+            <div className="flex items-center gap-3 px-3 py-2 border-b border-border bg-muted">
+              <span className="w-24 text-caption font-medium">Product</span>
+              <span className="text-caption font-medium">Categories</span>
+            </div>
+            <div className="flex items-start gap-3 px-3 py-2">
+              <span className="w-24 text-caption pt-1">Headphones</span>
+              <Combobox wrap options={categoryOptions} value={['electronics', 'lifestyle', 'sports']} mode="readonly" className="flex-1" />
+            </div>
+            <div className="flex items-start gap-3 px-3 py-2 border-t border-border">
+              <span className="w-24 text-caption pt-1">USB Hub</span>
+              <Combobox wrap options={categoryOptions} value={['electronics']} mode="readonly" className="flex-1" />
+            </div>
+          </div>
+          <Label warn>↑ 每 row 高度不同 → 掃視節奏被破壞。Table 用單行 + +N 指示器</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const TagOperationRule: Story = {
+  name: 'Tag 操作規則',
+  render: () => {
+    const [value, setValue] = React.useState(['electronics', 'food', 'lifestyle'])
+    const [ro] = React.useState(['electronics', 'food'])
+    return (
+      <div>
+        <Rule
+          title="Tag 只能被「移除」，不能被「編輯」或「重排」"
+          note="每個 Tag 右側的 X 是唯一被允許的互動——保持 Tag 的心智模型單純：它代表一個已選中的選項，要換就刪了重選"
+        >
+          <Combobox options={categoryOptions} value={value} onChange={setValue} />
+          <Label>↑ 點 Tag 的 X 移除；右側 clear all 一次清除；新增從 dropdown 選擇</Label>
+        </Rule>
+
+        <Rule
+          title="readonly / disabled 的 Tag 沒有任何互動"
+          note="沒有 dismiss X、沒有 clear;readonly 不顯示 ChevronDown(純值、不可開啟),disabled 才保留為類型身份 indicator。Tag 變純顯示,溢出規則仍然套用(+N 指示器可 hover 查看完整)"
+        >
+          <Combobox mode="readonly" options={categoryOptions} value={ro} />
+          <Label>↑ 不可移除、不可新增、不可清空——整個 field 變「顯示」</Label>
+        </Rule>
+
+        <Rule
+          title="已選中的選項在下拉裡以打勾標示，再點一次即取消"
+          note="桌機（預設）走自建浮層選單：已選項保留在清單中並以打勾呈現，再點一次即移除——避免使用者跨越下拉與 field 才能對照已選狀態。手機 / 觸控裝置改走原生 select，已選項則不重複出現在原生下拉"
+        >
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} />
+          <Label>↑ 打開 dropdown，Electronics 仍在清單裡並打勾，可再點一次取消</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const OverflowRule: Story = {
+  name: '溢出指示必須存在',
+  render: () => {
+    const [value, setValue] = React.useState(['electronics', 'food', 'lifestyle', 'clothing', 'books', 'sports'])
+    return (
+      <div>
+        <Rule
+          title="+N 指示器是單行模式的必要元件"
+          note="使用者必須知道「還有多少沒看到」——沒有 +N 的單行會誤導使用者以為選項已完整顯示。Hover 可看完整清單"
+        >
+          <Combobox options={categoryOptions} value={value} onChange={setValue} />
+          <Label>↑ 窄容器內多個 Tag，自動出現 +N</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不從零自刻下拉互動"
+          note="與 Select 同理——下拉的開關、鍵盤導覽、聚焦管理、screen reader 支援很容易做不完整。Combobox 桌機走共用的浮層選單元件（已內建搜尋與方向鍵導覽），手機則走原生 picker，兩者都不該繞過去從零自刻"
+        >
+          <Label>實作細節見 Design System / Components / Combobox / 設計規格</Label>
+        </Rule>
+      </div>
+    )
+  },
+}

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

@@ -0,0 +1,202 @@
+---
+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 陣列呈現，支援單行溢出與多行換行兩種版面。底層依裝置走兩條實作（觸控偵測自動切換）：**桌機（預設，非觸控）走自建浮層選單**（SelectMenu → Popover + Command（cmdk）），**手機 / 觸控裝置走隱藏的原生 `<select>`**（配合 Tag 疊層 overlay）。詳見「A11y 預設」段的雙路徑設計。
+
+共用規則見 `../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` 為唯一狀態來源(canonical 用法必同傳;型別 optional、無 runtime 強制),不支援 `defaultValue` uncontrolled fallback。
+
+**為什麼**:
+- 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
+- Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
+- 世界級對照:Ant AutoComplete / MUI Autocomplete(frontmatter benchmark)皆支援 dual-mode(`defaultValue`);我們選 controlled-only 對齊狀態一致性優先 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,目前不在 scope。
+
+### Open-pair rationale:defaultOpen + onOpenChange,無 controlled open(2026-06-12 deep-audit R2 補)
+
+value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaultOpen`(初始開)+ `onOpenChange`(通知 callback),無 controlled `open` prop。
+
+**為什麼**:
+- 已知需求只要「初始開 + 知道何時關」:(1) 視覺快照 — Storybook OpenSnapshot / visual-audit(M15)`defaultOpen` 一行達成;(2) DataTable cell-as-input(`DataTable/cell-registry.tsx`)— `defaultOpen` 1-step 開選單,`onOpenChange(false)` → cell exit edit mode
+- open 綁內部行為:關閉自動清 search(combobox.tsx `if (!open) setSearch('')`)/ Enter / Space / ArrowDown opener + Esc dismiss / trigger 內 inline input click 開啟。controlled `open` 要 consumer 忠實 echo 每一條內部 intent,漏接任一 → 卡開 / 卡關 / search 殘留
+- 世界級對照:Radix Popover([radix-ui.com/primitives/docs/components/popover](https://www.radix-ui.com/primitives/docs/components/popover))/ Ant Select([ant.design/components/select](https://ant.design/components/select))/ MUI Select([mui.com/material-ui/api/select](https://mui.com/material-ui/api/select/))皆提供 controlled `open` — 它們是泛用 primitive / library,必須支援任意 orchestration;本 DS 是 opinionated form control,無真實 consumer 需求前不為「可能性」付受控成本(Rule-of-3)
+
+**若未來要開 controlled open**:同 value 軸引入 `useControllableState` helper + 測 controlled↔uncontrolled switch,屬 major API 擴充,目前不在 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:**readonly 不顯示**(純值、不可開下拉)/ **disabled 保留**(類型身份 indicator,`fg-disabled`,`pointer-events-none`)/ naked cell 依 `showDisplayEndIcon`(2026-06-26)
+- 沒有 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「現有消費者」SelectMenu loading row SSOT)。Trigger 不變,user 隨時可開。對齊 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 內渲 SelectMenu 預設 `emptyText`「沒有符合的選項」(Combobox 不傳 `emptyText`,走 SelectMenu primitive default)。Combobox 不暴露 `creatable` / `onCreate` prop(僅 SelectMenu primitive 本身支援),故 Combobox consumer 無「建立 "xxx"」row。
+- **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` 不可省略——使用者需要知道有多少被隱藏的項目
+- ❌ 不破壞「單一鍵盤聚焦點 + 多滑鼠點擊區」雙路徑無障礙——桌機浮層選單（`role="combobox"` 容器 + 選單鍵盤導覽）與手機原生 `<select>` 各自提供完整鍵盤可達性，欄位內 `onClick` 點擊區不可加 `tabIndex` 搶 focus（見「A11y 預設」段）
+- ❌ 單選場景用 Combobox——使用者每次需手動清除再選新的，改用 `Select`
+- ❌ 法律 / 權限類多選用 Combobox——完整閱讀優先，改用 Checkbox stack（見 Checkbox spec「Clamp 政策」）
+- ❌ 「多選就一律用 Combobox」——2-5 個選項且全可見時 Checkbox stack 更有效（掃視快 + 支援描述文字），Combobox 從 6+ 選項才開始划算（見「與 Checkbox stack 的分界」）
+
+---
+
+## Internal API（PeoplePicker stack wrapper 私用，end-user 勿用）
+
+`tagWrapperClassName` / `overflowWrapperClassName` / `tagAreaGapPx` / `tagAreaPaddingLeftPx` / `visibleCountOverride` 是 Combobox overflow 量測層的內部 hook,只供 DS-internal wrapper(PeoplePicker avatar stack)用,已標 `@internal`。`tagAreaPaddingLeftPx` 目前無 active consumer(PeoplePicker 走 `!px-3` 路徑),保留供未來精準 padding 但新 consumer 請先評估。`overflowShape` 是 public typed enum(矩形/圓形 +N),不在此列。
+
+---
+
+## A11y 預設
+
+### 鍵盤可達性的雙路徑設計
+
+Combobox 依裝置走兩條不同實作（觸控偵測自動切換）：
+
+**桌機（預設，非觸控裝置）**:觸發區是一個 `role="combobox"` 的容器（`aria-expanded` / `aria-controls` 指向選單 / `tabIndex={0}` 可 tab 聚焦），開啟後是一個浮層選單（內含搜尋 + 選項清單）。鍵盤路徑：Tab 聚焦觸發區，方向鍵在選項間移動，Enter 選取，Esc 關閉——由選單元件的鍵盤導覽負責，**不是**原生 `<select>`。
+
+**手機 / 觸控裝置**:改用隱藏的原生 `<select>`（tab-focusable，方向鍵導覽，原生 picker），以保留行動裝置 screen reader / 語音輸入 / OS-level 整合。有值時這個 `<select>` 以全幅透明 overlay 蓋住整個欄位，點擊任何位置都會喚起原生 picker。
+
+兩條路徑共通點：欄位內多個 `<div>` / `<Tag>` 上的 `onClick` 是 mouse 優化的點擊區，**不是鍵盤介面**——鍵盤使用者不經過它們，但兩條路徑都已各自提供完整鍵盤可達性。
+
+**為什麼這些 click target 不加 `role="button" tabIndex`**: 若每個點擊區都加 `tabIndex={0}` 會搶走真正聚焦目標（桌機的 combobox 容器 / 手機的原生 select）的 tab focus，反而破壞鍵盤體驗。「單一鍵盤聚焦點 + 多個滑鼠點擊區」是混合型控制項的世界級 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。若要手動補充,寫在本節之前。
+
+- `checkbox.spec.md`
+- `overflow-indicator.spec.md`
+- `people-picker.spec.md`
+- `select-menu.spec.md`
+- `select.spec.md`
+- `tag.spec.md`

package/src/components/Combobox/combobox.stories.tsx

@@ -0,0 +1,184 @@
+// @story-trait-rationale: D3 mechanical migration (size:N → meta.width) — preexisting Default/WithError trait gap unrelated to this edit; tracked separately
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#WithBulkActions
+// Combobox 為主元件;當 stories 內 wrap DataTable 演示 cell-context,baseline = DataTable WithBulkActions(per .claude/references/story-baseline-registry.json#DataTable)
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { createColumnHelper } from '@tanstack/react-table'
+import { Combobox } from './combobox'
+import { Button } from '@/design-system/components/Button/button'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types'
+
+const categoryOptions = [
+  { value: 'electronics', label: 'Electronics' },
+  { value: 'furniture', label: 'Furniture' },
+  { value: 'food', label: 'Food' },
+  { value: 'lifestyle', label: 'Lifestyle' },
+  { value: 'clothing', label: 'Clothing' },
+]
+
+const meta: Meta<typeof Combobox> = {
+  title: 'Design System/Components/Combobox/展示',
+  component: Combobox,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Combobox>
+
+// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add display mode card to Modes story only.
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => {
+    const [value, setValue] = React.useState(['electronics', 'food'])
+    return (
+      <div className="flex flex-col gap-6 max-w-sm">
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
+          <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="類別(edit mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">display</h3>
+          <Combobox mode="display" options={categoryOptions} value={value} aria-label="類別(display mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+          <Combobox mode="readonly" options={categoryOptions} value={value} aria-label="類別(readonly mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+          <Combobox mode="disabled" options={categoryOptions} value={value} aria-label="類別(disabled mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">readonly (empty)</h3>
+          <Combobox mode="readonly" options={categoryOptions} value={[]} aria-label="類別(readonly empty demo)" />
+        </div>
+      </div>
+    )
+  },
+}
+
+/* ── 尺寸與 Button 對齊 ── */
+export const SizeAlignment: Story = {
+  name: '尺寸與 Button 對齊',
+  render: () => {
+    const [sm, setSm] = React.useState(['electronics', 'food', 'lifestyle'])
+    const [md, setMd] = React.useState(['electronics', 'food', 'lifestyle'])
+    const [lg, setLg] = React.useState(['electronics', 'food', 'lifestyle'])
+    const states: Record<string, [string[], (v: string[]) => void]> = { sm: [sm, setSm], md: [md, setMd], lg: [lg, setLg] }
+    return (
+      <div className="flex flex-col gap-4">
+        {(['sm', 'md', 'lg'] as const).map(size => (
+          <div key={size} className="flex items-center gap-3">
+            <Combobox size={size} options={categoryOptions} value={states[size][0]} onChange={states[size][1]} className="max-w-xs" />
+            <Button variant="primary" size={size}>送出</Button>
+            <span className="text-caption text-fg-muted">size="{size}"</span>
+          </div>
+        ))}
+      </div>
+    )
+  },
+}
+
+/* ── 單行 vs 換行 ── */
+export const WrapModes: Story = {
+  name: '單行 vs 換行',
+  render: () => {
+    const init = ['electronics', 'food', 'lifestyle', 'clothing', 'furniture']
+    const [v1, setV1] = React.useState(init)
+    const [v2, setV2] = React.useState(init)
+    return (
+      <div className="flex flex-col gap-6 w-72">
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">單行（預設）</h3>
+          <p className="text-caption text-fg-muted mb-3">塞不下的自動收進 +N，hover 顯示隱藏項</p>
+          <Combobox options={categoryOptions} value={v1} onChange={setV1} />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">單行 readonly</h3>
+          <Combobox mode="readonly" options={categoryOptions} value={init} />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">換行（wrap）</h3>
+          <p className="text-caption text-fg-muted mb-3">高度隨內容長，badges 自動換行</p>
+          <Combobox options={categoryOptions} value={v2} onChange={setV2} wrap />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">換行 readonly</h3>
+          <Combobox mode="readonly" options={categoryOptions} value={init} wrap />
+        </div>
+      </div>
+    )
+  },
+}
+
+/* ── 搜尋 ── */
+export const Searchable: Story = {
+  name: '搜尋',
+  render: () => {
+    const [value, setValue] = React.useState<string[]>(['electronics'])
+    const [value2, setValue2] = React.useState<string[]>(['electronics'])
+    return (
+      <div className="flex flex-col gap-6 max-w-sm">
+        <div className="flex flex-col gap-4">
+          <p className="text-caption text-fg-muted">searchable — 浮層內搜尋框，關鍵字保留可連續勾選</p>
+          <Combobox
+            options={categoryOptions}
+            value={value}
+            onChange={setValue}
+            searchable
+            aria-label="類別(searchable popover demo)"
+          />
+        </div>
+        <div className="flex flex-col gap-4">
+          <p className="text-caption text-fg-muted">searchIn='trigger' — inline 搜尋框，直接在欄位內輸入</p>
+          <Combobox
+            options={categoryOptions}
+            value={value2}
+            onChange={setValue2}
+            searchable
+            searchIn="trigger"
+            aria-label="類別(searchable inline demo)"
+          />
+        </div>
+      </div>
+    )
+  },
+}
+
+/* ── DataTable 整合 ── */
+export const InDataTable: Story = {
+  name: 'DataTable 整合',
+  render: () => {
+    interface Product {
+      name: string
+      categories: string[]
+      price: number
+    }
+
+    const data: Product[] = [
+      { name: 'Wireless Headphones', categories: ['electronics', 'lifestyle'], price: 2490 },
+      { name: 'Office Chair', categories: ['furniture'], price: 8900 },
+      { name: 'Green Tea', categories: ['food'], price: 350 },
+      { name: 'USB-C Hub', categories: ['electronics'], price: 1290 },
+    ]
+
+    const col = createColumnHelper<Product>()
+    const columns = [
+      col.accessor('name', { header: 'Product', meta: { type: 'string', width: 200 } }),
+      col.accessor('categories', {
+        header: 'Categories',
+        meta: { type: 'multiSelect', options: categoryOptions, width: 200 },
+      }),
+      col.accessor('price', { header: 'Price', meta: { type: 'currency', prefix: '$', width: 100 } }),
+    ]
+
+    return (
+      <div>
+        <p className="text-caption text-fg-muted mb-3">multiSelect 欄位自動用多個 Tag 渲染</p>
+        <DataTable columns={columns} data={data} height="auto" />
+      </div>
+    )
+  },
+}