@aceshooting/lyra-ui 1.0.1 → 1.2.0

package/dist/components/graph/graph.js

@@ -10,38 +10,39 @@ import { styleMap } from 'lit/directives/style-map.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { styles } from './graph.styles.js';
+import { loadD3 } from './graph-loader.js';
 import '../skeleton/skeleton.js';
-let d3Modules;
+function prefersReducedMotion() {
+    return typeof window !== 'undefined' && !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+}
 /**
- * Lazily loads the optional peer dependencies `d3-force`/`d3-drag`/`d3-zoom`/
- * `d3-selection` once per page. Resolves to `null` (with a one-time warning)
- * if they aren't installed — mirrors `<lyra-flag>`'s peer-dependency pattern.
+ * Tiny deterministic PRNG (mulberry32, public-domain) used only when `seed`
+ * is set, so a node's initial x/y is reproducible instead of whatever
+ * forceSimulation() would otherwise randomize it to. This is the whole
+ * algorithm — not worth a dependency for.
  */
-function loadD3() {
-    if (!d3Modules) {
-        d3Modules = Promise.all([
-            import('d3-force'),
-            import('d3-drag'),
-            import('d3-zoom'),
-            import('d3-selection'),
-        ])
-            .then(([force, dragMod, zoomMod, selectionMod]) => ({
-            forceSimulation: force.forceSimulation,
-            forceLink: force.forceLink,
-            forceManyBody: force.forceManyBody,
-            forceCenter: force.forceCenter,
-            forceCollide: force.forceCollide,
-            drag: dragMod.drag,
-            zoom: zoomMod.zoom,
-            select: selectionMod.select,
-        }))
-            .catch(() => {
-            console.warn('<lyra-graph> needs the optional peer dependencies `d3-force`, `d3-drag`, ' +
-                '`d3-zoom`, and `d3-selection` — install them with `pnpm add d3-force d3-drag d3-zoom d3-selection`.');
-            return null;
-        });
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), a | 1);
+        t = (t + Math.imul(t ^ (t >>> 7), t | 61)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Derives a per-node mulberry32 seed from the component's `seed` and the
+ * node's **id** — hashing by id (a simple FNV-1a-style mix), not by the
+ * node's index in `nodes`, is what keeps a seeded layout reproducible no
+ * matter how a caller orders/reorders the `nodes` array between renders.
+ */
+function hashNodeSeed(seed, id) {
+    let h = seed >>> 0;
+    for (let i = 0; i < id.length; i++) {
+        h = Math.imul(h ^ id.charCodeAt(i), 2654435761);
+        h ^= h >>> 15;
     }
-    return d3Modules;
+    return h >>> 0;
 }
 const MIN_RADIUS = 6;
 const MAX_RADIUS = 24;
@@ -64,6 +65,10 @@ function sanitizeNodeColor(color) {
  * Requires the optional peer deps `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection`
  * (lazy-loaded; a consumer who never uses this component pays zero d3 cost).
  *
+ * 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`.
+ *
  * @customElement lyra-graph
  * @event lyra-node-click - `detail: { id }`.
  * @event lyra-link-click - `detail: { source, target }`.
@@ -84,8 +89,6 @@ export class LyraGraph extends LyraElement {
         this.loading = true;
         this.simNodes = [];
         this.simLinks = [];
-        /** Current pan/zoom transform (SVG `transform` attribute syntax), driven by d3-zoom. */
-        this.transform = '';
         /** 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();
@@ -137,11 +140,15 @@ export class LyraGraph extends LyraElement {
         if (!this.d3)
             return;
         if (!changed.has('nodes') && !changed.has('links')) {
+            // These two branches are independent (not else-if): a consumer can set
+            // width/height and chargeStrength/linkDistance in the same reactive
+            // update batch, and both retunes must apply — not just whichever branch
+            // happens to come first.
             if (changed.has('width') || changed.has('height')) {
                 this.simulation?.force('center', this.d3.forceCenter(this.width / 2, this.height / 2));
                 this.simulation?.alpha(0.1).restart();
             }
-            else if (changed.has('chargeStrength') || changed.has('linkDistance')) {
+            if (changed.has('chargeStrength') || changed.has('linkDistance')) {
                 // Without this branch, chargeStrength/linkDistance only took effect
                 // the next time nodes/links also changed (rebuildSimulation() reads
                 // them fresh) — retune the already-created force objects in place
@@ -157,35 +164,48 @@ export class LyraGraph extends LyraElement {
         // rebuildSimulation()'s doc comment) — never on a tick — so gating the
         // node/link querySelectorAll scan on that is equivalent to "structurally
         // changed" without needing a separate flag.
-        this.applyInteractions(changed.has('simNodes') || changed.has('simLinks'));
+        this.applyInteractions(changed);
     }
     /**
      * Imperatively wires up d3-zoom (pan/zoom on the `<svg>`) and d3-drag
-     * (per-node drag) against the just-rendered DOM. The zoom bind is a
-     * one-time no-op guard (`zoomedEl`); the node-drag bind + node/link/label
-     * element caching for `onTick()` only run when `structural` is true (a
-     * fresh structural render just happened), not on every call — otherwise
-     * this would re-scan the DOM via `querySelectorAll` on every Lit update,
-     * which used to include every single simulation tick. `<circle>`s already
-     * bound are skipped (`boundNodeEls`) — a WeakSet reset on every
-     * `rebuildSimulation()` so DOM nodes Lit reuses across a rebuild get
-     * rebound against their new datum instead of a stale one.
+     * (per-node drag) against the just-rendered DOM. The zoom bind itself is a
+     * one-time guard (`zoomedEl`) — but the bound `zoomBehavior`'s
+     * `scaleExtent` is re-read from `minZoom`/`maxZoom` on every call so a
+     * post-mount change to either still takes effect. The node-drag bind +
+     * node/link/label element caching for `onTick()` only run when
+     * `changed` indicates a fresh structural render just happened, not on
+     * every call — otherwise this would re-scan the DOM via
+     * `querySelectorAll` on every Lit update, which used to include every
+     * single simulation tick. `<circle>`s already bound are skipped
+     * (`boundNodeEls`) — a WeakSet reset on every `rebuildSimulation()` so DOM
+     * nodes Lit reuses across a rebuild get rebound against their new datum
+     * instead of a stale one. The zoom handler writes the resulting transform
+     * straight to the cached `gEl` (bound once alongside `zoomedEl`, since the
+     * outer `<g>` is a static part of the template and never recreated by Lit)
+     * instead of assigning a Lit reactive property — panning/zooming fires
+     * continuously while dragging, and reassigning a `@state()` there would
+     * force a full re-render (recomputing every node/link template) on every
+     * single event, the same class of cost `onTick()` already avoids for ticks.
      */
-    applyInteractions(structural) {
+    applyInteractions(changed) {
         if (!this.d3)
             return;
         const svgEl = this.renderRoot.querySelector('svg');
         if (svgEl && svgEl !== this.zoomedEl) {
             this.zoomedEl = svgEl;
-            const zoomBehavior = this.d3
+            this.gEl = this.renderRoot.querySelector('g') ?? undefined;
+            this.zoomBehavior = this.d3
                 .zoom()
                 .scaleExtent([this.minZoom, this.maxZoom])
                 .on('zoom', (event) => {
-                this.transform = event.transform.toString();
+                this.gEl?.setAttribute('transform', event.transform.toString());
             });
-            this.d3.select(svgEl).call(zoomBehavior);
+            this.d3.select(svgEl).call(this.zoomBehavior);
         }
-        if (!structural)
+        else if (this.zoomBehavior && (changed.has('minZoom') || changed.has('maxZoom'))) {
+            this.zoomBehavior.scaleExtent([this.minZoom, this.maxZoom]);
+        }
+        if (!(changed.has('simNodes') || changed.has('simLinks')))
             return;
         const nodeEls = Array.from(this.renderRoot.querySelectorAll('[part="node"]'));
         this.nodeEls = nodeEls;
@@ -223,24 +243,25 @@ export class LyraGraph extends LyraElement {
      * Runs on every d3-force simulation tick (up to ~300 while a graph settles
      * on load, continuously while a node is being dragged via
      * `alphaTarget(0.3)`). Writes positions straight to the already-rendered
-     * DOM via direct d3-selection `.attr()` calls instead of reassigning the
-     * reactive `simNodes`/`simLinks` properties, which would force a full Lit
-     * re-render (and, before the `structural` gate above, an unconditional
-     * `querySelectorAll` scan) on every single frame.
+     * DOM via `setAttribute()` instead of reassigning the reactive
+     * `simNodes`/`simLinks` properties, which would force a full Lit re-render
+     * (and, before the structural-render gate in `applyInteractions()`, an
+     * unconditional `querySelectorAll` scan) on every single frame. Writing attributes
+     * directly (rather than wrapping each element in a d3 selection just to
+     * call `.attr()`) avoids allocating a throwaway Selection per element on
+     * this component's highest-frequency code path.
      */
     onTick() {
-        if (!this.d3)
-            return;
-        const d3 = this.d3;
         this.simNodes.forEach((n, i) => {
             const circle = this.nodeEls[i];
-            if (circle)
-                d3.select(circle).attr('cx', n.x ?? 0).attr('cy', n.y ?? 0);
+            if (circle) {
+                circle.setAttribute('cx', String(n.x ?? 0));
+                circle.setAttribute('cy', String(n.y ?? 0));
+            }
             const label = this.nodeLabelEls[i];
             if (label) {
-                d3.select(label)
-                    .attr('x', (n.x ?? 0) + this.nodeRadius(n) + 2)
-                    .attr('y', n.y ?? 0);
+                label.setAttribute('x', String((n.x ?? 0) + this.nodeRadius(n) + 2));
+                label.setAttribute('y', String(n.y ?? 0));
             }
         });
         this.simLinks.forEach((l, i) => {
@@ -249,11 +270,10 @@ export class LyraGraph extends LyraElement {
                 return;
             const source = l.source;
             const target = l.target;
-            d3.select(line)
-                .attr('x1', source.x ?? 0)
-                .attr('y1', source.y ?? 0)
-                .attr('x2', target.x ?? 0)
-                .attr('y2', target.y ?? 0);
+            line.setAttribute('x1', String(source.x ?? 0));
+            line.setAttribute('y1', String(source.y ?? 0));
+            line.setAttribute('x2', String(target.x ?? 0));
+            line.setAttribute('y2', String(target.y ?? 0));
         });
     }
     rebuildSimulation() {
@@ -261,20 +281,61 @@ export class LyraGraph extends LyraElement {
             return;
         this.simulation?.stop();
         this.boundNodeEls = new WeakSet();
-        const nodes = this.nodes.map((n) => ({ ...n }));
+        // Carry over each existing SimNode's settled position/velocity (and any
+        // in-progress drag fx/fy) by id instead of starting every node fresh —
+        // otherwise any structural nodes/links change (e.g. appending one new
+        // node to a live/streaming graph) would discard every already-settled
+        // node's (x, y) and restart the whole force layout's ~300-tick random-
+        // start settle animation from scratch. Only nodes with no previous
+        // counterpart (genuinely new ids) get forceSimulation()'s default
+        // fresh random start below.
+        const prevById = new Map(this.simNodes.map((n) => [n.id, n]));
+        const nodes = this.nodes.map((n) => {
+            const prev = prevById.get(n.id);
+            return prev ? { ...prev, ...n } : { ...n };
+        });
         const byId = new Map(nodes.map((n) => [n.id, n]));
         const links = this.links
             .filter((l) => byId.has(l.source) && byId.has(l.target))
             .map((l) => ({ ...l, source: byId.get(l.source), target: byId.get(l.target) }));
+        // Give brand-new nodes (no carried-over position from prevById above) a
+        // deterministic starting x/y, keyed by node id, instead of leaving them
+        // for forceSimulation() below to randomize. Nodes that already have a
+        // position are left untouched — same "only randomize nodes without x/y"
+        // rule forceSimulation() itself follows — so an incremental update to a
+        // seeded, already-settled graph doesn't reshuffle existing nodes.
+        const seed = this.seed;
+        if (seed != null) {
+            for (const n of nodes) {
+                if (n.x != null && n.y != null)
+                    continue;
+                const rng = mulberry32(hashNodeSeed(seed, n.id));
+                n.x = rng() * this.width;
+                n.y = rng() * this.height;
+            }
+        }
         this.linkForce = this.d3.forceLink(links).distance(this.linkDistance);
         this.chargeForce = this.d3.forceManyBody().strength(this.chargeStrength);
-        this.simulation = this.d3
+        const simulation = this.d3
             .forceSimulation(nodes)
             .force('link', this.linkForce)
             .force('charge', this.chargeForce)
             .force('center', this.d3.forceCenter(this.width / 2, this.height / 2))
             .force('collide', this.d3.forceCollide().radius((n) => this.nodeRadius(n) + 10))
             .on('tick', () => this.onTick());
+        this.simulation = simulation;
+        if (prefersReducedMotion() || this.seed != null) {
+            // Converge synchronously instead of animating the settle over ~300
+            // rendered frames — the simulation is already stopped (alpha at
+            // alphaMin) by the time the DOM for this rebuild is first painted.
+            // A seed converging synchronously (not just deterministically-seeded)
+            // is what makes its end state reproducible: two runs must agree on the
+            // exact same number of ticks, not merely start from the same x/y.
+            // User-initiated motion (dragging a node) is unaffected.
+            simulation.stop();
+            while (simulation.alpha() > simulation.alphaMin())
+                simulation.tick();
+        }
         // Assign these SAME array/object references (not copies) exactly once
         // for this structural rebuild: forceSimulation(nodes) above already
         // initialized their .x/.y synchronously, so this one Lit re-render
@@ -307,19 +368,33 @@ export class LyraGraph extends LyraElement {
         }
         return html `
       <div part="base">
-        <svg part="svg" viewBox="0 0 ${this.width} ${this.height}">
-          <g transform=${this.transform}>
+        <svg
+          part="svg"
+          role="group"
+          aria-label="Node-link diagram with ${this.simNodes.length} nodes and ${this.simLinks.length} links"
+          viewBox="0 0 ${this.width} ${this.height}"
+        >
+          <g transform="">
             ${this.simLinks.map((l) => {
             const source = l.source;
             const target = l.target;
             return svg `<line
                 part="link"
+                role="button"
+                tabindex="0"
+                aria-label="Link from ${source.label ?? source.id} to ${target.label ?? target.id}"
                 stroke-width=${l.width ?? 1.5}
                 x1=${source.x ?? 0}
                 y1=${source.y ?? 0}
                 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);
+                }
+            }}
               ></line>`;
         })}
             ${this.simNodes.map((n) => {
@@ -343,7 +418,7 @@ export class LyraGraph extends LyraElement {
             }}
                 ></circle>
                 ${n.label
-                ? svg `<text part="label" x=${(n.x ?? 0) + this.nodeRadius(n) + 2} y=${n.y ?? 0}>${n.label}</text>`
+                ? svg `<text part="label" aria-hidden="true" x=${(n.x ?? 0) + this.nodeRadius(n) + 2} y=${n.y ?? 0}>${n.label}</text>`
                 : ''}
               </g>`;
         })}
@@ -377,6 +452,9 @@ __decorate([
 __decorate([
     property({ type: Number, attribute: 'max-zoom' })
 ], LyraGraph.prototype, "maxZoom", void 0);
+__decorate([
+    property({ type: Number })
+], LyraGraph.prototype, "seed", void 0);
 __decorate([
     state()
 ], LyraGraph.prototype, "loading", void 0);
@@ -386,7 +464,4 @@ __decorate([
 __decorate([
     state()
 ], LyraGraph.prototype, "simLinks", void 0);
-__decorate([
-    state()
-], LyraGraph.prototype, "transform", void 0);
 defineElement('graph', LyraGraph);

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

@@ -3,3 +3,6 @@ declare const meta: Meta;
 export default meta;
 type Story = StoryObj;
 export declare const Default: Story;
+export declare const TunedForces: Story;
+export declare const BoundedZoom: Story;
+export declare const SeededLayout: Story;

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));
 }