@aceshooting/lyra-ui 1.0.1 → 1.2.0

package/dist/components/heatmap/heatmap.js

@@ -5,22 +5,32 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { html } from 'lit';
-import { property, query } from 'lit/decorators.js';
+import { property, query, state } from 'lit/decorators.js';
+import { styleMap } from 'lit/directives/style-map.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
+import { srOnly } from '../../internal/a11y.js';
 import { linearAlpha, minMax, sqrtStep } from './heatmap-scale.js';
 import { styles } from './heatmap.styles.js';
-import { buildCalendarGrid, quartileBucket } from './calendar-grid.js';
+import { buildCalendarGrid, parseIsoDate, quartileBucket } from './calendar-grid.js';
 const PAD_LEFT = 60;
 const PAD_TOP = 20;
 const FALLBACK_NO_DATA_FILL = 'rgba(128,128,128,0.25)';
 const RAMP_STEPS = 7;
 const FALLBACK_SCALE_LO = '#cde2fb';
 const FALLBACK_SCALE_HI = '#0969da';
+const FALLBACK_LABEL_FONT = '10px sans-serif';
 const CAL_PAD_LEFT = 28;
 const CAL_LABEL_H = 16;
 const CAL_CELL = 11;
 const CAL_GAP = 2;
+const DEFAULT_BUCKET_COUNT = 5;
+/** Ring stroke width for both the annotation overlay and the keyboard focus ring. */
+const RING_LINE_WIDTH = 2;
+const FALLBACK_FOCUS_RING_COLOR = '#0969da';
+const FALLBACK_ANNOTATION_COLOR = '#cf222e';
+const ARROW_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']);
+const MS_PER_DAY = 86_400_000;
 const HEX_RE = /^([0-9a-f]{3}|[0-9a-f]{6})$/i;
 const RGB_RE = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i;
 /**
@@ -56,6 +66,30 @@ function warnInvalidColor(color) {
     console.warn(`<lyra-heatmap> could not parse "${color}" (set via --lyra-heatmap-scale-lo/-hi) as a CSS ` +
         'color; falling back to the default ramp endpoint.');
 }
+const warnedInvalidBucketCounts = new Set();
+function warnInvalidBucketCount(value) {
+    if (warnedInvalidBucketCounts.has(value))
+        return;
+    warnedInvalidBucketCounts.add(value);
+    console.warn(`<lyra-heatmap> received a non-finite bucket-count (${value}); falling back to ${DEFAULT_BUCKET_COUNT}.`);
+}
+/**
+ * Normalizes `bucketCount` to a finite integer >= 2. `Math.max(2, bucketCount)`
+ * alone stays `NaN` for a non-numeric `bucket-count` attribute (`Math.max`
+ * propagates `NaN`), which silently zeroes out the ramp array and makes every
+ * cell keep whatever `fillStyle` the previous draw left. A fractional count
+ * is floored rather than passed through as-is, so the ramp array's length
+ * (built via `Array.from({ length: buckets }, ...)`, which truncates a
+ * fractional `length`) always agrees with the index `quartileBucket` computes
+ * from the same `buckets` value.
+ */
+function resolveBucketCount(bucketCount) {
+    if (!Number.isFinite(bucketCount)) {
+        warnInvalidBucketCount(bucketCount);
+        return DEFAULT_BUCKET_COUNT;
+    }
+    return Math.max(2, Math.floor(bucketCount));
+}
 /**
  * Resolves any syntactically valid CSS `<color>` — hex, `rgb()`, `hsl()`,
  * `oklch()`, a named color, etc. — to an `[r, g, b]` triple.
@@ -102,16 +136,44 @@ export function mixColor(fromColor, toColor, t) {
     return mixRgb(resolveRgb(fromColor, FALLBACK_SCALE_LO), resolveRgb(toColor, FALLBACK_SCALE_HI), t);
 }
 /**
- * `<lyra-heatmap>` — a Canvas matrix heatmap with a DPR-aware, resize-aware
- * redraw loop. `-1` cells are treated as "no data". The sequential color
- * ramp's endpoints are read from the `--lyra-heatmap-scale-lo`/`-hi` custom
- * properties (declared in `heatmap.styles.ts`) so hosts can retheme it —
- * canvas can't consume `var()` directly, so they're resolved once per draw
- * via `getComputedStyle`, then normalized to RGB by `resolveRgb()` (any
- * valid CSS color syntax, not just hex — see its doc comment).
+ * `<lyra-heatmap>` — a Canvas heatmap with a DPR-aware, resize-aware redraw
+ * loop, in one of two `mode`s:
+ *
+ * - `"matrix"` (default): a `rowLabels` x `colLabels` grid of `values`. `-1`
+ *   (or any non-finite value) is treated as "no data". `scale="sqrt"`
+ *   compresses the ramp via `sqrtStep()` so one heavy cell doesn't wash out
+ *   the rest; the default `"linear"` scale maps linearly instead. `scale`
+ *   only affects matrix mode — calendar mode always buckets by quartile.
+ * - `"calendar"`: a GitHub-style Sunday-Saturday x week grid built from
+ *   `days`, colored by `quartileBucket()` into `bucketCount` buckets. As in
+ *   matrix mode, a cell whose `value` is negative or non-finite is treated
+ *   as "no data" rather than being bucketed.
+ *
+ * The sequential color ramp's endpoints are read from the
+ * `--lyra-heatmap-scale-lo`/`-hi` custom properties (declared in
+ * `heatmap.styles.ts`) so hosts can retheme it — canvas can't consume
+ * `var()` directly, so they're resolved once per draw via
+ * `getComputedStyle`, then normalized to RGB by `resolveRgb()` (any valid
+ * CSS color syntax, not just hex — see its doc comment).
+ *
+ * Every cell is independently addressable: a `pointermove` hit test over the
+ * canvas shows `[part="tooltip"]` with that cell's label + value (hidden on
+ * `pointerleave`); the canvas is `tabindex="0"` with arrow-key roving focus
+ * (a stroked ring redrawn over the focused cell on every draw, plus a
+ * visually-hidden `aria-live="polite"` status announcement — avoids a
+ * DOM-node-per-cell overlay, which would be hundreds of nodes for a year
+ * calendar); and a click, or Enter/Space on the focused cell, fires
+ * `lyra-cell-click`. `annotations` additionally strokes a ring around
+ * specific cells (e.g. to call out an anomaly), each one optionally
+ * surfaced in the legend too via `[part="legend-annotation"]`.
  *
  * @customElement lyra-heatmap
- * @csspart base, canvas, legend
+ * @event lyra-cell-click - Fired on click, or Enter/Space on the
+ * focused/hovered cell. `detail: { row, col, value }` in matrix mode,
+ * `detail: { date, value }` in calendar mode. `cellText` overrides the
+ * built-in English "Row X, Col Y: value" / "Mon DD: value" template used for
+ * both the hover tooltip and the keyboard live-region announcement.
+ * @csspart base, canvas, tooltip, live-region, legend, legend-lo, legend-hi, legend-annotation
  */
 export class LyraHeatmap extends LyraElement {
     constructor() {
@@ -133,13 +195,47 @@ export class LyraHeatmap extends LyraElement {
         this.fitToWidth = false;
         this.mode = 'matrix';
         this.days = [];
-        this.bucketCount = 5;
+        this.bucketCount = DEFAULT_BUCKET_COUNT;
+        /** Cells to ring-highlight — `row`/`col` in matrix mode, `date` in calendar mode. See `HeatmapAnnotation`. */
+        this.annotations = [];
+        /** The current value range, refreshed once per update cycle by `willUpdate()`. See `computeValueRange()`. */
+        this.cachedValueRange = null;
+        /** The cell currently under the pointer (`null` when not hovering one) — drives `[part="tooltip"]`. */
+        this.hoverCell = null;
+        /** The roving keyboard-focus cell cursor, moved by arrow keys — drives the
+         *  canvas-drawn focus ring and the `[part="live-region"]` announcement. */
+        this.focusedCell = null;
+        /** Text of the visually-hidden `aria-live="polite"` status announcement, refreshed on every focus move. */
+        this.liveText = '';
         this.onDprChange = () => {
             this.watchDpr();
             this.draw();
         };
+        this.onPointerMove = (e) => {
+            this.hoverCell = this.hitTest(e.offsetX, e.offsetY);
+        };
+        this.onPointerLeave = () => {
+            this.hoverCell = null;
+        };
+        this.onCanvasClick = (e) => {
+            // Prefer the click's own position; fall back to whatever's already
+            // keyboard-focused (e.g. a synthetic click dispatched via
+            // HTMLElement.click(), which carries no real coordinates).
+            const pos = this.hitTest(e.offsetX, e.offsetY) ?? this.focusedCell;
+            if (!pos)
+                return;
+            this.focusedCell = pos;
+            this.announce(pos);
+            this.emitCellClick(pos);
+        };
+        this.onKeyDown = (e) => {
+            if (this.mode === 'calendar')
+                this.onCalendarKeyDown(e);
+            else
+                this.onMatrixKeyDown(e);
+        };
     }
-    static { this.styles = [LyraElement.styles, styles]; }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
     connectedCallback() {
         super.connectedCallback();
         this.resizeObserver = new ResizeObserver(() => this.draw());
@@ -160,10 +256,23 @@ export class LyraHeatmap extends LyraElement {
         this.dprQuery = matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
         this.dprQuery.addEventListener('change', this.onDprChange);
     }
-    willUpdate() {
-        const bounds = this.valueRange();
+    willUpdate(changed) {
+        if (changed.has('mode') || changed.has('rowLabels') || changed.has('colLabels') || changed.has('days')) {
+            // The previous focus/hover cursor may no longer address a real cell
+            // once the grid's shape (or mode) changes out from under it —
+            // stroking a focus ring at a stale (row, col)/(week, weekday), or
+            // leaving the live region announcing a stale value, would be actively
+            // misleading, so drop both instead. Reactive-property writes belong in
+            // willUpdate() (not updated()), which folds them into this same
+            // render rather than scheduling a whole extra update pass.
+            this.focusedCell = null;
+            this.hoverCell = null;
+            this.liveText = '';
+        }
+        this.cachedValueRange = this.computeValueRange();
+        const bounds = this.cachedValueRange;
         const range = bounds ? `${bounds[0]}–${bounds[1]}` : 'no data';
-        this.setAttribute('role', 'img');
+        this.setAttribute('role', 'group');
         if (this.mode === 'calendar') {
             this.setAttribute('aria-label', `Calendar heatmap of ${this.days.length} days, ${this.valueLabel} range ${range}`);
         }
@@ -173,8 +282,16 @@ export class LyraHeatmap extends LyraElement {
             this.setAttribute('aria-label', `Heatmap of ${rows} × ${cols} cells, ${this.valueLabel} range ${range}`);
         }
     }
-    /** The real (non-no-data) value range across `values` (or `days` in calendar mode), or `null` if there is none. Shared by `willUpdate()`, `draw()`, and the legend. */
-    valueRange() {
+    /**
+     * The real (non-no-data) value range across `values` (or `days` in
+     * calendar mode), or `null` if there is none. Only called from
+     * `willUpdate()`, which caches the result in `cachedValueRange` for
+     * `render()` and `drawMatrix()` to reuse — `willUpdate()`, `render()`, and
+     * `updated()` (which triggers `draw()`) all run within the same Lit update
+     * cycle against the same `values`/`days`, so a single scan per cycle
+     * suffices instead of one per consumer.
+     */
+    computeValueRange() {
         const source = this.mode === 'calendar' ? this.days.map((d) => d.value) : this.values.flat();
         return minMax(source.filter((v) => Number.isFinite(v) && v >= 0));
     }
@@ -192,10 +309,22 @@ export class LyraHeatmap extends LyraElement {
     labelColor() {
         return getComputedStyle(this).getPropertyValue('--lyra-color-text-quiet').trim() || '#6b7280';
     }
+    /** Reads the customizable canvas axis/label font off the host's computed style. */
+    labelFont() {
+        return getComputedStyle(this).getPropertyValue('--lyra-heatmap-label-font').trim() || FALLBACK_LABEL_FONT;
+    }
     /** Reads the customizable no-data cell fill off the host's computed style. */
     noDataFill() {
         return getComputedStyle(this).getPropertyValue('--lyra-heatmap-no-data-fill').trim() || FALLBACK_NO_DATA_FILL;
     }
+    /** Reads the customizable canvas-drawn keyboard-focus-ring stroke color off the host's computed style. */
+    focusRingColor() {
+        return (getComputedStyle(this).getPropertyValue('--lyra-heatmap-focus-ring-color').trim() || FALLBACK_FOCUS_RING_COLOR);
+    }
+    /** Reads the customizable canvas-drawn annotation-ring stroke color off the host's computed style. */
+    annotationColor() {
+        return (getComputedStyle(this).getPropertyValue('--lyra-heatmap-annotation-color').trim() || FALLBACK_ANNOTATION_COLOR);
+    }
     draw() {
         if (this.mode === 'calendar')
             this.drawCalendar();
@@ -225,7 +354,7 @@ export class LyraHeatmap extends LyraElement {
         const [scaleLo, scaleHi] = this.scaleEndpoints();
         const loRgb = resolveRgb(scaleLo, FALLBACK_SCALE_LO);
         const hiRgb = resolveRgb(scaleHi, FALLBACK_SCALE_HI);
-        const buckets = Math.max(2, this.bucketCount);
+        const buckets = resolveBucketCount(this.bucketCount);
         const ramp = Array.from({ length: buckets }, (_, i) => mixRgb(loRgb, hiRgb, i / (buckets - 1)));
         const noDataFill = this.noDataFill();
         for (const cell of cells) {
@@ -237,8 +366,37 @@ export class LyraHeatmap extends LyraElement {
                     : ramp[quartileBucket(cell.value, sortedValues, buckets)];
             ctx.fillRect(x, y, CAL_CELL, CAL_CELL);
         }
+        // Annotation ring overlay, stroked after the fill pass so it reads
+        // clearly over the data-driven cell color — see drawMatrix()'s twin of
+        // this block for the matrix-mode equivalent.
+        if (this.annotations.length) {
+            ctx.lineWidth = RING_LINE_WIDTH;
+            ctx.strokeStyle = this.annotationColor();
+            for (const ann of this.annotations) {
+                if (ann.date == null)
+                    continue;
+                const match = cells.find((c) => c.date === ann.date);
+                if (!match)
+                    continue;
+                const x = CAL_PAD_LEFT + match.week * (CAL_CELL + CAL_GAP);
+                const y = CAL_LABEL_H + match.weekday * (CAL_CELL + CAL_GAP);
+                ctx.strokeRect(x + 0.5, y + 0.5, CAL_CELL - 1, CAL_CELL - 1);
+            }
+        }
+        // Keyboard focus ring, redrawn on top of the fill pass (and any
+        // annotation rings) on every draw.
+        if (this.focusedCell && 'week' in this.focusedCell) {
+            const { week, weekday } = this.focusedCell;
+            if (week < weekCount && weekday < 7) {
+                ctx.lineWidth = RING_LINE_WIDTH;
+                ctx.strokeStyle = this.focusRingColor();
+                const x = CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP);
+                const y = CAL_LABEL_H + weekday * (CAL_CELL + CAL_GAP);
+                ctx.strokeRect(x + 0.5, y + 0.5, CAL_CELL - 1, CAL_CELL - 1);
+            }
+        }
         ctx.fillStyle = this.labelColor();
-        ctx.font = '10px sans-serif';
+        ctx.font = this.labelFont();
         for (const m of monthLabels) {
             ctx.fillText(m.label, CAL_PAD_LEFT + m.week * (CAL_CELL + CAL_GAP), CAL_LABEL_H - 4);
         }
@@ -248,16 +406,26 @@ export class LyraHeatmap extends LyraElement {
                 ctx.fillText(label, 2, CAL_LABEL_H + weekday * (CAL_CELL + CAL_GAP) + CAL_CELL - 1);
         });
     }
+    /**
+     * Effective per-cell size in matrix mode — `fitToWidth` derives it from
+     * the host's measured width, otherwise it's the fixed `cellSize`
+     * property. Shared by `drawMatrix()` and the pointer/keyboard hit-testing
+     * below (`hitTestMatrix()`, `cellRect()`) so they always agree on exactly
+     * the same geometry as what's actually painted.
+     */
+    matrixCellSize(cols) {
+        if (this.fitToWidth && cols > 0) {
+            const hostWidth = this.clientWidth || PAD_LEFT + cols * this.cellSize;
+            return Math.max(4, (hostWidth - PAD_LEFT) / cols);
+        }
+        return this.cellSize;
+    }
     drawMatrix() {
         if (!this.canvas)
             return;
         const rows = this.rowLabels.length;
         const cols = this.colLabels.length;
-        let cellSize = this.cellSize;
-        if (this.fitToWidth && cols > 0) {
-            const hostWidth = this.clientWidth || PAD_LEFT + cols * this.cellSize;
-            cellSize = Math.max(4, (hostWidth - PAD_LEFT) / cols);
-        }
+        const cellSize = this.matrixCellSize(cols);
         const w = PAD_LEFT + cols * cellSize;
         const h = PAD_TOP + rows * cellSize;
         const dpr = window.devicePixelRatio || 1;
@@ -270,7 +438,7 @@ export class LyraHeatmap extends LyraElement {
             return;
         ctx.scale(dpr, dpr);
         ctx.clearRect(0, 0, w, h);
-        const bounds = this.valueRange();
+        const bounds = this.cachedValueRange;
         const lo = bounds ? bounds[0] : 0;
         const hi = bounds ? bounds[1] : 1;
         const [scaleLo, scaleHi] = this.scaleEndpoints();
@@ -305,8 +473,40 @@ export class LyraHeatmap extends LyraElement {
                 ctx.fillRect(x, y, cellSize - 1, cellSize - 1);
             }
         }
+        // Annotation ring overlay, stroked after the fill pass so it reads
+        // clearly over the data-driven cell color. Uses a dedicated
+        // --lyra-heatmap-annotation-color token (defaults to --lyra-color-danger)
+        // rather than any of the sequential ramp colors, since it needs to stay
+        // visible regardless of which point on that ramp it's drawn over.
+        if (this.annotations.length) {
+            ctx.lineWidth = RING_LINE_WIDTH;
+            ctx.strokeStyle = this.annotationColor();
+            for (const ann of this.annotations) {
+                if (ann.row == null || ann.col == null)
+                    continue;
+                if (ann.row < 0 || ann.row >= rows || ann.col < 0 || ann.col >= cols)
+                    continue;
+                const x = PAD_LEFT + ann.col * cellSize;
+                const y = PAD_TOP + ann.row * cellSize;
+                ctx.strokeRect(x + 1, y + 1, cellSize - 3, cellSize - 3);
+            }
+        }
+        // Keyboard focus ring, redrawn on top of the fill pass (and any
+        // annotation rings) on every draw — canvas has no persistent DOM focus
+        // affordance of its own for an individual cell, only a `:focus-visible`
+        // outline around the whole element (see heatmap.styles.ts).
+        if (this.focusedCell && 'row' in this.focusedCell) {
+            const { row, col } = this.focusedCell;
+            if (row < rows && col < cols) {
+                ctx.lineWidth = RING_LINE_WIDTH;
+                ctx.strokeStyle = this.focusRingColor();
+                const x = PAD_LEFT + col * cellSize;
+                const y = PAD_TOP + row * cellSize;
+                ctx.strokeRect(x + 1, y + 1, cellSize - 3, cellSize - 3);
+            }
+        }
         ctx.fillStyle = this.labelColor();
-        ctx.font = '10px sans-serif';
+        ctx.font = this.labelFont();
         this.rowLabels.forEach((label, r) => {
             ctx.fillText(label, 4, PAD_TOP + r * cellSize + cellSize / 2 + 3);
         });
@@ -314,16 +514,218 @@ export class LyraHeatmap extends LyraElement {
             ctx.fillText(label, PAD_LEFT + c * cellSize + 2, PAD_TOP - 6);
         });
     }
+    /**
+     * Maps a pointer position, in canvas-local CSS px (e.g.
+     * `PointerEvent.offsetX/offsetY`), to the cell underneath it — or `null`
+     * if the pointer is outside the grid. Dispatches on `mode` so callers
+     * don't have to.
+     */
+    hitTest(x, y) {
+        return this.mode === 'calendar' ? this.hitTestCalendar(x, y) : this.hitTestMatrix(x, y);
+    }
+    hitTestMatrix(x, y) {
+        const rows = this.rowLabels.length;
+        const cols = this.colLabels.length;
+        if (rows === 0 || cols === 0)
+            return null;
+        const cellSize = this.matrixCellSize(cols);
+        const col = Math.floor((x - PAD_LEFT) / cellSize);
+        const row = Math.floor((y - PAD_TOP) / cellSize);
+        if (row < 0 || row >= rows || col < 0 || col >= cols)
+            return null;
+        return { row, col };
+    }
+    hitTestCalendar(x, y) {
+        const { weekCount } = buildCalendarGrid(this.days);
+        if (weekCount === 0)
+            return null;
+        const week = Math.floor((x - CAL_PAD_LEFT) / (CAL_CELL + CAL_GAP));
+        const weekday = Math.floor((y - CAL_LABEL_H) / (CAL_CELL + CAL_GAP));
+        if (week < 0 || week >= weekCount || weekday < 0 || weekday > 6)
+            return null;
+        return { week, weekday };
+    }
+    /**
+     * Resolves a (week, weekday) grid position to its real calendar date and
+     * value. Computed from grid geometry (`firstWeekStart` + offset), not
+     * just looked up in `cells` — so a position with no matching entry in
+     * `days` (a gap in a sparse calendar) still resolves to a real ISO date,
+     * with a `-1` "no data" sentinel value (the same convention `values`' `-1`
+     * sentinel uses in matrix mode), instead of being unresolvable.
+     */
+    calendarCellAt(pos) {
+        const { cells, firstWeekStart } = buildCalendarGrid(this.days);
+        const match = cells.find((c) => c.week === pos.week && c.weekday === pos.weekday);
+        if (match)
+            return { date: match.date, value: match.value };
+        const date = new Date(firstWeekStart.getTime() + (pos.week * 7 + pos.weekday) * MS_PER_DAY);
+        return { date: date.toISOString().slice(0, 10), value: -1 };
+    }
+    /**
+     * Pixel rect (canvas-local CSS px) of a cell — shared by `tooltipStyle()`
+     * so the tooltip's position always agrees with the same geometry
+     * `drawMatrix()`/`drawCalendar()`/`hitTest*()` use.
+     */
+    cellRect(pos) {
+        if ('week' in pos) {
+            return {
+                x: CAL_PAD_LEFT + pos.week * (CAL_CELL + CAL_GAP),
+                y: CAL_LABEL_H + pos.weekday * (CAL_CELL + CAL_GAP),
+                w: CAL_CELL,
+                h: CAL_CELL,
+            };
+        }
+        const cellSize = this.matrixCellSize(this.colLabels.length);
+        return { x: PAD_LEFT + pos.col * cellSize, y: PAD_TOP + pos.row * cellSize, w: cellSize - 1, h: cellSize - 1 };
+    }
+    /**
+     * Human-readable "<label>: <value>" text for a cell — shared by the hover
+     * tooltip and the keyboard-focus live-region announcement, so both always
+     * describe a cell the same way. This is the built-in English fallback used
+     * when `cellText` isn't set — see `resolveCellText()`.
+     */
+    defaultCellText(pos) {
+        return 'week' in pos ? this.calendarCellText(pos) : this.matrixCellText(pos);
+    }
+    matrixCellText(pos) {
+        const rowLabel = this.rowLabels[pos.row] ?? `row ${pos.row + 1}`;
+        const colLabel = this.colLabels[pos.col] ?? `col ${pos.col + 1}`;
+        const v = this.values[pos.row]?.[pos.col];
+        const valueText = v == null || v < 0 || !Number.isFinite(v) ? 'no data' : String(v);
+        return `Row ${rowLabel}, Col ${colLabel}: ${valueText}`;
+    }
+    calendarCellText(pos) {
+        const { date, value } = this.calendarCellAt(pos);
+        const label = parseIsoDate(date).toLocaleString(undefined, { month: 'short', day: 'numeric', timeZone: 'UTC' });
+        const valueText = value < 0 || !Number.isFinite(value) ? 'no data' : String(value);
+        return `${label}: ${valueText}`;
+    }
+    /** The raw numeric value at a cell position, in either mode — shared by `resolveCellText()`
+     *  so a custom `cellText` formatter receives the same value the built-in template would use. */
+    valueAt(pos) {
+        if ('week' in pos)
+            return this.calendarCellAt(pos).value;
+        return this.values[pos.row]?.[pos.col] ?? -1;
+    }
+    /** Dispatches to the host-provided `cellText` formatter when set, otherwise the built-in template. */
+    resolveCellText(pos) {
+        return this.cellText ? this.cellText(pos, this.valueAt(pos)) : this.defaultCellText(pos);
+    }
+    /** Refreshes the visually-hidden live-region text for a newly-focused cell. */
+    announce(pos) {
+        this.liveText = this.resolveCellText(pos);
+    }
+    emitCellClick(pos) {
+        if ('week' in pos) {
+            const { date, value } = this.calendarCellAt(pos);
+            this.emit('lyra-cell-click', { date, value });
+        }
+        else {
+            const value = this.values[pos.row]?.[pos.col] ?? -1;
+            this.emit('lyra-cell-click', { row: pos.row, col: pos.col, value });
+        }
+    }
+    /** Inline `style` for `[part="tooltip"]`, centered above the given cell. */
+    tooltipStyle(pos) {
+        const rect = this.cellRect(pos);
+        return { left: `${rect.x + rect.w / 2}px`, top: `${rect.y}px` };
+    }
+    onMatrixKeyDown(e) {
+        const rows = this.rowLabels.length;
+        const cols = this.colLabels.length;
+        if (rows === 0 || cols === 0)
+            return;
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            if (this.focusedCell)
+                this.emitCellClick(this.focusedCell);
+            return;
+        }
+        if (!ARROW_KEYS.has(e.key))
+            return;
+        e.preventDefault();
+        // The first arrow keypress just moves focus onto the grid (at the
+        // top-left cell) rather than also applying that keypress's delta —
+        // otherwise ArrowRight from "unfocused" would land on column 1,
+        // silently skipping column 0.
+        if (!this.focusedCell || !('row' in this.focusedCell)) {
+            const next = { row: 0, col: 0 };
+            this.focusedCell = next;
+            this.announce(next);
+            return;
+        }
+        const { row, col } = this.focusedCell;
+        let next = { row, col };
+        if (e.key === 'ArrowUp')
+            next = { row: Math.max(0, row - 1), col };
+        else if (e.key === 'ArrowDown')
+            next = { row: Math.min(rows - 1, row + 1), col };
+        else if (e.key === 'ArrowLeft')
+            next = { row, col: Math.max(0, col - 1) };
+        else if (e.key === 'ArrowRight')
+            next = { row, col: Math.min(cols - 1, col + 1) };
+        this.focusedCell = next;
+        this.announce(next);
+    }
+    onCalendarKeyDown(e) {
+        const { weekCount } = buildCalendarGrid(this.days);
+        if (weekCount === 0)
+            return;
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            if (this.focusedCell)
+                this.emitCellClick(this.focusedCell);
+            return;
+        }
+        if (!ARROW_KEYS.has(e.key))
+            return;
+        e.preventDefault();
+        if (!this.focusedCell || !('week' in this.focusedCell)) {
+            const next = { week: 0, weekday: 0 };
+            this.focusedCell = next;
+            this.announce(next);
+            return;
+        }
+        const { week, weekday } = this.focusedCell;
+        let next = { week, weekday };
+        if (e.key === 'ArrowUp')
+            next = { week, weekday: Math.max(0, weekday - 1) };
+        else if (e.key === 'ArrowDown')
+            next = { week, weekday: Math.min(6, weekday + 1) };
+        else if (e.key === 'ArrowLeft')
+            next = { week: Math.max(0, week - 1), weekday };
+        else if (e.key === 'ArrowRight')
+            next = { week: Math.min(weekCount - 1, week + 1), weekday };
+        this.focusedCell = next;
+        this.announce(next);
+    }
     render() {
-        const range = this.valueRange();
+        const range = this.cachedValueRange;
+        const labeledAnnotations = this.annotations.filter((a) => a.label);
         return html `
       <div part="base">
-        <canvas part="canvas"></canvas>
+        <canvas
+          part="canvas"
+          tabindex="0"
+          @pointermove=${this.onPointerMove}
+          @pointerleave=${this.onPointerLeave}
+          @click=${this.onCanvasClick}
+          @keydown=${this.onKeyDown}
+        ></canvas>
+        <div
+          part="tooltip"
+          ?hidden=${!this.hoverCell}
+          style=${styleMap(this.hoverCell ? this.tooltipStyle(this.hoverCell) : {})}
+        >
+          ${this.hoverCell ? this.resolveCellText(this.hoverCell) : ''}
+        </div>
+        <div part="live-region" class="sr-only" role="status" aria-live="polite">${this.liveText}</div>
         <div part="legend">
           <span part="legend-lo">${range ? range[0] : ''}</span>
           <span class="bar"></span>
           <span part="legend-hi">${range ? range[1] : ''}</span>
           <span>${this.valueLabel}</span>
+          ${labeledAnnotations.map((a) => html `<span part="legend-annotation"><span class="ring-swatch"></span>${a.label}</span>`)}
         </div>
       </div>
     `;
@@ -359,7 +761,22 @@ __decorate([
 __decorate([
     property({ attribute: 'bucket-count', type: Number })
 ], LyraHeatmap.prototype, "bucketCount", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraHeatmap.prototype, "annotations", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraHeatmap.prototype, "cellText", void 0);
 __decorate([
     query('canvas')
 ], LyraHeatmap.prototype, "canvas", void 0);
+__decorate([
+    state()
+], LyraHeatmap.prototype, "hoverCell", void 0);
+__decorate([
+    state()
+], LyraHeatmap.prototype, "focusedCell", void 0);
+__decorate([
+    state()
+], LyraHeatmap.prototype, "liveText", void 0);
 defineElement('heatmap', LyraHeatmap);

package/dist/components/heatmap/heatmap.stories.d.ts

@@ -3,3 +3,25 @@ declare const meta: Meta;
 export default meta;
 type Story = StoryObj;
 export declare const Default: Story;
+export declare const SqrtScaleFitToWidth: Story;
+export declare const CalendarMode: Story;
+export declare const CustomTheme: Story;
+/**
+ * Hover a cell for its tooltip, tab to the grid and use the arrow keys to
+ * move the focus ring (a visually-hidden live region announces each move),
+ * and click or press Enter/Space on a cell to see its `lyra-cell-click`
+ * detail logged below.
+ */
+export declare const HoverFocusClick: Story;
+/**
+ * Cells flagged via `annotations` get a stroked ring; ones with a `label`
+ * also surface a swatch + text entry in the legend.
+ */
+export declare const Annotations: Story;
+/**
+ * `cellText` overrides the built-in English tooltip/live-region template —
+ * here with a French translation — for both matrix and calendar modes.
+ */
+export declare const CustomCellText: Story;
+/** `annotations` in calendar mode match by ISO `date` instead of `row`/`col`. */
+export declare const CalendarAnnotations: Story;