@aceshooting/lyra-ui 4.2.0 → 5.1.0

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

@@ -0,0 +1,662 @@
+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;
+}
+/**
+ * One entry of a discrete legend key, supplied via `legendStops`. Purely a legend description —
+ * it never feeds back into the cell color ramp (see `LyraHeatmap.legendStops`).
+ */
+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;
+    /** Optional label override; defaults to the component's own numeric formatting of `value`. */
+    label?: string;
+}
+/** A single cell to mark as persistently selected -- `row`/`col` in matrix mode, `date` in
+ *  calendar mode (whichever pair matches the active `mode`; the other field is ignored),
+ *  mirroring `HeatmapAnnotation`'s own row/col/date shape. */
+export interface HeatmapSelectedCell {
+    row?: number;
+    col?: number;
+    date?: string;
+}
+/**
+ * Parses a strict `#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa` hex string into an
+ * `[r, g, b, a]` quadruple (`a` in `[0, 1]`, defaulting to `1` for the
+ * 3/6-digit alpha-less forms), 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, 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, a]` quadruple (`a` in
+ * `[0, 1]`, `1` for an opaque input). A translucent input (e.g.
+ * `rgba(255,255,255,.028)`, a common way to key a color ramp off a themed
+ * "quiet surface" token) round-trips its alpha rather than silently
+ * resolving to the fully opaque equivalent.
+ *
+ * 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, number];
+export type LyraHeatmapCellClickDetail = {
+    date: string;
+    value: number;
+} | {
+    row: number;
+    col: number;
+    value: number;
+};
+export interface LyraHeatmapEventMap {
+    'lr-cell-click': CustomEvent<LyraHeatmapCellClickDetail>;
+}
+/**
+ * `<lr-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
+ * `--lr-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
+ * `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"]`.
+ *
+ * `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
+ * derived from the controlled `selectedCell` property; the canvas remains the
+ * visual rendering surface underneath.
+ *
+ * `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 lr-heatmap
+ * @event lr-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 cells - The opt-in per-cell accessibility overlay.
+ * @csspart cell - An opt-in native button for one matrix or calendar cell.
+ * @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 (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-stop-label - The text of one `legendStops` entry.
+ * @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.
+ * @cssprop [--lr-heatmap-no-data-fill=var(--lr-color-no-data)] - Fill for cells with no value.
+ * @cssprop [--lr-heatmap-label-font] - Font for axis/legend labels drawn on the canvas.
+ * @cssprop [--lr-heatmap-tooltip-bg=var(--lr-color-surface)] - Hover tooltip background.
+ * @cssprop [--lr-heatmap-tooltip-text=var(--lr-color-text)] - Hover tooltip text color.
+ * @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 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[];
+    private _firstDayOfWeek;
+    /**
+     * 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. Normalized into `[0, 6]` via modulo wrap (not
+     * clamp) -- mirrors `buildCalendarGrid()`'s own `(x + 7) % 7` weekday-wrapping
+     * convention (already used elsewhere in this file), so e.g. `7` wraps to `0`
+     * (Sunday) and `-1` wraps to `6` (Saturday) rather than being clamped to the
+     * nearest in-range end. A non-finite input falls back to `0`.
+     */
+    get firstDayOfWeek(): number;
+    set firstDayOfWeek(value: 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[];
+    /**
+     * A discrete legend key rendered *instead of* the `--lr-heatmap-scale-lo`/`-hi` gradient bar
+     * and its `[part="legend-lo"]`/`[part="legend-hi"]` endpoint labels — one
+     * `[part="legend-stop"]` per entry, in array order, each a `[part="legend-swatch"]` in that
+     * entry's `color` plus a `[part="legend-stop-label"]`. Labels default to this component's own
+     * locale-aware numeric formatting of `value`, so a stop only needs an explicit `label` when
+     * the number isn't the right caption ("none", "≥ 90%").
+     *
+     * 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
+     * re-implementing swatches, labels and the annotation entries by hand.
+     *
+     * Strictly presentation: the stops are never consulted by the color ramp, the bucket math, the
+     * tooltip, or the accessible name — supplying them changes nothing a cell renders. Any
+     * `annotations` with a `label` still render their `[part="legend-annotation"]` entries after
+     * the stops. Unset (the default) or an empty array reproduces today's exact gradient legend.
+     */
+    legendStops?: HeatmapLegendStop[];
+    /**
+     * The single cell to mark as persistently selected -- `row`/`col` in matrix mode, `date` in
+     * calendar mode. Purely a controlled, consumer-owned visual/accessibility marker, mirroring
+     * `<lr-lite-chart>`'s `selectedIndex` -- this component never mutates it itself; a consumer
+     * wires it up from `lr-cell-click` (or any other source) to build a toggle-select
+     * interaction. Unset (the default, `null`) draws no selection ring, adds no selected-cell text
+     * to the host's `aria-label`, and adds no "(selected)" suffix to the live-region announcement,
+     * reproducing today's exact output.
+     */
+    selectedCell: HeatmapSelectedCell | null;
+    /**
+     * Renders an opt-in DOM overlay of native buttons over the canvas. Each
+     * button has a localized accessible name, explicit `aria-pressed="true"` or
+     * `"false"` from `selectedCell`, and participates in a roving tabindex so a
+     * dense calendar does not create hundreds of tab stops. The selection is
+     * controlled: clicking a cell still emits `lr-cell-click`, and the
+     * consumer updates `selectedCell` when it wants `aria-pressed` to change.
+     */
+    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
+     *  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. A returned value containing a CSS custom property
+     *  (e.g. `var(--x)`) or other browser-resolvable color syntax (e.g. `color-mix(...)`) is
+     *  automatically resolved before being used as a canvas fill color. */
+    cellColor?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string | undefined;
+    /** Overrides the weekday-axis label text in calendar mode -- receives the real JS weekday index
+     *  (`0` Sunday .. `6` Saturday) for a row that would otherwise render a label (today, only rows
+     *  1/3/5 relative to `firstDayOfWeek` ever do) and, when it returns a string, uses it instead of
+     *  the built-in `Intl.DateTimeFormat`-derived short weekday name. Unset (the default) reproduces
+     *  today's exact locale-derived output. */
+    weekdayLabelText?: (jsWeekday: number) => string | undefined;
+    /** Overrides the month-axis label text in calendar mode -- receives the real JS month index
+     *  (`0` January .. `11` December) and full year for a month boundary that would otherwise
+     *  render a label and, when it returns a string, uses it instead of the built-in
+     *  `Intl.DateTimeFormat`-derived short month name. Mirrors `weekdayLabelText`'s exact
+     *  override-with-fallback shape -- unset (the default) reproduces today's exact
+     *  `toLocaleString(undefined, ...)`-derived output. */
+    monthLabelText?: (jsMonth: number, year: number) => string | undefined;
+    /** A discrete array (≥2) of CSS colors used as exact ramp steps instead of linearly
+     *  interpolating between the two `--lr-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;
+    /** 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. */
+    private canvasHasContent;
+    /** 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 localized "Selected: <cell>." description appended to the host `aria-label`, or `''` when
+     *  `selectedCell` is unset or doesn't resolve to a real cell in the current grid. */
+    private selectedCellDescription;
+    /**
+     * 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;
+    private localizedValueLabel;
+    private formatNumericValue;
+    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 `--lr-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;
+    /** Reads the customizable canvas-drawn selected-cell-ring stroke color off the host's computed style. */
+    private selectedColor;
+    /** Whether `selectedCell` refers to the given grid position, in whichever mode is active --
+     *  `row`/`col` equality in matrix mode, resolved-date equality in calendar mode (looking the
+     *  position's actual date up via `calendarCellAt()`, the same way the annotation ring resolves
+     *  `ann.date` against `cells`). Shared by the live-region announcement, which needs to know
+     *  whether the just-announced cell *is* the selection. */
+    private isSelectedPos;
+    private draw;
+    /** Repaints the old and new focus-ring cells after keyboard/click navigation. The underlying
+     * cell fill plus annotation/selection rings are restored before the new focus ring is stroked,
+     * so clearing a dirty rectangle never erases persistent data. Returns false when a complete draw
+     * is still required (for example before the first canvas pass or after a mode change). */
+    private repaintFocusRing;
+    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. The labeled weekdays are always Monday, Wednesday, and
+     * Friday — matching today's sparse every-other-day label density — the
+     * rest stay blank. Which *row* each one lands on depends on
+     * `firstDayOfWeek`, since `buildCalendarGrid()` anchors `firstWeekStart`
+     * (and therefore row 0) at that weekday. For each target weekday (using
+     * the standard JS convention, Sunday=0..Saturday=6, so Monday=1,
+     * Wednesday=3, Friday=5), the row is `(weekday - firstDayOfWeek + 7) % 7`;
+     * with the default `firstDayOfWeek` of 0 this reduces to rows 1/3/5,
+     * unchanged. The label *text* for each computed row is derived via
+     * `Intl.DateTimeFormat` on a real UTC date that actually falls on that row,
+     * 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 paintMatrixCell;
+    private paintMatrixFocusOverlays;
+    private repaintMatrixFocusCell;
+    private paintCalendarCell;
+    private paintCalendarFocusOverlays;
+    private repaintCalendarFocusCell;
+    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.
+     *  The selected state goes through the same `heatmapSelectedCellLabel`
+     *  template as the host aria-label, so a locale can place the "selected"
+     *  wording anywhere around the cell text instead of it being appended. */
+    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;
+    /** Cache of resolved colors for the current draw pass, cleared at the top
+     *  of drawCalendar()/drawMatrix() so a theme change is always picked up on
+     *  the very next full redraw, while repeated identical cellColor() outputs
+     *  within the same pass resolve only once. */
+    private canvasColorCache;
+    private colorProbe?;
+    /** Resolves a cellColor() return value that may contain a CSS custom
+     *  property (or any other CSS color syntax the browser understands, e.g.
+     *  color-mix()) into a literal color canvas's fillStyle can actually use --
+     *  fillStyle silently no-ops on an unparseable string, per the Canvas 2D
+     *  spec, leaving whatever the previous cell painted. Falls back to
+     *  noDataFill() for a genuinely invalid color. */
+    private resolveCanvasColor;
+    /** Positions represented by the optional DOM accessibility overlay. The
+     * canvas paints empty calendar grid positions too, so those positions get a
+     * real date and a no-data announcement just like pointer/keyboard hit tests. */
+    private accessibleCellPositions;
+    private accessibleCellKey;
+    private accessibleCellAtKey;
+    private focusAccessibleCell;
+    private onAccessibleCellFocus;
+    private onAccessibleCellClick;
+    private onAccessibleCellKeyDown;
+    private renderAccessibleCells;
+    /**
+     * 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.
+     */
+    private renderLegendScale;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-heatmap': LyraHeatmap;
+    }
+}
+//# sourceMappingURL=heatmap.class.d.ts.map