@aceshooting/lyra-ui 1.0.0 → 1.1.0

package/dist/components/graph/graph.stories.js

@@ -28,3 +28,41 @@ export const Default = {
     ></lyra-graph>
   `,
 };
+export const TunedForces = {
+    render: () => html `
+    <lyra-graph
+      width="480"
+      height="320"
+      style="height: 20rem"
+      charge-strength="-900"
+      link-distance="200"
+      .nodes=${nodes}
+      .links=${links}
+    ></lyra-graph>
+  `,
+};
+export const BoundedZoom = {
+    render: () => html `
+    <lyra-graph
+      width="480"
+      height="320"
+      style="height: 20rem"
+      min-zoom="1"
+      max-zoom="2"
+      .nodes=${nodes}
+      .links=${links}
+    ></lyra-graph>
+  `,
+};
+export const SeededLayout = {
+    render: () => html `
+    <p>
+      Both graphs below share <code>seed="42"</code> — reload the page or diff a screenshot across builds and their
+      node positions are bit-identical, unlike the non-seeded <code>Default</code> story above.
+    </p>
+    <div style="display: flex; gap: 1rem; flex-wrap: wrap">
+      <lyra-graph width="320" height="240" style="height: 15rem" seed="42" .nodes=${nodes} .links=${links}></lyra-graph>
+      <lyra-graph width="320" height="240" style="height: 15rem" seed="42" .nodes=${nodes} .links=${links}></lyra-graph>
+    </div>
+  `,
+};

package/dist/components/graph/graph.styles.js

@@ -11,6 +11,11 @@ export const styles = css `
   [part='link'] {
     stroke: var(--lyra-color-border);
     fill: none;
+    cursor: pointer;
+  }
+  [part='link']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
   }
   [part='node'] {
     /* --lyra-node-fill is set inline per-node (see graph.ts) from GraphNode.color;
@@ -26,7 +31,7 @@ export const styles = css `
     outline-offset: var(--lyra-focus-ring-offset);
   }
   [part='label'] {
-    font-size: 10px;
+    font-size: 0.625rem;
     fill: var(--lyra-color-text);
     font-family: var(--lyra-font);
     pointer-events: none;

package/dist/components/heatmap/calendar-grid.d.ts

@@ -17,6 +17,13 @@ export declare function parseIsoDate(iso: string): Date;
  * Lays `days` out onto a GitHub-style Sunday-Saturday x week grid. `days`
  * need not be sorted or contiguous; the grid spans from the earliest to the
  * latest date present, anchored at the Sunday on/before the earliest date.
+ *
+ * An entry whose `date` doesn't parse to a valid calendar date (e.g. `''` or
+ * `'2026-03'`) is dropped rather than included: `parseIsoDate` on a malformed
+ * string yields an `Invalid Date` (`getTime()` is `NaN`), and letting that
+ * single `NaN` reach the min/max below would poison `firstWeekStart` (and
+ * therefore every cell's `week`) for the whole grid instead of just the bad
+ * entry.
  */
 export declare function buildCalendarGrid(days: CalendarDay[]): {
     cells: CalendarCell[];

package/dist/components/heatmap/calendar-grid.js

@@ -1,3 +1,4 @@
+import { minMax } from './heatmap-scale.js';
 const MS_PER_DAY = 86_400_000;
 /** Parses a `yyyy-mm-dd` string as UTC midnight, avoiding local-timezone day-boundary drift. */
 export function parseIsoDate(iso) {
@@ -8,14 +9,23 @@ export function parseIsoDate(iso) {
  * Lays `days` out onto a GitHub-style Sunday-Saturday x week grid. `days`
  * need not be sorted or contiguous; the grid spans from the earliest to the
  * latest date present, anchored at the Sunday on/before the earliest date.
+ *
+ * An entry whose `date` doesn't parse to a valid calendar date (e.g. `''` or
+ * `'2026-03'`) is dropped rather than included: `parseIsoDate` on a malformed
+ * string yields an `Invalid Date` (`getTime()` is `NaN`), and letting that
+ * single `NaN` reach the min/max below would poison `firstWeekStart` (and
+ * therefore every cell's `week`) for the whole grid instead of just the bad
+ * entry.
  */
 export function buildCalendarGrid(days) {
-    if (days.length === 0) {
+    const parsed = days
+        .map((d) => ({ ...d, dateObj: parseIsoDate(d.date) }))
+        .filter((d) => !Number.isNaN(d.dateObj.getTime()));
+    if (parsed.length === 0) {
         return { cells: [], weekCount: 0, firstWeekStart: new Date(0), monthLabels: [] };
     }
-    const parsed = days.map((d) => ({ ...d, dateObj: parseIsoDate(d.date) }));
-    const minTime = Math.min(...parsed.map((d) => d.dateObj.getTime()));
-    const min = new Date(minTime);
+    const timeBounds = minMax(parsed.map((d) => d.dateObj.getTime()));
+    const min = new Date(timeBounds[0]);
     const firstWeekStart = new Date(Date.UTC(min.getUTCFullYear(), min.getUTCMonth(), min.getUTCDate() - min.getUTCDay()));
     const cells = parsed.map((d) => {
         const weekday = d.dateObj.getUTCDay();
@@ -23,7 +33,7 @@ export function buildCalendarGrid(days) {
         const week = Math.floor(daysSinceStart / 7);
         return { date: d.date, value: d.value, week, weekday };
     });
-    const weekCount = Math.max(...cells.map((c) => c.week)) + 1;
+    const weekCount = minMax(cells.map((c) => c.week))[1] + 1;
     const monthLabels = [];
     let lastMonth = -1;
     for (const cell of cells.slice().sort((a, b) => a.week - b.week)) {
@@ -43,10 +53,17 @@ export function buildCalendarGrid(days) {
 export function quartileBucket(value, sorted, bucketCount) {
     if (sorted.length === 0)
         return 0;
-    let count = 0;
-    for (const v of sorted)
-        if (v <= value)
-            count++;
-    const rank = count / sorted.length;
+    // `sorted` is ascending, so the count of elements <= value is found via an
+    // upper-bound binary search (O(log n)) instead of scanning the whole array.
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const rank = lo / sorted.length;
     return Math.min(bucketCount - 1, Math.floor(rank * bucketCount));
 }

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,42 @@ 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.
+ * @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 +105,102 @@ 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[];
     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.
+     */
+    private cellText;
+    private matrixCellText;
+    private calendarCellText;
+    /** 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 {