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

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

@@ -0,0 +1,344 @@
+// @principles-rationale: Merged WhenToUse + CalendarVsDatePickerRule + NotAnEventViewRule
+// into a single `UsageGuidance` story (3 sections) per 2026-04-26 user mandate to
+// consolidate decision-related stories. ModeRule / VisualTokenRule / LocaleRule kept.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import { useState } from 'react'
+import { zhTW } from 'date-fns/locale/zh-TW'
+import type { DateRange } from 'react-day-picker'
+import { DateGrid } from './date-grid'
+import { DatePicker } from '@/design-system/components/DatePicker/date-picker'
+
+const meta: Meta = {
+  title: 'Design System/Internal/DateGrid/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// Fixed local date keeps rendered states deterministic across run dates and time zones.
+const STORY_TODAY = new Date(2026, 6, 15)
+const storyDate = (day: number) =>
+  new Date(STORY_TODAY.getFullYear(), STORY_TODAY.getMonth(), day)
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+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-wrap gap-5 items-start">{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 Demo = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <div className="flex flex-col gap-2 min-w-0">
+    <span className="text-footnote text-fg-secondary font-medium">{title}</span>
+    <div className="bg-surface-raised border border-border rounded-lg p-2 w-fit">{children}</div>
+  </div>
+)
+
+// ── Stories ──────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [date, setDate] = useState<string | null>('2026-04-20')
+    const [inline, setInline] = useState<Date | undefined>(new Date(2026, 3, 20))
+
+    return (
+      <div>
+        <Section title="何時用">
+          <div className="prose prose-sm max-w-prose">
+            <p>適合 DateGrid 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+            <ul className="space-y-1">
+              <li>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="單日 — 生日 / 到期日"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Single — 生日 / 到期日</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="多日 — 活動可參加日期"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Multiple — 活動可參加日期</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="範圍 — 分析時段 / 訂單範圍"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Range — 分析時段 / 訂單範圍</span></LinkTo>
+              </li>
+              <li>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="行內 — 儀表板小卡"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">行內 — Linear 專案截止日小卡</span></LinkTo>
+              </li>
+            </ul>
+            <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>
+          </div>
+        </Section>
+
+        <Section title="何時不用 + 替代">
+          <Rule
+            title="DateGrid 是「日期 picker」,不是「事件日曆」"
+            note="本元件只處理日期選擇(選一天、多天、範圍)。若需求是「顯示一個月內的事件清單、拖曳事件、切換 week / month / agenda view」——那是事件行事曆,需要專用元件(Google Calendar / Outlook 類),不屬於本元件範疇。"
+          >
+            <Demo title="✅ 正確用途:選日">
+              <DateGrid mode="single" defaultMonth={STORY_TODAY} today={STORY_TODAY} locale={zhTW} />
+            </Demo>
+          </Rule>
+
+          <Rule
+            title="事件行事曆需要的能力(本元件沒有)"
+            note="判斷需求時看這幾個指標:一格日內要顯示多個事件、事件可拖曳移動、需要 week / day / agenda 視圖切換、事件跨多日的視覺連線。任一命中 → 需要專用行事曆元件。"
+          >
+            <Label warn>
+              ❌ 事件 overlay(一格顯示「09:00 Standup · 14:00 Design review」)<br />
+              ❌ Week / Day 視圖切換<br />
+              ❌ 拖曳事件改時間<br />
+              ❌ 跨日事件的連線 bar
+            </Label>
+          </Rule>
+
+          <Rule
+            title="判斷法 — 問「使用者產生的輸出是什麼」"
+            note="輸出是「一個日期值 / 多個日期值 / 一段日期範圍」→ DateGrid;輸出是「操作了某個事件(建立 / 移動 / 編輯)」→ 事件行事曆。"
+          >
+            <Label>
+              報表查詢時段、活動 RSVP 日、個資生日、訂房日期 → DateGrid<br />
+              會議日程、任務日曆、月曆視圖瀏覽 → 事件行事曆(專用元件)
+            </Label>
+          </Rule>
+        </Section>
+
+        <Section title="vs 近親 — DateGrid(inline)vs DatePicker(field trigger)">
+          <Rule
+            title="DateGrid — inline 月曆,頁面上常駐可見"
+            note="dashboard 小卡、側欄 widget、日期 filter bar。使用者一眼就看到整月,不需點開。DateGrid 是純 primitive,不自包 Popover。"
+          >
+            <Demo title="Linear 專案截止日 widget">
+              <div className="flex flex-col gap-2 w-fit">
+                <span className="text-caption text-fg-muted px-1">Project deadline</span>
+                <DateGrid
+                  mode="single"
+                  selected={inline}
+                  onSelect={setInline}
+                  defaultMonth={inline}
+                  today={STORY_TODAY}
+                  locale={zhTW}
+                />
+              </div>
+            </Demo>
+          </Rule>
+
+          <Rule
+            title="DatePicker — field 風格 trigger,點開才顯示月曆"
+            note="表單欄位、設定頁、table cell 編輯。使用者先看到日期值,需要改時才展開選擇器。DatePicker 內部消費 DateGrid 作為 popup 內容。"
+          >
+            <Demo title="Notion 設定頁:訂閱續約日">
+              <div className="w-[220px]">
+                <DatePicker value={date} onChange={setDate} clearable />
+              </div>
+            </Demo>
+          </Rule>
+
+          <Rule
+            title="判斷法 — 看「頁面是否常駐顯示整月」"
+            note="常駐(月曆是主要內容)→ DateGrid;輔助(主要是一個欄位,偶爾改)→ DatePicker。空間有限的表單永遠用 DatePicker,不要塞整個月曆進表單。"
+          >
+            <Label>
+              常駐月曆 = 使用者「在選日的脈絡中」(排班、活動、分析時段篩選);
+              DatePicker = 使用者「順手填一個日」(個資、發票、提醒)
+            </Label>
+          </Rule>
+        </Section>
+      </div>
+    )
+  },
+}
+
+export const ModeRule: Story = {
+  name: '模式 選擇',
+  render: () => {
+    const ModeDemo = () => {
+      const [single, setSingle] = useState<Date | undefined>(
+        storyDate(10),
+      )
+      const [multiple, setMultiple] = useState<Date[]>([
+        storyDate(5),
+        storyDate(12),
+        storyDate(20),
+      ])
+      const [range, setRange] = useState<DateRange | undefined>({
+        from: storyDate(8),
+        to: storyDate(18),
+      })
+
+      return (
+        <div className="flex flex-col gap-10">
+          <Rule
+            title="single — 單一日期(生日、到期日、截止日)"
+            note="資料欄位只接受一個日期值。使用者心智模型:「我要選一個日」。點新日取代舊選。此 mode 是 DatePicker 內建行為,最常見。"
+          >
+            <Demo title="Stripe 發票到期日 / Notion 個人生日">
+              <DateGrid
+                mode="single"
+                selected={single}
+                onSelect={setSingle}
+                defaultMonth={STORY_TODAY}
+                today={STORY_TODAY}
+                locale={zhTW}
+              />
+            </Demo>
+          </Rule>
+
+          <Rule
+            title="multiple — 不連續多日(活動可參加日、排休日)"
+            note="使用者要標記多個獨立日期,彼此不相關。參考 Luma RSVP 活動日標記、請假系統排休日。點已選日 = 取消。"
+          >
+            <Demo title="Luma 活動可參加日">
+              <DateGrid
+                mode="multiple"
+                selected={multiple}
+                onSelect={(d) => setMultiple(d ?? [])}
+                defaultMonth={STORY_TODAY}
+                today={STORY_TODAY}
+                locale={zhTW}
+              />
+            </Demo>
+          </Rule>
+
+          <Rule
+            title="range — 連續範圍(from → to)"
+            note="資料語意是「一段時間」,start 與 end 有順序關係。參考 Stripe 分析時段、Vercel Analytics 期間、Airbnb 訂房 check-in/out。"
+          >
+            <Demo title="Stripe Dashboard 查詢時段">
+              <DateGrid
+                mode="range"
+                selected={range}
+                onSelect={setRange}
+                defaultMonth={STORY_TODAY}
+                today={STORY_TODAY}
+                locale={zhTW}
+              />
+            </Demo>
+          </Rule>
+
+          <Rule
+            title="❌ 用錯 mode 的常見誤用"
+            note="mode 決定值的型別與鍵盤行為。用錯會讓 onSelect 收到不符預期的值型,也會誤導使用者對「可以選多少」的預期。"
+          >
+            <Label warn>
+              ❌ 連續範圍用 multiple(使用者要點滿每一天)<br />
+              ❌ 單一到期日用 range(使用者不知道要點第二次做什麼)<br />
+              ❌ 不連續多日用 range(中間日期會被強制填入)
+            </Label>
+          </Rule>
+        </div>
+      )
+    }
+    return <ModeDemo />
+  },
+}
+
+export const VisualTokenRule: Story = {
+  name: '視覺設計變數 統一',
+  render: () => (
+    <div>
+      <Rule
+        title="selected = bg-primary · today = 數字下方藍色底線"
+        note="選中日用 primary 實心填滿(和系統其他選中態如 Checkbox checked、Tab active 一致);今日但未選 = 數字下方藍色底線 bar(after pseudo,告訴使用者「這是今天」,但不搶選中視覺)。兩者同時成立時實心 selected 視覺優先,底線 bar 切 on-emphasis(白)保持可見。"
+      >
+        <Demo title="今日 + 已選他日">
+          <DateGrid
+            mode="single"
+            selected={storyDate(STORY_TODAY.getDate() + 3)}
+            defaultMonth={STORY_TODAY}
+            today={STORY_TODAY}
+            locale={zhTW}
+          />
+        </Demo>
+      </Rule>
+
+      <Rule
+        title="前後月日期 = text-fg-muted(淡化,比 disabled 弱),禁用日 = text-fg-disabled(semantic)"
+        note="前後月的補格讓使用者認得「跨月邊界」但不搶主要月份的閱讀焦點;disabled 日期保留可見(告訴使用者「這天存在但不能選」),套 `bg-disabled` + `text-fg-disabled` + `cursor-not-allowed`,點擊阻擋靠 react-day-picker 給 button 的 native `disabled` 屬性(對齊 Button disabled 設計準則,非 opacity)。"
+      >
+        <Demo title="showOutsideDays + disabled 過去日期">
+          <DateGrid
+            mode="single"
+            defaultMonth={STORY_TODAY}
+            today={STORY_TODAY}
+            locale={zhTW}
+            disabled={{ before: STORY_TODAY }}
+          />
+        </Demo>
+      </Rule>
+
+      <Rule
+        title="❌ 禁止硬寫色值繞過 token"
+        note="bg-primary / text-fg-disabled / ring-primary 等全部來自 DS semantic token。dark mode / brand swap 會自動聯動,若改用 bg-blue-500 / text-gray-400 會在 dark mode 顯示錯誤顏色。"
+      >
+        <Label warn>
+          ❌ bg-blue-500(硬色) → ✅ bg-primary(semantic)<br />
+          ❌ text-gray-400 → ✅ text-fg-disabled<br />
+          ❌ 自寫 box-shadow → ✅ ring-1 ring-primary<br />
+          ❌ 直接操作 .rdp-* 原生 class → ✅ 透過 classNames prop 覆寫
+        </Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const LocaleRule: Story = {
+  name: 'Locale 與週首日',
+  render: () => (
+    <div>
+      <Rule
+        title="locale prop 控制週首日與星期標頭語言"
+        note="react-day-picker 接受 date-fns locale 物件。週首日由 locale 物件決定,不以語言籠統判斷:en-US 週日起、en-GB 週一起——同樣是英文,週首日就不同;zhTW / de / fr(date-fns 內建值)都是週一起。下方對照:zhTW 首欄是週一,en-US 首欄是週日。Consumer 決定傳哪個 locale;locale 只控制「可見」的日期格式與週首日,不內建可見語言層。註:螢幕報讀器 aria-label(上/下月、日期朗讀等)DS 內建繁中 default,可透過 labels prop 逐鍵覆寫做 i18n(見 tsx labels 段)。"
+      >
+        <Demo title="zhTW(繁體中文 · 週一起)">
+          <DateGrid mode="single" defaultMonth={new Date(2026, 3, 1)} today={STORY_TODAY} locale={zhTW} />
+        </Demo>
+        <Demo title="預設(en-US · 週日起)">
+          <DateGrid mode="single" defaultMonth={new Date(2026, 3, 1)} today={STORY_TODAY} />
+        </Demo>
+      </Rule>
+
+      <Rule
+        title="不自訂 i18n layer"
+        note="DateGrid 不包 i18n context、不讀 app-level locale 設定。原因:date-fns locale 已是事實標準(Vercel / Stripe / Linear 都用),重新發明會綁架消費端的國際化策略。想全站同步週首日 → app 層統一傳 locale prop。"
+      >
+        <Label>
+          ✅ 全站統一:app 層 createContext(locale) → 所有 DateGrid 消費端讀 context → 傳 locale prop<br />
+          ❌ DateGrid 自包 i18nProvider(劫持 app-level 配置,違反「元件不自包 Provider」原則)
+        </Label>
+      </Rule>
+
+      <Rule
+        title="週首日不可在元件內硬寫"
+        note="若需要強制週一起(德法慣例),從 locale 來,不用 weekStartsOn prop 硬覆蓋(會讓同一 locale 在不同頁不一致)。"
+      >
+        <Label warn>
+          ❌ 元件內寫死 weekStartsOn={'{1}'}(破壞 locale 一致性)<br />
+          ✅ 傳 locale={'{de}'} → 週首自動從 locale 決定
+        </Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -12,7 +12,6 @@ benchmark:
   - 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)-->
 
@@ -22,11 +21,11 @@ benchmark:
 
 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-*` 樣式漂移。
+**實作基礎**:`react-day-picker@9` 包裝 + 本 DS token 覆寫預設視覺。**載入 RDP `style.css` 為結構基底**(tsx `import 'react-day-picker/style.css'`),再以 `classNames` prop 逐 key 用 DS token 覆寫視覺層(caption / weekday / day / range 等);**未列出的結構 key 沿用 RDP 原生 `.rdp-*` 預設**。故非「零 rdp-*」,而是「DS token 管視覺層、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 包)。
+**Storybook title 層級**:`Design System/Internal/DateGrid/*`(非 Components/,因為它是 DatePicker 的 internal primitive;對齊 `.claude/rules/ui-development.md`「Public component vs Internal primitive canonical」(intent-based 判準):consumer 經 `DatePicker` wrapper 取得,不直接 import 本元件)。
 
 **世界級命名對照(為什麼不叫 Calendar)**:
 
@@ -37,15 +36,17 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 | 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>` |
+| React Aria | `<Calendar>`(date picker grid)— source: [React Aria Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html) | `<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 -->
+結論:本 DS 用 **`Calendar` 表示 event view**、用 **`DateGrid` 表示 date-picker grid**。兩個名稱直接反映資料模型與 interaction contract，避免 consumer 以同一 component identity 混用事件瀏覽與日期選取。
 
 ---
 
 ## 何時用
 
+DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker` 取得;以下為 DS 內部組合或進階 inline 場景:
+
 - **Inline 月曆顯示**:dashboard / 行事曆小卡 / 日期 filter bar
 - **DatePicker 浮層內嵌**:DatePicker 消費本元件作為選日 popup(見 `../DatePicker/date-picker.spec.md`)
 - **範圍選擇**:`mode="range"` 適用「from → to」場景(訂單日期範圍、查詢時段)
@@ -55,10 +56,10 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 
 | 場景 | 改用 | 原因 |
 |------|------|------|
-| 日期輸入欄位 | `DatePicker` | Calendar 是 inline,欄位需要 trigger + popup 結構 |
-| 純顯示單日期 | `<DatePicker mode="display">` / `Intl.DateTimeFormat` | 不需 interactive 月曆 |
-| 時間選擇(時分) | ⚠️ 未來 TimePicker | Calendar 只處理日期層級 |
-| 事件行事曆(日程本) | 專用行事曆元件 | Calendar 是日期選擇;事件日誌需要 event overlay / drag / week/month view 切換 |
+| 日期輸入欄位 | `DatePicker` | DateGrid 是 inline,欄位需要 trigger + popup 結構 |
+| 純顯示單日期 | `<DatePicker mode="view">` / `Intl.DateTimeFormat` | 不需 interactive 月曆 |
+| 時間選擇(時分) | `TimePicker`(見 `../TimePicker/time-picker.spec.md`)| DateGrid 只處理日期層級 |
+| 事件行事曆(日程本) | 專用行事曆元件 | DateGrid 是日期選擇;事件日誌需要 event overlay / drag / week/month view 切換 |
 
 ---
 
@@ -66,19 +67,23 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 
 | 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 **根本不會生效**(舊版做法錯誤)。
 
-**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: 'bg-[var(--color-neutral-2)] [&>button]:!bg-transparent'`。
+**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: "before:content-[''] before:absolute before:inset-y-0 before:-inset-x-[2px] before:bg-neutral-selected [&>button]:!bg-transparent"`(用 `before:` pseudo + semantic `--neutral-selected` token,對齊下方 Range track canonical 與 tsx)。
 
 `[&>button]:xxx` 從 cell 向內選子 button 用於 button-level 樣式(selected / disabled 的藍底白圓等)。
 
@@ -86,7 +91,7 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 
 ## 五種 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):
+本 DS picker grid 的視覺狀態 contract：
 - today 不做 ring circle(跟 hover ring 混淆),改用 underline 或 dot
 - selected 用藍底白字圓,range 端點共用同樣視覺
 - range 中段用灰底 rectangle track,跟端點的圓相切成連續 pill
@@ -95,22 +100,23 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 
 | State | 視覺 | Token 角色(class 細節見 tsx)| 備註 |
 |-------|------|------------------------------|------|
-| **today**(未選) | 數字下方短圓桿(藍) | button `::after` bar,色用 `primary`,尺寸靠近文字行底(不貼 button 邊) | affordance 方式,不 fill bg;位置刻意貼近數字避免「黏 button 邊」視覺 flaw |
+| **today**(未選) | today indicator | 消費 `primary` semantic role；確切結構與尺寸由 `date-grid.tsx` 擁有 | 與 selected background 保持不同狀態語言，兩者疊加時仍可辨識 |
 | **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) |
+| **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-hover`(2026-07-07 user 拍板統一:瞬時 hover 進 primary 家族 = hover 階,FileUpload / Slider thumb hover 同族;base 專屬持續選中與 focus),無 bg(ring 寬度等 class 細節見 tsx)| outline 保留 cell 底色，與 selected fill 明確區分 |
 
 ## 組合狀態(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)
+- 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)
 
@@ -123,20 +129,20 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 - **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)保持比例。
+**為什麼用 `h-field-sm` 而非固定 `h-9`**:picker grid 在 lg density 下也要跟 Input 系統一起放大,`h-field-sm` 在 md = 28px / lg = 32px。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)
 - `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 防再犯)。
+歷史(2026-05-03):v6-v8 曾以未驗證的「Ant chevron muted」印象覆蓋 DS canonical,已撤回(M23 防再犯)。
 
 ⚠️ RDP `PreviousMonthButton` override 必丟 `children`(RDP 把 `<Chevron>` 當 children 傳)否則 double svg(2026-05-03 v8 抓到 bug)。
 
@@ -146,10 +152,9 @@ Prev/Next chevron 用 `<Button variant="text" size="xs" iconOnly>`(DS primitive
 
 ## 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)
+Range 起訖使用 stadium 端點，讓連續區間有清楚的開始、延伸與結束：
+- `range_start` / `range_end` cell pseudo:左 / 右半圓 stadium,向 middle 側外擴 2px bridge gap(class 細節見 tsx `range_start` / `range_end`)
+- `range_middle` cell pseudo:滿 cell 高矩形、左右各外擴 2px,無 rounding(class 細節見 tsx)
 - pseudo 蓋全 cell + bridge 4px gap → button 圓的 corner triangle 看到 pseudo bg(對齊 button 圓的左/右半弧,無「凸出」)
 - `bg-neutral-selected`(semantic = neutral-2)— 對齊 TimePicker 選中項目樣式
 
@@ -159,35 +164,35 @@ Prev/Next chevron 用 `<Button variant="text" size="xs" iconOnly>`(DS primitive
 
 - ❌ **不改視覺 token 為硬色值**(`bg-primary` 必須來自 semantic,不可 `bg-blue-500`)
 - ❌ **不用 `.rdp-*` 原生 class 直接樣式化**(繞過本元件 classNames prop 會跨版本斷掉)
-- ❌ **不自包 Popover**(Calendar 是 inline primitive;需要浮層由 consumer 包 Popover,見 DatePicker)
+- ❌ **不自包 Popover**(DateGrid 是 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` 機械攔截
+- ❌ **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_pattern_invariants.sh` C.3(P0 BLOCK,PRIMITIVES_REGEX 含 DateGrid)機械攔截
 
 ---
 
 ## A11y 預設
 
 react-day-picker v9 自動處理:
-- **鍵盤**：ArrowLeft/Right 切日,ArrowUp/Down 切週,PageUp/Down 切月,Home/End 切週首尾
+- **鍵盤**：ArrowLeft/Right 切日,ArrowUp/Down 切週,Shift+ArrowLeft/Right 切月、Shift+ArrowUp/Down 切年,PageUp/Down 切月、Shift+PageUp/Down 切年,Home/End 切週首尾
 - **ARIA**：`role="grid"` + 日格 `role="gridcell" aria-selected`
 - **Focus**：`autoFocus` prop 自動 focus 到選中日(或今天)
 - **Locale**：`locale` prop 控制週首日、星期標頭語言
 
-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 即可。
 
 ---
 
 ## shadcn passthrough 例外說明
 
-Calendar 本元件是**對 `react-day-picker` 的 `<DayPicker>` 元件薄包裝**,用於橋接 DS token(classNames 覆寫 + components 注入自訂 IconLeft/IconRight)。**不套 `React.forwardRef`**,原因如下:
+DateGrid 本元件是**對 `react-day-picker` 的 `<DayPicker>` 元件薄包裝**,用於橋接 DS token(classNames 覆寫 + components 注入自訂 `PreviousMonthButton` / `NextMonthButton`)。
+
+**ref 處理**:採 **DS 統一 `React.forwardRef` 慣例**(`forwardRef<HTMLDivElement, DateGridProps>`),但因 react-day-picker v9 的 `DayPicker` 內部是多 `<div>` 結構、未對外 forward ref 到單一 DOM 節點,故 **ref 簽名保留但不附著**(真要取 DOM 由 consumer 包一層 wrapper)。保留 forwardRef 簽名是為了跟 Radix / shadcn 其餘元件的一致設計語言對齊,即使 ref 不附著。
 
-- **底層 `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 不期待的節點,都不對
+**props passthrough**:`DateGridProps = React.ComponentProps<typeof DayPicker>`,經 `{...props}` 直接 spread 至 `DayPicker`(declarative API:selected / onSelect / mode / classNames / components 等)。
 
-保留 `displayName = 'Calendar'` 讓 React DevTools / Storybook 辨識;`...props` 透過 props interface 顯式列舉 passthrough 至 DayPicker(不 spread DOM,保持 API 邊界清楚)。
+`displayName = 'DateGrid'` 讓 React DevTools / Storybook 辨識。
 
-**何時應改**:若未來 react-day-picker 升級提供 forwardRef 或 `ref` prop,或我們決定包一層自有 DOM 容器(如加 footer action buttons),再改為 canonical forwardRef wrapper。
+**何時應改 ref 附著**:若未來 react-day-picker 升級提供單節點 `ref` prop,或我們決定包一層自有 DOM 容器(如加 footer action buttons),再把 ref 接到該容器上。
 
 ---
 
@@ -195,15 +200,15 @@ Calendar 本元件是**對 `react-day-picker` 的 `<DayPicker>` 元件薄包裝*
 
 - **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 內建)。
+- **Empty(全 disabled days)**:極端場景(所有日期都被 disabled matcher 命中),DateGrid 渲完整 grid 但全部 cell 為 disabled state,鍵盤焦點停留無導覽目標(react-day-picker v9 內建)。Enter / Space 在 disabled cell 上無動作不報錯(RDP DayButton 對 disabled day 渲染 native `disabled`,focus target 時改掛 `aria-disabled`),Tab 走 roving tabIndex 整個 grid 只停一格。
 - **Dark mode**:走 semantic token(primary / neutral / fg-muted)自動 adapt。
-- **Density**:DateGrid cell 尺寸固定不隨 density 變(date grid 為密度敏感的 8 列 × 6 行 layout,壓縮會破壞 reading)。
+- **Density**:DateGrid day cell 走 `h-field-sm w-[var(--field-height-sm)]`,**隨 density 縮放**(md = 28×28 / lg = 32×32,token `--field-height-sm` 在 `[data-density="lg"]` override 為 `2rem`),跟 popup 內 Input / Button 等 field 家族一起放大保持比例(見 L128 + L120)。grid 寬度為 intrinsic(7 × cell + 4px gap + `p-3`),lg 下整體變寬;DateGrid 無內部 overflow / responsive 縮排機制,容器(Popover / parent)以內容寬呈現。
 
 ---
 
 ## 相關
 
-- `../DatePicker/date-picker.spec.md` — **本元件 consumer**:DatePicker 消費 Calendar 作為選日 popup
+- `../DatePicker/date-picker.spec.md` — **本元件 consumer**:DatePicker 消費 DateGrid 作為選日 popup
 - `../../tokens/color/color.spec.md` — semantic token 來源（primary / neutral / fg-muted 等）
 - react-day-picker 官方文件 — `https://react-day-picker.js.org`