@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.85

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

@@ -211,7 +211,7 @@ export const Overview = {
               <span className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
                 style={{ borderColor: 'var(--success)', backgroundColor: 'var(--success-subtle)', color: 'var(--success)' }}>formatted text (flex-1)</span>
             </div>
-            <span className="text-[10px] text-fg-muted font-mono">Intl.DateTimeFormat · null 顯示 — (em dash)</span>
+            <span className="text-[10px] text-fg-muted font-mono">Intl.DateTimeFormat · null 顯示 - (hyphen)</span>
           </div>
         </div>
       </div>
@@ -416,8 +416,8 @@ const InspectorInner = () => {
             )}
             {!isEdit && mode === 'readonly' && !value && (
               <PropRow label="Empty">
-                <TokenValue value="--fg-muted" />
-                <span className="text-[10px] text-fg-muted ml-1">em dash —</span>
+                <TokenValue value="--foreground" />
+                <span className="text-[10px] text-fg-muted ml-1">hyphen -</span>
               </PropRow>
             )}
           </div>
@@ -750,7 +750,7 @@ export const StateBehavior = {
 
         {/* Empty value display */}
         <div className="flex flex-col gap-4">
-          <span className="text-caption font-medium text-fg-secondary">空值 — 統一 em dash（—）+ fg-muted</span>
+          <span className="text-caption font-medium text-fg-secondary">空值 — 統一半形 hyphen（-）+ foreground</span>
           <div className="flex flex-col gap-3">
             <div className="flex items-center gap-3">
               <span className="text-[11px] text-fg-muted w-20 shrink-0">readonly</span>
@@ -939,11 +939,11 @@ export const Accessibility = {
         </ul>
       </section>
       <section>
-        <h3 className="text-body font-bold mb-2">鍵盤(Radix Popover + react-day-picker v9 內建)</h3>
+        <h3 className="text-body font-bold mb-2">鍵盤</h3>
         <ul className="list-disc list-inside text-caption text-fg-secondary space-y-1">
-          <li>Trigger:<kbd>Space</kbd> / <kbd>Enter</kbd> 開 popover</li>
-          <li>Popover 開啟:<kbd>Esc</kbd> 關閉 + focus return to trigger</li>
-          <li>DateGrid:<kbd>←</kbd> <kbd>→</kbd> 切日 / <kbd>PgUp</kbd> <kbd>PgDn</kbd> 切月 / <kbd>Home</kbd> <kbd>End</kbd> 行首尾</li>
+          <li>Trigger 開 popover(<kbd>Space</kbd> / <kbd>Enter</kbd>):單一 DatePicker 的 <code>{`<div role="combobox">`}</code> 無 native Enter/Space→click,由元件<strong>自建 <code>onKeyDown</code></strong> 補開(date-picker.tsx:554;Radix PopoverTrigger 只 compose onClick)。Range 雙 trigger 為 native <code>{`<button>`}</code> onClick 開啟(同非 Radix Popover 內建)</li>
+          <li>Popover 開啟 <kbd>Esc</kbd> 關閉 + 回焦:單一 DatePicker 用 PopoverTrigger → Radix <strong>內建</strong> <code>triggerRef.focus()</code> 回焦;Range 只有 PopoverAnchor(triggerRef 恆 null,內建回焦為 no-op),改由元件<strong>自建 <code>onCloseAutoFocus</code></strong> 手動回焦 active 端 button(date-picker.tsx:1020-1026,守 WCAG 2.4.3)</li>
+          <li>DateGrid(react-day-picker v9 內建):<kbd>←</kbd> <kbd>→</kbd> 切日 / <kbd>PgUp</kbd> <kbd>PgDn</kbd> 切月 / <kbd>Home</kbd> <kbd>End</kbd> 行首尾</li>
           <li>showTime:<kbd>Tab</kbd> 從 calendar 跳到右側 time panel,各 column <kbd>↑</kbd> <kbd>↓</kbd> 切 option</li>
         </ul>
       </section>

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

@@ -67,7 +67,7 @@ export const UsageGuidance: Story = {
 
         <Rule
           title="❌ 不用其他 calendar library 平行實作"
-          note="未來若需要 Date Range / DateTime,擴充本 DateGrid(`../DateGrid/date-grid.tsx`)而非引入第二個 library——避免兩套視覺語言在同一系統並存"
+          note="Date Range / DateTime 已內建(DatePicker.Range / showTime,見下方近親規則)且都基於本 DateGrid(`../DateGrid/date-grid.tsx`);未來任何日曆類擴充也走 DateGrid,而非引入第二個 library——避免兩套視覺語言在同一系統並存"
         >
           <Label>實作細節見 Design System / Components / DatePicker / 設計規格</Label>
         </Rule>
@@ -169,8 +169,8 @@ export const FormattingRule: Story = {
       </Rule>
 
       <Rule
-        title="null 值統一顯示 em dash"
-        note="Display 模式 null / undefined 顯示 —(fg-muted),與其他 Field 元件一致"
+        title="null 值統一顯示半形連字號"
+        note="Display 模式 null / undefined 顯示半形 -(foreground,同 readonly value 色),與其他 Field 元件一致"
       >
         <DatePicker mode="readonly" value={null} />
       </Rule>

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

@@ -267,7 +267,7 @@ DateGrid cell 有 5 種語意視覺,每種用不同形狀/色彩語言避免混
 `clearable` prop 在有值時顯示 clear 按鈕（endAction）。
 
 - 只在 edit 模式顯示
-- 清除後 value 變為 `null`（Display 顯示 —）
+- 清除後 value 變為 `null`（Display 顯示半形 -,text-foreground）
 - **Dual-state sync canonical**(2026-05-03 v10):X 點擊必同時 `onChange?.('')` + `setDraft(null)`(Range 同),否則 `needConfirm=true`(showTime 預設)且 popover 開著時 `displayValue=draft` 仍顯示舊值,trigger 看起來「沒清」。X 在 trigger 上是 standard clear affordance,不走 needConfirm「等確定」語義 — 立刻 commit + 同步 draft
 
 ---
@@ -295,7 +295,7 @@ DatePicker 套 `React.forwardRef` + `displayName`;`DatePickerProps` extends `Omi
 - Trigger:`role="combobox"` + `aria-haspopup="dialog"` + `aria-expanded={open}` + 必含 accessible name(`aria-label` / 或外層 `<label>` / 或 fieldCtx label)
 - Popover content:`role="dialog"`;單一日期 popover 不重覆 `aria-label`(由 trigger 的 `role="combobox"` accessible name 標示),Range popover 加 `aria-label="日期區間選擇"`
 - DateGrid 鍵盤:Arrow keys 切日 / PageUp/Down 切月 / Home/End 行首尾(react-day-picker v9 內建)
-- Trigger 鍵盤:Space / Enter open;Esc close + focus return to trigger(Radix Popover 內建)
+- Trigger 鍵盤(Space / Enter open;Esc close + 回焦):單一 DatePicker 的 `<div role="combobox">` 無 native Enter/Space→click,由元件**自建 `onKeyDown`** 開 popover(Radix PopoverTrigger 只 compose onClick;date-picker.tsx:554),Esc 關閉後靠 PopoverTrigger 的 Radix **內建** `triggerRef.focus()` 回焦;Range 用 native `<button>` onClick 開、只掛 PopoverAnchor(triggerRef 恆 null → 內建回焦 no-op),改由**自建 `onCloseAutoFocus`** 手動回焦 active 端 button(date-picker.tsx:1020-1026,守 WCAG 2.4.3)
 - Range 雙 trigger:`activeEnd` state 指向當前編輯端,`aria-expanded` 對應只當該 trigger active 時 true
 
 ---
@@ -317,7 +317,7 @@ DatePicker 套 `React.forwardRef` + `displayName`;`DatePickerProps` extends `Omi
 - **Invalid date input**:Field validation 處理 `aria-invalid="true"` + error border + 下方 error message;DatePicker 本身不 own validation 規則。
 - **極長格式化日期**:trigger 文字單行 `truncate`(ellipsis),不換行不撐高(Display / Edit / typeable / Range 雙 input 皆同)。
 - **RTL**:未實作方向鏡像(trigger / Range 雙 input / DateGrid 皆以 LTR physical 方向設計);RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。
-- **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;DateGrid 內 cell 尺寸固定不隨 density 漂移(date grid 為密度敏感不可變區)。
+- **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;DateGrid 內 cell 尺寸 density-aware(消費 `--field-height-sm`:md=28×28 / lg=32×32,對齊 L128 + `date-grid.spec.md:120`),隨 density 縮放而非固定。
 
 ---
 

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

@@ -136,7 +136,7 @@ export const RangePicker: Story = {
     return (
       <div className="flex flex-col gap-4 max-w-md">
         <p className="text-caption text-fg-muted">
-          雙 input + 中間箭頭。點 start input 開 popover + activeEnd='start';點 end input 同理。Auto-advance:選完 start 自動切 end。clearable=true → trigger 顯示 X 清空按鈕。
+          兩個輸入框加中間箭頭:點開始欄開月曆選起日,選完自動跳到結束欄選迄日;有值時右側出現清除鈕。
         </p>
         <DatePicker.Range value={range} onChange={setRange} clearable />
         <p className="text-caption text-fg-muted">
@@ -160,7 +160,7 @@ export const WithError: Story = {
   render: () => (
     <div className="flex flex-col gap-4 max-w-xs">
       <p className="text-caption text-fg-muted">
-        error=true 時 trigger border 切 error palette,hover/focus 同步切 error-hover。
+        驗證失敗時外框轉紅色,滑過或聚焦時同步用較深的紅。
       </p>
       <DatePicker error value="2026-04-02" onChange={() => {}} />
       <DatePicker error value={null} onChange={() => {}} placeholder="必填日期" />
@@ -226,7 +226,7 @@ export const ShowTimePopoverOpen: Story = {
 /* ── OpenSnapshot:needConfirm date-only(2026-07-05 D4 修 footer gate 死路)── */
 export const NeedConfirmDateOnlyOpen: Story = {
   name: 'needConfirm:合約生效日確認',
-  parameters: { docs: { description: { story: 'date-only + needConfirm:點日期只暫存 draft(trigger 即時顯示),footer「確定」才 commit onChange——footer 渲染 gate = showTime || needConfirm(2026-07-05 D4 修 single 漏 || needConfirm 時「點了日期什麼都不會發生」的死路)。適用選錯成本高的日期(合約生效日 / 帳單結算起算日)。Visual-audit OpenSnapshot verify date-only popover 有渲 footer(此刻 / 確定)。' } } },
+  parameters: { docs: { description: { story: '需確認模式:選日期只會先暫存(輸入框即時顯示),要按下方「確定」才真正套用。適用選錯成本高的日期,例如合約生效日、帳單結算起算日。' } } },
   render: () => {
     const [effectiveDate, setEffectiveDate] = React.useState('2026-08-01')
     return (
@@ -297,8 +297,7 @@ export const ShowTimeRange: Story = {
     return (
       <div className="flex flex-col gap-4 max-w-lg">
         <p className="text-caption text-fg-muted">
-          Range + showTime:點 start input → activeEnd='start' + TimeColumns 編 start 的時間;點 end input 同理。
-          兩端都填好 + 按確定才 commit(needConfirm=true 預設)。
+          範圍 + 時間:點開始欄選起始日期與時間,點結束欄選結束的日期與時間;兩端都選好、按下方「確定」才會套用。
         </p>
         <DatePicker.Range
           showTime

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

@@ -3,14 +3,14 @@
 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 { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { Popover, PopoverTrigger, PopoverAnchor, PopoverContent } from '@/design-system/components/Popover/popover'
 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, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } 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,
@@ -53,7 +53,15 @@ 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) {
@@ -103,11 +111,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 才檢驗)。
@@ -123,6 +131,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')
@@ -290,6 +301,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) */
@@ -362,6 +376,7 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
     {
       mode,
       variant: variantProp,
+      width,
       error: errorProp = false,
       size: sizeProp,
       value,
@@ -396,7 +411,8 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
     const disabled = useResolvedFieldDisabled(disabledProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    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']
@@ -408,11 +424,14 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
     // 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])
 
@@ -464,16 +483,16 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
       if (!showDisplayEndIcon) {
         // 2026-05-14 I2 fix(spec contract (e) display 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>
+        if (!value) return <span className={cn(fieldDisplayTextClass(size), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
         return <span className={cn(fieldDisplayTextClass(size), 'truncate', className)}>{displayCommitted}</span>
       }
       return (
         <div
-          className={cn(fieldWrapperStyles({ mode: 'display', variant, size }), className)}
+          className={cn(fieldWrapperStyles({ mode: 'display', variant, width, size }), className)}
           data-field-mode="display"
         >
-          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && 'text-fg-muted')}>
-            {value ? displayCommitted : EMPTY_DISPLAY}
+          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && fieldEmptyColorClass(resolvedMode))}>
+            {value ? displayCommitted : emptyDisplay}
           </span>
           <ItemSuffix className="pointer-events-none">
             <CalendarIcon size={iconSize} className="text-fg-muted" aria-hidden />
@@ -486,7 +505,7 @@ 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>)}
@@ -494,7 +513,7 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
           <span className={cn('flex-1 min-w-0 truncate', resolvedMode === 'disabled' && 'text-fg-disabled')}>
             {value
               ? displayCommitted
-              : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+              : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             }
           </span>
           {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開) / disabled 保留(fg-disabled,對齊原生 <select disabled>);
@@ -527,18 +546,22 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
         <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}
+            // 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}
             data-field-mode="edit"
             data-error={error ? '' : undefined}
             // Radix PopoverTrigger 只 compose onClick(onOpenToggle),`<div>` trigger 無
@@ -551,7 +574,7 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
               if (e.key === 'Escape') setOpen(false)
             }}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
+              fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }),
               'text-left cursor-pointer',
               'focus-visible:outline-none',
               className,
@@ -562,8 +585,21 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
               // 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-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}
@@ -575,6 +611,7 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
                   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()}
@@ -607,12 +644,18 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
             </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
+        <PopoverContent
+          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">
+          <div className="flex flex-col flex-1 min-h-0">
             {/* Calendar 區包 overflow-y-auto:viewport 壓縮時 calendar 內滾(Material / Carbon
                 date picker idiom)。footer 永遠 in-view(SurfaceFooter shrink-0)。 */}
             <div className="flex-1 min-h-0 overflow-y-auto">
@@ -704,6 +747,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 代表尚未選。 */
@@ -728,6 +774,7 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
     {
       mode,
       variant: variantProp,
+      width,
       error: errorProp = false,
       size: sizeProp,
       value,
@@ -756,7 +803,8 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
     const disabled = useResolvedFieldDisabled(disabledProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    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']
@@ -778,12 +826,15 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
     const endBtnRef = React.useRef<HTMLButtonElement>(null)
     const hasInteractedOutsideRef = React.useRef(false)
 
-    // 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 同步。
+    // 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])
 
@@ -888,7 +939,7 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
     // mode='display'(Phase B2 2026-05-05):純內容輸出 — 無 Field wrapper / 無 Calendar icon。
     if (resolvedMode === 'display') {
       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')}>
@@ -907,7 +958,7 @@ 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}
@@ -943,7 +994,7 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             data-error={error ? '' : undefined}
             data-state={open ? 'open' : 'closed'}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', size, error }),
+              fieldWrapperStyles({ mode: 'edit', width, size, error }),
               'cursor-text',
               className,
             )}
@@ -1002,6 +1053,7 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
         <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)
@@ -1015,8 +1067,10 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             hasInteractedOutsideRef.current = false
           }}
         >
-          {/* 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">
+          {/* 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">
             <div className="flex-1 min-h-0 overflow-y-auto">
             <CalendarTimeContainer
               showTime={showTime}

package/src/components/DescriptionList/description-list.anatomy.stories.tsx

@@ -156,23 +156,23 @@ export const StateBehavior: Story = {
   render: () => (
     <div className="flex flex-col gap-10">
       <div>
-        <H3>空值呈現 — 一律用 `—` 字元(em dash)</H3>
+        <H3>空值呈現 — 一律用半形 `-` 字元(hyphen)</H3>
         <Desc>
-          DescriptionList 是唯讀資訊展示,空值不留空白(會讓使用者以為資料沒載入完)。一律用 em dash
-          (`—`)明確表達「有查過,但這個欄位目前沒值」。對齊 Atlassian / Polaris / GitHub 的資訊卡慣例。
+          DescriptionList 是唯讀資訊展示,空值不留空白(會讓使用者以為資料沒載入完)。一律用半形連字號
+          (`-`,對齊 Field `EMPTY_DISPLAY`)明確表達「有查過,但這個欄位目前沒值」;色同 value `text-foreground`。對齊 Atlassian / Polaris / GitHub 的資訊卡慣例。
         </Desc>
         <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
           <DescriptionList cols={2}>
             <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
-            <DescriptionItem label="職稱"><span className="text-fg-muted">—</span></DescriptionItem>
+            <DescriptionItem label="職稱"><span className="text-foreground">-</span></DescriptionItem>
             <DescriptionItem label="Email">user@example.com</DescriptionItem>
-            <DescriptionItem label="電話"><span className="text-fg-muted">—</span></DescriptionItem>
+            <DescriptionItem label="電話"><span className="text-foreground">-</span></DescriptionItem>
             <DescriptionItem label="團隊">Engineering</DescriptionItem>
-            <DescriptionItem label="直屬主管"><span className="text-fg-muted">—</span></DescriptionItem>
+            <DescriptionItem label="直屬主管"><span className="text-foreground">-</span></DescriptionItem>
           </DescriptionList>
         </div>
         <p className="text-footnote text-fg-muted mt-3">
-          空值不應該用「N/A」/「暫無」等字串——不同 consumer 會選不同字,破壞視覺一致。一律 em dash。
+          空值不應該用「N/A」/「暫無」等字串——不同 consumer 會選不同字,破壞視覺一致。一律半形連字號 `-`。
         </p>
       </div>
 
@@ -180,14 +180,16 @@ export const StateBehavior: Story = {
         <H3>長 value — 自然換行,撐高該 grid cell</H3>
         <Desc>
           `value` 是自然流文字,超過欄寬自然換行(CSS grid 會讓該 row 的 cell 變高,其他 cell 保持 label
-          top-aligned)。不使用 truncate——value 是被讀的內容,截斷會讓使用者漏資訊。
+          top-aligned)。不使用 truncate——value 是被讀的內容,截斷會讓使用者漏資訊。帶空白的文字(如職稱)
+          自然斷行;無空白長字串(email / URL / token)需在該 item 加 `break-all` 才會斷(此範例 Email 欄已加;
+          vertical dd 預設不強制斷字,長字串由 consumer 自加 break-all)。
         </Desc>
         <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
           <DescriptionList cols={2}>
             <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
             <DescriptionItem label="職稱">Senior Staff Principal Engineer, Design Systems</DescriptionItem>
             <DescriptionItem label="辦公地點">Taipei, Taiwan</DescriptionItem>
-            <DescriptionItem label="Email">very.long.email.address@subdomain.example.com</DescriptionItem>
+            <DescriptionItem label="Email" className="min-w-0 break-all">very.long.email.address@subdomain.example.com</DescriptionItem>
           </DescriptionList>
         </div>
       </div>
@@ -246,7 +248,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"詳 `description-list.spec.md`「無障礙」段。摘要:\n\n- 語意 HTML:外層 <dl>,每組 <dt>(term)+ <dd>(description)— screen reader 讀「term X, description Y」配對敘事\n- DT/DD 配對:DescriptionItem 強制一組配對,不分開暴露 <dt>/<dd> primitive\n- 空值:consumer 傳 — 占位(SR 讀出長破折號,比空 <dd> 明確)\n- 多欄 cols>1:視覺 grid、DOM 仍 item 順序,SR 依 DOM 敘事\n- 無互動:純唯讀呈現,無 keyboard / focus state(無 ARIA 補強需求,語意由原生 dl/dt/dd 承載)"}</p>
+      <p className="whitespace-pre-line">{"詳 `description-list.spec.md`「無障礙」段。摘要:\n\n- 語意 HTML:外層 <dl>,每組 <dt>(term)+ <dd>(description)— screen reader 讀「term X, description Y」配對敘事\n- DT/DD 配對:DescriptionItem 強制一組配對,不分開暴露 <dt>/<dd> primitive\n- 空值:consumer 傳半形 - 占位(裸 - SR 敘事弱,宜補 sr-only「無資料」,比空 <dd> 明確)\n- 多欄 cols>1:視覺 grid、DOM 仍 item 順序,SR 依 DOM 敘事\n- 無互動:純唯讀呈現,無 keyboard / focus state(無 ARIA 補強需求,語意由原生 dl/dt/dd 承載)"}</p>
     </div>
   ),
 }

package/src/components/DescriptionList/description-list.principles.stories.tsx

@@ -185,7 +185,7 @@ export const LayoutRule: Story = {
             <DescriptionItem label="職稱">Senior Design Engineer</DescriptionItem>
           </DescriptionList>
         </Frame>
-        <Label warn>↑ 窄容器配 cols=2 → email 與職稱都被壓到斷行,可讀性差</Label>
+        <Label warn>↑ 窄容器配 cols=2 → 職稱被迫斷行、email 擠壓貼邊,節奏亂、可讀性差</Label>
       </Rule>
     </div>
   ),
@@ -238,7 +238,7 @@ export const LabelAlignmentRule: Story = {
           </div>
         </Frame>
         <Label warn>
-          ↑ 這是自訂 layout 模擬 key-right-value-left → 不是 DescriptionList,也無 dl/dt/dd 語義
+          ↑ 這是自訂 layout 模擬 label 左 / value 右(key-left-value-right)→ 不是 DescriptionList,也無 dl/dt/dd 語義
         </Label>
       </Rule>
     </div>

package/src/components/DescriptionList/description-list.spec.md

@@ -173,7 +173,7 @@ consumer 要在 DL 上方加 section heading(「基本資料」/「團隊資訊
 
 - **語意 HTML**:外層 `<dl>`,每組內 `<dt>` 為 term、`<dd>` 為 description——screen reader 會讀成「term X, description Y」對話,明確表達屬性-值關係
 - **DT / DD 配對**:每個 `<dt>` 必須有對應的 `<dd>`(不可孤立),否則 SR 敘事會中斷;元件內建一組 `DescriptionItem` 強制配對,不分開暴露 `<dt>` / `<dd>` primitive
-- **空值呈現**:value 空時由 **consumer 自行傳入** `<span className="text-fg-muted">—</span>` 占位(元件不自動 normalize——`<dd>` 直接 render `children`),`text-fg-muted` 降低視覺重量;SR 會讀出「長破折號」,比空 `<dd>` 更明確
+- **空值呈現**:value 空時由 **consumer 自行傳入** `<span className="text-foreground">-</span>` 占位(半形 hyphen `-`,對齊 Field `EMPTY_DISPLAY` DS-wide 空值符號,2026-07-08 user 拍板「空值都用"-"⋯我從頭到尾哪裡有說要用全形的」;元件不自動 normalize——`<dd>` 直接 render `children`),`text-foreground`(同 value 色——「-」是不可編輯供檢視的值,非 placeholder 提示,2026-07-09 user 拍板)。**a11y known follow-up**:裸 `-` SR 敘事弱(半形連字號多被 SR 略過),宜補 `<span className="sr-only">無資料</span>` 或 `aria-label`,比空 `<dd>` 更明確
 - **多欄 `cols > 1`**:視覺為 grid 欄位,但 DOM 順序為 item 順序——SR 仍依 DOM 敘事(term1 → desc1 → term2 → desc2),不依視覺欄位;設計時確保 DOM 順序符合語意分組
 - **長值換行**:horizontal 模式的 value(`<dd>`)以 `break-all min-w-0` 處理,讓 URL / ID 等無空白長字串能斷行,避免撐破單列;vertical 模式 value 佔滿整欄寬,自然流文字依字詞換行(不強制單行 truncate,長內容保留可讀完整性)。若 vertical 模式需展示無空白長字串(連續英數 token),由 consumer 自行於該 value 加 `break-all`
 - **列表識別**:預設 `<dl>` 有部分瀏覽器 SR 不視為 list,若需明確 list 語意,DL 根容器可搭配 `role="list"` + `<div role="listitem">`(目前預設不加,保留標準 `<dl>` 語意,consumer 可自行加 role 覆蓋)
@@ -188,7 +188,7 @@ DescriptionList 是**唯讀 label / value 資料呈現**(非互動 / 非 variant
 - **無 ColorMatrix**:DL 固定 semantic token(label `text-fg-secondary` / value `text-foreground`),無自己的色彩變體,dark mode 由 semantic token 自動切換。加 color variant 不符語意(DL 是資訊展示,非狀態載體)。
 - **無 SizeMatrix**:DL 無 size prop——垂直間距隨 `layout-space` token 感知 density(見「間距」段),但 label / value typography 走 reading mode 固定 tier,不提供 sm / md / lg 變體。不同 density 由 token 自動處理,非 prop 切換。
 
-對應 anatomy story(實際 5 個,對齊 6-canonical 結構;ColorMatrix / SizeMatrix N/A):`Overview`(anatomy + typography + 間距) + `Inspector`(Controls 即時切 `cols` / `direction` / `divided`) + `ColsMatrix`(元件特有 1 / 2 / 3 欄對照) + `StateBehavior`(空值 `—` / 長值 / 多行 / ReactNode value) + `Accessibility`(`dl/dt/dd` 語意 + 無互動說明)。
+對應 anatomy story(實際 5 個,對齊 6-canonical 結構;ColorMatrix / SizeMatrix N/A):`Overview`(anatomy + typography + 間距) + `Inspector`(Controls 即時切 `cols` / `direction` / `divided`) + `ColsMatrix`(元件特有 1 / 2 / 3 欄對照) + `StateBehavior`(空值 `-` / 長值 / 多行 / ReactNode value) + `Accessibility`(`dl/dt/dd` 語意 + 無互動說明)。
 
 ---
 
@@ -196,7 +196,7 @@ DescriptionList 是**唯讀 label / value 資料呈現**(非互動 / 非 variant
 
 - **Disabled(action cell)**:DescriptionList 主體為唯讀資料呈現,本身無 disabled state。**dd 內互動內容 canonical(2026-07-04 Q9 拍板,三處立場收斂)**:操作型互動(Button / Input)**禁止**(見「禁止事項」— 需要動作 → Field read-only / inline-edit / action row / 卡片 header action);展示 / 導覽型 ReactNode(Tag / Badge / **Link**)**允許**,Link 自行 own disabled,DL 不干預。對齊 Polaris(ReactNode 型別 + 純敘述範例)/ Ant(action 放 extra 不放 dd)/ Carbon(read-only default)三家共識。
 - **Loading**:DL 非 async surface,無 loading prop。若 page-level data 載入中,consumer 應在 DL 外層用 `<Skeleton>`(每組 dt/dd 對應一條 skeleton line)取代;DL 本體不渲染 loading state。
-- **Empty(no items / empty value)**:no items → consumer 應 conditional 渲 `<Empty>` 取代 DL,不渲空 `<dl>`(SR 會讀「empty list」造成混淆);individual value 空 → consumer 應自行傳入 `—`(em dash,包 `text-fg-muted`;元件不自動 normalize,已在「無障礙」段 codify)。
+- **Empty(no items / empty value)**:no items → consumer 應 conditional 渲 `<Empty>` 取代 DL,不渲空 `<dl>`(SR 會讀「empty list」造成混淆);individual value 空 → consumer 應自行傳入半形 `-`(hyphen,對齊 Field `EMPTY_DISPLAY`,2026-07-08 user 拍板;包 `text-foreground`(色同 value,2026-07-09);元件不自動 normalize,已在「無障礙」段 codify)。
 - **長 label / 長值**:horizontal 模式 label(`dt`)`shrink-0` 不收縮、不截斷,value(`dd`)`break-all min-w-0` 斷行吸收擠壓;vertical 模式兩者佔滿欄寬自然換行。無空白長字串(URL / ID)詳「無障礙」段「長值換行」。
 - **Dark mode**:走 semantic token(`text-fg-secondary` / `text-foreground`)自動 adapt。
 - **Density**:垂直 gap 隨 `layout-space` token density-aware(見「間距」段),typography fixed reading mode tier 不變。