@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/generation-status/generation-status.d.ts

@@ -71,10 +71,11 @@ export declare class LyraGenerationStatus extends LyraElement {
     /** Whether generation is currently in progress. The elapsed-time ticker
      *  runs only while this is `true` (see the class doc). */
     active: boolean;
-    /** Epoch-ms timestamp of when generation began. Optional -- when unset
-     *  while `active` is `true`, this component captures the current time
-     *  itself the moment `active` becomes `true` and counts from there instead
-     *  (see the class doc). */
+    /** Epoch-ms timestamp of when generation began. Optional -- when unset (or
+     *  when set to a value that fails to parse as a finite number, e.g. an
+     *  ISO-8601 date string) while `active` is `true`, this component captures
+     *  the current time itself the moment `active` becomes `true` and counts
+     *  from there instead (see the class doc). */
     startedAt?: number;
     /** Running token count so far. Omitted from the readout entirely (no
      *  `tokens` segment) while unset. */
@@ -84,16 +85,23 @@ export declare class LyraGenerationStatus extends LyraElement {
      *  itself once one is available -- see the class doc for the exact rule
      *  and why. */
     tokensPerSecond?: number;
-    /** Whether the built-in Stop button renders at all. */
+    /** Whether the built-in Stop button renders at all. Defaults to `true`.
+     *  Uses {@link showStopConverter} rather than Lit's default presence-based
+     *  `type: Boolean` handling, so a plain-HTML consumer with no way to write
+     *  a `.showStop` property binding can still turn this off with
+     *  `show-stop="false"`; a Lit template can do the same with either that
+     *  attribute string or a `.showStop=${false}` property binding. */
     showStop: boolean;
     private elapsedMs;
     private tickTimer?;
     private fallbackStartMs?;
+    connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     private startTicker;
     private stopTicker;
+    private get validStartedAt();
     private computeElapsedMs;
     /** `tokens-per-second` when set; otherwise a derived figure once enough
      *  elapsed time has accumulated for it to be meaningful; otherwise

package/dist/components/generation-status/generation-status.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { html, nothing, svg } from 'lit';
+import { html, nothing, svg, } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
@@ -71,6 +71,29 @@ function formatThroughput(value) {
     const rounded = clamped < 10 ? Math.round(clamped * 10) / 10 : Math.round(clamped);
     return `${rounded} tok/s`;
 }
+/**
+ * String-aware boolean attribute converter for `show-stop`. Lit's built-in
+ * `type: Boolean` converter is presence-based -- the attribute's mere
+ * presence (regardless of its string value) maps to `true`, so a plain-
+ * markup consumer writing the literal `show-stop="false"` would actually get
+ * the button *shown*, the opposite of what that string reads as (the same
+ * bug class `<lyra-streaming-text>`'s `optionalBooleanConverter` and
+ * `<lyra-line-chart>`'s `WithoutBeginAtZero` story both document). Unlike
+ * `<lyra-streaming-text>`'s tri-state converter, this property's default is
+ * `true`, not "unset" -- so this one only needs two states: attribute absent
+ * (or removed) -> `true` (the default); `show-stop="false"` -> `false`;
+ * anything else present (no value, `="true"`, ...) -> `true`.
+ */
+const showStopConverter = {
+    fromAttribute(value) {
+        return value !== 'false';
+    },
+    toAttribute(value) {
+        // `true` is this property's default, so there's nothing worth reflecting
+        // for it; only the non-default `false` needs an attribute at all.
+        return value ? null : 'false';
+    },
+};
 /**
  * `<lyra-generation-status>` — a compact, ticking status readout shown
  * alongside an in-progress AI response: elapsed time, token count, and
@@ -143,7 +166,12 @@ export class LyraGenerationStatus extends LyraElement {
         /** Whether generation is currently in progress. The elapsed-time ticker
          *  runs only while this is `true` (see the class doc). */
         this.active = false;
-        /** Whether the built-in Stop button renders at all. */
+        /** Whether the built-in Stop button renders at all. Defaults to `true`.
+         *  Uses {@link showStopConverter} rather than Lit's default presence-based
+         *  `type: Boolean` handling, so a plain-HTML consumer with no way to write
+         *  a `.showStop` property binding can still turn this off with
+         *  `show-stop="false"`; a Lit template can do the same with either that
+         *  attribute string or a `.showStop=${false}` property binding. */
         this.showStop = true;
         // Recomputed on activation and on every ~1s tick; frozen (not reset) once
         // `active` goes false -- see the class doc's "ticker" paragraph.
@@ -153,6 +181,21 @@ export class LyraGenerationStatus extends LyraElement {
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
+    // A re-parenting host (e.g. a virtualized/reordering list) disconnects and
+    // reconnects this element without ever toggling `active` -- `willUpdate`/
+    // `updated` only react to *changes* of `active`, so with no override here
+    // a still-active element would come back with `disconnectedCallback`'s
+    // cleared ticker never restarted, freezing the readout even though
+    // `active` (still `true`) says generation is ongoing. Restarting from
+    // `computeElapsedMs()` (rather than resuming a stale in-flight interval)
+    // matches how `startTicker()` already re-baselines on every fresh start.
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.active) {
+            this.elapsedMs = this.computeElapsedMs();
+            this.startTicker();
+        }
+    }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.stopTicker();
@@ -175,7 +218,7 @@ export class LyraGenerationStatus extends LyraElement {
     // first-update special case needed.
     willUpdate(changed) {
         if (changed.has('active') && this.active) {
-            if (this.startedAt == null)
+            if (this.validStartedAt == null)
                 this.fallbackStartMs = Date.now();
             this.elapsedMs = this.computeElapsedMs();
         }
@@ -214,8 +257,19 @@ export class LyraGenerationStatus extends LyraElement {
             this.tickTimer = undefined;
         }
     }
+    // `startedAt` is host-supplied and, unlike `tokenCount`/`tokensPerSecond`
+    // (both already guarded at their read sites), had no `Number.isFinite`
+    // check of its own -- a non-numeric `started-at` attribute (e.g. an
+    // ISO-8601 date string that failed the `type: Number` conversion, landing
+    // as `NaN`) would flow straight into `Date.now() - start`, permanently
+    // rendering the literal text "NaNm NaNs" with no fallback or recovery.
+    // Treating an invalid value the same as "unset" here restores this
+    // property's own documented fallback-clock behavior instead.
+    get validStartedAt() {
+        return this.startedAt != null && Number.isFinite(this.startedAt) ? this.startedAt : undefined;
+    }
     computeElapsedMs() {
-        const start = this.startedAt ?? this.fallbackStartMs;
+        const start = this.validStartedAt ?? this.fallbackStartMs;
         return start == null ? 0 : Math.max(0, Date.now() - start);
     }
     /** `tokens-per-second` when set; otherwise a derived figure once enough
@@ -265,7 +319,7 @@ __decorate([
     property({ type: Number, attribute: 'tokens-per-second' })
 ], LyraGenerationStatus.prototype, "tokensPerSecond", void 0);
 __decorate([
-    property({ type: Boolean, attribute: 'show-stop' })
+    property({ attribute: 'show-stop', converter: showStopConverter })
 ], LyraGenerationStatus.prototype, "showStop", void 0);
 __decorate([
     state()

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,17 +6,26 @@ 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
@@ -28,7 +37,7 @@ export declare function parseIsoDate(iso: string): Date;
  * 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

@@ -12,9 +12,13 @@ function isCalendarValid(iso, parsed) {
     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
@@ -26,7 +30,7 @@ function isCalendarValid(iso, parsed) {
  * 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()) && isCalendarValid(d.date, d.dateObj));
@@ -35,9 +39,16 @@ export function buildCalendarGrid(days) {
     }
     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 };

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
@@ -18,5 +18,9 @@ export declare function minMax(values: number[]): [number, number] | null;
  * (`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;
@@ -35,10 +35,16 @@ export function minMax(values) {
  * (`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));
 }