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

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

@@ -1,5 +1,17 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 // code-quality-allow: file-size — foundational composite — 拆檔會複雜化 context / ref / state 同步
+//
+// ── 檔案結構(2026-05-03 split matrix;2026-06-11 自 data-table.spec.md 遷入,Level 4 code home)──
+// 每個檔過 M21 / M17 / Rule-of-3 三 test:
+//   - data-table.tsx(主,foundational)
+//   - data-table-filter-panel.tsx + data-table-sort-manager.tsx + data-table-column-visibility-panel.tsx(panel state 隔離)
+//   - cell-registry.tsx(column type → cell display / edit 解析 SSOT)
+//   - data-table-interaction-layer.tsx + active-editor-controller.ts(spreadsheet overlay + portal editor)
+//   - column-types.ts + filter-operators.ts(✓ Rule-of-3 SSOT,3+ consumer)
+//   - filter-tree.ts(pure data + eval,test isolation)
+//   - lib/column-meta.ts(Internal SSOT,消 5 處 `(col as any)`)
+//   - + stories / spec / css
+// M21 retract:filter-value-picker.tsx 1 consumer → 已 inline 回 panel。
 import * as React from 'react'
 import { createPortal } from 'react-dom'
 import { Empty } from '@/design-system/components/Empty/empty'
@@ -24,7 +36,7 @@ import { DndContext, DragOverlay, useDraggable, useDroppable, useDndContext, poi
 import { cn } from '@/lib/utils'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 import { dragSourceStyle, dropIndicatorRow, dropIndicatorColumn, dragActiveCursor, isReorderNoop, reconstructFullRowGhost, snapToCursorModifier } from '@/design-system/lib/drag-visual'
-import { nakedCellEditableDisplayHover } from '@/design-system/components/Field/field-wrapper'
+import { nakedCellEditableDisplayHover, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
 import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator } from '@/design-system/components/DropdownMenu/dropdown-menu'
 import { ItemInlineActionButton } from '@/design-system/patterns/element-anatomy/item-anatomy'
@@ -56,6 +68,7 @@ type TableSize = 'sm' | 'md' | 'lg'
 export interface DataTableProps<TData>
   extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
     VariantProps<typeof dataTableVariants> {
+  // any-allow: TanStack ColumnDef TValue idiom(per-column value 型別異質,官方範例同)— 對齊本 module 既有 escape 紀律
   columns: ColumnDef<TData, any>[]
   data: TData[]
   size?: TableSize
@@ -121,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) */
@@ -175,8 +190,8 @@ export interface DataTableProps<TData>
    *
    * **v2(2026-05-05)修正**:
    * - Virtualizer × transform:被拖 row 略過 `measureElement`(透過 SortableRowCtx 廣播 active id),避免 transform 干擾測量
-   * - 3-panel mirror sync:每 region 都呼叫 `useSortable({id})`(同 SortableContext 共用 state),mirror 自然取得相同 transform
-   * - Cross-parent drop:nested 全 row 進 SortableContext.items,自訂 collisionDetection 過濾出「同 parent siblings」;cross-parent over → 不觸發,handle cursor `not-allowed`
+   * - 3-panel mirror sync:每 region 對同 row id 各呼叫 `useDraggable` + `useDroppable`,mirror 自然取得相同 transform
+   * - Cross-parent drop:nested 全 row 各自 `useDroppable`,自訂 collisionDetection 過濾出「同 parent siblings」;cross-parent over → 不觸發,handle cursor `not-allowed`
    *
    * 詳 `data-table.spec.md`「L4 Row drag」段。
    */
@@ -251,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'
 
@@ -299,8 +356,8 @@ function columnSizeStyle(
   // **flex-basis: baseSize(2026-05-06 v14.2)**:把 baseSize 當 explicit basis(不是 `0%`)。
   // 為什麼:flex item base = basis + padding(box-sizing: border-box content-box 行為)。前 `0%`
   // basis → cell padding 變 base 一部分。display(padding 12)vs edit(padding 0,Field 接管)
-  // 兩態 base 不同 → flex 重分配 → user 報「Price cell 進 edit 寬度縮 12px」(verify by
-  // debug-v14-1-display-edit-rect-match.mjs:Price display 130.5 → edit 118.5 = -12px)。
+  // 兩態 base 不同 → flex 重分配 → user 報「Price cell 進 edit 寬度縮 12px」
+  // (量測:Price display 130.5 → edit 118.5 = -12px)。
   // explicit basis = baseSize 讓 padding 不參與 base 計算 → display↔edit 寬度穩定。
   return { flex: `1 1 ${baseSize}px`, minWidth: baseSize, maxWidth: maxSize }
 }
@@ -761,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,
@@ -874,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 時做區間選
@@ -1368,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 (
@@ -1395,7 +1453,7 @@ function DataTableInner<TData>(
           ) : (
             <Checkbox
               size={checkboxSize}
-              checked={selectionSet.has(rowId)}
+              checked={isSelectedId(rowId)}
               disabled={isDisabled}
               aria-label={ariaLabel}
               onClick={(e) => {
@@ -1529,7 +1587,11 @@ function DataTableInner<TData>(
           //     「框框跟 cell 一樣大並取代 cell 的框且與 table 隔線無縫接軌」(2026-05-05)。
           //   - **沒有** cell 自己 box-shadow ring — focus / hover / open ring 由 Field naked 自帶
           //     state machine 提供(對齊 user「狀態樣式取決於原輸入框」reminder)
-          'group/cell flex text-foreground text-body font-normal shrink-0 relative self-stretch',
+          // 字級隨 size:sm/md text-body / lg text-body-lg(fieldDisplayTextClass),對齊 Field family
+          // size→font SSOT。此為非-Field content(consumer 自訂 cell / TruncateCell 純文字)的 fallback 字級;
+          // typed cell 各自的 Field 控件已自帶 size→font(cell-registry 傳 size)。
+          'group/cell flex text-foreground font-normal shrink-0 relative self-stretch',
+          fieldDisplayTextClass(size),
           // Issue 9(2026-05-10):有 cell error → unset overflow-hidden 讓 error message
           // wrap 撐 row 高。**H1(2026-05-10)升級**:overflow-visible 條件改 `rowHasAnyError` —
           // row 內任一 cell 有 error 整 row 全 cells 都 overflow-visible(error 訊息可能多行
@@ -1581,7 +1643,7 @@ function DataTableInner<TData>(
                       type="button"
                       aria-label={isExpanded ? '收合' : '展開'}
                       aria-expanded={isExpanded}
-                      className="inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-foreground rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform"
+                      className="inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-foreground rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform"
                       style={{ transform: isExpanded ? 'rotate(90deg)' : undefined }}
                       onClick={(e) => { e.stopPropagation(); toggleExpand?.() }}
                     >
@@ -1626,7 +1688,7 @@ function DataTableInner<TData>(
                     type="button"
                     aria-label={isExpanded ? '收合' : '展開'}
                     aria-expanded={isExpanded}
-                    className="inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-foreground rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform"
+                    className="inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-foreground rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform"
                     style={{ transform: isExpanded ? 'rotate(90deg)' : undefined }}
                     onClick={(e) => { e.stopPropagation(); toggleExpand?.() }}
                   >
@@ -1662,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])
 
@@ -1675,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
@@ -1691,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
     }
@@ -1722,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
@@ -1806,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]
   )
 
@@ -1875,7 +1940,10 @@ function DataTableInner<TData>(
           // absolute → hover 顯時佔位 → label 自動讓出空間給 sort + more,**不再重疊**(對齊
           // user 圖示質疑 + Notion / Airtable header layout 共識)。
           // cell padding 12px 由外層 cellPadding style 提供 → more 距 cell 右邊 = 12px。
-          'group relative flex items-center gap-2 text-fg-secondary text-body font-normal shrink-0 overflow-hidden select-none',
+          // header 字級也隨 size(原寫死 text-body → lg 表格 header 字偏小,跟 body 不一致)。
+          // 對齊 cell wrapper + Field family size→font SSOT。色弱化由 text-fg-secondary 維持。
+          'group relative flex items-center gap-2 text-fg-secondary font-normal shrink-0 overflow-hidden select-none',
+          fieldDisplayTextClass(size),
           align === 'right' && 'justify-end',
           align === 'center' && 'justify-center',
         )}
@@ -2886,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/DataTable/filter-operators.spec.md

@@ -0,0 +1,267 @@
+# Advanced Filter 設計原則(Operator × ColumnType × ValueShape SSOT,v3)
+
+> **狀態**:已落地 — registry 寫成 `filter-operators.ts`,`filter-tree.ts` + `data-table-filter-panel.tsx` 消費(原 draft 兩個升級條件皆已達成,2026-06-11 對齊)。
+> **M8 benchmark**:對照 ClickUp(CU)/ Airtable(AT)/ Notion(NT)三家。**v3 加 datetime / includeTime + 砍 number.between(2/3 業界共識)**。
+> **設計路線**:**ClickUp 為 baseline**,合理 + 不衝突 + 真實用的擴充採納。
+> **檔位**:暫放 DataTable/,若決定抽 `patterns/advanced-filter/` 再搬。
+
+## v3 變動 changelog
+
+- **砍 `number.between`**(9→8 ops)— Notion + Airtable 共識,同 field 重複 condition 可組合 `gte X AND lte Y`,無自然視覺也無業界 NumberRangeInput 元件
+- **加 `column.meta.includeTime: boolean` 旗標** — 對齊 Notion idiom,不另設 datetime column type
+- **加 ValueShape `datetime_single` / `datetime_range`** — `includeTime=true` 時切到這兩個 shape
+- **datetime 不另設 relative shape** — `is_relative` 維持 `date_relative`(relative 邏輯不變;12-shape 表與 code `ValueShape` union 皆無 `datetime_relative`)
+- **filter 比對精度**:`includeTime=true` 走 ms 精度(避開 Airtable 著名地雷:filter 忽略 time)
+- **不新增 `time-only` column type**(業界沒人做,罕見場景)
+
+## 1. ValueShape canonical(12 種)
+
+每個 operator 的「值該用什麼 picker」由 ValueShape 決定 — panel 只認 ValueShape,不認 op。新增 op 只需 map 到既有 shape。
+
+| ValueShape | UI 渲染 | 何時用 |
+|---|---|---|
+| `none` | (不渲) | `is_set / is_not_set / is_true / is_false` 純 predicate |
+| `text` | `<Input>` | 單行文字 |
+| `number` | `<NumberInput>` | 單一數字 |
+| `date_single` | `<DatePicker>` 單選 | 特定日期(`includeTime=false`) |
+| `date_range` | `<DatePickerRange>`(已是 Ant-style split-input) | 日期介於(`includeTime=false`) |
+| `date_relative` | `<Select>` 預設選項 | 相對日期 |
+| `datetime_single` | `<DatePicker showTime>` | 特定 datetime(`includeTime=true`) |
+| `datetime_range` | `<DatePickerRange showTime>` | datetime 介於(`includeTime=true`) |
+| `select_multi` | `<SelectMenu multiple>` from `column.meta.options` | 多選(`select.is` 也走這 — OR 語意) |
+| `person_multi` | `<PeoplePicker multiple>` | 多人員(`person.is` 也走這 — OR 語意) |
+| `select_single` | `<Select>` from `column.meta.options` | (預留)罕用 |
+| `person_single` | `<PeoplePicker>` 單選 | (預留)罕用 |
+
+**date_relative 預設選項**(13 個,分過去 / 目前 / 未來三組 — 對齊 code `DATE_RELATIVE_OPTIONS` / `DATE_RELATIVE_GROUPS`):
+`today / yesterday / tomorrow / this_week / last_week / next_week / this_month / last_month / next_month / past_7_days / past_30_days / next_7_days / next_30_days`
+
+**`number_range` 已砍**(配合 `number.between` 砍除)。
+
+## 2. Operator Registry — 各 columnType 完整 op set
+
+### `string`(6 ops)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `contains` | 包含 | contains | `text` | ✓ | ✓ | ✓ |
+| `does_not_contain` | 不包含 | does not contain | `text` | ✓ | ✓ | ✓ |
+| `is` | 等於 | is | `text` | — | ✓ | ✓ |
+| `is_not` | 不等於 | is not | `text` | — | ✓ | ✓ |
+| `is_set` | 已設定 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未設定 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`contains`。
+**擴充說明**:`is` / `is_not` 為 v2 擴充(CU 沒有,AT + NT 有)。實務需求:`title is "Project Alpha"` 跟 `contains "Project"` 語意不同 — 精確等於不被部分匹配誤觸發。**不衝突**:CU 沒這 op 不代表反對,只是 minimal 派。
+
+### `url`(8 ops — 獨立於 string)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `contains` | 包含 | contains | `text` | ✓ | ✓ | ✓ |
+| `does_not_contain` | 不包含 | does not contain | `text` | ✓ | ✓ | ✓ |
+| `is` | 等於 | is | `text` | — | ✓ | ✓ |
+| `is_not` | 不等於 | is not | `text` | — | ✓ | ✓ |
+| `starts_with` | 開頭為 | starts with | `text` | — | — | ✓ |
+| `ends_with` | 結尾為 | ends with | `text` | — | — | ✓ |
+| `is_set` | 已設定 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未設定 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`contains`。
+**為何獨立 string**:URL filtering 場景 prefix / suffix 匹配是強剛需(`starts_with "https://"` / `ends_with ".pdf"`)。string 場景則否。語意分流避免 over-extension。
+
+### `number` / `currency`(8 ops — v3 砍 between)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `equals` | 等於 | = | `number` | ✓ | ✓ | ✓ |
+| `not_equals` | 不等於 | ≠ | `number` | ✓ | ✓ | ✓ |
+| `gt` | 大於 | > | `number` | ✓ | ✓ | ✓ |
+| `gte` | 大於等於 | ≥ | `number` | ✓ | ✓ | ✓ |
+| `lt` | 小於 | < | `number` | ✓ | ✓ | ✓ |
+| `lte` | 小於等於 | ≤ | `number` | ✓ | ✓ | ✓ |
+| `is_set` | 已設定 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未設定 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`equals`。`currency` 共用同 set,渲染依 `column.meta.precision/prefix` 格式化。
+**`between` 已砍**:2/3 業界共識(Notion + Airtable 沒做)+ 同 field 重複 condition 可組 `gte X AND lte Y` + 沒有任何主流 DS 做 NumberRangeInput 元件。
+
+### `date` / `datetime`(9 ops — `includeTime` 旗標切 ValueShape)
+| op key | 中 | en | valueShape(includeTime=false → true) | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `is` | 是 | is | `date_single` → `datetime_single` | — | ✓ | ✓ |
+| `is_before` | 早於 | before | `date_single` → `datetime_single` | ✓ | ✓ | ✓ |
+| `is_after` | 晚於 | after | `date_single` → `datetime_single` | ✓ | ✓ | ✓ |
+| `is_on_or_before` | 不晚於 | on or before | `date_single` → `datetime_single` | — | ✓ | ✓ |
+| `is_on_or_after` | 不早於 | on or after | `date_single` → `datetime_single` | — | ✓ | ✓ |
+| `is_between` | 介於 | between | `date_range` → `datetime_range` | ✓ | ✓ | — |
+| `is_relative` | 相對 | relative | `date_relative`(不變,relative 仍 day-level) | ✓ | ✓ | ✓ |
+| `is_set` | 已設定 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未設定 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`is`。
+**擴充說明**:`is_on_or_before` / `is_on_or_after` 為 v2 擴充(CU 沒,AT + NT 有)— 實務「截止 ≤ 今天(含當天)」不能用嚴格 `before` 表達,語意上是 CU 的 gap。
+**`includeTime` 行為**:`column.meta.includeTime=true` 時 ValueShape 切 datetime_*,filter 比對走 ms 精度。`is_relative` 不受影響(relative 本質仍 day-level,`today` = 從今天 00:00 到 23:59:59)。
+
+### `select`(4 ops — CU UX 派,不另設 is_any_of)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `is` | 是 | is | `select_multi` | ✓ | ✓ | ✓ |
+| `is_not` | 不是 | is not | `select_multi` | ✓ | ✓ | ✓ |
+| `is_set` | 已設定 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未設定 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`is`。
+**關鍵**:`is` / `is_not` 配 `select_multi`(picker 多選,1 個值也合法)。
+- `is [Open]` = Open
+- `is [Open, Review]` = Open OR Review
+
+對齊 CU UX:`is` 直接接受多值,**不另設 `is_any_of` / `is_none_of`**(Airtable 派,過度切)。
+
+### `multiSelect`(5 ops — CU 派)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `has_any_of` | 含其中之一 | Any | `select_multi` | ✓ | ✓ | ✓(叫 contains)|
+| `has_all_of` | 全部包含 | All | `select_multi` | ✓ | ✓ | — |
+| `has_none_of` | 不含其中任一 | None of | `select_multi` | ✓ | ✓ | ✓(叫 does_not_contain)|
+| `is_set` | 已設定 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未設定 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`has_any_of`。**`is_exactly` 已砍**(user 確認 v1 不需,實務 edge case)。
+
+### `select` vs `multiSelect` op set 為何不同(根源 cell 資料形狀)
+
+| | `select`(cell = 單一字串) | `multiSelect`(cell = 字串陣列) |
+|---|---|---|
+| 1-to-1 比對 | ✓ `is` / `is_not`(picker 多選 OR-語意) | ✗ 不適用(陣列比單值 ambiguous) |
+| 集合運算 | ✗ 不適用 | ✓ `has_any_of` / `has_all_of` / `has_none_of` |
+
+差異**根源於 cell 資料形狀**,不是 picker 不同。Value picker 兩者都共用 `SelectMenu` DS 既有元件。
+
+### `person`(4 ops — 跟 select 同邏輯)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `is` | 是 | is | `person_multi` | ✓ | ✓ | ✓ |
+| `is_not` | 不是 | is not | `person_multi` | ✓ | ✓ | ✓ |
+| `is_set` | 已指派 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未指派 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`is`。對齊 CU assignee 邏輯(單欄但 picker 多選)。
+
+### `multiPerson`(5 ops — 跟 multiSelect 同邏輯)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `has_any_of` | 含其中之一 | Any | `person_multi` | ✓ | ✓ | ✓ |
+| `has_all_of` | 全部包含 | All | `person_multi` | ✓ | ✓ | — |
+| `has_none_of` | 不含其中任一 | None of | `person_multi` | ✓ | ✓ | ✓ |
+| `is_set` | 已指派 | is set | `none` | ✓ | ✓ | ✓ |
+| `is_not_set` | 未指派 | is not set | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`has_any_of`。
+
+### `boolean`(2 ops)
+| op key | 中 | en | valueShape | CU | AT | NT |
+|---|---|---|---|---|---|---|
+| `is_true` | 是 | is checked | `none` | ✓ | ✓ | ✓ |
+| `is_false` | 否 | is not checked | `none` | ✓ | ✓ | ✓ |
+
+**default op**:`is_true`。**沒有 `is_set`**(boolean 在 DB 通常 default false,語意上不存在 unset 狀態)。
+
+## 3. 數量總覽(v3)
+
+| Type | ops 數 | CU 派 / 擴充 |
+|---|---|---|
+| `string` | 6 | CU 4 + 擴 `is` / `is_not` |
+| `url` | 8 | CU 4 + 擴 `is` / `is_not` / `starts_with` / `ends_with`(獨立 type) |
+| `number` / `currency` | **8**(v3 砍 between) | 純 CU(無擴充) |
+| `date` | 9 | CU 7 + 擴 `is_on_or_before` / `is_on_or_after`(`includeTime` 切 ValueShape) |
+| `select` | 4 | 純 CU |
+| `multiSelect` | 5 | 純 CU |
+| `person` | 4 | 純 CU |
+| `multiPerson` | 5 | 純 CU |
+| `boolean` | 2 | 純 CU |
+| **總計** | **51 ops, 9 types** | 6 ops 擴充 / 45 ops CU 對齊 |
+
+**ColumnType meta 擴充**:`includeTime?: boolean`(date 用)。
+**ValueShape 12 種**(加 `datetime_single` / `datetime_range`,砍 `number_range`)。
+
+## 4. 設計語言一致性自查(對齊 CU,M8 自我比對 web-researched docs)
+
+| 一致性面向 | 對齊狀態 |
+|---|---|
+| 統一用 `is_set` / `is_not_set`(不混 `is_empty`) | 9 types 全用(boolean 豁免) |
+| select / person 用 `is` 配多值 picker(不另設 `is_any_of`) | ✓ 對齊 CU UX |
+| multiSelect / multiPerson 用 `has_*` 動詞(對應 CU labels Any/All/None) | ✓ |
+| number 不設 `between`(v3 砍 — 同 field `gte AND lte` 組合替代,見拍板 #10) | ✓ |
+| date 用 `before/after/between/relative` + `is_set` 不混 Airtable `is_empty` 風 | ✓ |
+| 6 ops 擴充項皆有 ≥ 2 家 world-class DS 採用,且不衝突 CU 設計語言 | ✓ |
+
+**未跑 audit / test 驗證**,僅與 web-researched ClickUp / Airtable / Notion docs 自我比對。
+
+## 5. TypeScript 結構(已落地)
+
+型別與 registry 落地於 `filter-operators.ts`(`ValueShape` 12 種含 `datetime_*`、無 `number_range`;`OPERATOR_REGISTRY` / `DEFAULT_OPERATOR`;`getValueShape` 處理 `includeTime` auto-promote)。Tree 型別與求值在 `filter-tree.ts`。原 v2 草案已退役,以 code 為準。
+
+## 6. 拍板紀錄
+
+### 2026-05-02 v2 拍板
+| # | 議題 | 決議 |
+|---|---|---|
+| 1 | 設計路線 | **走 ClickUp 派**,合理擴充採納 |
+| 2 | `string` 擴 `is` / `is_not` | ✅ 採用(CU minimal 不夠) |
+| 3 | `url` 獨立 type 擴 `starts_with` / `ends_with` | ✅ 採用(URL prefix 強剛需) |
+| 4 | `date` 擴 `is_on_or_before` / `is_on_or_after` | ✅ 採用(CU gap) |
+| 5 | `multiSelect` 走 5 ops(含 `has_all_of`)| ✅ |
+| 6 | `is_exactly` 全砍 | ✅ |
+| 7 | label 暫硬編繁中 + 留 i18n hook | ✅ |
+| 8 | op 命名 snake_case | ✅ |
+| 9 | 統一 `is_set` / `is_not_set`(不混 `is_empty`) | ✅ |
+
+### 2026-05-02 v3 datetime 拍板
+| # | 議題 | 決議 |
+|---|---|---|
+| 10 | `number.between` | ❌ 砍(2/3 業界共識 + composability) |
+| 11 | `date` 加 `includeTime` 旗標,不另設 datetime column type | ✅ 對齊 Notion |
+| 12 | `includeTime=true` 時 filter 走 ms 精度 | ✅ 避開 Airtable 地雷 |
+| 13 | `time-only` 場景 v1 不做 | ✅ 業界沒人做 |
+| 14 | DateTimePicker 走 Ant idiom + 借 React Aria a11y | ✅ |
+| 15 | DateTimeRangePicker layout = single calendar + time panel(showTime 模式)| ✅ 對齊 Ant 實際行為 |
+| 16 | 先做 advanced filter 主架構,DateTimePicker 排 phase D 平行 track | ✅ |
+| 17 | filter 範圍 Input 不需新變體 | ✅ |
+
+## 7. 同 field 可重複加 condition(設計約束)
+
+對齊 ClickUp idiom — 同一 field 可加多筆 condition,例:
+
+```
+(Status is Open OR Status is Review) AND Priority is High
+```
+
+我們的 FilterTree model 天然支援。
+
+**技術坑(信心 85%,Phase B spec.md 詳)**:TanStack `ColumnFiltersState` per-column 一筆 filter value,N 條同 column 會 AND-chain 不能 OR。**業界標準解法**:棄用 `columnFilters`,改自管 FilterTree state + 用 `globalFilter` + 自訂 `globalFilterFn` 走樹求 boolean。
+
+## 8. 邊界案例(code 真值 — `filter-tree.ts` / `data-table-filter-panel.tsx`)
+
+- **Condition 值空 / 未選 field**:視為 incomplete,求值 **pass-through**(不過濾任何 row);空值 ≠ `is_not_set`(後者是顯式 op)— `isConditionComplete` 守門
+- **群組刪光 condition**:空群組保留並 pass-through(true),panel 顯示「移除空群組」按鈕由 user 顯式刪除,不自動消失
+- **巢狀深度**:1-level cap 由 TypeScript 型別鎖死(`FilterGroup.children: FilterCondition[]`),無 runtime guard;繞過型別塞入的非 condition 物件缺 `field`/`op` → incomplete → pass-through,不 crash
+- **relative 區間邊界**:全部 local time、雙端 inclusive(`startOfDay`–`endOfDay`);`past_7_days` = 7 天前 00:00 起**含今天整天**;week 以週一起算(`weekStartsOn: 1`)
+
+## 9. Phase B 進度
+
+- [x] ValueShape × DS 元件對照 — 完成,coverage 8/12 直接消費 + 4 預留;datetime 走 `<DatePicker showTime>` / `<DatePickerRange showTime>` prop variant(M21,非新元件)
+- [x] InputSurface 議題消失(配合砍 `number.between`)
+- [x] FilterTree data model + DataTable 耦合 — 已落地 `filter-tree.ts` + `data-table-filter-panel.tsx`(原規劃 `advanced-filter.draft.md` 未另立檔,內容即本 spec + code)
+- [x] datetime spec — 併入本 spec v3(原規劃 `datetime-picker.draft.md` 不需要,無新元件)
+- [x] i18n 策略 — 暫硬編繁中,留 i18n hook(對齊 DS 既有元件慣例)
+- [→] Phase B.5 lock canonical via `/ensure-canonical`(spec 全收斂後)
+
+## Sources(M8 benchmark)
+
+- [ClickUp filter help](https://help.clickup.com/hc/en-us/articles/6308875427223-Use-filters-to-search-tasks)
+- [ClickUp custom field filter](https://help.clickup.com/hc/en-us/articles/12665650881943-Search-sort-and-filter-tasks-by-Custom-Fields)
+- [ClickUp filter API](https://developer.clickup.com/docs/filter-views)
+- [ClickUp range operator](https://developer.clickup.com/docs/range)
+- [Airtable filter records](https://support.airtable.com/docs/filtering-records-using-conditions)
+- [Airtable single select](https://support.airtable.com/docs/single-select-field)
+- [Airtable multiple select](https://support.airtable.com/docs/multiple-select-field)
+- [Notion API filter](https://developers.notion.com/reference/post-database-query-filter)
+- [go-notion SDK source](https://github.com/sorcererxw/go-notion/blob/master/api.go)

package/src/components/DataTable/filter-operators.ts

@@ -7,7 +7,7 @@
  * **禁止**:component 內 hardcode op 字串。一律走 `OPERATOR_REGISTRY[columnType]`。
  *
  * 設計路線:ClickUp baseline + 合理擴充(string +2, url 獨立 +4, date +2)。
- * 詳細 spec:`./advanced-filter-operators.draft.md`
+ * 詳細 spec:`./filter-operators.spec.md`
  */
 
 import type { ColumnType } from './column-types'

package/src/components/DataTable/filter-tree.ts

@@ -4,7 +4,7 @@
  * 抽自 data-table-filter-panel.tsx 為了 file-size budget(panel 拆分)。
  * 純資料結構 + pure functions,無 UI dep。
  *
- * 詳:./advanced-filter.draft.md
+ * 詳:./filter-operators.spec.md
  */
 
 import {
@@ -235,7 +235,7 @@ function matchOperator(op: string, cellValue: unknown, filterValue: unknown): bo
     case 'contains':         return String(cellValue ?? '').toLowerCase().includes(String(filterValue).toLowerCase())
     case 'does_not_contain': return !String(cellValue ?? '').toLowerCase().includes(String(filterValue).toLowerCase())
     // 2026-05-12 Round 6 fix(user 抓 Roadmap 進階篩選「全部」結果空)— impl-vs-spec drift。
-    // Per `advanced-filter-operators.draft.md` L116「is 直接接受多值,不另設 is_any_of」+ L103-116
+    // Per `filter-operators.spec.md` L116「is 直接接受多值,不另設 is_any_of」+ L103-116
     // select(is/is_not + select_multi ValueShape OR 語意)+ L31-32(select.is / person.is 都走
     // select_multi / person_multi ValueShape)。原 impl 只做 single-value 比對,filterValue 是
     // array(全選 options)→ String(array)= "v1,v2" → 永遠 != single cellValue → 結果空。

package/src/components/DataTable/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 './data-table'