# `lr-graph` - **Import** `import '@aceshooting/lyra-ui/components/lr-graph.js';` (stable tag alias; registers the tag) - **Class** `LyraGraph`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js` - **Family** `components/retrieval/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecations** none - **Optional peers** `d3-drag`, `d3-force`, `d3-selection`, `d3-zoom` — see `llms/peers.md` - **Themeable via** 19 parts, 17 custom properties — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-graph` A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`. A zero-width canvas link paints neither a stroke nor an arrowhead; its relationship remains in the nonvisual topology summary. In both renderers, roving navigation transfers real focus through nodes, operable links, then community hulls; zero-width, fully transparent, and dangling links remain outside that focus order. **Properties:** - `nodes: LyraGraphNode[] = []` (attribute: false) — readonly `LyraGraphNode { id: string; label?: string; accessibleLabel?: string; description?: string; radius?: number; color?: string; type?: string; expandable?: boolean; communityId?: string }`; `accessibleLabel` supplies richer spoken text than the visible label, while `description` renders as the preferred bounded tooltip/summary text in both renderers. `radius` is clamped to `[6, 24]` (an unset/non-finite value falls back to the midpoint, `15`) so a node can never render invisibly small or absurdly large. `type` is a key into `nodeTypes` (matched by `LyraNodeTypeStyle.id`); unknown/absent renders as an untyped default circle with the token fill, but an unmatched `type` still participates in `hiddenTypes` filtering by its raw string value - `nodeTypes: LyraNodeTypeStyle[] = []` (attribute: false) — readonly `LyraNodeTypeStyle { id: string; label: string; color?: string; shape?: 'circle' | 'square' | 'diamond' }`, one entry per `LyraGraphNode.type` value: `label` feeds the spoken "typed node" summary, and `shape`/`color` drive rendering per node. Per-node fill resolution precedence is `LyraGraphNode.color` (most specific) > the matched `LyraNodeTypeStyle.color` > an ordered categorical fallback palette assigned by the type's index in `nodeTypes` (`--lr-graph-cat-1` through `-8`, wrapping every 8 entries) > the untyped `--lr-node-fill` default; both data-driven color sources are sanitized the same way as `LyraGraphNode.color` itself. A typed node with no matching `nodeTypes` entry renders as a plain circle with the untyped default fill - `hiddenTypes: string[] = []` (attribute: false) — hides nodes whose raw `type` is listed and every incident link from rendering, layout, keyboard navigation, the data-list alternative, and the accessible counts. Hidden positions are retained by id, so showing a type restores its prior layout even when no matching `nodeTypes` entry exists - `links: LyraGraphLink[] = []` (attribute: false) — readonly `LyraGraphLink { id?: string; source: string; target: string; width?: number; label?: string; accessibleLabel?: string; description?: string; directed?: boolean; color?: string; dash?: number[] }` (source/target are node ids). `directed` adds an arrowhead; `color` and `dash` style the individual stroke; `label` provides a spoken-name and SVG tooltip fallback but is not rendered as visible edge text; `accessibleLabel` and `description` can override the spoken name and tooltip independently. `width` is normalized before reaching SVG, canvas paint, or canvas picking: negative values clamp to `0`, while a non-finite or unset value uses `1.5`. A zero-width or fully transparent link remains in the nonvisual topology summary but is excluded from pointer picking and keyboard navigation, so invisible geometry never becomes an operable control. A link whose `source` id doesn't resolve to a real node is still dropped entirely (there's no position to draw a stub from). A link whose `target` id doesn't resolve instead renders as a short, dashed, non-interactive stub off `source`'s own position (`[part='link'][data-dangling]`, `aria-hidden="true"`) rather than being silently dropped — e.g. for a wiki-style `[[link]]` reference to a not-yet-created node. A dangling stub is excluded from `d3-force`'s own simulation input and from click/keyboard interaction. - `fitTo: 'none' | 'container' = 'none'` (attribute `fit-to`) — where the drawing space comes from. `'none'` uses the numeric `width`/`height` below, unchanged. `'container'` measures the host's own content box and feeds that to the SVG `viewBox`, the layout's centring force, `focusNode()`/`fit()`'s camera math and the loading skeleton, so the drawing always matches the box it is rendered into and no host-side `ResizeObserver` is needed. The first measurement is taken synchronously before the first paint, with the host's own height already applied, so the first painted frame is already the right size; every later one arrives on the component's own host-resize watcher and is rounded to whole CSS pixels, so sub-pixel jitter changes nothing. A resize re-centres the running layout in place (`forceCenter` plus a low-alpha restart) and never rebuilds the simulation, so settled node positions, pins and an in-flight drag all survive it. Works in both renderers and across a renderer switch. While `'container'` is in effect the measured box wins over `width`/`height`; it falls back to them when the box is unmeasurable (detached, `display: none`, or a realm with no `ResizeObserver`). It does **not** change how the host itself is sized — an outer `block-size`, `--lr-canvas-reserved-height` and `height` still do that, and `'container'` simply follows whichever of them won - `width: number = 800` — ignored while `fitTo` is `'container'` - `height: number = 600` — also sizes the rendered host itself (see `--lr-canvas-reserved-height`'s entry below) whenever neither that nor an explicit outer `block-size` overrides it. Only the drawing space is ignored while `fitTo` is `'container'`; the host sizing above still applies - `chargeStrength: number = -300` (attribute `charge-strength` — live-reactive, see gotchas) - `linkDistance: number = 100` (attribute `link-distance` — live-reactive, see gotchas) - `minZoom: number = 0.1` (attribute `min-zoom`) - `maxZoom: number = 8` (attribute `max-zoom`) - `accessibleLabel: string | null = null` (attribute `aria-label`) — setting the JS property while the host attribute is absent names the SVG/canvas owner. Authored host `aria-label` presence, including an explicitly empty value, instead makes the host the sole named graph owner; the inner renderer drops its parallel role/name. Removing the attribute restores the inner owner and its localized node/link-count fallback - `seed?: number` — when set, seeds each node's initial x/y deterministically (keyed by node **id**, not array index/order) instead of `forceSimulation()`'s own random start, and settles the simulation synchronously instead of animating the settle (same effect `prefers-reduced-motion` has, see gotchas) - `showEdgeLabels: boolean = false` (attribute `show-edge-labels`) — draws each resolved (non-dangling) link's `label` as visible SVG text (`[part="link-label"]`) at the segment midpoint. Off by default: `LyraGraphLink.label` stays spoken/tooltip-only, matching pre-existing behavior, unless this is set - `edgeLabelMinZoom: number = 0.6` (attribute `edge-label-min-zoom`) — below this zoom scale, every drawn edge label is hidden (toggled via a `data-edge-labels-hidden` attribute on the zoomed ``, not a Lit re-render, so it tracks pan/zoom smoothly). Ignored entirely when `showEdgeLabels` is `false` - `nodeLabels?: 'always' | 'zoom' | 'none'` (attribute `node-labels`) — node-label visibility. `'always'` draws every node's label unconditionally; `'zoom'` hides them below the same canvas-declutter zoom threshold used before this property existed (toggled via a `data-node-labels-hidden` attribute on the zoomed `` for `renderer="svg"`, mirroring `showEdgeLabels`/`edgeLabelMinZoom`'s own mechanism — not a Lit re-render); `'none'` never renders them. Left unset (the default), each renderer keeps its own exact pre-existing behavior — `'always'` for `renderer="svg"`, `'zoom'` for `renderer="canvas"` — so this is purely additive - `layout: 'force' | 'layered' = 'force'` — `'force'` runs the `d3-force` simulation described throughout this section, unchanged. `'layered'` swaps in a deterministic Sugiyama-lite layered layout instead (longest-path layering, barycenter crossing reduction, cycle-safe — back edges are reversed only for layering, never mutating caller data): positions are computed synchronously with no settle animation, sized from each node's own radius and spaced by `linkDistance` (the layer gap) and a fixed 12px in-layer gap. Node drag is disabled in this mode (dragging would fight a computed layout) and `chargeStrength` becomes a documented no-op; pan/zoom, keyboard roving, `focusNode()`/`fit()`, hulls, edge labels, and `hiddenTypes` filtering all work identically to force mode. Switching `layout` at runtime repositions every node without a tween. The layering algorithm itself lives in the standalone, dependency-free `layeredLayout()` export (`@aceshooting/lyra-ui/utilities/layered-layout`), reusable by any other layered-diagram consumer - `renderer: 'svg' | 'canvas' = 'svg'` — `'canvas'` swaps the per-node/per-link SVG DOM for a single DPR-aware ``; every event/method/property behaves identically to `'svg'`, with hit-testing resolved via an offscreen color-picking canvas instead of DOM event targets. Trade-offs: no `::part(node)`/`::part(link)` styling (pixels, not elements — theme via cssprops instead), no native SVG `