@qijenchen/design-system 0.1.0-beta.3

package/src/components/CircularProgress/circular-progress.tsx

@@ -0,0 +1,204 @@
+// @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.
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * CircularProgress — 圓形進度指示(determinate + indeterminate 雙模式)
+ *
+ * 世界級對照:Material `CircularProgress` / Chakra `CircularProgress` — 同元件管
+ * determinate(有 `value`)+ indeterminate(無 `value`)兩態。本 DS 採此流派作為
+ * circular progress 的 SSOT,`Spinner` 名稱廢除(遷至本元件)。
+ *
+ * ── 姊妹元件 ──
+ * `ProgressBar`       = linear determinate(大區塊、頁面級、表單步驟、上傳 bar)
+ * `CircularProgress`  = circular 兩態(本元件,inline 小空間 / Button loading / Field loading)
+ *
+ * ── API ──
+ * value:     undefined → indeterminate(旋轉 partial arc,Spinner 樣式)
+ *            number 0-100 → determinate(固定 arc + track)
+ * size:      自由 px(預設 24,≤ 64 建議)— 跟 Avatar / Lucide icon 同策略
+ * label:     可選 inline label,font-size inherit parent,color text-fg-muted
+ * affix:     (determinate only)'value' | ReactNode
+ *
+ * ── 視覺 ──
+ * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-primary`,不隨狀態變色)。
+ * stroke-linecap round,rotate -90deg。
+ * Indeterminate mode:arc 固定 25%,外層 `animate-spin` 旋轉,視覺同 Spinner。
+ *
+ * ── 不設 status prop(決策 2026-04-20)──
+ * 世界級沒有「success / error CircularProgress」的穩態呈現——完成 / 失敗的語義應由
+ * consumer 在業務邏輯上**替換 CircularProgress 為實際內容**(status icon + label、
+ * 成功的結果、錯誤訊息等),而非讓 CircularProgress 變色 + 加 check icon。這種「綠底
+ * 空心 circle + check icon 並排」是 DS 典型 over-designing 的 anti-pattern(參考:
+ * Material / Chakra / Ant / Polaris 全部沒有此 variant)。
+ *
+ * Consumer 端範例:
+ *   {uploading ? <CircularProgress /> : done ? <Check /> : error ? <AlertCircle /> : null}
+ *
+ * ── A11y ──
+ * 有 value → role="progressbar" + aria-valuenow/min/max
+ * 無 value → role="status"(loading 語義) + aria-label(如傳)或 aria-hidden(否則)
+ */
+
+// Indeterminate mode 的 arc 比例(Material 流派:25%-30% 視覺最平衡)
+const INDETERMINATE_ARC_RATIO = 0.25
+
+export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /**
+   * 進度 0-100。
+   * - undefined → indeterminate(旋轉 partial arc,Spinner 樣式)
+   * - number → determinate(固定 arc + track)
+   */
+  value?: number
+  /** 直徑(px)。預設 24,建議 ≤ 64。 */
+  size?: number
+  /** 狀態色(lifecycle,與 ProgressBar 同契約)。 */
+  /**
+   * 視覺 label(inline 顯示於右側)。
+   * - font-size 繼承 parent(不設 text-size class,CSS inherit)
+   * - color 鎖 `text-fg-muted`(neutral-7)
+   * - 塞在元件內時預設不用(e.g. Button loading);全頁 / Empty overlay 可用
+   */
+  label?: string
+  /**
+   * 右側 affix(determinate only;indeterminate 忽略)。
+   * - `'value'` → `{value}%` 文字
+   * - ReactNode → 客製(若需顯示「已完成」,consumer 端整個 swap 為 Check icon,不走此 prop)
+   */
+  affix?: 'value' | React.ReactNode
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps>(
+  (
+    {
+      value,
+      size = 24,
+      label,
+      affix,
+      className,
+      'aria-label': ariaLabel,
+      ...props
+    },
+    ref,
+  ) => {
+    const isDeterminate = typeof value === 'number'
+    const clampedValue = isDeterminate ? Math.max(0, Math.min(100, value)) : 0
+    const strokeWidth = Math.max(2, Math.round(size / 10))
+    const radius = (size - strokeWidth) / 2
+    const circumference = 2 * Math.PI * radius
+    const dashOffset = isDeterminate
+      ? circumference * (1 - clampedValue / 100)
+      : circumference * (1 - INDETERMINATE_ARC_RATIO)
+
+    const hasLabel = typeof label === 'string' && label.length > 0
+    const hasAriaLabel = typeof ariaLabel === 'string' && ariaLabel.length > 0
+    const shouldAnnounce = hasAriaLabel || hasLabel
+
+    // Affix(determinate only)
+    let affixNode: React.ReactNode = null
+    if (isDeterminate) {
+      if (affix === 'value') {
+        affixNode = (
+          <span className="text-caption text-foreground tabular-nums shrink-0">
+            {Math.round(clampedValue)}%
+          </span>
+        )
+      } else if (
+        React.isValidElement(affix) ||
+        typeof affix === 'string' ||
+        typeof affix === 'number'
+      ) {
+        affixNode = affix
+      }
+    }
+
+    const a11yRole = isDeterminate ? 'progressbar' : shouldAnnounce ? 'status' : undefined
+    const a11yLabel = hasAriaLabel ? ariaLabel : hasLabel ? label : undefined
+    const a11yValueAttrs = isDeterminate
+      ? {
+          'aria-valuenow': Math.round(clampedValue),
+          'aria-valuemin': 0,
+          'aria-valuemax': 100,
+        }
+      : {}
+
+    const graphic = (
+      <span
+        ref={ref}
+        role={a11yRole}
+        aria-label={a11yLabel}
+        aria-hidden={!a11yRole ? true : undefined}
+        {...a11yValueAttrs}
+        className={cn(
+          // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線
+          //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)
+          'inline-flex shrink-0 align-middle text-primary',
+          // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),
+          // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。
+          !isDeterminate && 'animate-spin motion-reduce:[animation-duration:3s]',
+          className,
+        )}
+        style={{ width: size, height: size }}
+        {...props}
+      >
+        <svg viewBox={`0 0 ${size} ${size}`} width={size} height={size} aria-hidden>
+          <circle
+            cx={size / 2}
+            cy={size / 2}
+            r={radius}
+            fill="none"
+            stroke="var(--secondary)"
+            strokeWidth={strokeWidth}
+          />
+          <circle
+            cx={size / 2}
+            cy={size / 2}
+            r={radius}
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={strokeWidth}
+            strokeDasharray={circumference}
+            strokeDashoffset={dashOffset}
+            strokeLinecap="round"
+            transform={`rotate(-90 ${size / 2} ${size / 2})`}
+            className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300' : undefined}
+          />
+        </svg>
+      </span>
+    )
+
+    // 單純 graphic(無 label / affix)
+    if (!hasLabel && !affixNode) return graphic
+
+    return (
+      <span className={cn('inline-flex items-center', (hasLabel || affixNode) && 'gap-2')}>
+        {graphic}
+        {hasLabel && <span className="text-fg-muted">{label}</span>}
+        {affixNode}
+      </span>
+    )
+  },
+)
+CircularProgress.displayName = 'CircularProgress'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const circularProgressMeta = {
+  component: 'CircularProgress',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: [],
+    fg: ['text-fg-muted', 'text-foreground', 'text-primary'],
+    ring: [],
+  },
+} as const
+
+export { CircularProgress }

package/src/components/Coachmark/coachmark.tsx

@@ -0,0 +1,255 @@
+// @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.
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverBody,
+  PopoverFooter,
+  PopoverHeader,
+  PopoverTitle,
+} from '@/design-system/components/Popover/popover'
+import { Button } from '@/design-system/components/Button/button'
+import { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'
+import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'
+
+/**
+ * Coachmark — 功能介紹 / onboarding tour 的浮層卡片
+ *
+ * 世界級對照:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/
+ * Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。
+ *
+ * 本元件 = **Popover 的 composition pattern**,consume 相同 overlay-surface SSOT:
+ *   - Header(可選,多步驟建議傳 `kind="tips" | "new-features" | 自訂 title`,
+ *     single-step 預設無 header 避免視覺過重)
+ *   - Media 區(圖 / 截圖 / illustration,full-width 邊緣對齊,由 AspectRatio 管比例)
+ *   - Body(SurfaceBody padding):title + description 左對齊
+ *   - Footer(SurfaceFooter padding,但 justify-between):step 計數左 / actions 右
+ *
+ * ── 單 vs 多步驟 canonical(世界級行為規則) ──
+ *   1. **Single step**(無 `onPrev` 且 `isLastStep`):CTA 文字 = `doneLabel ?? '知道了'`
+ *      (Apple HIG / Intercom 慣例;不用 "Next" 因為沒有下一步)
+ *   2. **Multi step 第一步**(無 `onPrev`,有 `onNext`):CTA = "Next",Skip 顯示
+ *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,
+ *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js
+ *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
+ *   4. **不強制 autoFocus 任何按鈕** — Radix Popover 預設 focus 第一個 focusable
+ *      (通常是 Prev 或 Skip),本元件不額外拉焦點到 Next,避免使用者以為一按 Enter
+ *      就會推進(實際上可能還在讀 body)。想推進者 tab 到 Next 再 Enter。
+ *
+ * ── 為什麼 Body+Footer 消費 overlay-surface ──
+ * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer
+ * padding(px-loose / py-tight),改 Dialog 就三邊自動跟進。
+ */
+
+interface CoachmarkStep {
+  current: number
+  total: number
+}
+
+export interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'title'> {
+  /** 控制顯示(controlled mode)*/
+  open?: boolean
+  /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */
+  children: React.ReactNode
+  /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */
+  image?: React.ReactNode
+  /**
+   * Media 區域的長寬比(ratio = 寬 / 高)。預設 `16/9`(onboarding feature tour
+   * 世界級 convention — Intercom / Pendo / Shepherd.js)。其他常用:`4/3` 產品截圖 /
+   * `1/1` 方圖 / `3/4` 直式 portrait。消費獨立的 `AspectRatio` primitive 元件。
+   */
+  mediaRatio?: number
+  /**
+   * 頂部 header 類型(多步驟 tour 建議傳)。
+   * - `'tips'` → header title = "使用技巧"
+   * - `'new-features'` → header title = "新功能介紹"
+   * - `ReactNode` → 自訂 title(string / JSX)
+   * - undefined → 無 header(單步驟常用)
+   */
+  kind?: 'tips' | 'new-features' | React.ReactNode
+  /** 標題(bold) */
+  title?: React.ReactNode
+  /** 說明文字(normal weight,多行 OK) */
+  description?: React.ReactNode
+  /** 步驟計數(2 of 3);若需多步導覽 consumer 自行管理 current */
+  step?: CoachmarkStep
+  /** Skip 按鈕 callback;不傳則不顯示 Skip。多步驟中間 / 最後步自動隱藏(有 onPrev 時) */
+  onSkip?: () => void
+  /** Next 按鈕 callback;不傳則不顯示 Next */
+  onNext?: () => void
+  /** Previous 按鈕 callback(多步 tour 第 2+ 步顯示);不傳則不顯示 */
+  onPrev?: () => void
+  /**
+   * 最後一步 flag。影響 primary CTA 文字:
+   * - single step(無 onPrev 且 isLastStep):CTA = `doneLabel ?? '知道了'`
+   * - multi-step 最後步(有 onPrev 且 isLastStep):CTA = 'Done'
+   * - 其他:CTA = 'Next'
+   */
+  isLastStep?: boolean
+  /** 自訂單步驟完成 CTA 文字(預設 `'知道了'`)。僅 single-step 使用 */
+  doneLabel?: string
+  /** 浮層定位(對齊 Popover props) */
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  align?: 'start' | 'center' | 'end'
+  sideOffset?: number
+  /** 外殼寬度(預設 w-80 = 320px,比一般 Popover 寬,因要放 media + 文字) */
+  className?: string
+}
+
+// i18n-allow: DS-internal kind → title 預設對照表;consumer 透過 `title` prop 直接覆寫
+const KIND_TITLE: Record<'tips' | 'new-features', string> = {
+  tips: '使用技巧',
+  'new-features': '新功能介紹',
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(
+  (
+    {
+      open,
+      defaultOpen,
+      onOpenChange,
+      children,
+      image,
+      mediaRatio = 16 / 9,
+      kind,
+      title,
+      description,
+      step,
+      onSkip,
+      onNext,
+      onPrev,
+      isLastStep = false,
+      doneLabel = '知道了', // i18n-allow: DS default; consumer override via doneLabel prop
+      side = 'bottom',
+      align = 'center',
+      sideOffset = OVERLAY_SIDE_OFFSET,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    // 單/多步驟行為推導
+    const isSingleStep = isLastStep && !onPrev
+    const showSkip = Boolean(onSkip) && !onPrev   // canonical:有 onPrev → 不顯示 Skip
+    const nextLabel = isSingleStep ? doneLabel : isLastStep ? 'Done' : 'Next'
+
+    const hasFooterContent = Boolean(step || showSkip || onNext || onPrev)
+    const stepText = step ? `${step.current} of ${step.total}` : null
+
+    // Header title 解析
+    const headerTitle =
+      kind === 'tips' || kind === 'new-features'
+        ? KIND_TITLE[kind as 'tips' | 'new-features']
+        : kind
+
+    return (
+      <Popover open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
+        <PopoverTrigger asChild>{children}</PopoverTrigger>
+        <PopoverContent
+          ref={ref}
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          className={cn('w-80 p-0 overflow-hidden', className)}
+          // 禁止 Radix 開啟時自動 focus 第一個 focusable(預設會 focus Prev / Skip / Next),
+          // Coachmark 的 CTA 不該被 auto-focus 偷觸發(user 可能還在讀 body,按 Enter 就推進)。
+          // 想推進的 user 自己 tab 到 CTA 即可。
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          {...props}
+        >
+          {headerTitle && (
+            // Header title 走 `<PopoverTitle>` 共用 Popover typography canonical(text-body font-medium)。
+            // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X
+            // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)
+            <PopoverHeader>
+              <PopoverTitle>{headerTitle}</PopoverTitle>
+            </PopoverHeader>
+          )}
+
+          {image && (
+            <AspectRatio ratio={mediaRatio} className="w-full overflow-hidden bg-muted">
+              {image}
+            </AspectRatio>
+          )}
+
+          {(title || description) && (
+            // 對齊 Dialog / Popover canonical:body 左對齊(不中置)
+            // Why: Coachmark 雖是 onboarding / feature discovery,但文字可讀性 > 視覺焦點;
+            // 中文 / 長句中置會「每行起點不同」造成閱讀鋸齒,左對齊最穩。
+            // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。
+            <PopoverBody className="flex flex-col">
+              {title && (
+                <h3 className="text-body-lg font-medium text-foreground">{title}</h3>
+              )}
+              {description && (
+                // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)
+                // 對齊 Dialog / Sheet canonical;移除原 gap-1(4px)drift
+                <p className="mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary">{description}</p>
+              )}
+            </PopoverBody>
+          )}
+
+          {hasFooterContent && (
+            // 專屬 Coachmark canonical:footer 無上方分隔線(media + body + footer 視覺一氣呵成,
+            // 不像 Dialog 需要 header/footer 分隔強化結構)。override SurfaceFooter default border-t
+            <PopoverFooter className="justify-between !border-t-0">
+              {stepText ? (
+                // step 文字走 text-body 跟 body content 字體一致
+                <span className="text-body text-fg-secondary tabular-nums">
+                  {stepText}
+                </span>
+              ) : (
+                <span aria-hidden /> /* 保持 justify-between space */
+              )}
+              <div className="flex items-center gap-2">
+                {onPrev && (
+                  <Button variant="tertiary" size="sm" onClick={onPrev}>
+                    Previous
+                  </Button>
+                )}
+                {showSkip && (
+                  <Button variant="tertiary" size="sm" onClick={onSkip}>
+                    Skip
+                  </Button>
+                )}
+                {onNext && (
+                  <Button variant="primary" size="sm" onClick={onNext}>
+                    {nextLabel}
+                  </Button>
+                )}
+              </div>
+            </PopoverFooter>
+          )}
+        </PopoverContent>
+      </Popover>
+    )
+  },
+)
+Coachmark.displayName = 'Coachmark'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const coachmarkMeta = {
+  component: 'Coachmark',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-muted'],
+    fg: ['text-fg-secondary', 'text-foreground'],
+    ring: [],
+  },
+} as const
+
+export { Coachmark }