@aceshooting/lyra-ui 1.0.1 → 1.1.0

package/dist/components/flag/language-map.d.ts

@@ -1,3 +1,14 @@
+/**
+ * ISO 3166-1 alpha-2 shape: exactly two ASCII letters, case-insensitive.
+ * Shared by `flag.ts` (validating `country`) and `languageToCountry` below
+ * (validating a language tag's region subtag), because both values end up
+ * passed to the peer package `@aceshooting/lyra-flags`' `flagUrl()`, which
+ * naively interpolates its `code` argument into a `new URL('./flags/${code}.svg',
+ * ...)` with no validation of its own -- an unvalidated value containing `../`
+ * segments can escape the intended flags/ directory. Anything that doesn't
+ * match this shape is treated the same as an unknown/missing flag.
+ */
+export declare const ALPHA2_RE: RegExp;
 /**
  * Default mapping from a language subtag to a representative country flag
  * (ISO 3166-1 alpha-2). Languages don't map 1:1 to countries; these are the

package/dist/components/flag/language-map.js

@@ -1,3 +1,14 @@
+/**
+ * ISO 3166-1 alpha-2 shape: exactly two ASCII letters, case-insensitive.
+ * Shared by `flag.ts` (validating `country`) and `languageToCountry` below
+ * (validating a language tag's region subtag), because both values end up
+ * passed to the peer package `@aceshooting/lyra-flags`' `flagUrl()`, which
+ * naively interpolates its `code` argument into a `new URL('./flags/${code}.svg',
+ * ...)` with no validation of its own -- an unvalidated value containing `../`
+ * segments can escape the intended flags/ directory. Anything that doesn't
+ * match this shape is treated the same as an unknown/missing flag.
+ */
+export const ALPHA2_RE = /^[a-z]{2}$/i;
 /**
  * Default mapping from a language subtag to a representative country flag
  * (ISO 3166-1 alpha-2). Languages don't map 1:1 to countries; these are the
@@ -56,7 +67,7 @@ export function languageToCountry(language) {
     const parts = language.toLowerCase().split(/[-_]/);
     const base = parts[0];
     const region = parts[1];
-    if (region && region.length === 2)
+    if (region && ALPHA2_RE.test(region))
         return region;
     return LANGUAGE_TO_COUNTRY[base];
 }

package/dist/components/gauge/gauge.d.ts

@@ -15,6 +15,8 @@ export declare class LyraGauge extends LyraElement {
     max: number;
     type: GaugeType;
     label: string;
+    /** Imperative override for the displayed/announced value text, e.g. `'72°F'` for a raw `value` of `72`.
+     * An empty string is treated the same as unset and falls back to the numeric `value`. */
     valueLabel?: string;
     private get ratio();
     protected willUpdate(): void;

package/dist/components/gauge/gauge.js

@@ -57,14 +57,28 @@ export class LyraGauge extends LyraElement {
     }
     static { this.styles = [LyraElement.styles, styles]; }
     get ratio() {
+        if (isNaN(this.value) || isNaN(this.min) || isNaN(this.max))
+            return 0;
         const span = this.max - this.min || 1;
         return Math.min(1, Math.max(0, (this.value - this.min) / span));
     }
     willUpdate() {
         this.setAttribute('role', 'meter');
-        this.setAttribute('aria-valuenow', String(this.value));
-        this.setAttribute('aria-valuemin', String(this.min));
-        this.setAttribute('aria-valuemax', String(this.max));
+        if (!isNaN(this.value) && !isNaN(this.min) && !isNaN(this.max)) {
+            const clamped = Math.min(this.max, Math.max(this.min, this.value));
+            this.setAttribute('aria-valuenow', String(clamped));
+        }
+        else {
+            this.removeAttribute('aria-valuenow');
+        }
+        if (isNaN(this.min))
+            this.removeAttribute('aria-valuemin');
+        else
+            this.setAttribute('aria-valuemin', String(this.min));
+        if (isNaN(this.max))
+            this.removeAttribute('aria-valuemax');
+        else
+            this.setAttribute('aria-valuemax', String(this.max));
         if (this.label)
             this.setAttribute('aria-label', this.label);
         else
@@ -75,7 +89,7 @@ export class LyraGauge extends LyraElement {
             this.removeAttribute('aria-valuetext');
     }
     renderRadial() {
-        const text = this.valueLabel ?? String(this.value);
+        const text = this.valueLabel || (isNaN(this.value) ? '' : String(this.value));
         // Dashoffset counts down from the full arc length (nothing revealed) to 0
         // (whole sweep revealed) as ratio goes 0 -> 1 — the classic "draw an SVG
         // path" technique, which transitions smoothly via plain CSS.
@@ -94,7 +108,7 @@ export class LyraGauge extends LyraElement {
     </svg>`;
     }
     renderLinear() {
-        const text = this.valueLabel ?? String(this.value);
+        const text = this.valueLabel || (isNaN(this.value) ? '' : String(this.value));
         const dashoffset = LINEAR_LENGTH * (1 - this.ratio);
         return html `<svg part="base" viewBox="0 0 100 20" preserveAspectRatio="none">
       <line part="track" x1="0" y1=${LINEAR_BAR_Y} x2="100" y2=${LINEAR_BAR_Y} stroke-width=${LINEAR_STROKE}></line>

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

@@ -4,3 +4,5 @@ export default meta;
 type Story = StoryObj;
 export declare const Radial: Story;
 export declare const Linear: Story;
+export declare const WithValueLabel: Story;
+export declare const NonzeroMin: Story;

package/dist/components/gauge/gauge.stories.js

@@ -11,3 +11,9 @@ export const Radial = {
 export const Linear = {
     render: () => html `<lyra-gauge type="linear" value="40" max="100" label="Disk"></lyra-gauge>`,
 };
+export const WithValueLabel = {
+    render: () => html `<lyra-gauge value="72" max="100" label="Temp" .valueLabel=${'72°F'}></lyra-gauge>`,
+};
+export const NonzeroMin = {
+    render: () => html `<lyra-gauge value="18" min="-20" max="40" label="Outdoor Temp"></lyra-gauge>`,
+};

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

@@ -0,0 +1,28 @@
+import type * as ForceModule from 'd3-force';
+import type * as DragModule from 'd3-drag';
+import type * as ZoomModule from 'd3-zoom';
+import type * as SelectionModule from 'd3-selection';
+export interface D3Modules {
+    forceSimulation: typeof ForceModule.forceSimulation;
+    forceLink: typeof ForceModule.forceLink;
+    forceManyBody: typeof ForceModule.forceManyBody;
+    forceCenter: typeof ForceModule.forceCenter;
+    forceCollide: typeof ForceModule.forceCollide;
+    drag: typeof DragModule.drag;
+    zoom: typeof ZoomModule.zoom;
+    select: typeof SelectionModule.select;
+}
+/**
+ * Resolves the optional peer dependencies `d3-force`/`d3-drag`/`d3-zoom`/
+ * `d3-selection` via the given importers (real dynamic imports by default).
+ * Uncached and dependency-injectable so both the success path and the
+ * caught-error warning path are directly testable without needing to
+ * actually uninstall any of the four packages.
+ */
+export declare function loadD3Modules(importForce?: () => Promise<typeof ForceModule>, importDrag?: () => Promise<typeof DragModule>, importZoom?: () => Promise<typeof ZoomModule>, importSelection?: () => Promise<typeof SelectionModule>): Promise<D3Modules | null>;
+/**
+ * Lazily loads the d3 peer dependencies (see `loadD3Modules()`) once per
+ * page. Resolves to `null` if they aren't installed — mirrors
+ * `<lyra-flag>`'s peer-dependency pattern.
+ */
+export declare function loadD3(): Promise<D3Modules | null>;

package/dist/components/graph/graph-loader.js

@@ -0,0 +1,44 @@
+/**
+ * Resolves the optional peer dependencies `d3-force`/`d3-drag`/`d3-zoom`/
+ * `d3-selection` via the given importers (real dynamic imports by default).
+ * Uncached and dependency-injectable so both the success path and the
+ * caught-error warning path are directly testable without needing to
+ * actually uninstall any of the four packages.
+ */
+export async function loadD3Modules(importForce = () => import('d3-force'), importDrag = () => import('d3-drag'), importZoom = () => import('d3-zoom'), importSelection = () => import('d3-selection')) {
+    try {
+        const [force, dragMod, zoomMod, selectionMod] = await Promise.all([
+            importForce(),
+            importDrag(),
+            importZoom(),
+            importSelection(),
+        ]);
+        return {
+            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 (err) {
+        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`:', err);
+        return null;
+    }
+}
+let d3Modules;
+/**
+ * Lazily loads the d3 peer dependencies (see `loadD3Modules()`) once per
+ * page. Resolves to `null` if they aren't installed — mirrors
+ * `<lyra-flag>`'s peer-dependency pattern.
+ */
+export function loadD3() {
+    if (!d3Modules) {
+        d3Modules = loadD3Modules();
+    }
+    return d3Modules;
+}

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

@@ -17,6 +17,10 @@ export interface GraphLink {
  * 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 }`.
@@ -32,12 +36,14 @@ export declare class LyraGraph extends LyraElement {
     linkDistance: number;
     minZoom: number;
     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(). */
+    seed?: number;
     /** True until the lazy-loaded d3 peer dependencies have settled (success or failure). */
     private loading;
     private simNodes;
     private simLinks;
-    /** Current pan/zoom transform (SVG `transform` attribute syntax), driven by d3-zoom. */
-    private transform;
     private simulation?;
     /** The live charge/link force objects, kept so chargeStrength/linkDistance
      *  changes can retune them in place (see updated()) instead of requiring a
@@ -47,6 +53,14 @@ export declare class LyraGraph extends LyraElement {
     private d3?;
     /** The `<svg>` currently wired up with d3-zoom (guards a one-time bind). */
     private zoomedEl?;
+    /** The pan/zoom `<g>`, cached alongside `zoomedEl` so the zoom handler can
+     *  write the transform straight to the DOM (see applyInteractions()) instead
+     *  of round-tripping through a Lit reactive property on every pan/zoom event. */
+    private gEl?;
+    /** The live zoom behavior, kept so minZoom/maxZoom changes can retune its
+     *  scaleExtent in place (see applyInteractions()) instead of requiring the
+     *  `<svg>` to be rebound. */
+    private zoomBehavior?;
     /** 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. */
     private boundNodeEls;
@@ -64,25 +78,37 @@ export declare class LyraGraph extends LyraElement {
     protected updated(changed: PropertyValues): void;
     /**
      * 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.
      */
     private applyInteractions;
     /**
      * 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.
      */
     private onTick;
     private rebuildSimulation;

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;