@principal-ai/principal-view-react 0.14.0 → 0.14.1

package/src/components/GraphRenderer.tsx

@@ -59,6 +59,11 @@ import {
   convertToXYFlowNodes,
   convertToXYFlowEdges,
 } from '../utils/graphConverter';
+import {
+  getCanvasBounds,
+  calculateInitialViewport,
+  type Viewport,
+} from '../utils/canvasBounds';
 import { GraphEditProvider } from '../contexts/GraphEditContext';
 import { useUndoRedo, type HistoryEntry } from '../hooks/useUndoRedo';
 
@@ -258,6 +263,20 @@ interface GraphRendererBaseProps {
    */
   onCopy?: (selectedNodeIds: string[]) => void;
 
+  /**
+   * Container width in pixels. When provided along with containerHeight,
+   * enables calculating the initial viewport synchronously to avoid the
+   * "zoom in then animate out" effect on initial render.
+   */
+  containerWidth?: number;
+
+  /**
+   * Container height in pixels. When provided along with containerWidth,
+   * enables calculating the initial viewport synchronously to avoid the
+   * "zoom in then animate out" effect on initial render.
+   */
+  containerHeight?: number;
+
 }
 
 /** GraphRenderer props - canvas format only */
@@ -514,6 +533,8 @@ interface GraphRendererInnerProps {
   draggableNodeIds?: Set<string>;
   onNodeDragStop?: (nodeId: string, position: { x: number; y: number }) => void;
   onCopy?: (selectedNodeIds: string[]) => void;
+  /** Pre-calculated initial viewport to avoid zoom animation on mount */
+  initialViewport?: Viewport;
 }
 
 /**
@@ -553,6 +574,7 @@ const GraphRendererInner: React.FC<GraphRendererInnerProps> = ({
   draggableNodeIds,
   onNodeDragStop: onNodeDragStopProp,
   onCopy,
+  initialViewport,
 }) => {
   const { fitView, fitBounds, getNodes } = useReactFlow();
   const updateNodeInternals = useUpdateNodeInternals();
@@ -2172,6 +2194,11 @@ const GraphRendererInner: React.FC<GraphRendererInnerProps> = ({
       return;
     }
 
+    // Skip delayed fitView if we have a pre-calculated initial viewport
+    if (initialViewport) {
+      return;
+    }
+
     const timeoutId = setTimeout(() => {
       fitView({
         padding: 0.2,
@@ -2183,7 +2210,7 @@ const GraphRendererInner: React.FC<GraphRendererInnerProps> = ({
     }, 100);
 
     return () => clearTimeout(timeoutId);
-  }, [baseNodesKey, baseEdgesKey, fitView, fitViewDuration, fitViewToNodeIds]);
+  }, [baseNodesKey, baseEdgesKey, fitView, fitViewDuration, fitViewToNodeIds, initialViewport]);
 
   // Create a stable key from fitViewToNodeIds for dependency tracking
   const fitViewToNodeIdsKey = useMemo(
@@ -2249,6 +2276,7 @@ const GraphRendererInner: React.FC<GraphRendererInnerProps> = ({
         edgeTypes={edgeTypes}
         minZoom={0.1}
         maxZoom={4}
+        defaultViewport={initialViewport}
         defaultEdgeOptions={{ type: 'custom' }}
         onEdgeClick={onEdgeClick}
         onNodeClick={onNodeClick}
@@ -2615,6 +2643,8 @@ export const GraphRenderer = forwardRef<GraphRendererHandle, GraphRendererProps>
     className,
     width = '100%',
     height = '100%',
+    containerWidth,
+    containerHeight,
   } = props;
   const { theme } = useTheme();
   const containerRef = useRef<HTMLDivElement>(null);
@@ -2629,6 +2659,20 @@ export const GraphRenderer = forwardRef<GraphRendererHandle, GraphRendererProps>
   // Also inject scope colors (for border) and span colors (for fill)
   const canvasData = useCanvasToLegacy(canvas, library, spansCanvas, workflowSpanPattern);
 
+  // Calculate initial viewport if container dimensions are provided
+  // This avoids the "zoom in then animate out" effect on initial render
+  const initialViewport = useMemo(() => {
+    if (!containerWidth || !containerHeight || !canvas) {
+      return undefined;
+    }
+    const bounds = getCanvasBounds(canvas);
+    return calculateInitialViewport(bounds, containerWidth, containerHeight, {
+      padding: 0.2,
+      minZoom: 0.1,
+      maxZoom: 1.5,
+    });
+  }, [canvas, containerWidth, containerHeight]);
+
   // Debug: Log canvas data to help diagnose disappearing edges
   if (process.env.NODE_ENV === 'development') {
     console.log('[GraphRenderer] Canvas data:', {
@@ -2812,6 +2856,7 @@ export const GraphRenderer = forwardRef<GraphRendererHandle, GraphRendererProps>
             draggableNodeIds={draggableNodeIds}
             onNodeDragStop={onNodeDragStop}
             onCopy={onCopy}
+            initialViewport={initialViewport}
           />
         </ReactFlowProvider>
       </TooltipPortalContext.Provider>

package/src/index.ts

@@ -77,5 +77,5 @@ export {
   swapNodePositions,
   swapEdgeSides,
 } from './utils/orientationUtils';
-export { getCanvasBounds, getCanvasDisplaySize } from './utils/canvasBounds';
-export type { CanvasBounds } from './utils/canvasBounds';
+export { getCanvasBounds, getCanvasDisplaySize, calculateInitialViewport } from './utils/canvasBounds';
+export type { CanvasBounds, Viewport } from './utils/canvasBounds';

package/src/stories/GraphRenderer.stories.tsx

@@ -2992,3 +2992,148 @@ export const FitViewToNodes: Story = {
     },
   },
 };
+
+// ============================================================================
+// Initial Viewport Comparison Story
+// ============================================================================
+
+const InitialViewportComparisonTemplate = () => {
+  const [key, setKey] = React.useState(0);
+
+  const handleRemount = () => {
+    setKey((k) => k + 1);
+  };
+
+  return (
+    <div>
+      <div
+        style={{
+          marginBottom: 16,
+          padding: 12,
+          backgroundColor: '#fef3c7',
+          borderRadius: 4,
+          border: '1px solid #f59e0b',
+        }}
+      >
+        <strong style={{ color: '#92400e' }}>Initial Viewport Comparison</strong>
+        <div style={{ marginTop: 8, fontSize: 12, color: '#78350f' }}>
+          <p style={{ margin: '4px 0' }}>
+            Compare the loading behavior with and without pre-calculated viewport dimensions.
+          </p>
+          <p style={{ margin: '8px 0 4px 0' }}>
+            <strong>Left:</strong> Default behavior - starts at zoom=1, then animates to fit
+          </p>
+          <p style={{ margin: '4px 0' }}>
+            <strong>Right:</strong> With <code>containerWidth</code>/<code>containerHeight</code> - instant correct positioning
+          </p>
+          <button
+            onClick={handleRemount}
+            style={{
+              marginTop: 12,
+              padding: '8px 16px',
+              backgroundColor: '#f59e0b',
+              color: 'white',
+              border: 'none',
+              borderRadius: 4,
+              cursor: 'pointer',
+              fontWeight: 'bold',
+              fontSize: 14,
+            }}
+          >
+            Remount Both (to see initial load behavior)
+          </button>
+        </div>
+      </div>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <div style={{ flex: 1 }}>
+          <div
+            style={{
+              padding: '8px 12px',
+              backgroundColor: '#fee2e2',
+              borderRadius: '4px 4px 0 0',
+              border: '1px solid #fca5a5',
+              borderBottom: 'none',
+              fontSize: 12,
+              fontWeight: 'bold',
+              color: '#991b1b',
+            }}
+          >
+            Without containerWidth/Height (animated)
+          </div>
+          <div
+            key={`animated-${key}`}
+            style={{ width: '100%', height: '500px', border: '1px solid #fca5a5' }}
+          >
+            <GraphRenderer canvas={versionRegistryCanvas} />
+          </div>
+        </div>
+        <div style={{ flex: 1 }}>
+          <div
+            style={{
+              padding: '8px 12px',
+              backgroundColor: '#dcfce7',
+              borderRadius: '4px 4px 0 0',
+              border: '1px solid #86efac',
+              borderBottom: 'none',
+              fontSize: 12,
+              fontWeight: 'bold',
+              color: '#166534',
+            }}
+          >
+            With containerWidth/Height (instant)
+          </div>
+          <div
+            key={`instant-${key}`}
+            style={{ width: '100%', height: '500px', border: '1px solid #86efac' }}
+          >
+            <GraphRenderer
+              canvas={versionRegistryCanvas}
+              containerWidth={600}
+              containerHeight={500}
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const InitialViewportComparison: Story = {
+  render: () => <InitialViewportComparisonTemplate />,
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**Initial Viewport Comparison** - Demonstrates the difference between default and pre-calculated viewport behavior.
+
+**The Problem:**
+By default, React Flow renders at zoom=1 centered at origin, then after ~100ms calls \`fitView()\` with a 200ms animation.
+This creates a visible "zoom in then zoom out" effect on initial load.
+
+**The Solution:**
+When you provide \`containerWidth\` and \`containerHeight\` props, the component calculates the correct viewport
+(zoom level and pan position) synchronously before the first render. This eliminates the animation entirely.
+
+**How to Use:**
+\`\`\`tsx
+<GraphRenderer
+  canvas={myCanvas}
+  containerWidth={800}   // Your container's width in pixels
+  containerHeight={600}  // Your container's height in pixels
+/>
+\`\`\`
+
+**When to Use:**
+- When you know the container dimensions ahead of time (fixed layouts)
+- When the container size comes from a layout system (CSS grid, flexbox with known dimensions)
+- When you want to eliminate any visual "settling" on initial load
+
+**When NOT to Use:**
+- When container dimensions are dynamic/unknown until mount
+- When using percentage-based sizing without a parent with known dimensions
+- In these cases, the default delayed fitView behavior is still appropriate
+        `,
+      },
+    },
+  },
+};

package/src/stories/data/graph-converter-test-execution.json

@@ -2,7 +2,7 @@
   {
     "id": "span-1",
     "name": "rules.lint.with.violations",
-    "startTime": 1773856917201,
+    "startTime": 1773938297323,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "rules.lint.with.violations",
@@ -11,7 +11,7 @@
     },
     "events": [
       {
-        "time": 1773856917201,
+        "time": 1773938297324,
         "name": "test.started",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -21,7 +21,7 @@
         }
       },
       {
-        "time": 1773856917201,
+        "time": 1773938297324,
         "name": "engine.creating",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -30,7 +30,7 @@
         }
       },
       {
-        "time": 1773856917201,
+        "time": 1773938297324,
         "name": "engine.created",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -39,7 +39,7 @@
         }
       },
       {
-        "time": 1773856917201,
+        "time": 1773938297324,
         "name": "lint.starting",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -50,7 +50,7 @@
         }
       },
       {
-        "time": 1773856917205,
+        "time": 1773938297328,
         "name": "lint.completed",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -62,7 +62,7 @@
         }
       },
       {
-        "time": 1773856917205,
+        "time": 1773938297328,
         "name": "violations.analyzed",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -74,13 +74,13 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917205,
-    "duration": 4
+    "endTime": 1773938297328,
+    "duration": 5
   },
   {
     "id": "span-2",
     "name": "rules.lint.valid.config",
-    "startTime": 1773856917205,
+    "startTime": 1773938297328,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "rules.lint.valid.config",
@@ -89,7 +89,7 @@
     },
     "events": [
       {
-        "time": 1773856917205,
+        "time": 1773938297328,
         "name": "test.started",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -100,7 +100,7 @@
         }
       },
       {
-        "time": 1773856917205,
+        "time": 1773938297328,
         "name": "lint.starting",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -110,7 +110,7 @@
         }
       },
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "lint.completed",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -122,13 +122,13 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917206,
+    "endTime": 1773938297329,
     "duration": 1
   },
   {
     "id": "span-3",
     "name": "rules.lint.severity.override",
-    "startTime": 1773856917206,
+    "startTime": 1773938297329,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "rules.lint.severity.override",
@@ -137,7 +137,7 @@
     },
     "events": [
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "test.started",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -147,7 +147,7 @@
         }
       },
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "lint.starting",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -157,7 +157,7 @@
         }
       },
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "lint.completed",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -168,13 +168,13 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917206,
+    "endTime": 1773938297329,
     "duration": 0
   },
   {
     "id": "span-4",
     "name": "rules.lint.disabled.rules",
-    "startTime": 1773856917206,
+    "startTime": 1773938297329,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "rules.lint.disabled.rules",
@@ -183,7 +183,7 @@
     },
     "events": [
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "test.started",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -193,7 +193,7 @@
         }
       },
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "lint.starting",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -202,7 +202,7 @@
         }
       },
       {
-        "time": 1773856917206,
+        "time": 1773938297329,
         "name": "lint.completed",
         "attributes": {
           "code.filepath": "rules-engine-instrumented.test.ts",
@@ -214,13 +214,13 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917206,
-    "duration": 0
+    "endTime": 1773938297330,
+    "duration": 1
   },
   {
     "id": "span-5",
     "name": "should convert simple config to nodes and edges",
-    "startTime": 1773856917458,
+    "startTime": 1773938297456,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "should convert simple config to nodes and edges",
@@ -231,7 +231,7 @@
     },
     "events": [
       {
-        "time": 1773856917458,
+        "time": 1773938297456,
         "name": "setup.started",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -240,7 +240,7 @@
         }
       },
       {
-        "time": 1773856917458,
+        "time": 1773938297456,
         "name": "setup.complete",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -250,7 +250,7 @@
         }
       },
       {
-        "time": 1773856917458,
+        "time": 1773938297456,
         "name": "execution.started",
         "attributes": {
           "code.filepath": "GraphConverter.ts",
@@ -259,7 +259,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "execution.complete",
         "attributes": {
           "code.filepath": "GraphConverter.ts",
@@ -269,7 +269,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "assertion.started",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -278,7 +278,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "assertion.complete",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -289,13 +289,13 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917459,
-    "duration": 1
+    "endTime": 1773938297456,
+    "duration": 0
   },
   {
     "id": "span-6",
     "name": "should extract manual positions from node types",
-    "startTime": 1773856917459,
+    "startTime": 1773938297456,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "should extract manual positions from node types",
@@ -306,7 +306,7 @@
     },
     "events": [
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "setup.started",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -315,7 +315,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "setup.complete",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -325,7 +325,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "execution.started",
         "attributes": {
           "code.filepath": "GraphConverter.ts",
@@ -334,7 +334,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "execution.complete",
         "attributes": {
           "code.filepath": "GraphConverter.ts",
@@ -343,7 +343,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "assertion.started",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -352,7 +352,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "assertion.complete",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -363,13 +363,13 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917459,
+    "endTime": 1773938297456,
     "duration": 0
   },
   {
     "id": "span-7",
     "name": "should handle nodes without positions",
-    "startTime": 1773856917459,
+    "startTime": 1773938297456,
     "attributes": {
       "span.kind": "test.case",
       "test.name": "should handle nodes without positions",
@@ -380,7 +380,7 @@
     },
     "events": [
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "setup.started",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -389,7 +389,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "setup.complete",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -399,7 +399,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "execution.started",
         "attributes": {
           "code.filepath": "GraphConverter.ts",
@@ -408,7 +408,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "execution.complete",
         "attributes": {
           "code.filepath": "GraphConverter.ts",
@@ -417,7 +417,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "assertion.started",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -426,7 +426,7 @@
         }
       },
       {
-        "time": 1773856917459,
+        "time": 1773938297456,
         "name": "assertion.complete",
         "attributes": {
           "code.filepath": "GraphConverter.test.ts",
@@ -437,7 +437,7 @@
       }
     ],
     "status": "OK",
-    "endTime": 1773856917459,
+    "endTime": 1773938297456,
     "duration": 0
   }
 ]