@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.87

package/src/components/SegmentedControl/segmented-control.principles.stories.tsx

@@ -6,7 +6,7 @@ import {
   List, LayoutGrid, Calendar,
 } from 'lucide-react'
 import { SegmentedControl, SegmentedControlItem } from './segmented-control'
-import { Tabs, TabsList, TabsTrigger } from '@/design-system/components/Tabs/tabs'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/design-system/components/Tabs/tabs'
 import { Button } from '@/design-system/components/Button/button'
 import { Badge } from '@/design-system/components/Badge/badge'
 
@@ -87,6 +87,9 @@ export const UsageGuidance: Story = {
                 <TabsTrigger value="customers">顧客</TabsTrigger>
                 <TabsTrigger value="products">產品</TabsTrigger>
               </TabsList>
+              <TabsContent value="orders" className="text-body text-fg-muted mt-2">訂單列表、篩選與批次出貨（各自的 toolbar / table）</TabsContent>
+              <TabsContent value="customers" className="text-body text-fg-muted mt-2">顧客名單、分群與生命週期價值</TabsContent>
+              <TabsContent value="products" className="text-body text-fg-muted mt-2">商品目錄、庫存與上下架狀態</TabsContent>
             </Tabs>
           </div>
         </Rule>

package/src/components/SegmentedControl/segmented-control.spec.md

@@ -62,17 +62,11 @@ SegmentedControl 是**互斥多選一的 compact control**——從 2–5 個選
 
 ---
 
-## 與 Tabs 的分界（詳見 `../Tabs/tabs.spec.md`）
+## 與 Tabs 的分界
 
-兩者都能「切換下方顯示的內容」，分界不是「切 view vs 切 value」，而是三個角度：
+**完整判斷 SSOT 在 `../Tabs/tabs.spec.md` 的「Tabs 與 SegmentedControl 的分界」段落**（三角度判斷：規模 / 角色 / 值生命週期 + 灰色地帶對照表）——以該段為 single source of truth，此處不重複列舉、也不平行維護，避免漂移。
 
-1. **規模**：SegmentedControl 切換的是 **局部內容的變體**（一個 chart、一個 list、一段 form section）；Tabs 切換的是 **整塊 container**（可能有自己的 header / toolbar / 多個 section）
-2. **結構角色**：SegmentedControl 是 **control**（可跟 Button / Input 並排），Tabs 是 **container 的結構元件**（跨越父容器整行）
-3. **值生命週期**：SegmentedControl 的值常綁 form state / URL param / 會被持久化，Tabs 的切換通常不進表單狀態
-
-**Fallback**：跟 Input / Button 並排不違和 → SegmentedControl；必須佔一整行當 section header → Tabs。
-
-**完整灰色地帶對照表在 `tabs.spec.md` 的「Tabs 與 SegmentedControl 的分界」段落**——以該段為 single source of truth，此處不重複列舉。
+本元件視角的一句話界線：切「局部內容的變體」（單一 chart / list / form section，可跟 Button / Input 並排）用 SegmentedControl；切「整塊 container」（有自己的 header / toolbar / 多個 section、必須佔一整行當 section header）改用 Tabs。
 
 ---
 
@@ -240,6 +234,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 - **個別 item disabled**：Radix roving focus 跳過該 item（`focusable: !disabled`），方向鍵不停留；disabled item 不得是當前 value（contract，見「狀態 › disabled」）
 - **所有 item disabled**：整組無可聚焦 item，Radix roving focus 將 group 的 tab 停留點設為 `tabIndex=-1`，Tab 直接跳過
 - **disabled × fullWidth 並存**：兩者正交——fullWidth 只控寬度等分，disabled 只控互動與色彩，無交互規則
+- **表單驗證 / invalid**：SegmentedControl **恆有一值**（radio 語意），故「必填未選」的 required 驗證天然不適用；元件**無 `invalid` / `error` prop**，不渲染 error 邊框或 `aria-invalid`（它讀 Field context 的 `disabled` / `size`，但**不讀 `invalid`**，與 Input / Select 等可空控件不同）。值的業務合法性（是否落在允許選項）由 consumer 保證，需要 invalid 視覺提示時由外層 Field / consumer 承擔——屬 consumer-owned，非本元件狀態
 
 ---
 
@@ -269,7 +264,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 
 - `../Button/button.spec.md` — item 內部結構與 size 系統的來源
 - `../Tabs/tabs.spec.md` — container 切換 vs control 切換的判斷（完整分界 SSOT 在 Tabs spec「Tabs 與 SegmentedControl 的分界」段落）
-- `../Field/field-controls.spec.md` — SegmentedControl 作為 Field control 時的 size 繼承機制
+- `../Field/field-controls.spec.md` — SegmentedControl 作為 Field control 時的 `size` / `disabled` 繼承機制（透過 `useResolvedFieldSize` / `useResolvedFieldDisabled`）；**不**繼承 `invalid` 驗證軸——表單驗證契約見上「規模限制與邊界案例 › 表單驗證 / invalid」（恆有一值，required / invalid 為 N/A 或 consumer-owned）
 - `../Checkbox/checkbox.spec.md` — RadioGroup 共用規則（選項數量多或需要描述文字時的替代）
 
 ## A11y 預設

package/src/components/SegmentedControl/segmented-control.tsx

@@ -15,8 +15,9 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
  * 內部 item 結構鏡射 Button，但兩者型別獨立。
  *
  * ── 定位 ──
- *   切 value（不是切 view）。塞得進 Field，Tabs 不行。
- *   切 view → Tabs；單一 on/off → Button pressed；>5 個選項 → Select。
+ *   互斥多選一的 compact control；選值可驅動下方內容變化（ViewSwitcher 合法——
+ *   「切 value 不能切 view」是錯的二分法，spec「定位」段）。塞得進 Field，Tabs 不行。
+ *   與 Tabs 分界看規模 / 結構角色（spec「與 Tabs 的分界」段）；單一 on/off → Button pressed；>5 個選項 → Select。
  *
  * ── Size（對齊 field-height / Button 系列）──
  *   xs   h-field-xs（24 固定）
@@ -217,7 +218,9 @@ const itemVariants = cva(
 // 但當 group iconOnly = true 時，每個 item 必須提供 startIcon + aria-label——
 // 這是語意契約，在 render 階段檢查並在 dev mode 發出警告（TS 層做不到這層檢查）。
 export interface SegmentedControlItemProps
-  extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+  // asChild Omit(2026-07-18 決策2):item 固定渲染 [startIcon?, <span>{children}</span>, badge?]
+  // 多節點陣列 → Radix Slot React.Children.only 恆 crash。children(label)保留合法。對齊 Chip 收窄。
+  extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, 'asChild'> {
   /** 左側 icon（LucideIcon）。group iconOnly = true 時必填。 */
   startIcon?: LucideIcon
   /** 右側 suffix badge（通常是計數指示器）。group iconOnly = true 時會被忽略。 */

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

@@ -258,9 +258,15 @@ export const Overview = {
           <div className="flex flex-col gap-2 items-start">
             <span className="text-[11px] text-fg-muted font-medium">edit</span>
             <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md px-3 py-2.5 gap-2">
-              {[{ name: 'Tag', color: 'turquoise' }, { name: 'Tag', color: 'success' }, { name: 'Tag', color: 'info' }, { name: 'Tag', color: 'magenta' }].map((s) => (
-                <span key={s.name} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
-                  style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
+              {/* turquoise/magenta 為 primitive(無 semantic token)→ 顯式 --color-{hue}-{6,1,7}(ProgressBar 同款修法) */}
+              {[
+                { name: 'Tag', border: 'var(--color-turquoise-6)', bg: 'var(--color-turquoise-1)', text: 'var(--color-turquoise-7)' },
+                { name: 'Tag', border: 'var(--success)', bg: 'var(--success-subtle)', text: 'var(--success)' },
+                { name: 'Tag', border: 'var(--info)', bg: 'var(--info-subtle)', text: 'var(--info)' },
+                { name: 'Tag', border: 'var(--color-magenta-6)', bg: 'var(--color-magenta-1)', text: 'var(--color-magenta-7)' },
+              ].map((s, i) => (
+                <span key={i} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
+                  style={{ borderColor: s.border, backgroundColor: s.bg, color: s.text }}>{s.name}</span>
               ))}
             </div>
             <span className="text-[10px] text-fg-muted font-mono">Tag: pointer-events-none · 點擊穿透到觸發點開選單</span>
@@ -304,7 +310,7 @@ export const Overview = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['mode', "'edit'|'display'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式——edit 可編輯 / display 純展示 / readonly 顯示值不可改 / disabled 灰化'],
+                ['mode', "'edit'|'view'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式——edit 可編輯 / view 純展示 / readonly 顯示值不可改 / disabled 灰化'],
                 ['variant', "'default'", "'default'", 'Field chrome variant(預設繼承 context.variant;naked = @internal cell-as-input,2026-07-14 型別收窄至 FieldVariantInternal)'],
                 ['display', "'plain'|'tag'", "'plain'", '顯示模式——plain 純文字，tag 用 Tag 元件呈現'],
                 ['size', "'sm'|'md'|'lg'", "'md'", '尺寸，與 Button 同 size 並排高度一致'],
@@ -316,14 +322,14 @@ export const Overview = {
                 ['placeholder', 'string', '—', '未選值時的提示文字'],
                 ['clearable', 'boolean', 'false', '有值時顯示 clear 按鈕（僅 edit 模式）'],
                 ['searchable', 'boolean', 'false', '啟用搜尋(desktop 時 field 變 input，打字即篩選)'],
-                ['loading', 'boolean', 'false', 'dropdown 開啟時取代 options 顯 CircularProgress'],
+                ['loading', 'boolean', 'false', 'dropdown 開啟且無可顯示選項時,empty slot 顯 CircularProgress(已有選項時保留顯示、不取代;對齊 spec「Loading」2026-07-04 拍板)'],
                 ['minRows', 'number', '3', 'menu list 最小列數(空 / 選項少時視覺一致)'],
                 ['startIcon', 'LucideIcon', '—', '左側 field-level 指示 icon（muted，僅 plain 模式；代表 value 的圖示走 option.icon）'],
                 ['error', 'boolean', 'false', '紅色邊框 + aria-invalid（僅 edit 模式有視覺效果）'],
                 ['defaultOpen', 'boolean', 'false', 'uncontrolled 初始開啟(DataTable cell click→1 step open)'],
                 ['onOpenChange', '(open: boolean) => void', '—', 'open 狀態變更 callback'],
-                ['showDisplayEndIcon', 'boolean', 'false', 'display 模式渲 ChevronDown(opt-in 逃生門;2026-07-08 A 案後 DataTable 預設不傳 — display 態零恆顯 icon)'],
-                ['selectedItemRenderer', '(opt: SelectOption) => ReactNode', '—', '已選項目客製 render;4 mode 共享(edit/display/readonly/disabled,contract (a))— display 態渲值內容無 chrome(PeoplePicker / status 欄用)'],
+                ['showDisplayEndIcon', 'boolean', 'false', 'view 模式渲 ChevronDown(opt-in 逃生門;2026-07-08 A 案後 DataTable 預設不傳 — view 態零恆顯 icon)'],
+                ['selectedItemRenderer', '(opt: SelectOption) => ReactNode', '—', '已選項目客製 render;4 mode 共享(edit/view/readonly/disabled,contract (a))— view 態渲值內容無 chrome(PeoplePicker / status 欄用)'],
                 ['disabled', 'boolean', '—', '原生屬性；未傳 mode 時 resolve 為 disabled 樣式（顯式 mode prop 恆優先，見 useResolvedFieldMode）'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>

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

@@ -70,10 +70,10 @@ export const UsageGuidance: Story = {
                 <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>
+                <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="尺寸與 Button 對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo>
+                <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>
@@ -276,7 +276,7 @@ export const SearchableRule: Story = {
 
       <Rule
         title="次要啟發:數量 > 50 幾乎必開(但仍看 label 性質)"
-        note="100 個 a/b/c 不需要搜尋(字母排序掃視快,手機原生 select 還有 type-to-jump 直達),5 個產品代碼需要搜尋。純數量 threshold 會誤判這兩端,詳見 spec"
+        note="100 個依字母排序的國家名不需要搜尋(自然語言掃視快,手機原生 select 還有 type-to-jump 直達),5 個產品代碼(SKU-4837)反而需要搜尋。純數量 threshold 會誤判這兩端,詳見 spec"
       >
         <Label>判斷優先序:label 性質 → 數量次要啟發</Label>
       </Rule>

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

@@ -222,6 +222,14 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 純量化規則會誤判這兩端。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）
@@ -233,7 +241,7 @@ 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 / display / readonly / disabled 4 mode 共享同一 renderer**(`field-controls.spec.md` 共享 contract (a),禁 edit-only)。renderer 輸出屬「值內容」— `mode="display"` 照常渲染(無 chrome 無 chevron);與 affordance(chevron/outline)分層見 `field.spec.md` L6。
+**`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。
 
 ### plain 模式
 
@@ -345,6 +353,7 @@ Select 是 **Field Controls family 成員**——互動狀態(focus / invalid /
 
 - `checkbox.spec.md`
 - `combobox.spec.md`
+- `command.spec.md`
 - `people-picker.spec.md`
 - `radio-group.spec.md`
 - `select-menu.spec.md`

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

@@ -44,8 +44,8 @@ export const Modes: Story = {
         </div>
         {/* @story-trait-rationale: pre-existing trait gaps tracked separately */}
         <div>
-          <h3 className="text-body font-bold text-foreground mb-2">display</h3>
-          <Select mode="display" options={statusOptions} value={value} aria-label="狀態(display mode demo)" />
+          <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+          <Select mode="view" options={statusOptions} value={value} aria-label="狀態(view 模式示範)" />
         </div>
         <div>
           <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -97,34 +97,14 @@ export const HugWidth: Story = {
   },
 }
 
-/* ── 顯示模式 ── */
-export const DisplayMode: Story = {
-  name: '顯示模式',
-  render: () => {
-    const [textVal, setTextVal] = React.useState('in_stock')
-    const [tagVal, setTagVal] = React.useState('in_stock')
-    return (
-      <div className="flex flex-col gap-6 max-w-xs">
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">plain（預設）</h3>
-          <p className="text-caption text-fg-muted mb-2">純文字，readonly/disabled 跟 Input 一致</p>
-          <Select options={statusOptions} value={textVal} onChange={setTextVal} />
-          <div className="mt-2"><Select mode="readonly" options={statusOptions} value={textVal} /></div>
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">tag</h3>
-          <p className="text-caption text-fg-muted mb-2">Tag 標籤 + 顏色(tagVariant),readonly/disabled 用 tagPadding</p>
-          <Select display="tag" options={statusOptions} value={tagVal} onChange={setTagVal} />
-          <div className="mt-2"><Select display="tag" mode="readonly" options={statusOptions} value={tagVal} /></div>
-        </div>
-      </div>
-    )
-  },
-}
+// @story-trait-rationale: DisplayMode(plain/tag × edit/readonly)retired 2026-07-17 per audit Dim 24 —
+//   為 anatomy.stories.tsx ColorMatrix(plain/tag × edit/readonly/disabled 完整矩陣)的嚴格子集;
+//   plain vs tag 的選用原則另由 principles.stories.tsx DisplayModeRule 承載。展示版無新增約束
+//   (earn-existence 2-test 雙 NO)→ retire。display 模式 canonical home = anatomy ColorMatrix + principles DisplayModeRule。
 
 /* ── 尺寸與 Button 對齊 ── */
 export const SizeAlignment: Story = {
-  name: '尺寸與 Button 對齊',
+  name: '三種尺寸',
   render: () => {
     const [sm, setSm] = React.useState('in_stock')
     const [md, setMd] = React.useState('in_stock')
@@ -192,6 +172,40 @@ export const Searchable: Story = {
   },
 }
 
+/* ── Creatable(搜尋 + 建立新選項）── */
+export const Creatable: Story = {
+  name: '建立新選項',
+  render: () => {
+    const [labels, setLabels] = React.useState([
+      { value: 'bug', label: 'Bug' },
+      { value: 'feature', label: 'Feature' },
+      { value: 'design', label: 'Design' },
+      { value: 'docs', label: 'Docs' },
+    ])
+    const [value, setValue] = React.useState<string>('')
+    return (
+      <div className="flex flex-col gap-4 max-w-xs">
+        <p className="text-caption text-fg-muted">
+          searchable + creatable — 搜尋不到既有標籤時,dropdown 底部出現「直接使用「…」」建立列,點擊即新增並選取
+        </p>
+        <Select
+          options={labels}
+          value={value}
+          onChange={setValue}
+          searchable
+          creatable
+          onCreate={(q) => {
+            const newLabel = { value: q.toLowerCase().replace(/\s+/g, '-'), label: q }
+            setLabels((prev) => [...prev, newLabel])
+            setValue(newLabel.value)
+          }}
+          placeholder="選擇或建立標籤…"
+        />
+      </div>
+    )
+  },
+}
+
 /* ── DataTable 整合 ── */
 export const InDataTable: Story = {
   name: 'DataTable 整合',

package/src/components/Select/select.tsx

@@ -1,6 +1,6 @@
 // @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.
 // code-quality-allow: file-size — Select 含 3 子元件(NativeSelect/CustomSelect/ReadonlyDisplay)+ helpers + 4-mode renderer + Field SSOT consumption,split-into-files 會破壞 file-local helper closure
-// @renderer-symmetry-allow: 2026-07-08 WM 戰役 A 案回歸修正 — ReadonlyDisplay 現已消費 selectedItemRenderer(display bare-span / D-path / readonly / disabled 四分支),對齊 field-controls.spec.md 共享 contract (a)「display/readonly/disabled/edit 4 mode 共享同一 renderer」。前 note「display→edit unify deferred」已兌現(值內容層);chrome 結構 unify(D-path)仍為 opt-in showDisplayEndIcon。
+// @renderer-symmetry-allow: 2026-07-08 WM 戰役 A 案回歸修正 — ReadonlyDisplay 現已消費 selectedItemRenderer(view bare-span / D-path / readonly / disabled 四分支),對齊 field-controls.spec.md 共享 contract (a)「view/readonly/disabled/edit 4 mode 共享同一 renderer」。前 note「display→edit unify deferred」已兌現(值內容層);chrome 結構 unify(D-path)仍為 opt-in showDisplayEndIcon。
 import * as React from 'react'
 import { X, ChevronDown } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
@@ -141,10 +141,10 @@ export interface SelectProps
    *  DataTable cell-as-input 用:open=false 時 cell 自動 exit edit mode(避免 dismiss 後卡住)。 */
   onOpenChange?: (open: boolean) => void
   /**
-   * Display mode 顯 picker intrinsic end icon(2026-05-08 D path Phase 1)。
-   * 預設 false:`mode="display"` 純展示 bare span(向後相容)。
-   * `variant="naked" && mode="display"` 場景(DataTable cell)opt-in 設 true → wrap 進
-   * Field naked-display + 渲 ChevronDown ItemSuffix。**只 display mode 生效**;readonly /
+   * View mode 顯 picker intrinsic end icon(2026-05-08 D path Phase 1)。
+   * 預設 false:`mode="view"` 純展示 bare span(向後相容)。
+   * `variant="naked" && mode="view"` 場景(DataTable cell)opt-in 設 true → wrap 進
+   * Field naked-view + 渲 ChevronDown ItemSuffix。**只 view mode 生效**;readonly /
    * disabled / edit 已有 Field wrapper + suffix(不受此 prop 影響)。
    * Authority:`data-table.spec.md:204` + `inline-action.spec.md:157`「Field family endAction(自動繼承)」。
    * @default false
@@ -154,9 +154,9 @@ export interface SelectProps
    * 「已選項目」客製 render(2026-05-07 v15.5;2026-07-08 A 案回歸修正擴及 4 mode)。
    *
    * 設了 → 已選值不走純文字 / Tag 預設 path,改用 consumer 提供的 ReactNode(收 selectedOpt)。
-   * **display / readonly / disabled / edit 4 mode 共享同一 renderer**(field-controls.spec.md
+   * **view / readonly / disabled / edit 4 mode 共享同一 renderer**(field-controls.spec.md
    * 共享 contract (a),禁 edit-only)— renderer 輸出屬「值內容」(status icon+text 等語意呈現),
-   * display 態照常渲染;A 案撤的是 affordance(chevron/outline),非值內容(field.spec.md L6 分層)。
+   * view 態照常渲染;A 案撤的是 affordance(chevron/outline),非值內容(field.spec.md L6 分層)。
    * Searchable+open 仍走 input(搜尋優先)。Empty value(no selection)仍走 placeholder。
    *
    * 用例:PeoplePicker 用此 slot 把 single 選中的 person render 成 PersonDisplay
@@ -168,6 +168,16 @@ export interface SelectProps
    *  僅 Custom path(searchable dropdown)生效,Native path 無搜尋空狀態。
    *  對齊 MUI noOptionsText / Ant notFoundContent / Polaris emptyState 三家公開覆寫點共識。 */
   emptyText?: string
+  /**
+   * 可建立新選項(creatable,2026-07-18 決策11 user 拍板 forward 到 Select)。**需搭配 `searchable`**
+   * ——搜尋非空且無完全同名既有選項時,dropdown 顯 create row(Plus + `createLabel`)。
+   * 邏輯/顯示/互動 SSOT 住在 SelectMenu(Select 的 trigger 搜尋以受控 `search` 驅動 SelectMenu creatable
+   * 顯隱)。與 Combobox.creatable 同一底層。非 searchable 時無 create 通道(無輸入處)。 */
+  creatable?: boolean
+  /** 建立新選項 callback（收使用者輸入的搜尋字串）。 */
+  onCreate?: (value: string) => void
+  /** create row 的 label 格式，預設 '直接使用「{query}」'（forward SelectMenu SSOT）。 */
+  createLabel?: (query: string) => string
 }
 
 // ── Icon / size helpers ─────────────────────────────────────────────────────
@@ -343,7 +353,7 @@ function CustomSelectTriggerContent({
 }
 CustomSelectTriggerContent.displayName = 'CustomSelectTriggerContent'
 
-// ── Shared readonly/disabled/display render ─────────────────────────────────
+// ── Shared readonly/disabled/view render ─────────────────────────────────
 function ReadonlyDisplay({
   mode, variant: variantProp, width, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon, selectedItemRenderer,
 }: Pick<SelectProps, 'mode' | 'width' | 'size' | 'options' | 'value' | 'display' | 'startIcon' | 'className' | 'placeholder' | 'showDisplayEndIcon' | 'selectedItemRenderer'> & {
@@ -355,7 +365,7 @@ function ReadonlyDisplay({
   const variant = variantProp ?? 'default'
   const sz = size ?? 'md'
   const iconSize = getIconSize(sz)
-  // selectedOpt 提前 hoist(2026-07-08 A 案回歸修正):display / D-path / readonly / disabled
+  // selectedOpt 提前 hoist(2026-07-08 A 案回歸修正):view / D-path / readonly / disabled
   // 四分支都需要 — renderer 值內容(field-controls.spec.md contract (a) 4-mode 共享)+ tagVariant 查找。
   const selectedOpt = options?.find(o => o.value === value)
   const label = selectedOpt?.label ?? value
@@ -366,20 +376,20 @@ function ReadonlyDisplay({
   const emptyColorCls = fieldEmptyColorClass(resolvedMode)
   const emptyText = placeholder ?? emptyDisplay
 
-  // mode='display':2 path(2026-05-08 D path Phase 1 Select canary)
+  // mode='view':2 path(2026-05-08 D path Phase 1 Select canary)
   //   ❌ 預設(無 showDisplayEndIcon):純內容輸出 bare span/Tag(原行為,backward compat)
   //      對齊原 SelectDisplay sub-component(retired)。readonly / disabled 仍走下方 fieldWrapperStyles。
-  //   ✅ showDisplayEndIcon=true(DataTable cell opt-in):Field naked-display wrapper +
+  //   ✅ showDisplayEndIcon=true(DataTable cell opt-in):Field naked-view wrapper +
   //      ChevronDown ItemSuffix。SSOT canonical 跟 readonly/edit/disabled mode 同 DOM 結構。
   //      Authority: data-table.spec.md:204 + inline-action.spec.md:157「Field family endAction」
-  if (resolvedMode === 'display') {
+  if (resolvedMode === 'view') {
     if (!showDisplayEndIcon) {
-      // 2026-05-14 I2 fix(spec contract (e) display typography canonical):bare span 必套
+      // 2026-05-14 I2 fix(spec contract (e) view typography canonical):bare span 必套
       // `fieldDisplayTextClass(sz)`(sm/md→text-body,lg→text-body-lg)— 對齊跨 Field
-      // family display 視覺尺寸統一。
+      // family view 視覺尺寸統一。
       if (!value) return <span className={cn(fieldDisplayTextClass(sz), emptyColorCls, className)}>{emptyText}</span>
       // 2026-07-08 A 案回歸修正:selectedItemRenderer(值內容:status icon+text 等語意呈現)
-      // display 態照常渲染 — 無 chrome 無 chevron,只有值內容本身。分層原則(field.spec.md L6):
+      // view 態照常渲染 — 無 chrome 無 chevron,只有值內容本身。分層原則(field.spec.md L6):
       // 本 renderer 歸「值內容」,恆顯;A 案撤的是 affordance(chevron/outline),非值內容。
       // 對齊 field-controls.spec.md 共享 contract (a)「4 mode 共享同一 renderer(禁 edit-only)」。
       if (selectedItemRenderer && selectedOpt) {
@@ -393,12 +403,12 @@ function ReadonlyDisplay({
       const tVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
       return <Tag size={sz} color={tVariant} className={className}>{label}</Tag>
     }
-    // D path opt-in: Field naked-display wrapper + ItemSuffix ChevronDown
+    // D path opt-in: Field naked-view wrapper + ItemSuffix ChevronDown
     const tVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant, width, size: sz }), value && !isTextDisplay && tagPadding[sz], className)}
-        data-field-mode="display"
+        className={cn(fieldWrapperStyles({ mode: 'view', variant, width, size: sz }), value && !isTextDisplay && tagPadding[sz], className)}
+        data-field-mode="view"
       >
         {selectedItemRenderer && value && selectedOpt ? (
           // renderer 優先(同 CustomSelectTriggerContent 優先序):值內容歸 renderer,chevron 歸 D-path chrome
@@ -473,16 +483,16 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
     // 2026-07-04:Custom-path-only props 顯式 destructure 丟棄(不 spread 到原生 <select> 消 React
     // unknown-prop warning);各 prop docblock 已註「僅 Custom path 生效」語意
     // 2026-07-08 A 案回歸修正:selectedItemRenderer 從丟棄名單移出 — Native path 的
-    // ReadonlyDisplay(display/readonly/disabled)同樣消費值內容 renderer(contract (a) 4-mode
+    // ReadonlyDisplay(view/readonly/disabled)同樣消費值內容 renderer(contract (a) 4-mode
     // 共享,值內容不因 pointer type 而異);native <select> edit 路徑仍不消費(原生 option 無法客製 render)。
-    searchable: _searchable, groups: _groups, loading: _loading, minRows: _minRows, emptyText: _emptyText, defaultOpen: _defaultOpen, onOpenChange: _onOpenChange, selectedItemRenderer,
+    searchable: _searchable, groups: _groups, loading: _loading, minRows: _minRows, emptyText: _emptyText, creatable: _creatable, onCreate: _onCreate, createLabel: _createLabel, defaultOpen: _defaultOpen, onOpenChange: _onOpenChange, selectedItemRenderer,
     ...props }, ref) => {
     const fieldCtx = useFieldContext()
     const error = useResolvedFieldInvalid(errorProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
     // 2026-05-31 #11:size 從 Field context cascade(對齊 Input/NumberInput + MUI FormControl)
     const size = useResolvedFieldSize(sizeProp)
-    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode(prop > 有效 disabled > fieldCtx.mode > 'edit');修 <Field mode="display"> 漏 cascade
+    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode(prop > 有效 disabled > fieldCtx.mode > 'edit');修 <Field mode="view"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
     const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const iconSize = getIconSize(size)
@@ -573,7 +583,7 @@ NativeSelect.displayName = 'NativeSelect'
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
-  ({ mode, variant: variantProp, width, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, name, required, form, clearable = false, display = 'plain', startIcon: StartIcon, searchable = false, loading, minRows, emptyText, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, 'aria-label': ariaLabel, onKeyDown: onKeyDownProp, style: styleProp,
+  ({ mode, variant: variantProp, width, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, name, required, form, clearable = false, display = 'plain', startIcon: StartIcon, searchable = false, loading, minRows, emptyText, creatable = false, onCreate, createLabel, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-errormessage': ariaErrorMessageProp, 'aria-label': ariaLabel, onKeyDown: onKeyDownProp, style: styleProp,
     // 2026-07-14 API 策展 D:mobile-only props(allowlist 註記)desktop 顯式丟棄 — div trigger 無原生
     // 對應,不 spread 進 DOM(對稱 NativeSelect 丟棄 custom-path-only props 的既有 pattern)
     autoFocus: _autoFocus, autoComplete: _autoComplete, ...rest }, ref) => {
@@ -582,7 +592,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     const disabled = useResolvedFieldDisabled(disabledProp)
     // 2026-05-31 #11:size 從 Field context cascade(對齊 Input/NumberInput + MUI FormControl)
     const size = useResolvedFieldSize(sizeProp)
-    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode(prop > 有效 disabled > fieldCtx.mode > 'edit');修 <Field mode="display"> 漏 cascade
+    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode(prop > 有效 disabled > fieldCtx.mode > 'edit');修 <Field mode="view"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
     const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const iconSize = getIconSize(size)
@@ -622,8 +632,11 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     const selectedLabel = selectedOpt?.label ?? value ?? ''
     const SelectedIcon = selectedOpt?.icon
     // ── 過濾選項 ──
-    const filteredOptions = searchable && search
-      ? options.filter(o => o.label.toLowerCase().includes(search.toLowerCase()))
+    // 2026-07-18:filter 用 trim 過的 search,對齊 SelectMenu creatable 的 `search.trim()` create-row 判定 —
+    //   否則尾隨空白(如 "Bug ")會讓 filter 漏掉完全同名選項、SelectMenu 卻誤判「無同名」提議重複建立。
+    const trimmedSearch = search.trim()
+    const filteredOptions = searchable && trimmedSearch
+      ? options.filter(o => o.label.toLowerCase().includes(trimmedSearch.toLowerCase()))
       : options
     // ── 轉換 SelectOption → SelectMenuOption(必在 early return 前) ──
     // Issue 4(2026-05-10):forward avatar / description / disabled SSOT(per SelectMenuOption schema)。
@@ -661,7 +674,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
       [setValue]
     )
 
-    // Early return AFTER all hooks(disabled / readonly / display mode 走 ReadonlyDisplay)
+    // Early return AFTER all hooks(disabled / readonly / view mode 走 ReadonlyDisplay)
     if (resolvedMode !== 'edit') {
       return <ReadonlyDisplay mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} display={display} startIcon={StartIcon} className={className} placeholder={placeholder} showDisplayEndIcon={showDisplayEndIcon} selectedItemRenderer={selectedItemRenderer} />
     }
@@ -821,6 +834,11 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         value={value ?? null}
         onValueChange={handleValueChange}
         searchable={false}
+        creatable={creatable}
+        onCreate={onCreate}
+        createLabel={createLabel}
+        search={searchable ? search : undefined}
+        onSearchChange={searchable ? setSearch : undefined}
         loading={loading}
         emptyText={emptyText}
         size={size}

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

@@ -183,7 +183,7 @@ export const Overview: Story = {
                   <Td mono>creatable</Td>
                   <Td mono>boolean</Td>
                   <Td mono>false</Td>
-                  <Td>無結果時顯示「直接使用「xxx」」option(createLabel 可自訂文案)</Td>
+                  <Td>無結果時顯示「直接使用「法務審核」」option(createLabel 可自訂文案)</Td>
                 </tr>
                 <tr>
                   <Td mono>groups</Td>
@@ -275,30 +275,48 @@ function SelectMenuInspector() {
         </div>
 
         <div>
-          <H3>浮層藍圖</H3>
+          <H3>浮層結構</H3>
           <div className="border border-divider rounded-md p-4 bg-muted">
-            <pre className="text-footnote font-mono text-fg-secondary leading-relaxed whitespace-pre">
-{`size=${size}   multiple=${multiple}   searchable=${searchable}   creatable=${creatable}
-
-┌─ Popover (bg-surface-raised · elevation-200 · rounded-lg) ──────────┐
-│ ┌─ Command ────────────────────────────────────────────────────┐    │
-│ │${searchable ? ' ┌─ CommandInput ───────────────────────────────────────┐ │' : ''}
-│ │${searchable ? ' │ [🔍] 搜尋…                                           │ │' : ''}
-│ │${searchable ? ' │ min-h = field-height(${size}) + 8px / border-b              │ │' : ''}
-│ │${searchable ? ' └─────────────────────────────────────────────────────┘ │' : ''}
-│ │ ┌─ CommandList — fit content (empty min-h=field×3+16px) ─┐  │
-│ │ │ CommandGroup (p-0 py-2)                                 │  │
-│ │ │ ▸ MenuItem size=${size} [checkbox=${multiple}] label + desc       │  │
-│ │ │ ▸ MenuItem ...                                           │  │
-│ │ └─────────────────────────────────────────────────────────┘  │
-│ ${multiple ? '│ ┌─ MenuFooter (border-t) ─────────────────────────────────┐ │' : '│'}
-│ ${multiple ? '│ │ [☐] 全部                                                │ │' : '│'}
-│ ${multiple ? '│ └─────────────────────────────────────────────────────────┘ │' : '│'}
-│ └──────────────────────────────────────────────────────────────┘    │
-└──────────────────────────────────────────────────────────────────────┘
-
-RowSizeProvider value=${size} 傳遞到所有 item slot (MenuItem / ItemIcon / ItemAvatar 自動讀)`}
-            </pre>
+            <p className="text-caption text-fg-muted mb-3">
+              size={size} · multiple={String(multiple)} · searchable={String(searchable)} · creatable={String(creatable)}
+            </p>
+            <ul className="text-footnote text-fg-secondary space-y-1 [&_ul]:mt-1 [&_ul]:ml-3 [&_ul]:space-y-1 [&_ul]:border-l [&_ul]:border-divider [&_ul]:pl-3">
+              <li>
+                <span className="font-medium text-foreground">Popover</span> — bg-surface-raised · elevation-200 · rounded-lg
+                <ul>
+                  <li>
+                    <span className="font-medium text-foreground">Command</span> — cmdk root 容器
+                    <ul>
+                      {searchable && (
+                        <li>
+                          <span className="font-medium text-foreground">CommandInput</span> — 搜尋框,min-h = field-height({size}) + 8px,底部 border-b
+                        </li>
+                      )}
+                      <li>
+                        <span className="font-medium text-foreground">CommandList</span> — 依內容撐高(空狀態 min-h = field × 3 + 16px)
+                        <ul>
+                          <li>
+                            <span className="font-medium text-foreground">CommandGroup</span> — p-0 py-2
+                            <ul>
+                              <li>MenuItem — size={size}{multiple ? ' · checkbox' : ''} · label + description</li>
+                              <li>MenuItem — 後續選項…</li>
+                            </ul>
+                          </li>
+                        </ul>
+                      </li>
+                      {multiple && (
+                        <li>
+                          <span className="font-medium text-foreground">MenuFooter</span> — border-t · 全選列(全部)
+                        </li>
+                      )}
+                    </ul>
+                  </li>
+                </ul>
+              </li>
+            </ul>
+            <p className="text-caption text-fg-muted mt-3">
+              RowSizeProvider value={size} 傳遞到所有 item slot(MenuItem / ItemIcon / ItemAvatar 自動讀取)
+            </p>
           </div>
         </div>
       </div>
@@ -696,12 +714,12 @@ export const StateBehavior: Story = {
           <H3>搜尋 empty state</H3>
           <Desc>
             搜尋無結果時顯示 Empty primitive,以 flex items-center justify-center + minHeight 撐高並垂直水平置中。
-            Creatable 模式會額外顯示「建立 xxx」option。
+            Creatable 模式會額外顯示「建立『林采潔』」option。
           </Desc>
           <div className="flex items-center gap-4">
             <SelectMenu options={reviewerOptions} value="" onValueChange={() => {}} searchable>
               <Button variant="tertiary" size="md">
-                點擊後搜尋不存在的字(如 "zzz")
+                點擊後搜尋清單外的名字(如「林采潔」)
               </Button>
             </SelectMenu>
           </div>

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

@@ -32,7 +32,6 @@ export const UsageGuidance: Story = {
             <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>