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

package/src/components/PeoplePicker/people-picker.tsx

@@ -1,23 +1,32 @@
 // @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.
-// @placeholder-vocabulary-allow: 1-cycle backward-compat — `placeholder` 已加(trigger empty SSOT),`emptyPlaceholder={emptyText}` forward 仍保留讓既有 consumer 不被 silent break;Combobox line 509 `placeholder ?? emptyPlaceholder` fallback → placeholder 永遠 takes precedence。Future cycle 移除 emptyPlaceholder forward(per field-controls.spec.md 共享 contract b)。
-// @cell-metric-escape-allow: comment describes RETIRED `tagAreaPaddingLeftPx={8}` magic — current code is surface-guarded (`surface === 'form'` only injects `!px-3`; table-cell context untouched, lets naked `!px-[var(--table-cell-px)]` SSOT take over). Hook regex grep'd the comment word, not the live code path. Per (a) fix 2026-05-13 user-approved Path a.
+// @placeholder-vocabulary-allow: 2026-07-04 Q4 完成 field-controls.spec.md 共享 contract b — emptyPlaceholder forward 已移除,emptyText 直達 Combobox → SelectMenu emptyText(search-empty 真住所);placeholder 為 trigger empty SSOT。
+// @cell-metric-escape-allow: comment describes RETIRED `tagAreaPaddingLeftPx={8}` magic — current code is surface-guarded (`surface === 'form'` only injects `!px-[var(--field-px)]`; table-cell context untouched, lets naked `!px-[var(--table-cell-px)]` SSOT take over). Hook regex grep'd the comment word, not the live code path. Per (a) fix 2026-05-13 user-approved Path a.
 import * as React from 'react'
 import { 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 } from '@/design-system/components/Field/field-wrapper'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
-import { useFieldContext, useFieldSurface } from '@/design-system/components/Field/field-context'
+import { useFieldSurface, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant } from '@/design-system/components/Field/field-context'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { Tag } from '@/design-system/components/Tag/tag'
-import { Select } from '@/design-system/components/Select/select'
-import { Combobox } from '@/design-system/components/Combobox/combobox'
-import { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonNameCard, resolvePerson, type PersonValue } from './person-display'
+import { Select as SelectPublic } from '@/design-system/components/Select/select'
+import { Combobox as ComboboxPublic } from '@/design-system/components/Combobox/combobox'
+import { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonProfileCard, resolvePerson, type PersonValue } from './person-display'
 import {
   getAvatarStackVisibleCount,
   AVATAR_STACK_AVATAR_PX,
   AVATAR_STACK_OVERFLOW_CHIP_PX,
 } from './avatar-stack-overflow'
+import type { WithFieldVariantInternal } from '@/design-system/components/Field/field-types'
+
+// ── @internal naked variant forward 通道(2026-07-14 API 策展 E)──────────────────────────
+// naked 已從公開 FieldVariant 拆出(field-types.ts FieldVariantInternal)。PeoplePicker 是
+// Select / Combobox 的 wrapper:cell-registry 傳入的 naked 需原樣 forward 給 primitive
+// (M30 wrapper forward 全 primitive surface)。型別層 widen,純型別、零 runtime。
+const Select = SelectPublic as WithFieldVariantInternal<typeof SelectPublic>
+const Combobox = ComboboxPublic as WithFieldVariantInternal<typeof ComboboxPublic>
 // Pure helpers extracted to sibling for file-size budget(2026-05-18,P1 ≤ 500 lines)。
 // 不消費 component closure 的純 constant / 純 mapping function 全部搬走,主檔保留 SSOT-bearing
 // render logic(消費 Combobox / Select / state 等 closure 的部分)。
@@ -29,16 +38,18 @@ import {
   findPerson,
 } from './people-picker-helpers'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
+import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
 export { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass }
 
 // ── PeoplePicker ────────────────────────────────────────────────────────────
 // **2026-05-07 v15.6 SSOT 重構 v2**:
 //
 //   - **single mode** wraps `<Select searchable selectedItemRenderer>`
-//   - **multi mode** 兩種 displayMode(consumer 自選):
+//   - **multi mode** 兩種 displayMode(consumer 自選),**皆 wrap `<Combobox>`**(同 SSOT,
+//     差別在 tagRenderer 視覺):
 //       - **'stack'**(default,baseline 既有視覺)— Avatar 疊合 + `+N` overflow indicator,
-//         不可 wrap。Trigger 自組 + 直接 wrap `<SelectMenu multiple>` primitive,
-//         trigger 內 render `<MultiPersonDisplay>` reuse baseline primitive(SSOT)。
+//         不可 wrap。tagRenderer 渲染 avatar stack(visible count 走 shared `avatar-stack-overflow`
+//         primitive deterministic formula,2026-05-15 Bug 3 fix;view 路徑 `<MultiPersonDisplay>` 同 primitive)。
 //         對齊 Notion / Linear / Atlassian / Slack 多人 quick-glance idiom。
 //       - **'pill'**(opt-in)— 每人 Tag pill,可 wrap。Wrap `<Combobox tagRenderer>`,
 //         tagRenderer 用 Tag 元件 `avatar` prop SSOT(不塞 children)。
@@ -49,11 +60,18 @@ export { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass }
 // 讓 consumer 可傳 `id` / `data-testid` / `onBlur` / `onFocus` / `aria-*` 等 HTML root props,
 // component 內部 `...rest` forward 到 trigger 容器(對齊 DS 既有 Combobox / Select 慣例)。
 // `onChange` 衝突走 Omit(本 component 用 PersonValue[] custom signature)。
-export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
-  /** Field mode(edit / display / readonly / disabled),默認 inherit Field context 或 'edit' */
+// 2026-07-17 Dim 26 修:`defaultValue` 一併 Omit — 本元件 controlled-only(spec「Controlled-only
+// rationale」),React.HTMLAttributes 內建的 `defaultValue` 若不 Omit 會讓 consumer 傳入假
+// uncontrolled API,runtime 經 `...rest` 靜默轉送 trigger div 後無效。Omit 本身即 type-level
+// regression(consumer 傳 defaultValue 直接 TS 編譯錯)。DS 先例 steps.tsx:166 同款 Omit。
+export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  /** Field mode(edit / view / readonly / disabled),默認 inherit Field context 或 'edit' */
   mode?: FieldMode
   /** Field chrome variant(對齊 Select / Combobox)*/
   variant?: FieldVariant
+  /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮(value 寬 + slot 寬 + gap + 內 padding);
+   *  chrome 與互動不變。SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+  width?: FieldWidth
   size?: 'sm' | 'md' | 'lg'
   /** 當前已選的人(單選 PersonValue,多選 PersonValue[])*/
   value?: PersonValue | PersonValue[] | null
@@ -64,10 +82,15 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
   /** 2026-05-12 Stream C Issue 4 fix(codex Q3 Cluster C):trigger empty placeholder。
    *  Default '請選擇人員'。**禁** 將 `emptyText`(search-empty)當 trigger placeholder 傳。 */
   placeholder?: string
-  /** 搜尋框 placeholder */
+  /** 搜尋框 placeholder — **僅 multi 模式 panel-top search(`searchIn='menu'`,default)生效**。
+   *  single mode wrap `<Select searchable>` 走 inline-trigger 搜尋,提示取自 `placeholder`
+   *  (Select 無 searchPlaceholder prop);multi `searchIn='trigger'` inline 搜尋同理走
+   *  placeholder 規則(spec「Trigger display SSOT canonical table」)。 */
   searchPlaceholder?: string
-  /** 搜尋無結果訊息(filtered menu empty)。**僅**用於 SelectMenu noResultsText,
-   *  不再 silent 轉 trigger placeholder(2026-05-12 Issue 4 semantic fix)。 */
+  /** Multi 模式搜尋框 accessible name。僅轉送 wrapped Combobox。 */
+  searchAriaLabel?: string
+  /** 搜尋無結果訊息(filtered menu empty)。**僅**用於 SelectMenu `emptyText`(菜單空狀態,
+   *  2026-07-04 Q4 接線完成),不轉 trigger placeholder(2026-05-12 Issue 4 semantic fix)。 */
   emptyText?: string
   className?: string
   disabled?: boolean
@@ -97,9 +120,16 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
    */
   searchIn?: 'menu' | 'trigger'
   /**
-   * Display 是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 PersonDisplay,backward compat)。
-   * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
+   * 一鍵清空(2026-08-05):X 在 ChevronDown 左,family SSOT → field-controls.spec.md「下拉箭頭」段。
+   * 機械轉發 wrapped Select(single)/ Combobox(multi)的 `clearable` — X 渲染與清空行為 SSOT 在基座
+   * (SelectClearButton / Combobox clear),本 wrapper 不另 render。何時開的判準繼承 select.spec.md
+   * 「Clearable」:「無選擇是有效狀態」(選填欄位 / 可清 filter)才開;必填欄位不開。
+   */
+  clearable?: boolean
+  /**
+   * View 態是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 PersonDisplay,backward compat)。
+   * 設 true 時 view 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
    * 與 edit (Select / Combobox wrapped) 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -110,54 +140,143 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
 const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(function PeoplePicker({
   mode: modeProp,
   variant: variantProp,
-  size = 'md',
+  width,
+  size: sizeProp,
   value,
   onChange,
   people = [],
   placeholder = '請選擇人員', // i18n-allow: DS default(2026-05-12 Stream C Issue 4)
   searchPlaceholder = '搜尋人員…', // i18n-allow: DS default
+  searchAriaLabel = '搜尋人員', // i18n-allow: DS default
   emptyText = '沒有符合的人員', // i18n-allow: DS default — only for SelectMenu noResultsText
   className,
-  disabled,
+  disabled: disabledProp,
   defaultOpen = false,
   onOpenChange,
   multiDisplay = 'stack',
   pillShowAvatar = true,
   pillWrap = true,
   searchIn = 'menu',
+  clearable = false,
   showDisplayEndIcon = false,
   'aria-label': ariaLabel,
   ...rest
 }, ref) {
-  const fieldCtx = useFieldContext()
   const surface = useFieldSurface()
-  const mode: FieldMode = modeProp ?? fieldCtx?.mode ?? 'edit'
-  const resolvedMode: FieldMode = disabled ? 'disabled' : mode
-  const resolvedVariant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+  const emptyDisplay = useFieldEmptyDisplay()
+  const size = useResolvedFieldSize(sizeProp)  // B 組 cascade fix
+  const disabled = useResolvedFieldDisabled(disabledProp)
+  // 2026-06-08 SSOT:mode/disabled/variant 統一經 helper;修 <Field disabled> 漏 cascade(原只讀 fieldCtx.mode)
+  const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled })
+  const resolvedVariant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   const isMulti = Array.isArray(value)
   const isEmpty = !value || (isMulti && value.length === 0)
+  // 觸控多選一律走既有 pill 型態(2026-08-05 user 拍板:「手機上自動把多選 people picker 改成
+  // combobox 的型態,所有樣式互動都是 combobox 的 SSOT,不要再造輪子」)。理由:stack 的移除鈕
+  // 是 hover-reveal,觸控沒有 hover;恆顯 X 又太亂(user 否決)。pill 是 DS 既有 canonical
+  // (`multiDisplay='pill'` + Tag `avatar` prop),每顆 pill 自帶 X = Combobox tag 移除 SSOT。
+  // 桌機(fine pointer)完全不受影響:仍是 avatar stack + 圓形 +N + hover X。
+  // consumer 顯式傳 'pill' 時本行為 no-op(同值)。hook 必在任何 early return 前呼叫(React #310)。
+  // **只在 form surface 降階**(2026-08-05):table-cell / inline-edit / toolbar 維持 stack —
+  // cell 的 view↔edit 像素對齊與固定列高契約不得被 pill 的 wrap 破壞(user:「尤其是 table
+  // 的部分」)。cell 觸控編輯本就走原生 picker,移除成員在 picker 內完成。
+  const isTouch = useIsTouchDevice()
+  const effectiveMultiDisplay = isTouch && isMulti && surface === 'form' ? 'pill' : multiDisplay
+
+  // 2026-07-05 D3 P0 修:以下派生 + 4 hooks 原宣告在 view/readonly/single/pill 四個 early return
+  // 之後 — 同一 mounted instance 的 resolvedMode 於 edit↔view/disabled 切換(<Field mode>/<Field
+  // disabled> cascade 正是 runtime 翻轉機制)時 hook 數 7→11 變動 → React #310 crash(與 Combobox
+  // beta.76 / LinkInput 2026-07-04 同家族)。全部 hoist 到任何 early return 之前(對齊 select.tsx
+  // 「所有 hooks 必在 early return 前 call」canonical);effect 加 mode/stack guard,邏輯不變。
+  const selectedNames: string[] = !value
+    ? []
+    : Array.isArray(value)
+      ? value.map(v => resolvePerson(v).name)
+      : [resolvePerson(value).name]
 
-  // ── mode='display' ────────────────────────────────────────────────────────
+  // SSOT visible count compute via formula primitive + ResizeObserver(multi stack mode 專用)
+  const stackContainerRef = React.useRef<HTMLDivElement | null>(null)
+  const [stackVisibleCount, setStackVisibleCount] = React.useState<number | undefined>(undefined)
+  React.useLayoutEffect(() => {
+    if (resolvedMode !== 'edit' || !isMulti || effectiveMultiDisplay !== 'stack' || selectedNames.length <= 1) {
+      setStackVisibleCount(undefined); return
+    }
+    const root = stackContainerRef.current
+    if (!root) return
+    // 2026-05-15 ROOT CAUSE FIX(user 抓「之前說的問題都還是存在」):
+    // stackContainerRef 透過 mergedStackRef 接 Combobox forwarded ref → root **就是** [role=combobox]
+    // div 自己。原 `root.querySelector('[role=combobox]')` 不找 self 永遠 null → trigger=null →
+    // tagArea=null → available=0 → setStackVisibleCount(0) → 整 stack 全 overflow → fallback 到
+    // Combobox DOM-based useOverflowCount(非 deterministic 那個算法)。修:用 root 自己當 trigger,
+    // 從 root 內找 tagArea(flex-1 min-w-0 div)。
+    const calc = () => {
+      // 2026-08-05 native-parity fix(touch 實圖抓「多人只剩 +N」):NativeCombobox root 無
+      // role="combobox"(a11y 在隱藏 <select> 上)→ 原查法 trigger=null → available=0 → 全
+      // overflow。雙分支通用:查無 combobox role 時 root 自身就是 trigger(native __triggerRef
+      // 即 field wrapper root),tagArea(flex-1 min-w-0)兩分支同構。
+      const trigger = root.matches('[role="combobox"]') ? root : (root.querySelector<HTMLElement>('[role="combobox"]') ?? root)
+      const tagArea = trigger?.querySelector<HTMLElement>('div[class*="flex-1"][class*="min-w-0"]')
+      const available = tagArea?.clientWidth ?? trigger?.clientWidth ?? 0
+      const visible = getAvatarStackVisibleCount({
+        availablePx: available,
+        total: selectedNames.length,
+        avatarPx: AVATAR_STACK_AVATAR_PX[size],
+        overflowChipPx: AVATAR_STACK_OVERFLOW_CHIP_PX[size],
+      })
+      setStackVisibleCount(visible)
+    }
+    calc()
+    const ro = new ResizeObserver(calc)
+    ro.observe(root)
+    return () => ro.disconnect()
+  }, [resolvedMode, isMulti, effectiveMultiDisplay, selectedNames.length, size])
+  // Merge ref:forward to parent + capture for ResizeObserver
+  const mergedStackRef = React.useCallback((el: HTMLDivElement | null) => {
+    stackContainerRef.current = el
+    if (typeof ref === 'function') ref(el)
+    else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = el
+  }, [ref])
+
+  // ── mode='view' ────────────────────────────────────────────────────────
   // Default(showDisplayEndIcon=false):裸 PersonDisplay / MultiPersonDisplay — backward compat。
   // Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix ChevronDown,
-  // 與 edit (Select / Combobox wrapped) 同 DOM 結構消除 cell display↔edit 像素偏移。
-  if (resolvedMode === 'display') {
+  // 與 edit (Select / Combobox wrapped) 同 DOM 結構消除 cell view↔edit 像素偏移。
+  if (resolvedMode === 'view') {
     if (!showDisplayEndIcon) {
-      if (isEmpty) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
-      return isMulti
-        ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
-        : <PersonDisplay value={value as PersonValue} size={size} />
+      // 2026-07-17 Dim 9 修:裸顯示分支原直接 return PersonDisplay/MultiPersonDisplay/span,
+      // 遺失 ref / className / DOM-safe rest props(違 spec「forwardRef + 單一 root」root props 契約,
+      // 與 readonly/disabled 分支不對稱)。補穩定 forwarding root:`w-full min-w-0` 保留
+      // PersonDisplay 既有 w-full truncate 寬度約束鏈(單人 fill + 多人 stack 左靠不變),
+      // 對齊 switch.tsx:209 view 分支轉發先例。
+      // 2026-08-20 修 beta.100 迴歸(user 拍板):root 必須是 `flex` 彈性容器,不可為純 block ——
+      // block 會把 MultiPersonDisplay 的 inline-flex root 放進文字基線行盒,字型下伸空間(~6.5px)
+      // 把頭像串推向行盒頂 → DataTable cell 內視覺偏上 6.4px。flex 容器無行盒語意;
+      // 單人(flex root)/空值(span)子項幾何不變(2026-08-20 線上注入實證 7.5/7.5 置中)。
+      return (
+        <div ref={ref} className={cn('flex w-full min-w-0', className)} aria-label={ariaLabel} {...rest}>
+          {isEmpty
+            ? <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
+            : isMulti
+              ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
+              : <PersonDisplay value={value as PersonValue} size={size} />}
+        </div>
+      )
     }
     // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant: resolvedVariant, size }), className)}
-        data-field-mode="display"
+        // 2026-07-17 Dim 9 修:D-path view root 補 ref / aria-label / {...rest} 轉發(原只套 className,
+        // 遺失 root props;對齊 readonly/disabled 分支與 spec root props 契約)。
+        ref={ref}
+        className={cn(fieldWrapperStyles({ mode: 'view', variant: resolvedVariant, width, size }), className)}
+        data-field-mode="view"
+        aria-label={ariaLabel}
+        {...rest}
       >
         <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)}>
           {isEmpty
-            ? <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+            ? <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             : isMulti
               ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
               : <PersonDisplay value={value as PersonValue} size={size} />}
@@ -174,52 +293,66 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     return (
       <div
         ref={ref}
-        className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: resolvedVariant, size }), className)}
+        className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: resolvedVariant, width, size }), className)}
         data-field-mode={resolvedMode}
+        aria-disabled={resolvedMode === 'disabled' ? true : undefined}
         aria-label={ariaLabel}
         {...rest}
       >
         <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign, resolvedMode === 'disabled' && 'text-fg-disabled')}>
+          {/* 2026-07-14 deep-audit 修:disabled 傳入 → 抑制 Avatar ProfileCard hoverCard + avatar dim
+              (spec「disabled:灰化整個 field,不可互動」原被 hoverCard falsify);readonly 保留 hoverCard(純展示仍可查閱) */}
           {isEmpty
-            ? <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+            ? <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             : isMulti
-              ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
-              : <PersonDisplay value={value as PersonValue} size={size} />}
+              ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured disabled={resolvedMode === 'disabled'} />
+              : <PersonDisplay value={value as PersonValue} size={size} disabled={resolvedMode === 'disabled'} />}
         </span>
+        {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示 / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
+        {(resolvedVariant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
+          <ItemSuffix className="pointer-events-none">
+            <ChevronDown size={ICON_SIZE[size as 'sm' | 'md' | 'lg']} className={cn('shrink-0', resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted')} aria-hidden />
+          </ItemSuffix>
+        )}
       </div>
     )
   }
 
   // ── edit mode ─────────────────────────────────────────────────────────────
-  const selectedNames: string[] = !value
-    ? []
-    : Array.isArray(value)
-      ? value.map(v => resolvePerson(v).name)
-      : [resolvePerson(value).name]
+  // (selectedNames 派生已 hoist 至檔上方 hooks 區,見 D3 P0 修註解)
 
   // ── single mode → wraps Select ────────────────────────────────────────────
   if (!isMulti) {
-    const handleSingleChange = (name: string) => onChange?.([findPerson(people, name)])
+    // clearable X 清空時 Select emit onChange('') — 空字串必映射為空陣列,
+    // 不可進 findPerson(fallback 會回 '' 字串 = 假人員)。清除後回 placeholder 態(select.spec.md「Clearable」)。
+    const handleSingleChange = (name: string) => onChange?.(name ? [findPerson(people, name)] : [])
     return (
       <Select
         ref={ref as React.Ref<HTMLDivElement>}
+        // 2026-07-14 deep-audit fix:width 補 forward(原漏傳 → single edit path 忽略公開 width prop;
+        // multi pill / stack 皆有傳,對齊 M30 wrapper forward 全 primitive surface)
+        width={width}
         size={size}
         variant={resolvedVariant}
         options={people.map(personToSelectOption)}
         value={selectedNames[0] ?? null}
         onChange={handleSingleChange}
         searchable
+        clearable={clearable}
         placeholder={placeholder}
-        // 2026-05-12 Stream C Issue 4 fix(codex Q3):傳 `placeholder` 給 Select trigger empty。
-        // 不再傳 `emptyText`(search-empty semantic 跟 trigger-empty 分離,canonical SSOT)。
+        // 2026-05-12 Issue 4:placeholder = trigger empty。2026-07-04 Q4:emptyText 走 Select →
+        // SelectMenu 接線(search-empty 語意,與 trigger-empty 分離)。
+        emptyText={emptyText}
         defaultOpen={defaultOpen}
         onOpenChange={onOpenChange}
         className={className}
         aria-label={ariaLabel}
         selectedItemRenderer={(opt) => <PersonDisplay value={findPerson(people, opt.value)} size={size} />}
-        // **codex P2 forward**:Select extends `SelectHTMLAttributes<HTMLSelectElement>`,
-        // event handler element 型別跟 PeoplePicker `HTMLAttributes<HTMLDivElement>` 不一致
-        // (`onCopy` / `onChange` 等)。Runtime spread 等效 — DOM 收到 attrs 不挑剔。
+        // **codex P2 forward**:Select 原生屬性走 allowlist(`Pick<SelectHTMLAttributes>`,
+        // 2026-07-14 API 策展 D,見 select.tsx SelectProps docblock),event handler element
+        // 型別跟 PeoplePicker `HTMLAttributes<HTMLDivElement>` 不一致(`onCopy` / `onChange` 等)。
+        // Runtime spread 等效 — DOM 收到 attrs 不挑剔(非 allowlist attrs 落 CustomSelect rest,
+        // 續 spread 到 trigger div,runtime 行為不變)。
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         // any-allow: rest 含 `onChange: FormEventHandler` 跟 Select onChange signature 衝突 — DOM runtime spread 安全(per codex P2 forward)
         {...(rest as any)}
@@ -228,12 +361,14 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   }
 
   // ── multi 'pill' → wraps Combobox(對齊 GitHub Reviewers / Combobox idiom)────
-  if (multiDisplay === 'pill') {
+  // 觸控多選亦走此分支(effectiveMultiDisplay,見上方 isTouch 註解)。
+  if (effectiveMultiDisplay === 'pill') {
     const handleMultiChange = (next: string[]) => {
       onChange?.(next.map(name => findPerson(people, name)))
     }
     return (
       <Combobox
+        width={width}
         ref={ref as React.Ref<HTMLDivElement>}
         size={size}
         variant={resolvedVariant}
@@ -241,13 +376,17 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         value={selectedNames}
         onChange={handleMultiChange}
         searchable
+        // 2026-07-14 deep-audit fix:searchIn 補 forward(原漏傳 → pill 模式永遠 Combobox default 'menu',
+        // documented multi opt-in `searchIn='trigger'` silently 無效;stack branch 已傳,對齊 M30 forward 全 surface)
+        searchIn={searchIn}
+        clearable={clearable}
         searchPlaceholder={searchPlaceholder}
+        searchAriaLabel={searchAriaLabel}
         // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty hint('請選擇人員')
-        // — semantic clean separation;emptyText 不再 silent 轉 trigger placeholder。
-        // emptyPlaceholder backward-compat forward(Combobox line 509 `placeholder ?? emptyPlaceholder` fallback)
-        // 1 cycle:future 移除 emptyPlaceholder forward,emptyText 改傳 SelectMenu noResultsText。
+        // — semantic clean separation。2026-07-04 Q4 拍板完成 1-cycle 承諾:emptyPlaceholder forward
+        // 移除,emptyText 改傳 Combobox → SelectMenu emptyText(search-empty 真住所,菜單空狀態)。
         placeholder={placeholder}
-        emptyPlaceholder={emptyText}
+        emptyText={emptyText}
         wrap={pillWrap}
         defaultOpen={defaultOpen}
         onOpenChange={onOpenChange}
@@ -271,9 +410,9 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
               // Combobox tagRenderer slot,SSOT = Tag primitive 視覺(per codex Round 3 verdict)。
               // 人名 99% < 25 chars 不觸發 cap;極端長名(複數姓 + middle name)觸發 ellipsis 是合理 UX。
               avatar={pillShowAvatar
-                ? <Avatar src={p.avatarUrl} alt={p.name} size={16} hoverCard={buildPersonNameCard(p)} />
+                ? <Avatar src={p.avatarUrl} alt={p.name} size={16} hoverCard={buildPersonProfileCard(p)} />
                 : undefined}
-              onDismiss={onRemove}
+              onRemove={onRemove}
             >
               {p.name}
             </Tag>
@@ -288,53 +427,17 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   // **2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus)**:visible count 走 shared
   // `avatar-stack-overflow` primitive deterministic formula(取代 Combobox DOM offsetWidth-based
   // useOverflowCount + 60px fallback 不 deterministic),pass override 給 Combobox bypass internal
-  // measurement。`MultiPersonDisplay`(display path)同 primitive,display + edit 結果一致。
+  // measurement。`MultiPersonDisplay`(view path)同 primitive,view + edit 結果一致。
   // 對齊 user verbatim SSOT「同 cell width 同 overflow 判斷」+ codex Q3 consensus shared primitive。
   const handleMultiChange = (next: string[]) => {
     onChange?.(next.map(name => findPerson(people, name)))
   }
-  // SSOT visible count compute via formula primitive + ResizeObserver
-  const stackContainerRef = React.useRef<HTMLDivElement | null>(null)
-  const [stackVisibleCount, setStackVisibleCount] = React.useState<number | undefined>(undefined)
-  React.useLayoutEffect(() => {
-    // 注:此 effect 只在 multi stack mode 跑(early return if not stack);length<=1 不需 override
-    if (!isMulti || selectedNames.length <= 1) {
-      setStackVisibleCount(undefined); return
-    }
-    const root = stackContainerRef.current
-    if (!root) return
-    // 2026-05-15 ROOT CAUSE FIX(user 抓「之前說的問題都還是存在」):
-    // stackContainerRef 透過 mergedStackRef 接 Combobox forwarded ref → root **就是** [role=combobox]
-    // div 自己。原 `root.querySelector('[role=combobox]')` 不找 self 永遠 null → trigger=null →
-    // tagArea=null → available=0 → setStackVisibleCount(0) → 整 stack 全 overflow → fallback 到
-    // Combobox DOM-based useOverflowCount(非 deterministic 那個算法)。修:用 root 自己當 trigger,
-    // 從 root 內找 tagArea(flex-1 min-w-0 div)。
-    const calc = () => {
-      const trigger = root.matches('[role="combobox"]') ? root : root.querySelector<HTMLElement>('[role="combobox"]')
-      const tagArea = trigger?.querySelector<HTMLElement>('div[class*="flex-1"][class*="min-w-0"]')
-      const available = tagArea?.clientWidth ?? trigger?.clientWidth ?? 0
-      const visible = getAvatarStackVisibleCount({
-        availablePx: available,
-        total: selectedNames.length,
-        avatarPx: AVATAR_STACK_AVATAR_PX[size],
-        overflowChipPx: AVATAR_STACK_OVERFLOW_CHIP_PX[size],
-      })
-      setStackVisibleCount(visible)
-    }
-    calc()
-    const ro = new ResizeObserver(calc)
-    ro.observe(root)
-    return () => ro.disconnect()
-  }, [isMulti, multiDisplay, selectedNames.length, size])
-  // Merge ref:forward to parent + capture for ResizeObserver
-  const mergedStackRef = React.useCallback((el: HTMLDivElement | null) => {
-    stackContainerRef.current = el
-    if (typeof ref === 'function') ref(el)
-    else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = el
-  }, [ref])
+  // ── edit mode ─────────────────────────────────────────────────────────────
+  // (selectedNames 派生已 hoist 至檔上方 hooks 區,見 D3 P0 修註解)
 
   return (
     <Combobox
+      width={width}
       ref={mergedStackRef}
       size={size}
       variant={resolvedVariant}
@@ -343,10 +446,12 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       onChange={handleMultiChange}
       searchable
       searchIn={searchIn}
+      clearable={clearable}
       searchPlaceholder={searchPlaceholder}
+      searchAriaLabel={searchAriaLabel}
       // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty('請選擇人員');emptyText = search-empty(僅 backward-compat forward 1 cycle)
       placeholder={placeholder}
-      emptyPlaceholder={emptyText}
+      emptyText={emptyText}
       wrap={false}
       defaultOpen={defaultOpen}
       onOpenChange={onOpenChange}
@@ -354,12 +459,12 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       // 撤掉 `tagAreaPaddingLeftPx={8}` magic — Combobox `tagPadding[size]` 是 density-dependent
       // calc 公式(`(field-height - icon-size) / 2`),只在 md size + default density 才 = 4px;
       // 其他 size/density 漂 6px / 8px → 4+8=12 spec 公式不成立。
-      // (a) fix:form context + 有 tag → 改 inject `!px-3`(固定 12px)直接 override `tagPadding[size]`,
+      // (a) fix:form context + 有 tag → 改 inject `!px-[var(--field-px)]`(固定 12px)直接 override `tagPadding[size]`,
       // 達成 GitHub PeoplePicker fixed 12px inset(對齊 cell context 同 13px from cell.left 含 1px border)。
-      // - form + 有 tag → `!px-3`(12px 固定 inset)+ tagAreaPaddingLeftPx undefined → field.padL=12 ✓
+      // - form + 有 tag → `!px-[var(--field-px)]`(12px 固定 inset)+ tagAreaPaddingLeftPx undefined → field.padL=12 ✓
       // - table-cell + 有 tag → naked variant `!px-[var(--table-cell-px)]` 已是 12px,不 inject ✓
       // - isEmpty → 不 inject,走 Combobox 預設文字 inset(`tagPadding[size]` 公式自然 vertical center)
-      className={cn(className, !isEmpty && surface === 'form' && '!px-3')}
+      className={cn(className, !isEmpty && surface === 'form' && '!px-[var(--field-px)]')}
       aria-label={ariaLabel}
       // 2026-05-15 Bug 1 fix(Claude+Codex Step 5 比稿 consensus,user verbatim「就 A」):per-length 動態
       // wrapper class — length=1 降階單人視覺需要 width constraint chain(`flex-1 min-w-0 overflow-hidden`),
@@ -383,10 +488,10 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       // 既有 OverflowIndicator default 'circle' SSOT。
       overflowShape="circle"
       // 2026-05-15 Bug 3 fix:formula-based visible count override(避免 Combobox DOM measurement +
-      // 60px fallback 不 deterministic)。SSOT in `./avatar-stack-overflow.ts`,display + edit 共用。
+      // 60px fallback 不 deterministic)。SSOT in `./avatar-stack-overflow.ts`,view + edit 共用。
       visibleCountOverride={stackVisibleCount}
       // 2026-05-14 I4 fix(per codex+Layer A 共識):hidden items 在 `+N` overflow popover 顯
-      // Tag with avatar(對齊 display MultiPersonDisplay popover SSOT,user 抓 display vs edit
+      // Tag with avatar(對齊 view path MultiPersonDisplay popover SSOT,user 抓 display vs edit
       // overflow 視覺不一致)。
       renderHiddenTag={(item) => {
         const p = resolvePerson(findPerson(people, item.value))
@@ -400,10 +505,10 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
                 src={p.avatarUrl}
                 alt={p.name}
                 size={16}
-                hoverCard={buildPersonNameCard(p)}
+                hoverCard={buildPersonProfileCard(p)}
               />
             }
-            onDismiss={() => {
+            onRemove={() => {
               onChange?.(selectedNames.filter(n => n !== item.value).map(n => findPerson(people, n)))
             }}
           >
@@ -420,9 +525,9 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         // selectedNames.length === 1 → PersonDisplay(avatar + name)代替 PersonAvatarTag(avatar only)。
         // SSOT 對齊 PeoplePicker single mode line 201 selectedItemRenderer。多選 1 人時視覺等同單選,
         // 只在 length > 1 才走 stack(各 avatar 純 chip)。多選 + inline 搜尋場景拿掉 name 改 cursor
-        // 是 future 工作(需 PeoplePicker 加 searchIn='trigger' opt-in,當前 wrapped Combobox 走 menu search)。
+        // 走 `searchIn='trigger'` opt-in(2026-05-12 規則 3 ship,已轉傳 Combobox;default 'menu' 走 panel-top search)。
         if (selectedNames.length === 1) {
-          return <PersonDisplay key={item.value} value={p} size={size} />
+          return <PersonDisplay key={item.value} value={p} size={size} onRemove={onRemove} />
         }
         return (
           <PersonAvatarTag
@@ -444,7 +549,8 @@ export const peoplePickerMeta = {
   family: 4,
   variants: {},
   sizes: {},
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — trigger 走 Field chrome、menu 走 MenuItem,皆無自有按壓視覺(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: ['text-fg-disabled', 'text-fg-muted'],
@@ -453,3 +559,14 @@ export const peoplePickerMeta = {
 } as const
 
 export { PeoplePicker }
+// 2026-07-10 C14 export 缺口修(R2 同類:定義存在但無 export 面,consumer 想守 PersonValue 鏈
+// import 不到 → 被逼手刻)。person-display 表面隨 PeoplePicker subpath + root barrel 一併公開。
+export {
+  PersonDisplay,
+  MultiPersonDisplay,
+  PersonAvatarTag,
+  buildPersonProfileCard,
+  resolvePerson,
+  type PersonValue,
+  type PersonData,
+} from './person-display'