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

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

@@ -0,0 +1,205 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { DatePicker } from './date-picker'
+
+const meta: Meta = {
+  title: 'Design System/Components/DatePicker/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-xs">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 DatePicker 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">請假單送審後日期欄位從可編輯轉唯讀/純展示(四模式)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="可清除"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">篩選器的選填截止日,填錯一鍵清空(可清除)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="尺寸"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">緊湊工具列與標準表單的尺寸對應(尺寸)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="範圍模式:訂房 / 訂機票情境"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Range:訂房 / 訂機票情境</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/DatePicker/展示" name="檢視樣式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">審批詳情頁唯讀展示申請日期(展示樣式)</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 不用 DatePicker 做純文字日期輸入(API debug)"
+          note="API 表單不需 picker 互動 → 用 Input type='text'。開發者工具的日期欄用純文字"
+        >
+          <Label warn>純文字 ISO date → Input,不需 picker UI</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用其他 calendar library 平行實作"
+          note="DatePicker.Range 與 showTime 已共用同一套日曆格線與互動。日曆類功能應延伸這個共用基礎，不要在同一產品另引入第二套視覺與操作邏輯"
+        >
+          <Label>實作細節見 Design System / Components / DatePicker / 設計規格</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不覆寫 Calendar token 為非 DS 色"
+          note="Calendar 視覺 token(bg-primary / ring-primary / neutral-hover 等)必須來自 semantic token。硬寫 #xxx / bg-blue-500 會破壞 dark mode 聯動、跟其他浮層語言分岔"
+        >
+          <Label>token 表見設計規格 → Calendar 內部 token</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="❌ 不用 DatePicker 選擇日期範圍(from-to)→ DatePicker.Range"
+          note="日期範圍用 DatePicker.Range(雙 input + 共用 calendar,對齊 Ant DatePicker.RangePicker)。Stripe 的 date range filter 用雙 picker"
+        >
+          <Label warn>日期範圍 → DatePicker.Range,不是單一 DatePicker × 2</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 DatePicker 選時間(時 / 分 / 秒)→ TimePicker"
+          note="只選時間時使用 TimePicker；需同時選日期與時間時，在 DatePicker 啟用 showTime，不要並排兩個不相關的輸入控制"
+        >
+          <Label warn>時間用 TimePicker,日期 + 時間用 showTime prop</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 DatePicker 做月檢視 event calendar → Calendar 元件"
+          note="Event 檢視(看某月有哪些事件)改用 Calendar 元件(是頁面 canvas 不是 form field)。Notion calendar 檢視用 Calendar,不用 DatePicker"
+        >
+          <Label warn>Event calendar 檢視 → Calendar 元件,DatePicker 只選日期</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const CalendarRule: Story = {
+  name: '自建 Calendar + 視覺一致性',
+  render: () => {
+    const [deadline, setDeadline] = React.useState('2026-05-15')
+    const [releaseDate, setReleaseDate] = React.useState('2025-12-25')
+    return (
+      <div>
+        <Rule
+          title="Edit 用本 DS 自建 Calendar + Popover"
+          note="點擊 trigger 開啟的 Calendar 使用本 DS 的 overlay-surface token(與 Dialog / SelectMenu / Combobox 相同)——浮層的圓角、陰影、間距、typography 跨元件視覺整齊。瀏覽器原生 picker 視覺不受控、跨 Chrome/Safari/Firefox 不一致,無法達成世界級設計系統的視覺連續性"
+        >
+          <DatePicker value={deadline} onChange={setDeadline} />
+          <Label>↑ 專案截止日:點擊 trigger → Popover 打開 Calendar,視覺與 SelectMenu 一致</Label>
+        </Rule>
+
+        <Rule
+          title="Calendar 內部 token 全由 DS 控制"
+          note="Calendar 的月份 caption / nav 按鈕 / 星期標頭 / 日格 / hover / selected / today 全部由 DS token 驅動:hover 用 ring-primary 透明底圈、selected 用 primary 藍底白字圓、today 用 primary 底部 bar(after 偽元素)。切 dark mode 自動聯動,不需元件內重寫"
+        >
+          <DatePicker value={releaseDate} onChange={setReleaseDate} />
+          <Label>↑ 發佈日:Calendar 所有視覺 token 來自 semantic.css</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const FormattingRule: Story = {
+  name: '顯示格式化',
+  render: () => (
+    <div>
+      <Rule
+        title="格式化跨模式一致 — 預設 YYYY/MM/DD,傳 formatOptions / locale 走 Intl.DateTimeFormat"
+        note="未傳格式 prop 時預設直接組 YYYY/MM/DD(locale-independent);傳 formatOptions + locale 才啟用 Intl.DateTimeFormat,同時控制 view / readonly / disabled 的格式化文字與 edit trigger 顯示文字。跨模式一致、跨頁面可預期。Calendar popup 的月份語言由 Calendar 內部 locale 處理"
+      >
+        <DatePicker
+          mode="readonly"
+          value="2026-05-15"
+          formatOptions={{ year: 'numeric', month: 'short', day: 'numeric' }}
+        />
+        <DatePicker
+          mode="readonly"
+          value="2026-05-15"
+          locale="zh-TW"
+          formatOptions={{ year: 'numeric', month: 'long', day: 'numeric' }}
+        />
+        <Label>↑ 專案截止日:formatOptions 控制格式;locale 控制語言</Label>
+      </Rule>
+
+      <Rule
+        title="Edit trigger 文字也受 formatOptions / locale 控制"
+        note={'原本原生 <input type="date"> 的 trigger 格式受瀏覽器 locale 控制無法干預;改自建後,edit trigger 顯示的已選日期也走 Intl.DateTimeFormat——跟 view 模式完全一致'}
+      >
+        <DatePicker
+          value="2026-05-15"
+          onChange={() => {}}
+          locale="zh-TW"
+          formatOptions={{ year: 'numeric', month: 'long', day: 'numeric' }}
+        />
+        <Label>↑ 專案截止日:edit trigger 顯示「2026年5月15日」,與 readonly 一致</Label>
+      </Rule>
+
+      <Rule
+        title="null 值統一顯示半形連字號"
+        note="view 模式 null / undefined 顯示半形 -(foreground,同 readonly value 色),與其他 Field 元件一致"
+      >
+        <DatePicker mode="readonly" value={null} />
+      </Rule>
+    </div>
+  ),
+}
+
+export const ClearableRule: Story = {
+  name: '可清空 使用',
+  render: () => {
+    const [value, setValue] = React.useState<string | null>('2026-05-15')
+    return (
+      <div>
+        <Rule
+          title="日期是選填時才開 clearable"
+          note="必填的日期欄位(出生日、到期日)不該有 clear——避免使用者不小心清空後不知怎麼填回。選填日期(備註日期、提醒日)開啟 clearable 才合理"
+        >
+          <DatePicker value={value} onChange={setValue} clearable />
+          <Label>↑ 選填情境:有值時右側出現 X,清除後回到空白</Label>
+        </Rule>
+
+        <Rule
+          title="readonly / disabled 不顯示 clear"
+          note="clear 是 edit 行為,readonly 的 field 邏輯上不可操作,clear 按鈕既無法點擊也造成視覺誤導"
+        >
+          <DatePicker mode="readonly" value="2026-05-15" clearable />
+          <Label>↑ readonly 模式下即使傳 clearable 也不顯示 clear 按鈕</Label>
+        </Rule>
+      </div>
+    )
+  },
+}

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

@@ -12,20 +12,19 @@ benchmark:
   - 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`。
+DatePicker 是**單一日期**的輸入與顯示元件(form 場景選定絕對日期的 Field control)。組成(DateGrid + Popover、`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 連續一致。
+**Layout Family**:本元件是 `components/Field/field-controls.spec.md` 所擁有的 **Family 4(Field control layout)** 消費者。結構繼承其 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1(Menu item)讓 SelectMenu trigger + options 連續一致。
 
 **實作基礎**:
-- Trigger:`<button>` 包 `fieldWrapperStyles`(視覺仍是 Input wrapper,只是改為可點擊觸發浮層)
+- Trigger:`<div role="combobox" tabIndex={0}>` 包 `fieldWrapperStyles`(視覺仍是 Input wrapper,只是改為可點擊觸發浮層)。**刻意不用 native `<button>`**——trigger 內含 `ItemInlineAction`(本身是 `<button>`),button 包 button 會構成 nested-interactive(axe serious 違規);改用 `div + role="combobox"`;Radix PopoverTrigger 只 compose onClick(div 無 native Enter/Space→click),Enter / Space 開 popover 由本檔自建 onKeyDown 補(見 date-picker.tsx trigger 註解)。對齊 Combobox / Select / TimePicker 同 pattern。**例外**:`DatePicker.Range` 的雙 input 是真 `<button type="button">`(各自獨立 active,無內含 inline-action)
 - Popup:`Popover`(消費 overlay-surface pattern 外殼)
 - DateGrid 主體:消費 `<DateGrid>` 內部 primitive(見 `../DateGrid/date-grid.spec.md`;`react-day-picker` 包裝成本 DS token);**不是** `<Calendar>` — `<Calendar>` 是 event 檢視 canvas,跟 DatePicker 無關
 
@@ -36,12 +35,23 @@ DatePicker 是**單一日期**的輸入與顯示元件。Edit 用**本 DS 自建
 本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
 
 **為什麼**:
-- 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
+- 內部狀態複雜(draft 暫存 / popover open / Range activeEnd)跟 `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。
 
+### Open-pair rationale:defaultOpen + onOpenChange,無 controlled open(2026-06-12 deep-audit R2 補)
+
+open 軸同樣只開最小 API — **uncontrolled-only**:`defaultOpen`(初始開)+ `onOpenChange`(通知 callback),無 controlled `open` prop。
+
+**為什麼**:
+- 已知需求只要「初始開 + 知道何時關」:(1) 視覺快照 — Storybook OpenSnapshot / visual-audit(M15)`defaultOpen` 一行達成;(2) DataTable cell-as-input(`DataTable/cell-registry.tsx`)— `defaultOpen` 1-step 開 calendar,`onOpenChange(false)` → cell exit edit mode
+- open 跟 draft 暫存生命週期綁死:確認 commit(date-picker.tsx `handleConfirm` → `onChange` + close)/ `needConfirm=false` 選日即關 / Esc + outside-click dismiss。controlled `open` 等於把 draft-commit 時機切一半給 consumer,漏接 → draft 沒 commit / cell 卡 edit。`DatePicker.Range` 更進一步 — open + `activeEnd` 純內部編排,連 pair 都不收
+- 世界級對照:Radix Popover([radix-ui.com/primitives/docs/components/popover](https://www.radix-ui.com/primitives/docs/components/popover))/ Ant Select([ant.design/components/select](https://ant.design/components/select))/ MUI Select([mui.com/material-ui/api/select](https://mui.com/material-ui/api/select/))皆提供 controlled `open` — 它們是泛用 primitive / library,必須支援任意 orchestration;本 DS 是 opinionated form control,無真實 consumer 需求前不為「可能性」付受控成本(Rule-of-3)
+
+**若未來要開 controlled open**:同 value 軸引入 `useControllableState` helper + 測 controlled↔uncontrolled switch,屬 major API 擴充,非本 session scope。
+
 ---
 
 ## 何時用
@@ -57,28 +67,30 @@ DatePicker 是**單一日期**的輸入與顯示元件。Edit 用**本 DS 自建
 |------|------|------|
 | 日期範圍（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 格式化 |
+| 相對時間（「3 天前」「昨天」）| 自訂展示元件 | DatePicker 的 view 態是絕對日期；相對時間需要計算 + 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 元件 |
 
+**常見誤解**:(1)「用 DatePicker 選日期範圍」— 單一 DatePicker 只選一天,範圍必用 `<DatePicker.Range>`;(2)「DatePicker = Calendar」— 前者選日期、後者看事件(見上表末列);(3)「date + time 要獨立 DateTimePicker 元件」— 走 `showTime` prop,非分離元件(見「showTime」段)。
+
 ---
 
 ## 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。
+DatePicker 使用**本 DS 自建 DateGrid** + Popover 而非瀏覽器原生 `<input type="date">`。歷史變更(2026-04-19):原本遵守「不自建 calendar」禁令以保留 mobile 原生 wheel UX,但 `AGENTS.md`「每次任務前的 6 條 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(不變)
+<div role="combobox" tabIndex={0} fieldWrapperStyles>  ← Input wrapper 外觀;用 div+role 不用 button 避免 nested-interactive
   <span>格式化的日期文字</span>
-  <ItemInlineAction X />            ← 選用,clearable=true 時顯示
+  <ItemInlineAction X />            ← 選用,clearable=true 時顯示(本身是 button)
   <CalendarIcon />                   ← 右側固定(lucide icon,視覺 affordance)
-</button>
-       │ 點擊開啟
+</div>
+       │ 點擊 / Enter / Space 開啟
        ▼
 <Popover>
   <DateGrid />                     ← react-day-picker + 本 DS token(原 Calendar)
@@ -90,20 +102,20 @@ DatePicker 使用**本 DS 自建 DateGrid** + Popover 而非瀏覽器原生 `<in
 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 -->)
+- **today** — 文字下方藍色底線(**非 ring circle**,避免與 hover 混淆)；today 是持續參考點，不與 hover 的瞬時 outline 共用形狀
 - **disabled** — 灰底圓圈 + 淺灰字(與 outside month 視覺略有區隔)
 - **selected**(single / range 端點) — **藍底白字圓**
-- **range track**(中間日期) — 灰底矩形橫條(打在 day 容器層,非 button 層;與端點圓接縫形成連續 bar)
+- **range track**(中間日期) — 灰底矩形橫條,與端點圓接縫形成連續 bar(實作層級詳 `date-grid.tsx` cell anatomy 註解)
 - **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,不互調。
+**為什麼 selected 用 primary 非 neutral**:DatePicker 的 selected 是「**最終選定日期**」強 affordance,用 primary 顯示確定性。**對照 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 規格、星期標頭弱化為輔助資訊。
+其他區塊(月份 caption / Nav 按鈕 / 星期標頭)視覺層級:月份 caption 與 SelectMenu 標題同等、Nav 按鈕消費 `Button variant="text" size="xs" iconOnly`(色彩走 Button 預設 text-foreground)、星期標頭與 caption 同視覺權重(不弱化,2026-05-03 撤銷 fg-secondary)。
 
 完整 class / token 對照見 anatomy `CalendarTokens` story。
 
@@ -114,13 +126,9 @@ DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混
 - **上下對稱**: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 不同)。
+`typeable?: boolean`(default false)→ trigger 內渲 real `<input type="text" role="combobox">` 取代 `<span>`,user 可直接打字 + Calendar icon 仍開 popover(Material X DatePicker / Ant DatePicker / Notion typed-date 雙 affordance 共識)。外層 Field wrapper 只負責視覺與 Popover click anchor,不重複 `role` / `aria-*`;popup 開啟、dialog 實際掛載後,真 input 才輸出 `aria-controls` 指向該 dialog,關閉後移除,禁止把 Radix 的懸空 IDREF 留在純視覺 wrapper。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 不同)。
 
 ---
 
@@ -145,20 +153,9 @@ DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混
 />
 ```
 
-### 結構(對齊 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 視覺)。
+外層是 `fieldWrapperStyles` 容器,內含**兩個獨立 button**(start / end input,點任一個都開 Popover **並設定 activeEnd**)、中間 `ArrowRight` icon(`mx-2`,`text-fg-muted`)、右側固定 `CalendarIcon`。Active 端點視覺以 `data-active-end="true"` underline 標示(對齊 Ant RangePicker active input 視覺)。
 
 ### Active-end 機制(canonical 2026-05-02,對齊 Ant Design RangePicker)
 
@@ -178,18 +175,18 @@ DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混
 
 ### Popover 行為
 
-- `mode="range"` + `numberOfMonths={2}`(兩月並列,對齊 [Ant RangePicker](https://ant.design/components/date-picker#rangepicker) <!-- @benchmark-unverified: Airbnb / Booking 無公開 DS spec URL,visual observation -->)
+- 用 `mode="single"` + 自管 `rangeModifiers`(**不**用 RDP 內建 `mode="range"`——其 click 配對邏輯與 activeEnd 衝突,見 date-picker.tsx Range DateGrid「mode='single' + manual modifiers」註解);`numberOfMonths={showTime ? 1 : 2}`：date-only Range 兩月並列以便同時看起訖範圍，showTime Range 保留一月讓時間 controls 有穩定空間
 - 點 date → 依 `activeEnd` 更新對應端點(start | end);auto-advance 至 end 等選
 - showTime=false:兩端點都填好 → Popover **自動關閉**
 - showTime=true:`needConfirm=true`(default),user 按「確定」才 commit + close
-- 期間 user 可 hover 未來端點預覽 range track 視覺(Calendar 內建)
+- range track 視覺由已選端點靜態算出(`rangeModifiers` 讀 committed start/end,見 date-picker.tsx `rangeModifiers` 註解);**無** hover 未選端點的預覽(RDP hover-preview 只在內建 `mode="range"` 才有,本元件刻意不用)
 - Clear 按鈕清空兩端點 `onChange([null, null])`
 
 ### Range 視覺規則
 
 - **range_start / range_end**:沿用 single selected 的視覺(藍底白字圓)
-- **range middle**:灰底矩形橫條(打在 day 容器層,不是 button 層)
-- **端點 ↔ 中間的接縫**:端點採半圓角(左端 `rounded-l-full` / 右端 `rounded-r-full`)讓圓弧 + 矩形無縫連接成一條連續底色帶
+- **range middle**:灰底矩形橫條(實作層級詳 `date-grid.tsx`)
+- **端點 ↔ 中間的接縫**:端點朝區間外側保留完整圓弧、朝區間內側與矩形無縫銜接,形成連續底色帶；實作 class 對照由 anatomy 管理
 
 完整 class 對照見 anatomy `CalendarTokens`(State canonical 表的 `selected` / `range track`)。
 
@@ -231,9 +228,10 @@ 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 }`)
+- Range stadium pattern(canonical 2026-05-03 v8):SSOT → `../DateGrid/date-grid.spec.md`(`range_start` / `range_end` 半圓 stadium 規則;class 細節見 `date-grid.tsx`)
 
 ### 為什麼用 prop 而非分離 `<DateTimePicker>` 元件
 
@@ -259,7 +257,7 @@ DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混
 | `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 對兩者皆生效）。
+預設(未傳 `formatOptions` / `locale`)直接組 `YYYY/MM/DD`(locale-independent,對齊 Ant year-first;見 date-picker.tsx `formatDate` 註解);傳 `formatOptions` / `locale` 才走 `Intl.DateTimeFormat`。View / readonly / disabled 模式(含 DataTable cell)與 Edit 模式 trigger 文字同一條格式化路徑,兩者一致。
 
 ---
 
@@ -268,7 +266,7 @@ Display 模式（readonly / disabled / DataTable cell）使用 `Intl.DateTimeFor
 `clearable` prop 在有值時顯示 clear 按鈕（endAction）。
 
 - 只在 edit 模式顯示
-- 清除後 value 變為 `null`（Display 顯示 —）
+- 清除後 `onChange?.('')`（空字串 = 空值；view 態顯示半形 -,text-foreground）
 - **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
 
 ---
@@ -283,26 +281,20 @@ Display 模式（readonly / disabled / DataTable cell）使用 `Intl.DateTimeFor
 
 ## 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 誤以為無效:
+DatePicker 套 `React.forwardRef` + `displayName`;`DatePickerProps` extends `Omit<React.HTMLAttributes<HTMLDivElement>, 'value' | 'onChange' | 'placeholder' | 'defaultValue'>`,剩餘 DOM attrs `...props` spread 到**當前 mode 的 root wrapper**(edit trigger `<div role="combobox">` / readonly · disabled wrapper div / Range wrapper div)。
 
-- consumer 傳 `onFocus` → 期待作用在「edit trigger button」,但 Display 模式無 trigger 會忽略
-- consumer 傳 `data-testid` → 指向哪個 render tree 取決於當下 mode,測試不穩定
-- consumer 傳 className → **這個有明確語義**:套在 root wrapper(不論哪個 mode 都穩定),`DatePickerProps.className` 顯式接收
+**例外**:`mode="view"` 預設(未 opt-in `showDisplayEndIcon`)輸出裸 `<span>`,**不** spread `...props`——consumer 傳 DOM attrs(`data-testid` / `onFocus` 等)時注意 view 模式不生效;`className` 各 mode 皆顯式接收(套在該 mode 的 root 元素)。
 
-顯式列 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。
+**`asChild` 不支援**:trigger 是 compound(view 裸 span / edit `div role="combobox"` 不同 render tree),無單一 Slot 目標。consumer 若要自訂 trigger 視覺,改用 `<DatePicker mode="view">` + 自家 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:`"日期區間選擇"`)
+- Trigger:非 typeable 由 Field wrapper 持 `role="combobox"`;typeable 由真 `<input>` 持 combobox 語意,外層 wrapper 不重複 ARIA。兩者皆有 `aria-haspopup="dialog"` + `aria-expanded={open}` + accessible name(`aria-label` / 或外層 `<label>` / 或 fieldCtx label),並只在 popup 已掛載時輸出 `aria-controls` 指向同一個 dialog ID(關閉時移除,不得留下懸空 IDREF)
+- Popover content:`role="dialog"`;單一日期 popover 的 PopoverContent 帶 `aria-label="日期選擇"`(date-picker.tsx:650,DS default dialog label),Range popover 加 `aria-label="日期區間選擇"`
 - DateGrid 鍵盤:Arrow keys 切日 / PageUp/Down 切月 / Home/End 行首尾(react-day-picker v9 內建)
-- Trigger 鍵盤:Space / Enter open;Esc close + focus return to trigger(Radix Popover 內建)
+- Trigger 鍵盤(Space / Enter open;Esc close + 回焦):單一 DatePicker 的 `<div role="combobox">` 無 native Enter/Space→click,由元件**自建 `onKeyDown`** 開 popover(Radix PopoverTrigger 只 compose onClick;date-picker.tsx:554),Esc 關閉後靠 PopoverTrigger 的 Radix **內建** `triggerRef.focus()` 回焦;Range 用 native `<button>` onClick 開、只掛 PopoverAnchor(triggerRef 恆 null → 內建回焦 no-op),改由**自建 `onCloseAutoFocus`** 手動回焦 active 端 button(date-picker.tsx:1020-1026,守 WCAG 2.4.3)
 - Range 雙 trigger:`activeEnd` state 指向當前編輯端,`aria-expanded` 對應只當該 trigger active 時 true
 
 ---
@@ -312,18 +304,19 @@ DatePicker 套 `React.forwardRef` + `displayName`,但**不 `...props` spread DOM
 走 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
+- Range mode:start > end → invalid;component 內建 `isOutOfRangeOrder` 在 picker 端視覺 disable 違序日期(activeEnd='end' 時 `date < start` disable;activeEnd='start' 時 `date > end` disable),consumer 仍應在 submit 端確保 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。
+- **Disabled**:Field SSOT own;resolvedMode='disabled' 走 readonly / disabled 純 wrapper 分支(無 Popover trigger、`aria-disabled`、不開 picker),文字與 Calendar icon 切 `text-fg-disabled`。readonly 不顯示 Calendar icon(類型身份 indicator 規則,SSOT field-controls.spec.md「下拉箭頭與類型身份 indicator」段 L266-276);disabled 保留並切 `fg-disabled`。顯式 `mode="view"` 永遠最優先(useResolvedFieldMode step 1,見 field-context.ts):view + disabled 同傳走 view 分支不套 disabled token;要 disabled chrome 傳 `disabled` 或 `mode="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 內建)。
+- **Empty(no value)**:`value=null` → trigger 顯 placeholder(預設 `YYYY/MM/DD`,showTime 時 `YYYY/MM/DD HH:MM`;consumer 可傳 `placeholder` 覆寫)。無導覽目標時鍵盤焦點停留(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 為密度敏感不可變區)。
+- **極長格式化日期**:trigger 文字單行 `truncate`(ellipsis),不換行不撐高(View / Edit / typeable / Range 雙 input 皆同);實際截斷時 hover / focus 顯完整值 tooltip(僅實際截斷才顯——rule owner `components/Tooltip/tooltip.spec.md:32`「截斷文字 → tooltip」):View 路徑消費 `<TruncatedText>`;Edit trigger 與 Range 兩端 button 為 interactive host,消費 `useTruncated` 自組(trigger = host、量測內層值 span,SSOT `patterns/element-anatomy/truncated-text.spec.md`「trigger 需自控」指定解),popover 開啟時靜默。typeable `<input>` 可捲動編輯,無截斷補救需求。
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。trigger / Range / DateGrid 不在本檔另立支援決策。
+- **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;DateGrid 內 cell 尺寸 density-aware(消費 `--field-height-sm`:md=28×28 / lg=32×32,對齊 L128 + `date-grid.spec.md:120`),隨 density 縮放而非固定。
 
 ---
 
@@ -332,3 +325,14 @@ DatePicker 套 `React.forwardRef` + `displayName`,但**不 `...props` spread DOM
 - `../Input/input.spec.md` — 純文字 YYYY-MM-DD（不需 picker 互動的場景）
 - `../NumberInput/number-input.spec.md` — 年齡、天數等數值
 - `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `calendar.spec.md`
+- `date-grid.spec.md`
+- `header-canonical.spec.md`
+- `input.spec.md`
+- `number-input.spec.md`
+- `time-picker.spec.md`