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 {
@@ -53,16 +54,23 @@ function QueryGraphInternal({treeDescription, children, nodeIdMapping}: QueryGra
     );
 
     // Layout the tree using the dimensions measured by React Flow itself.
+    const layoutDimensions = useGraphRenderingStore((s) => s.layoutDimensions);
     const expandedSubtrees = useGraphRenderingStore((s) => s.expandedSubtrees);
+    const layoutAnimation = useGraphRenderingStore((s) => s.layoutAnimation);
     const layout = useMemo(
-        () => layoutTree(treeDescription, nodeIdMapping, nodeDimensions, expandedSubtrees),
-        [treeDescription, nodeIdMapping, nodeDimensions, expandedSubtrees],
+        () => layoutTree(treeDescription, nodeIdMapping, layoutDimensions, nodeDimensions, expandedSubtrees),
+        [treeDescription, nodeIdMapping, layoutDimensions, nodeDimensions, expandedSubtrees],
+    );
+    const animatedLayout = useAnimatedGraphLayout(
+        layout,
+        layoutAnimation,
+        layout.nodes.every((node) => layoutDimensions.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 +92,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,10 +94,9 @@
     max-width: 0;
     max-height: 0;
     overflow: hidden;
-    transition-property: max-width, max-height;
-    transition-duration: .2s;
 
-    .qg-graph-node.qg-expanded & {
+    .qg-graph-node.qg-expanded &,
+    .qg-graph-node.qg-animating & {
         max-width: 30em;
         max-height: 20em;
     }

query-graphs/src/ui/QueryNode.tsx

@@ -1,43 +1,112 @@
 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);
+        clonedGraphNode?.classList.remove("qg-animating");
+        clonedBodyWrapper?.style.removeProperty("width");
+        clonedBodyWrapper?.style.removeProperty("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");
+            return;
+        }
+
+        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(
@@ -51,6 +120,7 @@ function QueryNode({data, id}: NodeProps<QueryGraphNode>) {
         "qg-graph-node",
         {
             "qg-expanded": expanded,
+            "qg-animating": sizeAnimation !== undefined,
             "qg-collapsed": hasProperties && !expanded,
             "qg-no-props": !hasProperties,
         },
@@ -75,15 +145,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,14 +6,32 @@ 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;
+    anchorNodeId?: string;
+}
+
 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;
+    toggleExpandedSubtree: (nodeId: string, startedAt: number | undefined) => void;
+    // React Flow's latest measurements are kept on its controlled node objects.
     nodeDimensions: Map<string, Dimensions>;
+    // Layout dimensions jump directly to an animation's endpoint, avoiding intermediate relayouts.
+    layoutDimensions: Map<string, Dimensions>;
+    nodeSizeAnimations: ReadonlyMap<string, NodeSizeAnimation>;
+    layoutAnimation: LayoutAnimation | undefined;
     updateNodeDimensions: (updates: readonly (readonly [string, Dimensions])[]) => void;
 }
 
@@ -24,31 +42,64 @@ 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);
+                    return {
+                        expandedNodes: {
+                            ...state.expandedNodes,
+                            [nodeId]: !state.expandedNodes[nodeId],
+                        },
+                        layoutDimensions: new Map(state.layoutDimensions).set(nodeId, targetDimensions),
+                        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(),
+            layoutDimensions: new Map(),
+            nodeSizeAnimations: new Map(),
+            layoutAnimation: undefined,
             updateNodeDimensions: (updates) =>
                 set((state) => {
                     let nodeDimensions: Map<string, Dimensions> | undefined;
+                    let layoutDimensions: Map<string, Dimensions> | undefined;
                     for (const [nodeId, dimensions] of updates) {
                         const previous = state.nodeDimensions.get(nodeId);
-                        if (previous?.width === dimensions.width && previous.height === dimensions.height) continue;
-                        nodeDimensions ??= new Map(state.nodeDimensions);
-                        nodeDimensions.set(nodeId, dimensions);
+                        if (previous?.width !== dimensions.width || previous.height !== dimensions.height) {
+                            nodeDimensions ??= new Map(state.nodeDimensions);
+                            nodeDimensions.set(nodeId, dimensions);
+                        }
+                        if (!state.nodeSizeAnimations.has(nodeId)) {
+                            const previousLayout = state.layoutDimensions.get(nodeId);
+                            if (previousLayout?.width !== dimensions.width || previousLayout.height !== dimensions.height) {
+                                layoutDimensions ??= new Map(state.layoutDimensions);
+                                layoutDimensions.set(nodeId, dimensions);
+                            }
+                        }
                     }
-                    return nodeDimensions === undefined ? state : {nodeDimensions};
+                    if (nodeDimensions === undefined && layoutDimensions === undefined) return state;
+                    return {
+                        ...(nodeDimensions === undefined ? {} : {nodeDimensions}),
+                        ...(layoutDimensions === undefined ? {} : {layoutDimensions}),
+                    };
                 }),
         })),
     );

query-graphs/src/ui/tree-layout.ts

@@ -24,6 +24,7 @@ interface TreeLayout {
 export function layoutTree(
     treeData: TreeDescription,
     nodeIds: Map<TreeNode, string>,
+    layoutDimensions: Map<string, Dimensions>,
     nodeDimensions: Map<string, Dimensions>,
     expandedSubtrees: Record<string, boolean>,
 ): TreeLayout {
@@ -41,7 +42,7 @@ export function layoutTree(
         .nodeSize((d) => {
             const id = nodeIds.get(d.data);
             assertNotNull(id);
-            const dim = nodeDimensions.get(id);
+            const dim = layoutDimensions.get(id);
             if (dim === undefined) {
                 // React Flow measures new nodes after their first render. It keeps them hidden until then,
                 // so this placeholder only determines where that measurement render happens.