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

package/src/components/PeoplePicker/person-display.tsx

@@ -1,11 +1,12 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 import * as React from 'react'
 import { X } from 'lucide-react'
-import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+import { cn } from '@/lib/utils'
+import { useFieldEmptyDisplay } from '@/design-system/components/Field/field-context'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { OverflowIndicator } from '@/design-system/components/OverflowIndicator/overflow-indicator'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
-import { NameCard, NameCardDefaultActions } from '@/design-system/components/NameCard/name-card'
+import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
 import { useTableIsScrolling } from '@/design-system/components/Field/field-context'
 import { ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import {
@@ -16,24 +17,25 @@ import {
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
-// PersonData 承載 NameCard 所需的完整資訊。DS 全域 person avatar 的 hoverCard NameCard 永遠
-// 顯示同一組 sections(name + subtitle + status + 4 default fields + 自訂 fields + actions + View more)
-// — 缺資料顯 placeholder,不會 collapse。對齊 avatar.spec.md「person avatar hover → NameCard」
-// DS-wide canonical(2026-05-06 v11 always-render schema 升級)。
+// PersonData 承載 ProfileCard 所需的完整資訊。DS 全域 person avatar 的 hoverCard ProfileCard 顯示
+// 同一組 sections(name + subtitle + status + 2 default fields(id + employeeNumber,見下方
+// NAMECARD_DEFAULT_FIELD_KEYS 對齊註解)+ 自訂 fields + actions + View more)— 缺資料顯 placeholder;
+// **例外:status undefined 時整 status block 省略(collapse,= loading transient,見 status jsDoc)**。
+// 對齊 avatar.spec.md「person avatar hover → ProfileCard」DS-wide canonical。
 export interface PersonData {
   name: string
   avatarUrl?: string
-  /** 角色 / 部門 / ID 等 meta 單行(NameCard subtitle) */
+  /** 角色 / 部門 / ID 等 meta 單行(ProfileCard subtitle) */
   description?: string
   /** Presence 狀態(對齊 Avatar presence canonical)。**2026-05-14 v12 update**(per user 拍板):
    *  production 每 user 一定有 presence state,**undefined = loading transient(資料還沒讀到)**,
-   *  不是「user 沒設定」。NameCard 在 undefined 期間隱藏整 status block,**禁** render「Status not set」
+   *  不是「user 沒設定」。ProfileCard 在 undefined 期間隱藏整 status block,**禁** render「Status not set」
    *  placeholder 文字。 */
   status?: 'online' | 'away' | 'busy' | 'offline'
-  /** Status 訊息(NameCard status section)。只在 status defined 時 render,缺則顯 `—` placeholder。
+  /** Status 訊息(ProfileCard status section)。只在 status defined 時 render,缺則顯 `—` placeholder。
    *  Status undefined 整 block skip(無 statusMessage 也跟著 skip)。 */
   statusMessage?: React.ReactNode
-  /** **2026-05-07 v15.7 user directive**:NameCard default 只 render `id` + `employeeNumber`,
+  /** **2026-05-07 v15.7 user directive**:ProfileCard default 只 render `id` + `employeeNumber`,
    *  其他 description 一律 opt-in by consumer 透過 `fields` array prop。對齊
    *  `NAMECARD_DEFAULT_FIELD_KEYS = ['id', 'employeeNumber']`。 */
   id?: string
@@ -41,8 +43,12 @@ export interface PersonData {
   /** 自訂額外 fields(在 default fields 之後 append)。Email / Phone / Department / Location
    *  / 任何其他 description 一律走這個 prop(opt-in,consumer 自選)。 */
   fields?: { label: string; value: string }[]
-  /** 跳至完整 profile 頁的 handler(hover NameCard 必含,不傳時 fallback noop placeholder) */
+  /** 跳至完整 profile 頁的 handler(hover ProfileCard 必含,不傳時 fallback noop placeholder) */
   onViewProfile?: () => void
+  /** ProfileCard 預設 Chat 按鈕 handler(2026-07-06 user 拍板加接線;未傳 dev-warn,見 ProfileCardDefaultActions) */
+  onChat?: () => void
+  /** ProfileCard 預設 Audio call 按鈕 handler(ChevronDown 下拉行為留 v2) */
+  onCall?: () => void
 }
 
 export type PersonValue = string | PersonData
@@ -51,16 +57,16 @@ function resolvePerson(value: PersonValue): PersonData {
   return typeof value === 'string' ? { name: value } : value
 }
 
-// buildPersonNameCard — DS 全域 person avatar hoverCard 的 canonical NameCard JSX 建構器。
-// SSOT for「avatar hover NameCard 一致視覺」— 任何 person avatar consumer 都走這個 helper,
-// 不可繞道直接 build NameCard。
+// buildPersonProfileCard — DS 全域 person avatar hoverCard 的 canonical ProfileCard JSX 建構器。
+// SSOT for「avatar hover ProfileCard 一致視覺」— 任何 person avatar consumer 都走這個 helper,
+// 不可繞道直接 build ProfileCard。
 //
 // **2026-05-07 v15.7 user directive**:default field values 只 `id` + `employeeNumber`,
 // 對齊 NAMECARD_DEFAULT_FIELD_KEYS。其他 description(email/phone/department/location/etc)
 // consumer 想顯式透過 `person.fields` opt-in 傳入。
-function buildPersonNameCard(person: PersonData): React.ReactNode {
+function buildPersonProfileCard(person: PersonData): React.ReactNode {
   return (
-    <NameCard
+    <ProfileCard
       name={person.name}
       subtitle={person.description}
       avatar={{ src: person.avatarUrl, alt: person.name }}
@@ -71,7 +77,7 @@ function buildPersonNameCard(person: PersonData): React.ReactNode {
         employeeNumber: person.employeeNumber,
       }}
       fields={person.fields}
-      actions={<NameCardDefaultActions />}
+      actions={<ProfileCardDefaultActions onChat={person.onChat} onCall={person.onCall} />}
       // onViewMore hover context 必含(avatar.spec.md canonical)。consumer 傳
       // `onViewProfile` 則用真 handler,否則 noop placeholder(UI 仍渲染 View more
       // footer,避免 preview 變死路)。
@@ -86,42 +92,49 @@ function buildPersonNameCard(person: PersonData): React.ReactNode {
 const AVATAR_PX: Record<'sm' | 'md' | 'lg', number> = { sm: 20, md: 24, lg: 24 }
 
 // ── PersonAvatar ────────────────────────────────────────────────────────────
-// Consume DS `Avatar` primitive(2026-04-22 refactor,M1 SSOT consumption)+ 預設 NameCard
-// hoverCard(avatar.spec.md DS-wide「person avatar hover → NameCard」canonical)。
+// Consume DS `Avatar` primitive(2026-04-22 refactor,M1 SSOT consumption)+ 預設 ProfileCard
+// hoverCard(avatar.spec.md DS-wide「person avatar hover → ProfileCard」canonical)。
 //
 // 之前用 local `<img>` / `<User icon />` hand-craft 繞過 DS Avatar,違反 M1。本次 refactor:
 // - 所有 person avatar 經過 DS Avatar primitive(size 對應 uiSize family,fallback / icon / badge 集中管理)
-// - 人員資訊 → NameCard(subtitle = description,actions = NameCardDefaultActions)
+// - 人員資訊 → ProfileCard(subtitle = description,actions = ProfileCardDefaultActions)
 
 // 2026-05-13 (a) perf fix(per codex Layer C HoverCard subtree dominant):
-// useMemo `buildPersonNameCard` per-person stable ref。原 every render call → new JSX ref →
+// useMemo `buildPersonProfileCard` per-person stable ref。原 every render call → new JSX ref →
 // Avatar.memo bails → HoverCard subtree 重建。Stable ref → memo skip → big win on scroll。
 //
-// (c) push-up scroll-defer:當 DataTable virtualizer.isScrolling=true,**完全不 build NameCard**
-// (Avatar 收 undefined → 跳 HoverCard wrapper)。原 (c) v1 在 Avatar 層 skip wrapper 但 NameCard
+// (c) push-up scroll-defer:當 DataTable virtualizer.isScrolling=true,**完全不 build ProfileCard**
+// (Avatar 收 undefined → 跳 HoverCard wrapper)。原 (c) v1 在 Avatar 層 skip wrapper 但 ProfileCard
 // JSX subtree 仍在此處 build → 浪費 React reconciliation work。push 到此處才真省。
 function PersonAvatar({
   person,
   size = 'md',
   className = '',
   style,
+  disabled = false,
 }: {
   person: PersonData
   size?: 'sm' | 'md' | 'lg'
   className?: string
   style?: React.CSSProperties
+  /** disabled field context(2026-07-14 deep-audit 修):抑制 ProfileCard hoverCard(Avatar 收
+   *  undefined → 無 HoverCard wrapper / 無 tabIndex,真不可互動)+ avatar 自身 dim(host-controlled
+   *  opacity — avatar.spec.md「Avatar 在 disabled 元件內 host-controlled opacity」canonical;
+   *  PeoplePicker disabled 分支無 fieldCtx,Avatar self-dim 搆不到,host 補)。
+   *  對齊 people-picker.spec.md「disabled:灰化整個 field,不可互動」。 */
+  disabled?: boolean
 }) {
   const isTableScrolling = useTableIsScrolling()
   const nameCard = React.useMemo(
-    () => (isTableScrolling ? undefined : buildPersonNameCard(person)),
-    [person, isTableScrolling]
+    () => (isTableScrolling || disabled ? undefined : buildPersonProfileCard(person)),
+    [person, isTableScrolling, disabled]
   )
   return (
     <Avatar
       src={person.avatarUrl}
       alt={person.name}
       size={AVATAR_PX[size]}
-      className={className}
+      className={cn(className, disabled && 'opacity-disabled')}
       style={style}
       hoverCard={nameCard}
     />
@@ -134,8 +147,9 @@ function PersonAvatar({
 // outer 改 items-start + Avatar 外包 ItemPrefix primitive consumption。單行視覺 = items-center 等效;
 // 多行(autoRowHeight cell)避免 avatar+name center 整 row 不對齊 first-line text top。M1 消費既有
 // 對齊 TreeView / MenuItem / SelectionItem 共用 ItemPrefix wrap chevron/icon/avatar canonical。
-function PersonDisplay({ value, size = 'md' }: { value?: PersonValue | null; size?: 'sm' | 'md' | 'lg' }) {
-  if (!value) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+function PersonDisplay({ value, size = 'md', disabled = false, onRemove }: { value?: PersonValue | null; size?: 'sm' | 'md' | 'lg'; /** 見 PersonAvatar.disabled jsDoc(抑制 hoverCard + dim) */ disabled?: boolean; onRemove?: () => void }) {
+const emptyDisplay = useFieldEmptyDisplay()
+  if (!value) return <span className="text-foreground">{emptyDisplay}</span>
 
   const person = resolvePerson(value)
 
@@ -146,7 +160,12 @@ function PersonDisplay({ value, size = 'md' }: { value?: PersonValue | null; siz
   // 對齊 GitHub Primer ActionList / Slack users_select / Atlassian UserPicker truncation canonical。
   return (
     <span className="flex items-start gap-2 min-w-0 w-full">
-      <ItemPrefix><PersonAvatar person={person} size={size} /></ItemPrefix>
+      <ItemPrefix>
+        <span className="relative inline-flex group/avatar">
+          <PersonAvatar person={person} size={size} disabled={disabled} />
+          {onRemove && <AvatarDismissOverlay onRemove={onRemove} label={person.name} />}
+        </span>
+      </ItemPrefix>
       <span className="truncate flex-1 min-w-0">{person.name}</span>
     </span>
   )
@@ -164,6 +183,7 @@ function MultiPersonDisplay({
   max,
   measured = false,
   onRemove,
+  disabled = false,
 }: {
   value?: PersonValue[] | null
   size?: 'sm' | 'md' | 'lg'
@@ -171,25 +191,28 @@ function MultiPersonDisplay({
   max?: number
   /**
    * 2026-05-15 codex Round 5 C+ SSOT fix:`measured=true` 啟動 container-width 量測(取代 hardcode `max ?? 3`)
-   * → display + edit stack 同 algorithm(同 cell width → 同 overflow 判斷),不再 display 用固定 3 vs edit
+   * → view + edit stack 同 algorithm(同 cell width → 同 overflow 判斷),不再 view 用固定 3 vs edit
    * 用 useOverflowCount。對齊 field-controls.spec.md:286 「4-mode 共享 renderer」contract + user round 3
    * verbatim「同空間兩判斷點」SSOT directive。Default false 保 backward compat(non-cell context 仍 max ?? 3)。
    */
   measured?: boolean
   /** 傳入時啟用 dismiss(edit mode),callback 接收被移除的 person */
   onRemove?: (person: PersonValue) => void
+  /** 見 PersonAvatar.disabled jsDoc(抑制全 stack ProfileCard hoverCard + avatar dim) */
+  disabled?: boolean
 }) {
-  if (!value || value.length === 0) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
-
+  const emptyDisplay = useFieldEmptyDisplay()
+  // 2026-07-05 D3 P1 修(React #310 家族):3 hooks 原在 empty early return 之後 — value 非空↔空
+  // 切換時 hook 數 0↔3 變動必 crash(現靠 consumer 三元切換 element type 偶然避開)。hoist 到 return 前。
   // 2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus):消費 shared `avatar-stack-overflow`
   // primitive。原 inline canvas-based formula 是 dual-implementation 違反 user SSOT「同 cell width 同
-  // overflow 判斷」(edit path 用 Combobox useOverflowCount DOM offsetWidth / display path 用 inline
-  // canvas)。**抽 primitive 統一**:display + edit 共用 `getAvatarStackVisibleCount` formula。
+  // overflow 判斷」(edit path 用 Combobox useOverflowCount DOM offsetWidth / view path 用 inline
+  // canvas)。**抽 primitive 統一**:view + edit 共用 `getAvatarStackVisibleCount` formula。
   // SSOT in `./avatar-stack-overflow.ts`,M14 mechanical guard 防 future drift。
   const containerRef = React.useRef<HTMLSpanElement>(null)
   const [measuredCount, setMeasuredCount] = React.useState<number | null>(null)
   React.useLayoutEffect(() => {
-    if (!measured) return
+    if (!measured || !value || value.length === 0) return
     const el = containerRef.current
     if (!el) return
     const calc = () => {
@@ -207,6 +230,8 @@ function MultiPersonDisplay({
     return () => ro.disconnect()
   }, [measured, size, value])
 
+  if (!value || value.length === 0) return <span className="text-foreground">{emptyDisplay}</span>
+
   const resolvedMax = measured && measuredCount !== null ? measuredCount : (max ?? 3)
   const people = value.map(resolvePerson)
   const visible = people.slice(0, resolvedMax)
@@ -215,7 +240,7 @@ function MultiPersonDisplay({
 
   // 單人回退到 PersonDisplay(顯示名字)
   if (people.length === 1) {
-    return <PersonDisplay value={value[0]} size={size} />
+    return <PersonDisplay value={value[0]} size={size} disabled={disabled} onRemove={onRemove ? () => onRemove(value[0]) : undefined} />
   }
 
   // 2026-05-14 item-anatomy SSOT fix(per codex+Layer A 共識):outer items-start + avatar stack
@@ -235,6 +260,7 @@ function MultiPersonDisplay({
               person={person}
               size={size}
               className="ring-2 ring-[var(--surface)]"
+              disabled={disabled}
             />
             {handleDismiss && <AvatarDismissOverlay onRemove={handleDismiss} label={person.name} />}
           </span>
@@ -253,17 +279,18 @@ function MultiPersonDisplay({
               size="sm"
               // Tag.avatar 是 ReactNode(非 AvatarData object)——傳 <Avatar> 元素。
               // Tag 內部用 `w-4 h-4 rounded-full` 容器 slot,Avatar 填滿 object-cover。
-              // **hoverCard 必帶**(avatar.spec.md DS-wide canonical:所有 person avatar 必 hover → NameCard)。
-              // 跟 PersonAvatar 共用 `buildPersonNameCard` helper 確保顯示資訊一致。
+              // **hoverCard 必帶**(avatar.spec.md DS-wide canonical:所有 person avatar 必 hover → ProfileCard)。
+              // 跟 PersonAvatar 共用 `buildPersonProfileCard` helper 確保顯示資訊一致。
               avatar={
                 <Avatar
                   src={person.avatarUrl}
                   alt={person.name}
                   size={16}
-                  hoverCard={buildPersonNameCard(person)}
+                  // disabled field:同 PersonAvatar — 抑制 ProfileCard hoverCard(不可互動)
+                  hoverCard={disabled ? undefined : buildPersonProfileCard(person)}
                 />
               }
-              onDismiss={onRemove ? () => onRemove(value![resolvedMax + i]) : undefined}
+              onRemove={onRemove ? () => onRemove(value![resolvedMax + i]) : undefined}
             >
               {person.name}
             </Tag>
@@ -283,11 +310,12 @@ MultiPersonDisplay.displayName = 'MultiPersonDisplay'
 //   - **12×12 圓**(固定,不隨 field size 變)
 //   - **bg `--surface-strong`**(neutral-6),hover → `--surface-strong-hover`
 //     (light=neutral-5 / dark=neutral-7,跨 mode 對稱)
-//   - **X icon size=12 strokeWidth=3.5**(icon 跟底色一樣大,對齊 checkbox checkmark
-//     sm/md stroke 規格)
+//   - **X icon size=12 strokeWidth=3**(icon 跟底色一樣大,對齊 checkbox checkmark
+//     sm/md stroke 規格;2026-06-12 同步 checkbox 2026-05-18 簡化 3.5→3,SSOT →
+//     packages/design-system/ds-canonical/references/ui-dev-rules.md「小尺寸 icon stroke 補償」)
 //   - **text-on-emphasis**(白 X,確保飽和色底對比)
-//   - **位置 `absolute top-0 right-0`**(button 右上角貼齊 avatar 右上角,完全在 avatar
-//     內 — user-confirmed canonical)
+//   - **位置 `absolute -top-px -right-1`**(top -1px / right -4px,右緣凸出 avatar 外 4px —
+//     v15.15 user-confirmed asymmetric canonical,rationale 見下方 className 內註解)
 //
 // **a11y**(codex P1 fix):`opacity-0` 而非 `display:none` — element 在 DOM/tab-order,
 // keyboard tab 可達,觸控 focus-within 也顯。Hover / focus-within / focus-visible
@@ -300,6 +328,7 @@ function AvatarDismissOverlay({ onRemove, label }: { onRemove: () => void; label
     <button
       type="button"
       onClick={(e) => { e.stopPropagation(); onRemove() }}
+      data-collection-remove
       aria-label={`移除 ${label}`}
       className={[
         // **Position(2026-05-07 v15.15 user-confirmed)**:asymmetric `-top-px -right-1`
@@ -319,12 +348,19 @@ function AvatarDismissOverlay({ onRemove, label }: { onRemove: () => void; label
         'bg-surface-strong text-on-emphasis hover:bg-surface-strong-hover',
         // a11y(codex P1 fix):opacity 而非 display:none — element 在 DOM/tab-order,
         // keyboard 可達。Hover / focus-within / focus-visible 三條件之一觸發。
+        // **此行是移除鈕可見性的唯一 gating,刪掉 = 全部恆顯**(2026-08-05 anchor:撤 A 案時
+        // 連同本行一起刪除,造成桌機 stack 所有 avatar 的 X 無條件顯示;mechanical guard
+        // 見 scripts/test-hover-revealed-affordances.mjs)。
         'opacity-0 group-hover/avatar:opacity-100 group-focus-within/avatar:opacity-100 focus-visible:opacity-100',
-        'transition-opacity duration-150',
+        // **不加 touch 恆顯**(2026-08-05 user 否決前一版 A 案:「一般狀態直接把所有成員 avatar
+        // 的 X 都秀出來,這樣看起來超亂」)。觸控的多人移除改由 PeoplePicker 自動降階為既有
+        // pill 型態(Combobox tag SSOT,每顆 pill 自帶 X)承擔 — 見 people-picker.spec.md
+        // 「觸控裝置(native 分支)」。本 overlay 維持 hover / focus 才顯的桌機語意。
+        'transition-opacity duration-150 motion-reduce:duration-0',
         'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
       ].join(' ')}
     >
-      <X size={12} strokeWidth={3.5} aria-hidden />
+      <X size={12} strokeWidth={3} aria-hidden />
     </button>
   )
 }
@@ -355,4 +391,4 @@ function PersonAvatarTag({
 }
 PersonAvatarTag.displayName = 'PersonAvatarTag'
 
-export { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonNameCard, resolvePerson }
+export { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonProfileCard, resolvePerson }

package/src/components/Popover/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './popover'

package/src/components/Popover/popover.anatomy.stories.tsx

@@ -0,0 +1,282 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import { Popover, PopoverTrigger, PopoverContent, PopoverHeader, PopoverBody, PopoverFooter, PopoverTitle } from './popover'
+import { Button } from '@/design-system/components/Button/button'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { CheckboxGroup } from '@/design-system/components/Checkbox/checkbox-group'
+import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/Popover/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Popover 是點擊觸發的浮層容器,提供定位 / 動畫 / 焦點管理 / click-outside 關閉。內容完全由 consumer 決定(可放任何 React 元素)。本 DS 在 Radix Popover 上橋接 elevation / radius / border token,並覆寫兩處 a11y 行為(非全等 Radix,詳「A11y 預設」段 DS 覆寫):開啟焦點落在 body 首個互動元素(而非 Radix 預設 close X)、以及自動接線 aria-labelledby(有 PopoverTitle 時)。</Desc>
+        <div className="flex items-center gap-4">
+          <Popover>
+            <PopoverTrigger asChild>
+              <Button variant="tertiary">篩選設定</Button>
+            </PopoverTrigger>
+            <PopoverContent>
+              <PopoverHeader><PopoverTitle>依類型篩選</PopoverTitle></PopoverHeader>
+              <PopoverBody>
+                <CheckboxGroup>
+                  <Checkbox defaultChecked label="待處理" />
+                  <Checkbox defaultChecked label="進行中" />
+                  <Checkbox label="已完成" />
+                </CheckboxGroup>
+              </PopoverBody>
+              <PopoverFooter>
+                <Button variant="tertiary" size="sm" className="flex-1">清除</Button>
+                <Button variant="primary" size="sm" className="flex-1">套用</Button>
+              </PopoverFooter>
+            </PopoverContent>
+          </Popover>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <Desc>Popover / PopoverTrigger / PopoverContent 沿用 Radix Popover 的同名 prop（定位 / 開關 / modal 等 props 與 Radix 一致），並接上設計系統 token。唯一例外:PopoverContent 覆寫兩處 a11y 行為(`onOpenAutoFocus` 讓開啟焦點落 body 首個互動元素、自動接線 `aria-labelledby`),故行為非全等 Radix，詳「A11y 預設」段。Props 依宣告元件分兩類——定位類(align / side / sideOffset / collisionPadding)寫在 {'<PopoverContent>'} 上,開關 / modal 類(open / onOpenChange / defaultOpen / modal)寫在最外層 {'<Popover>'}(Root)上;寫錯元件不會生效(見「所屬元件」欄)。完整 API 見 <a href="https://www.radix-ui.com/primitives/docs/components/popover" className="underline" target="_blank" rel="noreferrer">Radix Popover 官方文件</a>。</Desc>
+        <div className="overflow-x-auto">
+          {/* @anatomy-exempt-next: Props 速查表為純文件對照(prop/type/default),非元件資料展示;DataTable 過重 */}
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>所屬元件</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>align</Td><Td mono>PopoverContent</Td><Td mono>'start' | 'center' | 'end'</Td><Td mono>'center'</Td><Td>相對 trigger 的對齊</Td></tr>
+              <tr><Td mono>side</Td><Td mono>PopoverContent</Td><Td mono>'top' | 'right' | 'bottom' | 'left'</Td><Td mono>'bottom'</Td><Td>浮層出現在 trigger 的哪一側</Td></tr>
+              <tr><Td mono>sideOffset</Td><Td mono>PopoverContent</Td><Td mono>number</Td><Td mono>8 ★default</Td><Td>與 trigger 的距離(px)。DS 設計準則 = 8(對標 Notion / Linear / Figma / Stripe)</Td></tr>
+              <tr><Td mono>collisionPadding</Td><Td mono>PopoverContent</Td><Td mono>number</Td><Td mono>8 ★default</Td><Td>浮層與 viewport 邊緣的最小間距(px)。DS 設計準則 = 8</Td></tr>
+              <tr><Td mono>open / onOpenChange</Td><Td mono>Popover(Root)</Td><Td mono>{'boolean / (o) => void'}</Td><Td mono>—</Td><Td>controlled 開關(選用)</Td></tr>
+              <tr><Td mono>defaultOpen</Td><Td mono>Popover(Root)</Td><Td mono>boolean</Td><Td mono>false</Td><Td>uncontrolled 初始開啟狀態</Td></tr>
+              <tr><Td mono>modal</Td><Td mono>Popover(Root)</Td><Td mono>boolean</Td><Td mono>false</Td><Td>`true` 時阻斷背景互動 + 鎖 body scroll + focus trap</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Inspector ─────────────────────────────────────────────────────────────
+
+interface InspectorArgs {
+  side: 'top' | 'right' | 'bottom' | 'left'
+  align: 'start' | 'center' | 'end'
+  sideOffset: number
+  width: 'w-72' | 'w-80' | 'w-96'
+  showHeader: boolean
+  showFooter: boolean
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '右側 Controls 切 PopoverContent props 即時 render,取代 Figma inspect。點擊「開啟篩選設定」觸發浮層,切 `side` / `align` 看 12 種定位組合;調 `sideOffset` 看與 trigger 距離。預設 open 以便直接觀察。',
+      },
+    },
+  },
+  args: {
+    side: 'bottom',
+    align: 'center',
+    sideOffset: 8,
+    width: 'w-72',
+    showHeader: true,
+    showFooter: true,
+  },
+  argTypes: {
+    side: {
+      control: 'radio',
+      options: ['top', 'right', 'bottom', 'left'],
+      description: '浮層出現在 trigger 的哪一側(Radix 撞牆自動翻轉)',
+    },
+    align: {
+      control: 'radio',
+      options: ['start', 'center', 'end'],
+      description: '相對 trigger 的對齊',
+    },
+    sideOffset: {
+      control: { type: 'range', min: 0, max: 24, step: 2 },
+      description: 'DS 設計準則 = 8(對標 Notion / Linear / Figma / Stripe)',
+    },
+    width: {
+      control: 'radio',
+      options: ['w-72', 'w-80', 'w-96'],
+      description: 'w-72★default(簡短設定)/ w-96(內容複雜)',
+    },
+    showHeader: { control: 'boolean', description: '顯示 PopoverHeader(含右上 X 關閉)' },
+    showFooter: { control: 'boolean', description: '顯示 PopoverFooter(含 CTA 按鈕)' },
+  },
+  render: (args) => {
+    const { side, align, sideOffset, width, showHeader, showFooter } = args as InspectorArgs
+    return (
+      <div className="flex items-center justify-center py-20">
+        <Popover defaultOpen>
+          <PopoverTrigger asChild>
+            <Button variant="tertiary">篩選設定</Button>
+          </PopoverTrigger>
+          <PopoverContent side={side} align={align} sideOffset={sideOffset} className={width}>
+            {showHeader && (
+              <PopoverHeader><PopoverTitle>依類型篩選</PopoverTitle></PopoverHeader>
+            )}
+            <PopoverBody>
+              <CheckboxGroup>
+                <Checkbox defaultChecked label="待處理" />
+                <Checkbox defaultChecked label="進行中" />
+                <Checkbox label="已完成" />
+              </CheckboxGroup>
+            </PopoverBody>
+            {showFooter && (
+              <PopoverFooter>
+                <Button variant="tertiary" size="sm" className="flex-1">清除</Button>
+                <Button variant="primary" size="sm" className="flex-1">套用</Button>
+              </PopoverFooter>
+            )}
+          </PopoverContent>
+        </Popover>
+      </div>
+    )
+  },
+}
+
+export const PlacementMatrix: Story = {
+  name: '定位（方向 × 對齊）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Side × Align 組合</H3>
+        <Desc>Radix 自動偵測 viewport 邊緣,撞牆時會自動翻向反向。若要強制固定方向,用 controlled `open` + 手動控制。</Desc>
+        <div className="grid grid-cols-2 gap-4 max-w-2xl">
+          {(['top', 'right', 'bottom', 'left'] as const).flatMap(side =>
+            (['start', 'center', 'end'] as const).map(align => (
+              <div key={`${side}-${align}`} className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
+                {/* side/align 屬定位參數,標在格外 caption(非浮層可見內容);浮層本體用真實使用情境 */}
+                <span className="text-caption font-mono text-fg-muted shrink-0 whitespace-nowrap">{side} / {align}</span>
+                {/* @overlay-open-skip:12-cell 定位矩陣示範 side×align 落點,全部 defaultOpen 會讓 12 個浮層互相重疊;點擊逐格開啟即可觀察定位,開啟態視覺覆蓋於 Inspector(defaultOpen) */}
+                <Popover>
+                  <PopoverTrigger asChild>
+                    <Button variant="tertiary" size="sm">使用說明</Button>
+                  </PopoverTrigger>
+                  {/* naked popover(無 PopoverTitle)→ 自傳 aria-label 讓 role="dialog" 有 accessible name */}
+                  <PopoverContent side={side} align={align} aria-label="使用說明">
+                    <PopoverBody><div className="text-caption text-fg-secondary">拖曳卡片可調整優先順序,變更會即時同步給協作者。</div></PopoverBody>
+                  </PopoverContent>
+                </Popover>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>浮層視覺 token(與 DropdownMenuContent / HoverCardContent 共用)</H3>
+        <Desc>所有 elevation-200 浮層共用同一套 token——改其中一個應該連動其他,不讓三個浮層視覺漂移。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>層</Th><Th>Token</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              <tr><Td>背景</Td><Td><TokenCell token="--surface-raised" display="bg-surface-raised" /></Td><Td>浮層背景(比 surface 高一階)</Td></tr>
+              <tr><Td>邊框</Td><Td><TokenCell token="--border" display="border-border" /></Td><Td>標準邊框</Td></tr>
+              <tr><Td>文字</Td><Td><TokenCell token="--foreground" display="text-foreground" /></Td><Td>主要文字色</Td></tr>
+              <tr><Td>次要文字</Td><Td><TokenCell token="--fg-secondary" display="text-fg-secondary" /></Td><Td>說明 / 次要資訊</Td></tr>
+              <tr><Td>圓角</Td><Td mono>rounded-lg(8px)</Td><Td>對齊 Dialog radius(浮層視覺語言一致)</Td></tr>
+              <tr><Td>陰影</Td><Td mono>--elevation-200</Td><Td>浮層級 elevation(見 `elevation.spec.md`)</Td></tr>
+              <tr><Td>Layout-space</Td><Td mono>data-layout-space="md"</Td><Td>只鎖版面間距(header py-tight 精簡);ui-size 跟 page → 內部控件對齊觸發點(2026-06-15 改,原 data-density master switch)</Td></tr>
+              <tr><Td>Header/Body/Footer padding</Td><Td mono>px-[loose] py-[tight]</Td><Td>結構化 sub-components 採 Dialog 同一套 padding token</Td></tr>
+              <tr><Td>Portal z-index</Td><Td mono>z-50</Td><Td>Radix Portal 統一層級,避開一般頁面內容</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>預設 w-72(18rem)</H3>
+        <Desc>Popover content 預設寬度 `w-72`——對應多數「簡短設定面板」情境。內容複雜時 consumer 傳 `className="w-96"` 或更寬覆寫。</Desc>
+        <div className="flex flex-col gap-3 max-w-md">
+          <div className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
+            <span className="text-caption font-mono w-20">w-72(預設)</span>
+            <Popover><PopoverTrigger asChild><Button variant="tertiary" size="sm">開啟</Button></PopoverTrigger>
+              <PopoverContent aria-label="預設寬度示範"><PopoverBody><div className="text-caption">預設寬度 w-72</div></PopoverBody></PopoverContent>
+            </Popover>
+          </div>
+          <div className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
+            <span className="text-caption font-mono w-20">w-96</span>
+            <Popover><PopoverTrigger asChild><Button variant="tertiary" size="sm">開啟</Button></PopoverTrigger>
+              <PopoverContent className="w-96" aria-label="自訂寬度示範"><PopoverBody><div className="text-caption">自訂 w-96</div></PopoverBody></PopoverContent>
+            </Popover>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>sideOffset(與 trigger 的距離)</H3>
+        <Desc>DS 設計準則 = 8px(對標 Notion / Linear / Figma / Stripe)。&lt; 4px 會讓浮層貼死 trigger 失去「另一層」感;&gt; 12px 會拉斷 trigger ↔ content 的視覺關聯。consumer 通常不需改,特殊情境(如 anchored tooltip-like)可傳覆蓋。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>開啟 / 關閉</H3>
+        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動(popover.tsx L105-106):進場 `fade-in + zoom-in-95 + slide-from-side`,離場 `fade-out + zoom-out`(無 slide-out,對齊 shadcn 慣例)。進場方向 side-aware slide,浮層看起來從 trigger 「長出來」。</Desc>
+        <ul className="text-caption text-fg-muted list-disc pl-5 space-y-1">
+          <li>點擊 trigger → 開啟</li>
+          <li>點 Popover 外部 → 關閉(click outside)</li>
+          <li>按 Esc → 關閉</li>
+          <li>焦點離開 trigger-content 樹 → 關閉(focus outside,Radix `DismissableLayer` 控制)</li>
+        </ul>
+      </div>
+
+      <div>
+        <H3>Modal vs Non-modal</H3>
+        <Desc>預設 non-modal:不鎖 body scroll,使用者可和 popover 外部互動(例:篩選 popover 開著,使用者仍可 scroll 列表看結果)。`modal={true}` 改為 modal 行為——適合「確認後才能繼續」的場景(但通常這種情境應改用 Dialog)。</Desc>
+      </div>
+
+      <div>
+        <H3>Disabled / loading / empty / error 的職責邊界</H3>
+        <Desc>{'Popover 是容器,本身無這些狀態——內容層負責。trigger 的 disabled 由 trigger 元件自己管(`<Button disabled>`);內容的 loading / empty / error 由 consumer 在 `PopoverContent` 內部渲染對應 primitive(Skeleton / Empty / Alert)。'}</Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"焦點 / 鍵盤 / ARIA 行為（部分為 DS 覆寫,部分為 Radix 內建）：\n\n-   開啟焦點（DS 覆寫）  ：DS 以  onOpenAutoFocus  覆寫 Radix 預設,開啟時把焦點落在 body 第一個可互動元素（避免 Radix 預設先 focus 右上 close X,觸發 tooltip leak）\n-   關閉返回（Radix 內建）  ：關閉時 focus return to trigger\n-   Esc 關閉（Radix 內建）  ：按 Esc 自動關閉並返回焦點\n-   Focus trap（Radix 內建,僅 modal）  ： modal={true}  時焦點鎖在 content 內\n-   點外 / 焦點離開即關（Radix 內建,non-modal）  ：預設 non-modal 不鎖焦點,焦點或指標離開 content 樹即自動關閉（dismiss,非 focus trap）\n-   ARIA（Radix 內建）  ：trigger 自動  aria-expanded  /  aria-controls ，content  role=\"dialog\" \n-   Accessible name（DS 覆寫）  ：content  role=\"dialog\"  預設無 accessible name， PopoverTitle  掛載時自動接上 content 的  aria-labelledby （consumer 自傳 aria-label / aria-labelledby 優先）\n\n保留 Radix  data-state  屬性即可；無  PopoverTitle  的 naked popover 需 consumer 自傳  aria-label ，否則 role=\"dialog\" 無 accessible name。"}</p>
+    </div>
+  ),
+}