@yggy-tech/graphraum 0.35.0 → 0.37.0

package/dist/index.d.ts

@@ -80,6 +80,42 @@ interface GraphraumSetDataOptions {
    */
   fit?: boolean;
 }
+type GraphraumNodeDragPhase = "start" | "move" | "end" | "cancel";
+/** One step of a node drag. `cancel` carries the position the node was restored to (or left at). */
+interface GraphraumNodeDragEvent {
+  nodeId: string;
+  phase: GraphraumNodeDragPhase;
+  position: GraphraumPosition;
+}
+interface GraphraumNodeDragOptions {
+  enabled: boolean;
+}
+interface GraphraumCameraPoint3d {
+  x: number;
+  y: number;
+  z: number;
+}
+/**
+ * A 2D view: where the camera looks and how much of the world it shows from top to bottom. The
+ * visible width follows the canvas aspect, so a state read on one canvas size fits another.
+ */
+interface GraphraumCameraState2d {
+  center: {
+    x: number;
+    y: number;
+  };
+  mode: "2d";
+  /** World units from the top to the bottom edge of the canvas, with the current zoom applied. */
+  visibleHeight: number;
+}
+/** A 3D view: the camera position and the point it orbits and looks at. */
+interface GraphraumCameraState3d {
+  mode: "3d";
+  position: GraphraumCameraPoint3d;
+  target: GraphraumCameraPoint3d;
+}
+/** The camera pose as plain JSON, for saving a view and restoring it with `setCameraState()`. */
+type GraphraumCameraState = GraphraumCameraState2d | GraphraumCameraState3d;
 interface GraphraumDataPatch<NodeAttributes = undefined, EdgeAttributes = undefined> {
   addedNodes?: readonly GraphraumNode<NodeAttributes>[];
   addedEdges?: readonly GraphraumEdge<EdgeAttributes>[];
@@ -240,8 +276,60 @@ type GraphraumPickHit = {
   kind: "node";
   id: string;
 };
+/** `linear`, cubic `easeIn` / `easeOut` / `easeInOut`, or a function from progress 0..1 to eased 0..1. */
+type GraphraumEasing = "easeIn" | "easeInOut" | "easeOut" | "linear" | ((t: number) => number);
+/** How depth of field animates focus moves and blur fades. */
+interface GraphraumDepthOfFieldTransition {
+  /** Default 400; 0 jumps. `prefers-reduced-motion: reduce` always jumps. */
+  durationMs?: number;
+  /** Default `"easeInOut"`. */
+  easing?: GraphraumEasing;
+}
+/**
+ * Opt-in 3D depth of field. The focal plane follows the selection, so selected nodes stay sharp and
+ * the rest of the graph blurs with its distance from them, in front and behind, like a thin lens:
+ * the closer the camera is to the focus, the shallower the depth of field. A no-op in 2D. See
+ * `Graphraum.setDepthOfField`.
+ */
+interface GraphraumDepthOfFieldOptions {
+  /** Default `false`. While disabled no extra passes or render targets exist. Toggling fades the blur. */
+  enabled?: boolean;
+  /**
+   * `"selection"` (default) focuses the mean position of the selected nodes and fades the blur out
+   * when nothing is selected. A number fixes the focal plane at that camera distance in world units.
+   */
+  focus?: "selection" | number;
+  /**
+   * Aperture, 0..1, default 0.5. A surface blurs by `strength * 24 * |d - f| / d` CSS pixels, where
+   * `d` is its camera distance and `f` the focal distance, clamped to `maxBlur`.
+   */
+  strength?: number;
+  /** Largest blur radius in CSS pixels. Default 12. */
+  maxBlur?: number;
+  /** Blur radii below this many CSS pixels render sharp, which widens the in-focus band. Default 0. */
+  minBlur?: number;
+  /** Camera-to-focus distance in world units up to which `strength` applies fully. Default 0. */
+  nearDistance?: number;
+  /** Camera-to-focus distance in world units at which the blur has faded out. Default `Infinity` (no fade). */
+  farDistance?: number;
+  /** Animation for focus moves between selections and for blur fades. */
+  transition?: GraphraumDepthOfFieldTransition;
+}
+/** Options for one `Graphraum.setDepthOfField` call. */
+interface GraphraumDepthOfFieldUpdate {
+  /** Default `true`: fade the blur to the new strength over the transition. `false` jumps. */
+  animate?: boolean;
+}
+/**
+ * `off`: disabled. `inactive`: enabled with nothing to blur (2D mode, or no selection with
+ * `focus: "selection"`), so frames render directly. `active`: the last frame ran the blur passes.
+ * `unsupported`: enabled, but the WebGL context cannot run it, so frames render directly.
+ */
+type GraphraumDepthOfFieldStatus = "active" | "inactive" | "off" | "unsupported";
 interface GraphraumOptions<NodeAttributes = undefined, EdgeAttributes = undefined> {
   antialias?: boolean;
+  /** Opt-in 3D depth of field; off by default. Change it later with `setDepthOfField`. */
+  depthOfField?: GraphraumDepthOfFieldOptions;
   maxVisibleEdges?: number;
   maxVisibleNodes?: number;
   maxPixelRatio?: number;
@@ -274,6 +362,7 @@ interface GraphraumDiagnostics {
   aggregatedNodeClusters: number;
   autoOrbit: GraphraumAutoOrbitStatus;
   cpuFrameMilliseconds: number;
+  depthOfField: GraphraumDepthOfFieldStatus;
   gpuFrameMilliseconds: number | null;
   gpuDrawCalls: number;
   gpuGeometries: number;
@@ -532,12 +621,23 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   /** True only during the orbit's own `controls.update(dt)`; see `handleViewChange`. */
   private orbitUpdating;
   private destroyed;
+  private canvasWidth;
+  private canvasHeight;
   private cpuFrameMilliseconds;
   private gpuFrameMilliseconds;
   private gpuTimer;
   private readonly viewListeners;
   private readonly focusListeners;
+  private readonly nodeDragListeners;
+  private readonly nodeDrag;
   private lastHoveredNodeId;
+  private readonly antialias;
+  private depthOfField;
+  private readonly depthOfFieldFocus;
+  /** Strength actually applied: fades toward `strength` while enabled and toward 0 when disabled. */
+  private readonly depthOfFieldStrength;
+  private depthOfFieldPass;
+  private depthOfFieldStatus;
   constructor(container: HTMLElement, options?: GraphraumOptions<NodeAttributes, EdgeAttributes>);
   /** Replaces the whole graph. Fits the camera unless `options.fit` is `false`. */
   setData(data: GraphraumData<NodeAttributes, EdgeAttributes>, options?: GraphraumSetDataOptions): void;
@@ -596,6 +696,19 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
    * before enabling it. Throws in 2D mode; `setMode("2d")` turns it off. Does nothing after `destroy()`.
    */
   setAutoOrbit(options: GraphraumAutoOrbitOptions | false): void;
+  /**
+   * Updates 3D depth of field; omitted fields keep their current values. Enabling, disabling and a
+   * new `strength` fade the blur over `transition` unless `update.animate` is `false`; a change
+   * during a fade continues from the blur shown last. With `focus: "selection"` the focal plane
+   * follows the mean position of the selected nodes, re-measured from the camera every frame, and
+   * moves over `transition` when the selection changes; with nothing selected the blur fades out.
+   * `prefers-reduced-motion: reduce` jumps. Resolves `true` when the blur reaches the new strength
+   * and `false` when a later call or `destroy()` interrupts the fade. While it blurs each frame adds
+   * three draw calls; disabled, or with nothing to blur, it costs nothing. A no-op in 2D. Picking
+   * and DOM overlays are unaffected. Throws for invalid values.
+   */
+  setDepthOfField(options: GraphraumDepthOfFieldOptions, update?: GraphraumDepthOfFieldUpdate): Promise<boolean>;
+  private depthOfFieldTargetStrength;
   getNodePresentation(nodeId: string): CompiledGraphraumPresentation | null;
   /** Returns canvas-relative screen coordinates for a node, or null when the node does not exist. */
   getNodeScreenPosition(nodeId: string): GraphraumScreenPosition | null;
@@ -614,6 +727,16 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   createOverlay(options?: GraphraumOverlayOptions): GraphraumOverlay<NodeAttributes, EdgeAttributes>;
   /** Subscribes to camera and viewport changes. Returns an unsubscribe function. */
   onViewChange(listener: () => void): () => boolean;
+  /**
+   * Turns node dragging on or off (default off). A drag starts when the pointer moves past a small
+   * tolerance after a press on a node (a finger must rest on the node first, so a swipe still pans
+   * the camera), moves the node on a plane facing the camera, and ends on release. Escape or a
+   * cancelled pointer put the node back. Not available while the density LOD shows clusters.
+   */
+  setNodeDrag(options: GraphraumNodeDragOptions): void;
+  /** Subscribes to node drag steps (`start`, `move`, `end`, `cancel`). Returns an unsubscribe function. */
+  onNodeDrag(listener: (event: GraphraumNodeDragEvent) => void): () => boolean;
+  private createNodeDragHost;
   /** Subscribes to selection and hover changes that affect overlay focus chrome. */
   onFocusChange(listener: () => void): () => boolean;
   private notifyFocusChange;
@@ -644,6 +767,20 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
    * reduce` or a zero duration it jumps. Throws for an invalid duration or distance scale.
    */
   flyTo(options: GraphraumFlyToOptions): Promise<boolean>;
+  /**
+   * The camera pose as plain JSON. 2D reports the centre and the world height the canvas shows; 3D
+   * reports the camera position and the point it orbits. Pass it to `setCameraState()` to return
+   * to the same view, for example after reloading a saved one.
+   */
+  getCameraState(): GraphraumCameraState;
+  /**
+   * Puts the camera on a pose from `getCameraState()` at once, without fitting or animating, and
+   * cancels a running `flyTo`. Throws for a state of the other mode (switch with `setMode()` first)
+   * or with a non-finite number. 2D keeps the saved height and takes the width from the canvas, so a
+   * view saved on one canvas size fits another. 3D derives the clip planes from the pose so the whole
+   * graph stays in view. Apply it after the canvas has its size: a 2D resize to a new size refits.
+   */
+  setCameraState(state: GraphraumCameraState): void;
   /** Nodes whose id is in `nodeIds`, in graph order; every node when `nodeIds` is omitted. */
   private nodesWithIds;
   /** The closest front-view camera that frames `nodes` (issue #124); applies the container aspect. */
@@ -673,6 +810,14 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   /** Renders a pending frame now instead of on the next animation frame. */
   private flushRender;
   private renderFrame;
+  /**
+   * Decides whether this frame blurs and records why in the diagnostics status. Returns null to
+   * render directly. Requests another frame while a fade or focus move runs; both end on their own.
+   */
+  private prepareDepthOfField;
+  /** Mean world position of the selected nodes, read every frame so a running layout keeps them in focus. */
+  private selectionFocusPoint;
+  private disposeDepthOfFieldPass;
   private stopAutoOrbit;
   /**
    * One orbit frame. `autoRotate` is on only for this `update(dt)` call: OrbitControls also calls
@@ -860,4 +1005,4 @@ declare function isTransparentGraphraumBackground(background: GraphraumBackgroun
 /** Defines typed, serializable graph visuals without coupling application data to the render loop. */
 declare function defineVisuals<NodeAttributes = undefined, EdgeAttributes = undefined>(visuals: GraphraumVisualMapper<NodeAttributes, EdgeAttributes>): GraphraumVisualMapper<NodeAttributes, EdgeAttributes>;
 //#endregion
-export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDiagnostics, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumSetDataOptions, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };
+export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumCameraPoint3d, type GraphraumCameraState, type GraphraumCameraState2d, type GraphraumCameraState3d, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDepthOfFieldOptions, type GraphraumDepthOfFieldStatus, type GraphraumDepthOfFieldTransition, type GraphraumDepthOfFieldUpdate, type GraphraumDiagnostics, type GraphraumEasing, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeDragEvent, type GraphraumNodeDragOptions, type GraphraumNodeDragPhase, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumSetDataOptions, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };