@qijenchen/design-system 0.1.0-beta.14 → 0.1.0-beta.142

package/src/components/Popover/popover.spec.md

@@ -12,8 +12,6 @@ benchmark:
   - Ant Design Popover: github.com/ant-design/ant-design/tree/master/components/popover
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Popover 設計原則
 
 ## 定位
@@ -24,16 +22,16 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
-**視覺對齊 Dialog**：外殼 token 與 Dialog 完全一致（`bg-surface-raised` / `border-border` / `rounded-lg` / `elevation-200`）。差別僅兩點：(1) Popover 是 non-modal 輕量浮層不阻斷背景，(2) **density 永遠鎖 `md`** — Popover 不隨頁面 density 放大（lightweight 浮層保持緊湊）。
+**視覺對齊 Dialog**：外殼 token 與 Dialog 完全一致（`bg-surface-raised` / `border-border` / `rounded-lg` / `elevation-200`）。差別僅兩點：(1) Popover 是 non-modal 輕量浮層不阻斷背景，(2) **layout-space 鎖 `md`** — header / footer padding 不隨頁面放大（輕量 chrome 保持精簡）；**ui-size 不鎖、繼承 page** — 內部控件隨 page 放大、對齊觸發點（2026-06-15 改,原 `data-density` master switch,見 `popover.tsx` docblock）。
 
-**Content size canonical（2026-04-29）**:density lock md → **fields(Input / Select / Checkbox)預設 `size="md"`**(field-height-md 32px,對齊 density)。其餘細節走 SSOT pointer:
+**Content size canonical（2026-04-29,2026-06-15 更新）**:ui-size 繼承 page → **fields(Input / Select / Checkbox)預設隨 page ui-size**(md page = `size="md"` field-height-md 32px;lg page 放大,與觸發點一致)。其餘細節走 SSOT pointer:
 - Chrome corner buttons(close X / refresh / dismiss)→ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(sm native + v5 trick)
 - Row inline action(panel list row 內 Eye / drag / suffix toggle)→ `patterns/element-anatomy/inline-action.spec.md`「尺寸對照」table(md = 16+18 hover bg)
 - Footer action button → `action-bar.spec.md`(輕量 chrome,sm canonical)
 
-**觸發距離 canonical**：`sideOffset = 8`（px）—— trigger 到 Popover 邊緣的垂直/水平間距。8px 是世界級浮層 idiom（Notion / Linear / Figma / Stripe 皆約 6-8px）;< 4px 會讓浮層貼死 trigger 失去「另一層」感,> 12px 會拉斷 trigger ↔ content 的視覺關聯。Radix/shadcn 預設 4px 太緊,本 DS 改為 8 對齊 overlay primitive 的呼吸感。Dialog 不適用(居中或 full-screen)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**觸發距離 canonical**：`sideOffset = 8`（px）—— trigger 到 Popover 邊緣的垂直/水平間距。小於 4px 會讓浮層貼死 trigger 失去「另一層」感，大於 12px 會拉斷 trigger ↔ content 的視覺關聯。本 DS 固定 8px 作為 overlay primitive 的共用呼吸距離；Dialog 居中或 full-screen，不適用此規則。
 
-**Viewport 邊距 canonical**:`collisionPadding = 8`(px)——浮層與 viewport 邊緣的最小間距。當 popover 原本要貼近 viewport 邊(trigger 在頁面最右側、或視窗很窄),Radix 會自動推開 8px 讓浮層不貼死邊界。世界級對照:macOS / iOS / Notion / Figma 的 overflow 選單永遠留視覺呼吸距。`sideOffset` 管 trigger↔popover,`collisionPadding` 管 popover↔viewport,兩者互補。Consumer 不需傳 — 預設值是 canonical。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Viewport 邊距 canonical**:`collisionPadding = 8`(px)——浮層與 viewport 邊緣的最小間距。當 popover 原本要貼近 viewport 邊(trigger 在頁面最右側、或視窗很窄)，定位 primitive 會自動推開 8px，防止內容與螢幕邊界相黏。`sideOffset` 管 trigger↔popover，`collisionPadding` 管 popover↔viewport，兩者互補。Consumer 不需傳 — 預設值是 canonical。
 
 **Align 對齊 canonical(跨浮層 SSOT)**:`align` 必須跟隨 trigger 在容器中的位置,**不是自由選擇**:
 
@@ -43,7 +41,7 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 | **置中**(toolbar 中央、modal 內置中按鈕) | `"center"`(default)| Popover 與 trigger 中心對齊 |
 | **右側 / 右上**(page header right、設定按鈕、overflow menu) | `"end"` | Popover 與 trigger 右邊緣對齊,向左展開 |
 
-**為什麼**:Popover 通常比 trigger 寬。align 錯方向會 (1)溢出容器邊緣 / 被 viewport 裁切、(2)視覺上 popover「沒黏在 trigger 那一側」產生 disconnect,使用者以為兩者無關。世界級對照:Figma / Notion / Linear / Stripe / Material / Ant Design 一律遵循(trigger 靠哪邊、浮層跟著靠哪邊)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**為什麼**:Popover 通常比 trigger 寬。align 錯方向會 (1)溢出容器邊緣 / 被 viewport 裁切、(2)視覺上 popover「沒黏在 trigger 那一側」產生 disconnect，使用者以為兩者無關。因此 trigger 靠哪邊，浮層就跟著靠哪邊。
 
 **SSOT 適用範圍(2026-04-20 精緻化)**:本規則是**「結構化浮層」的 canonical** —— Popover / DropdownMenu / Coachmark / SelectMenu 嚴格遵守(這些浮層寬度通常比 trigger 寬、且有結構化內容,錯方向必視覺 disconnect)。
 
@@ -54,7 +52,7 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 其他結構化浮層 spec 若討論 align 應 pointer 指回本節。
 
 **結構化組合（可選）**：PopoverContent 外殼無內距，consumer 可選擇：
-- **單一 body**：包 `<PopoverBody>` 取得 Dialog body 同 padding (`px-loose py-tight`)
+- **單一 body**：包 `<PopoverBody>` 取得 SurfaceBody canonical padding (`px-loose py-tight`,`overlay-surface.spec.md` SSOT;Dialog body 另有 `pb-[--layout-space-bottom]` 特化)
 - **含標題**：組合 `<PopoverHeader>` + `<PopoverBody>`（下分隔線由 Header 提供）
 - **含操作按鈕列**：再加 `<PopoverFooter>`（上分隔線由 Footer 提供）
 
@@ -62,15 +60,15 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 
 > **跨家族 SSOT pointer**:PopoverHeader 屬 **Padding-based overlay header 家族**;border / padding / dismiss size / withTabs(tabs 進 PopoverHeader 時 border auto-suppress + tabs size sm)的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Popover 特有 close X v5 unbounded canonical。
 
-**Close X 按鈕(2026-04-22 v5 unbounded canonical)**:所有 `PopoverHeader` 內建右上 X 按鈕,`<Button data-dismiss iconOnly dismiss size="sm" />` native sm(28 md / 32 lg)。透過 SurfaceHeader 的 v5 CSS rule 自動套負 margin 讓 layout 佔位 = 24(chrome-header-height 幾何)。`hideClose` prop 可讓 composition 元件(如 Coachmark)選擇隱藏。詳 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+**Close X 按鈕(2026-04-22 v5 unbounded canonical)**:所有 `PopoverHeader` 內建右上 X 按鈕,`<Button data-dismiss iconOnly dismiss size="sm" />` native sm(28 md / 32 lg)。透過 SurfaceHeader 的 v5 CSS rule 自動套負 margin 讓 layout 佔位;PopoverHeader 走 `COMPACT_HEADER_SLOT`(= calc(--font-body-size×1.5) = 21 = title line-box,衍生)→ 佔位 21(輕量 chrome,見 `popover.tsx` docblock),非 Dialog 的 24。`hideClose` prop 可讓 composition 元件(如 Coachmark)選擇隱藏。詳 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
 
-**Header / Footer 高度 canonical**:padding-based(繼承 SurfaceHeader / SurfaceFooter),高度 = max(child layout) + 2×tight。unbounded 透過 v5 trick layout 佔位 24 → header 48 / footer 48(若只有 unbounded)或自然長(若有 bounded)。詳 `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」。
+**Header / Footer 高度 canonical**:padding-based(繼承 SurfaceHeader / SurfaceFooter),高度 = max(child layout) + 2×tight。header:slot 佔位 21(`COMPACT_HEADER_SLOT` = title line-box,衍生)→ max(21 title, 21 slot) + 2×12 = **45**,自然比 Dialog / Sheet 48 輕一級(`popover.tsx` PopoverHeader docblock + overlay-surface.tsx 對照);footer:SurfaceFooter **不**套 unbounded slot trick(僅 padding + `border-t`,見 `overlay-surface.spec.md`「為什麼 SurfaceHeader 是 padding-based」)→ 高度 = max(child layout) + 2×tight(sm action button 28 → **52** md)。詳 `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」。
 
 ---
 
 ## Title typography canonical(non-modal 特化,2026-04-22 v4)
 
-**PopoverTitle 用 `text-body font-medium`(14px),不是 Dialog / Sheet 的 `text-body-lg`(16px)**。這是針對 **non-modal 輕量浮層** 的視覺考量,跟 density 鎖 md 同源的輕量 rationale。
+**PopoverTitle 用 `text-body font-medium`(14px),不是 Dialog / Sheet 的 `text-body-lg`(16px)**。這是針對 **non-modal 輕量浮層** 的視覺考量,跟 layout-space 鎖 md 同源的輕量 rationale。
 
 **重量分級(world-class 共通 pattern)**:
 
@@ -92,7 +90,7 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 
 **共通原則**:non-modal overlay 的 title 比 modal 小一級。我方採 16 → 14 分級,在 world-class 範圍內。
 
-**Coachmark 的 PopoverTitle 消費**:Coachmark 的 header 小標籤(如 "新功能介紹" / "Tip 1 of 3")繼承 PopoverTitle 14px。Coachmark **body 內容的主 title**(長敘述型 "建立你的第一個 Workspace")另走 `text-body-lg`(見 `coachmark.tsx:L178`)— 那是 body content 不是 chrome title,分離 concerns。
+**Coachmark 的 PopoverTitle 消費**:Coachmark 的 header 小標籤(如 "新功能介紹" / "Tip 1 of 3")繼承 PopoverTitle 14px。Coachmark **body 內容的主 title**(長敘述型 "建立你的第一個 Workspace")另走 `text-body-lg`(見 `coachmark.tsx` CoachmarkBody 主 title `<h3>`)— 那是 body content 不是 chrome title,分離 concerns。
 
 **禁止**:consumer 自己在 PopoverContent 裡手刻 `<h2 className="text-body-lg">` 當 title(繞 PopoverTitle 的 canonical)。若需要大 title,視為該用 Dialog 而非 Popover(選對元件)。
 
@@ -132,10 +130,12 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 
 ### 合法但少見:Popover 內含可選 item 列 + footer save CTA
 
-Popover 可以在 body 放 checkbox / radio 列表 / 可選 chip / 可選 menu-item-like elements,**但必在 footer 有 CTA 按鈕(套用 / 儲存 / 完成)觸發狀態提交**。這個 pattern 跟 DropdownMenu 的差別是:**DropdownMenu 一 click 即觸發動作,Popover 這類是「暫存選擇 → 按 CTA 才 commit」**。典型情境:
+Popover 可以在 body 放可選 item 列,**但必在 footer 有 CTA 按鈕(套用 / 儲存 / 完成)觸發狀態提交**。這個 pattern 跟 DropdownMenu 的差別是:**DropdownMenu 一 click 即觸發動作,Popover 這類是「暫存選擇 → 按 CTA 才 commit」**。
+
+**body 是一份可選清單時,列走選單列**(`patterns/overlay-surface/overlay-surface.spec.md`「預設:浮層的 body 是一份可選清單 → 走選單列」):body 撤 chrome padding、`Command`(cmdk)包住提供鍵盤與 listbox 結構、item 自帶 `px-loose` 對齊 header 標題。**不要用 `CheckboxGroup` + 裸 `Checkbox` 自組** —— 那是表單欄位的組合方式,不是選項清單。典型情境:
 
-- **多選 filter panel**:checkbox 列表 + 底部 `清除 / 套用`(見 `FilterPanel` story)
-- **Bulk edit**:選多個 menu-item-like options + 底部 `儲存變更`
+- **多選 filter panel**:勾選列 + 底部 `清除 / 套用`(canonical = `FilterPanel` story 的 `StatusFilterPanel`)
+- **Bulk edit**:選多個 options + 底部 `儲存變更`
 - **Custom toolbar 設定**:可選 toggle 列 + 底部 `套用偏好`
 
 canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是 → DropdownMenu;否(要按 footer CTA 才 commit)→ Popover。
@@ -150,26 +150,39 @@ canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是
 
 ---
 
+## 邊界案例
+
+- **極長內容**:PopoverContent 設 `max-h-[var(--radix-popover-content-available-height)]`(popover.tsx:103),body 包 `<PopoverBody>`(SurfaceBody `flex-1 min-h-0 overflow-y-auto`)→ viewport 太小時 header / footer 留在視窗內、body 內捲。中間 wrapper 必 forward flex chain,詳 `../../patterns/overlay-surface/overlay-surface.spec.md`「Viewport-aware scroll chain invariant」。
+- **Viewport 邊緣**:`collisionPadding = 8` 自動推開(見「Viewport 邊距 canonical」)。
+- **嵌套 Popover**:禁止(見「禁止事項」)。
+- **Dark mode**:殼走 semantic token 自動 adapt(見 `color.spec.md`)。
+- **Density**:layout-space 鎖 `md`(header / footer padding 精簡);ui-size 繼承 page(見「定位」段)。
+- **空內容 / loading / error / validation ownership**:Popover shell **不擁有**這些狀態——由 `PopoverBody` 內的 consumer 內容層負責:空狀態放 `<Empty>`、載入放 `<Skeleton>`、錯誤放 `<Alert>`、表單驗證放 `<Field>` 的 `FieldError`。structural pattern 的職責邊界 SSOT 見 `../../patterns/overlay-surface/overlay-surface.spec.md` SurfaceBody「邊界」段(loading / error / empty 屬 consumer 內容層)。
+- **disabled ownership**:Popover 容器無 disabled 態;trigger 的 disabled 由 trigger 元件自管(`<Button disabled>`),content 內控件各自的 disabled 由該控件負責(對應 `StateBehavior` story「職責邊界」段)。
+
+---
+
 ## A11y 預設
 
-Radix Popover 自動處理：
+焦點 / 鍵盤 / ARIA 行為分兩層——**DS 覆寫**(改 Radix 預設)與 **Radix 內建**(沿用)：
 
-- **焦點管理**：開啟時移動焦點進入 content；關閉時 focus return to trigger
-- **Esc 關閉**：按 Esc 自動關閉並返回焦點
-- **Focus trap**：`modal={true}` 時焦點鎖在 content 內；預設 non-modal 下焦點離開 content 樹會自動關閉
-- **ARIA**：trigger 自動 `aria-expanded` / `aria-controls`，content `role="dialog"`
+- **開啟焦點(DS 覆寫)**：DS 以 `onOpenAutoFocus` 覆寫底層 primitive 的預設 autofocus(見 `popover.tsx` `handlePopoverOpenAutoFocus`),開啟時把焦點落在 body 第一個**表單控件**(`input` / `textarea` / `select` / `button`,排除右上 close X);查無表單控件時退回 footer 按鈕,再無則落在 content 容器(`role="dialog"`)本身。原預設會先 focus 右上 close X,DS 覆寫以避免觸發 tooltip leak，selector 與 `dialog.tsx handleOpenAutoFocus` 共用同一套 DS canonical。**注意**:(1) 若移除此 default handler,行為會回退成底層預設 focus close X;(2) selector 只認表單控件——body 若只含 `a[href]` / `[tabindex]` / `contenteditable` 類可聚焦內容,焦點會落在 content 容器而非該內容,consumer 需自傳 `onOpenAutoFocus` 指定要聚焦的元素。
+- **關閉返回(Radix 內建)**：關閉時 focus return to trigger
+- **Esc 關閉(Radix 內建)**：按 Esc 自動關閉並返回焦點
+- **Focus trap(Radix 內建,僅 modal)**：`modal={true}` 時焦點鎖在 content 內
+- **點外 / 焦點離開即關(Radix 內建,non-modal)**：預設 non-modal **不鎖焦點**(無 focus trap),焦點或指標離開 content 樹時由 DismissableLayer 觸發 dismiss 自動關閉——這是 dismiss-on-focus-out 機制,**不是** focus trap
+- **ARIA(Radix 內建)**：trigger 自動 `aria-expanded` / `aria-controls`，content `role="dialog"`
+- **Accessible name(DS 覆寫)**:Radix Popover 沒有 Radix Dialog Title 式的自動接線,content `role="dialog"` 預設**無 accessible name**。DS 以 context 補同機制(見 `popover.tsx` `PopoverTitleContext`):`<PopoverTitle>` 掛載時自動把 id 接上 content 的 `aria-labelledby`;consumer 自傳 `aria-label` / `aria-labelledby` 一律優先
 
-Consumer 無需額外處理 a11y，保留 Radix `data-state` 屬性即可。
+焦點與 accessible name 的 DS 覆寫 default 已 wire 在 `PopoverContent`(consumer 可傳自己的 `onOpenAutoFocus` override),保留 Radix `data-state` 屬性即可。**無 `<PopoverTitle>` 的 naked popover 需 consumer 自傳 `aria-label`**,否則 `role="dialog"` 無 accessible name。
 
 ---
 
-## 為何無 Inspector
+## Inspector
 
-Popover 是**浮層容器 primitive**——關鍵決策是 `side` × `align` × `sideOffset`,以及內部 Header / Body / Footer 結構。`PlacementMatrix` 是完整的 side × align 12-cell 矩陣,比互動 Inspector(切單一 side/align)更能呈現所有定位組合。Header / Body / Footer padding 屬 `overlay-surface` SSOT,已由 `ColorMatrix` 的 token 表 + 該 pattern spec 覆蓋。
+`Inspector` 提供互動 Controls 即時切換 PopoverContent 六個關鍵維度:`side` / `align`(12 種定位組合)、`sideOffset`(與 trigger 距離)、`width`(w-72 / w-80 / w-96)、`showHeader` / `showFooter`(chrome 結構開關)。內容區由 consumer 決定,Inspector 聚焦容器層級的可試玩 prop(對齊 `sheet.spec.md`「Inspector」canonical)。`PlacementMatrix` 另以靜態 12-cell side × align 矩陣一眼呈現所有定位組合;Header / Body / Footer padding 屬 `overlay-surface` SSOT,由 `ColorMatrix` 的 token 表 + 該 pattern spec 覆蓋。
 
-Popover 內容完全由 consumer 決定,無自己的 variant/size/disabled 等可試玩 prop——Inspector 對 container 類元件價值低。
-
-對應 anatomy story:保留 `Overview` + 元件特有 `PlacementMatrix`(12-cell side × align 矩陣) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`(open / close / animation)。
+對應 anatomy story:保留 `Overview` + `Inspector` + 元件特有 `PlacementMatrix`(12-cell side × align 矩陣) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`(open / close / animation) + `Accessibility`。
 
 ---
 
@@ -188,11 +201,10 @@ Popover 內容完全由 consumer 決定,無自己的 variant/size/disabled 等
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `command.spec.md`
-- `file-viewer.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `density.spec.md`
+- `coachmark.spec.md`
+- `dialog.spec.md`
+- `dropdown-menu.spec.md`
+- `hover-card.spec.md`
+- `overlay-surface.spec.md`
+- `select-menu.spec.md`
+- `tooltip.spec.md`

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

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Filter } from 'lucide-react'
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverBody,
+  PopoverFooter,
+  PopoverTitle,
+} from './popover'
+import * as React from 'react'
+import { Button } from '@/design-system/components/Button/button'
+import { Command, CommandList, CommandGroup, CommandItem } from '@/design-system/components/Command/command'
+
+const meta: Meta = {
+  title: 'Design System/Components/Popover/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: { description: { component: '由 trigger 錨定的輕量浮層，可承載簡短資訊、篩選或小型表單。內容需要保留來源位置且不值得打斷整頁時使用；複雜流程改用 Dialog 或 Sheet。' } },
+  },
+}
+export default meta
+type Story = StoryObj
+
+const STATUS_OPTIONS = ['待處理', '進行中', '已完成', '已封存'] as const
+
+/**
+ * 狀態篩選面板 —— 兩支 story(互動版 / 截圖版)共用同一份內容,避免只改一邊造成漂移。
+ *
+ * body 主體就是一份可選清單 → 走 `overlay-surface.spec.md`「List-as-region in overlay body」:
+ * body 撤掉 chrome padding、`CommandGroup` 自帶 `py-2` 給上下呼吸、item 自帶 `px-loose`。
+ * 容器用 `Command`(cmdk)而不是裸 `MenuItem`:`menu-item.spec.md:246` 要求選單項目待在提供鍵盤
+ * 導覽與 listbox 結構的容器內,`Command` 自帶方向鍵與 `role="listbox"`(`SelectMenu` 內部走同一條路)。
+ * **列的水平內距是唯一要客製的東西**,而且**設在清單容器上、不是設在每一列**:
+ * 列的內距讀 `--item-px`(owner = `item-anatomy.spec.md`「Token: `--item-px`」,預設 `var(--field-px)` 12px);
+ * 這裡在 `Command` 根設一次 `var(--layout-space-loose)`(16px),整份清單(含空狀態 / 載入中訊息列)一起換。
+ *
+ * 目的是讓**列的最前緣**(這裡是勾選框)對齊 header 標題與 footer 按鈕左緣
+ * (`overlay-surface.spec.md:100` 第 2 條 + `:202` footer 同一條對齊線)。**對齊的是前緣不是文字** ——
+ * `item-anatomy.spec.md:423` content 槽的 x 是剩餘空間、`:665`/`:671` 跨群組不強求文字對齊、
+ * `:677` 把「為了讓文字齊左而改前綴尺寸」列為錯誤示範。
+ *
+ * **禁止寫在單列的 `className`**:`CommandItem` 是兩層,外層 cmdk Item 負責「反白底色鋪滿整列」恆為
+ * `p-0`(`command.tsx:326`),內層 `MenuItem` 才帶內距(`:352-366`)。寫在 className 會落在外層與內層相加 ——
+ * 2026-09-17 實測 16+12=28px,標題在 17px、勾選框跑到 29px。機械閘 `scripts/overlay-list-as-region-invariant.mjs`。
+ */
+function StatusFilterPanel({ defaultOpen = false }: { defaultOpen?: boolean }) {
+  // 暫存選擇:勾選只改這裡,按「套用」才 commit(對照 DropdownMenu 的 click 即觸發)。
+  const [staged, setStaged] = React.useState<string[]>(['待處理', '進行中'])
+  const toggle = (value: string) =>
+    setStaged((prev) => (prev.includes(value) ? prev.filter((v) => v !== value) : [...prev, value]))
+  return (
+    <Popover defaultOpen={defaultOpen}>
+      <PopoverTrigger asChild>
+        <Button variant="tertiary" startIcon={Filter}>依狀態篩選</Button>
+      </PopoverTrigger>
+      <PopoverContent align="start">
+        <PopoverHeader>
+          <PopoverTitle>依狀態篩選</PopoverTitle>
+        </PopoverHeader>
+        <PopoverBody className="!px-0 !pt-0 !pb-0">
+          <Command label="狀態選項" style={{ '--item-px': 'var(--layout-space-loose)' } as React.CSSProperties}>
+            <CommandList>
+              <CommandGroup>
+                {STATUS_OPTIONS.map((status) => (
+                  <CommandItem
+                    key={status}
+                    value={status}
+                    checkbox
+                    checked={staged.includes(status)}
+                    onSelect={() => toggle(status)}
+                  >
+                    {status}
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            </CommandList>
+          </Command>
+        </PopoverBody>
+        <PopoverFooter>
+          <Button variant="tertiary" size="sm" className="flex-1" onClick={() => setStaged([])}>清除</Button>
+          <Button variant="primary" size="sm" className="flex-1">套用</Button>
+        </PopoverFooter>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export const FilterPanel: Story = {
+  name: '篩選面板',
+  render: () => <StatusFilterPanel />,
+}
+
+/**
+ * OpenSnapshot — visual-audit 專用 story(非 consumer-facing 教學範例)。
+ *
+ * 用 `defaultOpen` 讓 Popover 在 render 當下就開著,Playwright 截圖才抓得到
+ * Popover chrome(Header + X / Body / Footer)。不用 play() + userEvent,是
+ * 因為 Radix `defaultOpen` 對 Portal 自動生效 — 世界級 DS 的 chromatic 稽核
+ * 也走同 pattern。
+ *
+ * 情境沿用 FilterPanel(Jira / Linear 狀態篩選),是 Popover「多選 + footer
+ * save CTA」canonical 的完整示範,涵蓋 Header X、checkbox list、footer 雙
+ * action 整組 chrome。
+ */
+export const OpenSnapshot: Story = {
+  name: '開啟狀態',
+  tags: ['test-only'],
+  render: () => <StatusFilterPanel defaultOpen />,
+}
+
+// SettingsPanel story 於 2026-04-20 移除:
+//   原本是「顯示設定 mini panel (Notion 頁面設定)」— 用 Popover + 多個 horizontal
+//   Field + Switch 展示 settings list。
+//
+//   B13 決策(user 回饋):Notion 頁面設定的實際做法是 `<DropdownMenu>` +
+//   `<DropdownMenuCheckboxItem>` — menu 內 binary toggle 已由 CheckboxItem 覆蓋
+//   (見 `../DropdownMenu/dropdown-menu.stories.tsx` 的 `CheckboxItems` story)。
+//   Popover 的 canonical 是「自由組合 UI 面板」(filter / form / 圖表),純 toggle
+//   列表用 DropdownMenu 語意更準確 + 鍵盤上下導覽更自然。
+//
+//   同一情境兩處 demo = 噪音 + 教壞 consumer,不保留重複範例。Popover 只保留
+//   FilterPanel(多選 checkbox + footer save CTA — Popover canonical)即可。
+
+// BareBody 範例於 2026-04-20 移除:
+//   原 demo 是「選擇優先度」(5 個選項選一個)、在浮層內手刻原生按鈕當作
+//   item 列表 — 這是 `<Select>` / `<DropdownMenu>` 的標準情境,不該走 Popover。
+//
+//   B1 決策(user):menu / select / combobox 早已定義過那種「格式化的選單範例」,
+//   Popover 不再 demo。Popover 的本質是「輕量盡量不干擾使用者心流的 modal」—
+//   結構化 form / filter / settings 等情境才是 canonical。

package/src/components/Popover/popover.tsx

@@ -4,16 +4,18 @@ import * as PopoverPrimitive from "@radix-ui/react-popover"
 import { X as XIcon } from "lucide-react"
 
 import { cn } from "@/lib/utils"
-import { SurfaceHeader, SurfaceBody, SurfaceFooter } from "@/design-system/patterns/overlay-surface/overlay-surface"
+import { SurfaceHeader, SurfaceBody, SurfaceFooter, COMPACT_HEADER_SLOT } from "@/design-system/patterns/overlay-surface/overlay-surface"
+import { TruncatedText } from "@/design-system/patterns/element-anatomy/truncated-text"
 import { Button } from "@/design-system/components/Button/button"
-import { OVERLAY_SIDE_OFFSET, OVERLAY_COLLISION_PADDING } from "@/design-system/tokens/elevation/overlay-geometry"
+import { OVERLAY_SIDE_OFFSET, OVERLAY_COLLISION_PADDING, OVERLAY_HIDE_WHEN_DETACHED } from "@/design-system/tokens/elevation/overlay-geometry"
+import { overlayMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * Popover — Radix Popover + 設計系統 token
  *
  * ── 視覺 ──
  * 與 Dialog 對齊：bg-surface-raised / rounded-lg / border-border / elevation-200。
- * density 永遠鎖 md（non-modal 輕量浮層不隨頁面 density 放大）。
+ * layout-space 鎖 md（輕量浮層 header py-tight 保持精簡）；ui-size 繼承 page（內部控件對齊觸發點，2026-06-15 改，原 data-density master switch）。
  *
  * ── 結構 ──
  * PopoverContent：外殼（bg / border / radius / shadow / density），無內距。
@@ -33,45 +35,88 @@ const PopoverAnchor = PopoverPrimitive.Anchor
 const PopoverClose = PopoverPrimitive.Close
 
 // AutoFocus canonical(對齊 Dialog / Sheet / Material / Polaris)—
-// 開啟時 focus 落在 body 第一個有意義互動元素,避免 focus 到 close X 觸發 tooltip leak
+// 開啟時 focus 落在 body 第一個有意義互動元素,避免 focus 到 close X 觸發 tooltip leak。
+// 兩段查詢對齊 dialog.tsx handleOpenAutoFocus(2026-07-05 修):舊版單一混合清單按 DOM 序取
+// 第一 match,header 內互動元素(非 data-dismiss)會搶走 body 首元素焦點,且 bare 段漏 select。
+// 改為:先 body-scoped 查詢,查無才退 bare 全域清單(保留 naked popover — consumer 不用
+// PopoverBody 自管結構 — 的 fallback 意圖),最後 footer → content 容器。
 const handlePopoverOpenAutoFocus = (e: Event) => {
   e.preventDefault()
   const content = e.currentTarget as HTMLElement
   const firstBodyTarget = content.querySelector<HTMLElement>(
-    '[data-popover-body] input:not([disabled]),[data-popover-body] textarea:not([disabled]),[data-popover-body] select:not([disabled]),[data-popover-body] button:not([disabled]):not([data-dismiss]),input:not([disabled]),textarea:not([disabled]),button:not([disabled]):not([data-dismiss])'
+    '[data-popover-body] input:not([disabled]),[data-popover-body] textarea:not([disabled]),[data-popover-body] select:not([disabled]),[data-popover-body] button:not([disabled]):not([data-dismiss])'
+  )
+  const firstBareTarget = content.querySelector<HTMLElement>(
+    'input:not([disabled]),textarea:not([disabled]),select:not([disabled]),button:not([disabled]):not([data-dismiss])'
   )
   const firstFooterButton = content.querySelector<HTMLElement>(
     '[data-popover-footer] button:not([disabled]):not([data-dismiss])'
   )
-  ;(firstBodyTarget ?? firstFooterButton ?? content).focus({ preventScroll: true })
+  ;(firstBodyTarget ?? firstBareTarget ?? firstFooterButton ?? content).focus({ preventScroll: true })
+}
+
+// ── PopoverTitle → aria-labelledby 自動接線(2026-07-05,照 Radix Dialog Title 機制補 DS 層)──
+// Radix Popover 的 content 有 role="dialog",但沒有 Radix Dialog Title 式的自動 accessible name
+// 接線 → 一般 Popover 預設無 accessible name。DS 層以 context 補同機制:PopoverContent 以 useId
+// 建 titleId 供給 children;PopoverTitle 掛載時註冊,PopoverContent 偵測到有 title 註冊才設
+// aria-labelledby。Consumer 自傳 aria-label / aria-labelledby 一律優先。PopoverTitle 亦被
+// DataTable sort / filter panel 等非 PopoverContent 場景裸用(raw SurfaceHeader chrome)—
+// context 為 null 時全部 no-op,行為與舊版一致。
+interface PopoverTitleContextValue {
+  titleId: string
+  onTitleMount: () => void
+  onTitleUnmount: () => void
 }
 
+const PopoverTitleContext = React.createContext<PopoverTitleContextValue | null>(null)
+
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
->(({ className, align = "center", sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, onOpenAutoFocus, ...props }, ref) => (
-  <PopoverPrimitive.Portal>
-    <PopoverPrimitive.Content
-      ref={ref}
-      align={align}
-      sideOffset={sideOffset}
-      collisionPadding={collisionPadding}
-      data-density="md"
-      onOpenAutoFocus={onOpenAutoFocus ?? handlePopoverOpenAutoFocus}
-      className={cn(
-        "z-50 w-72 rounded-lg border border-border bg-surface-raised text-foreground shadow-[var(--elevation-200)] outline-none",
-        // 2026-05-04 viewport-aware max-h SSOT(從 NameCard 升 DS-wide):header/footer 永遠 in-viewport,body 壓縮 scroll
-        // 2026-05-05 audit dim 35 補:加 `min-h-0` 完成 M25 chain invariant(flex item default min-h: auto 阻 shrink)
-        "max-h-[var(--radix-popover-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
-        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 motion-reduce:animate-none",
-        "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
-        "origin-[var(--radix-popover-content-transform-origin)]",
-        className
-      )}
-      {...props}
-    />
-  </PopoverPrimitive.Portal>
-))
+>(({ className, align = "center", sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, hideWhenDetached = OVERLAY_HIDE_WHEN_DETACHED, onOpenAutoFocus, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }, ref) => {
+  const titleId = React.useId()
+  const [hasTitle, setHasTitle] = React.useState(false)
+  const titleContext = React.useMemo<PopoverTitleContextValue>(
+    () => ({ titleId, onTitleMount: () => setHasTitle(true), onTitleUnmount: () => setHasTitle(false) }),
+    [titleId],
+  )
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverTitleContext.Provider value={titleContext}>
+        <PopoverPrimitive.Content
+          ref={ref}
+          align={align}
+          sideOffset={sideOffset}
+          collisionPadding={collisionPadding}
+          // 錨點失去版面時不畫(同 Tooltip;詳 tokens/elevation/overlay-geometry.ts)
+          hideWhenDetached={hideWhenDetached}
+          // Layout-space lock(2026-06-15 canonical,原 data-density="md" 改為只鎖 layout-space):Popover 是
+          // 輕量浮層,header/footer 用 py-tight(layout-space)→ 鎖 layout-space=md 保持精簡 padding;但
+          // **ui-size 不鎖、繼承 page** → 內部 field 控件 / dismiss 按鈕隨 page 放大,跟觸發點一致(decouple)。
+          // [data-layout-space="md"] 有 reset selector(layoutSpace.css L31)→ lg page 上正確 reset 回 md。
+          data-layout-space="md"
+          onOpenAutoFocus={onOpenAutoFocus ?? handlePopoverOpenAutoFocus}
+          aria-label={ariaLabel}
+          // accessible name 自動接線:consumer 自傳優先;無 aria-label 且有 PopoverTitle 註冊才掛 titleId
+          aria-labelledby={ariaLabelledBy ?? (ariaLabel == null && hasTitle ? titleId : undefined)}
+          className={cn(
+            // @focus-suppress E — E 浮層程式落點;承擔者:浮層開啟時的程式落點;內部控件各自有指示
+            "z-50 w-72 rounded-lg border border-border bg-surface-raised text-foreground shadow-[var(--elevation-200)] outline-none",
+            // 2026-05-04 viewport-aware max-h SSOT(從 ProfileCard 升 DS-wide):header/footer 永遠 in-viewport,body 壓縮 scroll
+            // 2026-05-05 audit dim 35 補:加 `min-h-0` 完成 M25 chain invariant(flex item default min-h: auto 阻 shrink)
+            "max-h-[var(--radix-popover-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
+            overlayMotion,
+            "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+            "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+            "origin-[var(--radix-popover-content-transform-origin)]",
+            className
+          )}
+          {...props}
+        />
+      </PopoverTitleContext.Provider>
+    </PopoverPrimitive.Portal>
+  )
+})
 PopoverContent.displayName = PopoverPrimitive.Content.displayName
 
 // PopoverHeader: SurfaceHeader + Close X(對齊 Dialog 的 canonical,見 docblock)
@@ -86,20 +131,19 @@ interface PopoverHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
 
 const PopoverHeader = React.forwardRef<HTMLDivElement, PopoverHeaderProps>(
   ({ className, children, hideClose = false, ...props }, ref) => (
-    // Popover lightweight chrome canonical(2026-05-04 重思 v2):
-    //   覆寫 `--chrome-slot-h: 1.25rem` (20px) → unbounded button 佔位縮成 20,**匹配 PopoverTitle
-    //   text-body line-height (14×1.5≈21,floor 20)**。Header 維持 padding-based 自然撐開:
-    //   max(21 title, 20 slot) + py-tight(12*2) = 45 → 自然比 Dialog/Sheet 48 輕一級。
-    //   Q10 穩定:title-only / title+close 都 = title + py 主導,slot 不 dominate。
-    //   無 min-h / 無 py override — 修正前一版過度設計。
+    // Popover lightweight chrome canonical(2026-05-04 重思 v2;2026-06-16 slot 改衍生 + 收斂 SSOT):
+    //   走 `COMPACT_HEADER_SLOT`(= calc(--font-body-size×1.5) = 14×1.5 = 21 = PopoverTitle text-body line-box,
+    //   衍生非寫死,取代舊各自寫死的 1.25rem / 20 巧合值)→ slot = title 行高,title 字級改 slot 自動跟。
+    //   Header 維持 padding-based:max(21 title, 21 slot) + py-tight(12*2) = 45 → 自然比 Dialog/Sheet 48 輕一級。
+    //   Q10 穩定:title-only / title+close 都 = title + py 主導(slot=title)。無 min-h / 無 py override。
     <SurfaceHeader
       ref={ref}
-      className={cn("justify-between [--chrome-slot-h:1.25rem]", className)}
+      className={cn("justify-between", COMPACT_HEADER_SLOT, className)}
       {...props}
     >
       <div className="flex-1 min-w-0">{children}</div>
       {!hideClose && (
-        // Dismiss X = native sm,SurfaceHeader 負 my trick 讓 layout 佔位 24 → 匹配 inner 24
+        // Dismiss X = native sm,SurfaceHeader 負 my trick 讓 layout 佔位縮到 slot(21 = title line-box)
         <PopoverPrimitive.Close asChild>
           <Button data-dismiss iconOnly dismiss size="sm" startIcon={XIcon} aria-label="關閉" />
         </PopoverPrimitive.Close>
@@ -131,24 +175,42 @@ PopoverFooter.displayName = "PopoverFooter"
 // PopoverTitle(2026-04-22 v4 non-modal canonical):`text-body font-medium`(14px)
 // Rationale:Popover / Coachmark 屬 **non-modal 輕量浮層**,跟 density 鎖 md 同源的視覺語言 —
 // chrome 全體輕量:
-//   - density 鎖 md(不隨 page 放大)
-//   - dismiss X 透過 v5 unbounded trick layout 佔位 24
+//   - layout-space 鎖 md(ui-size 繼承 page,2026-06-15)
+//   - dismiss X 走 COMPACT_HEADER_SLOT 佔位 21(= title text-body line-box;見 PopoverHeader docblock)
 //   - **title `text-body`(14px)跟 Dialog / Sheet modal 的 body-lg(16px)形成重量級 vs 輕量級視覺區分**
 // 世界級對照:Figma / Notion / Linear / Material 的 popover / filter panel / inline settings
 // 的 header title 多半比 modal dialog title 小一級(16→14 或同比),視覺宣告「此浮層可忽略」
 //
 // Coachmark 同樣消費 PopoverTitle 作 header 小標籤(如 "新功能介紹" / "Tip 1 of 3"),
-// CoachmarkBody 的主 title 另走 text-body-lg(見 coachmark.tsx L178)。
+// CoachmarkBody 的主 title 另走 text-body-lg(見 coachmark.tsx CoachmarkBody 主 title <h3>)。
 const PopoverTitle = React.forwardRef<
   HTMLHeadingElement,
   React.HTMLAttributes<HTMLHeadingElement>
->(({ className, ...props }, ref) => (
-  <h2
-    ref={ref}
-    className={cn("text-body font-medium truncate", className)}
-    {...props}
-  />
-))
+>(({ className, id, children, ...props }, ref) => {
+  const titleCtx = React.useContext(PopoverTitleContext)
+  // 掛載時向 PopoverContent 註冊 → content 自動設 aria-labelledby(見 PopoverTitleContext docblock)。
+  // consumer 自傳 id 時不註冊:auto 接線指向 context titleId,自訂 id 下引用會斷 → aria 由 consumer 自管。
+  const shouldRegister = id == null && titleCtx != null
+  const onTitleMount = titleCtx?.onTitleMount
+  const onTitleUnmount = titleCtx?.onTitleUnmount
+  React.useLayoutEffect(() => {
+    if (!shouldRegister) return
+    onTitleMount?.()
+    return onTitleUnmount
+  }, [shouldRegister, onTitleMount, onTitleUnmount])
+  return (
+    <h2
+      ref={ref}
+      id={id ?? titleCtx?.titleId}
+      className={cn("text-body font-medium truncate", className)}
+      {...props}
+    >
+      {/* 2026-07-28:截斷必附 tooltip(tooltip.spec.md「截斷 → tooltip,僅實際截斷時顯示」)——
+          同 DialogTitle 同型修;id/aria-labelledby 留在 h2 本體不受影響。 */}
+      <TruncatedText display="block">{children}</TruncatedText>
+    </h2>
+  )
+})
 PopoverTitle.displayName = "PopoverTitle"
 
 // Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
@@ -162,7 +224,7 @@ export const popoverMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 浮層容器 primitive,無自己的 variant/size/disabled 互動 state(spec「為何無 Inspector」段;對齊 separator.tsx meta canonical)
   tokens: {
     bg: ['bg-surface-raised'],
     fg: ['text-foreground'],

package/src/components/ProfileCard/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 './profile-card'