iter(g277): 新增日历热力图组件

.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"
+            ]
           }
         ]
       },

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

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，不发布）

README.md

@@ -12,13 +12,13 @@ npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全
 npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
 ```
 
-## 组件（共 84 个）
+## 组件（共 85 个）
 
 <!-- ua:components -->
-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
 <!-- /ua:components -->
 
-分组：表单（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 打包成单文件） |

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 不参与页面布局

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)：日历热力图，按周列 × 星期行铺格子、四档浓度表示当天数量，悬停看明细
 
 一行用法：
 

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 为回调

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<string, number>();
+  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);
+}

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';

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; // 悬停提示文案；缺省「日期 · 数量」
+}

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"
+        ]
       }
     ]
   }

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);
+}