@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/graph/graph.d.ts

@@ -4,6 +4,7 @@ import '../skeleton/skeleton.js';
 export interface GraphNode {
     id: string;
     label?: string;
+    /** Clamped to [6, 24] (a non-finite/missing value uses the midpoint, 15) — never rendered smaller/larger. */
     radius?: number;
     color?: string;
 }
@@ -19,12 +20,24 @@ export interface GraphLink {
  *
  * Set `seed` for a deterministic layout: node initial positions become
  * reproducible (keyed by node id) and the settle happens synchronously
- * instead of animating, like `prefers-reduced-motion`.
+ * instead of animating, like `prefers-reduced-motion`. `seed` only takes
+ * effect on the update that first populates `nodes`/`links` (or a later
+ * update that adds genuinely new node ids) — willUpdate() only reads it from
+ * inside rebuildSimulation(), which itself only ever assigns x/y to nodes
+ * that don't already have a settled position, so changing `seed` on an
+ * already-rendered graph is a no-op; nothing re-derives already-positioned
+ * nodes' x/y from the new value.
  *
  * @customElement lyra-graph
  * @event lyra-node-click - `detail: { id }`.
  * @event lyra-link-click - `detail: { source, target }`.
- * @csspart base, svg, node, link, label
+ * @csspart base - The graph wrapper.
+ * @csspart svg - The graph SVG.
+ * @csspart node - A graph node.
+ * @csspart link - A graph link.
+ * @csspart label - A node label.
+ * @csspart live-region - The current graph item announcement.
+ * @csspart data-list - A visually hidden list alternative for graph data.
  */
 export declare class LyraGraph extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -38,12 +51,20 @@ export declare class LyraGraph extends LyraElement {
     maxZoom: number;
     /** When set, seeds each node's initial x/y deterministically (keyed by
      *  node id, not array index) instead of forceSimulation()'s own random
-     *  start, and settles the simulation synchronously — see rebuildSimulation(). */
+     *  start, and settles the simulation synchronously — see rebuildSimulation().
+     *  Only takes effect on the update that first assigns a given node id an
+     *  x/y (i.e. supplied at/before `nodes`/`links` first populate, or when a
+     *  later update introduces new node ids) — changing `seed` afterwards does
+     *  not retroactively reposition already-settled nodes; there is currently
+     *  no way to make an already-rendered graph reproducible after the fact. */
     seed?: number;
     /** True until the lazy-loaded d3 peer dependencies have settled (success or failure). */
     private loading;
     private simNodes;
     private simLinks;
+    /** One roving tab stop across all nodes and links; nodes are the initial entry order. */
+    private activeGraphItem;
+    private graphLiveText;
     private simulation?;
     /** The live charge/link force objects, kept so chargeStrength/linkDistance
      *  changes can retune them in place (see updated()) instead of requiring a
@@ -73,6 +94,13 @@ export declare class LyraGraph extends LyraElement {
     private linkEls;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * A caller-supplied `radius` is clamped to [MIN_RADIUS, MAX_RADIUS] (and a
+     * non-finite/NaN value falls back to the same default average as an unset
+     * one) — an unclamped 0/negative radius would render an invisibly small
+     * `<circle>` that's still `role="button" tabindex="0"`, an invisible,
+     * focusable/clickable control with no visible focus indicator.
+     */
     private nodeRadius;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
@@ -114,6 +142,12 @@ export declare class LyraGraph extends LyraElement {
     private rebuildSimulation;
     private onNodeClick;
     private onLinkClick;
+    private graphItemCount;
+    private normalizedGraphItem;
+    private graphItemText;
+    private onGraphItemFocus;
+    private focusGraphItem;
+    private onGraphKeyDown;
     render(): TemplateResult;
 }
 declare global {

package/dist/components/graph/graph.js

@@ -9,6 +9,7 @@ import { property, state } from 'lit/decorators.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
+import { srOnly } from '../../internal/a11y.js';
 import { styles } from './graph.styles.js';
 import { loadD3 } from './graph-loader.js';
 import '../skeleton/skeleton.js';
@@ -67,12 +68,24 @@ function sanitizeNodeColor(color) {
  *
  * Set `seed` for a deterministic layout: node initial positions become
  * reproducible (keyed by node id) and the settle happens synchronously
- * instead of animating, like `prefers-reduced-motion`.
+ * instead of animating, like `prefers-reduced-motion`. `seed` only takes
+ * effect on the update that first populates `nodes`/`links` (or a later
+ * update that adds genuinely new node ids) — willUpdate() only reads it from
+ * inside rebuildSimulation(), which itself only ever assigns x/y to nodes
+ * that don't already have a settled position, so changing `seed` on an
+ * already-rendered graph is a no-op; nothing re-derives already-positioned
+ * nodes' x/y from the new value.
  *
  * @customElement lyra-graph
  * @event lyra-node-click - `detail: { id }`.
  * @event lyra-link-click - `detail: { source, target }`.
- * @csspart base, svg, node, link, label
+ * @csspart base - The graph wrapper.
+ * @csspart svg - The graph SVG.
+ * @csspart node - A graph node.
+ * @csspart link - A graph link.
+ * @csspart label - A node label.
+ * @csspart live-region - The current graph item announcement.
+ * @csspart data-list - A visually hidden list alternative for graph data.
  */
 export class LyraGraph extends LyraElement {
     constructor() {
@@ -89,6 +102,9 @@ export class LyraGraph extends LyraElement {
         this.loading = true;
         this.simNodes = [];
         this.simLinks = [];
+        /** One roving tab stop across all nodes and links; nodes are the initial entry order. */
+        this.activeGraphItem = 0;
+        this.graphLiveText = '';
         /** Node `<circle>`s already wired up with d3-drag; cleared on every simulation rebuild
          *  so DOM elements Lit reuses across a rebuild get rebound to their fresh datum. */
         this.boundNodeEls = new WeakSet();
@@ -100,9 +116,22 @@ export class LyraGraph extends LyraElement {
         this.nodeLabelEls = [];
         this.linkEls = [];
     }
-    static { this.styles = [LyraElement.styles, styles]; }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
     connectedCallback() {
         super.connectedCallback();
+        // A reconnect (e.g. a drag-and-drop reparent that keeps this same
+        // element instance) fires disconnectedCallback then connectedCallback
+        // synchronously with no update in between — this.d3 is already set from
+        // the initial mount, and the live simulation/DOM are still intact
+        // (disconnectedCallback only stops the simulation's timer, it doesn't
+        // tear anything down). Redoing the lazy-load + rebuildSimulation() here
+        // would discard every already-settled node's position and restart the
+        // whole ~300-tick alpha=1 settle animation for no reason — just resume
+        // the existing simulation in place instead.
+        if (this.d3) {
+            this.simulation?.restart();
+            return;
+        }
         void loadD3().then((mods) => {
             this.loading = false;
             // The element may have been removed from the DOM while the dynamic
@@ -118,8 +147,16 @@ export class LyraGraph extends LyraElement {
         super.disconnectedCallback();
         this.simulation?.stop();
     }
+    /**
+     * A caller-supplied `radius` is clamped to [MIN_RADIUS, MAX_RADIUS] (and a
+     * non-finite/NaN value falls back to the same default average as an unset
+     * one) — an unclamped 0/negative radius would render an invisibly small
+     * `<circle>` that's still `role="button" tabindex="0"`, an invisible,
+     * focusable/clickable control with no visible focus indicator.
+     */
     nodeRadius(n) {
-        return n.radius ?? (MIN_RADIUS + MAX_RADIUS) / 2;
+        const r = n.radius ?? (MIN_RADIUS + MAX_RADIUS) / 2;
+        return Number.isFinite(r) ? Math.min(MAX_RADIUS, Math.max(MIN_RADIUS, r)) : (MIN_RADIUS + MAX_RADIUS) / 2;
     }
     willUpdate(changed) {
         // rebuildSimulation() (re)assigns the simNodes/simLinks reactive
@@ -355,6 +392,69 @@ export class LyraGraph extends LyraElement {
         const target = typeof link.target === 'object' ? link.target.id : String(link.target);
         this.emit('lyra-link-click', { source, target });
     }
+    graphItemCount() {
+        return this.simNodes.length + this.simLinks.length;
+    }
+    normalizedGraphItem(index = this.activeGraphItem) {
+        const count = this.graphItemCount();
+        return count ? Math.min(Math.max(index, 0), count - 1) : -1;
+    }
+    graphItemText(index) {
+        if (index < this.simNodes.length) {
+            const node = this.simNodes[index];
+            return node ? `Node ${node.label ?? node.id}` : '';
+        }
+        const link = this.simLinks[index - this.simNodes.length];
+        if (!link)
+            return '';
+        const source = typeof link.source === 'object' ? link.source.label ?? link.source.id : String(link.source);
+        const target = typeof link.target === 'object' ? link.target.label ?? link.target.id : String(link.target);
+        return `Link from ${source} to ${target}`;
+    }
+    onGraphItemFocus(index) {
+        if (this.normalizedGraphItem(index) < 0)
+            return;
+        this.activeGraphItem = index;
+        this.graphLiveText = `${this.graphItemText(index)} (${index + 1} of ${this.graphItemCount()})`;
+    }
+    focusGraphItem(index) {
+        const normalized = this.normalizedGraphItem(index);
+        if (normalized < 0)
+            return;
+        this.activeGraphItem = normalized;
+        this.graphLiveText = `${this.graphItemText(normalized)} (${normalized + 1} of ${this.graphItemCount()})`;
+        void this.updateComplete.then(() => {
+            const items = [
+                ...Array.from(this.renderRoot.querySelectorAll('[part="node"]')),
+                ...Array.from(this.renderRoot.querySelectorAll('[part="link"]')),
+            ];
+            items[normalized]?.focus();
+        });
+    }
+    onGraphKeyDown(e, index, activate) {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            this.onGraphItemFocus(index);
+            activate();
+            return;
+        }
+        const count = this.graphItemCount();
+        if (!count)
+            return;
+        let next = index;
+        if (e.key === 'ArrowRight' || e.key === 'ArrowDown')
+            next = Math.min(count - 1, index + 1);
+        else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp')
+            next = Math.max(0, index - 1);
+        else if (e.key === 'Home')
+            next = 0;
+        else if (e.key === 'End')
+            next = count - 1;
+        else
+            return;
+        e.preventDefault();
+        this.focusGraphItem(next);
+    }
     render() {
         if (this.loading) {
             return html `
@@ -373,15 +473,17 @@ export class LyraGraph extends LyraElement {
           role="group"
           aria-label="Node-link diagram with ${this.simNodes.length} nodes and ${this.simLinks.length} links"
           viewBox="0 0 ${this.width} ${this.height}"
+          tabindex=${this.graphItemCount() ? '-1' : '0'}
         >
           <g transform="">
-            ${this.simLinks.map((l) => {
+            ${this.simLinks.map((l, linkIndex) => {
             const source = l.source;
             const target = l.target;
+            const itemIndex = this.simNodes.length + linkIndex;
             return svg `<line
                 part="link"
                 role="button"
-                tabindex="0"
+                tabindex=${this.normalizedGraphItem() === itemIndex ? '0' : '-1'}
                 aria-label="Link from ${source.label ?? source.id} to ${target.label ?? target.id}"
                 stroke-width=${l.width ?? 1.5}
                 x1=${source.x ?? 0}
@@ -389,33 +491,26 @@ export class LyraGraph extends LyraElement {
                 x2=${target.x ?? 0}
                 y2=${target.y ?? 0}
                 @click=${() => this.onLinkClick(l)}
-                @keydown=${(e) => {
-                if (e.key === 'Enter' || e.key === ' ') {
-                    e.preventDefault();
-                    this.onLinkClick(l);
-                }
-            }}
+                @focus=${() => this.onGraphItemFocus(itemIndex)}
+                @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, () => this.onLinkClick(l))}
               ></line>`;
         })}
-            ${this.simNodes.map((n) => {
+            ${this.simNodes.map((n, nodeIndex) => {
             const fill = sanitizeNodeColor(n.color);
+            const itemIndex = nodeIndex;
             return svg `<g>
                 <circle
                   part="node"
                   role="button"
-                  tabindex="0"
+                  tabindex=${this.normalizedGraphItem() === itemIndex ? '0' : '-1'}
                   aria-label=${n.label ?? n.id}
                   r=${this.nodeRadius(n)}
                   cx=${n.x ?? 0}
                   cy=${n.y ?? 0}
                   style=${styleMap(fill ? { '--lyra-node-fill': fill } : {})}
                   @click=${() => this.onNodeClick(n)}
-                  @keydown=${(e) => {
-                if (e.key === 'Enter' || e.key === ' ') {
-                    e.preventDefault();
-                    this.onNodeClick(n);
-                }
-            }}
+                  @focus=${() => this.onGraphItemFocus(itemIndex)}
+                  @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, () => this.onNodeClick(n))}
                 ></circle>
                 ${n.label
                 ? svg `<text part="label" aria-hidden="true" x=${(n.x ?? 0) + this.nodeRadius(n) + 2} y=${n.y ?? 0}>${n.label}</text>`
@@ -424,6 +519,17 @@ export class LyraGraph extends LyraElement {
         })}
           </g>
         </svg>
+        <div part="live-region" class="sr-only" role="status" aria-live="polite" aria-atomic="true">
+          ${this.graphLiveText || (this.normalizedGraphItem() >= 0 ? `${this.graphItemText(this.normalizedGraphItem())} (1 of ${this.graphItemCount()})` : '')}
+        </div>
+        <ul part="data-list" class="sr-only" aria-label="Graph data">
+          ${this.simNodes.map((node) => html `<li>Node ${node.label ?? node.id}</li>`)}
+          ${this.simLinks.map((link) => {
+            const source = link.source;
+            const target = link.target;
+            return html `<li>Link from ${source.label ?? source.id} to ${target.label ?? target.id}</li>`;
+        })}
+        </ul>
       </div>
     `;
     }
@@ -464,4 +570,10 @@ __decorate([
 __decorate([
     state()
 ], LyraGraph.prototype, "simLinks", void 0);
+__decorate([
+    state()
+], LyraGraph.prototype, "activeGraphItem", void 0);
+__decorate([
+    state()
+], LyraGraph.prototype, "graphLiveText", void 0);
 defineElement('graph', LyraGraph);

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

@@ -6,26 +6,38 @@ export interface CalendarDay {
 export interface CalendarCell {
     date: string;
     value: number;
-    /** 0-based week column, counting from the grid's first (earliest-containing) Sunday. */
+    /** 0-based week column, counting from the grid's first (earliest-containing) anchor week — see `buildCalendarGrid()`'s `firstDayOfWeek` parameter. */
     week: number;
-    /** 0 (Sunday) .. 6 (Saturday). */
+    /**
+     * Day-of-week position within the row, relative to `firstDayOfWeek`: 0 for
+     * the anchor weekday itself, up to 6 for the day immediately before it.
+     * With the default `firstDayOfWeek` of 0, this is the familiar 0 (Sunday)
+     * .. 6 (Saturday) numbering, unchanged from before `firstDayOfWeek` existed.
+     */
     weekday: number;
 }
 /** Parses a `yyyy-mm-dd` string as UTC midnight, avoiding local-timezone day-boundary drift. */
 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.
+ * Lays `days` out onto a GitHub-style week grid, 7 rows deep. `days` need not
+ * be sorted or contiguous; the grid spans from the earliest to the latest
+ * date present, anchored at the `firstDayOfWeek`-weekday on/before the
+ * earliest date (`firstDayOfWeek` is 0–6, Sunday-first by default — same
+ * numbering as `CalendarCell.weekday`). With the default `firstDayOfWeek` of
+ * 0, this is the Sunday on/before the earliest date, exactly as before this
+ * parameter existed.
  *
  * 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.
+ * entry. Likewise, an entry whose `date` is numerically well-formed but
+ * calendar-invalid (e.g. `'2026-02-30'`, which `Date.UTC` silently rolls
+ * over into March) is dropped rather than silently renormalized — see
+ * `isCalendarValid()`.
  */
-export declare function buildCalendarGrid(days: CalendarDay[]): {
+export declare function buildCalendarGrid(days: CalendarDay[], firstDayOfWeek?: number): {
     cells: CalendarCell[];
     weekCount: number;
     firstWeekStart: Date;

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

@@ -5,47 +5,71 @@ export function parseIsoDate(iso) {
     const [y, m, d] = iso.split('-').map(Number);
     return new Date(Date.UTC(y, m - 1, d));
 }
+/** Whether `iso` (already run through parseIsoDate) actually round-trips —
+ *  Date.UTC silently rolls e.g. day 30 of a 28-day February into March. */
+function isCalendarValid(iso, parsed) {
+    const [y, m, d] = iso.split('-').map(Number);
+    return parsed.getUTCFullYear() === y && parsed.getUTCMonth() === m - 1 && parsed.getUTCDate() === d;
+}
 /**
- * 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.
+ * Lays `days` out onto a GitHub-style week grid, 7 rows deep. `days` need not
+ * be sorted or contiguous; the grid spans from the earliest to the latest
+ * date present, anchored at the `firstDayOfWeek`-weekday on/before the
+ * earliest date (`firstDayOfWeek` is 0–6, Sunday-first by default — same
+ * numbering as `CalendarCell.weekday`). With the default `firstDayOfWeek` of
+ * 0, this is the Sunday on/before the earliest date, exactly as before this
+ * parameter existed.
  *
  * 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.
+ * entry. Likewise, an entry whose `date` is numerically well-formed but
+ * calendar-invalid (e.g. `'2026-02-30'`, which `Date.UTC` silently rolls
+ * over into March) is dropped rather than silently renormalized — see
+ * `isCalendarValid()`.
  */
-export function buildCalendarGrid(days) {
+export function buildCalendarGrid(days, firstDayOfWeek = 0) {
     const parsed = days
         .map((d) => ({ ...d, dateObj: parseIsoDate(d.date) }))
-        .filter((d) => !Number.isNaN(d.dateObj.getTime()));
+        .filter((d) => !Number.isNaN(d.dateObj.getTime()) && isCalendarValid(d.date, d.dateObj));
     if (parsed.length === 0) {
         return { cells: [], weekCount: 0, firstWeekStart: new Date(0), monthLabels: [] };
     }
     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()));
+    // Days back from `min` to the nearest `firstDayOfWeek`-weekday on/before
+    // it — with the default firstDayOfWeek of 0, this reduces to
+    // `min.getUTCDay()` exactly, i.e. today's original Sunday anchor.
+    const daysBackToAnchor = (min.getUTCDay() - firstDayOfWeek + 7) % 7;
+    const firstWeekStart = new Date(Date.UTC(min.getUTCFullYear(), min.getUTCMonth(), min.getUTCDate() - daysBackToAnchor));
     const cells = parsed.map((d) => {
-        const weekday = d.dateObj.getUTCDay();
+        // Relative to the anchor weekday (see `CalendarCell.weekday`'s doc
+        // comment) — with the default firstDayOfWeek of 0 this is just
+        // `d.dateObj.getUTCDay()`, unchanged from before.
+        const weekday = (d.dateObj.getUTCDay() - firstDayOfWeek + 7) % 7;
         const daysSinceStart = Math.round((d.dateObj.getTime() - firstWeekStart.getTime()) / MS_PER_DAY);
         const week = Math.floor(daysSinceStart / 7);
         return { date: d.date, value: d.value, week, weekday };
     });
     const weekCount = minMax(cells.map((c) => c.week))[1] + 1;
+    // Label every distinct (year, month) present in the data, not just months
+    // that happen to contain a Sunday-anchored cell — a sparse calendar (few
+    // days per month, none landing on a Sunday) would otherwise render zero
+    // month labels for months that do have data.
     const monthLabels = [];
-    let lastMonth = -1;
-    for (const cell of cells.slice().sort((a, b) => a.week - b.week)) {
+    const seenMonths = new Set();
+    for (const cell of cells.slice().sort((a, b) => a.week - b.week || a.weekday - b.weekday)) {
         const cellDate = parseIsoDate(cell.date);
-        const month = cellDate.getUTCMonth();
-        if (cell.weekday === 0 && month !== lastMonth) {
-            lastMonth = month;
-            monthLabels.push({
-                week: cell.week,
-                label: cellDate.toLocaleString('en', { month: 'short', timeZone: 'UTC' }),
-            });
-        }
+        const key = `${cellDate.getUTCFullYear()}-${cellDate.getUTCMonth()}`;
+        if (seenMonths.has(key))
+            continue;
+        seenMonths.add(key);
+        monthLabels.push({
+            week: cell.week,
+            label: cellDate.toLocaleString(undefined, { month: 'short', timeZone: 'UTC' }),
+        });
     }
     return { cells, weekCount, firstWeekStart, monthLabels };
 }

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

@@ -1,4 +1,4 @@
-/** Maps `value` in `[lo, hi]` to a 0.1–1.0 alpha, matching the cd-heatmap ramp. */
+/** Maps `value` in `[lo, hi]` to a 0.1-1.0 alpha so the lowest real value still reads as faintly present rather than invisible. */
 export declare function linearAlpha(value: number, lo: number, hi: number): number;
 /**
  * Computes `[min, max]` of `values` via a linear scan, or `null` for an
@@ -12,5 +12,15 @@ export declare function minMax(values: number[]): [number, number] | null;
  * Square-root-scaled bucket index in `[0, steps-1]`, or `-1` for no-data.
  * Compresses large counts so a single heavy cell doesn't wash out the rest
  * of a sequential color ramp.
+ *
+ * Only a negative `count` means "no data" here — the true no-data sentinel
+ * (`v < 0 || !Number.isFinite(v)`) is already filtered out by the caller
+ * (`drawMatrix()`) before `sqrtStep` is ever invoked, so a real `count === 0`
+ * (e.g. "zero events that day") reaches this function and must bucket to the
+ * lowest ramp step like any other legitimate value, not render as no-data.
+ * Likewise, `max <= 0` means every real value in the dataset is zero (a
+ * legitimate "zero events everywhere" dataset, not an absence of data) — the
+ * whole range collapses to a single point, so `count` (itself necessarily 0)
+ * buckets to the lowest step rather than being misread as no-data.
  */
 export declare function sqrtStep(count: number, max: number, steps: number): number;

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

@@ -1,4 +1,4 @@
-/** Maps `value` in `[lo, hi]` to a 0.1–1.0 alpha, matching the cd-heatmap ramp. */
+/** Maps `value` in `[lo, hi]` to a 0.1-1.0 alpha so the lowest real value still reads as faintly present rather than invisible. */
 export function linearAlpha(value, lo, hi) {
     const span = hi - lo || 1;
     const t = (value - lo) / span;
@@ -29,10 +29,22 @@ export function minMax(values) {
  * Square-root-scaled bucket index in `[0, steps-1]`, or `-1` for no-data.
  * Compresses large counts so a single heavy cell doesn't wash out the rest
  * of a sequential color ramp.
+ *
+ * Only a negative `count` means "no data" here — the true no-data sentinel
+ * (`v < 0 || !Number.isFinite(v)`) is already filtered out by the caller
+ * (`drawMatrix()`) before `sqrtStep` is ever invoked, so a real `count === 0`
+ * (e.g. "zero events that day") reaches this function and must bucket to the
+ * lowest ramp step like any other legitimate value, not render as no-data.
+ * Likewise, `max <= 0` means every real value in the dataset is zero (a
+ * legitimate "zero events everywhere" dataset, not an absence of data) — the
+ * whole range collapses to a single point, so `count` (itself necessarily 0)
+ * buckets to the lowest step rather than being misread as no-data.
  */
 export function sqrtStep(count, max, steps) {
-    if (count <= 0 || max <= 0)
+    if (count < 0)
         return -1;
+    if (max <= 0)
+        return 0;
     const ratio = Math.sqrt(count) / Math.sqrt(max);
     return Math.min(steps - 1, Math.floor(ratio * steps));
 }