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

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