@aceshooting/lyra-ui 2.0.0 → 2.2.0

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

@@ -0,0 +1,167 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../skeleton/skeleton.class.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;
+}
+export interface GraphLink {
+    source: string;
+    target: string;
+    width?: number;
+}
+/**
+ * `<lyra-graph>` — a force-directed node-link diagram with pan/zoom/drag.
+ * 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`. `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 - 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 interface LyraGraphEventMap {
+    'lyra-node-click': CustomEvent<{
+        id: string;
+    }>;
+    'lyra-link-click': CustomEvent<{
+        source: string;
+        target: string;
+    }>;
+}
+export declare class LyraGraph extends LyraElement<LyraGraphEventMap> {
+    static styles: import("lit").CSSResultGroup[];
+    nodes: GraphNode[];
+    links: GraphLink[];
+    width: number;
+    height: number;
+    chargeStrength: number;
+    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().
+     *  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
+     *  full rebuildSimulation(). */
+    private chargeForce?;
+    private linkForce?;
+    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;
+    /** Node/link/label DOM elements, index-aligned with simNodes/simLinks, cached
+     *  once per structural rebuild and written to directly by onTick() — this is
+     *  what lets ticks update positions without going through Lit's reactive
+     *  simNodes/simLinks properties (see rebuildSimulation()'s doc comment). */
+    private nodeEls;
+    private nodeLabelEls;
+    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;
+    /**
+     * Imperatively wires up d3-zoom (pan/zoom on the `<svg>`) and d3-drag
+     * (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 `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;
+    private onNodeClick;
+    private onLinkClick;
+    private graphItemCount;
+    private normalizedGraphItem;
+    private graphItemText;
+    private onGraphItemFocus;
+    private focusGraphItem;
+    private onGraphKeyDown;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-graph': LyraGraph;
+    }
+}
+//# sourceMappingURL=graph.class.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph.class.d.ts","sourceRoot":"","sources":["../../../src/components/graph/graph.class.ts"],"names":[],"mappings":"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"}