@qijenchen/design-system 0.1.0-beta.3

package/src/components/NumberInput/number-input.tsx

@@ -0,0 +1,203 @@
+import * as React from 'react'
+import { type VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import type { InlineActionConfig } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext } from '@/design-system/components/Field/field-context'
+import { ItemInlineAction } from '@/design-system/patterns/element-anatomy/item-anatomy'
+
+// ── Format ──────────────────────────────────────────────────────────────────
+
+export interface NumberFormatOptions {
+  /** 小數位數 */
+  precision?: number
+  /** 前綴（如 '$'、'NT$'） */
+  prefix?: string
+  /** 後綴（如 '%'、'元'） */
+  suffix?: string
+  /** locale（預設 'en-US'） */
+  locale?: string
+}
+
+function formatNumber(
+  value: number | null | undefined,
+  options: NumberFormatOptions = {},
+): string {
+  if (value == null) return ''
+  const { precision, prefix = '', suffix = '', locale = 'en-US' } = options
+  const formatted = precision != null
+    ? value.toLocaleString(locale, { minimumFractionDigits: precision, maximumFractionDigits: precision })
+    : value.toLocaleString(locale)
+  return `${prefix}${formatted}${suffix}`
+}
+
+// Phase B1(2026-05-05):NumberInputDisplay 退場。
+// 改用 `<NumberInput mode="display" value={...} prefix={...} ... />`,format 邏輯在 mode='display' 分支重用。
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface NumberInputProps
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'onChange' | 'type'>,
+    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'>,
+    NumberFormatOptions {
+  /** Field display mode */
+  mode?: FieldMode
+  /**
+   * Visual chrome(正交於 mode);Phase B1(2026-05-05)新增。
+   * - `'default'`(預設)— 完整 Field wrapper chrome。
+   * - `'bare'` — 透明 variant,hover/focus 才 reveal(Toolbar inline / DataTable cell)。
+   *
+   * 透傳:在 `<Field variant="bare">` 內自動繼承 context.variant;per-prop override context。
+   */
+  variant?: FieldVariant
+  /** Error 狀態（正交於 mode）。 */
+  error?: boolean
+  /** 數值 */
+  value?: number | null
+  /** 數值變更 */
+  onChange?: (value: number | null) => void
+  /** 右側 inline action — 宣告式 API，Field 根據 size 自動渲染。 */
+  endAction?: InlineActionConfig
+  /**
+   * 右側 slot(ReactNode)— escape hatch 供 consumer 放自訂元素(如 stepper button group / 自訂 popover trigger)。
+   * 跟 `endAction` 互斥(同時傳 endSlot 會優先,endAction 被忽略)。
+   * 規則對齊 Input.endSlot:90% case 用 endAction 宣告式 API,10% config 表達不出時走 endSlot。
+   */
+  endSlot?: React.ReactNode
+}
+
+// ── Component ───────────────────────────────────────────────────────────────
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
+  (
+    {
+      mode: modeProp,
+      variant: variantProp,
+      error: errorProp = false,
+      size: sizeProp,
+      value,
+      onChange,
+      precision,
+      prefix,
+      suffix,
+      locale,
+      endAction,
+      endSlot,
+      className,
+      disabled: disabledProp,
+      readOnly,
+      id: idProp,
+      'aria-describedby': ariaDescribedByProp,
+      'aria-errormessage': ariaErrorMessageProp,
+      ...props
+    },
+    ref
+  ) => {
+    const fieldCtx = useFieldContext()
+    const error = errorProp || (fieldCtx?.invalid ?? false)
+    const size = sizeProp ?? fieldCtx?.size ?? 'md'
+    const disabled = disabledProp ?? fieldCtx?.disabled
+    // chrome 透傳:per-prop override context;context 沒值則 'default'
+    const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+    // mode resolve order(Phase B1 2026-05-05):prop > fieldCtx > readOnly/disabled fallback
+    const resolvedMode: FieldMode = modeProp
+      ?? fieldCtx?.mode
+      ?? (readOnly ? 'readonly' : disabled ? 'disabled' : 'edit')
+
+    // display / readonly / disabled 都顯示格式化值(span 取代 input)
+    if (resolvedMode !== 'edit') {
+      return (
+        <div
+          className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }), className)}
+          data-field-mode={resolvedMode}
+        >
+          <span
+            className={cn(
+              'flex-1 min-w-0',
+              resolvedMode === 'disabled' && 'text-fg-disabled cursor-not-allowed',
+              value == null && 'text-fg-muted',
+            )}
+          >
+            {value == null ? EMPTY_DISPLAY : formatNumber(value, { precision, prefix, suffix, locale })}
+          </span>
+        </div>
+      )
+    }
+
+    // edit 模式：raw 數值輸入
+    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      if (!onChange) return
+      const raw = e.target.value
+      if (raw === '' || raw === '-') {
+        onChange(null)
+        return
+      }
+      const parsed = Number(raw)
+      if (!Number.isNaN(parsed)) {
+        onChange(parsed)
+      }
+    }
+
+    return (
+      <div
+        className={cn(
+          fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
+          error && [
+            'border-error hover:border-error-hover',
+            'focus-within:border-error focus-within:hover:border-error',
+          ],
+          className,
+        )}
+        data-field-mode="edit"
+        data-error={error ? '' : undefined}
+      >
+        <input
+          ref={ref}
+          type="text"
+          inputMode="decimal"
+          id={idProp ?? fieldCtx?.id}
+          value={value ?? ''}
+          onChange={handleChange}
+          aria-invalid={error || undefined}
+          aria-required={fieldCtx?.required || undefined}
+          aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
+          aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
+          className={bareInputStyles}
+          {...props}
+        />
+        {endSlot ? (
+          // endSlot escape hatch:consumer 自控右側 slot(對齊 Input.endSlot canonical)
+          endSlot
+        ) : endAction ? (
+          <ItemInlineAction action={endAction} size={size ?? 'md'} />
+        ) : null}
+      </div>
+    )
+  }
+)
+NumberInput.displayName = 'NumberInput'
+
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const numberInputMeta = {
+  component: 'NumberInput',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: [],
+    fg: ['text-fg-disabled', 'text-fg-muted'],
+    ring: [],
+  },
+} as const
+
+// code-quality-allow: dead-export — public API surface — consumer-exposed for future use
+export { NumberInput, formatNumber }

package/src/components/OverflowIndicator/overflow-indicator.tsx

@@ -0,0 +1,156 @@
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+import { HoverCard, HoverCardTrigger, HoverCardContent } from '@/design-system/components/HoverCard/hover-card'
+import { tagVariants } from '@/design-system/components/Tag/tag'
+import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
+
+/**
+ * OverflowIndicator — +N 觸發器 + HoverCard 顯示溢出內容
+ *
+ * 統一用 HoverCard（不用 Tooltip）——溢出內容可能需要互動：
+ * - 人員 +N：tag dismiss + hover name card
+ * - 一般 +N：穩定顯示溢出項目
+ *
+ * trigger 不用 Tag 元件（Tag 有內建 truncation Tooltip 會跟 HoverCard 衝突），
+ * 改用 tagVariants 直接套樣式。
+ */
+
+const triggerSize: Record<string, string> = {
+  sm: 'h-5 min-w-5',
+  md: 'h-6 min-w-6',
+  lg: 'h-6 min-w-6',
+}
+
+const triggerText: Record<string, string> = {
+  sm: 'text-[10px]',
+  md: 'text-caption',
+  lg: 'text-caption',
+}
+
+export interface OverflowIndicatorProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
+  count: number
+  shape?: 'circle' | 'tag'
+  size?: 'sm' | 'md' | 'lg'
+  children: React.ReactNode
+  className?: string
+}
+
+function ShrinkWrapList({ children }: { children: React.ReactNode }) {
+  const containerRef = React.useRef<HTMLDivElement | null>(null)
+
+  // 2026-05-16 audit codex Round 6:rAF capture + cancel on unmount/re-run(defensive hygiene)。
+  // 原 callback ref `requestAnimationFrame(() => ...)` 沒 cancel,unmount-during-rAF 可能 fire 後
+  // mutate detached element.style — no-op but pattern hygiene 應對齊 DS-wide rAF cancel canonical。
+  React.useLayoutEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+    let rafId = 0
+    rafId = requestAnimationFrame(() => {
+      rafId = 0
+      const cs = getComputedStyle(container)
+      const padL = parseFloat(cs.paddingLeft) || 0
+      const padR = parseFloat(cs.paddingRight) || 0
+      const gap = parseFloat(cs.gap) || parseFloat(cs.columnGap) || 0
+      const available = container.offsetWidth - padL - padR
+
+      const items = Array.from(container.children) as HTMLElement[]
+      if (items.length === 0) return
+
+      let currentRow = 0
+      let maxRow = 0
+
+      items.forEach(item => {
+        const w = item.offsetWidth
+        const needed = currentRow > 0 ? currentRow + gap + w : w
+
+        if (needed > available && currentRow > 0) {
+          maxRow = Math.max(maxRow, currentRow)
+          currentRow = w
+        } else {
+          currentRow = needed
+        }
+      })
+      maxRow = Math.max(maxRow, currentRow)
+
+      container.style.maxWidth = `${Math.ceil(maxRow) + padL + padR + 1}px`
+    })
+    return () => { if (rafId) cancelAnimationFrame(rafId) }
+  }, [children])
+
+  return (
+    <div ref={containerRef} className="flex flex-wrap gap-1 p-2 max-w-[280px]">
+      {children}
+    </div>
+  )
+}
+
+const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorProps>(
+  function OverflowIndicator(
+    { count, shape = 'circle', size = 'md', children, className, ...props },
+    ref,
+  ) {
+    if (count <= 0) return null
+
+    const trigger = shape === 'tag' ? (
+      <span
+        ref={ref}
+        data-overflow-indicator=""
+        className={cn(tagVariants({ color: 'neutral', size }), 'cursor-default', className)}
+        {...props}
+      >
+        <span className="px-1">+{count}</span>
+      </span>
+    ) : (
+      <span
+        ref={ref}
+        data-overflow-indicator=""
+        className={cn(
+          'shrink-0 rounded-full inline-grid place-content-center',
+          'bg-muted text-foreground font-medium leading-none cursor-default',
+          triggerSize[size],
+          triggerText[size],
+          className,
+        )}
+        {...props}
+      >
+        +{count}
+      </span>
+    )
+
+    // 2026-05-18 fix(per user audit「所有 hovercard 應消費 hover delay token」+ motion.spec.md SSOT):
+    // rich tier(可互動 popup,user 可移浮層上操作)= HOVER_DELAY_RICH_MS;close = HOVER_DELAY_CLOSE_MS。
+    return (
+      <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+        <HoverCardTrigger asChild>
+          {trigger}
+        </HoverCardTrigger>
+        <HoverCardContent className="bg-tooltip rounded-lg" data-theme="dark">
+          <ShrinkWrapList>{children}</ShrinkWrapList>
+        </HoverCardContent>
+      </HoverCard>
+    )
+  },
+)
+OverflowIndicator.displayName = 'OverflowIndicator'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const overflowIndicatorMeta = {
+  component: 'OverflowIndicator',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-muted'],
+    fg: ['text-foreground'],
+    ring: [],
+  },
+} as const
+
+export { OverflowIndicator }

package/src/components/PeoplePicker/avatar-stack-overflow.ts

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

package/src/components/PeoplePicker/people-picker-helpers.ts

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