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

package/src/components/Checkbox/checkbox.tsx

@@ -7,6 +7,7 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "@/lib/utils"
 import type { FieldMode, FieldVariant } from "@/design-system/components/Field/field-types"
 import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from "@/design-system/components/Field/field-context"
+import { useControllable } from "@/design-system/hooks/use-controllable"
 import { fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
 import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
 import { BooleanValueIcon } from "@/design-system/components/SelectionControl/boolean-value"
@@ -80,8 +81,13 @@ const checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+// asChild / children 從公開型別 Omit(2026-07-17 d9i6):Checkbox 有**固定 anatomy** —
+// 內部恆渲染 Indicator(Check / Minus 兩子節點),非 Slot host。若保留 Radix `asChild`,
+// consumer 傳入的元素會被 Radix Slot `React.Children.only` 因多子節點在執行期拋錯(失敗記憶索引
+// 已 codify 此 asChild 多子節點 bug class);`children` 同理會被固定 Indicator 覆蓋。需自訂佈局
+// 請用 `label` / `description` / `icon` / `avatar` 一級 props(內部自動包 SelectionItem)。
 export interface CheckboxProps
-  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,
+  extends Omit<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, 'asChild' | 'children'>,
     VariantProps<typeof checkboxVariants> {
   /**
    * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，
@@ -111,7 +117,7 @@ export interface CheckboxProps
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 checkbox(預設)
-   *   display  — **純展示**:渲染 Check / X icon(true=勾 / false=叉,無互動 primitive、無 input chrome);
+   *   view     — **純展示**:渲染 Check / X icon(true=勾 / false=叉,無互動 primitive、無 input chrome);
    *              對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。
    *   readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal
    *   disabled — 同 disabled prop:降色 + 鎖互動
@@ -143,6 +149,13 @@ const Checkbox = React.forwardRef<
       mode,
       // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。
       variant: _chrome,
+      // controllable checked triplet(2026-07-17 d26i0):於 wrapper 層取出,交由 useControllable 持有
+      // resolved 值,供 edit / view / readonly 三分支共用。原本 view / readonly 分支各自讀 raw prop →
+      // uncontrolled(只傳 defaultChecked)在 edit 態 toggle 後切 mode 會丟失目前值(Radix 內部狀態
+      // wrapper 讀不到)。移出 props 後 edit 主路徑改由 checked={resolvedChecked} 受控(見下方 rootEl)。
+      checked: checkedProp,
+      defaultChecked: defaultCheckedProp,
+      onCheckedChange,
       id: idProp,
       ...props
     },
@@ -154,7 +167,7 @@ const Checkbox = React.forwardRef<
 
     // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管
     // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。
-    // 原 mode='display' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。
+    // 原 mode='view' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。
     //
     // **例外**:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),**每個 checkbox
     // 的 label 是它自己的選項名**,FieldLabel 只是群組名稱 — 此時 label **必須保留**,
@@ -181,7 +194,7 @@ const Checkbox = React.forwardRef<
     const generatedId = React.useId()
     const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))
 
-    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode="display"> 漏 cascade)
+    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode="view"> 漏 cascade)
     const resolvedDisabled = useResolvedFieldDisabled(disabled)
     const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })
     const effectiveReadOnly = readOnly || resolvedMode === 'readonly'
@@ -192,36 +205,74 @@ const Checkbox = React.forwardRef<
     // readonly 灰框 size:走 SSOT resolver(prop > ctx > 'md',field-context.ts:150-161)
     const resolvedBoxSize = useResolvedFieldSize(size ?? undefined, 'md') as 'sm' | 'md' | 'lg'
 
-    // 2026-07-04 修:display / readonly-in-Field 分支的裸 span/div 原丟棄剩餘 props
+    // 2026-07-04 修:view / readonly-in-Field 分支的裸 span/div 原丟棄剩餘 props
     // (id/data-*/aria-*)且不轉發 forwardRef ref → consumer 的 aria-label 等靜默失效。
-    // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Switch/
-    // RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。
+    // 抽出 Radix 專屬 form props(required/name/value 不可落到裸 span/div),其餘 DOM props 於兩分支
+    // spread 轉發(與 Switch/RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。
+    // (checked/defaultChecked/onCheckedChange 已於上方 top-level destructure 取出交 useControllable;
+    //  asChild/children 已從 CheckboxProps 型別 Omit — 固定 anatomy 非 Slot host,見型別註解。)
     const {
-      checked: checkedProp,
-      defaultChecked: defaultCheckedProp,
-      onCheckedChange: _onCheckedChange,
       required: _required,
       name: _name,
       value: _value,
-      asChild: _asChild,
-      children: _children,
       ...restDomProps
     } = props
 
-    // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
+    // ── Resolved checked SSOT(controlled / uncontrolled dual-mode,2026-07-17 d26i0)──────────
+    // 對齊 Input / Textarea 既有 canonical(field-controls.spec.md「有值判定」:useControllable 內部
+    // resolved value + form.reset bridge)。修 view / readonly 分支原各自讀 raw prop 導致「uncontrolled
+    // 切 mode 丟失目前值」的 dual-mode 缺口。controlled(傳 checked)時 useControllable 純 passthrough,
+    // edit 行為 Δ=0。
+    const isControlled = checkedProp !== undefined
+    const [resolvedChecked, setResolvedChecked] = useControllable<boolean | 'indeterminate'>({
+      value: checkedProp,
+      defaultValue: defaultCheckedProp ?? false,
+    })
+
+    // form.reset() bridge(uncontrolled only):wrapper 取得 controllable 主導後,HTML 標準 reset 不發
+    // 變更事件 → 手動把 resolvedChecked 歸位 defaultChecked(對齊 input.tsx 同名 bridge)。keyed on
+    // resolvedMode:切回 edit 重掛 native Root 時 effect 重跑補掛 listener;view / readonly(Root
+    // unmount)時 innerRef 為 null → early return 不掛。
+    const innerRef = React.useRef<HTMLButtonElement | null>(null)
+    React.useEffect(() => {
+      if (isControlled) return
+      const form = innerRef.current?.form
+      if (!form) return
+      const handleReset = () => setResolvedChecked(defaultCheckedProp ?? false)
+      form.addEventListener('reset', handleReset)
+      return () => form.removeEventListener('reset', handleReset)
+    }, [isControlled, resolvedMode, defaultCheckedProp, setResolvedChecked])
+    // Merge refs(input.tsx setRef idiom):innerRef 供 reset bridge 取 form,同時轉發 forwardRef ref。
+    const setRef = React.useCallback((el: HTMLButtonElement | null) => {
+      innerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLButtonElement | null>).current = el
+    }, [ref])
+
+    // ── mode='view'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
     // 純展示模式:無互動 primitive、渲染 Check / X icon(true=勾 / false=叉,中性 foreground 色)。
     // boolean 值展示符號 SSOT = SelectionControl/boolean-value.tsx(勾/叉 icon + 中性色 + M22 世界級對照)。取代 BooleanDisplay。
-    if (resolvedMode === 'display') {
-      const isChecked = checkedProp === true
+    if (resolvedMode === 'view') {
+      const isChecked = resolvedChecked === true
+      // a11y(2026-07-17 d10i2):BooleanValueIcon 帶 aria-hidden → 裸 span 在 a11y tree 無名,
+      // 布林值對螢幕閱讀器完全消失。給 view 容器 role="img" + aria-label 承載值語意(對齊 MUI X
+      // DataGrid boolean cell 的 icon role/label 世界級做法);consumer 若自帶 aria-label 則優先。
+      const viewAriaLabel = (restDomProps as { 'aria-label'?: string })['aria-label'] ?? (isChecked ? '是' : '否')
       return (
-        <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="inline-flex">
+        <span
+          {...restDomProps}
+          ref={ref as React.Ref<HTMLSpanElement>}
+          role="img"
+          aria-label={viewAriaLabel}
+          className="inline-flex"
+        >
           <BooleanValueIcon checked={isChecked} size={resolvedBoxSize} />
         </span>
       )
     }
 
     // ── mode='readonly' in Field(2026-06-12 拍板「灰框 + 勾/叉」;2026-07-09 ✓/— glyph → Check/X icon)─
-    // Field 內 readonly boolean = readonly 灰框 chrome + display 同款值語言(勾/叉 icon)。
+    // Field 內 readonly boolean = readonly 灰框 chrome + view 同款值語言(勾/叉 icon)。
     // 灰框消費 fieldWrapperStyles 同一 cva = 與 Input readonly 字面同源(SSOT,改一處全動)。
     // 理由:同一張 readonly 表單裡文字控件有 bg-readonly 灰框鎖定訊號,boolean 保留全彩
     // 控件會誤導「仍可操作」(世界級 0/4 用原樣鎖互動:Salesforce=✓ 靜態 glyph /
@@ -229,7 +280,7 @@ const Checkbox = React.forwardRef<
     // Scope:僅 Field 內且無 inline label(FieldLabel 接管 label 的表單欄位場景);
     // standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動不變。
     if (effectiveReadOnly && insideField && effectiveLabel == null) {
-      const isChecked = (checkedProp ?? defaultCheckedProp) === true
+      const isChecked = resolvedChecked === true
       const boxSize = resolvedBoxSize
       return (
         <div
@@ -256,8 +307,17 @@ const Checkbox = React.forwardRef<
     const rootEl = (
       <CheckboxPrimitive.Root
         id={inputId}
-        ref={ref}
+        ref={setRef}
         disabled={effectiveDisabled}
+        // controllable checked SSOT(2026-07-17 d26i0):Root 受 wrapper resolvedChecked 主導,
+        // onCheckedChange 先同步 wrapper 內部 state 再 forward consumer → uncontrolled(只傳
+        // defaultChecked)toggle 後切 mode(view / readonly)仍保留目前值。controlled(傳 checked)
+        // 時 useControllable 純 passthrough,edit 行為 Δ=0。
+        checked={resolvedChecked}
+        onCheckedChange={(next) => {
+          setResolvedChecked(next)
+          onCheckedChange?.(next)
+        }}
         aria-readonly={effectiveReadOnly || undefined}
         data-readonly={effectiveReadOnly || undefined}
         tabIndex={effectiveReadOnly ? -1 : undefined}

package/src/components/Coachmark/coachmark.anatomy.stories.tsx

@@ -68,7 +68,7 @@ export const Overview: Story = {
           <table className="text-caption border-collapse">
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
-              <tr><Td mono>children</Td><Td mono>ReactNode</Td><Td mono>—</Td><Td>anchor trigger element(Popover asChild)</Td></tr>
+              <tr><Td mono>children</Td><Td mono>ReactElement</Td><Td mono>—</Td><Td>anchor trigger element(Popover asChild Slot 單 element 契約,2026-07-05 型別收緊)</Td></tr>
               <tr><Td mono>open / onOpenChange</Td><Td mono>boolean / (o) =&gt; void</Td><Td mono>—</Td><Td>controlled 控制(多步 tour 必用)</Td></tr>
               <tr><Td mono>defaultOpen</Td><Td mono>boolean</Td><Td mono>—</Td><Td>uncontrolled 初始開啟狀態</Td></tr>
               <tr><Td mono>kind</Td><Td mono>'tips' | 'new-features' | ReactNode</Td><Td mono>—</Td><Td>有值則渲染 Header(tour-level title);'tips'→「使用技巧」、'new-features'→「新功能介紹」、ReactNode→自訂;multi-step tour 建議傳</Td></tr>
@@ -126,9 +126,9 @@ export const Inspector: Story = {
             </div>
             <Coachmark
               open
-              image={hasImage ? <MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Sparkles} label="功能介紹" /> : undefined}
-              title="試試新功能"
-              description="這是 Coachmark 的說明文字;多行內容會自動換行並保持 leading 一致。"
+              image={hasImage ? <MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Sparkles} label="AI 續寫" /> : undefined}
+              title="讓 AI 幫你續寫草稿"
+              description="選取一段文字,AI 會依前後文續寫並保留你的語氣;不滿意可以一鍵重新產生。"
               step={hasStep ? { current: 2, total: 3 } : undefined}
               onPrev={hasPrev ? () => {} : undefined}
               onSkip={hasSkip ? () => {} : undefined}
@@ -137,7 +137,7 @@ export const Inspector: Story = {
               side="right"
               align="start"
             >
-              <Button variant="primary" size="sm" startIcon={Sparkles}>Anchor</Button>
+              <Button variant="primary" size="sm" startIcon={Sparkles}>AI 續寫</Button>
             </Coachmark>
           </div>
         </div>

package/src/components/Coachmark/coachmark.principles.stories.tsx

@@ -158,7 +158,7 @@ export const UsageGuidance: Story = {
             image={<MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Bot} label="AI 助理" />}
             title="試試新的 AI 助理"
             description="在任何文件中按下 AI 按鈕,讓 Claude 幫你摘要、翻譯或改寫內容。"
-            onSkip={() => {}}
+            isLastStep
             onNext={() => {}}
             side="bottom"
             align="start"

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

@@ -306,7 +306,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 四模式;顯式傳入時永遠最優先,不被 disabled 覆蓋'],
+                ['mode', "'edit'|'view'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式;顯式傳入時永遠最優先,不被 disabled 覆蓋'],
                 ['size', "'sm'|'md'|'lg'", "'md'", '尺寸，與 Button 共用 field-height token'],
                 ['options', 'ComboboxOption[]', '—', '選項列表（extends SelectMenuOption：value / label / icon / avatar / description / disabled / group）'],
                 ['value', 'string[]', '[]', '已選中的值陣列'],
@@ -410,6 +410,7 @@ const InspectorInner = () => {
               value={value}
               onChange={setValue}
               placeholder="選擇分類"
+              aria-label="產品分類"
               className="w-72"
             />
           </div>
@@ -551,6 +552,7 @@ export const ColorMatrix = {
                         size="sm"
                         disabled={st === 'disabled'}
                         onChange={() => {}}
+                        aria-label={`產品分類(${st})`}
                       />
                       <TokenAnnotation colors={st === 'disabled' ? TOKEN_MAP.disabled.default : TOKEN_MAP.edit[st]} />
                     </td>
@@ -567,6 +569,7 @@ export const ColorMatrix = {
                         error={st !== 'disabled'}
                         disabled={st === 'disabled'}
                         onChange={() => {}}
+                        aria-label={`產品分類(錯誤態、${st})`}
                       />
                       <TokenAnnotation colors={st === 'disabled' ? TOKEN_MAP.disabled.default : ERROR_COLORS[st]} />
                     </td>
@@ -588,10 +591,10 @@ export const ColorMatrix = {
                   <tr key={m}>
                     <Td mono>{m}</Td>
                     <td className="p-3 border-b border-divider align-top min-w-[180px]">
-                      <Combobox mode={m} options={categoryOptions} value={['electronics', 'food']} size="sm" />
+                      <Combobox mode={m} options={categoryOptions} value={['electronics', 'food']} size="sm" aria-label={`產品分類(${m})`} />
                     </td>
                     <td className="p-3 border-b border-divider align-top min-w-[160px]">
-                      <Combobox mode={m} options={categoryOptions} value={[]} size="sm" />
+                      <Combobox mode={m} options={categoryOptions} value={[]} size="sm" aria-label={`產品分類(${m}、空值)`} />
                     </td>
                     <td className="p-3 border-b border-divider align-top min-w-[160px]">
                       <TokenAnnotation colors={TOKEN_MAP[m].default} />
@@ -726,7 +729,7 @@ export const SizeMatrix = {
         <div className="flex flex-col gap-3">
           {SIZES.map((sz) => (
             <div key={sz} className="flex items-center gap-3">
-              <Combobox size={sz} options={categoryOptions} value={['electronics', 'food']} onChange={() => {}} className="w-64" />
+              <Combobox size={sz} options={categoryOptions} value={['electronics', 'food']} onChange={() => {}} className="w-64" aria-label={`產品分類(size=${sz})`} />
               <span className="text-caption text-fg-secondary font-mono">size=&quot;{sz}&quot;</span>
             </div>
           ))}
@@ -778,6 +781,7 @@ export const StateBehavior = {
               options={categoryOptions}
               value={overflowV}
               onChange={setOverflowV}
+              aria-label="產品分類(單行溢出 +N 範例)"
             />
           </div>
           <div className="flex flex-col gap-1 text-[11px] text-fg-secondary">
@@ -814,6 +818,7 @@ export const StateBehavior = {
                   value={wrapV}
                   onChange={setWrapV}
                   wrap
+                  aria-label="產品分類(換行模式範例)"
                 />
               </div>
             </div>
@@ -846,6 +851,7 @@ export const StateBehavior = {
               onChange={setClearV}
               clearable
               className="w-64"
+              aria-label="產品分類(清除全部範例)"
             />
             <button
               type="button"
@@ -872,6 +878,7 @@ export const StateBehavior = {
               value={dismissV}
               onChange={setDismissV}
               className="w-72"
+              aria-label="產品分類(個別移除 Tag 範例)"
             />
             <button
               type="button"

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

@@ -60,10 +60,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">四模式</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Combobox/展示" name="尺寸與 Button 對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo>
-        </li>
-        <li>
-          <LinkTo kind="Design System/Components/Combobox/展示" name="單行 vs 換行"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單行 vs 換行</span></LinkTo>
+          <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>
@@ -81,14 +78,14 @@ export const UsageGuidance: Story = {
           title="Combobox 的 sweet spot — 多選 + 空間受限 + 選項數 6+"
           note="Tag / 分類 / 協作成員 / 通知訂閱。使用者快速加選、移除，label 自帶語意不需描述"
         >
-          <Combobox options={categoryOptions} value={tags} onChange={setTags} />
+          <Combobox options={categoryOptions} value={tags} onChange={setTags} aria-label="商品分類(多選 Tag 範例)" />
         </Rule>
 
         <Rule
           title="❌ 單選:用 Select"
           note="Combobox 永遠多選——單選塞進來使用者每次要手動先移除舊 Tag 再選新的，多餘的互動"
         >
-          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} />
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} aria-label="商品分類(單選反例——應改用 Select)" />
           <Label warn>↑ 只選一個 electronics → 應該用 Select，一次點擊完成切換</Label>
         </Rule>
 
@@ -104,6 +101,7 @@ export const UsageGuidance: Story = {
             ]}
             value={['terms']}
             onChange={() => {}}
+            aria-label="同意項目"
           />
           <Label warn>↑ 條款勾選是「完整閱讀後同意」→ 用 Checkbox stack 全露內容</Label>
         </Rule>
@@ -121,6 +119,7 @@ export const UsageGuidance: Story = {
             ]}
             value={['eng-fe']}
             onChange={() => {}}
+            aria-label="部門"
           />
           <Label warn>↑ 用縮排偽造階層 → 沒有展開收合、不能按父節點全選、破壞資料結構</Label>
         </Rule>
@@ -141,7 +140,7 @@ export const WrapRule: Story = {
           title="單行（預設）— Table cell、空間受限的 Form"
           note="固定高度，與 Input / Select 等欄位並排對齊。多於可見寬度的 Tag 以 +N 指示器代替，hover 可看完整清單"
         >
-          <Combobox options={categoryOptions} value={single} onChange={setSingle} />
+          <Combobox options={categoryOptions} value={single} onChange={setSingle} aria-label="商品分類(單行溢出範例)" />
           <Label>↑ 單行：高度固定，超出的 Tag → +N</Label>
         </Rule>
 
@@ -149,7 +148,7 @@ export const WrapRule: Story = {
           title="多行 wrap — 空間充裕的 Form"
           note="高度隨選中數量展開，每個 Tag 都完整可見。適合填答型表單——使用者一眼看到所有選項，不需 hover 溢出指示器"
         >
-          <Combobox wrap options={categoryOptions} value={wrapped} onChange={setWrapped} />
+          <Combobox wrap options={categoryOptions} value={wrapped} onChange={setWrapped} aria-label="商品分類(多行 wrap 範例)" />
           <Label>↑ 多行：完整展開，無溢出</Label>
         </Rule>
 
@@ -189,7 +188,7 @@ export const TagOperationRule: Story = {
           title="Tag 只能被「移除」，不能被「編輯」或「重排」"
           note="每個 Tag 右側的 X 是唯一被允許的互動——保持 Tag 的心智模型單純：它代表一個已選中的選項，要換就刪了重選"
         >
-          <Combobox options={categoryOptions} value={value} onChange={setValue} />
+          <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="商品分類(Tag 移除範例)" />
           <Label>↑ 點 Tag 的 X 移除；右側 clear all 一次清除；新增從 dropdown 選擇</Label>
         </Rule>
 
@@ -205,7 +204,7 @@ export const TagOperationRule: Story = {
           title="已選中的選項在下拉裡以打勾標示，再點一次即取消"
           note="桌機（預設）走自建浮層選單：已選項保留在清單中並以打勾呈現，再點一次即移除——避免使用者跨越下拉與 field 才能對照已選狀態。手機 / 觸控裝置改走原生 select，已選項則不重複出現在原生下拉"
         >
-          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} />
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} aria-label="商品分類(已選項打勾範例)" />
           <Label>↑ 打開 dropdown，Electronics 仍在清單裡並打勾，可再點一次取消</Label>
         </Rule>
       </div>
@@ -223,7 +222,7 @@ export const OverflowRule: Story = {
           title="+N 指示器是單行模式的必要元件"
           note="使用者必須知道「還有多少沒看到」——沒有 +N 的單行會誤導使用者以為選項已完整顯示。Hover 可看完整清單"
         >
-          <Combobox options={categoryOptions} value={value} onChange={setValue} />
+          <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="商品分類(+N 溢出指示範例)" />
           <Label>↑ 窄容器內多個 Tag，自動出現 +N</Label>
         </Rule>
 

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

@@ -124,7 +124,7 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 
 ## Loading
 
-`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補):dropdown body 內取代 options 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(消費 既有 empty.spec.md「現有消費者」SelectMenu loading row SSOT)。Trigger 不變,user 隨時可開。對齊 Ant AutoComplete loading idiom。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+`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 隨時可開。對齊 MUI Autocomplete「loading 只在無 suggestions 時顯 loadingText」共識(cite 詳 select.spec.md 同段)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ---
 
@@ -132,7 +132,7 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 
 - **Disabled**:Field SSOT own(`Field/field-controls.spec.md`)。trigger / tag dismiss / 搜尋 input 全部 disabled,token 走 M24 state precedence(`text-fg-disabled`);已選 Tag 的 dismiss X 自動隱藏(見「readonly / disabled 的 Tag」段)。
 - **Loading**:已 codify(見「Loading」段)。
-- **Empty(no search results)**:dropdown body 內渲 SelectMenu 預設 `emptyText`「沒有符合的選項」(Combobox 不傳 `emptyText`,走 SelectMenu primitive default)。Combobox 不暴露 `creatable` / `onCreate` prop(僅 SelectMenu primitive 本身支援),故 Combobox consumer 無「建立 "xxx"」row。
+- **Empty(no 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。
 
@@ -145,6 +145,10 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 - 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)。
+
 ---
 
 ## 禁止事項

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

@@ -26,7 +26,7 @@ const meta: Meta<typeof Combobox> = {
 export default meta
 type Story = StoryObj<typeof Combobox>
 
-// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add display mode card to Modes story only.
+// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add view mode card to Modes story only.
 /* ── 四模式 ── */
 export const Modes: Story = {
   name: '四模式',
@@ -39,8 +39,8 @@ export const Modes: Story = {
           <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="類別(edit mode demo)" />
         </div>
         <div>
-          <h3 className="text-body font-bold text-foreground mb-2">display</h3>
-          <Combobox mode="display" options={categoryOptions} value={value} aria-label="類別(display mode demo)" />
+          <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>
@@ -61,7 +61,7 @@ export const Modes: Story = {
 
 /* ── 尺寸與 Button 對齊 ── */
 export const SizeAlignment: Story = {
-  name: '尺寸與 Button 對齊',
+  name: '三種尺寸',
   render: () => {
     const [sm, setSm] = React.useState(['electronics', 'food', 'lifestyle'])
     const [md, setMd] = React.useState(['electronics', 'food', 'lifestyle'])
@@ -71,7 +71,7 @@ export const SizeAlignment: Story = {
       <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" />
+            <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>
@@ -81,37 +81,10 @@ export const SizeAlignment: Story = {
   },
 }
 
-/* ── 單行 vs 換行 ── */
-export const WrapModes: Story = {
-  name: '單行 vs 換行',
-  render: () => {
-    const init = ['electronics', 'food', 'lifestyle', 'clothing', 'furniture']
-    const [v1, setV1] = React.useState(init)
-    const [v2, setV2] = React.useState(init)
-    return (
-      <div className="flex flex-col gap-6 w-72">
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">單行（預設）</h3>
-          <p className="text-caption text-fg-muted mb-3">塞不下的自動收進 +N，hover 顯示隱藏項</p>
-          <Combobox options={categoryOptions} value={v1} onChange={setV1} />
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">單行 readonly</h3>
-          <Combobox mode="readonly" options={categoryOptions} value={init} />
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">換行（wrap）</h3>
-          <p className="text-caption text-fg-muted mb-3">高度隨內容長，badges 自動換行</p>
-          <Combobox options={categoryOptions} value={v2} onChange={setV2} wrap />
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">換行 readonly</h3>
-          <Combobox mode="readonly" options={categoryOptions} value={init} wrap />
-        </div>
-      </div>
-    )
-  },
-}
+// @story-trait-rationale: 原 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 = {