@principal-ai/subsystems-react 0.56.10 → 0.56.12

package/dist/subsystem/trailSidebarScope.js

@@ -0,0 +1,47 @@
+import { buildTreePathMapping, purlOwnerName, purlRepoKey } from './paths';
+/** Scope sidebar content to a trail's endpoints and authored source sites. */
+export function buildTrailSidebarScope(components, trails, issues, trailId) {
+    const trail = trails?.find((item) => item.id === trailId) ?? null;
+    if (!trail) {
+        return { trail: null, treePaths: buildTreePathMapping(components), issues: issues ?? [] };
+    }
+    const aliases = new Set(trail.steps.flatMap((step) => [step.from, step.to]));
+    const participants = components.filter((component) => aliases.has(component.alias));
+    const files = [...participants];
+    for (const step of trail.steps) {
+        files.push(step);
+        if (step.target)
+            files.push(step.target);
+    }
+    const modules = new Set(participants.map((component) => component.module?.trim()).filter(Boolean));
+    const processes = new Set(participants.map((component) => component.process).filter(Boolean));
+    const repos = new Set(files.flatMap((file) => [purlRepoKey(file.purl), purlOwnerName(file.purl)].filter((key) => !!key)));
+    const scopedIssues = (issues ?? []).filter((issue) => {
+        const target = issue.target;
+        if (!target)
+            return false;
+        const key = target.id ?? target.label;
+        switch (target.kind) {
+            case 'component': {
+                const component = components.find((candidate) => candidate.alias === target.id || candidate.alias === target.label ||
+                    candidate.name === target.label || candidate.symbol === target.label);
+                return component != null && aliases.has(component.alias);
+            }
+            case 'trail':
+                return target.id != null ? target.id === trail.id : target.label === trail.title;
+            case 'step':
+                return target.id === trail.id && target.stepIndex != null &&
+                    Number.isInteger(target.stepIndex) && trail.steps[target.stepIndex] != null;
+            case 'module':
+                return modules.has(key);
+            case 'process':
+                return processes.has(key);
+            case 'repo':
+                return repos.has(purlRepoKey(key) ?? key);
+            default:
+                return false;
+        }
+    });
+    return { trail, treePaths: buildTreePathMapping(files), issues: scopedIssues };
+}
+//# sourceMappingURL=trailSidebarScope.js.map

package/dist/subsystem/trailSidebarScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailSidebarScope.js","sourceRoot":"","sources":["../../src/subsystem/trailSidebarScope.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/subsystems-react",
-  "version": "0.56.10",
+  "version": "0.56.12",
   "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/stories/Canvases/Subsystem/TrailSidebarViews.stories.tsx

@@ -0,0 +1,68 @@
+import { useState } from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent, SubsystemTrail } from '../../../subsystem/model';
+import type { SubsystemIssue } from '../../../subsystem/IssueList';
+
+const components: SubsystemComponent[] = [
+  { alias: 'checkout', name: 'Checkout', construct: 'function', file: 'src/checkout.ts', purl: 'pkg:github/acme/app' },
+  { alias: 'store', name: 'Store', construct: 'function', file: 'src/store.ts', purl: 'pkg:github/acme/app' },
+  { alias: 'report', name: 'Report', construct: 'function', file: 'src/report.ts', purl: 'pkg:github/acme/app' },
+  { alias: 'mail', name: 'Mail', construct: 'function', file: 'src/mail.ts', purl: 'pkg:github/acme/app' },
+];
+const trails: SubsystemTrail[] = [
+  { id: 'checkout', title: 'Validate the checkout and persist the customer’s order with all selected items', steps: [
+    { from: 'checkout', to: 'store', mechanism: 'calls', file: 'src/checkout.ts',
+      purl: 'pkg:github/acme/app', symbol: 'saveCheckout', annotation: 'Persist the checkout.' },
+  ] },
+  { id: 'report', title: 'Generate the monthly account activity report and deliver it to every subscribed recipient', steps: [
+    { from: 'report', to: 'mail', mechanism: 'calls', file: 'src/report.ts',
+      purl: 'pkg:github/acme/app', symbol: 'sendReport' },
+  ] },
+];
+const issues: SubsystemIssue[] = [
+  { id: 'checkout-symbol', severity: 'error', kind: 'symbol_unmatched',
+    message: 'Checkout declaration needs verification.',
+    target: { kind: 'component', id: 'checkout', label: 'Checkout' } },
+  { id: 'checkout-step', severity: 'error', kind: 'step_span_unconfirmed',
+    message: 'Capture the checkout seam.',
+    target: { kind: 'step', id: 'checkout', stepIndex: 0, label: 'Checkout → Store' } },
+  { id: 'report-symbol', severity: 'error', kind: 'symbol_unmatched',
+    message: 'Report declaration needs verification.',
+    target: { kind: 'component', id: 'report', label: 'Report' } },
+];
+
+function Demo() {
+  const [showIssues, setShowIssues] = useState(false);
+  return (
+    <div style={{ height: '100vh' }}>
+      <SubsystemComponentGraph
+        title="Trail-scoped sidebar"
+        description="Select a trail, then switch between Trails, Files, and Issues. Its header stays visible and each panel shows only that trail’s information. Back clears the trail context."
+        components={components}
+        trails={trails}
+        issues={issues}
+        showIssues={showIssues}
+        diagnostic={{ status: 'issues', issueCount: issues.length,
+          onToggle: () => setShowIssues((value) => !value) }}
+        renderFileViewer={(file) => (
+          <pre style={{ padding: 16 }}>Source preview: {file}</pre>
+        )}
+      />
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Canvases/Subsystem/TrailSidebarViews',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  decorators: [(Story) => (
+    <ThemeProvider theme={defaultEditorTheme}><Story /></ThemeProvider>
+  )],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const ScopedPanels: Story = { render: () => <Demo /> };

package/src/subsystem/DiagnosticToggle.tsx

@@ -155,7 +155,7 @@ export function SubsystemDiagnosticToggle({
           justifyContent: bordered || segmented ? 'center' : undefined,
           gap: 4,
           height: bordered || segmented ? 28 : 22,
-          padding: bordered || segmented ? '4px 7px' : showCount ? '0 7px 0 6px' : '0 5px',
+          padding: segmented ? '4px 16px' : bordered ? '4px 7px' : showCount ? '0 7px 0 6px' : '0 5px',
           border: bordered ? `1px solid ${theme.colors.border}` : 'none',
           borderRadius: 4,
           background,
@@ -227,6 +227,7 @@ export function SubsystemDiagnosticToggle({
               fontFamily: theme.fonts.monospace,
               fontSize: theme.fontSizes[0],
               fontWeight: 600,
+              marginLeft: segmented && labelText ? 4 : undefined,
               lineHeight: 1,
             }}
           >

package/src/subsystem/SubsystemComponentGraph.sidebar.test.tsx

@@ -73,15 +73,51 @@ describe('subsystem graph sidebar', () => {
   });
 
   test('groups Trails, Files, and Issues into one switch with Trails selected by default', () => {
-    const body = renderGraph();
+    const body = renderGraph({ diagnostic: { status: 'issues', issueCount: 1 } });
     const group = body.querySelector('header [role="group"][aria-label="Sidebar view"]');
     expect(group?.querySelectorAll('button').length).toBe(3);
     expect(group?.querySelectorAll('button[aria-pressed="true"]').length).toBe(1);
-    expect(group?.querySelector('button[aria-label="Trails"]')?.getAttribute('aria-pressed')).toBe('true');
-    expect(group?.querySelector('button[aria-label^="Issues:"]')?.textContent).toBe('Issues');
+    expect(group?.querySelector('button[aria-label^="Trails"]')?.getAttribute('aria-pressed')).toBe('true');
+    expect(group?.querySelector('button[aria-label^="Trails"]')?.textContent).toBe('Trails1');
+    expect(group?.querySelector('button[aria-label^="Issues:"]')?.textContent).toBe('Issues1');
     expect((group as HTMLElement).style.borderStyle).toBe('solid');
+    expect((group as HTMLElement).style.gridAutoColumns).toBe('1fr');
+    for (const button of group!.querySelectorAll('button')) {
+      expect((button as HTMLElement).style.paddingLeft).toBe('16px');
+      expect((button as HTMLElement).style.paddingRight).toBe('16px');
+      expect((button.lastElementChild as HTMLElement).style.marginLeft).toBe('4px');
+    }
   });
 
+  for (const count of [0, 1, 3]) {
+    test(`shows ${count} in the plural Trails option`, () => {
+      const body = renderGraph({
+        trails: Array.from({ length: count }, (_, index) => ({ ...trails![0], id: `trail-${index}` })),
+        graphifyRelations,
+      });
+      const button = body.querySelector('header button[aria-label^="Trails"]');
+      expect(button?.textContent).toBe(`Trails${count}`);
+      expect(button?.getAttribute('aria-label')).toBe(`Trails (${count} ${count === 1 ? 'trail' : 'trails'})`);
+    });
+  }
+
+  for (const props of [
+    {},
+    { diagnostic: { status: 'ok' as const, issueCount: 0 } },
+    { issues: [], diagnostic: { status: 'issues' as const, issueCount: 3 } },
+    { issues: [], showIssues: true },
+  ]) {
+    test(`hides Issues and keeps Trails active for an empty scope: ${JSON.stringify(props)}`, () => {
+      const body = renderGraph(props);
+      const group = body.querySelector('header [aria-label="Sidebar view"]');
+      expect(group?.querySelectorAll('button').length).toBe(2);
+      expect(group?.querySelector('button[aria-label^="Issues:"]')).toBeNull();
+      expect(group?.querySelector('button[aria-label^="Trails"]')?.getAttribute('aria-pressed')).toBe('true');
+      expect(body.textContent).toContain('Request flow');
+      expect((group as HTMLElement).style.gridAutoColumns).toBe('1fr');
+    });
+  }
+
   test('omits the Files button when no components have files', () => {
     const body = renderGraph({
       components: components.map((component) => ({ ...component, file: '' })),
@@ -110,7 +146,7 @@ describe('subsystem graph sidebar', () => {
       expect(toggle?.getAttribute('aria-pressed')).toBe(String(active));
       expect(header?.querySelectorAll('button').length).toBe(3);
       expect(header?.querySelectorAll('button[aria-pressed="true"]').length).toBe(1);
-      expect(header?.querySelector('button[aria-label="Trails"]')?.getAttribute('aria-pressed')).toBe(String(!active));
+      expect(header?.querySelector('button[aria-label^="Trails"]')?.getAttribute('aria-pressed')).toBe(String(!active));
       expect(body.querySelectorAll('button[aria-label^="Issues:"]').length).toBe(1);
       expect(header?.nextElementSibling?.querySelector('button[aria-label^="Issues:"]')).toBeNull();
       expect(body.textContent).toContain('Always visible description.');
@@ -188,6 +224,8 @@ describe('subsystem graph sidebar', () => {
     globalThis.window = dom as unknown as typeof window;
     try {
       const body = renderGraph({ persistKey: 'trail-nav-test' });
+      expect(body.querySelector('header button[aria-label="Trail"]')?.textContent).toBe('Trail');
+      expect(body.querySelector('header button[aria-label^="Trails"]')).toBeNull();
       expect(body.querySelector('[aria-hidden="false"] button[aria-label="Back to trails"]')).not.toBeNull();
       expect(body.querySelector('button[aria-label^="Play "]')).toBeNull();
       expect(body.querySelector('button[aria-label^="Focus layout"]')).toBeNull();
@@ -197,6 +235,66 @@ describe('subsystem graph sidebar', () => {
     }
   });
 
+  test('keeps the trail header and scoped counts in Issues after graph selection is cleared', () => {
+    const previousWindow = globalThis.window;
+    const dom = new Window();
+    dom.localStorage.setItem('principal.subsystems.viewState.scoped-sidebar-test', JSON.stringify({
+      sidebarTrailId: 'request',
+      focusedTrailId: null,
+    }));
+    globalThis.window = dom as unknown as typeof window;
+    try {
+      const body = renderGraph({
+        persistKey: 'scoped-sidebar-test',
+        showIssues: true,
+        components: [...components, {
+          alias: 'other', name: 'Other', construct: 'function', file: 'src/other.ts', purl: 'pkg:github/test/app',
+        }],
+        issues: [
+          { id: 'related', severity: 'error', kind: 'missing_file', message: 'Related finding',
+            target: { kind: 'component', id: 'entry', label: 'Entry' } },
+          { id: 'unrelated', severity: 'error', kind: 'missing_file', message: 'Unrelated finding',
+            target: { kind: 'component', id: 'other', label: 'Other' } },
+        ],
+        diagnostic: { status: 'issues', issueCount: 2 },
+      });
+      expect(body.querySelector('[aria-hidden="false"] button[aria-label="Back to trails"]')).not.toBeNull();
+      expect(body.querySelector('[aria-hidden="false"]')?.textContent).toContain('Request flow');
+      expect(body.querySelector('header button[aria-label^="Files"]')?.textContent).toBe('Files2');
+      expect(body.querySelector('header button[aria-label^="Issues:"]')?.textContent).toBe('Issues1');
+      expect(body.querySelector('header button[aria-label="Trail"]')?.textContent).toBe('Trail');
+      expect(body.querySelector('[aria-hidden="false"]')?.textContent).not.toContain('Unrelated finding');
+    } finally {
+      globalThis.window = previousWindow;
+    }
+  });
+
+  test('hides Issues for a selected trail with no findings even when other trails have issues', () => {
+    const previousWindow = globalThis.window;
+    const dom = new Window();
+    dom.localStorage.setItem('principal.subsystems.viewState.empty-trail-issues-test', JSON.stringify({
+      sidebarTrailId: 'request',
+    }));
+    globalThis.window = dom as unknown as typeof window;
+    try {
+      const body = renderGraph({
+        persistKey: 'empty-trail-issues-test',
+        showIssues: true,
+        issues: [{
+          id: 'unrelated', severity: 'error', kind: 'missing_file', message: 'Unrelated finding',
+          target: { kind: 'component', id: 'other', label: 'Other' },
+        }],
+        diagnostic: { status: 'issues', issueCount: 1 },
+      });
+      expect(body.querySelector('header button[aria-label^="Issues:"]')).toBeNull();
+      expect(body.querySelector('header button[aria-label="Trail"]')?.getAttribute('aria-pressed')).toBe('true');
+      expect(body.querySelector('[aria-hidden="false"] button[aria-label="Back to trails"]')).not.toBeNull();
+      expect(body.querySelector('[aria-hidden="false"]')?.textContent).toContain('Entry');
+    } finally {
+      globalThis.window = previousWindow;
+    }
+  });
+
   test('static graphs keep their description but do not show a file panel', () => {
     const body = renderGraph({ trails: undefined, graphifyRelations });
     expect(body.textContent).toContain('Always visible description.');
@@ -217,7 +315,10 @@ describe('subsystem graph sidebar', () => {
   });
 
   test('the description stays visible while diagnostics replace the trails', () => {
-    const body = renderGraph({ showIssues: true, issues: [] });
+    const body = renderGraph({ showIssues: true, issues: [{
+      id: 'related', severity: 'error', kind: 'missing_file', message: 'Related finding',
+      target: { kind: 'component', id: 'entry', label: 'Entry' },
+    }] });
     expect(body.textContent).toContain('Always visible description.');
     expect(body.textContent).not.toContain('Request flow');
     expect(body.querySelector('[aria-label="Resize sidebar"]')).not.toBeNull();