@aceshooting/lyra-ui 1.2.0 → 2.1.0

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

@@ -1,6 +1,13 @@
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { type CalendarDay } from './calendar-grid.js';
+/**
+ * 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 declare const MAX_BUCKET_COUNT = 256;
 /** A cell cursor in matrix mode. */
 export interface MatrixCellPos {
     row: number;
@@ -30,6 +37,13 @@ export interface HeatmapAnnotation {
  * string to `0` via `Number.parseInt(..., 16)` returning `NaN`).
  */
 export declare function hexToRgb(hex: string): [number, number, number] | null;
+/**
+ * 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()`.
+ */
+export declare function normalizeBucketCount(bucketCount: number): number;
 /**
  * Resolves any syntactically valid CSS `<color>` — hex, `rgb()`, `hsl()`,
  * `oklch()`, a named color, etc. — to an `[r, g, b]` triple.
@@ -54,12 +68,16 @@ export declare function mixColor(fromColor: string, toColor: string, t: number):
  * - `"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
@@ -79,45 +97,150 @@ export declare function mixColor(fromColor: string, toColor: string, t: number):
  * specific cells (e.g. to call out an anomaly), each one optionally
  * surfaced in the legend too via `[part="legend-annotation"]`.
  *
+ * `columnX` (calendar mode only) overrides the x-origin computed for each
+ * week column — drawing, hit-testing, the focus ring, and month-label
+ * positioning all consult it consistently, so a consumer can pixel-align a
+ * calendar's week columns with a sibling chart's coordinate system. Unset
+ * (the default) keeps the original evenly-spaced formula. `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 declare class LyraHeatmap extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     rowLabels: string[];
     colLabels: string[];
     values: number[][];
-    cellSize: number;
+    private _cellSize?;
+    /**
+     * 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(): number;
+    set cellSize(value: number);
     valueLabel: string;
+    /**
+     * `"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.
+     */
     scale: 'linear' | 'sqrt';
     /**
      * 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.
      */
     fitToWidth: boolean;
     mode: 'matrix' | 'calendar';
     days: CalendarDay[];
-    bucketCount: number;
+    /**
+     * 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.
+     */
+    firstDayOfWeek: number;
+    private _bucketCount;
+    get bucketCount(): number;
+    set bucketCount(value: number);
     /** Cells to ring-highlight — `row`/`col` in matrix mode, `date` in calendar mode. See `HeatmapAnnotation`. */
     annotations: HeatmapAnnotation[];
     /** Formats the per-cell tooltip and keyboard live-region text — receives the cell position
      *  (`MatrixCellPos` in matrix mode, `CalendarCellPos` in calendar mode) and its value. Falls back to
      *  the built-in English "Row X, Col Y: value" / "Mon DD: value" template when unset. */
     cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string;
+    /**
+     * Calendar mode only: overrides the x-origin (canvas-local CSS px) of week
+     * column `index` (0-based, same indexing as `CalendarCellPos.week`).
+     * Consulted consistently by every calendar-mode geometry call site —
+     * drawing, hit-testing, the keyboard focus ring, and month-label
+     * positioning — via the private `columnXFor()` helper, so painted
+     * geometry and pointer hit-testing never disagree. Lets a consumer
+     * pixel-align a calendar's week columns with a sibling chart's bars by
+     * supplying that chart the same coordinate function. Unset (the default)
+     * keeps today's evenly-spaced `CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP)`
+     * formula unchanged. Ignored in matrix mode.
+     */
+    columnX?: (index: number) => number;
+    /**
+     * Calendar mode only: overrides the y-origin (canvas-local CSS px) of
+     * weekday row `weekday` (0-based, same indexing as
+     * `CalendarCellPos.weekday`). The vertical analogue of `columnX` — consulted
+     * consistently by every calendar-mode geometry call site that computes a
+     * cell's y-coordinate from its weekday — drawing, hit-testing, and the
+     * keyboard focus ring — via the private `rowYFor()` helper (mirroring
+     * `columnXFor()`'s exact dispatch-with-computed-fallback shape). Also
+     * consulted at `weekday = 7` (one past the last row) to size the canvas's
+     * height, mirroring how `columnX` is consulted at `week = weekCount` to
+     * size its width — so a function that spaces rows out further than the
+     * default formula still gets a canvas tall enough to paint every row.
+     * Unset (the default) keeps today's evenly-spaced `CAL_LABEL_H + weekday *
+     * (cellSize + CAL_GAP)` formula unchanged. Ignored in matrix mode.
+     */
+    rowY?: (weekday: number) => number;
     private canvas?;
     private resizeObserver?;
+    private drawRafId?;
     private dprQuery?;
+    private colorSchemeQuery?;
+    private themeObserver?;
+    private themeRefreshQueued;
     /** The current value range, refreshed once per update cycle by `willUpdate()`. See `computeValueRange()`. */
     private cachedValueRange;
+    /**
+     * 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.
+     */
+    private cachedCalendarGrid;
+    private cachedCalendarSortedValues;
+    private cachedCalendarCellsByPos;
+    private cachedRamp;
     /** The cell currently under the pointer (`null` when not hovering one) — drives `[part="tooltip"]`. */
     private hoverCell;
     /** The roving keyboard-focus cell cursor, moved by arrow keys — drives the
@@ -125,10 +248,26 @@ export declare class LyraHeatmap extends LyraElement {
     private focusedCell;
     /** Text of the visually-hidden `aria-live="polite"` status announcement, refreshed on every focus move. */
     private liveText;
+    /**
+     * Whether `role`/`aria-label` were present on the host *before* this
+     * element's own code ever wrote to them — snapshotted once, in the very
+     * first `willUpdate()` (guarded by `hasUpdated`, which Lit only flips to
+     * `true` after that first update commits). Re-checking `hasAttribute()` on
+     * every update instead would self-poison: once this element writes its own
+     * default `aria-label` on the first render, `hasAttribute('aria-label')`
+     * is permanently `true` afterwards, which would wrongly look like an
+     * author-supplied value and freeze the label instead of refreshing it as
+     * `values`/`days` change on later updates.
+     */
+    private authorSuppliedRole;
+    private authorSuppliedAriaLabel;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private watchDpr;
     private onDprChange;
+    private onColorSchemeChange;
+    private queueThemeRefresh;
+    private watchTheme;
     protected willUpdate(changed: PropertyValues): void;
     /**
      * The real (non-no-data) value range across `values` (or `days` in
@@ -140,7 +279,9 @@ export declare class LyraHeatmap extends LyraElement {
      * suffices instead of one per consumer.
      */
     private computeValueRange;
-    protected updated(): void;
+    protected updated(changed: PropertyValues): void;
+    /** Redraws canvas content after an upstream token or theme change. */
+    refreshTheme(): void;
     /** Reads the customizable ramp endpoints off the host's computed style. */
     private scaleEndpoints;
     /** Resolves the `--lyra-color-text-quiet` chrome token for axis labels. */
@@ -154,6 +295,72 @@ export declare class LyraHeatmap extends LyraElement {
     /** Reads the customizable canvas-drawn annotation-ring stroke color off the host's computed style. */
     private annotationColor;
     private draw;
+    private scheduleDraw;
+    private colorRamp;
+    /**
+     * 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.
+     */
+    private calendarCellSize;
+    /**
+     * 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()`.
+     */
+    private columnXFor;
+    /**
+     * 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.
+     */
+    private rowYFor;
+    /**
+     * Inverse of `columnXFor()`: resolves an x position (canvas-local CSS px)
+     * to the week column it falls in, or `null` if it's outside every column
+     * (`weekCount` is 0, or `x` doesn't land inside `[0, weekCount)`'s span).
+     * The default spacing has a closed-form inverse (division); an arbitrary
+     * `columnX` override doesn't, so that case instead scans each column's
+     * `[columnXFor(week), columnXFor(week + 1))` span — algebraically the same
+     * span the default formula's division derives — so hit-testing always
+     * agrees with wherever `columnXFor()` actually painted that column.
+     */
+    private weekAtX;
+    /**
+     * 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.
+     */
+    private weekdayAtY;
+    /**
+     * 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).
+     */
+    private weekdayLabels;
     private drawCalendar;
     /**
      * Effective per-cell size in matrix mode — `fitToWidth` derives it from
@@ -207,6 +414,14 @@ export declare class LyraHeatmap extends LyraElement {
     private emitCellClick;
     /** Inline `style` for `[part="tooltip"]`, centered above the given cell. */
     private tooltipStyle;
+    /**
+     * Value-equality check for a `CellPos`, since `hoverCell` is assigned a
+     * fresh object literal on every `pointermove` — Lit's `@state()`
+     * change-detection only no-ops an identical *reference*, so without this,
+     * `{row,col} !== {row,col}` by reference triggers a full canvas clear +
+     * redraw on every pixel of pointer movement, even within the same cell.
+     */
+    private samePos;
     private onPointerMove;
     private onPointerLeave;
     private onCanvasClick;