@aceshooting/lyra-ui 5.1.0 → 5.2.0

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

@@ -18,6 +18,14 @@ export interface MatrixCellPos {
 export interface CalendarCellPos {
     week: number;
     weekday: number;
+    /**
+     * The real ISO `yyyy-mm-dd` date this grid position falls on, so a `cellText`/`cellColor`/
+     * `cellInteractive` callback can key off the date without reconstructing the grid's own
+     * `firstWeekStart + week * 7 + weekday` arithmetic. Always populated — including for a **gap**
+     * position with no matching entry in `days` at all, which still sits on a real calendar day
+     * (that case simply reports the `-1` "no data" value alongside it).
+     */
+    date: string;
 }
 /**
  * A marker drawn as a stroked ring over a matching cell (matrix mode:
@@ -38,8 +46,14 @@ export interface HeatmapAnnotation {
 export interface HeatmapLegendStop {
     /** Domain value this stop represents; used for the rendered label. */
     value: number;
-    /** Any CSS color — typically whatever the consumer's own `cellColor` returns for `value`. */
-    color: string;
+    /**
+     * Any CSS color — typically whatever the consumer's own `cellColor` returns for `value`.
+     * Omit it (or pass an empty string) for a **caption-only** stop: the entry then renders its
+     * `[part="legend-stop-label"]` alone, with no `[part="legend-swatch"]` element in the DOM at
+     * all, so a leading "0" / trailing "more" caption around a run of colored stops doesn't leave
+     * an empty swatch box in the row.
+     */
+    color?: string;
     /** Optional label override; defaults to the component's own numeric formatting of `value`. */
     label?: string;
 }
@@ -114,6 +128,14 @@ export interface LyraHeatmapEventMap {
  *   being bucketed — as is a grid position with no matching entry in `days`
  *   at all (a gap in a sparse calendar).
  *
+ * `fitToWidth` divides the host's measured width across the grid in either
+ * mode; `maxCellSize`/`minCellSize` bound the result, so a sparse grid in a
+ * wide pane cannot inflate into a few giant blocks and a year calendar in a
+ * narrow one cannot collapse into hairlines. Both are ignored while
+ * `fitToWidth` is unset (an explicit `cellSize` is an exact request), and the
+ * canvas is sized from the *clamped* size — a capped grid leaves the host's
+ * remaining width unfilled rather than stretching to it.
+ *
  * The sequential color ramp's endpoints are read from the
  * `--lr-heatmap-scale-lo`/`-hi` custom properties (declared in
  * `heatmap.styles.ts`) so hosts can retheme it — canvas can't consume
@@ -132,6 +154,12 @@ export interface LyraHeatmapEventMap {
  * specific cells (e.g. to call out an anomaly), each one optionally
  * surfaced in the legend too via `[part="legend-annotation"]`.
  *
+ * In calendar mode every cell position handed to `cellText`, `cellColor` and
+ * `cellInteractive` is a `CalendarCellPos` carrying the resolved ISO
+ * `yyyy-mm-dd` `date` alongside `week`/`weekday` — including for a grid
+ * position with no entry in `days` at all — so a callback can key off the
+ * date without re-deriving the grid's own anchor arithmetic.
+ *
  * `legendStops` swaps the legend's two-endpoint gradient bar for a discrete
  * key of swatches, so a consumer whose `cellColor` callback paints an
  * entirely different domain than the `--lr-heatmap-scale-lo`/`-hi` ramp can
@@ -182,8 +210,9 @@ export interface LyraHeatmapEventMap {
  * @csspart legend-lo - The low legend endpoint (omitted when `legendStops` is supplied).
  * @csspart legend-hi - The high legend endpoint (omitted when `legendStops` is supplied).
  * @csspart legend-stop - One discrete `legendStops` entry — swatch plus label.
- * @csspart legend-swatch - The color swatch of one `legendStops` entry.
+ * @csspart legend-swatch - The color swatch of one `legendStops` entry. Not rendered at all for a caption-only stop (one with no `color`).
  * @csspart legend-stop-label - The text of one `legendStops` entry.
+ * @csspart legend-value-label - The trailing `valueLabel` caption that closes the legend row, in both the gradient and the `legendStops` branch.
  * @csspart legend-annotation - An annotation label.
  * @cssprop [--lr-heatmap-scale-lo=var(--lr-color-brand-quiet)] - Low endpoint of the sequential color ramp.
  * @cssprop [--lr-heatmap-scale-hi=var(--lr-color-brand)] - High endpoint of the sequential color ramp.
@@ -234,6 +263,38 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * only; now applies to calendar mode too.
      */
     fitToWidth: boolean;
+    private _maxCellSize?;
+    /**
+     * Ceiling (CSS px) on the cell size `fitToWidth` derives from the host width, in **both** modes.
+     * Ignored entirely while `fitToWidth` is unset — an explicit `cellSize` is never clamped, since
+     * it is already an exact request.
+     *
+     * Exists because `fitToWidth` divides the whole host width across the grid: a 5-week calendar or
+     * a 3-column matrix in a wide pane produces enormous cells. Capping them keeps the cell a cell.
+     * The canvas is sized *from the clamped cell size*, so a capped grid deliberately leaves the
+     * remaining host width unfilled (the canvas simply ends early) rather than stretching to fill it
+     * — position it with normal CSS on the host if you want it centered or end-aligned.
+     *
+     * Unset (the default) reproduces today's exact fit-to-width behavior. Clamped to at least the
+     * built-in `4`px floor; a non-finite value (or an empty attribute) means unset rather than `0`.
+     * When both clamps are set and `maxCellSize < minCellSize`, the ceiling wins — the same
+     * precedence `finiteRange()` itself applies.
+     */
+    get maxCellSize(): number | undefined;
+    set maxCellSize(value: number | undefined);
+    private _minCellSize?;
+    /**
+     * Floor (CSS px) under the cell size `fitToWidth` derives from the host width, in **both** modes
+     * — the mirror of `maxCellSize`, and likewise ignored while `fitToWidth` is unset. Raises the
+     * built-in `FIT_MIN_CELL` (4px) floor so a year-long calendar in a narrow pane keeps legible,
+     * hit-testable cells and overflows its host instead of collapsing to hairlines.
+     *
+     * Can only raise that floor, never lower it: a value below `4` normalizes to `4`. Unset (the
+     * default) reproduces today's exact fit-to-width behavior, and a non-finite value (or an empty
+     * attribute) means unset.
+     */
+    get minCellSize(): number | undefined;
+    set minCellSize(value: number | undefined);
     mode: 'matrix' | 'calendar';
     days: CalendarDay[];
     private _firstDayOfWeek;
@@ -264,6 +325,11 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * locale-aware numeric formatting of `value`, so a stop only needs an explicit `label` when
      * the number isn't the right caption ("none", "≥ 90%").
      *
+     * A stop's `color` is optional: omit it (or pass `''`) for a **caption-only** entry, which
+     * renders its label with no `[part="legend-swatch"]` element in the DOM at all — the shape a
+     * "less ▢▢▢▢ more" style key needs for its two end captions, without an empty swatch box
+     * sitting at either end of the row.
+     *
      * Exists for the consumer who supplies `cellColor`: because that callback overrides a cell's
      * color entirely, the built-in two-endpoint bar can describe a ramp the grid no longer uses.
      * Supplying the same colors here keeps the legend honest without hiding `[part="legend"]` and
@@ -295,18 +361,22 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      */
     accessibleCells: boolean;
     /** 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
+     *  (`MatrixCellPos` in matrix mode, `CalendarCellPos` — which carries the resolved ISO
+     *  `yyyy-mm-dd` `date`, gap positions included — 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;
     /** Opts individual cells out of the interaction model — receives the cell position and its
      *  value, return `false` to make that cell present-but-non-interactive (no hover tooltip,
      *  click, or keyboard roving-focus stop), without losing the layout/color-ramp machinery. Lets
      *  a consumer omit a future/out-of-range date from interaction, or mark a zero-value cell as
-     *  non-interactive, without ~300+ meaningless keyboard tab stops on a dense grid. Unset (the
-     *  default) keeps every cell interactive, unchanged from before this property existed. */
+     *  non-interactive, without ~300+ meaningless keyboard tab stops on a dense grid. In calendar
+     *  mode the position carries its resolved ISO `date`, so "everything after today" is a direct
+     *  string comparison. Unset (the default) keeps every cell interactive, unchanged from before
+     *  this property existed. */
     cellInteractive?: (pos: MatrixCellPos | CalendarCellPos, value: number) => boolean;
     /** Overrides a cell's computed ramp/no-data color entirely for an exact value -- receives the
-     *  cell position (`MatrixCellPos` in matrix mode, `CalendarCellPos` in calendar mode) and its
+     *  cell position (`MatrixCellPos` in matrix mode, `CalendarCellPos` — carrying the resolved ISO
+     *  `date` — in calendar mode) and its
      *  value, return a CSS color string to force that cell to it, or `undefined` to fall back to the
      *  normal `colorSteps`/ramp math unchanged. Lets a consumer designate a value as categorically
      *  outside the ramp (e.g. a real zero-count day rendered as a neutral hairline, distinct from
@@ -387,6 +457,17 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
     private cachedCalendarGrid;
     private cachedCalendarSortedValues;
     private cachedCalendarCellsByPos;
+    /**
+     * Every grid position's ISO date, indexed by `week * 7 + weekday`, rebuilt alongside
+     * `cachedCalendarCellsByPos` whenever the grid itself is. Populating `CalendarCellPos.date` from
+     * a flat array keeps that field an O(1) string read at every call site — crucially inside
+     * `drawCalendar()`'s inner loop, where computing it per cell would be a `new Date()` plus a
+     * `toISOString()` for all ~365 positions of a year grid on *every* repaint (hover, resize, theme
+     * change). Built once per grid change instead, which is the same order of work
+     * `buildCalendarGrid()` already does on that same path. Covers gap positions too, so a day
+     * missing from `days` still resolves to its real date.
+     */
+    private cachedCalendarDateByPos;
     private cachedRamp;
     /** Set after a complete canvas pass. Focus movement can then repaint only the old/new cell
      * rectangles instead of clearing and repainting an entire dense heatmap. */
@@ -476,6 +557,14 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * geometry as what's actually painted.
      */
     private calendarCellSize;
+    /**
+     * Applies the optional `minCellSize`/`maxCellSize` clamps to a width-derived cell size. Only
+     * ever reached from the `fitToWidth` branch of `calendarCellSize()`/`matrixCellSize()` — an
+     * explicitly-set `cellSize` is an exact request and is never clamped. With both clamps unset
+     * this is exactly the `Math.max(FIT_MIN_CELL, …)` floor both call sites applied before they
+     * existed, so an untouched consumer's geometry is unchanged.
+     */
+    private clampFitCellSize;
     /**
      * Calendar-mode week-column x-origin (canvas-local CSS px) — `columnX(week)`
      * when set, otherwise the original evenly-spaced formula (now derived from
@@ -577,6 +666,17 @@ export declare class LyraHeatmap extends LyraElement<LyraHeatmapEventMap> {
      * sentinel uses in matrix mode), instead of being unresolvable.
      */
     private calendarCellAt;
+    /**
+     * The ISO `yyyy-mm-dd` date of a (week, weekday) grid position — an O(1) read out of
+     * `cachedCalendarDateByPos`, falling back to the grid-geometry arithmetic for a position outside
+     * the cached grid (a cursor left over from a shrinking `days`, say). Grid geometry guarantees
+     * this agrees with the `date` of a matching `days` entry: `week * 7 + weekday` *is* the day
+     * offset from `firstWeekStart` (see `buildCalendarGrid()`).
+     */
+    private calendarDateAt;
+    /** Builds the full calendar-mode cursor for a grid position, `date` included. Every calendar-mode
+     *  `CalendarCellPos` in this component goes through here, so no call site can forget the date. */
+    private calendarPos;
     /**
      * Pixel rect (canvas-local CSS px) of a cell — shared by `tooltipStyle()`
      * so the tooltip's position always agrees with the same geometry

package/dist/components/data/heatmap/heatmap.class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heatmap.class.d.ts","sourceRoot":"","sources":["../../../../src/components/data/heatmap/heatmap.class.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"heatmap.class.d.ts","sourceRoot":"","sources":["../../../../src/components/data/heatmap/heatmap.class.ts"],"names":[],"mappings":"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"}

package/dist/components/data/heatmap/heatmap.class.js

@@ -33,6 +33,12 @@ const CAL_GAP = 2;
  *  `cellSize` accessor uses in matrix mode when left unset. */
 const DEFAULT_MATRIX_CELL_SIZE = 22;
 const DEFAULT_BUCKET_COUNT = 5;
+/**
+ * Hard lower bound on a `fitToWidth`-derived cell size, in both modes. A grid squeezed below this
+ * stops being a readable heatmap and starts producing degenerate geometry (sub-pixel fill rects,
+ * a hit-test rounding to the wrong cell), so `minCellSize` can raise this floor but never lower it.
+ */
+const FIT_MIN_CELL = 4;
 /**
  * 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
@@ -51,6 +57,10 @@ const FALLBACK_SELECTED_COLOR = '#1a7f37';
 // onMatrixKeyDown()/onCalendarKeyDown().
 const ARROW_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']);
 const MS_PER_DAY = 86_400_000;
+/** The ISO `yyyy-mm-dd` date `dayOffset` days after a calendar grid's anchor week start. */
+function isoDateAtOffset(firstWeekStart, dayOffset) {
+    return new Date(firstWeekStart.getTime() + dayOffset * MS_PER_DAY).toISOString().slice(0, 10);
+}
 const HEX_RE = /^([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
 const RGB_RE = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)/i;
 /**
@@ -103,6 +113,35 @@ function warnInvalidColor(color) {
 export function normalizeBucketCount(bucketCount) {
     return finiteInteger(bucketCount, DEFAULT_BUCKET_COUNT, 2, MAX_BUCKET_COUNT);
 }
+/**
+ * Attribute converter for the optional `max-cell-size`/`min-cell-size` clamps. Unlike Lit's default
+ * `Number` converter — which turns a missing-but-present `foo=""` into `0` — anything that isn't a
+ * finite number (absent, empty, whitespace, `"auto"`, garbage) maps to `undefined`, i.e. genuinely
+ * unset. `max-cell-size=""` silently pinning every cell to the 4px floor would be a trap, and these
+ * two are the only properties on this component where "no value" is a meaningful state.
+ */
+const optionalCellSizeConverter = {
+    fromAttribute(value) {
+        if (value === null || value.trim() === '')
+            return undefined;
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    },
+    toAttribute(value) {
+        return value == null ? null : String(value);
+    },
+};
+/**
+ * Normalizes a `maxCellSize`/`minCellSize` assignment: a non-finite (or absent) value means
+ * genuinely unset, and anything else is clamped to the `FIT_MIN_CELL` floor via the same
+ * `finiteRange()` helper `cellSize`'s own setter uses, so the two clamps and the size they clamp
+ * agree on what a legal cell size is.
+ */
+function normalizeCellSizeClamp(value) {
+    if (value == null || !Number.isFinite(value))
+        return undefined;
+    return finiteRange(value, FIT_MIN_CELL, FIT_MIN_CELL);
+}
 const bucketCountConverter = {
     fromAttribute(value) {
         return value === null ? DEFAULT_BUCKET_COUNT : normalizeBucketCount(Number(value));
@@ -176,6 +215,14 @@ function mixRgb(from, to, t) {
  *   being bucketed — as is a grid position with no matching entry in `days`
  *   at all (a gap in a sparse calendar).
  *
+ * `fitToWidth` divides the host's measured width across the grid in either
+ * mode; `maxCellSize`/`minCellSize` bound the result, so a sparse grid in a
+ * wide pane cannot inflate into a few giant blocks and a year calendar in a
+ * narrow one cannot collapse into hairlines. Both are ignored while
+ * `fitToWidth` is unset (an explicit `cellSize` is an exact request), and the
+ * canvas is sized from the *clamped* size — a capped grid leaves the host's
+ * remaining width unfilled rather than stretching to it.
+ *
  * The sequential color ramp's endpoints are read from the
  * `--lr-heatmap-scale-lo`/`-hi` custom properties (declared in
  * `heatmap.styles.ts`) so hosts can retheme it — canvas can't consume
@@ -194,6 +241,12 @@ function mixRgb(from, to, t) {
  * specific cells (e.g. to call out an anomaly), each one optionally
  * surfaced in the legend too via `[part="legend-annotation"]`.
  *
+ * In calendar mode every cell position handed to `cellText`, `cellColor` and
+ * `cellInteractive` is a `CalendarCellPos` carrying the resolved ISO
+ * `yyyy-mm-dd` `date` alongside `week`/`weekday` — including for a grid
+ * position with no entry in `days` at all — so a callback can key off the
+ * date without re-deriving the grid's own anchor arithmetic.
+ *
  * `legendStops` swaps the legend's two-endpoint gradient bar for a discrete
  * key of swatches, so a consumer whose `cellColor` callback paints an
  * entirely different domain than the `--lr-heatmap-scale-lo`/`-hi` ramp can
@@ -244,8 +297,9 @@ function mixRgb(from, to, t) {
  * @csspart legend-lo - The low legend endpoint (omitted when `legendStops` is supplied).
  * @csspart legend-hi - The high legend endpoint (omitted when `legendStops` is supplied).
  * @csspart legend-stop - One discrete `legendStops` entry — swatch plus label.
- * @csspart legend-swatch - The color swatch of one `legendStops` entry.
+ * @csspart legend-swatch - The color swatch of one `legendStops` entry. Not rendered at all for a caption-only stop (one with no `color`).
  * @csspart legend-stop-label - The text of one `legendStops` entry.
+ * @csspart legend-value-label - The trailing `valueLabel` caption that closes the legend row, in both the gradient and the `legendStops` branch.
  * @csspart legend-annotation - An annotation label.
  * @cssprop [--lr-heatmap-scale-lo=var(--lr-color-brand-quiet)] - Low endpoint of the sequential color ramp.
  * @cssprop [--lr-heatmap-scale-hi=var(--lr-color-brand)] - High endpoint of the sequential color ramp.
@@ -325,6 +379,17 @@ export class LyraHeatmap extends LyraElement {
         this.cachedCalendarGrid = buildCalendarGrid(this.days);
         this.cachedCalendarSortedValues = [];
         this.cachedCalendarCellsByPos = new Map();
+        /**
+         * Every grid position's ISO date, indexed by `week * 7 + weekday`, rebuilt alongside
+         * `cachedCalendarCellsByPos` whenever the grid itself is. Populating `CalendarCellPos.date` from
+         * a flat array keeps that field an O(1) string read at every call site — crucially inside
+         * `drawCalendar()`'s inner loop, where computing it per cell would be a `new Date()` plus a
+         * `toISOString()` for all ~365 positions of a year grid on *every* repaint (hover, resize, theme
+         * change). Built once per grid change instead, which is the same order of work
+         * `buildCalendarGrid()` already does on that same path. Covers gap positions too, so a day
+         * missing from `days` still resolves to its real date.
+         */
+        this.cachedCalendarDateByPos = [];
         this.cachedRamp = null;
         /** Set after a complete canvas pass. Focus movement can then repaint only the old/new cell
          * rectangles instead of clearing and repainting an entire dense heatmap. */
@@ -460,6 +525,48 @@ export class LyraHeatmap extends LyraElement {
         this._cellSize = finiteRange(value, this.mode === 'calendar' ? CAL_CELL : DEFAULT_MATRIX_CELL_SIZE, 1);
         this.requestUpdate('cellSize', oldValue);
     }
+    /**
+     * Ceiling (CSS px) on the cell size `fitToWidth` derives from the host width, in **both** modes.
+     * Ignored entirely while `fitToWidth` is unset — an explicit `cellSize` is never clamped, since
+     * it is already an exact request.
+     *
+     * Exists because `fitToWidth` divides the whole host width across the grid: a 5-week calendar or
+     * a 3-column matrix in a wide pane produces enormous cells. Capping them keeps the cell a cell.
+     * The canvas is sized *from the clamped cell size*, so a capped grid deliberately leaves the
+     * remaining host width unfilled (the canvas simply ends early) rather than stretching to fill it
+     * — position it with normal CSS on the host if you want it centered or end-aligned.
+     *
+     * Unset (the default) reproduces today's exact fit-to-width behavior. Clamped to at least the
+     * built-in `4`px floor; a non-finite value (or an empty attribute) means unset rather than `0`.
+     * When both clamps are set and `maxCellSize < minCellSize`, the ceiling wins — the same
+     * precedence `finiteRange()` itself applies.
+     */
+    get maxCellSize() {
+        return this._maxCellSize;
+    }
+    set maxCellSize(value) {
+        const oldValue = this._maxCellSize;
+        this._maxCellSize = normalizeCellSizeClamp(value);
+        this.requestUpdate('maxCellSize', oldValue);
+    }
+    /**
+     * Floor (CSS px) under the cell size `fitToWidth` derives from the host width, in **both** modes
+     * — the mirror of `maxCellSize`, and likewise ignored while `fitToWidth` is unset. Raises the
+     * built-in `FIT_MIN_CELL` (4px) floor so a year-long calendar in a narrow pane keeps legible,
+     * hit-testable cells and overflows its host instead of collapsing to hairlines.
+     *
+     * Can only raise that floor, never lower it: a value below `4` normalizes to `4`. Unset (the
+     * default) reproduces today's exact fit-to-width behavior, and a non-finite value (or an empty
+     * attribute) means unset.
+     */
+    get minCellSize() {
+        return this._minCellSize;
+    }
+    set minCellSize(value) {
+        const oldValue = this._minCellSize;
+        this._minCellSize = normalizeCellSizeClamp(value);
+        this.requestUpdate('minCellSize', oldValue);
+    }
     /**
      * Calendar mode only (no-op in matrix mode): anchors the calendar grid at
      * a different weekday instead of always Sunday — `0`-`6`, same numbering
@@ -575,6 +682,8 @@ export class LyraHeatmap extends LyraElement {
                 .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]));
+            const { firstWeekStart, weekCount } = this.cachedCalendarGrid;
+            this.cachedCalendarDateByPos = Array.from({ length: weekCount * 7 }, (_, index) => isoDateAtOffset(firstWeekStart, index));
         }
         if (!this.hasUpdated) {
             this.authorSuppliedRole = this.hasAttribute('role');
@@ -649,7 +758,7 @@ export class LyraHeatmap extends LyraElement {
             if (!match)
                 return '';
             return this.localize('heatmapSelectedCellLabel', undefined, {
-                cell: this.calendarCellText({ week: match.week, weekday: match.weekday }),
+                cell: this.calendarCellText({ week: match.week, weekday: match.weekday, date: match.date }),
             });
         }
         const { row, col } = this.selectedCell;
@@ -684,6 +793,8 @@ export class LyraHeatmap extends LyraElement {
             'rowLabels',
             'colLabels',
             'cellSize',
+            'maxCellSize',
+            'minCellSize',
             'valueLabel',
             'scale',
             'fitToWidth',
@@ -834,10 +945,20 @@ export class LyraHeatmap extends LyraElement {
             // 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.clampFitCellSize((hostWidth - CAL_PAD_LEFT) / weekCount - CAL_GAP);
         }
         return this.cellSize;
     }
+    /**
+     * Applies the optional `minCellSize`/`maxCellSize` clamps to a width-derived cell size. Only
+     * ever reached from the `fitToWidth` branch of `calendarCellSize()`/`matrixCellSize()` — an
+     * explicitly-set `cellSize` is an exact request and is never clamped. With both clamps unset
+     * this is exactly the `Math.max(FIT_MIN_CELL, …)` floor both call sites applied before they
+     * existed, so an untouched consumer's geometry is unchanged.
+     */
+    clampFitCellSize(size) {
+        return finiteRange(size, FIT_MIN_CELL, Math.max(FIT_MIN_CELL, this.minCellSize ?? FIT_MIN_CELL), this.maxCellSize ?? Number.POSITIVE_INFINITY);
+    }
     /**
      * Calendar-mode week-column x-origin (canvas-local CSS px) — `columnX(week)`
      * when set, otherwise the original evenly-spaced formula (now derived from
@@ -980,7 +1101,11 @@ export class LyraHeatmap extends LyraElement {
                 const value = this.cachedCalendarCellsByPos.get(`${week}:${weekday}`)?.value ?? -1;
                 const x = this.columnXFor(week);
                 const y = this.rowYFor(weekday);
-                const override = this.cellColor?.({ week, weekday }, value);
+                // `calendarPos()` is an array read plus one object literal, and the optional-call syntax
+                // short-circuits it entirely when `cellColor` is unset — deliberately *not*
+                // `calendarCellAt()`, whose miss path would allocate a Date and an ISO string for every
+                // gap position on every repaint.
+                const override = this.cellColor?.(this.calendarPos(week, weekday), value);
                 if (override != null) {
                     ctx.fillStyle = this.resolveCanvasColor(override, cs);
                 }
@@ -1066,7 +1191,7 @@ export class LyraHeatmap extends LyraElement {
     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.clampFitCellSize((hostWidth - PAD_LEFT) / cols);
         }
         return this.cellSize;
     }
@@ -1134,7 +1259,7 @@ export class LyraHeatmap extends LyraElement {
         const bounds = this.cachedValueRange;
         const lo = bounds ? bounds[0] : 0;
         const hi = bounds ? bounds[1] : 1;
-        const override = this.cellColor?.({ week, weekday }, value);
+        const override = this.cellColor?.(this.calendarPos(week, weekday), value);
         if (override != null)
             ctx.fillStyle = this.resolveCanvasColor(override, cs);
         else if (value < 0 || !Number.isFinite(value))
@@ -1152,7 +1277,7 @@ export class LyraHeatmap extends LyraElement {
         ctx.fillRect(this.columnXFor(week), this.rowYFor(weekday), cellSize, cellSize);
     }
     paintCalendarFocusOverlays(ctx, week, weekday, cellSize, cs) {
-        const date = this.calendarCellAt({ week, weekday }).date;
+        const date = this.calendarDateAt(week, weekday);
         const x = this.columnXFor(week);
         const y = this.rowYFor(weekday);
         const matches = (candidate) => candidate?.date === date;
@@ -1378,8 +1503,9 @@ export class LyraHeatmap extends LyraElement {
     firstInteractiveCalendarCell(weekCount) {
         for (let week = 0; week < weekCount; week++) {
             for (let weekday = 0; weekday < 7; weekday++) {
-                if (this.isCellInteractive({ week, weekday }))
-                    return { week, weekday };
+                const pos = this.calendarPos(week, weekday);
+                if (this.isCellInteractive(pos))
+                    return pos;
             }
         }
         return null;
@@ -1392,11 +1518,12 @@ export class LyraHeatmap extends LyraElement {
             const nw = Math.min(weekCount - 1, Math.max(0, w + dWeek));
             const nd = Math.min(6, Math.max(0, d + dWeekday));
             if (nw === w && nd === d)
-                return { week, weekday };
+                return this.calendarPos(week, weekday);
             w = nw;
             d = nd;
-            if (this.isCellInteractive({ week: w, weekday: d }))
-                return { week: w, weekday: d };
+            const pos = this.calendarPos(w, d);
+            if (this.isCellInteractive(pos))
+                return pos;
         }
     }
     hitTestCalendar(x, y) {
@@ -1407,7 +1534,7 @@ export class LyraHeatmap extends LyraElement {
         const weekday = this.weekdayAtY(y);
         if (week === null || weekday === null)
             return null;
-        const pos = { week, weekday };
+        const pos = this.calendarPos(week, weekday);
         return this.isCellInteractive(pos) ? pos : null;
     }
     /**
@@ -1419,12 +1546,27 @@ export class LyraHeatmap extends LyraElement {
      * sentinel uses in matrix mode), instead of being unresolvable.
      */
     calendarCellAt(pos) {
-        const { firstWeekStart } = this.cachedCalendarGrid;
         const match = this.cachedCalendarCellsByPos.get(`${pos.week}:${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 };
+        return { date: this.calendarDateAt(pos.week, pos.weekday), value: -1 };
+    }
+    /**
+     * The ISO `yyyy-mm-dd` date of a (week, weekday) grid position — an O(1) read out of
+     * `cachedCalendarDateByPos`, falling back to the grid-geometry arithmetic for a position outside
+     * the cached grid (a cursor left over from a shrinking `days`, say). Grid geometry guarantees
+     * this agrees with the `date` of a matching `days` entry: `week * 7 + weekday` *is* the day
+     * offset from `firstWeekStart` (see `buildCalendarGrid()`).
+     */
+    calendarDateAt(week, weekday) {
+        const index = week * 7 + weekday;
+        return (this.cachedCalendarDateByPos[index] ??
+            isoDateAtOffset(this.cachedCalendarGrid.firstWeekStart, index));
+    }
+    /** Builds the full calendar-mode cursor for a grid position, `date` included. Every calendar-mode
+     *  `CalendarCellPos` in this component goes through here, so no call site can forget the date. */
+    calendarPos(week, weekday) {
+        return { week, weekday, date: this.calendarDateAt(week, weekday) };
     }
     /**
      * Pixel rect (canvas-local CSS px) of a cell — shared by `tooltipStyle()`
@@ -1647,7 +1789,7 @@ export class LyraHeatmap extends LyraElement {
             const positions = [];
             for (let week = 0; week < weekCount; week++) {
                 for (let weekday = 0; weekday < 7; weekday++) {
-                    const pos = { week, weekday };
+                    const pos = this.calendarPos(week, weekday);
                     if (this.isCellInteractive(pos))
                         positions.push(pos);
                 }
@@ -1722,7 +1864,14 @@ export class LyraHeatmap extends LyraElement {
         if (stops && stops.length > 0) {
             return html `${stops.map((stop) => html `
           <span part="legend-stop">
-            <span part="legend-swatch" style=${styleMap({ background: stop.color })}></span>
+            ${
+            // A template guard, deliberately not just `styleMap({ background: stop.color })` with
+            // an optional `color`: styleMap skips a nullish value silently, which is a legal
+            // no-op that would still leave the swatch's own 0.6rem box sitting in the row. A
+            // caption-only stop has to omit the element itself.
+            stop.color
+                ? html `<span part="legend-swatch" style=${styleMap({ background: stop.color })}></span>`
+                : nothing}
             <span part="legend-stop-label">${stop.label ?? this.formatNumericValue(stop.value)}</span>
           </span>
         `)}`;
@@ -1759,7 +1908,7 @@ export class LyraHeatmap extends LyraElement {
         </div>
         <div part="live-region" class="sr-only" role="status" aria-live="polite">${this.liveText}</div>
         <div part="legend">${this.renderLegendScale(range)}
-          <span>${this.localizedValueLabel()}</span>
+          <span part="legend-value-label">${this.localizedValueLabel()}</span>
           ${labeledAnnotations.map((a) => html `<span part="legend-annotation"><span class="ring-swatch"></span>${a.label}</span>`)}
         </div>
       </div>
@@ -1787,6 +1936,12 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: 'fit-to-width' })
 ], LyraHeatmap.prototype, "fitToWidth", void 0);
+__decorate([
+    property({ type: Number, attribute: 'max-cell-size', converter: optionalCellSizeConverter })
+], LyraHeatmap.prototype, "maxCellSize", null);
+__decorate([
+    property({ type: Number, attribute: 'min-cell-size', converter: optionalCellSizeConverter })
+], LyraHeatmap.prototype, "minCellSize", null);
 __decorate([
     property()
 ], LyraHeatmap.prototype, "mode", void 0);