@teamix-evo/ui 0.1.1

package/src/components/steps/steps.meta.md

@@ -0,0 +1,102 @@
+---
+id: steps
+name: Steps
+type: component
+category: navigation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Steps
+
+步骤条 — antd 独有补足。引导用户完成多步流程(注册 / 下单 / 部署),清晰展示当前 / 已完成 / 待完成 / 错误状态。
+
+## When to use
+
+- 多步表单(注册 / 入驻 / 配置)
+- 流程进度可视化(订单状态 / CI/CD)
+- 长任务的阶段反馈
+
+## When NOT to use
+
+- 平级 tab → `Tabs`
+- 简单进度 → `Progress` / `ProgressCircle`
+- 历史时间线 → 自定义 timeline(暂无组件)
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `items` | `StepItem[]` | – | ✓ | 步骤列表。 |
+| `current` | `number` | `0` | – | 当前步骤(0-based)。`current` 之前的为 finish,`current` 为 process,之后为 wait。 |
+| `status` | `'process' \| 'error'` | `"process"` | – | 当前步骤的状态(只影响 `current` 那一步;`process` 默认,`error` 标红)。 |
+| `direction` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 排列方向。 |
+| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add steps` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> `StepItem` 类型:`{ title; description?; status?: 'wait' | 'process' | 'finish' | 'error'; icon? }`。
+
+## AI 生成纪律
+
+- **`current` 0-based**:第一步是 0,与数组索引一致
+- **`status="error"` 仅当前步**:把整体状态置错;**不要**对历史已完成步标 error
+- **`description` 简短**:不超过 1 行,长说明放主区
+- **vertical 用于侧栏**:横向用于宽屏 / 顶部
+- **不要堆叠超过 6 步**:认知超载;> 6 步改用 Wizard 模式 + 折叠
+
+## Examples
+
+```tsx
+import { Steps } from '@/components/ui/steps';
+
+// 横向
+<Steps
+  current={1}
+  items={[
+    { title: '账户信息', description: '填写基本信息' },
+    { title: '验证邮箱', description: '收取验证码' },
+    { title: '完成', description: '注册成功' },
+  ]}
+/>
+
+// 当前步出错
+<Steps
+  current={1}
+  status="error"
+  items={[
+    { title: '上传文件' },
+    { title: '解析数据' },
+    { title: '导入完成' },
+  ]}
+/>
+
+// 纵向
+<Steps direction="vertical" current={2} items={[...]} />
+
+// 自定义 icon
+<Steps
+  current={0}
+  items={[
+    { title: '提交', icon: <UploadIcon /> },
+    { title: '审核', icon: <ShieldCheck /> },
+    { title: '通过', icon: <Check /> },
+  ]}
+/>
+```

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

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Steps } from './steps';
+
+const meta: Meta<typeof Steps> = {
+  title: '导航 · Navigation/Steps',
+  component: Steps,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '步骤条 — 引导多步流程(注册 / 下单 / 部署)。状态自动推导(wait/process/finish/error),支持横向 / 纵向、两种尺寸、自定义图标。OpenTrek tokens 适配。',
+      },
+    },
+  },
+  argTypes: {
+    current: { control: 'number' },
+    status: { control: 'inline-radio', options: ['process', 'error'] },
+    direction: { control: 'inline-radio', options: ['horizontal', 'vertical'] },
+    size: { control: 'inline-radio', options: ['sm', 'default'] },
+  },
+  args: { current: 1, status: 'process', direction: 'horizontal', size: 'default' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Steps>;
+
+const items = [
+  { title: '账户信息', description: '填写基本信息' },
+  { title: '验证邮箱', description: '收取验证码' },
+  { title: '完成', description: '注册成功' },
+];
+
+export const Horizontal: Story = {
+  render: (args) => (
+    <div className="w-[600px]">
+      <Steps {...args} items={items} />
+    </div>
+  ),
+};
+
+export const Vertical: Story = {
+  args: { direction: 'vertical', current: 1 },
+  render: (args) => (
+    <div className="w-72">
+      <Steps {...args} items={items} />
+    </div>
+  ),
+};
+
+export const ErrorState: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-[600px]">
+      <Steps
+        current={1}
+        status="error"
+        items={[
+          { title: '上传文件' },
+          { title: '解析数据', description: '解析失败,请重试' },
+          { title: '导入完成' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+export const Small: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-96">
+      <Steps size="sm" current={1} items={items} />
+    </div>
+  ),
+};

package/src/components/steps/steps.tsx

@@ -0,0 +1,170 @@
+import * as React from 'react';
+import { Check, X } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export type StepStatus = 'wait' | 'process' | 'finish' | 'error';
+
+export interface StepItem {
+  /** 步骤标题(必填)。 */
+  title: React.ReactNode;
+  /** 描述(可选)。 */
+  description?: React.ReactNode;
+  /** 自定义状态(覆盖父级根据 current 推导出的状态)。 */
+  status?: StepStatus;
+  /** 自定义图标(覆盖默认数字 / 勾选 / 错误)。 */
+  icon?: React.ReactNode;
+}
+
+export interface StepsProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 步骤列表。 */
+  items: StepItem[];
+  /**
+   * 当前步骤(0-based)。`current` 之前的为 finish,`current` 为 process,之后为 wait。
+   * @default 0
+   */
+  current?: number;
+  /**
+   * 当前步骤的状态(只影响 `current` 那一步;`process` 默认,`error` 标红)。
+   * @default "process"
+   */
+  status?: 'process' | 'error';
+  /**
+   * 排列方向。
+   * @default "horizontal"
+   */
+  direction?: 'horizontal' | 'vertical';
+  /**
+   * 尺寸。
+   * @default "default"
+   */
+  size?: 'sm' | 'default';
+}
+
+function statusFor(
+  i: number,
+  current: number,
+  topStatus: 'process' | 'error',
+  itemStatus?: StepStatus,
+): StepStatus {
+  if (itemStatus) return itemStatus;
+  if (i < current) return 'finish';
+  if (i === current) return topStatus;
+  return 'wait';
+}
+
+const dotColor: Record<StepStatus, string> = {
+  wait: 'border-border bg-background text-muted-foreground',
+  process: 'border-primary bg-primary text-primary-foreground',
+  finish: 'border-primary bg-primary text-primary-foreground',
+  error: 'border-destructive bg-destructive text-destructive-foreground',
+};
+
+const lineColor: Record<StepStatus, string> = {
+  wait: 'bg-border',
+  process: 'bg-border',
+  finish: 'bg-primary',
+  error: 'bg-border',
+};
+
+const titleColor: Record<StepStatus, string> = {
+  wait: 'text-muted-foreground',
+  process: 'text-foreground font-medium',
+  finish: 'text-foreground',
+  error: 'text-destructive',
+};
+
+const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
+  (
+    {
+      items,
+      current = 0,
+      status = 'process',
+      direction = 'horizontal',
+      size = 'default',
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const isVertical = direction === 'vertical';
+    const dotSize = size === 'sm' ? 'size-6 text-xs' : 'size-8 text-sm';
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex',
+          isVertical ? 'flex-col gap-0' : 'flex-row items-start gap-0',
+          className,
+        )}
+        {...props}
+      >
+        {items.map((it, i) => {
+          const s = statusFor(i, current, status, it.status);
+          const isLast = i === items.length - 1;
+          const icon =
+            it.icon ??
+            (s === 'finish' ? (
+              <Check className="size-4" />
+            ) : s === 'error' ? (
+              <X className="size-4" />
+            ) : (
+              i + 1
+            ));
+          return (
+            <div
+              key={i}
+              className={cn(
+                'flex flex-1',
+                isVertical ? 'flex-row gap-3' : 'flex-col gap-2',
+              )}
+            >
+              <div
+                className={cn(
+                  'flex',
+                  isVertical
+                    ? 'flex-col items-center gap-2'
+                    : 'flex-row items-center gap-2',
+                )}
+              >
+                <div
+                  className={cn(
+                    'flex shrink-0 items-center justify-center rounded-full border-2 font-medium tabular-nums',
+                    dotSize,
+                    dotColor[s],
+                  )}
+                >
+                  {icon}
+                </div>
+                {!isLast ? (
+                  <div
+                    className={cn(
+                      lineColor[s],
+                      isVertical ? 'min-h-8 w-px flex-1' : 'h-px flex-1',
+                    )}
+                  />
+                ) : null}
+              </div>
+              <div
+                className={cn(
+                  'flex flex-col gap-0.5',
+                  !isVertical && 'pr-3',
+                )}
+              >
+                <div className={cn('text-sm', titleColor[s])}>{it.title}</div>
+                {it.description ? (
+                  <div className="text-xs text-muted-foreground">
+                    {it.description}
+                  </div>
+                ) : null}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    );
+  },
+);
+Steps.displayName = 'Steps';
+
+export { Steps };

package/src/components/switch/switch.meta.md

@@ -0,0 +1,92 @@
+---
+id: switch
+name: Switch
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Switch
+
+开关 — Radix Switch + antd 的 `loading / checkedChildren / unCheckedChildren / size`。
+
+## When to use
+
+- 立即生效的二元状态切换(订阅 / 通知 / 主题)
+- 对比 Checkbox:Switch 表示**立即应用**,Checkbox 表示**待提交**
+
+## When NOT to use
+
+- 表单内需提交后生效 → 用 `Checkbox`
+- 多个互斥选项 → 用 `Radio Group` 或 `Toggle Group`
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `loading` | `boolean` | `false` | – | 加载态 — 自动 `disabled`,thumb 上叠加自旋 spinner(antd 并集)。 |
+| `checkedChildren` | `React.ReactNode` | – | – | 选中态显示的内文(antd `checkedChildren` 并集)。 |
+| `unCheckedChildren` | `React.ReactNode` | – | – | 未选中态显示的内文(antd `unCheckedChildren` 并集)。 |
+| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add switch` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-switch@^1.1.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 Radix Switch.Root props(`checked` / `defaultChecked` / `onCheckedChange` / `name` / `value` 等)。
+
+## AI 生成纪律
+
+- **`loading` 期间禁止操作**:已自动 `disabled`,**不要**手动叠加 disabled 影响 UX 一致
+- **`checkedChildren` 文字 ≤ 2 个汉字**:仅"开/关"或"On/Off",过长会溢出胶囊
+- **配 Label 无障碍**:Switch 不带可见文字时,必须用 `aria-label` 或外部 `<Label>` + `id` 关联
+- **size="sm" 用于密集列表**:常规表单用 `default`
+
+## Examples
+
+```tsx
+import { Switch } from '@/components/ui/switch';
+import { Label } from '@/components/ui/label';
+
+// 基础(可控)
+const [on, setOn] = React.useState(false);
+<Switch checked={on} onCheckedChange={setOn} aria-label="启用通知" />
+
+// 配 Label
+<div className="flex items-center gap-2">
+  <Switch id="notify" />
+  <Label htmlFor="notify">订阅邮件提醒</Label>
+</div>
+
+// 加载态
+<Switch loading defaultChecked />
+
+// 内文(开/关 / On/Off)
+<Switch checkedChildren="开" unCheckedChildren="关" defaultChecked />
+
+// 小尺寸
+<Switch size="sm" />
+```

package/src/components/switch/switch.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Switch } from './switch';
+
+const meta: Meta<typeof Switch> = {
+  title: '表单与输入 · Form/Switch',
+  component: Switch,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '开关 — 在开 / 关两种状态间切换，适用于需要即时生效的二值设置。Radix Switch 实现 + antd Switch 的并集能力：支持 `size` (sm / default)、`loading` 异步状态、以及 `checkedChildren` / `unCheckedChildren` 在轨道内渲染状态文本（对齐 antd）。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'default'] },
+    loading: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    checkedChildren: { control: 'text' },
+    unCheckedChildren: { control: 'text' },
+  },
+  args: { size: 'default', loading: false, disabled: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof Switch>;
+
+export const Playground: Story = {};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Switch size="sm" defaultChecked />
+      <Switch size="default" defaultChecked />
+    </div>
+  ),
+};
+
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Switch />
+      <Switch defaultChecked />
+      <Switch disabled />
+      <Switch disabled defaultChecked />
+      <Switch loading />
+      <Switch loading defaultChecked />
+    </div>
+  ),
+};
+
+export const WithLabel: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Switch id="notify-stories" />
+      <label htmlFor="notify-stories" className="text-sm font-medium">
+        订阅邮件提醒
+      </label>
+    </div>
+  ),
+};
+
+export const InnerText: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Switch checkedChildren="开" unCheckedChildren="关" defaultChecked />
+      <Switch checkedChildren="On" unCheckedChildren="Off" />
+    </div>
+  ),
+};

package/src/components/switch/switch.tsx

@@ -0,0 +1,101 @@
+import * as React from 'react';
+import * as SwitchPrimitive from '@radix-ui/react-switch';
+import { Loader2 } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface SwitchProps
+  extends React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root> {
+  /**
+   * 加载态 — 自动 `disabled`,thumb 上叠加自旋 spinner(antd 并集)。
+   * @default false
+   */
+  loading?: boolean;
+  /** 选中态显示的内文(antd `checkedChildren` 并集)。 */
+  checkedChildren?: React.ReactNode;
+  /** 未选中态显示的内文(antd `unCheckedChildren` 并集)。 */
+  unCheckedChildren?: React.ReactNode;
+  /**
+   * 尺寸。
+   * @default "default"
+   */
+  size?: 'sm' | 'default';
+}
+
+const Switch = React.forwardRef<
+  React.ElementRef<typeof SwitchPrimitive.Root>,
+  SwitchProps
+>(
+  (
+    {
+      className,
+      loading = false,
+      checkedChildren,
+      unCheckedChildren,
+      size = 'default',
+      disabled,
+      ...props
+    },
+    ref,
+  ) => {
+    const isSm = size === 'sm';
+    return (
+      <SwitchPrimitive.Root
+        ref={ref}
+        disabled={disabled || loading}
+        className={cn(
+          'peer relative inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
+          isSm ? 'h-5 w-9' : 'h-6 w-11',
+          className,
+        )}
+        {...props}
+      >
+        {/* Inner labels (checkedChildren / unCheckedChildren) */}
+        {checkedChildren != null || unCheckedChildren != null ? (
+          <>
+            <span
+              className={cn(
+                'pointer-events-none absolute select-none text-[10px] font-medium leading-none text-primary-foreground transition-opacity peer-data-[state=unchecked]:opacity-0',
+                isSm ? 'left-1.5' : 'left-2',
+              )}
+              aria-hidden="true"
+            >
+              {checkedChildren}
+            </span>
+            <span
+              className={cn(
+                'pointer-events-none absolute select-none text-[10px] font-medium leading-none text-muted-foreground transition-opacity peer-data-[state=checked]:opacity-0',
+                isSm ? 'right-1.5' : 'right-2',
+              )}
+              aria-hidden="true"
+            >
+              {unCheckedChildren}
+            </span>
+          </>
+        ) : null}
+
+        <SwitchPrimitive.Thumb
+          className={cn(
+            'pointer-events-none flex items-center justify-center rounded-full bg-background shadow-lg ring-0 transition-transform',
+            isSm
+              ? 'size-4 data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0'
+              : 'size-5 data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0',
+          )}
+        >
+          {loading ? (
+            <Loader2
+              className={cn(
+                'animate-spin text-muted-foreground motion-reduce:animate-none',
+                isSm ? 'size-3' : 'size-3.5',
+              )}
+              aria-hidden="true"
+            />
+          ) : null}
+        </SwitchPrimitive.Thumb>
+      </SwitchPrimitive.Root>
+    );
+  },
+);
+Switch.displayName = 'Switch';
+
+export { Switch };