diff --git a/.ua/index.json b/.ua/index.json index 4f928da..4eaea4d 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T15:00:29.937Z", + "generatedAt": "2026-10-26T15:02:00.489Z", "repoRoot": ".", "packages": [ { @@ -226,7 +226,8 @@ "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮", "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）", "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁", - "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值" + "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值", + "sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互" ], "keyTypes": [ "ButtonProps", @@ -4429,6 +4430,51 @@ "精确时间放在 title：鼠标悬停可看，不必为「想知道具体哪天」再点开详情", "时间非法（空串 / 格式错）不猜也不抛，显示 fallback（缺省「—」），列表不会因一条脏数据空白" ] + }, + { + "id": "sparkline", + "title": "迷你趋势线 Sparkline", + "demo": "sec-spark", + "props": [ + { + "n": "values", + "t": "number[]", + "d": "数值序列（按时间顺序）；非有限数会被剔除" + }, + { + "n": "width", + "t": "number", + "d": "宽度（px）；缺省 120" + }, + { + "n": "height", + "t": "number", + "d": "高度（px）；缺省 32" + }, + { + "n": "area", + "t": "boolean", + "d": "是否填充折线下方面积；缺省 true" + }, + { + "n": "marker", + "t": "boolean", + "d": "是否标记末点；缺省 true（一眼看出当前值位置）" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "可访问名；缺省「趋势图」" + } + ], + "example": "sparkline({ values: last7Days, width: 140, height: 36 })", + "steps": [ + "把按时间顺序的数值数组交给 values：不用自己算最大最小与像素坐标，组件按 viewBox 等比缩放", + "和 statistic 并排用：主数值走 statistic、走向走 sparkline，趋势线不画坐标轴也不带交互", + "不要面积就传 area: false，不要末点圆点传 marker: false（极窄的表格单元格里圆点会糊成一团）", + "改颜色在父级设 color：线、面积、圆点都读 currentColor，放进 card 或表格行自动跟随文字色", + "少于两个点时画不出趋势，组件返回空图——请在外面判空并给「暂无数据」，别让它空着占位" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index e92750c..a255ea1 100644 --- a/AGENTS.md +++ b/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）：83 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：84 个 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 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index b072c4b..fc697ec 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 83 个组件 + ui.css +│ │ └── ui/ # 84 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index 8297b59..516d1f5 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全 npm run changelog # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移） ``` -## 组件（共 83 个） +## 组件（共 84 个） -accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · loading · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · relativeTime · result · segmented · select · signaturePad · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark +accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · loading · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · relativeTime · result · segmented · select · signaturePad · skeleton · slider · space · sparkline · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark -分组：表单（button / copyButton / signaturePad / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / loading / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / relativeTime / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。 +分组：表单（button / copyButton / signaturePad / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / loading / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / relativeTime / sparkline / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。 ## 可访问性约定 @@ -34,7 +34,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup |---|---| | `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：83 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：84 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） | | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server | | `apps/demo` | 交互演示（esbuild 打包成单文件） | diff --git a/apps/demo/main.ts b/apps/demo/main.ts index a48475f..1ad1f72 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -78,6 +78,7 @@ import { skeleton, splitter, slider, + sparkline, space, spinner, stepper, @@ -1826,6 +1827,15 @@ const content = h( h('span', null, '脏数据：'), relativeTime({ value: 'not-a-date' }), ), ), + section( + 'sec-spark', + '迷你趋势线', + 'sparkline：把数值序列压成一条折线，可选面积与末点标记；不画坐标轴、不带交互，只表达走向——主数值交给 statistic。', + h('div', { class: 'row' }, + card({ title: '订单量（7 天）' }, h('div', { style: 'display:flex;align-items:center;gap:12px' }, statistic({ value: signal(1284) }), sparkline({ values: [820, 932, 901, 934, 1290, 1330, 1284], width: 140, height: 36 }))), + card({ title: '转化率（30 天）' }, h('div', { style: 'display:flex;align-items:center;gap:12px' }, statistic({ value: signal(3.62), precision: 2, suffix: '%' }), sparkline({ values: [4.1, 3.9, 4.0, 3.8, 3.7, 3.9, 3.6], area: false }))), + ), + ), ); // 悬浮按钮：fixed 定位，挂 body 不参与页面布局 diff --git a/llms-full.txt b/llms-full.txt index 9f15ee7..d00a61d 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T15:00:29.937Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T15:02:00.489Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -2367,6 +2367,33 @@ relativeTime({ value: row.createdAt, ariaLabel: '下单时间' }) 现场演示：apps/docs/demo.html#sec-reltime +### sparkline — 迷你趋势线 Sparkline + +参数： + +- values：number[] —— 数值序列（按时间顺序）；非有限数会被剔除 +- width：number —— 宽度（px）；缺省 120 +- height：number —— 高度（px）；缺省 32 +- area：boolean —— 是否填充折线下方面积；缺省 true +- marker：boolean —— 是否标记末点；缺省 true（一眼看出当前值位置） +- ariaLabel：string —— 可访问名；缺省「趋势图」 + +示例： + +``` +sparkline({ values: last7Days, width: 140, height: 36 }) +``` + +手把手： + +1. 把按时间顺序的数值数组交给 values：不用自己算最大最小与像素坐标，组件按 viewBox 等比缩放 +2. 和 statistic 并排用：主数值走 statistic、走向走 sparkline，趋势线不画坐标轴也不带交互 +3. 不要面积就传 area: false，不要末点圆点传 marker: false（极窄的表格单元格里圆点会糊成一团） +4. 改颜色在父级设 color：线、面积、圆点都读 currentColor，放进 card 或表格行自动跟随文字色 +5. 少于两个点时画不出趋势，组件返回空图——请在外面判空并给「暂无数据」，别让它空着占位 + +现场演示：apps/docs/demo.html#sec-spark + API 速览： - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调 @@ -2454,6 +2481,7 @@ API 速览： - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty） - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁 - relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值 +- sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互 一行用法： diff --git a/llms.txt b/llms.txt index 64f1b64..66da608 100644 --- a/llms.txt +++ b/llms.txt @@ -132,6 +132,7 @@ - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty） - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁 - relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值 + - sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')` - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调 diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index 7d68973..a275939 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -83,3 +83,4 @@ export { codeBlock } from './codeBlock.js'; export { signaturePad } from './signaturePad.js'; export { loading } from './loading.js'; export { relativeTime } from './relativeTime.js'; +export { sparkline } from './sparkline.js'; diff --git a/packages/skin/ui/src/sparkline.ts b/packages/skin/ui/src/sparkline.ts new file mode 100644 index 0000000..01e191f --- /dev/null +++ b/packages/skin/ui/src/sparkline.ts @@ -0,0 +1,41 @@ +import { h } from '@ui-arch/frame'; +import type { SparklineProps } from './types.js'; + +// SVG 命名空间：createElement 不认 svg 标签，必须走 createElementNS +const NS = 'http://www.w3.org/2000/svg'; +// 缺省尺寸：120×32 塞得进统计卡片的右上角 +const W = 120; +const H = 32; + +/*** 建 SVG 元素并批量写属性：svg 的属性都得 setAttribute，写个小工具省掉每处重复 ***/ +function svgEl(tag: string, attrs: Record): SVGElement { + const el = document.createElementNS(NS, tag); + for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, String(v)); + return el; +} + +/*** 迷你趋势线：把一串数值压成一条折线（可选面积填充 + 末点标记），不画坐标轴、不带交互，只表达走向 ***/ +export function sparkline(props: SparklineProps): SVGElement { + const values = props.values.filter((v) => Number.isFinite(v)); // 脏数据先剔掉，否则整条线会被一个 undefined 拉平 + const w = props.width ?? W; + const hgt = props.height ?? H; + const pad = 2; // 内缩 2px：线宽与末点圆点不会被 viewBox 边缘裁掉 + const svg = svgEl('svg', { viewBox: `0 0 ${w} ${hgt}`, width: w, height: hgt, class: 'ua-spark', role: 'img', 'aria-label': props.ariaLabel ?? '趋势图' }); + if (values.length < 2) return svg; // 少于两点没有「趋势」可言：给空图，别画一根假横线 + const min = Math.min(...values); + const max = Math.max(...values); + const span = max - min || 1; // 全等值时除零保护：所有点落在中线 + const x = (i: number): number => pad + (i * (w - pad * 2)) / (values.length - 1); // 首末点贴边，中间均分 + const y = (v: number): number => pad + (1 - (v - min) / span) * (hgt - pad * 2); // 值越大越靠上（SVG y 轴向下） + const points = values.map((v, i) => `${x(i).toFixed(2)},${y(v).toFixed(2)}`).join(' '); + if (props.area !== false) { + // 面积：折线两端下探到底边闭合，填充走 currentColor 的低透明度（颜色由 CSS 的 color 决定） + svg.append(svgEl('polygon', { points: `${points} ${x(values.length - 1).toFixed(2)},${hgt} ${x(0).toFixed(2)},${hgt}`, class: 'ua-spark-area' })); + } + svg.append(svgEl('polyline', { points, class: 'ua-spark-line', 'stroke-linejoin': 'round', 'stroke-linecap': 'round' })); + if (props.marker !== false) { + // 末点标记：一眼看出当前值落在哪，不用去数最后一段的斜率 + svg.append(svgEl('circle', { cx: x(values.length - 1).toFixed(2), cy: y(values[values.length - 1]).toFixed(2), r: 2, class: 'ua-spark-dot' })); + } + return svg; +} diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index 8818e72..f34a666 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -1087,3 +1087,13 @@ export interface RelativeTimeProps { fallback?: string; // 时间非法时的占位文案；缺省「—」 ariaLabel?: string; // 可访问名（如「下单时间」），让读屏知道这个时间是什么 } + +/*** 迷你趋势线入参 ***/ +export interface SparklineProps { + values: number[]; // 数值序列（按时间顺序）；非有限数会被剔除 + width?: number; // 宽度（px）；缺省 120 + height?: number; // 高度（px）；缺省 32 + area?: boolean; // 是否填充折线下方面积；缺省 true + marker?: boolean; // 是否标记末点；缺省 true（一眼看出当前值位置） + ariaLabel?: string; // 可访问名；缺省「趋势图」（趋势无法只靠图形传达，请把结论写进旁边文案） +} diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 3e1cee8..6446632 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -97,7 +97,8 @@ "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮", "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）", "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁", - "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值" + "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值", + "sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互" ], "keyTypes": [ "ButtonProps", @@ -4300,6 +4301,51 @@ "精确时间放在 title：鼠标悬停可看，不必为「想知道具体哪天」再点开详情", "时间非法（空串 / 格式错）不猜也不抛，显示 fallback（缺省「—」），列表不会因一条脏数据空白" ] + }, + { + "id": "sparkline", + "title": "迷你趋势线 Sparkline", + "demo": "sec-spark", + "props": [ + { + "n": "values", + "t": "number[]", + "d": "数值序列（按时间顺序）；非有限数会被剔除" + }, + { + "n": "width", + "t": "number", + "d": "宽度（px）；缺省 120" + }, + { + "n": "height", + "t": "number", + "d": "高度（px）；缺省 32" + }, + { + "n": "area", + "t": "boolean", + "d": "是否填充折线下方面积；缺省 true" + }, + { + "n": "marker", + "t": "boolean", + "d": "是否标记末点；缺省 true（一眼看出当前值位置）" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "可访问名；缺省「趋势图」" + } + ], + "example": "sparkline({ values: last7Days, width: 140, height: 36 })", + "steps": [ + "把按时间顺序的数值数组交给 values：不用自己算最大最小与像素坐标，组件按 viewBox 等比缩放", + "和 statistic 并排用：主数值走 statistic、走向走 sparkline，趋势线不画坐标轴也不带交互", + "不要面积就传 area: false，不要末点圆点传 marker: false（极窄的表格单元格里圆点会糊成一团）", + "改颜色在父级设 color：线、面积、圆点都读 currentColor，放进 card 或表格行自动跟随文字色", + "少于两个点时画不出趋势，组件返回空图——请在外面判空并给「暂无数据」，别让它空着占位" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index decf119..0054fc9 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -5786,3 +5786,25 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); } font-variant-numeric: tabular-nums; /* 等宽数字：列表里时间列不左右抖动 */ white-space: nowrap; /* 「3 分钟前」不该被折成两行 */ } + +/* ---- 迷你趋势线：颜色一律走 currentColor，因此放进任何容器都自动跟随该处文字色 ---- */ +.ua-spark { + display: block; + overflow: visible; /* 末点圆点可能压在边缘，别被 svg 自身裁掉 */ + color: var(--ua-color-accent); /* 缺省跟主题强调色；想换色在父级改 color 即可 */ +} + +.ua-spark-line { + fill: none; + stroke: currentColor; + stroke-width: 1.5; /* 细线：趋势线是辅助信息，不该抢主数值 */ +} + +.ua-spark-area { + fill: color-mix(in srgb, currentColor var(--ua-alpha-tint), transparent); /* 面积比线更淡一层，避免压过折线 */ + stroke: none; +} + +.ua-spark-dot { + fill: currentColor; +}