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

package/src/components/DataTable/filter-operators.spec.md

@@ -0,0 +1,269 @@
+# Advanced Filter 設計原則(Operator × ColumnType × ValueShape SSOT,v3)
+
+> **狀態**:已落地 — registry 寫成 `filter-operators.ts`,`filter-tree.ts` + filter panel 家族消費(`data-table-filter-panel.tsx`;row/picker 直接消費點在 2026-07-14 拆檔子模組 `data-table-filter-group.tsx` / `data-table-filter-value-picker.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 精度;default day 級(`startOfDay` 截斷,含 `is` 日期比對 — 2026-07-04 Q6 實作於 `filter-tree.ts` `datePrecision`)(避開 Airtable 著名地雷:filter 忽略 time)
+- **不新增 `time-only` column type**(業界沒人做,罕見場景)—— 後續 Phase C(2026-05-05)已補 `'time'` columnType 供 cell render(`<TimePicker>`);advanced filter 暫 reuse `DATE_OPS`,`time_*` ValueShape 整合留 Phase D+(見 `filter-operators.ts` registry 註解)
+
+## 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` | `<Combobox>` 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 兩者都共用 `<Combobox>` DS 既有元件(code 真值 `data-table-filter-value-picker.tsx` select_multi case;2026-07-14 拆檔自 panel)。
+
+### `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 | registry 繁中 label 作預設；panel 以 `labels.operatorLabels` / relative-date maps 提供 consumer i18n override | ✅ 2026-07-31 落地 |
+| 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` / filter panel 家族:`data-table-filter-panel.tsx` + `data-table-filter-group.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`)
+
+**A11y / Loading(明文 N/A)**:本 spec 是 Operator × ColumnType × ValueShape 資料模型 SSOT(非 UI 元件)——filter panel 的互動 a11y / loading 狀態屬 UI 層 owner(`data-table.spec.md` + filter panel 家族元件)與各 Field 控件 spec。
+
+## 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 策略 — registry 繁中 label 保持預設 SSOT；`DataTableFilterPanel labels` 可 deep-partial override operator、relative-date group / option 與全部 panel chrome(2026-07-31)
+- [→] 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 {
@@ -53,6 +53,11 @@ export interface FilterCondition {
   op: string
   /** 依 ValueShape 解讀的值 */
   value: unknown
+  /** Date 欄位比對精度(2026-07-04 Q6 拍板,兌現 spec「includeTime」雙精度契約):
+   *  panel 建 condition 時依 column meta 寫入 — includeTime=true → 'ms',否則 'day'
+   *  (AG Grid midnight-truncate / MUI X setHours(0,0,0,0) 共識;避 Airtable 邊界漏抓地雷)。
+   *  非 date 欄位 / 舊 tree 無此欄 → undefined(date ops fallback 'day' 預設)。 */
+  datePrecision?: 'day' | 'ms'
 }
 
 export interface FilterGroup {
@@ -105,13 +110,21 @@ function isConditionComplete(c: FilterCondition): boolean {
   return c.value !== '' && c.value !== null && c.value !== undefined
 }
 
-/** loose lookup — 我們不知 columnType,試所有 type */
+/** loose lookup — 我們不知 columnType,試所有 type。
+ *  D3 perf(2026-07-06):module-level Map cache — OPERATOR_REGISTRY 是 module 常數,
+ *  同一 op key 查詢結果永不變;原每 call 線性掃全 registry,而 evaluateTree 熱路徑
+ *  per-row 呼叫時(10k rows × N conditions)放大成數十萬次比較,cache 後 O(1)。 */
+const opSpecLooseCache = new Map<string, OperatorSpec | null>()
 function getOperatorSpecLoose(op: string): OperatorSpec | null {
+  const cached = opSpecLooseCache.get(op)
+  if (cached !== undefined) return cached
+  let found: OperatorSpec | null = null
   for (const list of Object.values(OPERATOR_REGISTRY)) {
-    const found = list.find((o) => o.op === op)
-    if (found) return found
+    const hit = list.find((o) => o.op === op)
+    if (hit) { found = hit; break }
   }
-  return null
+  opSpecLooseCache.set(op, found)
+  return found
 }
 
 // ── Deep-equal compare(refresh icon 顯示判定用) ─────────────────────────
@@ -142,6 +155,68 @@ function isConditionEqual(a: FilterCondition, b: FilterCondition): boolean {
 
 // ── Tree Evaluation(globalFilter approach)──────────────────────────────
 
+// ── D3 perf(2026-07-06):per-condition compile-once cache ────────────────
+// TanStack globalFilterFn 逐 row 呼叫 evaluateTree,原實作每 row 重做「跨全 rows 不變」
+// 的常數工作:isConditionComplete(operator registry 掃描)、dateMs(filterValue) 重 parse、
+// filterValue 重 toLowerCase、is_relative 重算時間區間 — 10k rows × N conditions 全額放大。
+// Fix:以 condition 物件為 key 的 WeakMap 快取 filterValue 側預解析結果,row loop 只轉
+// cellValue 側。Panel 更新走 immutable `{ ...c, ...patch }`(新物件 = 新 cache entry),
+// 舊 entry 隨舊 condition 物件 GC — cache 無失效問題。
+interface PreparedCondition {
+  /** isConditionComplete 結果(registry 掃描一次,取代原 per-row filter 掃描) */
+  complete: boolean
+  /** filterValue 側是否 Person(物件或含 Person 的陣列) */
+  filterIsPerson: boolean
+  /** person 比對 ops 的 filter 側 id array(cellValue 是 Person 時也走 person path,故照 op 準備) */
+  filterPersonIds: string[] | null
+  /** 文字 ops 用:String(filterValue).toLowerCase() */
+  filterTextLower: string | null
+  /** is / is_not 陣列(多值 OR 語意)逐元素 lowercase */
+  filterTextLowerArr: string[] | null
+  /** 單值 date ops(is_before 家族;is / is_not with datePrecision)— datePrecision 已套 */
+  filterDateMs: number | null
+  /** is_between 兩端(空端 = ±Infinity,語意同原 inline 邏輯) */
+  filterDateStart: number | null
+  filterDateEnd: number | null
+  /** is_relative:快取區間 + 計算當日 stamp(跨日自動重算 — 所有 relative 區間都是
+   *  calendar day 的純函數,同日內恆定,見 localDayKey) */
+  relRange: [number, number] | null
+  relDayKey: number
+}
+
+const PERSON_CAPABLE_OPS = new Set(['is', 'is_not', 'has_any_of', 'has_all_of', 'has_none_of'])
+const DATE_SINGLE_OPS = new Set(['is_before', 'is_after', 'is_on_or_before', 'is_on_or_after'])
+const TEXT_OPS = new Set(['contains', 'does_not_contain', 'starts_with', 'ends_with', 'is', 'is_not'])
+
+const preparedCache = new WeakMap<FilterCondition, PreparedCondition>()
+
+function prepareCondition(c: FilterCondition): PreparedCondition {
+  const hit = preparedCache.get(c)
+  if (hit) return hit
+  const fv = c.value
+  const isBetweenPair = c.op === 'is_between' && Array.isArray(fv) && fv.length === 2
+  const prepared: PreparedCondition = {
+    complete: isConditionComplete(c),
+    filterIsPerson: isPersonObject(fv) || (Array.isArray(fv) && fv.some(isPersonObject)),
+    filterPersonIds: PERSON_CAPABLE_OPS.has(c.op)
+      ? (Array.isArray(fv) ? fv.map(personId) : [personId(fv)])
+      : null,
+    filterTextLower: TEXT_OPS.has(c.op) ? String(fv).toLowerCase() : null,
+    filterTextLowerArr:
+      (c.op === 'is' || c.op === 'is_not') && Array.isArray(fv) ? fv.map((v) => String(v).toLowerCase()) : null,
+    filterDateMs:
+      DATE_SINGLE_OPS.has(c.op) || ((c.op === 'is' || c.op === 'is_not') && c.datePrecision !== undefined)
+        ? toDateMs(fv, c.datePrecision)
+        : null,
+    filterDateStart: isBetweenPair ? (fv[0] ? toDateMs(fv[0], c.datePrecision) : -Infinity) : null,
+    filterDateEnd: isBetweenPair ? (fv[1] ? toDateMs(fv[1], c.datePrecision) : Infinity) : null,
+    relRange: null,
+    relDayKey: 0,
+  }
+  preparedCache.set(c, prepared)
+  return prepared
+}
+
 /**
  * 整棵 FilterTree 對 row 求 boolean。
  * 配合 useReactTable `globalFilterFn`:
@@ -159,33 +234,54 @@ 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)
+    // null = 無 complete condition → pass-through(語意同原 completed.length === 0 分支)
+    return evaluateConditionsJoined(tree.children, tree.conjunction, row) ?? true
   }
 
-  // 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)
+  // nested — group 沒任何 complete condition 的視為 pass-through(不參與 conjunction),
+  // 語意同原 meaningful filter
+  let sawMeaningful = false
+  for (const g of tree.children) {
+    const r = evaluateConditionsJoined(g.children, g.conjunction, row)
+    if (r === null) continue
+    sawMeaningful = true
+    if (tree.conjunction === 'and') {
+      if (!r) return false
+    } else if (r) {
+      return true
+    }
+  }
+  if (!sawMeaningful) return true
+  return tree.conjunction === 'and'
 }
 
+/** 一組 conditions 依 conjunction 求 boolean;null = 組內無 complete condition(pass-through)。
+ *  D3 perf:prepared.complete 取代原 per-row `children.filter(isConditionComplete)`
+ *  (registry 掃描 + filter/map 兩個中間陣列 alloc);and/or 短路 — 條件是 pure predicate
+ *  無副作用,求值順序 / 省略不影響結果。 */
 // 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)
+function evaluateConditionsJoined(children: FilterCondition[], conjunction: Conjunction, row: any): boolean | null {
+  let sawComplete = false
+  for (const c of children) {
+    const prepared = prepareCondition(c)
+    if (!prepared.complete) continue
+    sawComplete = true
+    const matched = evaluateCondition(c, prepared, row)
+    if (conjunction === 'and') {
+      if (!matched) return false
+    } else if (matched) {
+      return true
+    }
+  }
+  if (!sawComplete) return null
+  return conjunction === 'and'
 }
 
 // any-allow: row-generic
-function evaluateCondition(cond: FilterCondition, row: any): boolean {
+function evaluateCondition(cond: FilterCondition, prepared: PreparedCondition, row: any): boolean {
   if (!cond.field || !cond.op) return true
   const cellValue = row?.[cond.field]
-  return matchOperator(cond.op, cellValue, cond.value)
+  return matchOperator(cond.op, cellValue, cond.value, cond.datePrecision, prepared)
 }
 
 // PersonValue identity helper(2026-05-07):
@@ -200,8 +296,24 @@ function isPersonObject(v: unknown): v is { name: string } {
   return !!v && typeof v === 'object' && 'name' in v
 }
 
+// Q6(2026-07-04):date 比對精度 helper — 'ms' 全精度;其餘(含 undefined)day 級
+// (本地時區 startOfDay 截斷,對齊 AG Grid / MUI X date 欄 midnight 慣例)。
+// D3 perf(2026-07-06):自 matchOperator 內 closure 提升 top-level — prepareCondition
+// (filterValue 側,每 condition 一次)與 matchOperator(cellValue 側,每 row)共用同一實作。
+function toDateMs(v: unknown, datePrecision?: 'day' | 'ms'): number {
+  const d = new Date(String(v))
+  if (Number.isNaN(d.getTime())) return NaN
+  return datePrecision === 'ms' ? d.getTime() : startOfDay(d).getTime()
+}
+
+/** 本地日曆日 stamp(yyyymmdd)— is_relative 快取跨日失效判定(每 row 1 個 Date alloc,
+ *  取代原 relativeKeyToRange 每 row 4-10 個 Date alloc + 區間重算) */
+function localDayKey(d: Date): number {
+  return d.getFullYear() * 10000 + (d.getMonth() + 1) * 100 + d.getDate()
+}
+
 // 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 {
+function matchOperator(op: string, cellValue: unknown, filterValue: unknown, datePrecision?: 'day' | 'ms', prepared?: PreparedCondition): boolean {
   // 不需 value 的 op
   switch (op) {
     case 'is_set':     return cellValue !== null && cellValue !== undefined && cellValue !== ''
@@ -216,11 +328,14 @@ function matchOperator(op: string, cellValue: unknown, filterValue: unknown): bo
 
   // Person-aware specialization(person_single / person_multi)— 物件透過 name 比對。
   // 偵測:cellValue 或 filterValue 任一是 Person object(或包 Person 的陣列)→ 走 personId path。
+  // D3 perf:filterValue 側偵測 + id array 消費 prepared 快取(cellValue 側必然 per-row)。
   const cellIsPerson = isPersonObject(cellValue) || (Array.isArray(cellValue) && cellValue.some(isPersonObject))
-  const filterIsPerson = isPersonObject(filterValue) || (Array.isArray(filterValue) && filterValue.some(isPersonObject))
+  const filterIsPerson = prepared
+    ? prepared.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)]
+    const filterIds = prepared?.filterPersonIds ?? (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]))
@@ -231,25 +346,46 @@ function matchOperator(op: string, cellValue: unknown, filterValue: unknown): bo
     }
   }
 
+  // (date 精度 helper 已提升為 top-level `toDateMs`;文字 ops 的 filterValue lowercase 消費
+  //  prepared 快取,prepared 缺席 = deprecated dataTableFilterMatch 路徑 inline fallback — D3 perf)
+
   switch (op) {
-    case 'contains':         return String(cellValue ?? '').toLowerCase().includes(String(filterValue).toLowerCase())
-    case 'does_not_contain': return !String(cellValue ?? '').toLowerCase().includes(String(filterValue).toLowerCase())
+    case 'contains':         return String(cellValue ?? '').toLowerCase().includes(prepared?.filterTextLower ?? String(filterValue).toLowerCase())
+    case 'does_not_contain': return !String(cellValue ?? '').toLowerCase().includes(prepared?.filterTextLower ?? 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 → 結果空。
     // 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()
+      // Q6:date 欄位(datePrecision 有值)走日期比對非字串 — 「2026-06-01」與「2026-06-01 14:30」
+      // 在 day 精度下相等(原字串小寫相等連同日不同格式都漏)
+      if (datePrecision) {
+        const a = toDateMs(cellValue, datePrecision)
+        const b = prepared?.filterDateMs ?? toDateMs(filterValue, datePrecision)
+        return !Number.isNaN(a) && a === b
+      }
+      if (Array.isArray(filterValue)) {
+        const cellLower = String(cellValue ?? '').toLowerCase()
+        const filterLowers = prepared?.filterTextLowerArr ?? filterValue.map((v) => String(v).toLowerCase())
+        return filterLowers.some((v) => cellLower === v)
+      }
+      return String(cellValue ?? '').toLowerCase() === (prepared?.filterTextLower ?? 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())
+      if (datePrecision) {
+        const a = toDateMs(cellValue, datePrecision)
+        const b = prepared?.filterDateMs ?? toDateMs(filterValue, datePrecision)
+        return Number.isNaN(a) || a !== b
+      }
+      if (Array.isArray(filterValue)) {
+        const cellLower = String(cellValue ?? '').toLowerCase()
+        const filterLowers = prepared?.filterTextLowerArr ?? filterValue.map((v) => String(v).toLowerCase())
+        return filterLowers.every((v) => cellLower !== v)
+      }
+      return String(cellValue ?? '').toLowerCase() !== (prepared?.filterTextLower ?? String(filterValue).toLowerCase())
+    case 'starts_with':      return String(cellValue ?? '').toLowerCase().startsWith(prepared?.filterTextLower ?? String(filterValue).toLowerCase())
+    case 'ends_with':        return String(cellValue ?? '').toLowerCase().endsWith(prepared?.filterTextLower ?? String(filterValue).toLowerCase())
 
     case 'equals':     return Number(cellValue) === Number(filterValue)
     case 'not_equals': return Number(cellValue) !== Number(filterValue)
@@ -258,20 +394,34 @@ function matchOperator(op: string, cellValue: unknown, filterValue: unknown): bo
     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_before':       return toDateMs(cellValue, datePrecision) < (prepared?.filterDateMs ?? toDateMs(filterValue, datePrecision))
+    case 'is_after':        return toDateMs(cellValue, datePrecision) > (prepared?.filterDateMs ?? toDateMs(filterValue, datePrecision))
+    case 'is_on_or_before': return toDateMs(cellValue, datePrecision) <= (prepared?.filterDateMs ?? toDateMs(filterValue, datePrecision))
+    case 'is_on_or_after':  return toDateMs(cellValue, datePrecision) >= (prepared?.filterDateMs ?? toDateMs(filterValue, datePrecision))
     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
+      const cv = toDateMs(cellValue, datePrecision)
+      const start = prepared?.filterDateStart ?? (filterValue[0] ? toDateMs(filterValue[0], datePrecision) : -Infinity)
+      const end = prepared?.filterDateEnd ?? (filterValue[1] ? toDateMs(filterValue[1], datePrecision) : Infinity)
       return cv >= start && cv <= end
     }
     case 'is_relative': {
       // Phase D 完整實作 — relative key → time range → in-range test
-      const range = relativeKeyToRange(String(filterValue))
+      // D3 perf:relativeKeyToRange 所有輸出都是 calendar day 的純函數(today / this_week /
+      // past_7_days… 全是日界),同日內恆定 → 以 localDayKey 判跨日,同日重用快取區間
+      // (原每 row 重算 4-10 個 Date alloc)。
+      let range: [number, number] | null
+      if (prepared) {
+        const now = new Date()
+        const dayKey = localDayKey(now)
+        if (prepared.relDayKey !== dayKey) {
+          prepared.relRange = relativeKeyToRange(String(filterValue), now)
+          prepared.relDayKey = dayKey
+        }
+        range = prepared.relRange
+      } else {
+        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 → 不命中

package/src/components/DataTable/index.ts

@@ -0,0 +1,8 @@
+// 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'
+export * from './data-table-column-visibility-panel'
+export * from './data-table-filter-panel'
+export * from './data-table-sort-manager'