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

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

@@ -11,8 +11,8 @@
 - **加 `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**(業界沒人做,罕見場景)
+- **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 種)
 
@@ -28,7 +28,7 @@
 | `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 語意) |
+| `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>` 單選 | (預留)罕用 |
@@ -133,7 +133,7 @@
 | 1-to-1 比對 | ✓ `is` / `is_not`(picker 多選 OR-語意) | ✗ 不適用(陣列比單值 ambiguous) |
 | 集合運算 | ✗ 不適用 | ✓ `has_any_of` / `has_all_of` / `has_none_of` |
 
-差異**根源於 cell 資料形狀**,不是 picker 不同。Value picker 兩者都共用 `SelectMenu` DS 既有元件。
+差異**根源於 cell 資料形狀**,不是 picker 不同。Value picker 兩者都共用 `<Combobox>` DS 既有元件(code 真值 `data-table-filter-panel.tsx` select_multi case)。
 
 ### `person`(4 ops — 跟 select 同邏輯)
 | op key | 中 | en | valueShape | CU | AT | NT |

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

@@ -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,9 +346,12 @@ 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 `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 都走
@@ -241,15 +359,33 @@ function matchOperator(op: string, cellValue: unknown, filterValue: unknown): bo
     // 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/DateGrid/date-grid.anatomy.stories.tsx

@@ -133,7 +133,7 @@ export const Overview = {
             </thead>
             <tbody>
               {[
-                ['mode', "'single' | 'multiple' | 'range'", "'single'", '選擇模式(react-day-picker v9)'],
+                ['mode', "'single' | 'multiple' | 'range'", '—', '選擇模式(react-day-picker v9;無預設,未傳時 grid 為非互動純展示)'],
                 ['selected', 'Date | Date[] | { from; to? }', '—', '受控值,型別依 mode 決定'],
                 ['onSelect', '(value) => void', '—', '值變動回呼,參數型別依 mode'],
                 ['defaultMonth', 'Date', 'new Date()', '初始可見月份'],

package/src/components/DateGrid/date-grid.spec.md

@@ -68,17 +68,19 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 
 | mode | 選擇行為 | 典型場景 |
 |------|---------|---------|
-| `single`（預設） | 單日選取,點新日取代舊選 | DatePicker / 生日 / 到期日 |
+| `single` | 單日選取,點新日取代舊選 | DatePicker / 生日 / 到期日 |
 | `multiple` | 可勾選多個不連續日期 | event 報名多日 |
 | `range` | from → to 連續範圍 | 訂單日期範圍 / 查詢時段 |
 
+**mode 無預設值**(react-day-picker v9 `mode?: Mode | undefined`,本元件薄包裝不補 default):未傳 `mode` 時 grid 為**非互動純展示**(day 渲染純文字非 button,不可選);DS 內所有消費者(DatePicker / stories)皆顯式傳 `mode`。
+
 **range vs multiple 分界**:選的是「連續區間」(只在乎起迄兩端)→ `range`;選的是「各自獨立的日子」(可不連續、逐日增減)→ `multiple`。起迄日場景(訂單 / 查詢時段)固定走 `range`;簽核 / 報名這類逐日勾選走 `multiple`。
 
 ---
 
 ## 實作機制:classNames 鏡射 modifier keys(2026-04-21 AR43 修正)
 
-**重要**:react-day-picker v9 的 cell 只有 `data-selected / data-disabled / data-today / data-outside / data-focused` 這幾個 DOM attribute;**`data-range-start / data-range-middle / data-range-end` 不存在**。
+**重要**:react-day-picker v9 的 cell state DOM attribute 只有 `data-selected / data-disabled / data-today / data-outside / data-focused`(另有非 state 的 `data-day / data-month / data-hidden`);**`data-range-start / data-range-middle / data-range-end` 不存在**。
 
 因此用 `[&[data-range-middle=true]]:xxx` 這種 attribute selector **根本不會生效**(舊版做法錯誤)。
 
@@ -106,15 +108,16 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 | **selected / range 端點** | 藍底白字圓 | button `primary` 底 + `on-emphasis` 字 | range_start / range_end 共用此視覺 |
 | **range 端點 cell bg** | 灰底半圓 track,**高度 = button**,向 middle 外擴 2px bridge gap | `neutral-selected`;class 細節見「Range track canonical」+ tsx | 圓弧半徑 = button 半徑無錯位;舊版 cell-level bg 圓弧半徑 16px 比 button 14px 大 = 視覺 misalign |
 | **range track(中間)** | 灰底矩形,**高度 = button**(28×28 @ md),左右各外擴 2px 接合相鄰 cell | `neutral-selected`;button 透明顯露 track(class 細節見 tsx)| track 高度跟 selected 圓一致,不留 2px「fat」邊;相鄰 pseudo 接合連貫橫向 track |
-| **hover(未選中)** | 藍圈 outline(無 fill) | button hover ring 色 `primary`,無 bg(ring 寬度等 class 細節見 tsx)| 細 ring 對齊 Apple HIG `@benchmark-unverified` / Ant `@benchmark-unverified`(visual,non-source-citable) |
+| **hover(未選中)** | 藍圈 outline(無 fill) | button hover ring 色 `primary-hover`(2026-07-07 user 拍板統一:瞬時 hover 進 primary 家族 = hover 階,FileUpload / Slider thumb hover 同族;base 專屬持續選中與 focus),無 bg(ring 寬度等 class 細節見 tsx)| 細 ring 對齊 Apple HIG `@benchmark-unverified` / Ant `@benchmark-unverified`(visual,non-source-citable) |
 
 ## 組合狀態(state stacking order)
 
 - today + selected → selected 勝出的**底色**(藍底白字圓);bar 跟著切 on-emphasis(白)保持可見
 - range-start / range-end → selected 規則(cell 半圓 track + button 圓)
 - range-middle → track 規則(cell 灰底矩形 + button 透明)
-- today + range-middle → track(灰底)+ today bar(藍色仍可見,cell 未 selected)
-- hover 在 selected / disabled 上被 ring-0 壓制(避免二次 hover 出現方框 bug);range-middle 的 button 透明顯露 track,hover ring 仍顯示(見 tsx `range_middle` 註解)
+- today + range-middle → track(灰底)+ today bar **維持藍色**(2026-07-07 user 拍板:切白只屬「藍底白字圓」的選中日/端點;range 中段是淺灰底,白 bar 近乎隱形 = today 標記消失。range_middle 以 `!bg-primary` 覆寫 today 的 `data-selected` 切白——RDP v9 range 中段日同樣掛 selected modifier 故會誤觸發。對照 Ant panel.ts:cell-today 指示 = colorPrimary,in-range 只換底色、無規則隱藏/改色 today 指示)
+- hover 在 selected / disabled 上被 ring-0 壓制(避免二次 hover 出現方框 bug);range-middle 因同樣掛 selected modifier,button hover ring **一併被 selected 的 ring-0 壓制**(與 selected 一致的 hover 抑制;button 透明僅顯露 track — 2026-07-05 對照 RDP source 修正舊句「hover ring 仍顯示」)
+- **選中日 hover 底色升階**:ring 壓制之外,選中日 hover 時 `bg-primary → bg-primary-hover`(2026-07-06 補明文——「選中之上 hover = 同色相升 hover 階」家族,Checkbox / Switch checked hover 同款;code 已有此行為,本句消 spec-code 落差)
 
 ## Spacing canonical(2026-05-03 v8)
 
@@ -127,13 +130,13 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 - **Caption row alignment canonical**:`pt-3 + h-field-xs + mb-3 = 12 + 24 + 12 = 48px`
   - DateGrid month_caption + TimePickerSidePanel header **必走同樣 48px caption row 結構**
   - title text vertical center Y 一致 = 12 + 12 = 24px(from container top)
-  - ⚠️ 改 DateGrid `p-3` → 必同步改 `TimePickerSidePanel py-3`,否則對齊破
+  - ⚠️ 改 DateGrid `p-3` → 必同步改 `TimePickerSidePanel pt-3`(root 刻意 bottom = 0,見 date-picker.tsx docblock),否則對齊破
 
 **為什麼用 `h-field-sm` 而非固定 `h-9`**:picker grid 在 lg density 下也要跟 Input 系統一起放大,`h-field-sm` 在 md = 28px / lg = 32px,比 Ant/Google 固定 36px(`@benchmark-unverified` visual measurement)稍緊但對齊本 DS 的 field 家族。day cell 尺寸雖固定,但**隨 density 縮放**,視覺跟 popup 內其他欄位(Input / Button)保持比例。
 
 ## Nav button canonical(2026-05-03 v9)
 
-Prev/Next chevron 用 `<Button variant="text" size="xs" iconOnly>`(DS primitive 消費,不 hand-coded inline-flex)。透過 RDP v9 `components.PreviousMonthButton / NextMonthButton` override(`node_modules/react-day-picker/dist/esm/components/Nav.js` 證實支援)。
+Prev/Next chevron 用 `<Button variant="text" size="xs" iconOnly>`(DS primitive 消費,不 hand-coded inline-flex)。透過 RDP v9 `components.PreviousMonthButton / NextMonthButton` override(本元件 `navLayout="around"` 下按鈕由 `DayPicker.js` 於首/末月 caption 兩側直渲;無 navLayout 時才走 `Nav.js` — 兩路徑皆消費此 override,`node_modules/react-day-picker/dist/esm/` 證實)。
 
 **Icon 顏色 = Button 預設 `text-foreground`(neutral-9 / 85% 黑)**,**對齊 DS 一致設計語言**(M23):
 - Icon-only Button 預設 = neutral-9(本 DS 既有 canonical)
@@ -176,7 +179,7 @@ react-day-picker v9 自動處理:
 - **Focus**：`autoFocus` prop 自動 focus 到選中日(或今天)
 - **Locale**：`locale` prop 控制週首日、星期標頭語言
 
-**DS 自訂部分**:day button 的 focus ring 由本元件 classNames 覆寫為 DS canonical(`focus-visible:ring-2 ring-ring`,非 RDP 預設樣式);nav 按鈕為 DS `<Button>` 並帶 `aria-label`(上一個月 / 下一個月)。其餘 consumer 無需額外處理,保留 react-day-picker API 即可。
+**DS 自訂部分**:day button 的 focus ring 由本元件 classNames 覆寫為 DS canonical(`focus-visible:ring-2 ring-ring`,非 RDP 預設樣式);SR 文案經 RDP `labels` API 提供中文 default(nav「上一個月 / 下一個月」、day / weekday / grid 等全繁中,對齊 2026-07-04 全庫 SR label 中文 canonical),consumer 傳 `labels` 可逐鍵覆寫(i18n),不在 components override 內 hardcode `aria-label`(會蓋死覆寫通道)。其餘 consumer 無需額外處理,保留 react-day-picker API 即可。
 
 ---
 

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

@@ -23,7 +23,7 @@ import { Button } from '@/design-system/components/Button/button'
  * | Nav + Month caption row | h-field-xs(24px)單行,chevron(xs)分居左右 / 月份置中垂直對齊 |
  * | Nav → Weekday gap | 12px(month_caption mb-3) |
  * | Weekday | text-body(14px)text-foreground font-medium(neutral-9,同 caption 權重;撤銷 v3 fg-secondary) |
- * | Cell gap(水平 + 垂直)| 4px(gap-1) |
+ * | Cell gap(水平 + 垂直)| 4px(table-native border-separate border-spacing-1;非 gap — grid 會 break,見下方 v7 註) |
  * | Day cell size | h-field-sm w-[var(--field-height-sm)](28×28 md / 32×32 lg) |
  * | Day button | rounded-full 填滿 cell |
  *
@@ -37,7 +37,7 @@ import { Button } from '@/design-system/components/Button/button'
  * | selected / range 端點 | 藍底白字圓 | [&>button]:bg-primary [&>button]:text-on-emphasis rounded-full |
  * | range middle | 灰底矩形 track(bg-neutral-selected = neutral-2),**高度 = cell 高度**(28×28 @ md) | before pseudo: `inset-y-0 -inset-x-[2px]` |
  * | range start/end 半圓 track | 左/右半圓 + selected 圓疊在上,**圓半徑 = button 半徑** | before pseudo: `rounded-l/r-full` + start `left-0 -right-[2px]` / end `-left-[2px] right-0`(向 middle 外擴 2px bridge gap)|
- * | hover(未選中) | 藍圈 outline | hover:ring-[1.5px] hover:ring-primary |
+ * | hover(未選中) | 藍圈 outline | hover:ring-[1.5px] hover:ring-primary-hover(2026-07-07 統一:瞬時 hover = hover 階)|
  *
  * ── Range track 高度 canonical(2026-05-03 v6,M8 4 家對照)──
  * Ant Design([picker source](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts))/ Material X DateRangePicker([mui-x source](https://github.com/mui/mui-x/tree/master/packages/x-date-pickers-pro/src/DateRangeCalendar))/ Apple Calendar `@benchmark-unverified`(closed-source)/ Google Calendar `@benchmark-unverified`(closed-source)共識:
@@ -57,11 +57,19 @@ import { Button } from '@/design-system/components/Button/button'
 
 export type DateGridProps = React.ComponentProps<typeof DayPicker>
 
+// ── SR label 中文 formatter(2026-07-05)──
+// 走 Intl.DateTimeFormat(對齊 TimePicker / Calendar 既有 canonical,不引第二套 date lib);
+// module-level 建一次 — label fn 每個 day cell 都會呼叫,避免 per-call new formatter。
+const ZH_FULL_DATE = new Intl.DateTimeFormat('zh-TW', { dateStyle: 'full' })
+const ZH_MONTH_YEAR = new Intl.DateTimeFormat('zh-TW', { year: 'numeric', month: 'long' })
+const ZH_WEEKDAY = new Intl.DateTimeFormat('zh-TW', { weekday: 'long' })
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGrid(
   {
     className,
     classNames,
+    labels,
     showOutsideDays = true,
     ...props
   },
@@ -114,7 +122,9 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
           'absolute inset-0 z-[1] flex items-center justify-center',
           'font-normal text-body rounded-full transition-colors',
           // Hover 藍圈 1.5px(對齊 Apple HIG / Ant `@benchmark-unverified` visual ring measurement)— ring 在 button 之上 + 透明 bg 不擋 range track
-          'hover:ring-[1.5px] hover:ring-primary hover:bg-transparent',
+          // 2026-07-07 user 拍板統一:瞬時 hover 進 primary 家族 = hover 階(FileUpload dropzone /
+          // Slider thumb hover 同族;base 專屬持續選中與 focus)——ring-primary → ring-primary-hover
+          'hover:ring-[1.5px] hover:ring-primary-hover hover:bg-transparent',
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
         ),
         // today:藍色 underline bar 貼近數字
@@ -124,7 +134,8 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
           '[&>button]:after:bottom-[5px] [&>button]:after:left-1/2 [&>button]:after:-translate-x-1/2',
           '[&>button]:after:w-[40%] [&>button]:after:h-[1.5px] [&>button]:after:rounded-full',
           '[&>button]:after:bg-primary',
-          // today + selected:bar 切 on-emphasis(白)
+          // today + selected:bar 切 on-emphasis(白)— 只為「藍底白字圓」的選中日/端點設計;
+          // range 中段(淺灰底)由 range_middle 的 !bg-primary 覆寫回藍(2026-07-07 user 拍板)。
           '[&[data-selected=true]>button]:after:bg-on-emphasis',
         ),
         outside: '[&>button]:text-fg-muted',
@@ -161,12 +172,53 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
         range_middle: cn(
           "before:content-[''] before:absolute before:inset-y-0 before:-inset-x-[2px]",
           'before:bg-neutral-selected before:pointer-events-none',
-          // button 透明顯露 track,但 hover ring 仍顯示
+          // 2026-07-07 user 拍板:range 中段的 today bar 維持藍(切白只屬藍底選中日;白條在
+          // neutral-selected 淺灰底上近乎隱形 = today 標記消失)。!important 確定性壓過 today 的
+          // data-selected 切白規則(同權重靠 stylesheet 順序不可靠)。Ant 源碼實錘:cell-today
+          // 指示 = colorPrimary,in-range 只換底色、無規則隱藏/改色 today 指示(panel.ts)。
+          // 非 today 的中段日無 after content,本規則無作用 — 安全。
+          '[&>button]:after:!bg-primary',
+          // button 透明顯露 track。2026-07-05 對齊 RDP v9 真實行為(deep-audit A.1b):
+          // range 中段日同樣掛 selected modifier(useRange rangeIncludesDate 不排除中段)→
+          // 上方 selected 的 `[&>button]:hover:ring-0` 一併壓制 hover ring(與 selected 一致
+          // 的 hover 抑制),非原註解宣稱的「hover ring 仍顯示」;today bar 亦被 data-selected
+          // selector 切 on-emphasis(見 spec「組合狀態」段)。
           '[&>button]:!bg-transparent [&>button]:!text-foreground',
         ),
         hidden: 'invisible',
         ...classNames,
       }}
+      // ── SR label 中文 defaults(2026-07-05,RDP labels API 正門)──
+      // 對齊 MUI X localeText「預設可覆寫」idiom + 2026-07-04 全庫 SR label 中文
+      // canonical(commit 241676c6):DS 給中文 default,consumer 傳 labels 逐鍵覆寫(i18n)。
+      // 禁在 components override 內 spread 後 hardcode aria-label — 會蓋死此覆寫通道
+      // (2026-07-05 修正 07-04 的錯誤修法:中文要走 labels 正門,不是蓋 RDP 算好的值)。
+      labels={{
+        labelPrevious: () => '上一個月',
+        labelNext: () => '下一個月',
+        // 鏡射 RDP default 結構(labels/labelDayButton.js:today 前綴 / selected 後綴),文案中文化
+        labelDayButton: (date, modifiers) => {
+          let label = ZH_FULL_DATE.format(date)
+          if (modifiers.today) label = `今天,${label}`
+          if (modifiers.selected) label = `${label},已選取`
+          return label
+        },
+        // 未傳 mode 的非互動 grid(spec「mode 無預設值」段)day cell 走 labelGridcell
+        labelGridcell: (date, modifiers) => {
+          let label = ZH_FULL_DATE.format(date)
+          if (modifiers?.today) label = `今天,${label}`
+          return label
+        },
+        labelGrid: (date) => ZH_MONTH_YEAR.format(date),
+        labelWeekday: (date) => ZH_WEEKDAY.format(date),
+        // 以下非 default 渲染面(captionLayout dropdown / showWeekNumber 由 consumer 經
+        // {...props} 開啟)— 一併補齊,避免開啟後 SR 中英夾雜
+        labelMonthDropdown: () => '選擇月份',
+        labelYearDropdown: () => '選擇年份',
+        labelWeekNumber: (weekNumber) => `第 ${weekNumber} 週`,
+        labelWeekNumberHeader: () => '週數',
+        ...labels,
+      }}
       components={{
         // ── Prev/Next nav(canonical 2026-05-03 v9,DS 一致設計語言)──
         // User 2026-05-03 audit:「icon-only Button icon 都用 neutral-9,只有 dismiss 用 45%」
@@ -174,14 +226,15 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
         // 不開新 tier 自打嘴(撤銷 v6-v8 用 fg-muted override 的 mistake)。
         // RDP v9 `PreviousMonthButton / NextMonthButton` override(node_modules/react-day-picker/dist/esm/components/Nav.js)
         // ⚠️ children: _ 必丟棄(RDP 把 <Chevron> 當 children 傳 → 跟 Button startIcon 重疊變 double chevron)
+        // 2026-07-05 修:此處**不** hardcode aria-label — 中文走上方 labels API 正門,
+        // RDP 算好 labelPrevious()/labelNext() 後經 {...props} 流入 Button;
+        // spread 後 hardcode(07-04 舊修法)= 蓋死 consumer labels 覆寫通道。
         PreviousMonthButton: ({ className, children: _children, ...props }) => (
           <Button variant="text" size="xs" iconOnly startIcon={ChevronLeft}
-            aria-label="上一個月"
             className={className} {...props} />
         ),
         NextMonthButton: ({ className, children: _children, ...props }) => (
           <Button variant="text" size="xs" iconOnly startIcon={ChevronRight}
-            aria-label="下一個月"
             className={className} {...props} />
         ),
       }}
@@ -202,7 +255,9 @@ export const dateGridMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 選中日期 / range 端點持續選中(藍底白字圓 bg-primary + range 帶 bg-neutral-selected);
+  // 'active' 移除 — 全檔無 Tailwind 按壓 utility,無按壓專屬視覺態(2026-07-07 詞彙統一對抗稽核補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-neutral-selected', 'bg-on-emphasis', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground', 'text-on-emphasis'],

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

@@ -32,7 +32,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

package/src/components/DatePicker/date-picker.spec.md

@@ -229,6 +229,7 @@ DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混
 - Range showTime footer **無「此刻」**(對齊 Ant `showNow={multiple ? false : showNow}`)— 只「確定」走 SurfaceFooter justify-end
 - value 格式:`'YYYY-MM-DDTHH:MM:SS'`(local-time 語意,不帶 timezone)
 - needConfirm=true 時 user 編輯先暫存 draft,trigger text 即時讀 draft(canonical 2026-05-03 v8 修);按確定才 onChange;false 時邊編邊 commit
+- **needConfirm 獨立於 showTime**(2026-07-05 D4 codify):date-only `<DatePicker needConfirm>` 亦成立,footer 渲染 gate = `showTime || needConfirm`(single 與 Range 一致)——needConfirm 時「確定」是唯一 commit 路徑,漏渲 footer = draft 永遠無法 commit 的死路(2026-07-05 修 single 漏 `|| needConfirm`)
 - showSeconds=false(default)→ TimeColumns 只顯示 H/M(對齊 Ant 預設)
 - Range cell disable(對齊 Ant `useRangeDisabledDate`):activeEnd='start' + end 已選 → date > end disabled;activeEnd='end' + start 已選 → date < start disabled
 - Range stadium pattern(canonical 2026-05-03 v8):rangeStart/End cell pseudo `before:rounded-l-full / rounded-r-full` 跟 button 圓的左/右半弧 EXACTLY OVERLAY → 無「凸出」(對齊 Ant `cell-range-start::before { border-radius: 9999px 0 0 9999px }`)

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

@@ -223,6 +223,25 @@ export const ShowTimePopoverOpen: Story = {
   play: openPopoverPlay('[role="combobox"]'),
 }
 
+/* ── OpenSnapshot:needConfirm date-only(2026-07-05 D4 修 footer gate 死路)── */
+export const NeedConfirmDateOnlyOpen: Story = {
+  name: 'needConfirm:合約生效日確認',
+  parameters: { docs: { description: { story: 'date-only + needConfirm:點日期只暫存 draft(trigger 即時顯示),footer「確定」才 commit onChange——footer 渲染 gate = showTime || needConfirm(2026-07-05 D4 修 single 漏 || needConfirm 時「點了日期什麼都不會發生」的死路)。適用選錯成本高的日期(合約生效日 / 帳單結算起算日)。Visual-audit OpenSnapshot verify date-only popover 有渲 footer(此刻 / 確定)。' } } },
+  render: () => {
+    const [effectiveDate, setEffectiveDate] = React.useState('2026-08-01')
+    return (
+      <div className="flex flex-col gap-4 max-w-xs" style={{ paddingBottom: 420 }}>
+        <p className="text-caption text-fg-muted">
+          合約生效日選錯成本高:點日期先暫存,按「確定」才真正寫入。
+        </p>
+        <DatePicker needConfirm value={effectiveDate} onChange={setEffectiveDate} />
+        <p className="text-caption text-fg-muted">已提交值:{effectiveDate || '(空)'}</p>
+      </div>
+    )
+  },
+  play: openPopoverPlay('[role="combobox"]'),
+}
+
 /* ── OpenSnapshot:showTime Range popover(activeEnd='start')── */
 export const ShowTimeRangePopoverOpen: Story = {
   name: 'showTime 範圍:浮層展開狀態',