@principal-ai/file-city-react 0.5.16 → 0.5.17

package/dist/components/FileCity3D/FileCity3D.d.ts

@@ -168,6 +168,8 @@ export interface FileCity3DProps {
     textColor?: string;
     /** Currently selected building (controlled by host) */
     selectedBuilding?: CityBuilding | null;
+    /** When true, camera height adjusts based on tallest building when grown */
+    adaptCameraToBuildings?: boolean;
 }
 /**
  * FileCity3D - 3D visualization of codebase structure
@@ -175,6 +177,6 @@ export interface FileCity3DProps {
  * Renders CityData as an interactive 3D city where buildings represent files
  * and their height corresponds to line count or file size.
  */
-export declare function FileCity3D({ cityData, width, height, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls, highlightLayers, isolationMode, dimOpacity: _dimOpacity, isLoading, loadingMessage, emptyMessage, heightScaling, linearScale, focusDirectory, focusColor, onDirectorySelect: _onDirectorySelect, backgroundColor, textColor, selectedBuilding, }: FileCity3DProps): import("react/jsx-runtime").JSX.Element;
+export declare function FileCity3D({ cityData, width, height, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls, highlightLayers, isolationMode, dimOpacity: _dimOpacity, isLoading, loadingMessage, emptyMessage, heightScaling, linearScale, focusDirectory, focusColor, onDirectorySelect: _onDirectorySelect, backgroundColor, textColor, selectedBuilding, adaptCameraToBuildings, }: FileCity3DProps): import("react/jsx-runtime").JSX.Element;
 export default FileCity3D;
 //# sourceMappingURL=FileCity3D.d.ts.map

package/dist/components/FileCity3D/FileCity3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileCity3D.d.ts","sourceRoot":"","sources":["../../../src/components/FileCity3D/FileCity3D.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"FileCity3D.d.ts","sourceRoot":"","sources":["../../../src/components/FileCity3D/FileCity3D.tsx"],"names":[],"mappings":"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"}

package/dist/components/FileCity3D/FileCity3D.js

@@ -623,7 +623,7 @@ export function getCameraAngle() {
 export function getCameraTilt() {
     return cameraApi?.getCurrentTilt() ?? null;
 }
-function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
+function AnimatedCamera({ citySize, isFlat, focusTarget, maxBuildingHeight = 0 }) {
     const { camera } = useThree();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const controlsRef = useRef(null);
@@ -632,6 +632,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
     const hasAppliedInitial = useRef(false);
     const frameCount = useRef(0);
     // Compute target camera position
+    // When flat, use a more top-down view; when grown, use an angled view
     const targetPos = useMemo(() => {
         if (focusTarget) {
             const distance = Math.max(focusTarget.size * 2, 50);
@@ -645,9 +646,15 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
                 targetZ: focusTarget.z,
             };
         }
-        // Default overview
-        const targetHeight = citySize * 1.1;
-        const targetZ = citySize * 1.3;
+        // Default overview - adjust angle based on flat/grown state
+        // Flat: directly overhead (90 degrees, looking straight down)
+        // Grown: angled view to see building heights (optionally based on max building height)
+        const baseHeight = citySize * 1.1;
+        const buildingAwareHeight = maxBuildingHeight > 0
+            ? Math.max(baseHeight, maxBuildingHeight * 2.5)
+            : baseHeight;
+        const targetHeight = isFlat ? citySize * 2.0 : buildingAwareHeight;
+        const targetZ = isFlat ? 0.001 : citySize * 1.3; // Near-zero for top-down (tiny offset to avoid gimbal lock)
         return {
             x: 0,
             y: targetHeight,
@@ -656,7 +663,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
             targetY: 0,
             targetZ: 0,
         };
-    }, [focusTarget, citySize]);
+    }, [focusTarget, citySize, isFlat, maxBuildingHeight]);
     // Spring animation for camera movement
     const [{ camX, camY, camZ, lookX, lookY, lookZ }, api] = useSpring(() => ({
         camX: targetPos.x,
@@ -1074,12 +1081,18 @@ function ControlsOverlay({ isFlat, onToggle, onResetCamera }) {
             gap: 8,
         }, children: [_jsx("button", { onClick: onResetCamera, style: buttonStyle, children: "Reset View" }), _jsx("button", { onClick: onToggle, style: buttonStyle, children: isFlat ? 'Grow to 3D' : 'Flatten to 2D' })] }));
 }
-function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding, selectedBuilding, growProgress, animationConfig, highlightLayers, isolationMode, heightScaling, linearScale, focusDirectory, focusColor, }) {
+function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding, selectedBuilding, growProgress, animationConfig, highlightLayers, isolationMode, heightScaling, linearScale, focusDirectory, focusColor, adaptCameraToBuildings = false, }) {
     const centerOffset = useMemo(() => ({
         x: (cityData.bounds.minX + cityData.bounds.maxX) / 2,
         z: (cityData.bounds.minZ + cityData.bounds.maxZ) / 2,
     }), [cityData.bounds]);
     const citySize = Math.max(cityData.bounds.maxX - cityData.bounds.minX, cityData.bounds.maxZ - cityData.bounds.minZ);
+    // Calculate max building height for camera positioning (when adaptCameraToBuildings is true)
+    const maxBuildingHeight = useMemo(() => {
+        if (!adaptCameraToBuildings)
+            return 0;
+        return Math.max(...cityData.buildings.map(b => b.dimensions[1]), 0);
+    }, [adaptCameraToBuildings, cityData.buildings]);
     const activeHighlights = useMemo(() => hasActiveHighlights(highlightLayers), [highlightLayers]);
     // Helper to check if a path is inside a directory
     const isPathInDirectory = useCallback((path, directory) => {
@@ -1262,7 +1275,7 @@ function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding
     const tension = animationConfig.tension || 120;
     const friction = animationConfig.friction || 14;
     const springDuration = Math.sqrt(1 / (tension * 0.001)) * friction * 20;
-    return (_jsxs(_Fragment, { children: [_jsx(AnimatedCamera, { citySize: citySize, isFlat: growProgress === 0, focusTarget: focusTarget }), _jsx("ambientLight", { intensity: 1.2 }), _jsx("hemisphereLight", { args: ['#ddeeff', '#667788', 0.8], position: [0, citySize, 0] }), _jsx("directionalLight", { position: [citySize, citySize * 1.5, citySize * 0.5], intensity: 2, castShadow: true, "shadow-mapSize": [2048, 2048] }), _jsx("directionalLight", { position: [-citySize * 0.5, citySize * 0.8, -citySize * 0.5], intensity: 1 }), _jsx("directionalLight", { position: [citySize * 0.3, citySize, citySize], intensity: 0.6 }), cityData.districts.map(district => {
+    return (_jsxs(_Fragment, { children: [_jsx(AnimatedCamera, { citySize: citySize, isFlat: growProgress === 0, focusTarget: focusTarget, maxBuildingHeight: maxBuildingHeight }), _jsx("ambientLight", { intensity: 1.2 }), _jsx("hemisphereLight", { args: ['#ddeeff', '#667788', 0.8], position: [0, citySize, 0] }), _jsx("directionalLight", { position: [citySize, citySize * 1.5, citySize * 0.5], intensity: 2, castShadow: true, "shadow-mapSize": [2048, 2048] }), _jsx("directionalLight", { position: [-citySize * 0.5, citySize * 0.8, -citySize * 0.5], intensity: 1 }), _jsx("directionalLight", { position: [citySize * 0.3, citySize, citySize], intensity: 0.6 }), cityData.districts.map(district => {
                 // Check if district matches focusDirectory
                 const isFocused = buildingFocusDirectory
                     ? district.path === buildingFocusDirectory
@@ -1293,7 +1306,7 @@ function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding
  * Renders CityData as an interactive 3D city where buildings represent files
  * and their height corresponds to line count or file size.
  */
-export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls = true, highlightLayers = [], isolationMode = 'transparent', dimOpacity: _dimOpacity = 0.15, isLoading = false, loadingMessage = 'Loading file city...', emptyMessage = 'No file tree data available', heightScaling = 'logarithmic', linearScale = 0.05, focusDirectory = null, focusColor = null, onDirectorySelect: _onDirectorySelect, backgroundColor = '#0f172a', textColor = '#94a3b8', selectedBuilding = null, }) {
+export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls = true, highlightLayers = [], isolationMode = 'transparent', dimOpacity: _dimOpacity = 0.15, isLoading = false, loadingMessage = 'Loading file city...', emptyMessage = 'No file tree data available', heightScaling = 'logarithmic', linearScale = 0.05, focusDirectory = null, focusColor = null, onDirectorySelect: _onDirectorySelect, backgroundColor = '#0f172a', textColor = '#94a3b8', selectedBuilding = null, adaptCameraToBuildings = false, }) {
     const [hoveredBuilding, setHoveredBuilding] = useState(null);
     const [internalIsGrown, setInternalIsGrown] = useState(false);
     const animationConfig = useMemo(() => ({ ...DEFAULT_ANIMATION, ...animation }), [animation]);
@@ -1364,6 +1377,6 @@ export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingC
                     left: 0,
                     width: '100%',
                     height: '100%',
-                }, children: _jsx(CityScene, { cityData: cityData, onBuildingHover: setHoveredBuilding, onBuildingClick: onBuildingClick, hoveredBuilding: hoveredBuilding, selectedBuilding: selectedBuilding, growProgress: growProgress, animationConfig: animationConfig, highlightLayers: highlightLayers, isolationMode: isolationMode, heightScaling: heightScaling, linearScale: linearScale, focusDirectory: focusDirectory, focusColor: focusColor }) }), _jsx(InfoPanel, { building: selectedBuilding || hoveredBuilding }), showControls && (_jsx(ControlsOverlay, { isFlat: !isGrown, onToggle: handleToggle, onResetCamera: resetCamera }))] }));
+                }, children: _jsx(CityScene, { cityData: cityData, onBuildingHover: setHoveredBuilding, onBuildingClick: onBuildingClick, hoveredBuilding: hoveredBuilding, selectedBuilding: selectedBuilding, growProgress: growProgress, animationConfig: animationConfig, highlightLayers: highlightLayers, isolationMode: isolationMode, heightScaling: heightScaling, linearScale: linearScale, focusDirectory: focusDirectory, focusColor: focusColor, adaptCameraToBuildings: adaptCameraToBuildings }) }), _jsx(InfoPanel, { building: selectedBuilding || hoveredBuilding }), showControls && (_jsx(ControlsOverlay, { isFlat: !isGrown, onToggle: handleToggle, onResetCamera: resetCamera }))] }));
 }
 export default FileCity3D;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/file-city-react",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "type": "module",
   "description": "React components for File City visualization",
   "main": "dist/index.js",

package/src/components/FileCity3D/FileCity3D.tsx

@@ -979,6 +979,7 @@ interface AnimatedCameraProps {
   citySize: number;
   isFlat: boolean;
   focusTarget?: FocusTarget | null;
+  maxBuildingHeight?: number;
 }
 
 // Camera rotation options
@@ -1096,7 +1097,7 @@ export function getCameraTilt() {
   return cameraApi?.getCurrentTilt() ?? null;
 }
 
-function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCameraProps) {
+function AnimatedCamera({ citySize, isFlat, focusTarget, maxBuildingHeight = 0 }: AnimatedCameraProps) {
   const { camera } = useThree();
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const controlsRef = useRef<any>(null);
@@ -1106,6 +1107,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCame
   const frameCount = useRef(0);
 
   // Compute target camera position
+  // When flat, use a more top-down view; when grown, use an angled view
   const targetPos = useMemo(() => {
     if (focusTarget) {
       const distance = Math.max(focusTarget.size * 2, 50);
@@ -1119,9 +1121,15 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCame
         targetZ: focusTarget.z,
       };
     }
-    // Default overview
-    const targetHeight = citySize * 1.1;
-    const targetZ = citySize * 1.3;
+    // Default overview - adjust angle based on flat/grown state
+    // Flat: directly overhead (90 degrees, looking straight down)
+    // Grown: angled view to see building heights (optionally based on max building height)
+    const baseHeight = citySize * 1.1;
+    const buildingAwareHeight = maxBuildingHeight > 0
+      ? Math.max(baseHeight, maxBuildingHeight * 2.5)
+      : baseHeight;
+    const targetHeight = isFlat ? citySize * 2.0 : buildingAwareHeight;
+    const targetZ = isFlat ? 0.001 : citySize * 1.3; // Near-zero for top-down (tiny offset to avoid gimbal lock)
     return {
       x: 0,
       y: targetHeight,
@@ -1130,7 +1138,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCame
       targetY: 0,
       targetZ: 0,
     };
-  }, [focusTarget, citySize]);
+  }, [focusTarget, citySize, isFlat, maxBuildingHeight]);
 
   // Spring animation for camera movement
   const [{ camX, camY, camZ, lookX, lookY, lookZ }, api] = useSpring(() => ({
@@ -1695,6 +1703,7 @@ interface CitySceneProps {
   linearScale: number;
   focusDirectory: string | null;
   focusColor?: string | null;
+  adaptCameraToBuildings?: boolean;
 }
 
 function CityScene({
@@ -1711,6 +1720,7 @@ function CityScene({
   linearScale,
   focusDirectory,
   focusColor,
+  adaptCameraToBuildings = false,
 }: CitySceneProps) {
   const centerOffset = useMemo(
     () => ({
@@ -1725,6 +1735,12 @@ function CityScene({
     cityData.bounds.maxZ - cityData.bounds.minZ,
   );
 
+  // Calculate max building height for camera positioning (when adaptCameraToBuildings is true)
+  const maxBuildingHeight = useMemo(() => {
+    if (!adaptCameraToBuildings) return 0;
+    return Math.max(...cityData.buildings.map(b => b.dimensions[1]), 0);
+  }, [adaptCameraToBuildings, cityData.buildings]);
+
   const activeHighlights = useMemo(() => hasActiveHighlights(highlightLayers), [highlightLayers]);
 
   // Helper to check if a path is inside a directory
@@ -1956,7 +1972,7 @@ function CityScene({
 
   return (
     <>
-      <AnimatedCamera citySize={citySize} isFlat={growProgress === 0} focusTarget={focusTarget} />
+      <AnimatedCamera citySize={citySize} isFlat={growProgress === 0} focusTarget={focusTarget} maxBuildingHeight={maxBuildingHeight} />
 
       <ambientLight intensity={1.2} />
       <hemisphereLight args={['#ddeeff', '#667788', 0.8]} position={[0, citySize, 0]} />
@@ -2093,6 +2109,8 @@ export interface FileCity3DProps {
   textColor?: string;
   /** Currently selected building (controlled by host) */
   selectedBuilding?: CityBuilding | null;
+  /** When true, camera height adjusts based on tallest building when grown */
+  adaptCameraToBuildings?: boolean;
 }
 
 /**
@@ -2126,6 +2144,7 @@ export function FileCity3D({
   backgroundColor = '#0f172a',
   textColor = '#94a3b8',
   selectedBuilding = null,
+  adaptCameraToBuildings = false,
 }: FileCity3DProps) {
   const [hoveredBuilding, setHoveredBuilding] = useState<CityBuilding | null>(null);
   const [internalIsGrown, setInternalIsGrown] = useState(false);
@@ -2241,6 +2260,7 @@ export function FileCity3D({
           linearScale={linearScale}
           focusDirectory={focusDirectory}
           focusColor={focusColor}
+          adaptCameraToBuildings={adaptCameraToBuildings}
         />
       </Canvas>
       <InfoPanel building={selectedBuilding || hoveredBuilding} />

package/src/stories/FileCity3D.stories.tsx

@@ -2001,3 +2001,134 @@ export const CameraControls: Story = {
     },
   },
 };
+
+/**
+ * 2D to 3D Transition - Tests the camera angle adjustment when transitioning from flat to grown
+ * Camera starts top-down when flat, then animates to an angled view when buildings grow
+ */
+const FlatToGrownTransitionTemplate: React.FC = () => {
+  const [isGrown, setIsGrown] = React.useState(false);
+  const [autoTransition, setAutoTransition] = React.useState(false);
+  const [adaptCamera, setAdaptCamera] = React.useState(true);
+
+  // Auto-transition effect (simulates the CodeCityPanel behavior)
+  React.useEffect(() => {
+    if (!autoTransition) return;
+    setIsGrown(false);
+    const timer = setTimeout(() => {
+      setIsGrown(true);
+    }, 600);
+    return () => clearTimeout(timer);
+  }, [autoTransition]);
+
+  return (
+    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column', position: 'relative' }}>
+      {/* 3D City */}
+      <FileCity3D
+        cityData={sampleCityData}
+        height="100%"
+        heightScaling="linear"
+        linearScale={0.5}
+        isGrown={isGrown}
+        adaptCameraToBuildings={adaptCamera}
+        animation={{
+          startFlat: true,
+          autoStartDelay: null, // External control
+          staggerDelay: 15,
+          tension: 120,
+          friction: 14,
+        }}
+        showControls={true}
+      />
+
+      {/* Control panel */}
+      <div
+        style={{
+          position: 'absolute',
+          bottom: 0,
+          left: 0,
+          right: 0,
+          zIndex: 100,
+          background: 'rgba(15, 23, 42, 0.95)',
+          borderTop: '1px solid #334155',
+          padding: '16px 24px',
+        }}
+      >
+        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', justifyContent: 'center' }}>
+          <div style={{ color: '#94a3b8', fontSize: '14px' }}>
+            State: <strong style={{ color: isGrown ? '#22c55e' : '#f59e0b' }}>{isGrown ? 'GROWN' : 'FLAT'}</strong>
+          </div>
+          <button
+            onClick={() => setIsGrown(false)}
+            style={{
+              padding: '8px 16px',
+              background: !isGrown ? '#3b82f6' : '#1e293b',
+              color: 'white',
+              border: '1px solid #334155',
+              borderRadius: '6px',
+              cursor: 'pointer',
+            }}
+          >
+            Flatten (2D)
+          </button>
+          <button
+            onClick={() => setIsGrown(true)}
+            style={{
+              padding: '8px 16px',
+              background: isGrown ? '#3b82f6' : '#1e293b',
+              color: 'white',
+              border: '1px solid #334155',
+              borderRadius: '6px',
+              cursor: 'pointer',
+            }}
+          >
+            Grow (3D)
+          </button>
+          <button
+            onClick={() => {
+              setAutoTransition(false);
+              setTimeout(() => setAutoTransition(true), 10);
+            }}
+            style={{
+              padding: '8px 16px',
+              background: '#7c3aed',
+              color: 'white',
+              border: '1px solid #334155',
+              borderRadius: '6px',
+              cursor: 'pointer',
+            }}
+          >
+            Simulate 2D→3D Transition
+          </button>
+          <label style={{ display: 'flex', alignItems: 'center', gap: '6px', color: '#94a3b8', fontSize: '14px', cursor: 'pointer' }}>
+            <input
+              type="checkbox"
+              checked={adaptCamera}
+              onChange={(e) => setAdaptCamera(e.target.checked)}
+              style={{ cursor: 'pointer' }}
+            />
+            Adapt to building heights
+          </label>
+        </div>
+        <div style={{ color: '#64748b', fontSize: '12px', textAlign: 'center', marginTop: '8px' }}>
+          Camera should start top-down when flat, then animate to angled view when grown.
+          {adaptCamera && ' Camera height will adjust based on tallest building.'}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const FlatToGrownTransition: Story = {
+  render: () => <FlatToGrownTransitionTemplate />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Tests the camera angle adjustment when transitioning between flat (2D) and grown (3D) states. ' +
+          'The camera should start with a top-down view when buildings are flat, then animate to an angled view when buildings grow. ' +
+          'Use "Simulate 2D→3D Transition" to test the full transition sequence as it happens in CodeCityPanel.',
+      },
+    },
+  },
+};