@principal-ai/file-city-react 0.5.39 → 0.5.41

package/src/components/FileCityExplorer/ScopeInfoOverlay.tsx

@@ -0,0 +1,229 @@
+import React from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import type { Event, Namespace, Scope } from './model';
+import { makeOverlayStyle, makeSectionLabelStyle } from './styles';
+
+export const ScopeInfoOverlay: React.FC<{
+  info: { scope: Scope; ns: Namespace | null; ev: Event | null };
+}> = ({ info }) => {
+  const { theme } = useTheme();
+  const overlayStyle = makeOverlayStyle(theme);
+  const sectionLabelStyle = makeSectionLabelStyle(theme);
+
+  const severityBg: Record<NonNullable<Event['severity']>, string> = {
+    ERROR: theme.colors.error,
+    WARN: theme.colors.warning,
+    INFO: theme.colors.info,
+  };
+  const defaultSeverityBg = theme.colors.backgroundSecondary;
+
+  const sectionDivider = `1px solid ${theme.colors.backgroundSecondary}`;
+  const codeChipStyle: React.CSSProperties = {
+    fontSize: theme.fontSizes[0],
+    color: theme.colors.textSecondary,
+    background: theme.colors.backgroundDark ?? theme.colors.background,
+    padding: '4px 6px',
+    borderRadius: theme.radii[2],
+    wordBreak: 'break-all',
+  };
+
+  const { scope, ns, ev } = info;
+
+  // Event leaf selected — show event detail.
+  if (ns && ev) {
+    return (
+      <div style={overlayStyle}>
+        <div style={{ padding: '14px 16px', borderBottom: sectionDivider }}>
+          <div style={sectionLabelStyle}>Event</div>
+          <div style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1], marginTop: 6 }}>
+            {ev.name}
+          </div>
+          {ev.severity && (
+            <div
+              style={{
+                display: 'inline-block',
+                fontSize: theme.fontSizes[0],
+                marginTop: theme.space[2],
+                padding: '2px 6px',
+                borderRadius: theme.radii[1],
+                background: severityBg[ev.severity] ?? defaultSeverityBg,
+                color: theme.colors.highlight,
+              }}
+            >
+              {ev.severity}
+            </div>
+          )}
+          {ev.description && (
+            <div style={{ fontSize: theme.fontSizes[0], color: theme.colors.textSecondary, marginTop: 10, lineHeight: 1.5 }}>
+              {ev.description}
+            </div>
+          )}
+        </div>
+        <div style={{ padding: '14px 16px' }}>
+          <div style={sectionLabelStyle}>Owning namespace</div>
+          <div style={{ marginTop: 6, display: 'flex', alignItems: 'center', gap: theme.space[2] }}>
+            <span
+              style={{ width: 12, height: 12, borderRadius: theme.radii[1], background: ns.color, flexShrink: 0 }}
+            />
+            <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1] }}>{ns.name}</span>
+          </div>
+          <div style={{ fontSize: theme.fontSizes[0], color: theme.colors.textTertiary, marginTop: 14, fontStyle: 'italic' }}>
+            Files-per-event mapping not wired yet — for now the event highlights its parent
+            namespace&apos;s paths.
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // Namespace selected — show namespace detail.
+  if (ns) {
+    return (
+      <div style={overlayStyle}>
+        <div style={{ padding: '14px 16px', borderBottom: sectionDivider }}>
+          <div style={sectionLabelStyle}>Namespace</div>
+          <div style={{ marginTop: 6, display: 'flex', alignItems: 'center', gap: theme.space[2] }}>
+            <span
+              style={{ width: 12, height: 12, borderRadius: theme.radii[1], background: ns.color, flexShrink: 0 }}
+            />
+            <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1] }}>{ns.name}</span>
+          </div>
+          <div style={{ fontSize: theme.fontSizes[0], color: theme.colors.textMuted, marginTop: theme.space[2], lineHeight: 1.5 }}>
+            {ns.description}
+          </div>
+          <div style={{ fontSize: theme.fontSizes[0], color: theme.colors.textTertiary, marginTop: theme.space[2] }}>
+            in <span style={{ fontFamily: theme.fonts.monospace }}>{scope.id}</span>
+          </div>
+        </div>
+        <div style={{ padding: '14px 16px', borderBottom: sectionDivider }}>
+          <div style={sectionLabelStyle}>Claimed paths ({ns.paths.length})</div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: theme.space[1], marginTop: 6 }}>
+            {ns.paths.map(p => (
+              <code key={p} style={codeChipStyle}>
+                {p}
+              </code>
+            ))}
+          </div>
+        </div>
+        <div style={{ padding: '14px 16px' }}>
+          <div style={sectionLabelStyle}>Events ({ns.events.length})</div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: theme.space[1], marginTop: 6 }}>
+            {ns.events.map(e => (
+              <div
+                key={e.name}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 6,
+                  padding: '4px 6px',
+                  background: theme.colors.backgroundDark ?? theme.colors.background,
+                  borderRadius: theme.radii[2],
+                }}
+              >
+                {e.severity && (
+                  <span
+                    style={{
+                      fontSize: theme.fontSizes[0],
+                      padding: '1px 4px',
+                      borderRadius: theme.radii[1],
+                      background: severityBg[e.severity] ?? defaultSeverityBg,
+                      color: theme.colors.highlight,
+                      flexShrink: 0,
+                    }}
+                  >
+                    {e.severity}
+                  </span>
+                )}
+                <code style={{ fontSize: theme.fontSizes[0], color: theme.colors.textSecondary }}>
+                  {e.name}
+                </code>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // Scope selected — show scope summary.
+  const totalEvents = scope.namespaces.reduce((n, x) => n + x.events.length, 0);
+  return (
+    <div style={overlayStyle}>
+      <div style={{ padding: '14px 16px', borderBottom: sectionDivider }}>
+        <div style={sectionLabelStyle}>Scope</div>
+        <div style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1], marginTop: 6 }}>{scope.id}</div>
+        <div style={{ fontSize: theme.fontSizes[0], color: theme.colors.textMuted, marginTop: theme.space[2], lineHeight: 1.5 }}>
+          {scope.description}
+        </div>
+        <div style={{ display: 'flex', gap: theme.space[3], marginTop: 12, fontSize: theme.fontSizes[0], color: theme.colors.textTertiary }}>
+          <div>
+            <div>{scope.paths.length}</div>
+            <div style={sectionLabelStyle}>scope paths</div>
+          </div>
+          <div>
+            <div>{scope.namespaces.length}</div>
+            <div style={sectionLabelStyle}>namespaces</div>
+          </div>
+          <div>
+            <div>{totalEvents}</div>
+            <div style={sectionLabelStyle}>events</div>
+          </div>
+        </div>
+      </div>
+      {scope.paths.length > 0 && (
+        <div style={{ padding: '14px 16px', borderBottom: sectionDivider }}>
+          <div style={sectionLabelStyle}>Scope-level paths ({scope.paths.length})</div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: theme.space[1], marginTop: 6 }}>
+            {scope.paths.map(p => (
+              <code key={p} style={codeChipStyle}>
+                {p}
+              </code>
+            ))}
+          </div>
+        </div>
+      )}
+      <div style={{ padding: '14px 16px' }}>
+        <div style={sectionLabelStyle}>Namespaces</div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: theme.space[2], marginTop: theme.space[2] }}>
+          {scope.namespaces.map(n => (
+            <div
+              key={n.name}
+              style={{
+                padding: theme.space[2],
+                background: theme.colors.backgroundDark ?? theme.colors.background,
+                borderRadius: theme.radii[3],
+              }}
+            >
+              <div style={{ display: 'flex', alignItems: 'center', gap: theme.space[2] }}>
+                <span
+                  style={{
+                    width: 10,
+                    height: 10,
+                    borderRadius: theme.radii[1],
+                    background: n.color,
+                    flexShrink: 0,
+                  }}
+                />
+                <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0] }}>{n.name}</span>
+                <span style={{ fontSize: theme.fontSizes[0], color: theme.colors.textTertiary, marginLeft: 'auto' }}>
+                  {n.events.length} event{n.events.length === 1 ? '' : 's'}
+                </span>
+              </div>
+              <div
+                style={{
+                  fontSize: theme.fontSizes[0],
+                  color: theme.colors.textTertiary,
+                  fontFamily: theme.fonts.monospace,
+                  marginTop: theme.space[1],
+                  wordBreak: 'break-all',
+                }}
+              >
+                {n.paths.join(' · ')}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/components/FileCityExplorer/index.ts

@@ -0,0 +1,2 @@
+export { FileCityExplorer, type FileCityExplorerProps } from './FileCityExplorer';
+export type { Event, Namespace, ProjectArea, Scope } from './model';

package/src/components/FileCityExplorer/layers.ts

@@ -0,0 +1,72 @@
+import type { HighlightLayer } from '../FileCity3D';
+import type { Scope } from './model';
+
+export const NAMESPACE_PALETTE = [
+  '#22c55e',
+  '#3b82f6',
+  '#f59e0b',
+  '#ec4899',
+  '#8b5cf6',
+  '#06b6d4',
+  '#ef4444',
+  '#14b8a6',
+  '#a855f7',
+  '#eab308',
+];
+
+/** Colour used for area umbrella tiles and their picker swatches. */
+export const AREA_PANEL_COLOR = '#64748b';
+
+export function pickNamespaceColor(scopes: readonly Scope[]): string {
+  const used = new Set(scopes.flatMap(s => s.namespaces.map(n => n.color)));
+  return (
+    NAMESPACE_PALETTE.find(c => !used.has(c)) ??
+    NAMESPACE_PALETTE[scopes.length % NAMESPACE_PALETTE.length]
+  );
+}
+
+/**
+ * Build highlight layers for a scope: one fill layer per namespace plus a
+ * border-only layer for scope-level paths. Priority is path depth (longest-
+ * prefix wins) per the partition convention in docs/scope-namespace-overlay.md.
+ *
+ * `toCityPath` translates scope-relative paths back to city paths so
+ * districts can be matched.
+ */
+export function buildLayersForScope(
+  scope: Scope,
+  toCityPath: (scopePath: string) => string,
+): HighlightLayer[] {
+  const layers: HighlightLayer[] = scope.namespaces.map(ns => {
+    const maxDepth = Math.max(1, ...ns.paths.map(p => p.split('/').length));
+    return {
+      id: `${scope.id}::${ns.name}`,
+      name: ns.name,
+      enabled: true,
+      color: ns.color,
+      opacity: 0.55,
+      priority: maxDepth,
+      items: ns.paths.map(p => ({
+        path: toCityPath(p),
+        type: 'directory' as const,
+        renderStrategy: 'fill' as const,
+      })),
+    };
+  });
+  if (scope.paths.length > 0) {
+    layers.push({
+      id: `${scope.id}::__scope__`,
+      name: `${scope.id} (scope-level)`,
+      enabled: true,
+      color: '#64748b',
+      opacity: 0.4,
+      priority: 0,
+      items: scope.paths.map(p => ({
+        path: toCityPath(p),
+        type: 'directory' as const,
+        renderStrategy: 'fill' as const,
+      })),
+    });
+  }
+  return layers;
+}

package/src/components/FileCityExplorer/model.ts

@@ -0,0 +1,35 @@
+/**
+ * Scope / namespace / area model for the explorer.
+ *
+ * `Event` and `Namespace` are derived from the upstream
+ * `EventNamespaceNode['namespace']` shape in `@principal-ai/principal-view-core`.
+ * `Namespace` adds a UI-required `color` (palette pick).
+ *
+ * `Scope` stays local: it flattens namespaces inline (`scope.namespaces[]`),
+ * which the upstream canvas-node split (`OtelScopeNode` + per-scope
+ * `*.events.canvas`) doesn't model. Treat as an explorer view-model.
+ *
+ * `ProjectArea` is re-exported directly from upstream.
+ */
+
+import type { EventNamespaceNode } from '@principal-ai/principal-view-core';
+export type { ProjectArea } from '@principal-ai/principal-view-core';
+
+export type Event = EventNamespaceNode['namespace']['events'][number];
+
+export type Namespace = EventNamespaceNode['namespace'] & {
+  /** UI palette pick — not part of the upstream canvas-node shape. */
+  color: string;
+  /** Required here even though upstream allows `paths?` — explorer always sets it. */
+  paths: string[];
+};
+
+export interface Scope {
+  /** Maps to `OtelScopeNode.otel.scope` upstream. */
+  id: string;
+  name: string;
+  description: string;
+  /** Scope-level paths — corresponds to optional `OtelScopeNode.paths` upstream. */
+  paths: string[];
+  namespaces: Namespace[];
+}

package/src/components/FileCityExplorer/pathConversion.ts

@@ -0,0 +1,32 @@
+/**
+ * Path converters for the explorer.
+ *
+ * City data is rooted at `packageRoot` (e.g. `electron-app/`). Scope/namespace
+ * paths are authored relative to the package root (matching how principal-view
+ * canvases are stored). These converters round-trip between the two
+ * representations.
+ *
+ * `packageRoot` should include a trailing slash. Pass `''` if the city data
+ * is already rooted at the project root.
+ */
+
+export interface PathConverters {
+  /** City path → scope/namespace path (strip the package-root prefix). */
+  toScopePath: (cityPath: string) => string;
+  /** Scope/namespace path → city path (re-add the package-root prefix). */
+  toCityPath: (scopePath: string) => string;
+}
+
+export function createPathConverters(packageRoot: string): PathConverters {
+  return {
+    toScopePath(cityPath: string): string {
+      let p = cityPath.endsWith('/') ? cityPath.slice(0, -1) : cityPath;
+      if (packageRoot && p.startsWith(packageRoot)) p = p.slice(packageRoot.length);
+      return p;
+    },
+    toCityPath(scopePath: string): string {
+      if (!packageRoot) return scopePath;
+      return scopePath.startsWith(packageRoot) ? scopePath : packageRoot + scopePath;
+    },
+  };
+}

package/src/components/FileCityExplorer/scopeTreePaths.ts

@@ -0,0 +1,52 @@
+import type { Scope } from './model';
+
+export interface ScopeTreeSelection {
+  scopeId: string;
+  namespaceName?: string;
+  eventName?: string;
+}
+
+/**
+ * Sentinel leaves used when a scope has no namespaces or a namespace has no
+ * events — the trees library infers directories from paths, so empty branches
+ * need a placeholder leaf to render.
+ */
+export const EMPTY_NS_SENTINEL = '(no namespaces)';
+export const EMPTY_EVENTS_SENTINEL = '(no events)';
+
+/**
+ * Build canonical paths for the scope tree: `<scope.id>/<namespace.name>/<event.name>`.
+ * Scopes are top-level directories, namespaces children, events leaves.
+ * Empty scopes/namespaces emit a sentinel leaf so they still appear.
+ */
+export function buildScopeTreePaths(scopes: readonly Scope[]): string[] {
+  const out: string[] = [];
+  for (const scope of scopes) {
+    if (scope.namespaces.length === 0) {
+      out.push(`${scope.id}/${EMPTY_NS_SENTINEL}`);
+      continue;
+    }
+    for (const ns of scope.namespaces) {
+      if (ns.events.length === 0) {
+        out.push(`${scope.id}/${ns.name}/${EMPTY_EVENTS_SENTINEL}`);
+        continue;
+      }
+      for (const ev of ns.events) {
+        out.push(`${scope.id}/${ns.name}/${ev.name}`);
+      }
+    }
+  }
+  return out;
+}
+
+export function parseScopeTreePath(path: string): ScopeTreeSelection {
+  const [scopeId, namespaceName, eventName] = path.split('/');
+  const result: ScopeTreeSelection = { scopeId };
+  if (namespaceName && namespaceName !== EMPTY_NS_SENTINEL) {
+    result.namespaceName = namespaceName;
+  }
+  if (eventName && eventName !== EMPTY_EVENTS_SENTINEL) {
+    result.eventName = eventName;
+  }
+  return result;
+}

package/src/components/FileCityExplorer/styles.ts

@@ -0,0 +1,34 @@
+import type React from 'react';
+import type { Theme } from '@principal-ade/industry-theme';
+
+/** Translucent overlay using the theme's background colour. */
+export const withAlpha = (color: string, percent: number): string =>
+  `color-mix(in oklab, ${color} ${percent}%, transparent)`;
+
+/** Reused across overlays, modals, and the selected-folder card. */
+export const makeSectionLabelStyle = (theme: Theme): React.CSSProperties => ({
+  fontSize: theme.fontSizes[0],
+  color: theme.colors.textTertiary,
+  textTransform: 'uppercase',
+  letterSpacing: 0.5,
+});
+
+/** Frame style for the right-side info overlay. */
+export const makeOverlayStyle = (theme: Theme): React.CSSProperties => ({
+  position: 'absolute',
+  top: 16,
+  left: 16,
+  width: 360,
+  maxHeight: 'calc(100vh - 32px)',
+  overflowY: 'auto',
+  background: withAlpha(theme.colors.background, 72),
+  backdropFilter: 'blur(8px)',
+  WebkitBackdropFilter: 'blur(8px)',
+  border: `1px solid ${theme.colors.border}`,
+  borderRadius: theme.radii[4],
+  color: theme.colors.text,
+  fontFamily: theme.fonts.body,
+  fontSize: theme.fontSizes[1],
+  zIndex: 100,
+  boxShadow: theme.shadows[3],
+});

package/src/index.ts

@@ -87,6 +87,14 @@ export type {
 // with the 2D HighlightLayer from drawLayeredBuildings
 export type { HighlightLayer as FileCity3DHL } from './components/FileCity3D';
 
+// Folder-driven elevated panels (file-tree expansion → 3D umbrella tiles)
+export {
+  buildFolderElevatedPanels,
+  buildFolderIndex,
+  hashFolderColor,
+} from './utils/folderElevatedPanels';
+export type { BuildFolderElevatedPanelsOptions } from './utils/folderElevatedPanels';
+
 // Visualization resolution utilities
 // See docs/VISUALIZATION_STATE_RESOLUTION.md for documentation
 export { resolveVisualizationIntent } from './utils/visualizationResolution';

package/src/stories/2D3DComparison.stories.tsx

@@ -1,8 +1,8 @@
-import React, { useState, useEffect } from 'react';
+import { useState, useEffect } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 
 import { ArchitectureMapHighlightLayers } from '../components/ArchitectureMapHighlightLayers';
-import { FileCity3D, type HighlightLayer, type IsolationMode, type CityData } from '../components/FileCity3D';
+import { FileCity3D, type HighlightLayer, type CityData } from '../components/FileCity3D';
 import { createFileColorHighlightLayers } from '../utils/fileColorHighlightLayers';
 import authServerCityData from '../../../../assets/auth-server-city-data.json';
 
@@ -53,6 +53,7 @@ export const ViewModeSwitch: StoryObj = {
         setHideOverlay(false);
         setOverlayOpacity(1);
       }
+      return undefined;
     }, [viewMode]);
 
     return (
@@ -266,6 +267,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 }],
       },
@@ -282,6 +284,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 }],
       },
@@ -298,6 +301,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 }],
       },
@@ -314,6 +318,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 }],
       },
@@ -321,6 +326,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 }],
       },
@@ -336,6 +342,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 }],
       },
@@ -343,6 +350,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 }],
       },
@@ -358,6 +366,7 @@ const testScenarios: TestScenario[] = [
         id: 'single-file-layer',
         name: 'Single File',
         enabled: true,
+        priority: 0,
         color: '#ec4899',
         items: [{ path: 'auth-server/src/app/api/auth/workos/callback/route.ts', type: 'file' as const }],
       },
@@ -373,6 +382,7 @@ const testScenarios: TestScenario[] = [
         id: 'files-layer',
         name: 'Selected Files',
         enabled: true,
+        priority: 0,
         color: '#14b8a6',
         items: [
           { path: 'auth-server/src/app/api/auth/workos/callback/route.ts', type: 'file' as const },
@@ -658,6 +668,7 @@ export const PanelTransitionTest: StoryObj = {
         setOverlayOpacity(1);
         setHideOverlay(true);
       }
+      return undefined;
     }, [viewMode]);
 
     return (