iter(g10): 新增 statistic 统计数值组件

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T02:22:42.729Z",
+  "generatedAt": "2026-10-26T02:24:35.622Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -179,7 +179,8 @@
           "image(props)：图片，缩略图点击 / 回车开遮罩大图预览（Esc 或点击遮罩关闭），width 控制缩略宽",
           "timeline(props)：时间线，items 按序渲染纵向事件流（标题 / 时间 / 正文 + 语义色节点），mode 控制轴线左右，pending 追加进行中节点",
           "segmented(props)：分段控制器，胶囊分段 + 滑动滑块，value 信号双向绑定，←→ 环形导航，整组或单项可禁用",
-          "descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列"
+          "descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列",
+          "statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -221,7 +222,8 @@
           "TimelineProps",
           "SegmentedProps",
           "DescriptionItem",
-          "DescriptionsProps"
+          "DescriptionsProps",
+          "StatisticProps"
         ]
       },
       "usage": "const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')",
@@ -1711,6 +1713,54 @@
               "窄屏自动降为单列，无需在调用方写媒体查询",
               "纯展示组件，无状态无回调：值变了由调用方重新渲染或传函数式 value"
             ]
+          },
+          {
+            "id": "statistic",
+            "title": "统计数值 Statistic",
+            "demo": "sec-statistic",
+            "props": [
+              {
+                "n": "title",
+                "t": "string",
+                "d": "指标名（小字灰标题）；缺省不渲染"
+              },
+              {
+                "n": "value",
+                "t": "Signal<number>",
+                "r": 1,
+                "d": "数值信号：变化时从当前显示值滚动到新值，首跑即入场动画"
+              },
+              {
+                "n": "precision",
+                "t": "number",
+                "d": "小数位，千分位分隔自动带；缺省 0",
+                "df": "0"
+              },
+              {
+                "n": "prefix",
+                "t": "string",
+                "d": "数字前缀（如 ¥）；缺省不渲染"
+              },
+              {
+                "n": "suffix",
+                "t": "string",
+                "d": "数字后缀（如 元 / %）；缺省不渲染"
+              },
+              {
+                "n": "trend",
+                "t": "'up' | 'down'",
+                "d": "环比方向：up 红 / down 绿（A 股涨红跌绿口径）；缺省不渲染"
+              }
+            ],
+            "example": "const gmv = signal(128000); statistic({ title: '本月 GMV', value: gmv, prefix: '¥', precision: 2, trend: 'up' })",
+            "steps": [
+              "value 必须传信号：组件用 effect 监听，值变了自动滚动过渡，不要在外部手动改文本",
+              "首跑也会从 0 滚到目标值（入场动画）；不想要就初始化信号为终值后在挂载后再改",
+              "precision 控制小数位，千分位由 toLocaleString 自动加，不要自己拼格式化",
+              "trend 只表达方向与颜色（涨红跌绿），数值本身与环比幅度仍由调用方组织",
+              "多条指标并排时用 descriptions 或 flex 容器排列，本组件不自带网格",
+              "用户开启「减弱动效」时组件直接落终值，无需调用方判断"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：37 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：38 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 37 个组件 + ui.css
+│   │   └── ui/               # 38 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -11,13 +11,13 @@ npm run demo            # 打开演示：apps/demo/dist/demo.html
 npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt
 ```
 
-## 组件（共 37 个）
+## 组件（共 38 个）
 
 <!-- ua:components -->
-accordion · alert · avatar · badge · breadcrumb · button · card · checkbox · dataTable · descriptions · divider · drawer · empty · form · image · inputNumber · menu · modal · pagination · popover · progress · radioGroup · rate · segmented · select · skeleton · slider · spinner · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip
+accordion · alert · avatar · badge · breadcrumb · button · card · checkbox · dataTable · descriptions · divider · drawer · empty · form · image · inputNumber · menu · modal · pagination · popover · progress · radioGroup · rate · segmented · select · skeleton · slider · spinner · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip
 <!-- /ua:components -->
 
-分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / segmented / form / formItem）、反馈（alert / toast / spinner / progress / skeleton / badge / empty）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper）、数据（dataTable / descriptions / tag / avatar / card）、其他（divider / timeline）。
+分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / segmented / form / formItem）、反馈（alert / toast / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper）、数据（dataTable / descriptions / tag / avatar / card）、其他（divider / timeline）。
 
 ## 目录
 
@@ -25,7 +25,7 @@ accordion · alert · avatar · badge · breadcrumb · button · card · checkbo
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：37 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：38 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -39,6 +39,7 @@ import {
   slider,
   spinner,
   stepper,
+  statistic,
   switchButton,
   tabs,
   tag,
@@ -154,6 +155,10 @@ const menuPick = signal('');
 // —— 禁用态演示：开关信号同时绑定 switch 的 checked 与 checkbox 的 disabled ——
 const locked = signal(true);
 
+// —— 统计数值：两个指标共用同一组按钮刷新，演示滚动过渡 ——
+const gmv = signal(128000);
+const orders = signal(2048);
+
 // —— 分段控制器：两个实例共用同一信号，演示信号驱动同步与整组禁用 ——
 const range = signal('week');
 
@@ -449,6 +454,25 @@ const content = h(
       button({ label: '导出', variant: 'ghost' }),
     ),
   ),
+  section(
+    'sec-statistic',
+    '统计数值',
+    'statistic：大号等宽数字 + 前后缀 + 环比趋势；value 变化时 400ms 缓出滚动（减弱动效偏好下直落终值）。',
+    h(
+      'div',
+      { class: 'row' },
+      statistic({ title: '本月 GMV', value: gmv, prefix: '¥', precision: 2, trend: 'up' }),
+      statistic({ title: '订单数', value: orders, suffix: '单', trend: 'down' }),
+    ),
+    h(
+      'div',
+      { class: 'row' },
+      button({ label: '刷新数据', variant: 'ghost', onClick: () => {
+        gmv(gmv() + Math.round(Math.random() * 20000 - 8000)); // 随机涨跌，演示双向滚动
+        orders(orders() + Math.round(Math.random() * 200 - 80));
+      } }),
+    ),
+  ),
   section(
     'sec-descriptions',
     '描述列表',

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T02:22:42.729Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T02:24:35.622Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -977,6 +977,34 @@ descriptions({ title: '订单信息', column: 2, bordered: true, items: [{ label
 
 现场演示：apps/docs/demo.html#sec-descriptions
 
+### statistic — 统计数值 Statistic
+
+参数：
+
+- title：string —— 指标名（小字灰标题）；缺省不渲染
+- value（必填）：Signal<number> —— 数值信号：变化时从当前显示值滚动到新值，首跑即入场动画
+- precision（默认 0）：number —— 小数位，千分位分隔自动带；缺省 0
+- prefix：string —— 数字前缀（如 ¥）；缺省不渲染
+- suffix：string —— 数字后缀（如 元 / %）；缺省不渲染
+- trend：'up' | 'down' —— 环比方向：up 红 / down 绿（A 股涨红跌绿口径）；缺省不渲染
+
+示例：
+
+```
+const gmv = signal(128000); statistic({ title: '本月 GMV', value: gmv, prefix: '¥', precision: 2, trend: 'up' })
+```
+
+手把手：
+
+1. value 必须传信号：组件用 effect 监听，值变了自动滚动过渡，不要在外部手动改文本
+2. 首跑也会从 0 滚到目标值（入场动画）；不想要就初始化信号为终值后在挂载后再改
+3. precision 控制小数位，千分位由 toLocaleString 自动加，不要自己拼格式化
+4. trend 只表达方向与颜色（涨红跌绿），数值本身与环比幅度仍由调用方组织
+5. 多条指标并排时用 descriptions 或 flex 容器排列，本组件不自带网格
+6. 用户开启「减弱动效」时组件直接落终值，无需调用方判断
+
+现场演示：apps/docs/demo.html#sec-statistic
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用
@@ -1017,6 +1045,7 @@ API 速览：
 - timeline(props)：时间线，items 按序渲染纵向事件流（标题 / 时间 / 正文 + 语义色节点），mode 控制轴线左右，pending 追加进行中节点
 - segmented(props)：分段控制器，胶囊分段 + 滑动滑块，value 信号双向绑定，←→ 环形导航，整组或单项可禁用
 - descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列
+- statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值
 
 一行用法：
 

llms.txt

@@ -85,6 +85,7 @@
   - timeline(props)：时间线，items 按序渲染纵向事件流（标题 / 时间 / 正文 + 语义色节点），mode 控制轴线左右，pending 追加进行中节点
   - segmented(props)：分段控制器，胶囊分段 + 滑动滑块，value 信号双向绑定，←→ 环形导航，整组或单项可禁用
   - descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列
+  - statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/index.ts

@@ -31,6 +31,7 @@ export { rate } from './rate.js';
 export { empty } from './empty.js';
 export { divider } from './divider.js';
 export { descriptions } from './descriptions.js';
+export { statistic } from './statistic.js';
 export { timeline } from './timeline.js';
 export { modal } from './modal.js';
 export { drawer } from './drawer.js';

packages/skin/ui/src/statistic.ts

@@ -0,0 +1,41 @@
+import { effect, h } from '@ui-arch/frame';
+import type { StatisticProps } from './types.js';
+
+/*** 统计数值：标题 + 大号数字 + 前后缀 + 环比趋势，数值变化时 rAF 滚动过渡（400ms，easeOutCubic） ***/
+export function statistic(props: StatisticProps): HTMLElement {
+  // —— 状态集中声明 ——
+  const precision = props.precision ?? 0; // 小数位
+  const reduce = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches; // 减弱动效偏好
+  const num = h('span', { class: 'ua-stat-num' }, '0'); // 数字节点：逐帧改文本，不重建 DOM
+  let shown = 0; // 当前显示中的值（动画中间态）
+  let raf = 0;   // 进行中的动画帧句柄，重复调用时先取消
+
+  /*** 格式化：千分位 + 固定小数位 ***/
+  const fmt = (v: number): string => v.toLocaleString('zh-CN', { minimumFractionDigits: precision, maximumFractionDigits: precision });
+
+  /*** 从当前显示值滚到目标值；偏好减弱动效时直接落终值 ***/
+  const roll = (to: number): void => {
+    cancelAnimationFrame(raf); // 新目标打断上一段动画，避免数值打架
+    if (reduce) { shown = to; num.textContent = fmt(to); return; }
+    const from = shown;
+    const start = performance.now();
+    const step = (t: number): void => {
+      const k = Math.min((t - start) / 400, 1); // 归一化进度 0→1
+      shown = from + (to - from) * (1 - (1 - k) ** 3); // easeOutCubic 缓出
+      num.textContent = fmt(shown);
+      if (k < 1) raf = requestAnimationFrame(step);
+      else shown = to; // 收尾对齐目标值，避免浮点残差
+    };
+    raf = requestAnimationFrame(step);
+  };
+
+  const row = h('div', { class: 'ua-stat-value' },
+    props.prefix ? h('span', { class: 'ua-stat-affix' }, props.prefix) : null,
+    num,
+    props.suffix ? h('span', { class: 'ua-stat-affix' }, props.suffix) : null,
+    props.trend ? h('span', { class: `ua-stat-trend is-${props.trend}` }, props.trend === 'up' ? '▲' : '▼') : null);
+  const view = h('div', { class: 'ua-stat' }, props.title ? h('div', { class: 'ua-stat-title' }, props.title) : null, row);
+
+  effect(() => roll(props.value())); // 信号变化即滚动到新值（首跑做入场动画）
+  return view;
+}

packages/skin/ui/src/types.ts

@@ -388,4 +388,14 @@ export interface DescriptionsProps {
   title?: string;             // 分组标题；缺省不渲染
 }
 
+/*** 统计数值入参 ***/
+export interface StatisticProps {
+  title?: string;        // 指标名；缺省不渲染标题行
+  value: Signal<number>; // 数值信号：变化时滚动过渡到新值（首跑即入场动画）
+  precision?: number;    // 小数位；缺省 0
+  prefix?: string;       // 数字前缀（如 ¥）；缺省不渲染
+  suffix?: string;       // 数字后缀（如 元 / %）；缺省不渲染
+  trend?: 'up' | 'down'; // 环比方向：up 红 / down 绿（A 股口径）；缺省不渲染
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方

packages/skin/ui/ua.manifest.json

@@ -50,7 +50,8 @@
       "image(props)：图片，缩略图点击 / 回车开遮罩大图预览（Esc 或点击遮罩关闭），width 控制缩略宽",
       "timeline(props)：时间线，items 按序渲染纵向事件流（标题 / 时间 / 正文 + 语义色节点），mode 控制轴线左右，pending 追加进行中节点",
       "segmented(props)：分段控制器，胶囊分段 + 滑动滑块，value 信号双向绑定，←→ 环形导航，整组或单项可禁用",
-      "descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列"
+      "descriptions(props)：描述列表，items(label/value/span) 铺进 column 列网格，bordered 切表格形态，窄屏自动单列",
+      "statistic(props)：统计数值，标题 + 大号数字 + 前后缀 + 环比趋势，value 变化时 rAF 滚动过渡（400ms easeOutCubic），减弱动效偏好下直落终值"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -92,7 +93,8 @@
       "TimelineProps",
       "SegmentedProps",
       "DescriptionItem",
-      "DescriptionsProps"
+      "DescriptionsProps",
+      "StatisticProps"
     ]
   },
   "usage": "const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')",
@@ -1582,6 +1584,54 @@
           "窄屏自动降为单列，无需在调用方写媒体查询",
           "纯展示组件，无状态无回调：值变了由调用方重新渲染或传函数式 value"
         ]
+      },
+      {
+        "id": "statistic",
+        "title": "统计数值 Statistic",
+        "demo": "sec-statistic",
+        "props": [
+          {
+            "n": "title",
+            "t": "string",
+            "d": "指标名（小字灰标题）；缺省不渲染"
+          },
+          {
+            "n": "value",
+            "t": "Signal<number>",
+            "r": 1,
+            "d": "数值信号：变化时从当前显示值滚动到新值，首跑即入场动画"
+          },
+          {
+            "n": "precision",
+            "t": "number",
+            "d": "小数位，千分位分隔自动带；缺省 0",
+            "df": "0"
+          },
+          {
+            "n": "prefix",
+            "t": "string",
+            "d": "数字前缀（如 ¥）；缺省不渲染"
+          },
+          {
+            "n": "suffix",
+            "t": "string",
+            "d": "数字后缀（如 元 / %）；缺省不渲染"
+          },
+          {
+            "n": "trend",
+            "t": "'up' | 'down'",
+            "d": "环比方向：up 红 / down 绿（A 股涨红跌绿口径）；缺省不渲染"
+          }
+        ],
+        "example": "const gmv = signal(128000); statistic({ title: '本月 GMV', value: gmv, prefix: '¥', precision: 2, trend: 'up' })",
+        "steps": [
+          "value 必须传信号：组件用 effect 监听，值变了自动滚动过渡，不要在外部手动改文本",
+          "首跑也会从 0 滚到目标值（入场动画）；不想要就初始化信号为终值后在挂载后再改",
+          "precision 控制小数位，千分位由 toLocaleString 自动加，不要自己拼格式化",
+          "trend 只表达方向与颜色（涨红跌绿），数值本身与环比幅度仍由调用方组织",
+          "多条指标并排时用 descriptions 或 flex 容器排列，本组件不自带网格",
+          "用户开启「减弱动效」时组件直接落终值，无需调用方判断"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -1880,3 +1880,45 @@ button.ua-step-dot:hover {
     grid-template-columns: minmax(0, 1fr);
   }
 }
+
+/* —— 统计数值：大号等宽数字 + 前后缀 + 环比趋势，涨红跌绿 —— */
+.ua-stat {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.ua-stat-title {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-sm);
+}
+.ua-stat-value {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 3px;
+}
+.ua-stat-num {
+  color: var(--ua-color-text);
+  font-size: 26px;
+  font-weight: 600;
+  line-height: 1.2;
+  font-variant-numeric: tabular-nums;
+}
+.ua-stat-affix {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-sm);
+}
+.ua-stat-trend {
+  font-size: var(--ua-font-size-sm);
+  margin-left: 2px;
+}
+.ua-stat-trend.is-up {
+  color: var(--ua-color-danger);
+}
+.ua-stat-trend.is-down {
+  color: var(--ua-color-success);
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-stat-num {
+    transition: none !important;
+  }
+}