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

package/src/components/Select/select.principles.stories.tsx

@@ -0,0 +1,312 @@
+// @principles-rationale: Merged WhenToUse + WhenNotToUse(已是 vs 近親 — RadioGroup /
+// SegmentedControl / Combobox / Switch)into a single `UsageGuidance` story (3 sections)
+// per 2026-04-26 user mandate. DisplayModeRule / ImmediateVsSubmitRule / SearchableRule
+// / NativeSelectRule kept as separate principles.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Flag } from 'lucide-react'
+import { Select } from './select'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+
+const meta: Meta = {
+  title: 'Design System/Components/Select/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+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-xs">{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 statusOptions = [
+  { value: 'in_stock', label: 'In stock', tagVariant: 'green' },
+  { value: 'low_stock', label: 'Low stock', tagVariant: 'yellow' },
+  { value: 'out_of_stock', label: 'Out of stock', tagVariant: 'red' },
+]
+
+const categoryOptions = [
+  { value: 'electronics', label: 'Electronics' },
+  { value: 'furniture', label: 'Furniture' },
+  { value: 'food', label: 'Food' },
+]
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [status, setStatus] = React.useState('in_stock')
+    return (
+      <div>
+        <Section title="何時用">
+          <div className="prose prose-sm max-w-prose">
+            <p>適合 Select 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+            <ul className="space-y-1">
+              <li>
+                <LinkTo kind="Design System/Components/Select/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">四模式</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Components/Select/展示" name="三種尺寸"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Components/Select/展示" name="建立新選項"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">建立新選項</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Components/Select/展示" name="可清除"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">可清除</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Components/Select/展示" name="搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋</span></LinkTo>
+              </li>
+            </ul>
+            <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>
+          </div>
+        </Section>
+
+        <Section title="何時不用 + 替代">
+          <Rule
+            title="Select 的 sweet spot — 3+ 選項、空間受限、不需一眼全看"
+            note="表單欄位、toolbar filter、table cell。使用者先看 label,點開才瀏覽選項"
+          >
+            <Select display="tag" options={statusOptions} value={status} onChange={setStatus} />
+          </Rule>
+
+          <Rule
+            title="❌ 多選:用 Combobox"
+            note="Select 永遠單選。需要多選(categories、tags、assignees)必須用 Combobox"
+          >
+            <Select options={categoryOptions} value="electronics" onChange={() => {}} />
+            <Label warn>↑ 需要「同時選 Electronics + Furniture」就不能用 Select</Label>
+          </Rule>
+
+          <Rule
+            title="❌ 布林 on/off:用 Switch"
+            note="on/off 不需要「選一個」的心智模型。Switch 視覺直接表達開關狀態,一次點擊完成切換"
+          >
+            <Select
+              options={[{ value: 'on', label: 'On' }, { value: 'off', label: 'Off' }]}
+              value="on"
+              onChange={() => {}}
+            />
+            <Label warn>↑ On/Off 用 Select → 多餘的 dropdown 互動、不如 Switch 直觀</Label>
+          </Rule>
+        </Section>
+
+        <Section title="vs 近親 — Select / RadioGroup / SegmentedControl / Combobox">
+          <Rule
+            title="❌ 決策節點(使用者需要對比評估):用 RadioGroup"
+            note="付款方式、訂閱方案、票種、權限角色——使用者必須看完所有選項才能決定,通常連帶 description / 價格 / feature list。RadioGroup 全露選項支援對比;Select 把選項藏起來,強迫使用者打開 → 讀 → 收起 → 再打開才能比較。判準不是數量,是「選擇本身是不是決策動作」,完整對照見 select.spec.md 的「與 RadioGroup 的分界」"
+          >
+            <Select
+              options={[
+                { value: 'credit', label: '信用卡(手續費 2.5%,即時)' },
+                { value: 'bank', label: '銀行轉帳(無手續費,1-2 工作日)' },
+                { value: 'cash', label: '貨到付款(手續費 NT$30,到貨時付)' },
+              ]}
+              value="credit"
+              onChange={() => {}}
+            />
+            <Label warn>↑ 付款方式是決策節點 + 需要對比手續費 / 處理時間 → 用 RadioGroup 讓選項全露</Label>
+          </Rule>
+
+          <Rule
+            title="❌ 緊湊切換 / filter:用 SegmentedControl"
+            note="SegmentedControl 是 compact control(pill 尺寸),能跟 Button / Input 並排不違和。適合 toolbar 的 view mode、filter tab、chart 時間維度切換。詳見 segmented-control.spec.md"
+          >
+            <Select
+              options={[
+                { value: 'all', label: '全部' },
+                { value: 'active', label: '進行中' },
+                { value: 'done', label: '已完成' },
+              ]}
+              value="active"
+              onChange={() => {}}
+            />
+            <Label warn>↑ Toolbar filter 放 Select → 佔空間、視覺重量比旁邊 Button 重</Label>
+          </Rule>
+        </Section>
+      </div>
+    )
+  },
+}
+
+export const DisplayModeRule: Story = {
+  name: '顯示模式選擇',
+  render: () => {
+    const [category, setCategory] = React.useState('electronics')
+    const [status, setStatus] = React.useState('in_stock')
+    const [badExample, setBadExample] = React.useState('in_stock')
+    return (
+      <div>
+        <Rule
+          title="plain — 純文字選項(預設)"
+          note="選項沒有色彩語意、僅靠文字就能識別時使用。常見場景:類別、地區、語言、角色等"
+        >
+          <Select options={categoryOptions} value={category} onChange={setCategory} />
+        </Rule>
+
+        <Rule
+          title="tag — 需要色彩識別的選項"
+          note="選項帶有類別或狀態語意,顏色能加速掃視(庫存狀態、優先級、標籤)。options 裡用 tagVariant 指定顏色,edit / readonly / disabled 都用同一顆 Tag 呈現"
+        >
+          <Select display="tag" options={statusOptions} value={status} onChange={setStatus} />
+        </Rule>
+
+        <Rule
+          title="❌ tag 模式不加 startIcon"
+          note="Tag 本身就是視覺標記(顏色 + 形狀),再加 startIcon 是雙重傳達——視覺冗餘且爭奪焦點"
+        >
+          <Select
+            display="tag"
+            startIcon={Flag}
+            options={statusOptions}
+            value={badExample}
+            onChange={setBadExample}
+          />
+          <Label warn>↑ 左側 Flag icon 和右邊 Tag 都在傳達「這是狀態」——去掉 startIcon</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const ImmediateVsSubmitRule: Story = {
+  name: '即時套用 vs 隨表單送出',
+  render: () => {
+    const [immediate, setImmediate] = React.useState('in_stock')
+    const [draft, setDraft] = React.useState('electronics')
+    return (
+      <div>
+        <Rule
+          title="即時套用 — onChange 直接觸發副作用"
+          note="Jira status、Linear priority、filter、theme 切換。改了立刻寫 DB / 送 API / 改 URL。onChange 通常呼叫 mutation 或 setState 更新父層。沒有「取消」的概念"
+        >
+          <div>
+            <p className="text-caption text-fg-muted mb-1">Task status(改了立刻寫 DB)</p>
+            <Select display="tag" options={statusOptions} value={immediate} onChange={setImmediate} />
+          </div>
+          <Label>↑ 視覺上是獨立的 inline control,旁邊沒有 submit button</Label>
+        </Rule>
+
+        <Rule
+          title="隨 form 送出 — onChange 只更新 local state"
+          note="建立/編輯表單、對話框設定。onChange 寫進 React state,直到 submit button 被按才送出。有「取消」可回復"
+        >
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <Field>
+              <FieldLabel>Category</FieldLabel>
+              <Select options={categoryOptions} value={draft} onChange={setDraft} />
+            </Field>
+            <div className="flex gap-2 pt-2">
+              <button className="h-field-md px-3 text-body rounded-md bg-primary text-inverse-fg">儲存</button>
+              <button className="h-field-md px-3 text-body rounded-md border border-border">取消</button>
+            </div>
+          </div>
+          <Label>↑ 包在 Form 容器內 + submit / cancel button,使用者清楚儲存時機</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 讓使用者搞不清楚是哪種"
+          note="最常見的失敗:inline 放一個 Select 但 onChange 只改 local state,旁邊卻沒有 submit button。使用者以為改了就套用,離開頁面才發現沒存。這是 DS 最常見的信任破壞點"
+        >
+          <Select options={categoryOptions} value={draft} onChange={setDraft} />
+          <Label warn>↑ 沒有 Form 容器、沒有 submit button、又是獨立的 inline control——使用者無法判斷是即時還是要送出</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const SearchableRule: Story = {
+  name: '可搜尋 開啟判斷',
+  render: () => (
+    <div>
+      <Rule
+        title="主判準:label 性質——獨特關鍵字 / 代碼 / 非自然語言 → 開 searchable"
+        note="使用者無法靠眼睛或 type-to-jump 快速定位時才需要搜尋。產品代碼(SKU-4837)、機場代碼(TPE / NRT)、使用者 ID、ticket number——這類 label 沒有記憶點,必須輸入才能找"
+      >
+        <Select
+          searchable
+          options={[
+            { value: 'sku-4837', label: 'SKU-4837' },
+            { value: 'sku-8210', label: 'SKU-8210' },
+            { value: 'sku-9104', label: 'SKU-9104' },
+          ]}
+          value="sku-4837"
+          onChange={() => {}}
+        />
+        <Label>↑ 即使只有 3 個選項,產品代碼 label 仍需要 searchable</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 流暢自然語言 label:不開 searchable"
+        note="Electronics / Furniture / Food 這類 label 短清單一眼可掃(手機原生 select 另有 type-to-jump 直達;桌機自建 combobox 無逐字定位,但掃視已夠快)。多加 searchable 等於多一層不必要的互動"
+      >
+        <Select
+          searchable
+          options={categoryOptions}
+          value="electronics"
+          onChange={() => {}}
+        />
+        <Label warn>↑ 3 個自然語言 label 加 searchable → 使用者必須打字或再點擊才能選</Label>
+      </Rule>
+
+      <Rule
+        title="次要啟發:數量 > 50 幾乎必開(但仍看 label 性質)"
+        note="100 個依字母排序的國家名不需要搜尋(自然語言掃視快,手機原生 select 還有 type-to-jump 直達),5 個產品代碼(SKU-4837)反而需要搜尋。純數量 threshold 會誤判這兩端,詳見 spec"
+      >
+        <Label>判斷優先序:label 性質 → 數量次要啟發</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const NativeSelectRule: Story = {
+  name: '桌機自建選單 vs 手機原生選擇器',
+  render: () => {
+    const [value, setValue] = React.useState('electronics')
+    return (
+      <div>
+        <Rule
+          title="依裝置自動切換兩種實作"
+          note="Select 偵測觸控裝置自動選路:桌機(非觸控)用自建選單——觸發點是一個可聚焦的容器,點開後在浮層裡顯示選項清單,支援搜尋與群組;手機(觸控)改用瀏覽器原生的 <select>,直接叫出作業系統內建的滾輪 picker。同一份 options 兩邊共用,consumer 不需分平台寫兩套。"
+        >
+          <Select options={categoryOptions} value={value} onChange={setValue} />
+          <Label>↑ 桌機這顆是自建選單(點開看浮層);切到手機模擬器會變成系統原生 picker</Label>
+        </Rule>
+
+        <Rule
+          title="tag 模式只是把選中值畫成 Tag,行為跟 plain 一樣"
+          note="tag 與 plain 的差別只在「選中值怎麼呈現」——tag 用一顆有顏色的 Tag,plain 用純文字。底層的開選單、選值、鍵盤行為兩種模式完全相同,都走上面那套依裝置切換的路徑。"
+        >
+          <Select display="tag" options={statusOptions} value="in_stock" onChange={() => {}} />
+          <Label>↑ 點這顆 Tag 會打開選單;桌機是自建浮層,手機是系統原生 picker</Label>
+        </Rule>
+      </div>
+    )
+  },
+}

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

@@ -13,17 +13,50 @@ benchmark:
   - 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. -->
+<!-- @spec-budget-exception: SSOT-heavy 例外(`AGENTS.md`「行數預算」的 foundational SSOT 例外 ≤800-1200)— 本檔持有跨元件 SSOT:「與 RadioGroup 的分界」(~40 行)+ 3 筆拍板記錄(2026-07-13 D2 hidden-input mirror / 2026-05-21 D3 dual-mode / 2026-06-12 R2 open-pair 例外);2026-07-14 knowledge-prune P2 結論「殘餘超標內容全是 canonical,再砍必動 meaning」(.claude/logs/prune-p2-candidates.md)。 -->
 
 # Select 設計原則
 
 ## 定位
 
-Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個，選項收在 dropdown 內展開。底層走原生 `<select>`，透過 CSS 客製視覺。
+> 寬度軸:`width="fill|hug"`(default fill;hug = 依內容收縮,detail pane inline metadata 用)— SSOT → `Field/field-controls.spec.md`「寬度軸(width: fill / hug)」。
+
+Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個，選項收在 dropdown 內展開。**裝置自適應雙路徑**:觸控裝置(`pointer: coarse`)走原生 `<select>` 取平台原生 picker;桌機走自建 combobox(`role="combobox"` + Radix Popover + Command 渲染 SelectMenu)。詳下方「實作:裝置自適應雙路徑」段。
 
 共用規則見 `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 連續一致。
+**Layout Family**：本元件是 `components/Field/field-controls.spec.md` 所擁有的 **Family 4（Field control layout）** 消費者。結構繼承其 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+## 實作：裝置自適應雙路徑
+
+`Select` public component 在 render 時用 `useIsTouchDevice()`（內部 `matchMedia('(pointer: coarse)')`）分流（`select.tsx`）：
+
+| 裝置 | 路徑 | 實作 | 為什麼 |
+|---|---|---|---|
+| 觸控（`pointer: coarse`，手機 / 平板）| `NativeSelect` | 真原生 `<select>` + CSS 客製 trigger | 行動裝置的原生 picker（iOS wheel / Android dialog）是平台最佳 a11y + 操作體驗，自建選單無法取代 |
+| 桌機（精確指標）| `CustomSelect` | 自建 combobox（`role="combobox"` + Radix Popover + Command + SelectMenu）| 桌機需可控渲染：搜尋輸入、選項內頭像 / 描述 / 分組、自訂鍵盤導覽——原生 `<select>` 都做不到 |
+
+**此分流是「裝置」軸，與 `searchable` 正交**：`searchable` 只決定桌機 combobox 的 trigger 要不要顯搜尋輸入框，**不**決定走原生還是 combobox。一個不可搜尋的桌機 Select 仍是完整自建 combobox（可捲動 / 點選，只是沒搜尋框）。
+
+### 原生表單參與(desktop hidden input mirror,2026-07-13 D2 拍板)
+
+`name` / `required` / `form` 在型別 allowlist 內(`SelectProps` 以 `Pick<SelectHTMLAttributes>` 顯式允收,2026-07-14 API 策展 D),兩路徑提交語義必須一致(歷史上桌機靜默丟棄 name、mobile 生效 — 此不對稱從未被拍板,屬 footgun,2026-07-13 修):
+
+| 路徑 | 機制 |
+|---|---|
+| 觸控(NativeSelect)| 真原生 `<select>`,`name` / `required` / `form` 直接生效 |
+| 桌機(CustomSelect)| **visually-hidden `<input>` 鏡像**(`aria-hidden` + `tabIndex={-1}` + opacity-0,絕對定位於 trigger 內):`value` 單向鏡射受控 state,`name` / `form` forward → 裸 `<form>` submit 收得到值;顯式 `required` prop forward → 原生 required 擋 submit |
+
+**設計規則**:
+
+- **型別 = allowlist,不 extends 全開(2026-07-14 API 策展 D,user 拍板「全部收窄」)**:`SelectProps` 只 `Pick<>` 兩路徑皆有實作出口的原生屬性(`id`/`className`/`style`/`name`/`form`/`required`/`disabled`/`onFocus`/`onBlur`/`onKeyDown`/`aria-label`/`aria-describedby`/`aria-errormessage` + mobile-only `autoFocus`/`autoComplete` + `data-*` passthrough);「型別承諾 ≠ 實作出口」者(`multiple`/`aria-labelledby`/`tabIndex` 等)不進型別,需要時先接線(兩路徑等效)再入表 — 完整盤點依據見 `select.tsx` SelectProps docblock
+- **單向 projection,非第二 SSOT(M17)**:mirror 的 value 恆來自既有 canonical state(`useControllable`);唯一寫回通道是瀏覽器 autofill,且僅在 match 既有非 disabled option 時經 canonical setter 生效(MUI SelectInput 同款 guard)
+- **空值 = `value=''`**:無選擇時送空字串,**不** default 第一項——採 MUI 式**單一 hidden input**而非 Radix BubbleSelect 完整 `<select>` option tree(後者無空 option 時 default 第一項,radix-ui/primitives issue #3521 documented footgun;2026-07-13 codex 辯論 verdict)
+- **原生 required 僅收顯式 `required` prop**(裸表單 opt-in):`<Field required>` 的 context required 續走 `aria-required` + `useFormValidation`(RHF)方法論(`form-validation.spec.md` 規則 1-9),不對既有 Field+RHF consumer 注入瀏覽器原生 bubble
+- **a11y 不變**:mirror `aria-hidden` + 不入 Tab 序,semantics 仍由 `role="combobox"` trigger own;顯式 `required` prop 同步進 trigger `aria-required`(對齊 mobile 原生 `<select required>` 播報)
+- **副作用(升級)**:`useFormValidation` 規則 8(focus-first-error 以 DOM name 定位)桌機 Select 現在可被定位——focus 落 mirror → trigger `focus-within` 顯示 focus 邊框,不再落入「非 native 控件略過」fallback
+
+**世界級對照**:MUI Select 非原生模式同步 opacity-0 hidden input 攜 `name`/`required`(官方測試涵蓋 required 阻止提交 + FormData 值,[github.com/mui/material-ui Select.test.js](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Select/Select.test.js))/ React Spectrum [HiddenSelect](https://github.com/adobe/react-spectrum/blob/main/packages/%40react-aria/select/src/HiddenSelect.tsx) / Headless UI Listbox `name` → [hidden input kept in sync](https://headlessui.com/react/listbox#using-with-html-forms)。Ant 走純 Form.Item(React state)派;本 DS 因型別已承諾 `name`/`form`/`required`,「同一 public API 依裝置改變提交語義」比補 projection 更危險(codex verdict),故補鏡像。
 
 ---
 
@@ -33,24 +66,11 @@ Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個
 
 ### 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。
+傳 `value` + `onChange`(如 `<Select value={country} onChange={setCountry}>`),Select **不**自管 state。**何時用**: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 當前值。
+不傳 `value`(可傳 `defaultValue` 設初始值,如 `<Select defaultValue="tw" onChange={...}>`),Select 內部自管,變更時 fire `onChange` 通知 consumer。**何時用**:純展示 / 一次性表單 submit / consumer 不需要 read 當前值。
 
 ### 為什麼支援 dual-mode(非 controlled-only)
 
@@ -60,8 +80,17 @@ const [country, setCountry] = useState('tw')
 
 ### 歷史
 
-- **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)`
+原刻意 controlled-only(「內部狀態複雜易 race」);**2026-05-21 D3 audit** per Dim 26 verify + user 拍板(「決策三照妳建議」)補 `defaultValue` + 互斥 signal — NativeSelect / CustomSelect 統一走既有 `useControllable` hook,`valueProp !== undefined` 為 controlled signal(M17 SSOT)。
+
+### Open-pair 例外:open 軸維持 uncontrolled-only(2026-06-12 deep-audit R2 補)
+
+value 軸 dual-mode,open 軸**刻意只有** `defaultOpen`(初始開)+ `onOpenChange`(通知 callback),無 controlled `open` prop:
+
+- **已知需求只要「初始開 + 知道何時關」**:(1) 視覺快照 — Storybook OpenSnapshot / visual-audit(M15)需「免互動即開」state,`defaultOpen` 一行達成;(2) DataTable cell-as-input(`DataTable/cell-registry.tsx`)— click → 1-step 開選單靠 `defaultOpen`,dismiss 後 `onOpenChange(false)` → cell exit edit mode
+- **受控成本高**:open 是內部 interaction state machine 的一環 — 關閉自動清 search(select.tsx「關閉時清搜尋」effect)/ searchable trigger 在 open 時切 input 顯示模式 / Enter / Space / ArrowDown opener + Esc dismiss 全是內部 intent。controlled `open` 要 consumer 忠實 echo 每一條,漏接任一 → 卡開 / 卡關 / 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 軸走既有 `useControllable` hook(M17 SSOT)+ 測 controlled↔uncontrolled switch,屬 major API 擴充,目前不在 scope。
 
 ---
 
@@ -71,7 +100,7 @@ const [country, setCountry] = useState('tw')
 - **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 快速定位
+- **選項 10+ 且不需搜尋**：時區、國家這類使用者熟悉的清單，靠捲動瀏覽即可定位（type-to-jump 逐字定位只有手機原生 `<select>` 才有；桌機是自建 combobox，非搜尋模式無逐字定位，選項偏多時建議直接開 searchable）
 
 ## 何時不用
 
@@ -171,10 +200,10 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
   - 郵遞區號、機場代碼（TPE / NRT / JFK）
   - 使用者 ID、專案 slug、ticket number
   - 中文姓名（同姓大量集中，字母跳不動）
-- ❌ **不需要 searchable**：label 是流暢自然語言、品類名稱，native select 的 type-to-jump 就夠用
+- ❌ **不需要 searchable**：label 是流暢自然語言、品類名稱，且選項數量在捲動可輕鬆掃完的範圍
   - `Electronics`、`Furniture`、`Food`
   - `Draft` / `In progress` / `Done`
-  - 國家英文名（按首字母跳夠快）
+  - 國家英文名（清單不長時捲動即可；注意桌機自建 combobox 無逐字定位，國家這類長清單仍建議開 searchable）
 
 ### 次要啟發：選項數量
 
@@ -186,11 +215,19 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 ### 為什麼不用純數量 threshold
 
-- 100 個 `a` / `b` / `c` / ... 不需要搜尋（native type-to-jump 直達）
+- 100 個 `a` / `b` / `c` / ... 因 label 有序好掃，捲動定位心智成本低（手機原生 `<select>` 另有 type-to-jump 加成；桌機若清單真的很長仍可開 searchable）
 - 5 個 `SKU-4837` / `SKU-8210` / ... 需要搜尋（使用者記不起哪個代碼對應哪個產品）
 
 純量化規則會誤判這兩端。label 性質是唯一可靠的主判準。
 
+### 建立新選項（`creatable`，2026-07-18 決策11）
+
+- `creatable` **需搭配 `searchable`**——搜尋字串非空且無完全同名既有選項時,dropdown 底部出現 create row(`Plus` icon + `createLabel`,預設「直接使用「{query}」」),點擊觸發 `onCreate(query)`。
+- **邏輯 / 顯示 / 互動 SSOT 住在 `SelectMenu`**(與 `Combobox.creatable` 同一底層):Select 的 trigger 內嵌搜尋 input 以**受控 `search`** 驅動 SelectMenu 的 create-row 顯隱(`SelectMenu.search` prop,選配受控;不傳 = 內部 uncontrolled,既有 consumer 零影響)。
+- `onCreate` 由 consumer 實作(通常:加進 options + 選取新值);create row 選取後 SelectMenu 清 search(受控時回呼 `onSearchChange`)。
+- **非 searchable 時無 create 通道**(沒有輸入處);`creatable` 單獨傳無效。
+- 何時用:label 是使用者自訂的自由文字集合(標籤 / 分類 / 專案名),清單非窮舉、允許擴充。何時不用:固定 enum(狀態 / 角色 / 國家)——不該讓使用者新增。
+
 ---
 
 ## 顯示模式（`display` prop）
@@ -202,20 +239,28 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 **命名 rationale**(2026-05-01 從 `'text'` 改 `'plain'`):跨元件 prop value 衝突防避 — `Button variant="text"` 表「無 chrome 文字按鈕」,跟 Select.display 的「純文字呈現」是兩個不同概念,共用 `'text'` 字面值會造成 consumer 認知衝突(命名三 test 第 3 條)。改 `'plain'` 後語意專屬:plain = 樸素文字呈現,對立 tag = 用 Tag 元件呈現。
 
+**`selectedItemRenderer` 優先於兩種顯示模式**(2026-07-08 A 案回歸修正):設定時已選值改渲 consumer renderer 輸出(status icon+text / PersonDisplay 等),且 **edit / view / readonly / disabled 4 mode 共享同一 renderer**(`field-controls.spec.md` 共享 contract (a),禁 edit-only)。renderer 輸出屬「值內容」— `mode="view"` 照常渲染(無 chrome 無 chevron);與 affordance(chevron/outline)分層見 `field.spec.md` L6。
+
+**雙分支同 SSOT(2026-08-05 修)**:觸控 NativeSelect edit 有值時同樣渲 renderer 輸出為可見層(native `<select>` 沿 tag 模式既有透明 overlay pattern,tap 開原生 picker;空值走原生 placeholder)——先前 native edit 只顯 option 純文字,PeoplePicker 手機單人因此無 avatar = touch 分支漏接 display 層(canonical 違反)。**Root invariant:display-layer renderer props 必雙分支(Custom/Native)同消費;新增 renderer-affecting prop 必同步 NativeSelect。**
+
 ### 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)
+- 桌面使用 custom trigger + SelectMenu；觸控裝置使用 NativeSelect 的純文字 + ChevronDown(`selectedItemRenderer` 設定時觸控同渲 renderer 輸出,見「雙分支同 SSOT」段)
+- **Icon-binding 矩陣**(icon kind canonical,2026-05-09 clarified):
+
+| Icon 角色 | Prop | 語意 | 色彩 | 優先序 |
+|---|---|---|---|---|
+| **Indicator icon**(field-level leading hint)| `startIcon` | 提示 field 類型 / 屬性(`Mail` / `Globe` / `Lock` / `Flag`),與選中值無關 | muted(對齊 `Input.startIcon` search-icon pattern)| 設定時恆顯,優先 |
+| **Value icon**(代表選中項)| `option.icon`(per-option)| 隨 selected option 變動 | fg-default(對齊 `MenuItem.startIcon` 跨元件 SSOT)| `startIcon` unset 時 fallback |
+
+兩 prop 不互斥——同時設定時 `startIcon` 勝(渲染分支見 `select.tsx`)。
 
 ### tag 模式
 
-- Tag 元件呈現選中值 + 隱藏的原生 select overlay
-- Tag 設為 `pointer-events-none`，點擊穿透到底層 select
+- 桌面使用 Tag 呈現選中值並由 custom trigger 開啟 SelectMenu；觸控裝置才在 Tag 上疊隱藏的 native select overlay
+- 觸控 overlay 路徑的 Tag 設為 `pointer-events-none`，點擊穿透到底層 select
 - edit 模式：Tag + ChevronDown + 可選 clear
-- readonly / disabled：Tag 只顯示，無 ChevronDown
+- readonly：Tag 顯示，**ChevronDown 不顯示**（純值、不可開選單）；disabled：Tag 顯示 + **ChevronDown 保留**（類型身份 indicator，fg-disabled），不可開選單
 
 ---
 
@@ -248,14 +293,23 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 ## 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 -->
+`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補;**2026-07-04 Q3 拍板措辭修訂 — 不清空 stale options**):spinner 只在**無可顯示選項時**佔 empty slot 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(cmdk `CommandEmpty` 機制;已有 options 時保留顯示,不取代)+ `aria-busy`。Trigger 不變(chevron 保留,user 隨時可開)。Benchmark 實查:MUI Autocomplete 官方逐字「shows the loadingText in place of suggestions **only if there are no suggestions to show**」/ Ant Select 清空是 consumer 自選(demo select-users.tsx setOptions([]))非元件行為 — 原「取代 options」是過度宣稱,code 行為即世界級共識。
+
+---
+
+## 邊界案例
+
+- **搜尋結果空**:dropdown 顯 `<Empty>`(`emptyText` 預設「沒有符合的選項」,可覆寫)——SSOT `select-menu.spec.md`
+- **disabled 選項**:`option.disabled` forward 至 menu item——不可點選,鍵盤導覽自動跳過(cmdk `aria-disabled` 行為)
+- **大量選項**:選單固定最大高度內捲動(`--menu-max-height` 預設 300px),無分頁 / 虛擬捲動——長清單開 `searchable`(見「Searchable 開啟判斷」)
+- **空值**:無選擇時顯 placeholder;「無選擇是有效狀態」場景開 `clearable`(見「Clearable」)
 
 ---
 
 ## 禁止事項
 
 - ❌ `startIcon` 不可用於 tag 模式——Tag 本身已有視覺標記，startIcon 是冗餘的
-- ❌ 不自建 dropdown menu——使用原生 `<select>` 保證無障礙和行動裝置體驗
+- ❌ 在**觸控裝置**自建 dropdown——手機 / 平板必走原生 `<select>`（平台 picker 的 a11y + 操作體驗最佳）；桌機才走自建 combobox（見「實作：裝置自適應雙路徑」）
 - ❌ 讓使用者搞不清楚是即時還是 on-submit——用 label / 按鈕位置明確傳達
 - ❌ 把「決策節點」選擇塞進 Select（付款方式、訂閱方案）——使用者需要對比評估，用 RadioGroup
 
@@ -279,15 +333,17 @@ Select 是 **Field Controls family 成員**——互動狀態(focus / invalid /
 
 ## A11y 預設
 
-**ARIA / Pattern**:native `<input>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+**ARIA / Pattern**:依裝置分兩條路徑。桌機(非觸控)觸發點是容器 `<div>`,標記 `role="combobox"` + `aria-expanded` / `aria-haspopup="listbox"`,選項在浮層 listbox 裡;searchable 模式時容器內另放可打字篩選的 `<input>`(開啟時實際聚焦的元素,accessible name 直接接在 input 本身:有 Field label 時 `aria-labelledby` 指向之、consumer `aria-label` 優先,兩者皆無時 fallback「搜尋選項」——與 Combobox 搜尋框 `searchAriaLabel` 同 canonical)。手機(觸控)改用瀏覽器原生 `<select>` element,直接取得作業系統內建的無障礙與 picker。兩路徑皆由 Field wrapper 補 `aria-invalid` / `aria-required` / `aria-describedby` / `aria-errormessage`。
 
 **Keyboard 行為**:
 
-- Tab — focus
-- 字母鍵 — 輸入
-- Esc — 清空(若 clearable + 有值)
+- Tab — 聚焦到觸發點
+- Enter / Space — 展開選單(searchable 模式則直接進入打字篩選)
+- ↓ — 選單關閉時亦可直接展開(APG combobox 展開鍵,與 Combobox 同 pattern;展開後不攔,讓方向鍵導覽選單)
+- ↑ / ↓ — 選單展開後在選項間移動
+- Esc — 關閉選單(清除值走右側 clear 按鈕,非 Esc)
 
-**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+**Focus**:DS focus 藍框(`focus-within:!border-primary`)由 Field wrapper 提供;手機原生 `<select>` 另有系統 focus ring。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -295,5 +351,9 @@ Select 是 **Field Controls family 成員**——互動狀態(focus / invalid /
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `checkbox.spec.md`
+- `combobox.spec.md`
+- `command.spec.md`
 - `people-picker.spec.md`
+- `radio-group.spec.md`
 - `select-menu.spec.md`