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

package/src/components/SelectMenu/select-menu.principles.stories.tsx

@@ -0,0 +1,107 @@
+// @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.
+// v3 canonical(2026-05-01):≥ 2 stories(UsageGuidance + CompositionRules)取代原
+// escape rationale,對齊 Polaris/Material/Ant 共識 internal primitive 仍應教 consumer pattern。
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+
+const meta: Meta = {
+  title: 'Design System/Internal/SelectMenu/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 SelectMenu 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="單選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">議題狀態欄位擇一指派(單選)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">數百人組織選負責人,輸入過濾(搜尋)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">工單同時貼多個標籤(多選)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選 + 搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">大量標籤庫中過濾並複選(多選 + 搜尋)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" 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="何時不用 + 替代方案">
+        <div className="prose prose-sm max-w-prose">
+          <p>SelectMenu 是 Internal primitive,被 Select / Combobox / PeoplePicker 消費。直接使用前先確認:</p>
+          <ul>
+            <li>結果寫回 form value(讀取已選)→ 透過 Select / Combobox 等 user-facing 元件消費,不直接用 SelectMenu</li>
+            <li>結果觸發某個 action(non-form)→ 用 Command 而不是 SelectMenu</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <div className="prose prose-sm max-w-prose">
+          <p>SelectMenu vs Command — 兩者都 keyboard-navigable + 搜尋,但 mental model 不同:</p>
+          <ul>
+            <li><strong>SelectMenu(本元件)</strong>—form-input dropdown;結果寫回 form value(read selected)</li>
+            <li><strong>Command</strong>—命令面板;結果是執行某 action(non-form)</li>
+          </ul>
+          <p className="text-fg-muted">判斷:結果回 form value → SelectMenu;結果觸發 action → Command。</p>
+        </div>
+      </Section>
+    </div>
+  ),
+}
+
+// ── CompositionRules — SelectMenu 三個 consumer pattern(對齊 Material Select / Polaris Combobox idiom)──────
+
+export const CompositionRules: Story = {
+  name: '組合規則',
+  render: () => (
+    <div>
+      <Section title="Pattern 1 — Select(static 單選 dropdown)">
+        <div className="prose prose-sm max-w-prose">
+          <p>已知選項清單 + 單選回 form → <LinkTo kind="Design System/Components/Select/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Select</span></LinkTo>(內部 SelectMenu + cmdk + MenuItem)。對齊 Material <code>Select</code> / Ant <code>Select</code> idiom。</p>
+          <ul>
+            <li>典型場景:Country picker / Status selector / Priority dropdown</li>
+            <li>判斷:選項 ≤ 20 + 不需搜尋 → Select(可選 searchable mode 啟用搜尋)</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="Pattern 2 — Combobox(多選 + 搜尋 + 可建立新值)">
+        <div className="prose prose-sm max-w-prose">
+          <p>多選 + 大量選項需搜尋 + 可創新 tag → <LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Combobox</span></LinkTo>。對齊 GitHub Label picker / Linear Multi-assignee / Notion Multi-select idiom。</p>
+          <ul>
+            <li>典型場景:Tag picker / Multi-assignee / Filter chips multi-value</li>
+            <li>單行模式自動接 OverflowIndicator(`+N`)避免 tag wrap</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="Pattern 3 — PeoplePicker(人員選擇 + Avatar 渲染)">
+        <div className="prose prose-sm max-w-prose">
+          <p>選人員(單 / 多)+ 渲染 avatar + 名稱 + role → <LinkTo kind="Design System/Components/PeoplePicker/展示" name="單人"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">PeoplePicker</span></LinkTo>。對齊 Slack mention / Linear assignee / Asana people-search idiom。</p>
+          <ul>
+            <li>典型場景:Task assignee / Document collaborator / Workspace member invite</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="禁止 — App code 直接消費 SelectMenu">
+        <div className="prose prose-sm max-w-prose">
+          <p>不可直接 <code>import &#123; SelectMenu &#125; from '@/design-system/...'</code> 在 app — 必透過 Select / Combobox / PeoplePicker 三個 user-facing wrapper 之一。如有特殊 dropdown 需求(這 3 個都不對),回 DS 開新 wrapper 而不是繞過抽象層。</p>
+        </div>
+      </Section>
+    </div>
+  ),
+}

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

@@ -0,0 +1,232 @@
+---
+component: SelectMenu
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - isInputLike
+  - isInternal
+benchmark:
+  - Polaris Listbox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Listbox
+  - Radix Select primitive: github.com/radix-ui/primitives/tree/main/packages/react/select
+  - MUI Material Select (controlled/uncontrolled API): mui.com/material-ui/api/select/
+  - Ant Design DatePicker (value/defaultValue API): ant.design/components/date-picker
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# SelectMenu 設計原則
+
+## 定位
+
+SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提供搜尋 + 鍵盤導覽 + 分組 + 可建立新選項，作為**選值類**元件的 internal primitive（不直接使用）。
+
+**實作基礎**：基於 cmdk（搜尋 / 鍵盤導覽）+ shadcn Popover（浮動容器）+ 消費 MenuItem primitive（item 佈局）。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## Controlled-only rationale(Dim 26)
+
+本元件刻意採 **controlled-only** 模式——**scope 限 value 軸**:value 軸走 `value` + `onValueChange`(型別宣告 optional、無 runtime 強制,但 internal 消費者 Select / Combobox / PeoplePicker 一律傳入),不支援 `defaultValue` uncontrolled fallback。open 軸自 2026-06-11 R2 起走 `useControllable` dual-mode(`open` + `defaultOpen` + `onOpenChange`,`select-menu.tsx:162-166`),不在 controlled-only 範圍。
+
+**為什麼**:
+- 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
+- Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
+- 世界級對照:Ant Design DatePicker(`value`「To set date」+ `defaultValue`「To set default date」,ant.design/components/date-picker)/ Material MUI Select(`value` controlled + `defaultValue`「Use when the component is not controlled」,mui.com/material-ui/api/select/)/ Radix Select(「Can be controlled or uncontrolled」`value`+`defaultValue`,radix-ui.com/primitives/docs/components/select)皆支援 dual-mode;我們選 controlled-only 對齊狀態一致性優先 <!-- @benchmark-cited: 2026-05-30 WebFetch 三家 API 實證 value+defaultValue dual-mode(MUI Select API / Ant DatePicker API / Radix Select),URL inline -->
+
+**若未來 value 軸要改 dual-mode**:DS 已有 `useControllable` helper(open 軸與 Select 皆已消費),另需測試 controlled↔uncontrolled switch 場景,屬 major API 擴充。
+
+---
+
+## 何時用 / 何時不用
+
+**SelectMenu 是 internal primitive**——不直接使用，透過外層選值元件消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| 人員選擇器（搜尋 + Avatar）| 用 `PeoplePicker`（內部消費 SelectMenu）|
+| 大量選項單選 + 搜尋 | 用 `Select` with `searchable`（內部會切換到 SelectMenu 模式）|
+| 大量選項多選 + 搜尋 | 用 `Combobox` with `searchable`（內部會切換到 SelectMenu 模式）|
+| 可建立新選項（creatable tag）| 用 `Combobox` + `creatable` prop |
+| 直接在 JSX 中用 `<SelectMenu>` | ❌ **禁止**——失去外層 Select / Combobox / PeoplePicker 的 Field 整合、trigger 行為、state 管理 |
+
+### 消費者
+
+- `../Select/select.tsx` — `searchable` 模式會切換到 SelectMenu 浮層（直接 import）
+- `../Combobox/combobox.tsx` — `searchable` 模式會切換到 SelectMenu 浮層（直接 import）
+- `../PeoplePicker/people-picker.tsx` — 人員選擇（永遠 searchable;**間接消費** — wrap Select / Combobox,不直接 import SelectMenu,見 `people-picker.spec.md`「實作基礎」）
+
+**常見誤解**:(1)「要下拉浮層就 import SelectMenu」— internal primitive,一律經 Select / Combobox / PeoplePicker 消費(見上表);(2)「SelectMenu = DropdownMenu」— SelectMenu 是**選值**(值留在 field),DropdownMenu 是**執行動作**(點完即關)— 分界 SSOT 見 `dropdown-menu.spec.md`「與 SelectMenu 的區別」。
+
+---
+
+## 架構
+
+```
+Popover（浮動容器，handle 展開 / 定位）
+  └─ Command（cmdk — 搜尋 + 鍵盤導覽）
+       ├─ 搜尋框（`CommandPrimitive.Input` raw cmdk + 自建 icon/min-h wrapper，非 DS `CommandInput`；searchable 模式時顯示；選項 > 5 時建議開啟）
+       ├─ CommandList（捲動區）
+       │    └─ CommandGroup（分組標題）
+       │         └─ MenuItem（選項 row，消費 item-layout）
+       └─ Footer（多選全選 checkbox，選填）
+```
+
+**定位**:SelectMenu 的 `sideOffset` 與 `align` 直接走 Popover canonical——`sideOffset=8` / `align` 跟隨 trigger 位置(見 `../Popover/popover.spec.md`「Align 對齊 canonical(跨浮層 SSOT)」)。SelectMenu 不自訂浮層定位規則。
+
+**視覺 vs 語意**(2026-04-20 精緻化):SelectMenu 的 **width 預設跟 trigger(input)同寬**(Radix trigger-width),此時 `start` / `end` 兩種 align 呈現視覺完全相同(popover 正好跟 input 貼合,左右邊緣對齊無差異)。但當 consumer 傳 `minWidth` 大於 input 寬度(例:長 option label 要空間展示)、或 option 內容撐開導致 popover 寬於 trigger,**align 的視覺差異立刻顯現**——此時嚴格照 structured overlay canonical(trigger 在左 → start / 右 → end)。(SelectMenu `align` prop 僅暴露 `'start' | 'end'`,不開放底層 Radix 的 `center`。) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+換言之 SelectMenu **永遠照 canonical**,只是大多數情況 width=trigger-width 讓 canonical 視覺上被 mask,一旦 popover 突破 trigger 寬度 canonical 立刻生效。規則沒例外,只是呈現條件。
+
+---
+
+## 單選 vs 多選
+
+透過 `multiple` prop 決定（`value` 型別只被 normalize 成內部 `selectedValues`，不參與模式判斷）：
+
+- **單選**（`multiple={false}`，預設）：`value: string | null`，選中後立即關閉浮層
+- **多選**（`multiple={true}`）：`value: string[]`，選中不關閉，可繼續選（footer 可顯示全選 checkbox）
+
+---
+
+## Creatable（建立新選項）
+
+透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」;`select-menu.tsx:230-235`)——完全同名時自動隱藏,防重複建立。
+
+**何時啟用**：
+- Tag input 允許使用者建立新 tag
+- Assignee 選擇允許邀請外部人員
+- Label / category 自由建立
+
+**何時不啟用**：
+- 固定選項清單（狀態、類別、角色）
+- 需要後端驗證合法性的 value（避免建立無效選項）
+
+---
+
+## 分組（group）
+
+透過 `groups` prop 定義分組標籤，每個 option 的 `group` 欄位指向 group key。
+
+**何時使用**：
+- 選項明顯分兩個以上邏輯群組（「Recent」/「All」、「Your team」/「Others」）
+- 超過 10 個選項需要視覺分區降低認知負擔
+
+**何時不用**：
+- 選項少於 6 個（分組反而增加視覺雜訊）
+- 選項本質平行（沒有自然分組）
+
+---
+
+## Empty state
+
+搜尋無結果時顯示 `Empty` 元件，可透過 `emptyText` 自訂訊息（預設「沒有符合的選項」）。
+
+- **Creatable 時**：即使搜尋無結果，仍顯示 create row 讓使用者補建選項（顯示條件見「Creatable」段）
+- **非 creatable**：顯示 emptyText 提示使用者修改搜尋詞
+- **SR 播報**（2026-07-05 D4）：empty / loading 空狀態同步經 visually-hidden `role="status"` + `aria-live="polite"` live region 播報（cmdk CommandEmpty 是 `role="presentation"`，SR 使用者原本聽不到 0 結果；對齊 `empty.spec.md`「動態 filter no-results 容器需 `aria-live="polite"`」+ react-select A11yText）。SSOT 在 SelectMenu 一處，Select / Combobox / PeoplePicker 全體受益。
+
+---
+
+## Loading（2026-05-15 audit B fix, codify 2026-05-16 audit Dim 7+8）
+
+非同步載入選項時，consumer 透過 `loading={true}` 控制：
+
+- **Trigger 不變**：dropdown 隨時可開（user 看 chevron 不會被 disable）
+- **Dropdown 開啟時**（2026-07-04 Q3 拍板措辭修訂）：spinner 只在**無可顯示選項時**佔 empty slot，渲 panel-center `<Empty icon={<CircularProgress size={48}/>} className="py-6"/>`（cmdk `CommandEmpty` 機制）；**已有 options 時保留顯示不清空**（MUI Autocomplete 官方「only if there are no suggestions to show」共識）
+- **CircularProgress 預設 24px**，但在 Empty wrapper 內 48px（取代 Empty 的 48px Avatar icon slot）
+
+對齊 MUI Autocomplete loading dropdown-body + Ant Select loading idiom + DS `empty.spec.md`「禁止事項」段「loading 用 Empty + CircularProgress compose」SSOT（SelectMenu loading 用法 canonical row 見 `empty.spec.md`「現有消費者」表）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**消費**：Select / Combobox forward `loading` prop 到 SelectMenu（PeoplePicker 尚未暴露 / 轉發 `loading`，見 `people-picker.spec.md`「邊界案例」），本元件不需 consumer 直接知道 Empty + CircularProgress 組合（封裝在內）。
+
+---
+
+## 禁止事項
+
+- ❌ 直接在 JSX 用 `<SelectMenu>`——透過外層元件（Select / Combobox / PeoplePicker）消費
+- ❌ 跳過 SelectMenu 自建 Popover + Command 組合——會漂移出共用 layout 與 item-layout 規則
+- ❌ 不搭配 trigger / field 使用——SelectMenu 是浮層，一定需要觸發元件
+- ❌ 超過 50 個選項不開搜尋——純捲動會變低效
+- ❌ 分組少於 2 組——分組本身是視覺成本，只有一組等於沒分組
+
+---
+
+## 邊界案例
+
+- **Disabled option**:individual MenuItem 透過 `disabled?: boolean` 控制(SelectMenu primitive option contract)。視覺繼承 `MenuItem` SSOT:text → `text-fg-disabled`(M24)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onChange、鍵盤導覽自動 skip。
+- **Disabled trigger**:trigger 由 consumer(Select / Combobox / PeoplePicker)的 `disabled` prop own,本元件不獨立 disable trigger。
+- **Loading**:已 codify(見「Loading」段),`loading=true` 且無可顯示選項時 empty slot 渲 panel-center Empty + CircularProgress 48px(stale options 保留)。
+- **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留 create row(可鍵盤選取)。
+- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:230-235`);選取既有選項為唯一路徑。
+- **Dark mode**:走 Popover / MenuItem semantic token 自動 adapt。
+- **Density**:row height 由 `MenuItem` SSOT 控(sm/md/lg);SelectMenu 不獨立 own density。
+
+---
+
+## 為何無 ColorMatrix
+
+SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
+
+- **無 ColorMatrix**:視覺完全繼承既有 DS primitive 的 token(`MenuItem` row / `Command` search / `Empty` layout / `Popover` surface),無自己的 bg / border / hover 決策。色彩漂移由 primitive layer 控制——SelectMenu 層級若加 ColorMatrix 會重複 MenuItem / Popover 的矩陣。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix` / `StateBehavior`,額外追加元件特有的 `ModeMatrix`(single / multi / searchable / creatable / grouped 等功能組合矩陣,這是 SelectMenu 真正的決策面向——取代 ColorMatrix)。
+
+---
+
+## shadcn passthrough 例外說明
+
+SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:127-130` rationale):
+
+- **沒有單一 DOM root 可 ref**:trigger / search input / list / content portal 各自 DOM tree 離散
+- **`...props` spread 目標不明**:composite 的 root wrapper 只是 control 容器,spread 到那裡 consumer 無從預期作用
+- **API 邊界明確**:SelectMenu 暴露「選值」語意(value / onValueChange / options / mode),不暴露 DOM 細節
+- **`className` 合併到 PopoverContent**(contextually 最接近 user-facing surface)
+
+`displayName = 'SelectMenu'` 保留。若 consumer 需要 DOM-level 控制(custom trigger / portal / search input ref),改用底層 Popover + Command 自組。
+
+`asChild` 不支援(composite 非 Slot-compat)。
+
+---
+
+## 相關
+
+- `../Menu/menu-item.spec.md` — 選項 row 的 item-layout 共用規則（SelectMenu 消費 MenuItem）
+- `../Popover/popover.tsx` — 浮動容器（SelectMenu 消費）
+- `../Command/command.tsx` — cmdk 搜尋 + 鍵盤導覽（SelectMenu 消費）
+- `../Empty/empty.spec.md` — 搜尋無結果的 empty state
+- `../Select/select.spec.md` — 主要消費者之一（searchable 時切換到 SelectMenu）
+- `../Combobox/combobox.spec.md` — 主要消費者之一（searchable 多選時切換到 SelectMenu）
+- `../PeoplePicker/people-picker.spec.md` — 永遠使用 SelectMenu 的消費者
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — item-layout pattern（MenuItem 繼承）
+
+## A11y 預設
+
+**ARIA / Pattern**:基於 `cmdk` library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。選項 row 的內層 `MenuItem` 傳 `role="presentation"`(cmdk CommandItem 是唯一 option 節點,避免 option 巢狀 option + 內外 `aria-selected` 語意相反;鏡射 DropdownMenu canonical,2026-07-05 D4)。多選 footer 全選列為 `role="checkbox"` + `aria-checked`(indeterminate → `"mixed"`)。空狀態 / loading 經 visually-hidden `role="status"` + `aria-live="polite"` live region 對 SR 播報(cmdk CommandEmpty 是 `role="presentation"`,SR 原本聽不到;2026-07-05 D4)。
+
+**Keyboard 行為**:
+
+- Tab — focus trigger
+- Enter / Space — 開啟 menu(trigger 由 consumer 經 `PopoverTrigger asChild` 提供,開啟行為由 consumer trigger 負責:Select / Combobox 的 trigger 是 `role="combobox"` 容器,自綁 Enter / Space handler 觸發開啟;若 consumer 用 DS `<Button>`(native button)則由 native click 觸發)
+- ↑/↓ — 導覽 options(menu 開啟後)
+- Enter — 選擇
+- 字母鍵 — type-ahead 過濾(search 模式)
+- Tab(menu 開啟 + multi 模式)— DOM focus 移到 footer 全選列(`tabIndex=0`;全選列在 CommandList 之外、非 cmdk-item,cmdk 方向鍵導覽不涵蓋,故走 DOM focus。2026-07-05 D4 鍵盤可達修)
+- Enter / Space(focus 在全選列)— 切換全選 / 全清(handler `preventDefault`,cmdk root onKeyDown 檢查 defaultPrevented 故不會重複觸發 active option)
+- Esc — 關閉
+
+**Focus**:menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(`aria-activedescendant` 高亮,非 DOM focus;cmdk listbox 模式);searchable 時 DOM focus 給搜尋 input,非 searchable 時 DOM focus 移到 cmdk 的 `[cmdk-root]`(`Command` 元素,見 `handleNonSearchableAutoFocus`),讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效。option 為 `role="option"` 無 tabIndex,DOM focus 不落在 option 上。關閉時 focus 回 trigger。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `command.spec.md`
+- `dropdown-menu.spec.md`
+- `menu-item.spec.md`
+- `popover.spec.md`
+- `select.spec.md`

package/src/components/SelectMenu/select-menu.stories.tsx

@@ -0,0 +1,155 @@
+// @story-trait-rationale: isInputLike trait — SelectMenu(internal,Select/Combobox 觸發)的 error state 由 Select.stories.tsx + Combobox.stories.tsx WithError 覆蓋(SelectMenu 是 internal popover surface,不直接 own input state)。AllSizes 同理 retired(anatomy auto-compile SizeMatrix owns)per F migration 2026-05-15。
+import type { Meta, StoryObj } from '@storybook/react'
+import React, { useState } from 'react'
+import { Select } from '@/design-system/components/Select/select'
+import { Combobox } from '@/design-system/components/Combobox/combobox'
+
+const meta: Meta = {
+  title: 'Design System/Internal/SelectMenu/展示',
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+// ── 單選（Select 觸發）──
+
+const statusOptions = [
+  { value: 'in_stock', label: 'In stock' },
+  { value: 'low_stock', label: 'Low stock' },
+  { value: 'out_of_stock', label: 'Out of stock' },
+]
+
+const SingleSelectDemo = () => {
+  const [value, setValue] = useState<string>('in_stock')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-muted">Select 作為觸發點，點擊開啟 SelectMenu</p>
+      <Select options={statusOptions} value={value} onChange={setValue} aria-label="狀態(SelectMenu single-select demo)" />
+    </div>
+  )
+}
+
+export const SingleSelect: StoryObj = {
+  name: '單選',
+  render: () => <SingleSelectDemo />,
+}
+
+// ── 單選 + 搜尋 ──
+
+const countries = [
+  { value: 'tw', label: '台灣' }, { value: 'jp', label: '日本' },
+  { value: 'us', label: '美國' }, { value: 'gb', label: '英國' },
+  { value: 'de', label: '德國' }, { value: 'fr', label: '法國' },
+  { value: 'kr', label: '韓國' }, { value: 'sg', label: '新加坡' },
+  { value: 'au', label: '澳洲' }, { value: 'ca', label: '加拿大' },
+]
+
+const SearchableDemo = () => {
+  const [value, setValue] = useState<string>('')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-muted">searchable — 觸發點變 input，打字即篩選</p>
+      <Select options={countries} value={value} onChange={setValue} searchable clearable placeholder="選擇國家…" />
+    </div>
+  )
+}
+
+export const Searchable: StoryObj = {
+  name: '搜尋',
+  render: () => <SearchableDemo />,
+}
+
+// ── 多選 ──
+
+const categoryOptions = [
+  { value: 'electronics', label: 'Electronics' },
+  { value: 'furniture', label: 'Furniture' },
+  { value: 'food', label: 'Food' },
+  { value: 'lifestyle', label: 'Lifestyle' },
+]
+
+const MultiSelectDemo = () => {
+  const [value, setValue] = useState<string[]>(['electronics'])
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <p className="text-caption text-fg-muted">Combobox — checkbox 多選，浮層不關閉</p>
+      <Combobox options={categoryOptions} value={value} onChange={setValue} />
+    </div>
+  )
+}
+
+export const MultiSelect: StoryObj = {
+  name: '多選',
+  render: () => <MultiSelectDemo />,
+}
+
+// ── 多選 + 搜尋 ──
+
+const MultiSearchDemo = () => {
+  const [value, setValue] = useState<string[]>([])
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <p className="text-caption text-fg-muted">searchable — 浮層內搜尋框，關鍵字保留可連續勾選</p>
+      <Combobox options={countries} value={value} onChange={setValue} searchable />
+    </div>
+  )
+}
+
+export const MultiSearchable: StoryObj = {
+  name: '多選 + 搜尋',
+  render: () => <MultiSearchDemo />,
+}
+
+// ── 可清除 ──
+
+const ClearableDemo = () => {
+  const [value, setValue] = useState<string>('in_stock')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-muted">clearable — 有值時右側出現清除按鈕</p>
+      <Select options={statusOptions} value={value} onChange={setValue} clearable />
+    </div>
+  )
+}
+
+export const Clearable: StoryObj = {
+  name: '可清除',
+  render: () => <ClearableDemo />,
+}
+
+// @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
+// @story-trait-rationale: 原 States(edit/readonly/disabled/error 觸發器狀態)retired 2026-06-11 —
+//   trigger field state 由 Select.stories.tsx「四模式」owns(SelectMenu 是 internal popover surface,
+//   不 own input state,見檔頭 rationale)。本層改示範浮層自己 own 的選項狀態。
+// ── 選項狀態(浮層內)──
+
+const assigneeOptions = [
+  { value: 'ada', label: 'Ada Chen', description: 'Design Engineer' },
+  { value: 'ben', label: 'Ben Liu', description: 'Frontend' },
+  { value: 'cindy', label: 'Cindy Wang', description: '休假中,暫不可指派', disabled: true },
+  { value: 'derek', label: 'Derek Kao', description: 'Backend' },
+]
+
+const OptionStatesDemo = () => {
+  const [value, setValue] = React.useState<string>('ada')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-secondary">
+        浮層內選項狀態 — 已選中(勾選標記)、disabled(休假成員不可選)、搜尋無結果(輸入不存在的名字)
+      </p>
+      <Select
+        options={assigneeOptions}
+        value={value}
+        onChange={setValue}
+        searchable
+        placeholder="指派負責人…"
+        aria-label="指派負責人(SelectMenu option-states demo)"
+      />
+    </div>
+  )
+}
+
+export const OptionStates: StoryObj = {
+  name: '選項狀態',
+  render: () => <OptionStatesDemo />,
+}