@qijenchen/design-system 0.1.0-beta.82 → 0.1.0-beta.84

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 不變。

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

@@ -21,7 +21,7 @@ type Story = StoryObj<typeof DescriptionList>
 export const UserProfile: Story = {
   name: '使用者個資',
   render: () => (
-    <div className="border border-border rounded-lg p-4 max-w-md">
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-md">
       <DescriptionList cols={1}>
         <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
         <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
@@ -37,7 +37,7 @@ export const UserProfile: Story = {
 export const ProductSpec: Story = {
   name: '產品規格',
   render: () => (
-    <div className="border border-border rounded-lg p-4 max-w-2xl">
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-2xl">
       <DescriptionList cols={2}>
         <DescriptionItem label="螢幕尺寸">6.7 吋 Super Retina XDR</DescriptionItem>
         <DescriptionItem label="處理器">A18 Pro</DescriptionItem>
@@ -54,8 +54,9 @@ export const ProductSpec: Story = {
 export const OrderSummary: Story = {
   name: '訂單明細',
   render: () => (
-    <div className="border border-border rounded-lg p-4 max-w-md">
-      <div className="text-body font-medium mb-3">訂單摘要</div>
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-md">
+      {/* title 到第一個 item 的間距 = item 之間間距(Gestalt proximity canonical,見 spec;對齊 Horizontal story)*/}
+      <div className="text-body font-medium mb-[var(--layout-space-tight)]">訂單摘要</div>
       <DescriptionList cols={1}>
         <DescriptionItem label="訂單編號">#20260418-A241</DescriptionItem>
         <DescriptionItem label="商品">Pro 年費方案 × 5 人</DescriptionItem>
@@ -75,7 +76,7 @@ export const OrderSummary: Story = {
 export const DetailPanel: Story = {
   name: '詳情面板',
   render: () => (
-    <div className="border border-border rounded-lg p-4 max-w-3xl">
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-3xl">
       <DescriptionList cols={3}>
         <DescriptionItem label="訂單狀態">已出貨</DescriptionItem>
         <DescriptionItem label="建立時間">2026-04-18 10:35</DescriptionItem>
@@ -92,7 +93,7 @@ export const DetailPanel: Story = {
 export const Horizontal: Story = {
   name: '水平佈局',
   render: () => (
-    <div className="border border-border rounded-lg p-4 max-w-md">
+    <div className="border border-border rounded-lg p-[var(--layout-space-loose)] max-w-md">
       {/* title 到第一個 item 的間距 = item 之間間距(Gestalt proximity canonical,見 spec) */}
       <div className="text-body font-medium mb-[var(--layout-space-tight)]">檔案資訊</div>
       <DescriptionList direction="horizontal">

package/src/components/Dialog/dialog.anatomy.stories.tsx

@@ -83,6 +83,7 @@ export const Overview: Story = {
               {[
                 ['autoHeight', 'boolean', 'false', 'true=隨內容 / false=填滿 viewport(body 捲動)'],
                 ['maxWidth', 'string | number', "'512px'", 'Content 最大寬度(傳 number 視為 px,亦可傳 CSS 值如 32rem),受 viewport inset 限制'],
+                ['actions(DialogHeader)', 'ReactNode', '—', 'Header 級操作 cluster(prev/next/⋮);DS 自動在 actions 與 Close X 間放 ButtonDivider(關閉誤觸保護,action-bar.spec.md:281)'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}

package/src/components/Dialog/dialog.spec.md

@@ -105,6 +105,15 @@ Modal 與 viewport 四邊保持 `--layout-space-bottom`（48px）最小間距。
 
 **Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
 
+### Header actions slot(2026-07-08)
+
+Header 級操作(記錄 prev / next 導覽、header 級溢出選單 ⋮ 等「作用於整個 dialog 內容」的操作)走 `<DialogHeader actions={…}>` slot,**不**塞 children 自刻右側 cluster。
+
+- **何時用**:操作對象是 dialog 承載的記錄本身(切換上下筆、複製連結、更多選單)。欄位級操作仍歸 body;confirm / cancel 歸 footer。
+- **分隔線由 DS 自動放**:actions 與內建 Close X 之間 DS 渲 `<ButtonDivider>` — `action-bar.spec.md:281`「最右側為關閉 / 解除按鈕 → 分隔線必須(誤觸保護)」;幾何 = ButtonDivider `mx-1` 於 `gap-2` cluster → 兩側 12px 對稱(同 spec「分隔線幾何」段)。
+- **按鈕形態**:`<Button variant="text" iconOnly …>`(text variant 自動 `data-unbounded`,不撐高 chrome header;對齊 action-bar「溢出按鈕一律最低視覺重量」)。
+- ❌ **禁**:consumer 在 children 內自刻 cluster + divider(分隔線落點歸 DS,自刻 = 漏分隔線 / 幾何 drift 根因 — 2026-07-08 WM 詳情 header 錨例)。
+
 ## Title
 
 `text-body-lg font-medium truncate`——單行截斷，不換行。