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

package/src/components/Combobox/combobox.tsx

@@ -1,16 +1,16 @@
 // @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.
-// @renderer-symmetry-allow: ComboboxTagStack(display path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer display-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer 線 314 PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
-// code-quality-allow: file-size — Combobox 含 NativeCombobox/CustomCombobox/useOverflowCount/OverflowTagList/ComboboxTagStack 5 子元件 + 共用 helpers,split-into-files 會破壞 measurement closures + 重複 type definitions。當前 751 lines 在 800 hard cap 內。
+// @renderer-symmetry-allow: ComboboxTagStack(view path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer view-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer(people-picker.tsx:426-444)PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
+// code-quality-allow: file-size — Combobox 含 NativeCombobox/CustomCombobox/useOverflowCount/OverflowTagList/ComboboxTagStack 5 子元件 + 共用 helpers,split-into-files 會破壞 measurement closures + 重複 type definitions。
 import * as React from 'react'
 import { X, ChevronDown } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, EMPTY_DISPLAY, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
-import { useFieldContext } from '@/design-system/components/Field/field-context'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { OverflowIndicator } from '@/design-system/components/OverflowIndicator/overflow-indicator'
-import { SelectMenu, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
+import { SelectMenu, forwardKeyToListbox, useActiveDescendant, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
 import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
@@ -18,6 +18,15 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
 const GAP = 4
 
+// 非-wrap tag 列 clip SSOT(4-path 共用:OverflowTagList base / readonly / native edit / custom edit):
+// 2026-05-18 F2 以 overflow-hidden 修「窄容器 tags 水平越界蓋 chevron / +N」,但雙軸 hidden 副作用
+// 是垂直同裁 — PeoplePicker stack hover 的 AvatarDismissOverlay(`-top-px` + 2px ring,
+// person-display.tsx v15.15,早於 F2)上緣被切(user 2026-08-05 抓「曾經沒有這問題」= F2 前確實沒有)。
+// 雙贏 = overflow-x-clip:水平維持 clip(F2 bug 不回歸;`clip` 不建 scroll container),垂直 visible
+// (overlay / avatar ring 完整)。**不可**改 overflow-x-hidden:單軸 hidden 令另一軸 visible 計算成
+// auto → 生 scroll container,垂直反而可捲。
+const tagRowOverflowClass = 'overflow-x-clip'
+
 const tagPadding: Record<string, string> = {
   sm: 'px-[calc((var(--field-height-sm)_-_1.25rem)_/_2)]',
   md: 'px-[calc((var(--field-height-md)_-_1.5rem)_/_2)]',
@@ -29,8 +38,8 @@ const tagPadding: Record<string, string> = {
  * SelectMenuOption(primitive SSOT)** — 避免重蹈先前 PeoplePicker 改壞的 wrapper schema drift。
  *
  * Why `extends SelectMenuOption`(per user 「全盤檢查避免下次又改壞或是偏移」要求):
- *   原 `interface SelectOption { value: string; label: string }` 是 weak schema,跟 Select 的
- *   `SelectOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
+ *   原 `interface ComboboxOption { value: string; label: string }` 是 weak schema,跟 Select 的
+ *   `ComboboxOption`(同名)雙重宣告但欄位不同 → TypeScript 不抓(同名 interface 在不同 file
  *   各 export,consumer import 到哪個版本看 import path)→ schema drift。
  *   PeoplePicker multi-mode 走 Combobox 路徑,dropdown menu rows lose avatar / description —
  *   user 看到「single mode 有 avatar / multi mode 沒 avatar」inconsistency。
@@ -42,7 +51,7 @@ const tagPadding: Record<string, string> = {
  * 對齊 Polaris ChoiceList / Material Autocomplete / Carbon Dropdown 的 wrapper-vs-primitive
  * schema-extension idiom。Hook `check_wrapper_primitive_schema_drift.sh`(M30 機械強制)。
  */
-export interface SelectOption extends SelectMenuOption {
+export interface ComboboxOption extends SelectMenuOption {
   // (no wrapper-only fields yet — kept for future扩 + same-name SSOT cross-wrapper)
 }
 
@@ -60,7 +69,7 @@ function useOverflowCount(
   const [state, setState] = React.useState({ visibleCount: totalCount, ready: !enabled })
   // 2026-05-18 Round 6 fix(per Codex M31 Round 6 H7 verdict + Step 5 共識):
   // `ofEl.offsetWidth` 在 expanded state(visibleCount === totalCount → overflow=0 →
-  // `OverflowIndicator` line 92 `return null` → ofEl wrapper empty)= 0,fallback 60;
+  // `OverflowIndicator` count≤0 早退 `return null` → ofEl wrapper empty)= 0,fallback 60;
   // 在 collapsed state(+N rendered)= 真實寬(~28-32px)。同 `available` 在兩 state 給
   // 不同 verdict → 臨界值區 `max(B+g+Q, B+g+O) ≤ available < B+g+F` 振盪。Cache last
   // non-zero measurement → measurement state-independent → oscillation 收斂。
@@ -168,7 +177,7 @@ function useOverflowCount(
       }
       if (ofEl) ofEl.hidden = count >= totalCount
       // 2026-05-18 A' fix functional setState value-equal guard(per Codex Round 3 verdict):
-      // sync calc 在 useLayoutEffect 內 + ResizeObserver re-fire 同時跑 → 若每次都 new object setState
+      // effect 內 calc 直跑 + ResizeObserver re-fire 同時跑 → 若每次都 new object setState
       // 觸發 re-render 即使值沒變,可能 cascade。回 prev 不更新 = avoid 抖動。
       setState(prev => (prev.visibleCount === count && prev.ready) ? prev : { visibleCount: count, ready: true })
     }
@@ -180,13 +189,13 @@ function useOverflowCount(
     //
     // 2026-05-16 Race close:capture rAF IDs + cancel on cleanup(原版 race I3 沒 close
     // 完;user 抓 path A 逐個 click vs path B 取消全選再全選 same length 不同 visible)。
-    // 2026-05-18 A' fix(per Codex Round 3 共識,user 拍板「執行」)— sync calc in useLayoutEffect:
-    // React 18 `useLayoutEffect` 在 DOM commit 後、瀏覽器繪製前同步跑,sync calc 在 paint 前
+    // 2026-05-18 A' fix(per Codex Round 3 共識,user 拍板「執行」)— effect fire 時 calc() 直跑
     // 完成 `el.hidden` 設定 + functional setState guard(value-equal 不更新 = 避免 ResizeObserver
-    // 抖動 cascade rerender)。double-rAF 改 fallback only(ResizeObserver / async update path)。
+    // 抖動 cascade rerender)。double-rAF 為 fallback path(ResizeObserver / async update path)。
     // 解 user verbatim「tag 過長 / 過多會先全顯再變 +N 閃動」root cause(per codex Round 3 cite
-    // `combobox.tsx:248 render 沒設 hidden + L129 calc imperative 寫 DOM`)。
-    // 對齊 React docs https://react.dev/reference/react/useLayoutEffect pre-paint guarantee。
+    // 「render 沒設 hidden + calc imperative 寫 DOM」)。
+    // 註:Round 3 原以 useLayoutEffect sync calc(paint 前設 hidden)實作;2026-05-18 Round 5
+    // 已改 React.useEffect after-paint(nested 場景 parent ref attach 時序,詳上方 Round 5 註解)。
     calc()
     let rafId1 = 0, rafId2 = 0
     const scheduleCalc = () => {
@@ -237,7 +246,7 @@ interface OverflowTagListProps {
    * 2026-05-14 I4 fix(per codex M31 verdict + user 抓「display overflow 有 avatar / edit 無」):
    * Optional renderer for hidden items in `+N` overflow popover。Default fallback = `<Tag>{label}</Tag>`
    * (純文字 chip,backward-compat)。Consumer pass 此 prop 讓 hidden items 顯示同 avatar 視覺
-   * (對齊 display MultiPersonDisplay overflow popover Tag avatar SSOT)。
+   * (對齊 view path MultiPersonDisplay overflow popover Tag avatar SSOT)。
    */
   renderHiddenTag?: (item: { value: string; label: string }) => React.ReactNode
   onRemove?: (value: string) => void
@@ -287,8 +296,9 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
 
   // 2026-05-18 A' fix(per Codex Round 3 共識,user 拍板「執行」)— 撤掉舊的 `style={{ opacity: ready ? 1 : 0 }}`
   // gate(掛在 `<span className="contents">` 上,但 CSS Display 3 spec 規定 `display:contents` 元素不產生 box,
-  // parent opacity 對 children 無效 → gate 從沒生效是 dead code)。Flicker 已改 sync calc in useLayoutEffect 解
-  // (L153 `calc()` 直跑,paint 前 hidden 設好)。`ready` state 保留供未來 instrumentation / debug,不再當 visual gate。
+  // parent opacity 對 children 無效 → gate 從沒生效是 dead code)。Flicker 由 `useOverflowCount` effect 內
+  // `calc()` 直跑(現 L190;2026-05-18 Round 5 改 useEffect after-paint + double-rAF guard,詳該 hook 註解)解。
+  // `ready` state 保留供未來 instrumentation / debug,不再當 visual gate。
   // 保留 `<span className="contents">` 維持 fragment-like rendering(parent JSX 期望 single child)。
   void ready  // intentional: ready 留供 future debug,目前無 consumer
   return (
@@ -296,7 +306,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
       {items.map((item, i) => (
         // 2026-05-14 I5 fix(per codex M31 verdict + user 抓「avatar stack 堆疊方向不一致」):
         // 加 z-index per-index — 前 item z 高(對齊 MultiPersonDisplay zIndex: visible.length - i
-        // canonical + MUI AvatarGroup surplus pattern)。display + edit stack 堆疊方向統一。
+        // canonical + MUI AvatarGroup surplus pattern)。view + edit stack 堆疊方向統一。
         <div key={item.value} ref={el => { tagEls.current[i] = el }} className={cn('shrink-0 max-w-full', tagWrapperClassName)} style={{ zIndex: items.length - i }}>{renderTag(item, i)}</div>
       ))}
       <div ref={overflowEl} className={cn('shrink-0', overflowWrapperClassName)}>
@@ -304,7 +314,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
           {hiddenItems.map(item => (
             renderHiddenTag
               ? <React.Fragment key={item.value}>{renderHiddenTag(item)}</React.Fragment>
-              : <Tag key={item.value} size="sm" onDismiss={onRemove ? () => onRemove(item.value) : undefined}>
+              : <Tag key={item.value} size="sm" onRemove={onRemove ? () => onRemove(item.value) : undefined}>
                   {item.label}
                 </Tag>
           ))}
@@ -315,18 +325,19 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
   )
 }
 
-// ── Internal tag-stack renderer (consumed by ReadonlyMultiSelect / mode='display') ───
+// ── Internal tag-stack renderer (consumed by ReadonlyMultiSelect / mode='view') ───
 //
-// Phase B2(2026-05-05):原 ComboboxDisplay sub-component 已 retire,改 inline `<Combobox mode="display">`。
+// Phase B2(2026-05-05):原 ComboboxDisplay sub-component 已 retire,改 inline `<Combobox mode="view">`。
 // 本 helper 只負責 tag-stack 內容渲染(OverflowTagList 消費),不包 Field wrapper。
 function ComboboxTagStack({
   value, options, tagSize = 'md', wrap = false, containerRef: externalRef, disabled = false,
 }: {
-  value?: string[] | null; options?: SelectOption[]; tagSize?: 'sm' | 'md' | 'lg'
+  value?: string[] | null; options?: ComboboxOption[]; tagSize?: 'sm' | 'md' | 'lg'
   wrap?: boolean; containerRef?: React.RefObject<HTMLDivElement | null>; disabled?: boolean
 }) {
+  const emptyDisplay = useFieldEmptyDisplay()
   const ownRef = React.useRef<HTMLDivElement>(null)
-  if (!value || value.length === 0) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+  if (!value || value.length === 0) return <span className={fieldEmptyColorClass(disabled ? 'disabled' : 'view')}>{emptyDisplay}</span>
   const items = value.map(v => ({ value: v, label: options?.find(o => o.value === v)?.label ?? v }))
   const disabledClass = disabled ? 'bg-disabled text-fg-disabled' : undefined
 
@@ -343,17 +354,17 @@ function ComboboxTagStack({
   )
 
   if (externalRef) return content
-  // 2026-05-05 v9 fix(Bug 4):display path 內 wrapper 必須 `flex-1 min-w-0`,否則在 cell flex
+  // 2026-05-05 v9 fix(Bug 4):view path 內 wrapper 必須 `flex-1 min-w-0`,否則在 cell flex
   // parent 下不認領完整可用寬度 → OverflowTagList 量得寬度小於 edit path → 顯 `+N` 多於 edit。
-  // edit path tagAreaRef wrapper 已是 `flex-1 min-w-0`(NativeCombobox/CustomCombobox line 258 / 354),
-  // display 必對稱才 SSOT。
+  // edit path tagAreaRef wrapper 已是 `flex-1 min-w-0`(NativeCombobox/CustomCombobox line 696 / 885),
+  // view 必對稱才 SSOT。
   // 2026-05-15 F1 Q3 fix(per user round 3 verbatim「單人選取時 Tag 越界蓋 indicator」):
   // `overflow-visible` → `overflow-hidden` 讓 narrow cell width 強制 clip(Tag 內建 truncate
   // 處理 text ellipsis,stack `-ml-0.5` 負 margin 在 wrapper 內不受影響)。對齊
   // `data-table.spec.md:233`「禁硬裁無 ellipsis」+ MUI X / Ant Table column.ellipsis 共識。
   // (2026-05-14 nakedCellRowModeAlign 同保留 — autoRowHeight cell first-line align canonical。)
   return (
-    <div ref={ownRef} className={cn('flex-1 min-w-0 flex items-center', nakedCellRowModeAlign, wrap ? 'flex-wrap' : 'overflow-hidden')} style={{ gap: GAP }}>
+    <div ref={ownRef} className={cn('flex-1 min-w-0 flex items-center', nakedCellRowModeAlign, wrap ? 'flex-wrap' : tagRowOverflowClass)} style={{ gap: GAP }}>
       {content}
     </div>
   )
@@ -365,9 +376,13 @@ export interface ComboboxProps {
   mode?: FieldMode
   /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
   variant?: FieldVariant
+  /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮:value 寬 + slot 元素寬 + gap +
+   *  field 內 padding;chrome 與互動不變。場景 = detail pane inline metadata。
+   *  SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+  width?: FieldWidth
   error?: boolean
   size?: 'sm' | 'md' | 'lg'
-  options: SelectOption[]
+  options: ComboboxOption[]
   value?: string[]
   onChange?: (value: string[]) => void
   placeholder?: string
@@ -378,8 +393,9 @@ export interface ComboboxProps {
   /** 啟用搜尋 */
   searchable?: boolean
   /** Loading state(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)。
-   *  Forward 給 SelectMenu primitive SSOT;dropdown 開啟時取代 options 顯 CircularProgress + loadingText。
-   *  Trigger 不變(user 隨時可開)。對齊 MUI Autocomplete `loadingText` + Field SSOT + Empty 元件 compose。*/
+   *  Forward 給 SelectMenu primitive SSOT;spinner 只在無可顯示選項時佔 CommandEmpty slot 顯 CircularProgress
+   *  (已有 options 保留顯示,不取代)。Trigger 不變(user 隨時可開)。
+   *  對齊 MUI Autocomplete「loading 只在無 suggestions 時顯 loadingText」+ Field SSOT + Empty 元件 compose。*/
   loading?: boolean
   /** 搜尋框位置：menu（浮層內，預設）或 trigger（inline input） */
   searchIn?: 'menu' | 'trigger'
@@ -389,6 +405,16 @@ export interface ComboboxProps {
   searchAriaLabel?: string
   /** Empty-selection placeholder text。Default: 「選擇…」 */
   emptyPlaceholder?: string
+  /** 搜尋無結果提示(2026-07-04 Q4 拍板接線)— forward SelectMenu primitive SSOT(default「沒有符合的選項」) */
+  emptyText?: string
+  /** 可建立新選項(creatable tag,2026-07-18 user 拍板 forward)—— 搜尋非空且無完全同名既有選項時,
+   *  dropdown 顯 create row(Plus + `createLabel`);forward 給底層 SelectMenu(邏輯/顯示/互動 SSOT 住在 SelectMenu)。
+   *  僅 searchable 桌機路徑生效(需打字);native mobile 路徑不支援。對齊 Ant tags / react-select Creatable。 */
+  creatable?: boolean
+  /** 建立新選項 callback(forward SelectMenu `onCreate`)。 */
+  onCreate?: (value: string) => void
+  /** create row 文字格式(forward SelectMenu `createLabel`,預設「直接使用「{query}」」)。 */
+  createLabel?: (query: string) => string
   /** a11y:無 Field wrapper 時提供 role='combobox' 的 accessible name(axe aria-input-field-name) */
   'aria-label'?: string
   /** Initial open state(uncontrolled)— 對齊 Select.defaultOpen / Radix Popover canonical。
@@ -400,7 +426,7 @@ export interface ComboboxProps {
    * Selected tag pill 客製 render(2026-05-07 v15.5)。
    *
    * 設了 → 每個 selected tag pill 走 consumer 提供的 ReactNode(收 item={value, label}
-   * + onRemove,consumer 自己組 onDismiss);沒設 → 走預設 `<Tag>` text-only pill。
+   * + onRemove,consumer 自己組 onRemove);沒設 → 走預設 `<Tag>` text-only pill。
    *
    * 用例:PeoplePicker(multi)用此 slot 把 selected tag 換成 avatar + name pill,而非
    * 純文字 Tag。對齊 PeoplePicker = Combobox wrapper SSOT。
@@ -408,18 +434,21 @@ export interface ComboboxProps {
   tagRenderer?: (item: { value: string; label: string }, onRemove: () => void) => React.ReactNode
   /**
    * 2026-05-14 I4 fix:Optional renderer for hidden items in `+N` overflow popover
-   * (對齊 display MultiPersonDisplay overflow popover 含 avatar SSOT)。PeoplePicker stack
-   * pass 此 prop 讓 hidden items 顯 avatar + name(同 display path)。Default fallback
+   * (對齊 view path MultiPersonDisplay overflow popover 含 avatar SSOT)。PeoplePicker stack
+   * pass 此 prop 讓 hidden items 顯 avatar + name(同 view path)。Default fallback
    * `<Tag>{label}</Tag>` 純文字 backward-compat。
    */
   renderHiddenTag?: (item: { value: string; label: string }) => React.ReactNode
   /**
+   * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
+   *
    * Optional class merged into each tag's outer measurement wrapper (2026-05-07 v15.13)。
    * Stack avatar 模式用此 hook point 達成 sibling-level overlap (`-ml-0.5`) + group selector
    * (`group/avatar`)— 既保留 Combobox 必要 measurement wrapper,又讓 dismiss/overlap 視覺生效。
    */
   tagWrapperClassName?: string
-  /** 2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
+  /** @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
+   *  2026-05-16:overflow chip wrapper 套此 class(對齊 tagWrapperClassName)。Stack 模式
    *  pass `-ml-0.5 first:ml-0` 讓 chip 跟 avatar 同 overlap step,物理上 chip = 1 個 slot 不
    *  外加 24px。Default undefined = chip 不 overlap(text-tag mode 等)。*/
   overflowWrapperClassName?: string
@@ -429,6 +458,8 @@ export interface ComboboxProps {
    * (CSS `gap` 套在 flex container 上會強制 sibling spacing,蓋過 negative margin)。
    * **Q2 known tradeoff**:0 後 useOverflowCount 仍按 wrapper.offsetWidth 累加(不含 overlap
    * 補償)→ +N 偏保守。當前接受;若需精準可 future 加 `overlapPx` 補償邏輯。
+   *
+   * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer hook)。
    */
   tagAreaGapPx?: number
   /**
@@ -438,10 +469,12 @@ export interface ComboboxProps {
    * paddingLeft - paddingRight` 自動 include**(`parseFloat(cs.paddingLeft)` 從 container CSS 抓)
    * → width calc 不漂移,無 side-effect。
    *
+   * @internal PeoplePicker stack wrapper 內部協議 — 目前無 active consumer(PeoplePicker 傳 undefined),保留供未來精準 padding;新 consumer 請先評估。
+   *
    * **2026-05-13 v2 deprecate path**:原 PeoplePicker pass `{8}` 假設「Combobox tagPadding=4px,4+8=12」
    * 但 `tagPadding[size]` 是 density-dependent calc `(field-height - icon-size) / 2`,只在 md size +
    * default density 才 = 4px;其他 size/density 漂 6/8px → 4+8=12 公式破。改 PeoplePicker 直接 inject
-   * `!px-3` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
+   * `!px-[var(--field-px)]` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
    * 走 undefined。Future 仍保留此 prop 給其他 consumer 精準調整 padding,但 PeoplePicker 已不再用。
    */
   tagAreaPaddingLeftPx?: number
@@ -452,6 +485,8 @@ export interface ComboboxProps {
    */
   overflowShape?: ComboboxOverflowShape
   /**
+   * @internal PeoplePicker stack wrapper 內部協議 — end-user 勿用(measurement-layer override)。
+   *
    * 2026-05-15 Bug 3 fix:override visible count via formula-based primitive(opt-in;default 走
    * DOM-based `useOverflowCount`)。PeoplePicker stack mode 用 `avatar-stack-overflow` primitive
    * deterministic formula 計算 visible count,forward 給 Combobox bypass DOM offsetWidth
@@ -460,8 +495,8 @@ export interface ComboboxProps {
   visibleCountOverride?: number
   /**
    * Display 是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 tag stack,backward compat)。
-   * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 tag stack,backward compat)。
+   * 設 true 時 view 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
    * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -470,40 +505,45 @@ export interface ComboboxProps {
 // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反)
 const getIconSize = (size: string) => ICON_SIZE[size as 'sm' | 'md' | 'lg']
 
-// ── Shared readonly/disabled/display render ─────────────────────────────────
+// ── Shared readonly/disabled/view render ─────────────────────────────────
 
 function ReadonlyMultiSelect({
-  mode, variant: variantProp, size, options, value, wrap, className, showDisplayEndIcon = false,
-}: Pick<ComboboxProps, 'mode' | 'variant' | 'size' | 'options' | 'value' | 'wrap' | 'className' | 'showDisplayEndIcon'>) {
+  mode, variant: variantProp, width, size, options, value, wrap, className, showDisplayEndIcon = false,
+}: Pick<ComboboxProps, 'mode' | 'width' | 'size' | 'options' | 'value' | 'wrap' | 'className' | 'showDisplayEndIcon'> & {
+  /** @internal 2026-07-14 API 策展 E:內部 render helper 吃 FieldVariantInternal(naked 由 cell-registry 通道傳入)*/
+  variant?: FieldVariantInternal
+}) {
   const resolvedMode = mode ?? 'readonly'
+  const emptyDisplay = useFieldEmptyDisplay()
   const variant = variantProp ?? 'default'
   const sz = size ?? 'md'
   const iconSize = sz === 'lg' ? 20 : 16
+  const tagHeight = sz === 'sm' ? 20 : 24
   const containerRef = React.useRef<HTMLDivElement>(null)
   const hasTags = (value?.length ?? 0) > 0
 
-  // mode='display'(Phase B2 2026-05-05):純內容輸出 — tag stack 不包 Field wrapper / 不 reserve 高度。
+  // mode='view'(Phase B2 2026-05-05):純內容輸出 — tag stack 不包 Field wrapper / 不 reserve 高度。
   //   對齊原 ComboboxDisplay sub-component(retired)。
   //   Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix ChevronDown,
-  //   與 edit 同結構消除 cell display↔edit 像素偏移(Layer-B padding mismatch)。
-  if (resolvedMode === 'display') {
+  //   與 edit 同結構消除 cell view↔edit 像素偏移(Layer-B padding mismatch)。
+  if (resolvedMode === 'view') {
     if (!showDisplayEndIcon) {
-      // 2026-05-14 I2 fix(spec contract (e) display typography canonical):empty bare span 套
+      // 2026-05-14 I2 fix(spec contract (e) view typography canonical):empty bare span 套
       // `fieldDisplayTextClass(sz)`(sm/md→text-body,lg→text-body-lg)— 對齊跨 Field family 統一。
-      if (!hasTags) return <span className={cn(fieldDisplayTextClass(sz), 'text-fg-muted', className)}>{EMPTY_DISPLAY}</span>
+      if (!hasTags) return <span className={cn(fieldDisplayTextClass(sz), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
       return (
         <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap} />
       )
     }
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant, size: sz }), hasTags && tagPadding[sz], className)}
-        data-field-mode="display"
+        className={cn(fieldWrapperStyles({ mode: 'view', variant, width, size: sz }), hasTags && tagPadding[sz], className)}
+        data-field-mode="view"
       >
         {hasTags ? (
           <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap} />
         ) : (
-          <span className={cn('flex-1 min-w-0', 'text-fg-muted')}>{EMPTY_DISPLAY}</span>
+          <span className={cn('flex-1 min-w-0', fieldEmptyColorClass(resolvedMode))}>{emptyDisplay}</span>
         )}
         <ItemSuffix className="pointer-events-none">
           <ChevronDown size={iconSize} className="shrink-0 text-fg-muted" aria-hidden />
@@ -514,17 +554,26 @@ function ReadonlyMultiSelect({
 
   return (
     <div ref={containerRef}
-      className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), hasTags && tagPadding[sz],
+      className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), hasTags && tagPadding[sz],
         // 2026-05-18 #6A Round 1 Step 1/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:451):
-        // readonly/disabled path 對齊 L293 display wrapper 已 ship 的 overflow-hidden fix。
-        // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 display 不對稱。
-        wrap ? 'flex-wrap py-1' : 'overflow-hidden', className)}
-      style={{ gap: GAP, ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}>
+        // readonly/disabled path 對齊 L293 view wrapper 已 ship 的 overflow-hidden fix。
+        // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 view 不對稱。
+        // 2026-06-27 對齊 edit path(L598-617):wrap 時 items-start + chevron self-start/tagHeight 鎖第一行;
+        // paddingRight: var(--field-px) re-assert 右緣 12px(tagPadding 對稱 calc 會吃掉右緣,跟 edit 一致)。
+        wrap ? 'flex-wrap items-start py-1' : tagRowOverflowClass, className)}
+      style={{ gap: GAP, paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}
+      aria-disabled={resolvedMode === 'disabled' ? true : undefined}>
       {hasTags ? (
         <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap}
           containerRef={containerRef} disabled={resolvedMode === 'disabled'} />
       ) : (
-        <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+        <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
+      )}
+      {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開下拉) / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
+      {(variant === 'naked' ? !!showDisplayEndIcon : resolvedMode === 'disabled') && (
+        <ItemSuffix className={cn('pointer-events-none', wrap && 'self-start')} style={wrap ? { height: tagHeight } : undefined}>
+          <ChevronDown size={iconSize} className={cn('shrink-0', resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted')} aria-hidden />
+        </ItemSuffix>
       )}
     </div>
   )
@@ -544,32 +593,86 @@ function ReadonlyMultiSelect({
 // target);唯本處 actionable drop。
 type ComboboxInternalProps = ComboboxProps & { __triggerRef?: React.Ref<HTMLDivElement> }
 
+function focusAfterTagRemoval(container: HTMLElement | null, owner: HTMLElement | null) {
+  const active = document.activeElement
+  const buttons = container
+    ? Array.from(container.querySelectorAll<HTMLButtonElement>('[data-collection-remove]'))
+      .filter((button) => button.getClientRects().length > 0)
+    : []
+  const index = buttons.indexOf(active as HTMLButtonElement)
+  const next = index >= 0 ? buttons[index + 1] ?? buttons[index - 1] : undefined
+  const fallback = owner ?? container?.closest<HTMLElement>('[role="combobox"]')
+  ;(next ?? fallback)?.focus()
+
+  // Some renderers intentionally change anatomy at collection length 1 (PeoplePicker stack:
+  // avatar stack → avatar + name). That remounts the button focused above. Re-apply the same
+  // next→previous→owner policy after React commits so focus cannot fall back to body.
+  const preferredIndex = index >= 0
+    ? (buttons[index + 1] ? index : buttons[index - 1] ? index - 1 : -1)
+    : -1
+  window.requestAnimationFrame(() => {
+    const updatedButtons = container
+      ? Array.from(container.querySelectorAll<HTMLButtonElement>('[data-collection-remove]'))
+        .filter((button) => button.getClientRects().length > 0)
+      : []
+    const updatedTarget = preferredIndex >= 0 ? updatedButtons[preferredIndex] : undefined
+    ;(updatedTarget ?? fallback)?.focus()
+  })
+}
+
 function NativeCombobox({
-  mode = 'edit', variant: variantProp, error = false, size = 'md', options, value = [], onChange, placeholder,
-  className, disabled, wrap = false, clearable = false, showDisplayEndIcon = false,
+  mode, variant: variantProp, width, error = false, size = 'md', options, value = [], onChange, placeholder,
+  className, disabled: disabledProp, wrap = false, clearable = false, showDisplayEndIcon = false,
+  // Display-layer parity(2026-08-05 user 拍板):renderer / overflow props 必雙分支(custom/native)
+  // 同消費 — 原 native 硬編碼 <Tag> 令 PeoplePicker 手機 edit 掉回文字 pill、avatar stack 全滅
+  // (touch 分支從未接 display 層的病根)。新增 renderer-affecting prop 時必同步本 destructure。
+  tagRenderer, renderHiddenTag, tagWrapperClassName, overflowWrapperClassName,
+  overflowShape, visibleCountOverride, tagAreaGapPx, tagAreaPaddingLeftPx,
   __triggerRef,
+  'aria-label': ariaLabel,
 }: ComboboxInternalProps) {
+  // a11y(2026-07-14 dim10):touch/native 路徑同樣接 fieldCtx — id 讓 FieldLabel htmlFor
+  // 命名 native <select>;describedby/errormessage/required 對齊 desktop CustomCombobox trigger。
   const fieldCtx = useFieldContext()
-  const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
-  const resolvedMode = disabled ? 'disabled' : mode
+  const disabled = useResolvedFieldDisabled(disabledProp)
+  const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
+  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
+  const resolvedMode = useResolvedFieldMode({ mode, disabled })
   const iconSize = getIconSize(size)
   const showClear = clearable && value.length > 0 && resolvedMode === 'edit'
 
-  const handleRemove = (v: string) => onChange?.(value.filter(x => x !== v))
   const handleAdd = (v: string) => { if (!value.includes(v)) onChange?.([...value, v]) }
 
+  // React #310 fix(對齊 select.tsx):hooks 必在 conditional early-return 前無條件呼叫。
+  // resolvedMode 在 edit↔非edit 切換(<Field mode/disabled> cascade / DataTable cell 進出編輯)時
+  // hook 數量不可變動,否則 Rules of Hooks violation → React #310 「rendered fewer/more hooks」crash。
+  const selectRef = React.useRef<HTMLSelectElement>(null)
+  const tagAreaRef = React.useRef<HTMLDivElement>(null)
+  const handleRemove = (v: string) => {
+    focusAfterTagRemoval(tagAreaRef.current, selectRef.current)
+    onChange?.(value.filter(x => x !== v))
+  }
+
   if (resolvedMode !== 'edit') {
-    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
+    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
   }
 
   const items = value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v }))
   const unselected = options.filter(o => !value.includes(o.value))
-  const selectRef = React.useRef<HTMLSelectElement>(null)
-  const tagAreaRef = React.useRef<HTMLDivElement>(null)
   const tagHeight = size === 'sm' ? 20 : 24
+  const tagAreaGap = tagAreaGapPx ?? GAP
 
   const selectDropdown = unselected.length > 0 ? (
     <select ref={selectRef} value="" onChange={(e) => handleAdd(e.target.value)}
+      // a11y(2026-07-14 dim10):accessible name — FieldLabel htmlFor 經 id 命名 native select;
+      // consumer aria-label 優先,否則 fieldCtx.labelId fallback(對齊 select.tsx:240 accname 優先序)。
+      id={fieldCtx?.id}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabel ? undefined : fieldCtx?.labelId}
+      aria-invalid={error || undefined}
+      aria-required={fieldCtx?.required || undefined}
+      aria-describedby={fieldCtx?.descriptionId}
+      aria-errormessage={error ? fieldCtx?.errorId : undefined}
       className={cn('bg-transparent outline-none border-none p-0 text-[inherit] font-[inherit] leading-[inherit] text-fg-muted cursor-pointer appearance-none',
         value.length > 0 ? 'absolute inset-0 w-full h-full opacity-0 z-0 cursor-pointer' : 'relative z-10 flex-1 min-w-20')}>
       <option value="" disabled>{placeholder ?? '選擇...'}</option>
@@ -578,22 +681,45 @@ function NativeCombobox({
   ) : null
 
   return (
-    <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value.length > 0 && tagPadding[size], 'relative',
-      wrap && 'items-start py-1', error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-      style={{ paddingRight: '0.75rem', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
+    <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), value.length > 0 && tagPadding[size], 'relative',
+      wrap && 'items-start py-1', className)}
+      style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
       onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
       {/* 2026-05-18 F2 sync(per user verbatim「modifying 修好 PeoplePicker stack 後改壞 Combobox tag display」
           + 「tag 應該要判斷所在空間最多可以呈現幾個tag(包括＋n)去自動判斷何時要變成+n」):
-          edit path tagArea 對齊 display path L293 已 ship 的 `overflow-hidden` fix。原 `overflow-visible`
+          edit path tagArea 對齊 view path L293 已 ship 的 `overflow-hidden` fix。原 `overflow-visible`
           讓 tag 視覺越界蓋 chevron / +N indicator(useOverflowCount measurement 對但 CSS overflow 仍露)。
           M10 violation root cause:2026-05-15 F1 Q3 只 fix display path,edit + Native(L518)沒同步。 */}
-      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : 'overflow-hidden')} style={{ gap: GAP }}
+      {/* Display-layer parity(2026-08-05):OverflowTagList 消費與 CustomCombobox(L859-867)同一組
+          renderer / overflow props — tagRenderer 存在(PeoplePicker avatar stack 等)→ 手機 edit 與
+          桌機同視覺;未傳 → 原 <Tag> 文字 pill 預設不變。 */}
+      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : tagRowOverflowClass)} style={{ gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }}
         onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
         <OverflowTagList containerRef={tagAreaRef} items={items} size={size} wrap={wrap}
+          tagWrapperClassName={tagWrapperClassName}
+          // Review fix(2026-08-05 F2):+N 抬到 overlay 上(可見不被壓)且 pointer 穿透 —
+          // touch 無 hover 開不了 HoverCard,tap 穿透開原生 picker(原生多選單列全員含 hidden,
+          // 即 touch 的 overflow 檢視/增刪路徑)。桌機 CustomCombobox 呼叫端不變。
+          overflowWrapperClassName={cn(overflowWrapperClassName, 'relative z-10 pointer-events-none')}
+          gap={tagAreaGap}
+          overflowShape={overflowShape}
+          visibleCountOverride={visibleCountOverride}
           renderTag={(item) => (
-            <Tag size={size} className="shrink-0 relative z-10" onClick={() => { selectRef.current?.showPicker?.(); selectRef.current?.focus() }}
-              onDismiss={() => handleRemove(item.value)}>{item.label}</Tag>
-          )} onRemove={handleRemove} trailing={value.length === 0 ? selectDropdown : undefined} />
+            tagRenderer
+              // Review fix(2026-08-05 F1/F3):renderer 輸出必套「抬升+穿透+按鈕回收」三件套 —
+              // relative z-10 抬到透明 native <select> overlay(z-0)之上(對齊 default <Tag> 的
+              // z-10;wrap 分支 OverflowTagList 無 wrapper div 時尤其必要);pointer-events-none 讓
+              // 非互動顯示區 tap 穿透 overlay(spec「點擊任何位置喚起原生 picker」);[&_button]:auto
+              // 回收 remove X / Tag onRemove 點擊。
+              // 幾何必須與 OverflowTagList non-wrap wrapper(`shrink-0 max-w-full`,L312)一致:
+              // wrap 分支 renderer 輸出是 flex row 的直接子項,若帶 `flex-1` 會被拉伸填滿列寬
+              // (2026-08-05 user 抓「手機兩顆 tag gap 怪」的 root cause)。
+              ? <span className="relative z-10 shrink-0 max-w-full inline-flex items-center pointer-events-none [&_button]:pointer-events-auto">{tagRenderer(item, () => handleRemove(item.value))}</span>
+              : <Tag size={size} className="shrink-0 relative z-10" onClick={() => { selectRef.current?.showPicker?.(); selectRef.current?.focus() }}
+                  onRemove={() => handleRemove(item.value)}>{item.label}</Tag>
+          )}
+          renderHiddenTag={renderHiddenTag}
+          onRemove={handleRemove} trailing={value.length === 0 ? selectDropdown : undefined} />
       </div>
       {value.length > 0 && selectDropdown}
       <ItemSuffix className={cn('relative z-10 pointer-events-none', wrap && 'self-start')}
@@ -615,11 +741,15 @@ function NativeCombobox({
 // ── Custom Combobox (desktop — consumes SelectMenu) ───────────────────
 
 function CustomCombobox({
-  mode = 'edit', variant: variantProp, error: errorProp = false, size = 'md', options, value = [], onChange, placeholder,
+  mode, variant: variantProp, width, error: errorProp = false, size = 'md', options, value = [], onChange, placeholder,
   className, disabled: disabledProp, wrap = false, clearable = false, searchable = false, loading, searchIn = 'menu',
   searchPlaceholder = '搜尋…', // i18n-allow: DS default
   searchAriaLabel = '搜尋選項', // i18n-allow: DS default
   emptyPlaceholder = '選擇…', // i18n-allow: DS default
+  emptyText,
+  creatable = false,
+  onCreate,
+  createLabel,
   defaultOpen = false,
   onOpenChange,
   __triggerRef,
@@ -636,10 +766,11 @@ function CustomCombobox({
 }: ComboboxInternalProps) {
   const tagAreaGap = tagAreaGapPx ?? GAP
   const fieldCtx = useFieldContext()
-  const error = errorProp || (fieldCtx?.invalid ?? false)
-  const disabled = disabledProp ?? fieldCtx?.disabled
-  const resolvedMode = disabled ? 'disabled' : mode
-  const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+  const error = useResolvedFieldInvalid(errorProp)
+  const disabled = useResolvedFieldDisabled(disabledProp)
+  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
+  const resolvedMode = useResolvedFieldMode({ mode, disabled })
+  const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   const iconSize = getIconSize(size)
   const showClear = clearable && value.length > 0 && resolvedMode === 'edit'
   const [open, setOpen] = React.useState(defaultOpen)
@@ -650,13 +781,16 @@ function CustomCombobox({
   // a11y: 為 listbox 容器(SelectMenu 內 PopoverContent)建立穩定 id,讓 trigger 的
   // aria-controls 能指向它(WAI-ARIA combobox pattern 要求)。React.useId 在 SSR/CSR 都穩定。
   const listboxId = React.useId()
+  // a11y(2026-07-05 D4):追蹤 cmdk active item id → searchIn='trigger' 搜尋 input 綁 aria-activedescendant
+  // (機制詳 select-menu.tsx useActiveDescendant docblock;必在 early return 前呼叫 — React #310 hook 順序)。
+  const activeOptionId = useActiveDescendant(listboxId, open)
 
   React.useEffect(() => { if (!open) setSearch('') }, [open])
 
-  if (resolvedMode !== 'edit') {
-    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
-  }
-
+  // React #310 fix(對齊 select.tsx):以下 hooks(useMemo/useRef)必在 conditional early-return 前
+  // 無條件呼叫。resolvedMode 在 edit↔非edit 切換時 hook 數量不可變動,否則 Rules of Hooks
+  // violation → React #310 「rendered fewer/more hooks」crash(ReadonlyMultiSelect 用不到這些值,
+  // 多算無害,對齊 select.tsx hoist pattern)。
   const items = React.useMemo(
     () => value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v })),
     [value, options]
@@ -664,7 +798,10 @@ function CustomCombobox({
   const tagAreaRef = React.useRef<HTMLDivElement>(null)
   const tagHeight = size === 'sm' ? 20 : 24
 
-  const handleRemove = (v: string) => onChange?.(value.filter(x => x !== v))
+  const handleRemove = (v: string) => {
+    focusAfterTagRemoval(tagAreaRef.current, inputRef.current)
+    onChange?.(value.filter(x => x !== v))
+  }
 
   // searchIn='trigger' 時由 trigger input 過濾，不走 SelectMenu 內建搜尋
   const filteredOptions = React.useMemo(
@@ -674,7 +811,7 @@ function CustomCombobox({
     [searchable, searchIn, search, options]
   )
 
-  // 轉換 SelectOption → SelectMenuOption
+  // 轉換 ComboboxOption → SelectMenuOption
   // 2026-05-10 post-Issue-4 follow-up:forward 全 SelectMenuOption surface(avatar / description /
   // disabled / icon / group)— 修先前 PeoplePicker multi-mode dropdown 漏 avatar drift bug。
   const menuOptions: SelectMenuOption[] = React.useMemo(
@@ -690,29 +827,62 @@ function CustomCombobox({
     [filteredOptions]
   )
 
-  const chevronEl = <ChevronDown size={iconSize} className={cn('shrink-0 text-fg-muted transition-transform', open && 'rotate-180')} aria-hidden />
+  if (resolvedMode !== 'edit') {
+    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
+  }
+
+  const chevronEl = <ChevronDown size={iconSize} className={cn('shrink-0 text-fg-muted transition-transform motion-reduce:duration-0', open && 'rotate-180')} aria-hidden />
 
   const trigger = (
     <div
       ref={__triggerRef}
       id={fieldCtx?.id}
-      role="combobox" aria-expanded={open} aria-controls={listboxId} tabIndex={0}
+      role="combobox" aria-expanded={open} aria-haspopup="listbox" aria-controls={listboxId} tabIndex={0}
       aria-label={ariaLabel}
+      // a11y(2026-07-14 dim-10):div-based role=combobox 的 <label for> 無效,接 FieldLabel labelId
+      // (field-context.ts labelId jsDoc);consumer aria-label 優先 — 與 sibling select.tsx:705 同款 guard。
+      aria-labelledby={ariaLabel ? undefined : fieldCtx?.labelId}
       aria-invalid={error || undefined}
       aria-required={fieldCtx?.required || undefined}
       aria-describedby={fieldCtx?.descriptionId}
       aria-errormessage={error ? fieldCtx?.errorId : undefined}
-      className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value.length > 0 && tagPadding[size], 'relative cursor-pointer',
+      className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), value.length > 0 && tagPadding[size], 'relative cursor-pointer',
         wrap && 'items-start py-1',
         // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
-        // 統一處理 — open=灰深(data-state)/ focus=藍(focus-within !important)。改一處全 control 跟動。
-        error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-      style={{ paddingRight: '0.75rem', ...(wrap ? { height: 'auto' } : undefined) }}
-      data-field-mode="edit" data-error={error ? '' : undefined}>
+        // 統一處理 — open=灰深(data-state)/ focus=藍;2026-07-04 Q1:error 亦收進 error variant。
+        className)}
+      style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }}
+      data-field-mode="edit" data-error={error ? '' : undefined}
+      // WAI-ARIA APG combobox 鍵盤開啟語意 — 對齊 sibling Select(select.tsx:593-598)。
+      // <div role=combobox> 不像 native <button> 自動 synthesize Enter/Space click,故顯式補:
+      //   Enter/Space → 開(searchable 時不攔,讓 inline search input 自行處理打字);
+      //   Escape → 關;ArrowDown → 開(APG required combobox 展開鍵,僅在 closed 時攔,
+      //   open 後不 preventDefault 讓方向鍵自由流向選單導覽)。
+      // 純 additive:此 trigger 原無 onKeyDown,不覆寫既有 handler;open 邏輯仍走 setOpen SSOT。
+      onKeyDown={(e) => {
+        // a11y(2026-07-14 dim-10):Enter/Space 來自 descendant 互動元素(Tag 移除 / clear 按鈕)
+        // 時直接放行 —— 否則下方 preventDefault 會取消 native button activation(鍵盤永遠按不動
+        // 按鈕)。guard 限 Enter/Space + button 類:search input 的 Enter 仍走 cmdk 選項選取
+        // (forwardKeyToListbox),Escape / 方向鍵仍走 combobox 導覽。
+        if (
+          (e.key === 'Enter' || e.key === ' ') &&
+          e.target !== e.currentTarget &&
+          (e.target as HTMLElement).closest?.('button, a, [role="button"]')
+        ) return
+        // 2026-07-05 D4 P0:open 後 ArrowUp/Down/Enter 轉送 cmdk root(select-menu.tsx forwardKeyToListbox)
+        if (open && forwardKeyToListbox(listboxId, e)) return
+        if (e.key === 'Enter' || e.key === ' ') {
+          // 2026-06-11 P0 a11y(R2,同 select.tsx 修):Combobox 恆 searchable → 原 `!searchable`
+          // guard 使 Enter/Space 永遠開不了(僅 ArrowDown 可)。正確 guard = !open。
+          if (!open) { e.preventDefault(); setOpen(true) }
+        }
+        if (e.key === 'ArrowDown' && !open) { e.preventDefault(); setOpen(true) }
+        if (e.key === 'Escape') setOpen(false)
+      }}>
       {/* 2026-05-18 #6A Round 1 Step 2/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:648):
-          CustomCombobox edit non-wrap tagArea 對齊 L293 display + L451 readonly + L518 native edit 已 ship 的 overflow-hidden fix。
+          CustomCombobox edit non-wrap tagArea 對齊 L293 view + L451 readonly + L518 native edit 已 ship 的 overflow-hidden fix。
           原 overflow-visible 讓 tag 越界蓋 chevron / +N indicator(user 圖三)。M10 propagation 完整 4-path align。 */}
-      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : 'overflow-hidden')} style={{ gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }}>
+      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : tagRowOverflowClass)} style={{ gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }}>
         {value.length > 0 ? (
           <OverflowTagList containerRef={tagAreaRef} items={items} size={size} wrap={wrap}
             tagWrapperClassName={tagWrapperClassName}
@@ -724,7 +894,7 @@ function CustomCombobox({
               tagRenderer
                 ? tagRenderer(item, () => handleRemove(item.value))
                 : <Tag size={size} className="shrink-0 relative z-10"
-                    onDismiss={() => handleRemove(item.value)}>{item.label}</Tag>
+                    onRemove={() => handleRemove(item.value)}>{item.label}</Tag>
             )}
             renderHiddenTag={renderHiddenTag}
             onRemove={handleRemove}
@@ -738,6 +908,8 @@ function CustomCombobox({
                 // empty-state fallback to trigger placeholder canonical。
                 placeholder={items.length === 0 ? placeholder : ''} onClick={(e) => { e.stopPropagation(); setOpen(true) }}
                 aria-label={searchAriaLabel}
+                // a11y(2026-07-05 D4):cmdk active item id(useActiveDescendant)→ SR 播報方向鍵導覽中的 option
+                aria-activedescendant={activeOptionId}
                 className="flex-1 min-w-[60px] bg-transparent outline-none text-body leading-compact relative z-10" />
             ) : undefined} />
         ) : (
@@ -769,12 +941,17 @@ function CustomCombobox({
   return (
     <SelectMenu
       loading={loading}
+      emptyText={emptyText}
       options={menuOptions}
       value={value}
       onValueChange={onChange as (value: string | string[]) => void}
       multiple
+      creatable={creatable}
+      onCreate={onCreate}
+      createLabel={createLabel}
       searchable={searchable && searchIn === 'menu'}
       searchPlaceholder={searchPlaceholder}
+      searchAriaLabel={searchAriaLabel}
       size={size}
       open={open}
       onOpenChange={(o) => { setOpen(o); onOpenChange?.(o) }}
@@ -792,14 +969,17 @@ function CustomCombobox({
 // ── Public component ────────────────────────────────────────────────────────
 
 const Combobox = React.forwardRef<HTMLDivElement, ComboboxProps>(
-  (props, ref) => {
+  ({ size: sizeProp, ...props }, ref) => {
+    // B 組 cascade fix:public wrapper 一處 resolve size(prop>Field>surface>md)後 forward 給內層,
+    // 讓 <Field size> / DataTable cell surface-size 對 Combobox 生效(內層默認 'md' 被此顯式 size 覆蓋)。
+    const size = useResolvedFieldSize(sizeProp)
     // 2026-05-16 真 root cause fix:之前用 `_ref` drop ref。修為 forward 給 internal
     // `__triggerRef`,讓 PeoplePicker stack 透過 ref 量 trigger DOM(visibleCountOverride
     // 才生效)。對齊 React forwardRef public-API canonical(MUI Autocomplete / Radix
     // Popover.Trigger 共識)+ codex M31 Step 5 比稿 verdict + DS-wide ref-drop iceberg audit。
     const isMobile = useIsTouchDevice()
-    if (isMobile) return <NativeCombobox {...props} __triggerRef={ref} />
-    return <CustomCombobox {...props} __triggerRef={ref} />
+    if (isMobile) return <NativeCombobox {...props} size={size} __triggerRef={ref} />
+    return <CustomCombobox {...props} size={size} __triggerRef={ref} />
   }
 )
 Combobox.displayName = 'Combobox'
@@ -815,7 +995,8 @@ export const comboboxMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — trigger 走 Field chrome(field-wrapper 無按壓態)、menu row 走 MenuItem(其 meta 無 active)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted'],