@aceshooting/lyra-ui 1.0.1 → 1.2.0

package/dist/components/flag/flag.js

@@ -9,31 +9,50 @@ import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { styles } from './flag.styles.js';
-import { languageToCountry } from './language-map.js';
+import { ALPHA2_RE, languageToCountry } from './language-map.js';
 import '../skeleton/skeleton.js';
 /**
- * ISO 3166-1 alpha-2 country code: exactly two letters, case-insensitive.
- * The peer package `@aceshooting/lyra-flags` naively interpolates its `code`
- * argument into a `new URL('./flags/${code}.svg', ...)` with no validation
- * of its own — an unvalidated `country` containing `../` segments (e.g.
- * `../../etc`) can escape the intended flags/ directory. Anything that
- * doesn't match this shape is treated the same as an unknown/missing flag.
+ * Resolves the optional peer dependency `@aceshooting/lyra-flags`'s `flagUrl`
+ * via the given importer (a real dynamic import by default). Uncached and
+ * dependency-injectable — unlike `loadFlagUrlResolver()` below — so the
+ * caught-error warning path is directly testable without needing to
+ * actually uninstall the package.
  */
-const COUNTRY_CODE_RE = /^[a-z]{2}$/i;
+export async function loadFlagUrl(importFlags = () => import('@aceshooting/lyra-flags')) {
+    try {
+        return (await importFlags()).flagUrl;
+    }
+    catch {
+        console.warn("<lyra-flag> needs the optional peer dependency '@aceshooting/lyra-flags' to render " +
+            'flag images — install it with `pnpm add @aceshooting/lyra-flags`.');
+        return null;
+    }
+}
+/**
+ * Resolves an ISO 3166-1 alpha-2 region code to a human-readable, localized
+ * display name (e.g. `'FR'` -> `'France'`) via `Intl.DisplayNames`, for use as
+ * the default accessible name (`alt`) instead of a bare code read
+ * letter-by-letter by most screen readers. Falls back to the uppercase code
+ * itself if `Intl.DisplayNames` throws (unrecognized region) or isn't
+ * available in the current runtime.
+ */
+function displayNameFor(code) {
+    try {
+        return new Intl.DisplayNames([navigator.language], { type: 'region' }).of(code.toUpperCase()) ?? code.toUpperCase();
+    }
+    catch {
+        return code.toUpperCase();
+    }
+}
 let flagUrlResolver;
 /**
  * Lazily loads the optional peer dependency '@aceshooting/lyra-flags' once per
- * page. Resolves to `null` (with a one-time warning) if it isn't installed.
+ * page. Resolves to `null` (with a one-time warning, see `loadFlagUrl()`) if
+ * it isn't installed.
  */
 function loadFlagUrlResolver() {
     if (!flagUrlResolver) {
-        flagUrlResolver = import('@aceshooting/lyra-flags')
-            .then((mod) => mod.flagUrl)
-            .catch(() => {
-            console.warn("<lyra-flag> needs the optional peer dependency '@aceshooting/lyra-flags' to render " +
-                'flag images — install it with `pnpm add @aceshooting/lyra-flags`.');
-            return null;
-        });
+        flagUrlResolver = loadFlagUrl();
     }
     return flagUrlResolver;
 }
@@ -43,11 +62,29 @@ function loadFlagUrlResolver() {
  * Flag images are shipped by the optional peer package `@aceshooting/lyra-flags`,
  * not bundled into lyra-ui itself, so importing the core library pulls zero flag
  * weight. Give it a `country` (ISO 3166-1 alpha-2) or a `language` tag (mapped to
- * a representative country).
+ * a representative country). While that peer package's `flagUrl()` resolves (or
+ * if it isn't installed), the host carries `aria-busy="true"` and a skeleton
+ * placeholder renders in its place.
+ *
+ * **Bundle-size note:** `country`/`language` resolve through the peer package's
+ * `flagUrl(code)`, which is itself genuinely code-split per flag (see that
+ * package's docs) — using `<lyra-flag country="fr">` anywhere in an app ships
+ * only the flags actually requested at runtime, not all 249. If you already
+ * have a flag's URL at build time (e.g. from your own literal
+ * `import frUrl from '@aceshooting/lyra-flags/flags/fr.svg?url'`), pass it as
+ * `src` instead to skip the peer-package round trip (and its loading-skeleton
+ * flash) entirely.
+ *
+ * A handful of flags (e.g. `es`, `pt` — any whose design includes a detailed coat of
+ * arms/seal/emblem) ship a second, full-detail source SVG alongside the default icon-optimized
+ * one; set `detailed` to request it (e.g. for a hero-scale display where the extra illustrative
+ * detail is actually visible). A no-op for every other code — see `detailed`'s own doc.
  *
  * @customElement lyra-flag
  * @example <lyra-flag country="fr"></lyra-flag>
  * @example <lyra-flag language="en" label="English"></lyra-flag>
+ * @example <lyra-flag src=${frUrl} label="French"></lyra-flag>
+ * @example <lyra-flag country="es" detailed></lyra-flag>
  * @csspart image - The underlying <img>.
  */
 export class LyraFlag extends LyraElement {
@@ -55,13 +92,30 @@ export class LyraFlag extends LyraElement {
         super(...arguments);
         /** Render as a circular flag. */
         this.round = false;
+        /**
+         * Requests the pristine, full-detail source SVG instead of the default icon-optimized one —
+         * only meaningful for the minority of `country`/`language` codes whose source art was large
+         * enough to need optimizing (e.g. `es`, `pt`, a national coat of arms/seal/emblem); for every
+         * other code this is a safe no-op (the default and detailed variants are the same file). Has no
+         * effect when `src` is set — a pre-resolved URL is used as-is regardless. Intended for rendering
+         * a flag larger than icon scale (e.g. a hero display) where the extra illustrative detail is
+         * actually visible.
+         */
+        this.detailed = false;
         /** True while the lazy-loaded `@aceshooting/lyra-flags` peer resolver is in flight. */
         this.loading = true;
+        /**
+         * Bumped on every `willUpdate` pass; captured by each in-flight resolver
+         * `.then()` so a resolution for a `country`/`language` that's since changed
+         * (or been cleared) can recognize itself as stale and no-op instead of
+         * overwriting newer state.
+         */
+        this.resolveToken = 0;
     }
     static { this.styles = [LyraElement.styles, styles]; }
     get code() {
         if (this.country) {
-            return COUNTRY_CODE_RE.test(this.country) ? this.country.toLowerCase() : undefined;
+            return ALPHA2_RE.test(this.country) ? this.country.toLowerCase() : undefined;
         }
         if (this.language)
             return languageToCountry(this.language);
@@ -69,22 +123,37 @@ export class LyraFlag extends LyraElement {
     }
     willUpdate(changed) {
         // `this.hasUpdated` (not just `changed`) forces this body to run once on
-        // the very first update even when neither `country` nor `language` is
+        // the very first update even when none of `country`/`language`/`src` is
         // ever set: an unset optional property's first "assignment" is
-        // undefined -> undefined (no-op to Lit), so `changed.has('country')`
-        // would otherwise never become true for a `<lyra-flag>` that never
-        // receives a code, leaving `loading` stuck at its initial `true` forever.
-        if (this.hasUpdated && !changed.has('country') && !changed.has('language'))
+        // undefined -> undefined (no-op to Lit), so none of `changed.has(...)`
+        // would otherwise ever become true for a `<lyra-flag>` that never
+        // receives one, leaving `loading` stuck at its initial `true` forever.
+        if (this.hasUpdated &&
+            !changed.has('country') &&
+            !changed.has('language') &&
+            !changed.has('src') &&
+            !changed.has('detailed')) {
             return;
+        }
+        const token = ++this.resolveToken; // invalidates any in-flight peer resolution either way
+        if (this.src) {
+            this.resolvedSrc = undefined;
+            this.loading = false;
+            return;
+        }
         const code = this.code;
         if (!code) {
-            this.src = undefined;
+            this.resolvedSrc = undefined;
             this.loading = false;
             return;
         }
         this.loading = true;
-        void loadFlagUrlResolver().then((resolve) => {
-            this.src = resolve?.(code);
+        void loadFlagUrlResolver()
+            .then((resolve) => resolve?.(code, this.detailed ? { variant: 'detailed' } : undefined))
+            .then((url) => {
+            if (token !== this.resolveToken)
+                return; // superseded by a later country/language/src change
+            this.resolvedSrc = url;
             this.loading = false;
         });
     }
@@ -97,10 +166,12 @@ export class LyraFlag extends LyraElement {
     render() {
         if (this.loading)
             return html `<lyra-skeleton variant="rect"></lyra-skeleton>`;
-        if (!this.src)
+        const url = this.src ?? this.resolvedSrc;
+        if (!url)
             return html ``;
-        const alt = this.label ?? (this.code ?? '').toUpperCase();
-        return html `<img part="image" src=${this.src} alt=${alt} loading="lazy" decoding="async" />`;
+        const code = this.code;
+        const alt = this.label ?? (code ? displayNameFor(code) : '');
+        return html `<img part="image" src=${url} alt=${alt} loading="lazy" decoding="async" />`;
     }
 }
 __decorate([
@@ -109,15 +180,21 @@ __decorate([
 __decorate([
     property()
 ], LyraFlag.prototype, "language", void 0);
+__decorate([
+    property()
+], LyraFlag.prototype, "src", void 0);
 __decorate([
     property()
 ], LyraFlag.prototype, "label", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraFlag.prototype, "round", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraFlag.prototype, "detailed", void 0);
 __decorate([
     state()
-], LyraFlag.prototype, "src", void 0);
+], LyraFlag.prototype, "resolvedSrc", void 0);
 __decorate([
     state()
 ], LyraFlag.prototype, "loading", void 0);

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

@@ -3,3 +3,4 @@ declare const meta: Meta;
 export default meta;
 type Story = StoryObj;
 export declare const Gallery: Story;
+export declare const DetailedVariant: Story;

package/dist/components/flag/flag.stories.js

@@ -15,3 +15,17 @@ export const Gallery = {
     </div>
   `,
 };
+export const DetailedVariant = {
+    render: () => html `
+    <div style="display:flex; gap:2rem; align-items:center;">
+      <div style="display:flex; flex-direction:column; align-items:center; gap:0.5rem;">
+        <lyra-flag country="es" label="Spain (default, icon-optimized)" style="height: 6rem"></lyra-flag>
+        <span>default</span>
+      </div>
+      <div style="display:flex; flex-direction:column; align-items:center; gap:0.5rem;">
+        <lyra-flag country="es" detailed label="Spain (detailed)" style="height: 6rem"></lyra-flag>
+        <span>detailed</span>
+      </div>
+    </div>
+  `,
+};

package/dist/components/flag/flag.styles.js

@@ -12,7 +12,7 @@ export const styles = css `
     block-size: 100%;
     inline-size: 100%;
     border-radius: var(--lyra-flag-radius, 2px);
-    box-shadow: 0 0 0 1px rgb(0 0 0 / 0.08) inset;
+    box-shadow: 0 0 0 1px var(--lyra-color-border) inset;
     object-fit: cover;
   }
   :host([round]) {

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;