@aceshooting/lyra-ui 1.1.0 → 2.0.0

package/dist/components/heatmap/calendar-grid.d.ts

@@ -23,7 +23,10 @@ export declare function parseIsoDate(iso: string): Date;
  * string yields an `Invalid Date` (`getTime()` is `NaN`), and letting that
  * single `NaN` reach the min/max below would poison `firstWeekStart` (and
  * therefore every cell's `week`) for the whole grid instead of just the bad
- * entry.
+ * entry. Likewise, an entry whose `date` is numerically well-formed but
+ * calendar-invalid (e.g. `'2026-02-30'`, which `Date.UTC` silently rolls
+ * over into March) is dropped rather than silently renormalized — see
+ * `isCalendarValid()`.
  */
 export declare function buildCalendarGrid(days: CalendarDay[]): {
     cells: CalendarCell[];

package/dist/components/heatmap/calendar-grid.js

@@ -5,6 +5,12 @@ export function parseIsoDate(iso) {
     const [y, m, d] = iso.split('-').map(Number);
     return new Date(Date.UTC(y, m - 1, d));
 }
+/** Whether `iso` (already run through parseIsoDate) actually round-trips —
+ *  Date.UTC silently rolls e.g. day 30 of a 28-day February into March. */
+function isCalendarValid(iso, parsed) {
+    const [y, m, d] = iso.split('-').map(Number);
+    return parsed.getUTCFullYear() === y && parsed.getUTCMonth() === m - 1 && parsed.getUTCDate() === d;
+}
 /**
  * Lays `days` out onto a GitHub-style Sunday-Saturday x week grid. `days`
  * need not be sorted or contiguous; the grid spans from the earliest to the
@@ -15,12 +21,15 @@ export function parseIsoDate(iso) {
  * string yields an `Invalid Date` (`getTime()` is `NaN`), and letting that
  * single `NaN` reach the min/max below would poison `firstWeekStart` (and
  * therefore every cell's `week`) for the whole grid instead of just the bad
- * entry.
+ * entry. Likewise, an entry whose `date` is numerically well-formed but
+ * calendar-invalid (e.g. `'2026-02-30'`, which `Date.UTC` silently rolls
+ * over into March) is dropped rather than silently renormalized — see
+ * `isCalendarValid()`.
  */
 export function buildCalendarGrid(days) {
     const parsed = days
         .map((d) => ({ ...d, dateObj: parseIsoDate(d.date) }))
-        .filter((d) => !Number.isNaN(d.dateObj.getTime()));
+        .filter((d) => !Number.isNaN(d.dateObj.getTime()) && isCalendarValid(d.date, d.dateObj));
     if (parsed.length === 0) {
         return { cells: [], weekCount: 0, firstWeekStart: new Date(0), monthLabels: [] };
     }
@@ -34,18 +43,22 @@ export function buildCalendarGrid(days) {
         return { date: d.date, value: d.value, week, weekday };
     });
     const weekCount = minMax(cells.map((c) => c.week))[1] + 1;
+    // Label every distinct (year, month) present in the data, not just months
+    // that happen to contain a Sunday-anchored cell — a sparse calendar (few
+    // days per month, none landing on a Sunday) would otherwise render zero
+    // month labels for months that do have data.
     const monthLabels = [];
-    let lastMonth = -1;
-    for (const cell of cells.slice().sort((a, b) => a.week - b.week)) {
+    const seenMonths = new Set();
+    for (const cell of cells.slice().sort((a, b) => a.week - b.week || a.weekday - b.weekday)) {
         const cellDate = parseIsoDate(cell.date);
-        const month = cellDate.getUTCMonth();
-        if (cell.weekday === 0 && month !== lastMonth) {
-            lastMonth = month;
-            monthLabels.push({
-                week: cell.week,
-                label: cellDate.toLocaleString('en', { month: 'short', timeZone: 'UTC' }),
-            });
-        }
+        const key = `${cellDate.getUTCFullYear()}-${cellDate.getUTCMonth()}`;
+        if (seenMonths.has(key))
+            continue;
+        seenMonths.add(key);
+        monthLabels.push({
+            week: cell.week,
+            label: cellDate.toLocaleString(undefined, { month: 'short', timeZone: 'UTC' }),
+        });
     }
     return { cells, weekCount, firstWeekStart, monthLabels };
 }

package/dist/components/heatmap/heatmap-scale.d.ts

@@ -12,5 +12,11 @@ export declare function minMax(values: number[]): [number, number] | null;
  * Square-root-scaled bucket index in `[0, steps-1]`, or `-1` for no-data.
  * Compresses large counts so a single heavy cell doesn't wash out the rest
  * of a sequential color ramp.
+ *
+ * Only a negative `count` means "no data" here — the true no-data sentinel
+ * (`v < 0 || !Number.isFinite(v)`) is already filtered out by the caller
+ * (`drawMatrix()`) before `sqrtStep` is ever invoked, so a real `count === 0`
+ * (e.g. "zero events that day") reaches this function and must bucket to the
+ * lowest ramp step like any other legitimate value, not render as no-data.
  */
 export declare function sqrtStep(count: number, max: number, steps: number): number;

package/dist/components/heatmap/heatmap-scale.js

@@ -29,9 +29,15 @@ export function minMax(values) {
  * Square-root-scaled bucket index in `[0, steps-1]`, or `-1` for no-data.
  * Compresses large counts so a single heavy cell doesn't wash out the rest
  * of a sequential color ramp.
+ *
+ * Only a negative `count` means "no data" here — the true no-data sentinel
+ * (`v < 0 || !Number.isFinite(v)`) is already filtered out by the caller
+ * (`drawMatrix()`) before `sqrtStep` is ever invoked, so a real `count === 0`
+ * (e.g. "zero events that day") reaches this function and must bucket to the
+ * lowest ramp step like any other legitimate value, not render as no-data.
  */
 export function sqrtStep(count, max, steps) {
-    if (count <= 0 || max <= 0)
+    if (count < 0 || max <= 0)
         return -1;
     const ratio = Math.sqrt(count) / Math.sqrt(max);
     return Math.min(steps - 1, Math.floor(ratio * steps));

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

@@ -79,10 +79,18 @@ export declare function mixColor(fromColor: string, toColor: string, t: number):
  * specific cells (e.g. to call out an anomaly), each one optionally
  * surfaced in the legend too via `[part="legend-annotation"]`.
  *
+ * `columnX` (calendar mode only) overrides the x-origin computed for each
+ * week column — drawing, hit-testing, the focus ring, and month-label
+ * positioning all consult it consistently, so a consumer can pixel-align a
+ * calendar's week columns with a sibling chart's coordinate system. Unset
+ * (the default) keeps the original evenly-spaced formula.
+ *
  * @customElement lyra-heatmap
  * @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.
+ * `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 declare class LyraHeatmap extends LyraElement {
@@ -107,6 +115,23 @@ export declare class LyraHeatmap extends LyraElement {
     bucketCount: number;
     /** Cells to ring-highlight — `row`/`col` in matrix mode, `date` in calendar mode. See `HeatmapAnnotation`. */
     annotations: HeatmapAnnotation[];
+    /** Formats the per-cell tooltip and keyboard live-region text — receives the cell position
+     *  (`MatrixCellPos` in matrix mode, `CalendarCellPos` in calendar mode) and its value. Falls back to
+     *  the built-in English "Row X, Col Y: value" / "Mon DD: value" template when unset. */
+    cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string;
+    /**
+     * Calendar mode only: overrides the x-origin (canvas-local CSS px) of week
+     * column `index` (0-based, same indexing as `CalendarCellPos.week`).
+     * Consulted consistently by every calendar-mode geometry call site —
+     * drawing, hit-testing, the keyboard focus ring, and month-label
+     * positioning — via the private `columnXFor()` helper, so painted
+     * geometry and pointer hit-testing never disagree. Lets a consumer
+     * pixel-align a calendar's week columns with a sibling chart's bars by
+     * supplying that chart the same coordinate function. Unset (the default)
+     * keeps today's evenly-spaced `CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP)`
+     * formula unchanged. Ignored in matrix mode.
+     */
+    columnX?: (index: number) => number;
     private canvas?;
     private resizeObserver?;
     private dprQuery?;
@@ -119,6 +144,19 @@ export declare class LyraHeatmap extends LyraElement {
     private focusedCell;
     /** Text of the visually-hidden `aria-live="polite"` status announcement, refreshed on every focus move. */
     private liveText;
+    /**
+     * Whether `role`/`aria-label` were present on the host *before* this
+     * element's own code ever wrote to them — snapshotted once, in the very
+     * first `willUpdate()` (guarded by `hasUpdated`, which Lit only flips to
+     * `true` after that first update commits). Re-checking `hasAttribute()` on
+     * every update instead would self-poison: once this element writes its own
+     * default `aria-label` on the first render, `hasAttribute('aria-label')`
+     * is permanently `true` afterwards, which would wrongly look like an
+     * author-supplied value and freeze the label instead of refreshing it as
+     * `values`/`days` change on later updates.
+     */
+    private authorSuppliedRole;
+    private authorSuppliedAriaLabel;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private watchDpr;
@@ -148,6 +186,40 @@ export declare class LyraHeatmap extends LyraElement {
     /** Reads the customizable canvas-drawn annotation-ring stroke color off the host's computed style. */
     private annotationColor;
     private draw;
+    /**
+     * Calendar-mode week-column x-origin (canvas-local CSS px) — `columnX(week)`
+     * when set, otherwise the original evenly-spaced formula. Shared by every
+     * calendar-mode drawing and hit-testing call site (`drawCalendar()`,
+     * `hitTestCalendar()`/`weekAtX()`, `cellRect()`) so painted geometry and
+     * interactive hit-testing never disagree — mirrors the existing
+     * `matrixCellSize()` invariant for matrix mode's
+     * `drawMatrix()`/`hitTestMatrix()`/`cellRect()`.
+     */
+    private columnXFor;
+    /**
+     * Inverse of `columnXFor()`: resolves an x position (canvas-local CSS px)
+     * to the week column it falls in, or `null` if it's outside every column
+     * (`weekCount` is 0, or `x` doesn't land inside `[0, weekCount)`'s span).
+     * The default spacing has a closed-form inverse (division); an arbitrary
+     * `columnX` override doesn't, so that case instead scans each column's
+     * `[columnXFor(week), columnXFor(week + 1))` span — algebraically the same
+     * span the default formula's division derives — so hit-testing always
+     * agrees with wherever `columnXFor()` actually painted that column.
+     */
+    private weekAtX;
+    /**
+     * Locale-derived weekday-axis labels for the Sunday..Saturday rows drawn
+     * down the left of the calendar grid. Only indices 1 (Mon), 3 (Wed), and 5
+     * (Fri) are filled in — matching today's sparse every-other-day label
+     * density — the rest stay blank. `firstWeekStart` is always a UTC Sunday
+     * by construction (see `buildCalendarGrid()`), so weekday index 0..6 is a
+     * fixed Sun..Sat positional mapping; only the label *text* for indices
+     * 1/3/5 is derived here, via `Intl.DateTimeFormat` on a real UTC date that
+     * actually falls on that weekday, so it follows the runtime locale instead
+     * of a hardcoded English array (see `calendarCellText()`'s tooltip text
+     * for the same pattern).
+     */
+    private weekdayLabels;
     private drawCalendar;
     /**
      * Effective per-cell size in matrix mode — `fitToWidth` derives it from
@@ -185,16 +257,30 @@ export declare class LyraHeatmap extends LyraElement {
     /**
      * 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.
+     * describe a cell the same way. This is the built-in English fallback used
+     * when `cellText` isn't set — see `resolveCellText()`.
      */
-    private cellText;
+    private defaultCellText;
     private matrixCellText;
     private calendarCellText;
+    /** 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. */
+    private valueAt;
+    /** Dispatches to the host-provided `cellText` formatter when set, otherwise the built-in template. */
+    private resolveCellText;
     /** Refreshes the visually-hidden live-region text for a newly-focused cell. */
     private announce;
     private emitCellClick;
     /** Inline `style` for `[part="tooltip"]`, centered above the given cell. */
     private tooltipStyle;
+    /**
+     * Value-equality check for a `CellPos`, since `hoverCell` is assigned a
+     * fresh object literal on every `pointermove` — Lit's `@state()`
+     * change-detection only no-ops an identical *reference*, so without this,
+     * `{row,col} !== {row,col}` by reference triggers a full canvas clear +
+     * redraw on every pixel of pointer movement, even within the same cell.
+     */
+    private samePos;
     private onPointerMove;
     private onPointerLeave;
     private onCanvasClick;

package/dist/components/heatmap/heatmap.js

@@ -167,10 +167,18 @@ export function mixColor(fromColor, toColor, t) {
  * specific cells (e.g. to call out an anomaly), each one optionally
  * surfaced in the legend too via `[part="legend-annotation"]`.
  *
+ * `columnX` (calendar mode only) overrides the x-origin computed for each
+ * week column — drawing, hit-testing, the focus ring, and month-label
+ * positioning all consult it consistently, so a consumer can pixel-align a
+ * calendar's week columns with a sibling chart's coordinate system. Unset
+ * (the default) keeps the original evenly-spaced formula.
+ *
  * @customElement lyra-heatmap
  * @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.
+ * `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 {
@@ -205,21 +213,37 @@ export class LyraHeatmap extends LyraElement {
         this.focusedCell = null;
         /** Text of the visually-hidden `aria-live="polite"` status announcement, refreshed on every focus move. */
         this.liveText = '';
+        /**
+         * Whether `role`/`aria-label` were present on the host *before* this
+         * element's own code ever wrote to them — snapshotted once, in the very
+         * first `willUpdate()` (guarded by `hasUpdated`, which Lit only flips to
+         * `true` after that first update commits). Re-checking `hasAttribute()` on
+         * every update instead would self-poison: once this element writes its own
+         * default `aria-label` on the first render, `hasAttribute('aria-label')`
+         * is permanently `true` afterwards, which would wrongly look like an
+         * author-supplied value and freeze the label instead of refreshing it as
+         * `values`/`days` change on later updates.
+         */
+        this.authorSuppliedRole = false;
+        this.authorSuppliedAriaLabel = false;
         this.onDprChange = () => {
             this.watchDpr();
             this.draw();
         };
         this.onPointerMove = (e) => {
-            this.hoverCell = this.hitTest(e.offsetX, e.offsetY);
+            const next = this.hitTest(e.offsetX, e.offsetY);
+            if (!this.samePos(this.hoverCell, next))
+                this.hoverCell = next;
         };
         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;
+            // Only the click's own hit-tested position counts — a click that lands
+            // outside the grid (e.g. on the canvas's own padding) is a genuine
+            // out-of-grid click and should do nothing, not fall back to whatever
+            // cell happens to still be keyboard-focused from an earlier interaction.
+            const pos = this.hitTest(e.offsetX, e.offsetY);
             if (!pos)
                 return;
             this.focusedCell = pos;
@@ -267,17 +291,31 @@ export class LyraHeatmap extends LyraElement {
             this.hoverCell = null;
             this.liveText = '';
         }
+        if (!this.hasUpdated) {
+            this.authorSuppliedRole = this.hasAttribute('role');
+            this.authorSuppliedAriaLabel = this.hasAttribute('aria-label');
+        }
         this.cachedValueRange = this.computeValueRange();
         const bounds = this.cachedValueRange;
         const range = bounds ? `${bounds[0]}–${bounds[1]}` : 'no data';
-        this.setAttribute('role', 'img');
-        if (this.mode === 'calendar') {
-            this.setAttribute('aria-label', `Calendar heatmap of ${this.days.length} days, ${this.valueLabel} range ${range}`);
-        }
-        else {
-            const rows = this.rowLabels.length;
-            const cols = this.colLabels.length;
-            this.setAttribute('aria-label', `Heatmap of ${rows} × ${cols} cells, ${this.valueLabel} range ${range}`);
+        // Only default role/aria-label when the author hasn't already supplied
+        // one — the canvas is a genuinely focusable/interactive control
+        // (tabindex="0", click/keydown handlers) plus a live role="status"
+        // region, so unconditionally forcing a role here would tell assistive
+        // tech to flatten the whole subtree, hiding both from the accessibility
+        // tree; it would also silently overwrite any author-supplied
+        // role/aria-label on every update.
+        if (!this.authorSuppliedRole)
+            this.setAttribute('role', 'group');
+        if (!this.authorSuppliedAriaLabel) {
+            if (this.mode === 'calendar') {
+                this.setAttribute('aria-label', `Calendar heatmap of ${this.days.length} days, ${this.valueLabel} range ${range}`);
+            }
+            else {
+                const rows = this.rowLabels.length;
+                const cols = this.colLabels.length;
+                this.setAttribute('aria-label', `Heatmap of ${rows} × ${cols} cells, ${this.valueLabel} range ${range}`);
+            }
         }
     }
     /**
@@ -329,11 +367,66 @@ export class LyraHeatmap extends LyraElement {
         else
             this.drawMatrix();
     }
+    /**
+     * Calendar-mode week-column x-origin (canvas-local CSS px) — `columnX(week)`
+     * when set, otherwise the original evenly-spaced formula. Shared by every
+     * calendar-mode drawing and hit-testing call site (`drawCalendar()`,
+     * `hitTestCalendar()`/`weekAtX()`, `cellRect()`) so painted geometry and
+     * interactive hit-testing never disagree — mirrors the existing
+     * `matrixCellSize()` invariant for matrix mode's
+     * `drawMatrix()`/`hitTestMatrix()`/`cellRect()`.
+     */
+    columnXFor(week) {
+        return this.columnX ? this.columnX(week) : CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP);
+    }
+    /**
+     * Inverse of `columnXFor()`: resolves an x position (canvas-local CSS px)
+     * to the week column it falls in, or `null` if it's outside every column
+     * (`weekCount` is 0, or `x` doesn't land inside `[0, weekCount)`'s span).
+     * The default spacing has a closed-form inverse (division); an arbitrary
+     * `columnX` override doesn't, so that case instead scans each column's
+     * `[columnXFor(week), columnXFor(week + 1))` span — algebraically the same
+     * span the default formula's division derives — so hit-testing always
+     * agrees with wherever `columnXFor()` actually painted that column.
+     */
+    weekAtX(x, weekCount) {
+        if (!this.columnX) {
+            const week = Math.floor((x - CAL_PAD_LEFT) / (CAL_CELL + CAL_GAP));
+            return week >= 0 && week < weekCount ? week : null;
+        }
+        for (let week = 0; week < weekCount; week++) {
+            const start = this.columnXFor(week);
+            const end = week + 1 < weekCount ? this.columnXFor(week + 1) : start + (CAL_CELL + CAL_GAP);
+            if (x >= start && x < end)
+                return week;
+        }
+        return null;
+    }
+    /**
+     * Locale-derived weekday-axis labels for the Sunday..Saturday rows drawn
+     * down the left of the calendar grid. Only indices 1 (Mon), 3 (Wed), and 5
+     * (Fri) are filled in — matching today's sparse every-other-day label
+     * density — the rest stay blank. `firstWeekStart` is always a UTC Sunday
+     * by construction (see `buildCalendarGrid()`), so weekday index 0..6 is a
+     * fixed Sun..Sat positional mapping; only the label *text* for indices
+     * 1/3/5 is derived here, via `Intl.DateTimeFormat` on a real UTC date that
+     * actually falls on that weekday, so it follows the runtime locale instead
+     * of a hardcoded English array (see `calendarCellText()`'s tooltip text
+     * for the same pattern).
+     */
+    weekdayLabels(firstWeekStart) {
+        const formatter = new Intl.DateTimeFormat(undefined, { weekday: 'short', timeZone: 'UTC' });
+        const labels = ['', '', '', '', '', '', ''];
+        for (const weekday of [1, 3, 5]) {
+            labels[weekday] = formatter.format(new Date(firstWeekStart.getTime() + weekday * MS_PER_DAY));
+        }
+        return labels;
+    }
     drawCalendar() {
         if (!this.canvas)
             return;
-        const { cells, weekCount, monthLabels } = buildCalendarGrid(this.days);
-        const w = CAL_PAD_LEFT + Math.max(1, weekCount) * (CAL_CELL + CAL_GAP);
+        const { cells, weekCount, firstWeekStart, monthLabels } = buildCalendarGrid(this.days);
+        const w = this.columnXFor(Math.max(1, weekCount));
         const h = CAL_LABEL_H + 7 * (CAL_CELL + CAL_GAP);
         const dpr = window.devicePixelRatio || 1;
         this.canvas.width = w * dpr;
@@ -356,7 +449,7 @@ export class LyraHeatmap extends LyraElement {
         const ramp = Array.from({ length: buckets }, (_, i) => mixRgb(loRgb, hiRgb, i / (buckets - 1)));
         const noDataFill = this.noDataFill();
         for (const cell of cells) {
-            const x = CAL_PAD_LEFT + cell.week * (CAL_CELL + CAL_GAP);
+            const x = this.columnXFor(cell.week);
             const y = CAL_LABEL_H + cell.weekday * (CAL_CELL + CAL_GAP);
             ctx.fillStyle =
                 cell.value < 0 || !Number.isFinite(cell.value)
@@ -376,7 +469,7 @@ export class LyraHeatmap extends LyraElement {
                 const match = cells.find((c) => c.date === ann.date);
                 if (!match)
                     continue;
-                const x = CAL_PAD_LEFT + match.week * (CAL_CELL + CAL_GAP);
+                const x = this.columnXFor(match.week);
                 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);
             }
@@ -388,7 +481,7 @@ export class LyraHeatmap extends LyraElement {
             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 x = this.columnXFor(week);
                 const y = CAL_LABEL_H + weekday * (CAL_CELL + CAL_GAP);
                 ctx.strokeRect(x + 0.5, y + 0.5, CAL_CELL - 1, CAL_CELL - 1);
             }
@@ -396,9 +489,9 @@ export class LyraHeatmap extends LyraElement {
         ctx.fillStyle = this.labelColor();
         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);
+            ctx.fillText(m.label, this.columnXFor(m.week), CAL_LABEL_H - 4);
         }
-        const WEEKDAY_LABELS = ['', 'Mon', '', 'Wed', '', 'Fri', ''];
+        const WEEKDAY_LABELS = this.weekdayLabels(firstWeekStart);
         WEEKDAY_LABELS.forEach((label, weekday) => {
             if (label)
                 ctx.fillText(label, 2, CAL_LABEL_H + weekday * (CAL_CELL + CAL_GAP) + CAL_CELL - 1);
@@ -537,9 +630,9 @@ export class LyraHeatmap extends LyraElement {
         const { weekCount } = buildCalendarGrid(this.days);
         if (weekCount === 0)
             return null;
-        const week = Math.floor((x - CAL_PAD_LEFT) / (CAL_CELL + CAL_GAP));
+        const week = this.weekAtX(x, weekCount);
         const weekday = Math.floor((y - CAL_LABEL_H) / (CAL_CELL + CAL_GAP));
-        if (week < 0 || week >= weekCount || weekday < 0 || weekday > 6)
+        if (week === null || weekday < 0 || weekday > 6)
             return null;
         return { week, weekday };
     }
@@ -567,7 +660,7 @@ export class LyraHeatmap extends LyraElement {
     cellRect(pos) {
         if ('week' in pos) {
             return {
-                x: CAL_PAD_LEFT + pos.week * (CAL_CELL + CAL_GAP),
+                x: this.columnXFor(pos.week),
                 y: CAL_LABEL_H + pos.weekday * (CAL_CELL + CAL_GAP),
                 w: CAL_CELL,
                 h: CAL_CELL,
@@ -579,9 +672,10 @@ export class LyraHeatmap extends LyraElement {
     /**
      * 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.
+     * describe a cell the same way. This is the built-in English fallback used
+     * when `cellText` isn't set — see `resolveCellText()`.
      */
-    cellText(pos) {
+    defaultCellText(pos) {
         return 'week' in pos ? this.calendarCellText(pos) : this.matrixCellText(pos);
     }
     matrixCellText(pos) {
@@ -593,13 +687,24 @@ export class LyraHeatmap extends LyraElement {
     }
     calendarCellText(pos) {
         const { date, value } = this.calendarCellAt(pos);
-        const label = parseIsoDate(date).toLocaleString('en', { month: 'short', day: 'numeric', timeZone: 'UTC' });
+        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.cellText(pos);
+        this.liveText = this.resolveCellText(pos);
     }
     emitCellClick(pos) {
         if ('week' in pos) {
@@ -616,6 +721,24 @@ export class LyraHeatmap extends LyraElement {
         const rect = this.cellRect(pos);
         return { left: `${rect.x + rect.w / 2}px`, top: `${rect.y}px` };
     }
+    /**
+     * Value-equality check for a `CellPos`, since `hoverCell` is assigned a
+     * fresh object literal on every `pointermove` — Lit's `@state()`
+     * change-detection only no-ops an identical *reference*, so without this,
+     * `{row,col} !== {row,col}` by reference triggers a full canvas clear +
+     * redraw on every pixel of pointer movement, even within the same cell.
+     */
+    samePos(a, b) {
+        if (a === b)
+            return true;
+        if (!a || !b)
+            return false;
+        if ('week' in a && 'week' in b)
+            return a.week === b.week && a.weekday === b.weekday;
+        if ('row' in a && 'row' in b)
+            return a.row === b.row && a.col === b.col;
+        return false;
+    }
     onMatrixKeyDown(e) {
         const rows = this.rowLabels.length;
         const cols = this.colLabels.length;
@@ -703,7 +826,7 @@ export class LyraHeatmap extends LyraElement {
           ?hidden=${!this.hoverCell}
           style=${styleMap(this.hoverCell ? this.tooltipStyle(this.hoverCell) : {})}
         >
-          ${this.hoverCell ? this.cellText(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">
@@ -750,6 +873,12 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], LyraHeatmap.prototype, "annotations", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraHeatmap.prototype, "cellText", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraHeatmap.prototype, "columnX", void 0);
 __decorate([
     query('canvas')
 ], LyraHeatmap.prototype, "canvas", void 0);

package/dist/components/json-viewer/json-viewer.d.ts

@@ -0,0 +1,53 @@
+import { type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/**
+ * `<lyra-json-viewer>` — a collapsible, copyable tree view for an arbitrary
+ * JSON-serializable value (object/array/string/number/boolean/null/
+ * undefined). Serves as the fallback renderer wherever a raw payload (tool
+ * call arguments, a tool result, an API response) needs inspecting without a
+ * bespoke view.
+ *
+ * Expand/collapse state is keyed by structural path (not by object identity),
+ * so it survives a `data` reassignment that keeps the same shape -- e.g. a
+ * streaming tool result being patched in place.
+ *
+ * @customElement lyra-json-viewer
+ * @event lyra-copy - `detail: { text }` -- fired by the top-level copy button or a per-node one. Fires even when `navigator.clipboard` silently failed or is unavailable (insecure context, older browser, stubbed-out test environment), so a consumer can still observe copy *intent*.
+ * @csspart base - The root scroll container; respects `max-height`.
+ * @csspart toolbar - The wrapper around the top-level copy button (only rendered when `copyable`).
+ * @csspart tree - The wrapper around the rendered node tree.
+ * @csspart key - An object property key or array index label.
+ * @csspart value - A primitive value's text -- carries `data-type` (`string`/`number`/`boolean`/`null`/`undefined`) for per-type coloring, and `data-match` while it matches `search`.
+ * @csspart bracket - A `{`, `}`, `[`, or `]` delimiter.
+ * @csspart toggle - A container node's expand/collapse button (hidden, but present for row alignment, on leaf/empty nodes).
+ * @csspart copy-button - A copy-to-clipboard button -- the top-level one (in `toolbar`) or a per-node one (only rendered when `copyable`).
+ */
+export declare class LyraJsonViewer extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The value to render. Any JSON-serializable value, plus `undefined`. */
+    data: unknown;
+    /** Nodes at or beyond this nesting depth (root = 0) start collapsed. Omit/undefined: nothing auto-collapses. */
+    collapsedDepth?: number;
+    /** A CSS length (e.g. `"20rem"`); once set, the viewer scrolls internally past this height instead of growing the page. */
+    maxHeight: string;
+    /** Shows copy-to-clipboard affordances: one for the whole value, plus one per node. */
+    copyable: boolean;
+    /** Case-insensitive substring match against keys/values; matches are highlighted and their ancestors auto-expanded. */
+    search: string;
+    /** Per-path (`JSON.stringify(path)`) explicit expand/collapse, overriding the `collapsedDepth`/search defaults once a node's toggle has been used. */
+    private expandedOverrides;
+    private isExpanded;
+    private toggleNode;
+    private writeClipboard;
+    private copy;
+    /** Builds the key/value-match sets and the ancestor-paths-of-a-match set that `search` drives. */
+    private computeSearch;
+    private renderCopyButton;
+    private renderNode;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-json-viewer': LyraJsonViewer;
+    }
+}