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

package/src/components/BulkActionBar/bulk-action-bar.principles.stories.tsx

@@ -0,0 +1,242 @@
+// @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 LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Trash2, Archive } from 'lucide-react'
+import { BulkActionBar } from './bulk-action-bar'
+import { Alert } from '@/design-system/components/Alert/alert'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/BulkActionBar/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+const Rule = ({ title, note, children }: { title: string; note?: string; children: React.ReactNode }) => (
+  <div className="mb-10">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-4 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3">{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>
+)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose">
+          <p>BulkActionBar 是「選取狀態驅動」的批次操作列,跟 selection state 生命週期綁定。真實業務場景:</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/BulkActionBar/展示" name="基本"><span className="text-primary hover:text-primary-hover cursor-pointer">基本</span></LinkTo>(收件匣多選郵件後,一次封存 / 加標籤 / 刪除)</li>
+            <li><LinkTo kind="Design System/Components/BulkActionBar/展示" name="提示擴選整個資料集"><span className="text-primary hover:text-primary-hover cursor-pointer">提示擴選整個資料集</span></LinkTo>(資料集共 5370 筆、本頁只顯示 50 筆:本頁全選後浮出提示,可一鍵把選取範圍擴大到全部 5370 筆)</li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定:對照 spec.md「何時用 / 何時不用」段。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ 對單一 item 操作不用 BulkActionBar"
+          note="單項 inline action(編輯 / 刪除某一筆)應在 row 內 inline action region(item-anatomy)。BulkActionBar 是『multi 狀態浮現』語意,單項 action 升 toolbar 是過度反應"
+        >
+          <Label warn>單項操作 → row 內 InlineAction(MoreVertical / Edit / Delete icon button)</Label>
+        </Rule>
+
+        <Rule
+          title="❌ Page-level Submit / Save 不放 BulkActionBar"
+          note="Page-level CTA 跟 selection 無關(沒選任何 row 也要 Submit)。耦合 BulkActionBar 生命週期會導致 selection 清空時 Submit 跟著消失,使用者卡關"
+        >
+          <Label warn>頁面主要按鈕放在頁尾或頁首,不與 BulkActionBar 耦合</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 永遠顯示的 toolbar(filter / sort / search)不用 BulkActionBar"
+          note="filter / sort / search 不依賴 selection,沒選也要顯示。用 action-bar pattern 組 toolbar 即可"
+        >
+          <Label warn>常駐 toolbar → patterns/action-bar(Toolbar 變體)</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="BulkActionBar — selection-driven,length=0 自動藏"
+          note="只在多選狀態浮現,清除選取就消失。生命週期跟 selection state 綁定。對齊 Linear / Notion / Polaris IndexTable / Material DataGrid"
+        >
+          <BulkActionBar
+            selection={['a', 'b', 'c']}
+            actions={
+              <>
+                <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
+                <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+              </>
+            }
+            onClear={() => {}}
+          />
+          <Label>↑ selection {`>`} 0 浮現,= 0 完全藏</Label>
+        </Rule>
+
+        <Rule
+          title="Action Bar / Toolbar pattern — 永遠顯示,不依賴 selection"
+          note="filter / sort / search / 新增按鈕等 page-level operations。詳見 patterns/action-bar/action-bar.spec.md"
+        >
+          <Label>常駐工具列,不隨 selection 變化</Label>
+        </Rule>
+
+        <Rule
+          title="Notice / Toast — 系統訊息,不是批次操作"
+          note="通知使用者某事發生(操作成功 / 失敗 / 系統公告)。可帶 1-2 個 action,但語意是『回應系統訊息』非『對選取項做事』"
+        >
+          <Label>系統訊息走 Notice / Toast,單純 ack 而非 batch operate</Label>
+        </Rule>
+      </Section>
+
+      <Section title="判斷法">
+        <p className="text-body text-fg-secondary max-w-prose">
+          「沒選取就消失嗎?」是 → BulkActionBar;否 → Action Bar pattern / Toolbar / Notice。
+        </p>
+      </Section>
+    </div>
+  ),
+}
+
+export const VsToastRule: Story = {
+  name: 'BulkActionBar vs Toast — 角色區分',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ BulkActionBar = 選取狀態下的批次操作;Toast = 事件後的短暫回饋"
+        note="兩者都浮在底部,但語意完全不同。BulkActionBar 隨 selection state 決定顯示(state-driven),容納多 action,使用者主動操作;Toast 是事件後 transient 通知(event-driven),自動消失,僅 1-2 action(undo / dismiss)。對齊 Polaris BulkActions vs Toast / Material BulkActionsBar vs Snackbar 共識。"
+      >
+        <Label>BulkActionBar</Label>
+        <BulkActionBar
+          selection={['a', 'b', 'c']}
+          actions={
+            <>
+              <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
+              <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+            </>
+          }
+        />
+      </Rule>
+      <Rule
+        title="❌ 不要用 BulkActionBar 顯示「3 個項目已封存,Undo」這類事件後通知"
+      >
+        <Label warn>這種情況應改用 Toast</Label>
+        <p className="text-fg-muted text-body">
+          事件後通知 → 用 Toast(sonner Toaster)。
+          BulkActionBar 是「選了 N 項要做什麼」的選取後 toolbar,不是「我做完了」的回饋。
+        </p>
+      </Rule>
+    </div>
+  ),
+}
+
+export const ActionVariantRule: Story = {
+  name: '動作 變體 規則（不用 主要）',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 批次 action 用 tertiary,destructive 用 tertiary + danger"
+        note="批次操作是『可取消的入口』(點下後通常還會跳出確認視窗),所以用次要樣式(tertiary)就好;最強調的 primary 樣式留給確認視窗裡那顆最終按鈕。刪除這類危險操作也只加 danger 紅色,不升成 primary。"
+      >
+        <BulkActionBar
+          selection={['a', 'b', 'c']}
+          actions={
+            <>
+              <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
+              <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+            </>
+          }
+          onClear={() => {}}
+        />
+        <Label>↑ tertiary 主 / tertiary danger 破壞性</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 批次 action 用 primary"
+        note="primary 視覺權重最高,留給 dialog 內最終確認。批次 toolbar 用 primary 會跟 page-level Submit 視覺衝突,user 認知混淆"
+      >
+        <BulkActionBar
+          selection={['a', 'b', 'c']}
+          actions={
+            <>
+              <Button variant="primary" size="md" startIcon={Archive}>封存</Button>
+              <Button variant="primary" size="md" startIcon={Trash2} danger>刪除</Button>
+            </>
+          }
+          onClear={() => {}}
+        />
+        <Label warn>↑ 兩顆都 primary → 視覺重量過高,跟 page Submit 競爭</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const HintBannerRule: Story = {
+  name: '提示 橫幅 — 用 Alert 不自刻',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 擴 dataset 提示用 Alert(variant=info, placement=fixed)+ ReactNode title 帶 inline link"
+        note="不在 BulkActionBar 內部 hardcode hint banner。Alert 既有 placement=fixed 已支援(rounded-none border-none),title 接 ReactNode 後可塞 inline button 自然 inline 連結。banner 黏在 BulkActionBar 上方 / 下方,共浮起"
+      >
+        <div className="border border-divider rounded-md overflow-hidden">
+          <Alert
+            variant="info"
+            placement="fixed"
+            dismissible={false}
+            title={
+              <>
+                已選取本頁全部 50 個。{' '}
+                <button type="button" className="text-primary hover:text-primary-hover">
+                  點此選取全部 5370 個項目
+                </button>
+              </>
+            }
+          />
+          <div className="border-t border-divider">
+            <BulkActionBar
+              selection={Array.from({ length: 50 }, (_, i) => `f-${i}`)}
+              actions={<Button variant="tertiary" size="md">下載</Button>}
+              onClear={() => {}}
+            />
+          </div>
+        </div>
+        <Label>↑ Alert + BulkActionBar 兩 bar 黏一起,inline link 流暢呈現</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 自刻 hint banner / 用 contrast 底色 div"
+        note="banner 是 Alert 的職責(自帶 a11y role / aria-live / 視覺一致性)。自刻會破壞跟其他 Alert 的視覺一致性,也漏 a11y"
+      >
+        <Label warn>(範例省略)有 Alert 元件不用是浪費</Label>
+      </Rule>
+
+      <Rule
+        title="✅ Filter hidden 進主 bar count 區 inline,不開 hint banner"
+        note="hint banner 唯一語意是「dataset 擴充入口」。filter hidden 是 minor status,inline 進 count 區即可,不該佔 banner 區域"
+      >
+        <BulkActionBar
+          selection={['a', 'b', 'c']}
+          hiddenByFilter={2}
+          actions={<Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>}
+          onClear={() => {}}
+        />
+        <Label>↑ count 文字 inline:「已選 3 項 · 2 個被 filter 隱藏」</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/BulkActionBar/bulk-action-bar.spec.md

@@ -0,0 +1,226 @@
+---
+component: BulkActionBar
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasActions
+benchmark:
+  - Polaris BulkActions: github.com/Shopify/polaris/tree/main/polaris-react/src/components/BulkActions
+  - Polaris IndexTable (bulk selection): github.com/Shopify/polaris/tree/main/polaris-react/src/components/IndexTable
+  - Carbon DataTable (batch actions): github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/DataTable
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# BulkActionBar 設計原則
+
+## 定位
+
+選取多項 item(table row / list item)後浮現的批次操作列。**不獨立於選取狀態存在**——`selection.length === 0` 時隱藏,`> 0` 時浮現。
+
+**Layout Family**:非 1-4 family — composite / multi-section(自 own layout,batch action 區 + count 區 + page-action 區 + hint banner)。
+
+**世界級對照**:Linear bulk action toolbar / Polaris IndexTable bulk actions / Material DataGrid `<GridToolbar>` selection mode / Notion database row selection bar / Gmail / GitHub Issues 多選 toolbar。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 何時用
+
+- DataTable / list / Combobox(multi)/ TreeView 的 batch operation
+- 多項 item 選取後需要對全部執行同一操作(Delete / Archive / Move / Tag / Assign / Export 等)
+- 提供「批次 → 個別」的 dataset 全選 escape hatch(對 large dataset 提供「點此選取全部 M 個」)
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 對單一 item 操作 | Inline Action(item-anatomy)| 單項操作不該升 batch toolbar |
+| Page-level primary CTA(Save / Submit / Publish)| 一般 button + page footer | Page-level 不依賴 selection 狀態 |
+| 永遠顯示的 toolbar(filter / sort / search)| Action Bar pattern + Toolbar | 不依賴 selection,沒「批次」語意 |
+| 系統 notification | Notice / Toast / Alert | 通知 ≠ batch action |
+
+---
+
+## 近親元件分界
+
+| 元件 | 觸發 | 視覺權重 |
+|---|---|---|
+| **BulkActionBar** | `selection.length > 0` | 高(selection 期間浮現)|
+| **Action Bar pattern** | 永遠 | 中(常駐 chrome) |
+| **Toolbar**(action-bar 變體)| 永遠 | 中 |
+| **Notice / Toast / Alert** | 系統訊息 | 低-中 |
+
+判斷:**「沒選取就消失嗎?」** 是 → BulkActionBar;否 → Action Bar / Toolbar / Notice。
+
+## 常見誤解
+
+| 誤解 | 正解 |
+|------|------|
+| 「BulkActionBar 可替代 toolbar」 | 否——additive 派,toolbar 永遠保留(selection 期間 filter / sort / search 仍可用,見「Placement」) |
+| 「批次主操作用 primary」 | 否——一律 tertiary(primary 留給 dialog 確認最終 action,見「禁止事項」) |
+| 「selection 為 0 顯示空 bar 佔位」 | 否——回 null 完全不佔 layout(見「結構」) |
+
+---
+
+## 結構
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ [✕] [{N} 已選 · M hidden by filter] │ [Action 1] [Action 2]   │
+│  ↑ clear  ↑ count + filter inline     ↑ batch actions(consumer)│
+└──────────────────────────────────────────────────────────────┘
+```
+
+- 全 md Buttons(`same-row consistency`,close X 同 size;rationale 見下方「Size canonical」)
+- `gap-2`(8px)+ `<ButtonDivider />`(自帶 mx-1 = 12px 視覺距離)
+- `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`
+- 自然高度 56md / 68lg(md Button `--field-height-md` 32/36 + `py-[var(--layout-space-tight)]` 12/16 ×2;對齊 SurfaceFooter / DataTable toolbar canonical)
+- `selection.length === 0` **且** `totalSelected` 為 0/未設 → 回 null 不佔 layout(反向選取 all 模式 `totalSelected > 0` 但可見列全 excluded 時仍顯示,見「Extend dataset pattern」)
+- **寬度邊界**:actions 為單行 flex 排列(`gap-2`),無折行、無內建 overflow 收納;寬度受限場景由 consumer 控制 action 數量
+
+### Slot
+
+- **`actions`**:consumer 提供 **md** Buttons(size rationale 見「Size canonical」);`variant=tertiary`(主)/ `tertiary danger`(destructive)— **不用 primary**(留 dialog 確認最終 action)
+- **count 區**:`{N} 已選`(內建)+ inline filter hidden status `· {M} 個被 filter 隱藏`(`hiddenByFilter` prop 傳入時)
+- **clear**:`<Button iconOnly size=md variant=text dismiss />`(內建,觸發 `onClear`)
+
+#### Size canonical(2026-05-04 升 SSOT)
+
+| Placement variant | Buttons size | 理由 |
+|--|--|--|
+| **default**(footer 浮層 / page-bottom 區段)| **md** | 視覺 weight 對齊 Dialog footer commit 系 / page primary-button bar(md)/ Linear/Notion/Asana world-class 共識 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| **top-toolbar 變體**(未來)| sm | 覆蓋 sm-density toolbar / GitHub-style;variant prop 驅動 override |
+
+#### Count text color canonical(2026-05-04 升 SSOT)
+
+| 元素 | Token / weight | 理由 |
+|--|--|--|
+| **count(`已選 N 項`)** | `text-foreground` + `font-medium` | state-bearing 主資訊(user 在 selection mode + N items),非裝飾 → primary foreground。對齊 Linear / Notion / Carbon / Polaris 共識;muted 化會弱化 state signal | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| **`hiddenByFilter` suffix(`· M 個被 filter 隱藏`)** | `text-fg-muted` + `font-normal` | 次資訊,視覺層次低於 count |
+| **clear X icon** | dismiss md(自動 fg-muted)| chrome dismiss canonical |
+
+### 不含 page-level primary / 不含 hint banner
+
+- **page-level Submit / Save**:跟 selection 無關,consumer 自擺,不耦合 BulkActionBar 生命週期
+- **Hint banner**(擴 dataset 提示):用 `<Alert variant="info" placement="fixed">` 黏在 BulkActionBar 上方,**不在 BulkActionBar 內部 hardcode**。Alert 的 `title` 接 ReactNode 可塞 inline `<button>` 連結
+
+---
+
+## Placement — inline composition canonical(撤 top-replace 派)
+
+BulkActionBar 是 plain block(無 positioning 邏輯),consumer 用 flex column 容器自然排列。Selection > 0 時 Alert + BulkActionBar 接在 DataTable 下方,**toolbar 永遠保留**(filter / sort / search 在 selection 期間仍可用)。
+
+```tsx
+<div className="flex flex-col">
+  <Toolbar />                                    {/* 永遠保留,selection 期間可用 */}
+  <DataTable selection={...} ... />
+  {showHint && <Alert variant="info" placement="fixed" title={<>...inline link CTA...</>} />}
+  {selection.length > 0 && <BulkActionBar selection={...} actions={...} />}
+</div>
+```
+
+**為什麼撤 top-replace**:Polaris IndexTable / Material DataGrid / GitHub / Gmail 等「替代 toolbar」做法在 selection 期間**喪失 filter / sort / search 功能**,user workflow 斷裂(「我選了 50 個再 filter 出 status=error 子集 batch action」這種常見 workflow 卡關)。本 DS 採 Linear / Notion / Apple Mail / iOS Files / Notion / Atlassian additive 派 — toolbar 永遠保留。
+
+### Layout 行為(4 use case 全 covered by inline composition)
+
+| Use case | DataTable 設定 | Inline composition 結果 |
+|---|---|---|
+| 1️⃣ Page 中一段 | `height="auto"` | BulkActionBar 自然接在 table 下方 ✓ |
+| 2️⃣ Container fill(dialog body 等)| `height="100%"` | flex column,table flex-1,BulkActionBar 接尾 ✓ |
+| 3️⃣ Viewport-fill app | `height="100%"` 配 flex-1 | table 自動讓位 ✓ |
+| 4️⃣ 長 page scroll(BulkActionBar 不可 scroll 走)| auto | consumer **自行套** `<div className="sticky bottom-0">` 或 `fixed bottom-0` wrapper |
+
+case 4 比較少見,consumer 知道自己 layout 時自加 wrapper 即可,DS primitive 不該替消費者決定 positioning。
+
+---
+
+## API
+
+```ts
+interface BulkActionBarProps {
+  /** 已選 ID,length === 0 時自動隱藏(回 null) */
+  selection: readonly string[]
+  /** Clear 觸發,user 點 X icon(consumer 在 page-level 監聽 Esc 觸發) */
+  onClear?: () => void
+  /** 批次 actions(consumer 提供 md Button,variant=tertiary 或 tertiary+danger,不用 primary) */
+  actions?: React.ReactNode
+  /** Filter 模式:hidden 數量,顯示在 count 區 inline 「{N} 已選 · {M} 個被 filter 隱藏」 */
+  hiddenByFilter?: number
+  /** 擴選整個 dataset 後的真總數;number 時 count 顯示此值,否則 fallback selection.length(見「Extend dataset pattern」) */
+  totalSelected?: number | null
+  /** i18n labels(Partial,merge with default;對齊 Material localeText / Polaris i18n 慣例) */
+  labels?: Partial<BulkActionBarLabels>
+  className?: string
+}
+
+interface BulkActionBarLabels {
+  count: (n: number) => string         // default 「已選 {n} 項」
+  clear: string                         // default 「清除選取」(X aria-label)
+  hiddenSuffix: (hidden: number) => string  // default 「· {hidden} 個被 filter 隱藏」
+  toolbarAriaLabel: string              // default 「批次操作」
+}
+```
+
+完整 default labels 由 component 內 export `BULK_ACTION_BAR_DEFAULT_LABELS`,consumer 可 spread 後 override(對齊 Material `defaultLocale` 模式)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**Hint banner(擴 dataset 提示)不在本 API**:由 consumer 用 `<Alert variant="info" placement="fixed">` 配 ReactNode title 帶 inline link 自組,黏在 BulkActionBar 上方。Alert / Notice 的 `title` + `description` 已支援 ReactNode(2026-04-28)。
+
+### Extend dataset pattern(totalSelected)
+
+「本頁全選 → hint 點擊 → 擴選整個 dataset」2-step 後,consumer 把 `totalSelected` 設為 dataset 真總數,count 區改顯示該值(否則 fallback `selection.length`)——避免 Alert 顯「已選 5370」但 bar 仍顯「已選 50」的不同步(2026-05-13 ship)。對齊 Gmail / Linear / Notion 全選 dataset hint pattern。
+
+**可見性與反向選取(DataTable all 模式,2026-06-22)**:顯示判準 = `selection.length > 0 || (totalSelected ?? 0) > 0`。反向選取(`{ mode:'all', excluded }`)下若可見列全被 excluded、`selection`(可見代表)為空但 `totalSelected > 0`(全集仍有選取),bar **仍顯示**(否則「已選 N 個但 bar 消失」矛盾)。對應 `data-table.spec.md`「L2 選取」inverted 模型。
+
+---
+
+## a11y 預設
+
+- BulkActionBar 整體用 `role="toolbar"` + `aria-label`(default `"批次操作"`,可 override)
+- count 文字用 `aria-live="polite"` 通知 selection 變更(SR 讀「3 selected」)
+- Clear button:`aria-label="清除選取"`
+- Hint banner 用 `role="status"` + `aria-live="polite"`(state 切換時通知)
+- 鍵盤:Esc → `onClear()`(consumer 應監聽 page-level keydown 觸發);Tab 序按 DOM 順序 = clear(X)→ actions(count 是純文字 span,非互動元素 → 不參與 Tab)
+- Disabled action(無權限等)用 Button `disabled` + tooltip 解釋,**不藏 action**(避免 user 困惑)
+
+---
+
+## 視覺與動畫
+
+- **出現 / 消失**:有選取(`selection.length > 0` **或** `totalSelected > 0`)直接 mount;歸零回 null 直接 unmount(無 fade 動畫)。inline composition 下自然 reflow;consumer 需固定高度時自擺 placeholder(見「禁止事項」)
+- **底色**:**無底色 contrast**,跟 page 同色(`bg-canvas` / `bg-surface` 視 placement 繼承)。對齊 Notion / Linear minimalist — 用文字內容切換呈現「mode」,**不**用底色 highlight。**不像 Polaris 那種顯著底色變化** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **邊界**:**無外框邊界**(融入 page chrome)— 恆 **`border-top` border-divider 切割 layout**(bar 是 page 結構,不是 floating overlay,不用 box-shadow 製造「浮層」誤導)。top-toolbar 變體為未來項(見「Size canonical」)
+- **與 table 的關係**:inline composition — bar 接在 DataTable 下方,toolbar 永遠保留(見「Placement」)
+- **Action variant**:`tertiary`(主)+ `tertiary danger`(destructive)— **不用 primary**(留給 dialog 確認最終 action)
+
+---
+
+## 禁止事項
+
+- ❌ 不內建 page-level Submit / Save / page primary CTA(consumer 自擺,不耦合 selection)
+- ❌ 不直接擴 dataset 全選(必須 2-step:本頁全選 → hint 點擊 → 擴 dataset)
+- ❌ 不在 selection.length === 0 仍佔 layout(必須完全藏 OR consumer 自擺 placeholder)
+- ❌ 不藏 disabled action(顯示 disabled 比藏起來易理解,user 知道為何不能用)
+- ❌ 不替代既有 toolbar 永久(只在 selection > 0 期間,clear 後恢復)
+- ❌ 批次 action **不用 variant="primary"**(留給 dialog 確認最終 action);批次用 `tertiary`,destructive 用 `tertiary` + `danger`(對齊 button.spec.md 「Inline destructive 不用 primary」 canonical)
+- ❌ 不用 contrast 底色 / box-shadow 製造「浮層」感(footer 是 layout 結構切割,不是 overlay)
+- ❌ Hint banner 不在「全可見已選 + dataset 還有更多」之外的場景顯示(小 dataset 顯示 hint 是 noise)
+- ❌ Filter hidden status 不獨立開 hint banner(進主 bar count 區 inline 即可)
+
+---
+
+## 為何無 SizeMatrix
+
+BulkActionBar 高度由消費者所在 placement 決定(top 模式 = toolbar 高度;footer 模式 = footer 高度),元件內部不提供 size prop。對齊 anatomy-standard.md 的 N/A 例外。
+
+`@anatomy-rationale: SizeMatrix N/A — 高度繼承 placement 的 toolbar/footer 容器`
+
+---
+
+## 相關
+
+- `../DataTable/data-table.spec.md`「L2 選取」段 — DataTable 端 selection state + 整合方式
+- `../../patterns/action-bar/action-bar.spec.md` — toolbar 操作排列規則,本元件繼承 batch action 排序原則
+- `../Button/button.spec.md` — Action button variant 規則
+- `../Notice/notice.spec.md` — hint banner 視覺繼承(role / aria-live 同源)
+- `../../tokens/color/color.spec.md` — toolbar bg / divider semantic token

package/src/components/BulkActionBar/bulk-action-bar.stories.tsx

@@ -0,0 +1,136 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Trash2, Archive, Tag as TagIcon, MoveRight, Download } from 'lucide-react'
+import { BulkActionBar } from './bulk-action-bar'
+import { Button } from '@/design-system/components/Button/button'
+import { Alert } from '@/design-system/components/Alert/alert'
+
+const meta: Meta<typeof BulkActionBar> = {
+  title: 'Design System/Components/BulkActionBar/展示',
+  component: BulkActionBar,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof BulkActionBar>
+
+// 真實業務 scenario:Email inbox 多選後的批次操作
+export const Default: Story = {
+  name: '基本',
+  render: () => {
+    const [selection, setSelection] = useState<string[]>(['mail-1', 'mail-2', 'mail-3'])
+    return (
+      <BulkActionBar
+        selection={selection}
+        onClear={() => setSelection([])}
+        actions={
+          <>
+            <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
+            <Button variant="tertiary" size="md" startIcon={TagIcon}>加標籤</Button>
+            <Button variant="tertiary" size="md" startIcon={MoveRight}>移動</Button>
+            <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+          </>
+        }
+      />
+    )
+  },
+}
+
+// Filter 模式:hidden 數量顯示在 count 區 inline
+export const WithFilterHidden: Story = {
+  name: '部分項目被篩選隱藏',
+  render: () => {
+    const [selection, setSelection] = useState<string[]>(['issue-1', 'issue-2', 'issue-3'])
+    return (
+      <BulkActionBar
+        selection={selection}
+        onClear={() => setSelection([])}
+        hiddenByFilter={2}
+        actions={
+          <>
+            <Button variant="tertiary" size="md" startIcon={Archive}>封存</Button>
+            <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+          </>
+        }
+      />
+    )
+  },
+}
+
+// Hint banner via Alert primitive(擴 dataset 提示)— 對齊 ref 圖
+// hint banner 唯一 trigger condition:本頁全選 + 還有 dataset 沒選到
+export const WithExtendDatasetHint: Story = {
+  name: '提示擴選整個資料集',
+  render: () => {
+    const TOTAL = 5370
+    const VISIBLE = 50
+    const [selection, setSelection] = useState<string[]>(
+      Array.from({ length: VISIBLE }, (_, i) => `file-${i}`)
+    )
+    const [allSelected, setAllSelected] = useState(false)
+    // **NEW fix(2026-05-04)**:Alert 必跟著 selection.length 一起 hide,否則「清除選取項目」
+    // 後 selection=0 但 Alert 仍 render → 怪 state「已選取本頁全部 0 個」
+    return (
+      <div className="flex flex-col">
+        {selection.length > 0 && (
+        <Alert
+          variant="info"
+          placement="fixed"
+          dismissible={false}
+          title={
+            allSelected ? (
+              <>
+                已選取全部 {TOTAL} 個項目。{' '}
+                <button
+                  type="button"
+                  onClick={() => { setSelection([]); setAllSelected(false) }}
+                  className="text-primary hover:text-primary-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+                >
+                  清除選取項目
+                </button>
+              </>
+            ) : (
+              <>
+                已選取本頁全部 {selection.length} 個。{' '}
+                <button
+                  type="button"
+                  onClick={() => setAllSelected(true)}
+                  className="text-primary hover:text-primary-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+                >
+                  點此選取全部 {TOTAL} 個項目
+                </button>
+              </>
+            )
+          }
+        />
+        )}
+        {/* 2026-05-13 fix(user 抓 Alert「已選 5370」但 BulkActionBar 顯「已選 50」):
+            allSelected 時 totalSelected={TOTAL} 同步 count = 5370,標準 extend-dataset 慣用組合 */}
+        <BulkActionBar
+          selection={selection}
+          totalSelected={allSelected ? TOTAL : undefined}
+          onClear={() => { setSelection([]); setAllSelected(false) }}
+          actions={
+            <>
+              <Button variant="tertiary" size="md" startIcon={Download}>下載</Button>
+              <Button variant="tertiary" size="md" startIcon={Trash2} danger>刪除</Button>
+            </>
+          }
+        />
+      </div>
+    )
+  },
+}
+
+// 空 selection:回傳 null,不佔 layout
+export const EmptySelectionHidden: Story = {
+  name: '無選取時自動藏',
+  render: () => (
+    <div className="text-caption text-fg-muted">
+      selection=[] → BulkActionBar 回傳 null,<strong>不佔 layout</strong>(對齊禁止事項 #3)
+      <div className="mt-3 border border-dashed border-border-muted p-3">
+        <BulkActionBar selection={[]} actions={<Button variant="tertiary" size="md">Action</Button>} />
+        ↑ 這裡 BulkActionBar 完全不渲染
+      </div>
+    </div>
+  ),
+}