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

package/src/stories/FileCityExplorerComponent.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { FileCityExplorer, type ProjectArea } from '../components/FileCityExplorer';
+import type { CityData } from '../components/FileCity3D';
+
+import electronAppCityData from '../../../../assets/electron-app-city-data.json';
+
+/**
+ * Side-by-side test of the extracted `<FileCityExplorer>` component against
+ * the original story-template implementation in
+ * `FileCityExplorer.stories.tsx`. The two should look and behave identically;
+ * differences indicate regressions in the extraction.
+ *
+ * Persistence is intentionally namespaced to a separate `localStorage` key
+ * (`file-city.scope-overlay-component`) so the two stories don't fight over
+ * the same scopes/areas state.
+ */
+
+const meta: Meta<typeof FileCityExplorer> = {
+  title: 'Experiments/FileCityExplorer (Component)',
+  component: FileCityExplorer,
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+type Story = StoryObj<typeof FileCityExplorer>;
+
+const DEFAULT_AREAS: ProjectArea[] = [
+  {
+    name: 'Documentation',
+    description: 'Project docs, READMEs, and design notes — not OTEL-instrumented.',
+    paths: ['docs'],
+  },
+  {
+    name: 'Build & tooling',
+    description: 'Build scripts, bundler config, and developer tooling.',
+    paths: ['scripts', 'build'],
+  },
+];
+
+export const Default: Story = {
+  render: () => (
+    <FileCityExplorer
+      cityData={electronAppCityData as CityData}
+      packageRoot="electron-app/"
+      initialAreas={DEFAULT_AREAS}
+      persistKey="file-city.scope-overlay-component"
+    />
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Extracted `<FileCityExplorer>` component over the electron-app city. ' +
+          'Should behave identically to the original story (FileCityExplorer / Default).',
+      },
+    },
+  },
+};

package/src/stories/LeaderLineSnippetOverlay.stories.tsx

@@ -0,0 +1,306 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { ArchitectureMapHighlightLayers } from '../components/ArchitectureMapHighlightLayers';
+import type { CityData } from '../components/FileCity3D';
+import { createFileColorHighlightLayers } from '../utils/fileColorHighlightLayers';
+import authServerCityData from '../../../../assets/auth-server-city-data.json';
+
+const meta = {
+  title: 'Prototypes/Leader Line Snippet Overlay',
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta;
+
+export default meta;
+
+// Mirrors the default `padding` inside ArchitectureMapHighlightLayers, so the
+// world->screen math here lines up with what the canvas actually draws.
+const CANVAS_PADDING = 20;
+
+const TARGET_PATH = 'auth-server/src/app/api/auth/workos/callback/route.ts';
+
+const SNIPPET = `export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const code = url.searchParams.get('code');
+  if (!code) {
+    return NextResponse.redirect(new URL('/login', req.url));
+  }
+
+  const { user, sessionId } = await workos.userManagement
+    .authenticateWithCode({
+      clientId: env.WORKOS_CLIENT_ID,
+      code,
+    });
+
+  return setSessionCookie({ user, sessionId });
+}`;
+
+const PANEL_WIDTH = 360;
+
+interface FitParams {
+  scale: number;
+  offsetX: number;
+  offsetZ: number;
+}
+
+// Replicates calculateScaleAndOffset from ArchitectureMapHighlightLayers.
+function fitCityToBox(
+  bounds: CityData['bounds'],
+  width: number,
+  height: number,
+  padding: number,
+): FitParams {
+  const cityWidth = bounds.maxX - bounds.minX;
+  const cityDepth = bounds.maxZ - bounds.minZ;
+  const horizontalPadding = padding;
+  const verticalPadding = padding * 2;
+  const scaleX = (width - horizontalPadding) / cityDepth;
+  const scaleZ = (height - verticalPadding) / cityWidth;
+  const scale = Math.min(scaleX, scaleZ);
+  const scaledCityWidth = cityDepth * scale;
+  const scaledCityHeight = cityWidth * scale;
+  return {
+    scale,
+    offsetX: (width - scaledCityWidth) / 2,
+    offsetZ: (height - scaledCityHeight) / 2,
+  };
+}
+
+export const SingleLeaderLine: StoryObj = {
+  render: function RenderSingleLeaderLine() {
+    const cityData = authServerCityData as CityData;
+    const highlightLayers = createFileColorHighlightLayers(cityData.buildings);
+
+    const target = cityData.buildings.find(b => b.path === TARGET_PATH);
+
+    const stageRef = useRef<HTMLDivElement | null>(null);
+    const canvasWrapRef = useRef<HTMLDivElement | null>(null);
+    const panelRef = useRef<HTMLDivElement | null>(null);
+
+    const [layout, setLayout] = useState<{
+      stageW: number;
+      stageH: number;
+      anchor: { x: number; y: number } | null;
+      panel: { x: number; y: number; w: number; h: number } | null;
+    }>({ stageW: 0, stageH: 0, anchor: null, panel: null });
+
+    useLayoutEffect(() => {
+      const stage = stageRef.current;
+      const canvasWrap = canvasWrapRef.current;
+      const panel = panelRef.current;
+      if (!stage || !canvasWrap || !panel || !target) return;
+
+      const measure = () => {
+        const stageRect = stage.getBoundingClientRect();
+        const canvasRect = canvasWrap.getBoundingClientRect();
+        const panelRect = panel.getBoundingClientRect();
+
+        // Compute world->screen position for the target building inside the
+        // canvas wrapper, then translate to stage-local coords for the SVG.
+        const fit = fitCityToBox(
+          cityData.bounds,
+          canvasRect.width,
+          canvasRect.height,
+          CANVAS_PADDING,
+        );
+        const buildingX =
+          (target.position.x - cityData.bounds.minX) * fit.scale + fit.offsetX;
+        const buildingY =
+          (target.position.z - cityData.bounds.minZ) * fit.scale + fit.offsetZ;
+
+        const anchor = {
+          x: canvasRect.left - stageRect.left + buildingX,
+          y: canvasRect.top - stageRect.top + buildingY,
+        };
+        const panelLocal = {
+          x: panelRect.left - stageRect.left,
+          y: panelRect.top - stageRect.top,
+          w: panelRect.width,
+          h: panelRect.height,
+        };
+
+        setLayout({
+          stageW: stageRect.width,
+          stageH: stageRect.height,
+          anchor,
+          panel: panelLocal,
+        });
+      };
+
+      measure();
+      const ro = new ResizeObserver(measure);
+      ro.observe(stage);
+      ro.observe(canvasWrap);
+      ro.observe(panel);
+      window.addEventListener('resize', measure);
+      return () => {
+        ro.disconnect();
+        window.removeEventListener('resize', measure);
+      };
+    }, [cityData.bounds, target]);
+
+    if (!target) {
+      return (
+        <div style={{ padding: 24, color: '#f87171' }}>
+          Target building not found: {TARGET_PATH}
+        </div>
+      );
+    }
+
+    // Snippet panel anchor: left edge, vertically centered on the card.
+    const panelAnchor =
+      layout.panel != null
+        ? { x: layout.panel.x, y: layout.panel.y + layout.panel.h / 2 }
+        : null;
+
+    // Smooth S-curve from building -> panel using a horizontal cubic Bezier.
+    const path =
+      layout.anchor && panelAnchor
+        ? (() => {
+            const a = layout.anchor;
+            const b = panelAnchor;
+            const dx = Math.max(80, (b.x - a.x) * 0.5);
+            return `M ${a.x} ${a.y} C ${a.x + dx} ${a.y}, ${b.x - dx} ${b.y}, ${b.x} ${b.y}`;
+          })()
+        : null;
+
+    return (
+      <div
+        style={{
+          width: '100vw',
+          height: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          backgroundColor: '#0f1419',
+        }}
+      >
+        <div
+          style={{
+            padding: '12px 16px',
+            backgroundColor: '#1f2937',
+            borderBottom: '1px solid #374151',
+            color: '#9ca3af',
+            fontSize: 13,
+          }}
+        >
+          Prototype: leader line from{' '}
+          <code style={{ color: '#e5e7eb' }}>{TARGET_PATH}</code> to a side-panel
+          snippet.
+        </div>
+
+        <div
+          ref={stageRef}
+          style={{
+            flex: 1,
+            position: 'relative',
+            display: 'flex',
+            minHeight: 0,
+          }}
+        >
+          <div
+            ref={canvasWrapRef}
+            style={{ flex: 1, position: 'relative', minWidth: 0 }}
+          >
+            <ArchitectureMapHighlightLayers
+              cityData={cityData}
+              highlightLayers={highlightLayers}
+              fullSize
+              canvasBackgroundColor="#0f1419"
+              defaultBuildingColor="#36454F"
+              defaultDirectoryColor="#111827"
+              enableZoom={false}
+            />
+          </div>
+
+          <div
+            style={{
+              width: PANEL_WIDTH,
+              padding: 24,
+              display: 'flex',
+              flexDirection: 'column',
+              justifyContent: 'center',
+              borderLeft: '1px solid #1f2937',
+              backgroundColor: '#0b0f14',
+            }}
+          >
+            <div
+              ref={panelRef}
+              style={{
+                backgroundColor: '#111827',
+                border: '1px solid #374151',
+                borderRadius: 8,
+                padding: 16,
+                boxShadow: '0 4px 16px rgba(0, 0, 0, 0.4)',
+              }}
+            >
+              <div
+                style={{
+                  fontSize: 11,
+                  color: '#9ca3af',
+                  textTransform: 'uppercase',
+                  letterSpacing: 0.5,
+                  marginBottom: 8,
+                }}
+              >
+                callback / route.ts
+              </div>
+              <pre
+                style={{
+                  margin: 0,
+                  fontSize: 12,
+                  lineHeight: 1.5,
+                  color: '#e5e7eb',
+                  fontFamily:
+                    'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+                  whiteSpace: 'pre-wrap',
+                }}
+              >
+                {SNIPPET}
+              </pre>
+            </div>
+          </div>
+
+          {/* SVG overlay spans the whole stage so the line can cross columns. */}
+          <svg
+            width={layout.stageW}
+            height={layout.stageH}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              pointerEvents: 'none',
+              zIndex: 5,
+            }}
+          >
+            {path && layout.anchor && panelAnchor && (
+              <>
+                <path
+                  d={path}
+                  fill="none"
+                  stroke="#fbbf24"
+                  strokeWidth={1.5}
+                  strokeDasharray="4 4"
+                  opacity={0.85}
+                />
+                <circle
+                  cx={layout.anchor.x}
+                  cy={layout.anchor.y}
+                  r={5}
+                  fill="#fbbf24"
+                  stroke="#0f1419"
+                  strokeWidth={1.5}
+                />
+                <circle
+                  cx={panelAnchor.x}
+                  cy={panelAnchor.y}
+                  r={3}
+                  fill="#fbbf24"
+                />
+              </>
+            )}
+          </svg>
+        </div>
+      </div>
+    );
+  },
+};

package/src/utils/folderElevatedPanels.ts

@@ -54,6 +54,13 @@ export function buildFolderIndex(cityData: CityData): FolderIndex {
   for (const d of cityData.districts) directorySet.add(d.path);
   const dirs = Array.from(directorySet).sort();
   for (const dir of dirs) {
+    // The empty path represents the synthetic project root that some city
+    // builders emit at depth 0. Including it here would register '' as its
+    // own parent (slash<0 → parent=''), which makes the recursive `walk`
+    // in `buildFolderElevatedPanels` loop forever the moment the root node
+    // is marked expanded. Top-level real folders already live under the
+    // empty-string parent, so skipping the empty entry costs nothing.
+    if (dir === '') continue;
     const slash = dir.lastIndexOf('/');
     const parent = slash >= 0 ? dir.slice(0, slash) : '';
     const arr = children.get(parent);
@@ -105,7 +112,9 @@ export interface BuildFolderElevatedPanelsOptions {
    */
   expandedFolders: ReadonlySet<string>;
   /** Toggle handler invoked when an umbrella tile is clicked. */
-  onToggleFolder?: (folderPath: string) => void;
+  onToggleFolder?: (folderPath: string, event: MouseEvent) => void;
+  /** Double-click handler for an umbrella tile. */
+  onDoubleClickFolder?: (folderPath: string, event: MouseEvent) => void;
   /**
    * Scale label font size by descendant file count. Default true. When false,
    * the renderer's auto-sized label is used (size derived from tile footprint).
@@ -134,6 +143,7 @@ export function buildFolderElevatedPanels(
     cityData,
     expandedFolders,
     onToggleFolder,
+    onDoubleClickFolder,
     scaleLabelByFileCount = true,
   } = options;
   const index = options.index ?? buildFolderIndex(cityData);
@@ -161,7 +171,10 @@ export function buildFolderElevatedPanels(
       bounds,
       label,
       labelSize,
-      onClick: onToggleFolder ? () => onToggleFolder(folderPath) : undefined,
+      onClick: onToggleFolder ? (event: MouseEvent) => onToggleFolder(folderPath, event) : undefined,
+      onDoubleClick: onDoubleClickFolder
+        ? (event: MouseEvent) => onDoubleClickFolder(folderPath, event)
+        : undefined,
     });
   };