@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

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

@@ -50,7 +50,7 @@ const PARTS: Record<PartKey, PartSpec> = {
   dayHover:     { label: 'Hover',        bg: 'transparent',     text: '--foreground',  border: '--primary',   extra: 'hover 藍圈 1.5px(無填底)' },
   dayOutside:   { label: 'Outside 月份', bg: 'transparent',     text: '--fg-muted',    border: 'transparent' },
   dayDisabled:  { label: 'Disabled',     bg: '--bg-disabled',   text: '--fg-disabled', border: 'transparent', extra: 'bg-disabled · cursor-not-allowed · native disabled' },
-  dayFocus:     { label: 'Focus-visible',bg: 'transparent',     text: '--foreground',  border: '--ring',      extra: 'ring-2 ring-ring' },
+  dayFocus:     { label: 'Focus-visible',bg: 'transparent',     text: '--foreground',  border: '--ring',      extra: 'focus-visible:focus-ring-inset · 內描邊往內 2px;填色格 focus-ring-inset-emphasis(1px 白線退 3px)' },
 }
 
 const PART_ORDER: PartKey[] = [
@@ -280,7 +280,7 @@ export const Inspector = {
                 <span className="text-[10px] font-semibold text-fg-muted uppercase tracking-wider">Style</span>
               </div>
               <PropRow label="日格 Radius">rounded-full · 圓形</PropRow>
-              <PropRow label="Focus">ring-2 ring-ring</PropRow>
+              <PropRow label="Focus">focus-visible:focus-ring-inset · 內描邊往內 2px;填色格 focus-ring-inset-emphasis(1px 白線退 3px)</PropRow>
               <PropRow label="Transition">transition-colors</PropRow>
             </div>
           </div>

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

@@ -108,7 +108,7 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 | **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 明確區分 |
-| **range 預覽框(停留 / 焦點)** | 同色同粗的藍色細框把「點下去會變成」的區間框起來,兩端半圓、與 track 同高;停留日就是框的那一端 | td `::after`(track 用 `::before`),1.5px `primary-hover`;class 住在 tsx `RANGE_PREVIEW_CLASSNAMES` | 只有 `DatePicker.Range` 會算出這組 modifier(它才知道正在選哪一端);DateGrid 只擁有畫法。規則見下方「區間預覽框」。**跨格不閃**:停留日掛在 button 的 mouseenter / mouseleave,格間 4px 縫隙屬於 table,指標經過縫隙會先 leave 再 enter、整條框卸掉一幀 —— day button 的 `::before` 命中區外擴 2px 補滿縫隙(與框跨縫用的 −2px 是同一個數字,hit = paint;user 2026-09-23 抓到「水平移動到隔日框會閃一下」) |
+| **range 預覽框(停留 / 焦點)** | 同色同粗的藍色細框把「點下去會變成」的區間框起來,兩端半圓、與 track 同高;停留日就是框的那一端 | td `::after`(track 用 `::before`),1.5px `primary-hover`;class 住在 tsx `RANGE_PREVIEW_CLASSNAMES` | 只有 `DatePicker.Range` 會算出這組 modifier(它才知道正在選哪一端);DateGrid 只擁有畫法。規則見下方「區間預覽框」。**跨格不閃**:停留日掛在 button 的 mouseenter / mouseleave,格間 4px 縫隙屬於 table、圓外的四個角屬於 td,指標經過這些地方會先 leave 再 enter、整條框卸掉一幀(user 2026-09-23 抓到「水平移動到隔日框會閃一下」)—— 現行解法是 DateGrid **只在指標真的離開整張格陣時才轉發 leave**,停在縫裡或可點日子圓外的角裡都算「還在上一天」(不論移得多快多慢、走不走中線;慢慢從縫裡走出去的那條路 2026-09-26 補上 = D1,圓外的角 2026-09-26 補上 = D2),見下方「日期格的命中區 = 可視形狀」的「現行機制」;框亮著時在縫或角裡點下去 = 點停留日,見同節「縫與角裡的點擊」;2026-09-23 曾用 day button `::before` 外擴 2px 吃掉那道縫,已於 2026-09-24 撤除(命中區大於可視形狀) |
 | **focus-visible(鍵盤焦點)** | 非填色格:往內 2px 藍線;填色格(selected / range 端點):1px 白線退 3px,外圈留藍 | day button `focus-visible:focus-ring-inset`;填色 modifier 另掛 `EMPHASIS_FOCUS_RING_CLASSNAME`(= `focus-ring-inset-emphasis`,幾何 owner `styles/base.css` + `focus-canonical.md`「填色元素上的內描邊」)| 格與格只隔 4px,track / 預覽框就跑在縫裡,往外畫會壓到框線;藍底上藍線看不見、白線貼邊只是削小藍圓(2026-09-23 user 拍板 D,原話在 focus-canonical 來源總帳) |
 
 ### 鄰月日子:一條原則(2026-09-24 user 拍板)
@@ -160,6 +160,168 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 
 **世界級對照**(讀原始碼,2026-09-23):五家有區間選擇的元件庫都在停留時預覽區間,差別只在畫法 —— Ant Design v4 用虛線上下邊 + 兩端側邊([panel.less](https://github.com/ant-design/ant-design/blob/4.x-stable/components/date-picker/style/panel.less) `-range-hover*`,`border-top/bottom: dashed @picker-date-hover-range-border-color`)、MUI X 用 1.2px 虛線([DateRangePickerDay.tsx](https://github.com/mui/mui-x/blob/master/packages/x-date-pickers-pro/src/DateRangePickerDay/DateRangePickerDay.tsx) `previewStyles`)、Ant v5 現行與 Polaris 用與已選區間同色的淺色填([rc-picker PanelBody.tsx](https://github.com/react-component/picker/blob/master/src/PickerPanel/PanelBody.tsx) 把 `hoverRangeValue` 算成 `-in-range`;[Polaris Day.tsx](https://github.com/Shopify/polaris/blob/main/polaris-react/src/components/DatePicker/components/Day/Day.tsx) `(inRange || inHoveringRange) && styles['Day-inRange']`)、Carbon(flatpickr)用填色([index.ts](https://github.com/flatpickr/flatpickr/blob/master/src/index.ts) `onMouseOver` → `startRange / inRange / endRange`)。**本 DS 選實線**:沿用單日 hover 圈的顏色與粗細,不新增第二種「暫定」表達(M23 DS 既有語言優先;user 2026-09-23 Q2 拍板)。我們包的 react-day-picker 本身沒有預覽([range-mode 文件](https://daypicker.dev/selections/range-mode)只有 `range_start / range_middle / range_end`),所以由 DatePicker.Range 自算。
 
+## 日期格的命中區 = 可視形狀(2026-09-24 逐案裁定)
+
+**日期格的可視形狀是那個 28×28(lg 32)的圓**(`day_button` 的 `rounded-full`,懸停時 1.5px 藍圈就畫在它身上),
+**命中區就是同一個圓,不外擴**。跨元件契約(`../../ds-canonical/references/hit-area-canonical.md`
+「懸停回饋的形狀 ≡ 命中區」)的唯一例外是「可視形狀先天當不了目標的線與點」;28px 的圓不屬於那一類,吃不到例外。
+(2026-09-26 補註:區間預覽框亮著時,縫與圓外的角裡那一下點擊交給停留日 —— 那**不是**把命中區外擴:滑過仍只從這顆圓開始,
+沒有框時縫與角點了照樣沒反應。規則與理由見下方「縫與角裡的點擊」。)
+
+### 先前這裡有一條隱形帶,而且比看起來大得多
+
+2026-09-23 這裡曾有 `before:content-[''] before:absolute before:-inset-[2px]`,
+名義上是「四邊各 2px」,**實測是最遠外推 9.3px** —— 因為 `::before` 是**方的**、沒有圓角,
+它不只補了格間 4px 的縫,還把圓**四個角外面**的區域一起收進命中區(方角到圓心 √2×16 ≈ 22.6,圓半徑 14)。
+
+| 量的東西(`elementFromPoint` 逐 0.5px 掃,storybook 展示--單選) | 移除前 | 移除後 |
+|---|---|---|
+| 圓內取樣點命中 / 漏掉 | 2188 / **0** | 2188 / **0** |
+| 圓外取樣點「仍然命中」 | **1763** | **40** |
+| 圓外最遠仍命中的距離 | **9.33px** | **1.10px**(瀏覽器對圓角命中測試的抗鋸齒,同 `agent-fab-hit-area-invariant.mjs` 的 `EDGE_TOLERANCE = 1.5`) |
+| 格間縫隙中點的擁有者 | 相鄰日期的 button | `<table>`(沒有人宣稱它) |
+
+### 那條帶原本在解什麼 —— 以及為什麼那是表層解
+
+它解的是 user 2026-09-23 抓到的「從某日水平移動到其隔日,藍色的區間框線都會閃動一下」:
+停留日掛在 button 的 `mouseenter` / `mouseleave`(react-day-picker 只給這一層),
+而格與格之間的 4px(`border-spacing-1`)屬於 `<table>`、不屬於任何一天 ——
+指標經過縫時先 leave(整條框卸掉)再 enter(補回)。
+
+**閃動的根因是「停留日在縫裡被清掉」,不是「縫裡沒有人收 enter」。** 幾何外擴改的是後者,是表層。
+根因層的解法就在當時那條註解自己引到的 MUI:**只在指標真的離開整張格陣時才清停留日**
+([DateRangeCalendar.tsx:479-486](https://github.com/mui/mui-x/blob/master/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx) ——
+`rangePreviewDay` 的清除逐字掛在 `CalendarTransitionProps` 的 `onMouseLeave`,也就是**整個日曆容器**,不是每一天)。
+
+### 現行機制(`date-grid.tsx`)
+
+1. 月曆格陣掛 `data-day-grid` 錨點(`AnchoredMonthGrid`,覆寫 RDP 的 `MonthGrid`)。
+2. `handleDayMouseLeave`:leave 事件的 `relatedTarget` 若落在同一張格陣的**縫或角**裡(`isGapOrCorner`),就**不轉發**給消費端;
+   其餘一律照常轉發。
+   - **縫**:在格陣裡、但既不在 `<td>` 也不在 `<th>` 上 —— border-spacing 的 4px 空白、表格最外圈,都屬於 `<table>` 自己。
+   - **角**(2026-09-26 補,D2):在某個**可點日子**的 `<td>` 裡、但不在它那顆圓(button)上。日期是 28px 的圓、放在 28×28 的方格裡,
+     圓外的四個角屬於 td、不屬於圓。先前只算縫、把角當成「已經離開」,指標只要沒走在格子正中線上就先清框再補回 ——
+     2026-09-26 實測(每步 1px,淺深色相同):偏上 1/4 格 6 步、貼上緣 2px 14 步、貼左緣 2px 14 步、斜穿四格交會處 12 步,
+     整條框(17 格)消失;走中線 0 步。09-24 的實測與閘都只走中線,所以沒抓到。
+   - 不可點的日子(含它的角)、空白補位格、星期列、格陣之外:都不算,照常清掉。
+   - 若整張 DateGrid 被放進別的表格的格子裡,`closest('td,th')` 會找到外面那一格;判斷一律以「那一格在不在本格陣裡」為準,不會把縫誤判成離開。
+3. `handleGridMouseOver`:補掉「穿過縫或角之後停在**不可點**的日子、空白補位格或星期列」那條路徑 ——
+   disabled 的 button 收不到滑鼠事件、不會再有任何 day enter/leave,沒有這一段的話上一天的預覽框會留著
+   (`datepicker-range-preview.mjs`「順序不合不預覽」那兩條斷言就是這樣紅的,2026-09-24 實測)。停在縫或角裡不動作(與第 2 條同一支判斷)。
+4. `handleGridMouseLeave`(2026-09-26 補,D1,待辦總帳 N54):補掉「**從縫或角直接離開格陣**」那條路徑 ——
+   指標離開最外圈那一天時落在縫或角裡,那次 leave 依第 2 條被吞(欠著);接著指標走出 `<table>`,已經沒有任何一天會再收到 leave、
+   也沒有 `td` / `th` 會收到 mouseover,預覽框就卡在上一天。實測(2026-09-26 前):從 6/13 每步 1px 往右,經過縫、月曆內距、浮層邊,
+   走到浮層外 20px,停 2 秒仍是 5/4→6/13;每步 1–4、8px 都卡住,6、12、20px 或一次跳出去才會清 —— 快慢決定了指標有沒有「停」在縫裡。
+   修法:格陣 `<table>` 掛 `onMouseLeave`,**只在有欠著的 leave 時**補送一次(一次跳出去那條路 day button 的 leave 已照常轉發,不重送)。
+   這是上面那句判準「只在指標真的離開整張格陣時才清」本來就要的,缺的只是實作:MUI X 同時掛了「容器 `onMouseLeave` 清除」
+   ([DateRangeCalendar.tsx#L481-L486](https://github.com/mui/mui-x/blob/v9.14.0/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx#L481-L486)
+   `onMouseLeave: () => setRangePreviewDay(null)`),2026-09-24 照 MUI 做「縫裡不清」時沒一起做這一半。
+   兩張月曆並排時每張各是一張格陣:兩張之間的空白算離開(`../DatePicker/date-picker.spec.md`「滑鼠離開**日期格區**」)。
+   縫與角裡照亮(維持上一天)不變;「偏離中線橫越時仍會閃」(D2)由第 2 條的「角」解決。
+   閘:`scripts/datepicker-range-preview.mjs`「慢慢移出」段(`exit` 家族,含對照組;(c) 路線貼上緣 2px,先穿過角再出去)。
+5. `handleGridClick` / `handleGridPointerDown` / `handleGridMouseMove` / `handleDayFocus`(2026-09-26):框亮著時在縫或角裡點下去 = 點停留日,
+   游標同為手形;`handleDayFocus` 只記「滑鼠停留之後,鍵盤又移了看得見的焦點」(最後一個輸入是鍵盤 → 縫與角不接點擊),不改任何焦點行為 ——
+   見下一節「縫與角裡的點擊」。
+
+錨點刻意用顯式屬性而不是 `closest('table')`:標籤名是「剛好成立的觀察量」,不是要保證的性質(M37);
+而且顯式屬性讓閘的對照組可以只用一行 `removeAttribute` 精準弄壞這個機制。
+
+⚠️ `AnchoredMonthGrid` **必須定義在 module 層**。第一版寫成 render 內的 inline 箭頭函式,
+每次 render 都是新的 component type → React 把整個格陣 unmount 再 mount → RDP 內部 effect 重設 state →
+`Maximum update depth exceeded`(React #185),storybook 整個 DatePicker range 故事白畫面。
+
+### 縫與角裡的點擊(2026-09-26)
+
+**規則**:區間預覽框亮著、指標停在縫或角裡(框仍停在上一天)時,**點下去 = 點那一天** —— 結果與直接點那一天完全相同
+(DatePicker.Range 正在選結束日時:結束日變成那一天、浮層關)。游標在那裡與日期一樣是手形。
+沒有框的時候,縫與角點下去沒反應、游標不是手形。
+跨元件的原則住在 `../../ds-canonical/references/hit-area-canonical.md`「滑過原則」一-6(評分星星同一條);本節只寫日期的細則。
+
+| 指標在哪、當時的狀態 | 縫與角裡的預覽框 | 點下去 | 游標 |
+|---|---|---|---|
+| 滑鼠從某一天移進縫或角,框亮著、停留端就是那一天 | 維持上一天 | = 點那一天 | 手形 |
+| 沒有框(兩端都空,或對面那端還空、只有單格 hover 圈) | —— | 沒反應 | 一般箭頭 |
+| 鍵盤把框移到別天之後,滑鼠還停在縫或角裡 | 框在鍵盤那一天 | 沒反應(縫與角屬於滑鼠上一天,那一天不是框的停留端) | 一般箭頭 |
+| 觸控 / 觸控筆點在縫或角裡 | —— | 沒反應(維持原樣) | —— |
+| 不可點的日子、空白補位格、星期列 | 清掉(見「現行機制」第 3 條) | 沒反應 | —— |
+
+**來源**:
+- 決定:待辦總帳(`governance/planning/2026-09-25-interaction-and-hover-remediation.md`)N54 建議 ①
+  「預覽亮著的任何位置、包括縫,點下去就得到正在預覽的值」(`:229`,AI 措辭);2026-09-26 同意批次 `:105` ——
+  「日期縫與角」列在 user 沒點名、依「其餘都照建議做嗎」的問法理解為照建議做的四項裡(總帳原文標為 AI 判讀、回報時明講);
+  實作的兩句「在縫或角裡點下去 = 確認正在預覽的那一天」「日期圓圈外的角滑過去不再閃」是 **AI 的措辭**,不是 user 原話。
+- 原則:user 2026-09-26(總帳 `:225`,逐字)「我滑到某個區塊但不是滑到文字上但文字卻變色了，此時表示產生了樣式變化，儘管沒滑到文字上，此時點擊也應該要有反應，我的意思是這樣」;
+  同意改寫原則見 `:65`(「1. 我同意」)。框亮著時,縫與角正是「滑過有變化」的位置。
+
+**點到哪一天 = 框停在哪一天**:同一個角點下去得到哪一天,取決於指標是從哪一天移進來的(例:從 5/20 移進 5/21 的左上角 → 得到 5/20;
+React Aria 實測相同,R20 已指出 —— 它在「月曆裡、但不在按鈕上」放開一律確認正在預覽的區間,[`useRangeCalendar.ts#L80-L86`](https://github.com/adobe/react-spectrum/blob/4dd44e0f400636a87a9ad4390903e78c5ae6113c/packages/react-aria/src/calendar/useRangeCalendar.ts#L80-L86))。滑鼠甩得很快、中間幾天沒被取樣到時也一樣 —— 框停在哪一天,點下去就是哪一天,永遠是畫面上框著的那一個。
+
+**這不是把命中區外擴**(與上方「命中區就是同一個圓」相容):滑過(enter)仍只從那顆圓開始;沒有框時縫與角點了照樣沒反應。
+縫與角只在「框已經亮著、而且停留端就是那一天」時接那一下點擊 —— 回饋在前、點擊在後,不會出現「沒亮卻點得到」。
+判斷「框的停留端就是那一天」直接看那一格有沒有掛上框的端點 class(`RANGE_PREVIEW_CLASSNAMES` 的起點 / 終點 / 單格,只住在 `date-grid.tsx`)——
+框正是那組 class 畫出來的,所以這一問就是性質本身,不是旁證(M37)。
+
+**實作**:真的去點那顆 button(`button.click()`),不另寫一份選取邏輯 —— 選取、焦點、關浮層都走 react-day-picker 的同一條路,結果與直接點那一天一模一樣。
+游標:日期是 button,手形來自 `../../styles/base.css`「`button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; }`」;
+縫與角裡點得到時,格陣掛 `data-gap-confirms`,`month_grid` 的 `data-[gap-confirms]:cursor-pointer` 讓縫(`<table>`)與角(`<td>` 繼承)同為手形。
+游標與點擊用同一支判斷(`gapConfirmTarget`),指標每移一步重算一次(框是 React 狀態、慢一幀才畫上;鍵盤也可能把框移走)。
+
+**只算滑鼠**(AI 工程判斷;user 的討論與 R21 實測都只涵蓋滑鼠):觸控沒有「滑過」,框停在上一次點的那一天,不是手指現在碰到的位置 ——
+手指點在 5/17 的角卻選到 5/10 是錯的。所以觸控 / 觸控筆點在縫或角裡維持原樣(沒反應)。
+
+**鍵盤不變**:本節只動滑鼠。方向鍵、Enter / Space、焦點框、預覽跟著焦點走,全部照舊。
+
+**世界級**(2026-09-26 R21 實測 + 釘版原始碼):
+
+| 系統 | 縫與角裡的預覽 | 在那裡點下去 | 一手出處 |
+|---|---|---|---|
+| MUI X DateRangeCalendar v9.14.0 | 維持上一天(只在離開月份容器時清) | 沒反應 | [`DateRangeCalendar.tsx#L481-L486`](https://github.com/mui/mui-x/blob/c83b3dd6996f6913947b1be3e5d47655153ced60/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx#L481-L486) `onMouseLeave: () => setRangePreviewDay(null),` |
+| Chakra UI DatePicker(Zag 1.43.3) | 維持上一天(只在離開表格時清) | 沒反應 | [`date-picker.connect.ts#L546-L548`](https://github.com/chakra-ui/zag/blob/46f88c089c1dbb0fc681b31172dc5eb8a07eef0d/packages/machines/date-picker/src/date-picker.connect.ts#L546-L548) `onPointerLeave() { send({ type: "TABLE.POINTER_LEAVE" })`;[`date-picker.machine.ts#L516-L519`](https://github.com/chakra-ui/zag/blob/46f88c089c1dbb0fc681b31172dc5eb8a07eef0d/packages/machines/date-picker/src/date-picker.machine.ts#L516-L519) `actions: ["clearHoveredDate"],` |
+| React Aria RangeCalendar | 維持上一天(只有 enter) | **確認正在預覽的區間** | [`useRangeCalendar.ts#L23-L32`](https://github.com/adobe/react-spectrum/blob/4dd44e0f400636a87a9ad4390903e78c5ae6113c/packages/react-aria/src/calendar/useRangeCalendar.ts#L23-L32) 預設 `select`:"select the currently hovered range of dates."(該設定的範圍:"Controls the behavior when a pointer is released outside the calendar or a blur occurs mid selection");讓「月曆裡、但不在按鈕上」也算進去的是 [`#L80-L86`](https://github.com/adobe/react-spectrum/blob/4dd44e0f400636a87a9ad4390903e78c5ae6113c/packages/react-aria/src/calendar/useRangeCalendar.ts#L80-L86) 的 `!target.closest('button, [role="button"]')` |
+| Ant Design RangePicker 6.6.5 | 沒有縫:整格就是那一天 | 選那一天 | [`panel.ts#L346-L349`](https://github.com/ant-design/ant-design/blob/4a39f54842eade4e565ab336ef6097cd7e723cdd/components/date-picker/style/panel.ts#L346-L349) `borderCollapse: 'collapse',`、[`#L364-L367`](https://github.com/ant-design/ant-design/blob/4a39f54842eade4e565ab336ef6097cd7e723cdd/components/date-picker/style/panel.ts#L364-L367) 整格 `cursor: 'pointer',`;[rc-picker `PanelBody.tsx#L145-L164`](https://github.com/react-component/picker/blob/a975a11f9a959a811b1ecd901e8ff8ae8f0e515b/src/PickerPanel/PanelBody.tsx#L145-L164) 同一個 `<td>` 掛 `onClick` / `onMouseEnter` / `onMouseLeave` |
+| **本 DS** | 維持上一天(縫 + 可點日子圓外的角) | 框亮著時 = 點那一天 | 本節 |
+
+沒有一家兩件事都做:「縫與角維持上一天」取 MUI X、Chakra,「縫裡點下去確認」取 React Aria。
+Ant 靠「整格都是那一天」達成同樣的「亮了就點得到」,但它能點的方格(36)大於畫出來的方塊(24),正是本 DS 09-24 撤掉的那條路(上方「先前這裡有一條隱形帶」)。
+Ant 整格是手形(上表 `#L364-L367`),與本節「點得到的縫與角是手形」同一個道理。
+
+閘:`scripts/datepicker-range-preview.mjs` 的 `corner` 家族(四條角落路線,每步 1px)與 `gapclick` 家族(角、縫各點一次 + 沒有框時的對照面),
+兩家各有 `--selftest` 對照組(把「離開圓進到角」改寫成離開格陣 / 攔下縫與角裡的點擊並把游標蓋回 auto → 必須紅)。
+
+### 實測(2026-09-24)
+
+| 斷言 | 結果 |
+|---|---|
+| 命中 ≡ 可視(圓) | 圓內 2188 點全命中、0 漏;圓外最遠 1.10px(抗鋸齒容差內) |
+| 水平跨格 5/20→5/21(30 小步) | 框最少仍有 **17** 格(0 = 縫裡整條框消失) |
+| 垂直跨列 5/20→5/27(30 小步) | 框最少仍有 **17** 格 |
+| **對照組**:拔掉 `data-day-grid` 錨點 | 兩條跨法都掉到 **0** —— 證明這組數字量得到機制在不在 |
+| `scripts/datepicker-range-preview.mjs` | 109 條全過(exit 0);`--selftest` 五個家族全部會紅,含 `crossing` |
+
+**不越出宿主**:第一格的命中左緣 42.5 落在 `month` 的 padding box(左緣 33)之內 9.5px,連 `<table>` 盒都沒出去。
+**不蓋鄰居**:相鄰兩格的命中盒水平間隙實測 **0.00px**(相切零重疊)。
+
+**依據不是觸控尺寸建議** —— 本 DS 明確不以「手指要多大才點得到」當命中區的依據
+(hit-area-canonical「本 DS 不採納觸控尺寸建議」)。
+
+### 實測(2026-09-26,角 + 縫與角的點擊)
+
+Chromium 單一行程、1280×900;「現行建置」= repo 的 `storybook-static`(已含 D1);「D1 前建置」= 09-25 的建置;「修後」= 本次改動建出的 storybook。
+
+| 斷言 | D1 前建置 | 現行建置 | 修後 |
+|---|---|---|---|
+| 角落路線(每步 1px,停 5/20)偏上 1/4 格 / 貼上緣 2px / 貼左緣 2px / 斜穿交會處:框縮掉的步數 | 6 / 14 / 14 / 12 | 6 / 14 / 14 / 12 | **0 / 0 / 0 / 0**(淺、深色另以 R21 量具重量,六條路線全 0) |
+| 同路線上「停在格子裡、圓外的角」的步數(證明路線真的經過角) | 2 / 10 / 10 / 8 | 2 / 10 / 10 / 8 | 2 / 10 / 10 / 8 |
+| 框亮著,在 5/20 右上角點下去 | 沒反應(框早已清掉) | 沒反應(框早已清掉) | 結束日 5/12 → **5/20**、浮層關;游標 `pointer` |
+| 框亮著,在 5/20 右邊縫的中點點下去 | 沒反應;游標 `auto` | 沒反應;游標 `auto` | 結束日 → **5/20**、浮層關;游標 `pointer` |
+| 沒有框(兩端都空),在某天的角裡點下去 | 沒反應;`auto` | 沒反應;`auto` | 沒反應;`auto`(不變) |
+| 慢慢移出 (c):6/13 貼上緣 2px 往右走出浮層 | 一進角框就沒了(格陣最外圈量到 0 格) | 同左 | 最外圈仍有框(48 格)、出去後 0 格 |
+| 鍵盤把框移到 5/5 後,滑鼠仍停在 5/20 的角裡點 | —— | —— | 沒反應;游標 `auto`(對照:不按鍵盤 → 選到 5/20) |
+| 同上,但滑鼠停的是 5/4(剛好是鍵盤那個框的起點) | —— | —— | 沒反應;游標 `auto` |
+| 框亮著,改用手指點同一個角 | —— | —— | 沒反應(對照:滑鼠點 → 選到框著的那一天) |
+| `scripts/datepicker-range-preview.mjs` | 12 條紅(新增 10 條 + D1 的 2 條) | 10 條紅(全是新增的) | 136 條全過;`--selftest` 八個家族全部會紅 |
+| **對照組**:拔掉 `data-day-grid` 錨點(中線橫向) | —— | —— | 縮掉 4 步(量具看得到閃) |
+
 ## Spacing canonical(2026-05-03 v8)
 
 - **內距住在每一張月曆身上,不在根**(2026-09-18 user 裁示,原話:「我覺得真的要做的話,邏輯就是這樣,

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

@@ -110,6 +110,14 @@ export const RANGE_PREVIEW_CLASSNAMES = Object.freeze({
   end: cn(PREVIEW_FRAME, PREVIEW_STROKE, 'after:-left-[2px] after:right-0 after:rounded-r-full', CLIP_INNER_LEFT),
   single: cn(PREVIEW_FRAME, PREVIEW_STROKE, 'after:inset-x-0 after:rounded-full'),
 })
+// 某一格是不是正畫著框的**端點**(起點 / 終點 / 單格)。判準就是上面這三串 class 有沒有整串落在那個 td 上 ——
+// 框正是由它們畫出來的,而它們只住在本檔(DatePicker.Range 原樣交給 modifiersClassNames),所以這一問就是「框的端點畫在這格上嗎」
+// 本身,不是旁證(M37)。中段只有上下線、不算端點。用在下方「縫或角裡點下去 = 點停留日」:停留日一定是框的端點,
+// 不是端點(框是鍵盤那一天設的、或根本沒有框)就不接那一下點擊。
+const PREVIEW_END_TOKENS = [RANGE_PREVIEW_CLASSNAMES.start, RANGE_PREVIEW_CLASSNAMES.end, RANGE_PREVIEW_CLASSNAMES.single]
+  .map((classes) => classes.split(/\s+/).filter(Boolean))
+const drawsPreviewEnd = (cell: Element | null) =>
+  !!cell && PREVIEW_END_TOKENS.some((tokens) => tokens.every((token) => cell.classList.contains(token)))
 // 預覽「上膛」的格(停留會有框的那些天)**靜態**壓掉 button 的單格 hover 圈。
 // 單格圈是 CSS :hover,指標一到就畫;框是 React 狀態,慢一幀。只靠上面 PREVIEW_FRAME 裡的壓制(掛在停留後才出現的
 // preview modifier 上),每次停留都會先閃一圈整圓、再變成半圓(user 2026-09-23:「hover 到日期都會先看到一圈圓形藍色外框,
@@ -128,6 +136,70 @@ const ZH_FULL_DATE = new Intl.DateTimeFormat('zh-TW', { dateStyle: 'full' })
 const ZH_MONTH_YEAR = new Intl.DateTimeFormat('zh-TW', { year: 'numeric', month: 'long' })
 const ZH_WEEKDAY = new Intl.DateTimeFormat('zh-TW', { weekday: 'long' })
 
+// 可點的日子 = 沒有 disabled、也沒有 aria-disabled 的那顆 button(RDP 對鍵盤焦點落在不可選日時改掛 aria-disabled)
+const CLICKABLE_DAY = 'button:not(:disabled):not([aria-disabled="true"])'
+
+// ── 「縫或角」:格陣裡不屬於任何一天、但仍算「指標還在上一天身上」的位置(2026-09-26 補上「角」)──
+//   (a) 縫:既不在 `<td>` 也不在 `<th>` 上 —— border-spacing 的 4px 空白、表格最外圈,都屬於 `<table>` 自己;
+//   (b) 角:在某個**可點日子**的 `<td>` 裡、但不在它那顆 button(28px 的圓)上 —— 圓放在 28×28 的方格裡,圓外的四個角屬於 td。
+// 停在不可點的日子(含它的角)、空白補位格、星期列、或格陣之外 → 都不算,照常清掉。
+// 先前只有 (a):角被當成「已經離開」,指標只要沒走在格子正中線上(偏 1/4 格、貼邊、斜著走)就先清框再補回 ——
+// 2026-09-26 實測整條框(17 格)消失 6–14 步(每步 1px),淺深色相同(世界級對照與一手出處:date-grid.spec.md「縫與角裡的點擊」)。
+// 格陣自己的判斷(`grid.contains(cell)`):整張 DateGrid 若被放進別的表格的格子裡,`closest('td,th')` 會找到外面那一格,
+// 那仍是本格陣的縫,不是「離開」。
+function isGapOrCorner(node: EventTarget | null, grid: Element | null): boolean {
+  if (!(node instanceof Element) || !grid || !grid.contains(node)) return false
+  const cell = node.closest('td,th')
+  if (!cell || !grid.contains(cell)) return true // (a) 縫
+  if (cell.tagName !== 'TD') return false // 星期列
+  const button = node.closest('button')
+  if (button && cell.contains(button)) return false // 就在那顆圓上(可點與否都不是縫也不是角)
+  return cell.querySelector(`:scope > ${CLICKABLE_DAY}`) !== null // (b) 可點日子的角
+}
+
+// 縫或角裡「點下去會確認」時掛在格陣上的屬性,只用來把游標變成跟日期一樣的手形
+//(日期是 button,手形來自 styles/base.css「button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer }」)。
+// 下方 month_grid 的 `data-[gap-confirms]:cursor-pointer` 讀的就是它 —— 兩處字串必須一致。
+// 用屬性而不是 React state:它跟著指標每一步變,不該讓整張格陣重畫(同 tabs.tsx 的 data-action-hover、data-table.tsx 的 data-hovered)。
+const GAP_CONFIRMS_ATTR = 'data-gap-confirms'
+
+// 月曆格陣:在 react-day-picker 預設的 `<table {...props} />`
+//(node_modules/react-day-picker/dist/esm/components/MonthGrid.js)上多掛這些東西 ——
+//   (1) `data-day-grid` 錨點,給下方 handleDayMouseLeave 判斷「指標現在停在格陣的哪一種地方」;
+//   (2) `onMouseOver`(由 context 遞進來),補掉「指標穿過縫或角之後停在不可點的日子」這條路徑;
+//   (3) `onMouseLeave`(由 context 遞進來),補掉「指標從縫或角直接離開格陣」這條路徑(D1,見 handleGridMouseLeave);
+//   (4) `onMouseMove` / `onPointerDown` / `onClick`(由 context 遞進來):縫或角裡的手形游標,與「在縫或角裡點下去 = 點停留日」。
+// 只多屬性與事件,不改結構。
+//
+// ⚠️ **必須定義在 module 層,不能寫成 render 內的 inline 箭頭函式。** 寫成 inline 時每次 render 都是一個
+// 新的 component type,React 會把整個格陣 unmount 再 mount,RDP 內部的焦點/動畫 effect 因此重新設 state,
+// 立刻撞上「Maximum update depth exceeded」(React #185)—— 2026-09-24 第一版就是這樣寫的,storybook
+// 整個 DatePicker range 故事白畫面。同檔的 PreviousMonthButton / NextMonthButton 是葉節點按鈕,沒有這個問題。
+// handler 走 context 而不是 props,正是因為 RDP 只給 MonthGrid 固定的那組 props,塞不進額外的。
+interface GridPointerHandlers {
+  onMouseOver?: (event: React.MouseEvent<HTMLTableElement>) => void
+  onMouseLeave?: (event: React.MouseEvent<HTMLTableElement>) => void
+  onMouseMove?: (event: React.MouseEvent<HTMLTableElement>) => void
+  onPointerDown?: (event: React.PointerEvent<HTMLTableElement>) => void
+  onClick?: (event: React.MouseEvent<HTMLTableElement>) => void
+}
+const GridPointerContext = React.createContext<GridPointerHandlers>({})
+
+function AnchoredMonthGrid(props: React.TableHTMLAttributes<HTMLTableElement>) {
+  const { onMouseOver, onMouseLeave, onMouseMove, onPointerDown, onClick } = React.useContext(GridPointerContext)
+  return (
+    <table
+      {...props}
+      data-day-grid=""
+      onMouseOver={onMouseOver}
+      onMouseLeave={onMouseLeave}
+      onMouseMove={onMouseMove}
+      onPointerDown={onPointerDown}
+      onClick={onClick}
+    />
+  )
+}
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGrid(
   {
@@ -136,13 +208,191 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
     labels,
     showOutsideDays = true,
     numberOfMonths,
+    onDayMouseEnter,
+    onDayMouseLeave,
+    onDayFocus,
     ...props
   },
   _ref,
 ) {
+  // ── 停留日只在指標真的離開整張格陣時才清(2026-09-24;2026-09-26 把「角」也算進來)──────────────
+  //
+  // react-day-picker 只把 mouseenter / mouseleave 掛在 day button 上,而格與格之間的 4px
+  // (`border-spacing-1`)屬於 `<table>`、不屬於任何一天;圓外的四個角屬於 `<td>`、也不屬於那顆圓。
+  // 指標經過這些地方時瀏覽器必然先送一次 leave、再送 enter,消費端(DatePicker 的 previewAnchor)因此把整條區間
+  // 預覽框卸掉再補回 —— user 2026-09-23 的原話是「從某日水平移動到其隔日,藍色的區間框線都會閃動一下」。
+  //
+  // 先前的解法是給 button 一條 `before:-inset-[2px]` 的隱形帶,讓縫裡也有人收 enter。
+  // 那是**表層**解:它改的是命中幾何,而閃動的根因是「停留日被清掉」。而且它讓命中區(32)大於
+  // 懸停回饋(28 圓 + 1.5px ring),違反 hit-area-canonical「懸停回饋的形狀 ≡ 命中區」,
+  // 而日期格既不是線也不是點,吃不到那條唯一例外。
+  //
+  // 根因層的解法:**只在離開整個日曆時才清停留日** —— MUI X 把清除只掛在月份容器上
+  //(v9.14.0 `DateRangeCalendar.tsx#L481-L486` `onMouseLeave: () => setRangePreviewDay(null)`,
+  //  https://github.com/mui/mui-x/blob/c83b3dd6996f6913947b1be3e5d47655153ced60/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx#L481-L486 ),
+  // Zag(Chakra DatePicker 的底層)只掛在整張表格上(`date-picker.connect.ts#L546-L548` `onPointerLeave` →
+  //  `send({ type: "TABLE.POINTER_LEAVE" })`,
+  //  https://github.com/chakra-ui/zag/blob/46f88c089c1dbb0fc681b31172dc5eb8a07eef0d/packages/machines/date-picker/src/date-picker.connect.ts#L546-L548 )。
+  // 本檔用同樣的判準:leave 事件的 `relatedTarget` 還落在同一張 `[data-day-grid]` 的**縫或角**裡(isGapOrCorner)就
+  // **不轉發**給消費端。指標真的離開格陣時 relatedTarget 落在格陣外(或為 null = 離開視窗),照常轉發。
+  //
+  // 為什麼錨在 `data-day-grid` 而不是 `closest('table')`:標籤名是「剛好成立的觀察量」,不是要保證的性質
+  //(M37);而且顯式屬性讓閘的對照組可以只用一行 `removeAttribute` 精準弄壞這個機制。
+  // 閘:`scripts/datepicker-range-preview.mjs`「跨格不閃」(中線)+「角落路線」(偏離中線、貼邊、斜穿交會處)+ 同檔 `--selftest` 對照組。
+
+  // 記住最後一次停留的日子與它的 button:下方補送 leave、縫或角裡的點擊都用得到
+  //(消費端 DatePicker 的 onDayMouseLeave 兩個參數都沒用到,但契約要求帶,不能亂編)。
+  const lastEnterRef = React.useRef<{
+    day: Date
+    modifiers: Parameters<NonNullable<typeof onDayMouseEnter>>[1]
+    button: HTMLButtonElement | null
+  } | null>(null)
+  // 縫或角裡被吞掉的那一次 leave 還欠著沒送 = 停留日(預覽框)還掛在上一天身上。只有這種狀態才需要在離開格陣時補送,
+  // 也只有這種狀態下,縫或角裡的點擊才會交給那一天。
+  const owesLeaveRef = React.useRef(false)
+  // 這一下點擊是哪一種指標按的(pointerdown 記、click 讀完就清)。只有滑鼠才有「滑過」:觸控的預覽框是上一次點的那一天,
+  // 不是手指現在碰到的位置,所以觸控 / 觸控筆點在縫或角裡維持原樣(沒反應)。
+  const pressPointerTypeRef = React.useRef<string | null>(null)
+  // 滑鼠停留之後,鍵盤又把**看得見的**焦點移到某一天 = 最後一個輸入是鍵盤(date-picker.spec.md「滑鼠與鍵盤,最後一個輸入贏」),
+  // 框改由焦點那一天決定,滑鼠所在的縫或角就不再代表框的停留端 —— 連「滑鼠上一天剛好是框另一端」的巧合也不接點擊。
+  // 只讀焦點事件、不改任何鍵盤行為;滑鼠再進任何一天就歸零。
+  const keyboardAfterPointerRef = React.useRef(false)
+
+  // 「縫或角裡點下去會確認」的對象:指標正停在縫或角裡(leave 欠著)、上一天那顆 button 還在這張格陣裡而且可點、
+  // 它那一格正畫著框的端點 —— 也就是「框亮著,而且框的停留端就是這一天」。沒有框(兩端都空、只有單格圈)就是 null:
+  // 那時縫與角裡什麼都沒亮,點下去不該有反應(hit-area-canonical「懸停回饋的形狀 ≡ 命中區」)。
+  // 手形游標與點擊用同一支判斷,游標不會說謊。
+  const gapConfirmTarget = (grid: Element | null): HTMLButtonElement | null => {
+    if (!owesLeaveRef.current || keyboardAfterPointerRef.current || !grid) return null
+    const button = lastEnterRef.current?.button
+    if (!button || !button.isConnected || !grid.contains(button) || !button.matches(CLICKABLE_DAY)) return null
+    return drawsPreviewEnd(button.closest('td')) ? button : null
+  }
+  const syncGapCursor = (grid: Element | null) => {
+    grid?.toggleAttribute(GAP_CONFIRMS_ATTR, gapConfirmTarget(grid) !== null)
+  }
+
+  const handleDayMouseEnter = (
+    day: Date,
+    modifiers: Parameters<NonNullable<typeof onDayMouseEnter>>[1],
+    event: React.MouseEvent,
+  ) => {
+    const button = event.currentTarget instanceof HTMLButtonElement ? event.currentTarget : null
+    lastEnterRef.current = { day, modifiers, button }
+    owesLeaveRef.current = false
+    keyboardAfterPointerRef.current = false
+    syncGapCursor(button?.closest('[data-day-grid]') ?? null)
+    onDayMouseEnter?.(day, modifiers, event)
+  }
+
+  const handleDayFocus = (
+    day: Date,
+    modifiers: Parameters<NonNullable<typeof onDayFocus>>[1],
+    event: React.FocusEvent,
+  ) => {
+    if (event.currentTarget instanceof Element && event.currentTarget.matches(':focus-visible')) {
+      keyboardAfterPointerRef.current = true
+      syncGapCursor(event.currentTarget.closest('[data-day-grid]'))
+    }
+    onDayFocus?.(day, modifiers, event)
+  }
+
+  const handleDayMouseLeave =
+    onDayMouseLeave &&
+    ((day: Date, modifiers: Parameters<NonNullable<typeof onDayMouseLeave>>[1], event: React.MouseEvent) => {
+      const from = (event.currentTarget ?? event.target) as Element | null
+      const grid = from?.closest?.('[data-day-grid]') ?? null
+      if (isGapOrCorner(event.relatedTarget, grid)) {
+        owesLeaveRef.current = true
+        syncGapCursor(grid)
+        return
+      }
+      owesLeaveRef.current = false
+      syncGapCursor(grid)
+      onDayMouseLeave(day, modifiers, event)
+    })
+
+  // 補洞:指標**穿過縫或角之後停在不可點的日子**(順序不合而 disabled 的那些)、空白補位格或星期列。
+  // 那條路徑上 button 的 leave 早在縫或角裡就發生過(被上面吞掉),而 disabled 的 button 收不到滑鼠事件、
+  // 不會再有任何 day enter/leave —— 沒有這一段的話,上一天的預覽框會一直留著。
+  // 判準跟上面同一條:停在縫或角裡不動作;停在其他 td / th 上,就補送一次 leave。
+  const handleGridMouseOver =
+    onDayMouseLeave &&
+    ((event: React.MouseEvent<HTMLTableElement>) => {
+      const grid = event.currentTarget
+      const last = lastEnterRef.current
+      if (!last) return
+      const target = event.target
+      if (!(target instanceof Element)) return
+      if (target.closest(CLICKABLE_DAY)) return // 停在可點的日子 → 交給 RDP 的 enter
+      if (isGapOrCorner(target, grid)) { syncGapCursor(grid); return } // 停在縫或角裡 → 視為還在上一天
+      owesLeaveRef.current = false
+      syncGapCursor(grid)
+      onDayMouseLeave(last.day, last.modifiers, event)
+    })
+
+  // D1 補洞(2026-09-26,待辦總帳 N54「日期 D1」;date-grid.spec.md「現行機制」第 4 條):指標**從縫或角直接離開格陣**。
+  // 上面兩支都不管這條路:離開最外圈那一天時 relatedTarget 落在縫或角裡 → leave 被吞(欠著);接著指標走出 <table>,
+  // 已經沒有任何一天會再收到 leave、也沒有 td / th 會收到 mouseover —— 預覽框就一直卡在上一天(實測:從 6/13 每步 1px
+  // 往右移到浮層外 20px,停 2 秒仍是 5/4→6/13;一次跳出去則會清,因為 day button 的 leave 直接落在格陣外、照常轉發)。
+  // 本檔「只在指標真的離開整張格陣時才清」的判準本來就涵蓋這條,缺的是實作:MUI X 在月份容器掛
+  // `onMouseLeave: () => setRangePreviewDay(null)`(上方同一條連結),09-24 照 MUI 做「縫裡不清」時沒一起做這一半。
+  // 只在「欠著」時補送:一次跳出去的那條路,day button 的 leave 已經照常轉發過,不重送。
+  // 兩張月曆並排時每張各是一張格陣,兩張之間的空白 = 離開格陣(date-picker.spec.md「滑鼠離開日期格區」)。
+  const handleGridMouseLeave =
+    onDayMouseLeave &&
+    ((event: React.MouseEvent<HTMLTableElement>) => {
+      const owed = owesLeaveRef.current
+      owesLeaveRef.current = false
+      syncGapCursor(event.currentTarget)
+      if (!owed) return
+      const last = lastEnterRef.current
+      if (!last) return
+      onDayMouseLeave(last.day, last.modifiers, event)
+    })
+
+  // 手形游標跟著每一步更新:框是 React 狀態、慢一幀才畫上,指標若在框畫好之前就滑進縫或角,上面 leave 那一刻還判不到端點;
+  // 鍵盤把框移走時也一樣。每一步重算一次(只讀幾個 class,不觸發 render)。
+  const handleGridMouseMove =
+    onDayMouseLeave &&
+    ((event: React.MouseEvent<HTMLTableElement>) => syncGapCursor(event.currentTarget))
+
+  const handleGridPointerDown =
+    onDayMouseLeave &&
+    ((event: React.PointerEvent<HTMLTableElement>) => { pressPointerTypeRef.current = event.pointerType })
+
+  // ── 縫或角裡點下去 = 點停留日(2026-09-26,待辦總帳 N54 ①;date-grid.spec.md「縫與角裡的點擊」)──
+  // 預覽框亮著時,指標停在縫或角裡,框仍停在上一天(上面吞掉的 leave);此時點下去 = 點那一天的 button —— 真的去點它
+  //(`button.click()`),所以結果、焦點、關浮層都跟直接點那一天一模一樣,不另寫一份選取邏輯。
+  // 點在日子本身上由 RDP 的 handleDayClick 處理(它 stopPropagation,不會走到這裡);點在不可點的格、星期列上 → isGapOrCorner 為 false,沒反應。
+  // 世界級:React Aria 預設就是「在月曆裡、但不在按鈕上放開 = 確認正在預覽的區間」(`useRangeCalendar.ts#L23-L32` 預設 `select`:
+  // "select the currently hovered range of dates."、`#L80-L86` 的條件 `!target.closest('button, [role="button"]')`,
+  // https://github.com/adobe/react-spectrum/blob/4dd44e0f400636a87a9ad4390903e78c5ae6113c/packages/react-aria/src/calendar/useRangeCalendar.ts#L80-L86 );
+  // MUI X、Chakra 在縫裡點沒反應(R21 實測)—— 本 DS 取前者,理由是 user 的原則「滑過有變化的地方,點下去要有反應」(待辦總帳 N50)。
+  const handleGridClick =
+    onDayMouseLeave &&
+    ((event: React.MouseEvent<HTMLTableElement>) => {
+      const pointerType = pressPointerTypeRef.current
+      pressPointerTypeRef.current = null
+      if (pointerType !== 'mouse') return
+      const grid = event.currentTarget
+      if (!isGapOrCorner(event.target, grid)) return
+      gapConfirmTarget(grid)?.click()
+    })
   // Note: react-day-picker v9 DayPicker 未對外 forward ref 到單一 DOM 節點(內部有多 div),
   // 故 ref 簽名保留但不附著(符合 DS 統一 forwardRef 慣例;真要取 DOM 用 wrapper 包)。
   return (
+    <GridPointerContext.Provider
+      value={{
+        onMouseOver: handleGridMouseOver,
+        onMouseLeave: handleGridMouseLeave,
+        onMouseMove: handleGridMouseMove,
+        onPointerDown: handleGridPointerDown,
+        onClick: handleGridClick,
+      }}
+    >
+    {/* 下方 <DayPicker> 刻意不隨這層 Provider 往內縮排:整塊兩百多行只為了多包一層 context 而全部位移,
+        會讓 diff 看起來像整檔重寫。Provider 本身沒有任何視覺或結構作用,只把格陣的指標事件(見 GridPointerHandlers)遞給 AnchoredMonthGrid。 */}
     <DayPicker
       // 兩月以上**不渲染鄰月日子**(2026-09-23 user 拍板):同一天會在相鄰兩張月曆各出現一次,區間 track / 端點藍圓 /
       // 預覽框就被畫兩次(user 圖一:4/26 在四月與五月面板各一顆藍圓)。MUI X(calendars > 1 時 filler 格 opacity 0,
@@ -204,6 +454,9 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
         // 一處宣告、三種 range 狀態一起管,也少兩個要同步的地方。
         month_grid: cn(
           'border-separate border-spacing-1 -m-1',
+          // 縫或角裡點下去會確認停留日時(GAP_CONFIRMS_ATTR,由上方 syncGapCursor 掛),游標跟日期一樣是手形。
+          // td 沒有自己的 cursor,角會繼承這一條;button 自己的 pointer / disabled 的 not-allowed 不受影響。
+          'data-[gap-confirms]:cursor-pointer',
           '[&_tr>td:first-child]:before:!left-0',
           '[&_tr>td:last-child]:before:!right-0',
           // 預覽框(td ::after)在列首 / 列尾同樣不得溢出面板留白;換列處框是開口的,與 track 同款
@@ -240,12 +493,14 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
           // 就跑在那 4px 縫裡 —— 往外畫的 2px 框正好壓在框線上(user 2026-09-23:「date 的鍵盤焦點感覺要改成
           // 往內畫的那種,否則會跟區間藍框有視覺衝突」)。藍底格另走 EMPHASIS_FOCUS_RING_CLASSNAME(白線退 3px)。
           'focus-visible:focus-ring-inset',
-          // 命中區外擴 2px 補滿格間 4px 縫隙(user 2026-09-23:「從某日水平移動到其隔日,藍色的區間框線都會閃動一下」):
-          // 停留日掛在 button 的 mouseenter / mouseleave(react-day-picker 只給這一層),指標跨格時只要有一次 mousemove 落在
-          // border-spacing 的縫裡就先 leave 再 enter,整條框先卸掉一幀再補回。框的畫法早就用 −2px 跨過縫隙把線接起來,
-          // 命中幾何卻沒跟上 —— 這一條讓 hit 與 paint 同一個數字。不畫任何東西(基準圖不動);Ant 整個 td 可命中、
-          // MUI 只在離開整個日曆才清,都沒有「縫隙裡沒有任何一天」這個狀態。閘:datepicker-range-preview.mjs「跨格不閃」。
-          "before:content-[''] before:absolute before:-inset-[2px]",
+          // 命中區 = 懸停回饋形狀(上面那圈 1.5px 藍圈就畫在這顆圓上)= 可視形狀 = 這顆 28×28(lg 32)的圓,不外擴
+          //(hit-area-canonical「一-4 細則:控件的懸停回饋形狀 ≡ 命中區」;理由與實測數字寫在 date-grid.spec.md「日期格的命中區 = 可視形狀」)。
+          // 2026-09-23 這裡曾有一條 `before:-inset-[2px]`,用四邊各 2px 的**不畫任何東西**的帶去補格間 4px 縫,
+          // 解的是「跨格時區間框閃一下」。帶是對的解嗎?不是 —— 閃動的根因是**停留日在縫裡被清掉**,
+          // 幾何外擴只是讓縫裡也有人收 enter。根因層的解法寫在上方 handleDayMouseLeave(只在指標真的離開整張格陣時才清),
+          // 那正是同一條註解當時就引到的 MUI 作法。
+          // 2026-09-26「縫或角裡點下去 = 點停留日」**不是**把這個盒外擴:滑過(enter)仍只從這顆圓開始,沒有框時縫與角點了照樣沒反應;
+          // 只有框亮著、停留端就是那一天時,縫與角那一下點擊交給那一天(上方 handleGridClick)。
         ),
         // today:藍色 underline bar 貼近數字
         today: cn(
@@ -344,6 +599,8 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
         ...labels,
       }}
       components={{
+        // 月曆格陣的錨點(module 層 AnchoredMonthGrid,不可寫成 inline —— 見該處註解)
+        MonthGrid: AnchoredMonthGrid,
         // ── Prev/Next nav(canonical 2026-05-03 v9,DS 一致設計語言)──
         // User 2026-05-03 audit:「icon-only Button icon 都用 neutral-9,只有 dismiss 用 45%」
         // → chevron 不是 dismiss,**走 Button 預設 text-foreground**(neutral-9 85%),
@@ -363,7 +620,13 @@ const DateGrid = React.forwardRef<HTMLDivElement, DateGridProps>(function DateGr
         ),
       }}
       {...props}
+      // 放在 {...props} 之後:本元件對 enter/leave/focus 的記錄與過濾是格陣幾何的不變條件,不可被 consumer 的同名 prop 蓋掉
+      //(consumer 的 handler 本來就由這三支包住後轉發,語意沒有被吃掉;focus 只多記一個「鍵盤在滑鼠之後」,不改焦點行為)。
+      onDayMouseEnter={handleDayMouseEnter}
+      onDayMouseLeave={handleDayMouseLeave}
+      onDayFocus={handleDayFocus}
     />
+    </GridPointerContext.Provider>
   )
 })
 DateGrid.displayName = 'DateGrid'
@@ -385,7 +648,7 @@ export const dateGridMeta = {
   tokens: {
     bg: ['bg-disabled', 'bg-neutral-selected', 'bg-on-emphasis', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground', 'text-on-emphasis'],
-    ring: ['ring-primary', 'ring-ring'],
+    ring: ['focus-ring-inset', 'focus-ring-inset-emphasis'],
   },
 } as const