@principal-ai/file-city-react 0.5.40 → 0.5.42

package/src/stories/ElevatedScopePanels.stories.tsx

@@ -0,0 +1,295 @@
+import type { Meta, StoryObj } from '@storybook/react';
+
+import {
+  FileCity3D,
+  type CityData,
+  type ElevatedScopePanel,
+} from '../components/FileCity3D';
+import {
+  buildFolderElevatedPanels,
+  buildFolderIndex,
+} from '../utils/folderElevatedPanels';
+
+import electronAppCityData from '../../../../assets/electron-app-city-data.json';
+
+/**
+ * Use cases for `ElevatedScopePanel` — the colored slabs the file explorer
+ * renders over collapsed directories. These stories drive `<FileCity3D>`
+ * directly with hand-crafted panel arrays, so each story is a frozen
+ * snapshot you can copy as a template when adding new panel features.
+ *
+ * Panels render only while the city is in flat (2D) mode; every story locks
+ * the city flat with `isGrown={false}`.
+ */
+
+const cityData = electronAppCityData as CityData;
+const folderIndex = buildFolderIndex(cityData);
+const districtsByPath = new Map(cityData.districts.map(d => [d.path, d]));
+
+function panelsFor(expanded: ReadonlySet<string>): ElevatedScopePanel[] {
+  return buildFolderElevatedPanels({
+    cityData,
+    expandedFolders: expanded,
+    index: folderIndex,
+  });
+}
+
+const ROOT_ONLY = new Set<string>();
+const TOP_LEVEL = new Set<string>(['electron-app']);
+const PARTIAL = new Set<string>(['electron-app', 'electron-app/src']);
+const DEEP = new Set<string>([
+  'electron-app',
+  'electron-app/src',
+  'electron-app/src/main',
+]);
+
+const meta: Meta<typeof FileCity3D> = {
+  title: 'Experiments/Elevated Scope Panels',
+  component: FileCity3D,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Panel-interface use cases extracted from FileCityExplorer. Each ' +
+          'story is static (no expansion/selection state) so the snapshots ' +
+          'stay readable as documentation and copy-paste templates.',
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof FileCity3D>;
+
+const baseArgs = {
+  cityData,
+  isGrown: false,
+  height: '100vh',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Expansion-state snapshots (helper-driven panels)
+// ---------------------------------------------------------------------------
+
+export const RootUmbrella: Story = {
+  args: { ...baseArgs, elevatedScopePanels: panelsFor(ROOT_ONLY) },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Empty `expandedFolders` — one umbrella covers the whole project.',
+      },
+    },
+  },
+};
+
+export const TopLevelExpanded: Story = {
+  args: { ...baseArgs, elevatedScopePanels: panelsFor(TOP_LEVEL) },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Project root expanded — one umbrella per top-level directory ' +
+          '(`src`, `docs`, `scripts`, …).',
+      },
+    },
+  },
+};
+
+export const PartiallyExpanded: Story = {
+  args: { ...baseArgs, elevatedScopePanels: panelsFor(PARTIAL) },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Root + `src` expanded. `src/*` directories surface as their own ' +
+          'tiles while sibling top-level directories stay umbrella-ed.',
+      },
+    },
+  },
+};
+
+export const DeeplyExpanded: Story = {
+  args: { ...baseArgs, elevatedScopePanels: panelsFor(DEEP) },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Three levels expanded — `src/main/*` directories are now visible ' +
+          'as individual tiles. Demonstrates how panel granularity follows ' +
+          'expansion depth.',
+      },
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Decorating helper output
+// ---------------------------------------------------------------------------
+
+const HUMAN_AREA_LABELS: Record<string, string> = {
+  'electron-app/docs': 'Documentation',
+  'electron-app/scripts': 'Build & Tooling',
+  'electron-app/.github': 'CI / CD',
+  'electron-app/src': 'Application Code',
+};
+
+export const WithDisplayLabels: Story = {
+  args: {
+    ...baseArgs,
+    elevatedScopePanels: panelsFor(TOP_LEVEL).map(panel => {
+      const folderPath = panel.id.startsWith('folder::')
+        ? panel.id.slice('folder::'.length)
+        : null;
+      const displayLabel = folderPath ? HUMAN_AREA_LABELS[folderPath] : undefined;
+      return displayLabel ? { ...panel, displayLabel } : panel;
+    }),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Post-process the helper\'s output to attach a `displayLabel` ' +
+          '(rendered above the technical folder name in a smaller font). ' +
+          'This is the pattern FileCityExplorer uses to surface ' +
+          'human-readable area names on top of folder umbrellas.',
+      },
+    },
+  },
+};
+
+const RECOLORED_BY_PATH: Record<string, string> = {
+  'electron-app/src': '#22c55e',
+  'electron-app/docs': '#3b82f6',
+  'electron-app/scripts': '#f59e0b',
+};
+
+export const RecoloredAndTranslucent: Story = {
+  args: {
+    ...baseArgs,
+    elevatedScopePanels: panelsFor(TOP_LEVEL).map(panel => {
+      const folderPath = panel.id.startsWith('folder::')
+        ? panel.id.slice('folder::'.length)
+        : null;
+      const color = folderPath ? RECOLORED_BY_PATH[folderPath] : undefined;
+      return color ? { ...panel, color, opacity: 0.55 } : { ...panel, opacity: 0.35 };
+    }),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Override `color` and `opacity` on helper output. Translucent ' +
+          'panels let buildings beneath show through — useful when the ' +
+          'panel is a hint, not an occluder.',
+      },
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Selection ring
+// ---------------------------------------------------------------------------
+
+const SELECTED_FOLDER = 'electron-app/src';
+const SELECTION_RING_COLOR = '#fbbf24';
+
+export const WithSelectionRing: Story = {
+  args: {
+    ...baseArgs,
+    elevatedScopePanels: (() => {
+      const panels = panelsFor(TOP_LEVEL);
+      const idx = panels.findIndex(p => p.id === `folder::${SELECTED_FOLDER}`);
+      if (idx < 0) return panels;
+      const target = panels[idx];
+      const inflate = 4;
+      const ring: ElevatedScopePanel = {
+        id: `folder-border::${SELECTED_FOLDER}`,
+        color: SELECTION_RING_COLOR,
+        height: (target.height ?? 4) - 2,
+        thickness: 1,
+        bounds: {
+          minX: target.bounds.minX - inflate,
+          maxX: target.bounds.maxX + inflate,
+          minZ: target.bounds.minZ - inflate,
+          maxZ: target.bounds.maxZ + inflate,
+        },
+      };
+      const next = [...panels];
+      next.splice(idx, 0, ring);
+      return next;
+    })(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Insert an inflated, lower-height panel just *before* the target ' +
+          'umbrella so only its rim peeks out — the selection-ring pattern ' +
+          'used by FileCityExplorer. Order matters: the ring must come ' +
+          'first so the umbrella draws on top of its centre.',
+      },
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Hand-built panels (no helper)
+// ---------------------------------------------------------------------------
+
+function panelFromDistrict(
+  path: string,
+  overrides: Partial<ElevatedScopePanel> = {},
+): ElevatedScopePanel | null {
+  const d = districtsByPath.get(path);
+  if (!d) return null;
+  return {
+    id: `manual::${path}`,
+    color: '#64748b',
+    height: 4,
+    thickness: 2,
+    bounds: d.worldBounds,
+    label: path.split('/').pop() ?? path,
+    ...overrides,
+  };
+}
+
+export const HandBuiltPanels: Story = {
+  args: {
+    ...baseArgs,
+    elevatedScopePanels: [
+      panelFromDistrict('electron-app/src', {
+        color: '#22c55e',
+        label: 'src',
+        displayLabel: 'Application Code',
+        labelColor: '#0f172a',
+        labelSize: 80,
+      }),
+      panelFromDistrict('electron-app/docs', {
+        color: '#3b82f6',
+        opacity: 0.6,
+        label: 'docs',
+      }),
+      panelFromDistrict('electron-app/scripts', {
+        color: '#f59e0b',
+        thickness: 6,
+        label: 'scripts',
+        displayLabel: 'Tooling',
+        displayLabelColor: '#78350f',
+      }),
+    ].filter((p): p is ElevatedScopePanel => p !== null),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Fully manual panel array — no helper. Bounds come straight from ' +
+          '`cityData.districts[i].worldBounds`. Demonstrates `color`, ' +
+          '`opacity`, `label`, `labelColor`, `labelSize`, `displayLabel`, ' +
+          '`displayLabelColor`, and `thickness`. Use this shape when adding ' +
+          'fields to `ElevatedScopePanel`.',
+      },
+    },
+  },
+};

package/src/stories/FileCity3D.stories.tsx

@@ -422,6 +422,7 @@ export const IsolationTransparent: Story = {
         id: 'focus',
         name: 'Focus Layer',
         enabled: true,
+        priority: 0,
         color: '#22c55e',
         items: [{ path: 'src', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
@@ -442,6 +443,7 @@ export const IsolationCollapse: Story = {
         id: 'focus',
         name: 'Focus Layer',
         enabled: true,
+        priority: 0,
         color: '#3b82f6',
         items: [{ path: 'src/components', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
@@ -462,6 +464,7 @@ export const IsolationHide: Story = {
         id: 'focus',
         name: 'Focus Layer',
         enabled: true,
+        priority: 0,
         color: '#f59e0b',
         items: [{ path: 'tests', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
@@ -483,6 +486,7 @@ export const MultipleHighlights: Story = {
         id: 'src',
         name: 'Source',
         enabled: true,
+        priority: 0,
         color: '#22c55e',
         items: [{ path: 'src', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
@@ -490,6 +494,7 @@ export const MultipleHighlights: Story = {
         id: 'tests',
         name: 'Tests',
         enabled: true,
+        priority: 0,
         color: '#ef4444',
         items: [{ path: 'tests', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
@@ -575,6 +580,7 @@ export const AnimatedWithHighlight: Story = {
         id: 'components',
         name: 'Components',
         enabled: true,
+        priority: 0,
         color: '#8b5cf6',
         items: [{ path: 'src/components', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
@@ -627,6 +633,7 @@ const authServerTourSteps: TourStep[] = [
         id: 'workos',
         name: 'WorkOS Auth',
         enabled: true,
+        priority: 0,
         color: '#22c55e',
         items: [{ path: 'auth-server/src/app/api/auth/workos', type: 'directory' as const }],
       },
@@ -642,6 +649,7 @@ const authServerTourSteps: TourStep[] = [
         id: 'browser',
         name: 'Browser Tokens',
         enabled: true,
+        priority: 0,
         color: '#3b82f6',
         items: [{ path: 'auth-server/src/app/api/auth/browser', type: 'directory' as const }],
       },
@@ -649,6 +657,7 @@ const authServerTourSteps: TourStep[] = [
         id: 'cli',
         name: 'CLI Tokens',
         enabled: true,
+        priority: 0,
         color: '#f59e0b',
         items: [{ path: 'auth-server/src/app/api/auth/cli', type: 'directory' as const }],
       },
@@ -664,6 +673,7 @@ const authServerTourSteps: TourStep[] = [
         id: 'lib',
         name: 'Libraries',
         enabled: true,
+        priority: 0,
         color: '#8b5cf6',
         items: [{ path: 'auth-server/src/lib', type: 'directory' as const }],
       },
@@ -679,6 +689,7 @@ const authServerTourSteps: TourStep[] = [
         id: 'bruno',
         name: 'Bruno Tests',
         enabled: true,
+        priority: 0,
         color: '#ef4444',
         items: [{ path: 'auth-server/bruno', type: 'directory' as const }],
       },
@@ -694,6 +705,7 @@ const authServerTourSteps: TourStep[] = [
         id: 'views',
         name: 'Principal Views',
         enabled: true,
+        priority: 0,
         color: '#ec4899',
         items: [{ path: 'auth-server/.principal-views', type: 'directory' as const }],
       },
@@ -1136,6 +1148,7 @@ const testScenarios: TestScenario[] = [
         id: 'api-layer',
         name: 'API Routes',
         enabled: true,
+        priority: 0,
         color: '#22c55e',
         items: [{ path: 'auth-server/src/app/api', type: 'directory' as const }],
       },
@@ -1152,6 +1165,7 @@ const testScenarios: TestScenario[] = [
         id: 'api-layer',
         name: 'API Routes',
         enabled: true,
+        priority: 0,
         color: '#3b82f6',
         items: [{ path: 'auth-server/src/app/api', type: 'directory' as const }],
       },
@@ -1168,6 +1182,7 @@ const testScenarios: TestScenario[] = [
         id: 'lib-layer',
         name: 'Libraries',
         enabled: true,
+        priority: 0,
         color: '#8b5cf6',
         items: [{ path: 'auth-server/src/lib', type: 'directory' as const }],
       },
@@ -1184,6 +1199,7 @@ const testScenarios: TestScenario[] = [
         id: 'api-layer',
         name: 'API Routes',
         enabled: true,
+        priority: 0,
         color: '#22c55e',
         items: [{ path: 'auth-server/src/app/api', type: 'directory' as const }],
       },
@@ -1191,6 +1207,7 @@ const testScenarios: TestScenario[] = [
         id: 'lib-layer',
         name: 'Libraries',
         enabled: true,
+        priority: 0,
         color: '#f59e0b',
         items: [{ path: 'auth-server/src/lib', type: 'directory' as const }],
       },
@@ -1207,6 +1224,7 @@ const testScenarios: TestScenario[] = [
         id: 'api-layer',
         name: 'API Routes',
         enabled: true,
+        priority: 0,
         color: '#3b82f6',
         items: [{ path: 'auth-server/src/app/api', type: 'directory' as const }],
       },
@@ -1214,6 +1232,7 @@ const testScenarios: TestScenario[] = [
         id: 'bruno-layer',
         name: 'Bruno Tests',
         enabled: true,
+        priority: 0,
         color: '#ef4444',
         items: [{ path: 'auth-server/bruno', type: 'directory' as const }],
       },
@@ -1231,6 +1250,7 @@ const testScenarios: TestScenario[] = [
         id: 'src-layer',
         name: 'All Source',
         enabled: true,
+        priority: 0,
         color: '#22c55e',
         items: [{ path: 'auth-server/src', type: 'directory' as const }],
       },
@@ -1238,6 +1258,7 @@ const testScenarios: TestScenario[] = [
         id: 'api-layer',
         name: 'API Only',
         enabled: true,
+        priority: 0,
         color: '#ef4444',
         items: [{ path: 'auth-server/src/app/api', type: 'directory' as const }],
       },
@@ -1254,6 +1275,7 @@ const testScenarios: TestScenario[] = [
         id: 'api-layer',
         name: 'All API',
         enabled: true,
+        priority: 0,
         color: '#8b5cf6',
         items: [{ path: 'auth-server/src/app/api', type: 'directory' as const }],
       },
@@ -2239,7 +2261,6 @@ const RepositoryProfileTemplate: React.FC = () => {
   // Create highlight layers
   const highlightLayers = React.useMemo(() => {
     const layers: HighlightLayer[] = [];
-    const backgroundColor = '#1e293b'; // slate-800
     const hasGitChanges = showGitStatus && gitStatusType !== 'clean';
 
     // 1. File suffix color layers (higher priority = rendered underneath)
@@ -2791,12 +2812,12 @@ const AsyncDataLoadingTemplate: React.FC = () => {
             </div>
             <div style={{ color: '#94a3b8', fontSize: 12, fontFamily: 'system-ui, sans-serif', lineHeight: 1.6 }}>
               <p style={{ margin: '0 0 8px' }}>
-                When FileCity3D mounts before cityData is available (or while it's null),
+                When FileCity3D mounts before cityData is available (or while it&apos;s null),
                 the camera may initialize at position (0,0,0) instead of calculating the
                 proper viewing position from city bounds.
               </p>
               <p style={{ margin: '8px 0 0' }}>
-                This caused electron-app's RepositoryProfilePanel to show a black screen
+                This caused electron-app&apos;s RepositoryProfilePanel to show a black screen
                 or wrong camera position, leading to a switch to the 2D view.
               </p>
             </div>