@aceshooting/lyra-ui 1.0.1 → 1.2.0

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

@@ -1,6 +1,29 @@
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { type CalendarDay } from './calendar-grid.js';
+/** 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
@@ -25,16 +48,44 @@ export declare function resolveRgb(color: string, fallbackHex: string): [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;
 /**
- * `<lyra-heatmap>` — a Canvas matrix heatmap with a DPR-aware, resize-aware
- * redraw loop. `-1` cells are treated as "no data". 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).
+ * `<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. `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 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"]`.
  *
  * @customElement lyra-heatmap
- * @csspart base, canvas, legend
+ * @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
  */
 export declare class LyraHeatmap extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -56,26 +107,112 @@ export declare class LyraHeatmap extends LyraElement {
     mode: 'matrix' | 'calendar';
     days: CalendarDay[];
     bucketCount: 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;
     private canvas?;
     private resizeObserver?;
     private dprQuery?;
+    /** The current value range, refreshed once per update cycle by `willUpdate()`. See `computeValueRange()`. */
+    private cachedValueRange;
+    /** 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;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private watchDpr;
     private onDprChange;
-    protected willUpdate(): void;
-    /** The real (non-no-data) value range across `values` (or `days` in calendar mode), or `null` if there is none. Shared by `willUpdate()`, `draw()`, and the legend. */
-    private valueRange;
+    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(): 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 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;
+    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;
+    /** 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;
+    private onPointerMove;
+    private onPointerLeave;
+    private onCanvasClick;
+    private onKeyDown;
+    private onMatrixKeyDown;
+    private onCalendarKeyDown;
     render(): TemplateResult;
 }
 declare global {