@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/statistic/{statistic.tsx → index.tsx}

@@ -1,30 +1,37 @@
+/**
+ * 统计数值 Statistic
+ *
+ * 突出展示数字或指标，支持前后缀、趋势箭头、千分位格式化和倒计时模式。
+ *
+ * @when
+ * - 仪表盘核心指标展示
+ * - 数据概览卡片（收入、用户量、转化率）
+ * - 倒计时 / 正计时场景
+ */
 import * as React from 'react';
 import { ArrowDown, ArrowUp } from 'lucide-react';
 
-import { cn } from '@/utils/cn';
+import { cn } from '@/lib/utils';
 
 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 生效。 */
+  /** 数值精度，仅 number 生效。 */
   precision?: number;
-  /** 千分位分隔符。 @default true */
+  /** 千分位分隔符。 */
   groupSeparator?: boolean;
-  /**
-   * 趋势 — `up`(绿色 ↑)/ `down`(红色 ↓)/ `none`。前置在数值上方或左侧。
-   * @default "none"
-   */
+  /** 趋势：`up`（绿色 ↑）/ `down`（红色 ↓）/ `none`。 */
   trend?: 'up' | 'down' | 'none';
-  /** 趋势百分比文字(配 trend 显示在 suffix 区)。 */
+  /** 趋势百分比文字。 */
   trendValue?: string | number;
-  /** 数值颜色覆盖(默认随 trend / 否则 foreground)。 */
+  /** 数值区域额外样式。 */
   valueClassName?: string;
 }
 
@@ -107,28 +114,20 @@ const Statistic = React.forwardRef<HTMLDivElement, StatisticProps>(
 );
 Statistic.displayName = 'Statistic';
 
-// ─── Statistic.Timer(antd 5.25+ 子组件)─────────────────────────────────
+// ─── StatisticTimer ──────────────────────────────────────────────────────────
 
 export interface StatisticTimerProps
   extends Omit<
     StatisticProps,
     'value' | 'precision' | 'groupSeparator' | 'onChange'
   > {
-  /**
-   * 计时类型 — `countdown` 倒计时到 `target`;`countup` 从 `value`(默认 0)向上计时。
-   * @default "countdown"
-   */
+  /** 计时类型：`countdown` 倒计时 / `countup` 正计时。 */
   type?: 'countdown' | 'countup';
-  /**
-   * 目标时间(毫秒时间戳)。`countdown` 必填;`countup` 可选(不传则从挂载时刻起算)。
-   */
+  /** 目标时间（毫秒时间戳）。 */
   target?: number;
-  /**
-   * 时间格式化字符串 — 支持 `HH` `mm` `ss` `SSS`(毫秒);`D` 天数;`d` 自动跳过为 0 的天数。
-   * @default "HH:mm:ss"
-   */
+  /** 时间格式化字符串，支持 `HH` `mm` `ss` `SSS` `D`。 */
   format?: string;
-  /** 倒计时到达 0 / 计时到达 target 时回调。 */
+  /** 计时结束回调。 */
   onFinish?: () => void;
   /** 每次 tick 回调。 */
   onChange?: (msLeft: number) => void;

package/src/components/statistic/meta.md

@@ -0,0 +1,94 @@
+# Statistic
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+统计数值 Statistic
+突出展示数字或指标，支持前后缀、趋势箭头、千分位格式化和倒计时模式。
+
+## 使用场景
+
+- 仪表盘核心指标展示
+- 数据概览卡片（收入、用户量、转化率）
+- 倒计时 / 正计时场景
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `title` | `React.ReactNode` | – | – | 标题。 |
+| `value` | `number \| string` | – | ✓ | 数值。 |
+| `prefix` | `React.ReactNode` | – | – | 前缀（图标 / 货币符号）。 |
+| `suffix` | `React.ReactNode` | – | – | 后缀（单位）。 |
+| `precision` | `number` | – | – | 数值精度，仅 number 生效。 |
+| `groupSeparator` | `boolean` | – | – | 千分位分隔符。 |
+| `trend` | `'up' \| 'down' \| 'none'` | – | – | 趋势：`up`（绿色 ↑）/ `down`（红色 ↓）/ `none`。 |
+| `trendValue` | `string \| number` | – | – | 趋势百分比文字。 |
+| `valueClassName` | `string` | – | – | 数值区域额外样式。 |
+| `type` | `'countdown' \| 'countup'` | – | – | 计时类型：`countdown` 倒计时 / `countup` 正计时。 |
+| `target` | `number` | – | – | 目标时间（毫秒时间戳）。 |
+| `format` | `string` | – | – | 时间格式化字符串，支持 `HH` `mm` `ss` `SSS` `D`。 |
+| `onFinish` | `() => void` | – | – | 计时结束回调。 |
+| `onChange` | `(msLeft: number) => void` | – | – | 每次 tick 回调。 |
+
+## 示例
+
+### WithPrefixSuffix
+
+带前后缀与精度
+
+```tsx
+<div className="flex gap-8">
+  <Statistic
+    title="收入"
+    value={93812.5}
+    prefix={<DollarSign className="size-4" />}
+    precision={2}
+  />
+  <Statistic
+    title="团队人数"
+    value={28}
+    prefix={<Users className="size-4" />}
+    suffix="人"
+  />
+</div>
+```
+
+### Trend
+
+趋势
+
+```tsx
+<div className="flex gap-8">
+  <Statistic
+    title="周增长"
+    value={12.5}
+    precision={1}
+    trend="up"
+    trendValue="12.5%"
+    suffix="%"
+  />
+  <Statistic
+    title="周下降"
+    value={3.2}
+    precision={1}
+    trend="down"
+    trendValue="3.2%"
+    suffix="%"
+  />
+</div>
+```
+
+### Countdown
+
+倒计时
+
+```tsx
+<StatisticTimer
+  title="距离活动结束"
+  type="countdown"
+  target={Date.now() + 3600 * 1000}
+  format="HH:mm:ss"
+/>
+```

package/src/components/statistic/stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { DollarSign, Users } from 'lucide-react';
+
+import { Statistic, StatisticTimer } from '.';
+
+const meta: Meta<typeof Statistic> = {
+  title: '数据展示 · Data Display/Statistic 统计数值',
+  component: Statistic,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '统计数值组件，突出展示数字或指标，支持前后缀、趋势箭头、千分位格式化和倒计时模式。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Statistic>;
+
+/** 基础用法 */
+export const Default: Story = {
+  args: {
+    title: '活跃用户',
+    value: 112893,
+  },
+};
+
+/** 带前后缀与精度 */
+export const WithPrefixSuffix: Story = {
+  render: () => (
+    <div className="flex gap-8">
+      <Statistic
+        title="收入"
+        value={93812.5}
+        prefix={<DollarSign className="size-4" />}
+        precision={2}
+      />
+      <Statistic
+        title="团队人数"
+        value={28}
+        prefix={<Users className="size-4" />}
+        suffix="人"
+      />
+    </div>
+  ),
+};
+
+/** 趋势 */
+export const Trend: Story = {
+  render: () => (
+    <div className="flex gap-8">
+      <Statistic
+        title="周增长"
+        value={12.5}
+        precision={1}
+        trend="up"
+        trendValue="12.5%"
+        suffix="%"
+      />
+      <Statistic
+        title="周下降"
+        value={3.2}
+        precision={1}
+        trend="down"
+        trendValue="3.2%"
+        suffix="%"
+      />
+    </div>
+  ),
+};
+
+/** 倒计时 */
+export const Countdown: Story = {
+  render: () => (
+    <StatisticTimer
+      title="距离活动结束"
+      type="countdown"
+      target={Date.now() + 3600 * 1000}
+      format="HH:mm:ss"
+    />
+  ),
+};