@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

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

@@ -0,0 +1,215 @@
+---
+component: DateGrid
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInternal
+benchmark:
+  - react-day-picker (shadcn Calendar base): github.com/gpbl/react-day-picker
+  - Ant Design DatePicker: github.com/ant-design/ant-design/tree/master/components/date-picker
+  - MUI X Date Pickers: github.com/mui/mui-x/tree/master/packages/x-date-pickers
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+<!-- M22 retrofit DONE 2026-05-03 v11(real source URLs added inline below)-->
+
+# DateGrid 設計原則
+
+## 定位
+
+DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後導航 + 日 cell),**不直接面向 consumer**。2026-04-21 從原本的 `Calendar/` 改名為 `DateGrid/`,因為「Calendar」此命名在世界級 DS 慣例專指**事件檢視 canvas**(見 `../Calendar/calendar.spec.md`),而本元件只是「選日期用的格網」,不做事件呈現。保留 Calendar 名字給 event view 元件是世界級對齊。
+
+**實作基礎**:`react-day-picker@9` 包裝 + 本 DS token 覆寫預設視覺。所有 classNames 透過 `classNames` prop 注入,避免引入原生 `.rdp-*` 樣式漂移。
+
+**Layout Family**:非上述 family — composite / multi-section(月份 caption + 星期標頭 + 日期網格 + nav 按鈕,多區塊組合)。
+
+**Storybook title 層級**:`Design System/Internal/DateGrid/*`(非 Components/,因為它是 DatePicker 的 internal primitive;對齊 CLAUDE.md「Internal vs Components 判斷 test」:無預設視覺 context、所有 consumer 透過 DatePicker 包)。
+
+**世界級命名對照(為什麼不叫 Calendar)**:
+
+| DS | 「Calendar」此名字給誰 | DayPicker 內部格網叫什麼 |
+|----|-----------------------|-------------------------|
+| Notion | event calendar 檢視(月/週/日) | 無(DatePicker 另有 calendar popup) |
+| Google | Google Calendar(event 檢視) | 無公開 DS,DatePicker 另管 |
+| Ant Design | inline 行事曆(含事件) | 無(DatePicker 自建 panel) |
+| Apple HIG / Fantastical | event 檢視 | 無(DatePicker inline) |
+| Material MUI | `<Calendar>` 已棄 → `<DateCalendar>`(date picker grid,single-date only;Range 走另元件 `<DateRangeCalendar>`)— source: [github.com/mui/mui-x](https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/DateCalendar/DateCalendar.tsx) | `<DateCalendar>` |
+| React Aria | `<Calendar>`(date picker grid)— source: [react-spectrum.adobe.com](https://react-spectrum.adobe.com/react-aria/Calendar.html) `@benchmark-unverified`(WebFetch 403)| `<Calendar>` |
+| **本 DS** | **`<Calendar>`**(event 檢視 canvas,見 `../Calendar/`) | **`<DateGrid>`**(本元件) |
+
+結論:Material / React Aria 用 `Calendar` 指 date-picker-grid 有點誤導(user 以為是 event 檢視);本 DS 對齊 Notion / Google / Ant / Apple 的大眾認知,**`Calendar` 給 event view**、**`DateGrid` 給 date picker grid**。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 何時用
+
+- **Inline 月曆顯示**:dashboard / 行事曆小卡 / 日期 filter bar
+- **DatePicker 浮層內嵌**:DatePicker 消費本元件作為選日 popup(見 `../DatePicker/date-picker.spec.md`)
+- **範圍選擇**:`mode="range"` 適用「from → to」場景(訂單日期範圍、查詢時段)
+- **多日選擇**:`mode="multiple"` 適用「勾選多個不連續日期」(event sign-up)
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 日期輸入欄位 | `DatePicker` | Calendar 是 inline,欄位需要 trigger + popup 結構 |
+| 純顯示單日期 | `<DatePicker mode="display">` / `Intl.DateTimeFormat` | 不需 interactive 月曆 |
+| 時間選擇(時分) | ⚠️ 未來 TimePicker | Calendar 只處理日期層級 |
+| 事件行事曆(日程本) | 專用行事曆元件 | Calendar 是日期選擇;事件日誌需要 event overlay / drag / week/month view 切換 |
+
+---
+
+## mode(react-day-picker API)
+
+| mode | 選擇行為 | 典型場景 |
+|------|---------|---------|
+| `single`（預設） | 單日選取,點新日取代舊選 | DatePicker / 生日 / 到期日 |
+| `multiple` | 可勾選多個不連續日期 | event 報名多日 |
+| `range` | from → to 連續範圍 | 訂單日期範圍 / 查詢時段 |
+
+---
+
+## 實作機制: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` 不存在**。
+
+因此用 `[&[data-range-middle=true]]:xxx` 這種 attribute selector **根本不會生效**(舊版做法錯誤)。
+
+**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: 'bg-[var(--color-neutral-2)] [&>button]:!bg-transparent'`。
+
+`[&>button]:xxx` 從 cell 向內選子 button 用於 button-level 樣式(selected / disabled 的藍底白圓等)。
+
+---
+
+## 五種 cell state canonical(2026-04-21,AR43 定案)
+
+世界級對照 — Ant Design([github.com/ant-design/ant-design](https://github.com/ant-design/ant-design/tree/master/components/date-picker))/ Google Calendar / macOS Calendar / Material 3([mui/mui-x DateCalendar](https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/DateCalendar/DateCalendar.tsx))的 picker grid 共通做法 `@benchmark-unverified`(visual claims,non-source-citable):
+- today 不做 ring circle(跟 hover ring 混淆),改用 underline 或 dot
+- selected 用藍底白字圓,range 端點共用同樣視覺
+- range 中段用灰底 rectangle track,跟端點的圓相切成連續 pill
+- hover 非 filled(與 selected 區隔)
+- disabled 顯示灰底圓圈(明確「此格不可選」),非 opacity-50
+
+| State | 視覺 | Token 角色(class 細節見 tsx)| 備註 |
+|-------|------|------------------------------|------|
+| **today**(未選) | 數字下方短圓桿(藍) | button `::after` bar,色用 `primary`,尺寸靠近文字行底(不貼 button 邊) | affordance 方式,不 fill bg;位置刻意貼近數字避免「黏 button 邊」視覺 flaw |
+| **today + selected** | 數字下方短圓桿(白) | bar 色切 `on-emphasis` | 選中藍底上藍 bar 隱形,必切白;以 state 疊加 selector 覆寫 |
+| **disabled** | 灰底 + 淡字 | `bg-disabled` + `fg-disabled` + `cursor-not-allowed` | 跟 Button disabled token 一致,不自創 palette |
+| **outside(非本月)**| 淡字(只文字) | `fg-muted` | 比 disabled 弱:outside 仍可 hover / 可點,純是「非焦點月份」的標示 |
+| **selected / range 端點** | 藍底白字圓 | button `primary` 底 + `on-emphasis` 字(cell `data-selected="true"`) | range_start / range_end 共用此視覺 |
+| **range 端點 cell bg** | 灰底半圓 track,**高度 = button** | `before:` pseudo `inset-y-0.5` + `rounded-l/r-full` + `left/right-0.5`(M8 對齊 Ant `cell-range-start::before { border-radius: 9999px 0 0 9999px }` — [ant-design picker style](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts) `@benchmark-unverified` style file path,Material X / Apple / Google `@benchmark-unverified` visual)| 圓弧半徑 = button 半徑無錯位;舊版 cell-level bg 圓弧半徑 16px 比 button 14px 大 = 視覺 misalign |
+| **range track(中間)** | 灰底矩形,**高度 = button**(28×28 @ md)| `before:` pseudo `inset-y-0.5 inset-x-0` `bg-neutral-selected`(對齊 range_start/end pseudo + tsx L148/154/159 實作);button 透明顯露 track | track 高度跟 selected 圓一致,不留 2px「fat」邊;cell 寬度維持 32px → 相鄰 pseudo 接合連貫橫向 track |
+| **hover(未選中)** | 藍圈 outline(無 fill) | button hover ring 色 `primary`,寬度 1.5px,無 bg | 1.5px 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 / range-middle 上被 ring-0 壓制(避免二次 hover 出現方框 bug)
+
+## Spacing canonical(2026-05-03 v8)
+
+- 整個 popover padding `p-3`(12px,對齊 `--layout-space-tight` @ md density)
+- 四邊對稱:左右 chevron 按鈕到邊距 = 最左最右日期 cell 到邊距(12px)
+- 上下對稱:caption 到頂 = 最後一排日期到底(均 12px,從 `p-3` 繼承)
+- day cell 固定 `h-field-sm w-[var(--field-height-sm)]`(28px @ md / 32px @ lg)
+- week header 同寬,`h-field-sm`
+- **Cell 之間 gap = 4px(H + V)**:走 table-native `border-separate border-spacing-1`,不用 grid layout(grid 會 break border-spacing)
+- **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`,否則對齊破
+
+**為什麼用 `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` 證實支援)。
+
+**Icon 顏色 = Button 預設 `text-foreground`(neutral-9 / 85% 黑)**,**對齊 DS 一致設計語言**(M23):
+- Icon-only Button 預設 = neutral-9(本 DS 既有 canonical)
+- `fg-muted`(45%)專屬 dismiss / inline action / placeholder(spec.md 既有定義)
+- chevron nav 是 functional navigation,不是 dismiss → 不該套 fg-muted 自開新 tier
+
+歷史(2026-05-03):v6-v8 我憑印象引「Ant chevron muted」(`@benchmark-unverified` 印象,non-cited claim)覆蓋 DS canonical(text-fg-muted 45%)→ user 4 輪糾正後撤回(M23 防再犯)。
+
+⚠️ RDP `PreviousMonthButton` override 必丟 `children`(RDP 把 `<Chevron>` 當 children 傳)否則 double svg(2026-05-03 v8 抓到 bug)。
+
+## Weekday header canonical(2026-05-03 v9)
+
+`text-foreground text-body font-medium`(neutral-9 + 500 weight + body size)。對齊 caption「April 2026」同視覺權重(都屬 calendar header 區),不弱化。撤銷 v3 用 `fg-secondary font-normal` 的 mistake(M23)。
+
+## Range track canonical(2026-05-03 v8)
+
+對齊 Ant `cell-range-start::before { border-radius: 9999px 0 0 9999px }`(stadium pattern): <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- `range_start` cell pseudo:`before:left-0 -right-[2px] inset-y-0 rounded-l-full bg-neutral-selected`
+- `range_end` cell pseudo:鏡像 `rounded-r-full`
+- `range_middle` cell pseudo:`before:-inset-x-[2px] inset-y-0 bg-neutral-selected`(無 rounding)
+- pseudo 蓋全 cell + bridge 4px gap → button 圓的 corner triangle 看到 pseudo bg(對齊 button 圓的左/右半弧,無「凸出」)
+- `bg-neutral-selected`(semantic = neutral-2)— 對齊 TimePicker 選中項目樣式
+
+---
+
+## 禁止事項
+
+- ❌ **不改視覺 token 為硬色值**(`bg-primary` 必須來自 semantic,不可 `bg-blue-500`)
+- ❌ **不用 `.rdp-*` 原生 class 直接樣式化**(繞過本元件 classNames prop 會跨版本斷掉)
+- ❌ **不自包 Popover**(Calendar 是 inline primitive;需要浮層由 consumer 包 Popover,見 DatePicker)
+- ❌ **不混用其他 calendar library**(若 DateRange / DateTime 需求出現,擴充本元件 `mode="range"` 或新 prop,不引第二套)
+- ❌ **Consumer 不可外加 padding wrapper**(canonical 2026-05-02)— DateGrid root 自帶 `p-3`;`<div className="p-2"><DateGrid /></div>` 會造成 popover edge → 第一個 day cell 雙重 padding(8 + 12 = 20px),違反 mindset #2「優先消費既有 SSOT」。直接放 `<DateGrid />` 在 Popover/parent 內即可。Hook `check_primitive_wrapper_padding.sh` 機械攔截
+
+---
+
+## A11y 預設
+
+react-day-picker v9 自動處理:
+- **鍵盤**：ArrowLeft/Right 切日,ArrowUp/Down 切週,PageUp/Down 切月,Home/End 切週首尾
+- **ARIA**：`role="grid"` + 日格 `role="gridcell" aria-selected`
+- **Focus**：`autoFocus` prop 自動 focus 到選中日(或今天)
+- **Locale**：`locale` prop 控制週首日、星期標頭語言
+
+Consumer 無需額外處理,保留 react-day-picker API 即可。
+
+---
+
+## shadcn passthrough 例外說明
+
+Calendar 本元件是**對 `react-day-picker` 的 `<DayPicker>` 元件薄包裝**,用於橋接 DS token(classNames 覆寫 + components 注入自訂 IconLeft/IconRight)。**不套 `React.forwardRef`**,原因如下:
+
+- **底層 `DayPicker` 自己不接受 forwarded ref**——react-day-picker 的 API 是 declarative props(selected / onSelect / classNames / components 等),沒有 DOM ref 介面可 forward
+- **沒有我們擁有的 DOM root 可 ref**——Calendar 的視覺全由 `DayPicker` render,我們只注入 className token 覆寫,沒有自己的外層 `<div>` 容器
+- **Radix-compat 的 forwardRef 在此無意義**——若硬 wrap 成 `const Calendar = forwardRef(...)` 則 ref 會指向哪裡?指向 `DayPicker`(DayPicker 不支援),或指向 consumer 不期待的節點,都不對
+
+保留 `displayName = 'Calendar'` 讓 React DevTools / Storybook 辨識;`...props` 透過 props interface 顯式列舉 passthrough 至 DayPicker(不 spread DOM,保持 API 邊界清楚)。
+
+**何時應改**:若未來 react-day-picker 升級提供 forwardRef 或 `ref` prop,或我們決定包一層自有 DOM 容器(如加 footer action buttons),再改為 canonical forwardRef wrapper。
+
+---
+
+## 邊界案例
+
+- **Disabled day**:`disabled` prop 走 react-day-picker matcher;disabled cell 視覺 `text-fg-disabled`(M24)、`cursor-not-allowed`、click 不觸發 onSelect、鍵盤導覽自動 skip。
+- **Loading(server-rendered grid)**:DateGrid 為 sync render(date math 在 client),非 async surface。consumer 若需 async disabled-dates fetch(如後端 holiday list),應先 disable trigger 直到 fetch 完成,DateGrid 開啟後立即 ready。
+- **Empty(全 disabled days)**:極端場景(所有日期都被 disabled matcher 命中),DateGrid 渲完整 grid 但全部 cell 為 disabled state,鍵盤焦點停留無導覽目標(react-day-picker v9 內建)。
+- **Dark mode**:走 semantic token(primary / neutral / fg-muted)自動 adapt。
+- **Density**:DateGrid cell 尺寸固定不隨 density 變(date grid 為密度敏感的 8 列 × 6 行 layout,壓縮會破壞 reading)。
+
+---
+
+## 相關
+
+- `../DatePicker/date-picker.spec.md` — **本元件 consumer**:DatePicker 消費 Calendar 作為選日 popup
+- `../../tokens/color/color.spec.md` — semantic token 來源（primary / neutral / fg-muted 等）
+- react-day-picker 官方文件 — `https://react-day-picker.js.org`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `calendar.spec.md`
+- `date-picker.spec.md`

package/src/components/DateGrid/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './date-grid'

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

@@ -0,0 +1,334 @@
+---
+component: DatePicker
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design DatePicker: github.com/ant-design/ant-design/tree/master/components/date-picker
+  - MUI X Date Pickers: github.com/mui/mui-x/tree/master/packages/x-date-pickers
+  - react-day-picker: github.com/gpbl/react-day-picker
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — all world-class DS claims below have inline URL or per-claim retract. Frontmatter benchmark list expanded with canonical doc URLs. -->
+
+# DatePicker 設計原則
+
+## 定位
+
+DatePicker 是**單一日期**的輸入與顯示元件。Edit 用**本 DS 自建 DateGrid**(基於 `react-day-picker` + 本 DS token)+ Popover 呈現;Display 用 `Intl.DateTimeFormat`。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 DatePicker 特有的原則。
+
+**Layout Family**:CLAUDE.md 4-Family Model **Family 4(Field control layout)** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1(Menu item)讓 SelectMenu trigger + options 連續一致。
+
+**實作基礎**:
+- Trigger:`<button>` 包 `fieldWrapperStyles`(視覺仍是 Input wrapper,只是改為可點擊觸發浮層)
+- Popup:`Popover`(消費 overlay-surface pattern 外殼)
+- DateGrid 主體:消費 `<DateGrid>` 內部 primitive(見 `../DateGrid/date-grid.spec.md`;`react-day-picker` 包裝成本 DS token);**不是** `<Calendar>` — `<Calendar>` 是 event 檢視 canvas,跟 DatePicker 無關
+
+---
+
+## Controlled-only rationale(Dim 26)
+
+本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+
+**為什麼**:
+- 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
+- Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
+- 世界級對照:Ant Design DatePicker([ant.design/components/date-picker](https://ant.design/components/date-picker)) / Material MUI X DatePicker([mui.com/x/react-date-pickers/date-picker](https://mui.com/x/react-date-pickers/date-picker/))皆 value + defaultValue 共存;我們選 controlled-only 對齊狀態一致性優先
+
+**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
+
+---
+
+## 何時用
+
+- **單一日期選擇**：出生日、到期日、提醒日、發佈日
+- **需要 locale-aware 顯示**（`Intl.DateTimeFormat` 自動處理年月日順序、月份語言）
+- **需要視覺上與 Dialog / Popover / SelectMenu 一致的浮層體驗**（所有浮層都用我們的 token）
+- **DataTable 的日期欄位**（自動整合，meta.type='date'）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 日期範圍（from → to） | **`<DatePicker.Range>`**(本檔下「DatePicker.Range」段,2026-04-21 新增) | 仿 Ant `DatePicker.RangePicker` 架構:雙 input + 箭頭 + 共用 calendar icon,Popover 展開兩月份並列 |
+| 日期 + 時間（含時分） | **本元件加 `showTime` prop**(canonical 2026-05-02,Ant idiom) | DatePicker `showTime` / DatePickerRange `showTime` 內建 TimeColumns + 此刻/確定 footer;value 變 ISO datetime |
+| 相對時間（「3 天前」「昨天」）| 自訂 Display 元件 | DatePicker 的 Display 是絕對日期；相對時間需要計算 + locale 格式化 |
+| 純文字 YYYY-MM-DD（不需要 picker）| `Input` | 如 API debug 介面、不需互動的純記錄 |
+| 生日等「只有月日、不需要年」的欄位 | 目前用 DatePicker 忍受年份 | 多數情境可接受；要極致可自訂 MonthDayPicker |
+| Notion / Google 式 event calendar 檢視 | **`<Calendar>`** 元件(見 `../Calendar/calendar.spec.md`,月/週/日 event view);**非本元件語義** | DatePicker 是「選日期」的 form control;Calendar 是「看事件」的頁面 canvas,兩者雖名字都有 calendar 但是不同 DS 元件 |
+
+---
+
+## DateGrid popup(本 DS 自建)
+
+DatePicker 使用**本 DS 自建 DateGrid** + Popover 而非瀏覽器原生 `<input type="date">`。歷史變更(2026-04-19):原本遵守「不自建 calendar」禁令以保留 mobile 原生 wheel UX,但 CLAUDE.md Mindset #1 擴充後明確要求「視覺上也必須跟世界級一樣整齊」——原生 picker 視覺不受控、跨瀏覽器不一致,無法達成與 Dialog / SelectMenu / Combobox 等浮層的視覺連續性。遂改為自建 DateGrid。
+
+**命名變更(2026-04-21)**:原 `<Calendar>` 元件改名為 `<DateGrid>`(DatePicker 內部 primitive),讓 `Calendar` 這個命名留給真正的事件檢視 canvas(對齊 Notion / Google / Apple / Ant 世界級慣例)。DatePicker 內部 primitive 以功能命名為 `DateGrid`。
+
+### 架構
+
+```
+<button fieldWrapperStyles>        ← 視覺仍是 Input wrapper(不變)
+  <span>格式化的日期文字</span>
+  <ItemInlineAction X />            ← 選用,clearable=true 時顯示
+  <CalendarIcon />                   ← 右側固定(lucide icon,視覺 affordance)
+</button>
+       │ 點擊開啟
+       ▼
+<Popover>
+  <DateGrid />                     ← react-day-picker + 本 DS token(原 Calendar)
+</Popover>
+```
+
+### Cell state canonical(5 種語意視覺)
+
+DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混淆:
+
+- **正常(未 hover)** — 黑字透明底(base reading state)
+- **today** — 文字下方藍色底線(**非 ring circle**,避免與 hover 混淆,對齊 [Ant DatePicker](https://ant.design/components/date-picker) `today` cell underline / Google Calendar / macOS Calendar <!-- @benchmark-unverified: Google Calendar + macOS Calendar 無公開 spec URL,visual observation -->)
+- **disabled** — 灰底圓圈 + 淺灰字(與 outside month 視覺略有區隔)
+- **selected**(single / range 端點) — **藍底白字圓**
+- **range track**(中間日期) — 灰底矩形橫條(打在 day 容器層,非 button 層;與端點圓接縫形成連續 bar)
+- **hover**(未選中) — 藍圈 outline **無 fill**(非 filled 避免跟 selected 混淆)
+
+**為什麼 selected 用 primary 非 neutral**:DatePicker 的 selected 是「**最終選定日期**」強 affordance,用 primary 顯示確定性(對齊 [Ant DatePicker selected blue fill](https://ant.design/components/date-picker) / Google Calendar / Notion Calendar 慣例 <!-- @benchmark-unverified: Google Calendar + Notion Calendar 無公開 spec URL,visual observation -->)。**對照 TimePicker 選項 selected 用 `bg-neutral-selected`**(見 `time-picker.spec.md`),因為 TimePicker panel 是「**列表選中**」語意(user 在時分選項間切換),跟 SelectMenu 同流派。兩者差異 codified 在各 spec,不互調。
+
+**State stacking(組合狀態處理)**:
+- today + selected → **selected 勝出**(藍底白字圓)
+- today + range-middle → track 灰底 + underline 仍可見
+- outside month → 弱化字色(不套 disabled 灰底圓,outside 只是「非當月」不是「禁選」)
+
+其他區塊(月份 caption / Nav 按鈕 / 星期標頭)視覺層級:月份 caption 與 SelectMenu 標題同等、Nav 按鈕走 tertiary icon button 規格、星期標頭弱化為輔助資訊。
+
+完整 class / token 對照見 anatomy `CalendarTokens` story。
+
+### Spacing canonical(2026-04-21 對齊 user 附圖)
+
+- Popover padding **四邊對稱** 12px(= `--layout-space-tight` @ md density,實作走 `p-3`)
+- **左右對稱**:prev/next chevron button 中心 = 第一/最後一欄日期 cell 中心;chevron 到 popover 邊距 = 最邊欄日期到 popover 邊距 = 12px
+- **上下對稱**:month caption 到 popover top 距離 = 最後一排日期到 popover bottom 距離 = 12px(均從 `p-3` 繼承)
+- day cell 與 week header 尺寸 SSOT → `date-grid.spec.md:120`(消費 `--field-height-sm` token,density-aware:md=28×28 / lg=32×32)
+
+### Calendar icon
+
+右側固定顯示 Calendar icon（視覺指示這是日期輸入）。Trigger 本身是 `<button>`,點擊開啟 Popover。
+
+### Typed input(Issue 10,2026-05-10 opt-in)
+
+`typeable?: boolean`(default false)→ trigger 內渲 real `<input type="text">` 取代 `<span>`,user 可直接打字 + Calendar icon 仍開 popover(Material X DatePicker / Ant DatePicker / Notion typed-date 雙 affordance 共識)。Parser `parseDateInput(input, { allowTime })` 接 ISO YYYY-MM-DD / YYYY/MM/DD / YYYY.MM.DD + native `Date.parse` fallback(RFC 'Mar 12 2026')。Partial input allow;`Enter`/`Blur` commit;`Esc` reset;IME `compositionstart/end` guard 不誤觸發。Invalid → `aria-invalid`。**v1 limits**:US `MM/DD/YYYY` vs EU `DD/MM/YYYY` ambiguous → Date.parse fallback;locale-aware format prop deferred v2;TimePicker typed input deferred(column picker UX 不同)。
+
+---
+
+## DatePicker.Range(2026-04-21 新增,仿 Ant Design)
+
+### API
+
+```tsx
+<DatePicker.Range
+  value={[startIso, endIso]}           // [string | null, string | null] | null
+  onChange={([start, end]) => ...}
+  size="sm" | "md" | "lg"              // default md,對齊 field-height family
+  placeholder={['Start date', 'End date']}   // 雙 placeholder
+  disabled
+  clearable                             // 一次清空兩端點
+  formatOptions                         // Intl.DateTimeFormatOptions,與 single 共用
+  locale
+  showTime                              // 啟用時間欄位 → value 變 [datetime, datetime]
+  showSeconds                           // showTime 時是否顯示秒
+  minuteStep={15}
+  needConfirm                           // 預設 showTime=true 時為 true
+/>
+```
+
+### 結構(對齊 user 提供附圖 [Image #3])
+
+```
+┌───────────────────────────────────────────────┐
+│ Start date     →     End date            📅  │
+└───────────────────────────────────────────────┘
+ │               │                │              │
+ │               │                │              └─ CalendarIcon(固定右側,視覺指示)
+ │               │                └─ End date(獨立 button,點擊 activeEnd='end')
+ │               └─ ArrowRight icon(`mx-2`,text-fg-muted)
+ └─ Start date(獨立 button,點擊 activeEnd='start')
+```
+
+外層是 `fieldWrapperStyles` 容器,內含**兩個獨立 button**(start / end input),點任一個都開 Popover **並設定 activeEnd**。Active 端點視覺以 `data-active-end="true"` underline 標示(對齊 Ant RangePicker active input 視覺)。
+
+### Active-end 機制(canonical 2026-05-02,對齊 Ant Design RangePicker)
+
+對齊 Ant Design 實證(WebFetch react-component/picker source code 2026-05-03):**input-click 切換 activeEnd**,而**非** footer toggle / radio 按鈕。
+
+**Source citations**:
+- Ant `activeIndex` tracking + `getActiveRange`:`https://github.com/react-component/picker/blob/master/src/PickerInput/RangePicker.tsx`(`function getActiveRange(activeIndex) { return activeIndex === 1 ? 'end' : 'start' }`)
+- Ant `useRangeDisabledDate`:`https://github.com/react-component/picker/blob/master/src/PickerInput/hooks/useRangeDisabledDate.ts`(activeIndex=1 + start 已選 → date < start disabled)
+- Material X DateRangePicker docs:`https://mui.com/x/react-date-pickers/date-range-picker/`(同 input-driven activeEnd 派)
+- Atlassian DateRangePicker:`https://atlassian.design/components/datetime-picker/`
+
+- 點 start input → `activeEnd='start'` + 開 popover;DateGrid range 選的端點落到 start
+- 點 end input → `activeEnd='end'` + 開 popover;同理只更新 end
+- **Auto-advance**:選完 start → 自動切 `activeEnd='end'` 等待 user 選 end(Ant idiom)
+- **showTime=true 時 TimeColumns 套 active end 的 time**(只能編一端的時間,符合單一焦點原則)
+- 視覺指示:active input 加 `decoration-primary underline-offset-4 decoration-2`(對齊 Field focus 語意)
+
+### Popover 行為
+
+- `mode="range"` + `numberOfMonths={2}`(兩月並列,對齊 [Ant RangePicker](https://ant.design/components/date-picker#rangepicker) <!-- @benchmark-unverified: Airbnb / Booking 無公開 DS spec URL,visual observation -->)
+- 點 date → 依 `activeEnd` 更新對應端點(start | end);auto-advance 至 end 等選
+- showTime=false:兩端點都填好 → Popover **自動關閉**
+- showTime=true:`needConfirm=true`(default),user 按「確定」才 commit + close
+- 期間 user 可 hover 未來端點預覽 range track 視覺(Calendar 內建)
+- Clear 按鈕清空兩端點 `onChange([null, null])`
+
+### Range 視覺規則
+
+- **range_start / range_end**:沿用 single selected 的視覺(藍底白字圓)
+- **range middle**:灰底矩形橫條(打在 day 容器層,不是 button 層)
+- **端點 ↔ 中間的接縫**:端點採半圓角(左端 `rounded-l-full` / 右端 `rounded-r-full`)讓圓弧 + 矩形無縫連接成一條連續底色帶
+
+完整 class 對照見 anatomy `CalendarTokens`(State canonical 表的 `selected` / `range track`)。
+
+### 禁止
+
+- ❌ 不自刻「兩個 `<Input>` + 中間箭頭」繞過 `DatePicker.Range`(canonical 本元件提供)
+- ❌ 不讓 Popover 在選第一個端點後就關閉(違反 range selection UX)
+- ❌ value 用單字串 `"2026-01-01/2026-01-07"`——必 `[string | null, string | null]`,語意清楚 + 避免 parse 錯誤
+- ❌ Range active-end **不**用 footer toggle / radio 切換(違反 Ant / Material / Atlassian 慣例);必走 input-click
+
+---
+
+## showTime(2026-05-02 新增,Ant idiom 整合 datetime)
+
+### API
+
+```tsx
+<DatePicker
+  showTime                              // 啟用時間欄位 → value 變 ISO datetime
+  showSeconds={false}                   // 是否顯示秒(預設 false,對齊 Ant)
+  minuteStep={15}                       // 分鐘步進,會議常用 15
+  secondStep={1}
+  needConfirm                           // 預設 showTime=true 時為 true(Ant idiom)
+  value={iso}                           // 'YYYY-MM-DDTHH:MM:SS'
+  onChange={...}
+/>
+
+<DatePicker.Range showTime ... />       // Range 同樣 props
+```
+
+### 行為
+
+- showTime=true:popover 右側出現 `<TimePickerSidePanel>`(內部消費 TimeColumns),通過 `<CalendarTimeContainer>` absolute positioning 讓 DateGrid 主導 row 高度(TimeColumns 不撐高)
+- TimePickerSidePanel **header dynamic 顯示當前 active time**(`HH:MM` / `HH:MM:SS`),對齊 Ant `<DatePicker showTime />` panel header(canonical 2026-05-03 v9)
+- TimePickerSidePanel 結構:**pt-3 + h-field-xs flex center + mb-3**(top 對齊 DateGrid month_caption 同 Y baseline;**bottom = 0,讓 time list 連續延伸到 SurfaceFooter border-t**,對齊 Ant / Material time-picker 「continuous scroll」idiom — canonical 2026-05-03 v10)
+- TimePickerSidePanel header **下方無 divider**(對齊 DateGrid month_caption 也無 border-b),DS internal canonical M23 優先於 Ant time-picker header divider 慣例 — 兩 panel 同層級 caption 視覺對稱(canonical 2026-05-03 v10)
+- 底部 footer **消費 SurfaceFooter SSOT**(`patterns/overlay-surface`)— border-t + canonical px-loose py-tight padding,**不**自寫 Separator + p-2 + ml-auto wrapper(canonical 2026-05-03 v8)
+- Footer 排版(對齊 Ant `marginInlineStart: auto` on OK):左「此刻」(`mr-auto` push)、右「確定」(needConfirm)或「關閉」
+- 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
+- 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 }`)
+
+### 為什麼用 prop 而非分離 `<DateTimePicker>` 元件
+
+世界級對照:**Ant Design / Material X / Atlassian / Carbon 全採 prop 模式**(`showTime` / `withTime` / `granularity`),非分離元件。Source:
+- Ant `<DatePicker showTime />`:`https://ant.design/components/date-picker#datepicker-demo-time`(`showTime: true | object`)
+- Material X `views={['day','hours','minutes']}` / `format`:`https://mui.com/x/react-date-pickers/date-time-picker/`
+- Atlassian `<DateTimePicker>`:`https://atlassian.design/components/datetime-picker/`
+- React Aria `granularity`:`https://react-spectrum.adobe.com/react-aria/DatePicker.html#granularity`
+
+理由:
+- API surface 一致(同 props 結構,只多 4 個 time-related prop)
+- 避免 DateTimePicker / DateTimeRangePicker / DatePicker / DatePickerRange 4 個元件 cross-product
+- consumer 從 date-only 升級 datetime 只加 prop,不換元件
+
+歷史(2026-04-21~05-01):曾分離為 `<DateTimePicker>` 在 DataTable 內,2026-05-02 user audit 發現抽象不對(M17 SSOT 違反 + API surface 不一致),合併回 DatePicker showTime。
+
+---
+
+## 格式化
+
+| 選項 | 說明 | 範例 |
+|------|------|------|
+| `formatOptions` | `Intl.DateTimeFormatOptions` | `{ year: 'numeric', month: 'short', day: 'numeric' }` |
+| `locale` | BCP 47 locale | `'zh-TW'`、`'en-US'` |
+
+Display 模式（readonly / disabled / DataTable cell）使用 `Intl.DateTimeFormat` 格式化。Edit 模式 trigger 顯示文字也透過 `Intl.DateTimeFormat` 格式化（與 Display 一致，`formatOptions` / `locale` prop 對兩者皆生效）。
+
+---
+
+## Clearable
+
+`clearable` prop 在有值時顯示 clear 按鈕（endAction）。
+
+- 只在 edit 模式顯示
+- 清除後 value 變為 `null`（Display 顯示 —）
+- **Dual-state sync canonical**(2026-05-03 v10):X 點擊必同時 `onChange?.('')` + `setDraft(null)`(Range 同),否則 `needConfirm=true`(showTime 預設)且 popover 開著時 `displayValue=draft` 仍顯示舊值,trigger 看起來「沒清」。X 在 trigger 上是 standard clear affordance,不走 needConfirm「等確定」語義 — 立刻 commit + 同步 draft
+
+---
+
+## 禁止事項
+
+- ❌ 不在 readonly / disabled 模式顯示 clear 按鈕
+- ❌ 不改 DateGrid 視覺 token 為本 DS 以外的顏色(`bg-primary` / `ring-primary` 等必須來自 semantic token,不可硬寫)
+- ❌ 不用其他 calendar library 平行實作(若有 DateRange / DateTime 未來需求,擴充本 DateGrid 而非引入第二個 library)
+
+---
+
+## shadcn passthrough 例外說明
+
+DatePicker 套 `React.forwardRef` + `displayName`,但**不 `...props` spread DOM**——consumer 透過 `DatePickerProps` 明列 API surface(value / onChange / mode / size / formatOptions 等),不 spread 任何剩餘 DOM attrs 到 trigger。
+
+**為什麼 intentional**:DatePicker trigger 是 **compound**(Display 模式為 span 視覺、Edit 模式為 Button),不同 render tree。若 spread `...props` 則會 leak 到特定一邊,另一邊 consumer 誤以為無效:
+
+- consumer 傳 `onFocus` → 期待作用在「edit trigger button」,但 Display 模式無 trigger 會忽略
+- consumer 傳 `data-testid` → 指向哪個 render tree 取決於當下 mode,測試不穩定
+- consumer 傳 className → **這個有明確語義**:套在 root wrapper(不論哪個 mode 都穩定),`DatePickerProps.className` 顯式接收
+
+顯式列 API surface 符合世界級 composite 元件慣例([Material DatePicker](https://mui.com/x/react-date-pickers/date-picker/) / [Atlassian DateTimePicker](https://atlassian.design/components/datetime-picker/examples) 皆如此),consumer 知道能傳什麼,避免靜默失效。
+
+**`asChild` 不支援**:同理,compound trigger 無單一 Slot 目標。consumer 若要自訂 trigger 視覺,改用 `<DatePicker mode="display">` + 自家 Button composition。
+
+---
+
+## A11y 預設
+
+- Trigger:`role="combobox"` + `aria-haspopup="dialog"` + `aria-expanded={open}` + 必含 accessible name(`aria-label` / 或外層 `<label>` / 或 fieldCtx label)
+- Popover content:`role="dialog"` + `aria-label="日期選擇"`(Range:`"日期區間選擇"`)
+- DateGrid 鍵盤:Arrow keys 切日 / PageUp/Down 切月 / Home/End 行首尾(react-day-picker v9 內建)
+- Trigger 鍵盤:Space / Enter open;Esc close + focus return to trigger(Radix Popover 內建)
+- Range 雙 trigger:`activeEnd` state 指向當前編輯端,`aria-expanded` 對應只當該 trigger active 時 true
+
+---
+
+## 驗證時機
+
+走 Field SSOT(`Field/form-validation.spec.md`)。DatePicker 為 form control,validation 行為:
+
+- `required` + `value=null` → submit 時 trigger error,`aria-invalid="true"` + error border
+- `min` / `max` date constraint:value 超出範圍時自動 error(consumer 傳 `disabledDates` predicate 視覺 disable,但 typed input 仍可輸入無效值需 validation 攔)
+- Range mode:start > end → invalid;consumer 應確保 start 先 commit 才接受 end
+- Typed input(`typeable=true`):`parseDateInput` 失敗 → `aria-invalid`,blur 觸發 error message
+- Validation timing:typed input → blur + submit;picker pick → onChange 即時(已選有效日期不需延遲)
+
+## 邊界案例
+
+- **Disabled**:Field SSOT own;trigger Button 自動繼承 disabled(`text-fg-disabled` + cursor-not-allowed + 不開 picker)。Display mode + disabled 維持格式化日期文字但 token 切 disabled。
+- **Loading(server-rendered grid)**:DatePicker 為 sync UI 不獨立 own loading。若 consumer 場景需 async date constraint fetch(如後端 disabled-dates list),consumer 應先 disable trigger 直到 fetch 完成,或在 popover 開啟後 body 切 `<Empty icon={<CircularProgress/>}/>`(對齊 panel-body loading SSOT)。本 spec scope 內不渲 loading state。
+- **Empty(no value / disabled all dates)**:`value=null` → trigger 顯 placeholder(預設「選擇日期」);若 `disabledDates` predicate 將所有可選日期 disable,DateGrid 自動顯 disabled cells,無導覽目標時鍵盤焦點停留(react-day-picker v9 內建)。
+- **Invalid date input**:Field validation 處理 `aria-invalid="true"` + error border + 下方 error message;DatePicker 本身不 own validation 規則。
+- **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;DateGrid 內 cell 尺寸固定不隨 density 漂移(date grid 為密度敏感不可變區)。
+
+---
+
+## 相關
+
+- `../Input/input.spec.md` — 純文字 YYYY-MM-DD（不需 picker 互動的場景）
+- `../NumberInput/number-input.spec.md` — 年齡、天數等數值
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）

package/src/components/DatePicker/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './date-picker'