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

package/src/components/PeoplePicker/people-picker.spec.md

@@ -11,19 +11,21 @@ benchmark:
   - Polaris Combobox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Combobox
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # PeoplePicker 設計原則
 
 ## 定位
 
 PeoplePicker 是**人員選擇器**——專為「從人員清單中選一個或多個」設計的複合元件。外觀對齊 Select / Combobox，差異在選項前綴有 Avatar 視覺。
 
-**實作基礎**：組合元件——Popover + Command（cmdk）搜尋 + SelectMenu 浮層 + PersonDisplay render。無直接 external primitive base（底層靠 shadcn passthrough 的 Popover / Command）。
+**實作基礎**：組合元件——single mode wrap `<Select searchable>`、multi mode wrap `<Combobox>`(stack / pill 皆同;`people-picker.tsx` 檔頭「v15.6 SSOT 重構 v2」comment SSOT),已選值 render 用 `PersonDisplay`(Avatar + Name)。Popover + Command(cmdk)搜尋 + SelectMenu 浮層是 Select / Combobox 內部下層細節,PeoplePicker 不直接 import / render 它們。
 
 共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 PeoplePicker 特有的原則。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+## Controlled-only rationale(Dim 26)
+
+本元件採 **controlled-only**:`value` + `onChange`,不支援 `defaultValue` uncontrolled fallback(value pair V1)。多選跟隨內部 wrap 的 `Combobox`(controlled-only,rationale 見其 spec「Controlled-only rationale(Dim 26)」段);單選雖 wrap dual-mode 的 `Select`(其有 `defaultValue`),但本 wrapper 刻意不 expose `defaultValue` 以維持兩 mode API 一致——wrapper 單側開放 dual-mode 會產生狀態斷層。未來要改 dual-mode 需自 primitive 層引入 `useControllableState`,屬 major API 擴充。
+
+**Layout Family**：本元件是 `components/Field/field-controls.spec.md` 所擁有的 **Family 4（Field control layout）** 消費者。結構繼承其 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
 
 ---
 
@@ -42,7 +44,7 @@ PeoplePicker 是**人員選擇器**——專為「從人員清單中選一個或
 | 一般分類選擇（非人員）| `Select` / `Combobox` | PeoplePicker 專為人員設計，有 Avatar prefix |
 | 單選純文字選項（狀態 / 類別）| `Select` | PeoplePicker 開銷較大，靠 Avatar 識別；非人員用 Select |
 | 多選非人員 tag | `Combobox` | Combobox 是通用多選，無 Avatar 假設 |
-| 只顯示單一人員（不需選擇）| `NameCard` + `Avatar` | PeoplePicker 是選擇器，純展示用 NameCard |
+| 只顯示單一人員（不需選擇）| `ProfileCard` + `Avatar` | PeoplePicker 是選擇器，純展示用 ProfileCard |
 | 顯示整個 team 成員列表 | `Avatar.Group` / 自訂 list | PeoplePicker 是「選人」介面，不是「展示 team」 |
 
 ---
@@ -54,7 +56,7 @@ PeoplePicker 是**人員選擇器**——專為「從人員清單中選一個或
 | 模式 | value 類型 | 視覺 |
 |------|-----------|------|
 | 單選 | `PersonValue \| null` | Field 顯示單一 Avatar + Name |
-| 多選 | `PersonValue[]` | Field 顯示 Avatar 陣列（與 Combobox 多選同模式）|
+| 多選 | `PersonValue[]` | default `multiDisplay='stack'`:Avatar 疊合陣列;`multiDisplay='pill'` opt-in:每人矩形 Tag pill |
 
 **判斷**：
 - 「這個 task 指派給誰」→ 單選（assignee 通常一個）
@@ -62,17 +64,35 @@ PeoplePicker 是**人員選擇器**——專為「從人員清單中選一個或
 - 「加入 channel 的成員」→ 多選
 - 「文章作者」→ 單選
 
+### 多選顯示樣式(multiDisplay)
+
+Multi mode 公開 `multiDisplay` / `pillShowAvatar` / `pillWrap` 三個顯示 props(jsDoc SSOT 見 `people-picker.tsx` `PeoplePickerProps`;single mode 忽略):`multiDisplay='stack'`(default)= Avatar 疊合 + 圓形 `+N` overflow、不可 wrap;`'pill'` opt-in = 每人矩形 Tag pill、可 wrap(對齊 GitHub Reviewers / Combobox tag-input idiom)。`pillShowAvatar`(default `true`)控 pill 內 avatar prefix,`false` → 純文字 pill(對齊 Tag 元件 `avatar` prop SSOT);`pillWrap`(default `true`)控 pill 換行(對齊 Combobox `wrap` prop)。
+
+Multi 模式搜尋文案公開 `searchPlaceholder` / `searchAriaLabel`，分別轉送 wrapped Combobox 的可見 placeholder 與搜尋 input accessible name；`emptyText` 只負責 filtered-menu 空態，三者不互相代用。Single mode 的 inline search accessible name 沿用 PeoplePicker `aria-label` / Field label，因底層 Select 不公開獨立 `searchAriaLabel`。
+
 ---
 
 ## 搜尋
 
 PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為人員清單通常規模較大且使用者記得人名關鍵字（符合 Select spec「Searchable 開啟判斷」的「label 性質」主判準：人名是獨特關鍵字）。
 
-- **搜尋 placeholder**：預設「搜尋人員…」，可透過 `searchPlaceholder` 覆寫
+- **搜尋 placeholder**：預設「搜尋人員…」，可透過 `searchPlaceholder` 覆寫。**僅 multi 模式 panel-top search（`searchIn='menu'`，default）生效**——single mode wrap `<Select searchable>` 走 inline-trigger 搜尋，提示取自 `placeholder`（Select 無 searchPlaceholder prop）；multi `searchIn='trigger'` inline 搜尋同理走 placeholder 規則（見「Trigger display SSOT canonical table」§E）
 - **空狀態**：預設「沒有符合的人員」，透過 `emptyText` 覆寫
 
 ---
 
+## 一鍵清空(clearable)
+
+`clearable`(2026-08-05 加)機械轉發 wrapped Select(single)/ Combobox(multi)——X 的渲染、位置與清空行為 SSOT 在基座與 family canonical,本元件不另定義:
+
+- **幾何**:有值時 clear X 在 ChevronDown 左(`../Field/field-controls.spec.md`「下拉箭頭與類型身份 indicator」段)
+- **單選**:清除後回 placeholder 態(`../Select/select.spec.md`「Clearable」);wrapper 把基座 clear 的空字串映射為 `onChange([])`,不進 people 回查(fallback 會產生空名假人員)
+- **多選**:clear all 一次清除所有已選人員(`../Combobox/combobox.spec.md`「全部清除」),與 per-chip 移除並存
+- **何時開**:繼承 select.spec.md「何時開 clearable」判準——「無選擇是有效狀態」(選填人員欄位如觀察者 / 可清的人員 filter)開;必須有人(assignee 必填)不開
+- 只在 edit 模式顯示;readonly / disabled 不渲(基座行為)
+
+---
+
 ## 與 Select / Combobox 的分界
 
 | | PeoplePicker | Select | Combobox |
@@ -80,21 +100,23 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 | 資料類型 | **人員**（含 Avatar） | 任意（純文字）| 任意（純文字）|
 | 單選 / 多選 | 兩者皆支援（value 類型決定）| 單選 | 多選 |
 | 視覺 prefix | Avatar（必備） | 可選 startIcon | 無 |
-| 底層實作 | Popover + Command + SelectMenu | native `<select>` | native `<select>` + Tag overlay |
-| 搜尋 | 永遠啟用（人名本質）— 走 inline-trigger | 可選 `searchable`（單選短列表 → inline-trigger only）| 可選 `searchable` + `searchIn='menu' \| 'trigger'`（多選 → 兩種模式）|
+| 底層實作 | Popover + Command + SelectMenu | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu，`select.tsx:816`）/ 觸控 native `<select>`(`select.tsx` NativeSelect) | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu + Tag overlay，`combobox.tsx:840`）/ 觸控 native `<select>`(`combobox.tsx` NativeCombobox) |
+| 搜尋 | 永遠啟用（人名本質）；single = inline-trigger（wrap `<Select searchable>`），multi 預設 panel-top（`searchIn='menu'`，`searchIn='trigger'` opt-in）— 對齊本 spec L91-92 SSOT 表 | 可選 `searchable`（單選短列表 → inline-trigger only）| 可選 `searchable` + `searchIn='menu' \| 'trigger'`（多選 → 兩種模式）|
 
 **搜尋型態 SSOT canonical**（A1-A5 spec,2026-05-11;2026-05-12 補 PeoplePicker multi `searchIn` opt-in）：
 
 | 型態 | 使用情境 | 元件 API |
 |---|---|---|
 | **none** | 短列表 (< 7 選項) / 自然語言 label 可用 native type-ahead | 不傳 `searchable` |
-| **inline-trigger** | 單選 + 需快速 type-and-pick;trigger 變 input | `<Select searchable />` / `<Combobox searchable searchIn='trigger' />` / `<PeoplePicker />` single / `<PeoplePicker multi searchIn='trigger' />` |
-| **panel-top** | 多選 + 連續 type-and-select(關鍵字保留在 menu 不被 chip 切走) | `<Combobox searchable searchIn='menu' />` / `<PeoplePicker multi />`(default menu) |
+| **inline-trigger** | 單選 + 需快速 type-and-pick;trigger 變 input | `<Select searchable />` / `<Combobox searchable searchIn='trigger' />` / `<PeoplePicker value={person} />`(single = value 非陣列)/ `<PeoplePicker value={[...]} searchIn='trigger' />`(multi opt-in;無 `multi` prop — 單/多選由 value 是否為陣列決定,見「單選 vs 多選」)|
+| **panel-top** | 多選 + 連續 type-and-select(關鍵字保留在 menu 不被 chip 切走) | `<Combobox searchable searchIn='menu' />` / `<PeoplePicker value={[...]} />`(multi default menu)|
 
 ### Trigger display SSOT canonical table(2026-05-15 v3 user verbatim 整理)
 
 **PeoplePicker 是獨立元件,有自己的另一層 SSOT,並非完全繼承 Select / Combobox**。下表標出哪些繼承、哪些 PeoplePicker 自己定義 — **改一處先看本表,違反該層 SSOT = 漂移**。
 
+**讀表方式**:每 row 的設計意圖(canonical)為主體;`file:line` cite 是 drift 防護的實作錨點(改 code 必同步 cite),非要求讀者 trace 實作。
+
 #### A. 元件本質繼承表
 
 | 面向 | 來源 SSOT |
@@ -102,8 +124,8 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 | 單人互動邏輯(open/close/keyboard/搜尋)| **繼承 Select**(只多套一層 Avatar 視覺包裝)|
 | 多人互動邏輯(N tag / overflow / inline-search)| **繼承 Combobox**(但 tag 和溢出**換成圓形 avatar 視覺**)|
 | Avatar 在 field 內 padding(12px 固定)| **PeoplePicker 自己**(不繼承 Combobox density-dependent 公式)|
-| +N 溢出 chip 形狀(**圓形**)| **PeoplePicker 自己**(不繼承 Combobox 矩形 tag) |
-| 多人 tag 視覺(**圓形 avatar overlap `-ml-0.5`**) | **PeoplePicker 自己**(不繼承 Combobox 矩形 Tag chip)|
+| +N 溢出 chip 形狀(**圓形**;stack mode)| **PeoplePicker 自己**(不繼承 Combobox 矩形 tag) |
+| 多人 tag 視覺(default `multiDisplay='stack'`:**圓形 avatar overlap `-ml-0.5`**) | **PeoplePicker 自己**(`multiDisplay='pill'` opt-in 才用 Combobox 矩形 Tag pill,見「多選顯示樣式」)|
 | 多人 length=1 視覺(降階為 avatar+人名,跟單人視覺一致)| **PeoplePicker 自己**(Combobox 無此特殊)|
 
 #### B. 單人完整 trigger SSOT
@@ -111,9 +133,9 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 | state | trigger 顯示 |
 |---|---|
 | 空、closed | placeholder「請選擇人員」+ 按空間 ellipsis |
-| 選 1 人、closed | avatar + 人名 + 按空間 ellipsis(`PersonDisplay`,`person-display.tsx:131-147`)|
+| 選 1 人、closed | avatar + 人名 + 按空間 ellipsis(`PersonDisplay`,`person-display.tsx:137-152`)|
 | open + inline-search、未選 | input cursor + placeholder「請選擇人員」(trigger empty placeholder,**不**用「搜尋…」)|
-| open + inline-search、選 1 人 | input cursor + placeholder = **該人名**(本人名字當搜尋預設值,按空間 ellipsis;`select.tsx:185` `selectedLabel \|\| placeholder` empty-state fallback canonical)|
+| open + inline-search、選 1 人 | input cursor + 該人名 overlay(本人名字當記憶提示,按空間 ellipsis;`select.tsx:286,301` `triggerEmptyPlaceholder = placeholder \|\| '搜尋…'` + `showSelectedOverlay` span 顯人名,2026-05-15 Bug 2 fix 改 span overlay 取代原 native placeholder)|
 | open + panel-search、選 1 人 | avatar + 人名 + ellipsis(搜尋框在 panel 內,trigger 視覺不變)|
 
 #### C. 多人 length=1 trigger SSOT(降階為單人視覺)
@@ -137,20 +159,20 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 | 共享項 | SSOT owner |
 |---|---|
-| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L94 + `people-picker.tsx:316` `!px-3` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
-| Avatar+人名視覺 | `person-display.tsx:131-147` `PersonDisplay`(共享 renderer)|
-| 人名按空間 ellipsis | `person-display.tsx:144` `truncate flex-1 min-w-0` |
+| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L175「Avatar 左 inset SSOT」段 + `people-picker.tsx:463` `!px-[var(--field-px)]` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
+| Avatar+人名視覺 | `person-display.tsx:137-152` `PersonDisplay`(共享 renderer)|
+| 人名按空間 ellipsis | `person-display.tsx:150` `truncate flex-1 min-w-0` |
 | Placeholder ellipsis(inline-search active 時)| `field-wrapper.tsx:244` `bareInputStyles` 含 `truncate` |
-| Empty-state inline-search placeholder(未選時 → trigger empty placeholder) | `select.tsx:185` `selectedLabel \|\| placeholder` / `combobox.tsx:554` `items.length === 0 ? placeholder : ''`(2026-05-15 Drift A fix 對齊 PeoplePicker SSOT)|
+| Empty-state inline-search placeholder(未選時 → trigger empty placeholder) | `select.tsx:286` `triggerEmptyPlaceholder = placeholder \|\| '搜尋…'` / `combobox.tsx:909` CustomCombobox inline input `items.length === 0 ? placeholder : ''`(2026-05-15 Drift A fix 對齊 PeoplePicker SSOT)|
 
 **Avatar-presence → placeholder 規則(2026-05-15 user verbatim「只要有 avatar 存在,placeholder 都是空的,只會出現 cursor,這樣才不會造成混亂」)**:
 
 | 場景 | avatar 是否可見 | placeholder 行為 |
 |---|---|---|
-| 單人 inline-search、已選、open | ❌(input **取代** avatar/name,avatar 消失)| placeholder = **selectedLabel(該人名,memory aid)** — `select.tsx:185` |
+| 單人 inline-search、已選、open | ❌(input **取代** avatar/name,avatar 消失)| 該人名以 span overlay 顯示(memory aid)— `select.tsx:286,301`(2026-05-15 Bug 2 fix 改 span overlay)|
 | 單人 inline-search、未選、open | ❌(從來沒 avatar)| placeholder = **trigger empty placeholder「請選擇人員」** |
 | 多人 inline-search、length≥1、open | ✅(avatar/stack 仍在,input 在 trailing)| **placeholder = '' 純 cursor**(避免跟 avatar 重複)|
-| 多人 inline-search、length=0、open | ❌(empty)| placeholder = **trigger empty placeholder「請選擇人員」** — `combobox.tsx:554`(Drift A fix)|
+| 多人 inline-search、length=0、open | ❌(empty)| placeholder = **trigger empty placeholder「請選擇人員」** — `combobox.tsx` CustomCombobox inline input(Drift A fix)|
 
 **規則一句話**:`placeholder = (visible_avatar_exists) ? '' : (selectedLabel ?? triggerEmptyPlaceholder)`。
 
@@ -158,35 +180,63 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 #### F. Cell-edit ↔ Field-edit 一致性 invariant
 
-`MultiPersonCell` / `PersonCell`(`cell-registry.tsx:381-391` cell-as-input)+ form context PeoplePicker **包同一個元件**,所以 §B/§C/§D 規則對兩 surface 都成立。差別只在 padding 機制(共 §E)— 兩 surface 都產出 12px inset,**禁分歧**。
+`MultiPersonCell` / `PersonCell`(`cell-registry.tsx` cell-as-input,DataTable)+ form context PeoplePicker **包同一個元件**,所以 §B/§C/§D 規則對兩 surface 都成立。差別只在 padding 機制(共 §E)— 兩 surface 都產出 12px inset,**禁分歧**。
+
+**唯一例外(2026-08-05)**:觸控多選的 pill 降階只在 form surface 生效,table-cell 維持 stack —— 理由是 cell 的固定列高與 view↔edit 像素對齊契約優先於「觸控可移除成員」;cell 觸控編輯本就走原生 picker,移除在 picker 內完成。見「觸控裝置(native 分支)」段。
 
 **改 PeoplePicker 視覺前必查本表,動 trigger render / placeholder / overflowShape / tagWrapperClassName 前先 cite 對應 row。** Hook `check_peoplepicker_ssot_drift.sh` 機械強制。
 
-**Avatar 左 inset SSOT(2026-05-13 v2 — user 拍 Path a + density-drift root-cause,GitHub people picker idiom)**:single trigger / multi stack 第一個 avatar 距 trigger.left = **12px 固定**(不隨 size / density 漂移)。實作:PeoplePicker form context + 有 tag → `cn(className, '!px-3')` inject 12px override 到 Combobox Field wrapper,**覆蓋** Combobox `tagPadding[size]` density-dependent calc 公式;`tagAreaPaddingLeftPx={undefined}` 不再 +8 magic。Cell context naked variant `!px-[var(--table-cell-px)]` 已是 12px 不 inject。**為何 v1「4+8=12」公式報廢**(per 2026-05-13 codex V2 verdict correction):`tagPadding[size]` 是 `(field-height - icon-size) / 2`,真值表:default sm/md=4px → 4+8=12 ✓;default lg=6px → 14px ✗;comfortable sm/md=6px → 14px ✗;comfortable lg=8px → 16px ✗。**default sm + default md 兩個 size 也 = 12px**(我前 too narrow claim「只 md」 codex 修正);**真正漂的 = default lg + 全 comfortable 共 4 個組合**。整體 stale 結論不變(4 個漂 / 2 個對),故 `!px-3` 固定 12px 是正解。對齊 GitHub picker / Material Autocomplete renderTags / Ant Select tagRender 共享 fixed-inset canonical(不 scale with size)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Avatar 左 inset SSOT**:single trigger / multi stack 第一個 avatar 距 trigger.left = **12px 固定**(不隨 size / density 漂移)。實作:PeoplePicker form context + 有 tag → `cn(className, '!px-[var(--field-px)]')` inject 12px override 到 Combobox Field wrapper,**覆蓋** Combobox `tagPadding[size]` density-dependent calc 公式(該公式在 default lg + 全 comfortable 共 4/6 組合漂離 12px,故報廢改固定值;推導史詳 git log 2026-05-13);`tagAreaPaddingLeftPx={undefined}` 不再 +8 magic。Cell context naked variant `!px-[var(--table-cell-px)]` 已是 12px 不 inject。固定 inset 讓 avatar 與其他 Field control 的文字起點共享同一水平節奏，不被 density 改寫。
 
 **判準**：
 - **選人 → PeoplePicker**（不用 Select / Combobox 代替，失去 Avatar 視覺）
 - **非人員單選 → Select**
 - **非人員多選 → Combobox**
 
+**常見誤解**:(1)「PeoplePicker 只是 Combobox + avatar 皮」— 它有自己一層 SSOT(avatar 12px 固定 inset / 圓形 +N chip / avatar-presence placeholder 規則),見上方 §A 繼承表;(2)「拿來展示 team 名單」— 它是選擇器,純展示用 `Avatar.Group` / `ProfileCard`(見禁止事項)。
+
+---
+
+## 觸控裝置(native 分支)
+
+觸控裝置(`(pointer: coarse)`,`use-is-touch-device.ts`)上 wrapped Select / Combobox 切至 native 分支(下拉 = 原生 `<select>` picker)。**Display 層與桌機同 SSOT — 「Trigger display SSOT canonical table」§B-§D 對觸控同樣成立**(2026-08-05 user 拍板;先前 native 分支硬編碼純文字/文字 Tag,手機 edit 單人無 avatar、多人掉回矩形 pill = canonical 違反,已修):
+
+- **單人 edit**:avatar + 人名(`selectedItemRenderer` 經 NativeSelect 透明 overlay pattern,見 `select.spec.md`「雙分支同 SSOT」);無 inline search,tap 開原生選單
+- **多人 edit → 自動降階 pill(2026-08-05 user 拍板)**:觸控多選**在 form surface** 自動降階為既有 `multiDisplay='pill'`(`people-picker.tsx:184` `isTouch && isMulti && surface === 'form'`);**table-cell / inline-edit / toolbar 維持 stack**(cell 固定列高與 view↔edit 像素對齊契約優先,cell 的 surface 由 `cell-registry.tsx:533` `FieldSurfaceProvider surface="table-cell"` 提供)。降階後的視覺是既有 pill 型態(**不是新型態**:Combobox tag SSOT + Tag `avatar` prop,見「多選顯示樣式(multiDisplay)」),每顆 pill 自帶 X = Combobox「個別移除」canonical。**理由**:stack 的移除鈕是 hover-reveal,觸控無 hover;而讓每個 avatar 恆顯 X 視覺過載(user 否決前一版)。consumer 顯式傳 `'pill'` 時此降階為 no-op;**桌機(fine pointer)完全不受影響** — 仍是 avatar stack + 圓形 +N + hover X。實作 `people-picker.tsx` `effectiveMultiDisplay`(`useIsTouchDevice`)
+- **顯示層 pointer 契約**:renderer 輸出套「抬升 z-10 + pointer-events-none + 按鈕 `[&_button]` 回收」三件套(NativeCombobox 消費同一組 display props,見 `combobox.spec.md`「Display 層雙分支同 SSOT」)— pill 本體 tap 穿透喚起原生 picker(新增成員),pill 上的 X 照常可點(移除成員)
+- **選單**:觸控走原生 `<select>` picker(Combobox 觸控 SSOT,平台 a11y 最佳);原生選項無法渲 avatar 屬平台限制,桌機選單維持 PeoplePicker avatar + description 選項不變
+- 一鍵清空 X(`clearable`)由基座 native 分支自行渲染,觸控同樣可用
+
 ---
 
 ## PersonValue 型別
 
 ```tsx
-type PersonValue = string | { name: string; avatarUrl?: string; description?: string }
+type PersonValue = string | PersonData
+
+interface PersonData {
+  name: string
+  avatarUrl?: string
+  description?: string
+  status?: 'online' | 'away' | 'busy' | 'offline'
+  statusMessage?: React.ReactNode
+  id?: string
+  employeeNumber?: string
+  fields?: { label: string; value: string }[]
+  onViewProfile?: () => void
+}
 ```
 
 - **簡單用 string**：只有名字（fallback 顯示 initials）
-- **完整物件**：包含 avatar URL 和 description（顯示 Avatar + 次要資訊如 role / email）
+- **完整物件 `PersonData`**：name + avatar + presence 狀態 + 狀態訊息 + 員工 ID + 自訂欄位 + profile 跳轉（展示完整 ProfileCard，對齊 `avatar.spec.md`「person avatar hover → ProfileCard」DS-wide canonical；SSOT 型別見 `person-display.tsx` PersonData）
 
 ---
 
 ## readonly / disabled
 
 與其他 Field 一致：
-- **readonly**：顯示選中人員（Avatar + Name），無 dropdown trigger、無搜尋
-- **disabled**：灰化整個 field，不可互動
+- **readonly**：顯示選中人員（Avatar + Name），無 dropdown trigger、無搜尋；avatar hover ProfileCard 保留（純展示仍可查閱人員資訊）
+- **disabled**：灰化整個 field，不可互動——含 avatar dim（host-controlled opacity）+ 抑制 avatar ProfileCard hoverCard（無 HoverCard wrapper / 無 tab stop；2026-07-14 修，原 hoverCard 未抑制 falsify「不可互動」）
 
 ---
 
@@ -200,21 +250,24 @@ type PersonValue = string | { name: string; avatarUrl?: string; description?: st
 
 ---
 
-## 為何無 Inspector
+## Anatomy story 結構
 
-PeoplePicker 是 **composite Field Control**(Field shell + Avatar + SelectMenu),關鍵決策維度是 `mode`(single / multi)× `size` × search behavior × value type——已由 `ModeMatrix` / `SizeMatrix` / `ColorMatrix` / `StateBehavior` / `PersonValueType` 五張矩陣完整覆蓋。互動 Inspector 對 composite 元件較弱:「傳 PersonValue 陣列」需要真實資料 fixture 展示,單組合試玩無法呈現——改以 `StateBehavior` 的真實 Assignee picker 場景取代。
+PeoplePicker 是 **composite Field Control**(Field shell + Avatar + SelectMenu),anatomy 採 DS 標準結構 + 元件特有矩陣:
 
-對應 anatomy story:保留 `Overview` + 元件特有 `ModeMatrix` / `PersonValueType` + `SizeMatrix` + `ColorMatrix` + `StateBehavior`。
+- `Overview` —— 預設視覺概覽
+- `Inspector` —— 互動式 prop 試玩(`mode` × `size` × `disabled` 即時切換,搭 `SAMPLE_PEOPLE` fixture)。對齊全部同類 composite Field Control(Combobox / Select / SelectMenu / DatePicker / TimePicker / NumberInput / LinkInput 皆有 Inspector)的 DS 慣例,單組合即時試玩 prop。
+- 元件特有 `ModeMatrix`(single / multi)+ `PersonValueType`(value 結構)—— Inspector 單一組合無法同時並列的跨模式 / 多值對照,由矩陣補齊
+- 標準 `SizeMatrix` / `ColorMatrix` / `StateBehavior`(真實 Assignee picker 場景)
 
 ---
 
 ## shadcn passthrough 例外說明
 
-PeoplePicker 是 **composite 元件**(Popover + Command + SelectMenu + Avatar 內部組裝),其 API 為完全 declarative(value / onChange / size / mode / options...)。**不套 `forwardRef` / `...props` spread**:
+PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / people...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:111` / L53 / L131 `...rest`):
 
-- **沒有單一 DOM root 可 ref**:consumer「對誰 forward」含糊——指 Popover trigger?Command search input?SelectMenu content?任一選擇都會誤導 consumer
-- **`...props` spread 會撒到何處?** composite 元件無 identity DOM,spread 若到 root wrapper 多半無意義(wrapper 只是 flex container);到 trigger 則語義不清
-- **API 邊界明確才是 composite 價值**:PeoplePicker 暴露的是「選人」語意,不是「彈出選單 + 搜尋 + 渲染頭像」的 DOM 細節。若 consumer 需要 DOM-level 控制,該用底層 Popover + Combobox 自組,不該透過 PeoplePicker
+- **forwardRef + 單一 root**:`PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>`,ref 與 `...rest`(`id` / `data-testid` / `onBlur` / `onFocus` / `aria-*` 等 HTML root props)forward 到內部 trigger 容器(readonly/disabled root div、或 wrapped Select / Combobox 的 root),對齊 DS 既有 Combobox / Select 慣例
+- **`onChange` 走 Omit**:本元件 onChange 用 `(value: PersonValue[]) => void` custom signature,跟 HTMLAttributes onChange 衝突,故 Omit
+- **API 邊界明確才是 composite 價值**:PeoplePicker 暴露的是「選人」語意,不是「彈出選單 + 搜尋 + 渲染頭像」的 DOM 細節。若 consumer 需要更細的 DOM-level 控制,該用底層 Popover + Combobox 自組,不該透過 PeoplePicker
 
 `displayName = 'PeoplePicker'` 保留,無 `asChild`(composite 不是 Slot-compat)。
 
@@ -222,11 +275,13 @@ PeoplePicker 是 **composite 元件**(Popover + Command + SelectMenu + Avatar
 
 ## 邊界案例
 
-- **Disabled**:Field SSOT own;trigger / dismiss / inline-search input 全 disable,已選 avatar tag dismiss X 自動隱藏(對齊 Combobox readonly/disabled tag 規則)。token 走 M24 state precedence。
-- **Loading(async people fetch)**:`loading?: boolean` forward 給 SelectMenu(SelectMenu 端「Loading」段 SSOT);dropdown body 替換為 `<Empty icon={<CircularProgress size={48}/>}/>` + `aria-busy`。trigger 不變,user 隨時可開。
-- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L72 已 codify);無 creatable mode(人員不可建立)。
+- **Disabled**:`disabled` → `resolvedMode='disabled'`(`useResolvedFieldMode`),走獨立 static-display 分支(`people-picker.tsx`「readonly / disabled」段)——渲染靜態 `<div>` 包 `MultiPersonDisplay` / `PersonDisplay` + `ItemSuffix` ChevronDown 類型身份 indicator(2026-06-26:disabled 保留 chevron、readonly 不顯示;naked variant 依 `showDisplayEndIcon`),**不** wrap Select / Combobox、無 dismiss X、無 inline-search input。token 走 M24 state precedence(`text-fg-disabled`,含 chevron)。
+- **Loading(async people fetch)**:目前 PeoplePicker **未暴露 `loading` prop**(`PeoplePickerProps` 無此欄位,內部也未 forward 給 wrapped Select / Combobox)。consumer 若需 loading 態,在 fetch 完成前自行控制 `people=[]`(走 emptyText 空態)。底層 Select / Combobox / SelectMenu 各有自己的 loading 機制,但尚未經 PeoplePicker API 層轉發。
+- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L80 已 codify);無 creatable mode(人員不可建立)。
 - **Empty(no value selected)**:single mode → trigger 顯 placeholder「請選擇人員」;multi mode `value=[]` → trigger 同 placeholder(無 avatar stack 渲);詳「Trigger display SSOT canonical table」B-D 段。
-- **Dark mode / density**:Avatar 12px inset 固定不隨 density 漂移(PeoplePicker own,本 spec L94 + L140 codify);其他走 Field + SelectMenu SSOT。
+- **`people` 清單變動(async fetch 後更新)**:已選 value 顯示不依賴 `people` 查找 — display 路徑直接渲染 value 自帶資料;edit 路徑以人名回查 `people`,查不到降級為純名字 string(initials fallback),不報錯(`people-picker-helpers.ts:74-75`)。選單選項即時跟隨 props 重渲。
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。avatar overlap / inset 不在本檔另立支援決策。
+- **Dark mode / density**:Avatar 12px inset 固定不隨 density 漂移(PeoplePicker own,見「Trigger display SSOT canonical table」§E + Avatar 左 inset SSOT 段);其他走 Field + SelectMenu SSOT。
 
 ---
 
@@ -237,7 +292,7 @@ PeoplePicker 是 **composite 元件**(Popover + Command + SelectMenu + Avatar
 - `../Combobox/combobox.spec.md` — 非人員多選的對應元件
 - `../SelectMenu/select-menu.tsx` — PeoplePicker edit mode 的浮層選單（內部消費）
 - `../Avatar/avatar.spec.md` — 選項與已選值的 Avatar 視覺
-- `../NameCard/name-card.spec.md` — 純顯示人員資訊的對應元件（非選擇器）
+- `../ProfileCard/profile-card.spec.md` — 純顯示人員資訊的對應元件（非選擇器）
 - `../Field/field-controls.spec.md` — Field Control 共用規則
 
 ## A11y 預設
@@ -252,7 +307,9 @@ PeoplePicker 是 **composite 元件**(Popover + Command + SelectMenu + Avatar
 - ↑/↓ — 導覽 people
 - Enter — 選擇 / 取消選擇
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+**Focus**:Field 家族 focus 由 Field wrapper 提供(`focus-within:!border-primary`,`field-wrapper.tsx` v13.3 SSOT;對齊 Select / Combobox spec「Focus」段),非 outline ring;focus management 由元件 own。
+
+移除已選人員後的 focus order 消費 Combobox collection contract：下一個 remove control → 前一個 → owner combobox trigger，禁止 focus 掉到 `body`。Stack avatar remove button 必保留 `data-collection-remove` marker 供 owner 統一接管。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 

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

@@ -0,0 +1,245 @@
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { expect, userEvent, waitFor, within } from '@storybook/test'
+import { PeoplePicker } from '@/design-system/components/PeoplePicker/people-picker'
+import type { PersonValue } from './person-display'
+import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldError, FieldLabel } from '@/design-system/components/Field/field'
+
+const meta: Meta = {
+  title: 'Design System/Components/PeoplePicker/展示',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: '用於指派、邀請或選擇一位或多位人員，並以 Avatar 幫助辨識同名成員。非人員的單選／多選改用 Select / Combobox；只顯示人員資訊時改用 ProfileCard、Avatar.Group 或 list。',
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+// PersonData sample 含 ProfileCard 重要資訊(status / statusMessage / fields)—
+// canonical:所有 person avatar hover 都應 render 完整資訊(profile-card.spec.md)。
+const samplePeople = [
+  {
+    name: 'Alice Chen', avatarUrl: 'https://i.pravatar.cc/48?u=alice', description: 'Design｜D-0042｜EMP-1001',
+    status: 'online' as const,
+    statusMessage: 'Out of Office: Back on Monday! For urgent matters please contact @Wei-Lun Cheng in the meantime.',
+    fields: [{ label: 'ID', value: 'YHANAX' }, { label: 'Employee number', value: 'EMP-1001' }],
+  },
+  {
+    name: 'Bob Lin', avatarUrl: 'https://i.pravatar.cc/48?u=bob', description: 'Engineering｜E-0087｜EMP-1002',
+    status: 'busy' as const,
+    statusMessage: '正在處理 Q2 release,優先處理 P0 issues',
+    fields: [{ label: 'ID', value: 'BLIN01' }, { label: 'Employee number', value: 'EMP-1002' }],
+  },
+  {
+    name: 'Charlie Wu', avatarUrl: 'https://i.pravatar.cc/48?u=charlie', description: 'Product｜P-0015｜EMP-1003',
+    status: 'away' as const,
+    statusMessage: '外出開會,下午 3 點後回覆',
+    fields: [{ label: 'ID', value: 'CWU003' }, { label: 'Employee number', value: 'EMP-1003' }],
+  },
+  {
+    name: 'Diana Huang', avatarUrl: 'https://i.pravatar.cc/48?u=diana', description: 'Marketing｜M-0023｜EMP-1004',
+    status: 'online' as const,
+    statusMessage: 'Welcome pings! 我下午在 campaign review meeting',
+    fields: [{ label: 'ID', value: 'DHUANG' }, { label: 'Employee number', value: 'EMP-1004' }],
+  },
+  {
+    name: 'Eric Tsai', avatarUrl: 'https://i.pravatar.cc/48?u=eric', description: 'Engineering｜E-0091｜EMP-1005',
+    status: 'offline' as const,
+    statusMessage: 'PTO until next Tuesday',
+    fields: [{ label: 'ID', value: 'ETSAI' }, { label: 'Employee number', value: 'EMP-1005' }],
+  },
+  {
+    name: 'Fiona Lee', avatarUrl: 'https://i.pravatar.cc/48?u=fiona', description: 'Design｜D-0056｜EMP-1006',
+    status: 'online' as const,
+    statusMessage: 'Working on ProfileCard v3 refactor',
+    fields: [{ label: 'ID', value: 'FLEE' }, { label: 'Employee number', value: 'EMP-1006' }],
+  },
+]
+
+/* ── 單人（互動） ── */
+const SinglePicker = () => {
+  const [val, setVal] = React.useState<PersonValue | null>(samplePeople[0])
+  return (
+    <div className="flex flex-col gap-6 max-w-xs">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">edit（可互動）</h3>
+        <PeoplePicker value={val} people={samplePeople} onChange={(v) => setVal(v[0] ?? null)} aria-label="負責人(edit mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <PeoplePicker mode="view" value={samplePeople[0]} />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+        <PeoplePicker mode="readonly" value={samplePeople[0]} />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+        <PeoplePicker mode="disabled" value={samplePeople[0]} />
+      </div>
+    </div>
+  )
+}
+
+export const Single: Story = {
+  name: '單人',
+  render: () => <SinglePicker />,
+}
+
+function PeoplePickerErrorExample() {
+  const [value, setValue] = React.useState<PersonValue | null>(null)
+  return (
+    <Field required invalid={value == null} className="max-w-xs">
+      <FieldLabel>任務負責人</FieldLabel>
+      <PeoplePicker
+        value={value}
+        people={samplePeople}
+        onChange={next => setValue(next[0] ?? null)}
+        aria-label="任務負責人"
+      />
+      {value == null && <FieldError>請指派一位任務負責人</FieldError>}
+    </Field>
+  )
+}
+
+export const WithError: Story = {
+  name: '驗證錯誤',
+  render: () => <PeoplePickerErrorExample />,
+}
+
+/* ── 多人（互動） ── */
+const MultiPicker = () => {
+  const [val, setVal] = React.useState<PersonValue[]>(samplePeople.slice(0, 4))
+  const readonlyVal = samplePeople.slice(0, 4)
+  return (
+    <div className="flex flex-col gap-6 max-w-xs">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">edit（可互動,多選）</h3>
+        <PeoplePicker value={val} people={samplePeople} onChange={setVal} aria-label="專案協作者(edit multi demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+        <PeoplePicker mode="readonly" value={readonlyVal} />
+      </div>
+    </div>
+  )
+}
+
+export const Multi: Story = {
+  name: '多人',
+  render: () => <MultiPicker />,
+}
+
+// Roving-focus 契約 probe:逐一移除 chip 時焦點依序落到下一個移除鈕,移除
+// 最後一人後回到 combobox。破壞性互動(清空全員)只屬測試,不得寄生在
+// reader-facing 展示 story(anchor:2026-08-05 user 抓「多人一打開就自己清空」;
+// 前身還為此加過「重設協作者」假 UI,ccf83b24)。story-rules「Technical probe
+// visibility」canonical:標 test-only,自 sidebar/Autodocs 排除,test runner 照跑。
+export const MultiRemoveFocusContract: Story = {
+  name: '移除焦點接力驗證',
+  tags: ['test-only'],
+  render: () => <MultiPicker />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    await userEvent.click(await canvas.findByRole('button', { name: '移除 Alice Chen' }))
+    await waitFor(() => expect(canvas.getByRole('button', { name: '移除 Bob Lin' })).toHaveFocus())
+    await userEvent.click(canvas.getByRole('button', { name: '移除 Bob Lin' }))
+    await waitFor(() => expect(canvas.getByRole('button', { name: '移除 Charlie Wu' })).toHaveFocus())
+    await userEvent.click(canvas.getByRole('button', { name: '移除 Charlie Wu' }))
+    await waitFor(() => expect(canvas.getByRole('button', { name: '移除 Diana Huang' })).toHaveFocus())
+    await userEvent.click(canvas.getByRole('button', { name: '移除 Diana Huang' }))
+    await waitFor(() => expect(canvas.getByRole('combobox', { name: '專案協作者(edit multi demo)' })).toHaveFocus())
+  },
+}
+
+// Stack 移除鈕完整性 probe:AvatarDismissOverlay(`-top-px` + 2px ring,person-display.tsx)
+// 必須完整可見,不被 tag 列裁切(combobox.tsx tagRowOverflowClass 只裁水平;anchor:2026-08-05
+// user 抓「hover X 上緣被裁」— 2026-05-18 F2 雙軸 overflow-hidden 副作用)。screenshot lane
+// 無 hover 能力,以 keyboard focus 觸發 group-focus-within 顯示 overlay。
+export const StackRemoveOverlayProbe: Story = {
+  name: '移除鈕完整性驗證',
+  tags: ['test-only'],
+  render: () => <MultiPicker />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const btn = await canvas.findByRole('button', { name: '移除 Alice Chen' })
+    btn.focus()
+  },
+}
+
+/* ── 一鍵清空(選填欄位) ── */
+// X 在 ChevronDown 左(family SSOT field-controls.spec.md「下拉箭頭」段)。「無選擇是有效
+// 狀態」的選填欄位才開 clearable(select.spec.md「何時開」)——代理人 / 觀察者是典型選填人員欄位。
+const ClearablePicker = () => {
+  const [delegate, setDelegate] = React.useState<PersonValue | null>(samplePeople[1])
+  const [watchers, setWatchers] = React.useState<PersonValue[]>(samplePeople.slice(2, 5))
+  return (
+    <div className="flex flex-col gap-6 max-w-xs">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">單人(代理人,選填)</h3>
+        <PeoplePicker clearable value={delegate} people={samplePeople} onChange={(v) => setDelegate(v[0] ?? null)} aria-label="代理人(選填)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">多人(觀察者,選填)</h3>
+        <PeoplePicker clearable value={watchers} people={samplePeople} onChange={setWatchers} aria-label="觀察者(選填)" />
+      </div>
+    </div>
+  )
+}
+
+export const Clearable: Story = {
+  name: '一鍵清空(選填欄位)',
+  render: () => <ClearablePicker />,
+}
+
+/* ── 尺寸與 Button 對齊 ── */
+const SizePicker = ({ size }: { size: 'sm' | 'md' | 'lg' }) => {
+  const [val, setVal] = React.useState<PersonValue | null>(samplePeople[0])
+  return (
+    <div className="flex items-center gap-3">
+      <PeoplePicker size={size} value={val} people={samplePeople} onChange={(v) => setVal(v[0] ?? null)} className="max-w-xs" aria-label={`負責人(size=${size})`} />
+      <Button variant="primary" size={size}>送出</Button>
+      <span className="text-caption text-fg-muted">size="{size}"</span>
+    </div>
+  )
+}
+
+export const SizeAlignment: Story = {
+  name: '尺寸',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      {(['sm', 'md', 'lg'] as const).map(size => (
+        <SizePicker key={size} size={size} />
+      ))}
+    </div>
+  ),
+}
+
+/* ── 人員清單非同步載入（已選值先到、名錄後到） ── */
+const AsyncDirectoryPicker = () => {
+  const [people, setPeople] = React.useState<PersonValue[]>([])
+  const [val, setVal] = React.useState<PersonValue[]>([samplePeople[0], samplePeople[2]])
+  React.useEffect(() => {
+    const timer = window.setTimeout(() => setPeople(samplePeople), 1500)
+    return () => window.clearTimeout(timer)
+  }, [])
+  return (
+    <div className="flex flex-col gap-2 max-w-xs">
+      <PeoplePicker value={val} people={people} onChange={setVal} aria-label="任務協作者" />
+      <p className="text-caption text-fg-secondary">
+        Jira 任務「協作者」欄位場景：已選成員隨任務資料先抵達，組織人員名錄約 1.5 秒後才從 API 回來——已選成員立即顯示、不報錯；名錄未到前 avatar 先以姓名縮寫 fallback 呈現，名錄載入後自動補上頭像。
+      </p>
+    </div>
+  )
+}
+
+export const AsyncDirectoryLoad: Story = {
+  name: '人員清單非同步載入',
+  render: () => <AsyncDirectoryPicker />,
+}