@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/progress/index.tsx

@@ -0,0 +1,176 @@
+/**
+ * 进度条 Progress
+ *
+ * 基于 Radix 线性进度的 shadcn v4 升级形态：在保留不确定态语义的基础上，提供
+ * size / 语义色 / 渐进色 / 百分比文本 / 自定义渲染等业界流行能力。
+ *
+ * @when
+ * - 文件上传/下载、批量任务等需要展示百分比进度
+ * - 配额、占用率等量化指标的可视化
+ * - 操作耗时较长需要给用户即时反馈时
+ */
+
+'use client';
+
+import * as React from 'react';
+import { Progress as ProgressPrimitive } from 'radix-ui';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+// ─── Variants ───────────────────────────────────────────────────────────────
+
+const progressTrackVariants = cva(
+  'relative w-full overflow-hidden rounded-full bg-secondary',
+  {
+    variants: {
+      size: {
+        sm: 'h-1',
+        default: 'h-1.5',
+        lg: 'h-2',
+      },
+    },
+    defaultVariants: {
+      size: 'default',
+    },
+  },
+);
+
+export type ProgressSize = 'sm' | 'default' | 'lg';
+export type ProgressColor = 'default' | 'success' | 'warning' | 'destructive';
+
+const COLOR_INDICATOR: Record<ProgressColor, string> = {
+  default: 'bg-primary',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  destructive: 'bg-destructive',
+};
+
+/** progressive 渐进色阶梯：低值 destructive、中值 warning、高值 success。 */
+function pickProgressiveColor(pct: number): ProgressColor {
+  if (pct < 34) return 'destructive';
+  if (pct < 67) return 'warning';
+  return 'success';
+}
+
+// ─── Props ──────────────────────────────────────────────────────────────────
+
+export interface ProgressProps
+  extends Omit<
+      React.ComponentProps<typeof ProgressPrimitive.Root>,
+      'value' | 'max' | 'getValueLabel'
+    >,
+    VariantProps<typeof progressTrackVariants> {
+  /** 当前进度值，范围 0 ~ max；为 null 时表示不确定状态（indeterminate）。 */
+  value?: number | null;
+  /** 进度最大值。 @default 100 */
+  max?: number;
+  /** 轨道高度尺寸：sm=h-1 / default=h-1.5 / lg=h-2。 @default default */
+  size?: ProgressSize;
+  /**
+   * 语义色（对齐 ADR 0021 双 prop 语义色规范）。优先级：color > progressive。
+   * @default default
+   */
+  color?: ProgressColor;
+  /**
+   * 渐进色：未显式传 color 时按 value/max 自动选段
+   * （<34 destructive / <67 warning / ≥67 success）。
+   * @default false
+   */
+  progressive?: boolean;
+  /** 是否在右侧展示百分比文本。传入 format 时自动视为 true。 @default false */
+  showInfo?: boolean;
+  /** 自定义文本渲染函数，签名 (value, max) => ReactNode；用于替代默认百分比文本。 */
+  format?: (value: number, max: number) => React.ReactNode;
+  /**
+   * 自定义可访问性的进度文案，返回值用作 `aria-valuetext`。
+   * @param value 当前进度值
+   * @param max 进度最大值
+   */
+  getValueLabel?: (value: number, max: number) => string;
+}
+
+// ─── Component ──────────────────────────────────────────────────────────────
+
+function Progress({
+  className,
+  value,
+  max = 100,
+  size,
+  color,
+  progressive = false,
+  showInfo = false,
+  format,
+  getValueLabel,
+  ...props
+}: ProgressProps) {
+  const isIndeterminate = value == null;
+  const safeValue = isIndeterminate
+    ? 0
+    : Math.max(0, Math.min(value as number, max));
+  const pct = max > 0 ? (safeValue / max) * 100 : 0;
+
+  const effectiveColor: ProgressColor =
+    color && color !== 'default'
+      ? color
+      : progressive && !isIndeterminate
+      ? pickProgressiveColor(pct)
+      : color ?? 'default';
+
+  const showInfoEffective = !isIndeterminate && (showInfo || format != null);
+
+  const track = (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      data-size={size ?? 'default'}
+      data-color={effectiveColor}
+      data-indeterminate={isIndeterminate || undefined}
+      max={max}
+      value={isIndeterminate ? null : safeValue}
+      getValueLabel={getValueLabel ? (v, m) => getValueLabel(v, m) : undefined}
+      className={cn(
+        progressTrackVariants({ size }),
+        // flex 容器场景下，外层已带 className；非 flex 场景下，root 直接吃 className
+        !showInfoEffective && className,
+      )}
+      {...(showInfoEffective ? {} : props)}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className={cn(
+          'size-full transition-all',
+          COLOR_INDICATOR[effectiveColor],
+          isIndeterminate && 'animate-pulse',
+        )}
+        style={
+          isIndeterminate
+            ? { width: '40%' }
+            : { transform: `translateX(-${100 - pct}%)` }
+        }
+      />
+    </ProgressPrimitive.Root>
+  );
+
+  if (!showInfoEffective) {
+    // 紧凑模式：直接渲染 root，保持与历史调用（如 Upload `className="h-0.5"`）零改动兼容
+    return track;
+  }
+
+  return (
+    <div
+      data-slot="progress-root"
+      className={cn('flex w-full items-center gap-2', className)}
+      {...props}
+    >
+      {track}
+      <span
+        data-slot="progress-info"
+        className="min-w-9 shrink-0 text-right text-xs tabular-nums text-muted-foreground"
+      >
+        {format ? format(safeValue, max) : `${Math.floor(pct)}%`}
+      </span>
+    </div>
+  );
+}
+
+export { Progress, progressTrackVariants };

package/src/components/progress/meta.md

@@ -0,0 +1,95 @@
+# Progress
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+进度条 Progress
+基于 Radix 线性进度的 shadcn v4 升级形态：在保留不确定态语义的基础上，提供
+size / 语义色 / 渐进色 / 百分比文本 / 自定义渲染等业界流行能力。
+
+## 使用场景
+
+- 文件上传/下载、批量任务等需要展示百分比进度
+- 配额、占用率等量化指标的可视化
+- 操作耗时较长需要给用户即时反馈时
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `number \| null` | – | – | 当前进度值，范围 0 ~ max；为 null 时表示不确定状态（indeterminate）。 |
+| `max` | `number` | `100` | – | 进度最大值。 |
+| `size` | `ProgressSize` | `default` | – | 轨道高度尺寸：sm=h-1 / default=h-1.5 / lg=h-2。 |
+| `color` | `ProgressColor` | `default` | – | 语义色（对齐 ADR 0021 双 prop 语义色规范）。优先级：color > progressive。 |
+| `progressive` | `boolean` | `false` | – | 渐进色：未显式传 color 时按 value/max 自动选段 （<34 destructive / <67 warning / ≥67 success）。 |
+| `showInfo` | `boolean` | `false` | – | 是否在右侧展示百分比文本。传入 format 时自动视为 true。 |
+| `format` | `(value: number, max: number) => React.ReactNode` | – | – | 自定义文本渲染函数，签名 (value, max) => ReactNode；用于替代默认百分比文本。 |
+| `getValueLabel` | `(value: number, max: number) => string` | – | – | 自定义可访问性的进度文案，返回值用作 `aria-valuetext`。 |
+
+## 示例
+
+### Sizes
+
+三档轨道高度：sm=h-1 / default=h-1.5 / lg=h-2。
+
+```tsx
+<div className="flex w-64 flex-col gap-4">
+  <Progress value={60} size="sm" />
+  <Progress value={60} size="default" />
+  <Progress value={60} size="lg" />
+</div>
+```
+
+### Colors
+
+四档语义色：default / success / warning / destructive（对齐 ADR 0021）。
+
+```tsx
+<div className="flex w-64 flex-col gap-4">
+  <Progress value={60} color="default" />
+  <Progress value={60} color="success" />
+  <Progress value={60} color="warning" />
+  <Progress value={60} color="destructive" />
+</div>
+```
+
+### Progressive
+
+渐进色：按 value 自动切换颜色段（&lt;34 destructive / &lt;67 warning / ≥67 success）。
+
+```tsx
+<div className="flex w-64 flex-col gap-4">
+  <Progress value={20} progressive />
+  <Progress value={60} progressive />
+  <Progress value={90} progressive />
+</div>
+```
+
+### WithInfo
+
+开启右侧百分比文本。
+
+```tsx
+<div className="flex w-80 flex-col gap-4">
+  <Progress value={30} showInfo />
+  <Progress value={75} showInfo color="success" />
+</div>
+```
+
+### CustomFormat
+
+自定义 format 渲染：完成时切换为图标，进行中保留两位小数百分比。
+
+```tsx
+<div className="flex w-80 flex-col gap-4">
+  <Progress value={42.5} format={(v) => `${v.toFixed(2)}%`} />
+  <Progress
+    value={100}
+    color="success"
+    format={(v) =>
+      v >= 100 ? <CheckIcon className="size-3.5" /> : `${Math.floor(v)}%`
+    }
+  />
+</div>
+```

package/src/components/progress/stories.tsx

@@ -0,0 +1,115 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import { CheckIcon } from 'lucide-react';
+
+import { Progress } from './index';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Progress> = {
+  title: '反馈 · Feedback/Progress 进度条',
+  component: Progress,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 基础进度条，传入 value(0-100)。 */
+export const Default: Story = {
+  render: () => <Progress value={60} className="w-64" />,
+};
+
+/** 三档轨道高度：sm=h-1 / default=h-1.5 / lg=h-2。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex w-64 flex-col gap-4">
+      <Progress value={60} size="sm" />
+      <Progress value={60} size="default" />
+      <Progress value={60} size="lg" />
+    </div>
+  ),
+};
+
+/** 四档语义色：default / success / warning / destructive（对齐 ADR 0021）。 */
+export const Colors: Story = {
+  render: () => (
+    <div className="flex w-64 flex-col gap-4">
+      <Progress value={60} color="default" />
+      <Progress value={60} color="success" />
+      <Progress value={60} color="warning" />
+      <Progress value={60} color="destructive" />
+    </div>
+  ),
+};
+
+/** 渐进色：按 value 自动切换颜色段（&lt;34 destructive / &lt;67 warning / ≥67 success）。 */
+export const Progressive: Story = {
+  render: () => (
+    <div className="flex w-64 flex-col gap-4">
+      <Progress value={20} progressive />
+      <Progress value={60} progressive />
+      <Progress value={90} progressive />
+    </div>
+  ),
+};
+
+/** 开启右侧百分比文本。 */
+export const WithInfo: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <Progress value={30} showInfo />
+      <Progress value={75} showInfo color="success" />
+    </div>
+  ),
+};
+
+/** 自定义 format 渲染：完成时切换为图标，进行中保留两位小数百分比。 */
+export const CustomFormat: Story = {
+  render: () => (
+    <div className="flex w-80 flex-col gap-4">
+      <Progress value={42.5} format={(v) => `${v.toFixed(2)}%`} />
+      <Progress
+        value={100}
+        color="success"
+        format={(v) =>
+          v >= 100 ? <CheckIcon className="size-3.5" /> : `${Math.floor(v)}%`
+        }
+      />
+    </div>
+  ),
+};
+
+/** 不确定态：value={null} 时展示常驻动画，不显示百分比文本。 */
+export const Indeterminate: Story = {
+  render: () => <Progress value={null} className="w-64" />,
+};
+
+/** 受控加减：模拟实时进度更新，搭配 progressive 颜色自动切换。 */
+export const Controlled: Story = {
+  render: function ControlledRender() {
+    const [value, setValue] = React.useState(0);
+    return (
+      <div className="flex w-80 flex-col gap-3">
+        <div className="flex gap-2">
+          <Button
+            size="sm"
+            variant="outline"
+            disabled={value === 0}
+            onClick={() => setValue((v) => Math.max(0, v - 10))}
+          >
+            -10
+          </Button>
+          <Button
+            size="sm"
+            variant="outline"
+            disabled={value === 100}
+            onClick={() => setValue((v) => Math.min(100, v + 10))}
+          >
+            +10
+          </Button>
+        </div>
+        <Progress value={value} progressive showInfo size="lg" />
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,78 @@
+/**
+ * 单选组 RadioGroup
+ *
+ * 在一组互斥选项中选择单个项目。
+ *
+ * @when
+ * - 需要用户在一组选项中只选择一个时
+ * - 选项数量较少（2–5 个）且需要全部展示时
+ * - Select 下拉体验不如平铺直观时
+ *
+ * 组合结构：RadioGroup > RadioGroupItem（搭配外部 `<label htmlFor>` 或 `Label` 组件使用）。
+ * 按钮形态请使用 `ToggleGroup type="single"`，本组件保持 dot 单一职责。
+ */
+
+import * as React from 'react';
+import { RadioGroup as RadioGroupPrimitive } from 'radix-ui';
+import { CircleIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface RadioGroupProps
+  extends React.ComponentProps<typeof RadioGroupPrimitive.Root> {
+  /**
+   * 排列方向，同时驱动键盘方向键导航与视觉布局。
+   * - `vertical`（默认）：按 grid 垂直堆叠
+   * - `horizontal`：按 flex 横向自适应换行
+   */
+  orientation?: 'horizontal' | 'vertical';
+}
+
+export interface RadioGroupItemProps
+  extends React.ComponentProps<typeof RadioGroupPrimitive.Item> {}
+
+// ─── RadioGroup ─────────────────────────────────────────────────────────────
+
+function RadioGroup({
+  className,
+  orientation = 'vertical',
+  ...props
+}: RadioGroupProps) {
+  return (
+    <RadioGroupPrimitive.Root
+      data-slot="radio-group"
+      orientation={orientation}
+      className={cn(
+        'grid gap-2 data-[orientation=horizontal]:flex data-[orientation=horizontal]:flex-row data-[orientation=horizontal]:flex-wrap data-[orientation=horizontal]:gap-x-4 data-[orientation=horizontal]:gap-y-2',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── RadioGroupItem ─────────────────────────────────────────────────────────
+
+function RadioGroupItem({ className, ...props }: RadioGroupItemProps) {
+  return (
+    <RadioGroupPrimitive.Item
+      data-slot="radio-group-item"
+      className={cn(
+        'peer relative flex aspect-square size-4 shrink-0 cursor-pointer items-center justify-center rounded-full border border-input shadow-xs transition-[color,box-shadow] outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-[state=checked]:border-primary data-[state=checked]:text-primary',
+        className,
+      )}
+      {...props}
+    >
+      <RadioGroupPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="relative flex items-center justify-center"
+      >
+        <CircleIcon className="size-2 fill-current" />
+      </RadioGroupPrimitive.Indicator>
+    </RadioGroupPrimitive.Item>
+  );
+}
+
+export { RadioGroup, RadioGroupItem };

package/src/components/radio-group/meta.md

@@ -0,0 +1,137 @@
+# RadioGroup
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+单选组 RadioGroup
+在一组互斥选项中选择单个项目。
+
+## 使用场景
+
+- 需要用户在一组选项中只选择一个时
+- 选项数量较少（2–5 个）且需要全部展示时
+- Select 下拉体验不如平铺直观时
+- 组合结构：RadioGroup > RadioGroupItem（搭配外部 `<label htmlFor>` 或 `Label` 组件使用）。
+- 按钮形态请使用 `ToggleGroup type="single"`，本组件保持 dot 单一职责。
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | – | – | 排列方向，同时驱动键盘方向键导航与视觉布局。 - `vertical`（默认）：按 grid 垂直堆叠 - `horizontal`：按 flex 横向自适应换行 |
+
+## 示例
+
+### Horizontal
+
+水平排列：通过 `orientation="horizontal"` 同时切换键盘方向键导航与视觉布局。
+
+```tsx
+<RadioGroup orientation="horizontal" defaultValue="apple">
+  {FRUITS.map((opt) => (
+    <div key={opt.value} className="flex items-center gap-2">
+      <RadioGroupItem value={opt.value} id={`h-${opt.value}`} />
+      <label htmlFor={`h-${opt.value}`} className="text-xs">
+        {opt.label}
+      </label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+### Disabled
+
+整组禁用 + 单项禁用。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <RadioGroup defaultValue="apple" disabled>
+    {FRUITS.map((opt) => (
+      <div key={opt.value} className="flex items-center gap-2">
+        <RadioGroupItem value={opt.value} id={`gd-${opt.value}`} />
+        <label
+          htmlFor={`gd-${opt.value}`}
+          className="text-xs text-muted-foreground"
+        >
+          {opt.label}
+        </label>
+      </div>
+    ))}
+  </RadioGroup>
+  <RadioGroup defaultValue="apple">
+    {[
+      { value: 'apple', label: '苹果' },
+      { value: 'banana', label: '香蕉', disabled: true },
+      { value: 'orange', label: '橙子' },
+    ].map((opt) => (
+      <div key={opt.value} className="flex items-center gap-2">
+        <RadioGroupItem
+          value={opt.value}
+          id={`id-${opt.value}`}
+          disabled={opt.disabled}
+        />
+        <label
+          htmlFor={`id-${opt.value}`}
+          className={
+            opt.disabled ? 'text-xs text-muted-foreground' : 'text-xs'
+          }
+        >
+          {opt.label}
+        </label>
+      </div>
+    ))}
+  </RadioGroup>
+</div>
+```
+
+### WithList
+
+数据驱动写法：业务侧用 `.map` 渲染，无需内置 `dataSource`。
+
+```tsx
+<RadioGroup defaultValue="banana">
+  {FRUITS.map((opt) => (
+    <div key={opt.value} className="flex items-center gap-2">
+      <RadioGroupItem
+        value={opt.value}
+        id={`l-${opt.value}`}
+        disabled={opt.disabled}
+      />
+      <label htmlFor={`l-${opt.value}`} className="text-xs">
+        {opt.label}
+      </label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+### WithAriaLabelledby
+
+无障碍：用 `aria-labelledby` 关联组级标题文案。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <span id="lang-label" className="text-xs">
+    编程语言
+  </span>
+  <RadioGroup
+    orientation="horizontal"
+    aria-labelledby="lang-label"
+    defaultValue="ts"
+  >
+    {[
+      { value: 'ts', label: 'TypeScript' },
+      { value: 'go', label: 'Go' },
+      { value: 'rs', label: 'Rust' },
+    ].map((opt) => (
+      <div key={opt.value} className="flex items-center gap-2">
+        <RadioGroupItem value={opt.value} id={`a-${opt.value}`} />
+        <label htmlFor={`a-${opt.value}`} className="text-xs">
+          {opt.label}
+        </label>
+      </div>
+    ))}
+  </RadioGroup>
+</div>
+```