@aceshooting/lyra-ui 4.0.0 → 4.1.0

package/dist/components/knowledge-graph-explorer/knowledge-graph-explorer.class.d.ts

@@ -0,0 +1,196 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import type { GraphNode, GraphLink, GraphNodeType, GraphCommunity } from '../graph/graph.class.js';
+import type { LyraEntity } from '../entity-card/entity-card.class.js';
+import type { LyraPathElement } from '../path-strip/path-strip.class.js';
+import '../graph/graph.class.js';
+import '../graph-legend/graph-legend.class.js';
+import '../entity-card/entity-card.class.js';
+import '../neighbor-list/neighbor-list.class.js';
+import '../path-strip/path-strip.class.js';
+import '../overlay/popover.class.js';
+import '../input/input.class.js';
+import '../chip/chip.class.js';
+import '../button/button.class.js';
+/** Extra `LyraEntity` fields a plain `GraphNode` doesn't carry -- merged in by node id to build
+ *  the entity shown in the details popover and neighbor rows. A node with no entry here still
+ *  renders fine: `degree` falls back to a live count derived from `links`, `description`/
+ *  `properties` are simply omitted. */
+export type LyraKnowledgeGraphEntityDetails = Pick<LyraEntity, 'description' | 'properties' | 'degree'>;
+export interface LyraKnowledgeGraphExplorerEventMap {
+    /** The user asked to find a path between the two currently pinned nodes (the "Find path" action,
+     *  only rendered once exactly two nodes are pinned). `detail: { sourceId, targetId }` -- this
+     *  component has no graph-traversal algorithm of its own (client-side, backend call, whatever the
+     *  host prefers); it only requests one. The host computes/fetches the path and assigns the result
+     *  back through `path`. */
+    'lr-path-request': CustomEvent<{
+        sourceId: string;
+        targetId: string;
+    }>;
+    /** A node's pinned state changed by user interaction. `detail: { pinnedNodeIds }` -- the complete
+     *  updated array. This component already toggles its own `pinnedNodeIds` copy before emitting
+     *  (the same self-toggle-then-emit contract `lr-graph-legend`'s `hiddenTypes`/`lr-visibility-
+     *  change` already establishes), so reassigning it back is optional -- useful only for a host
+     *  that wants to persist or observe pins elsewhere. */
+    'lr-pin-change': CustomEvent<{
+        pinnedNodeIds: string[];
+    }>;
+}
+/**
+ * `<lr-knowledge-graph-explorer>` — an orchestration-level surface for exploring a knowledge
+ * graph: the `lr-graph` canvas plus entity search, type filters, neighborhood expansion, pinned
+ * nodes, path finding between pins, node selection, and a details overlay. Composes existing
+ * primitives rather than re-implementing graph rendering: `lr-graph` (canvas/pan-zoom/selection),
+ * `lr-graph-legend` (type filters), `lr-entity-card` (the details popover's default content),
+ * `lr-neighbor-list` (the selected entity's relationships), `lr-path-strip` (a found path), and
+ * `lr-popover.showAt()` (the details overlay itself).
+ *
+ * **How the details popover finds its viewport position.** `lr-graph.getNodePosition()` and the
+ * `lr-node-click` event's `{ x, y }` are in the graph's own *local drawing space* (pre pan/zoom),
+ * never viewport pixels -- passing them straight to `showAt()` would anchor the popover at the
+ * wrong place as soon as the graph has panned or zoomed even once. A direct node click resolves
+ * the correct viewport rect the way this library's own documented `lr-graph` + `lr-popover.showAt()`
+ * composition does: for `renderer="svg"` (the default), `event.composedPath()` (the native `click`
+ * that bubbles out of `lr-graph`'s shadow root) locates the actual clicked `[part="node"]` element,
+ * whose `getBoundingClientRect()` is already viewport-relative; for `renderer="canvas"` (no
+ * per-node DOM element to find), the click event's own `clientX`/`clientY` are used directly, since
+ * canvas hit-testing already treats those as viewport coordinates internally. While the popover
+ * stays open after an `renderer="svg"` click, this component re-reads that same resolved node
+ * element's `getBoundingClientRect()` on a bounded `requestAnimationFrame` loop and re-calls
+ * `showAt()` every frame -- `lr-graph` exposes no public pan/zoom/tick event to subscribe to
+ * instead, so polling the live element (which pan/zoom moves via an ancestor transform, not by
+ * mutating the element itself) is the closest available approximation to the "re-anchor on
+ * pan/zoom" contract `showAt()`'s own docs describe as the caller's responsibility; the loop stops
+ * automatically once the popover closes or the element leaves the DOM. Selecting a node any other
+ * way -- a search result, a neighbor row, a path-strip element, keyboard Enter/Space on a graph
+ * node (which never dispatches a native `click`) -- has no click event to read a rect from, so it
+ * instead calls the public `lr-graph.focusNode(id)` (which centers that node in the viewport) and
+ * then anchors the popover at the graph element's own `getBoundingClientRect()` center once that
+ * settles; no continuous tracking applies to that path.
+ *
+ * **Controlled vs. self-managed state.** `nodes`/`links`/`nodeTypes`/`communities`/`entityDetails`/
+ * `path` are purely host-supplied data, rendered as given. `hiddenTypes`/`selectedNodeId`/
+ * `searchQuery`/`pinnedNodeIds` are this component's own genuinely new contribution: it wires them
+ * into `lr-graph`'s existing controlled props (`hiddenTypes`, `selectedNodeIds`, `dimmedNodeIds`)
+ * itself, toggling its own copy on interaction (the same self-toggle-then-emit contract
+ * `lr-graph-legend` already uses) so every feature works with zero host wiring, while still being
+ * presettable/observable properties and emitting events (`lr-pin-change`, `lr-path-request`,
+ * plus every composed primitive's own event bubbling straight through unmodified) for a host that
+ * wants to persist or react to them.
+ *
+ * @customElement lr-knowledge-graph-explorer
+ * @slot details - Overrides the details popover's default content (an `lr-entity-card` with a
+ *   nested `lr-neighbor-list` and a pin toggle). Receives no data -- a consumer overriding this
+ *   slot reads the selected entity from `selectedNodeId`/`nodes` itself.
+ * @event lr-path-request - `detail: { sourceId, targetId }`. See the class doc above.
+ * @event lr-pin-change - `detail: { pinnedNodeIds }`. See the class doc above.
+ * @event lr-node-click - Bubbles straight through from the composed `lr-graph`, unmodified.
+ * @event lr-link-click - Bubbles straight through from the composed `lr-graph`, unmodified.
+ * @event lr-node-expand - Bubbles straight through from `lr-graph` and/or `lr-neighbor-list` (the
+ *   same event name/detail shape from either source) -- this component never appends neighbors
+ *   itself, only forwards the request; a host fetches/generates the expansion and assigns updated
+ *   `nodes`/`links` back.
+ * @event lr-community-click - Bubbles straight through from the composed `lr-graph`, unmodified.
+ * @event lr-relation-activate - Bubbles straight through from the composed `lr-path-strip`, unmodified.
+ * @csspart base - The root `role="group"` wrapper.
+ * @csspart toolbar - The row wrapping the search input and the type-filter legend.
+ * @csspart search - The composed `lr-entity-card` search `lr-input`.
+ * @csspart legend - The composed `lr-graph-legend`.
+ * @csspart search-results - The search-match list, only rendered while `searchQuery` is non-empty.
+ * @csspart search-result - One search-match row (`role="listitem"`, wrapping a `<button>`).
+ * @csspart search-empty - The "no matches" message, shown when `searchQuery` is non-empty but no node matches.
+ * @csspart pinned - The pinned-nodes row, only rendered while `pinnedNodeIds` is non-empty.
+ * @csspart pinned-heading - The pinned-nodes row's leading label.
+ * @csspart path - The composed `lr-path-strip`, only rendered while `path` is non-empty.
+ * @csspart graph - The composed `lr-graph`.
+ * @csspart detail-popover - The composed `lr-popover` hosting the details overlay.
+ * @csspart detail-card - The default-content `lr-entity-card`, only present while `selectedNodeId` resolves to a node.
+ */
+export declare class LyraKnowledgeGraphExplorer extends LyraElement<LyraKnowledgeGraphExplorerEventMap> {
+    static styles: import("lit").CSSResultGroup[];
+    nodes: GraphNode[];
+    links: GraphLink[];
+    nodeTypes: GraphNodeType[];
+    communities: GraphCommunity[];
+    /** Extra dossier fields, keyed by node id -- see `LyraKnowledgeGraphEntityDetails`. */
+    entityDetails: Record<string, LyraKnowledgeGraphEntityDetails>;
+    /** Currently-pinned node ids. Self-toggled by the pin action in the details popover and by a
+     *  pinned chip's remove button (see the class doc's "controlled vs. self-managed" note); still
+     *  presettable/overridable like any other property. Exactly two pinned nodes reveals the "Find
+     *  path" action. */
+    pinnedNodeIds: string[];
+    /** Host-supplied path-finding result, rendered via `lr-path-strip`. Empty (the default) renders
+     *  no path strip. See `lr-path-request`. */
+    path: LyraPathElement[];
+    /** Currently-hidden `GraphNode.type` values, forwarded to both `lr-graph.hiddenTypes` and
+     *  `lr-graph-legend.hiddenTypes`. Self-toggled by the composed legend; still presettable. */
+    hiddenTypes: string[];
+    /** The currently-selected node id, driving both the details popover and `lr-graph`'s
+     *  `selectedNodeIds` visual state. Presettable (e.g. to deep-link to a specific entity) as well
+     *  as self-managed on every selection interaction. `null` (the default) shows no selection and
+     *  keeps the details popover closed. */
+    selectedNodeId: string | null;
+    /** Forwarded to `lr-graph.renderer`. `renderer="canvas"` has no per-node DOM element, which
+     *  narrows how the node-detail popover anchors and disables its pan/zoom tracking -- see the
+     *  class doc's anchoring note. */
+    renderer: 'svg' | 'canvas';
+    width: number;
+    height: number;
+    /** Accessible name for the root landmark; falls back to the localized `graphExplorerLabel`. */
+    label: string;
+    private searchQuery;
+    private pinLiveText;
+    private graphEl?;
+    private popoverEl?;
+    /** Set by `onGraphNodeClick` and consumed either synchronously by the native `click` that
+     *  follows it on the same user gesture (a real pointer click), or, failing that, by a queued
+     *  microtask fallback (a keyboard Enter/Space activation, which -- unlike a native `<button>` --
+     *  never dispatches a synthetic `click` on a `role="button"` SVG/canvas element). */
+    private pendingNodeId?;
+    /** The exact rendered `[part="node"]` element resolved for the currently-open popover
+     *  (`renderer="svg"`, direct-click path only) -- re-read every tracking frame so the popover
+     *  keeps tracking a pan/zoom gesture while it stays open. */
+    private trackedNodeEl?;
+    private trackRafId?;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    private nodeLabel;
+    private degreeOf;
+    private entityFor;
+    private communityLabelFor;
+    private neighborRowsFor;
+    private matchingNodes;
+    private neighborIdsOf;
+    /** Non-matching nodes while searching; otherwise everything outside the selected node's
+     *  immediate neighborhood while a selection is active; otherwise nothing. Wires the search/
+     *  selection state this component owns into `lr-graph`'s existing `dimmedNodeIds` contract
+     *  instead of introducing a parallel highlighting mechanism. */
+    private get computedDimmedNodeIds();
+    private togglePin;
+    private requestPath;
+    private onVisibilityChange;
+    private onSearchInput;
+    private onEntityActivate;
+    /** Selects `id` and opens its details popover without a click event to read a rect from --
+     *  centers the node via the public `lr-graph.focusNode()`, then anchors at the graph element's
+     *  own viewport rect center once that settles. Shared by search results, neighbor rows,
+     *  path-strip elements, `lr-entity-card`'s own built-in focus button, and the keyboard-Enter/
+     *  Space fallback for a direct graph node activation. */
+    private activateEntity;
+    private openDetailAt;
+    /** Resolves the viewport rect for a direct pointer click on a graph node -- see the class doc's
+     *  "how the details popover finds its viewport position" note for the full reasoning. */
+    private resolveDirectClickAnchor;
+    private onGraphNodeClick;
+    private onGraphNativeClick;
+    private startTracking;
+    private stopTracking;
+    private onPopoverHide;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-knowledge-graph-explorer': LyraKnowledgeGraphExplorer;
+    }
+}
+//# sourceMappingURL=knowledge-graph-explorer.class.d.ts.map

package/dist/components/knowledge-graph-explorer/knowledge-graph-explorer.class.d.ts.map

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