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

package/src/components/TimePicker/time-picker.spec.md

@@ -11,8 +11,6 @@ benchmark:
   - MUI X Date Pickers (Time): github.com/mui/mui-x/tree/master/packages/x-date-pickers
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — all claims have inline URL or per-claim @benchmark-unverified retract. M22 inline cites added 2026-05-03 v11. -->
-
 # TimePicker 設計原則
 
 ## 定位
@@ -22,24 +20,35 @@ TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Desi
 **Layout Family**:**Family 4(Field control layout)**,視覺對齊 Family 1(Menu item)。見 `patterns/element-anatomy/element-anatomy.spec.md`「Field Composition(不在 family 但相關)」段。
 
 **實作基礎**:
-- **Trigger**:`<button>` + `fieldWrapperStyles`(視覺 = Input wrapper,但 role 是 button 開 popover)
+- **Trigger**:`<div role="combobox">` + `fieldWrapperStyles`(視覺 = Input wrapper;**不用 `<button>`** —— 避免內層 `ItemInlineAction` 清除 button 構成 nested-interactive,對齊 Select / Combobox 同 pattern。Radix PopoverTrigger 在 `asChild` 下只 compose onClick 與 aria / data attributes,**不** inject 任何 onKeyDown——Enter / Space / ↓ 鍵盤開啟由 trigger 顯式 `onKeyDown` 實作,對齊 select.tsx canonical + APG combobox required keys)
 - **Popup**:`<Popover>`(消費 `patterns/overlay-surface/` 的 surface chrome)
 - **Panel 主體**:**自建** 2-3 欄 column picker(時 / 分 / 秒),**不引入第三方 time library**——自建讓 DS own 視覺與交互(對齊 Ant Design 的 Panel 結構 — [react-component/picker TimePanel](https://github.com/react-component/picker/tree/master/src/PickerPanel/TimePanel) + 本 DS token)
-- **世界級對照**:Ant Design TimePicker([source](https://github.com/react-component/picker/tree/master/src/PickerPanel/TimePanel))/ Material DateTimePicker([mui-x DigitalClock](https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/DigitalClock/DigitalClock.tsx))/ iOS native time picker `@benchmark-unverified`(closed-source)——共同行為:column scroll selector、minuteStep 支援、Now / OK footer、clearable
+- **交互契約**:column scroll selector、minuteStep、Now / OK footer 與 clearable 共同構成這個元件的最小完整流程
 
 ---
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+本元件刻意採 **controlled-only** 模式:`value` + `onChange` 成對傳入(型別宣告 optional、無 runtime 強制,對齊 DatePicker / SelectMenu 同慣例),不支援 `defaultValue` uncontrolled fallback。
 
 **為什麼**:
-- 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
+- 內部狀態(panel `open` + 暫存 `draft` 值)若要跟外部 `value` 雙向 sync 會產生 race condition
 - Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
 - 世界級對照:Ant Design DatePicker([source](https://github.com/react-component/picker/blob/master/src/PickerInput/SinglePicker.tsx)) / Material MUI Select([source](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Select/Select.js))皆支援 dual-mode;我們選 controlled-only 對齊狀態一致性優先
 
 **若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
 
+### Open-pair rationale:defaultOpen + onOpenChange,無 controlled open(2026-06-12 deep-audit R2 補)
+
+open 軸同樣只開最小 API — **uncontrolled-only**:`defaultOpen`(初始開)+ `onOpenChange`(通知 callback),無 controlled `open` prop。
+
+**為什麼**:
+- 已知需求只要「初始開 + 知道何時關」:(1) 視覺快照 — Storybook OpenSnapshot / visual-audit(M15)`defaultOpen` 一行達成;(2) DataTable cell-as-input(`DataTable/cell-registry.tsx`)— `defaultOpen` 1-step 開 panel,`onOpenChange(false)` → cell exit edit mode
+- open 跟 panel draft 生命週期綁死:開啟時以當前 value 重新初始化 draft(time-picker.tsx open effect)/ Now → commit + 關 / OK → 關 / Esc dismiss,全走 `setOpen` wrapper 統一 fire `onOpenChange`。controlled `open` 等於把 draft 初始化 + 關閉時機切一半給 consumer,漏接 → draft 殘留 / cell 卡 edit
+- 世界級對照:Radix Popover([radix-ui.com/primitives/docs/components/popover](https://www.radix-ui.com/primitives/docs/components/popover))/ Ant Select([ant.design/components/select](https://ant.design/components/select))/ MUI Select([mui.com/material-ui/api/select](https://mui.com/material-ui/api/select/))皆提供 controlled `open` — 它們是泛用 primitive / library,必須支援任意 orchestration;本 DS 是 opinionated form control,無真實 consumer 需求前不為「可能性」付受控成本(Rule-of-3)
+
+**若未來要開 controlled open**:同 value 軸引入 `useControllableState` helper + 測 controlled↔uncontrolled switch,屬 major API 擴充,非本 session scope。
+
 ---
 
 ## 何時用
@@ -55,7 +64,7 @@ TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Desi
 
 | 場景 | 改用 | 原因 |
 |------|------|------|
-| 同時需要日期 + 時間 | **DatePicker with time** 或 `<DatePicker> + <TimePicker>` 並列 | TimePicker 本身不帶日期;需配 DatePicker 組合 |
+| 同時需要日期 + 時間 | **`<DatePicker showTime>`**(canonical 2026-05-02,Ant idiom;非獨立並列組合,見 date-picker.spec「showTime」段) | TimePicker 本身不帶日期;datetime 是單一 picker 職責 |
 | 時間範圍(from-to) | **兩個 `<TimePicker>`** 並列 + 之間 `<ArrowRight>` | TimePicker **MVP 不支援 range**,用組合達成(對齊 Ant `TimePicker.RangePicker` 的 composition 思路 — [source](https://github.com/react-component/picker/blob/master/src/PickerInput/RangePicker.tsx)) |
 | 純文字時間輸入(秒有意義的科學測量) | `<Input>` + mask / regex validation | TimePicker 的 column UX 不適合大量精確輸入 |
 | 倒數計時 / 相對時間 | 自行渲染 `MM:SS` 倒數 | TimePicker 是 wall-clock time,不是 duration |
@@ -69,7 +78,7 @@ TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Desi
   value={time}                   // ISO "HH:mm" or "HH:mm:ss" | null
   onChange={setTime}
   size="sm" | "md" | "lg"        // 對齊 field-height family,default md
-  mode="edit" | "readonly" | "disabled"
+  mode="edit" | "view" | "readonly" | "disabled"   // view = 純展示值(DataTable cell 用)
   disabled={boolean}
   error={boolean}
   clearable={boolean}
@@ -94,7 +103,7 @@ TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Desi
 
 ### 顯示格式化
 
-**Display 走 `Intl.DateTimeFormat`**(跨 locale 統一、12h/24h 支援)。`formatOptions` 透傳進去。
+**View 走 `Intl.DateTimeFormat`**(跨 locale 統一、12h/24h 支援)。`formatOptions` 透傳進去。
 
 ---
 
@@ -115,16 +124,14 @@ TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Desi
 Panel 展開後的 column picker 結構:
 
 ```
-┌─────────────────────────────────┐
-│  時    分    [秒]                │  ← header(有 label 時顯示)
-├─────┬─────┬──────────────────┤
+┌─────┬─────┬──────────────────┐
 │  09 │  00 │                   │
-│  10 │  15 │  每欄 scrollable   │  ← body
-│▓11▓│▓30▓│  選中項藍底白字     │
+│  10 │  15 │  每欄 scrollable   │  ← body(無可見「時 / 分 / 秒」標題列;
+│▓11▓│▓30▓│  選中項灰底         │     label 僅作 listbox aria-label,不渲染)
 │  12 │  45 │                   │
 │  13 │     │                   │
 ├─────┴─────┴──────────────────┤
-│            [Now]    [OK]     │  ← footer(選填)
+│            [此刻]    [確定]    │  ← footer(固定)
 └───────────────────────────────┘
 ```
 
@@ -134,45 +141,35 @@ Panel 展開後的 column picker 結構:
 |-------|------|-------|
 | 正常 | 置中文字 | `text-foreground` |
 | hover | 灰底 | `hover:bg-neutral-hover` |
-| **selected** | **灰底**(非藍底) | `bg-neutral-selected text-foreground rounded-md` |
+| **selected** | **灰底**(非藍底,滿欄矩形填色 `w-full`,無圓角) | `bg-neutral-selected text-foreground` |
 | disabled(`disabledTime`) | 灰字 | `text-fg-disabled cursor-not-allowed` |
 
 **為什麼 selected 走 neutral 非 primary**(2026-04-21 canonical):TimePicker panel 是「**列表選中**」語意 — user 在時 / 分 / 秒選項間切換,跟 `SelectMenu` / `MenuItem` 同流派(單選 list → `bg-neutral-selected`)。**DatePicker date cell selected 用 `bg-primary`** 是因為那是「**最終選定日期**」的強 affordance(確定性)。兩者不同語意,不互調。
 
-對齊 SelectMenu / MenuItem 的好處:consumer 看 TimePicker 面板知道這是「選一個項目」,跟 Select 下拉選單認知一致(Ant Design TimePicker panel 同樣採 neutral selected — [picker style source](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts) `@benchmark-unverified` exact line)。
+對齊 SelectMenu / MenuItem 的好處:consumer 看 TimePicker 面板便知道這是「選一個項目」，跟 Select 下拉選單使用同一套 selection 語言。
 
 ### Spacing + 結構(2026-04-21 canonical,2026-04-21 window width 修正)
 
-- Panel 內 padding = `--layout-space-tight`(12px @ md density)
-- **三欄(時 / 分 / 秒)各欄 `w-12`(48px)固定,非 flex-1 均分**(對齊 Ant / Google 世界級慣例 `@benchmark-unverified` visual measurement)。**分隔「:」移除**(AR8 canonical — Ant TimePicker / Google Calendar 同樣不加 `:`,靠 column 間距自明 `@benchmark-unverified` visual)
+- Footer 內 padding = `--layout-space-tight`(12px @ md density);**消費 `<SurfaceFooter>` SSOT**(border-t + py + gap + justify + shrink-0),px 經 `className` override 回 tight——因滿欄 column 面板無 chrome-padded body 內縮邊可對齊(見 `overlay-surface.spec.md` SurfaceFooter「footer px = body 內縮原則」例外);此刻按鈕 `mr-auto` 推右,視覺等同原 justify-between(零視覺變化)
+- **Panel 容器固定寬:2 欄(時 / 分)`w-40`(160px)/ 3 欄(時 / 分 / 秒)`w-60`(240px)**;**每欄 `flex-1 h-full` 等分**容器寬(非固定 `w-12`)。**分隔「:」移除**(AR8 canonical，以 column 間距表達欄位分界)
 - Scrollable list 用 **`<ScrollArea>`**(對齊 DS 跨 OS 一致 overlay 捲軸 canonical);不 raw `overflow-y-auto`
-- **Scroll-into-view**:mount = `behavior:'auto'`(避閃爍),後續 `value` 變更 = `behavior:'smooth'`(對齊 iOS / Material / Ant timepicker idiom)。SSOT 在 `time-columns.tsx` `TimeColumn` useEffect
+- **Scroll-into-view**:mount = `behavior:'auto'`(避閃爍),後續 `value` 變更 = `behavior:'smooth'`(讓選取移動保持可追蹤)。SSOT 在 `time-columns.tsx` `TimeColumn` useEffect
 - 每 item **`h-field-sm`(28px @ md / 32px @ lg)對齊 DatePicker date cell**(跨 picker 視覺一致)
-- List 高 `h-[216px]`(容納約 7 個 item 置中)
-
-### Panel 寬度 content-driven(AR42 修正,2026-04-21)
+- Panel 容器高 `h-[216px]`(含 footer);TimeColumns 為 `flex-1 min-h-0`,實際可捲動 list 高 = 216 − footer 實高(Button sm 28px + `py-tight` 12px×2 + border-t 1px ≈ 53px @ md)≈ **~163px**(約可見 5-6 個 item)
 
-**每欄 w-12(48px)固定,Panel 寬度隨 showSeconds 動態變化**:
+### Panel 寬度(固定容器寬,隨 showSeconds 切換)
 
-| 模式 | 欄數 | Panel 寬(含 padding + gap) |
-|------|------|---------------------------|
-| HH:mm(預設)| 2 欄 | `2 × 48 + gap-1 × 1 + px × 2` ≈ 48×2 + 4 + 24 = **124px** |
-| HH:mm:ss(showSeconds=true)| 3 欄 | `3 × 48 + gap-1 × 2 + px × 2` ≈ 48×3 + 8 + 24 = **176px** |
+**Panel 容器固定寬度,欄位 `flex-1` 等分該寬度**(`TimeColumns` 的 `widthClass = showSeconds ? 'w-60' : 'w-40'`):
 
-**世界級對照**:
-- Ant Design TimePicker:每欄 ~56px,3 欄 ~170px(Panel 含 footer)`@benchmark-unverified` visual measurement(visual sampling,not source-citable as exact pixel)
-- Google Calendar Quick-Time:~150-170px
-- Material 3 TimePicker dial:~180px(含 AM/PM)`@benchmark-unverified` visual measurement
-- 本 DS:每欄 48px,2 欄 ~124px / 3 欄 ~176px,**符合世界級緊湊節奏**
+| 模式 | 欄數 | TimeColumns 容器寬 | 每欄寬(`flex-1` 等分) |
+|------|------|------|------|
+| HH:mm(預設)| 2 欄 | `w-40` = **160px** | ~80px |
+| HH:mm:ss(showSeconds=true)| 3 欄 | `w-60` = **240px** | ~80px |
 
-**為什麼每欄 48px 不 56 / 64**:
-- 48px = `h-field-sm × 1.7`,兩位數字 `tabular-nums`(約 16-18px 寬)+ 左右呼吸 ~15px。不貼邊也不浪費
-- 56-64px 寬度逼近 Select menu 語境;picker column 超過此寬度會模糊 picker vs menu 的視覺界線
-- Ant 56 / 本 DS 48 差異在:Ant 的 item 有圓角 button 佔寬,本 DS 走 `rounded-md` `text-center`,視覺 48px 不擠 `@benchmark-unverified` visual measurement
+**寬度 rationale**:本 DS 以每欄約 80px 保留雙位數字的穩定 hit area；2 欄 160px、3 欄 240px，欄數變化不壓縮單欄可操作面積。
 
 **showSeconds 切換時 panel 寬度會跟著變**(刻意):
-- 對齊 Ant 慣例(content-driven)
-- showSeconds=false 的 panel 本就應該更窄,兩欄 + 大量留白會顯得 panel 空洞
+- showSeconds=false 的 panel 本就應該更窄(`w-40`),兩欄 + 大量留白會顯得 panel 空洞
 - Popover position 受 side / align / collisionPadding 控制,寬度變化只移動 panel 位置不影響 anchor 關係
 
 ---
@@ -182,11 +179,11 @@ Panel 展開後的 column picker 結構:
 | 按鍵 | 行為 |
 |------|------|
 | 點 trigger | 開 Panel |
+| Enter / Space / ↓(focus 在 trigger)| 開 Panel(APG combobox required keys,trigger 顯式 `onKeyDown`)|
 | Esc | 關 Panel(不確認) |
 | Tab | 焦點在 column 間移動 |
-| ↑ / ↓ | 欄內上下選 |
-| Enter | 確認當前 highlight |
-| 直接鍵入數字(optional) | 跳到對應值 |
+| ↑ / ↓ | 欄內上下選(每次移動即 commit,無 highlight 中間態) |
+| Home / End | 跳該欄首 / 尾 enabled 值 |
 
 ---
 
@@ -196,10 +193,10 @@ Panel 展開後的 column picker 結構:
 詳見 `../Field/field-controls.spec.md`(共用規則)。
 
 ### Empty 值
-`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。Display 模式空值顯示 `—`(對齊 `EMPTY_DISPLAY`)。
+`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。View 模式空值顯示半形 `-`(對齊 `EMPTY_DISPLAY`,text-foreground)。
 
 ### 驗證時機
-- Panel 關閉(OK 或 outside click)時 commit value 給 `onChange`
+- **每次欄位選取(時 / 分 / 秒任一改變)當下即 commit value 給 `onChange`**(eager commit,非 OK 才送)。OK 鈕(「確定」)只負責關閉 Panel,不另行 commit。`此刻` 按鈕則一次 commit 當前時間並關閉 Panel
 - `disabledTime` 在 Panel 開啟時套用(selected hour 改變會重算 disabledMinutes)
 - 若 consumer 需要 form-level 必填驗證 → 外層 `<Field>` + `<FieldError>` 承擔(不是 TimePicker 本體責任)
 
@@ -210,14 +207,15 @@ N/A — TimePicker 是純同步輸入,無 async 狀態。
 
 ## A11y 預設
 
-- trigger 需 `aria-label`(若沒外部 `<label>`)
-- Panel 開啟時 trigger `aria-expanded="true"`
-- 每欄 `role="listbox"`,item `role="option" aria-selected`
-- Screen reader 讀出「時間選擇器,當前 9 時 30 分」
+- trigger `role="combobox"`,在 `<Field>` 內時以 `aria-labelledby` 指向 field label(`fieldCtx.labelId`)
+- **Standalone(無 `<Field>` 包裹)accessible name**:trigger 無預設 `aria-label`,`<Field>` 外使用時 consumer **必須**自帶 `aria-label` 或 `aria-labelledby`,否則 `role="combobox"` 成為無名稱控件(對齊 Select / Combobox / DatePicker 同家族 standalone 約定)。DS 不為 trigger 塞泛用 fallback name(如「時間」),避免遮蔽 consumer 的具體語意(如「會議開始時間」);Field 內則自動接線無需 consumer 介入。Panel 本體(Popover dialog)另有本 DS 提供的 `aria-label="選擇時間"`,與 trigger name 職責分離
+- Panel 開啟時 trigger `aria-expanded="true"` + `aria-haspopup="dialog"`
+- 每欄 `role="listbox"`(`aria-label` 為 `hours` / `minutes` / `seconds`),item `role="option" aria-selected`
+- Screen reader 經 trigger 的 label + 內層可見值文字朗讀目前選取時間(目前值以可見 `<span>` 呈現,無額外 `aria-valuetext`)
 
 ---
 
-## Dismiss / Clear 規則(對齊 CLAUDE.md canonical)
+## Dismiss / Clear 規則(對齊 `packages/design-system/ds-canonical/references/props-naming.md` callback canonical)
 
 - **關閉 Panel** → `onOpenChange(false)`(Popover 內建)/ outside click / Esc —— 這是 **overlay close**,不是 `onClear`
 - **清空值** → `clearable={true}` 在 trigger 的 endAction slot 顯示 `X` 透過 `ItemInlineActionButton`(canonical),點擊 `onChange("")`
@@ -246,10 +244,17 @@ TimePicker 視覺分兩層,各自繼承不同 SSOT:
 
 trigger 的互動狀態(focus / invalid / disabled / readonly)完全繼承 `../Field/field-controls.spec.md` SSOT「Mode 狀態」;panel 內 column item 的 hover / selected / disabled 走 `patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」。TimePicker 層級無自有 state 行為,panel 開 / 關由 Popover primitive 處理。重寫 StateBehavior = 與兩個 SSOT 同時漂移。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(兩層整合展示) + `SizeMatrix` + 元件特有 `ModeMatrix` / `PrecisionMatrix`。Field-level state 見 Input `StateBehavior` + field-controls.spec.md;panel item-level state 見 SelectMenu / MenuItem 的對應 story。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(兩層整合展示) + `SizeMatrix` + `Accessibility` + 元件特有 `ModeMatrix` / `PrecisionMatrix`。Field-level state 見 Input `StateBehavior` + field-controls.spec.md;panel item-level state 見 SelectMenu / MenuItem 的對應 story。
 
 ---
 
+## 常見誤解
+
+- 「OK(確定)鈕才 commit value」→ 錯;每次欄位選取**當下即 commit**(eager commit),OK 只關 Panel(見「驗證時機」)
+- 「時間範圍要等內建 Range」→ 用兩個 `<TimePicker>` 並列組合即可(見「為何無 Range(MVP)」)
+- 「value 可傳 Date object」→ 不可;家族統一 ISO time string(見「Value 格式」)
+- 「selected 該用藍底」→ panel 是「列表選中」語意走 `bg-neutral-selected`,藍底是 DatePicker date cell 的「最終選定」語意(見「欄內 item 狀態」)
+
 ## 禁止事項
 
 - ❌ 不要在 TimePicker 內部直接顯示日期——那是 DatePicker 的語義
@@ -262,10 +267,11 @@ trigger 的互動狀態(focus / invalid / disabled / readonly)完全繼承 `../F
 
 ## 邊界案例
 
-- **Disabled**:Field SSOT own;trigger 自動 disabled(`text-fg-disabled` + 不開 picker),Display mode + disabled 維持時間格式但 token 切 disabled。
+- **Disabled**:Field SSOT own;trigger 自動 disabled(`text-fg-disabled` + 不開 picker)。顯式 `mode` 優先於 `disabled` prop(`useResolvedFieldMode` prop > disabled),view 分支無 disabled token 邏輯——要 disabled 視覺走 `mode="disabled"`(readonly/disabled 分支 `text-fg-disabled`,時間格式維持)。
 - **Loading**:TimePicker 為 sync UI(time math 在 client),無 loading state。極端 case(後端 disabled-times list)應由 consumer 先 disable trigger 直到 fetch 完成。
-- **Empty(no value)**:`value=null` 為合法 initial state,trigger 顯 placeholder(預設「選擇時間」);`null` + Display mode 顯 `—`(em dash + `text-fg-muted`)對齊 Input display empty 慣例。
+- **Empty(no value)**:`value=null` 為合法 initial state,trigger 顯 placeholder;**未傳 `placeholder` 時 default = 格式遮罩**(`HH:MM`,showSeconds=true 時 `HH:MM:SS`),非固定文案。`null` + view mode 顯半形 `-`(hyphen + `text-foreground`;`mode="disabled"` → fg-disabled)對齊 Input view empty 慣例。
 - **Empty(disabled all times)**:極端場景(`disabledHours` / `disabledMinutes` 覆蓋全範圍),panel column 全 disabled,鍵盤焦點停留無導覽目標。
+- **Panel 開啟中外部 value 變更**:controlled 單向資料流——欄位選中即時反映新 value,並 scroll-into-view(`behavior:'smooth'`,mount 後的變更;見「Spacing + 結構」的 Scroll-into-view 條)。
 - **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;panel column item 由 MenuItem SSOT 控 density。
 
 ---

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

@@ -0,0 +1,193 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+// M22 retrofit DONE 2026-05-03 v11(spec.md SSOT bears full citations; stories cite via spec.md ref line 15)
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { TimePicker } from './time-picker'
+import { Field, FieldLabel, FieldError } from '@/design-system/components/Field/field'
+
+const meta: Meta<typeof TimePicker> = {
+  title: 'Design System/Components/TimePicker/展示',
+  tags: ['autodocs'],
+  component: TimePicker,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '用於表單中選擇單一時鐘時間，例如會議、營業、排班或提醒時間。同時需日期改用 `DatePicker showTime`，時間範圍使用兩個 TimePicker 組合，倒數／時長或大量精確輸入則用專用控件或 Input。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
+    showSeconds: { control: 'boolean' },
+    minuteStep: { control: 'inline-radio', options: [1, 5, 10, 15, 30] },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof TimePicker>
+
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
+        <TimePicker value="14:30" onChange={() => {}} aria-label="會議時段(edit mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <TimePicker mode="view" value="14:30" aria-label="會議時段(view 模式示範)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+        <TimePicker mode="readonly" value="14:30" aria-label="會議時段(readonly mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+        <TimePicker mode="disabled" value="14:30" aria-label="會議時段(disabled mode demo)" />
+      </div>
+    </div>
+  ),
+}
+
+// ── 真實業務情境(禁用 Option A/B/C 或抽象場景)─────────────────────────────
+
+/**
+ * 會議排程 — 會議時間常以 15 分鐘為粒度,minuteStep=15 是世界級慣例
+ * (Google Calendar / Outlook / Notion Calendar 預設皆是 15)。
+ */
+export const MeetingSlot: Story = {
+  name: '會議時段',
+  render: () => {
+    const [start, setStart] = React.useState<string>('09:00')
+    const [end, setEnd] = React.useState<string>('10:00')
+    return (
+      <div className="flex flex-col gap-4 w-80">
+        <Field>
+          <FieldLabel>會議開始</FieldLabel>
+          <TimePicker value={start} onChange={setStart} minuteStep={15} />
+        </Field>
+        <Field>
+          <FieldLabel>會議結束</FieldLabel>
+          <TimePicker value={end} onChange={setEnd} minuteStep={15} />
+        </Field>
+      </div>
+    )
+  },
+}
+
+/**
+ * 航班時刻 — HH:mm 格式,不需要秒。
+ * 對照:Google Flights / Expedia / KAYAK 時間選擇都是分鐘粒度。
+ */
+export const FlightDepartureTime: Story = {
+  name: '航班起飛時間',
+  render: () => {
+    const [time, setTime] = React.useState<string>('14:35')
+    return (
+      <Field>
+        <FieldLabel>起飛時間</FieldLabel>
+        <TimePicker value={time} onChange={setTime} placeholder="請選擇起飛時間" />
+      </Field>
+    )
+  },
+}
+
+/**
+ * 營業時間 — 需要「開始到結束」的時間範圍時,並排放兩個 TimePicker(中間加箭頭)即可,
+ * TimePicker 本身不提供範圍模式。
+ */
+export const ShopBusinessHours: Story = {
+  name: '店家營業時間',
+  render: () => {
+    const [open, setOpen] = React.useState<string>('10:00')
+    const [close, setClose] = React.useState<string>('22:00')
+    return (
+      <Field>
+        <FieldLabel>營業時段</FieldLabel>
+        <div className="flex items-center gap-2">
+          <TimePicker value={open} onChange={setOpen} placeholder="開店時間" />
+          <span className="text-fg-muted">→</span>
+          <TimePicker value={close} onChange={setClose} placeholder="打烊時間" />
+        </div>
+      </Field>
+    )
+  },
+}
+
+/**
+ * 精確 log 時間 — 需要秒時啟用 showSeconds,format 自動升級到 HH:mm:ss。
+ * 對照:DevTools timeline / Datadog event timestamp 都秒級。
+ */
+export const EventTimestamp: Story = {
+  name: '事件發生時間',
+  render: () => {
+    const [time, setTime] = React.useState<string>('14:35:22')
+    return (
+      <Field>
+        <FieldLabel>事件發生時間</FieldLabel>
+        <TimePicker value={time} onChange={setTime} showSeconds clearable />
+      </Field>
+    )
+  },
+}
+
+/**
+ * 上下班 disabled 示例:半夜 0-6 點不可選(`disabledTime` 動態禁)。
+ * 對照:HR 排班系統 / 打卡 App 的時段限制。
+ */
+export const EmployeeShiftSchedule: Story = {
+  name: '員工上班時段設定',
+  render: () => {
+    const [clockIn, setClockIn] = React.useState<string>('09:00')
+    return (
+      <Field>
+        <FieldLabel>上班時間(0-5 點不可選)</FieldLabel>
+        <TimePicker
+          value={clockIn}
+          onChange={setClockIn}
+          minuteStep={5}
+          disabledTime={() => ({
+            disabledHours: [0, 1, 2, 3, 4, 5],
+          })}
+        />
+      </Field>
+    )
+  },
+}
+
+/**
+ * Disabled 整體禁用 — 例如表單在 read-only 階段,整個 TimePicker
+ * 走 `disabled` prop(不只 disabledTime 部分時段),trigger 不可開 popover。
+ * 對照:Salesforce / Workday read-only state、訂位確認頁的提交後鎖定。
+ */
+export const Disabled: Story = {
+  name: '整體禁用',
+  render: () => (
+    <Field>
+      <FieldLabel>面試時段(已確認,不可改)</FieldLabel>
+      <TimePicker value="14:00" onChange={() => {}} disabled />
+    </Field>
+  ),
+}
+
+/**
+ * WithError 驗證錯誤 — Field error 狀態 + TimePicker 套紅框。對照
+ * Material `<TextField error helperText>` / Ant `<Form.Item validateStatus="error">`。
+ */
+export const WithError: Story = {
+  name: '驗證錯誤',
+  render: () => {
+    const [time, setTime] = React.useState<string>('')
+    return (
+      <Field invalid={!time}>
+        <FieldLabel required>會議時段</FieldLabel>
+        <TimePicker value={time} onChange={setTime} placeholder="尚未選擇時段" />
+        {!time && <FieldError>請選擇會議時段才能預約</FieldError>}
+      </Field>
+    )
+  },
+}