@yewdiel21/motion-kit 0.14.0 → 0.16.0

package/src/components/filter-builder/engine.ts

@@ -7,6 +7,7 @@ import {
   type FilterField, type FilterGroup, type FilterNode, type FilterRule,
 } from '../../core/filter';
 import { blurIn, collapse, press, rollDigits, shake } from '../../motion/micro';
+import { createSelect, type SelectInstance } from '../select/engine';
 import { slideIndicator } from '../../motion/indicator';
 
 /*
@@ -102,6 +103,28 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
     root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: cloneFilter(model), summary: describeFilter(model, fields) } }));
   };
 
+  // ── Choices: every <select> is the kit's select (it opens the kit's menu), kept in step with the select itself, so
+  // the change handlers below read it as always. Each one lives as long as its row.
+  const selects = new Map<HTMLElement, SelectInstance>();
+  const choice = (select: HTMLSelectElement, label: string) => {
+    const box = el('span', { class: 'mk-select', 'data-mk-fb-select': '' });
+    box.append(select);
+    selects.set(box, createSelect(box, { label }));
+    return box;
+  };
+  /** The selects inside `container` go (before it is emptied or removed). */
+  const dropChoices = (container: Element) => {
+    for (const [box, select] of selects) {
+      if (!container.contains(box)) continue;
+      select.destroy();
+      selects.delete(box);
+    }
+  };
+  scope.add(() => {
+    for (const select of selects.values()) select.destroy();
+    selects.clear();
+  });
+
   // ── Value controls ───────────────────────────────────────────────────────
   const valueControl = (rule: FilterRule, index: 0 | 1) => {
     const field = fieldOf(rule.field);
@@ -111,6 +134,9 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
     if (type === 'select') {
       control = el('select');
       control.append(el('option', { value: '' }, 'Elige…'), ...(field?.options ?? []).map((option) => el('option', { value: option.value }, option.label)));
+      control.dataset.mkFbValue = String(index);
+      control.value = current === null || current === undefined ? '' : String(current);
+      return choice(control, index === 1 ? 'Hasta' : operatorOf(field, rule.operator).arity === 2 ? 'Desde' : 'Valor');
     } else {
       control = el('input');
       control.type = type === 'number' ? 'text' : type === 'date' ? 'date' : 'text';
@@ -126,6 +152,7 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
   const fillValues = (row: HTMLElement, rule: FilterRule) => {
     const host = row.querySelector<HTMLElement>('[data-mk-fb-values]')!;
     const { arity } = operatorOf(fieldOf(rule.field), rule.operator);
+    dropChoices(host);
     host.replaceChildren();
     if (arity === 0) return;
     host.append(valueControl(rule, 0));
@@ -147,7 +174,7 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
     const values = el('span', { 'data-mk-fb-values': '' });
     const remove = el('button', { type: 'button', 'data-mk-fb-remove': '', 'aria-label': 'Quitar condición' });
     remove.innerHTML = CLOSE;
-    row.append(field, operator, values, remove);
+    row.append(choice(field, 'Campo'), choice(operator, 'Operador'), values, remove);
     fillOperators(row, rule);
     fillValues(row, rule);
     return row;
@@ -195,6 +222,7 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
   };
 
   const render = () => {
+    dropChoices(tree);
     tree.replaceChildren(groupBox(model, 0));
     placeIndicators(true);
     describe();
@@ -220,7 +248,7 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
     parts.push(element);
     if (isGroup(node)) placeIndicators(true);
     keep(blurIn(parts, { from: 'rise', stagger: 0.04 }));
-    element.querySelector<HTMLElement>('select, input')?.focus();
+    element.querySelector<HTMLElement>('[data-mk-select-trigger], input')?.focus();
     emit();
   };
 
@@ -236,6 +264,7 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
     const box = boxOf(parent.id)!;
     const focusAfter = box.querySelector<HTMLElement>(':scope > [data-mk-fb-actions] button');
     const gone = () => {
+      dropChoices(element);
       element.remove();
       link?.remove();
     };
@@ -292,6 +321,8 @@ export function createFilterBuilder(root: HTMLElement | null, options: FilterBui
     setCombinator(group, next);
     option.parentElement!.querySelector<HTMLElement>(`[data-combinator="${next}"]`)!.focus();
   });
+  // The selects' own events stay inside: listeners on the builder hear the builder's mk:change.
+  scope.on(tree, 'mk:change', (event) => event.stopPropagation());
   scope.on(tree, 'change', (event) => {
     const target = event.target as HTMLElement;
     const row = target.closest<HTMLElement>('[data-mk-fb-rule]');

package/src/components/filter-builder/filter-builder.css

@@ -88,7 +88,13 @@ mk-filter-builder {
   min-width: 0;
 }
 
-[data-mk-fb-rule] :is(select, input) {
+/* Choices are the kit's select (select.css draws the button); inputs share its look. */
+[data-mk-fb-rule] .mk-select {
+  min-width: 8rem;
+  max-width: 100%;
+}
+
+[data-mk-fb-rule] input {
   box-sizing: border-box;
   min-width: 0;
   height: 2.5rem;
@@ -103,22 +109,11 @@ mk-filter-builder {
   transition: box-shadow 0.2s ease;
 }
 
-[data-mk-fb-rule] select {
-  max-width: 100%;
-  padding-right: 1.9rem;
-  appearance: none;
-  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M6 9l6 6 6-6' fill='none' stroke='%23888' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
-  background-position: right 0.55rem center;
-  background-repeat: no-repeat;
-  background-size: 1rem;
-  cursor: pointer;
-}
-
 [data-mk-fb-rule] input {
   width: 9rem;
 }
 
-[data-mk-fb-rule] :is(select, input):focus-visible {
+[data-mk-fb-rule] input:focus-visible {
   box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
 }
 
@@ -217,7 +212,7 @@ mk-filter-builder {
 }
 
 @media (max-width: 480px) {
-  [data-mk-fb-rule] :is(select, input) {
+  [data-mk-fb-rule] :is(.mk-select, input) {
     flex: 1 1 8rem;
   }
 }
@@ -225,7 +220,7 @@ mk-filter-builder {
 @media (prefers-reduced-motion: reduce) {
   [data-mk-fb-combinator] [role='radio'],
   [data-mk-fb-actions] button,
-  [data-mk-fb-rule] :is(select, input) {
+  [data-mk-fb-rule] input {
     transition: none;
   }
 }

package/src/components/heatmap-chart/README.md

@@ -0,0 +1,48 @@
+# heatmap-chart
+
+Calendario de actividad tipo GitHub con intensidad por día, tooltips y desplazamiento horizontal.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { HeatmapChart } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add heatmap-chart --react --elements
+```
+
+## React
+
+```tsx
+<HeatmapChart end="2026-10-31" weeks={26} data={{ "2026-10-30": 4, "2026-10-31": 8 }} unit="sesiones" locale="es-MX" />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-heatmap-chart end="2026-10-31" weeks="26" data='{"2026-10-30":4,"2026-10-31":8}'></mk-heatmap-chart>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-heatmap-chart']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createHeatmapChart } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+data: {date, value}[] o mapa YYYY-MM-DD a valor. end: hoy. weeks: 53. firstDay: 1 (lunes). levels: 4. color: acento. locale, unit, legend. onSelect(date, value). Instancia: select(date | null), update(options), selected.
+
+Todos los gráficos aceptan `label`, `emptyLabel` y `formatValue`. Se actualizan con `update(options)` sin desmontarse; `select(index | null)` y `selected` controlan la selección (en heatmap se usa una fecha). `onSelect` también emite `mk:select`.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-heatmap-color, --mk-heatmap-empty; --mk-chart-surface.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/heatmap-chart/element.ts

@@ -0,0 +1,21 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createHeatmapChart, type HeatmapChartInstance, type HeatmapChartOptions } from './engine';
+
+/** <mk-heatmap-chart></mk-heatmap-chart> */
+export class MkHeatmapChartElement extends MkElement<HeatmapChartInstance> {
+  static options: Record<string, OptionType> = { data: 'json', end: 'string', weeks: 'number', firstDay: 'number', locale: 'string', levels: 'number', color: 'string', unit: 'string', label: 'string', legend: 'boolean', emptyLabel: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createHeatmapChart(this, options);
+  }
+
+  attributeChangedCallback(_name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    this.instance.update({ legend: undefined, color: undefined, ...this.options });
+  }
+
+  update(options: HeatmapChartOptions) { this.instance?.update(options); }
+  select(date: string | null) { this.instance?.select(date); }
+}
+
+export const defineHeatmapChart = () => defineElement('mk-heatmap-chart', MkHeatmapChartElement);

package/src/components/heatmap-chart/engine.ts

@@ -0,0 +1,281 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { addDays, capitalize, dayKey, safeFormat, startOfWeek, toDate, weekdayNames, type DateInput } from '../../core/dates';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { chartFrame, finite, formatNumber, onWidth, round, svg } from '../chart/parts';
+
+/*
+ * Heatmap chart: daily activity on a calendar, a column per week like
+ * GitHub's, in chart's family. Each day is a 3 px rounded cell whose colour
+ * deepens in steps (four by default) from the track to the accent. The cells
+ * pop in along the diagonal, oldest first (.35 s, 8 ms apart); new data
+ * crossfades their colours. Pointing at a day (or the arrows: up and down a
+ * day, left and right a week, PageUp/PageDown four) lifts it with a ring and
+ * the tooltip says its value and date; the "less … more" scale lights the
+ * days of a step. Narrow screens scroll the weeks, ending on the latest.
+ */
+
+export interface HeatmapDatum {
+  date: DateInput;
+  value: number;
+}
+
+export interface HeatmapChartOptions {
+  /** Values by day: a list or a { 'YYYY-MM-DD': value } map. */
+  data?: HeatmapDatum[] | Record<string, number>;
+  /** The last day shown (default: today). */
+  end?: DateInput;
+  /** Weeks shown (default 53). */
+  weeks?: number;
+  /** First day of the week, 0 Sunday … 6 Saturday (default 1, Monday). */
+  firstDay?: number;
+  locale?: string;
+  /** Coloured steps above zero (default 4). */
+  levels?: number;
+  /** The deepest step's colour (default the accent). */
+  color?: string;
+  /** What a value counts, for the tooltip (default 'actividades'). */
+  unit?: string;
+  label?: string;
+  /** The "less … more" scale (default true). */
+  legend?: boolean;
+  formatValue?: (value: number) => string;
+  emptyLabel?: string;
+  onSelect?: (date: string | null, value: number | null) => void;
+}
+
+export interface HeatmapChartInstance extends Instance {
+  update(options: HeatmapChartOptions): void;
+  /** Choose a day ('YYYY-MM-DD') or none. */
+  select(date: string | null): void;
+  readonly selected: string | null;
+}
+
+const LEFT = 28;
+const TOP = 18;
+
+export function createHeatmapChart(root: HTMLElement | null, initial: HeatmapChartOptions = {}): HeatmapChartInstance {
+  if (!root) return inert({ update() {}, select() {}, selected: null });
+  registerMotion();
+  const scope = createScope();
+  const frame = chartFrame(root, scope, 'heatmap');
+  const { plot, canvas, keep } = frame;
+  let options: HeatmapChartOptions = { ...initial };
+  let selected: number | null = null;
+
+  // The weeks scroll inside the plot; the tooltip stays over it, unclipped.
+  const scroller = document.createElement('div');
+  scroller.dataset.mkHeatmapScroll = '';
+  plot.prepend(scroller);
+  scroller.append(canvas);
+  scope.add(() => scroller.remove());
+
+  const scale = document.createElement('div');
+  scale.dataset.mkHeatmapScale = '';
+  scale.setAttribute('aria-hidden', 'true');
+  root.insertBefore(scale, frame.legend);
+  scope.add(() => scale.remove());
+
+  const locale = () => options.locale ?? (document.documentElement.lang || 'es');
+  const format = (value: number) => (options.formatValue ? options.formatValue(value) : formatNumber(value));
+  const levels = () => Math.max(1, Math.min(8, Math.round(options.levels ?? 4)));
+
+  const modelOf = () => {
+    const values = new Map<string, number>();
+    const add = (key: string, value: number) => finite(value) && values.set(key, (values.get(key) ?? 0) + value);
+    if (Array.isArray(options.data)) for (const datum of options.data) add(dayKey(toDate(datum.date)), datum.value);
+    else if (options.data) for (const [key, value] of Object.entries(options.data)) add(dayKey(toDate(key)), value);
+    const weeks = Math.max(1, Math.min(106, Math.round(options.weeks ?? 53)));
+    const firstDay = Number.isInteger(options.firstDay) && options.firstDay! >= 0 && options.firstDay! <= 6 ? options.firstDay! : 1;
+    const end = toDate(options.end ?? new Date());
+    const start = startOfWeek(addDays(end, -(weeks - 1) * 7), firstDay);
+    const days: Array<{ key: string; date: Date; value: number; week: number; day: number }> = [];
+    for (let date = start, i = 0; date <= end; date = addDays(date, 1), i++) {
+      const key = dayKey(date);
+      days.push({ key, date, value: values.get(key) ?? 0, week: Math.floor(i / 7), day: i % 7 });
+    }
+    const max = Math.max(0, ...days.map((each) => each.value));
+    return { days, weeks: (days[days.length - 1]?.week ?? 0) + 1, firstDay, max, total: days.reduce((sum, each) => sum + each.value, 0) };
+  };
+  let model = modelOf();
+  const levelOf = (value: number) => (value <= 0 || !model.max ? 0 : Math.max(1, Math.ceil((value / model.max) * levels())));
+  const fillOf = (level: number) => (level === 0 ? 'var(--mk-heatmap-empty)' : `color-mix(in srgb, ${options.color ?? 'var(--mk-heatmap-color)'} ${Math.round(22 + (78 * level) / levels())}%, var(--mk-heatmap-empty))`);
+
+  let cells: SVGRectElement[] = [];
+  /** The first day drawn: the same days keep their cells. */
+  let builtFrom = '';
+  let geometry = { cell: 12, gap: 3, width: 0, height: 0 };
+  const longDate = () => safeFormat(locale(), { weekday: 'short', day: 'numeric', month: 'long', year: 'numeric' });
+
+  const build = (animate: boolean) => {
+    canvas.replaceChildren();
+    const available = Math.max(0, (plot.clientWidth || root.clientWidth || 0) - LEFT);
+    const gap = 3;
+    // Cells fill the width between 10 and 14 px; past that the weeks scroll.
+    const fit = available ? Math.floor(available / model.weeks - gap) : 12;
+    const cell = Math.max(10, Math.min(14, fit));
+    const width = LEFT + model.weeks * (cell + gap);
+    const height = TOP + 7 * (cell + gap);
+    geometry = { cell, gap, width, height };
+    canvas.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    canvas.setAttribute('width', String(width));
+    canvas.setAttribute('height', String(height));
+    plot.style.setProperty('--mk-heatmap-width', `${width}px`);
+
+    // Month names over the week where each month starts; weekday names on every other row.
+    const months = svg('g', { 'data-mk-part': 'months' });
+    const monthName = safeFormat(locale(), { month: 'short' });
+    let last = -1;
+    for (const each of model.days) {
+      if (each.day !== 0) continue;
+      const month = addDays(each.date, 6).getMonth();
+      if (month === last) continue;
+      last = month;
+      if (each.week > model.weeks - 2 && model.weeks > 4) continue;
+      const text = svg('text', { x: LEFT + each.week * (cell + gap), y: 10 });
+      text.textContent = capitalize(monthName.format(addDays(each.date, 6)).replace('.', ''));
+      months.append(text);
+    }
+    const names = weekdayNames(locale(), model.firstDay, 'short');
+    const weekdays = svg('g', { 'data-mk-part': 'weekdays' });
+    [1, 3, 5].forEach((row) => {
+      const text = svg('text', { x: 0, y: round(TOP + row * (cell + gap) + cell / 2), 'dominant-baseline': 'middle' });
+      text.textContent = capitalize(names[row]!.replace('.', '')).slice(0, 3);
+      weekdays.append(text);
+    });
+    const grid = svg('g', { 'data-mk-part': 'cells' });
+    cells = model.days.map((each, i) => {
+      const rect = svg('rect', { x: LEFT + each.week * (cell + gap), y: TOP + each.day * (cell + gap), width: cell, height: cell, rx: 3, 'data-mk-index': i, 'data-mk-level': levelOf(each.value) });
+      rect.style.fill = fillOf(levelOf(each.value));
+      grid.append(rect);
+      return rect;
+    });
+    canvas.append(months, weekdays, grid);
+    builtFrom = model.days[0]?.key ?? '';
+    // The latest weeks in view when they scroll.
+    scroller.scrollLeft = scroller.scrollWidth;
+    if (animate && !reduced()) keep(gsap.fromTo(cells, { opacity: 0, scale: 0.3 }, { opacity: 1, scale: 1, duration: 0.35, ease: EASE.pop, clearProps: 'opacity,transform', stagger: (i: number) => Math.min(0.7, (model.days[i]!.week + model.days[i]!.day) * 0.008) }));
+  };
+  scope.add(() => plot.style.removeProperty('--mk-heatmap-width'));
+
+  const paintScale = () => {
+    scale.replaceChildren();
+    scale.hidden = options.legend === false || !model.days.length;
+    if (scale.hidden) return;
+    const less = document.createElement('span');
+    less.textContent = 'Menos';
+    scale.append(less);
+    for (let level = 0; level <= levels(); level++) {
+      const swatch = document.createElement('i');
+      swatch.style.background = fillOf(level);
+      swatch.addEventListener('pointerenter', () => {
+        for (const cell of cells) cell.toggleAttribute('data-mk-dim', cell.getAttribute('data-mk-level') !== String(level));
+      });
+      swatch.addEventListener('pointerleave', () => {
+        for (const cell of cells) cell.removeAttribute('data-mk-dim');
+      });
+      scale.append(swatch);
+    }
+    const more = document.createElement('span');
+    more.textContent = 'Más';
+    scale.append(more);
+  };
+
+  const unit = () => options.unit ?? 'actividades';
+  const paintSelection = (announce: boolean) => {
+    cells.forEach((cell, i) => cell.toggleAttribute('data-mk-on', i === selected));
+    const each = selected === null ? null : model.days[selected];
+    if (!each) {
+      frame.tip(null);
+      return;
+    }
+    const { cell, gap } = geometry;
+    const x = LEFT + each.week * (cell + gap) + cell / 2 - scroller.scrollLeft;
+    const y = TOP + each.day * (cell + gap);
+    const title = capitalize(longDate().format(each.date));
+    frame.tip({ x, y, title, rows: [{ name: unit(), color: fillOf(Math.max(1, levelOf(each.value))), value: format(each.value) }] });
+    if (announce) frame.live.textContent = `${title}: ${format(each.value)} ${unit()}`;
+  };
+
+  const draw = (animate: boolean) => {
+    const name = options.label ?? 'Actividad diaria';
+    canvas.setAttribute('aria-label', model.days.length ? `${name}. ${model.weeks} semanas, ${format(model.total)} ${unit()} en total. Usa las flechas para recorrer los días.` : `${name}: ${options.emptyLabel ?? 'sin datos'}`);
+    // The days with something, for screen readers (a year of empty rows says nothing).
+    const active = model.days.filter((each) => each.value > 0);
+    frame.fillTable(`${name}: ${format(model.total)} ${unit()}`, ['Día', capitalize(unit())], active.map((each) => [capitalize(longDate().format(each.date)), format(each.value)]));
+    frame.fillLegend([], false);
+    paintScale();
+    if (selected !== null && selected >= model.days.length) selected = null;
+    const same = cells.length === model.days.length && cells.length > 0 && builtFrom === model.days[0]!.key;
+    if (same && animate) {
+      // New values over the same days: the colours crossfade (CSS).
+      cells.forEach((cell, i) => {
+        const level = levelOf(model.days[i]!.value);
+        cell.setAttribute('data-mk-level', String(level));
+        cell.style.fill = fillOf(level);
+      });
+    } else build(animate);
+    paintSelection(false);
+  };
+
+  const select = (index: number | null, announce = false) => {
+    if (scope.disposed) return;
+    const next = index === null || !model.days.length ? null : Math.max(0, Math.min(model.days.length - 1, Math.round(index)));
+    if (next === selected) return;
+    selected = next;
+    paintSelection(announce);
+    const each = selected === null ? null : model.days[selected]!;
+    options.onSelect?.(each?.key ?? null, each?.value ?? null);
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { date: each?.key ?? null, value: each?.value ?? null } }));
+  };
+
+  scope.on(canvas, 'pointermove', (event) => {
+    const cell = (event.target as Element).closest('[data-mk-index]');
+    select(cell ? Number(cell.getAttribute('data-mk-index')) : null);
+  });
+  scope.on(canvas, 'pointerleave', (event) => {
+    if ((event as PointerEvent).pointerType === 'mouse') select(null);
+  });
+  scope.on(canvas, 'focus', () => {
+    if (selected === null && model.days.length) select(model.days.length - 1, true);
+  });
+  scope.on(canvas, 'blur', () => select(null));
+  scope.on(canvas, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const at = selected ?? model.days.length - 1;
+    const moves: Record<string, number | null> = { ArrowUp: at - 1, ArrowDown: at + 1, ArrowLeft: at - 7, ArrowRight: at + 7, PageUp: at - 28, PageDown: at + 28, Home: 0, End: model.days.length - 1, Escape: null };
+    if (!(key in moves) || !model.days.length) return;
+    event.preventDefault();
+    select(moves[key]!, true);
+    // Keep the chosen day in view when the weeks scroll.
+    const cell = selected === null ? null : cells[selected];
+    if (cell) {
+      const x = Number(cell.getAttribute('x'));
+      if (x - scroller.scrollLeft < LEFT || x - scroller.scrollLeft > scroller.clientWidth - geometry.cell * 2) scroller.scrollLeft = x - scroller.clientWidth / 2;
+    }
+  });
+  onWidth(root, scope, () => {
+    build(false);
+    paintSelection(false);
+  });
+
+  draw(true);
+
+  return {
+    update(next) {
+      if (scope.disposed) return;
+      options = { ...options, ...next };
+      model = modelOf();
+      draw(true);
+    },
+    select(date) {
+      const index = date === null ? -1 : model.days.findIndex((each) => each.key === date);
+      select(index < 0 ? null : index);
+    },
+    get selected() {
+      return selected === null ? null : (model.days[selected]?.key ?? null);
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/heatmap-chart/heatmap-chart.css

@@ -0,0 +1,93 @@
+/* heatmap-chart — a week per column of 3 px rounded days, deepening from the track to the accent; needs chart.css.
+   The day under the pointer lifts with a ring; the "less … more" scale sits under it, to the right. */
+.mk-heatmap-chart,
+mk-heatmap-chart {
+  --mk-heatmap-color: var(--mk-accent);
+  --mk-heatmap-empty: var(--mk-surface-2);
+  display: grid;
+  gap: 0.6rem;
+  min-width: 0;
+}
+
+[data-mk-heatmap-scroll] {
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding-block: 4px;
+  scrollbar-width: thin;
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-chart-svg] {
+  width: var(--mk-heatmap-width, auto);
+  max-width: none;
+  overflow: visible;
+  cursor: pointer;
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect {
+  transform-box: fill-box;
+  transform-origin: center;
+  transition:
+    fill 0.35s ease,
+    opacity 0.2s ease,
+    transform 0.3s var(--mk-ease-swatch);
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect[data-mk-on] {
+  stroke: var(--mk-text);
+  stroke-width: 1.5;
+  transform: scale(1.3);
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect[data-mk-dim] {
+  opacity: 0.25;
+}
+
+[data-mk-chart-type='heatmap'] [data-mk-part='months'] text,
+[data-mk-chart-type='heatmap'] [data-mk-part='weekdays'] text {
+  font-size: 10px;
+}
+
+[data-mk-heatmap-scale] {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 3px;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+}
+
+[data-mk-heatmap-scale][hidden] {
+  display: none;
+}
+
+[data-mk-heatmap-scale] span {
+  margin-inline: 0.35rem;
+}
+
+[data-mk-heatmap-scale] i {
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  cursor: pointer;
+  transition: transform 0.25s var(--mk-ease-swatch);
+}
+
+@media (hover: hover) {
+  [data-mk-heatmap-scale] i:hover {
+    transform: scale(1.25);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect,
+  [data-mk-heatmap-scale] i {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-mk-chart-type='heatmap'] [data-mk-part='cells'] rect {
+    stroke: CanvasText;
+    stroke-width: 0.5;
+  }
+}

package/src/components/heatmap-chart/react.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import type { HTMLAttributes } from 'react';
+import { useChart } from '../chart/use-chart';
+import { createHeatmapChart, type HeatmapChartInstance, type HeatmapChartOptions } from './engine';
+
+export interface HeatmapChartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'>, HeatmapChartOptions {
+  instanceRef?: { current: HeatmapChartInstance | null };
+}
+
+export function HeatmapChart({ data, end, weeks, firstDay, locale, levels, color, unit, label, legend, formatValue, emptyLabel, onSelect, instanceRef, className, ...props }: HeatmapChartProps) {
+  const ref = useChart(createHeatmapChart, { data, end, weeks, firstDay, locale, levels, color, unit, label, legend, emptyLabel }, { formatValue, onSelect }, instanceRef);
+  return <div {...props} ref={ref} className={['mk-heatmap-chart', className].filter(Boolean).join(' ')} />;
+}