Animate query graph layout transitions

Compute the final layout once and interpolate node size and layout from a shared clock, avoiding intermediate relayout jumps.

Animate subtree additions and removals from or toward their parent while fading nodes, edges, and labels. Delay entry animations until React Flow has measured the new nodes and preserve exit destinations across interrupted transitions.

Disable pointer interaction for transient elements so they do not affect hover behavior.

Author: vogelsgesang

query-graphs/src/ui/ColoredEdge.tsx

@@ -1,5 +1,5 @@
 import type {Edge, EdgeProps} from "@xyflow/react";
-import {BaseEdge, getBezierPath} from "@xyflow/react";
+import {BezierEdge} from "@xyflow/react";
 
 // Must be a `type` instead of the usual `interface`.
 // xyflow's `Node<NodeData>` requires NodeData to satisfy `Record<string, unknown>` and
@@ -18,9 +18,7 @@ export type ColoredGraphEdge = Edge<ColoredEdgeData, "colored">;
 // stroke is painted with a gradient of contiguous color bands (one per color,
 // running source->target); a single color is drawn as a solid stroke.
 export function ColoredEdge(props: EdgeProps<ColoredGraphEdge>) {
-    const {id, sourceX, sourceY, targetX, targetY, markerEnd, label, labelStyle, style} = props;
-    const [edgePath, labelX, labelY] = getBezierPath(props);
-
+    const {id, sourceX, sourceY, targetX, targetY, style} = props;
     const colors = props.data?.colors ?? [];
     const multi = colors.length > 1;
 
@@ -46,28 +44,10 @@ export function ColoredEdge(props: EdgeProps<ColoredGraphEdge>) {
                         ])}
                     </linearGradient>
                 </defs>
-                <BaseEdge
-                    path={edgePath}
-                    labelX={labelX}
-                    labelY={labelY}
-                    label={label}
-                    labelStyle={labelStyle}
-                    markerEnd={markerEnd}
-                    style={{...style, stroke: `url(#${gradientId})`}}
-                />
+                <BezierEdge {...props} style={{...style, stroke: `url(#${gradientId})`}} />
             </>
         );
     }
 
-    return (
-        <BaseEdge
-            path={edgePath}
-            labelX={labelX}
-            labelY={labelY}
-            label={label}
-            labelStyle={labelStyle}
-            markerEnd={markerEnd}
-            style={{...style, stroke: colors[0] ?? style?.stroke}}
-        />
-    );
+    return <BezierEdge {...props} style={{...style, stroke: colors[0] ?? style?.stroke}} />;
 }

query-graphs/src/ui/QueryGraph.tsx

@@ -11,6 +11,7 @@ import {QueryNode} from "./QueryNode";
 import type {QueryGraphNode} from "./QueryNode";
 import {ColoredEdge} from "./ColoredEdge";
 import {createGraphRenderingStore, GraphRenderingStoreContext, useGraphRenderingStore} from "./store";
+import {useAnimatedGraphLayout} from "./useAnimatedGraphLayout";
 import "./QueryGraph.css";
 
 interface QueryGraphProps {
@@ -40,29 +41,34 @@ function QueryGraphInternal({treeDescription, children, nodeIdMapping}: QueryGra
     // Keep React Flow's measurements in the controlled node objects. Dropping them when
     // recomputing the layout makes React Flow repeatedly hide and re-initialize the nodes.
     const nodeDimensions = useGraphRenderingStore((s) => s.nodeDimensions);
-    const updateNodeDimensions = useGraphRenderingStore((s) => s.updateNodeDimensions);
+    const updateNodeMeasurements = useGraphRenderingStore((s) => s.updateNodeMeasurements);
     const onNodesChange = useCallback(
         (changes: NodeChange<QueryGraphNode>[]) => {
             const updates = changes.flatMap((change) => {
                 if (change.type !== "dimensions" || change.dimensions === undefined) return [];
                 return [[change.id, change.dimensions] as const];
             });
-            updateNodeDimensions(updates);
+            updateNodeMeasurements(updates);
         },
-        [updateNodeDimensions],
+        [updateNodeMeasurements],
     );
 
-    // Layout the tree using the dimensions measured by React Flow itself.
     const expandedSubtrees = useGraphRenderingStore((s) => s.expandedSubtrees);
+    const layoutAnimation = useGraphRenderingStore((s) => s.layoutAnimation);
     const layout = useMemo(
         () => layoutTree(treeDescription, nodeIdMapping, nodeDimensions, expandedSubtrees),
         [treeDescription, nodeIdMapping, nodeDimensions, expandedSubtrees],
     );
+    const animatedLayout = useAnimatedGraphLayout(
+        layout,
+        layoutAnimation,
+        layout.nodes.every((node) => nodeDimensions.has(node.id)),
+    );
 
     return (
         <ReactFlow
-            nodes={layout.nodes}
-            edges={layout.edges}
+            nodes={animatedLayout.nodes}
+            edges={animatedLayout.edges}
             nodeOrigin={[0.5, 0]}
             nodeTypes={nodeTypes}
             edgeTypes={edgeTypes}
@@ -84,13 +90,13 @@ function QueryGraphInternal({treeDescription, children, nodeIdMapping}: QueryGra
 }
 
 function createGraphState(treeDescription: TreeDescription) {
-    let nextId = 0;
+    let nextNodeId = 0;
     const nodeIdMapping = new Map<TreeNode, string>();
     const expandedSubtrees: Record<string, boolean> = {};
     visitTreeNodes(
         treeDescription.root,
         (node) => {
-            const id = "" + nextId++;
+            const id = "" + nextNodeId++;
             nodeIdMapping.set(node, id);
             if (node.expandedByDefault) expandedSubtrees[id] = true;
         },

query-graphs/src/ui/QueryNode.css

@@ -94,8 +94,6 @@
     max-width: 0;
     max-height: 0;
     overflow: hidden;
-    transition-property: max-width, max-height;
-    transition-duration: .2s;
 
     .qg-graph-node.qg-expanded & {
         max-width: 30em;

query-graphs/src/ui/QueryNode.tsx

@@ -1,43 +1,117 @@
 import type {ReactElement, MouseEvent} from "react";
-import {memo, useCallback} from "react";
+import {memo, useCallback, useLayoutEffect, useRef} from "react";
 import type {Node, NodeProps} from "@xyflow/react";
 import {Handle, Position} from "@xyflow/react";
 import cc from "classcat";
 import type {TreeNode} from "../tree-description";
 import {NodeIcon} from "./NodeIcon";
 import "./QueryNode.css";
 import {useGraphRenderingStore} from "./store";
+import {animationStartTime, graphAnimationProgress} from "./animation-timing";
 
 export type QueryGraphNode = Node<TreeNode, "querynode">;
 
 function QueryNode({data, id}: NodeProps<QueryGraphNode>) {
     const expanded = useGraphRenderingStore((s) => s.expandedNodes[id]);
     const toggleNode = useGraphRenderingStore((s) => s.toggleExpandedNode);
+    const finishNodeAnimation = useGraphRenderingStore((s) => s.finishNodeAnimation);
+    const sizeAnimation = useGraphRenderingStore((s) => s.nodeSizeAnimations.get(id));
     const subtreeExpanded = useGraphRenderingStore((s) => s.expandedSubtrees[id]);
     const toggleSubtree = useGraphRenderingStore((s) => s.toggleExpandedSubtree);
 
     const hasProperties = data.properties?.size;
     const hasSubtree = data.collapsedChildren && data.collapsedChildren.length > 0;
+    const graphNodeRef = useRef<HTMLDivElement>(null);
+    const bodyWrapperRef = useRef<HTMLDivElement>(null);
+
+    const measureTargetDimensions = useCallback((targetExpanded: boolean) => {
+        const graphNode = graphNodeRef.current;
+        const flowNode = graphNode?.closest<HTMLElement>(".react-flow__node");
+        if (graphNode === null || flowNode === null || flowNode === undefined) {
+            return {node: {width: 50, height: 50}, body: {width: 0, height: 0}};
+        }
+
+        const clone = flowNode.cloneNode(true) as HTMLElement;
+        const clonedGraphNode = clone.querySelector<HTMLElement>(".qg-graph-node");
+        const clonedBodyWrapper = clone.querySelector<HTMLElement>(".qg-graph-node-body-wrapper");
+        clone.style.position = "fixed";
+        clone.style.transform = "none";
+        clone.style.visibility = "hidden";
+        clone.style.pointerEvents = "none";
+        clonedGraphNode?.classList.toggle("qg-expanded", targetExpanded);
+        clonedBodyWrapper?.style.removeProperty("width");
+        clonedBodyWrapper?.style.removeProperty("height");
+        clonedBodyWrapper?.style.removeProperty("max-width");
+        clonedBodyWrapper?.style.removeProperty("max-height");
+        flowNode.parentElement?.append(clone);
+        const measurements = {
+            node: {width: clone.offsetWidth, height: clone.offsetHeight},
+            body: {width: clonedBodyWrapper?.offsetWidth ?? 0, height: clonedBodyWrapper?.offsetHeight ?? 0},
+        };
+        clone.remove();
+        return measurements;
+    }, []);
+
+    useLayoutEffect(() => {
+        const element = bodyWrapperRef.current;
+        if (element === null) return;
+        if (sizeAnimation === undefined) {
+            element.style.removeProperty("width");
+            element.style.removeProperty("height");
+            element.style.removeProperty("max-width");
+            element.style.removeProperty("max-height");
+            return;
+        }
+
+        element.style.maxWidth = "none";
+        element.style.maxHeight = "none";
+        let animationFrame: number | undefined;
+        const step = (now: number) => {
+            const progress = graphAnimationProgress(sizeAnimation.startedAt, now);
+            const width = sizeAnimation.from.width + (sizeAnimation.to.width - sizeAnimation.from.width) * progress;
+            const height = sizeAnimation.from.height + (sizeAnimation.to.height - sizeAnimation.from.height) * progress;
+            element.style.width = `${width}px`;
+            element.style.height = `${height}px`;
+            if (progress < 1) animationFrame = requestAnimationFrame(step);
+            else finishNodeAnimation(id);
+        };
+        step(sizeAnimation.startedAt);
+        return () => {
+            if (animationFrame !== undefined) cancelAnimationFrame(animationFrame);
+        };
+    }, [finishNodeAnimation, id, sizeAnimation]);
 
     const onClick = useCallback(
         (e: MouseEvent) => {
             if (e.shiftKey) {
-                if (hasSubtree) toggleSubtree(id);
+                if (hasSubtree) toggleSubtree(id, animationStartTime());
             } else {
-                if (hasProperties) toggleNode(id);
+                if (hasProperties) {
+                    const target = measureTargetDimensions(!expanded);
+                    const bodyWrapper = bodyWrapperRef.current;
+                    const startedAt = animationStartTime();
+                    const sizeAnimation =
+                        startedAt === undefined || bodyWrapper === null
+                            ? undefined
+                            : {
+                                  from: {width: bodyWrapper.offsetWidth, height: bodyWrapper.offsetHeight},
+                                  to: target.body,
+                                  startedAt,
+                              };
+                    toggleNode(id, target.node, sizeAnimation);
+                }
             }
             e.stopPropagation();
         },
-        [toggleNode, toggleSubtree, hasProperties, hasSubtree, id],
+        [toggleNode, toggleSubtree, hasProperties, hasSubtree, expanded, id, measureTargetDimensions],
     );
     const onSubtreeHandleClick = useCallback(
         (e: MouseEvent) => {
-            if (hasSubtree) toggleSubtree(id);
+            if (hasSubtree) toggleSubtree(id, animationStartTime());
             e.stopPropagation();
         },
         [toggleSubtree, hasSubtree, id],
     );
-
     const children = [] as ReactElement[];
     for (const [key, value] of (data.properties || []).entries()) {
         children.push(
@@ -75,15 +149,15 @@ function QueryNode({data, id}: NodeProps<QueryGraphNode>) {
     return (
         <>
             <Handle type="target" position={Position.Top} />
-            <div className={nodeClassName} onClick={onClick}>
+            <div ref={graphNodeRef} className={nodeClassName} onClick={onClick}>
                 <div className="qg-graph-node-head">
                     {colorBar(data.barsAbove, "above")}
                     <NodeIcon icon={data.icon} iconColor={data.iconColor} />
                     <div className="qg-graph-node-label" style={{background: data.nodeColor}}>
                         {data.name}
                     </div>
                 </div>
-                <div className="qg-graph-node-body-wrapper nowheel">
+                <div ref={bodyWrapperRef} className="qg-graph-node-body-wrapper nowheel">
                     <div className="qg-graph-node-body">{children}</div>
                 </div>
                 {colorBar(data.barsBelow, "below")}

query-graphs/src/ui/animation-timing.ts

@@ -0,0 +1,10 @@
+export const graphAnimationDuration = 200;
+
+export function animationStartTime(): number | undefined {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches ? undefined : performance.now();
+}
+
+export function graphAnimationProgress(startTime: number, now: number): number {
+    const elapsed = Math.min(1, Math.max(0, (now - startTime) / graphAnimationDuration));
+    return (1 - Math.cos(Math.PI * elapsed)) / 2;
+}

query-graphs/src/ui/store.ts

@@ -6,15 +6,38 @@ import {createStore} from "zustand/vanilla";
 import type {StoreApi} from "zustand/vanilla";
 import {assertNotNull} from "../assert";
 
+export interface NodeSizeAnimation {
+    from: Dimensions;
+    to: Dimensions;
+    startedAt: number;
+}
+
+export interface LayoutAnimation {
+    kind: "resize" | "subtree";
+    startedAt: number;
+    // Entering and exiting nodes animate from or toward this node's position.
+    anchorNodeId?: string;
+}
+
+export interface GraphNodeDimensions {
+    // React Flow's latest measurement, preserved on its controlled node object.
+    measured: Dimensions;
+    // The endpoint used for layout, frozen while the measured size animates toward it.
+    target: Dimensions;
+}
+
 export interface GraphRenderingState {
     // `expandedNodes` tracks which nodes show their property detail panel (toggled by a plain click).
     expandedNodes: Record<string, boolean>;
-    toggleExpandedNode: (nodeId: string) => void;
+    toggleExpandedNode: (nodeId: string, targetDimensions: Dimensions, sizeAnimation: NodeSizeAnimation | undefined) => void;
+    finishNodeAnimation: (nodeId: string) => void;
     // `expandedSubtrees` tracks which nodes reveal their `collapsedChildren` (toggled by shift-click or the +/- handle).
     expandedSubtrees: Record<string, boolean>;
-    toggleExpandedSubtree: (nodeId: string) => void;
-    nodeDimensions: Map<string, Dimensions>;
-    updateNodeDimensions: (updates: readonly (readonly [string, Dimensions])[]) => void;
+    toggleExpandedSubtree: (nodeId: string, startedAt: number | undefined) => void;
+    nodeDimensions: ReadonlyMap<string, GraphNodeDimensions>;
+    nodeSizeAnimations: ReadonlyMap<string, NodeSizeAnimation>;
+    layoutAnimation: LayoutAnimation | undefined;
+    updateNodeMeasurements: (updates: readonly (readonly [string, Dimensions])[]) => void;
 }
 
 export type GraphRenderingStore = StoreApi<GraphRenderingState>;
@@ -24,29 +47,61 @@ export function createGraphRenderingStore(expandedSubtrees: Record<string, boole
         devtools((set) => ({
             expandedNodes: {},
             expandedSubtrees,
-            toggleExpandedNode: (nodeId) =>
-                set((state) => ({
-                    expandedNodes: {
-                        ...state.expandedNodes,
-                        [nodeId]: !state.expandedNodes[nodeId],
-                    },
-                })),
-            toggleExpandedSubtree: (nodeId) =>
+            toggleExpandedNode: (nodeId, targetDimensions, sizeAnimation) =>
+                set((state) => {
+                    const nodeSizeAnimations = new Map(state.nodeSizeAnimations);
+                    if (sizeAnimation === undefined) nodeSizeAnimations.delete(nodeId);
+                    else nodeSizeAnimations.set(nodeId, sizeAnimation);
+                    const nodeDimensions = new Map(state.nodeDimensions);
+                    const previousDimensions = nodeDimensions.get(nodeId);
+                    nodeDimensions.set(nodeId, {
+                        measured: previousDimensions?.measured ?? targetDimensions,
+                        target: targetDimensions,
+                    });
+                    return {
+                        expandedNodes: {
+                            ...state.expandedNodes,
+                            [nodeId]: !state.expandedNodes[nodeId],
+                        },
+                        nodeDimensions,
+                        nodeSizeAnimations,
+                        layoutAnimation:
+                            sizeAnimation === undefined ? undefined : {kind: "resize", startedAt: sizeAnimation.startedAt},
+                    };
+                }),
+            finishNodeAnimation: (nodeId) =>
+                set((state) => {
+                    if (!state.nodeSizeAnimations.has(nodeId)) return state;
+                    const nodeSizeAnimations = new Map(state.nodeSizeAnimations);
+                    nodeSizeAnimations.delete(nodeId);
+                    return {nodeSizeAnimations};
+                }),
+            toggleExpandedSubtree: (nodeId, startedAt) =>
                 set((state) => ({
                     expandedSubtrees: {
                         ...state.expandedSubtrees,
                         [nodeId]: !state.expandedSubtrees[nodeId],
                     },
+                    layoutAnimation: startedAt === undefined ? undefined : {kind: "subtree", startedAt, anchorNodeId: nodeId},
                 })),
             nodeDimensions: new Map(),
-            updateNodeDimensions: (updates) =>
+            nodeSizeAnimations: new Map(),
+            layoutAnimation: undefined,
+            updateNodeMeasurements: (updates) =>
                 set((state) => {
-                    let nodeDimensions: Map<string, Dimensions> | undefined;
-                    for (const [nodeId, dimensions] of updates) {
+                    let nodeDimensions: Map<string, GraphNodeDimensions> | undefined;
+                    for (const [nodeId, measured] of updates) {
                         const previous = state.nodeDimensions.get(nodeId);
-                        if (previous?.width === dimensions.width && previous.height === dimensions.height) continue;
+                        const target = state.nodeSizeAnimations.has(nodeId) ? (previous?.target ?? measured) : measured;
+                        if (
+                            previous?.measured.width === measured.width &&
+                            previous.measured.height === measured.height &&
+                            previous.target.width === target.width &&
+                            previous.target.height === target.height
+                        )
+                            continue;
                         nodeDimensions ??= new Map(state.nodeDimensions);
-                        nodeDimensions.set(nodeId, dimensions);
+                        nodeDimensions.set(nodeId, {measured, target});
                     }
                     return nodeDimensions === undefined ? state : {nodeDimensions};
                 }),