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

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)
 
@@ -378,12 +386,12 @@ ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 
 ### 四、UI canonical
 
-- 第 1 row conjunction 是靜態 `Where` label(`px-3` 對齊下方 Field value 起點 = 12px)
+- 第 1 row conjunction 是靜態 `Where` label(`px-[var(--field-px)]` 對齊下方 Field value 起點 = 12px)
 - field 未選 → operator + value picker disabled;同 group 共用 conjunction(toggle 任一 → flip 整 group)
 - **空狀態**:無 condition → 只顯 inline `+ 加篩選` CTA(對齊 Notion / Airtable / Linear,**禁止** auto-create 空 row) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **CTA 位置**:緊貼最後一條 row(text variant 輕量,**廢 SurfaceFooter**),條件與「加入」屬同一語境
 - **Trash / 刪除**:row 是 form-control row → text Button(non Inline Action,違 item-anatomy canonical)
-- **And/Or Select** `minRows={2}`(2 選項顯式縮 menu 高度);**Where padding** `px-3` align Field
+- **And/Or Select** `minRows={2}`(2 選項顯式縮 menu 高度);**Where padding** `px-[var(--field-px)]` align Field
 - Header refresh icon:`value !== defaultValue` 顯;ButtonDivider 串接 close X(對齊欄位顯示 chrome canonical)
 - **Relative date 群組**:`DATE_RELATIVE_GROUPS` Past / Current / Future,走 `<Select groups>`
 - Trigger button checked(`aria-pressed`):`value` 有 ≥ 1 active condition → on(語意:資料被篩,獨立於 refresh)

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.anatomy.stories.tsx

@@ -39,7 +39,7 @@ const PARTS: Record<PartKey, PartSpec> = {
   caption:      { label: '月份標題',    bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: 'text-body font-medium' },
   nav:          { label: 'Nav 按鈕',    bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: 'Button variant=text size=xs iconOnly · hover 藍圈' },
   weekday:      { label: '星期標頭',    bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: 'text-body font-medium · h-7' },
-  day:          { label: '日格(default)', bg: 'transparent',   text: '--foreground',  border: 'transparent', extra: 'h-field-sm w-field-sm rounded-full' },
+  day:          { label: '日格(default)', bg: 'transparent',   text: '--foreground',  border: 'transparent', extra: 'h-field-sm w-[var(--field-height-sm)] rounded-full' },
   daySelected:  { label: 'Selected',     bg: '--primary',       text: 'white',         border: 'transparent' },
   dayToday:     { label: 'Today(未選)', bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: '數字下方藍色底線(underline bar)' },
   dayHover:     { label: 'Hover',        bg: 'transparent',     text: '--foreground',  border: '--primary',   extra: 'hover 藍圈 1.5px(無填底)' },

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/DateGrid/date-grid.spec.md

@@ -82,7 +82,7 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 
 因此用 `[&[data-range-middle=true]]:xxx` 這種 attribute selector **根本不會生效**(舊版做法錯誤)。
 
-**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: 'bg-[var(--color-neutral-2)] [&>button]:!bg-transparent'`。
+**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: "before:content-[''] before:absolute before:inset-y-0 before:-inset-x-[2px] before:bg-neutral-selected [&>button]:!bg-transparent"`(用 `before:` pseudo + semantic `--neutral-selected` token,對齊下方 Range track canonical 與 tsx)。
 
 `[&>button]:xxx` 從 cell 向內選子 button 用於 button-level 樣式(selected / disabled 的藍底白圓等)。
 

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

@@ -33,7 +33,7 @@ const COLOR_MAP: Record<ModeKey, Partial<Record<StateKey, ColorSpec>>> = {
     disabled: { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent',     icon: '--fg-disabled' },
   },
   readonly: {
-    default:  { bg: '--bg-readonly', text: '--foreground',  border: 'transparent',     icon: '--fg-muted' },
+    default:  { bg: '--bg-readonly', text: '--foreground',  border: 'transparent',     icon: '—' },
   },
   disabled: {
     default:  { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent',     icon: '--fg-disabled' },
@@ -50,9 +50,9 @@ interface SizeSpec {
 }
 
 const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
-  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
-  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
-  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, clearHover: 22 },
+  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
+  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
+  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, clearHover: 22 },
 }
 
 const MODE_DESC: Record<ModeKey, string> = {
@@ -172,7 +172,7 @@ export const Overview = {
       <div className="flex flex-col gap-4">
         <div className="flex flex-col gap-1">
           <H3>結構（Anatomy）</H3>
-          <Desc>edit 模式：可點擊的觸發列顯示格式化日期文字 + 日曆圖示（固定右側），點任意位置都會展開日期面板。clearable 有值時額外顯示 X 清除按鈕。readonly / disabled 模式：格式化文字 + Calendar icon（類型身份 indicator；disabled 切 fg-disabled），無 X。</Desc>
+          <Desc>edit 模式：可點擊的觸發列顯示格式化日期文字 + 日曆圖示（固定右側），點任意位置都會展開日期面板。clearable 有值時額外顯示 X 清除按鈕。readonly 模式：純格式化文字，無 Calendar icon、無 X。disabled 模式：格式化文字 + Calendar icon（類型身份 indicator，切 fg-disabled），無 X。</Desc>
         </div>
         <div className="flex gap-8">
           {/* Edit layout */}
@@ -346,7 +346,7 @@ const InspectorInner = () => {
                 { c: Z.pad, l: '左右內距' },
                 ...(isEdit ? [{ c: Z.input, l: 'trigger text' }] : [{ c: Z.input, l: 'formatted text' }]),
                 ...(showClear ? [{ c: Z.action, l: 'X clear' }] : []),
-                { c: Z.icon, l: 'Calendar' },
+                ...(mode !== 'readonly' ? [{ c: Z.icon, l: 'Calendar' }] : []),
               ].map(({ c, l }) => (
                 <span key={l} className="inline-flex items-center gap-1">
                   <span className="w-2.5 h-2.5 rounded-md" style={{ background: c.bg, border: `1px dashed ${c.border}` }} />
@@ -364,8 +364,12 @@ const InspectorInner = () => {
                     <BpZone w={44} color={Z.action} label={`${s.icon}px`} sub="clear" />
                   </>
                 )}
-                <BpZone w={32} color={Z.gap} label={s.gapToken} sub={`${s.gap}px`} />
-                <BpZone w={44} color={Z.icon} label={`${s.icon}px`} sub="Calendar" />
+                {mode !== 'readonly' && (
+                  <>
+                    <BpZone w={32} color={Z.gap} label={s.gapToken} sub={`${s.gap}px`} />
+                    <BpZone w={44} color={Z.icon} label={`${s.icon}px`} sub="Calendar" />
+                  </>
+                )}
                 <BpZone w={44} color={Z.pad} label={s.pxToken} sub={`${s.px}px`} />
               </div>
               <div className="ml-3 flex items-center" style={{ height: 52 }}>
@@ -393,7 +397,7 @@ const InspectorInner = () => {
             <PropRow label="Fill"><TokenValue value={colors.bg} /></PropRow>
             <PropRow label="Text"><TokenValue value={colors.text} /></PropRow>
             <PropRow label="Border"><TokenValue value={colors.border} /></PropRow>
-            {isEdit && (
+            {mode !== 'readonly' && (
               <PropRow label="Calendar">
                 <TokenValue value={colors.icon} />
               </PropRow>
@@ -424,7 +428,7 @@ const InspectorInner = () => {
             <PropRow label="高度" dot={Z.dim.text}><TkVal token={s.heightToken} value={s.height} /></PropRow>
             <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={s.pxToken} value={`${s.px}px`} /></PropRow>
             <PropRow label="元素間距" dot={Z.gap.text}><TkVal token={s.gapToken} value={`${s.gap}px`} /></PropRow>
-            {isEdit && (
+            {mode !== 'readonly' && (
               <PropRow label="Calendar" dot={Z.icon.text}>{s.icon}px</PropRow>
             )}
             {showClear && (
@@ -686,7 +690,7 @@ export const StateBehavior = {
               <span className="text-fg-muted text-caption">→</span>
               <DatePicker mode="disabled" value="2026-04-02" className="w-56" />
             </div>
-            <span className="text-[11px] text-fg-muted">左：edit（有 X）→ 中：readonly（無 X，保留 Calendar）→ 右：disabled（無 X，Calendar 與文字切 fg-disabled）</span>
+            <span className="text-[11px] text-fg-muted">左：edit（有 X）→ 中：readonly（無 X、無 Calendar，純文字）→ 右：disabled（無 X，保留 Calendar，與文字切 fg-disabled）</span>
           </div>
         </div>
 

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>