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

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

@@ -11,17 +11,16 @@ benchmark:
   - 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` 時浮現。
+選取多項 item(table row / list item)後浮現的批次操作列。**不獨立於選取狀態存在**——無選取時隱藏,有選取時浮現(完整判準含 `totalSelected` 反向選取例外,見「Extend dataset pattern」)。
 
-**Layout Family**:非 1-4 family — composite / multi-section(自 own layout,batch action 區 + count 區 + page-action 區 + hint banner)。
+**Layout Family**:非 1-4 family — composite / multi-section(自 own layout:clear 區 + count 區 + batch actions 區;**不含** page-level primary / 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 -->
+其 identity 由 selection lifecycle 決定：零選取時不存在，非零選取時呈現只作用於該 selection 的 actions；永遠顯示的 page toolbar 不屬於本 primitive。
 
 ---
 
@@ -53,41 +52,50 @@ benchmark:
 
 判斷:**「沒選取就消失嗎?」** 是 → 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)│
-└──────────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────────────┐
+│ [✕] [已選 {N} 項 · {M} 個被 filter 隱藏] │ [Action 1] [Action 2]   │
+│  ↑ clear  ↑ count + filter inline          ↑ batch actions(consumer)│
+└────────────────────────────────────────────────────────────────────┘
 ```
 
-- 全 sm Buttons(`same-row consistency`,close X 同 size)
+- 全 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)]`
-- 自然高度 52md / 60lg(對齊 SurfaceFooter / DataTable toolbar canonical)
-- `selection.length === 0` → 回 null 不佔 layout
+- 自然高度 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(2026-05-04 spec update,前版 sm 為錯);`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`)
+- **`actions`**:consumer 提供 **md** Buttons(size rationale 見「Size canonical」);**一律 `variant=tertiary`**(含 destructive — `Trash` 等 icon + label 已辨識危險)— **不用 primary、destructive 不上 danger 紅填色**(2026-07-17 user 拍板:批次刪除鈕點下去是**開確認 dialog**非直接刪,紅色強調留給 dialog 內確認最終不可逆 action;對齊 UX Movement / GitLab Pajamas「紅留給不可逆最終確認」+ button.spec.md「Inline destructive 不用高強調」)
+- **count 區**:`已選 {N} 項`(內建)+ inline filter hidden status `· {M} 個被 filter 隱藏`(`hiddenByFilter` prop 傳入時)
+- **clear**:`<Button iconOnly size=md variant=text dismiss />`(內建,觸發 `onClearSelection`)
 
 #### 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 -->
+| **default**(footer 浮層 / page-bottom 區段)| **md** | 與 DS Dialog footer commit 系及 page primary-button bar 共用 action measure |
 | **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 -->
+| **count(`已選 N 項`)** | `text-foreground` + `font-medium` | state-bearing 主資訊(user 在 selection mode + N items),非裝飾 → primary foreground；muted 化會弱化 state signal |
 | **`hiddenByFilter` suffix(`· M 個被 filter 隱藏`)** | `text-fg-muted` + `font-normal` | 次資訊,視覺層次低於 count |
 | **clear X icon** | dismiss md(自動 fg-muted)| chrome dismiss canonical |
 
@@ -111,7 +119,7 @@ BulkActionBar 是 plain block(無 positioning 邏輯),consumer 用 flex column
 </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 永遠保留。
+**為什麼撤 top-replace**:selection 期間若替換原 toolbar，filter / sort / search 會消失，像「先選 50 個、再 filter 出 status=error 子集」的 workflow 會斷裂。本 DS 採 additive composition，原 toolbar 永遠保留。
 
 ### Layout 行為(4 use case 全 covered by inline composition)
 
@@ -129,16 +137,19 @@ case 4 比較少見,consumer 知道自己 layout 時自加 wrapper 即可,DS pri
 ## API
 
 ```ts
-interface BulkActionBarProps {
-  /** 已選 ID,length === 0 時自動隱藏(回 null) */
+// extends HTMLAttributes:其餘 div 屬性(id / data-* / event handlers)spread 到 root
+interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 已選 ID;length === 0 且無 totalSelected 時自動隱藏(回 null,完整判準見「Extend dataset pattern」) */
   selection: readonly string[]
   /** Clear 觸發,user 點 X icon(consumer 在 page-level 監聽 Esc 觸發) */
-  onClear?: () => void
-  /** 批次 actions(consumer 提供 sm Button,variant=tertiary 或 tertiary+danger,不用 primary) */
+  onClearSelection?: () => void
+  /** 批次 actions(consumer 提供 md Button,一律 variant=tertiary,不用 primary / danger) */
   actions?: React.ReactNode
-  /** Filter 模式:hidden 數量,顯示在 count 區 inline 「{N} 已選 · {M} 個被 filter 隱藏」 */
+  /** Filter 模式:hidden 數量,顯示在 count 區 inline 「已選 {N} 項 · {M} 個被 filter 隱藏」 */
   hiddenByFilter?: number
-  /** i18n labels(Partial,merge with default;對齊 Material localeText / Polaris i18n 慣例) */
+  /** 擴選整個 dataset 後的真總數;number 時 count 顯示此值,否則 fallback selection.length(見「Extend dataset pattern」) */
+  totalSelected?: number | null
+  /** i18n labels(Partial,merge with exported canonical defaults) */
   labels?: Partial<BulkActionBarLabels>
   className?: string
 }
@@ -147,35 +158,52 @@ interface BulkActionBarLabels {
   count: (n: number) => string         // default 「已選 {n} 項」
   clear: string                         // default 「清除選取」(X aria-label)
   hiddenSuffix: (hidden: number) => string  // default 「· {hidden} 個被 filter 隱藏」
-  toolbarAriaLabel: string              // default 「批次操作」
+  ariaLabel?: string                    // root role="group" 的 aria-label(2026-07-06 新主 key;未傳 fallback toolbarAriaLabel)
+  /** @deprecated 2026-07-06 role 已降級 "group"(見 a11y 段),改用 ariaLabel;此 key 保留 backward-compat,值仍作 fallback。default 「批次操作」 */
+  toolbarAriaLabel: string
 }
 ```
 
-完整 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 -->
+完整 default labels 由 component 內 export `BULK_ACTION_BAR_DEFAULT_LABELS`,consumer 可 spread 後 override；單一 default object 避免 runtime 文案與文件範例各自漂移。
 
 **Hint banner(擴 dataset 提示)不在本 API**:由 consumer 用 `<Alert variant="info" placement="fixed">` 配 ReactNode title 帶 inline link 自組,黏在 BulkActionBar 上方。Alert / Notice 的 `title` + `description` 已支援 ReactNode(2026-04-28)。
 
+### 批次操作進行中(loading / 防重複提交 / 選取保留)
+
+`actions` 由 consumer 注入 ReactNode,**批次操作的非同步生命週期由 consumer 擁有**(BulkActionBar 是 stateless 呈現層,不介入 action 執行):
+
+- **Loading**:非同步 action(批次刪除 / 匯出)進行中,對應 action Button 傳 `loading`(既有 API,spinner + 自動 disabled)——不在 bar 內另加全域 spinner
+- **防重複提交**:同一批次操作進行中,consumer 對該 action Button 設 `loading` / `disabled` 阻止連點觸發多次(語義同 `../Field/form-validation.spec.md` double-submit 防護,但 owner 在 consumer 而非 bar)
+- **選取保留**:操作進行中 `selection` 維持不變、bar 持續可見;**成功**後才由 consumer 清空 `selection`(觸發 bar 自動隱藏),**失敗**則保留選取讓 user 重試
+
+這個 ownership 跟 `actions` 為 consumer-injected ReactNode 的 API 一致：bar 不知道 action promise，也不應另建第二套 async state。
+
+### Extend dataset pattern(totalSelected)
+
+「本頁全選 → hint 點擊 → 擴選整個 dataset」2-step 後,consumer 把 `totalSelected` 設為 dataset 真總數,count 區改顯示該值(否則 fallback `selection.length`)——避免 Alert 顯「已選 5370」但 bar 仍顯「已選 50」的不同步(2026-05-13 ship)。
+
+**可見性與反向選取(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 `"Bulk actions"`,可 override)
-- count 文字用 `aria-live="polite"` 通知 selection 變更(SR 讀「3 selected」)
-- Clear button:`aria-label="Clear selection"`
+- BulkActionBar 整體用 `role="group"` + `aria-label`(default `"批次操作"`,由 `labels.ariaLabel ?? labels.toolbarAriaLabel` 決定,可 override)。**降級 rationale(2026-07-06 user 拍板)**:原宣告 `role="toolbar"` 但未實作 APG toolbar 方向鍵 roving 契約(AT 告知「工具列」但方向鍵無反應 = 空承諾);改 `role="group"` 語意誠實,Tab 序照 DOM(見下)。
+- count 文字用 `aria-live="polite"` + `aria-atomic="true"`(selection 變更時 SR 整句重讀「已選 3 項」)
+- Clear button:`aria-label="清除選取"`
 - Hint banner 用 `role="status"` + `aria-live="polite"`(state 切換時通知)
-- 鍵盤:Esc → `onClear()`(consumer 應監聽 page-level keydown 觸發);Tab 序按 actions → count → clear
+- 鍵盤:Esc → `onClearSelection()`(consumer 應監聽 page-level keydown 觸發);Tab 序按 DOM 順序 = clear(X)→ actions(count 是純文字 span,非互動元素 → 不參與 Tab)
 - Disabled action(無權限等)用 Button `disabled` + tooltip 解釋,**不藏 action**(避免 user 困惑)
 
 ---
 
 ## 視覺與動畫
 
-- **出現 / 消失**:`selection.length` 0→>0 時 fade in;>0→0 時 fade out（animation timing — see motion canonical, not invariant）。**不 layout shift**(預留位置或 absolute / fixed)
-- **底色**:**無底色 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)— Top 模式跟 toolbar 共位置;Footer 模式 **`border-top` border-divider 切割 layout**(因 footer 是 page 結構,不是 floating overlay,不用 box-shadow 製造「浮層」誤導)
-- **與 table 的關係**:Top scenario 跟 toolbar 共邊;Footer scenario 是 page 結構性 footer,純 border-top 切
-- **Action variant**:`tertiary`(主)+ `tertiary danger`(destructive)— **不用 primary**(留給 dialog 確認最終 action)
-- **respects `motion-reduce`**:fade 動畫 disable
+- **出現 / 消失**:有選取(`selection.length > 0` **或** `totalSelected > 0`)直接 mount;歸零回 null 直接 unmount(無 fade 動畫)。inline composition 下自然 reflow;consumer 需固定高度時自擺 placeholder(見「禁止事項」)
+- **底色**:**無底色 contrast**,跟 page 同色(`bg-canvas` / `bg-surface` 視 placement 繼承)。Selection mode 由 count、clear 與 actions 的內容變化表達，不另用底色製造第二個狀態訊號。
+- **邊界**:**無外框邊界**(融入 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`**(含 destructive,icon+label 辨識危險)— **不用 primary、不用 danger 紅填色**(紅色強調留給 dialog 內確認最終 action,見「Slot」rationale)
 
 ---
 
@@ -186,7 +214,7 @@ interface BulkActionBarLabels {
 - ❌ 不在 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)
+- ❌ 批次 action **不用 `variant="primary"` 或 `danger`**(留給 dialog 內最終不可逆 action);批次 destructive 仍用 `tertiary`,由 Trash icon + 動作文字表達語意(對齊上方 Slot / Action variant canonical)
 - ❌ 不用 contrast 底色 / box-shadow 製造「浮層」感(footer 是 layout 結構切割,不是 overlay)
 - ❌ Hint banner 不在「全可見已選 + dataset 還有更多」之外的場景顯示(小 dataset 顯示 hint 是 noise)
 - ❌ Filter hidden status 不獨立開 hint banner(進主 bar count 區 inline 即可)

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

@@ -0,0 +1,124 @@
+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/展示',
+  tags: ['autodocs'],
+  component: BulkActionBar,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '在使用者選取多筆資料後顯示選取數量與批次操作，並可清除選取。表格或清單進入批次處理狀態時使用，動作一律維持次要視覺重量。' } },
+  },
+}
+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}
+        onClearSelection={() => 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}>刪除</Button>
+          </>
+        }
+      />
+    )
+  },
+}
+
+// @story-history: WithFilterHidden(selection=3 + hiddenByFilter=2)retired 2026-07-17 per audit Dim 24 —
+//   principles.stories.tsx HintBannerRule 第三 Rule 已用同情境(selection 3 + hiddenByFilter=2)且多教「filter hidden
+//   inline 進 count 區、不開 hint banner」規則;展示版無新增約束(earn-existence 2-test 雙 NO)→ retire。
+//   hiddenByFilter inline 呈現 canonical home = principles HintBannerRule。
+
+// 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}
+          onClearSelection={() => { setSelection([]); setAllSelected(false) }}
+          actions={
+            <>
+              <Button variant="tertiary" size="md" startIcon={Download}>下載</Button>
+              <Button variant="tertiary" size="md" startIcon={Trash2}>刪除</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">封存</Button>} />
+        ↑ 這裡 BulkActionBar 完全不渲染
+      </div>
+    </div>
+  ),
+}

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

@@ -7,12 +7,12 @@ import { ButtonDivider } from '@/design-system/components/Button/button-group'
 // ── 消費的 SSOT ───────────────────────────────────────────────────────────────
 // - bulk-action-bar.spec.md(本元件 SSOT)
 // - DataTable/data-table.spec.md「L2 選取」(整合方式)
-// - button.spec.md + button-group.tsx(action variant=tertiary,size=sm,
+// - button.spec.md + button-group.tsx(action variant=tertiary,size=md,
 //   gap-2 + ButtonDivider 自帶 mx-1 = 12px 視覺距離)
-// - inline-action.spec.md「same-row consistency rule」(close X 同尺寸 sm)
+// - inline-action.spec.md「same-row consistency rule」(close X 同尺寸 md)
 // - tokens/layoutSpace/layoutSpace.spec.md(footer 用 px-loose py-tight)
 // - patterns/overlay-surface/overlay-surface.spec.md SurfaceFooter canonical
-// - Alert(banner)用 description ReactNode 帶 inline link CTA
+// - Alert(banner)用 title ReactNode 帶 inline link CTA
 
 // ── i18n labels ─────────────────────────────────────────────────────────────
 
@@ -21,7 +21,10 @@ export interface BulkActionBarLabels {
   count: (n: number) => string
   clear: string
   hiddenSuffix: (hidden: number) => string
+  /** @deprecated 2026-07-06 role 已降級 "group"(user 拍板),改用 `ariaLabel`;此 key 保留 backward-compat(值仍作 fallback)。 */
   toolbarAriaLabel: string
+  /** root `role="group"` 的 aria-label(2026-07-06 新名;未傳 fallback toolbarAriaLabel)。 */
+  ariaLabel?: string
 }
 
 // code-quality-allow: dead-export — public API per spec.md(consumer spread + override)
@@ -38,10 +41,10 @@ export interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement>
   /** 已選 ID,length === 0 時自動隱藏(回傳 null) */
   selection: readonly string[]
   /** Clear 觸發,user 點 X icon 或 Esc(consumer 在 page-level 監聽) */
-  onClear?: () => void
-  /** 批次 actions(consumer 提供 sm Button,variant=tertiary 或 tertiary+danger;不用 primary) */
+  onClearSelection?: () => void
+  /** 批次 actions(consumer 提供 md Button,一律 variant=tertiary；不用 primary/danger) */
   actions?: React.ReactNode
-  /** Filter 模式:hidden 數量,顯示在 count 區 inline「{N} 已選 · {M} 個被 filter 隱藏」 */
+  /** Filter 模式:hidden 數量,顯示在 count 區 inline「已選 {N} 項 · {M} 個被 filter 隱藏」 */
   hiddenByFilter?: number
   /**
    * 「擴選整個 dataset」狀態(2026-05-13 ship,per user 抓 Alert「已選 5370」但 BulkActionBar
@@ -63,18 +66,18 @@ export interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement>
 // 視覺結構(同 SurfaceFooter / DataTable toolbar canonical):
 //   px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]
 //   gap-2 between elements
-//   全 sm Buttons(same-row consistency)
+//   全 md Buttons(same-row consistency)
 //   <ButtonDivider /> 自帶 mx-1 = 12px 視覺距離
 //
 // Hint banner(擴 dataset 提示)完全外包給 Alert 元件 — consumer 視 ref 圖
 // 黏在 BulkActionBar 上方/下方,用 Alert variant="info" placement="fixed"
-// description={inline link JSX}。BulkActionBar 自己不再有 hint banner slot。
+// title={inline link JSX}。BulkActionBar 自己不再有 hint banner slot。
 //
 // 浮起 / fixed positioning 由 consumer wrap 決定(BulkActionBar 不限定 placement)。
 
 const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
   function BulkActionBar(
-    { selection, onClear, actions, hiddenByFilter, totalSelected, labels: labelsOverride, className, ...props },
+    { selection, onClearSelection, actions, hiddenByFilter, totalSelected, labels: labelsOverride, className, ...props },
     ref
   ) {
     const labels: BulkActionBarLabels = React.useMemo(
@@ -82,14 +85,18 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
       [labelsOverride]
     )
 
-    // selection.length === 0 自動藏(對齊 spec 禁止事項 #3)
-    if (selection.length === 0) return null
+    // selection.length === 0 自動藏(對齊 spec 禁止事項 #3)。
+    // 反向選取(DataTable all 模式)例外:visible 全被 excluded 但 totalSelected>0 仍有選取 → 顯示(2026-06-22)
+    if (selection.length === 0 && (totalSelected ?? 0) === 0) return null
 
     return (
       <div
         ref={ref}
-        role="toolbar"
-        aria-label={labels.toolbarAriaLabel}
+        // 2026-07-06 user 拍板:role "toolbar" → "group" — 原宣告 toolbar 但未實作 APG toolbar
+        // 方向鍵 roving 契約(AT 告知「工具列」但方向鍵無反應 = 空承諾);group 語意誠實,
+        // Tab 序照 DOM(spec 本有 canonical),Gmail / Linear bulk bar 實務同款。
+        role="group"
+        aria-label={labels.ariaLabel ?? labels.toolbarAriaLabel}
         className={cn(
           'flex items-center gap-2',
           'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
@@ -102,7 +109,7 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
         {/* X close — md dismiss(2026-05-04 spec update:default placement = footer variant,
             visual weight 對齊 Dialog footer commitment buttons md;same-row consistency 維持)
             未來若有 top-toolbar variant(覆蓋 sm-density toolbar)→ 該 variant override sm */}
-        {onClear && (
+        {onClearSelection && (
           <Button
             variant="text"
             size="md"
@@ -110,7 +117,7 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
             dismiss
             startIcon={X}
             aria-label={labels.clear}
-            onClick={onClear}
+            onClick={onClearSelection}
           />
         )}
 
@@ -119,7 +126,8 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
             理由:count 是 state-bearing 主資訊(「你在 selection mode + N items」),非裝飾
             World-class 共識:Linear/Notion/Carbon/Polaris 均用 primary foreground;muted 化弱化 state signal
             hiddenByFilter suffix 維持 muted(這是次資訊,視覺層次正確) */}
-        <span className="text-body text-foreground tabular-nums">
+        {/* 2026-05-31 #3:aria-live 通知 SR 選取數變更;#20:補 font-medium 對齊 spec「Count text color canonical」表 + 上方 comment(state-bearing 主資訊) */}
+        <span className="text-body text-foreground font-medium tabular-nums" aria-live="polite" aria-atomic="true">
           {/* 2026-05-13:totalSelected override 走 dataset 擴選後真總數,否則 fallback page-level selection.length */}
           {labels.count(typeof totalSelected === 'number' ? totalSelected : selection.length)}
           {hiddenByFilter !== undefined && hiddenByFilter > 0 && (
@@ -130,7 +138,7 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
         {/* divider */}
         {actions && <ButtonDivider />}
 
-        {/* batch actions slot(consumer 提供 sm Buttons) */}
+        {/* batch actions slot(consumer 提供 md Buttons) */}
         {actions && (
           <div className="flex items-center gap-2 flex-1 min-w-0">{actions}</div>
         )}
@@ -148,7 +156,7 @@ export const bulkActionBarMeta = {
   sizes: {},
   states: ['default'],
   tokens: {
-    fg: ['text-fg-secondary', 'text-fg-muted'],
+    fg: ['text-foreground', 'text-fg-muted'],
     border: ['border-divider'],
   },
 } as const

package/src/components/BulkActionBar/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 './bulk-action-bar'

package/src/components/Button/button-group.tsx

@@ -23,14 +23,14 @@ import { ButtonGroupContext } from './button'
  * </ButtonGroup>
  *
  * // 垂直排列（fullWidth 自動套用）
- * <ButtonGroup direction="vertical">
+ * <ButtonGroup orientation="vertical">
  *   <Button variant="primary">確認</Button>
  *   <Button variant="tertiary">取消</Button>
  * </ButtonGroup>
  */
 interface ButtonGroupProps extends React.HTMLAttributes<HTMLDivElement> {
   /** 排列方向，預設 horizontal */
-  direction?: 'horizontal' | 'vertical'
+  orientation?: 'horizontal' | 'vertical'
   /** 水平對齊，預設 start */
   align?: 'start' | 'center' | 'end'
 }
@@ -40,8 +40,8 @@ const BUTTON_GROUP_CTX_VERTICAL = { fullWidth: true } as const
 const BUTTON_GROUP_CTX_HORIZONTAL = { fullWidth: false } as const
 
 const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
-  ({ direction = 'horizontal', align = 'start', className, children, ...props }, ref) => {
-    const isVertical = direction === 'vertical'
+  ({ orientation = 'horizontal', align = 'start', className, children, ...props }, ref) => {
+    const isVertical = orientation === 'vertical'
 
     return (
       <ButtonGroupContext.Provider value={isVertical ? BUTTON_GROUP_CTX_VERTICAL : BUTTON_GROUP_CTX_HORIZONTAL}>
@@ -64,10 +64,37 @@ const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
 )
 ButtonGroup.displayName = 'ButtonGroup'
 
+export interface ButtonDividerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 群組排列方向。橫排群組畫直線（預設），直排群組畫橫線。寫死方向會讓
+   * `<ButtonGroup orientation="vertical">` 出現方向錯誤的線。
+   */
+  orientation?: 'horizontal' | 'vertical'
+  /**
+   * 是否對輔助科技宣告語意。預設 `true`（純視覺）→ `role="none"`，與 Separator primitive
+   * 預設一致（separator.spec.md:102「純視覺分隔，SR 不朗讀」）。動作群組的分組語意已由排列
+   * 順序與間距表達，線本身不切分內容，故不朗讀。
+   */
+  decorative?: boolean
+}
+
 /**
- * ButtonDivider — 按鈕群組內的分隔線
+ * ButtonDivider — action region 群組分隔線
+ *
+ * **幾何 SSOT** → `patterns/action-bar/action-bar.spec.md`「分隔線幾何」：
+ * 線長 = 所在那一列**最高元件**的高度 − `--action-divider-inset`（8px），不短於
+ * `--action-divider-min`（16px），垂直置中。
  *
- * 自身左右各 4px，與相鄰按鈕形成 8px（gap）+ 4px（自身）= 12px 的視覺距離。
+ * 兩層構造是必要的而非包裝：外層 `self-stretch` 取「該列最高元件」當基準——同一列的每條線
+ * 因此必然等長、不會參差；內層畫線並套 inset 與地板，置中由外層 `items-center` 負責，所以
+ * 地板生效時線仍置中。單層寫法（`self-stretch` + `min-h`）會被釘在行首，地板一啟動線就歪掉。
+ * 外層佔位與舊寫法完全相同，改動不位移任何同列元素。
+ *
+ * **前提**：必須放在自動高度的 cluster 內。直接置於固定高度容器（如 48px chrome header）時
+ * 基準會退化成容器高——CSS 無法在容器有明確高度時看見「最高手足」。由
+ * `scripts/test-action-divider-placement.mjs` 機械把關。
+ *
+ * **水平間距**：自身兩端各 4px，與 `gap-2` 容器合成 12px 視覺距離。
  *
  * @example
  * <ButtonGroup>
@@ -76,21 +103,37 @@ ButtonGroup.displayName = 'ButtonGroup'
  *   <Button variant="primary" danger size="sm" iconOnly startIcon={Trash2} aria-label="刪除" />
  * </ButtonGroup>
  */
-const ButtonDivider = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => (
-  <div
-    ref={ref}
-    role="separator"
-    className={cn(
-      'self-stretch w-px mx-1 my-1',
-      'bg-divider',
-      className,
-    )}
-    {...props}
-  />
-))
+const ButtonDivider = React.forwardRef<HTMLDivElement, ButtonDividerProps>(
+  ({ className, orientation = 'vertical', decorative = true, ...props }, ref) => {
+    const isVertical = orientation === 'vertical'
+    return (
+      <div
+        ref={ref}
+        role={decorative ? 'none' : 'separator'}
+        aria-orientation={decorative ? undefined : orientation}
+        data-orientation={orientation}
+        // 穩定標記:讓像素量測(scripts/measure-action-dividers.mjs)只鎖 action region 群組線,
+        // 不會誤抓版面切分家族(DataTable 欄界 / 欄寬把手 / Steps connector — 那些不適用本幾何)。
+        data-action-divider=""
+        className={cn(
+          'flex shrink-0 self-stretch',
+          isVertical ? 'w-px mx-1 items-center' : 'h-px my-1 justify-center',
+          className,
+        )}
+        {...props}
+      >
+        <div
+          className={cn(
+            'bg-divider',
+            isVertical
+              ? 'w-px h-[calc(100%-var(--action-divider-inset))] min-h-[var(--action-divider-min)]'
+              : 'h-px w-[calc(100%-var(--action-divider-inset))] min-w-[var(--action-divider-min)]',
+          )}
+        />
+      </div>
+    )
+  },
+)
 ButtonDivider.displayName = 'ButtonDivider'
 
 export { ButtonGroup, ButtonDivider }