@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/heatmap/heatmap.js

@@ -22,9 +22,22 @@ const FALLBACK_SCALE_HI = '#0969da';
 const FALLBACK_LABEL_FONT = '10px sans-serif';
 const CAL_PAD_LEFT = 28;
 const CAL_LABEL_H = 16;
+/** Calendar mode's original fixed cell size — now also the effective fallback
+ *  the `cellSize` accessor uses in calendar mode when left unset (see its
+ *  doc comment), so a consumer who never touches `cellSize` sees no change. */
 const CAL_CELL = 11;
 const CAL_GAP = 2;
+/** Matrix mode's original fixed cell size — the effective fallback the
+ *  `cellSize` accessor uses in matrix mode when left unset. */
+const DEFAULT_MATRIX_CELL_SIZE = 22;
 const DEFAULT_BUCKET_COUNT = 5;
+/**
+ * A linear RGB ramp cannot contain more than 256 visually distinct integer
+ * steps on any channel. Keeping the bucket count within that bound avoids an
+ * untrusted attribute/property value turning the ramp into an unbounded
+ * allocation without discarding any useful color resolution.
+ */
+export const MAX_BUCKET_COUNT = 256;
 /** Ring stroke width for both the annotation overlay and the keyboard focus ring. */
 const RING_LINE_WIDTH = 2;
 const FALLBACK_FOCUS_RING_COLOR = '#0969da';
@@ -66,30 +79,26 @@ 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.
+ * Normalizes a bucket count to the safe, renderable range. Non-finite values
+ * restore the public default; finite values are floored and clamped to
+ * `[2, MAX_BUCKET_COUNT]`. Flooring keeps the ramp array's length in exact
+ * agreement with the count used by `quartileBucket()`.
  */
-function resolveBucketCount(bucketCount) {
+export function normalizeBucketCount(bucketCount) {
     if (!Number.isFinite(bucketCount)) {
-        warnInvalidBucketCount(bucketCount);
         return DEFAULT_BUCKET_COUNT;
     }
-    return Math.max(2, Math.floor(bucketCount));
+    return Math.min(MAX_BUCKET_COUNT, Math.max(2, Math.floor(bucketCount)));
 }
+const bucketCountConverter = {
+    fromAttribute(value) {
+        return value === null ? DEFAULT_BUCKET_COUNT : normalizeBucketCount(Number(value));
+    },
+    toAttribute(value) {
+        return String(normalizeBucketCount(value));
+    },
+};
 /**
  * Resolves any syntactically valid CSS `<color>` — hex, `rgb()`, `hsl()`,
  * `oklch()`, a named color, etc. — to an `[r, g, b]` triple.
@@ -142,12 +151,16 @@ export function mixColor(fromColor, toColor, t) {
  * - `"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 rest; the default `"linear"` scale maps linearly instead.
+ * - `"calendar"`: a GitHub-style Sunday-Saturday (or `firstDayOfWeek`-anchored
+ *   — see below) x week grid built from `days`. `scale` governs its
+ *   bucketing too: the default `"linear"` buckets by `quartileBucket()`
+ *   (today's original behavior, unchanged); `"sqrt"` instead compresses via
+ *   the same `sqrtStep()` magnitude compression matrix mode uses, so one
+ *   heavy day doesn't wash out the rest. As in matrix mode, a cell whose
+ *   `value` is negative or non-finite is treated as "no data" rather than
+ *   being bucketed — as is a grid position with no matching entry in `days`
+ *   at all (a gap in a sparse calendar).
  *
  * The sequential color ramp's endpoints are read from the
  * `--lyra-heatmap-scale-lo`/`-hi` custom properties (declared in
@@ -167,13 +180,40 @@ 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. `rowY` is its
+ * calendar-mode vertical analogue — overrides the y-origin computed for each
+ * weekday row, consulted consistently by drawing, hit-testing, and the focus
+ * ring via the private `rowYFor()` helper (mirroring `columnXFor()` exactly).
+ *
+ * `firstDayOfWeek` (calendar mode only, default `0`/Sunday, no-op in matrix
+ * mode) anchors the calendar grid at a different weekday — `0`-`6`, same
+ * numbering as `CalendarCellPos.weekday` (`0` Sunday .. `6` Saturday) —
+ * threaded into `buildCalendarGrid()`.
+ *
+ * `cellSize`/`fitToWidth` (previously matrix-mode only) also drive calendar
+ * mode's per-cell size: unset, calendar mode keeps today's original 11px
+ * cell size unchanged; explicitly set, the same fixed size (or, with
+ * `fitToWidth`, the same host-width-derived size matrix mode already
+ * supports) governs calendar mode's grid too.
+ *
  * @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. `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
+ * @csspart base - The heatmap wrapper.
+ * @csspart canvas - The heatmap canvas.
+ * @csspart tooltip - The hover tooltip.
+ * @csspart live-region - The visually hidden keyboard announcement region.
+ * @csspart legend - The color legend.
+ * @csspart legend-lo - The low legend endpoint.
+ * @csspart legend-hi - The high legend endpoint.
+ * @csspart legend-annotation - An annotation label.
  */
 export class LyraHeatmap extends LyraElement {
     constructor() {
@@ -181,25 +221,57 @@ export class LyraHeatmap extends LyraElement {
         this.rowLabels = [];
         this.colLabels = [];
         this.values = [];
-        this.cellSize = 22;
         this.valueLabel = 'value';
+        /**
+         * `"linear"` (default) maps values linearly to the color ramp in matrix
+         * mode, and buckets calendar-mode values via `quartileBucket()` — both
+         * unchanged from before this property governed calendar mode too.
+         * `"sqrt"` compresses via `sqrtStep()`'s square-root magnitude compression
+         * instead, in *both* modes, so one heavy cell/day doesn't wash out the
+         * rest of a skewed dataset.
+         */
         this.scale = 'linear';
         /**
          * When set, `cellSize` is derived from the host's measured `clientWidth`
          * on every draw (including ResizeObserver-triggered redraws) instead of
          * the fixed `cell-size` attribute, so the grid actually fills the
          * available width. Without this, canvas dimensions are computed purely
-         * from `PAD_LEFT + cols * cellSize`, so a resize-triggered redraw is a
-         * geometric no-op.
+         * from `PAD_LEFT + cols * cellSize` (matrix mode) or
+         * `CAL_PAD_LEFT + weekCount * cellSize` (calendar mode), so a
+         * resize-triggered redraw is a geometric no-op. Originally matrix-mode
+         * only; now applies to calendar mode too.
          */
         this.fitToWidth = false;
         this.mode = 'matrix';
         this.days = [];
-        this.bucketCount = DEFAULT_BUCKET_COUNT;
+        /**
+         * Calendar mode only (no-op in matrix mode): anchors the calendar grid at
+         * a different weekday instead of always Sunday — `0`-`6`, same numbering
+         * as `CalendarCellPos.weekday` (`0` Sunday .. `6` Saturday, matching
+         * `CalendarCell.weekday`'s existing convention). Threaded into
+         * `buildCalendarGrid()`. Defaults to `0` (Sunday), unchanged from before
+         * this property existed.
+         */
+        this.firstDayOfWeek = 0;
+        this._bucketCount = DEFAULT_BUCKET_COUNT;
         /** Cells to ring-highlight — `row`/`col` in matrix mode, `date` in calendar mode. See `HeatmapAnnotation`. */
         this.annotations = [];
+        this.themeRefreshQueued = false;
         /** The current value range, refreshed once per update cycle by `willUpdate()`. See `computeValueRange()`. */
         this.cachedValueRange = null;
+        /**
+         * The calendar-mode grid layout, refreshed by `willUpdate()` only when
+         * `days` actually changes (see `computeValueRange()`'s twin comment above)
+         * — `buildCalendarGrid()` parses every date, filters invalid ones, and does
+         * a full `.slice().sort()` for month labels, so recomputing it from
+         * `drawCalendar()`, `hitTestCalendar()`, `calendarCellAt()`, and
+         * `onCalendarKeyDown()` independently would redo that work 2-4x for a
+         * single hover/click/keydown.
+         */
+        this.cachedCalendarGrid = buildCalendarGrid(this.days);
+        this.cachedCalendarSortedValues = [];
+        this.cachedCalendarCellsByPos = new Map();
+        this.cachedRamp = 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
@@ -207,21 +279,59 @@ 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.onColorSchemeChange = () => {
+            this.refreshTheme();
+        };
+        this.queueThemeRefresh = () => {
+            if (this.themeRefreshQueued)
+                return;
+            this.themeRefreshQueued = true;
+            queueMicrotask(() => {
+                this.themeRefreshQueued = false;
+                if (this.isConnected)
+                    this.refreshTheme();
+            });
+        };
+        this.scheduleDraw = () => {
+            if (this.drawRafId !== undefined)
+                return;
+            this.drawRafId = requestAnimationFrame(() => {
+                this.drawRafId = undefined;
+                if (this.isConnected)
+                    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;
@@ -236,16 +346,49 @@ export class LyraHeatmap extends LyraElement {
         };
     }
     static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    /**
+     * Effective per-cell size (CSS px). Originally matrix-mode only; now also
+     * governs calendar mode's cell size (replacing the previously hardcoded
+     * 11px constant there) once explicitly set. Left unset, each mode keeps
+     * its own original default — `DEFAULT_MATRIX_CELL_SIZE` (22) in matrix
+     * mode, `CAL_CELL` (11) in calendar mode — so an existing consumer who
+     * never touches `cellSize` sees no change in either mode. Set explicitly
+     * (attribute or property), the same value governs both modes alike.
+     */
+    get cellSize() {
+        return this._cellSize ?? (this.mode === 'calendar' ? CAL_CELL : DEFAULT_MATRIX_CELL_SIZE);
+    }
+    set cellSize(value) {
+        const oldValue = this._cellSize;
+        this._cellSize = value;
+        this.requestUpdate('cellSize', oldValue);
+    }
+    get bucketCount() {
+        return this._bucketCount;
+    }
+    set bucketCount(value) {
+        const oldValue = this._bucketCount;
+        this._bucketCount = normalizeBucketCount(value);
+        this.requestUpdate('bucketCount', oldValue);
+    }
     connectedCallback() {
         super.connectedCallback();
-        this.resizeObserver = new ResizeObserver(() => this.draw());
+        this.resizeObserver = new ResizeObserver(this.scheduleDraw);
         this.resizeObserver.observe(this);
         this.watchDpr();
+        this.watchTheme();
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.resizeObserver?.disconnect();
         this.dprQuery?.removeEventListener('change', this.onDprChange);
+        this.colorSchemeQuery?.removeEventListener('change', this.onColorSchemeChange);
+        this.themeObserver?.disconnect();
+        this.themeObserver = undefined;
+        if (this.drawRafId !== undefined) {
+            cancelAnimationFrame(this.drawRafId);
+            this.drawRafId = undefined;
+        }
     }
     watchDpr() {
         // A MediaQueryList's `matches` is fixed at creation time, so crossing the
@@ -256,30 +399,89 @@ export class LyraHeatmap extends LyraElement {
         this.dprQuery = matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
         this.dprQuery.addEventListener('change', this.onDprChange);
     }
+    watchTheme() {
+        const view = this.ownerDocument.defaultView;
+        if (!view)
+            return;
+        this.colorSchemeQuery = view.matchMedia?.('(prefers-color-scheme: dark)');
+        this.colorSchemeQuery?.addEventListener('change', this.onColorSchemeChange);
+        if (typeof MutationObserver === 'undefined')
+            return;
+        const targets = [this];
+        let parent = this.parentElement;
+        while (parent) {
+            targets.push(parent);
+            parent = parent.parentElement;
+        }
+        this.themeObserver = new MutationObserver(this.queueThemeRefresh);
+        for (const target of targets) {
+            this.themeObserver.observe(target, {
+                attributes: true,
+                attributeFilter: ['class', 'style', 'data-theme', 'data-color-scheme'],
+            });
+        }
+    }
     willUpdate(changed) {
-        if (changed.has('mode') || changed.has('rowLabels') || changed.has('colLabels') || changed.has('days')) {
+        if (changed.has('mode') ||
+            changed.has('rowLabels') ||
+            changed.has('colLabels') ||
+            changed.has('days') ||
+            changed.has('firstDayOfWeek')) {
             // 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.
+            // render rather than scheduling a whole extra update pass. A
+            // `firstDayOfWeek` change reshuffles every cell's week/weekday the same
+            // way a `days` change does, so it resets the cursor too.
             this.focusedCell = null;
             this.hoverCell = null;
             this.liveText = '';
         }
-        this.cachedValueRange = this.computeValueRange();
+        // Calendar-mode grid layout depends only on `days`/`firstDayOfWeek` (not
+        // `mode`) — rebuilt here, once per cycle, instead of independently by
+        // every call site (see `cachedCalendarGrid`'s doc comment).
+        if (changed.has('days') || changed.has('firstDayOfWeek') || !this.hasUpdated) {
+            this.cachedCalendarGrid = buildCalendarGrid(this.days, this.firstDayOfWeek);
+            this.cachedCalendarSortedValues = this.cachedCalendarGrid.cells
+                .map((cell) => cell.value)
+                .filter((value) => Number.isFinite(value) && value >= 0)
+                .sort((a, b) => a - b);
+            this.cachedCalendarCellsByPos = new Map(this.cachedCalendarGrid.cells.map((cell) => [`${cell.week}:${cell.weekday}`, cell]));
+        }
+        if (!this.hasUpdated) {
+            this.authorSuppliedRole = this.hasAttribute('role');
+            this.authorSuppliedAriaLabel = this.hasAttribute('aria-label');
+        }
+        // A hover/keyboard-focus @state() change (hoverCell/focusedCell/liveText)
+        // triggers this same willUpdate() but never touches values/days/mode, so
+        // gating the O(rows*cols) rescan the same way the focus/hover reset above
+        // is gated avoids redoing it on every pointer move.
+        if (changed.has('values') || changed.has('days') || changed.has('mode') || !this.hasUpdated) {
+            this.cachedValueRange = this.computeValueRange();
+        }
         const bounds = this.cachedValueRange;
         const range = bounds ? `${bounds[0]}–${bounds[1]}` : 'no data';
-        this.setAttribute('role', 'group');
-        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}`);
+            }
         }
     }
     /**
@@ -295,7 +497,29 @@ export class LyraHeatmap extends LyraElement {
         const source = this.mode === 'calendar' ? this.days.map((d) => d.value) : this.values.flat();
         return minMax(source.filter((v) => Number.isFinite(v) && v >= 0));
     }
-    updated() {
+    updated(changed) {
+        if ([
+            'values',
+            'rowLabels',
+            'colLabels',
+            'cellSize',
+            'valueLabel',
+            'scale',
+            'fitToWidth',
+            'mode',
+            'days',
+            'bucketCount',
+            'annotations',
+            'columnX',
+            'rowY',
+            'firstDayOfWeek',
+            'focusedCell',
+        ].some((name) => changed.has(name))) {
+            this.draw();
+        }
+    }
+    /** Redraws canvas content after an upstream token or theme change. */
+    refreshTheme() {
         this.draw();
     }
     /** Reads the customizable ramp endpoints off the host's computed style. */
@@ -331,12 +555,141 @@ export class LyraHeatmap extends LyraElement {
         else
             this.drawMatrix();
     }
+    colorRamp(bucketCount) {
+        const [scaleLo, scaleHi] = this.scaleEndpoints();
+        const normalizedBucketCount = normalizeBucketCount(bucketCount);
+        const key = `${scaleLo}\u0000${scaleHi}\u0000${normalizedBucketCount}`;
+        if (this.cachedRamp?.key === key)
+            return this.cachedRamp;
+        const loRgb = resolveRgb(scaleLo, FALLBACK_SCALE_LO);
+        const hiRgb = resolveRgb(scaleHi, FALLBACK_SCALE_HI);
+        const colors = Array.from({ length: normalizedBucketCount }, (_, i) => mixRgb(loRgb, hiRgb, i / (normalizedBucketCount - 1)));
+        this.cachedRamp = { key, colors, loRgb, hiRgb };
+        return this.cachedRamp;
+    }
+    /**
+     * Effective per-cell size in calendar mode — mirrors `matrixCellSize()`
+     * exactly: `fitToWidth` derives it from the host's measured width,
+     * otherwise it's the (possibly explicitly-set) `cellSize` property, which
+     * itself falls back to today's original 11px calendar default when left
+     * unset (see `cellSize`'s accessor doc comment). Shared by `columnXFor()`,
+     * `rowYFor()`, `drawCalendar()`, and the hit-testing below (`weekAtX()`,
+     * `weekdayAtY()`, `cellRect()`) so they always agree on exactly the same
+     * geometry as what's actually painted.
+     */
+    calendarCellSize() {
+        const { weekCount } = this.cachedCalendarGrid;
+        if (this.fitToWidth && weekCount > 0) {
+            // Unlike matrix mode's contiguous cells, calendar columns are spaced
+            // `cellSize + CAL_GAP` apart (see `columnXFor()`), so the gap has to be
+            // subtracted back out here — otherwise the painted width would overshoot
+            // `hostWidth` by `weekCount * CAL_GAP` (every column's gap, once each).
+            const hostWidth = this.clientWidth || CAL_PAD_LEFT + weekCount * (this.cellSize + CAL_GAP);
+            return Math.max(4, (hostWidth - CAL_PAD_LEFT) / weekCount - CAL_GAP);
+        }
+        return this.cellSize;
+    }
+    /**
+     * Calendar-mode week-column x-origin (canvas-local CSS px) — `columnX(week)`
+     * when set, otherwise the original evenly-spaced formula (now derived from
+     * `calendarCellSize()` rather than the fixed `CAL_CELL` constant). 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 * (this.calendarCellSize() + CAL_GAP);
+    }
+    /**
+     * Calendar-mode weekday-row y-origin (canvas-local CSS px) — `rowY(weekday)`
+     * when set, otherwise the original evenly-spaced formula (now derived from
+     * `calendarCellSize()` rather than the fixed `CAL_CELL` constant). The
+     * vertical analogue of `columnXFor()`, mirroring its exact
+     * dispatch-with-computed-fallback shape and shared by the same
+     * drawing/hit-testing/focus-ring call sites.
+     */
+    rowYFor(weekday) {
+        return this.rowY ? this.rowY(weekday) : CAL_LABEL_H + weekday * (this.calendarCellSize() + 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 cellSize = this.calendarCellSize();
+            const week = Math.floor((x - CAL_PAD_LEFT) / (cellSize + 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 + (this.calendarCellSize() + CAL_GAP);
+            if (x >= start && x < end)
+                return week;
+        }
+        return null;
+    }
+    /**
+     * Inverse of `rowYFor()`: resolves a y position (canvas-local CSS px) to
+     * the weekday row it falls in (0-6), or `null` if it's outside every row.
+     * Mirrors `weekAtX()`'s closed-form-vs-scan split for the same reason: the
+     * default spacing has a closed-form inverse; an arbitrary `rowY` override
+     * doesn't.
+     */
+    weekdayAtY(y) {
+        if (!this.rowY) {
+            const cellSize = this.calendarCellSize();
+            const weekday = Math.floor((y - CAL_LABEL_H) / (cellSize + CAL_GAP));
+            return weekday >= 0 && weekday < 7 ? weekday : null;
+        }
+        for (let weekday = 0; weekday < 7; weekday++) {
+            const start = this.rowYFor(weekday);
+            const end = weekday + 1 < 7 ? this.rowYFor(weekday + 1) : start + (this.calendarCellSize() + CAL_GAP);
+            if (y >= start && y < end)
+                return weekday;
+        }
+        return null;
+    }
+    /**
+     * Locale-derived weekday-axis labels for the 7 rows drawn down the left of
+     * the calendar grid. Only indices 1, 3, and 5 (relative to `firstWeekStart`)
+     * are filled in — matching today's sparse every-other-day label density —
+     * the rest stay blank. `firstWeekStart` is always the UTC
+     * `firstDayOfWeek`-weekday by construction (see `buildCalendarGrid()`), so
+     * weekday index 0..6 is a fixed positional mapping relative to it (with the
+     * default `firstDayOfWeek` of 0, that's the original Sun..Sat mapping,
+     * unchanged); 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 h = CAL_LABEL_H + 7 * (CAL_CELL + CAL_GAP);
+        const { cells, weekCount, firstWeekStart, monthLabels } = this.cachedCalendarGrid;
+        const cellSize = this.calendarCellSize();
+        const w = this.columnXFor(Math.max(1, weekCount));
+        // Derived from `rowYFor(7)` (one past the last of the 7 weekday rows), the
+        // vertical mirror of `w`'s `columnXFor(weekCount)` — so a custom `rowY`
+        // that spaces rows out further than the default formula still gets a
+        // canvas tall enough to paint every row, instead of clipping them.
+        const h = this.rowYFor(7);
         const dpr = window.devicePixelRatio || 1;
         this.canvas.width = w * dpr;
         this.canvas.height = h * dpr;
@@ -347,24 +700,39 @@ export class LyraHeatmap extends LyraElement {
             return;
         ctx.scale(dpr, dpr);
         ctx.clearRect(0, 0, w, h);
-        const sortedValues = cells
-            .map((c) => c.value)
-            .filter((v) => Number.isFinite(v) && v >= 0)
-            .sort((a, b) => a - b);
-        const [scaleLo, scaleHi] = this.scaleEndpoints();
-        const loRgb = resolveRgb(scaleLo, FALLBACK_SCALE_LO);
-        const hiRgb = resolveRgb(scaleHi, FALLBACK_SCALE_HI);
-        const buckets = resolveBucketCount(this.bucketCount);
-        const ramp = Array.from({ length: buckets }, (_, i) => mixRgb(loRgb, hiRgb, i / (buckets - 1)));
+        // Normalize at the allocation boundary as a final guard even though the
+        // public accessor and attribute converter already normalize their inputs.
+        const buckets = normalizeBucketCount(this.bucketCount);
+        const ramp = this.colorRamp(buckets).colors;
         const noDataFill = this.noDataFill();
-        for (const cell of cells) {
-            const x = CAL_PAD_LEFT + cell.week * (CAL_CELL + CAL_GAP);
-            const y = CAL_LABEL_H + cell.weekday * (CAL_CELL + CAL_GAP);
-            ctx.fillStyle =
-                cell.value < 0 || !Number.isFinite(cell.value)
-                    ? noDataFill
-                    : ramp[quartileBucket(cell.value, sortedValues, buckets)];
-            ctx.fillRect(x, y, CAL_CELL, CAL_CELL);
+        // Only consulted when `scale === 'sqrt'` — mirrors `drawMatrix()`'s own
+        // `hi` bound, reusing the already-cached value range instead of
+        // rescanning `sortedValues` for its max.
+        const bounds = this.cachedValueRange;
+        const hi = bounds ? bounds[1] : 1;
+        // Indexed once per draw so every (week, weekday) grid position can be
+        // painted below, not just positions with a matching entry in `cells` — a
+        // day missing from `days` entirely (a gap in a sparse calendar) still
+        // gets a real grid cell (see `calendarCellAt()`'s doc comment for the
+        // same `-1` no-data sentinel used here) instead of being left
+        // transparent.
+        for (let week = 0; week < weekCount; week++) {
+            for (let weekday = 0; weekday < 7; weekday++) {
+                const value = this.cachedCalendarCellsByPos.get(`${week}:${weekday}`)?.value ?? -1;
+                const x = this.columnXFor(week);
+                const y = this.rowYFor(weekday);
+                if (value < 0 || !Number.isFinite(value)) {
+                    ctx.fillStyle = noDataFill;
+                }
+                else if (this.scale === 'sqrt') {
+                    const step = sqrtStep(value, hi, buckets);
+                    ctx.fillStyle = step < 0 ? noDataFill : ramp[step];
+                }
+                else {
+                    ctx.fillStyle = ramp[quartileBucket(value, this.cachedCalendarSortedValues, buckets)];
+                }
+                ctx.fillRect(x, y, cellSize, cellSize);
+            }
         }
         // Annotation ring overlay, stroked after the fill pass so it reads
         // clearly over the data-driven cell color — see drawMatrix()'s twin of
@@ -378,9 +746,9 @@ 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 y = CAL_LABEL_H + match.weekday * (CAL_CELL + CAL_GAP);
-                ctx.strokeRect(x + 0.5, y + 0.5, CAL_CELL - 1, CAL_CELL - 1);
+                const x = this.columnXFor(match.week);
+                const y = this.rowYFor(match.weekday);
+                ctx.strokeRect(x + 0.5, y + 0.5, cellSize - 1, cellSize - 1);
             }
         }
         // Keyboard focus ring, redrawn on top of the fill pass (and any
@@ -390,20 +758,20 @@ 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 y = CAL_LABEL_H + weekday * (CAL_CELL + CAL_GAP);
-                ctx.strokeRect(x + 0.5, y + 0.5, CAL_CELL - 1, CAL_CELL - 1);
+                const x = this.columnXFor(week);
+                const y = this.rowYFor(weekday);
+                ctx.strokeRect(x + 0.5, y + 0.5, cellSize - 1, cellSize - 1);
             }
         }
         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);
+                ctx.fillText(label, 2, this.rowYFor(weekday) + cellSize - 1);
         });
     }
     /**
@@ -441,10 +809,9 @@ export class LyraHeatmap extends LyraElement {
         const bounds = this.cachedValueRange;
         const lo = bounds ? bounds[0] : 0;
         const hi = bounds ? bounds[1] : 1;
-        const [scaleLo, scaleHi] = this.scaleEndpoints();
-        const loRgb = resolveRgb(scaleLo, FALLBACK_SCALE_LO);
-        const hiRgb = resolveRgb(scaleHi, FALLBACK_SCALE_HI);
-        const ramp = Array.from({ length: RAMP_STEPS }, (_, i) => mixRgb(loRgb, hiRgb, i / (RAMP_STEPS - 1)));
+        const rampData = this.colorRamp(RAMP_STEPS);
+        const ramp = rampData.colors;
+        const { loRgb, hiRgb } = rampData;
         const noDataFill = this.noDataFill();
         for (let r = 0; r < rows; r++) {
             for (let c = 0; c < cols; c++) {
@@ -536,12 +903,12 @@ export class LyraHeatmap extends LyraElement {
         return { row, col };
     }
     hitTestCalendar(x, y) {
-        const { weekCount } = buildCalendarGrid(this.days);
+        const { weekCount } = this.cachedCalendarGrid;
         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)
+        const week = this.weekAtX(x, weekCount);
+        const weekday = this.weekdayAtY(y);
+        if (week === null || weekday === null)
             return null;
         return { week, weekday };
     }
@@ -554,7 +921,7 @@ export class LyraHeatmap extends LyraElement {
      * sentinel uses in matrix mode), instead of being unresolvable.
      */
     calendarCellAt(pos) {
-        const { cells, firstWeekStart } = buildCalendarGrid(this.days);
+        const { cells, firstWeekStart } = this.cachedCalendarGrid;
         const match = cells.find((c) => c.week === pos.week && c.weekday === pos.weekday);
         if (match)
             return { date: match.date, value: match.value };
@@ -568,11 +935,12 @@ export class LyraHeatmap extends LyraElement {
      */
     cellRect(pos) {
         if ('week' in pos) {
+            const cellSize = this.calendarCellSize();
             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,
+                x: this.columnXFor(pos.week),
+                y: this.rowYFor(pos.weekday),
+                w: cellSize,
+                h: cellSize,
             };
         }
         const cellSize = this.matrixCellSize(this.colLabels.length);
@@ -630,6 +998,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;
@@ -668,7 +1054,7 @@ export class LyraHeatmap extends LyraElement {
         this.announce(next);
     }
     onCalendarKeyDown(e) {
-        const { weekCount } = buildCalendarGrid(this.days);
+        const { weekCount } = this.cachedCalendarGrid;
         if (weekCount === 0)
             return;
         if (e.key === 'Enter' || e.key === ' ') {
@@ -742,7 +1128,7 @@ __decorate([
 ], LyraHeatmap.prototype, "values", void 0);
 __decorate([
     property({ type: Number, attribute: 'cell-size' })
-], LyraHeatmap.prototype, "cellSize", void 0);
+], LyraHeatmap.prototype, "cellSize", null);
 __decorate([
     property({ attribute: 'value-label' })
 ], LyraHeatmap.prototype, "valueLabel", void 0);
@@ -759,14 +1145,23 @@ __decorate([
     property({ attribute: false })
 ], LyraHeatmap.prototype, "days", void 0);
 __decorate([
-    property({ attribute: 'bucket-count', type: Number })
-], LyraHeatmap.prototype, "bucketCount", void 0);
+    property({ type: Number, attribute: 'first-day-of-week' })
+], LyraHeatmap.prototype, "firstDayOfWeek", void 0);
+__decorate([
+    property({ attribute: 'bucket-count', converter: bucketCountConverter })
+], LyraHeatmap.prototype, "bucketCount", null);
 __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([
+    property({ attribute: false })
+], LyraHeatmap.prototype, "rowY", void 0);
 __decorate([
     query('canvas')
 ], LyraHeatmap.prototype, "canvas", void 0);