@opendata-ai/openchart-vanilla 8.4.0 → 8.5.0

package/dist/graph-3d/index.d.ts

@@ -0,0 +1,272 @@
+import { GraphSpec } from '@opendata-ai/openchart-core';
+import { a as GraphCamera, b as GraphFlyTarget, g as GraphRendererContext, d as GraphInstance, f as GraphMountOptions } from '../renderer-registry-B5tW6yAZ.js';
+import '@opendata-ai/openchart-engine';
+import '@floating-ui/dom';
+
+/**
+ * Per-frame focus model for the graph: unifies the three emphasis sources
+ * (programmatic highlight, search matches, hover-neighborhood) into a single
+ * snapshot pair that the renderer crossfades between.
+ *
+ * Composition, not strict precedence (see plan §5a):
+ * - Standing state = highlight ∩ search when both active; if that intersection
+ *   is empty, search matches win (fresher user intent). This preserves the
+ *   "filter by topic, then search within it" workflow.
+ * - Hover-neighborhood is the transient top layer over whatever the standing
+ *   state is.
+ *
+ * The transition tweens between two discrete FocusSnapshots. Rapid hover sweeps
+ * retarget mid-flight: `retarget(next, now)` snapshots the endpoint CLOSEST to
+ * the current display (`prev = p < 0.5 ? old prev : old next`), so a low-p
+ * retarget keeps the old prev — no forward snap, worst-case visual jump halved
+ * vs. a naive "always start from current next" rule. Exact per-edge capture
+ * would destroy the renderer's tier batching, so this discrete approximation is
+ * deliberate.
+ */
+/** The set of emphasis relationships in effect for one steady state. */
+interface FocusSnapshot {
+    /** True when any emphasis source is active (something is dimmed). */
+    hasActive: boolean;
+    /** Nodes connected to the active/hovered set (includes the active nodes). */
+    connected: Set<string>;
+    /** Search matches, or null when search is inactive. */
+    searchMatches: Set<string> | null;
+    /** Selected nodes (selection rings; always emphasized). */
+    selected: Set<string>;
+}
+
+/**
+ * Emphasis composition for the 3D renderer: turns the focus model into a
+ * per-node and per-edge target opacity.
+ *
+ * The composition rules are NOT re-derived here. `composeStandingFocus` and
+ * `layerHoverFocus` from `../graph/focus-transition` are the single source of
+ * truth for "highlight ∩ search, hover on top" and are reused verbatim; this
+ * module only maps the resulting {@link FocusSnapshot} onto opacity numbers,
+ * mirroring the tier rules the 2D canvas renderer applies
+ * (`graph/canvas-renderer.ts` `nodeTier` / `edgeTier` / `*TierAlpha`).
+ *
+ * The one 3D-specific input is `edgeBaseAlpha`: above `LINK_WIDTH_MAX_EDGES`
+ * the renderer draws plain lines and maps `edgeWidth` to a resting alpha
+ * instead of a cylinder radius, so the resting tier is per-edge rather than a
+ * single constant.
+ *
+ * Pure: no three.js, no DOM.
+ */
+
+/** Minimal node shape the composition needs. */
+interface EmphasisNode {
+    id: string;
+    /** Compiled `nodeOpacity` encoding value; multiplies into the result. */
+    opacity: number;
+}
+/** Minimal edge shape the composition needs. Index is the link object key. */
+interface EmphasisEdge {
+    source: string;
+    target: string;
+}
+interface EmphasisInput {
+    nodes: EmphasisNode[];
+    edges: EmphasisEdge[];
+    /** The composed focus snapshot (standing state with the hover layer on top). */
+    focus: FocusSnapshot;
+    /** Ids that never dim (the spec's `seedNode`). */
+    exemptIds: Set<string>;
+    /** Resolved `interaction.hover.dimOpacity`. */
+    dimOpacity: number;
+    /** Per-edge resting alpha keyed by edge index; defaults to EDGE_ALPHA_DEFAULT. */
+    edgeBaseAlpha?: Map<number, number>;
+}
+interface EmphasisTargets {
+    /** Target material opacity by node id. */
+    nodes: Map<string, number>;
+    /** Target material opacity by edge index. */
+    edges: Map<number, number>;
+}
+/**
+ * Compose the focus snapshot into target opacities.
+ *
+ * Node rule (mirrors `nodeTier` + `nodeTierAlpha`): nothing active → 1; an
+ * exempt id → 1; in the connected set → 1; otherwise `dimOpacity`. An active
+ * search multiplies non-matching nodes by {@link SEARCH_NON_MATCH_ALPHA}, and
+ * exemption deliberately does NOT apply to search (a seed that doesn't match
+ * the query should not pretend to). The compiled `nodeOpacity` multiplies last.
+ *
+ * Edge rule (mirrors `edgeTier` + `edgeTierAlpha`): nothing active → the edge's
+ * resting alpha; both endpoints connected → 1; otherwise `dimOpacity / 3`,
+ * which preserves the node-to-edge dim ratio that keeps dense hairballs quiet.
+ * Edges are NOT exempted by `exemptIds`: the seed stays lit while its edges dim
+ * with everything else.
+ */
+declare function resolveEmphasis(input: EmphasisInput): EmphasisTargets;
+
+/**
+ * Force wiring for the 3D simulation.
+ *
+ * 3d-force-graph owns a d3-force-3d simulation on the main thread; we do not
+ * drive it and we do not port the 2D web worker here. This module maps the
+ * engine's `SimulationConfig` onto that simulation's knobs and supplies the one
+ * force d3-force-3d does not ship: the community cluster force, which is a
+ * 3-axis port of `forceCluster` in `../graph/simulation.ts`. Both copies must
+ * stay in sync.
+ */
+
+/**
+ * A community cluster force in three axes: each node is pulled toward the
+ * centroid of its own community, scaled by `strength * alpha`. Port of
+ * `forceCluster` in `../graph/simulation.ts` with the z axis added.
+ *
+ * Uses d3's `initialize` hook rather than closing over a node array, so the
+ * force keeps working after `graphData()` swaps the node objects.
+ */
+declare function forceCluster3D(strength: number): (alpha: number) => void;
+
+/**
+ * Label visibility policy for the 3D renderer.
+ *
+ * Same two-stage shape as 2D: rank, then declutter. This module is the ranking
+ * half — forced labels (seed / `alwaysShowLabel` overrides, hovered, selected,
+ * search matches) first, then the highest-priority nodes, nearest camera first,
+ * up to the budget. The mount does the screen-space overlap pass on the ordered
+ * result, which is why the order matters and not just the membership.
+ *
+ * Pure: no three.js, no DOM. The mount feeds it plain positions.
+ */
+/** A label candidate: a node with a resolved label and a compiled priority. */
+interface LabelCandidate {
+    id: string;
+    /** Compiled `labelPriority` (0..1, degree-derived). Higher wins. */
+    priority: number;
+    x: number;
+    y: number;
+    z: number;
+}
+/** Default 3D label budget beyond the forced set. */
+declare const LABEL_BUDGET_3D = 40;
+/**
+ * Node ids whose label sprite may be shown, best first.
+ *
+ * `forced` ids lead the list and do NOT consume budget. The rest are ranked by
+ * `(priority desc, camera distance asc)` and the top `budget` follow.
+ */
+declare function resolveVisibleLabels(nodes: LabelCandidate[], forced: Set<string>, cameraPos: {
+    x: number;
+    y: number;
+    z: number;
+}, budget: number): string[];
+
+/**
+ * Per-link three.js objects.
+ *
+ * Same reason as `nodes.ts`: `linkOpacity` is a single global number in
+ * 3d-force-graph, so per-edge hover dimming needs each link to own its
+ * material. (An rgba `linkColor` IS honoured for per-link opacity — see
+ * `../graph-3d/README` notes in the RFC report — but changing it only takes
+ * effect on a `refresh()`, which rebuilds every link object. That is exactly
+ * what hover must not do.)
+ *
+ * Two shapes: a `Line` (constant screen width, cheap) and a cylinder `Mesh`
+ * (true world-space width, needed when `edgeWidth` is encoded). Above
+ * `LINK_WIDTH_MAX_EDGES` the mount stays on lines and maps `edgeWidth` to a
+ * resting alpha instead.
+ *
+ * Positioning: three-forcegraph's own tick loop positions custom `Line` and
+ * `Mesh` link objects generically (it branches on `obj.type` and, for meshes,
+ * on the geometry already being a `CylinderGeometry`). The mount still installs
+ * a `linkPositionUpdate` because dashed lines need `computeLineDistances()`
+ * after every move, which the library's path does not call.
+ */
+
+/** Above this edge count `edgeWidth` maps to opacity steps, not cylinder radius. */
+declare const LINK_WIDTH_MAX_EDGES = 2000;
+
+/**
+ * The 3D graph renderer: a `GraphInstance` backed by `3d-force-graph`.
+ *
+ * Registered against `dimensions: 3` by `./index`. `createGraph()` builds the
+ * shared shell (wrapper, chrome, legend slot, tooltip manager, resize wiring)
+ * and hands it here; this module owns the WebGL scene, the d3-force-3d
+ * simulation the library drives, the per-node and per-link three.js objects,
+ * emphasis state, the label budget, tooltip anchoring, and disposal.
+ *
+ * Three library facts shape almost everything below and are easy to get wrong:
+ *
+ * 1. `nodeOpacity` and `linkOpacity` are GLOBAL numbers, not accessors. Every
+ *    per-object opacity (dim, highlight, entrance, search) therefore needs a
+ *    custom object with its own material. See `nodes.ts` / `links.ts`.
+ * 2. `refresh()` rebuilds every node and link object. It must never run on
+ *    hover; the hover path only writes `material.opacity`.
+ * 3. `rendererConfig` and `controlType` are CONSTRUCTOR options, not chained
+ *    setters.
+ *
+ * Differences from 2D that are deliberate and documented in RFC 27: no
+ * keyboard navigation, no node drag, no cursor repulsion or springy drag, no
+ * wall-clock warmup budget, and a structural `update()` reheats globally
+ * (`graphData()` restarts the layout at alpha 1) instead of applying 2D's local
+ * impulse.
+ */
+
+/**
+ * The camera distance that `getCamera().k === 1` refers to. 3D has no zoom
+ * scalar, so `k` is expressed as `FIT_DISTANCE / cameraDistance`: a `k` of 2 is
+ * twice as close as the reference framing, matching the 2D sign convention.
+ */
+declare const FIT_DISTANCE = 1000;
+/** Camera standoff from a node for `zoomToNode`, in scene units. */
+declare const NODE_FOCUS_DISTANCE = 120;
+/**
+ * A camera pose: the shared `GraphCamera` with the pose fields narrowed to
+ * required, since the 3D renderer always reports them.
+ */
+interface Camera3D extends GraphCamera {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** `flyTo` accepts either the 2D shape or a full 3D pose from `getCamera()`. */
+type FlyTarget3D = GraphFlyTarget;
+declare function createGraph3DRenderer(ctx: GraphRendererContext): GraphInstance;
+
+/**
+ * `@opendata-ai/openchart-vanilla/graph-3d` — the WebGL graph renderer.
+ *
+ * Importing this module registers the 3D renderer for `dimensions: 3`; after
+ * that, `createGraph()` picks it up on its own. That side effect is the whole
+ * point of the separate subpath: three.js (~30MB unpacked) never enters the
+ * default bundle, and `createGraph()` never dynamically imports a renderer,
+ * because mount is synchronous and every framework wrapper assumes it is.
+ *
+ * ```ts
+ * import { createGraph } from '@opendata-ai/openchart-vanilla';
+ * import '@opendata-ai/openchart-vanilla/graph-3d';
+ *
+ * createGraph(el, { type: 'graph', dimensions: 3, nodes, edges });
+ * ```
+ *
+ * `three`, `3d-force-graph` and `three-spritetext` are optional peer
+ * dependencies; install them alongside openchart to use this entry point, and
+ * check `npm ls three` shows exactly one copy (two copies fail at runtime with
+ * `Cannot read properties of undefined (reading 'VERTEX')`).
+ *
+ * SSR: the libraries touch `window` at import, so import this module from a
+ * client-only path (a `useEffect` dynamic import in React Router / Next).
+ */
+
+/**
+ * Mount a 3D graph without the caller having to set `dimensions: 3` themselves.
+ *
+ * A thin convenience over `createGraph()`: the spec is forced to three
+ * dimensions and everything else — shell, compilation, node-count gate, handle
+ * — is the shared path. A graph above `MAX_3D_NODES` still falls back to the 2D
+ * renderer with a warning, exactly as `createGraph()` would.
+ */
+declare function createGraph3D(container: HTMLElement, spec: GraphSpec, options?: GraphMountOptions): GraphInstance;
+
+export { type Camera3D, type EmphasisInput, type EmphasisTargets, FIT_DISTANCE, type FlyTarget3D, LABEL_BUDGET_3D, LINK_WIDTH_MAX_EDGES, type LabelCandidate, NODE_FOCUS_DISTANCE, createGraph3D, createGraph3DRenderer, forceCluster3D, resolveEmphasis, resolveVisibleLabels };