@teamix-evo/ui 0.1.1

package/src/components/slider/slider.meta.md

@@ -0,0 +1,94 @@
+---
+id: slider
+name: Slider
+type: component
+category: form
+since: 0.1.0
+package: '@teamix-evo/ui'
+---
+
+# Slider
+
+滑块 — Radix Slider + antd 的 `marks` 刻度标签。**单 / 双滑块由 `value`/`defaultValue` 数组长度决定**(传 `[lo, hi]` 自动变范围滑块)。
+
+## When to use
+
+- 数值范围调节(音量 / 缩放 / 亮度)
+- 区间筛选(价格区间、日期区间)
+- 配合实时预览的微调控件
+
+## When NOT to use
+
+- 离散选项 → 用 `Radio Group` 或 `Select`
+- 精确数值输入 → 用 `Input type="number"`
+- 多于 2 个滑块 → 改用专门的多段滑块组件(暂未提供)
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `marks` | `Record<number, React.ReactNode>` | – | – | 刻度标记(antd `marks` 并集)。键为 0~max 的数值,值为标签文本。 渲染时小标记点 + 文字标签出现在轨道下方。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add slider` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-slider@^1.2.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 Radix Slider.Root props(`min` / `max` / `step` / `disabled` / `onValueChange` / `name` / `inverted` 等)。
+
+## AI 生成纪律
+
+- **`value` 永远是数组**:即使单滑块,Radix 期望 `[42]` 而非 `42`,初学者最易踩坑
+- **`marks` 键必须在 `[min, max]` 内**:超出范围的标记仍会渲染但位置错乱
+- **范围滑块由数据决定形态**:不要用单独的 `range` prop,**直接** `defaultValue={[20, 80]}` 即可
+- **配 Label**:Slider 不带可见数值时,必须 `aria-label` 或外部 Label 关联
+- **`step` 跨度的可访问性**:键盘 Page Up/Down 步进 = step × 10,设计 step 时考虑这一点
+- **marks 的"圆点"和"文字"必须分两层渲染,不要打包成一个 box**:
+  - **圆点**:`absolute top-1/2 -translate-x-1/2 -translate-y-1/2` 居中压在 track 中线上,渲染在 `<SliderPrimitive.Root>` 内、`<Track>` 之外(放进 Track 内会被 `overflow-hidden` 裁掉或被 `Range` 高亮覆盖)
+  - **文字**:独立放在父容器 `bottom-0` 处,通过父容器 `pb-6` 留出 ~14px 间距;不要用 `mt-1` 把文字直接挂在圆点下方,会出现"点和文字粘在一起"的视觉 bug(对照 antd 标准:点压 track、文字距 track ~12px)
+- **`<Thumb>` 必须加 `relative z-10`**:让滑块视觉层级高于 marks 圆点,避免拖动时圆点突兀露在 thumb 之上
+
+## Examples
+
+```tsx
+import { Slider } from '@/components/ui/slider';
+
+// 单滑块
+<Slider defaultValue={[42]} max={100} step={1} />
+
+// 范围滑块
+<Slider defaultValue={[20, 80]} max={100} step={1} />
+
+// 带刻度标签
+<Slider
+  defaultValue={[40]}
+  max={100}
+  step={20}
+  marks={{ 0: '0°C', 20: '20', 40: '40', 60: '60', 80: '80', 100: '100°C' }}
+/>
+
+// 受控
+const [v, setV] = React.useState([50]);
+<Slider value={v} onValueChange={setV} max={100} />
+```

package/src/components/slider/slider.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Slider } from './slider';
+
+const meta: Meta<typeof Slider> = {
+  title: '表单与输入 · Form/Slider',
+  component: Slider,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '滑块 — 在给定范围内选取一个数值或一段区间。Radix Slider 实现 + antd 的 `marks` 刻度能力：`value` / `defaultValue` 为数组，长度为 1 时为单滑块、为 2 时自动切换为区间滑块；可配 `marks` 渲染轨道下方的刻度点与标签。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    min: { control: 'number' },
+    max: { control: 'number' },
+    step: { control: 'number' },
+    disabled: { control: 'boolean' },
+  },
+  args: { defaultValue: [42], min: 0, max: 100, step: 1 },
+  decorators: [
+    (Story) => (
+      <div className="w-80">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Slider>;
+
+export const Playground: Story = {};
+
+export const Range: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Slider defaultValue={[20, 80]} max={100} />,
+};
+
+export const WithMarks: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Slider
+      defaultValue={[40]}
+      max={100}
+      step={20}
+      marks={{
+        0: '0°C',
+        20: '20',
+        40: '40',
+        60: '60',
+        80: '80',
+        100: '100°C',
+      }}
+    />
+  ),
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Slider defaultValue={[42]} disabled />
+      <Slider defaultValue={[20, 80]} disabled />
+    </div>
+  ),
+};

package/src/components/slider/slider.tsx

@@ -0,0 +1,86 @@
+import * as React from 'react';
+import * as SliderPrimitive from '@radix-ui/react-slider';
+
+import { cn } from '@/utils/cn';
+
+export interface SliderProps
+  extends React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> {
+  /**
+   * 刻度标记(antd `marks` 并集)。键为 0~max 的数值,值为标签文本。
+   * 渲染时小标记点 + 文字标签出现在轨道下方。
+   */
+  marks?: Record<number, React.ReactNode>;
+}
+
+const Slider = React.forwardRef<
+  React.ElementRef<typeof SliderPrimitive.Root>,
+  SliderProps
+>(
+  (
+    { className, marks, value, defaultValue, min = 0, max = 100, ...props },
+    ref,
+  ) => {
+    // Radix Slider supports range natively when `value` / `defaultValue` is array of length 2.
+    const thumbCount = (value ?? defaultValue ?? [0]).length;
+    return (
+      <div className={cn('relative w-full', marks ? 'pb-6' : '')}>
+        <SliderPrimitive.Root
+          ref={ref}
+          value={value}
+          defaultValue={defaultValue}
+          min={min}
+          max={max}
+          className={cn(
+            'relative flex w-full touch-none select-none items-center',
+            className,
+          )}
+          {...props}
+        >
+          <SliderPrimitive.Track className="relative h-1.5 w-full grow overflow-hidden rounded-full bg-secondary">
+            <SliderPrimitive.Range className="absolute h-full bg-primary" />
+          </SliderPrimitive.Track>
+          {marks
+            ? Object.entries(marks).map(([k]) => {
+                const num = Number(k);
+                const pct = ((num - min) / (max - min)) * 100;
+                return (
+                  <span
+                    key={`dot-${k}`}
+                    aria-hidden
+                    className="pointer-events-none absolute top-1/2 size-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-muted-foreground"
+                    style={{ left: `${pct}%` }}
+                  />
+                );
+              })
+            : null}
+          {Array.from({ length: thumbCount }).map((_, i) => (
+            <SliderPrimitive.Thumb
+              key={i}
+              className="relative z-10 block size-4 rounded-full border-2 border-primary bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50"
+            />
+          ))}
+        </SliderPrimitive.Root>
+        {marks ? (
+          <div className="pointer-events-none absolute inset-x-0 bottom-0 h-4">
+            {Object.entries(marks).map(([k, label]) => {
+              const num = Number(k);
+              const pct = ((num - min) / (max - min)) * 100;
+              return (
+                <span
+                  key={k}
+                  className="absolute -translate-x-1/2 whitespace-nowrap text-xs text-muted-foreground"
+                  style={{ left: `${pct}%` }}
+                >
+                  {label}
+                </span>
+              );
+            })}
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+);
+Slider.displayName = 'Slider';
+
+export { Slider };

package/src/components/sonner/sonner.meta.md

@@ -0,0 +1,96 @@
+---
+id: sonner
+name: Sonner
+type: component
+category: feedback
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Sonner
+
+Toast 通知 — 基于 [`sonner`](https://sonner.emilkowal.ski/),已**同时覆盖** antd `message`(行内简短)+ `notification`(标题 + 描述 + 行动)的并集。
+
+**应用根挂 `<Toaster />` 一次**,在任意地方 `import { toast } from '@/components/ui/sonner'` 触发。
+
+## When to use
+
+- 异步操作结果反馈(保存成功 / 网络错误)
+- 系统通知(新消息 / 协作动作)
+- Promise 状态自动切换(`toast.promise(saving, { loading, success, error })`)
+- 带行动按钮的提示(`toast(... { action: { label: '撤销', onClick } })`)
+
+## When NOT to use
+
+- 阻断式确认 → `AlertDialog`
+- 静态常驻提示 → `Alert`
+- 表单字段错误 → 字段下方文本
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `<Toaster />` 的 props。`toast()` 函数式 API 见下方 Examples。
+
+<!-- auto:props:begin -->
+_(no props)_
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+_无 — 本组件不依赖其他 ui entry。_
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add sonner@^1.5.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 sonner `<Toaster>` 原生属性(`position` / `richColors` / `expand` / `closeButton` 等)。
+
+## AI 生成纪律
+
+- **应用根只挂一次**:不要在多处 `<Toaster />`,触发会重复
+- **不要替代必读信息**:Toast 会自动消失,**不要**用它呈现"用户必须知道"的关键信息(用 `Alert` / `AlertDialog`)
+- **错误用 `toast.error()`**:语义化方法比 `toast({ type: 'error' })` 优先
+- **长任务用 `toast.promise()`**:自动显示 loading → success / error,避免手写状态切换
+- **Action 按钮用一个就够**:不要塞多个,过载
+
+## Examples
+
+```tsx
+import { Toaster, toast } from '@/components/ui/sonner';
+
+// 应用根
+<Toaster position="top-right" richColors />
+
+// 简单消息(等价 antd message)
+toast('已复制到剪贴板');
+
+// 带标题 + 描述(等价 antd notification)
+toast.success('保存成功', {
+  description: '所有更改已生效。',
+});
+
+toast.error('提交失败', {
+  description: '请检查网络后重试。',
+});
+
+// 异步任务(自动 loading → success / error)
+toast.promise(saveProject(), {
+  loading: '保存中...',
+  success: '保存成功',
+  error: (err) => `保存失败: ${err.message}`,
+});
+
+// 带行动按钮
+toast('文件已删除', {
+  action: { label: '撤销', onClick: () => undo() },
+});
+```

package/src/components/sonner/sonner.stories.tsx

@@ -0,0 +1,91 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Toaster, toast } from './sonner';
+import { Button } from '@/components/button/button';
+
+const meta: Meta<typeof Toaster> = {
+  title: '反馈与浮层 · Feedback/Sonner',
+  component: Toaster,
+  tags: ['autodocs'],
+  argTypes: {
+    position: {
+      control: 'select',
+      options: [
+        'top-left',
+        'top-center',
+        'top-right',
+        'bottom-left',
+        'bottom-center',
+        'bottom-right',
+      ],
+    },
+    richColors: { control: 'boolean' },
+    expand: { control: 'boolean' },
+    closeButton: { control: 'boolean' },
+  },
+  args: {
+    position: 'top-right',
+    richColors: true,
+    closeButton: true,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Toaster>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-2">
+      <Toaster {...args} />
+      <Button onClick={() => toast('已复制到剪贴板')}>普通</Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.success('保存成功', { description: '所有更改已生效。' })
+        }
+      >
+        Success
+      </Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.error('提交失败', { description: '请检查网络后重试。' })
+        }
+      >
+        Error
+      </Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.warning('注意', { description: '账号 7 天后过期。' })
+        }
+      >
+        Warning
+      </Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.promise(
+            new Promise((res) => setTimeout(res, 1500)),
+            {
+              loading: '保存中...',
+              success: '保存成功',
+              error: '保存失败',
+            },
+          )
+        }
+      >
+        Promise
+      </Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast('文件已删除', {
+            action: { label: '撤销', onClick: () => toast('已撤销') },
+          })
+        }
+      >
+        With Action
+      </Button>
+    </div>
+  ),
+};

package/src/components/sonner/sonner.tsx

@@ -0,0 +1,40 @@
+import { Toaster as Sonner, type ToasterProps as SonnerProps } from 'sonner';
+
+/**
+ * Toaster 容器 — 应用根挂一次,后续在任意地方调 `toast()` / `toast.success()` / `toast.error()` /
+ * `toast.warning()` / `toast.loading()` / `toast.promise()` 等触发 toast。
+ *
+ * 默认主题跟随系统;视觉走 design tokens(`--background` / `--border` / `--foreground`)。
+ *
+ * 来自 antd `message` + `notification` 的并集 — sonner 的 toast API 已经覆盖了:
+ *   - 短文字提示(对应 message)
+ *   - 标题 + 描述(对应 notification)
+ *   - 操作按钮(action)
+ *   - Promise 状态切换(loading → success/error)
+ */
+export interface ToasterProps extends SonnerProps {}
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  return (
+    <Sonner
+      theme="system"
+      className="toaster group"
+      toastOptions={{
+        classNames: {
+          toast:
+            'group toast group-[.toaster]:bg-background group-[.toaster]:text-foreground group-[.toaster]:border-border group-[.toaster]:shadow-lg',
+          description: 'group-[.toast]:text-muted-foreground',
+          actionButton:
+            'group-[.toast]:bg-primary group-[.toast]:text-primary-foreground',
+          cancelButton:
+            'group-[.toast]:bg-muted group-[.toast]:text-muted-foreground',
+        },
+      }}
+      {...props}
+    />
+  );
+};
+
+// Re-export the imperative API so consumers only depend on this module.
+export { toast } from 'sonner';
+export { Toaster };

package/src/components/space/space.meta.md

@@ -0,0 +1,94 @@
+---
+id: space
+name: Space
+type: component
+category: layout
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Space
+
+间距容器 — antd 独有补足。**等价 antd `Space`**:把同语义并排子项统一间距、对齐与可选换行,可选 `split` 节点(常用 Separator)。与 `Flex` 区别:Space 偏向**小集合 inline 间距**(按钮组、tag 组、表单 label-value 对),Flex 偏向**完整布局容器**。
+
+## When to use
+
+- 多个按钮 / 标签 / 链接并排(避免直接写 `flex gap-2`)
+- 表单某一行的"标签 + 值"对
+- 列表行末的多个操作链接(配 `split=<Separator orientation="vertical" />`)
+
+## When NOT to use
+
+- 完整页面布局 → `Flex` / `Grid`
+- 按钮粘连共享边线 → `ButtonGroup`
+- 大段排版分段 → `Typography Prose`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `direction` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 排列方向(antd `direction` 并集)。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 间距档位(antd `size` 并集) — 走 design 间距刻度,不接受 number。 |
+| `wrap` | `boolean` | `false` | – | 是否自动换行(antd `wrap` 并集) — horizontal 模式生效。 |
+| `align` | `'start' \| 'center' \| 'end' \| 'baseline' \| 'stretch'` | `"center"` | – | 主轴对齐方式(antd `align` 并集)。 |
+| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | – | – | 副轴对齐(antd `Space` 无,Space.Compact 也无 — 但中后台需求高,补)。 |
+| `split` | `React.ReactNode` | – | – | 分隔节点(antd `split` 并集) — 在每两个子项之间插入(常用 `<Separator>`)。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add space` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`size` 是档位枚举**(sm/default/lg),**不接受 number** — 与 antd 偏离,因为我们走 design 间距刻度
+- **`wrap` 仅 horizontal 生效** — vertical 自动换行无意义
+- **`split` 应是无状态轻节点**(Separator / `|` / dot),不要传 Button 等复杂组件,语义混乱
+- **`justify`** 是 antd 缺失但中后台高频补的能力 — 列表行末右对齐操作就用 `justify="end"`
+- **不要嵌套 Space**:嵌套用 Flex 表达父子结构
+
+## Examples
+
+```tsx
+import { Space } from '@/components/ui/space';
+import { Button } from '@/components/ui/button';
+import { Separator } from '@/components/ui/separator';
+
+// 按钮组
+<Space>
+  <Button variant="outline">取消</Button>
+  <Button>确定</Button>
+</Space>
+
+// 链接组 + split
+<Space split={<Separator orientation="vertical" className="h-4" />} size="sm">
+  <a href="#">查看</a>
+  <a href="#">编辑</a>
+  <a href="#">删除</a>
+</Space>
+
+// 表单行
+<Space justify="between">
+  <span className="text-sm text-muted-foreground">总计</span>
+  <span className="text-lg font-semibold">¥ 1,299</span>
+</Space>
+
+// 纵向
+<Space direction="vertical" align="start">
+  <Title>标题</Title>
+  <Paragraph>描述</Paragraph>
+</Space>
+```

package/src/components/space/space.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Space } from './space';
+import { Button } from '@/components/button/button';
+import { Separator } from '@/components/separator/separator';
+
+const meta: Meta<typeof Space> = {
+  title: '布局与容器 · Layout/Space',
+  component: Space,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '间距容器 — 把同语义并排子项统一间距、对齐与可选换行(按钮组、tag 组、表单 label-value 对)。等价 antd `Space`,与 Flex 互补:Space 偏 inline 小集合,Flex 偏完整布局。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    direction: { control: 'inline-radio', options: ['horizontal', 'vertical'] },
+    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    wrap: { control: 'boolean' },
+    align: {
+      control: 'inline-radio',
+      options: ['start', 'center', 'end', 'baseline', 'stretch'],
+    },
+    justify: {
+      control: 'inline-radio',
+      options: ['start', 'center', 'end', 'between', 'around'],
+    },
+  },
+  args: { direction: 'horizontal', size: 'default', wrap: false, align: 'center' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Space>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Space {...args}>
+      <Button variant="outline">取消</Button>
+      <Button>确定</Button>
+      <Button variant="ghost">更多</Button>
+    </Space>
+  ),
+};
+
+export const Vertical: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Space direction="vertical" align="start">
+      <span className="text-base font-semibold">标题</span>
+      <span className="text-sm text-muted-foreground">这是描述文字</span>
+      <Button size="sm">操作</Button>
+    </Space>
+  ),
+};
+
+export const WithSplit: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Space split={<Separator orientation="vertical" className="h-4" />} size="sm">
+      <a href="#" className="text-sm text-primary hover:underline">查看</a>
+      <a href="#" className="text-sm text-primary hover:underline">编辑</a>
+      <a href="#" className="text-sm text-destructive hover:underline">删除</a>
+    </Space>
+  ),
+};
+
+export const Between: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80 rounded-md border p-3">
+      <Space justify="between">
+        <span className="text-sm text-muted-foreground">总计</span>
+        <span className="text-lg font-semibold">¥ 1,299</span>
+      </Space>
+    </div>
+  ),
+};
+
+export const Wrap: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80 rounded-md border p-3">
+      <Space wrap>
+        {Array.from({ length: 12 }).map((_, i) => (
+          <Button key={i} variant="outline" size="sm">
+            标签 {i + 1}
+          </Button>
+        ))}
+      </Space>
+    </div>
+  ),
+};