@principal-ai/file-city-react 0.3.0 → 0.4.0

package/src/components/ArchitectureMapHighlightLayers.tsx

@@ -46,6 +46,11 @@ export interface ArchitectureMapHighlightLayersProps {
   onFileClick?: (path: string, type: 'file' | 'directory') => void;
   enableZoom?: boolean;
 
+  // Animated zoom to directory
+  zoomToPath?: string | null; // When set, animates zoom to frame this directory/file
+  onZoomComplete?: () => void; // Called when zoom animation completes
+  zoomAnimationSpeed?: number; // Animation easing factor (0-1), default 0.12
+
   // Display options
   fullSize?: boolean;
   showGrid?: boolean;
@@ -213,6 +218,9 @@ function ArchitectureMapHighlightLayersInner({
   onDirectorySelect,
   onFileClick,
   enableZoom = false,
+  zoomToPath = null,
+  onZoomComplete,
+  zoomAnimationSpeed = 0.12,
   fullSize = false,
   showGrid = false,
   showFileNames = false,
@@ -257,6 +265,16 @@ function ArchitectureMapHighlightLayersInner({
     hasMouseMoved: false,
   });
 
+  // Target zoom state for animated transitions
+  const [targetZoom, setTargetZoom] = useState<{
+    scale: number;
+    offsetX: number;
+    offsetY: number;
+  } | null>(null);
+
+  // Track the last zoomToPath to detect changes
+  const lastZoomToPathRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (!enableZoom) {
       setZoomState(prev => ({
@@ -267,9 +285,53 @@ function ArchitectureMapHighlightLayersInner({
         isDragging: false,
         hasMouseMoved: false,
       }));
+      setTargetZoom(null);
     }
   }, [enableZoom]);
 
+  // Animation loop for smooth zoom transitions
+  useEffect(() => {
+    if (!targetZoom) return;
+
+    const animate = () => {
+      setZoomState(prev => {
+        const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+        const easing = zoomAnimationSpeed;
+
+        const newScale = lerp(prev.scale, targetZoom.scale, easing);
+        const newOffsetX = lerp(prev.offsetX, targetZoom.offsetX, easing);
+        const newOffsetY = lerp(prev.offsetY, targetZoom.offsetY, easing);
+
+        // Check if close enough to target (within 0.1% for scale, 0.5px for offset)
+        const scaleDone = Math.abs(newScale - targetZoom.scale) < 0.001;
+        const offsetXDone = Math.abs(newOffsetX - targetZoom.offsetX) < 0.5;
+        const offsetYDone = Math.abs(newOffsetY - targetZoom.offsetY) < 0.5;
+
+        if (scaleDone && offsetXDone && offsetYDone) {
+          // Animation complete - set exact target values
+          setTargetZoom(null);
+          onZoomComplete?.();
+          return {
+            ...prev,
+            scale: targetZoom.scale,
+            offsetX: targetZoom.offsetX,
+            offsetY: targetZoom.offsetY,
+          };
+        }
+
+        return {
+          ...prev,
+          scale: newScale,
+          offsetX: newOffsetX,
+          offsetY: newOffsetY,
+        };
+      });
+    };
+
+    const frameId = requestAnimationFrame(animate);
+    return () => cancelAnimationFrame(frameId);
+  }, [targetZoom, zoomState, zoomAnimationSpeed, onZoomComplete]);
+
   const [hitTestCache, setHitTestCache] = useState<HitTestCache | null>(null);
 
   const calculateCanvasResolution = (
@@ -329,6 +391,120 @@ function ArchitectureMapHighlightLayersInner({
     return filteredCityData;
   }, [subdirectoryMode?.enabled, subdirectoryMode?.autoCenter, cityData, filteredCityData]);
 
+  // Handle zoomToPath changes - calculate target zoom to frame the specified path
+  useEffect(() => {
+    // Skip if zoom is not enabled or path hasn't changed
+    if (!enableZoom || zoomToPath === lastZoomToPathRef.current) {
+      return;
+    }
+
+    lastZoomToPathRef.current = zoomToPath;
+
+    // If zoomToPath is null, reset to default view
+    if (zoomToPath === null) {
+      setTargetZoom({
+        scale: 1,
+        offsetX: 0,
+        offsetY: 0,
+      });
+      return;
+    }
+
+    // Need city data and canvas ref to calculate zoom
+    if (!filteredCityData || !canvasRef.current) {
+      return;
+    }
+
+    // Get actual display size - the canvas is resized to match this during render
+    // so canvas coordinates = display coordinates
+    const displayWidth = canvasRef.current.clientWidth || canvasSize.width;
+    const displayHeight = canvasRef.current.clientHeight || canvasSize.height;
+
+    if (!displayWidth || !displayHeight) {
+      return;
+    }
+
+    // Find the target - first check districts, then buildings
+    const normalizedPath = zoomToPath.replace(/^\/+|\/+$/g, '');
+    const targetDistrict = filteredCityData.districts.find(
+      d => d.path === normalizedPath || d.path === zoomToPath,
+    );
+    const targetBuilding = filteredCityData.buildings.find(
+      b => b.path === normalizedPath || b.path === zoomToPath,
+    );
+
+    if (!targetDistrict && !targetBuilding) {
+      return;
+    }
+
+    // Get the bounds to zoom to
+    let targetBounds: { minX: number; maxX: number; minZ: number; maxZ: number };
+
+    if (targetDistrict) {
+      targetBounds = targetDistrict.worldBounds;
+    } else if (targetBuilding) {
+      // Create bounds around the building with some padding
+      const [width, , depth] = targetBuilding.dimensions;
+      const padding = Math.max(width, depth) * 2;
+      targetBounds = {
+        minX: targetBuilding.position.x - width / 2 - padding,
+        maxX: targetBuilding.position.x + width / 2 + padding,
+        minZ: targetBuilding.position.z - depth / 2 - padding,
+        maxZ: targetBuilding.position.z + depth / 2 + padding,
+      };
+    } else {
+      return;
+    }
+
+    // Use the same coordinate system as rendering
+    const coordinateData = canvasSizingData || filteredCityData;
+    const { scale: baseScale, offsetX: baseOffsetX, offsetZ: baseOffsetZ } = calculateScaleAndOffset(
+      coordinateData,
+      displayWidth,
+      displayHeight,
+      displayOptions.padding,
+    );
+
+    // Calculate target center in world coordinates
+    const targetCenterX = (targetBounds.minX + targetBounds.maxX) / 2;
+    const targetCenterZ = (targetBounds.minZ + targetBounds.maxZ) / 2;
+
+    // Calculate target size in screen coordinates (at base zoom)
+    const targetScreenWidth = (targetBounds.maxX - targetBounds.minX) * baseScale;
+    const targetScreenHeight = (targetBounds.maxZ - targetBounds.minZ) * baseScale;
+
+    // Calculate zoom scale to fit target with padding (80% of display)
+    const paddingFactor = 0.8;
+    const scaleToFitWidth = (displayWidth * paddingFactor) / targetScreenWidth;
+    const scaleToFitHeight = (displayHeight * paddingFactor) / targetScreenHeight;
+    const newZoomScale = Math.min(scaleToFitWidth, scaleToFitHeight, 5); // Cap at 5x
+
+    // Calculate the base screen position of target center (before zoom transform)
+    // This matches the worldToCanvas formula: ((x - bounds.minX) * scale + offsetX)
+    const baseScreenX = (targetCenterX - coordinateData.bounds.minX) * baseScale + baseOffsetX;
+    const baseScreenY = (targetCenterZ - coordinateData.bounds.minZ) * baseScale + baseOffsetZ;
+
+    // Calculate offset to center the target
+    // Full formula: screenPos = baseScreenPos * zoomScale + zoomOffset
+    // To center: displayCenter = baseScreen * zoomScale + zoomOffset
+    // Therefore: zoomOffset = displayCenter - baseScreen * zoomScale
+    const newOffsetX = displayWidth / 2 - baseScreenX * newZoomScale;
+    const newOffsetY = displayHeight / 2 - baseScreenY * newZoomScale;
+
+    setTargetZoom({
+      scale: newZoomScale,
+      offsetX: newOffsetX,
+      offsetY: newOffsetY,
+    });
+  }, [
+    zoomToPath,
+    enableZoom,
+    filteredCityData,
+    canvasSizingData,
+    canvasSize,
+    displayOptions.padding,
+  ]);
+
   // Build hit test cache with spatial indexing
   const buildHitTestCache = useCallback(
     (

package/src/stories/ArchitectureMapGridLayout.stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import {
   CodeCityBuilderWithGrid,
@@ -24,7 +25,7 @@ interface CodebaseView {
   name: string;
   description: string;
   overviewPath: string;
-  cells: {
+  referenceGroups: {
     [key: string]: {
       files: string[];
       coordinates: [number, number];
@@ -144,7 +145,7 @@ export const DefaultsTest: Story = {
       name: 'Test Default UI Settings',
       description: 'Tests default UI metadata settings when none are provided',
       overviewPath: 'README.md',
-      cells: {
+      referenceGroups: {
         Source: {
           files: ['src', 'lib'],
           coordinates: [0, 0],
@@ -181,7 +182,7 @@ export const TwoByTwoGrid: Story = {
       name: 'Two by Two Grid Layout',
       description: 'A 2x2 grid layout organizing code into four quadrants',
       overviewPath: 'README.md',
-      cells: {
+      referenceGroups: {
         Source: {
           files: ['src', 'lib'],
           coordinates: [0, 0],
@@ -227,7 +228,7 @@ export const ThreeByThreeGrid: Story = {
       name: 'Three by Three Grid Layout',
       description: 'A 3x3 grid layout for more granular organization',
       overviewPath: 'README.md',
-      cells: {
+      referenceGroups: {
         Source: {
           files: ['src'],
           coordinates: [0, 0],
@@ -281,7 +282,7 @@ export const SparseGrid: Story = {
       name: 'Sparse Grid Layout',
       description: 'A grid with intentional gaps for visual organization',
       overviewPath: 'README.md',
-      cells: {
+      referenceGroups: {
         Source: {
           files: ['src', 'lib'],
           coordinates: [0, 0],
@@ -315,7 +316,7 @@ export const GridWithHighlights: Story = {
       name: 'Grid with Highlights',
       description: 'Grid layout with custom highlight layers',
       overviewPath: 'README.md',
-      cells: {
+      referenceGroups: {
         Source: {
           files: ['src', 'lib'],
           coordinates: [0, 0],
@@ -371,7 +372,7 @@ export const LargeGrid: Story = {
       name: 'Large 5x5 Grid',
       description: 'A large grid for complex projects',
       overviewPath: 'README.md',
-      cells: {
+      referenceGroups: {
         'Core Source': { files: ['src/core'], coordinates: [0, 0] },
         Components: { files: ['src/components'], coordinates: [1, 0] },
         Utils: { files: ['src/utils'], coordinates: [2, 0] },

package/src/stories/ArchitectureMapHighlightLayers.stories.tsx

@@ -1,5 +1,5 @@
+import React, { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import { useState } from 'react';
 
 import { ArchitectureMapHighlightLayers } from '../components/ArchitectureMapHighlightLayers';
 import { HighlightLayer } from '../render/client/drawLayeredBuildings';
@@ -310,3 +310,196 @@ export const WithBorderRadius: Story = {
     enableZoom: true,
   },
 };
+
+// Story with animated zoom to directory
+export const AnimatedZoomToDirectory: Story = {
+  render: function RenderAnimatedZoom() {
+    const [zoomToPath, setZoomToPath] = useState<string | null>(null);
+    const [isAnimating, setIsAnimating] = useState(false);
+    const cityData = createSampleCityData();
+
+    // Get unique top-level directories for navigation buttons
+    const topLevelDirs = Array.from(
+      new Set(
+        cityData.districts
+          .map(d => d.path.split('/')[0])
+          .filter(Boolean),
+      ),
+    ).sort();
+
+    const handleZoomTo = (path: string | null) => {
+      setIsAnimating(true);
+      setZoomToPath(path);
+    };
+
+    const handleZoomComplete = () => {
+      setIsAnimating(false);
+    };
+
+    // Create highlight layer for the focused directory
+    const highlightLayers: HighlightLayer[] = zoomToPath
+      ? [
+          {
+            id: 'zoom-focus',
+            name: 'Zoom Focus',
+            enabled: true,
+            color: '#3b82f6',
+            priority: 1,
+            items: [{ path: zoomToPath, type: 'directory' }],
+          },
+        ]
+      : [];
+
+    return (
+      <div style={{ position: 'relative', width: '100%', height: '100%' }}>
+        <ArchitectureMapHighlightLayers
+          cityData={cityData}
+          fullSize={true}
+          enableZoom={true}
+          zoomToPath={zoomToPath}
+          onZoomComplete={handleZoomComplete}
+          zoomAnimationSpeed={0.1}
+          highlightLayers={highlightLayers}
+          onFileClick={(path, type) => {
+            if (type === 'directory') {
+              handleZoomTo(path);
+            }
+          }}
+        />
+        {/* Navigation Controls */}
+        <div
+          style={{
+            position: 'absolute',
+            top: 20,
+            left: 20,
+            zIndex: 100,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '8px',
+            backgroundColor: 'rgba(0, 0, 0, 0.8)',
+            padding: '16px',
+            borderRadius: '8px',
+            maxWidth: '200px',
+          }}
+        >
+          <div
+            style={{
+              color: 'white',
+              fontFamily: 'monospace',
+              fontSize: '12px',
+              marginBottom: '8px',
+            }}
+          >
+            {isAnimating ? '🎬 Animating...' : '📍 Click to zoom'}
+          </div>
+
+          {/* Reset button */}
+          <button
+            onClick={() => handleZoomTo(null)}
+            disabled={isAnimating}
+            style={{
+              padding: '8px 12px',
+              backgroundColor: zoomToPath === null ? '#3b82f6' : '#374151',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: isAnimating ? 'not-allowed' : 'pointer',
+              fontFamily: 'monospace',
+              fontSize: '12px',
+              opacity: isAnimating ? 0.6 : 1,
+            }}
+          >
+            🏠 Reset View
+          </button>
+
+          {/* Directory buttons */}
+          {topLevelDirs.map(dir => (
+            <button
+              key={dir}
+              onClick={() => handleZoomTo(dir)}
+              disabled={isAnimating}
+              style={{
+                padding: '8px 12px',
+                backgroundColor: zoomToPath === dir ? '#3b82f6' : '#374151',
+                color: 'white',
+                border: 'none',
+                borderRadius: '4px',
+                cursor: isAnimating ? 'not-allowed' : 'pointer',
+                fontFamily: 'monospace',
+                fontSize: '12px',
+                textAlign: 'left',
+                opacity: isAnimating ? 0.6 : 1,
+              }}
+            >
+              📁 {dir}
+            </button>
+          ))}
+
+          {/* Some nested directories */}
+          <div
+            style={{
+              borderTop: '1px solid #4b5563',
+              paddingTop: '8px',
+              marginTop: '4px',
+            }}
+          >
+            <div
+              style={{
+                color: '#9ca3af',
+                fontFamily: 'monospace',
+                fontSize: '10px',
+                marginBottom: '4px',
+              }}
+            >
+              Nested:
+            </div>
+            {['src/components', 'src/utils', 'tests/unit'].map(dir => (
+              <button
+                key={dir}
+                onClick={() => handleZoomTo(dir)}
+                disabled={isAnimating}
+                style={{
+                  padding: '6px 10px',
+                  backgroundColor: zoomToPath === dir ? '#3b82f6' : '#1f2937',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '4px',
+                  cursor: isAnimating ? 'not-allowed' : 'pointer',
+                  fontFamily: 'monospace',
+                  fontSize: '11px',
+                  textAlign: 'left',
+                  marginBottom: '4px',
+                  width: '100%',
+                  opacity: isAnimating ? 0.6 : 1,
+                }}
+              >
+                📂 {dir}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Current zoom info */}
+        <div
+          style={{
+            position: 'absolute',
+            bottom: 20,
+            left: 20,
+            zIndex: 100,
+            backgroundColor: 'rgba(0, 0, 0, 0.8)',
+            padding: '12px',
+            borderRadius: '8px',
+            color: 'white',
+            fontFamily: 'monospace',
+            fontSize: '11px',
+          }}
+        >
+          <div>Current: {zoomToPath || '(root)'}</div>
+          <div style={{ color: '#9ca3af', marginTop: '4px' }}>
+            💡 Click directories in the map or use buttons above
+          </div>
+        </div>
+      </div>
+    );
+  },
+};