@qijenchen/design-system 0.1.0-beta.74 → 0.1.0-beta.75

package/src/components/DataTable/data-table.principles.stories.tsx

@@ -71,13 +71,13 @@ export const UsageGuidance: Story = {
       <p>適合 DataTable 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/DataTable/展示" name="數字靠右對齊"><span className="text-primary hover:underline font-medium cursor-pointer">商品庫存後台 — 單價 / 金額數字靠右對齊</span></LinkTo>
+          <LinkTo kind="Design System/Components/DataTable/展示" name="數字靠右對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品庫存後台 — 單價 / 金額數字靠右對齊</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DataTable/展示" name="自動行高"><span className="text-primary hover:underline font-medium cursor-pointer">商品備註長短不一 — 自動行高撐開列高</span></LinkTo>
+          <LinkTo kind="Design System/Components/DataTable/展示" name="自動行高"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品備註長短不一 — 自動行高撐開列高</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DataTable/展示" name="空狀態"><span className="text-primary hover:underline font-medium cursor-pointer">目錄尚無商品 — 空狀態引導新增</span></LinkTo>
+          <LinkTo kind="Design System/Components/DataTable/展示" name="空狀態"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">目錄尚無商品 — 空狀態引導新增</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>

package/src/components/DataTable/data-table.spec.md

@@ -263,18 +263,24 @@ DataTable 的 row selection layer。提供 controlled/uncontrolled state + 視
 
 **世界級對照**:Material DataGrid `rowSelectionModel` / Polaris IndexTable `selectedResources` / Linear / Notion 全 controlled-first + uncontrolled fallback。AG Grid 的 imperative `gridRef.api` 不採(違背 React idiom + 既有 Field/Switch/Checkbox controllable 慣例)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-### 一、State 模式
+### 一、State 模式(discriminated union,2026-06-22 支援反向選取 inverted)
 
 ```ts
-selection?: string[]                  // controlled
-defaultSelection?: string[]           // uncontrolled
-onSelectionChange?: (ids: string[]) => void
-selectable?: boolean | 'single' | 'multi'  // default 'multi'
+// 選取模型:include(列舉)/ all(反向,全集 − excluded)
+type DataTableSelection =
+  | { mode: 'include'; ids: string[] }     // 只選 ids 列(預設)
+  | { mode: 'all'; excluded: string[] }    // 全資料集(filter 後)選取,扣掉 excluded
+
+selection?: string[] | DataTableSelection         // controlled;傳 string[] = include shorthand(向後相容)
+defaultSelection?: string[] | DataTableSelection  // uncontrolled
+onSelectionChange?: (next: DataTableSelection) => void  // 一律 emit union
+totalCount?: number                   // 全集筆數 M(server-side / filter 後);all 模式計數用
+selectable?: boolean | 'single' | 'multi'  // default 'multi';single 永遠 include
 isRowSelectable?: (row: TData) => boolean
 preserveSelectionOnFilter?: boolean   // default false
 ```
 
-對齊 `useControllableState` idiom(Field / Switch / Checkbox 已用)。
+對齊 `useControllableState` idiom(Field / Switch / Checkbox 已用)+ MUI X DataGrid v8 `rowSelectionModel { type:'include'|'exclude', ids }` / AG Grid `selectAll + toggledNodes` 反向選取共識。**計數(consumer)**:`mode==='all' ? totalCount − excluded.length : ids.length`。**向後相容**:傳 `string[]` 自動正規化為 `{ mode:'include' }`;但 `onSelectionChange` 一律 emit union(consumer 讀取端需處理兩 mode)。
 
 ### 二、Checkbox column
 
@@ -283,15 +289,16 @@ preserveSelectionOnFilter?: boolean   // default false
 - **顯示時機**:**always visible**(對齊 Linear 2024 / Polaris / Material consensus,不允 hover-show) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Header tri-state**:none / indeterminate / all,使用既有 Checkbox `indeterminate` prop
 
-### 三、全選邏輯(2-step pattern)
+### 三、全選邏輯(2-step pattern + 反向選取 inverted)
 
-對齊 ref 圖 + Linear / Gmail / Notion canonical: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+對齊 ref 圖 + Linear / Gmail / Notion 2-step + MUI X v8 / AG Grid inverted: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-1. Header checkbox click(none → all)→ 選**目前可見** rows(filter 後 visible-only)
-2. 全頁可見已選 → BulkActionBar 顯示 hint:「已選取本頁 N 個。**點此選取全部 M 個**」
-3. 點 hint → 擴 dataset 全選,hint 改:「已選取全部 M 個。**清除選取項目**」
+1. Header checkbox click(none → all)→ 選**目前可見** rows(filter 後 visible-only)= `{ mode:'include', ids:[…visible] }`
+2. 全頁可見已選 → BulkActionBar hint:「已選取本頁 N 個。**點此選取全部 M 個**」
+3. 點 hint → consumer `setSelection({ mode:'all', excluded:[] })` 擴 dataset 全選,hint 改:「已選取全部 M 個。**清除選取項目**」
+4. **反向選取(inverted)**:all 模式下取消勾選某幾筆 → 加進 `excluded`(`選取 = 全集 − excluded`);再勾回 → 移出 `excluded`。對 10k 筆只載 50 筆**不需列舉其餘 ID**,任意 toggle 順序封閉、O(1)。count = `totalCount − excluded.length`,hint 顯示「已選取全部 M 個(排除 K 個)」。
 
-不直接擴 dataset(避免誤觸大量資料)。
+不**一鍵**直接擴 dataset(避免誤觸大量資料,必先 2-step);擴選後的反向扣除由 inverted 模型自動處理。
 
 ### 四、互動
 
@@ -308,9 +315,10 @@ preserveSelectionOnFilter?: boolean   // default false
 
 ### 六、Selection × filter / sort 互動
 
-- **filter 套用 → filtered-out 的 selected rows 預設清掉**(對齊 Material / AG Grid / Polaris / GitHub / Gmail consensus) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **opt-in `preserveSelectionOnFilter={true}`** → 給 productivity scope(Linear / Airtable 用法),保留 hidden selected,BulkActionBar 顯示「{visible} selected ({hidden} hidden by filter)」
-- sort 套用 → selection 全保留(sort 不影響可見性)
+- **`include` 模式**:filter 套用 → filtered-out 的 selected rows 預設清掉(對齊 Material / AG Grid / Polaris / GitHub / Gmail consensus) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **`all`(反向)模式**:語意 = 「全部**符合當前 filter**的列 − excluded」→ filter 變動時 selection set 隨 filter **自然重算**(M 跟著變),`excluded` 保留不清(被 filter 掉的 excluded 列無害,回到該 filter 時仍排除);**不**套用上面的 include-mode 清除。consumer 計數用更新後的 `totalCount`。
+- **opt-in `preserveSelectionOnFilter={true}`**(僅 include 模式)→ 給 productivity scope(Linear / Airtable 用法),保留 hidden selected,BulkActionBar 顯示「{visible} selected ({hidden} hidden by filter)」
+- sort 套用 → selection 全保留(sort 不影響可見性,兩 mode 同)
 
 ### 七、BulkActionBar 整合(inline composition canonical)
 

package/src/components/DataTable/data-table.stories.tsx

@@ -4,7 +4,7 @@ import React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { createColumnHelper, type ColumnDef } from '@tanstack/react-table'
 import { Pencil, Trash2, MoreVertical, Search, Filter, Eye, Download, Plus, ArrowUpDown } from 'lucide-react'
-import { DataTable } from './data-table'
+import { DataTable, type DataTableSelection } from './data-table'
 import { DataTableSortManager } from './data-table-sort-manager'
 import { DataTableColumnVisibilityPanel } from './data-table-column-visibility-panel'
 import { DataTableFilterPanel, evaluateTree, createEmptyFilterTree, isFilterTreeActive, type FilterTree } from './data-table-filter-panel'
@@ -948,8 +948,7 @@ export const WithBulkActions: Story = {
   name: '選取 + 批次操作',
   parameters: { layout: 'fullscreen' },
   render: () => {
-    const [selection, setSelection] = React.useState<string[]>([])
-    const [allSelected, setAllSelected] = React.useState(false)
+    const [selection, setSelection] = React.useState<DataTableSelection>({ mode: 'include', ids: [] })
     const [search, setSearch] = React.useState('')
     const [columnVisibility, setColumnVisibility] = React.useState<Record<string, boolean>>({})
     // Issue 3(2026-05-10):columnSearch 移到 `<DataTableColumnVisibilityPanel>` 內 own,
@@ -968,13 +967,16 @@ export const WithBulkActions: Story = {
       [search]
     )
     const VISIBLE = filteredData.length
-    // **NEW fix(2026-05-04)**:showHint 必含 selection.length > 0 前提,否則「清除選取」後 allSelected
-    // 還是 true 邏輯走「: true」branch → Alert 仍 render「已選取全部 N 個」 → 怪 state
-    const showHint = selection.length > 0 && (
-      !allSelected
-        ? selection.length === VISIBLE && VISIBLE > 0 && TOTAL > VISIBLE
-        : true
-    )
+    // 反向選取(inverted)showcase:include 全可見已選且 dataset 更大 → offer「選取全部 M」;
+    // all 模式 → 顯示「已選取全部 M(排除 K)」。count = M − excluded(consumer 端計算)。
+    const isAll = selection.mode === 'all'
+    const visibleIds = filteredData.map((p) => p.sku)
+    const selectedCount = isAll ? TOTAL - selection.excluded.length : selection.ids.length
+    const visibleSelectedIds = isAll
+      ? visibleIds.filter((id) => !selection.excluded.includes(id))
+      : selection.ids.filter((id) => visibleIds.includes(id))
+    const allVisibleSelected = VISIBLE > 0 && visibleSelectedIds.length === VISIBLE
+    const showHint = isAll || (allVisibleSelected && TOTAL > VISIBLE)
 
     return (
       // 撐滿 parent(layout=fullscreen);
@@ -1068,6 +1070,7 @@ export const WithBulkActions: Story = {
             selectable
             selection={selection}
             onSelectionChange={setSelection}
+            totalCount={TOTAL}
             columnVisibility={columnVisibility}
             onColumnVisibilityChange={setColumnVisibility}
             getRowId={(row) => row.sku}
@@ -1092,7 +1095,7 @@ export const WithBulkActions: Story = {
 
         {/* 底部 chrome group(撤回前一版 absolute overlay,2026-05-04 user 抓 BulkActionBar 沒底色 + 蓋表底列 regression):
             回 flex flow 自然推 table。Q7 mount-time growth 真因 = virtualizer estimateRowHeight ≠ token,已在 DataTable 內修(estimate size-aware) */}
-        {(showHint || selection.length > 0) && (
+        {(showHint || selectedCount > 0) && (
           <div className="flex flex-col">
             {showHint && (
               <Alert
@@ -1100,24 +1103,24 @@ export const WithBulkActions: Story = {
                 placement="fixed"
                 dismissible={false}
                 title={
-                  allSelected ? (
+                  isAll ? (
                     <>
-                      已選取全部 {TOTAL} 個項目。{' '}
+                      已選取全部 {TOTAL} 個項目{selection.excluded.length > 0 ? `(排除 ${selection.excluded.length} 個)` : ''}。{' '}
                       <button
                         type="button"
-                        onClick={() => { setSelection([]); setAllSelected(false) }}
-                        className="text-primary hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+                        onClick={() => setSelection({ mode: 'include', ids: [] })}
+                        className="text-primary hover:text-primary-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
                       >
                         清除選取項目
                       </button>
                     </>
                   ) : (
                     <>
-                      已選取本頁全部 {selection.length} 個。{' '}
+                      已選取本頁全部 {selectedCount} 個。{' '}
                       <button
                         type="button"
-                        onClick={() => setAllSelected(true)}
-                        className="text-primary hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+                        onClick={() => setSelection({ mode: 'all', excluded: [] })}
+                        className="text-primary hover:text-primary-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
                       >
                         點此選取全部 {TOTAL} 個項目
                       </button>
@@ -1126,10 +1129,11 @@ export const WithBulkActions: Story = {
                 }
               />
             )}
-            {selection.length > 0 && (
+            {selectedCount > 0 && (
               <BulkActionBar
-                selection={selection}
-                onClear={() => { setSelection([]); setAllSelected(false) }}
+                selection={visibleSelectedIds}
+                totalSelected={selectedCount}
+                onClear={() => setSelection({ mode: 'include', ids: [] })}
                 actions={
                   <>
                     <Button variant="tertiary" size="md" startIcon={Download}>下載</Button>
@@ -1165,7 +1169,7 @@ export const SelectionKeyboardAndShift: Story = {
           height="400px"
           selectable
           selection={selection}
-          onSelectionChange={setSelection}
+          onSelectionChange={(s) => setSelection(s.mode === 'include' ? s.ids : [])}
           getRowId={(row) => row.sku}
         />
       </div>
@@ -1192,7 +1196,7 @@ export const SelectionSingleMode: Story = {
           height="auto"
           selectable="single"
           selection={selection}
-          onSelectionChange={setSelection}
+          onSelectionChange={(s) => setSelection(s.mode === 'include' ? s.ids : [])}
           getRowId={(row) => row.sku}
         />
       </div>
@@ -1216,7 +1220,7 @@ export const SelectionDisabledRows: Story = {
           height="auto"
           selectable
           selection={selection}
-          onSelectionChange={setSelection}
+          onSelectionChange={(s) => setSelection(s.mode === 'include' ? s.ids : [])}
           getRowId={(row) => row.sku}
           isRowSelectable={(row) => row.stock !== 'Out of stock'}
         />
@@ -1819,7 +1823,7 @@ export const RoadmapAllInOne: Story = {
             inlineEdit
             selectable
             selection={selection}
-            onSelectionChange={setSelection}
+            onSelectionChange={(s) => setSelection(s.mode === 'include' ? s.ids : [])}
             columnVisibility={columnVisibility}
             onColumnVisibilityChange={setColumnVisibility}
             pinnedLeftColumns={['id']}

package/src/components/DataTable/data-table.tsx

@@ -134,12 +134,14 @@ export interface DataTableProps<TData>
   spreadsheetMode?: boolean
 
   // ── L2 Selection(see data-table.spec.md「L2 選取」)──
-  /** 已選 row IDs(controlled) */
-  selection?: string[]
-  /** 預設選取(uncontrolled) */
-  defaultSelection?: string[]
-  /** Selection 變更 callback */
-  onSelectionChange?: (next: string[]) => void
+  /** 已選列(controlled)。傳 string[] = include shorthand;傳 DataTableSelection 支援反向選取(all + excluded) */
+  selection?: string[] | DataTableSelection
+  /** 預設選取(uncontrolled);同上接受 string[] 或 DataTableSelection */
+  defaultSelection?: string[] | DataTableSelection
+  /** Selection 變更 callback(emit DataTableSelection union;include / all 兩模型) */
+  onSelectionChange?: (next: DataTableSelection) => void
+  /** 全資料集筆數 M(server-side / filter 後);all 模式 count = totalCount − excluded.length(consumer 計算) */
+  totalCount?: number
   /** 是否啟用 selection / 模式;true 等同 'multi' */
   selectable?: boolean | 'single' | 'multi'
   /** Row 是否可選(disabled rows 只 disable checkbox,row 內容正常 render) */
@@ -264,6 +266,48 @@ const cellEditId = (rowId: string, colId: string) => `${rowId}__${colId}`
 //   (詳 ./data-table.css)— consumer 可走 CSS override 改值,不再 hard-code in TS。
 // L2 selection 內部 column id(避免 magic string 重複)
 const SELECT_COL_ID = '__select__'
+
+/**
+ * L2 選取模型(discriminated union,2026-06-22 對齊 MUI X DataGrid v8
+ * rowSelectionModel { type: include | exclude, ids } + AG Grid selectAll + toggledNodes)。
+ *
+ * - mode==='include' (ids):只選 ids 列(預設;= 載入/可見列逐一選取)。
+ * - mode==='all' (excluded):全資料集(filter 後)選取,扣掉 excluded —— 反向選取(inverted)。
+ *   解決「全選 10k 筆只載 50 筆 → 無法列舉其餘 ID」:all 模式「選取 = 全集 − excluded」,
+ *   任何 toggle 都只是 excluded 的 add/remove,對任意順序封閉、O(1)、不需列舉未載入 ID。
+ *
+ * 計數(consumer):mode==='all' ? totalCount − excluded.length : ids.length(需傳 totalCount)。
+ * 進入 all 模式:consumer 在「選取全部 M」hint 點擊時 setSelection({ mode: 'all', excluded: [] })。
+ */
+export type DataTableSelection =
+  | { mode: 'include'; ids: string[] }
+  | { mode: 'all'; excluded: string[] }
+
+// 正規化:string[] shorthand → { mode:'include' }(向後相容既有 consumer 傳 ID 陣列)
+function normalizeSelection(
+  input: string[] | DataTableSelection | undefined,
+): DataTableSelection | undefined {
+  if (input === undefined) return undefined
+  if (Array.isArray(input)) return { mode: 'include', ids: input }
+  return input
+}
+
+// union-aware「把 ids 設成 willSelect 狀態」純函式(對任意 toggle 順序封閉)
+function applySelectIds(
+  sel: DataTableSelection,
+  ids: string[],
+  willSelect: boolean,
+): DataTableSelection {
+  if (sel.mode === 'include') {
+    const set = new Set(sel.ids)
+    ids.forEach((id) => { if (willSelect) set.add(id); else set.delete(id) })
+    return { mode: 'include', ids: Array.from(set) }
+  }
+  // all 模式:選取 = 全集 − excluded → willSelect 移出 excluded;取消選取 加進 excluded
+  const set = new Set(sel.excluded)
+  ids.forEach((id) => { if (willSelect) set.delete(id); else set.add(id) })
+  return { mode: 'all', excluded: Array.from(set) }
+}
 const cellPadding: React.CSSProperties = { paddingBlock: 'var(--table-cell-py)', paddingInline: 'var(--table-cell-px)' }
 const HEADER_BG = 'bg-muted'
 
@@ -774,6 +818,7 @@ function DataTableInner<TData>(
     estimateRowHeight, tableOptions, rowActions, cellErrors,
     pinnedLeftColumns, pinnedRightColumns, inlineEdit = false,
     selection: selectionProp, defaultSelection, onSelectionChange,
+    totalCount,
     selectable = false, isRowSelectable, getRowId, getRowAriaLabel,
     preserveSelectionOnFilter = false,
     columnVisibility: columnVisibilityProp, defaultColumnVisibility, onColumnVisibilityChange,
@@ -887,9 +932,9 @@ function DataTableInner<TData>(
   // ── L2 Selection state ──
   const enabled = selectable !== false
   const mode = selectable === 'single' ? 'single' : 'multi'
-  const [selection, setSelection] = useControllable<string[]>({
-    value: selectionProp,
-    defaultValue: defaultSelection ?? [],
+  const [selection, setSelection] = useControllable<DataTableSelection>({
+    value: normalizeSelection(selectionProp),
+    defaultValue: normalizeSelection(defaultSelection) ?? { mode: 'include', ids: [] },
     onChange: onSelectionChange,
   })
   // Shift-click anchor:存最後一次「單擊」的 row id,shift-click 時做區間選
@@ -1381,7 +1426,7 @@ function DataTableInner<TData>(
       // 內部 checkbox/radio 用 stopPropagation 避免 double-fire
       const onCellClick = isDisabled ? undefined : (e: React.MouseEvent) => {
         e.stopPropagation()
-        if (mode === 'single') setSelection([rowId])
+        if (mode === 'single') setSelection({ mode: 'include', ids: [rowId] })
         else toggleRow(rowId, rowOriginal, { shiftKey: e.shiftKey })
       }
       return (
@@ -1408,7 +1453,7 @@ function DataTableInner<TData>(
           ) : (
             <Checkbox
               size={checkboxSize}
-              checked={selectionSet.has(rowId)}
+              checked={isSelectedId(rowId)}
               disabled={isDisabled}
               aria-label={ariaLabel}
               onClick={(e) => {
@@ -1679,8 +1724,10 @@ function DataTableInner<TData>(
   React.useEffect(() => {
     if (!enabled || preserveSelectionOnFilter) return
     setSelection(prev => {
-      const filtered = prev.filter(id => visibleRowIdsSet.has(id))
-      return filtered.length === prev.length ? prev : filtered
+      // all 模式 = 「全部符合當前 filter」→ 不清(excluded 留著,被 filter 掉的 excluded 列無害)
+      if (prev.mode === 'all') return prev
+      const filtered = prev.ids.filter(id => visibleRowIdsSet.has(id))
+      return filtered.length === prev.ids.length ? prev : { mode: 'include', ids: filtered }
     })
   }, [visibleRowIdsKey, enabled, preserveSelectionOnFilter, visibleRowIdsSet, setSelection])
 
@@ -1692,9 +1739,22 @@ function DataTableInner<TData>(
       .map(r => r.id)
   }, [rows, enabled, isRowSelectable])
 
+  // Union-aware「某列是否選取」+ 計數(include = ids 內;all = 不在 excluded 內)
+  const includeSet = React.useMemo(
+    () => (selection.mode === 'include' ? new Set(selection.ids) : new Set<string>()),
+    [selection],
+  )
+  const excludeSet = React.useMemo(
+    () => (selection.mode === 'all' ? new Set(selection.excluded) : new Set<string>()),
+    [selection],
+  )
+  const isSelectedId = React.useCallback(
+    (id: string) => (selection.mode === 'include' ? includeSet.has(id) : !excludeSet.has(id)),
+    [selection.mode, includeSet, excludeSet],
+  )
+  const hasAnySelection = selection.mode === 'all' || includeSet.size > 0
   // Header tri-state checkbox value
-  const selectionSet = React.useMemo(() => new Set(selection), [selection])
-  const visibleSelectedCount = selectableVisibleIds.filter(id => selectionSet.has(id)).length
+  const visibleSelectedCount = selectableVisibleIds.filter(id => isSelectedId(id)).length
   const headerCheckedState: boolean | 'indeterminate' =
     selectableVisibleIds.length === 0 ? false
       : visibleSelectedCount === 0 ? false
@@ -1708,20 +1768,16 @@ function DataTableInner<TData>(
   )
 
   const toggleHeaderCheckbox = React.useCallback(() => {
-    if (headerCheckedState === true) {
-      // 清掉本頁可見已選(保留可見外的 selection)
-      const visibleSet = new Set(selectableVisibleIds)
-      setSelection(prev => prev.filter(id => !visibleSet.has(id)))
-    } else {
-      // 選全可見(扣除 disabled);保留可見外的既有 selection
-      setSelection(prev => Array.from(new Set([...prev, ...selectableVisibleIds])))
-    }
+    // header tri-state visible-scoped:全可見已選 → 取消可見;否則 → 選全可見。
+    // include / all 兩模型由 applySelectIds 處理(all 模式 toggle 改寫 excluded)。
+    const willSelect = headerCheckedState !== true
+    setSelection(prev => applySelectIds(prev, selectableVisibleIds, willSelect))
   }, [headerCheckedState, selectableVisibleIds, setSelection])
 
   const toggleRow = React.useCallback((rowId: string, rowOriginal: TData, opts?: { shiftKey?: boolean }) => {
     if (isRowSelectable && !isRowSelectable(rowOriginal)) return
     if (mode === 'single') {
-      setSelection(selectionSet.has(rowId) ? [] : [rowId])
+      setSelection(isSelectedId(rowId) ? { mode: 'include', ids: [] } : { mode: 'include', ids: [rowId] })
       anchorRowIdRef.current = rowId
       return
     }
@@ -1739,24 +1795,16 @@ function DataTableInner<TData>(
           return row && (!isRowSelectable || isRowSelectable(row.original))
         })
         // Mail / GitHub 慣例:shift-click 把 range 全變「rowId 點擊後該變的狀態」
-        const willCheck = !selectionSet.has(rowId)
-        setSelection(prev => {
-          const set = new Set(prev)
-          rangeIds.forEach(id => willCheck ? set.add(id) : set.delete(id))
-          return Array.from(set)
-        })
+        const willCheck = !isSelectedId(rowId)
+        setSelection(prev => applySelectIds(prev, rangeIds, willCheck))
         return
       }
     }
-    // 一般 toggle + 更新 anchor
-    setSelection(prev => {
-      const set = new Set(prev)
-      if (set.has(rowId)) set.delete(rowId)
-      else set.add(rowId)
-      return Array.from(set)
-    })
+    // 一般 toggle + 更新 anchor(include / all 由 applySelectIds 處理)
+    const willCheck = !isSelectedId(rowId)
+    setSelection(prev => applySelectIds(prev, [rowId], willCheck))
     anchorRowIdRef.current = rowId
-  }, [isRowSelectable, mode, selectionSet, rows, visibleIdToRow, setSelection])
+  }, [isRowSelectable, mode, isSelectedId, rows, visibleIdToRow, setSelection])
 
   // ── Cmd+A / Esc / Arrow keys 鍵盤 handler(table-level)──
   // code-quality-allow: long-function — single keyboard dispatch covering Cmd+A / Esc / Arrow / Space + selection state mutations,拆 sub-handler 會切散 keyboard mode coherence
@@ -1823,18 +1871,18 @@ function DataTableInner<TData>(
       // Cmd/Ctrl+A:選全可見(扣 disabled)— 對齊 Mail / GitHub / Linear 慣例
       if ((e.metaKey || e.ctrlKey) && e.key === 'a' && mode === 'multi') {
         e.preventDefault()
-        setSelection(prev => Array.from(new Set([...prev, ...selectableVisibleIds])))
+        setSelection(prev => applySelectIds(prev, selectableVisibleIds, true))
         return
       }
       // Esc:clear selection
-      if (e.key === 'Escape' && selection.length > 0) {
+      if (e.key === 'Escape' && hasAnySelection) {
         e.preventDefault()
-        setSelection([])
+        setSelection({ mode: 'include', ids: [] })
         anchorRowIdRef.current = null
         return
       }
     },
-    [enabled, mode, selection.length, selectableVisibleIds, setSelection,
+    [enabled, mode, hasAnySelection, selectableVisibleIds, setSelection,
      spreadsheetMode, selectedCellId, editingCellId, table, isCellEditable]
   )
 
@@ -2906,8 +2954,8 @@ function DataTableInner<TData>(
   if (enabled && mode === 'single') {
     return (
       <RadioGroupPrimitive.Root
-        value={selection[0] ?? ''}
-        onValueChange={(v) => v && setSelection([v])}
+        value={selection.mode === 'include' ? (selection.ids[0] ?? '') : ''}
+        onValueChange={(v) => v && setSelection({ mode: 'include', ids: [v] })}
       >
         {wrapWithDnd(tableContent)}
       </RadioGroupPrimitive.Root>

package/src/components/DateGrid/date-grid.principles.stories.tsx

@@ -71,16 +71,16 @@ export const UsageGuidance: Story = {
             <p>適合 DateGrid 的真實業務場景(點擊跳轉「展示」頁範例):</p>
             <ul className="space-y-1">
               <li>
-                <LinkTo kind="Design System/Internal/DateGrid/展示" name="單日 — 生日 / 到期日"><span className="text-primary hover:underline font-medium cursor-pointer">Single — 生日 / 到期日</span></LinkTo>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="單日 — 生日 / 到期日"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Single — 生日 / 到期日</span></LinkTo>
               </li>
               <li>
-                <LinkTo kind="Design System/Internal/DateGrid/展示" name="多日 — 活動可參加日期"><span className="text-primary hover:underline font-medium cursor-pointer">Multiple — 活動可參加日期</span></LinkTo>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="多日 — 活動可參加日期"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Multiple — 活動可參加日期</span></LinkTo>
               </li>
               <li>
-                <LinkTo kind="Design System/Internal/DateGrid/展示" name="範圍 — 分析時段 / 訂單範圍"><span className="text-primary hover:underline font-medium cursor-pointer">Range — 分析時段 / 訂單範圍</span></LinkTo>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="範圍 — 分析時段 / 訂單範圍"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Range — 分析時段 / 訂單範圍</span></LinkTo>
               </li>
               <li>
-                <LinkTo kind="Design System/Internal/DateGrid/展示" name="行內 — 儀表板小卡"><span className="text-primary hover:underline font-medium cursor-pointer">行內 — Linear 專案截止日小卡</span></LinkTo>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="行內 — 儀表板小卡"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">行內 — Linear 專案截止日小卡</span></LinkTo>
               </li>
             </ul>
             <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>

package/src/components/DatePicker/date-picker.principles.stories.tsx

@@ -47,11 +47,11 @@ export const UsageGuidance: Story = {
         <div className="prose prose-sm max-w-prose mb-8">
           <p>適合 DatePicker 的真實業務場景(點擊跳轉「展示」頁範例):</p>
           <ul className="space-y-1">
-            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="四模式"><span className="text-primary hover:underline font-medium cursor-pointer">請假單送審後日期欄位從可編輯轉唯讀/純展示(四模式)</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="可清除"><span className="text-primary hover:underline font-medium cursor-pointer">篩選器的選填截止日,填錯一鍵清空(可清除)</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="尺寸"><span className="text-primary hover:underline font-medium cursor-pointer">緊湊工具列與標準表單的尺寸對應(尺寸)</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="範圍模式:訂房 / 訂機票情境"><span className="text-primary hover:underline font-medium cursor-pointer">Range:訂房 / 訂機票情境</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="展示樣式"><span className="text-primary hover:underline font-medium cursor-pointer">審批詳情頁唯讀展示申請日期(展示樣式)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">請假單送審後日期欄位從可編輯轉唯讀/純展示(四模式)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="可清除"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">篩選器的選填截止日,填錯一鍵清空(可清除)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="尺寸"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">緊湊工具列與標準表單的尺寸對應(尺寸)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="範圍模式:訂房 / 訂機票情境"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Range:訂房 / 訂機票情境</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="展示樣式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">審批詳情頁唯讀展示申請日期(展示樣式)</span></LinkTo></li>
           </ul>
           <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
         </div>

package/src/components/DescriptionList/description-list.principles.stories.tsx

@@ -53,19 +53,19 @@ export const UsageGuidance: Story = {
       <p>適合 DescriptionList 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/DescriptionList/展示" name="使用者個資"><span className="text-primary hover:underline font-medium cursor-pointer">使用者個資</span></LinkTo>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="使用者個資"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">使用者個資</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DescriptionList/展示" name="產品規格"><span className="text-primary hover:underline font-medium cursor-pointer">產品規格</span></LinkTo>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="產品規格"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">產品規格</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DescriptionList/展示" name="訂單明細"><span className="text-primary hover:underline font-medium cursor-pointer">訂單明細</span></LinkTo>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="訂單明細"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">訂單明細</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DescriptionList/展示" name="詳情面板"><span className="text-primary hover:underline font-medium cursor-pointer">詳情面板</span></LinkTo>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="詳情面板"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">詳情面板</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DescriptionList/展示" name="水平佈局"><span className="text-primary hover:underline font-medium cursor-pointer">水平佈局</span></LinkTo>
+          <LinkTo kind="Design System/Components/DescriptionList/展示" name="水平佈局"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">水平佈局</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>

package/src/components/Dialog/dialog.principles.stories.tsx

@@ -52,16 +52,16 @@ export const UsageGuidance: Story = {
       <p>適合 Dialog 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Dialog/展示" name="表單"><span className="text-primary hover:underline font-medium cursor-pointer">表單</span></LinkTo>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="表單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">表單</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Dialog/展示" name="長內容"><span className="text-primary hover:underline font-medium cursor-pointer">長內容</span></LinkTo>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="長內容"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長內容</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Dialog/展示" name="危險操作"><span className="text-primary hover:underline font-medium cursor-pointer">危險操作</span></LinkTo>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="危險操作"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">危險操作</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Dialog/展示" name="主體放清單"><span className="text-primary hover:underline font-medium cursor-pointer">主體放清單</span></LinkTo>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="主體放清單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">主體放清單</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>

package/src/components/DropdownMenu/dropdown-menu.anatomy.stories.tsx

@@ -963,7 +963,7 @@ export const Accessibility = {
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
       <p className="whitespace-pre-line">{"無障礙能力沿用 Radix 選單元件的內建支援,涵蓋語意角色、選單導覽與焦點管理,設計師與工程師不需額外設定。\n\n鍵盤操作:\n\n- Tab — 將焦點移到觸發按鈕\n- Enter / Space / 向下鍵 — 開啟選單\n- 向上鍵 / 向下鍵 — 在選項之間移動\n- Enter — 選擇目前的選項\n- Esc — 關閉整個選單(含子選單;逐層收合用左方向鍵)\n\n焦點管理:選單開啟時焦點會進入選單,關閉後自動回到原本的觸發按鈕;目前導覽到的選項會以明顯的 highlight 底色標示,鍵盤使用者隨時看得到自己在哪一項。\n\n驗證:鍵盤可完整操作(不需滑鼠),文字對比達 WCAG AA;在 Storybook 無障礙檢查面板上應為零項嚴重問題。"}</p>
-      <p className="mt-4 text-fg-muted">完整 ARIA 細節參考 <a className="text-primary hover:underline" href="https://www.radix-ui.com/primitives/docs/components/dropdown-menu#accessibility" target="_blank" rel="noreferrer">Radix Accessibility 文件</a>。</p>
+      <p className="mt-4 text-fg-muted">完整 ARIA 細節參考 <a className="text-primary hover:text-primary-hover" href="https://www.radix-ui.com/primitives/docs/components/dropdown-menu#accessibility" target="_blank" rel="noreferrer">Radix Accessibility 文件</a>。</p>
     </div>
   ),
 }

package/src/components/DropdownMenu/dropdown-menu.principles.stories.tsx

@@ -58,19 +58,19 @@ export const UsageGuidance: Story = {
       <p>適合 DropdownMenu 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="群組"><span className="text-primary hover:underline font-medium cursor-pointer">群組 — 帳號選單(個人資料 / 設定 / 登出分組)</span></LinkTo>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="群組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">群組 — 帳號選單(個人資料 / 設定 / 登出分組)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="後綴"><span className="text-primary hover:underline font-medium cursor-pointer">後綴 — 收件匣未讀數 badge、外開連結提示</span></LinkTo>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="後綴"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">後綴 — 收件匣未讀數 badge、外開連結提示</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="子選單"><span className="text-primary hover:underline font-medium cursor-pointer">子選單 — 主題切換(淺色 / 深色 / 跟隨系統)</span></LinkTo>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="子選單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">子選單 — 主題切換(淺色 / 深色 / 跟隨系統)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="勾選項"><span className="text-primary hover:underline font-medium cursor-pointer">勾選項 — 表格顯示欄位切換</span></LinkTo>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="勾選項"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">勾選項 — 表格顯示欄位切換</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="單選"><span className="text-primary hover:underline font-medium cursor-pointer">單選 — 檔案清單排序方式</span></LinkTo>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="單選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單選 — 檔案清單排序方式</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:先看「選完之後畫面是否需要保留選中狀態」——需要就改用 Select / SelectMenu。下方的「DropdownMenu vs 選值元件」與「群組 vs 分隔線」範例提供更完整的對照。</p>