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

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

@@ -3,14 +3,18 @@
 import * as React from 'react'
 import { X, Calendar as CalendarIcon, ArrowRight } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, bareInputStyles, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'
 import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { Popover, PopoverTrigger, PopoverAnchor, PopoverContent } from '@/design-system/components/Popover/popover'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+import { useTruncated } from '@/design-system/hooks/use-truncated'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
 import { DateGrid } from '@/design-system/components/DateGrid/date-grid'
 import { Button } from '@/design-system/components/Button/button'
 import { SurfaceFooter } from '@/design-system/patterns/overlay-surface/overlay-surface'
-import { useFieldContext } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import {
   TimeColumns,
   isoToTimeParts,
@@ -35,15 +39,37 @@ export interface DateFormatOptions {
  * (跟 ISO date 視覺對不上,跟 sort 順序也對不上)。Ant / Material X / Apple HIG
  * 一致 year-first。Consumer 想自訂可傳 `formatOptions` + `locale`。
  */
+// 2026-07-06 D3 perf:formatOptions/locale 顯式傳入時走 Intl.DateTimeFormat(貴 constructor)。
+// DataTable date 欄轉發此 config → 每 cell × 每次表格 re-render 重建。module-level cache 重用實例
+// (無狀態可安全重用),key = locale|JSON.stringify(options)。行為 Δ=0。
+const dtfCache = new Map<string, Intl.DateTimeFormat>()
+function getDateTimeFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = locale + '|' + JSON.stringify(options)
+  let fmt = dtfCache.get(key)
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options)
+    dtfCache.set(key, fmt)
+  }
+  return fmt
+}
+
 function formatDate(
   value: string | number | Date,
   options: DateFormatOptions = {},
 ): string {
-  const date = value instanceof Date ? value : new Date(value)
+  // TZ-safe:date-only / datetime ISO string 走 isoToDate(local-time 語意,new Date(y,m-1,d))
+  // 而非 new Date('YYYY-MM-DD')(ECMAScript 以 UTC 解析 → 負時區 off-by-one,如 LA 顯前一天)。
+  // 非 ISO string(RFC 'Mar 12 2025' 等)fallback new Date();number timestamp 直接 new Date()。
+  const date =
+    value instanceof Date
+      ? value
+      : typeof value === 'string'
+        ? (isoToDate(value) ?? new Date(value))
+        : new Date(value)
   if (Number.isNaN(date.getTime())) return String(value)
   // 若 consumer 顯式傳 formatOptions / locale → 走 Intl.DateTimeFormat
   if (options.formatOptions || options.locale) {
-    return new Intl.DateTimeFormat(options.locale ?? 'en-US', options.formatOptions ?? { year: 'numeric', month: '2-digit', day: '2-digit' }).format(date)
+    return getDateTimeFormatter(options.locale ?? 'en-US', options.formatOptions ?? { year: 'numeric', month: '2-digit', day: '2-digit' }).format(date)
   }
   // 預設:YYYY/MM/DD(直接組,locale-independent + 視覺穩定)
   const y = date.getFullYear()
@@ -89,11 +115,11 @@ function isoToDate(iso: string | null | undefined): Date | undefined {
  * 或 ISO datetime(YYYY-MM-DDTHH:MM[:SS])。
  *
  * 支援 format(per Material X DatePicker / Ant DatePicker typed input idiom):
- *   - `YYYY-MM-DD` / `YYYY/MM/DD` / `YYYY.MM.DD`(ISO + 慣例 separator)
- *   - `MM/DD/YYYY` / `MM-DD-YYYY`(US locale)
- *   - `DD/MM/YYYY` / `DD-MM-YYYY`(EU locale)
+ *   - `YYYY-MM-DD` / `YYYY/MM/DD` / `YYYY.MM.DD`(ISO + 慣例 separator,明確 parse branch)
  *   - `YYYY-MM-DD HH:MM[:SS]` / `YYYY-MM-DDTHH:MM[:SS]`(datetime,showTime 才接)
- *   - native `Date.parse()` fallback(handle 'Mar 12 2025' 等英文 RFC)
+ *   - native `Date.parse()` fallback(handle 'Mar 12 2025' 等英文 RFC;US `MM/DD/YYYY` 亦由此判讀,ambiguous)
+ *   ⚠️ 不支援 EU `DD/MM/YYYY`:無專屬 parser branch;native Date.parse 把 slash 日期當 US MM/DD,
+ *      `31/12/2026`(月 > 12)直接 Invalid。v1 known-gap,需 EU 請走 formatOptions/locale 或另加 parser branch。
  *
  * Return:`{ iso, valid }`。Invalid → `valid=false` + `iso=null`,UI 顯 aria-invalid。
  * Partial input(打到一半)→ valid=false 但不顯 error UI(consumer 用 onBlur / Enter 才檢驗)。
@@ -109,6 +135,9 @@ function parseDateInput(input: string, opts: { allowTime: boolean }): { iso: str
     const [, y, m, d, hh, mm, ss] = isoDateMatch
     const date = new Date(Number(y), Number(m) - 1, Number(d), Number(hh ?? 0), Number(mm ?? 0), Number(ss ?? 0))
     if (isNaN(date.getTime()) || date.getMonth() !== Number(m) - 1) return { iso: null, valid: false }
+    // time 分量越界校驗:JS Date 會 silently normalize(25:99:99 → 隔日某時,getTime 仍 valid、
+    // getMonth 未必變),但回傳 iso 用的是原始越界字串 → 需在此擋掉 hh>23 / mm>59 / ss>59。
+    if (hh != null && (Number(hh) > 23 || Number(mm) > 59 || Number(ss ?? 0) > 59)) return { iso: null, valid: false }
     const datePart = dateToIso(date)
     if (hh != null && opts.allowTime) {
       const h2 = String(Number(hh)).padStart(2, '0')
@@ -276,6 +305,9 @@ export interface DatePickerProps
   mode?: FieldMode
   /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
   variant?: FieldVariant
+  /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮(value 寬 + slot 寬 + gap + 內 padding);
+   *  chrome 與互動不變。SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+  width?: FieldWidth
   error?: boolean
   size?: 'sm' | 'md' | 'lg'
   /** ISO date(YYYY-MM-DD)或 ISO datetime(YYYY-MM-DDTHH:MM:SS,當 showTime=true) */
@@ -300,9 +332,9 @@ export interface DatePickerProps
    */
   needConfirm?: boolean
   /**
-   * Display 是否渲 Calendar icon + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
-   * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix CalendarIcon,
+   * View 態是否渲 Calendar icon + Field naked wrapper(D-path opt-in,2026-05-08)
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
+   * 設 true 時 view 走 fieldWrapperStyles(naked variant)+ ItemSuffix CalendarIcon,
    * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -339,15 +371,18 @@ export interface DatePickerProps
 
 // Trigger uses `<div role="combobox" tabIndex={...}>` instead of `<button>` —
 // 對齊 Combobox / Select / TimePicker 同 pattern,避免 ItemInlineAction(內部 button)
-// 構成 nested-interactive(axe serious)。Radix Popover asChild 仍處理 Enter/Space 鍵盤觸發。
+// 構成 nested-interactive(axe serious)。Radix PopoverTrigger 只 compose onClick(非
+// native button → 無 Enter/Space→click),Enter/Space 開 popover 由本檔自建 onKeyDown 補
+// (對齊 select.tsx desktop trigger canonical);typeable 模式交由內層 <input> 自管鍵盤。
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
   (
     {
-      mode = 'edit',
+      mode,
       variant: variantProp,
+      width,
       error: errorProp = false,
-      size = 'md',
+      size: sizeProp,
       value,
       onChange,
       placeholder,
@@ -375,26 +410,36 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
     ref
   ) => {
     const fieldCtx = useFieldContext()
-    const error = errorProp || (fieldCtx?.invalid ?? false)
-    const disabled = disabledProp ?? fieldCtx?.disabled
-    const resolvedMode = disabled ? 'disabled' : mode
-    const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+    const size = useResolvedFieldSize(sizeProp)  // B 組 cascade fix:<Field size>/cell surface-size 對 DatePicker 生效
+    const error = useResolvedFieldInvalid(errorProp)
+    const disabled = useResolvedFieldDisabled(disabledProp)
+    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
+    const resolvedMode = useResolvedFieldMode({ mode, disabled })
+    const emptyDisplay = useFieldEmptyDisplay()
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const isEditable = resolvedMode === 'edit'
     // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
     const needConfirm = needConfirmProp ?? showTime  // datetime 預設需確認
     const [open, setOpenState] = React.useState(defaultOpen)
     const setOpen = React.useCallback((next: boolean) => { setOpenState(next); onOpenChange?.(next) }, [onOpenChange])
+    // Radix Popover 的預設 contentId 在 content 未掛載時仍會留在 trigger。
+    // DatePicker 改用穩定 ID，且只在 dialog 已掛載(open)時輸出 aria-controls，
+    // 避免 closed state 的懸空 IDREF；typeable 模式則把關聯放到真正的 combobox input。
+    const popupId = React.useId()
     const [draft, setDraft] = React.useState<string | null>(value ?? null)
     const resolvedPlaceholder = placeholder ?? (showTime ? 'YYYY/MM/DD HH:MM' : 'YYYY/MM/DD')
     // a11y:role="combobox" 必須有 accessible name(aria-label / labelledby / fieldCtx label)
     const accessibleName = ariaLabelProp ?? (ariaLabelledByProp ? undefined : (fieldCtx?.id ? undefined : resolvedPlaceholder))
 
-    // Sync draft from value ONLY on open false→true(避免 popover 開啟期間 value 改變
-    // clobber user 的編輯。Popover 關閉後下次再開時自動同步最新 value。)
+    // Sync draft from value:closed 期間恆跟隨 + open false→true 同步(避免 popover 開啟期間
+    // value 改變 clobber user 的編輯)。
+    // 2026-07-14 audit Dim 26(V4 state shadow):needConfirm trigger 讀 draft,原「只在 false→true
+    // 同步」使 controlled value 於關閉期間更新後,trigger 仍顯示舊值直到再次開啟 —— 改為
+    // 只要 open=false 就同步(與 range picker 分支 L83x 同款 canonical)。
     const lastOpenRef = React.useRef(open)
     React.useEffect(() => {
-      if (!lastOpenRef.current && open) setDraft(value ?? null)
+      if (!open || !lastOpenRef.current) setDraft(value ?? null)
       lastOpenRef.current = open
     }, [open, value])
 
@@ -438,25 +483,38 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
       }
     }, [onChange, showTime])
 
-    // mode='display'(Phase B2 2026-05-05):純內容輸出 — 對齊原 DatePickerDisplay sub-component(retired)。
+    // 截斷 tooltip(tooltip.spec.md:32 截斷 → 顯完整內容,僅實際截斷時):非 typeable edit
+    // trigger 的值 span(bareInputStyles + truncate)是截斷元素;trigger = 整個 field wrapper
+    // (interactive host,hover 直達)、量測內層值 span — useTruncated 自組 pattern
+    // (truncated-text.spec.md「trigger 需自控」指定解;範本 inline-edit.tsx:251)。
+    // typeable 走 <input>(可捲動編輯,無截斷補救需求);popover 開啟時靜默(open 是 hover 之外的 reveal 路徑)。
+    // ⚠️ hook 必在下方 view / readonly early return 之前(React #310 hook-count 鐵律,同 select.tsx 教訓)。
+    const { ref: triggerTruncationRef, isTruncated: triggerTruncated } = useTruncated<HTMLSpanElement>({
+      deps: [!typeable && displayValue ? displayLive : ''],
+    })
+    const triggerTooltipActive = !typeable && !!displayValue && triggerTruncated && !open
+
+    // mode='view'(Phase B2 2026-05-05):純內容輸出 — 對齊原 DatePickerDisplay sub-component(retired)。
     //   Default(showDisplayEndIcon=false):無 Field wrapper / 無 Calendar icon — backward compat 裸 span。
     //   Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix Calendar,
-    //   與 edit 同結構消除 cell display↔edit 像素偏移(Layer-B padding mismatch)。
-    if (resolvedMode === 'display') {
+    //   與 edit 同結構消除 cell view↔edit 像素偏移(Layer-B padding mismatch)。
+    if (resolvedMode === 'view') {
       if (!showDisplayEndIcon) {
-        // 2026-05-14 I2 fix(spec contract (e) display typography canonical):bare span 套
+        // 2026-05-14 I2 fix(spec contract (e) view typography canonical):bare span 套
         // `fieldDisplayTextClass(size)`(sm/md→text-body,lg→text-body-lg)— 對齊 Field family 統一。
-        if (!value) return <span className={cn(fieldDisplayTextClass(size), 'text-fg-muted', className)}>{EMPTY_DISPLAY}</span>
-        return <span className={cn(fieldDisplayTextClass(size), 'truncate', className)}>{displayCommitted}</span>
+        if (!value) return <span className={cn(fieldDisplayTextClass(size), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
+        // 截斷必附 tooltip(tooltip.spec.md:32)— 改消費 truncated-text primitive(同 input.tsx:196 同型修)
+        return <TruncatedText className={cn(fieldDisplayTextClass(size), className)}>{displayCommitted}</TruncatedText>
       }
       return (
         <div
-          className={cn(fieldWrapperStyles({ mode: 'display', variant, size }), className)}
-          data-field-mode="display"
+          className={cn(fieldWrapperStyles({ mode: 'view', variant, width, size }), className)}
+          data-field-mode="view"
         >
-          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && 'text-fg-muted')}>
-            {value ? displayCommitted : EMPTY_DISPLAY}
-          </span>
+          {/* 截斷必附 tooltip(tooltip.spec.md:32;data-table.spec.md:183 view 態元件自管 truncation) */}
+          <TruncatedText className={cn(bareInputStyles, 'flex-1 min-w-0', !value && fieldEmptyColorClass(resolvedMode))}>
+            {value ? displayCommitted : emptyDisplay}
+          </TruncatedText>
           <ItemSuffix className="pointer-events-none">
             <CalendarIcon size={iconSize} className="text-fg-muted" aria-hidden />
           </ItemSuffix>
@@ -468,19 +526,25 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
     if (!isEditable) {
       return (
         <div
-          className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }), className)}
+          className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, width, size }), className)}
           data-field-mode={resolvedMode}
+          aria-disabled={resolvedMode === 'disabled' ? true : undefined}
           {...(props as React.HTMLAttributes<HTMLDivElement>)}
         >
-          <span className={cn('flex-1 min-w-0', resolvedMode === 'disabled' && 'text-fg-disabled')}>
+          {/* 截斷必附 tooltip(tooltip.spec.md:32)— readonly/disabled 無編輯入口,tooltip 是唯一補救路徑(同 Range readonly 分支同型) */}
+          <TruncatedText className={cn('flex-1', resolvedMode === 'disabled' && 'text-fg-disabled')}>
             {value
               ? displayCommitted
-              : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+              : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             }
-          </span>
-          <ItemSuffix className="pointer-events-none">
-            <CalendarIcon size={iconSize} className="text-fg-muted" aria-hidden />
-          </ItemSuffix>
+          </TruncatedText>
+          {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開) / disabled 保留(fg-disabled,對齊原生 <select disabled>);
+              naked cell 依 showDisplayEndIcon=isEditable(維持 2026-05-10 cell canonical「非可編欄不顯」)*/}
+          {(variant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
+            <ItemSuffix className="pointer-events-none">
+              <CalendarIcon size={iconSize} className={resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'} aria-hidden />
+            </ItemSuffix>
+          )}
         </div>
       )
     }
@@ -501,93 +565,135 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
 
     return (
       <Popover open={open} onOpenChange={setOpen}>
-        <PopoverTrigger asChild>
-          <div
-            ref={ref}
-            id={idProp ?? fieldCtx?.id}
-            role="combobox"
-            tabIndex={disabled ? -1 : 0}
-            aria-disabled={disabled || undefined}
-            aria-label={accessibleName}
-            aria-labelledby={ariaLabelledByProp ?? fieldCtx?.labelId}
-            aria-invalid={error || undefined}
-            aria-required={fieldCtx?.required || undefined}
-            aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
-            aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
-            aria-haspopup="dialog"
-            aria-expanded={open}
-            data-field-mode="edit"
-            data-error={error ? '' : undefined}
-            className={cn(
-              fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
-              'text-left cursor-pointer',
-              'focus-visible:outline-none',
-              error && [
-                'border-error hover:border-error-hover',
-                'focus-within:border-error focus-within:hover:border-error',
-              ],
-              className,
-            )}
-            {...props}
-          >
-            {typeable ? (
-              // Issue 10 typed input(2026-05-10):real `<input>` 接 user 鍵盤打字。
-              // Click 在 input 上不 propagate 給外層 popover trigger(避免每次打字都開 popover)。
-              // Calendar icon `<ItemSuffix>` 點才開 popover(Material/Ant typed-date idiom)。
-              <input
-                type="text"
-                className={cn(bareInputStyles, 'truncate', !inputDraft && 'placeholder:text-fg-muted')}
-                value={inputDraft}
-                placeholder={resolvedPlaceholder}
-                aria-invalid={inputInvalid || error || undefined}
-                onChange={(e) => { setInputDraft(e.target.value); setInputInvalid(false) }}
-                onCompositionStart={() => { composingRef.current = true }}
-                onCompositionEnd={() => { composingRef.current = false }}
-                onKeyDown={(e) => {
-                  if (composingRef.current) return
-                  if (e.key === 'Enter') { e.preventDefault(); handleInputCommit(inputDraft) }
-                  if (e.key === 'Escape') { setInputDraft(displayLive); setInputInvalid(false); e.preventDefault() }
-                }}
-                onBlur={() => { if (!composingRef.current) handleInputCommit(inputDraft) }}
-                onClick={(e) => e.stopPropagation()}
-              />
-            ) : (
-              <span className={cn(bareInputStyles, 'truncate', !displayValue && 'text-fg-muted')}>
-                {triggerText}
-              </span>
-            )}
-            {showClear && (
-              <ItemInlineAction
-                size={size ?? 'md'}
-                action={{
-                  icon: X,
-                  label: '清除日期', // i18n-allow: DS default inline-action label
-                  // Clear = 立刻 commit + 同步 draft(對齊 user 體感 / Ant trigger X 慣例)
-                  // 不走 needConfirm「等確定」語義 — X 在 trigger 上是 standard clear affordance,
-                  // 應立刻清空。dual-state 必同步:value('') + draft(null),否則 popover 開
-                  // 著時 displayValue=draft 仍顯示舊值(see line 318: displayValue = needConfirm ? draft : value)。
-                  onClick: (e) => {
-                    e?.stopPropagation()
-                    onChange?.('')
-                    setDraft(null)
-                  },
+        {/* 截斷 tooltip:恆 wrap(truncated-text.spec.md always-wrap),未截斷或 popover 開啟時
+            open={false} 靜默。TooltipTrigger 放最內側(緊貼 div):PopoverTrigger 注入的
+            data-state(Field open 邊框樣式依賴)在 TooltipTrigger 內以 triggerProps 後 spread
+            勝出;反序會被 tooltip 的 data-state 蓋掉。 */}
+        <Tooltip open={triggerTooltipActive ? undefined : false}>
+          <PopoverTrigger asChild type={undefined}>
+            <TooltipTrigger asChild>
+              <div
+                ref={ref}
+                // a11y(2026-07-14 dim-10 修):typeable 模式 combobox 語意(name / state / 鍵盤)
+                // 集中在內層 <input>(APG editable-combobox idiom)— 外層 div 移除 role / tabIndex
+                // / aria-*,否則形成「關掉鍵盤 handler 的假 combobox tab stop」+ 內層 input 變成
+                // 第二個未命名 tab stop(雙重焦點站)。非 typeable 維持原 div-as-combobox canonical。
+                id={typeable ? undefined : (idProp ?? fieldCtx?.id)}
+                role={typeable ? undefined : 'combobox'}
+                tabIndex={typeable ? undefined : (disabled ? -1 : 0)}
+                aria-disabled={typeable ? undefined : (disabled || undefined)}
+                aria-label={typeable ? undefined : accessibleName}
+                aria-labelledby={typeable ? undefined : (ariaLabelledByProp ?? fieldCtx?.labelId)}
+                aria-invalid={typeable ? undefined : (error || undefined)}
+                aria-required={typeable ? undefined : (fieldCtx?.required || undefined)}
+                aria-describedby={typeable ? undefined : (ariaDescribedByProp ?? fieldCtx?.descriptionId)}
+                aria-errormessage={typeable ? undefined : (ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined))}
+                aria-haspopup={typeable ? undefined : 'dialog'}
+                aria-expanded={typeable ? undefined : open}
+                aria-controls={typeable || !open ? undefined : popupId}
+                data-field-mode="edit"
+                data-error={error ? '' : undefined}
+                // Radix PopoverTrigger 只 compose onClick(onOpenToggle),`<div>` trigger 無
+                // native Enter/Space→click → 自建 onKeyDown 開 popover(對齊 select.tsx desktop
+                // trigger canonical:Enter/Space → 開;Esc → 關)。typeable 模式不攔 — 內層
+                // <input> 自有 Enter/Esc 語意(commit / reset draft),Calendar icon click 開
+                // popover(Material/Ant typed-date idiom),避免 div 層 keydown 與 input 衝突。
+                onKeyDown={typeable ? undefined : (e) => {
+                  if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setOpen(true) }
+                  if (e.key === 'Escape') setOpen(false)
                 }}
-              />
-            )}
-            <ItemSuffix className="pointer-events-none">
-              <CalendarIcon size={iconSize} className="text-fg-muted" aria-hidden />
-            </ItemSuffix>
-          </div>
-        </PopoverTrigger>
-        <PopoverContent className="w-auto p-0" align="start">
-          {/* role="dialog" 為 flex item of PopoverContent(flex flex-col overflow-hidden)。
-              2026-05-06 v9.1:加 `flex flex-col flex-1 min-h-0` 完成 M25 chain — viewport
+                className={cn(
+                  fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }),
+                  'text-left cursor-pointer',
+                  'focus-visible:outline-none',
+                  className,
+                )}
+                {...props}
+              >
+                {typeable ? (
+                  // Issue 10 typed input(2026-05-10):real `<input>` 接 user 鍵盤打字。
+                  // Click 在 input 上不 propagate 給外層 popover trigger(避免每次打字都開 popover)。
+                  // Calendar icon `<ItemSuffix>` 點才開 popover(Material/Ant typed-date idiom)。
+                  // a11y(2026-07-14 dim-10 修):input 持完整 combobox 語意(id/name/state,APG
+                  // editable-combobox)— 外層 div 已讓位(見上方 role/tabIndex 註解);ArrowDown
+                  // 開 popover 補鍵盤開啟路徑(原僅 icon click 可開,鍵盤 user 無入口)。
+                  <input
+                    type="text"
+                    id={idProp ?? fieldCtx?.id}
+                    role="combobox"
+                    aria-haspopup="dialog"
+                    aria-expanded={open}
+                    aria-controls={open ? popupId : undefined}
+                    aria-label={accessibleName}
+                    aria-labelledby={ariaLabelledByProp ?? fieldCtx?.labelId}
+                    aria-required={fieldCtx?.required || undefined}
+                    aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
+                    aria-errormessage={ariaErrorMessageProp ?? ((inputInvalid || error) ? fieldCtx?.errorId : undefined)}
+                    disabled={disabled}
+                    className={cn(bareInputStyles, 'truncate', !inputDraft && 'placeholder:text-fg-muted')}
+                    value={inputDraft}
+                    placeholder={resolvedPlaceholder}
+                    aria-invalid={inputInvalid || error || undefined}
+                    onChange={(e) => { setInputDraft(e.target.value); setInputInvalid(false) }}
+                    onCompositionStart={() => { composingRef.current = true }}
+                    onCompositionEnd={() => { composingRef.current = false }}
+                    onKeyDown={(e) => {
+                      if (composingRef.current) return
+                      if (e.key === 'Enter') { e.preventDefault(); handleInputCommit(inputDraft) }
+                      if (e.key === 'Escape') { setInputDraft(displayLive); setInputInvalid(false); e.preventDefault() }
+                      if (e.key === 'ArrowDown' && !open) { e.preventDefault(); setOpen(true) }
+                    }}
+                    onBlur={() => { if (!composingRef.current) handleInputCommit(inputDraft) }}
+                    onClick={(e) => e.stopPropagation()}
+                  />
+                ) : (
+                  // ref = 截斷量測點(值 span 是截斷元素;tooltip trigger 在外層 host div,見 triggerTruncationRef 註解)
+                  <span ref={triggerTruncationRef} className={cn(bareInputStyles, 'truncate', !displayValue && 'text-fg-muted')}>
+                    {triggerText}
+                  </span>
+                )}
+                {showClear && (
+                  <ItemInlineAction
+                    size={size ?? 'md'}
+                    action={{
+                      icon: X,
+                      label: '清除日期', // i18n-allow: DS default inline-action label
+                      // Clear = 立刻 commit + 同步 draft(對齊 user 體感 / Ant trigger X 慣例)
+                      // 不走 needConfirm「等確定」語義 — X 在 trigger 上是 standard clear affordance,
+                      // 應立刻清空。dual-state 必同步:value('') + draft(null),否則 popover 開
+                      // 著時 displayValue=draft 仍顯示舊值(see line 318: displayValue = needConfirm ? draft : value)。
+                      onClick: (e) => {
+                        e?.stopPropagation()
+                        onChange?.('')
+                        setDraft(null)
+                      },
+                    }}
+                  />
+                )}
+                <ItemSuffix className="pointer-events-none">
+                  <CalendarIcon size={iconSize} className="text-fg-muted" aria-hidden />
+                </ItemSuffix>
+              </div>
+            </TooltipTrigger>
+          </PopoverTrigger>
+          <TooltipContent>{triggerTooltipActive ? displayLive : null}</TooltipContent>
+        </Tooltip>
+        <PopoverContent
+          id={popupId}
+          className="w-auto p-0"
+          align="start"
+          aria-label="日期選擇" // i18n-allow: DS default dialog label
+        >
+          {/* a11y(2026-07-14 dim-10 修):Radix PopoverContent 自帶 role="dialog"(popover.tsx:58)
+              — 內層 div 原本重複 role="dialog" 形成雙層 nested unnamed dialog,改為純 layout div,
+              accessible name 收斂到外層 PopoverContent aria-label(單一 dialog 層)。
+              2026-05-06 v9.1:`flex flex-col flex-1 min-h-0` 完成 M25 chain — viewport
               壓縮時 dialog 縮 + 內 calendar/footer 排序;原無 chain 致 calendar 末行被
               overflow-hidden 切掉、footer 推出 popover(user 報「位置改變就壞掉」根因)。 */}
-          <div role="dialog" className="flex flex-col flex-1 min-h-0">
-            {/* Calendar 區包 overflow-y-auto:viewport 壓縮時 calendar 內滾(Material / Carbon
+          <div className="flex flex-col flex-1 min-h-0">
+            {/* Calendar 區包 ScrollArea(2026-08-12 自 raw overflow-y-auto 遷移,跨 OS 一致 overlay 捲軸;M25 chain 由 flex-1 min-h-0 照傳):viewport 壓縮時 calendar 內滾(Material / Carbon
                 date picker idiom)。footer 永遠 in-view(SurfaceFooter shrink-0)。 */}
-            <div className="flex-1 min-h-0 overflow-y-auto">
+            <ScrollArea className="flex-1 min-h-0">
               <CalendarTimeContainer
                 showTime={showTime}
                 showSeconds={showSeconds}
@@ -621,11 +727,14 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
                   />
                 }
               />
-            </div>
-            {showTime && (
+            </ScrollArea>
+            {(showTime || needConfirm) && (
               // Footer:消費 SurfaceFooter SSOT(border-t + canonical px-loose py-tight padding,
               // 不再 hand-coded p-2 / Separator / ml-auto wrapper 三層垃圾)。
               // 「此刻」加 mr-auto 把後面 button 推右(對齊 Ant `marginInlineStart: auto` on OK)。
+              // 2026-07-05 D4:gate 由 `showTime` 改 `(showTime || needConfirm)` 對齊 Range(:1068)—
+              // date-only `needConfirm` 時 onSelect 只寫 draft 且不關 popover,footer「確定」是唯一
+              // commit 路徑,原 gate 漏渲 footer = draft 永遠無法 commit 的死路。
               <SurfaceFooter>
                 <Button variant="tertiary" size="sm" onClick={handleNow} className="mr-auto">此刻</Button>
                 {needConfirm ? (
@@ -673,6 +782,9 @@ export interface DatePickerRangeProps
   mode?: FieldMode
   /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
   variant?: FieldVariant
+  /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮(value 寬 + slot 寬 + gap + 內 padding);
+   *  chrome 與互動不變。SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+  width?: FieldWidth
   error?: boolean
   size?: 'sm' | 'md' | 'lg'
   /** 區間值:[start ISO, end ISO]。任一 null 代表尚未選。 */
@@ -695,10 +807,11 @@ export interface DatePickerRangeProps
 const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
   (
     {
-      mode = 'edit',
+      mode,
       variant: variantProp,
+      width,
       error: errorProp = false,
-      size = 'md',
+      size: sizeProp,
       value,
       onChange,
       placeholder,
@@ -720,28 +833,43 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
     ref,
   ) => {
     const fieldCtx = useFieldContext()
-    const error = errorProp || (fieldCtx?.invalid ?? false)
-    const disabled = disabledProp ?? fieldCtx?.disabled
-    const resolvedMode = disabled ? 'disabled' : mode
-    const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+    const size = useResolvedFieldSize(sizeProp)  // B 組 cascade fix:<Field size>/cell surface-size 對 DatePicker 生效
+    const error = useResolvedFieldInvalid(errorProp)
+    const disabled = useResolvedFieldDisabled(disabledProp)
+    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
+    const resolvedMode = useResolvedFieldMode({ mode, disabled })
+    const emptyDisplay = useFieldEmptyDisplay()
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const isEditable = resolvedMode === 'edit'
     // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
     const needConfirm = needConfirmProp ?? showTime
     const resolvedPlaceholder: [string, string] = placeholder ?? (
-      showTime ? ['Start date time', 'End date time'] : ['Start date', 'End date']
+      showTime ? ['Start date time', 'End date time'] : ['Start date', 'End date'] // i18n-allow: DS default; consumer override via placeholder prop
     )
 
     const [open, setOpen] = React.useState(false)
     const [draft, setDraft] = React.useState<[string | null, string | null]>(value ?? [null, null])
     const [activeEnd, setActiveEnd] = React.useState<'start' | 'end'>('start')
 
-    // Sync draft from value ONLY on open false→true(canonical 2026-05-02 v3):
-    // 之前用 `[value, open]` 雙 dep,popover 開啟期間 value 任何 reference 變更 → useEffect
-    // 觸發 → 直接 clobber user 的 draft 編輯。改成只在 open 從 false→true 同步。
+    // 2026-07-05 D4 focus 回復:Range 只用 PopoverAnchor(start/end button 自行 onClick 開啟),
+    // Radix triggerRef 恆 null → 內建 onCloseAutoFocus 的 triggerRef.focus() no-op 後又
+    // preventDefault 掉 FocusScope fallback → Esc/確定/選完自動關閉後焦點掉到 document.body
+    // (WCAG 2.4.3)。手動回焦 active 端 button(對齊 Ant RangePicker);outside-click 關閉
+    // 依 Radix non-modal 慣例不搶焦(hasInteractedOutside 鏡射 Radix 自家 guard)。
+    const startBtnRef = React.useRef<HTMLButtonElement>(null)
+    const endBtnRef = React.useRef<HTMLButtonElement>(null)
+    const hasInteractedOutsideRef = React.useRef(false)
+
+    // Draft sync canonical(2026-07-14 dim-26 V4 修,升級 2026-05-02 v3):
+    // - open=false(關閉期間):controlled value 變更**必**同步 draft — needConfirm 顯示層讀
+    //   draft(startIso/endIso),不同步會讓 trigger 持續顯示 stale 舊區間(外部 controlled
+    //   update 被凍結)。關閉期間無編輯進行,直接鏡射無 clobber 風險。
+    // - open=true(開啟期間):只在 false→true 轉換時 seed 一次;開啟中 value reference 變更
+    //   不覆寫,保護 user 尚未確認的 draft 編輯(原 v3 canonical 保留)。
     const lastOpenRef = React.useRef(open)
     React.useEffect(() => {
-      if (!lastOpenRef.current && open) setDraft(value ?? [null, null])
+      if (!open || !lastOpenRef.current) setDraft(value ?? [null, null])
       lastOpenRef.current = open
     }, [open, value])
 
@@ -759,6 +887,20 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
       ? formatDateOrDateTime(endIso, showTime, showSeconds, { formatOptions, locale })
       : resolvedPlaceholder[1]
 
+    // 截斷 tooltip(tooltip.spec.md:32 截斷 → 顯完整內容,僅實際截斷時):Range 兩端 edit
+    // trigger button 各自截斷、各自量測顯示 — trigger = button 本體(interactive host,hover
+    // 直達)、量測內層文字 span,useTruncated 自組 pattern(truncated-text.spec.md「trigger 需
+    // 自控」指定解;範本 inline-edit.tsx:251)。popover 開啟時靜默;hook 必在 view / readonly
+    // early return 之前(React #310 hook-count 鐵律,同 select.tsx 教訓)。
+    const { ref: startTruncationRef, isTruncated: startTruncated } = useTruncated<HTMLSpanElement>({
+      deps: [startIso ? startText : ''],
+    })
+    const { ref: endTruncationRef, isTruncated: endTruncated } = useTruncated<HTMLSpanElement>({
+      deps: [endIso ? endText : ''],
+    })
+    const startTooltipActive = !!startIso && startTruncated && !open
+    const endTooltipActive = !!endIso && endTruncated && !open
+
     const activeIso = activeEnd === 'start' ? startIso : endIso
     const activeDate = activeEnd === 'start' ? startDate : endDate
     const activeTime = isoToTimeParts(activeIso) ?? { hours: 0, minutes: 0, seconds: 0 }
@@ -843,19 +985,20 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
       return false
     }, [activeEnd, startDate, endDate])
 
-    // mode='display'(Phase B2 2026-05-05):純內容輸出 — 無 Field wrapper / 無 Calendar icon。
-    if (resolvedMode === 'display') {
+    // mode='view'(Phase B2 2026-05-05):純內容輸出 — 無 Field wrapper / 無 Calendar icon。
+    if (resolvedMode === 'view') {
       const hasAny = !!(startIso || endIso)
-      if (!hasAny) return <span className={cn('text-fg-muted', className)}>{EMPTY_DISPLAY}</span>
+      if (!hasAny) return <span className={cn(fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
       return (
         <span className={cn('inline-flex items-center min-w-0', nakedCellRowModeAlign, className)}>
-          <span className={cn('truncate', !startIso && 'text-fg-muted')}>
+          {/* 截斷必附 tooltip(tooltip.spec.md:32)— start / end 各自獨立截斷、各自量測 */}
+          <TruncatedText className={cn(!startIso && 'text-fg-muted')}>
             {startIso ? formatDateOrDateTime(startIso, showTime, showSeconds, { formatOptions, locale }) : resolvedPlaceholder[0]}
-          </span>
+          </TruncatedText>
           <ArrowRight size={iconSize} className="shrink-0 text-fg-muted mx-2" aria-hidden />
-          <span className={cn('truncate', !endIso && 'text-fg-muted')}>
+          <TruncatedText className={cn(!endIso && 'text-fg-muted')}>
             {endIso ? formatDateOrDateTime(endIso, showTime, showSeconds, { formatOptions, locale }) : resolvedPlaceholder[1]}
-          </span>
+          </TruncatedText>
         </span>
       )
     }
@@ -865,20 +1008,25 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
       return (
         <div
           ref={ref}
-          className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }), className)}
+          className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, width, size }), className)}
           data-field-mode={resolvedMode}
+          aria-disabled={resolvedMode === 'disabled' ? true : undefined}
           {...props}
         >
-          <span className={cn('flex-1 min-w-0 truncate', !startIso && 'text-fg-muted', resolvedMode === 'disabled' && 'text-fg-disabled')}>
+          {/* 截斷必附 tooltip(tooltip.spec.md:32)— readonly/disabled 無編輯入口,tooltip 是唯一補救路徑 */}
+          <TruncatedText className={cn('flex-1', !startIso && 'text-fg-muted', resolvedMode === 'disabled' && 'text-fg-disabled')}>
             {startIso ? formatDateOrDateTime(startIso, showTime, showSeconds, { formatOptions, locale }) : resolvedPlaceholder[0]}
-          </span>
-          <ArrowRight size={iconSize} className="shrink-0 text-fg-muted mx-2" aria-hidden />
-          <span className={cn('flex-1 min-w-0 truncate', !endIso && 'text-fg-muted', resolvedMode === 'disabled' && 'text-fg-disabled')}>
+          </TruncatedText>
+          <ArrowRight size={iconSize} className={cn('shrink-0 mx-2', resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted')} aria-hidden />
+          <TruncatedText className={cn('flex-1', !endIso && 'text-fg-muted', resolvedMode === 'disabled' && 'text-fg-disabled')}>
             {endIso ? formatDateOrDateTime(endIso, showTime, showSeconds, { formatOptions, locale }) : resolvedPlaceholder[1]}
-          </span>
-          <ItemSuffix className="pointer-events-none">
-            <CalendarIcon size={iconSize} className="text-fg-muted" aria-hidden />
-          </ItemSuffix>
+          </TruncatedText>
+          {/* 2026-06-26 類型身份 indicator:readonly 不顯示 / disabled 保留(fg-disabled)— 對齊單一 DatePicker(:488)+ SSOT;Range 無 naked-cell 變體故 gate = resolvedMode==='disabled' */}
+          {resolvedMode === 'disabled' && (
+            <ItemSuffix className="pointer-events-none">
+              <CalendarIcon size={iconSize} className="text-fg-disabled" aria-hidden />
+            </ItemSuffix>
+          )}
         </div>
       )
     }
@@ -897,49 +1045,60 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             data-error={error ? '' : undefined}
             data-state={open ? 'open' : 'closed'}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', size }),
+              fieldWrapperStyles({ mode: 'edit', width, size, error }),
               'cursor-text',
-              error && [
-                'border-error hover:border-error-hover',
-                'focus-within:border-error focus-within:hover:border-error',
-              ],
               className,
             )}
             {...props}
           >
-            <button
-              type="button"
-              onClick={() => openWithActive('start')}
-              data-active-end={open && activeEnd === 'start' ? 'true' : undefined}
-              aria-label={resolvedPlaceholder[0]}
-              aria-haspopup="dialog"
-              aria-expanded={open && activeEnd === 'start'}
-              className={cn(
-                bareInputStyles,
-                'truncate text-left cursor-pointer focus-visible:outline-none',
-                'data-[active-end=true]:underline decoration-primary underline-offset-4 decoration-2',
-                !startIso && 'text-fg-muted',
-              )}
-            >
-              {startText}
-            </button>
+            {/* 兩端截斷 tooltip:恆 wrap、未截斷 open={false} 靜默(truncated-text.spec.md
+                always-wrap);TooltipTrigger asChild 只合併 handler / data-state 到 button,
+                零多餘 DOM → wrapper flex 佈局不變。內層 span = 量測點(見 startTruncationRef 註解)。 */}
+            <Tooltip open={startTooltipActive ? undefined : false}>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  ref={startBtnRef}
+                  onClick={() => openWithActive('start')}
+                  data-active-end={open && activeEnd === 'start' ? 'true' : undefined}
+                  aria-label={resolvedPlaceholder[0]}
+                  aria-haspopup="dialog"
+                  aria-expanded={open && activeEnd === 'start'}
+                  className={cn(
+                    bareInputStyles,
+                    'truncate text-left cursor-pointer focus-visible:outline-none',
+                    'data-[active-end=true]:underline decoration-primary underline-offset-4 decoration-2',
+                    !startIso && 'text-fg-muted',
+                  )}
+                >
+                  <span ref={startTruncationRef} className="block truncate">{startText}</span>
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>{startTooltipActive ? startText : null}</TooltipContent>
+            </Tooltip>
             <ArrowRight size={iconSize} className="shrink-0 text-fg-muted mx-2" aria-hidden />
-            <button
-              type="button"
-              onClick={() => openWithActive('end')}
-              data-active-end={open && activeEnd === 'end' ? 'true' : undefined}
-              aria-label={resolvedPlaceholder[1]}
-              aria-haspopup="dialog"
-              aria-expanded={open && activeEnd === 'end'}
-              className={cn(
-                bareInputStyles,
-                'truncate text-left cursor-pointer focus-visible:outline-none',
-                'data-[active-end=true]:underline decoration-primary underline-offset-4 decoration-2',
-                !endIso && 'text-fg-muted',
-              )}
-            >
-              {endText}
-            </button>
+            <Tooltip open={endTooltipActive ? undefined : false}>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  ref={endBtnRef}
+                  onClick={() => openWithActive('end')}
+                  data-active-end={open && activeEnd === 'end' ? 'true' : undefined}
+                  aria-label={resolvedPlaceholder[1]}
+                  aria-haspopup="dialog"
+                  aria-expanded={open && activeEnd === 'end'}
+                  className={cn(
+                    bareInputStyles,
+                    'truncate text-left cursor-pointer focus-visible:outline-none',
+                    'data-[active-end=true]:underline decoration-primary underline-offset-4 decoration-2',
+                    !endIso && 'text-fg-muted',
+                  )}
+                >
+                  <span ref={endTruncationRef} className="block truncate">{endText}</span>
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>{endTooltipActive ? endText : null}</TooltipContent>
+            </Tooltip>
             {showClear && (
               <ItemInlineAction
                 size={size ?? 'md'}
@@ -955,10 +1114,28 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             </ItemSuffix>
           </div>
         </PopoverAnchor>
-        <PopoverContent className="w-auto p-0" align="start">
-          {/* 2026-05-06 v9.1 M25 chain — 同 single DatePicker 修法,viewport 壓縮 calendar 內滾 + footer 永遠 in-view */}
-          <div role="dialog" aria-label="日期區間選擇" className="flex flex-col flex-1 min-h-0">
-            <div className="flex-1 min-h-0 overflow-y-auto">
+        <PopoverContent
+          className="w-auto p-0"
+          align="start"
+          aria-label="日期區間選擇" // i18n-allow: DS default dialog label
+          // 2026-07-05 D4 focus 回復(機制詳 :758 comment):outside-click 標記不搶焦(鏡射
+          // Radix non-modal 自家 hasInteractedOutside guard);其餘關閉路徑(Esc / 確定 /
+          // 選完自動關)preventDefault 掉內建 triggerRef.focus()(Anchor-only 恆 null no-op)
+          // 後手動回焦 active 端 button — 對齊 Ant RangePicker 關閉後焦點回 active 端輸入格。
+          onInteractOutside={() => { hasInteractedOutsideRef.current = true }}
+          onCloseAutoFocus={(e) => {
+            e.preventDefault()
+            if (!hasInteractedOutsideRef.current) {
+              ;(activeEnd === 'start' ? startBtnRef : endBtnRef).current?.focus()
+            }
+            hasInteractedOutsideRef.current = false
+          }}
+        >
+          {/* a11y(2026-07-14 dim-10 修):accessible name 收斂到外層 PopoverContent(Radix 自帶
+              role="dialog")— 原內層第二個 role="dialog" 移除,避免 nested dialog 且外層 dialog 無名。
+              2026-05-06 v9.1 M25 chain — 同 single DatePicker 修法,viewport 壓縮 calendar 內滾 + footer 永遠 in-view */}
+          <div className="flex flex-col flex-1 min-h-0">
+            <ScrollArea className="flex-1 min-h-0">
             <CalendarTimeContainer
               showTime={showTime}
               showSeconds={showSeconds}
@@ -1008,14 +1185,19 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
                     // Cell 的 top-left + bottom-left corner triangle:pseudo 不蓋 + button 不蓋 →
                     // popover white 顯露(乾淨 breathing)
                     rangeStart: cn(
-                      '[&>button]:!bg-primary [&>button]:!text-on-emphasis [&>button]:hover:!ring-0',
+                      // 2026-08-11 修偏移:!bg-primary 連 hover 也壓死 → 端點 hover 零回饋,違反
+                      // date-grid.spec.md:119「選中日 hover 升階 primary→primary-hover」(端點可再點
+                      // 重選範圍 = 可取消家族,依 user 原則該有回饋)。補顯式 hover 升階(同 !important,
+                      // hover 變體更特定故 hover 時勝出;ring-0 壓制照舊,spec:118)。
+                      '[&>button]:!bg-primary [&>button]:hover:!bg-primary-hover [&>button]:!text-on-emphasis [&>button]:hover:!ring-0',
                       "before:content-[''] before:absolute before:inset-y-0",
                       'before:left-0 before:-right-[2px]',
                       'before:bg-neutral-selected before:pointer-events-none',
                       'before:rounded-l-full',  // ← stadium 左半圓 matches button 圓的左半弧
                     ),
                     rangeEnd: cn(
-                      '[&>button]:!bg-primary [&>button]:!text-on-emphasis [&>button]:hover:!ring-0',
+                      // 2026-08-11:同 rangeStart — 補 hover 升階(spec:119),鏡像。
+                      '[&>button]:!bg-primary [&>button]:hover:!bg-primary-hover [&>button]:!text-on-emphasis [&>button]:hover:!ring-0',
                       "before:content-[''] before:absolute before:inset-y-0",
                       'before:-left-[2px] before:right-0',
                       'before:bg-neutral-selected before:pointer-events-none',
@@ -1048,7 +1230,7 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
                 />
               }
             />
-            </div>
+            </ScrollArea>
             {(showTime || needConfirm) && (
             // Footer 消費 SurfaceFooter SSOT(border-t + canonical px-loose py-tight)。
             // showTime Range 無「此刻」(對齊 Ant `showNow={multiple ? false : showNow}`)→ 只有 確定 走 justify-end。
@@ -1099,9 +1281,11 @@ export const datePickerMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = range 帶持續選中(before:bg-neutral-selected,本檔自有);'active' 移除 — 全檔無按壓
+  // 視覺(data-active-end 是定位 attr 非按壓 token;2026-07-07 詞彙統一 DS-wide 交叉掃補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: [],
+    bg: ['bg-neutral-selected'],
     fg: ['text-fg-disabled', 'text-fg-muted'],
     ring: [],
   },