@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/steps/meta.md

@@ -0,0 +1,245 @@
+# Steps
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+步骤条 Steps
+引导用户按流程完成任务的导航条，展示当前所处步骤。
+支持三种形态：circle（圆圈带数字）、dot（小圆点）、arrow（箭头色带）。
+
+## 使用场景
+
+- 任务需分多步完成且步骤间有先后顺序
+- 需要清晰展示当前进度和各步骤状态
+- 配合表单向导、创建流程等场景
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `items` | `StepItem[]` | – | ✓ | 步骤列表。 |
+| `current` | `number` | `0` | – | 当前步骤（0-based）。current 之前为 finish，当前为 process，之后为 wait。 |
+| `status` | `'process' \| 'error'` | `"process"` | – | 当前步骤的状态。 |
+| `shape` | `'circle' \| 'dot' \| 'arrow'` | `"circle"` | – | 步骤点形态。arrow 为箭头色带，circle 为圆圈带数字，dot 为小圆点。 |
+| `direction` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 排列方向（arrow 形态仅支持 horizontal）。 |
+| `labelPlacement` | `'horizontal' \| 'vertical'` | `"vertical"` | – | 标签放置方向（circle/dot 生效）。vertical 标签在指示器下方，horizontal 标签在右侧。 |
+| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸。 |
+| `onChange` | `(index: number) => void` | – | – | 步骤点击回调。传入后各步骤可点击。 |
+
+## 示例
+
+### ShapeArrow
+
+Arrow 形态——色带箭头风格，适合简洁的步骤导航。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Steps
+    shape="arrow"
+    current={1}
+    items={[
+      { title: '选择模板' },
+      { title: '填写信息' },
+      { title: '完成创建' },
+    ]}
+  />
+  <Steps
+    shape="arrow"
+    current={2}
+    items={[
+      { title: '上传' },
+      { title: '校验' },
+      { title: '导入' },
+      { title: '完成' },
+    ]}
+  />
+</div>
+```
+
+### ShapeCircle
+
+Circle 形态——圆圈内显示序号/勾选/错误图标，标签在下方居中。
+
+```tsx
+<Steps
+  shape="circle"
+  current={1}
+  items={[
+    { title: '账户信息', description: '填写基本信息' },
+    { title: '验证邮箱', description: '收取验证码' },
+    { title: '完成注册', description: '设置密码' },
+  ]}
+/>
+```
+
+### ShapeDot
+
+Dot 形态——小圆点指示器，视觉最轻量。
+
+```tsx
+<Steps
+  shape="dot"
+  current={1}
+  items={[
+    { title: '提交申请', description: '已提交' },
+    { title: '审核中', description: '预计 1-2 个工作日' },
+    { title: '审核完成' },
+  ]}
+/>
+```
+
+### LabelHorizontal
+
+labelPlacement="horizontal"——标签在指示器右侧水平排列。
+
+```tsx
+<div className="flex flex-col gap-8">
+  <Steps
+    shape="circle"
+    current={1}
+    labelPlacement="horizontal"
+    items={basicItems}
+  />
+  <Steps
+    shape="dot"
+    current={1}
+    labelPlacement="horizontal"
+    items={basicItems}
+  />
+</div>
+```
+
+### Vertical
+
+垂直方向步骤条（适合侧栏场景）。
+
+```tsx
+<div className="flex gap-12">
+  <div className="w-56">
+    <Steps
+      direction="vertical"
+      shape="circle"
+      current={2}
+      items={[
+        { title: '创建项目', description: '已完成' },
+        { title: '安装依赖', description: '已完成' },
+        { title: '启动开发', description: '进行中' },
+        { title: '部署上线' },
+      ]}
+    />
+  </div>
+  <div className="w-56">
+    <Steps
+      direction="vertical"
+      shape="dot"
+      current={1}
+      items={[
+        { title: '提交代码', description: '已提交至主分支' },
+        { title: 'CI 构建', description: '正在执行' },
+        { title: '部署预发' },
+        { title: '发布上线' },
+      ]}
+    />
+  </div>
+</div>
+```
+
+### ErrorStatus
+
+错误状态——当前步骤标红提示。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Steps
+    shape="circle"
+    current={1}
+    status="error"
+    items={[
+      { title: '上传文件' },
+      { title: '校验数据', description: '发现格式错误' },
+      { title: '导入完成' },
+    ]}
+  />
+  <Steps
+    shape="arrow"
+    current={1}
+    status="error"
+    items={[{ title: '上传' }, { title: '校验失败' }, { title: '导入' }]}
+  />
+</div>
+```
+
+### Small
+
+小尺寸——紧凑场景下使用。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Steps
+    size="sm"
+    shape="circle"
+    current={1}
+    items={[{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]}
+  />
+  <Steps
+    size="sm"
+    shape="dot"
+    current={1}
+    items={[{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]}
+  />
+  <Steps
+    size="sm"
+    shape="arrow"
+    current={1}
+    items={[{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]}
+  />
+</div>
+```
+
+### AllStatuses
+
+所有状态一览。
+
+```tsx
+<Steps
+  current={1}
+  shape="circle"
+  items={[
+    { title: 'Finish', description: '已完成', status: 'finish' },
+    { title: 'Process', description: '进行中', status: 'process' },
+    { title: 'Wait', description: '等待中', status: 'wait' },
+    { title: 'Error', description: '失败', status: 'error' },
+    { title: 'Disabled', description: '不可用', status: 'disabled' },
+  ]}
+/>
+```
+
+### WithDisabled
+
+禁用某一步骤。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Steps
+    shape="circle"
+    current={1}
+    items={[
+      { title: '选择模板' },
+      { title: '填写信息' },
+      { title: '高级配置', status: 'disabled' },
+      { title: '完成' },
+    ]}
+  />
+  <Steps
+    shape="arrow"
+    current={1}
+    items={[
+      { title: '步骤 1' },
+      { title: '步骤 2' },
+      { title: '步骤 3', status: 'disabled' },
+      { title: '步骤 4' },
+    ]}
+  />
+</div>
+```

package/src/components/steps/stories.tsx

@@ -0,0 +1,287 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { Steps } from './index';
+
+const meta: Meta<typeof Steps> = {
+  title: '导航 · Navigation/Steps 步骤条',
+  component: Steps,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const basicItems = [
+  { title: '基本信息', description: '填写名称和描述' },
+  { title: '配置规则', description: '设置触发条件' },
+  { title: '确认提交', description: '检查并提交' },
+];
+
+/**
+ * 三种形态总览：Arrow（箭头色带）、Circle（圆圈带数字）、Dot（小圆点）。
+ * Circle 和 Dot 另有 `labelPlacement` 控制标签在下方或右侧。
+ */
+export const Default: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <section>
+        <h3 className="mb-3 text-sm font-medium text-muted-foreground">
+          Arrow
+        </h3>
+        <Steps shape="arrow" current={1} items={basicItems} />
+      </section>
+
+      <section>
+        <h3 className="mb-3 text-sm font-medium text-muted-foreground">
+          Circle
+        </h3>
+        <Steps shape="circle" current={1} items={basicItems} />
+      </section>
+
+      <section>
+        <h3 className="mb-3 text-sm font-medium text-muted-foreground">
+          Circle (labelPlacement=horizontal)
+        </h3>
+        <Steps
+          shape="circle"
+          current={1}
+          labelPlacement="horizontal"
+          items={basicItems}
+        />
+      </section>
+
+      <section>
+        <h3 className="mb-3 text-sm font-medium text-muted-foreground">Dot</h3>
+        <Steps shape="dot" current={1} items={basicItems} />
+      </section>
+    </div>
+  ),
+};
+
+/** Arrow 形态——色带箭头风格，适合简洁的步骤导航。 */
+export const ShapeArrow: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <Steps
+        shape="arrow"
+        current={1}
+        items={[
+          { title: '选择模板' },
+          { title: '填写信息' },
+          { title: '完成创建' },
+        ]}
+      />
+      <Steps
+        shape="arrow"
+        current={2}
+        items={[
+          { title: '上传' },
+          { title: '校验' },
+          { title: '导入' },
+          { title: '完成' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+/** Circle 形态——圆圈内显示序号/勾选/错误图标，标签在下方居中。 */
+export const ShapeCircle: Story = {
+  render: () => (
+    <Steps
+      shape="circle"
+      current={1}
+      items={[
+        { title: '账户信息', description: '填写基本信息' },
+        { title: '验证邮箱', description: '收取验证码' },
+        { title: '完成注册', description: '设置密码' },
+      ]}
+    />
+  ),
+};
+
+/** Dot 形态——小圆点指示器，视觉最轻量。 */
+export const ShapeDot: Story = {
+  render: () => (
+    <Steps
+      shape="dot"
+      current={1}
+      items={[
+        { title: '提交申请', description: '已提交' },
+        { title: '审核中', description: '预计 1-2 个工作日' },
+        { title: '审核完成' },
+      ]}
+    />
+  ),
+};
+
+/** labelPlacement="horizontal"——标签在指示器右侧水平排列。 */
+export const LabelHorizontal: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <Steps
+        shape="circle"
+        current={1}
+        labelPlacement="horizontal"
+        items={basicItems}
+      />
+      <Steps
+        shape="dot"
+        current={1}
+        labelPlacement="horizontal"
+        items={basicItems}
+      />
+    </div>
+  ),
+};
+
+/** 垂直方向步骤条（适合侧栏场景）。 */
+export const Vertical: Story = {
+  render: () => (
+    <div className="flex gap-12">
+      <div className="w-56">
+        <Steps
+          direction="vertical"
+          shape="circle"
+          current={2}
+          items={[
+            { title: '创建项目', description: '已完成' },
+            { title: '安装依赖', description: '已完成' },
+            { title: '启动开发', description: '进行中' },
+            { title: '部署上线' },
+          ]}
+        />
+      </div>
+      <div className="w-56">
+        <Steps
+          direction="vertical"
+          shape="dot"
+          current={1}
+          items={[
+            { title: '提交代码', description: '已提交至主分支' },
+            { title: 'CI 构建', description: '正在执行' },
+            { title: '部署预发' },
+            { title: '发布上线' },
+          ]}
+        />
+      </div>
+    </div>
+  ),
+};
+
+/** 错误状态——当前步骤标红提示。 */
+export const ErrorStatus: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <Steps
+        shape="circle"
+        current={1}
+        status="error"
+        items={[
+          { title: '上传文件' },
+          { title: '校验数据', description: '发现格式错误' },
+          { title: '导入完成' },
+        ]}
+      />
+      <Steps
+        shape="arrow"
+        current={1}
+        status="error"
+        items={[{ title: '上传' }, { title: '校验失败' }, { title: '导入' }]}
+      />
+    </div>
+  ),
+};
+
+/** 小尺寸——紧凑场景下使用。 */
+export const Small: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <Steps
+        size="sm"
+        shape="circle"
+        current={1}
+        items={[{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]}
+      />
+      <Steps
+        size="sm"
+        shape="dot"
+        current={1}
+        items={[{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]}
+      />
+      <Steps
+        size="sm"
+        shape="arrow"
+        current={1}
+        items={[{ title: '第一步' }, { title: '第二步' }, { title: '第三步' }]}
+      />
+    </div>
+  ),
+};
+
+/** 可点击步骤——传入 onChange 后步骤可交互切换。 */
+export const Clickable: Story = {
+  render: function ClickableSteps() {
+    const [current, setCurrent] = useState(0);
+    return (
+      <div className="flex flex-col gap-6">
+        <Steps
+          shape="circle"
+          current={current}
+          onChange={setCurrent}
+          items={[
+            { title: '选择类型', description: '点击可跳转' },
+            { title: '填写内容', description: '点击可跳转' },
+            { title: '确认发布', description: '点击可跳转' },
+          ]}
+        />
+        <p className="text-xs text-muted-foreground">当前步骤：{current + 1}</p>
+      </div>
+    );
+  },
+};
+
+/** 所有状态一览。 */
+export const AllStatuses: Story = {
+  render: () => (
+    <Steps
+      current={1}
+      shape="circle"
+      items={[
+        { title: 'Finish', description: '已完成', status: 'finish' },
+        { title: 'Process', description: '进行中', status: 'process' },
+        { title: 'Wait', description: '等待中', status: 'wait' },
+        { title: 'Error', description: '失败', status: 'error' },
+        { title: 'Disabled', description: '不可用', status: 'disabled' },
+      ]}
+    />
+  ),
+};
+
+/** 禁用某一步骤。 */
+export const WithDisabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <Steps
+        shape="circle"
+        current={1}
+        items={[
+          { title: '选择模板' },
+          { title: '填写信息' },
+          { title: '高级配置', status: 'disabled' },
+          { title: '完成' },
+        ]}
+      />
+      <Steps
+        shape="arrow"
+        current={1}
+        items={[
+          { title: '步骤 1' },
+          { title: '步骤 2' },
+          { title: '步骤 3', status: 'disabled' },
+          { title: '步骤 4' },
+        ]}
+      />
+    </div>
+  ),
+};

package/src/components/switch/index.tsx

@@ -0,0 +1,175 @@
+/**
+ * 开关 Switch
+ *
+ * 用于在两种状态间切换（开/关），类似物理开关。
+ *
+ * @when
+ * - 需要表示"开/关"两态切换时（如启用/禁用功能）
+ * - Checkbox 语义不够直观，需要更强视觉反馈时
+ * - 需要异步保存切换结果时（配合 `loading`）
+ *
+ * 组合结构：搭配外部 `<label htmlFor>` 或 `Label` 组件使用；可通过
+ * `checkedChildren` / `unCheckedChildren` 在 track 内嵌入文本或图标，
+ * track 宽度自适应内文长度。
+ */
+
+import * as React from 'react';
+import { Switch as SwitchPrimitive } from 'radix-ui';
+import { cva } from 'class-variance-authority';
+import { Loader2Icon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── cva ────────────────────────────────────────────────────────────────────
+
+const switchVariants = cva(
+  'peer group/switch relative inline-flex shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input data-disabled:cursor-not-allowed data-disabled:opacity-50 data-[loading=true]:pointer-events-none data-[loading=true]:opacity-70',
+  {
+    variants: {
+      size: {
+        sm: 'h-4',
+        default: 'h-5',
+      },
+      hasChildren: {
+        true: 'min-w-fit',
+        false: '',
+      },
+    },
+    compoundVariants: [
+      { size: 'sm', hasChildren: false, class: 'w-7' },
+      { size: 'default', hasChildren: false, class: 'w-8' },
+      { size: 'sm', hasChildren: true, class: 'gap-1' },
+      { size: 'default', hasChildren: true, class: 'gap-1.5' },
+    ],
+    defaultVariants: { size: 'default', hasChildren: false },
+  },
+);
+
+const thumbVariants = cva(
+  'pointer-events-none flex shrink-0 items-center justify-center rounded-full bg-background ring-0 transition-transform',
+  {
+    variants: {
+      size: {
+        sm: 'size-3',
+        default: 'size-4',
+      },
+      hasChildren: {
+        // 有内文时通过 flex order + 单侧 0.5 平移实现两端各 2px 视觉间距
+        true: 'data-[state=checked]:order-2 data-[state=checked]:-translate-x-0.5 data-[state=unchecked]:order-1 data-[state=unchecked]:translate-x-0.5',
+        false: '',
+      },
+    },
+    compoundVariants: [
+      // 无内文：保留原 translate 数值，与历史视觉对齐
+      {
+        size: 'sm',
+        hasChildren: false,
+        class:
+          'data-[state=checked]:translate-x-3 data-[state=unchecked]:translate-x-0.5',
+      },
+      {
+        size: 'default',
+        hasChildren: false,
+        class:
+          'data-[state=checked]:translate-x-3 data-[state=unchecked]:translate-x-0.5',
+      },
+    ],
+    defaultVariants: { size: 'default', hasChildren: false },
+  },
+);
+
+const textVariants = cva(
+  // padding 与 order 跟随 root data-state 切换：满足"thumb 紧贴边缘"规范（root 不加 px）
+  'inline-flex select-none items-center justify-center whitespace-nowrap leading-none transition-colors group-data-[state=checked]/switch:order-1 group-data-[state=checked]/switch:text-primary-foreground group-data-[state=unchecked]/switch:order-2 group-data-[state=unchecked]/switch:text-muted-foreground',
+  {
+    variants: {
+      size: {
+        sm: 'text-xxs group-data-[state=checked]/switch:pl-1 group-data-[state=unchecked]/switch:pr-1',
+        default:
+          'text-xs group-data-[state=checked]/switch:pl-1.5 group-data-[state=unchecked]/switch:pr-1.5',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type SwitchSize = 'sm' | 'default';
+
+export interface SwitchProps
+  extends Omit<React.ComponentProps<typeof SwitchPrimitive.Root>, 'children'> {
+  /** 尺寸。 @default default */
+  size?: SwitchSize;
+  /** 加载中：展示自旋图标并阻止交互。 @default false */
+  loading?: boolean;
+  /** 选中时显示在 track 内的内容（文本或 lucide 图标）。 */
+  checkedChildren?: React.ReactNode;
+  /** 未选中时显示在 track 内的内容（文本或 lucide 图标）。 */
+  unCheckedChildren?: React.ReactNode;
+}
+
+// ─── Switch ─────────────────────────────────────────────────────────────────
+
+function Switch({
+  className,
+  size = 'default',
+  loading = false,
+  checkedChildren,
+  unCheckedChildren,
+  disabled,
+  ...props
+}: SwitchProps) {
+  const hasChildren = checkedChildren != null || unCheckedChildren != null;
+  const spinnerSize = size === 'sm' ? 'size-2' : 'size-3';
+
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      data-size={size}
+      data-loading={loading || undefined}
+      aria-busy={loading || undefined}
+      disabled={disabled || loading}
+      className={cn(switchVariants({ size, hasChildren }), className)}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        className={cn(thumbVariants({ size, hasChildren }))}
+      >
+        {loading ? (
+          <Loader2Icon
+            className={cn('animate-spin text-foreground/60', spinnerSize)}
+            aria-hidden="true"
+          />
+        ) : null}
+      </SwitchPrimitive.Thumb>
+      {hasChildren ? (
+        <>
+          <span
+            data-slot="switch-text"
+            data-state-text="checked"
+            className={cn(
+              textVariants({ size }),
+              'group-data-[state=unchecked]/switch:hidden',
+            )}
+          >
+            {checkedChildren}
+          </span>
+          <span
+            data-slot="switch-text"
+            data-state-text="unchecked"
+            className={cn(
+              textVariants({ size }),
+              'group-data-[state=checked]/switch:hidden',
+            )}
+          >
+            {unCheckedChildren}
+          </span>
+        </>
+      ) : null}
+    </SwitchPrimitive.Root>
+  );
+}
+
+export { Switch, switchVariants };