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

package/dist/components/PeoplePicker/avatar-stack-overflow.d.ts

@@ -10,7 +10,7 @@
  *   4. **架構違反**:`MultiPersonDisplay` display path 用 canvas-based 算 / Combobox edit path 用 DOM offsetWidth
  *      → 同 cell width 兩 path 不同結果 → user verbatim「同寬 cell overflow 時間不一樣」SSOT 根本被違反
  *
- * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,display + edit 兩 path **共用**。
+ * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,view + edit 兩 path **共用**。
  *
  * **Deterministic formula**:
  * ```

package/dist/components/PeoplePicker/avatar-stack-overflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"avatar-stack-overflow.js","sources":["../../../src/components/PeoplePicker/avatar-stack-overflow.ts"],"sourcesContent":["/**\n * avatar-stack-overflow — Deterministic SSOT primitive for avatar stack overflow math\n *\n * **2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus,user verbatim「就 A」)**:\n *\n * Real root cause of Bug 3「same cell width but different overflow timing per total count」:\n *   1. `useOverflowCount` 在 Combobox 用 DOM `offsetWidth` 量測 + `overflowW = 60` fallback(實際 24px)\n *   2. `overflowEl` 不被 ResizeObserver observe,first calc 用 fallback 後不會 recalc\n *   3. `offsetWidth` 不減 `-ml-0.5` overlap → measurement 偏保守\n *   4. **架構違反**:`MultiPersonDisplay` display path 用 canvas-based 算 / Combobox edit path 用 DOM offsetWidth\n *      → 同 cell width 兩 path 不同結果 → user verbatim「同寬 cell overflow 時間不一樣」SSOT 根本被違反\n *\n * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,display + edit 兩 path **共用**。\n *\n * **Deterministic formula**:\n * ```\n * firstAvatar + (visible - 1) * (avatar - overlap) + overflowChip <= available\n * ```\n * - `firstAvatar`:第一個 avatar 全寬 = `avatarPx`\n * - subsequent items:`avatar - overlap`(stack `-ml-0.5` 視覺等同 measurement subtract)\n * - `overflowChip`:若有 hidden,留 +N chip 空間;最後一個 visible item 不需留(`remaining === 0`)\n *\n * **Why centralize**:M14 mechanical guard against future drift。`MultiPersonDisplay` +\n * PeoplePicker stack edit + future avatar consumers 都 import 此 helper,不可 copy formula。\n * 對齊 codex「one avatar-stack primitive owns avatarPx, overlapPx, overflowChipPx」directive。\n *\n * **Benchmark cite**(per codex external baseline):MDN flex truncation / MUI Autocomplete\n * limitTags / Ant Select maxTagCount=\"responsive\"(explicit overflow contract,非 incidental clip)/\n * Primer Truncate(parent-constrained max width)。\n */\n\n/**\n * Pure deterministic visible-count formula for avatar stack with overlap + overflow chip.\n *\n * @param availablePx — Container width available for the entire stack(含 +N chip 預留空間)\n * @param total — Total avatars in selection\n * @param avatarPx — Per-avatar pixel width(包含 ring border)\n * @param overlapPx — Negative margin overlap between siblings(default 2px = `-ml-0.5`)\n * @param overflowChipPx — Width reserved for +N indicator when overflow needed(default 24px = circle h-6 min-w-6)\n * @returns visible count(0 ≤ visible ≤ total)。若全部 fit 則 visible = total(無 +N chip);否則 visible 為 max fit。\n */\nexport function getAvatarStackVisibleCount({\n  availablePx,\n  total,\n  avatarPx,\n  overlapPx = 2,\n  // NOTE: overflowChipPx is kept for backward-compat API but the slot-based\n  // formula below treats chip = avatar physical size(both circles same shape\n  // + same -ml-0.5 overlap when stacked)。Consumer 必 ensure 視覺 chip wrapper\n  // 也套同 `-ml-0.5` overlap class(Combobox `overflowWrapperClassName`)。\n  overflowChipPx: _overflowChipPx = 24,\n}: {\n  availablePx: number\n  total: number\n  avatarPx: number\n  overlapPx?: number\n  overflowChipPx?: number\n}): number {\n  if (total <= 0 || availablePx <= 0) return 0\n  // 2026-05-16 真 root cause fix(Claude+Codex Round 2 + user 物理模型 directive):\n  //\n  // 原 formula 雙態 bug:\n  //   1. full-fit 路徑算 fullStack(無 chip space)\n  //   2. overflow 路徑重算 remainder(chip 當 24px 額外空間)\n  //   兩 path 切換時 visible 跳 2(saw)— 因 chip 不被當「stack 內 1 個圓」,\n  //   被當「stack 外額外 chunk」。User 抓 length=4→4、length=5→2+3 = 物理錯。\n  //\n  // **User 物理模型(對齊 MUI AvatarGroup / Primer AvatarStack / Material idiom)**:\n  //   avatar 跟 +N 都是同尺寸圓形 + 同 -ml-0.5 overlap → 同 step。空間 W 容\n  //   `slots = 1 + floor((W - avatar) / step)` 個圓。total ≤ slots → 全 avatar 無 chip;\n  //   total > slots → (slots-1) avatar + 1 chip(共 slots 個圓)。\n  //\n  // 物理 saw 性質:length 從 slots 跳到 slots+1 時 visible 從 slots 跳到 slots-1\n  // = delta 1 avatar(同 slots 個圓,只 swap 最後一個 avatar 變 chip)。對齊 user 直覺。\n  const step = avatarPx - overlapPx\n  if (step <= 0) return Math.min(total, 1)\n  const slots = 1 + Math.floor((availablePx - avatarPx) / step)\n  if (slots <= 0) return 0\n  if (total <= slots) return total  // 全 fit:每 slot 一個 avatar\n  return Math.max(0, slots - 1)  // 超過 slots:slots-1 個 avatar + 1 個 chip(last slot)\n}\n\n/**\n * Map size token to avatar pixel(對齊 person-display.tsx:80 AVATAR_PX SSOT)。\n */\nexport const AVATAR_STACK_AVATAR_PX: Record<'sm' | 'md' | 'lg', number> = {\n  sm: 20,\n  md: 24,\n  lg: 24,\n}\n\n/**\n * Default overflow chip width per size(對齊 overflow-indicator.tsx:17 triggerSize SSOT)。\n * shape='circle' → h-{5|6} min-w-{5|6} ≈ 20-24px\n */\nexport const AVATAR_STACK_OVERFLOW_CHIP_PX: Record<'sm' | 'md' | 'lg', number> = {\n  sm: 20,\n  md: 24,\n  lg: 24,\n}\n"],"names":[],"mappings":"AAyCO,SAAS,2BAA2B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA,EAKZ,gBAAgB,kBAAkB;AACpC,GAMW;AACT,MAAI,SAAS,KAAK,eAAe,EAAG,QAAO;AAgB3C,QAAM,OAAO,WAAW;AACxB,MAAI,QAAQ,EAAG,QAAO,KAAK,IAAI,OAAO,CAAC;AACvC,QAAM,QAAQ,IAAI,KAAK,OAAO,cAAc,YAAY,IAAI;AAC5D,MAAI,SAAS,EAAG,QAAO;AACvB,MAAI,SAAS,MAAO,QAAO;AAC3B,SAAO,KAAK,IAAI,GAAG,QAAQ,CAAC;AAC9B;AAKO,MAAM,yBAA6D;AAAA,EACxE,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAMO,MAAM,gCAAoE;AAAA,EAC/E,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;"}
+{"version":3,"file":"avatar-stack-overflow.js","sources":["../../../src/components/PeoplePicker/avatar-stack-overflow.ts"],"sourcesContent":["/**\n * avatar-stack-overflow — Deterministic SSOT primitive for avatar stack overflow math\n *\n * **2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus,user verbatim「就 A」)**:\n *\n * Real root cause of Bug 3「same cell width but different overflow timing per total count」:\n *   1. `useOverflowCount` 在 Combobox 用 DOM `offsetWidth` 量測 + `overflowW = 60` fallback(實際 24px)\n *   2. `overflowEl` 不被 ResizeObserver observe,first calc 用 fallback 後不會 recalc\n *   3. `offsetWidth` 不減 `-ml-0.5` overlap → measurement 偏保守\n *   4. **架構違反**:`MultiPersonDisplay` display path 用 canvas-based 算 / Combobox edit path 用 DOM offsetWidth\n *      → 同 cell width 兩 path 不同結果 → user verbatim「同寬 cell overflow 時間不一樣」SSOT 根本被違反\n *\n * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,view + edit 兩 path **共用**。\n *\n * **Deterministic formula**:\n * ```\n * firstAvatar + (visible - 1) * (avatar - overlap) + overflowChip <= available\n * ```\n * - `firstAvatar`:第一個 avatar 全寬 = `avatarPx`\n * - subsequent items:`avatar - overlap`(stack `-ml-0.5` 視覺等同 measurement subtract)\n * - `overflowChip`:若有 hidden,留 +N chip 空間;最後一個 visible item 不需留(`remaining === 0`)\n *\n * **Why centralize**:M14 mechanical guard against future drift。`MultiPersonDisplay` +\n * PeoplePicker stack edit + future avatar consumers 都 import 此 helper,不可 copy formula。\n * 對齊 codex「one avatar-stack primitive owns avatarPx, overlapPx, overflowChipPx」directive。\n *\n * **Benchmark cite**(per codex external baseline):MDN flex truncation / MUI Autocomplete\n * limitTags / Ant Select maxTagCount=\"responsive\"(explicit overflow contract,非 incidental clip)/\n * Primer Truncate(parent-constrained max width)。\n */\n\n/**\n * Pure deterministic visible-count formula for avatar stack with overlap + overflow chip.\n *\n * @param availablePx — Container width available for the entire stack(含 +N chip 預留空間)\n * @param total — Total avatars in selection\n * @param avatarPx — Per-avatar pixel width(包含 ring border)\n * @param overlapPx — Negative margin overlap between siblings(default 2px = `-ml-0.5`)\n * @param overflowChipPx — Width reserved for +N indicator when overflow needed(default 24px = circle h-6 min-w-6)\n * @returns visible count(0 ≤ visible ≤ total)。若全部 fit 則 visible = total(無 +N chip);否則 visible 為 max fit。\n */\nexport function getAvatarStackVisibleCount({\n  availablePx,\n  total,\n  avatarPx,\n  overlapPx = 2,\n  // NOTE: overflowChipPx is kept for backward-compat API but the slot-based\n  // formula below treats chip = avatar physical size(both circles same shape\n  // + same -ml-0.5 overlap when stacked)。Consumer 必 ensure 視覺 chip wrapper\n  // 也套同 `-ml-0.5` overlap class(Combobox `overflowWrapperClassName`)。\n  overflowChipPx: _overflowChipPx = 24,\n}: {\n  availablePx: number\n  total: number\n  avatarPx: number\n  overlapPx?: number\n  overflowChipPx?: number\n}): number {\n  if (total <= 0 || availablePx <= 0) return 0\n  // 2026-05-16 真 root cause fix(Claude+Codex Round 2 + user 物理模型 directive):\n  //\n  // 原 formula 雙態 bug:\n  //   1. full-fit 路徑算 fullStack(無 chip space)\n  //   2. overflow 路徑重算 remainder(chip 當 24px 額外空間)\n  //   兩 path 切換時 visible 跳 2(saw)— 因 chip 不被當「stack 內 1 個圓」,\n  //   被當「stack 外額外 chunk」。User 抓 length=4→4、length=5→2+3 = 物理錯。\n  //\n  // **User 物理模型(對齊 MUI AvatarGroup / Primer AvatarStack / Material idiom)**:\n  //   avatar 跟 +N 都是同尺寸圓形 + 同 -ml-0.5 overlap → 同 step。空間 W 容\n  //   `slots = 1 + floor((W - avatar) / step)` 個圓。total ≤ slots → 全 avatar 無 chip;\n  //   total > slots → (slots-1) avatar + 1 chip(共 slots 個圓)。\n  //\n  // 物理 saw 性質:length 從 slots 跳到 slots+1 時 visible 從 slots 跳到 slots-1\n  // = delta 1 avatar(同 slots 個圓,只 swap 最後一個 avatar 變 chip)。對齊 user 直覺。\n  const step = avatarPx - overlapPx\n  if (step <= 0) return Math.min(total, 1)\n  const slots = 1 + Math.floor((availablePx - avatarPx) / step)\n  if (slots <= 0) return 0\n  if (total <= slots) return total  // 全 fit:每 slot 一個 avatar\n  return Math.max(0, slots - 1)  // 超過 slots:slots-1 個 avatar + 1 個 chip(last slot)\n}\n\n/**\n * Map size token to avatar pixel(對齊 person-display.tsx:80 AVATAR_PX SSOT)。\n */\nexport const AVATAR_STACK_AVATAR_PX: Record<'sm' | 'md' | 'lg', number> = {\n  sm: 20,\n  md: 24,\n  lg: 24,\n}\n\n/**\n * Default overflow chip width per size(對齊 overflow-indicator.tsx:17 triggerSize SSOT)。\n * shape='circle' → h-{5|6} min-w-{5|6} ≈ 20-24px\n */\nexport const AVATAR_STACK_OVERFLOW_CHIP_PX: Record<'sm' | 'md' | 'lg', number> = {\n  sm: 20,\n  md: 24,\n  lg: 24,\n}\n"],"names":[],"mappings":"AAyCO,SAAS,2BAA2B;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA,EAKZ,gBAAgB,kBAAkB;AACpC,GAMW;AACT,MAAI,SAAS,KAAK,eAAe,EAAG,QAAO;AAgB3C,QAAM,OAAO,WAAW;AACxB,MAAI,QAAQ,EAAG,QAAO,KAAK,IAAI,OAAO,CAAC;AACvC,QAAM,QAAQ,IAAI,KAAK,OAAO,cAAc,YAAY,IAAI;AAC5D,MAAI,SAAS,EAAG,QAAO;AACvB,MAAI,SAAS,MAAO,QAAO;AAC3B,SAAO,KAAK,IAAI,GAAG,QAAQ,CAAC;AAC9B;AAKO,MAAM,yBAA6D;AAAA,EACxE,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAMO,MAAM,gCAAoE;AAAA,EAC/E,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;"}

package/dist/components/PeoplePicker/index.d.ts

@@ -0,0 +1,2 @@
+export * from './people-picker';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/PeoplePicker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/index.ts"],"names":[],"mappings":"AAIA,cAAc,iBAAiB,CAAA"}

package/dist/components/PeoplePicker/index.js

@@ -0,0 +1,15 @@
+import { PeoplePicker, peoplePickerMeta } from "./people-picker.js";
+import { MultiPersonDisplay, PersonAvatarTag, PersonDisplay, buildPersonProfileCard, resolvePerson } from "./person-display.js";
+import { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass } from "./people-picker-helpers.js";
+export {
+  MultiPersonDisplay,
+  PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS,
+  PeoplePicker,
+  PersonAvatarTag,
+  PersonDisplay,
+  buildPersonProfileCard,
+  getPeoplePickerTagWrapperClass,
+  peoplePickerMeta,
+  resolvePerson
+};
+//# sourceMappingURL=index.js.map

package/dist/components/PeoplePicker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/components/PeoplePicker/people-picker-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"people-picker-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/people-picker-helpers.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAsC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AA8BvF,eAAO,MAAM,mCAAmC,wFAAqE,CAAA;AAGrH,wBAAgB,8BAA8B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAK5E;AAYD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAQtE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAE3E"}
+{"version":3,"file":"people-picker-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/people-picker-helpers.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAyC,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AA8B1F,eAAO,MAAM,mCAAmC,wFAAqE,CAAA;AAGrH,wBAAgB,8BAA8B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAK5E;AAYD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAQtE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAE3E"}

package/dist/components/PeoplePicker/people-picker-helpers.js

@@ -1,5 +1,5 @@
 import { nakedCellRowModeAlign } from "../Field/field-wrapper.js";
-import { resolvePerson, buildPersonNameCard } from "./person-display.js";
+import { resolvePerson, buildPersonProfileCard } from "./person-display.js";
 const PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS = `flex-1 min-w-0 inline-flex items-center ${nakedCellRowModeAlign}`;
 function getPeoplePickerTagWrapperClass(selectedCount) {
   return selectedCount === 1 ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS : "-ml-0.5 first:ml-0 relative inline-flex group/avatar";
@@ -9,7 +9,7 @@ function personToSelectOption(person) {
   return {
     value: p.name,
     label: p.name,
-    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonNameCard(p) },
+    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonProfileCard(p) },
     description: p.description
   };
 }

package/dist/components/PeoplePicker/people-picker-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"people-picker-helpers.js","sources":["../../../src/components/PeoplePicker/people-picker-helpers.ts"],"sourcesContent":["// PeoplePicker — pure helpers extracted from `people-picker.tsx`(2026-05-18 file-size refactor)\n//\n// 抽出原因:`people-picker.tsx` 達 P1 file-size budget (500 lines)。本檔收 **不消費 component\n// closure** 的純 helper（constant / pure function），讓主檔 ≤ 480。視覺 / behavior /\n// user-facing API 完全未動 — 只是 module-level 邊界搬家。\n//\n// SSOT-bearing render logic(tagRenderer / selectedItemRenderer / 多人 stack 視覺等）仍留在\n// `people-picker.tsx`,因為消費 Combobox / Select / state 等 closure。\n//\n// Hook `check_peoplepicker_ssot_drift.sh` 不檢查本檔 literal — 因規則 cite spec.md row 的義務\n// 在主檔 SSOT-bearing API 邊界處,本檔屬機械搬移。\nimport { nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'\nimport type { SelectOption } from '@/design-system/components/Select/select'\nimport { buildPersonNameCard, resolvePerson, type PersonValue } from './person-display'\n\n// ── Tag wrapper className SSOT ──────────────────────────────────────────────\n//\n// **2026-05-15 Bug 1 fix(Claude+Codex Step 5 比稿 consensus)**:length=1 走 PersonDisplay\n// (avatar+人名+ellipsis,per spec.md §C row 1)需要 width constraint chain;length>=2 走\n// PersonAvatarTag stack overlap(per spec.md §D row 1)需要 negative margin overlap visual。\n// 一個 static wrapper class 涵蓋兩 contract 不可能 — Combobox `OverflowTagList` 把 result 包\n// `shrink-0`,如果 wrapper 還疊 `inline-flex` 就 intrinsic content-width → PersonDisplay\n// truncate 無效(Bug 1 user 抓「越界蓋 indicator」)。\n//\n// **Why centralize**:M14 mechanical guard against future drift。任何人未來改 stack mode 邏輯,\n// 必經此 helper(hook `check_peoplepicker_ssot_drift.sh` 攔接 wrapper class literal in tsx)。\n//\n// **2026-05-15 SSOT alignment**(user verbatim「單選 people picker 沒壞,難道沒有 SSOT?」):\n// 單選 picker wrapper(`select.tsx:229`)= `flex-1 min-w-0 inline-flex items-center +\n// nakedCellRowModeAlign` — proven working,canonical SSOT。本 helper 對齊 single SSOT,\n// **不**自定一套(spec.md §C row 1 +「length=1 視覺 = 跟單人 closed 一致」+ §E「PersonDisplay\n// 共享 renderer」)。\n//\n// `inline-flex items-center` 提供:wrapper 對 PersonDisplay flex container 適當 vertical centering,\n//   不靠外層 tagArea items-center cascade(避免 wrapper 高度 collapse 不可控)。\n// `nakedCellRowModeAlign` 提供:autoRow cell 內 first-line align(對齊既有 row geometry SSOT)。\n//\n// **禁加 overflow-hidden**:inner `<span truncate>` 自帶 overflow-hidden + text-overflow:ellipsis,\n//   wrapper overflow-hidden 反而 clip 24px avatar(ItemPrefix h-[1lh]~20px slot 容不下)+ break inner\n//   ellipsis trigger(圖一 + 圖二 root cause)。\n\n// code-quality-allow: dead-export — SSOT primitive 公開供 future cross-file 消費 + hook\n// `check_peoplepicker_ssot_drift.sh` enforce wrapper class literal pattern\nexport const PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS = `flex-1 min-w-0 inline-flex items-center ${nakedCellRowModeAlign}`\n\n// code-quality-allow: dead-export — paired helper for SSOT primitive(同上 hook + future use rationale)\nexport function getPeoplePickerTagWrapperClass(selectedCount: number): string {\n  return selectedCount === 1\n    ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS  // SSOT aligned to single picker wrapper(select.tsx:229)\n    // length>=2 stack 視覺(spec.md §D row 1):圓形 avatar overlap + group/avatar selector for dismiss overlay\n    : '-ml-0.5 first:ml-0 relative inline-flex group/avatar'\n}\n\n// ── Person → SelectOption mapping ───────────────────────────────────────────\n//\n// Issue 4(2026-05-10):forward person 的 description + avatar 給 Select(SelectOption schema\n// 已 unified with SelectMenuOption per Issue 4)。先前 PeoplePicker single mode 透過 Select 開\n// menu 時 dropdown row 只顯純文字 name(資訊弱)— 現透過 wrapper schema unify 直接帶 avatar /\n// description 給 SelectMenu primitive 渲。\n//\n// 2026-05-18 fix(per user directive「所有 avatar hover 都要 NameCard」+ avatar.spec.md\n// DS-wide canonical):dropdown menu items Avatar 必帶 hoverCard,跟 PersonDisplay / Tag\n// avatar 對齊。漏掉 = user 抓「PeoplePicker 選單內 avatar 沒有 namecard」。\nexport function personToSelectOption(person: PersonValue): SelectOption {\n  const p = resolvePerson(person)\n  return {\n    value: p.name,\n    label: p.name,\n    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonNameCard(p) },\n    description: p.description,\n  }\n}\n\nexport function findPerson(people: PersonValue[], name: string): PersonValue {\n  return people.find(p => resolvePerson(p).name === name) ?? name\n}\n"],"names":[],"mappings":";;AA2CO,MAAM,sCAAsC,2CAA2C,qBAAqB;AAG5G,SAAS,+BAA+B,eAA+B;AAC5E,SAAO,kBAAkB,IACrB,sCAEA;AACN;AAYO,SAAS,qBAAqB,QAAmC;AACtE,QAAM,IAAI,cAAc,MAAM;AAC9B,SAAO;AAAA,IACL,OAAO,EAAE;AAAA,IACT,OAAO,EAAE;AAAA,IACT,QAAQ,EAAE,KAAK,EAAE,WAAW,KAAK,EAAE,MAAM,WAAW,oBAAoB,CAAC,EAAA;AAAA,IACzE,aAAa,EAAE;AAAA,EAAA;AAEnB;AAEO,SAAS,WAAW,QAAuB,MAA2B;AAC3E,SAAO,OAAO,KAAK,CAAA,MAAK,cAAc,CAAC,EAAE,SAAS,IAAI,KAAK;AAC7D;"}
+{"version":3,"file":"people-picker-helpers.js","sources":["../../../src/components/PeoplePicker/people-picker-helpers.ts"],"sourcesContent":["// PeoplePicker — pure helpers extracted from `people-picker.tsx`(2026-05-18 file-size refactor)\n//\n// 抽出原因:`people-picker.tsx` 達 P1 file-size budget (500 lines)。本檔收 **不消費 component\n// closure** 的純 helper（constant / pure function），讓主檔 ≤ 480。視覺 / behavior /\n// user-facing API 完全未動 — 只是 module-level 邊界搬家。\n//\n// SSOT-bearing render logic(tagRenderer / selectedItemRenderer / 多人 stack 視覺等）仍留在\n// `people-picker.tsx`,因為消費 Combobox / Select / state 等 closure。\n//\n// Hook `check_peoplepicker_ssot_drift.sh` 不檢查本檔 literal — 因規則 cite spec.md row 的義務\n// 在主檔 SSOT-bearing API 邊界處,本檔屬機械搬移。\nimport { nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'\nimport type { SelectOption } from '@/design-system/components/Select/select'\nimport { buildPersonProfileCard, resolvePerson, type PersonValue } from './person-display'\n\n// ── Tag wrapper className SSOT ──────────────────────────────────────────────\n//\n// **2026-05-15 Bug 1 fix(Claude+Codex Step 5 比稿 consensus)**:length=1 走 PersonDisplay\n// (avatar+人名+ellipsis,per spec.md §C row 1)需要 width constraint chain;length>=2 走\n// PersonAvatarTag stack overlap(per spec.md §D row 1)需要 negative margin overlap visual。\n// 一個 static wrapper class 涵蓋兩 contract 不可能 — Combobox `OverflowTagList` 把 result 包\n// `shrink-0`,如果 wrapper 還疊 `inline-flex` 就 intrinsic content-width → PersonDisplay\n// truncate 無效(Bug 1 user 抓「越界蓋 indicator」)。\n//\n// **Why centralize**:M14 mechanical guard against future drift。任何人未來改 stack mode 邏輯,\n// 必經此 helper(hook `check_peoplepicker_ssot_drift.sh` 攔接 wrapper class literal in tsx)。\n//\n// **2026-05-15 SSOT alignment**(user verbatim「單選 people picker 沒壞,難道沒有 SSOT?」):\n// 單選 picker wrapper(`select.tsx:244` selectedItemRenderer wrapper)= `flex-1 min-w-0 inline-flex items-center +\n// nakedCellRowModeAlign` — proven working,canonical SSOT。本 helper 對齊 single SSOT,\n// **不**自定一套(spec.md §C row 1 +「length=1 視覺 = 跟單人 closed 一致」+ §E「PersonDisplay\n// 共享 renderer」)。\n//\n// `inline-flex items-center` 提供:wrapper 對 PersonDisplay flex container 適當 vertical centering,\n//   不靠外層 tagArea items-center cascade(避免 wrapper 高度 collapse 不可控)。\n// `nakedCellRowModeAlign` 提供:autoRow cell 內 first-line align(對齊既有 row geometry SSOT)。\n//\n// **禁加 overflow-hidden**:inner `<span truncate>` 自帶 overflow-hidden + text-overflow:ellipsis,\n//   wrapper overflow-hidden 反而 clip 24px avatar(ItemPrefix h-[1lh]~20px slot 容不下)+ break inner\n//   ellipsis trigger(圖一 + 圖二 root cause)。\n\n// code-quality-allow: dead-export — SSOT primitive 公開供 future cross-file 消費 + hook\n// `check_peoplepicker_ssot_drift.sh` enforce wrapper class literal pattern\nexport const PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS = `flex-1 min-w-0 inline-flex items-center ${nakedCellRowModeAlign}`\n\n// code-quality-allow: dead-export — paired helper for SSOT primitive(同上 hook + future use rationale)\nexport function getPeoplePickerTagWrapperClass(selectedCount: number): string {\n  return selectedCount === 1\n    ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS  // SSOT aligned to single picker wrapper(select.tsx:244 selectedItemRenderer wrapper)\n    // length>=2 stack 視覺(spec.md §D row 1):圓形 avatar overlap + group/avatar selector for dismiss overlay\n    : '-ml-0.5 first:ml-0 relative inline-flex group/avatar'\n}\n\n// ── Person → SelectOption mapping ───────────────────────────────────────────\n//\n// Issue 4(2026-05-10):forward person 的 description + avatar 給 Select(SelectOption schema\n// 已 unified with SelectMenuOption per Issue 4)。先前 PeoplePicker single mode 透過 Select 開\n// menu 時 dropdown row 只顯純文字 name(資訊弱)— 現透過 wrapper schema unify 直接帶 avatar /\n// description 給 SelectMenu primitive 渲。\n//\n// 2026-05-18 fix(per user directive「所有 avatar hover 都要 ProfileCard」+ avatar.spec.md\n// DS-wide canonical):dropdown menu items Avatar 必帶 hoverCard,跟 PersonDisplay / Tag\n// avatar 對齊。漏掉 = user 抓「PeoplePicker 選單內 avatar 沒有 namecard」。\nexport function personToSelectOption(person: PersonValue): SelectOption {\n  const p = resolvePerson(person)\n  return {\n    value: p.name,\n    label: p.name,\n    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonProfileCard(p) },\n    description: p.description,\n  }\n}\n\nexport function findPerson(people: PersonValue[], name: string): PersonValue {\n  return people.find(p => resolvePerson(p).name === name) ?? name\n}\n"],"names":[],"mappings":";;AA2CO,MAAM,sCAAsC,2CAA2C,qBAAqB;AAG5G,SAAS,+BAA+B,eAA+B;AAC5E,SAAO,kBAAkB,IACrB,sCAEA;AACN;AAYO,SAAS,qBAAqB,QAAmC;AACtE,QAAM,IAAI,cAAc,MAAM;AAC9B,SAAO;AAAA,IACL,OAAO,EAAE;AAAA,IACT,OAAO,EAAE;AAAA,IACT,QAAQ,EAAE,KAAK,EAAE,WAAW,KAAK,EAAE,MAAM,WAAW,uBAAuB,CAAC,EAAA;AAAA,IAC5E,aAAa,EAAE;AAAA,EAAA;AAEnB;AAEO,SAAS,WAAW,QAAuB,MAA2B;AAC3E,SAAO,OAAO,KAAK,CAAA,MAAK,cAAc,CAAC,EAAE,SAAS,IAAI,KAAK;AAC7D;"}

package/dist/components/PeoplePicker/people-picker.d.ts

@@ -1,13 +1,16 @@
 import * as React from 'react';
-import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
+import type { FieldMode, FieldVariant, FieldWidth } from '../../components/Field/field-types';
 import { type PersonValue } from './person-display';
 import { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass } from './people-picker-helpers';
 export { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass };
-export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
-    /** Field mode(edit / display / readonly / disabled),默認 inherit Field context 或 'edit' */
+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;
@@ -18,10 +21,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;
@@ -51,9 +59,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;
@@ -66,7 +81,7 @@ export declare const peoplePickerMeta: {
     readonly family: 4;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default", "hover", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly [];
         readonly fg: readonly ["text-fg-disabled", "text-fg-muted"];
@@ -74,4 +89,5 @@ export declare const peoplePickerMeta: {
     };
 };
 export { PeoplePicker };
+export { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonProfileCard, resolvePerson, type PersonValue, type PersonData, } from './person-display';
 //# sourceMappingURL=people-picker.d.ts.map

package/dist/components/PeoplePicker/people-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"people-picker.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/people-picker.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAQ3F,OAAO,EAA0F,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAU3I,OAAO,EACL,mCAAmC,EACnC,8BAA8B,EAG/B,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,mCAAmC,EAAE,8BAA8B,EAAE,CAAA;AAoB9E,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IAC/F,yFAAyF;IACzF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,GAAG,IAAI,CAAA;IAC1C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,IAAI,CAAA;IACzC,4BAA4B;IAC5B,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;IACtB;oFACgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sBAAsB;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;4EACwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sCAAsC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,iBAAiB;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,QAAA,MAAM,YAAY,0FAwUhB,CAAA;AAIF,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAWnB,CAAA;AAEV,OAAO,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"people-picker.d.ts","sourceRoot":"","sources":["../../../src/components/PeoplePicker/people-picker.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAwB,UAAU,EAAE,MAAM,8CAA8C,CAAA;AAS7H,OAAO,EAA6F,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAkB9I,OAAO,EACL,mCAAmC,EACnC,8BAA8B,EAG/B,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,mCAAmC,EAAE,8BAA8B,EAAE,CAAA;AAyB9E,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC;IAChH,sFAAsF;IACtF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB;8EAC0E;IAC1E,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,GAAG,IAAI,CAAA;IAC1C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,IAAI,CAAA;IACzC,4BAA4B;IAC5B,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;IACtB;oFACgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;sEAGkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;uFACmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sCAAsC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,iBAAiB;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,QAAA,MAAM,YAAY,0FAmZhB,CAAA;AAIF,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAYnB,CAAA;AAEV,OAAO,EAAE,YAAY,EAAE,CAAA;AAGvB,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAA"}

package/dist/components/PeoplePicker/people-picker.js

@@ -2,21 +2,25 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { ChevronDown } from "lucide-react";
 import { cn } from "../../lib/utils.js";
-import { EMPTY_DISPLAY, fieldWrapperStyles, nakedCellRowModeAlign } from "../Field/field-wrapper.js";
-import { ItemSuffix, ICON_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
-import { useFieldContext, useFieldSurface } from "../Field/field-context.js";
+import { nakedCellRowModeAlign, fieldWrapperStyles } from "../Field/field-wrapper.js";
+import { useFieldSurface, useFieldEmptyDisplay, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, fieldEmptyColorClass } from "../Field/field-context.js";
+import { ICON_SIZE, ItemSuffix } from "../../patterns/element-anatomy/item-anatomy.js";
 import { Avatar } from "../Avatar/avatar.js";
 import { Tag } from "../Tag/tag.js";
-import { Select } from "../Select/select.js";
-import { Combobox } from "../Combobox/combobox.js";
-import { MultiPersonDisplay, PersonDisplay, resolvePerson, buildPersonNameCard, PersonAvatarTag } from "./person-display.js";
+import { Select as Select$1 } from "../Select/select.js";
+import { Combobox as Combobox$1 } from "../Combobox/combobox.js";
+import { resolvePerson, MultiPersonDisplay, PersonDisplay, buildPersonProfileCard, PersonAvatarTag } from "./person-display.js";
 import { getAvatarStackVisibleCount, AVATAR_STACK_AVATAR_PX, AVATAR_STACK_OVERFLOW_CHIP_PX } from "./avatar-stack-overflow.js";
 import { findPerson, personToSelectOption, getPeoplePickerTagWrapperClass } from "./people-picker-helpers.js";
 import { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS } from "./people-picker-helpers.js";
+import { useIsTouchDevice } from "../../hooks/use-is-touch-device.js";
+const Select = Select$1;
+const Combobox = Combobox$1;
 const PeoplePicker = React.forwardRef(function PeoplePicker2({
   mode: modeProp,
   variant: variantProp,
-  size = "md",
+  width,
+  size: sizeProp,
   value,
   onChange,
   people = [],
@@ -24,72 +28,118 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
   // 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 = modeProp ?? (fieldCtx == null ? void 0 : fieldCtx.mode) ?? "edit";
-  const resolvedMode = disabled ? "disabled" : mode;
-  const resolvedVariant = variantProp ?? (fieldCtx == null ? void 0 : fieldCtx.variant) ?? "default";
+  const emptyDisplay = useFieldEmptyDisplay();
+  const size = useResolvedFieldSize(sizeProp);
+  const disabled = useResolvedFieldDisabled(disabledProp);
+  const resolvedMode = useResolvedFieldMode({ mode: modeProp, disabled });
+  const resolvedVariant = useResolvedFieldVariant(variantProp);
   const isMulti = Array.isArray(value);
   const isEmpty = !value || isMulti && value.length === 0;
-  if (resolvedMode === "display") {
+  const isTouch = useIsTouchDevice();
+  const effectiveMultiDisplay = isTouch && isMulti && surface === "form" ? "pill" : multiDisplay;
+  const selectedNames = !value ? [] : Array.isArray(value) ? value.map((v) => resolvePerson(v).name) : [resolvePerson(value).name];
+  const stackContainerRef = React.useRef(null);
+  const [stackVisibleCount, setStackVisibleCount] = React.useState(void 0);
+  React.useLayoutEffect(() => {
+    if (resolvedMode !== "edit" || !isMulti || effectiveMultiDisplay !== "stack" || selectedNames.length <= 1) {
+      setStackVisibleCount(void 0);
+      return;
+    }
+    const root = stackContainerRef.current;
+    if (!root) return;
+    const calc = () => {
+      const trigger = root.matches('[role="combobox"]') ? root : root.querySelector('[role="combobox"]') ?? root;
+      const tagArea = trigger == null ? void 0 : trigger.querySelector('div[class*="flex-1"][class*="min-w-0"]');
+      const available = (tagArea == null ? void 0 : tagArea.clientWidth) ?? (trigger == null ? void 0 : 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]);
+  const mergedStackRef = React.useCallback((el) => {
+    stackContainerRef.current = el;
+    if (typeof ref === "function") ref(el);
+    else if (ref) ref.current = el;
+  }, [ref]);
+  if (resolvedMode === "view") {
     if (!showDisplayEndIcon) {
-      if (isEmpty) return /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY });
-      return isMulti ? /* @__PURE__ */ jsx(MultiPersonDisplay, { value, size, measured: true }) : /* @__PURE__ */ jsx(PersonDisplay, { value, size });
+      return /* @__PURE__ */ jsx("div", { ref, className: cn("flex w-full min-w-0", className), "aria-label": ariaLabel, ...rest, children: isEmpty ? /* @__PURE__ */ jsx("span", { className: fieldEmptyColorClass(resolvedMode), children: emptyDisplay }) : isMulti ? /* @__PURE__ */ jsx(MultiPersonDisplay, { value, size, measured: true }) : /* @__PURE__ */ jsx(PersonDisplay, { value, size }) });
     }
     const iconSize = ICON_SIZE[size];
     return /* @__PURE__ */ jsxs(
       "div",
       {
-        className: cn(fieldWrapperStyles({ mode: "display", variant: resolvedVariant, size }), className),
-        "data-field-mode": "display",
+        ref,
+        className: cn(fieldWrapperStyles({ mode: "view", variant: resolvedVariant, width, size }), className),
+        "data-field-mode": "view",
+        "aria-label": ariaLabel,
+        ...rest,
         children: [
-          /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 inline-flex items-center", nakedCellRowModeAlign), children: isEmpty ? /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY }) : isMulti ? /* @__PURE__ */ jsx(MultiPersonDisplay, { value, size, measured: true }) : /* @__PURE__ */ jsx(PersonDisplay, { value, size }) }),
+          /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 inline-flex items-center", nakedCellRowModeAlign), children: isEmpty ? /* @__PURE__ */ jsx("span", { className: fieldEmptyColorClass(resolvedMode), children: emptyDisplay }) : isMulti ? /* @__PURE__ */ jsx(MultiPersonDisplay, { value, size, measured: true }) : /* @__PURE__ */ jsx(PersonDisplay, { value, size }) }),
           /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: "shrink-0 text-fg-muted", "aria-hidden": true }) })
         ]
       }
     );
   }
   if (resolvedMode !== "edit") {
-    return /* @__PURE__ */ jsx(
+    return /* @__PURE__ */ jsxs(
       "div",
       {
         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 : void 0,
         "aria-label": ariaLabel,
         ...rest,
-        children: /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 inline-flex items-center", nakedCellRowModeAlign, resolvedMode === "disabled" && "text-fg-disabled"), children: isEmpty ? /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: EMPTY_DISPLAY }) : isMulti ? /* @__PURE__ */ jsx(MultiPersonDisplay, { value, size, measured: true }) : /* @__PURE__ */ jsx(PersonDisplay, { value, size }) })
+        children: [
+          /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 inline-flex items-center", nakedCellRowModeAlign, resolvedMode === "disabled" && "text-fg-disabled"), children: isEmpty ? /* @__PURE__ */ jsx("span", { className: fieldEmptyColorClass(resolvedMode), children: emptyDisplay }) : isMulti ? /* @__PURE__ */ jsx(MultiPersonDisplay, { value, size, measured: true, disabled: resolvedMode === "disabled" }) : /* @__PURE__ */ jsx(PersonDisplay, { value, size, disabled: resolvedMode === "disabled" }) }),
+          (resolvedVariant === "naked" ? showDisplayEndIcon : resolvedMode === "disabled") && /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: ICON_SIZE[size], className: cn("shrink-0", resolvedMode === "disabled" ? "text-fg-disabled" : "text-fg-muted"), "aria-hidden": true }) })
+        ]
       }
     );
   }
-  const selectedNames = !value ? [] : Array.isArray(value) ? value.map((v) => resolvePerson(v).name) : [resolvePerson(value).name];
   if (!isMulti) {
-    const handleSingleChange = (name) => onChange == null ? void 0 : onChange([findPerson(people, name)]);
+    const handleSingleChange = (name) => onChange == null ? void 0 : onChange(name ? [findPerson(people, name)] : []);
     return /* @__PURE__ */ jsx(
       Select,
       {
         ref,
+        width,
         size,
         variant: resolvedVariant,
         options: people.map(personToSelectOption),
         value: selectedNames[0] ?? null,
         onChange: handleSingleChange,
         searchable: true,
+        clearable,
         placeholder,
+        emptyText,
         defaultOpen,
         onOpenChange,
         className,
@@ -99,13 +149,14 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
       }
     );
   }
-  if (multiDisplay === "pill") {
+  if (effectiveMultiDisplay === "pill") {
     const handleMultiChange2 = (next) => {
       onChange == null ? void 0 : onChange(next.map((name) => findPerson(people, name)));
     };
     return /* @__PURE__ */ jsx(
       Combobox,
       {
+        width,
         ref,
         size,
         variant: resolvedVariant,
@@ -113,9 +164,12 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
         value: selectedNames,
         onChange: handleMultiChange2,
         searchable: true,
+        searchIn,
+        clearable,
         searchPlaceholder,
+        searchAriaLabel,
         placeholder,
-        emptyPlaceholder: emptyText,
+        emptyText,
         wrap: pillWrap,
         defaultOpen,
         onOpenChange,
@@ -129,8 +183,8 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
             {
               size,
               color: "neutral",
-              avatar: pillShowAvatar ? /* @__PURE__ */ jsx(Avatar, { src: p.avatarUrl, alt: p.name, size: 16, hoverCard: buildPersonNameCard(p) }) : void 0,
-              onDismiss: onRemove,
+              avatar: pillShowAvatar ? /* @__PURE__ */ jsx(Avatar, { src: p.avatarUrl, alt: p.name, size: 16, hoverCard: buildPersonProfileCard(p) }) : void 0,
+              onRemove,
               children: p.name
             },
             item.value
@@ -142,40 +196,10 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
   const handleMultiChange = (next) => {
     onChange == null ? void 0 : onChange(next.map((name) => findPerson(people, name)));
   };
-  const stackContainerRef = React.useRef(null);
-  const [stackVisibleCount, setStackVisibleCount] = React.useState(void 0);
-  React.useLayoutEffect(() => {
-    if (!isMulti || selectedNames.length <= 1) {
-      setStackVisibleCount(void 0);
-      return;
-    }
-    const root = stackContainerRef.current;
-    if (!root) return;
-    const calc = () => {
-      const trigger = root.matches('[role="combobox"]') ? root : root.querySelector('[role="combobox"]');
-      const tagArea = trigger == null ? void 0 : trigger.querySelector('div[class*="flex-1"][class*="min-w-0"]');
-      const available = (tagArea == null ? void 0 : tagArea.clientWidth) ?? (trigger == null ? void 0 : 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]);
-  const mergedStackRef = React.useCallback((el) => {
-    stackContainerRef.current = el;
-    if (typeof ref === "function") ref(el);
-    else if (ref) ref.current = el;
-  }, [ref]);
   return /* @__PURE__ */ jsx(
     Combobox,
     {
+      width,
       ref: mergedStackRef,
       size,
       variant: resolvedVariant,
@@ -184,13 +208,15 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
       onChange: handleMultiChange,
       searchable: true,
       searchIn,
+      clearable,
       searchPlaceholder,
+      searchAriaLabel,
       placeholder,
-      emptyPlaceholder: emptyText,
+      emptyText,
       wrap: false,
       defaultOpen,
       onOpenChange,
-      className: cn(className, !isEmpty && surface === "form" && "!px-3"),
+      className: cn(className, !isEmpty && surface === "form" && "!px-[var(--field-px)]"),
       "aria-label": ariaLabel,
       tagWrapperClassName: getPeoplePickerTagWrapperClass(selectedNames.length),
       overflowWrapperClassName: "-ml-0.5 first:ml-0 relative inline-flex",
@@ -211,10 +237,10 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
                 src: p.avatarUrl,
                 alt: p.name,
                 size: 16,
-                hoverCard: buildPersonNameCard(p)
+                hoverCard: buildPersonProfileCard(p)
               }
             ),
-            onDismiss: () => {
+            onRemove: () => {
               onChange == null ? void 0 : onChange(selectedNames.filter((n) => n !== item.value).map((n) => findPerson(people, n)));
             },
             children: p.name
@@ -226,7 +252,7 @@ const PeoplePicker = React.forwardRef(function PeoplePicker2({
       tagRenderer: (item, onRemove) => {
         const p = resolvePerson(findPerson(people, item.value));
         if (selectedNames.length === 1) {
-          return /* @__PURE__ */ jsx(PersonDisplay, { value: p, size }, item.value);
+          return /* @__PURE__ */ jsx(PersonDisplay, { value: p, size, onRemove }, item.value);
         }
         return /* @__PURE__ */ jsx(
           PersonAvatarTag,
@@ -247,7 +273,8 @@ 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"],
@@ -255,9 +282,14 @@ const peoplePickerMeta = {
   }
 };
 export {
+  MultiPersonDisplay,
   PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS,
   PeoplePicker,
+  PersonAvatarTag,
+  PersonDisplay,
+  buildPersonProfileCard,
   getPeoplePickerTagWrapperClass,
-  peoplePickerMeta
+  peoplePickerMeta,
+  resolvePerson
 };
 //# sourceMappingURL=people-picker.js.map