@teamix-evo/ui 0.1.1

package/src/components/space/space.tsx

@@ -0,0 +1,106 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+const spaceVariants = cva('flex', {
+  variants: {
+    direction: {
+      horizontal: 'flex-row',
+      vertical: 'flex-col',
+    },
+    size: {
+      sm: 'gap-2',
+      default: 'gap-3',
+      lg: 'gap-4',
+    },
+    wrap: {
+      true: 'flex-wrap',
+      false: 'flex-nowrap',
+    },
+    align: {
+      start: 'items-start',
+      center: 'items-center',
+      end: 'items-end',
+      baseline: 'items-baseline',
+      stretch: 'items-stretch',
+    },
+    justify: {
+      start: 'justify-start',
+      center: 'justify-center',
+      end: 'justify-end',
+      between: 'justify-between',
+      around: 'justify-around',
+    },
+  },
+  defaultVariants: { direction: 'horizontal', size: 'default', wrap: false, align: 'center' },
+});
+
+export interface SpaceProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof spaceVariants> {
+  /**
+   * 排列方向(antd `direction` 并集)。
+   * @default "horizontal"
+   */
+  direction?: 'horizontal' | 'vertical';
+  /**
+   * 间距档位(antd `size` 并集) — 走 design 间距刻度,不接受 number。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+  /**
+   * 是否自动换行(antd `wrap` 并集) — horizontal 模式生效。
+   * @default false
+   */
+  wrap?: boolean;
+  /**
+   * 主轴对齐方式(antd `align` 并集)。
+   * @default "center"
+   */
+  align?: 'start' | 'center' | 'end' | 'baseline' | 'stretch';
+  /**
+   * 副轴对齐(antd `Space` 无,Space.Compact 也无 — 但中后台需求高,补)。
+   */
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around';
+  /**
+   * 分隔节点(antd `split` 并集) — 在每两个子项之间插入(常用 `<Separator>`)。
+   */
+  split?: React.ReactNode;
+}
+
+/**
+ * 间距容器 — antd 独有补足。**等价 antd `Space`**:把同语义并排子项统一间距、对齐与可选换行。
+ * 与 `Flex` 区别:Space 偏向"小集合 inline 间距"(按钮组、tag 组、表单 label-value 对),
+ * Flex 偏向"完整布局容器"。
+ */
+const Space = React.forwardRef<HTMLDivElement, SpaceProps>(
+  (
+    { direction, size, wrap, align, justify, split, className, children, ...props },
+    ref,
+  ) => {
+    const items = React.Children.toArray(children).filter(Boolean);
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          spaceVariants({ direction, size, wrap, align, justify }),
+          className,
+        )}
+        {...props}
+      >
+        {split
+          ? items.map((child, i) => (
+              <React.Fragment key={i}>
+                {i > 0 ? split : null}
+                {child}
+              </React.Fragment>
+            ))
+          : children}
+      </div>
+    );
+  },
+);
+Space.displayName = 'Space';
+
+export { Space, spaceVariants };

package/src/components/spinner/spinner.meta.md

@@ -0,0 +1,76 @@
+---
+id: spinner
+name: Spinner
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Spinner
+
+旋转加载指示器 — shadcn 2025-10 新增,**等价 antd `Spin`**(无遮罩版)。基于 `lucide-react` 的 `Loader2`,4 档尺寸 + 4 档语义配色,自带 `role="status"` 与读屏文本。
+
+## When to use
+
+- 按钮 / 表单内联 loading(`Button loading` 内部已用同一图标,这里独立 spinner 用于自定义触发器)
+- 容器局部加载(请求中)
+- 全屏 loading 占位(`size="xl"` + 居中)
+
+## When NOT to use
+
+- 内容结构占位 → `Skeleton`(组件级 / 段落级)
+- 整页"模态阻塞 loading" → `Dialog` + Spinner 自行组合(本组件不内置遮罩)
+- 进度可知场景 → `Progress`(线形)或 `ProgressCircle`(环形)
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。 |
+| `tone` | `'default' \| 'muted' \| 'primary' \| 'destructive'` | `"default"` | – | 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。 |
+| `label` | `string` | – | – | 给读屏器的描述(默认 "Loading...")。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add spinner` 时,以下 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 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **不要自己写 `<div className="animate-spin">`** — 用本组件,保留读屏可访问性
+- **`tone="primary"` 配主操作 loading**,`tone="destructive"` 仅用于真正失败回退 — 不要乱用
+- **不要给 spinner 加旋转字幕 / 进度数字** — 那是 Progress 的职责,语义不同
+- **包裹遮罩 loading**:外层加 `relative` 容器 + spinner 居中,**不要**包到本组件内部破坏其单一职责
+
+## Examples
+
+```tsx
+import { Spinner } from '@/components/ui/spinner';
+
+// 行内
+<span>正在保存 <Spinner size="sm" tone="muted" /></span>
+
+// 居中
+<div className="flex h-40 items-center justify-center">
+  <Spinner size="lg" tone="primary" label="加载用户信息..." />
+</div>
+
+// 全屏
+<div className="fixed inset-0 grid place-items-center bg-background/80 backdrop-blur-sm">
+  <Spinner size="xl" tone="primary" />
+</div>
+```

package/src/components/spinner/spinner.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Spinner } from './spinner';
+
+const meta: Meta<typeof Spinner> = {
+  title: '基础原语 · Foundation/Spinner',
+  component: Spinner,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '旋转加载指示器 — 局部 / 行内 loading(请求中、按钮提交、占位等待)。基于 lucide Loader2,4 档尺寸 + 4 档配色,自带 role="status" 与 sr-only 读屏文案。shadcn 2025-10 新增,对齐 antd `Spin`(无遮罩版本)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'default', 'lg', 'xl'] },
+    tone: {
+      control: 'inline-radio',
+      options: ['default', 'muted', 'primary', 'destructive'],
+    },
+  },
+  args: { size: 'default', tone: 'default' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Spinner>;
+
+export const Playground: Story = {};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-end gap-6">
+      <Spinner size="sm" />
+      <Spinner size="default" />
+      <Spinner size="lg" />
+      <Spinner size="xl" />
+    </div>
+  ),
+};
+
+export const Tones: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Spinner tone="default" />
+      <Spinner tone="muted" />
+      <Spinner tone="primary" />
+      <Spinner tone="destructive" />
+    </div>
+  ),
+};
+
+export const Inline: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <p className="text-sm">
+      正在保存草稿 <Spinner size="sm" tone="muted" />
+    </p>
+  ),
+};
+
+export const Centered: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex h-40 items-center justify-center rounded-md border">
+      <Spinner size="lg" tone="primary" />
+    </div>
+  ),
+};

package/src/components/spinner/spinner.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Loader2 } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+const spinnerVariants = cva('inline-block shrink-0 animate-spin', {
+  variants: {
+    size: {
+      sm: 'size-3',
+      default: 'size-4',
+      lg: 'size-6',
+      xl: 'size-8',
+    },
+    tone: {
+      default: 'text-foreground',
+      muted: 'text-muted-foreground',
+      primary: 'text-primary',
+      destructive: 'text-destructive',
+    },
+  },
+  defaultVariants: { size: 'default', tone: 'default' },
+});
+
+export interface SpinnerProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'>,
+    VariantProps<typeof spinnerVariants> {
+  /**
+   * 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg' | 'xl';
+  /**
+   * 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。
+   * @default "default"
+   */
+  tone?: 'default' | 'muted' | 'primary' | 'destructive';
+  /**
+   * 给读屏器的描述(默认 "Loading...")。
+   */
+  label?: string;
+}
+
+/**
+ * 简单旋转 loading — shadcn 2025-10 新增,等价 antd `Spin`(无遮罩版)。
+ * 需要"包裹内容显示遮罩 loading"时配合 `Skeleton` 或自行包一层。
+ */
+const Spinner = React.forwardRef<HTMLSpanElement, SpinnerProps>(
+  ({ size, tone, label = 'Loading...', className, ...props }, ref) => (
+    <span
+      ref={ref}
+      role="status"
+      aria-live="polite"
+      className={cn('inline-flex items-center', className)}
+      {...props}
+    >
+      <Loader2 className={cn(spinnerVariants({ size, tone }))} aria-hidden="true" />
+      <span className="sr-only">{label}</span>
+    </span>
+  ),
+);
+Spinner.displayName = 'Spinner';
+
+export { Spinner, spinnerVariants };

package/src/components/statistic/statistic.meta.md

@@ -0,0 +1,99 @@
+---
+id: statistic
+name: Statistic
+type: component
+category: data-display
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Statistic
+
+数字展示 — antd 独有补足。**仪表板专用**:大字号数值 + 标题 + 前缀(¥/$ / 图标)+ 后缀(单位)+ 趋势(上 / 下,自动配色)+ 千分位 + 精度。
+
+## When to use
+
+- 仪表板核心指标(GMV / 在线人数 / 成功率)
+- 卡片内 KPI 数字
+- 报表 / 数据周报顶部摘要
+
+## When NOT to use
+
+- 长文本数据 → 普通 `Paragraph`
+- 表格内数字 → 直接 `<td className="tabular-nums">`
+- 图表 → `Chart`(本仓暂未提供)
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `title` | `React.ReactNode` | – | – | 标题(antd `title` 并集)。 |
+| `value` | `number \| string` | – | ✓ | 数值(antd `value` 并集)。 |
+| `prefix` | `React.ReactNode` | – | – | 前缀(图标 / 货币符号 / 单位)。 |
+| `suffix` | `React.ReactNode` | – | – | 后缀(单位 / 趋势)。 |
+| `precision` | `number` | – | – | 数值精度(antd `precision` 并集),仅 number 生效。 |
+| `groupSeparator` | `boolean` | `true` | – | 千分位分隔符。 |
+| `trend` | `'up' \| 'down' \| 'none'` | `"none"` | – | 趋势 — `up`(绿色 ↑)/ `down`(红色 ↓)/ `none`。前置在数值上方或左侧。 |
+| `trendValue` | `string \| number` | – | – | 趋势百分比文字(配 trend 显示在 suffix 区)。 |
+| `valueClassName` | `string` | – | – | 数值颜色覆盖(默认随 trend / 否则 foreground)。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add statistic` 时,以下 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 -->
+
+## AI 生成纪律
+
+- **`trend` 颜色优先级最高**:有 trend 时数值 + 箭头自动套色,**不要**额外加 className 颜色
+- **`prefix` 用 ¥ / $ / icon**:**不要**塞文字单位(那是 suffix 的职责)
+- **`precision` 仅 number 生效**:string value(如 `'1,234.56k'`)请自行格式化好再传
+- **`tabular-nums` 已自动**:数字对齐用,不要再覆盖
+
+## Examples
+
+```tsx
+import { Statistic } from '@/components/ui/statistic';
+
+// 基础
+<Statistic title="今日 GMV" value={8493521} prefix="¥" />
+
+// 精度 + 后缀
+<Statistic title="转化率" value={3.245} precision={2} suffix="%" />
+
+// 趋势(自动配色)
+<Statistic
+  title="活跃用户"
+  value={1234}
+  trend="up"
+  trendValue="+12.4%"
+/>
+
+<Statistic
+  title="错误率"
+  value={0.83}
+  precision={2}
+  suffix="%"
+  trend="down"
+  trendValue="-0.5%"
+/>
+
+// 卡片内
+<Card>
+  <CardContent className="pt-6">
+    <Statistic title="本月订单" value={2847} prefix={<ShoppingCart />} />
+  </CardContent>
+</Card>
+```

package/src/components/statistic/statistic.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ShoppingCart, Users } from 'lucide-react';
+import { Statistic } from './statistic';
+import { Card, CardContent } from '@/components/card/card';
+
+const meta: Meta<typeof Statistic> = {
+  title: '数据展示 · Data Display/Statistic',
+  component: Statistic,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '数字展示 — 仪表板核心指标。大字号 + 千分位 + 精度 + 前后缀 + 趋势(上 / 下,自动配色)。OpenTrek tokens 适配,等价 antd Statistic。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Statistic>;
+
+export const Basic: Story = {
+  args: { title: '今日 GMV', value: 8493521, prefix: '¥' },
+};
+
+export const Trends: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap gap-8">
+      <Statistic title="活跃用户" value={1234} trend="up" trendValue="+12.4%" />
+      <Statistic
+        title="错误率"
+        value={0.83}
+        precision={2}
+        suffix="%"
+        trend="down"
+        trendValue="-0.5%"
+      />
+      <Statistic title="待处理" value={42} />
+    </div>
+  ),
+};
+
+export const InCards: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid grid-cols-2 gap-4">
+      <Card>
+        <CardContent className="pt-6">
+          <Statistic
+            title="本月订单"
+            value={2847}
+            prefix={<ShoppingCart />}
+            trend="up"
+            trendValue="+18%"
+          />
+        </CardContent>
+      </Card>
+      <Card>
+        <CardContent className="pt-6">
+          <Statistic
+            title="活跃用户"
+            value={12480}
+            prefix={<Users />}
+          />
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};

package/src/components/statistic/statistic.tsx

@@ -0,0 +1,197 @@
+import * as React from 'react';
+import { ArrowDown, ArrowUp } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface StatisticProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title' | 'prefix'> {
+  /** 标题(antd `title` 并集)。 */
+  title?: React.ReactNode;
+  /** 数值(antd `value` 并集)。 */
+  value: number | string;
+  /** 前缀(图标 / 货币符号 / 单位)。 */
+  prefix?: React.ReactNode;
+  /** 后缀(单位 / 趋势)。 */
+  suffix?: React.ReactNode;
+  /** 数值精度(antd `precision` 并集),仅 number 生效。 */
+  precision?: number;
+  /** 千分位分隔符。 @default true */
+  groupSeparator?: boolean;
+  /**
+   * 趋势 — `up`(绿色 ↑)/ `down`(红色 ↓)/ `none`。前置在数值上方或左侧。
+   * @default "none"
+   */
+  trend?: 'up' | 'down' | 'none';
+  /** 趋势百分比文字(配 trend 显示在 suffix 区)。 */
+  trendValue?: string | number;
+  /** 数值颜色覆盖(默认随 trend / 否则 foreground)。 */
+  valueClassName?: string;
+}
+
+function formatNumber(
+  v: number,
+  precision?: number,
+  groupSeparator = true,
+): string {
+  const fixed =
+    precision !== undefined ? v.toFixed(precision) : v.toString();
+  if (!groupSeparator) return fixed;
+  const [intPart, decPart] = fixed.split('.');
+  const grouped = intPart!.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return decPart !== undefined ? `${grouped}.${decPart}` : grouped;
+}
+
+const trendStyles = {
+  up: 'text-emerald-600',
+  down: 'text-destructive',
+  none: '',
+} as const;
+
+const Statistic = React.forwardRef<HTMLDivElement, StatisticProps>(
+  (
+    {
+      title,
+      value,
+      prefix,
+      suffix,
+      precision,
+      groupSeparator = true,
+      trend = 'none',
+      trendValue,
+      valueClassName,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const display =
+      typeof value === 'number'
+        ? formatNumber(value, precision, groupSeparator)
+        : value;
+    const TrendIcon =
+      trend === 'up' ? ArrowUp : trend === 'down' ? ArrowDown : null;
+    return (
+      <div
+        ref={ref}
+        className={cn('flex flex-col gap-1', className)}
+        {...props}
+      >
+        {title ? (
+          <div className="text-sm text-muted-foreground">{title}</div>
+        ) : null}
+        <div
+          className={cn(
+            'flex items-baseline gap-2 text-2xl font-semibold tabular-nums',
+            trendStyles[trend],
+            valueClassName,
+          )}
+        >
+          {prefix ? (
+            <span className="text-base font-medium opacity-80">{prefix}</span>
+          ) : null}
+          <span>{display}</span>
+          {suffix ? (
+            <span className="text-sm font-normal text-muted-foreground">
+              {suffix}
+            </span>
+          ) : null}
+          {TrendIcon ? (
+            <span className="inline-flex items-baseline gap-0.5 text-sm font-medium">
+              <TrendIcon className="size-3" />
+              {trendValue}
+            </span>
+          ) : null}
+        </div>
+      </div>
+    );
+  },
+);
+Statistic.displayName = 'Statistic';
+
+// ─── Statistic.Timer(antd 5.25+ 子组件)─────────────────────────────────
+
+export interface StatisticTimerProps
+  extends Omit<
+    StatisticProps,
+    'value' | 'precision' | 'groupSeparator' | 'onChange'
+  > {
+  /**
+   * 计时类型 — `countdown` 倒计时到 `target`;`countup` 从 `value`(默认 0)向上计时。
+   * @default "countdown"
+   */
+  type?: 'countdown' | 'countup';
+  /**
+   * 目标时间(毫秒时间戳)。`countdown` 必填;`countup` 可选(不传则从挂载时刻起算)。
+   */
+  target?: number;
+  /**
+   * 时间格式化字符串 — 支持 `HH` `mm` `ss` `SSS`(毫秒);`D` 天数;`d` 自动跳过为 0 的天数。
+   * @default "HH:mm:ss"
+   */
+  format?: string;
+  /** 倒计时到达 0 / 计时到达 target 时回调。 */
+  onFinish?: () => void;
+  /** 每次 tick 回调。 */
+  onChange?: (msLeft: number) => void;
+}
+
+function pad(n: number, width = 2): string {
+  return String(Math.max(0, Math.floor(n))).padStart(width, '0');
+}
+
+function formatDuration(ms: number, fmt: string): string {
+  const totalSec = Math.floor(ms / 1000);
+  const days = Math.floor(totalSec / 86400);
+  const hours = Math.floor((totalSec % 86400) / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+  const millis = ms % 1000;
+  return fmt
+    .replace(/D/g, String(days))
+    .replace(/HH/g, pad(hours))
+    .replace(/mm/g, pad(minutes))
+    .replace(/ss/g, pad(seconds))
+    .replace(/SSS/g, pad(millis, 3));
+}
+
+const StatisticTimer = React.forwardRef<HTMLDivElement, StatisticTimerProps>(
+  (
+    {
+      type = 'countdown',
+      target,
+      format = 'HH:mm:ss',
+      onFinish,
+      onChange,
+      ...rest
+    },
+    ref,
+  ) => {
+    const start = React.useMemo(() => Date.now(), []);
+    const [now, setNow] = React.useState<number>(() => Date.now());
+    const finished = React.useRef(false);
+
+    React.useEffect(() => {
+      const tick = () => setNow(Date.now());
+      const id = window.setInterval(tick, 1000);
+      return () => window.clearInterval(id);
+    }, []);
+
+    const ms =
+      type === 'countdown'
+        ? Math.max(0, (target ?? start) - now)
+        : Math.max(0, now - (target ?? start));
+
+    React.useEffect(() => {
+      onChange?.(ms);
+      if (type === 'countdown' && ms === 0 && !finished.current) {
+        finished.current = true;
+        onFinish?.();
+      }
+    }, [ms, type, onChange, onFinish]);
+
+    return <Statistic ref={ref} value={formatDuration(ms, format)} {...rest} />;
+  },
+);
+StatisticTimer.displayName = 'StatisticTimer';
+
+export { Statistic, StatisticTimer };