@aceshooting/lyra-ui 5.0.0 → 5.2.0

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
@@ -193,6 +240,20 @@ function mixRgb(from, to, t) {
  * `lr-cell-click`. `annotations` additionally strokes a ring around
  * specific cells (e.g. to call out an anomaly), each one optionally
  * surfaced in the legend too via `[part="legend-annotation"]`.
+ *
+ * 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
+ * keep the built-in legend (labels, number formatting, annotation entries)
+ * instead of hiding `[part="legend"]` and hand-rolling swatches. It is
+ * presentation only — it never feeds back into the cell colors.
+ *
  * Set `accessibleCells` when each cell needs a persistent DOM control for
  * assistive technology. The opt-in overlay uses native buttons with a
  * roving tabindex, localized `aria-label`, and explicit `aria-pressed` state
@@ -233,8 +294,12 @@ function mixRgb(from, to, t) {
  * @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-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. 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.
@@ -245,6 +310,7 @@ function mixRgb(from, to, t) {
  * @cssprop [--lr-heatmap-focus-ring-color=var(--lr-focus-ring-color)] - Focus ring around a focused cell.
  * @cssprop [--lr-heatmap-annotation-color=var(--lr-color-danger)] - Border color for an annotated cell.
  * @cssprop [--lr-heatmap-selected-color=var(--lr-color-success)] - Border color for the selected cell.
+ * @cssprop [--lr-heatmap-color-steps-gradient=linear-gradient(to right, var(--lr-heatmap-scale-lo), var(--lr-heatmap-scale-hi))] - Gradient painted on the continuous legend bar. Set on the host by the component itself while `colorSteps` is supplied, and removed again when it is not; the fallback is the two-endpoint scale ramp.
  */
 export class LyraHeatmap extends LyraElement {
     constructor() {
@@ -313,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. */
@@ -448,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
@@ -563,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');
@@ -637,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;
@@ -672,6 +793,8 @@ export class LyraHeatmap extends LyraElement {
             'rowLabels',
             'colLabels',
             'cellSize',
+            'maxCellSize',
+            'minCellSize',
             'valueLabel',
             'scale',
             'fitToWidth',
@@ -688,6 +811,7 @@ export class LyraHeatmap extends LyraElement {
             'colorSteps',
             'cellColor',
             'selectedCell',
+            'legendStops',
         ].some((name) => changed.has(name))) {
             const focusOnly = changed.has('focusedCell') && [...changed.keys()].every((key) => key === 'focusedCell' || key === 'liveText');
             if (focusOnly && this.repaintFocusRing(changed.get('focusedCell')))
@@ -821,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
@@ -967,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);
                 }
@@ -1053,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;
     }
@@ -1121,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))
@@ -1139,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;
@@ -1365,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;
@@ -1379,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) {
@@ -1394,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;
     }
     /**
@@ -1406,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()`
@@ -1634,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);
                 }
@@ -1699,6 +1854,36 @@ export class LyraHeatmap extends LyraElement {
       </div>
     `;
     }
+    /**
+     * The legend's color description: the discrete `legendStops` key when one is supplied, the
+     * original `--lr-heatmap-scale-lo`/`-hi` gradient bar and its endpoint labels otherwise. An
+     * unset (or empty) `legendStops` therefore reproduces the pre-`legendStops` markup exactly.
+     */
+    renderLegendScale(range) {
+        const stops = this.legendStops;
+        if (stops && stops.length > 0) {
+            return html `${stops.map((stop) => html `
+          <span part="legend-stop">
+            ${
+            // 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>
+        `)}`;
+        }
+        // The indentation here, and the `<div part="legend">`-hugging interpolation in render(),
+        // are deliberate: together they reproduce this branch's markup — whitespace included —
+        // exactly as it was emitted inline before `legendStops` introduced the branch.
+        return html `
+          <span part="legend-lo">${range ? this.formatNumericValue(range[0]) : ''}</span>
+          <span class="bar"></span>
+          <span part="legend-hi">${range ? this.formatNumericValue(range[1]) : ''}</span>`;
+    }
     render() {
         const range = this.cachedValueRange;
         const labeledAnnotations = this.annotations.filter((a) => a.label);
@@ -1722,11 +1907,8 @@ export class LyraHeatmap extends LyraElement {
           ${this.hoverCell ? this.resolveCellText(this.hoverCell) : ''}
         </div>
         <div part="live-region" class="sr-only" role="status" aria-live="polite">${this.liveText}</div>
-        <div part="legend">
-          <span part="legend-lo">${range ? this.formatNumericValue(range[0]) : ''}</span>
-          <span class="bar"></span>
-          <span part="legend-hi">${range ? this.formatNumericValue(range[1]) : ''}</span>
-          <span>${this.localizedValueLabel()}</span>
+        <div part="legend">${this.renderLegendScale(range)}
+          <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>
@@ -1754,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);
@@ -1769,6 +1957,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], LyraHeatmap.prototype, "annotations", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraHeatmap.prototype, "legendStops", void 0);
 __decorate([
     property({ attribute: false })
 ], LyraHeatmap.prototype, "selectedCell", void 0);