Skip to content

✨ Innovative and open-source visualization application that transforms various data formats, such as JSON, YAML, XML and CSV into interactive graphs.

23.6 KB
Raw Blame
"use client";

import {
  forwardRef,
  useCallback,
  useEffect,
  useImperativeHandle,
  useMemo,
  useRef,
  useState,
  type CSSProperties,
  type ReactNode,
} from "react";
import type { JSONPath } from "jsonc-parser";
import type { ViewPort } from "react-zoomable-ui";
import { Space } from "react-zoomable-ui";
import { Canvas } from "reaflow";
import type { EdgeProps, ElkRoot, NodeProps } from "reaflow";
import { useLongPress } from "use-long-press";
import styles from "./JSONCrackStyles.module.css";
import {
  adjustViewPortZoom,
  buildCanvasClassName,
  buildCanvasStyle,
  buildEdgeTargetMap,
  fitGraphToViewPort,
  focusRootNode,
  getShiftWheelHorizontalPanDelta,
  parseJsonGraph,
  setCanvasDragging,
  setViewPortZoom,
  toJsonText,
  type JsonInput,
} from "./canvasHelpers";
import { CollapseContext, isNodeHidden, prunePaths } from "./components/CollapseContext";
import { Controls } from "./components/Controls";
import { CustomEdge } from "./components/CustomEdge";
import { CustomNode } from "./components/CustomNode";
import type { CanvasThemeMode, GraphData, LayoutDirection, NodeData } from "./types";

const layoutOptions = {
  "elk.layered.compaction.postCompaction.strategy": "EDGE_LENGTH",
  "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX",
  "elk.spacing.edgeLabel": "15",
};

/** Imperative handle exposed via the component ref for viewport control. */
export interface JSONCrackRef {
  /** Nudge the current zoom factor up by one step while keeping center fixed. */
  zoomIn: () => void;
  /** Nudge the current zoom factor down by one step while keeping center fixed. */
  zoomOut: () => void;
  /** Set an absolute zoom factor at the current viewport center. */
  setZoom: (zoomFactor: number) => void;
  /** Fit-to-center the full graph inside the viewport. */
  centerView: () => void;
  /** Center and zoom on the root node of the graph. */
  focusFirstNode: () => void;
  /** Toggle collapse for a specific JSON path (uncontrolled mode only). */
  toggleCollapse: (path: JSONPath) => void;
  /** Collapse every first-level container of the root (uncontrolled mode only). */
  collapseAll: () => void;
  /** Clear all collapsed paths (uncontrolled mode only). */
  expandAll: () => void;
  /** Current collapsed-paths snapshot (serialized keys). */
  getCollapsedPaths: () => string[];
}

/** Props accepted by the `JSONCrack` component. */
export interface JSONCrackProps {
  /** JSON to visualize. Accepts a string or plain object. */
  json: JsonInput;
  /** Color theme applied to the canvas and nodes. Defaults to `dark`. */
  theme?: CanvasThemeMode;
  /** ELK layout direction for node placement. Defaults to `RIGHT`. */
  layoutDirection?: LayoutDirection;
  /** Whether to render the built-in zoom/focus control overlay. Defaults to `true`. */
  showControls?: boolean;
  /** Whether to draw the background grid. Defaults to `true`. */
  showGrid?: boolean;
  /** Treat two-finger trackpad gestures as touch (pinch-zoom, etc). Defaults to `false`. */
  trackpadZoom?: boolean;
  /** Auto fit-to-center after each ELK layout pass. Defaults to `true`. */
  centerOnLayout?: boolean;
  /** Hard cap on renderable nodes; exceeding it triggers the limit overlay. Defaults to `1500`. */
  maxRenderableNodes?: number;
  /** Additional class name appended to the canvas wrapper. */
  className?: string;
  /** Additional inline style merged onto the canvas wrapper. */
  style?: CSSProperties;
  /** Called when a node is clicked. */
  onNodeClick?: (node: NodeData) => void;
  /** Called with parsed `nodes`/`edges` after each successful parse. */
  onParse?: (graph: GraphData) => void;
  /** Called with any error thrown during JSON parsing or graph construction. */
  onParseError?: (error: Error) => void;
  /** Called once the internal `ViewPort` is created, before the first render. */
  onViewportCreate?: (viewPort: ViewPort) => void;
  /** Custom renderer shown when the graph exceeds `maxRenderableNodes`. */
  renderNodeLimitExceeded?: (nodeCount: number, maxRenderableNodes: number) => ReactNode;
  /**
   * Controlled collapsed-paths set (serialized via `pathKey` / `JSON.stringify`).
   * When provided, the component becomes controlled for collapse state and
   * `onToggleCollapse` is required to mutate it. When omitted, the component
   * manages collapse state internally.
   */
  collapsedPaths?: string[];
  /** Called with the `JSONPath` of a row's value when the user clicks a chevron (controlled mode). */
  onToggleCollapse?: (path: JSONPath) => void;
  /** Observe the internal collapsed-paths set (uncontrolled mode). */
  onCollapseChange?: (collapsedPaths: string[]) => void;
}

/** Interactive JSON-to-graph visualization. Forwards a `JSONCrackRef` for imperative viewport control. */
export const JSONCrack = forwardRef<JSONCrackRef, JSONCrackProps>(
  (
    {
      json,
      theme = "dark",
      layoutDirection = "RIGHT",
      showControls = true,
      showGrid = true,
      trackpadZoom = false,
      centerOnLayout = true,
      maxRenderableNodes = 1500,
      className,
      style,
      onNodeClick,
      onParse,
      onParseError,
      onViewportCreate,
      renderNodeLimitExceeded,
      collapsedPaths: controlledCollapsedPaths,
      onToggleCollapse: controlledOnToggle,
      onCollapseChange,
    },
    ref
  ) => {
    const containerRef = useRef<HTMLDivElement | null>(null);
    const [viewPort, setViewPort] = useState<ViewPort | null>(null);
    const [nodes, setNodes] = useState<GraphData["nodes"]>([]);
    const [edges, setEdges] = useState<GraphData["edges"]>([]);
    const [loading, setLoading] = useState(true);
    const [initialFitDone, setInitialFitDone] = useState(false);
    const [aboveSupportedLimit, setAboveSupportedLimit] = useState(false);
    const [totalNodes, setTotalNodes] = useState(0);
    const [paneWidth, setPaneWidth] = useState(2000);
    const [paneHeight, setPaneHeight] = useState(2000);
    const layoutSizeRef = useRef<{ width: number; height: number } | null>(null);

    // Ref-mirror consumer callbacks so the parse effect / onCreate callbacks can read the latest without re-running.
    const callbacksRef = useRef({ onParse, onParseError });
    const onViewportCreateRef = useRef(onViewportCreate);
    useEffect(() => {
      callbacksRef.current = { onParse, onParseError };
    }, [onParse, onParseError]);
    useEffect(() => {
      onViewportCreateRef.current = onViewportCreate;
    }, [onViewportCreate]);

    // Memoize the class/style so reaflow doesn't see a new style object every render.
    const canvasClassName = useMemo(
      () => buildCanvasClassName(showGrid, className),
      [showGrid, className]
    );
    const canvasStyle = useMemo(() => buildCanvasStyle(theme, style), [theme, style]);

    // Normalize `json` to a string once per reference. Memoized so the parse effect can depend on a primitive.
    const jsonText = useMemo(() => toJsonText(json), [json]);

    // Parse → dispatch to React state. The pure helper keeps the effect body tiny.
    useEffect(() => {
      setLoading(true);
      setInitialFitDone(false);
      const result = parseJsonGraph(jsonText, maxRenderableNodes);

      if (result.kind === "error") {
        setNodes([]);
        setEdges([]);
        setLoading(false);
        callbacksRef.current.onParseError?.(result.error);
        return;
      }

      if (result.kind === "above-limit") {
        setTotalNodes(result.total);
        setAboveSupportedLimit(true);
        setNodes([]);
        setEdges([]);
        setLoading(false);
        return;
      }

      const { graph, syntaxErrorCount } = result;
      if (syntaxErrorCount > 0) {
        callbacksRef.current.onParseError?.(
          new Error(`Failed to parse data (${syntaxErrorCount} syntax error(s)).`)
        );
      }
      setTotalNodes(graph.nodes.length);
      setAboveSupportedLimit(false);
      setNodes(graph.nodes);
      setEdges(graph.edges);
      callbacksRef.current.onParse?.({ nodes: graph.nodes, edges: graph.edges });
      if (graph.nodes.length === 0) setLoading(false);
    }, [jsonText, maxRenderableNodes]);

    // Keep the viewport in sync with container resizes — react-zoomable-ui snapshots dimensions at creation and does not re-measure on its own.
    useEffect(() => {
      if (!viewPort) return;
      const container = containerRef.current;
      if (!container || typeof ResizeObserver === "undefined") return;

      const observer = new ResizeObserver(() => {
        if (container.clientWidth === 0 || container.clientHeight === 0) return;
        viewPort.updateContainerSize();
      });

      observer.observe(container);
      return () => observer.disconnect();
    }, [viewPort]);

    useEffect(() => {
      if (!viewPort) return;
      const space = containerRef.current?.querySelector<HTMLElement>(".jsoncrack-space");
      if (!space) return;

      const handleShiftWheel = (event: WheelEvent) => {
        const delta = getShiftWheelHorizontalPanDelta(
          event,
          space.clientWidth || window.innerWidth
        );
        if (delta === null) return;

        const camera = viewPort.camera;
        if (!camera) return;

        event.preventDefault();
        event.stopImmediatePropagation();
        camera.moveByInClientSpace(delta, 0, 0);
      };

      space.addEventListener("wheel", handleShiftWheel, { capture: true, passive: false });
      return () => space.removeEventListener("wheel", handleShiftWheel, { capture: true });
    }, [viewPort]);

    const viewPortApi = useMemo(
      () => ({
        zoomIn: () => adjustViewPortZoom(viewPort, 0.1),
        zoomOut: () => adjustViewPortZoom(viewPort, -0.1),
        setZoom: (zoomFactor: number) => setViewPortZoom(viewPort, zoomFactor),
        centerView: () => fitGraphToViewPort(viewPort, containerRef.current, layoutSizeRef.current),
        focusFirstNode: () => focusRootNode(viewPort, containerRef.current),
      }),
      [viewPort]
    );

    // Uncontrolled collapse state. `controlledCollapsedPaths` takes precedence when provided.
    const [internalCollapsedPaths, setInternalCollapsedPaths] = useState<string[]>([]);
    const isControlled = controlledCollapsedPaths !== undefined;
    const collapsedPaths = isControlled ? controlledCollapsedPaths : internalCollapsedPaths;

    const onCollapseChangeRef = useRef(onCollapseChange);
    useEffect(() => {
      onCollapseChangeRef.current = onCollapseChange;
    }, [onCollapseChange]);

    // Skip the initial mount so only actual changes are reported.
    const hasReportedCollapseRef = useRef(false);
    useEffect(() => {
      if (isControlled) return;
      if (!hasReportedCollapseRef.current) {
        hasReportedCollapseRef.current = true;
        return;
      }
      onCollapseChangeRef.current?.(internalCollapsedPaths);
    }, [internalCollapsedPaths, isControlled]);

    // Prune internally-held collapsed paths that no longer resolve to an
    // object/array in the current data (e.g., after a JSON edit).
    useEffect(() => {
      if (isControlled) return;
      if (internalCollapsedPaths.length === 0) return;
      const kept = prunePaths(jsonText, internalCollapsedPaths);
      if (kept.length !== internalCollapsedPaths.length) setInternalCollapsedPaths(kept);
    }, [jsonText, internalCollapsedPaths, isControlled]);

    const collapsedSet = useMemo(() => new Set(collapsedPaths ?? []), [collapsedPaths]);

    // Pre-parse the serialized paths once per collapsedSet change so the
    // per-node prefix check doesn't re-parse on every iteration.
    const collapsedPrefixes = useMemo<JSONPath[]>(() => {
      if (collapsedSet.size === 0) return [];
      const out: JSONPath[] = [];
      for (const key of collapsedSet) {
        try {
          out.push(JSON.parse(key) as JSONPath);
        } catch {
          // skip malformed entries
        }
      }
      return out;
    }, [collapsedSet]);

    const { visibleNodes, visibleEdges } = useMemo(() => {
      if (collapsedPrefixes.length === 0) return { visibleNodes: nodes, visibleEdges: edges };
      const hiddenIds = new Set<string>();
      const keptNodes: typeof nodes = [];
      for (const node of nodes) {
        if (isNodeHidden(collapsedPrefixes, node.path)) {
          hiddenIds.add(node.id);
        } else {
          keptNodes.push(node);
        }
      }
      const keptEdges = edges.filter(edge => !hiddenIds.has(edge.from) && !hiddenIds.has(edge.to));
      return { visibleNodes: keptNodes, visibleEdges: keptEdges };
    }, [nodes, edges, collapsedPrefixes]);

    // Remember where a collapse button sat on screen at click time so the
    // post-layout camera pan can pin it back under the cursor.
    const pendingRecenterRef = useRef<{
      key: string;
      clientX: number;
      clientY: number;
    } | null>(null);
    // While a collapse-toggle is mid-flight (ELK running, pan pending) we
    // fade the canvas to hide the intermediate shifted layout — otherwise the
    // user sees a flash of the un-pinned graph before the camera recenters.
    const [isRelayouting, setIsRelayouting] = useState(false);

    const findCollapseButton = useCallback((key: string): HTMLElement | null => {
      const container = containerRef.current;
      if (!container) return null;
      const buttons = container.querySelectorAll<HTMLElement>("[data-collapse-path]");
      for (let i = 0; i < buttons.length; i += 1) {
        if (buttons[i].getAttribute("data-collapse-path") === key) return buttons[i];
      }
      return null;
    }, []);

    const wrappedToggleCollapse = useCallback(
      (path: JSONPath) => {
        const key = JSON.stringify(path);
        const btn = findCollapseButton(key);
        if (btn) {
          const rect = btn.getBoundingClientRect();
          pendingRecenterRef.current = {
            key,
            clientX: rect.left + rect.width / 2,
            clientY: rect.top + rect.height / 2,
          };
          setIsRelayouting(true);
        } else {
          pendingRecenterRef.current = null;
        }
        if (isControlled) {
          controlledOnToggle?.(path);
          return;
        }
        setInternalCollapsedPaths(prev =>
          prev.includes(key) ? prev.filter(p => p !== key) : [...prev, key]
        );
      },
      [isControlled, controlledOnToggle, findCollapseButton]
    );

    const collapseContextValue = useMemo(
      () => ({ collapsedSet, onToggleCollapse: wrappedToggleCollapse }),
      [collapsedSet, wrappedToggleCollapse]
    );

    const collapsedPathsRef = useRef(collapsedPaths);
    collapsedPathsRef.current = collapsedPaths;

    const collapseApi = useMemo(
      () => ({
        toggleCollapse: (path: JSONPath) => wrappedToggleCollapse(path),
        collapseAll: () => {
          if (isControlled) return;
          let parsed: unknown;
          try {
            parsed = JSON.parse(jsonText);
          } catch {
            return;
          }
          if (!parsed || typeof parsed !== "object") return;
          const keys = Array.isArray(parsed)
            ? parsed.map((_, i) => i)
            : Object.keys(parsed as Record<string, unknown>);
          const next: string[] = [];
          for (const k of keys) {
            const v = (parsed as Record<string | number, unknown>)[k as string & number];
            if (v && typeof v === "object") {
              if (Array.isArray(v) && v.length === 0) continue;
              if (!Array.isArray(v) && Object.keys(v).length === 0) continue;
              next.push(JSON.stringify([k]));
            }
          }
          setInternalCollapsedPaths(next);
        },
        expandAll: () => {
          if (isControlled) return;
          setInternalCollapsedPaths([]);
        },
        getCollapsedPaths: () => collapsedPathsRef.current ?? [],
      }),
      [isControlled, jsonText, wrappedToggleCollapse]
    );

    useImperativeHandle(ref, () => ({ ...viewPortApi, ...collapseApi }), [
      viewPortApi,
      collapseApi,
    ]);

    const edgeTargetById = useMemo(() => buildEdgeTargetMap(visibleEdges), [visibleEdges]);

    // Signal "relayouting" whenever the collapsed-set changes so the spinner
    // appears immediately on collapse/expand. JSON edits already route
    // through the parse effect which handles `setLoading(true)` on its own,
    // so we scope this trigger to collapse toggles only.
    const visibleNodesRef = useRef(visibleNodes);
    visibleNodesRef.current = visibleNodes;
    const isFirstCollapsedPassRef = useRef(true);
    useEffect(() => {
      if (isFirstCollapsedPassRef.current) {
        isFirstCollapsedPassRef.current = false;
        return;
      }
      if (visibleNodesRef.current.length > 0) setLoading(true);
    }, [collapsedSet]);

    const onLayoutChange = useCallback((layout: ElkRoot) => {
      if (!layout.width || !layout.height) {
        setLoading(false);
        return;
      }

      layoutSizeRef.current = { width: layout.width, height: layout.height };
      setPaneWidth(layout.width + 50);
      setPaneHeight(layout.height + 50);
      setLoading(false);
    }, []);

    // After a collapse toggle triggers relayout, pin the clicked button back
    // under the cursor. We poll each rAF until the button's rect is stable
    // for two consecutive frames (reaflow runs ELK + framer-motion commits
    // the new transforms over several frames on large graphs), then shift
    // the camera by the measured screen-pixel delta.
    useEffect(() => {
      const pending = pendingRecenterRef.current;
      if (!pending) return;
      pendingRecenterRef.current = null;

      let cancelled = false;
      let attempts = 0;
      let lastX: number | null = null;
      let lastY: number | null = null;
      let movementSeen = false;
      const MAX_ATTEMPTS = 180;

      const finish = (x?: number, y?: number) => {
        if (x !== undefined && y !== undefined) {
          const dx = x - pending.clientX;
          const dy = y - pending.clientY;
          if (Math.abs(dx) >= 1 || Math.abs(dy) >= 1) {
            viewPort?.camera?.moveByInClientSpace(dx, dy);
          }
        }
        setIsRelayouting(false);
      };

      const tick = () => {
        if (cancelled) return;
        attempts += 1;
        const btn = findCollapseButton(pending.key);
        if (!btn) {
          if (attempts < MAX_ATTEMPTS) requestAnimationFrame(tick);
          else finish();
          return;
        }
        const rect = btn.getBoundingClientRect();
        const x = rect.left + rect.width / 2;
        const y = rect.top + rect.height / 2;

        if (lastX !== null) {
          const moved = Math.abs(x - lastX) >= 0.5 || Math.abs(y - (lastY ?? 0)) >= 0.5;
          if (moved) {
            movementSeen = true;
          } else if (movementSeen) {
            // Stabilised after detected movement — safe to apply.
            finish(x, y);
            return;
          }
        }

        lastX = x;
        lastY = y;

        if (attempts < MAX_ATTEMPTS) {
          requestAnimationFrame(tick);
        } else if (movementSeen) {
          finish(x, y);
        } else {
          finish();
        }
      };

      const rafId = requestAnimationFrame(tick);
      return () => {
        cancelled = true;
        cancelAnimationFrame(rafId);
        setIsRelayouting(false);
      };
    }, [visibleNodes, visibleEdges, viewPort, findCollapseButton]);

    // Auto-fit on initial load / new data. Gated on `paneWidth`/`paneHeight`
    // as deps: `onLayoutChange` batches the pane-size state updates with
    // `setLoading(false)` in the same commit, so by the time this effect
    // runs the svg has its final width/height attributes and reaflow has
    // finished reconciling. A single rAF then lets paint catch up before
    // measurement.
    useEffect(() => {
      if (initialFitDone) return;
      if (!centerOnLayout) {
        setInitialFitDone(true);
        return;
      }
      if (!viewPort || visibleNodes.length === 0 || loading) return;
      if (!layoutSizeRef.current) return;

      let cancelled = false;
      const rafId = window.requestAnimationFrame(() => {
        if (cancelled) return;
        fitGraphToViewPort(viewPort, containerRef.current, layoutSizeRef.current);
        setInitialFitDone(true);
      });
      return () => {
        cancelled = true;
        window.cancelAnimationFrame(rafId);
      };
    }, [viewPort, visibleNodes, loading, centerOnLayout, initialFitDone, paneWidth, paneHeight]);

    // Stable render factories so reaflow doesn't re-key nodes/edges on every parent render.
    const renderNode = useCallback(
      (nodeProps: NodeProps) => <CustomNode {...nodeProps} onNodeClick={onNodeClick} />,
      [onNodeClick]
    );
    const renderEdge = useCallback(
      (edgeProps: EdgeProps) => (
        <CustomEdge
          {...edgeProps}
          viewPort={viewPort}
          edgeTargetById={edgeTargetById}
          hostElement={containerRef.current}
        />
      ),
      [viewPort, edgeTargetById]
    );

    const bindLongPress = useLongPress(() => setCanvasDragging(containerRef.current, true), {
      threshold: 150,
      onFinish: () => setCanvasDragging(containerRef.current, false),
    });

    const tooLargeContent = renderNodeLimitExceeded?.(totalNodes, maxRenderableNodes);

    return (
      <div
        ref={containerRef}
        className={canvasClassName}
        style={canvasStyle}
        role="img"
        aria-label="JSON data visualization"
        onContextMenu={event => event.preventDefault()}
        {...bindLongPress()}
      >
        {showControls && (
          <Controls
            onFocusRoot={viewPortApi.focusFirstNode}
            onCenterView={viewPortApi.centerView}
            onZoomOut={viewPortApi.zoomOut}
            onZoomIn={viewPortApi.zoomIn}
          />
        )}

        {aboveSupportedLimit &&
          (tooLargeContent ? (
            tooLargeContent
          ) : (
            <div className={styles.tooLarge}>
              {`This graph has ${totalNodes} nodes and exceeds the maxRenderableNodes limit (${maxRenderableNodes}).`}
            </div>
          ))}

        {loading && (
          <div className={styles.overlay}>
            <div className={styles.spinner} />
          </div>
        )}

        <Space
          onCreate={nextViewPort => {
            setViewPort(nextViewPort);
            onViewportCreateRef.current?.(nextViewPort);
          }}
          onContextMenu={event => event.preventDefault()}
          treatTwoFingerTrackPadGesturesLikeTouch={trackpadZoom}
          className="jsoncrack-space"
          style={{
            opacity: initialFitDone && !isRelayouting ? 1 : 0,
            visibility: isRelayouting ? "hidden" : "visible",
            transition: "opacity 120ms",
          }}
        >
          <CollapseContext.Provider value={collapseContextValue}>
            <Canvas
              className="jsoncrack-canvas"
              onLayoutChange={onLayoutChange}
              node={renderNode}
              edge={renderEdge}
              nodes={visibleNodes}
              edges={visibleEdges}
              arrow={null}
              maxHeight={paneHeight}
              maxWidth={paneWidth}
              height={paneHeight}
              width={paneWidth}
              direction={layoutDirection}
              layoutOptions={layoutOptions}
              key={layoutDirection}
              pannable={false}
              zoomable={false}
              animated={false}
              readonly
              dragEdge={null}
              dragNode={null}
              // Disable reaflow's built-in auto-centering of content inside the
              // pane. Passing a nullish `defaultPosition` makes reaflow leave
              // the group at the svg origin so our fit-to-viewport rect math
              // matches reality.
              defaultPosition={null as unknown as undefined}
            />
          </CollapseContext.Provider>
        </Space>
      </div>
    );
  }
);

JSONCrack.displayName = "JSONCrack";