@aceshooting/lyra-ui 2.1.0 → 2.3.0

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

@@ -48,3 +48,16 @@ export function sqrtStep(count, max, steps) {
     const ratio = Math.sqrt(count) / Math.sqrt(max);
     return Math.min(steps - 1, Math.floor(ratio * steps));
 }
+/**
+ * Linear (non-quantile) bucket index in `[0, steps-1]` for `value` in `[lo, hi]` — mirrors
+ * `linearAlpha()`'s own min-max normalization (matrix mode's default continuous color mapping),
+ * discretized into `steps` buckets instead of a continuous alpha. Used when a discrete
+ * `colorSteps` ramp replaces the default continuous 2-endpoint interpolation for the `'linear'`
+ * scale case (the `'sqrt'` scale already has its own discrete `sqrtStep()`).
+ */
+export function linearBucket(value, lo, hi, steps) {
+    const span = hi - lo || 1;
+    const t = Math.min(1, Math.max(0, (value - lo) / span));
+    return Math.min(steps - 1, Math.floor(t * steps));
+}
+//# sourceMappingURL=heatmap-scale.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap-scale.js","sourceRoot":"","sources":["../../../src/components/heatmap/heatmap-scale.ts"],"names":[],"mappings":"AAAA,mIAAmI;AACnI,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,EAAU,EAAE,EAAU;IAC/D,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAC9B,OAAO,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,MAAgB;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,EAAE,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACpB,IAAI,EAAE,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,CAAC,GAAG,EAAE;YAAE,EAAE,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,GAAG,EAAE;YAAE,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,GAAW,EAAE,KAAa;IAChE,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IACzB,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACvB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,EAAU,EAAE,EAAU,EAAE,KAAa;IAC/E,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;AACpD,CAAC"}

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

@@ -0,0 +1,489 @@
+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;
+    col: number;
+}
+/** A cell cursor in calendar mode — a grid position, not necessarily one with
+ *  a matching entry in `days` (see `calendarCellAt()`). */
+export interface CalendarCellPos {
+    week: number;
+    weekday: number;
+}
+/**
+ * A marker drawn as a stroked ring over a matching cell (matrix mode:
+ * `row`/`col`; calendar mode: `date` — whichever pair matches the active
+ * `mode`; the other fields are simply ignored). An optional `label`
+ * additionally surfaces the annotation in the legend.
+ */
+export interface HeatmapAnnotation {
+    row?: number;
+    col?: number;
+    date?: string;
+    label?: string;
+}
+/**
+ * Parses a strict `#rgb` or `#rrggbb` hex string into an `[r, g, b]` triple,
+ * or `null` if `hex` isn't one (rather than silently coercing an unparsable
+ * 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.
+ *
+ * Hand-rolling a parser for every CSS color syntax is unnecessary and
+ * error-prone (a naive hex-only parser silently turns an unrecognized format
+ * into `NaN` -> `0`, i.e. solid black). The canvas 2D context already
+ * implements the full CSS color grammar via its `fillStyle` setter, so this
+ * normalizes through that instead. Assigning an unparsable string to
+ * `fillStyle` is a spec'd no-op (the previous value is kept, it never
+ * throws), so a sentinel round-trip is used to detect that case and fall
+ * back to `fallbackHex` (with a one-time `console.warn`) instead of
+ * silently drawing the wrong color.
+ */
+export declare function resolveRgb(color: string, fallbackHex: string): [number, number, number];
+/** Linearly interpolates between two CSS colors (any valid syntax) at `t` in `[0, 1]`. */
+export declare function mixColor(fromColor: string, toColor: string, t: number): string;
+export type LyraHeatmapCellClickDetail = {
+    date: string;
+    value: number;
+} | {
+    row: number;
+    col: number;
+    value: number;
+};
+export interface LyraHeatmapEventMap {
+    'lyra-cell-click': CustomEvent<LyraHeatmapCellClickDetail>;
+}
+/**
+ * `<lyra-heatmap>` — a Canvas heatmap with a DPR-aware, resize-aware redraw
+ * loop, in one of two `mode`s:
+ *
+ * - `"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.
+ * - `"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
+ * `heatmap.styles.ts`) so hosts can retheme it — canvas can't consume
+ * `var()` directly, so they're resolved once per draw via
+ * `getComputedStyle`, then normalized to RGB by `resolveRgb()` (any valid
+ * CSS color syntax, not just hex — see its doc comment).
+ *
+ * Every cell is independently addressable: a `pointermove` hit test over the
+ * canvas shows `[part="tooltip"]` with that cell's label + value (hidden on
+ * `pointerleave`); the canvas is `tabindex="0"` with arrow-key roving focus
+ * (a stroked ring redrawn over the focused cell on every draw, plus a
+ * visually-hidden `aria-live="polite"` status announcement — avoids a
+ * DOM-node-per-cell overlay, which would be hundreds of nodes for a year
+ * calendar); and a click, or Enter/Space on the focused cell, fires
+ * `lyra-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"]`.
+ *
+ * `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.
+ * `cellColor` overrides a cell's ramp-computed color entirely for an exact value.
+ * @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<LyraHeatmapEventMap> {
+    static styles: import("lit").CSSResultGroup[];
+    rowLabels: string[];
+    colLabels: string[];
+    values: 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` (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[];
+    /**
+     * 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;
+    /** 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. */
+    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
+     *  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
+     *  both "no data" and the ramp's own lightest step) without a prepended synthetic ramp color,
+     *  which can't safely reserve an exact value on a skewed dataset (the bucket selectors round by
+     *  continuous ratio, with no equality-based reservation). Unset (the default) reproduces today's
+     *  exact ramp/no-data behavior for every cell. */
+    cellColor?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string | undefined;
+    /** A discrete array (≥2) of CSS colors used as exact ramp steps instead of linearly
+     *  interpolating between the two `--lyra-heatmap-scale-lo`/`-hi` endpoints — lets a consumer
+     *  bring a validated, non-linear (or simply non-2-endpoint) sequential palette. Governs both
+     *  `mode`s and both `scale` values, discretizing whichever scale would otherwise interpolate
+     *  continuously into `colorSteps.length` buckets instead. Unset (the default, or fewer than 2
+     *  entries) keeps today's 2-endpoint interpolation exactly. */
+    colorSteps?: 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
+     *  canvas-drawn focus ring and the `[part="live-region"]` announcement. */
+    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
+     * calendar mode), or `null` if there is none. Only called from
+     * `willUpdate()`, which caches the result in `cachedValueRange` for
+     * `render()` and `drawMatrix()` to reuse — `willUpdate()`, `render()`, and
+     * `updated()` (which triggers `draw()`) all run within the same Lit update
+     * cycle against the same `values`/`days`, so a single scan per cycle
+     * suffices instead of one per consumer.
+     */
+    private computeValueRange;
+    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. */
+    private labelColor;
+    /** Reads the customizable canvas axis/label font off the host's computed style. */
+    private labelFont;
+    /** Reads the customizable no-data cell fill off the host's computed style. */
+    private noDataFill;
+    /** Reads the customizable canvas-drawn keyboard-focus-ring stroke color off the host's computed style. */
+    private focusRingColor;
+    /** 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
+     * the host's measured width, otherwise it's the fixed `cellSize`
+     * property. Shared by `drawMatrix()` and the pointer/keyboard hit-testing
+     * below (`hitTestMatrix()`, `cellRect()`) so they always agree on exactly
+     * the same geometry as what's actually painted.
+     */
+    private matrixCellSize;
+    private drawMatrix;
+    /**
+     * Maps a pointer position, in canvas-local CSS px (e.g.
+     * `PointerEvent.offsetX/offsetY`), to the cell underneath it — or `null`
+     * if the pointer is outside the grid. Dispatches on `mode` so callers
+     * don't have to.
+     */
+    private hitTest;
+    private hitTestMatrix;
+    /** The first interactive matrix cell in row-major order, or `null` if every cell is excluded —
+     *  used by `onMatrixKeyDown()`'s first-arrow-press case. */
+    private firstInteractiveMatrixCell;
+    /** Steps from `(row, col)` by `(dRow, dCol)` repeatedly, skipping non-interactive cells, until
+     *  an interactive cell is found or the grid edge is reached (in which case the original
+     *  position is returned unchanged, matching today's clamp-at-edge behavior). Bounded: each
+     *  iteration strictly approaches the edge, so this always terminates. */
+    private nextInteractiveMatrixCell;
+    /** Calendar-mode analogue of `firstInteractiveMatrixCell()`. */
+    private firstInteractiveCalendarCell;
+    /** Calendar-mode analogue of `nextInteractiveMatrixCell()`. */
+    private nextInteractiveCalendarCell;
+    private hitTestCalendar;
+    /**
+     * Resolves a (week, weekday) grid position to its real calendar date and
+     * value. Computed from grid geometry (`firstWeekStart` + offset), not
+     * just looked up in `cells` — so a position with no matching entry in
+     * `days` (a gap in a sparse calendar) still resolves to a real ISO date,
+     * with a `-1` "no data" sentinel value (the same convention `values`' `-1`
+     * sentinel uses in matrix mode), instead of being unresolvable.
+     */
+    private calendarCellAt;
+    /**
+     * Pixel rect (canvas-local CSS px) of a cell — shared by `tooltipStyle()`
+     * so the tooltip's position always agrees with the same geometry
+     * `drawMatrix()`/`drawCalendar()`/`hitTest*()` use.
+     */
+    private cellRect;
+    /**
+     * Human-readable "<label>: <value>" text for a cell — shared by the hover
+     * tooltip and the keyboard-focus live-region announcement, so both always
+     * describe a cell the same way. This is the built-in English fallback used
+     * when `cellText` isn't set — see `resolveCellText()`.
+     */
+    private defaultCellText;
+    private matrixCellText;
+    private calendarCellText;
+    /** The raw numeric value at a cell position, in either mode — shared by `resolveCellText()`
+     *  so a custom `cellText` formatter receives the same value the built-in template would use. */
+    private valueAt;
+    /** Dispatches to the host-provided `cellText` formatter when set, otherwise the built-in template. */
+    private resolveCellText;
+    /** Dispatches to the host-provided `cellInteractive` predicate when set, otherwise `true`
+     *  (every cell interactive, today's unchanged default). */
+    private isCellInteractive;
+    /** Refreshes the visually-hidden live-region text for a newly-focused cell. */
+    private announce;
+    private emitCellClick;
+    /** Inline `style` for `[part="tooltip"]`, centered above the given cell. */
+    private tooltipStyle;
+    /**
+     * Value-equality check for a `CellPos`, since `hoverCell` is assigned a
+     * fresh object literal on every `pointermove` — Lit's `@state()`
+     * change-detection only no-ops an identical *reference*, so without this,
+     * `{row,col} !== {row,col}` by reference triggers a full canvas clear +
+     * redraw on every pixel of pointer movement, even within the same cell.
+     */
+    private samePos;
+    private onPointerMove;
+    private onPointerLeave;
+    private onCanvasClick;
+    private onKeyDown;
+    private onMatrixKeyDown;
+    private onCalendarKeyDown;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-heatmap': LyraHeatmap;
+    }
+}
+//# sourceMappingURL=heatmap.class.d.ts.map

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

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