@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,281 @@
+// M22 retrofit DONE 2026-05-03 v11(spec.md SSOT bears full citations; anatomy claim「Ant Design / Google Calendar TimePicker」line 150 = spec-derived `@benchmark-unverified` visual)
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @anatomy-rationale:
+//   StateBehavior covered by ColorMatrix「Trigger Field family + Panel item
+//     SelectMenu family」雙層狀態對照(trigger:default / hover / focus / open /
+//     disabled / error,panel:default / hover / selected / disabled)+ ModeMatrix(6.)
+//     edit / readonly / disabled / empty / error / clearable 6 模式視覺對照。
+//     TimePicker 的色彩繼承上游 SSOT(Field + SelectMenu),無 own state 變化,
+//     集中於 ColorMatrix + ModeMatrix 比拆 5. 更直觀。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { TimePicker } from './time-picker'
+
+/**
+ * TimePicker 設計規格 — 完整技術規格。anatomy 5-story 最小版本。
+ * 深度規格見 `time-picker.spec.md`。
+ */
+
+const meta: Meta<typeof TimePicker> = {
+  title: 'Design System/Components/TimePicker/設計規格',
+  component: TimePicker,
+  parameters: { layout: 'centered' },
+}
+export default meta
+
+type Story = StoryObj<typeof TimePicker>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => <TimePicker value="09:00" onChange={() => {}} />,
+}
+
+/**
+ * ColorMatrix — Trigger(Field family)+ Panel item(MenuItem family) 色彩對照
+ * 兩層色彩分別繼承不同 SSOT,本 story 展示整合對照。
+ */
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => {
+    const Swatch = ({ value }: { value: string }) => (
+      <span className="inline-block w-3 h-3 rounded-sm border border-black/10 align-middle mr-1.5" style={{ backgroundColor: `var(${value})` }} />
+    )
+    return (
+      <div className="flex flex-col gap-10">
+        <div>
+          <div className="text-h6 font-semibold text-foreground mb-2">TimePicker 色彩分兩層</div>
+          <div className="text-caption text-fg-muted max-w-[720px]">
+            Trigger 層走 Field Controls family 色彩(與 Input / Select 共用);Panel 層 column item 走 SelectMenu / MenuItem family 色彩(與 Select dropdown / DropdownMenu 共用)。TimePicker 本身無色彩變體——色彩完全繼承上游 主檔。
+          </div>
+        </div>
+
+        {/* Trigger layer */}
+        <div className="flex flex-col gap-2">
+          <div className="text-h6 font-semibold text-foreground">第 1 層:觸發欄位(沿用一般輸入欄位配色)</div>
+          <div className="text-caption text-fg-muted mb-2">色彩與 Input / Select 等輸入欄位共用同一套規則。</div>
+          <div className="overflow-x-auto">
+            <table className="text-caption border-collapse min-w-[640px]">
+              <thead>
+                <tr>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">State</th>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">Background</th>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">Border</th>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">Foreground</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">default</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--surface" /><span className="font-mono">--surface</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--border" /><span className="font-mono">--border</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">hover</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--surface" /><span className="font-mono">--surface</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--border-hover" /><span className="font-mono">--border-hover</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">focus(focus-within)</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--surface" /><span className="font-mono">--surface</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--primary" /><span className="font-mono">--primary</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">open(autofocus 移入 panel)</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--surface" /><span className="font-mono">--surface</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--border-hover" /><span className="font-mono">--border-hover</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">disabled</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--bg-disabled" /><span className="font-mono">--bg-disabled</span></td>
+                  <td className="p-2 border-b border-divider"><span className="font-mono">transparent</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--fg-disabled" /><span className="font-mono">--fg-disabled</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">error</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--surface" /><span className="font-mono">--surface</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--error" /><span className="font-mono">--error</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+          <div className="flex gap-3 mt-3">
+            <TimePicker value="09:00" onChange={() => {}} />
+            <TimePicker value="09:00" onChange={() => {}} error />
+            <TimePicker value="09:00" onChange={() => {}} disabled />
+          </div>
+        </div>
+
+        {/* Panel layer */}
+        <div className="flex flex-col gap-2">
+          <div className="text-h6 font-semibold text-foreground">第 2 層:面板裡的時 / 分 / 秒選項(沿用下拉選單配色)</div>
+          <div className="text-caption text-fg-muted mb-2">
+            選項的 hover / 選中 / 停用配色,與下拉選單(Select / 選單項目)的選取狀態共用同一套規則。
+          </div>
+          <div className="text-caption text-fg-secondary mb-3 max-w-[720px]">
+            <strong>關鍵決策:selected 走 neutral 非 primary</strong>(對齊 SelectMenu 設計準則)。TimePicker panel 是「列表選中」語意,跟 SelectMenu / MenuItem 同流派;DatePicker date cell 用 `--primary` 是因為那是「最終選定日期」的強 affordance(確定性),兩者不同語意,不互調。
+          </div>
+          <div className="overflow-x-auto">
+            <table className="text-caption border-collapse min-w-[640px]">
+              <thead>
+                <tr>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">State</th>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">Background</th>
+                  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium">Foreground</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">default(normal 數字)</td>
+                  <td className="p-2 border-b border-divider"><span className="font-mono">transparent</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">hover</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--neutral-hover" /><span className="font-mono">--neutral-hover</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">selected</td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--neutral-selected" /><span className="font-mono">--neutral-selected(非 primary)</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--foreground" /><span className="font-mono">--foreground</span></td>
+                </tr>
+                <tr>
+                  <td className="p-2 border-b border-divider font-mono">disabled(disabledTime)</td>
+                  <td className="p-2 border-b border-divider"><span className="font-mono">transparent</span></td>
+                  <td className="p-2 border-b border-divider"><Swatch value="--fg-disabled" /><span className="font-mono">--fg-disabled + cursor-not-allowed</span></td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+          <div className="text-caption text-fg-muted mt-3">
+            對照 DatePicker `ColorMatrix` 的 date cell selected 用 `--primary` — 那是「提交語意」;TimePicker 是「正在挑選」中的中間態,neutral-selected 與 Ant Design / Google Calendar TimePicker 一致。點開本頁 TimePicker trigger 可直接看到 Panel selected 的視覺效果。
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
+
+/** 尺寸矩陣 sm / md(預設) / lg */
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-3">
+        <span className="w-12 text-caption text-fg-muted">sm</span>
+        <TimePicker size="sm" value="09:00" onChange={() => {}} />
+      </div>
+      <div className="flex items-center gap-3">
+        <span className="w-12 text-caption text-fg-muted">md ★default</span>
+        <TimePicker size="md" value="09:00" onChange={() => {}} />
+      </div>
+      <div className="flex items-center gap-3">
+        <span className="w-12 text-caption text-fg-muted">lg</span>
+        <TimePicker size="lg" value="09:00" onChange={() => {}} />
+      </div>
+    </div>
+  ),
+}
+
+/** Mode / error 狀態 matrix */
+export const ModeMatrix: Story = {
+  name: '模式對照',
+  render: () => (
+    <div className="flex flex-col gap-3 w-60">
+      <TimePicker value="09:00" onChange={() => {}} placeholder="edit(預設)" aria-label="edit mode demo" />
+      <TimePicker value="09:00" onChange={() => {}} mode="readonly" aria-label="readonly mode demo" />
+      <TimePicker value="09:00" onChange={() => {}} disabled aria-label="disabled mode demo" />
+      <TimePicker value="" onChange={() => {}} placeholder="空值 → placeholder" aria-label="empty value demo" />
+      <TimePicker value="09:00" onChange={() => {}} error aria-label="error state demo" />
+      <TimePicker value="09:00" onChange={() => {}} clearable aria-label="clearable demo" />
+    </div>
+  ),
+}
+
+/** Panel 精度:showSeconds 三欄 vs 兩欄 / minuteStep 粒度 */
+export const PrecisionMatrix: Story = {
+  name: '精度對照',
+  render: () => (
+    <div className="flex flex-col gap-3 w-80">
+      <div>
+        <div className="text-caption text-fg-muted mb-1">兩欄(showSeconds=false,預設)</div>
+        <TimePicker value="09:00" onChange={() => {}} />
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">三欄(showSeconds=true)</div>
+        <TimePicker value="09:00:00" onChange={() => {}} showSeconds />
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">minuteStep=15(會議常用)</div>
+        <TimePicker value="09:00" onChange={() => {}} minuteStep={15} />
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">disabledTime:0-5 點不可選</div>
+        <TimePicker
+          value="09:00"
+          onChange={() => {}}
+          disabledTime={() => ({ disabledHours: [0, 1, 2, 3, 4, 5] })}
+        />
+      </div>
+    </div>
+  ),
+}
+
+/** Inspector — live props 調整驗規格 */
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  args: {
+    value: '09:00',
+    size: 'md',
+    clearable: false,
+    showSeconds: false,
+    minuteStep: 1,
+    disabled: false,
+    error: false,
+    placeholder: '請選擇時間',
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
+    minuteStep: { control: 'inline-radio', options: [1, 5, 10, 15, 30] },
+  },
+  render: (args) => {
+    const [v, setV] = React.useState(args.value ?? '')
+    return <TimePicker {...args} value={v} onChange={setV} />
+  },
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 7. Accessibility — ARIA roles + keyboard map
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const Accessibility: Story = {
+  name: '無障礙',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-3xl text-body">
+      <section>
+        <h3 className="text-body font-bold mb-2">ARIA roles</h3>
+        <ul className="list-disc list-inside text-caption text-fg-secondary space-y-1">
+          <li>Trigger:<code>role="combobox"</code> + <code>aria-expanded={`{open}`}</code>;在 <code>{'<Field>'}</code> 內以 <code>aria-labelledby</code> 指向 field label(無 Field 時 consumer 需自帶 <code>aria-label</code>)</li>
+          <li>Panel:每欄(時 / 分 / 秒)<code>role="listbox"</code></li>
+          <li>每 item:<code>role="option"</code> + <code>aria-selected</code> 反映當前 value</li>
+          <li>Screen reader 經 trigger label(field label)+ combobox 內可見值文字朗讀目前選取時間(目前值以可見 <code>{'<span>'}</code> 呈現,無額外 <code>aria-valuetext</code>)</li>
+        </ul>
+      </section>
+      <section>
+        <h3 className="text-body font-bold mb-2">鍵盤導覽(WAI-ARIA listbox pattern)</h3>
+        <ul className="list-disc list-inside text-caption text-fg-secondary space-y-1">
+          <li>Trigger:<kbd>Space</kbd> / <kbd>Enter</kbd> / <kbd>↓</kbd> 開 panel(對齊 APG combobox + Select)</li>
+          <li>Panel 開啟:<kbd>Esc</kbd> 關閉 + focus return to trigger</li>
+          <li>Column 內:<kbd>↑</kbd> <kbd>↓</kbd> 切 option</li>
+          <li><kbd>Home</kbd> <kbd>End</kbd> 跳 column 首尾</li>
+          <li><kbd>Tab</kbd> / <kbd>Shift+Tab</kbd> 切換 column(時 → 分 → 秒)</li>
+        </ul>
+      </section>
+    </div>
+  ),
+}

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

@@ -0,0 +1,140 @@
+// @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; this file's claims are spec-derived rationale stories)
+import * as React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { TimePicker } from './time-picker'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+
+/**
+ * TimePicker 設計原則 stories — 讀 `time-picker.spec.md` 了解完整規則。
+ * 每則 story 示範一條設計判斷(何時用、何時不用、禁止事項)。
+ */
+
+const meta: Meta<typeof TimePicker> = {
+  title: 'Design System/Components/TimePicker/設計原則',
+  component: TimePicker,
+  parameters: { layout: 'centered' },
+}
+export default meta
+
+type Story = StoryObj<typeof TimePicker>
+
+/**
+ * Rule:會議場景 minuteStep=15
+ * 世界級(Google Calendar / Outlook / Notion Calendar)開會排時間都是 15 分鐘粒度——
+ * minuteStep=1 讓使用者困在挑「9:07 還是 9:08」,失去會議排程本質。
+ */
+// ── WhenToUse — 何時使用 TimePicker ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 TimePicker 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/TimePicker/展示" name="會議時段"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">會議時段</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/TimePicker/展示" name="航班起飛時間"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">航班起飛時間</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/TimePicker/展示" name="店家營業時間"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">店家營業時間</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/TimePicker/展示" name="事件發生時間"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">事件發生時間</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/TimePicker/展示" name="員工上班時段設定"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">員工上班時段設定</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">不確定是否該用 TimePicker 時,先對照下方「何時不用」清單;若情境不符,改用清單建議的替代元件(例如同時要日期就用 DatePicker)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div className="prose prose-sm max-w-prose space-y-4">
+      <p>TimePicker 只管時間,以下情境改用其他元件:</p>
+      <ul className="list-disc list-inside space-y-1 text-fg-secondary">
+        <li><strong>同時選日期和時間</strong> → DatePicker + TimePicker 並列。Jira 的 due date 用 DatePicker，time 用 TimePicker</li>
+        <li><strong>時間範圍（from-to）</strong> → 兩個 TimePicker 並列。Google Calendar 的 event time 是兩個 picker</li>
+        <li><strong>純文字時間輸入</strong> → Input + validation。開發者工具用 Input</li>
+        <li><strong>倒數計時或相對時間</strong> → 自訂計時器。TimePicker 是 wall-clock time（09:30），不是 duration</li>
+      </ul>
+    </div>
+    </div>
+  ),
+}
+
+export const RuleMinuteStepForMeetings: Story = {
+  name: '會議時段用 15 分鐘間隔',
+  render: () => (
+    <div className="flex gap-8">
+      <div className="flex flex-col gap-1.5">
+        <h3 className="text-caption font-medium text-foreground">✅ minuteStep=15</h3>
+        <Field>
+          <FieldLabel>專案週會時間</FieldLabel>
+          <TimePicker value="09:15" onChange={() => {}} minuteStep={15} />
+        </Field>
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <h3 className="text-caption font-medium text-fg-muted">❌ 預設 minuteStep=1(會議排程無意義)</h3>
+        <Field>
+          <FieldLabel>專案週會時間</FieldLabel>
+          <TimePicker value="09:07" onChange={() => {}} />
+        </Field>
+      </div>
+    </div>
+  ),
+}
+
+/**
+ * Rule:Range 語意用兩個 TimePicker 組合
+ * TimePicker MVP 不內建 Range(見 spec「為何無 Range」)——對齊 Ant composition 思路,
+ * consumer 用兩個 TimePicker + arrow 達成營業時段 / 會議時段等 range 場景。
+ */
+export const RuleRangeComposition: Story = {
+  name: '時間範圍用兩個 TimePicker 組合,不內建',
+  render: () => {
+    const [open, setOpen] = React.useState('10:00')
+    const [close, setClose] = React.useState('22:00')
+    return (
+      <Field>
+        <FieldLabel>營業時段(兩個 TimePicker + →)</FieldLabel>
+        <div className="flex items-center gap-2">
+          <TimePicker value={open} onChange={setOpen} />
+          <span className="text-fg-muted">→</span>
+          <TimePicker value={close} onChange={setClose} />
+        </div>
+      </Field>
+    )
+  },
+}
+
+/**
+ * 規則:清除用 X 行內動作,不要用文字按鈕
+ * 設定 clearable 後,TimePicker 會自動在欄位尾端渲染一個 X 行內動作來清空值,
+ * 點擊即清空。不要自己擺一顆「清除」文字按鈕——統一用 X 圖示符合全站慣例。
+ */
+export const RuleClearNoLabelButton: Story = {
+  name: '清除用 X 行內動作,不用文字按鈕',
+  render: () => {
+    const [t, setT] = React.useState<string>('14:30')
+    return (
+      <div className="flex flex-col gap-1.5">
+        <h3 className="text-caption font-medium text-foreground">✅ clearable=true(自動渲染 X 行內動作)</h3>
+        <Field>
+          <FieldLabel>提醒時間</FieldLabel>
+          <TimePicker value={t} onChange={setT} clearable />
+        </Field>
+      </div>
+    )
+  },
+}
+
+