@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,295 @@
+// @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 React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Filter, Copy, Edit, Trash2, Info } from 'lucide-react'
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverBody,
+  PopoverFooter,
+  PopoverTitle,
+} from './popover'
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogBody,
+  DialogFooter,
+} from '@/design-system/components/Dialog/dialog'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+import {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+} from '@/design-system/components/Tooltip/tooltip'
+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'
+
+const meta: Meta = {
+  title: 'Design System/Components/Popover/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-wrap gap-3 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 Popover ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsDialogRule / VsDropdownMenuRule / VsTooltipRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Popover 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Popover/展示" name="篩選面板"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">篩選面板</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:往下看下方「Popover 與近親元件的分界」三組對照(對上 Dialog、DropdownMenu、Tooltip),確認該用哪個元件。</p>
+    </div>
+
+      {/* vs 近親 — VsDialogRule — 原 VsDialogRule */}
+      <div>
+      <Rule
+        title="Popover — non-modal 輕量浮層,使用者可 ignore 繼續主流程"
+        note="篩選 / 設定 / 快速切換等補充 UI。背景仍可 scroll、可 click,使用者不需要「處理完」才能繼續工作。典型案例:Jira filter panel、Linear view settings、GitHub file tree 的 branch switcher"
+      >
+        <Popover>
+          <PopoverTrigger asChild>
+            <Button variant="tertiary" startIcon={Filter}>依狀態篩選</Button>
+          </PopoverTrigger>
+          <PopoverContent align="start">
+            <PopoverHeader><PopoverTitle>依狀態篩選</PopoverTitle></PopoverHeader>
+            <PopoverBody>
+              {/* CheckboxGroup zero-gap canonical(checkbox.spec.md L225)— 非手刻 grid div */}
+              <CheckboxGroup>
+                <Checkbox defaultChecked label="進行中" />
+                <Checkbox label="已完成" />
+              </CheckboxGroup>
+            </PopoverBody>
+          </PopoverContent>
+        </Popover>
+        <Label>↑ 篩選條件是輔助工具,使用者可選擇不用;不該阻斷背景的列表互動</Label>
+      </Rule>
+
+      <Rule
+        title="Dialog — modal 阻斷背景,使用者必須處理才能繼續"
+        note="建立 / 編輯表單、破壞性確認、重要決策。Overlay 強制聚焦,使用者完成或取消才回到主頁。典型案例:Stripe 建立付款方式、Notion 永久刪除頁面確認、Linear 建立 issue form"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="primary" danger startIcon={Trash2}>永久刪除專案</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth="440px">
+            <DialogHeader>
+              <DialogTitle>確定要永久刪除此專案?</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">此動作無法復原,所有相關任務、評論、附件都會一併刪除。</p>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary" danger>永久刪除</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+        <Label>↑ 破壞性動作必須完整決策,不能讓使用者點旁邊就跳過</Label>
+      </Rule>
+
+      <Rule
+        title="判準 — 問「使用者可以 ignore 這個浮層、繼續用主介面嗎?」"
+        note="可以 ignore → Popover(filter / settings / quick switch)。不能 ignore,必須完成或取消才能繼續 → Dialog(confirm / 表單 wizard / 破壞性動作)"
+      >
+        <Label>Popover:filter 面板、Linear priority picker、Notion 字體設定</Label>
+        <Label>Dialog:建立 project、刪除確認、付款資訊輸入、多步驟 wizard</Label>
+      </Rule>
+    </div>
+
+      {/* vs 近親 — VsDropdownMenuRule — 原 VsDropdownMenuRule */}
+      <div>
+      <Rule
+        title="DropdownMenu — 固定結構的操作選單(一排 item list)"
+        note="語意是「從清單中選一個動作」。鍵盤可上下導覽、Enter 觸發,MenuItem 結構統一。典型案例:Gmail 右鍵選單、Figma layer context menu、GitHub 檔案的 ⋯ 選單"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary">檔案操作 ▾</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="start">
+            <DropdownMenuItem startIcon={Copy}>複製連結</DropdownMenuItem>
+            <DropdownMenuItem startIcon={Edit}>重新命名</DropdownMenuItem>
+            <DropdownMenuItem startIcon={Trash2}>刪除</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label>↑ 一排可點選的動作 → DropdownMenu,MenuItem 結構鍵盤可直接上下選</Label>
+      </Rule>
+
+      <Rule
+        title="Popover — 自由組合的 UI 面板(多欄、輸入、圖表皆可)"
+        note="語意是「這裡給我一塊可組自訂內容的浮層」。內容完全由 consumer 決定,可放輸入框、多個 section、圖表。典型案例:Jira advanced filter、Notion 屬性編輯、Linear date range picker"
+      >
+        <Popover>
+          <PopoverTrigger asChild>
+            <Button variant="tertiary">進階篩選</Button>
+          </PopoverTrigger>
+          <PopoverContent align="start" className="w-80">
+            <PopoverHeader><PopoverTitle>進階篩選</PopoverTitle></PopoverHeader>
+            <PopoverBody>
+              <CheckboxGroup>
+                <Checkbox defaultChecked label="我指派的" />
+                <Checkbox label="我建立的" />
+                <Checkbox label="我追蹤的" />
+              </CheckboxGroup>
+              <div className="border-t border-divider pt-3 mt-1 text-caption text-fg-muted">最多 3 個條件</div>
+            </PopoverBody>
+            <PopoverFooter>
+              <Button variant="tertiary" size="sm" className="flex-1">清除</Button>
+              <Button variant="primary" size="sm" className="flex-1">套用</Button>
+            </PopoverFooter>
+          </PopoverContent>
+        </Popover>
+        <Label>↑ 多種控制元件並存(checkbox + 說明 + 按鈕列)→ Popover</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 把 Popover 當 DropdownMenu 用"
+        note="一排 MenuItem 塞進 Popover 會失去 menu 語意(鍵盤導覽不完整、role='menu' 缺失、screen reader 不知道這是選單)"
+      >
+        <Label warn>一排可點選動作應該用 DropdownMenu;Popover 的內容應該是自由組合不只單一 list</Label>
+      </Rule>
+    </div>
+
+      {/* vs 近親 — VsTooltipRule — 原 VsTooltipRule */}
+      <div>
+      <Rule
+        title="Tooltip — hover 觸發,純文字輔助說明"
+        note="解釋 icon 按鈕含義、欄位說明、快捷鍵提示。使用者 hover 看到、移開就消失,內容不可互動。典型案例:Figma toolbar icon tooltip、Slack 按鈕功能提示、Gmail 的快捷鍵說明"
+      >
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button variant="text" size="sm" iconOnly startIcon={Info} aria-label="說明" />
+          </TooltipTrigger>
+          <TooltipContent>此欄位只接受英文與數字</TooltipContent>
+        </Tooltip>
+        <Label>↑ 純文字輔助 → Tooltip(hover 觸發,移開消失)</Label>
+      </Rule>
+
+      <Rule
+        title="Popover — click 觸發,互動式內容面板"
+        note="浮層內可放按鈕、輸入、選擇。使用者點擊才出現,點外部 / Esc 才關閉。典型案例:Linear priority picker、Jira filter panel、Notion 頁面設定"
+      >
+        <Popover>
+          <PopoverTrigger asChild>
+            <Button variant="tertiary" size="sm" startIcon={Filter}>篩選</Button>
+          </PopoverTrigger>
+          <PopoverContent align="start">
+            <PopoverBody>
+              <CheckboxGroup>
+                <Checkbox defaultChecked label="我的任務" />
+                <Checkbox label="全部" />
+              </CheckboxGroup>
+            </PopoverBody>
+          </PopoverContent>
+        </Popover>
+        <Label>↑ 需要互動 → Popover(click 觸發,內容可點擊)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 把 Tooltip 當 Popover 用"
+        note="Tooltip 在 hover 離開時就消失,使用者無法把滑鼠移到浮層上點按鈕。放互動元素會失效"
+      >
+        <Label warn>浮層裡要放按鈕 / checkbox / link → 必須 Popover 或 HoverCard(不是 Tooltip)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 把 Popover 當 Tooltip 用"
+        note="Popover 必須 click 觸發,「滑到 icon 上看說明」的場景用 Popover 使用者得先點一下才看得到,體驗變重"
+      >
+        <Label warn>純文字提示應該 hover 就出現 → 用 Tooltip(不要用 Popover)</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const VisualAlignmentRule: Story = {
+  name: '視覺對齊 Dialog（浮層視覺語言共用）',
+  render: () => (
+    <div>
+      <Rule
+        title="Popover 與 Dialog 共用 overlay-surface 視覺語言"
+        note="bg-surface-raised / border-border / rounded-lg / elevation-200 完全一致。Header / Body / Footer 內 padding 來自 overlay-surface pattern 主檔(px-loose py-tight)。差異:(1) Popover 是 non-modal 無 overlay 遮罩,(2) Popover 鎖 layout-space=md(header 精簡);Dialog 不鎖 layout-space,全繼承 page(md page → 16 / lg page → 24)。兩者 ui-size 都繼承 page"
+      >
+        <Popover>
+          <PopoverTrigger asChild>
+            <Button variant="tertiary">Popover</Button>
+          </PopoverTrigger>
+          <PopoverContent align="start">
+            <PopoverHeader><PopoverTitle>Header</PopoverTitle></PopoverHeader>
+            <PopoverBody><p className="text-body">Body 區域</p></PopoverBody>
+            <PopoverFooter>
+              <Button variant="tertiary" size="sm">取消</Button>
+              <Button variant="primary" size="sm">套用</Button>
+            </PopoverFooter>
+          </PopoverContent>
+        </Popover>
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="tertiary">Dialog</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth="360px">
+            <DialogHeader><DialogTitle>Header</DialogTitle></DialogHeader>
+            <DialogBody><p className="text-body">Body 區域</p></DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary">套用</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+        <Label>↑ 兩個浮層視覺語言一致,consumer 切換不會產生視覺斷層</Label>
+      </Rule>
+
+      <Rule
+        title="為什麼 layout-space 鎖 md"
+        note="Popover 只鎖 layout-space=md(header / footer padding 永遠精簡),內部控件的 ui-size 繼承 page(對齊 trigger)。頁面 layout-space 大(lg)時,Popover 若 header / footer 跟著放大會失去「輕量補充 UI」的定位 — 使用者會誤以為是主 modal。鎖 layout-space=md 讓 Popover chrome 永遠比主頁面緊湊,保持「這是補充不是主流程」的視覺暗示"
+      >
+        <Label>頁面 layout-space = lg,Popover header / footer 仍是 md(內部控件 ui-size 繼承 page)— 輕量感不被放大破壞</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -0,0 +1,209 @@
+---
+component: Popover
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isOverlay
+benchmark:
+  - Radix Popover primitive: github.com/radix-ui/primitives/tree/main/packages/react/popover
+  - MUI Popover: github.com/mui/material-ui/tree/master/packages/mui-material/src/Popover
+  - Polaris Popover: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Popover
+  - 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 設計原則
+
+## 定位
+
+Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點管理，內容由 consumer 決定。
+
+**實作基礎**：shadcn passthrough——基於 Radix Popover。本 DS 保留 shadcn 原結構 + 橋接 DS token（elevation / radius / border）。
+
+**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 浮層保持緊湊）。
+
+**Content size canonical（2026-04-29）**:density lock md → **fields(Input / Select / Checkbox)預設 `size="md"`**(field-height-md 32px,對齊 density)。其餘細節走 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 -->
+
+**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 -->
+
+**Align 對齊 canonical(跨浮層 SSOT)**:`align` 必須跟隨 trigger 在容器中的位置,**不是自由選擇**:
+
+| Trigger 在容器 | `align` | 對齊行為 |
+|---------------|---------|----------|
+| **左側 / 左上**(page header left、sidebar filter button) | `"start"` | Popover 與 trigger 左邊緣對齊,向右展開 |
+| **置中**(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 -->
+
+**SSOT 適用範圍(2026-04-20 精緻化)**:本規則是**「結構化浮層」的 canonical** —— Popover / DropdownMenu / Coachmark / SelectMenu 嚴格遵守(這些浮層寬度通常比 trigger 寬、且有結構化內容,錯方向必視覺 disconnect)。
+
+**輕量浮層例外**:Tooltip / HoverCard 不適用此 canonical —— 兩者 predominantly hover 觸發、純展示(不互動或極少互動)、寬度隨內容自適應,Radix 預設 `align="center"` 即可涵蓋絕大多數情境。強行套 trigger-position alignment 反而破壞 Tooltip「貼合指標」的輕量感。這兩個 primitive 走自己的 spec canonical(通常 center + 小 sideOffset)。
+
+**SelectMenu 特例**:SelectMenu 是 input-triggered,width 在 min/max 範圍內自動跟 input 同寬 → `align="start"`(對齊 input 左邊緣)在視覺上與「popover 跟 input 同寬」重疊,consumer 感知不到 alignment 差異。仍採用 canonical 以保 code 一致性,但視覺上是透明的。
+
+其他結構化浮層 spec 若討論 align 應 pointer 指回本節。
+
+**結構化組合（可選）**：PopoverContent 外殼無內距，consumer 可選擇：
+- **單一 body**：包 `<PopoverBody>` 取得 Dialog body 同 padding (`px-loose py-tight`)
+- **含標題**：組合 `<PopoverHeader>` + `<PopoverBody>`（下分隔線由 Header 提供）
+- **含操作按鈕列**：再加 `<PopoverFooter>`（上分隔線由 Footer 提供）
+
+**Dismiss 預設**(與 Dialog 一致):Popover **預設 dismissible** —— 點擊 trigger 外 / 按 Esc / focus 離開 content 樹,三者任一皆關閉。由 Radix 內建 `onPointerDownOutside` / `onEscapeKeyDown` 行為提供,consumer 無需額外 wire。如需強制 modal(必須按 Close 才能關),傳 `modal={true}` 並在 Header 放 Close 按鈕;但這是例外,不是預設——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 佔位;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。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:無 override,unbounded 佔位 24 → 48(若只有 unbounded)或自然長(若有 bounded)。詳 `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。
+
+**重量分級(world-class 共通 pattern)**:
+
+| Overlay 類型 | Title typography | Rationale |
+|------------|------------------|-----------|
+| **Modal**(Dialog / Sheet)| `text-body-lg`(16px)| 重量級決策 surface,title 是決策 anchor,需視覺重量 |
+| **Non-modal**(Popover / Coachmark / Tooltip / HoverCard)| `text-body`(14px)| 輕量浮層,可忽略、非阻斷,title 是輔助標籤不搶視覺重心 |
+
+**世界級對照**(7 家 DS 同 split):
+| DS | Modal title | Non-modal popover title |
+|----|-------------|------------------------|
+| Material M3 | Headline(24px large / 16px body 分 variant)| Smaller(usually 14-16px) |
+| Polaris | Modal title 大號 | Popover 較小 |
+| Atlassian | Modal 大 | InlineDialog 小 |
+| Notion | Modal 16px+ | Popover 14px |
+| Linear | Modal 16px | Popover / HoverCard 14px |
+| Figma | Modal 16px | Inline panel / popover 13-14px |
+| GitHub Primer | Dialog 16px | Overlay 14px |
+
+**共通原則**: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` CoachmarkBody 主 title `<h3>`)— 那是 body content 不是 chrome title,分離 concerns。
+
+**禁止**:consumer 自己在 PopoverContent 裡手刻 `<h2 className="text-body-lg">` 當 title(繞 PopoverTitle 的 canonical)。若需要大 title,視為該用 Dialog 而非 Popover(選對元件)。
+
+---
+
+## 何時用
+
+- **點擊觸發的輕量浮層**：filter panel、date picker 展開、設定 mini panel
+- **需要放互動元素的浮層**：按鈕、輸入框、checkbox 群組
+- **非 modal 的補充 UI**：使用者可以忽略並繼續主流程，不阻斷背景互動
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| hover 觸發（非點擊）| `HoverCard` | HoverCard 觸發是 hover，Popover 是點擊 |
+| 純文字提示 | `Tooltip` | Tooltip 更輕量，適合純文字 |
+| 需要阻斷背景的流程 | `Dialog` | Dialog 是 modal，Popover 非 modal |
+| 操作選單（複製 / 刪除）| `DropdownMenu` | DropdownMenu 有 menu 語意 + 鍵盤導覽 |
+| 選值下拉 | `Select` / `Combobox` | 下拉選單用專用元件，不自組 Popover + list |
+
+---
+
+## 與 Dialog 的分界
+
+- **Popover**：non-modal 輕量浮層（filter / settings panel / mini 操作面板）——背景仍可互動
+- **Dialog**：modal 阻斷互動（confirmation / form wizard / 需要完成才能繼續的流程）
+
+**判斷法**：問「使用者可以 ignore 這個浮層、繼續使用主介面嗎？」可以 → Popover；不可以、必須處理才能繼續 → Dialog。
+
+## 與 DropdownMenu 的分界
+
+- **DropdownMenu**：有預設 item 結構（MenuItem list），語意是「從清單中選一個動作」— click 單一 item 即觸發 action,無 save CTA
+- **Popover**：內容自由（任意 React 元素），可放按鈕、輸入框、圖表、form;支援「暫存選中狀態 + 明確 save CTA」
+
+選單類(click 單項即動作,無 save)用 DropdownMenu;自由組合 UI 面板(多欄表單、filter 控制群、「選完按套用」的多選工作流)用 Popover。
+
+### 合法但少見:Popover 內含可選 item 列 + footer save CTA
+
+Popover 可以在 body 放 checkbox / radio 列表 / 可選 chip / 可選 menu-item-like elements,**但必在 footer 有 CTA 按鈕(套用 / 儲存 / 完成)觸發狀態提交**。這個 pattern 跟 DropdownMenu 的差別是:**DropdownMenu 一 click 即觸發動作,Popover 這類是「暫存選擇 → 按 CTA 才 commit」**。典型情境:
+
+- **多選 filter panel**:checkbox 列表 + 底部 `清除 / 套用`(見 `FilterPanel` story)
+- **Bulk edit**:選多個 menu-item-like options + 底部 `儲存變更`
+- **Custom toolbar 設定**:可選 toggle 列 + 底部 `套用偏好`
+
+canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是 → DropdownMenu;否(要按 footer CTA 才 commit)→ Popover。
+
+---
+
+## 禁止事項
+
+- ❌ **不把 Popover 當 Tooltip**：Tooltip 是 hover 觸發的純文字輔助，Popover 是 click 觸發的互動面板，語意與觸發模型不同
+- ❌ **不用 Popover 做 confirmation dialog**：確認框必須阻斷背景互動,使用者不能忽略——那是 Dialog 的職責
+- ❌ **不在 Popover 內放 nested Popover**：嵌套層級混亂、焦點管理崩壞，複雜互動改用 Dialog 或拆成多步驟
+
+---
+
+## 邊界案例
+
+- **極長內容**:PopoverContent 設 `max-h-[var(--radix-popover-content-available-height)]`(popover.tsx:65),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**:永遠鎖 `md`(見「定位」段),不隨頁面 density 放大。
+
+---
+
+## A11y 預設
+
+焦點 / 鍵盤 / ARIA 行為分兩層——**DS 覆寫**(改 Radix 預設)與 **Radix 內建**(沿用)：
+
+- **開啟焦點(DS 覆寫)**：DS 以 `onOpenAutoFocus` 覆寫 Radix 預設 autofocus(見 `popover.tsx` `handlePopoverOpenAutoFocus`),開啟時把焦點落在 body 第一個可互動元素。Radix 預設會先 focus 右上 close X,DS 覆寫以避免觸發 tooltip leak(對齊 Material / Polaris「open 時 focus 落首個有意義控制」)。**注意**:若移除此 default handler,行為會回退成 Radix 預設 focus close X
+- **關閉返回(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"`
+
+Consumer 無需額外處理 a11y,保留 Radix `data-state` 屬性即可(開啟焦點的 DS 覆寫 default 已 wire 在 `PopoverContent`,consumer 可傳自己的 `onOpenAutoFocus` override)。
+
+---
+
+## 為何無 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 覆蓋。
+
+Popover 內容完全由 consumer 決定,無自己的 variant/size/disabled 等可試玩 prop——Inspector 對 container 類元件價值低。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `PlacementMatrix`(12-cell side × align 矩陣) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`(open / close / animation)。
+
+---
+
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — hover 觸發的對應浮層
+- `../Tooltip/tooltip.spec.md` — 純文字提示
+- `../Dialog/dialog.spec.md` — 需要阻斷的 modal
+- `../DropdownMenu/dropdown-menu.spec.md` — 有 menu 語意的操作選單
+- `../SelectMenu/select-menu.spec.md` — SelectMenu 消費 Popover 作為浮層容器
+- `../Coachmark/coachmark.spec.md` — Coachmark 為 Popover 的 composition pattern(無 header / 有 media / footer justify-between),共用所有 overlay-surface SSOT
+- Radix Popover primitive — `@radix-ui/react-popover`
+- `../../patterns/overlay-surface/overlay-surface.spec.md` — Header / Body / Footer padding SSOT（Dialog + Popover 共用）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `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,116 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Filter } from 'lucide-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'
+
+const meta: Meta = {
+  title: 'Design System/Components/Popover/展示',
+  parameters: { layout: 'centered' },
+}
+export default meta
+type Story = StoryObj
+
+export const FilterPanel: Story = {
+  name: '篩選面板',
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="tertiary" startIcon={Filter}>依狀態篩選</Button>
+      </PopoverTrigger>
+      <PopoverContent align="start">
+        <PopoverHeader>
+          <PopoverTitle>依狀態篩選</PopoverTitle>
+        </PopoverHeader>
+        <PopoverBody>
+          {/* 此 Popover 是「多選 + footer save CTA」模式 — 勾多項按「套用」才 commit。
+              區別於 DropdownMenu「click 即觸發」。CheckboxGroup 設計準則 自帶 zero-gap
+              + Context 隔離,取代既有手刻 grid div(2026-04-29 migration)。 */}
+          {/* CheckboxGroup zero-gap canonical(checkbox.spec.md L225)— 取代既有手刻 grid div */}
+          <CheckboxGroup>
+            <Checkbox defaultChecked label="待處理" />
+            <Checkbox defaultChecked label="進行中" />
+            <Checkbox 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>
+  ),
+}
+
+/**
+ * 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: ['!autodocs'],
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="tertiary" startIcon={Filter}>依狀態篩選</Button>
+      </PopoverTrigger>
+      <PopoverContent align="start">
+        <PopoverHeader>
+          <PopoverTitle>依狀態篩選</PopoverTitle>
+        </PopoverHeader>
+        <PopoverBody>
+          {/* CheckboxGroup zero-gap canonical(checkbox.spec.md L225)— 取代既有手刻 grid div */}
+          <CheckboxGroup>
+            <Checkbox defaultChecked label="待處理" />
+            <Checkbox defaultChecked label="進行中" />
+            <Checkbox 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>
+  ),
+}
+
+// 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 個選項選一個)、手刻 `<Popover>` 內放 raw `<button>`
+//   item 列表 — 這是 `<Select>` / `<DropdownMenu>` 的標準情境,不該走 Popover。
+//
+//   B1 決策(user):menu / select / combobox 早已定義過那種「格式化的選單範例」,
+//   Popover 不再 demo。Popover 的本質是「輕量盡量不干擾使用者心流的 modal」—
+//   結構化 form / filter / settings 等情境才是 canonical。