@qijenchen/design-system 0.1.0-beta.10

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

@@ -0,0 +1,225 @@
+/**
+ * filter-operators.ts — Advanced Filter Operator Registry SSOT
+ *
+ * Single source of truth for all filter operator definitions.
+ * 51 ops × 9 columnTypes × 12 ValueShapes.
+ *
+ * **禁止**:component 內 hardcode op 字串。一律走 `OPERATOR_REGISTRY[columnType]`。
+ *
+ * 設計路線:ClickUp baseline + 合理擴充(string +2, url 獨立 +4, date +2)。
+ * 詳細 spec:`./advanced-filter-operators.draft.md`
+ */
+
+import type { ColumnType } from './column-types'
+
+// ── ValueShape ───────────────────────────────────────────────────────────
+
+/**
+ * Filter value 該用什麼 picker — panel 只認 ValueShape,不認 op。
+ * 新增 op 只需 map 到既有 shape。
+ */
+export type ValueShape =
+  | 'none'              // is_set / is_not_set / is_true / is_false 純 predicate
+  | 'text'              // <Input>
+  | 'number'            // <NumberInput>
+  | 'date_single'       // <DatePicker> single date
+  | 'date_range'        // <DatePickerRange> Ant-style split-input
+  | 'date_relative'     // <Select> 預設選項(today/yesterday/this_week/...)
+  | 'datetime_single'   // <DatePicker showTime>(includeTime=true)
+  | 'datetime_range'    // <DatePickerRange showTime>(includeTime=true)
+  | 'select_single'     // <Select>(預留,目前無 op 採用)
+  | 'select_multi'      // <SelectMenu multiple>(select.is 也走這)
+  | 'person_single'     // <PeoplePicker>(預留)
+  | 'person_multi'      // <PeoplePicker multiple>(person.is 也走這)
+
+// ── OperatorSpec ────────────────────────────────────────────────────────
+
+export interface OperatorSpec {
+  /** Internal key, snake_case, immutable for FilterTree serialization */
+  op: string
+  /** UI label in zh-TW(暫硬編,留 i18n hook) */
+  label: string
+  /** Reference label for English / future i18n key */
+  labelEn: string
+  /**
+   * Value picker shape.
+   * date_* shapes auto-promote to datetime_* when includeTime=true(via `getValueShape`).
+   */
+  valueShape: ValueShape
+}
+
+// ── Date Relative Options(13 個,含分組)───────────────────────────────
+// 群組順序 + 排列對齊 Linear / Notion / ClickUp 共識:Past → Current → Future
+// 群內排列:由遠到近(Past:30 → 7 → 月 → 週 → 昨;Future:明 → 週 → 月 → 7 → 30)
+//          中間語義 anchor today/this 排於 Current
+
+export const DATE_RELATIVE_GROUPS = [
+  { key: 'past',    label: '過去' },
+  { key: 'current', label: '目前' },
+  { key: 'future',  label: '未來' },
+] as const
+
+export const DATE_RELATIVE_OPTIONS = [
+  // Past
+  { value: 'past_30_days',  label: '過去 30 天', group: 'past' },
+  { value: 'past_7_days',   label: '過去 7 天',  group: 'past' },
+  { value: 'last_month',    label: '上月',       group: 'past' },
+  { value: 'last_week',     label: '上週',       group: 'past' },
+  { value: 'yesterday',     label: '昨天',       group: 'past' },
+  // Current
+  { value: 'today',         label: '今天',       group: 'current' },
+  { value: 'this_week',     label: '本週',       group: 'current' },
+  { value: 'this_month',    label: '本月',       group: 'current' },
+  // Future
+  { value: 'tomorrow',      label: '明天',       group: 'future' },
+  { value: 'next_week',     label: '下週',       group: 'future' },
+  { value: 'next_month',    label: '下月',       group: 'future' },
+  { value: 'next_7_days',   label: '未來 7 天',  group: 'future' },
+  { value: 'next_30_days',  label: '未來 30 天', group: 'future' },
+] as const
+
+// ── Per-columnType op definitions ───────────────────────────────────────
+
+const STRING_OPS: OperatorSpec[] = [
+  { op: 'contains',         label: '包含',       labelEn: 'contains',          valueShape: 'text' },
+  { op: 'does_not_contain', label: '不包含',     labelEn: 'does not contain',  valueShape: 'text' },
+  { op: 'is',               label: '等於',       labelEn: 'is',                valueShape: 'text' },
+  { op: 'is_not',           label: '不等於',     labelEn: 'is not',            valueShape: 'text' },
+  { op: 'is_set',           label: '已設定',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未設定',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const URL_OPS: OperatorSpec[] = [
+  { op: 'contains',         label: '包含',       labelEn: 'contains',          valueShape: 'text' },
+  { op: 'does_not_contain', label: '不包含',     labelEn: 'does not contain',  valueShape: 'text' },
+  { op: 'is',               label: '等於',       labelEn: 'is',                valueShape: 'text' },
+  { op: 'is_not',           label: '不等於',     labelEn: 'is not',            valueShape: 'text' },
+  { op: 'starts_with',      label: '開頭為',     labelEn: 'starts with',       valueShape: 'text' },
+  { op: 'ends_with',        label: '結尾為',     labelEn: 'ends with',         valueShape: 'text' },
+  { op: 'is_set',           label: '已設定',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未設定',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const NUMBER_OPS: OperatorSpec[] = [
+  { op: 'equals',           label: '等於',       labelEn: '=',                 valueShape: 'number' },
+  { op: 'not_equals',       label: '不等於',     labelEn: '≠',                 valueShape: 'number' },
+  { op: 'gt',               label: '大於',       labelEn: '>',                 valueShape: 'number' },
+  { op: 'gte',              label: '大於等於',   labelEn: '≥',                 valueShape: 'number' },
+  { op: 'lt',               label: '小於',       labelEn: '<',                 valueShape: 'number' },
+  { op: 'lte',              label: '小於等於',   labelEn: '≤',                 valueShape: 'number' },
+  { op: 'is_set',           label: '已設定',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未設定',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const DATE_OPS: OperatorSpec[] = [
+  { op: 'is',               label: '是',         labelEn: 'is',                valueShape: 'date_single' },
+  { op: 'is_before',        label: '早於',       labelEn: 'before',            valueShape: 'date_single' },
+  { op: 'is_after',         label: '晚於',       labelEn: 'after',             valueShape: 'date_single' },
+  { op: 'is_on_or_before',  label: '不晚於',     labelEn: 'on or before',      valueShape: 'date_single' },
+  { op: 'is_on_or_after',   label: '不早於',     labelEn: 'on or after',       valueShape: 'date_single' },
+  { op: 'is_between',       label: '介於',       labelEn: 'between',           valueShape: 'date_range' },
+  { op: 'is_relative',      label: '相對',       labelEn: 'relative',          valueShape: 'date_relative' },
+  { op: 'is_set',           label: '已設定',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未設定',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const SELECT_OPS: OperatorSpec[] = [
+  { op: 'is',               label: '是',         labelEn: 'is',                valueShape: 'select_multi' },
+  { op: 'is_not',           label: '不是',       labelEn: 'is not',            valueShape: 'select_multi' },
+  { op: 'is_set',           label: '已設定',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未設定',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const MULTI_SELECT_OPS: OperatorSpec[] = [
+  { op: 'has_any_of',       label: '含其中之一', labelEn: 'Any',               valueShape: 'select_multi' },
+  { op: 'has_all_of',       label: '全部包含',   labelEn: 'All',               valueShape: 'select_multi' },
+  { op: 'has_none_of',      label: '不含其中任一', labelEn: 'None of',         valueShape: 'select_multi' },
+  { op: 'is_set',           label: '已設定',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未設定',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const PERSON_OPS: OperatorSpec[] = [
+  { op: 'is',               label: '是',         labelEn: 'is',                valueShape: 'person_multi' },
+  { op: 'is_not',           label: '不是',       labelEn: 'is not',            valueShape: 'person_multi' },
+  { op: 'is_set',           label: '已指派',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未指派',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const MULTI_PERSON_OPS: OperatorSpec[] = [
+  { op: 'has_any_of',       label: '含其中之一', labelEn: 'Any',               valueShape: 'person_multi' },
+  { op: 'has_all_of',       label: '全部包含',   labelEn: 'All',               valueShape: 'person_multi' },
+  { op: 'has_none_of',      label: '不含其中任一', labelEn: 'None of',         valueShape: 'person_multi' },
+  { op: 'is_set',           label: '已指派',     labelEn: 'is set',            valueShape: 'none' },
+  { op: 'is_not_set',       label: '未指派',     labelEn: 'is not set',        valueShape: 'none' },
+]
+
+const BOOLEAN_OPS: OperatorSpec[] = [
+  { op: 'is_true',          label: '是',         labelEn: 'is checked',        valueShape: 'none' },
+  { op: 'is_false',         label: '否',         labelEn: 'is not checked',    valueShape: 'none' },
+]
+
+/**
+ * SSOT canonical — 全部 51 ops, 9 columnTypes 對照表.
+ *
+ * **禁止繞過**:component 內勿 hardcode op 字串(M17 Rule-of-3 + Phase 5 Q3=c TypeScript-enforce 派)。
+ * `currency` 共用 `number` op set,渲染依 `column.meta.precision/prefix` 格式化。
+ */
+export const OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]> = {
+  string:      STRING_OPS,
+  url:         URL_OPS,
+  number:      NUMBER_OPS,
+  currency:    NUMBER_OPS,
+  date:        DATE_OPS,
+  // Phase C(2026-05-05):time column 暫先 reuse DATE_OPS shape — advanced filter `time_*`
+  // ValueShape 整合留 Phase D+。consumer 走基本 cell render(無 advanced filter)不影響。
+  time:        DATE_OPS,
+  select:      SELECT_OPS,
+  multiSelect: MULTI_SELECT_OPS,
+  person:      PERSON_OPS,
+  multiPerson: MULTI_PERSON_OPS,
+  boolean:     BOOLEAN_OPS,
+}
+
+/** Default operator per columnType — 開新 condition 時的 op preset */
+export const DEFAULT_OPERATOR: Record<ColumnType, string> = {
+  string:      'contains',
+  url:         'contains',
+  number:      'equals',
+  currency:    'equals',
+  date:        'is',
+  time:        'is',
+  select:      'is',
+  multiSelect: 'has_any_of',
+  person:      'is',
+  multiPerson: 'has_any_of',
+  boolean:     'is_true',
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Resolve ValueShape for a given op + columnType + includeTime flag.
+ *
+ * `date_single` / `date_range` shapes auto-promote to `datetime_single` /
+ * `datetime_range` when columnType=`date` && includeTime=true. All other
+ * shapes pass-through unchanged.
+ *
+ * `date_relative` stays as-is(relative 本質 day-level,e.g. `today` =
+ * 從今天 00:00 到 23:59:59,跟 includeTime 無關)。
+ */
+export function getValueShape(
+  op: OperatorSpec,
+  columnType: ColumnType,
+  includeTime?: boolean,
+): ValueShape {
+  if (columnType === 'date' && includeTime) {
+    if (op.valueShape === 'date_single') return 'datetime_single'
+    if (op.valueShape === 'date_range') return 'datetime_range'
+  }
+  return op.valueShape
+}
+
+/** Get OperatorSpec by columnType + op key. Returns null if not found. */
+export function getOperatorSpec(columnType: ColumnType, op: string): OperatorSpec | null {
+  return OPERATOR_REGISTRY[columnType]?.find((o) => o.op === op) ?? null
+}

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

@@ -0,0 +1,313 @@
+/**
+ * filter-tree.ts — FilterTree types + helpers + evaluator
+ *
+ * 抽自 data-table-filter-panel.tsx 為了 file-size budget(panel 拆分)。
+ * 純資料結構 + pure functions,無 UI dep。
+ *
+ * 詳:./advanced-filter.draft.md
+ */
+
+import {
+  startOfDay, endOfDay,
+  startOfWeek, endOfWeek,
+  startOfMonth, endOfMonth,
+  addDays, addWeeks, addMonths, subDays,
+} from 'date-fns'
+import { OPERATOR_REGISTRY, type OperatorSpec } from './filter-operators'
+
+/**
+ * 把 relative key 轉成 [start, end] 時間區間(local time,inclusive)。
+ * 對齊 Notion / ClickUp idiom — 以「今天」為錨點計算。
+ */
+function relativeKeyToRange(key: string, now: Date = new Date()): [number, number] | null {
+  const today = startOfDay(now)
+  switch (key) {
+    case 'today':        return [today.getTime(), endOfDay(now).getTime()]
+    case 'yesterday':    return [startOfDay(subDays(now, 1)).getTime(), endOfDay(subDays(now, 1)).getTime()]
+    case 'tomorrow':     return [startOfDay(addDays(now, 1)).getTime(), endOfDay(addDays(now, 1)).getTime()]
+    case 'this_week':    return [startOfWeek(now, { weekStartsOn: 1 }).getTime(), endOfWeek(now, { weekStartsOn: 1 }).getTime()]
+    case 'last_week':    return [startOfWeek(addWeeks(now, -1), { weekStartsOn: 1 }).getTime(), endOfWeek(addWeeks(now, -1), { weekStartsOn: 1 }).getTime()]
+    case 'next_week':    return [startOfWeek(addWeeks(now, 1), { weekStartsOn: 1 }).getTime(), endOfWeek(addWeeks(now, 1), { weekStartsOn: 1 }).getTime()]
+    case 'this_month':   return [startOfMonth(now).getTime(), endOfMonth(now).getTime()]
+    case 'last_month':   return [startOfMonth(addMonths(now, -1)).getTime(), endOfMonth(addMonths(now, -1)).getTime()]
+    case 'next_month':   return [startOfMonth(addMonths(now, 1)).getTime(), endOfMonth(addMonths(now, 1)).getTime()]
+    case 'past_7_days':  return [startOfDay(subDays(now, 7)).getTime(), endOfDay(now).getTime()]
+    case 'past_30_days': return [startOfDay(subDays(now, 30)).getTime(), endOfDay(now).getTime()]
+    case 'next_7_days':  return [startOfDay(now).getTime(), endOfDay(addDays(now, 7)).getTime()]
+    case 'next_30_days': return [startOfDay(now).getTime(), endOfDay(addDays(now, 30)).getTime()]
+    default: return null
+  }
+}
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type Conjunction = 'and' | 'or'
+
+export interface FilterCondition {
+  kind: 'cond'
+  /** 唯一 row id(stable across renders) */
+  id: string
+  /** 對應 column id;空字串 = 尚未選 field(operator/value picker disabled) */
+  field: string
+  /** OperatorSpec.op key — 對齊 OPERATOR_REGISTRY */
+  op: string
+  /** 依 ValueShape 解讀的值 */
+  value: unknown
+}
+
+export interface FilterGroup {
+  kind: 'group'
+  id: string
+  /** group 內 children 共用的 join(全 AND 或全 OR;不允許混) */
+  conjunction: Conjunction
+  /** ⚠️ 型別鎖死:children 只能 condition,不可再 nested group(1-level cap) */
+  children: FilterCondition[]
+}
+
+export type FilterTreeFlat = {
+  mode: 'flat'
+  conjunction: Conjunction
+  children: FilterCondition[]
+}
+
+export type FilterTreeNested = {
+  mode: 'nested'
+  conjunction: Conjunction
+  children: FilterGroup[]
+}
+
+export type FilterTree = FilterTreeFlat | FilterTreeNested
+
+// ── Helpers — public API ────────────────────────────────────────────────
+
+/** Empty FilterTree — consumer 用來 init useState */
+export function createEmptyFilterTree(mode: 'flat'): FilterTreeFlat
+export function createEmptyFilterTree(mode: 'nested'): FilterTreeNested
+export function createEmptyFilterTree(mode: 'flat' | 'nested'): FilterTree {
+  if (mode === 'flat') return { mode: 'flat', conjunction: 'and', children: [] }
+  return { mode: 'nested', conjunction: 'and', children: [] }
+}
+
+/** 是否有任何 active filter — DataTable trigger button checked state 用 */
+export function isFilterTreeActive(tree: FilterTree): boolean {
+  if (tree.mode === 'flat') {
+    return tree.children.some((c) => isConditionComplete(c))
+  }
+  return tree.children.some((g) => g.children.some((c) => isConditionComplete(c)))
+}
+
+/** Condition 是否「已填齊」可參與 filter 求值 */
+function isConditionComplete(c: FilterCondition): boolean {
+  if (!c.field || !c.op) return false
+  const spec = getOperatorSpecLoose(c.op)
+  if (!spec) return false
+  if (spec.valueShape === 'none') return true
+  return c.value !== '' && c.value !== null && c.value !== undefined
+}
+
+/** loose lookup — 我們不知 columnType,試所有 type */
+function getOperatorSpecLoose(op: string): OperatorSpec | null {
+  for (const list of Object.values(OPERATOR_REGISTRY)) {
+    const found = list.find((o) => o.op === op)
+    if (found) return found
+  }
+  return null
+}
+
+// ── Deep-equal compare(refresh icon 顯示判定用) ─────────────────────────
+
+/** Compare two FilterTrees structurally — 忽略內部 row id(refresh-detect 不該被內部 id 干擾)*/
+export function isFilterTreeEqual(a: FilterTree, b: FilterTree): boolean {
+  if (a.mode !== b.mode || a.conjunction !== b.conjunction) return false
+  if (a.children.length !== b.children.length) return false
+  if (a.mode === 'flat' && b.mode === 'flat') {
+    return a.children.every((c, i) => isConditionEqual(c, b.children[i]))
+  }
+  if (a.mode === 'nested' && b.mode === 'nested') {
+    return a.children.every((g, i) => isGroupEqual(g, b.children[i]))
+  }
+  return false
+}
+
+function isGroupEqual(a: FilterGroup, b: FilterGroup): boolean {
+  if (a.conjunction !== b.conjunction) return false
+  if (a.children.length !== b.children.length) return false
+  return a.children.every((c, i) => isConditionEqual(c, b.children[i]))
+}
+
+function isConditionEqual(a: FilterCondition, b: FilterCondition): boolean {
+  if (a.field !== b.field || a.op !== b.op) return false
+  return JSON.stringify(a.value) === JSON.stringify(b.value)
+}
+
+// ── Tree Evaluation(globalFilter approach)──────────────────────────────
+
+/**
+ * 整棵 FilterTree 對 row 求 boolean。
+ * 配合 useReactTable `globalFilterFn`:
+ *
+ *   const tree = useState<FilterTree>(createEmptyFilterTree('flat'))
+ *   useReactTable({
+ *     state: { globalFilter: tree },
+ *     onGlobalFilterChange: setTree,
+ *     globalFilterFn: (row, _, t: FilterTree) => evaluateTree(t, row.original),
+ *     getFilteredRowModel: getFilteredRowModel(),
+ *   })
+ */
+// any-allow: row-generic — TanStack row.original 是 generic,filter eval 跨 type 必走 any
+export function evaluateTree(tree: FilterTree, row: any): boolean {
+  if (tree.children.length === 0) return true
+
+  if (tree.mode === 'flat') {
+    const completed = tree.children.filter(isConditionComplete)
+    if (completed.length === 0) return true
+    const results = completed.map((c) => evaluateCondition(c, row))
+    return tree.conjunction === 'and' ? results.every(Boolean) : results.some(Boolean)
+  }
+
+  // nested
+  const groupResults = tree.children.map((g) => evaluateGroup(g, row))
+  // group 沒任何 complete condition 的視為 pass-through(true)
+  const meaningful = groupResults.filter((_, i) => tree.children[i].children.some(isConditionComplete))
+  if (meaningful.length === 0) return true
+  return tree.conjunction === 'and' ? meaningful.every(Boolean) : meaningful.some(Boolean)
+}
+
+// any-allow: row-generic
+function evaluateGroup(group: FilterGroup, row: any): boolean {
+  const completed = group.children.filter(isConditionComplete)
+  if (completed.length === 0) return true
+  const results = completed.map((c) => evaluateCondition(c, row))
+  return group.conjunction === 'and' ? results.every(Boolean) : results.some(Boolean)
+}
+
+// any-allow: row-generic
+function evaluateCondition(cond: FilterCondition, row: any): boolean {
+  if (!cond.field || !cond.op) return true
+  const cellValue = row?.[cond.field]
+  return matchOperator(cond.op, cellValue, cond.value)
+}
+
+// PersonValue identity helper(2026-05-07):
+// person/multiPerson cell value 是 `{ name, avatarUrl?, description? }` 物件 — 比對時用 `name`
+// 當 stable id(PeoplePicker SSOT 沒有 id field,name 是唯一身分標識)。對齊 Notion / Linear /
+// Asana 的 person filter 比對 idiom(都用 name/email 當 id)。
+function personId(v: unknown): string {
+  if (v && typeof v === 'object' && 'name' in v) return String((v as { name: unknown }).name ?? '')
+  return String(v ?? '')
+}
+function isPersonObject(v: unknown): v is { name: string } {
+  return !!v && typeof v === 'object' && 'name' in v
+}
+
+// code-quality-allow: long-function — 13-operator switch dispatch table,table-driven 重構會把 op-specific guards 拆出反增 indirection
+function matchOperator(op: string, cellValue: unknown, filterValue: unknown): boolean {
+  // 不需 value 的 op
+  switch (op) {
+    case 'is_set':     return cellValue !== null && cellValue !== undefined && cellValue !== ''
+    case 'is_not_set': return cellValue === null || cellValue === undefined || cellValue === ''
+    case 'is_true':    return cellValue === true
+    case 'is_false':   return cellValue === false
+  }
+
+  // 需 value 但 value 空 → 視為 incomplete,pass-through
+  if (filterValue === null || filterValue === undefined || filterValue === '') return true
+  if (Array.isArray(filterValue) && filterValue.length === 0) return true
+
+  // Person-aware specialization(person_single / person_multi)— 物件透過 name 比對。
+  // 偵測:cellValue 或 filterValue 任一是 Person object(或包 Person 的陣列)→ 走 personId path。
+  const cellIsPerson = isPersonObject(cellValue) || (Array.isArray(cellValue) && cellValue.some(isPersonObject))
+  const filterIsPerson = isPersonObject(filterValue) || (Array.isArray(filterValue) && filterValue.some(isPersonObject))
+  if (cellIsPerson || filterIsPerson) {
+    const cellIds = Array.isArray(cellValue) ? cellValue.map(personId) : [personId(cellValue)]
+    const filterIds = Array.isArray(filterValue) ? filterValue.map(personId) : [personId(filterValue)]
+    switch (op) {
+      case 'is':         return cellIds.length === 1 && filterIds.length >= 1 && filterIds.includes(cellIds[0])
+      case 'is_not':     return !(cellIds.length === 1 && filterIds.length >= 1 && filterIds.includes(cellIds[0]))
+      case 'has_any_of': return cellIds.some((c) => filterIds.includes(c))
+      case 'has_all_of': return filterIds.every((f) => cellIds.includes(f))
+      case 'has_none_of':return !cellIds.some((c) => filterIds.includes(c))
+      default:           return true
+    }
+  }
+
+  switch (op) {
+    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
+    // 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 → 結果空。
+    // Fix:加 array handling,走 OR 語意:any → match;is_not → every-not-match。
+    case 'is':
+      if (Array.isArray(filterValue))
+        return filterValue.some((v) => String(cellValue ?? '').toLowerCase() === String(v).toLowerCase())
+      return String(cellValue ?? '').toLowerCase() === String(filterValue).toLowerCase()
+    case 'is_not':
+      if (Array.isArray(filterValue))
+        return filterValue.every((v) => String(cellValue ?? '').toLowerCase() !== String(v).toLowerCase())
+      return String(cellValue ?? '').toLowerCase() !== String(filterValue).toLowerCase()
+    case 'starts_with':      return String(cellValue ?? '').toLowerCase().startsWith(String(filterValue).toLowerCase())
+    case 'ends_with':        return String(cellValue ?? '').toLowerCase().endsWith(String(filterValue).toLowerCase())
+
+    case 'equals':     return Number(cellValue) === Number(filterValue)
+    case 'not_equals': return Number(cellValue) !== Number(filterValue)
+    case 'gt':         return Number(cellValue) > Number(filterValue)
+    case 'gte':        return Number(cellValue) >= Number(filterValue)
+    case 'lt':         return Number(cellValue) < Number(filterValue)
+    case 'lte':        return Number(cellValue) <= Number(filterValue)
+
+    case 'is_before':       return new Date(String(cellValue)).getTime() < new Date(String(filterValue)).getTime()
+    case 'is_after':        return new Date(String(cellValue)).getTime() > new Date(String(filterValue)).getTime()
+    case 'is_on_or_before': return new Date(String(cellValue)).getTime() <= new Date(String(filterValue)).getTime()
+    case 'is_on_or_after':  return new Date(String(cellValue)).getTime() >= new Date(String(filterValue)).getTime()
+    case 'is_between': {
+      if (!Array.isArray(filterValue) || filterValue.length !== 2) return true
+      const cv = new Date(String(cellValue)).getTime()
+      const start = filterValue[0] ? new Date(String(filterValue[0])).getTime() : -Infinity
+      const end = filterValue[1] ? new Date(String(filterValue[1])).getTime() : Infinity
+      return cv >= start && cv <= end
+    }
+    case 'is_relative': {
+      // Phase D 完整實作 — relative key → time range → in-range test
+      const range = relativeKeyToRange(String(filterValue))
+      if (!range) return true  // unknown key,pass-through
+      const cv = new Date(String(cellValue)).getTime()
+      if (Number.isNaN(cv)) return false  // invalid cellValue → 不命中
+      const [start, end] = range
+      return cv >= start && cv <= end
+    }
+
+    case 'has_any_of': {
+      if (!Array.isArray(filterValue)) return true
+      if (Array.isArray(cellValue)) return cellValue.some((c) => filterValue.includes(c))
+      return filterValue.includes(cellValue)
+    }
+    case 'has_all_of': {
+      if (!Array.isArray(filterValue)) return true
+      if (Array.isArray(cellValue)) return filterValue.every((v) => cellValue.includes(v))
+      return false
+    }
+    case 'has_none_of': {
+      if (!Array.isArray(filterValue)) return true
+      if (Array.isArray(cellValue)) return !cellValue.some((c) => filterValue.includes(c))
+      return !filterValue.includes(cellValue)
+    }
+
+    default: return true
+  }
+}
+
+/**
+ * @deprecated v0.x — old per-column filterFn integration。
+ * 新版用 `evaluateTree` 配 TanStack `globalFilter`。
+ * 保留為了過渡期 backward-compat,新 consumer 不要用。
+ */
+export function dataTableFilterMatch(cellValue: unknown, filterValue: unknown): boolean {
+  if (typeof filterValue === 'object' && filterValue !== null && 'operator' in filterValue && 'value' in filterValue) {
+    const fv = filterValue as { operator: string; value: unknown }
+    return matchOperator(fv.operator, cellValue, fv.value)
+  }
+  return String(cellValue ?? '').toLowerCase().includes(String(filterValue ?? '').toLowerCase())
+}

package/src/components/DataTable/lib/column-meta.ts

@@ -0,0 +1,79 @@
+/**
+ * column-meta — TanStack ColumnDef typed accessor helpers.
+ *
+ * **Scope:Internal-only — DataTable 自用,非 public API**(本檔不 re-export 出
+ * `data-table-filter-panel.tsx` / `data-table.tsx`,consumer 透過 panel / sort-manager
+ * 間接使用)。M21 (a) classification:lib/ folder 慣例 = internal helper。
+ *
+ * 為什麼存在:`ColumnDef<T, V>` 是 discriminated union(AccessorKey / AccessorFn /
+ * Display / Group),每個 variant 有不同欄位,直接 `col.id` 在型別上不安全。
+ * 既有 consumer 用 `(col as any).id` cast,3+ 處 hard-code = M17 違反。
+ * 抽成 typed helper 統一型別 narrowing,消除 `any` cast。
+ *
+ * Why not annotate each `as any`:DRY + single SSOT for column field access。
+ * 任一 helper 行為變更(e.g. 加 fallback 邏輯)只需改一處。
+ *
+ * 對齊 mindset #2 「優先消費既有」+ M17「同 hard-code 在 3+ consumer 必抽」。
+ */
+
+import type { ColumnDef, ColumnMeta, RowData } from '@tanstack/react-table'
+
+/**
+ * 取 column 的 stable identifier。
+ *
+ * 解析順序對齊 TanStack 內部行為:
+ * 1. `col.id`(顯式設定優先)
+ * 2. `col.accessorKey`(string version,fallback for accessor columns)
+ *
+ * 都無 → return undefined(display column 無 accessorKey 且未設 id)。
+ */
+export function getColumnId<T extends RowData>(
+  col: ColumnDef<T, unknown>,
+): string | undefined {
+  if ('id' in col && typeof col.id === 'string' && col.id) return col.id
+  if (
+    'accessorKey' in col &&
+    (typeof col.accessorKey === 'string' || typeof col.accessorKey === 'number')
+  ) {
+    return String(col.accessorKey)
+  }
+  return undefined
+}
+
+/**
+ * 取 column 的 header 定義(可為 string / React node / function — TanStack 規約)。
+ *
+ * 注意:本 helper 不執行 header function。consumer 若需 rendered string,
+ * 自行 narrow + call,或用 TanStack `flexRender` API。
+ */
+export function getColumnHeader<T extends RowData>(
+  col: ColumnDef<T, unknown>,
+): ColumnDef<T, unknown>['header'] {
+  return 'header' in col ? col.header : undefined
+}
+
+/**
+ * 取 column 的 meta(本 DS 的 ColumnMeta 已 extend 加上 type / align / wrap 等)。
+ */
+export function getColumnMeta<T extends RowData>(
+  col: ColumnDef<T, unknown>,
+): ColumnMeta<T, unknown> | undefined {
+  return col.meta
+}
+
+/**
+ * 從 header 定義抽 plain string label(filter / sort UI 顯示用)。
+ *
+ * 處理 3 種 header 形式:
+ * - string → 直接 return
+ * - function → 不執行(避過 React render context),fallback id
+ * - undefined / 其他 → fallback id
+ */
+export function getColumnLabel<T extends RowData>(
+  col: ColumnDef<T, unknown>,
+  fallbackId?: string,
+): string {
+  const header = getColumnHeader(col)
+  if (typeof header === 'string') return header
+  return fallbackId ?? getColumnId(col) ?? ''
+}