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

package/src/components/TimePicker/time-picker.tsx

@@ -3,17 +3,18 @@ import * as React from 'react'
 import { X, Clock } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
 import {
   fieldWrapperStyles,
   bareInputStyles,
-  EMPTY_DISPLAY,
   fieldDisplayTextClass,
 } from '@/design-system/components/Field/field-wrapper'
 import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
 import { Popover, PopoverTrigger, PopoverContent } from '@/design-system/components/Popover/popover'
-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 { Button } from '@/design-system/components/Button/button'
+import { SurfaceFooter } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import {
   TimeColumns,
   isoToTimeParts,
@@ -39,7 +40,8 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
  * Ant DatePicker / Polaris Picker 共識)。
  *
  * ── 實作基礎 ──
- * Trigger:`<button>` + `fieldWrapperStyles`(視覺仍是 Input wrapper,改為可點擊觸發浮層)
+ * Trigger:`<div role="combobox">` + `fieldWrapperStyles`(視覺仍是 Input wrapper,改為可點擊觸發浮層;
+ *   2026-04-25 由 `<button>` 改 div 避 nested-interactive,對齊 Select / Combobox,鍵盤靠顯式 onKeyDown)
  * Popup:`Popover`(消費 overlay-surface pattern)
  * Panel 主體:自建 column picker(三欄 scrollable list),不引入第三方 time library
  *
@@ -61,6 +63,21 @@ export interface TimeFormatOptions {
   locale?: string
 }
 
+// 2026-07-06 D3 perf:Intl.DateTimeFormat 是標準庫最貴 constructor 之一(locale data
+// resolution)。formatTime 無 cheap path,view/readonly/edit 每 render 必建;DataTable time 欄
+// 轉發 config 時每 cell × 每次表格 re-render 重建。module-level cache 重用實例(DateTimeFormat
+// 無狀態可安全重用),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 formatTime(
   iso: string,
   options: TimeFormatOptions = {},
@@ -74,7 +91,7 @@ function formatTime(
   // 借用 Date 讓 Intl.DateTimeFormat 處理 locale / 12h-24h
   const d = new Date()
   d.setHours(parts.hours, parts.minutes, parts.seconds, 0)
-  return new Intl.DateTimeFormat(locale, formatOptions).format(d)
+  return getDateTimeFormatter(locale, formatOptions).format(d)
 }
 
 // ── Disabled time callback ──────────────────────────────────────────────────
@@ -93,7 +110,10 @@ export interface TimePickerProps
   extends TimeFormatOptions,
     Omit<
       React.HTMLAttributes<HTMLDivElement>,
-      'onChange' | 'placeholder'
+      // 'defaultValue' 明確排除:本元件 controlled-only(time-picker.spec.md「Controlled-only
+      // rationale」),不支援 uncontrolled 初始值 — 若不 Omit,HTMLAttributes 會讓 defaultValue
+      // 通過型別卻靜默無效(不初始化 draft),與 spec contract 矛盾。
+      'onChange' | 'placeholder' | 'defaultValue'
     > {
   mode?: FieldMode
   /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
@@ -125,9 +145,9 @@ export interface TimePickerProps
    */
   endIcon?: LucideIcon | null
   /**
-   * Display 是否渲 endIcon + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
-   * 設 true 時 display 也走 fieldWrapperStyles(naked variant)+ ItemSuffix Clock,
+   * View 態是否渲 endIcon + Field naked wrapper(D-path opt-in,2026-05-08)
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
+   * 設 true 時 view 也走 fieldWrapperStyles(naked variant)+ ItemSuffix Clock,
    * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -141,10 +161,10 @@ export interface TimePickerProps
 const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
   (
     {
-      mode = 'edit',
+      mode,
       variant: variantProp,
       error: errorProp = false,
-      size = 'md',
+      size: sizeProp,
       value,
       onChange,
       placeholder,
@@ -169,10 +189,13 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     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
+    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']
@@ -185,7 +208,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     const setOpen = React.useCallback((next: boolean) => { setOpenState(next); onOpenChange?.(next) }, [onOpenChange])
 
     const currentParts = React.useMemo(() => isoToTimeParts(value), [value])
-    // draft 僅在 panel 開啟時用來處理 commit(OK button)的暫存
+    // draft = panel 開啟期間的暫存:供 eager commit(每次欄選 commitDraft 即 commit)+ disabledTime 重算;OK 按鈕只 setOpen(false) 關 Panel,不做 commit
     const [draft, setDraft] = React.useState<TimeParts>(
       () => currentParts ?? { hours: 0, minutes: 0, seconds: 0 },
     )
@@ -214,39 +237,51 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
 
     const handleNow = () => {
       const now = new Date()
-      // 按照 minuteStep / secondStep 對齊
-      const m = Math.round(now.getMinutes() / minuteStep) * minuteStep
-      const s = showSeconds
-        ? Math.round(now.getSeconds() / secondStep) * secondStep
-        : 0
+      // 按照 minuteStep / secondStep 對齊。
+      // 2026-07-05 邊界修正(deep-audit A.1b):Math.round 進位到 60 時,舊 `Math.min(round, 59)`
+      // 會產生 59 這種「不對齊 step、也不在 column values 內」的值(如 53 分 @ step=15 → 59)
+      // → panel 該欄失去 selected 高亮。改 clamp 到 ≤59 的最大 step 對齊值(= buildRange 產出的
+      // 最後一格,如 45),不跨小時進位 — 保持「此刻 = commit 當前時間(step 對齊)」語意
+      // (time-picker.spec.md「每次欄位選取當下即 commit」段)。
+      const alignToStep = (raw: number, step: number) => {
+        const rounded = Math.round(raw / step) * step
+        return rounded > 59 ? Math.floor(59 / step) * step : rounded
+      }
       const next: TimeParts = {
         hours: now.getHours(),
-        minutes: Math.min(m, 59),
-        seconds: Math.min(s, 59),
+        minutes: alignToStep(now.getMinutes(), minuteStep),
+        seconds: showSeconds ? alignToStep(now.getSeconds(), secondStep) : 0,
       }
       commitDraft(next)
       setOpen(false)
     }
 
-    // mode='display'(Phase B2 2026-05-05):純內容輸出 — 對齊原 TimePickerDisplay sub-component(retired)。
+    // mode='view'(Phase B2 2026-05-05):純內容輸出 — 對齊原 TimePickerDisplay sub-component(retired)。
     //   Default(showDisplayEndIcon=false):無 Field wrapper / 無 Clock icon — backward compat 裸 span。
     //   Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix Clock,
-    //   與 edit 同結構消除 cell display↔edit 像素偏移(Layer-B padding mismatch)。
-    if (resolvedMode === 'display') {
+    //   與 edit 同結構消除 cell view↔edit 像素偏移(Layer-B padding mismatch)。
+    if (resolvedMode === 'view') {
+      // 2026-07-16 DA3 fix:view 分支補 {...props} spread(aria-label 等 DOM attr 原本靜默丟失;
+      // Switch 同型 2026-07-04 已修,本檔漏 — M10 同型)。
       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)}>{formatTime(value, { formatOptions, locale })}</span>
+        if (!value) return <span {...props} ref={ref as React.Ref<HTMLSpanElement>} className={cn(fieldDisplayTextClass(size), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
+        // 截斷必附 tooltip(tooltip.spec.md:32)— 外層 span 保留 ref/props 轉發(2026-07-16 DA3),
+        // 值文字包 TruncatedText(display="block":外層 span 在 flex cell 內是 block container)
+        return <span {...props} ref={ref as React.Ref<HTMLSpanElement>} className={cn(fieldDisplayTextClass(size), 'truncate', className)}><TruncatedText display="block">{formatTime(value, { formatOptions, locale })}</TruncatedText></span>
       }
       return (
         <div
-          className={cn(fieldWrapperStyles({ mode: 'display', variant, size }), className)}
-          data-field-mode="display"
+          ref={ref}
+          {...props}
+          className={cn(fieldWrapperStyles({ mode: 'view', variant, size }), className)}
+          data-field-mode="view"
         >
-          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && 'text-fg-muted')}>
-            {value ? formatTime(value, { formatOptions, locale }) : 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 ? formatTime(value, { formatOptions, locale }) : emptyDisplay}
+          </TruncatedText>
           {EndIconCmp && (
             <ItemSuffix className="pointer-events-none">
               <EndIconCmp size={iconSize} className="text-fg-muted" aria-hidden />
@@ -260,8 +295,12 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     if (!isEditable) {
       return (
         <div
+          // 2026-07-16 DA3 fix:非-edit 分支補 ref 轉發(forwardRef<HTMLDivElement> 原本只有 edit
+          // 與 bare-span view 接 ref,readonly/disabled 及 endIcon-view div 靜默丟失 — 同 view props 漏接)。
+          ref={ref}
           className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }), className)}
           data-field-mode={resolvedMode}
+          aria-disabled={resolvedMode === 'disabled' ? true : undefined}
           {...(props as React.HTMLAttributes<HTMLDivElement>)}
         >
           <span
@@ -272,10 +311,11 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
           >
             {value
               ? formatTime(value, { formatOptions, locale })
-              : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+              : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             }
           </span>
-          {EndIconCmp && (
+          {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示 / disabled 保留(fg-disabled);naked cell 依 showDisplayEndIcon=isEditable(修 disabled cell 漏顯 bug)*/}
+          {EndIconCmp && (variant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
             <ItemSuffix className="pointer-events-none">
               <EndIconCmp
                 size={iconSize}
@@ -296,8 +336,12 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
       <Popover open={open} onOpenChange={setOpen}>
         {/* a11y(2026-04-25 nested-interactive fix):trigger 改 <div role='combobox'>
             (對齊 Select / Combobox 同 pattern),原 <button> 會與內層 ItemInlineAction
-            清除 button 構成 nested-interactive。Radix Popover 在 trigger asChild 下會
-            自動 inject keyboard handler(Enter / Space 開啟)+ 正確 aria attributes。 */}
+            清除 button 構成 nested-interactive。
+            2026-06-01 鍵盤開啟修正:Radix PopoverTrigger 只 compose onClick
+            (@radix-ui/react-popover index.js:145),不 inject 任何 onKeyDown。原生 <button>
+            靠瀏覽器在 Enter/Space 自動派發 click 才能開;但本 trigger 是 <div role=combobox>,
+            div 不會自動派發 click → 鍵盤使用者打不開 panel。故顯式加 onKeyDown
+            (對齊 select.tsx:609-619 既有 canonical + WAI-ARIA APG combobox required keys)。 */}
         <PopoverTrigger asChild>
           <div
             ref={ref}
@@ -312,23 +356,35 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
             aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
             aria-haspopup="dialog"
             aria-expanded={open}
+            onKeyDown={(e) => {
+              if (disabled) return
+              // 2026-07-14 dim-10 修:內層「清除時間」ItemInlineAction button 的 Enter/Space
+              // 會 bubble 到本 handler 被 preventDefault 吞掉(按鈕 activation 被取消、panel 反而開)。
+              // trigger 鍵盤邏輯只在事件源自 trigger div 本身時執行。
+              if (e.target !== e.currentTarget) return
+              // Enter / Space / ArrowDown / Alt+ArrowDown → 開 panel(APG combobox required + Select canonical)
+              if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
+                e.preventDefault()
+                setOpen(true)
+              }
+              // Escape → 關(Radix Content 已自帶,trigger 補位對齊 select.tsx:597)
+              if (e.key === 'Escape') setOpen(false)
+            }}
             data-field-mode="edit"
             data-error={error ? '' : undefined}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
+              fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
               '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}
           >
-            <span className={cn(bareInputStyles, 'truncate', !value && 'text-fg-muted')}>
+            {/* 截斷必附 tooltip(tooltip.spec.md:32)— trigger div 自身是 hover 目標、無疊層,
+                值 span 直接消費 TruncatedText(對照 date-picker Range edit trigger 同型) */}
+            <TruncatedText className={cn(bareInputStyles, !value && 'text-fg-muted')}>
               {displayText}
-            </span>
+            </TruncatedText>
             {showClear && (
               <ItemInlineAction
                 size={size ?? 'md'}
@@ -349,10 +405,12 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
             )}
           </div>
         </PopoverTrigger>
-        <PopoverContent className="w-auto p-0" align="start">
+        {/* a11y(2026-07-14 dim-10):Radix PopoverContent 輸出 role="dialog",無 title 需
+            accessible name(WAI-ARIA dialog required);對齊 date-picker.tsx:1040「日期區間選擇」同款 DS default。 */}
+        <PopoverContent className="w-auto p-0" align="start" aria-label="選擇時間" /* i18n-allow: DS default dialog label */>
           {/* Panel 對齊 ref/timepicker.png:2-3 個 SelectMenu 式欄位並排,分隔線分開。
               Width 依欄數由 TimeColumns 決定:2 欄 w-40 / 3 欄 w-60。
-              Height 由 wrapper 控:216px 預設(~7 items)。
+              Height 由 wrapper 控:216px 預設(扣 footer 後 list 約可見 5-6 items)。
               TimeColumns 本身 h-full,parent 控 height — 讓 DatePicker showTime / Range 可
               用 flex-row items-stretch 自動同 calendar 高。 */}
           <div className="flex flex-col h-[216px]">
@@ -365,20 +423,18 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
               disabled={disabledForColumns}
               // 2026-05-06 v9.1 M25 chain fix:TimeColumns 自然高 = 24 buttons × ~28.7px = 688px
               // 會撐破 parent h-[216px]。flex-1 + min-h-0 讓 TimeColumns 取 parent 剩餘空間
-              // (216 - footer 40 = 176px)→ ScrollArea h-full 才能正確收斂 →
+              // (216 − footer ≈53px ≈ 163px)→ ScrollArea h-full 才能正確收斂 →
               // listbox scrollIntoView 找對 nearest scrollable ancestor(內部 viewport),
               // 不會走到 document body 把 popover 內容推出畫面(user 報「hours 欄空白」根因)。
               className="flex-1 min-h-0"
             />
-            {/* Footer:Now + OK */}
-            <div
-              className={cn(
-                'flex items-center justify-between gap-2',
-                'border-t border-divider',
-                'px-[var(--layout-space-tight)] py-[var(--layout-space-tight)]',
-              )}
-            >
-              <Button variant="text" size="sm" onClick={handleNow}>
+            {/* Footer:消費 SurfaceFooter SSOT(border-t + py-tight + gap-2 + shrink-0 + justify-end)。
+                px override 回 layout-space-tight,因 TimePicker 滿欄 column 面板無 chrome-padded body
+                內縮邊可對齊(footer px = body 內縮 原則;column-selector 數字置中、零內距,
+                見 time-picker.spec.md)。此刻 mr-auto 把確定推右,視覺等同原 justify-between
+                —— 純結構消費 overlay-surface canonical(overlay-surface.spec.md:17「不自寫 padding token」),零視覺變化。 */}
+            <SurfaceFooter className="px-[var(--layout-space-tight)]">
+              <Button variant="text" size="sm" onClick={handleNow} className="mr-auto">
                 此刻
               </Button>
               <Button
@@ -388,7 +444,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
               >
                 確定
               </Button>
-            </div>
+            </SurfaceFooter>
           </div>
         </PopoverContent>
       </Popover>
@@ -408,9 +464,12 @@ export const timePickerMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // states 對齊真實視覺態:trigger 與 panel item 皆無 'active'(按下)專屬視覺態(2026-07-04 audit 對齊);
+  // 'selected' = panel item 持續選中(bg-neutral-selected,time-columns.tsx isSelected;2026-07-07 詞彙統一補列)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-primary', 'bg-transparent'],
+    // panel selected 走 bg-neutral-selected(time-columns.tsx isSelected;spec「欄內 item 狀態」),非 bg-primary。
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],
     ring: [],
   },

package/src/components/Toast/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './toast'