diff --git a/.ua/index.json b/.ua/index.json index 4eaea4d..9825a02 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T15:02:00.489Z", + "generatedAt": "2026-10-26T15:03:08.889Z", "repoRoot": ".", "packages": [ { @@ -227,7 +227,8 @@ "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）", "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁", "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值", - "sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互" + "sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互", + "heatmap(props)：日历热力图，按周列 × 星期行铺格子、四档浓度表示当天数量，悬停看明细" ], "keyTypes": [ "ButtonProps", @@ -4475,6 +4476,51 @@ "改颜色在父级设 color：线、面积、圆点都读 currentColor，放进 card 或表格行自动跟随文字色", "少于两个点时画不出趋势，组件返回空图——请在外面判空并给「暂无数据」，别让它空着占位" ] + }, + { + "id": "heatmap", + "title": "日历热力图 Heatmap", + "demo": "sec-heat", + "props": [ + { + "n": "values", + "t": "{ date: string; count: number }[]", + "d": "每一项 = 某天与当天数值；date 用 YYYY-MM-DD，同日多条自动求和" + }, + { + "n": "weeks", + "t": "number", + "d": "显示最近多少周；缺省 12" + }, + { + "n": "cellSize", + "t": "number", + "d": "格子边长（px）；缺省 11" + }, + { + "n": "legendText", + "t": "string", + "d": "图例左端文案；缺省「少」（右端固定「多」）" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "可访问名；缺省「最近 N 周活跃度」" + }, + { + "n": "formatValue", + "t": "(count: number, date: string) => string", + "d": "悬停提示文案；缺省「日期 · 数量」" + } + ], + "example": "heatmap({ values: activity, weeks: 12, formatValue: (n, d) => d + ' 提交 ' + n + ' 次' })", + "steps": [ + "values 只给「有数据的那几天」即可：缺失的日期自动按 0 渲染，不必把 84 天全部补齐", + "末列永远对齐到本周（周一到周日完整七行），所以数据是滚动的，不会出现半截列", + "同一天多条记录会求和（合并成一个格子），上游按天预聚合也行，两种都吃", + "格子颜色是相对深浅：按序列最大值归一成四档——所以它说的是「哪天更密」，不是绝对值高低", + "默认 12 周、11px 格子；嵌进窄卡片就调小 weeks，看不出格子边界就调大 cellSize" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index a255ea1..af719b0 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）：84 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：85 个 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 fc697ec..bb1b93c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 84 个组件 + ui.css +│ │ └── ui/ # 85 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index 516d1f5..ac7afe4 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 可查漂移） ``` -## 组件（共 84 个） +## 组件（共 85 个） -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 +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 · heatmap · 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 / 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）。 +分组：表单（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 / heatmap / 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：84 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：85 个 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 1ad1f72..d479179 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -34,6 +34,7 @@ import { layout, jsonViewer, kbd, + heatmap, highlight, datePicker, transfer, @@ -1836,6 +1837,22 @@ const content = h( 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 }))), ), ), + section( + 'sec-heat', + '日历热力图', + 'heatmap：一周一列、七天一行，格子浓度表示当天数量（按最大值归一四档）；末列对齐到本周，悬停看具体日期与次数。', + (() => { + const today = new Date(); + const values: { date: string; count: number }[] = []; + for (let i = 0; i < 84; i += 1) { + const d = new Date(today.getTime() - i * 86400000); + const key = d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0'); + const count = (i * 7) % 5 === 0 ? 0 : (i * 3) % 7; // 伪随机但确定性：每次渲染同一图案 + values.push({ date: key, count }); + } + return heatmap({ values, weeks: 12, formatValue: (n, d) => d + ' 提交 ' + n + ' 次' }); + })(), + ), ); // 悬浮按钮：fixed 定位，挂 body 不参与页面布局 diff --git a/llms-full.txt b/llms-full.txt index d00a61d..37591e8 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T15:02:00.489Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T15:03:08.889Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -2394,6 +2394,33 @@ sparkline({ values: last7Days, width: 140, height: 36 }) 现场演示：apps/docs/demo.html#sec-spark +### heatmap — 日历热力图 Heatmap + +参数： + +- values：{ date: string; count: number }[] —— 每一项 = 某天与当天数值；date 用 YYYY-MM-DD，同日多条自动求和 +- weeks：number —— 显示最近多少周；缺省 12 +- cellSize：number —— 格子边长（px）；缺省 11 +- legendText：string —— 图例左端文案；缺省「少」（右端固定「多」） +- ariaLabel：string —— 可访问名；缺省「最近 N 周活跃度」 +- formatValue：(count: number, date: string) => string —— 悬停提示文案；缺省「日期 · 数量」 + +示例： + +``` +heatmap({ values: activity, weeks: 12, formatValue: (n, d) => d + ' 提交 ' + n + ' 次' }) +``` + +手把手： + +1. values 只给「有数据的那几天」即可：缺失的日期自动按 0 渲染，不必把 84 天全部补齐 +2. 末列永远对齐到本周（周一到周日完整七行），所以数据是滚动的，不会出现半截列 +3. 同一天多条记录会求和（合并成一个格子），上游按天预聚合也行，两种都吃 +4. 格子颜色是相对深浅：按序列最大值归一成四档——所以它说的是「哪天更密」，不是绝对值高低 +5. 默认 12 周、11px 格子；嵌进窄卡片就调小 weeks，看不出格子边界就调大 cellSize + +现场演示：apps/docs/demo.html#sec-heat + API 速览： - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调 @@ -2482,6 +2509,7 @@ API 速览： - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁 - relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值 - sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互 +- heatmap(props)：日历热力图，按周列 × 星期行铺格子、四档浓度表示当天数量，悬停看明细 一行用法： diff --git a/llms.txt b/llms.txt index 66da608..64138ab 100644 --- a/llms.txt +++ b/llms.txt @@ -133,6 +133,7 @@ - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁 - relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值 - sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互 + - heatmap(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/heatmap.ts b/packages/skin/ui/src/heatmap.ts new file mode 100644 index 0000000..71e275f --- /dev/null +++ b/packages/skin/ui/src/heatmap.ts @@ -0,0 +1,46 @@ +import { h } from '@ui-arch/frame'; +import type { HeatmapProps } from './types.js'; + +// 缺省：最近 12 周、格子 11px、周一为首行——与国内日历习惯一致 +const WEEKS = 12; +const CELL = 11; +const DAY = 86_400_000; +const LEVELS = 4; // 非零分四档，加上「零」共五档 + +/*** 补零与日期键：热力图的键必须与外部数据同一格式（YYYY-MM-DD） ***/ +const pad = (n: number): string => String(n).padStart(2, '0'); +const keyOf = (d: Date): string => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; + +/*** 日历热力图：按周列 × 星期行铺格子，颜色深浅表示当天数值；不画坐标轴，靠 title 看具体日期与数量 ***/ +export function heatmap(props: HeatmapProps): HTMLElement { + const weeks = props.weeks ?? WEEKS; + const cell = props.cellSize ?? CELL; + const counts = new Map(); + for (const item of props.values) counts.set(item.date, (counts.get(item.date) ?? 0) + item.count); // 同一天多条求和，不覆盖 + const max = Math.max(1, ...counts.values()); // 分母：至少 1，避免全零时除零 + // 末列对齐到「本周」：先取今天，再回退到本周末，保证最后一列是完整 7 行 + const today = new Date(); + today.setHours(0, 0, 0, 0); + const end = new Date(today.getTime() + (6 - ((today.getDay() + 6) % 7)) * DAY); // 周一起算的第 6 天（周日） + const start = new Date(end.getTime() - (weeks * 7 - 1) * DAY); + const grid = h('div', { class: 'ua-heat-grid', role: 'img', 'aria-label': props.ariaLabel ?? `最近 ${weeks} 周活跃度` }); + grid.style.gridTemplateRows = `repeat(7, ${cell}px)`; // 七行对应周一到周日，行高与格子边长同源 + for (let i = 0; i < weeks * 7; i += 1) { + const d = new Date(start.getTime() + i * DAY); + const n = counts.get(keyOf(d)) ?? 0; + const level = n === 0 ? 0 : Math.min(LEVELS, Math.ceil((n / max) * LEVELS)); // 归一成四档，最大那天必落在最高档 + const box = h('span', { class: `ua-heat-cell is-${level}` }); + box.style.width = `${cell}px`; + box.style.height = `${cell}px`; + box.title = props.formatValue ? props.formatValue(n, keyOf(d)) : `${keyOf(d)} · ${n}`; // 悬停看明细：热力图本身不标数字 + grid.append(box); + } + const legend = h( + 'div', + { class: 'ua-heat-legend' }, + h('span', { class: 'ua-heat-hint' }, props.legendText ?? '少'), + ...[0, 1, 2, 3, 4].map((lv) => h('span', { class: `ua-heat-cell is-${lv}` })), + h('span', { class: 'ua-heat-hint' }, '多'), + ); + return h('div', { class: 'ua-heat' }, grid, legend); +} diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index a275939..b20e80c 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -84,3 +84,4 @@ export { signaturePad } from './signaturePad.js'; export { loading } from './loading.js'; export { relativeTime } from './relativeTime.js'; export { sparkline } from './sparkline.js'; +export { heatmap } from './heatmap.js'; diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index f34a666..4fe7582 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -1097,3 +1097,13 @@ export interface SparklineProps { marker?: boolean; // 是否标记末点；缺省 true（一眼看出当前值位置） ariaLabel?: string; // 可访问名；缺省「趋势图」（趋势无法只靠图形传达，请把结论写进旁边文案） } + +/*** 日历热力图入参 ***/ +export interface HeatmapProps { + values: { date: string; count: number }[]; // 每一项 = 某天与当天数值；date 用 YYYY-MM-DD，同日多条自动求和 + weeks?: number; // 显示最近多少周；缺省 12 + cellSize?: number; // 格子边长（px）；缺省 11 + legendText?: string; // 图例左端文案；缺省「少」（右端固定「多」） + ariaLabel?: string; // 可访问名；缺省「最近 N 周活跃度」 + formatValue?: (count: number, date: string) => string; // 悬停提示文案；缺省「日期 · 数量」 +} diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 6446632..a504169 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -98,7 +98,8 @@ "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）", "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁", "relativeTime(props)：把时间戳渲染成「3 分钟前」并自动刷新，超阈值改显示绝对日期，title 恒给精确值", - "sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互" + "sparkline(props)：迷你趋势线，把数值序列压成折线（可填充 + 末点标记），无坐标轴无交互", + "heatmap(props)：日历热力图，按周列 × 星期行铺格子、四档浓度表示当天数量，悬停看明细" ], "keyTypes": [ "ButtonProps", @@ -4346,6 +4347,51 @@ "改颜色在父级设 color：线、面积、圆点都读 currentColor，放进 card 或表格行自动跟随文字色", "少于两个点时画不出趋势，组件返回空图——请在外面判空并给「暂无数据」，别让它空着占位" ] + }, + { + "id": "heatmap", + "title": "日历热力图 Heatmap", + "demo": "sec-heat", + "props": [ + { + "n": "values", + "t": "{ date: string; count: number }[]", + "d": "每一项 = 某天与当天数值；date 用 YYYY-MM-DD，同日多条自动求和" + }, + { + "n": "weeks", + "t": "number", + "d": "显示最近多少周；缺省 12" + }, + { + "n": "cellSize", + "t": "number", + "d": "格子边长（px）；缺省 11" + }, + { + "n": "legendText", + "t": "string", + "d": "图例左端文案；缺省「少」（右端固定「多」）" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "可访问名；缺省「最近 N 周活跃度」" + }, + { + "n": "formatValue", + "t": "(count: number, date: string) => string", + "d": "悬停提示文案；缺省「日期 · 数量」" + } + ], + "example": "heatmap({ values: activity, weeks: 12, formatValue: (n, d) => d + ' 提交 ' + n + ' 次' })", + "steps": [ + "values 只给「有数据的那几天」即可：缺失的日期自动按 0 渲染，不必把 84 天全部补齐", + "末列永远对齐到本周（周一到周日完整七行），所以数据是滚动的，不会出现半截列", + "同一天多条记录会求和（合并成一个格子），上游按天预聚合也行，两种都吃", + "格子颜色是相对深浅：按序列最大值归一成四档——所以它说的是「哪天更密」，不是绝对值高低", + "默认 12 周、11px 格子；嵌进窄卡片就调小 weeks，看不出格子边界就调大 cellSize" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index 0054fc9..fee9d0b 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -5808,3 +5808,56 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); } .ua-spark-dot { fill: currentColor; } + +/* ---- 日历热力图：格子按列排（一周一列），深浅四档 + 零档；色阶全部由 accent 与透明度档派生 ---- */ +.ua-heat { + display: inline-flex; + flex-direction: column; + gap: var(--ua-space-2); +} + +.ua-heat-grid { + display: grid; + grid-auto-flow: column; /* 先竖后横：一列就是一周 */ + grid-template-columns: repeat(auto-fill, auto); + gap: var(--ua-space-1); +} + +.ua-heat-cell { + display: block; + width: var(--ua-space-3); + height: var(--ua-space-3); + border-radius: var(--ua-radius-sm); +} + +/* 五档色阶：0 档是凹陷底（无活动），1-4 档 accent 浓度递增 */ +.ua-heat-cell.is-0 { + background: var(--ua-color-surface-inset); +} + +.ua-heat-cell.is-1 { + background: color-mix(in srgb, var(--ua-color-accent) var(--ua-alpha-soft), transparent); +} + +.ua-heat-cell.is-2 { + background: color-mix(in srgb, var(--ua-color-accent) var(--ua-alpha-tint), transparent); +} + +.ua-heat-cell.is-3 { + background: color-mix(in srgb, var(--ua-color-accent) var(--ua-alpha-mid), transparent); +} + +.ua-heat-cell.is-4 { + background: var(--ua-color-accent); +} + +.ua-heat-legend { + display: flex; + align-items: center; + gap: var(--ua-space-1); +} + +.ua-heat-hint { + color: var(--ua-color-text-faint); + font-size: var(--ua-font-size-xs); +}