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

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