@principal-ai/file-city-react 0.5.22 → 0.5.24

package/dist/stories/sample-data.js

@@ -1,51 +1,52 @@
 import { CodeCityBuilderWithGrid, buildFileSystemTreeFromFileInfoList, } from '@principal-ai/file-city-builder';
 // Sample file structure representing a typical project
+// lineCount is estimated as size / 35 (avg ~35 bytes per line)
 const sampleFileStructure = [
     // Source files
-    { path: 'src/index.ts', size: 1500 },
-    { path: 'src/App.tsx', size: 3200 },
-    { path: 'src/components/Header.tsx', size: 1800 },
-    { path: 'src/components/Footer.tsx', size: 1200 },
-    { path: 'src/components/Sidebar.tsx', size: 2100 },
-    { path: 'src/components/Card.tsx', size: 900 },
-    { path: 'src/components/Button.tsx', size: 600 },
-    { path: 'src/utils/helpers.ts', size: 2500 },
-    { path: 'src/utils/api.ts', size: 3100 },
-    { path: 'src/utils/validators.ts', size: 1400 },
-    { path: 'src/hooks/useAuth.ts', size: 800 },
-    { path: 'src/hooks/useData.ts', size: 1100 },
-    { path: 'src/styles/main.css', size: 4500 },
-    { path: 'src/styles/components.css', size: 2800 },
+    { path: 'src/index.ts', size: 1500, lineCount: 45 },
+    { path: 'src/App.tsx', size: 3200, lineCount: 95 },
+    { path: 'src/components/Header.tsx', size: 1800, lineCount: 55 },
+    { path: 'src/components/Footer.tsx', size: 1200, lineCount: 35 },
+    { path: 'src/components/Sidebar.tsx', size: 2100, lineCount: 65 },
+    { path: 'src/components/Card.tsx', size: 900, lineCount: 28 },
+    { path: 'src/components/Button.tsx', size: 600, lineCount: 20 },
+    { path: 'src/utils/helpers.ts', size: 2500, lineCount: 75 },
+    { path: 'src/utils/api.ts', size: 3100, lineCount: 92 },
+    { path: 'src/utils/validators.ts', size: 1400, lineCount: 42 },
+    { path: 'src/hooks/useAuth.ts', size: 800, lineCount: 25 },
+    { path: 'src/hooks/useData.ts', size: 1100, lineCount: 34 },
+    { path: 'src/styles/main.css', size: 4500, lineCount: 180 },
+    { path: 'src/styles/components.css', size: 2800, lineCount: 112 },
     // Test files
-    { path: 'tests/unit/app.test.ts', size: 2200 },
-    { path: 'tests/unit/header.test.ts', size: 1600 },
-    { path: 'tests/unit/footer.test.tsx', size: 1400 },
-    { path: 'tests/integration/api.test.ts', size: 3400 },
-    { path: '__tests__/components.test.tsx', size: 2900 },
-    { path: '__tests__/utils.test.ts', size: 1900 },
+    { path: 'tests/unit/app.test.ts', size: 2200, lineCount: 68 },
+    { path: 'tests/unit/header.test.ts', size: 1600, lineCount: 50 },
+    { path: 'tests/unit/footer.test.tsx', size: 1400, lineCount: 44 },
+    { path: 'tests/integration/api.test.ts', size: 3400, lineCount: 105 },
+    { path: '__tests__/components.test.tsx', size: 2900, lineCount: 90 },
+    { path: '__tests__/utils.test.ts', size: 1900, lineCount: 58 },
     // Config files
-    { path: 'package.json', size: 1200 },
-    { path: 'tsconfig.json', size: 800 },
-    { path: 'webpack.config.js', size: 2100 },
-    { path: '.eslintrc.js', size: 600 },
-    { path: '.prettierrc', size: 200 },
-    { path: 'README.md', size: 3500 },
+    { path: 'package.json', size: 1200, lineCount: 45 },
+    { path: 'tsconfig.json', size: 800, lineCount: 30 },
+    { path: 'webpack.config.js', size: 2100, lineCount: 65 },
+    { path: '.eslintrc.js', size: 600, lineCount: 22 },
+    { path: '.prettierrc', size: 200, lineCount: 8 },
+    { path: 'README.md', size: 3500, lineCount: 120 },
     // Documentation
-    { path: 'docs/README.md', size: 4200 },
-    { path: 'docs/API.md', size: 5100 },
-    { path: 'docs/CONTRIBUTING.md', size: 2300 },
+    { path: 'docs/README.md', size: 4200, lineCount: 140 },
+    { path: 'docs/API.md', size: 5100, lineCount: 170 },
+    { path: 'docs/CONTRIBUTING.md', size: 2300, lineCount: 80 },
     // Build files
-    { path: 'dist/bundle.js', size: 45000 },
-    { path: 'dist/index.html', size: 800 },
-    { path: 'dist/styles.css', size: 12000 },
+    { path: 'dist/bundle.js', size: 45000, lineCount: 1500 },
+    { path: 'dist/index.html', size: 800, lineCount: 30 },
+    { path: 'dist/styles.css', size: 12000, lineCount: 480 },
     // Node modules (sample)
-    { path: 'node_modules/react/index.js', size: 8000 },
-    { path: 'node_modules/react/package.json', size: 1500 },
-    { path: 'node_modules/typescript/lib/typescript.js', size: 65000 },
-    { path: 'node_modules/@types/react/index.d.ts', size: 3200 },
+    { path: 'node_modules/react/index.js', size: 8000, lineCount: 250 },
+    { path: 'node_modules/react/package.json', size: 1500, lineCount: 55 },
+    { path: 'node_modules/typescript/lib/typescript.js', size: 65000, lineCount: 2200 },
+    { path: 'node_modules/@types/react/index.d.ts', size: 3200, lineCount: 100 },
     // Deprecated files
-    { path: 'src/deprecated/OldComponent.tsx', size: 2400 },
-    { path: 'src/deprecated/LegacyAPI.ts', size: 3100 },
+    { path: 'src/deprecated/OldComponent.tsx', size: 2400, lineCount: 72 },
+    { path: 'src/deprecated/LegacyAPI.ts', size: 3100, lineCount: 95 },
 ];
 // Convert file structure to FileInfo objects
 function createFileInfoList(files) {
@@ -54,6 +55,7 @@ function createFileInfoList(files) {
         path: file.path,
         relativePath: file.path,
         size: file.size,
+        lineCount: file.lineCount,
         extension: file.path.includes('.') ? '.' + (file.path.split('.').pop() || '') : '',
         lastModified: new Date(),
         isDirectory: false,
@@ -81,10 +83,10 @@ export function createSampleCityData() {
 }
 // Smaller sample file structure
 const smallFileStructure = [
-    { path: 'src/index.ts', size: 1500 },
-    { path: 'src/App.tsx', size: 3200 },
-    { path: 'src/utils/helpers.ts', size: 800 },
-    { path: 'package.json', size: 1200 },
+    { path: 'src/index.ts', size: 1500, lineCount: 45 },
+    { path: 'src/App.tsx', size: 3200, lineCount: 95 },
+    { path: 'src/utils/helpers.ts', size: 800, lineCount: 25 },
+    { path: 'package.json', size: 1200, lineCount: 45 },
 ];
 let cachedSmallCityData = null;
 // Create a smaller sample for performance testing

package/dist/utils/visualizationResolution.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Visualization State Resolution
+ *
+ * This module resolves visualization intent (focus, highlights, file colors)
+ * into the primitives needed by the 2D and 3D components.
+ *
+ * Both ArchitectureMapHighlightLayers (2D) and FileCity3D (3D) use this
+ * resolution internally to ensure consistent behavior.
+ *
+ * See docs/VISUALIZATION_STATE_RESOLUTION.md for detailed documentation.
+ */
+import { HighlightLayer, LayerItem } from '../render/client/drawLayeredBuildings';
+export type { HighlightLayer, LayerItem };
+/**
+ * Input highlight layer type - more permissive than the full HighlightLayer
+ * to allow both 2D and 3D components to use this resolution.
+ * Uses generics to preserve the original layer type through resolution.
+ */
+export interface InputHighlightLayer {
+    id: string;
+    name: string;
+    enabled: boolean;
+    color: string;
+    items: Array<{
+        path: string;
+        type: 'file' | 'directory';
+    }>;
+    opacity?: number;
+    priority?: number;
+    borderWidth?: number;
+    dynamic?: boolean;
+}
+/**
+ * Visualization intent - inputs to the resolution
+ */
+export interface VisualizationIntent {
+    /** Directory/file to zoom camera to */
+    focusPath?: string | null;
+    /** Border color for the focused area */
+    focusColor?: string | null;
+    /** Highlight layers (specific directories/files to highlight) */
+    highlightLayers?: InputHighlightLayer[];
+    /** Base file type color layers */
+    fileColorLayers?: InputHighlightLayer[];
+}
+/**
+ * Resolved visualization state - what the components use internally
+ */
+export interface ResolvedVisualizationState {
+    /** Combined and filtered highlight layers */
+    highlightLayers: InputHighlightLayer[];
+    /** Where to point camera (2D: zoomToPath, 3D: focusDirectory) */
+    cameraFocusPath: string | null;
+    /** Focus area border color */
+    focusColor: string | null;
+    /** Whether isolation/collapse should be enabled */
+    shouldIsolate: boolean;
+}
+/**
+ * Resolve visualization intent to component primitives.
+ *
+ * Resolution Rules:
+ * 1. When there's a focusPath or highlightLayers, fileColorLayers are filtered
+ *    to only include files within the visible scope
+ * 2. Buildings/files not in any highlight layer automatically collapse/dim
+ * 3. Camera focuses on focusPath if provided
+ *
+ * @param intent - Visualization intent (focus, highlights, file colors)
+ * @returns Resolved state with primitives for 2D/3D components
+ */
+export declare function resolveVisualizationIntent(intent: VisualizationIntent): ResolvedVisualizationState;
+//# sourceMappingURL=visualizationResolution.d.ts.map

package/dist/utils/visualizationResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualizationResolution.d.ts","sourceRoot":"","sources":["../../src/utils/visualizationResolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAGlF,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iEAAiE;IACjE,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC,kCAAkC;IAClC,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,6CAA6C;IAC7C,eAAe,EAAE,mBAAmB,EAAE,CAAC;IACvC,iEAAiE;IACjE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8BAA8B;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mDAAmD;IACnD,aAAa,EAAE,OAAO,CAAC;CACxB;AAuED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,mBAAmB,GAAG,0BAA0B,CA0BlG"}

package/dist/utils/visualizationResolution.js

@@ -0,0 +1,100 @@
+/**
+ * Visualization State Resolution
+ *
+ * This module resolves visualization intent (focus, highlights, file colors)
+ * into the primitives needed by the 2D and 3D components.
+ *
+ * Both ArchitectureMapHighlightLayers (2D) and FileCity3D (3D) use this
+ * resolution internally to ensure consistent behavior.
+ *
+ * See docs/VISUALIZATION_STATE_RESOLUTION.md for detailed documentation.
+ */
+/**
+ * Check if a path is within a given scope (directory or file)
+ */
+function isPathInScope(path, scope, scopeType) {
+    if (scopeType === 'file') {
+        return path === scope;
+    }
+    // Directory: path is the directory itself or is inside it
+    return path === scope || path.startsWith(scope + '/');
+}
+/**
+ * Get all paths covered by highlight layers
+ */
+function getHighlightedPaths(highlightLayers) {
+    const paths = [];
+    for (const layer of highlightLayers) {
+        if (!layer.enabled)
+            continue;
+        for (const item of layer.items) {
+            paths.push({ path: item.path, type: item.type });
+        }
+    }
+    return paths;
+}
+/**
+ * Filter file color layers to only include items within the visible scope.
+ *
+ * Rules:
+ * - If there are highlight layers, only show file colors for files within highlighted areas
+ * - If there's only a focus path, show file colors for all files within the focus
+ * - If neither, show all file colors
+ */
+function filterFileColorLayers(fileColorLayers, focusPath, highlightLayers) {
+    const highlightedPaths = getHighlightedPaths(highlightLayers);
+    const hasHighlights = highlightedPaths.length > 0;
+    // If no focus and no highlights, return all layers unfiltered
+    if (!focusPath && !hasHighlights) {
+        return fileColorLayers;
+    }
+    return fileColorLayers
+        .map(layer => {
+        const filteredItems = layer.items.filter(item => {
+            if (hasHighlights) {
+                // With highlights: only include items that are within a highlighted path
+                return highlightedPaths.some(highlight => isPathInScope(item.path, highlight.path, highlight.type));
+            }
+            else if (focusPath) {
+                // Focus only: include all items within the focus path
+                return isPathInScope(item.path, focusPath, 'directory');
+            }
+            return true;
+        });
+        return {
+            ...layer,
+            items: filteredItems,
+        };
+    })
+        .filter(layer => layer.items.length > 0);
+}
+/**
+ * Resolve visualization intent to component primitives.
+ *
+ * Resolution Rules:
+ * 1. When there's a focusPath or highlightLayers, fileColorLayers are filtered
+ *    to only include files within the visible scope
+ * 2. Buildings/files not in any highlight layer automatically collapse/dim
+ * 3. Camera focuses on focusPath if provided
+ *
+ * @param intent - Visualization intent (focus, highlights, file colors)
+ * @returns Resolved state with primitives for 2D/3D components
+ */
+export function resolveVisualizationIntent(intent) {
+    const { focusPath = null, focusColor = null, highlightLayers = [], fileColorLayers = [], } = intent;
+    // Filter file color layers based on focus/highlight scope
+    const filteredFileColorLayers = filterFileColorLayers(fileColorLayers, focusPath, highlightLayers);
+    // Combine filtered file colors with highlight layers
+    // File colors go first (lower priority), highlight layers on top
+    const combinedLayers = [...filteredFileColorLayers, ...highlightLayers];
+    // Determine if we should isolate (collapse non-highlighted items)
+    // Isolate when there's a focus path OR active highlight layers
+    const hasActiveHighlights = getHighlightedPaths(highlightLayers).length > 0;
+    const shouldIsolate = Boolean(focusPath) || hasActiveHighlights;
+    return {
+        highlightLayers: combinedLayers,
+        cameraFocusPath: focusPath,
+        focusColor,
+        shouldIsolate,
+    };
+}

package/package.json

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

package/src/components/ArchitectureMapHighlightLayers.tsx

@@ -23,6 +23,7 @@ import {
 import { MapInteractionState, MapDisplayOptions } from '../types/react-types';
 import { getDefaultFileColorConfig } from '../utils/fileColorHighlightLayers';
 import { extractIconConfig } from '../utils/fileTypeIcons';
+import { resolveVisualizationIntent } from '../utils/visualizationResolution';
 
 const DEFAULT_DISPLAY_OPTIONS: MapDisplayOptions = {
   showGrid: false,
@@ -105,6 +106,12 @@ export interface ArchitectureMapHighlightLayersProps {
   // Border radius configuration
   buildingBorderRadius?: number; // Border radius for buildings (files), default: 0 (sharp corners)
   districtBorderRadius?: number; // Border radius for districts (directories), default: 0 (sharp corners)
+
+  /** Color to highlight the focused directory border (hex color, e.g. "#3b82f6") */
+  focusColor?: string | null;
+
+  /** Base file type color layers (resolved with highlightLayers) */
+  fileColorLayers?: HighlightLayer[];
 }
 
 // Spatial Grid for fast hit testing (copied from original for now)
@@ -289,14 +296,14 @@ interface HitTestCache {
 
 function ArchitectureMapHighlightLayersInner({
   cityData,
-  highlightLayers = [],
+  highlightLayers: externalHighlightLayers,
   onLayerToggle,
   focusDirectory = null,
   rootDirectoryName,
   onDirectorySelect,
   onFileClick,
   enableZoom = false,
-  zoomToPath = null,
+  zoomToPath: externalZoomToPath,
   onZoomComplete,
   zoomAnimationSpeed = 0.12,
   allowZoomToPath = true,
@@ -319,9 +326,49 @@ function ArchitectureMapHighlightLayersInner({
   onHover,
   buildingBorderRadius = 0,
   districtBorderRadius = 0,
+  focusColor: externalFocusColor,
+  fileColorLayers,
 }: ArchitectureMapHighlightLayersProps) {
   const { theme } = useTheme();
 
+  // ============================================================================
+  // Visualization Resolution
+  // Always resolve: combines highlightLayers with fileColorLayers,
+  // filtering fileColorLayers based on focus/highlight scope.
+  // ============================================================================
+  const resolved = useMemo(() => {
+    // Cast to InputHighlightLayer[] for resolution - types are compatible at runtime
+    const resolution = resolveVisualizationIntent({
+      focusPath: externalZoomToPath,
+      focusColor: externalFocusColor,
+      highlightLayers: (externalHighlightLayers ?? []) as Parameters<typeof resolveVisualizationIntent>[0]['highlightLayers'],
+      fileColorLayers: (fileColorLayers ?? []) as Parameters<typeof resolveVisualizationIntent>[0]['fileColorLayers'],
+    });
+
+    return {
+      highlightLayers: resolution.highlightLayers,
+      zoomToPath: resolution.cameraFocusPath,
+      focusColor: resolution.focusColor,
+      shouldDim: resolution.shouldIsolate,
+    };
+  }, [
+    fileColorLayers,
+    externalHighlightLayers,
+    externalZoomToPath,
+    externalFocusColor,
+  ]);
+
+  // Use resolved values, ensuring layers have required priority for drawing functions
+  const highlightLayers: HighlightLayer[] = useMemo(() =>
+    resolved.highlightLayers.map((layer, index) => ({
+      ...layer,
+      priority: layer.priority ?? index,
+    })) as HighlightLayer[],
+    [resolved.highlightLayers]
+  );
+  const zoomToPath = resolved.zoomToPath;
+  const focusColor = resolved.focusColor;
+
   // Use theme colors as defaults, with prop overrides
   const resolvedCanvasBackgroundColor = canvasBackgroundColor ?? theme.colors.background;
   const resolvedHoverBorderColor = hoverBorderColor ?? theme.colors.text;
@@ -1234,6 +1281,55 @@ function ArchitectureMapHighlightLayersInner({
       iconMap, // Icon configuration map for file type icons
     );
 
+    // Draw focus color border around the zoomToPath target
+    if (focusColor && zoomToPath) {
+      const normalizedPath = zoomToPath.replace(/^\/+|\/+$/g, '');
+      // Find the district or building that matches the path
+      const targetDistrict = filteredCityData.districts?.find(
+        d => d.path === normalizedPath || d.path === zoomToPath,
+      );
+      const targetBuilding = !targetDistrict
+        ? filteredCityData.buildings?.find(
+            b => b.path === normalizedPath || b.path === zoomToPath,
+          )
+        : null;
+
+      if (targetDistrict) {
+        // Draw border around district
+        const { minX, maxX, minZ, maxZ } = targetDistrict.worldBounds;
+        const topLeft = worldToCanvas(minX, minZ);
+        const bottomRight = worldToCanvas(maxX, maxZ);
+        const width = bottomRight.x - topLeft.x;
+        const height = bottomRight.y - topLeft.y;
+
+        ctx.save();
+        ctx.strokeStyle = focusColor;
+        ctx.lineWidth = 3 * zoomState.scale;
+        ctx.strokeRect(topLeft.x, topLeft.y, width, height);
+        ctx.restore();
+      } else if (targetBuilding) {
+        // Draw border around building
+        const size = Math.max(targetBuilding.dimensions[0], targetBuilding.dimensions[2]);
+        const halfSize = size / 2;
+        const topLeft = worldToCanvas(
+          targetBuilding.position.x - halfSize,
+          targetBuilding.position.z - halfSize,
+        );
+        const bottomRight = worldToCanvas(
+          targetBuilding.position.x + halfSize,
+          targetBuilding.position.z + halfSize,
+        );
+        const width = bottomRight.x - topLeft.x;
+        const height = bottomRight.y - topLeft.y;
+
+        ctx.save();
+        ctx.strokeStyle = focusColor;
+        ctx.lineWidth = 3 * zoomState.scale;
+        ctx.strokeRect(topLeft.x, topLeft.y, width, height);
+        ctx.restore();
+      }
+    }
+
     // Performance monitoring end available for debugging
     // Performance stats available but not logged to reduce console noise
     // Uncomment for debugging: render time, buildings/districts counts, layer counts
@@ -1268,6 +1364,9 @@ function ArchitectureMapHighlightLayersInner({
     abstractedPathsSet,
     layerIndex,
     iconMap,
+    // Focus color border
+    focusColor,
+    zoomToPath,
   ]);
 
   // Optimized hit testing