@qijenchen/design-system 0.1.0-beta.3

package/src/components/ProgressBar/progress-bar.tsx

@@ -0,0 +1,157 @@
+// @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 * as ProgressPrimitive from '@radix-ui/react-progress'
+import { CircleCheck, XCircle } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+/**
+ * ProgressBar — 水平進度條(determinate)
+ *
+ * 世界級對照:Material `LinearProgress` / Ant `Progress` / Polaris `ProgressBar` /
+ * shadcn `Progress`(皆為 Radix Progress primitive 的包裝)。本 DS 命名為
+ * `ProgressBar`(linear)以和 `CircularProgress`(circular)做清楚區分。
+ *
+ * ── 與 CircularProgress 的分界 ──
+ * CircularProgress = circular 兩態(indeterminate 旋轉 / determinate arc),inline 小空間
+ * ProgressBar      = linear determinate(0-100% 已知量化),頁面級大區塊 / 表單 wizard / quota
+ * 兩者視覺與語意都不同,consumer 依「形狀(linear / circular)+ 是否量化」擇一。
+ *
+ * ── 與 FileItem 的分界(2026-04-20 user 決策) ──
+ * **檔案上傳 UI 走 `FileItem`,不直接消費 ProgressBar**。FileItem 是檔案上傳情境的
+ * canonical consumer-facing primitive(檔名 / icon / 進度 / status / actions 一條龍);
+ * FileItem 內部可能消費 ProgressBar(engineering 實作細節),consumer 不用也不該自己
+ * 組合 raw ProgressBar + 檔名 + action 來做上傳列表。世界級對照:Ant Design 的 `Upload`
+ * vs `Progress`(Upload.List 內部用 Progress,consumer 不直接用 Progress 做上傳 UI)。
+ *
+ * ── 3 狀態,單一 size ──
+ * status: inProgress(進行中藍) / success(完成綠) / error(失敗紅)
+ *   ^ 命名理由:`status` 是 lifecycle(在途 / 終態),不是視覺 emphasis 階。前身
+ *   `primary` 會撞 Button `variant="primary"`(emphasis 最高階),改用世界級
+ *   lifecycle 慣例(Polaris `inProgress` / Ant Progress `active`)。
+ *
+ * **單一高度 4px**(2026-04-20 user 決策):對齊 Material 3 / Carbon / Ant 慣例
+ * (固定 4dp/px 不給 size 選項)。4px 是 linear progress 的業界 canonical;若需
+ * 視覺強調改用 CircularProgress + label 或改做 full-width hero 版型,不靠 size
+ * 階梯撐。移除前的 sm(2)/ md(4)/ lg(6)刻度差太小,無實質視覺區分。
+ *
+ * ── affix(右側附加) ──
+ * `affix="value"` → 顯示 `{value}%` 文字
+ * `affix="status-icon"` → 顯示狀態 icon(success ✓ / error ✗;inProgress 時無 icon)
+ * `affix={<custom />}` → consumer 客製
+ * 不傳 → 純 bar
+ */
+
+const DEFAULT_TRACK_H = 4 // 預設 4px(見 docblock「單一高度」)
+const STATUS_FILL = {
+  inProgress: 'bg-primary',
+  success: 'bg-success',
+  error: 'bg-error',
+} as const
+const STATUS_ICON = {
+  success: { Icon: CircleCheck, className: 'text-success' },
+  error:   { Icon: XCircle,     className: 'text-error' },
+} as const
+
+export interface ProgressBarProps extends Omit<React.ComponentProps<typeof ProgressPrimitive.Root>, 'value'> {
+  /** 當前進度 0-100 */
+  value: number
+  /** 狀態色(lifecycle,非 emphasis 階) */
+  status?: 'inProgress' | 'success' | 'error'
+  /** 右側附加 */
+  affix?: 'value' | 'status-icon' | React.ReactNode
+  /**
+   * Track 高度(px)override。**預設 4**(對齊 Material / Carbon / Ant canonical)。
+   *
+   * **非公開 size 階**——這不是給 consumer 自由選擇粗細的 API,而是給**內部另一個
+   * DS 元件(FileItem)在極密集 row layout 下壓低到 2px** 的逃生艙。Consumer 端
+   * 一律走預設 4px。未來若新 primitive(例如 health-bar 型 hero progress)需要
+   * 較高的 track,再評估是否擴公開 API。
+   *
+   * 世界級對照:Ant `<Progress>` 有 `strokeWidth` 原生 prop;本 DS 只暴露給內部
+   * 元件使用,不在 public API 宣傳,避免 consumer 重新陷入「選哪個 size」的判斷負擔。
+   */
+  height?: number
+}
+
+const ProgressBar = React.forwardRef<HTMLDivElement, ProgressBarProps>(
+  (
+    {
+      value,
+      status = 'inProgress',
+      affix,
+      height,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const clampedValue = Math.max(0, Math.min(100, value))
+    const fillColor = STATUS_FILL[status]
+    const trackH = height ?? DEFAULT_TRACK_H
+
+    // Affix 渲染
+    let affixNode: React.ReactNode = null
+    if (affix === 'value') {
+      affixNode = (
+        <span className="text-caption text-foreground tabular-nums shrink-0">
+          {Math.round(clampedValue)}%
+        </span>
+      )
+    } else if (affix === 'status-icon') {
+      const s = status !== 'inProgress' ? STATUS_ICON[status] : null
+      if (s) affixNode = <s.Icon size={16} className={cn('shrink-0', s.className)} aria-hidden />
+    } else if (React.isValidElement(affix) || typeof affix === 'string' || typeof affix === 'number') {
+      affixNode = affix
+    }
+
+    const bar = (
+      <ProgressPrimitive.Root
+        ref={ref}
+        value={clampedValue}
+        max={100}
+        className={cn(
+          'relative overflow-hidden rounded-full bg-secondary w-full',
+          className,
+        )}
+        style={{ height: trackH }}
+        {...props}
+      >
+        <ProgressPrimitive.Indicator
+          className={cn('h-full rounded-full transition-all duration-300', fillColor)}
+          style={{ width: `${clampedValue}%` }}
+        />
+      </ProgressPrimitive.Root>
+    )
+
+    if (!affixNode) return bar
+
+    return (
+      <div className="flex items-center gap-2 w-full">
+        <div className="flex-1 min-w-0">{bar}</div>
+        {affixNode}
+      </div>
+    )
+  },
+)
+ProgressBar.displayName = 'ProgressBar'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const progressBarMeta = {
+  component: 'ProgressBar',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-error', 'bg-primary', 'bg-secondary', 'bg-success'],
+    fg: ['text-foreground'],
+    ring: [],
+  },
+} as const
+
+export { ProgressBar }

package/src/components/README.md

@@ -0,0 +1,58 @@
+# components/ Charter
+
+## 這裡只收:元件家族的 folder
+
+每個元件家族一個 PascalCase folder,內含:
+- `{name}.tsx` — 元件本體
+- `{name}.spec.md` — 設計原則
+- `{name}.stories.tsx` — 展示
+- `{name}.anatomy.stories.tsx` — 設計規格
+- `{name}.principles.stories.tsx` — 設計原則 stories
+- 子檔案視元件需要(`{name}-context.ts` / `{name}-types.ts` 等)
+
+**folder 名**: PascalCase(`Button/` / `DatePicker/`)
+**file 名**: kebab-case(`button.tsx` / `date-picker.tsx`)
+
+## Compound component family(多元件 + 共享規則)
+
+部分 folder 是**元件家族 home**,houses 多個緊耦合 primitive + 共享規則 spec。對齊 Ant Design `Checkbox.Group` / Mantine `Checkbox.Group` / Chakra compound pattern 世界級慣例:tightly coupled primitives 同資料夾而非拆分。
+
+現有 compound folders:
+- `Field/` — `field.tsx` + `field-wrapper.tsx` + `field-context.ts` + `field-types.ts` + `field-controls.spec.md`(跨 form 元件共享 mode/disabled/readonly 規則)+ `form-validation.spec.md`(表單驗證跨 primitive 規則,**無 Layout Family — behavior spec 非元件**)
+- `Checkbox/` — `checkbox.tsx` + `checkbox-group.tsx`(2026-04-21 CheckboxGroup merge 自 separate folder,對齊 standalone + group 世界級慣例)+ `boolean-display.tsx`(table cell 顯示)
+- `Menu/` — `menu-item.tsx`(家族預留位)
+- `SelectionControl/` — `selection-item.tsx`(Checkbox/Radio 共享的 row layout primitive home)
+
+**判斷 compound vs 單獨 folder**:
+- 元件能**獨立 lifecycle / 獨立使用** → 各自獨立 folder(Button / Input / Select)
+- 元件**同家族共享 context / 命名 / 規則** → compound folder(Field / Checkbox / Menu)
+- 新元件若模糊,先問「能不能不依賴同家族其他元件獨立使用」— 能 → 獨立 folder;不能 → compound family
+
+## 這裡**不收**(反例)
+
+| 疑似要放這但其實不是 | 實際應去 | 為什麼 |
+|-------------------|---------|--------|
+| 平坦 `.md` 檔(`components/foo.md`) | Skill / CLAUDE.md / spec | 本 dir 慣例是 PascalCase folder,平坦 md 破壞結構 |
+| 跨元件共用的 checklist | `.claude/skills/component-quality-gate/` | 是 invoke-time workflow |
+| 跨元件 runtime primitive | `../patterns/` | 本 dir 是單元件,跨元件去 patterns |
+| 命名規則 / Props 命名慣例 | `CLAUDE.md` | 每 session signal |
+
+## 新元件進來的條件
+
+進 `components/` 前:
+1. 走 `.claude/skills/component-quality-gate/`(完整 checklist)
+2. 聲明 Layout Family(第一段 spec 必含,見 `patterns/element-anatomy/element-anatomy.spec.md`「4-Family Model Taxonomy」)
+3. 對標至少 2 個世界級 DS 的相似元件
+4. spec 第一段寫明實作基礎(Radix X / cmdk / native / 自建+理由)
+
+## Internal primitive vs Public 元件
+
+兩類都住同一個 folder,差別在:
+- **Public**(Components/):有預設視覺,consumer 直接 `<X>` 就能用 — Storybook title `Design System/Components/{Name}`
+- **Internal primitive**(Internal/):無預設視覺,必被 wrapper 元件包 — Storybook title `Design System/Internal/{Name}`
+
+判斷 test 見 `.claude/rules/story-rules.md` → 「Internal vs Components 三 test」。
+
+## 建立前必 Read
+
+本 README + 該元件所在 pattern spec(若屬 Family) + `.claude/rules/ui-development.md`「元件 Props 命名」 + `.claude/skills/component-quality-gate/`。

package/src/components/RadioGroup/radio-group.tsx

@@ -0,0 +1,261 @@
+// @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 * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
+import { Circle } from "lucide-react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import type { FieldMode, FieldVariant } from "@/design-system/components/Field/field-types"
+import { useFieldContext } from "@/design-system/components/Field/field-context"
+import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
+import { EMPTY_DISPLAY } from "@/design-system/components/Field/field-wrapper"
+
+// ── RadioGroup display context ──────────────────────────────────────────────
+// RadioGroup mode='display' 時:Group 不渲染 Radix primitive(無 radio 視覺),
+// 改透過 Context 通知 child RadioGroupItem「我在 display mode、selected value 是 X」;
+// item 自決 — 命中 selected 渲染 label 純文字,未命中 render null。
+// 為什麼用 context(不是 RadioGroup 自己解析 children):children 可能是任意巢狀
+// (Field 包 RadioGroup,內含 RadioGroupItem 散在 fragment / 條件式內),強行 walk children
+// 會破壞 React composability;用 context 讓 item 自己判定是 idiom 對齊 Radix 原生模型。
+interface RadioGroupDisplayContextValue {
+  displayMode: true
+  selectedValue?: string
+}
+const RadioGroupDisplayContext = React.createContext<RadioGroupDisplayContextValue | null>(null)
+
+// ── RadioGroup ──────────────────────────────────────────────────────────────
+
+export interface RadioGroupProps
+  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {
+  /**
+   * Field mode(2026-05-05 Phase B3 align):
+   *   edit     — 一般可互動 RadioGroup(預設)
+   *   display  — **純展示**:不渲染 Radix Root / 任何 radio 視覺,僅 child item 中
+   *              value === group.value 那筆把 label 渲染為純文字 span;其他 item render null。
+   *              對齊 Carbon read-only / DataTable single-select cell read mode。
+   *   readonly — 同 child item 各自 readOnly:radio 視覺保留 + 鎖互動
+   *   disabled — 同 RadioGroupPrimitive.Root disabled 屬性
+   */
+  mode?: FieldMode
+  /**
+   * Visual chrome — RadioGroup 本體無 input wrapper variant,本 prop 對主體無視覺影響;
+   * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。
+   */
+  variant?: FieldVariant
+}
+
+const RadioGroup = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Root>,
+  RadioGroupProps
+>(({ className, mode, variant: _chrome, value, defaultValue, ...props }, ref) => {
+  // mode='display' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。
+  // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。
+  // 實作:walk children 找 control.value === selectedValue 的 SelectionItem,render label plain text。
+  // (不用 context dispatch 給 RadioGroupItem — SelectionItem layout wrapper 仍會渲染所有 item label)
+  if (mode === 'display') {
+    const selectedValue = (value ?? defaultValue) as string | undefined
+    if (!selectedValue) {
+      return <div role="group" className={cn('grid', className)}><span className="text-fg-muted">{EMPTY_DISPLAY}</span></div>
+    }
+    let selectedLabel: React.ReactNode = null
+    React.Children.forEach(props.children, (child) => {
+      if (!React.isValidElement(child)) return
+      const cProps = child.props as { control?: unknown; label?: React.ReactNode }
+      const control = cProps.control
+      if (React.isValidElement(control)) {
+        const controlValue = (control.props as { value?: unknown }).value
+        if (controlValue === selectedValue) {
+          selectedLabel = cProps.label ?? selectedValue
+        }
+      }
+    })
+    return (
+      <div role="group" className={cn('grid', className)}>
+        <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
+      </div>
+    )
+  }
+
+  return (
+    <RadioGroupPrimitive.Root
+      className={cn("grid", className)}
+      value={value}
+      defaultValue={defaultValue}
+      {...props}
+      ref={ref}
+    />
+  )
+})
+RadioGroup.displayName = 'RadioGroup'
+// Field layout 宣告：RadioGroup 是 block primitive（多項堆疊），
+// 進入 <Field> 時 control area 自動切 items-start + padding-top 公式對齊。
+// Convention 詳見 components/Field/field.spec.md「Control area:Inline vs Block」段落。
+;(RadioGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'
+
+// ── RadioGroupItem Variants ─────────────────────────────────────────────────
+// 與 Checkbox 完全對齊：sm/md=16px, lg=20px。差異只有形狀（rounded-full）和指示器（filled dot）。
+
+const radioItemVariants = cva(
+  [
+    'grid place-content-center shrink-0 rounded-full',
+    'border border-border bg-surface',
+    'transition-colors duration-150',
+    'hover:border-border-hover',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+    'data-[state=checked]:border-primary data-[state=checked]:text-primary',
+    'data-[state=checked]:hover:border-primary-hover data-[state=checked]:hover:text-primary-hover',
+    'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',
+    'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:border-transparent disabled:data-[state=checked]:text-fg-disabled',
+    // readOnly：鎖定互動但維持 checked/unchecked 視覺
+    'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',
+    'data-[readonly=true]:hover:border-border',
+  ],
+  {
+    variants: {
+      size: {
+        sm: 'h-4 w-4',
+        md: 'h-4 w-4',
+        lg: 'h-5 w-5',
+      },
+    },
+    defaultVariants: {
+      size: 'md',
+    },
+  }
+)
+
+// ── Dot Size ────────────────────────────────────────────────────────────────
+const dotSize: Record<string, number> = { sm: 8, md: 8, lg: 10 }
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+type RadioItemPrimitiveProps = React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
+
+export interface RadioGroupItemProps
+  extends RadioItemPrimitiveProps,
+    VariantProps<typeof radioItemVariants> {
+  /**
+   * Inline label。提供時 RadioGroupItem 自動透過 SelectionItem 包裝，
+   * 套用 codified 樣式（text-body / text-foreground / disabled 色）。
+   * 在 <Field> context 內時此 prop 仍然生效（Radio 的 label 是每個 item
+   * 各自的，不是整組 Field 的；FieldLabel 是 RadioGroup 整體的 label）。
+   */
+  label?: React.ReactNode
+  /**
+   * Inline description（secondary 文字）。須與 label 搭配使用。
+   * 套用 text-body / text-fg-secondary 樣式。
+   */
+  description?: React.ReactNode
+  /**
+   * readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。
+   * 通常整個 RadioGroup 一起設 readonly（由 parent RadioGroup 的 disabled
+   * 或 readonly 行為決定），個別 item 也可設。
+   */
+  readOnly?: boolean
+}
+
+// ── RadioGroupItem ──────────────────────────────────────────────────────────
+
+const RadioGroupItem = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Item>,
+  RadioGroupItemProps
+>(
+  (
+    {
+      className,
+      size,
+      label,
+      description,
+      readOnly = false,
+      disabled,
+      id: idProp,
+      ...props
+    },
+    ref
+  ) => {
+    const sizeKey = size ?? 'md'
+    const dotPx = dotSize[sizeKey]
+
+    // ── RadioGroup mode='display' branch ──────────────────────────────────
+    // 命中 selected → 渲染 label 純文字 span;未命中 → render null(group 內只剩 selected 的 label)。
+    // 設計理由:對齊 Carbon read-only single-select 「只顯示 selected 內容、不列其他選項」原則。
+    const displayCtx = React.useContext(RadioGroupDisplayContext)
+    if (displayCtx?.displayMode) {
+      if (displayCtx.selectedValue !== props.value) return null
+      return <span className="text-foreground">{label ?? props.value}</span>
+    }
+
+    // 注意：Radio 的 label 語意與 Checkbox/Switch 不同——
+    // Checkbox/Switch 的 label 就是該 control 的唯一 label（被 Field context 接管），
+    // RadioGroupItem 的 label 是「該選項」的 label（每 item 各自擁有），
+    // FieldLabel 則是整個 RadioGroup 的 label。
+    // 因此 RadioGroupItem 的 label 不因 Field context 被忽略。
+    const fieldCtx = useFieldContext()
+
+    const generatedId = React.useId()
+    const inputId = idProp ?? generatedId
+
+    const rootEl = (
+      <RadioGroupPrimitive.Item
+        id={inputId}
+        ref={ref}
+        disabled={disabled}
+        aria-readonly={readOnly || undefined}
+        data-readonly={readOnly || undefined}
+        tabIndex={readOnly ? -1 : undefined}
+        className={cn(radioItemVariants({ size }), className)}
+        {...props}
+      >
+        <RadioGroupPrimitive.Indicator className="grid place-content-center">
+          <Circle
+            style={{ width: dotPx, height: dotPx }}
+            className="fill-current text-current"
+          />
+        </RadioGroupPrimitive.Indicator>
+      </RadioGroupPrimitive.Item>
+    )
+
+    // 無 label → 只渲染 radio 本體
+    if (label == null) return rootEl
+
+    // 有 label → 透過 SelectionItem 包裝，與 Checkbox 一致
+    // 同時繼承 Field context 的 disabled（若 RadioGroup 在 Field disabled 內）
+    const resolvedDisabled = disabled ?? fieldCtx?.disabled ?? false
+
+    return (
+      <SelectionItem
+        control={rootEl}
+        label={label}
+        description={description}
+        htmlFor={inputId}
+        disabled={resolvedDisabled}
+        size={sizeKey}
+      />
+    )
+  }
+)
+RadioGroupItem.displayName = 'RadioGroupItem'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const radioGroupMeta = {
+  component: 'RadioGroup',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-disabled', 'bg-surface'],
+    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],
+    ring: ['ring-ring'],
+  },
+  defaultSize: 'md',
+} as const
+
+export { RadioGroup, RadioGroupItem, radioItemVariants }