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

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

@@ -0,0 +1,238 @@
+// @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="三種尺寸"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</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} aria-label="商品分類(多選 Tag 範例)" />
+        </Rule>
+
+        <Rule
+          title="❌ 單選:用 Select"
+          note="Combobox 永遠多選——單選塞進來使用者每次要手動先移除舊 Tag 再選新的，多餘的互動"
+        >
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} aria-label="商品分類(單選反例——應改用 Select)" />
+          <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={() => {}}
+            aria-label="同意項目"
+          />
+          <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={() => {}}
+            aria-label="部門"
+          />
+          <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} aria-label="商品分類(單行溢出範例)" />
+          <Label>↑ 單行：高度固定，超出的 Tag → +N</Label>
+        </Rule>
+
+        <Rule
+          title="多行 wrap — 空間充裕的 Form"
+          note="高度隨選中數量展開，每個 Tag 都完整可見。適合填答型表單——使用者一眼看到所有選項，不需 hover 溢出指示器"
+        >
+          <Combobox wrap options={categoryOptions} value={wrapped} onChange={setWrapped} aria-label="商品分類(多行 wrap 範例)" />
+          <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} aria-label="商品分類(Tag 移除範例)" />
+          <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={() => {}} aria-label="商品分類(已選項打勾範例)" />
+          <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} aria-label="商品分類(+N 溢出指示範例)" />
+          <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

@@ -12,30 +12,40 @@ benchmark:
   - 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）。
+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 連續一致。
+**Layout Family**：本元件是 `components/Field/field-controls.spec.md` 所擁有的 **Family 4（Field control layout）** 消費者。結構繼承其 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
 
 ---
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+本元件刻意採 **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 Design DatePicker / Material MUI Select 皆支援 dual-mode;我們選 controlled-only 對齊狀態一致性優先 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- 本 API 目前採 controlled-only；query、value 與 async options 的 ownership 由 consumer 明確持有，避免元件內外同時維護來源不明的選取狀態
 
-**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
+**若未來要改 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。
 
 ---
 
@@ -88,6 +98,8 @@ Combobox 是**多選下拉**的輸入與顯示元件。選中值以 Tag 陣列
 
 每個 Tag 有 dismiss 按鈕（X），點擊移除該選項。
 
+Keyboard focus 在移除後依序交給下一個可見 Tag remove button；沒有下一個則前一個；最後一個移除後回 owner select/combobox trigger。焦點不可因 DOM unmount 掉到 `body`；PeoplePicker 的自訂 avatar Tag 亦走相同 `data-collection-remove` contract。
+
 ### 全部清除
 
 `clearable` 在有值時顯示 clear all 按鈕，一次清除所有選項。位於最右側，ChevronDown 左邊。
@@ -105,7 +117,7 @@ Combobox 是**多選下拉**的輸入與顯示元件。選中值以 Tag 陣列
 ## readonly / disabled 的 Tag
 
 - 沒有 dismiss 按鈕——不可操作
-- 沒有 ChevronDown——不可新增
+- ChevronDown:**readonly 不顯示**(純值、不可開下拉)/ **disabled 保留**(類型身份 indicator,`fg-disabled`,`pointer-events-none`)/ naked cell 依 `showDisplayEndIcon`(2026-06-26)
 - 沒有 clear 按鈕——不可清除
 - 溢出行為與 edit 模式相同（+N 指示器）
 
@@ -113,7 +125,7 @@ Combobox 是**多選下拉**的輸入與顯示元件。選中值以 Tag 陣列
 
 ## 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 -->
+`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補;措辭對齊 `select.spec.md`「Loading」2026-07-04 Q3 拍板 — 不清空 stale options):spinner 只在**無可顯示選項時**佔 empty slot 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(cmdk `CommandEmpty` 機制;已有 options 時保留顯示,不取代)。Trigger 不變,user 隨時可開。這可保留仍可選的 stale options，同時只在沒有內容可呈現時讓 loading 佔據 empty slot。
 
 ---
 
@@ -121,7 +133,7 @@ Combobox 是**多選下拉**的輸入與顯示元件。選中值以 Tag 陣列
 
 - **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 search results)**:dropdown body 內渲 `emptyText`(Combobox 暴露 `emptyText` prop 並 forward 給 SelectMenu;未傳時走 SelectMenu 預設「沒有符合的選項」)。Combobox **暴露 `creatable` / `onCreate` / `createLabel` prop 並 forward 給 SelectMenu**(2026-07-18 user 拍板;搜尋非空且無完全同名既有選項時,dropdown 顯 create row `Plus + createLabel`)——邏輯/顯示/互動 SSOT 住在 SelectMenu(`select-menu.tsx` :271-275 顯隱 / render)。僅 searchable 桌機路徑生效(native mobile 不支援)。對齊 Ant tags / react-select Creatable。
 - **Empty(no value selected)**:multi mode `value=[]` 時 trigger 顯 placeholder(如「請選擇」);empty state 不渲 tag 區。
 - **Dark mode / density**:走 Field + SelectMenu SSOT 自動 adapt。
 
@@ -134,29 +146,44 @@ Combobox 是**多選下拉**的輸入與顯示元件。選中值以 Tag 陣列
 - multi mode 可附 `min` / `max` selected count 限制(consumer 自驗,Combobox 不獨立 own validation rules)
 - Validation timing:預設 onBlur + onSubmit,onChange 不立即 validate(避免邊選邊紅)
 
+## Ref 契約(cross-mode 例外,2026-07-17 user 拍板)
+
+Combobox 是 **4-mode field**(edit / view / readonly / disabled),各 mode 渲染**本質不同的 subtree**(edit = trigger + hidden select;view/readonly = `ReadonlyMultiSelect`)。**`ref` 只保證在 edit mode 指向 trigger root(`__triggerRef`)**;view / readonly / disabled mode **不保證穩定 root**(對齊 React「avoid over-exposing DOM nodes in higher-level components」)。需在任意 mode 取穩定 DOM root 的 consumer 應在外層自包一層容器,不依賴 Combobox `ref` 跨 mode 一致。與 T1 RadioGroup / Switch 的跨 mode 缺口採同一哲學(記錄例外,不硬造統一 host)。
+
 ---
 
 ## 禁止事項
 
 - ❌ 不在已選中的選項上再顯示 dismiss 以外的互動——Tag 只能被移除，不能被編輯或重新排序
 - ❌ 溢出指示器 `+N` 不可省略——使用者需要知道有多少被隱藏的項目
-- ❌ 不自建 dropdown——使用原生 `<select>` 保證無障礙
+- ❌ 不破壞「單一鍵盤聚焦點 + 多滑鼠點擊區」雙路徑無障礙——桌機浮層選單（`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-[var(--field-px)]` 路徑,`people-picker.tsx:371`),保留供未來精準 padding 但新 consumer 請先評估。`overflowShape` 是 public typed enum(矩形/圓形 +N),不在此列。
 
 ---
 
 ## A11y 預設
 
-### 鍵盤可達性的 delegation 設計
+### 鍵盤可達性的雙路徑設計
+
+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。
 
-Combobox 內部結構有多個 `<div>` / `<Tag>` 帶 `onClick`（tag 容器、ChevronDown 區域、搜尋輸入 wrapper 等）——**這些是 mouse 優化的 click-path delegation，不是鍵盤介面**。鍵盤路徑由**隱藏的 native `<select>`** 處理（tab-focusable，Enter/Space 開啟，arrow 導覽，Esc 關閉）。
+**Display 層雙分支同 SSOT(2026-08-05 修)**:NativeCombobox 的 OverflowTagList 消費與 CustomCombobox **同一組** renderer / overflow props(`tagRenderer` / `renderHiddenTag` / `tagWrapperClassName` / `overflowWrapperClassName` / `overflowShape` / `visibleCountOverride` / `tagAreaGapPx` / `tagAreaPaddingLeftPx`)——`tagRenderer` 存在(如 PeoplePicker avatar stack)時手機 edit 與桌機同視覺;未傳維持原 `<Tag>` 文字 pill 預設。先前 native 硬編碼 `<Tag>`,PeoplePicker 手機 edit 掉回文字 pill = touch 分支漏接 display 層(canonical 違反)。**Root invariant:新增 renderer-affecting prop 必同步 NativeCombobox destructure。** 疊層契約:renderer 輸出經「relative z-10(抬到透明 `<select>` overlay 之上)+ pointer-events-none(非互動區 tap 穿透喚起原生 picker)+ `[&_button]`:pointer-events-auto(remove 鈕回收點擊)」三件套包裝;+N wrapper 同抬升且 pointer 穿透(touch 的 overflow 檢視/增刪走原生 picker 本身)。
 
-**設計取捨**:
-- ✅ **好處**: 保留原生 `<select>` 的完整 a11y（包含 mobile screen reader + 語音輸入 + 所有 OS-level 整合）
-- ⚠️ **後果**: 非 button 元素帶 `onClick` 是 mouse-only 互動,鍵盤使用者不經過它們——但他們也不需要（native select 路徑涵蓋所有功能）
+兩條路徑共通點：欄位內多個 `<div>` / `<Tag>` 上的 `onClick` 是 mouse 優化的點擊區，**不是鍵盤介面**——鍵盤使用者不經過它們，但兩條路徑都已各自提供完整鍵盤可達性。
 
-**為什麼不 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 共識）。
+**為什麼這些 click target 不加 `role="button" tabIndex`**: 若每個點擊區都加 `tabIndex={0}` 會搶走真正聚焦目標（桌機的 combobox 容器 / 手機的原生 select）的 tab focus，反而破壞鍵盤體驗。「單一鍵盤聚焦點 + 多個滑鼠點擊區」是混合型控制項的世界級 canonical pattern（Material / Atlassian / GitHub issue filter 共識）。
 
 **結論**: Combobox 多處 `onClick` 在非 button 元素上**是經過評估的 acceptable a11y 模式**,不是需要修復的 bug。
 
@@ -174,7 +201,9 @@ Combobox 內部結構有多個 `<div>` / `<Tag>` 帶 `onClick`（tag 容器、Ch
 
 > 本節由 `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,194 @@
+// @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 { expect, userEvent, waitFor, within } from '@storybook/test'
+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 { Field, FieldError, FieldLabel } from '@/design-system/components/Field/field'
+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'],
+  parameters: {
+    docs: { description: { component: '可搜尋並選取一個或多個選項，已選值以 tag 或摘要呈現。選項很多、需要篩選或多選時使用；少量單選且不需搜尋時優先用 Select。' } },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Combobox>
+
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => {
+    const [value, setValue] = React.useState(['electronics', 'food', 'lifestyle'])
+    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)" />
+          <Button variant="text" size="xs" onClick={() => setValue(['electronics', 'food', 'lifestyle'])}>重設編輯模式</Button>
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+          <Combobox mode="view" options={categoryOptions} value={value} aria-label="類別(view 模式示範)" />
+        </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>
+    )
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    await userEvent.click(await canvas.findByRole('button', { name: '移除 Electronics' }))
+    await waitFor(() => expect(canvas.getByRole('button', { name: '移除 Food' })).toHaveFocus())
+    await userEvent.click(canvas.getByRole('button', { name: '移除 Food' }))
+    await waitFor(() => expect(canvas.getByRole('button', { name: '移除 Lifestyle' })).toHaveFocus())
+    await userEvent.click(canvas.getByRole('button', { name: '移除 Lifestyle' }))
+    await waitFor(() => expect(canvas.getByRole('combobox', { name: '類別(edit mode demo)' })).toHaveFocus())
+    await userEvent.click(canvas.getByRole('button', { name: '重設編輯模式' }))
+  },
+}
+
+function ComboboxErrorExample() {
+  const [value, setValue] = React.useState<string[]>([])
+  return (
+    <Field required invalid={value.length === 0} className="max-w-sm">
+      <FieldLabel>商品類別</FieldLabel>
+      <Combobox
+        options={categoryOptions}
+        value={value}
+        onChange={setValue}
+        searchable
+        aria-label="商品類別"
+        placeholder="選擇至少一個類別"
+      />
+      {value.length === 0 && <FieldError>請至少選擇一個商品類別</FieldError>}
+    </Field>
+  )
+}
+
+export const WithError: Story = {
+  name: '驗證錯誤',
+  render: () => <ComboboxErrorExample />,
+}
+
+/* ── 尺寸與 Button 對齊 ── */
+export const SizeAlignment: Story = {
+  name: '三種尺寸',
+  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" aria-label={`商品分類(size=${size})`} />
+            <Button variant="primary" size={size}>送出</Button>
+            <span className="text-caption text-fg-muted">size="{size}"</span>
+          </div>
+        ))}
+      </div>
+    )
+  },
+}
+
+// @story-history: 原 WrapModes(單行 vs 換行)retired 2026-07-17(Dim 24 earn-existence)—
+//   單行/wrap × edit/readonly 矩陣已由 anatomy「狀態行為」(單行溢出 + readonly 溢出 + edit/readonly wrap)
+//   完整覆蓋機制,wrap 選擇原則由 principles「Wrap 模式選擇」(WrapRule)owns。展示層不重演矩陣(三層定位);
+//   principles 使用指引頁對應 LinkTo(單行 vs 換行)同步移除。
+
+/* ── 搜尋 ── */
+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>
+    )
+  },
+}