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

package/src/components/Steps/steps.stories.tsx

@@ -0,0 +1,335 @@
+// @story-trait-rationale: AllSizes retired 2026-05-15(anatomy SizeMatrix own size matrix);
+//   AllStates retired 2026-05-17 per audit Dim 46(anatomy StateBehavior own state matrix,
+//   manual trait grid 違 story-rules.md 三層定位「展示層 = 典型使用情境,不是 trait grid」)。
+//   Disabled state 由 FocusRingCombinations 內部展示(disabled + ring combo 正交)。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Check } from 'lucide-react'
+import {
+  Steps,
+  StepItem,
+  StepLabel,
+  StepDescription,
+  StepContent,
+} from './steps'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta<typeof Steps> = {
+  title: 'Design System/Components/Steps/展示',
+  component: Steps,
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj<typeof Steps>
+
+// ── 典型 wizard ──────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  name: '預設',
+  render: () => {
+    const [value, setValue] = React.useState('info')
+    const [completed, setCompleted] = React.useState<string[]>([])
+    const [submitted, setSubmitted] = React.useState(false)
+
+    const advance = () => {
+      const nextMap: Record<string, string> = { info: 'account', account: 'review' }
+      setCompleted(prev => Array.from(new Set([...prev, value])))
+      const next = nextMap[value]
+      if (next) setValue(next)
+    }
+    const back = () => {
+      const prevMap: Record<string, string> = { account: 'info', review: 'account' }
+      const prev = prevMap[value]
+      if (prev) setValue(prev)
+    }
+    const submit = () => {
+      setCompleted(prev => Array.from(new Set([...prev, 'review'])))
+      setSubmitted(true)
+    }
+    const reset = () => {
+      setValue('info')
+      setCompleted([])
+      setSubmitted(false)
+    }
+
+    // ── Pattern A:submit 在最後一步,送出後整個 wizard 替換成 success banner ──
+    // 世界級 wizard UX(Ant / Linear / Stripe 常見):最後一步的 submit 按下後,
+    // stepper 不再顯示,改成一個 success card(+ 重置 button for demo 用)。
+    if (submitted) {
+      return (
+        <div className="w-[480px] flex flex-col gap-4 p-6 bg-muted rounded-md border border-border">
+          <div className="flex items-center gap-3">
+            <span className="h-8 w-8 rounded-full bg-info flex items-center justify-center shrink-0">
+              <Check className="text-white" size={20} strokeWidth={2.5} aria-hidden />
+            </span>
+            <span className="text-body-lg font-medium text-foreground">
+              已成功送出申請
+            </span>
+          </div>
+          <p className="text-body text-fg-secondary">
+            我們會盡快處理,結果將寄送至您的電子信箱。
+          </p>
+          <div>
+            <Button variant="secondary" onClick={reset}>
+              重新開始 demo
+            </Button>
+          </div>
+        </div>
+      )
+    }
+
+    return (
+      <div className="w-[480px]">
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={completed}
+        >
+          <StepItem value="info">
+            <StepLabel>基本資料</StepLabel>
+            <StepDescription>填寫姓名與聯絡方式</StepDescription>
+            <StepContent>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-fg-secondary">
+                  請輸入你的姓名、電子郵件與電話。
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="primary" onClick={advance}>下一步</Button>
+                </div>
+              </div>
+            </StepContent>
+          </StepItem>
+
+          <StepItem value="account">
+            <StepLabel>帳號設定</StepLabel>
+            <StepDescription>選擇使用者名稱與密碼</StepDescription>
+            <StepContent>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-fg-secondary">
+                  設定登入帳號。使用者名稱至少 3 個字元。
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="primary" onClick={advance}>下一步</Button>
+                  <Button variant="secondary" onClick={back}>
+                    上一步
+                  </Button>
+                </div>
+              </div>
+            </StepContent>
+          </StepItem>
+
+          <StepItem value="review">
+            <StepLabel>確認並送出</StepLabel>
+            <StepDescription>送出前最後檢查</StepDescription>
+            <StepContent>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-fg-secondary">
+                  請確認所有欄位正確,按下送出後系統會建立您的帳號。
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="primary" onClick={submit}>送出</Button>
+                  <Button variant="secondary" onClick={back}>
+                    上一步
+                  </Button>
+                </div>
+              </div>
+            </StepContent>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// @story-trait-rationale: AllSizes + AllStates retired per F migration 2026-05-17 —
+//   AllSizes retired 2026-05-15(anatomy SizeMatrix own);AllStates retired 2026-05-17
+//   per Dim 46 audit(anatomy StateBehavior 已 own state matrix,manual trait grid 違反
+//   story-rules.md 三層定位「展示層應為典型使用情境,不是 trait grid」)。
+
+// ── Focus marker 的正交示範 ─────────────────────────────────────────────
+// Ring 跟 content state 正交:任何 state + focused 都能組合
+
+export const FocusRingCombinations: Story = {
+  name: '聚焦環正交示範',
+  render: () => {
+    const [value, setValue] = React.useState('step-2')
+    return (
+      <div className="flex flex-col gap-4 w-[420px]">
+        <p className="text-caption text-fg-secondary">
+          點任何 step 看看 ring 如何獨立於底色——ring 表達「使用者在這步」,底色
+          表達「這步的狀態」。兩者正交。
+        </p>
+        <div className="flex gap-2">
+          {['step-1', 'step-2', 'step-3', 'step-4'].map(v => (
+            <Button
+              key={v}
+              size="sm"
+              variant={value === v ? 'primary' : 'secondary'}
+              onClick={() => setValue(v)}
+            >
+              value={v}
+            </Button>
+          ))}
+        </div>
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={['step-1', 'step-3']}
+          errorValues={['step-4']}
+          linear={false}
+        >
+          <StepItem value="step-1">
+            <StepLabel>Completed</StepLabel>
+            <StepDescription>藍底 ✓ + ring(若 focused)</StepDescription>
+          </StepItem>
+          <StepItem value="step-2">
+            <StepLabel>Current</StepLabel>
+            <StepDescription>中性底(bg-secondary)數字 + ring(若 focused)</StepDescription>
+          </StepItem>
+          <StepItem value="step-3">
+            <StepLabel>Completed</StepLabel>
+            <StepDescription>藍底 ✓ + ring(若 focused)</StepDescription>
+          </StepItem>
+          <StepItem value="step-4">
+            <StepLabel>Error</StepLabel>
+            <StepDescription>紅底 ✕ + 紅 ring(若 focused)</StepDescription>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// ── Non-linear ──────────────────────────────────────────────────────────
+
+export const NonLinear: Story = {
+  name: '非線性',
+  render: () => {
+    const [value, setValue] = React.useState('overview')
+    return (
+      <div className="w-[360px]">
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={['overview']}
+          linear={false}
+        >
+          <StepItem value="overview">
+            <StepLabel>總覽</StepLabel>
+            <StepDescription>可隨時回看</StepDescription>
+          </StepItem>
+          <StepItem value="members">
+            <StepLabel>成員管理</StepLabel>
+            <StepDescription>新增 / 移除團隊成員</StepDescription>
+          </StepItem>
+          <StepItem value="billing">
+            <StepLabel>計費設定</StepLabel>
+            <StepDescription>付款方式</StepDescription>
+          </StepItem>
+          <StepItem value="integrations">
+            <StepLabel>整合</StepLabel>
+            <StepDescription>連接第三方服務</StepDescription>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// ── Horizontal ──────────────────────────────────────────────────────────
+
+export const Horizontal: Story = {
+  name: '水平',
+  render: () => {
+    const [value, setValue] = React.useState('shipping')
+    return (
+      <div className="w-full max-w-3xl">
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={['cart', 'address']}
+          orientation="horizontal"
+        >
+          <StepItem value="cart">
+            <StepLabel>購物車</StepLabel>
+            <StepDescription>已確認</StepDescription>
+          </StepItem>
+          <StepItem value="address">
+            <StepLabel>寄送地址</StepLabel>
+            <StepDescription>已填寫</StepDescription>
+          </StepItem>
+          <StepItem value="shipping">
+            <StepLabel>運送方式</StepLabel>
+            <StepDescription>選擇配送</StepDescription>
+          </StepItem>
+          <StepItem value="payment">
+            <StepLabel>付款</StepLabel>
+            <StepDescription>信用卡 / Apple Pay</StepDescription>
+          </StepItem>
+          <StepItem value="done">
+            <StepLabel>完成</StepLabel>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// ── Multiple expansion ─────────────────────────────────────────────────
+
+export const MultipleExpansion: Story = {
+  name: '多重展開模式',
+  render: () => (
+    <div className="w-[480px]">
+      <p className="text-caption text-fg-secondary mb-4">
+        點 step header 切換展開(並更新 value)。本例顯式傳 `defaultExpanded="all"` 全部展開起手(預設 `"none"`)。
+      </p>
+      <Steps
+        defaultValue="b"
+        completedValues={['a']}
+        expansion="multiple"
+        defaultExpanded="all"
+        linear={false}
+      >
+        <StepItem value="a">
+          <StepLabel>安裝套件</StepLabel>
+          <StepDescription>執行 npm install</StepDescription>
+          <StepContent>
+            <div className="max-w-full overflow-x-auto rounded-md bg-muted">
+              <pre className="text-caption p-3 whitespace-pre w-max">
+              npm install @qijenchen/design-system
+            </pre>
+            </div>
+          </StepContent>
+        </StepItem>
+        <StepItem value="b">
+          <StepLabel>匯入元件</StepLabel>
+          <StepDescription>從 design-system 引入</StepDescription>
+          <StepContent>
+            <div className="max-w-full overflow-x-auto rounded-md bg-muted">
+              <pre className="text-caption p-3 whitespace-pre w-max">
+              {"import { Steps } from '@/design-system/components/Steps/steps'"}
+            </pre>
+            </div>
+          </StepContent>
+        </StepItem>
+        <StepItem value="c">
+          <StepLabel>設定 provider</StepLabel>
+          <StepDescription>包在 App 最外層</StepDescription>
+          <StepContent>
+            <div className="max-w-full overflow-x-auto rounded-md bg-muted">
+              <pre className="text-caption p-3 whitespace-pre w-max">
+              {"<TooltipProvider>{children}</TooltipProvider>"}
+            </pre>
+            </div>
+          </StepContent>
+        </StepItem>
+      </Steps>
+    </div>
+  ),
+}
+
+// @story-trait-rationale: MixedDescription(欄節奏驗證 grid)retired 2026-06-11 per audit
+//   EXAMPLE_REDUNDANT — indicator 對齊 label 第一行的 column rhythm 已由 anatomy「欄位節奏」+
+//   principles「規則:指示欄節奏一致」雙層 own;展示層不重複 trait 驗證 grid。

package/src/components/Steps/steps.tsx

@@ -4,6 +4,7 @@ import * as React from 'react'
 import { Check, ChevronDown, X } from 'lucide-react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
+import { ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 // ── Types ─────────────────────────────────────────────────────────────────
 
@@ -47,7 +48,7 @@ function getOuterRingShadow(ringColor: string): string {
 function resolveRingColor(state: StepContentState, linear: boolean): string {
   if (state === 'error') return 'var(--error-hover)'
   if (state === 'current' && !linear) return 'var(--border-hover)'
-  return 'var(--primary-hover)'
+  return 'var(--info-hover)'
 }
 
 // ── Contexts ──────────────────────────────────────────────────────────────
@@ -64,6 +65,7 @@ interface StepsContextValue {
   expandedSet: Set<string>
   setValue: (value: string) => void
   toggleExpanded: (value: string) => void
+  total: number
 }
 
 const StepsContext = React.createContext<StepsContextValue | null>(null)
@@ -240,6 +242,8 @@ const Steps = React.forwardRef<HTMLOListElement, StepsProps>(
       })
     }, [])
 
+    const stepCount = React.Children.count(children)
+
     const ctxValue = React.useMemo<StepsContextValue>(
       () => ({
         value,
@@ -253,12 +257,13 @@ const Steps = React.forwardRef<HTMLOListElement, StepsProps>(
         expandedSet,
         setValue,
         toggleExpanded,
+        total: stepCount,
       }),
-      [value, completedValues, errorValues, reachableValues, linear, size, orientation, expansion, expandedSet, setValue, toggleExpanded],
+      [value, completedValues, errorValues, reachableValues, linear, size, orientation, expansion, expandedSet, setValue, toggleExpanded, stepCount],
     )
 
     // Interleave horizontal connectors between items
-    const count = React.Children.count(children)
+    const count = stepCount
     const itemsWithIndex: React.ReactNode[] = []
 
     React.Children.forEach(children, (child, index) => {
@@ -421,8 +426,20 @@ function StepItemLayout({ children }: { children: React.ReactNode }) {
 
 // ── Clickable header ─────────────────────────────────────────────────────
 
+// SR-only 狀態文字 map(2026-06-01 #25 a11y:indicator 是 aria-hidden 純視覺,故「第 N 步/共 M 步/狀態」
+// 需經 sr-only span 給螢幕報讀器。對齊 Carbon ProgressIndicator `--assistive-text`(已完成/進行中/未開始)慣例)
+const STEP_STATUS_TEXT: Record<StepContentState, string> = {
+  completed: '已完成',
+  current: '進行中',
+  error: '錯誤',
+  reachable: '未開始',
+  upcoming: '未開始',
+}
+
 function StepItemHeader({ children, className, style }: { children: React.ReactNode; className?: string; style?: React.CSSProperties }) {
   const item = useStepItemContext()
+  const steps = useStepsContext()
+  const index = React.useContext(StepIndexContext)
   const onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
     if (!item.clickable) return
     if (e.key === 'Enter' || e.key === ' ') {
@@ -438,7 +455,11 @@ function StepItemHeader({ children, className, style }: { children: React.ReactN
       onKeyDown={item.clickable ? onKeyDown : undefined}
       aria-disabled={item.disabled || undefined}
       className={cn(
-        'outline-none',
+        // leading-compact:scanning-family header 行高 = 1.3(item-anatomy.spec.md:776 掃描模式 label 行高)。
+        // 設在 header 而非 li 根 → prefix h-[1lh] + 水平 connector h-[1lh] + label(StepLabel 亦 leading-compact)
+        // 全用 1.3 對齊;li 根 text-body(1.5,steps.tsx:329-331)留給展開 content 的 reading 行高,不被
+        // scanning 波及(避免 改A壞B)。對齊 MenuItem 把 leading-compact 放 row 容器之原則(item-anatomy.tsx:144-146)。
+        'outline-none leading-compact',
         item.clickable
           ? 'cursor-pointer rounded-md focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring'
           : 'cursor-not-allowed',
@@ -446,6 +467,7 @@ function StepItemHeader({ children, className, style }: { children: React.ReactN
       )}
       style={style}
     >
+      <span className="sr-only">{`第 ${index} 步,共 ${steps.total} 步,${STEP_STATUS_TEXT[item.state]}`}</span>
       {children}
     </div>
   )
@@ -472,18 +494,20 @@ function VerticalLayout({
   return (
     <>
       <StepItemHeader className="flex items-start gap-3">
-        <div className="shrink-0" style={{ width: indicatorBox }}>
-          <div className="h-[1lh] flex items-center justify-center">
-            <StepIndicator />
-          </div>
-        </div>
-        <div className="flex-1 min-w-0 flex items-start">
+        {/* Row prefix slot — 消費 item-anatomy <ItemPrefix>(h-[1lh] 對齊 label 第一行 SSOT);
+            width = INDICATOR_BOX_WIDTH 固定欄寬,base justify-center 讓 sm dot 在欄內置中 */}
+        <ItemPrefix style={{ width: indicatorBox }}>
+          <StepIndicator />
+        </ItemPrefix>
+        <div className="flex-1 min-w-0 flex items-start gap-2">
           <div className="flex-1 min-w-0 flex flex-col">
             {label}
             {description}
           </div>
+          {/* Row suffix slot — 消費 item-anatomy <ItemSuffix>(h-[1lh] 對齊 label 第一行);
+              text col 是 flex-1 → base ml-auto 惰性,8px 間距由父層 gap-2 提供(= MenuItem 父層 gap idiom)*/}
           {steps.expansion === 'multiple' && !!content && (
-            <span aria-hidden className="h-[1lh] flex items-center shrink-0 ml-2">
+            <ItemSuffix aria-hidden>
               <ChevronDown
                 size={16}
                 className={cn(
@@ -491,7 +515,7 @@ function VerticalLayout({
                   item.expanded && 'rotate-180',
                 )}
               />
-            </span>
+            </ItemSuffix>
           )}
         </div>
       </StepItemHeader>
@@ -519,8 +543,10 @@ function VerticalConnectorLine() {
     <div
       aria-hidden
       className={cn(
-        'absolute w-px',
-        isBlue ? 'bg-primary' : 'bg-border',
+        // leading-compact:connector 的 0.5lh 須跟 scanning label 同行高(1.3)→ 起點對齊 circle 中心
+        // (circle 對齊 label 第一行;label 已 leading-compact)。否則 connector 繼承 li 根 1.5 → 0.5lh 偏大 → 起點偏低。
+        'absolute w-px leading-compact',
+        isBlue ? 'bg-info' : 'bg-border',
       )}
       style={{
         left: INDICATOR_BOX_WIDTH[steps.size] / 2,
@@ -563,14 +589,15 @@ function HorizontalLayout({
     <>
       {/* Row 1: indicator + label + connector(在同一個 flex row) */}
       <StepItemHeader className="flex items-start gap-3">
-        <div className="h-[1lh] flex items-center shrink-0">
+        {/* Row prefix slot — 消費 item-anatomy <ItemPrefix>(h-[1lh] 對齊 label 第一行 SSOT)*/}
+        <ItemPrefix>
           <StepIndicator />
-        </div>
+        </ItemPrefix>
         <div className="shrink-0 min-w-0">{label}</div>
         {/* Connector 在 item 內部,flex-1 填滿剩餘寬度 */}
         {!item.isLast && (
           <div className="h-[1lh] flex-1 flex items-center min-w-4" aria-hidden>
-            <div className={cn('h-px w-full', isBlue ? 'bg-primary' : 'bg-border')} />
+            <div className={cn('h-px w-full', isBlue ? 'bg-info' : 'bg-border')} />
           </div>
         )}
       </StepItemHeader>
@@ -618,12 +645,12 @@ function SmIndicator({
       width: INDICATOR_SIZE.sm,
       height: INDICATOR_SIZE.sm,
       background: 'transparent',
-      border: '2px solid var(--primary-hover)',
+      border: '2px solid var(--info-hover)',
       boxShadow: focused ? getOuterRingShadow(resolveRingColor(state, linear)) : undefined,
     }
   } else {
     const dotBg =
-      state === 'completed' ? 'var(--primary)'
+      state === 'completed' ? 'var(--info)'
         : state === 'error' ? 'var(--error)'
           : state === 'current' && !linear ? 'var(--fg-disabled)'
             : 'var(--fg-disabled)' // upcoming + non-linear fallback
@@ -677,12 +704,12 @@ function MdLgIndicator({
       contentColor = 'var(--on-emphasis)'
       break
     case 'completed':
-      fillBg = 'var(--primary)'
+      fillBg = 'var(--info)'
       contentColor = 'var(--on-emphasis)'
       break
     case 'current':
       if (linear) {
-        fillBg = 'var(--primary)'
+        fillBg = 'var(--info)'
         contentColor = 'var(--on-emphasis)'
       } else {
         fillBg = 'var(--secondary)'
@@ -690,7 +717,7 @@ function MdLgIndicator({
       }
       break
     case 'reachable':
-      fillBg = 'var(--primary)'
+      fillBg = 'var(--info)'
       contentColor = 'var(--on-emphasis)'
       break
     default: // upcoming
@@ -717,7 +744,8 @@ function MdLgIndicator({
         height: diameter,
         background: fillBg,
         color: contentColor,
-        fontSize: size === 'lg' ? 'var(--font-body-size)' : 'var(--font-caption-size)',
+        // 2026-06-11 R2:對齊 spec canonical「indicator 數字與 label 同級」(steps.spec.md 狀態表 md=14/lg=16;spec 明文「之前寫小一號(md=12,lg=14)是錯的」)
+        fontSize: size === 'lg' ? 'var(--font-body-lg-size)' : 'var(--font-body-size)',
         boxShadow: focused ? getOuterRingShadow(resolveRingColor(state, linear)) : undefined,
       }}
     >
@@ -751,7 +779,9 @@ const StepLabel = React.forwardRef<HTMLSpanElement, StepLabelProps>(
       <span
         ref={ref}
         className={cn(
-          'font-medium break-words',
+          // leading-compact:scanning-family label 行高 = 1.3(item-anatomy.spec.md:776);text-body utility
+          // 自帶 lh:1.5,須顯式 leading-compact 蓋回 1.3,跟 MenuItem label(實測 14px/18px=1.3)一致。
+          'font-medium break-words leading-compact',
           size === 'lg' ? 'text-body-lg' : 'text-body',
           disabled
             ? 'text-fg-disabled'
@@ -839,9 +869,9 @@ export const stepsMeta = {
     md: { px: 24, when: '預設 — wizard / checkout / 註冊主流程;indicator 24px circle' },
     lg: { px: 32, when: 'Marketing 流程展示 / 重要 onboarding;indicator 32px circle' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['upcoming', 'reachable', 'current', 'completed', 'error'], // 2026-06-11 R2:content-state 模型(spec 狀態表),非 Phase-1 boilerplate 互動 states,
   tokens: {
-    bg: ['bg-primary'],
+    bg: ['bg-info'],
     fg: ['--fg-disabled', '--foreground', '--on-emphasis', 'text-error-text', 'text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
     ring: [],
   },

package/src/components/Switch/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 './switch'