@principal-ai/subsystems-react 0.17.0

package/src/stories/Subsystem/ComponentGraph/fixtures.ts

@@ -0,0 +1,129 @@
+import type {
+  SubsystemComponent,
+  SubsystemComponentEdge,
+} from '../../../subsystem/model';
+import type { GraphifyComponentDetail } from '../../../graphify';
+
+// ---------------------------------------------------------------------------
+// Build a subsystem graph from a compact spec - helpers
+// ---------------------------------------------------------------------------
+export function components(
+  spec: Array<[id: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, detail?: GraphifyComponentDetail]>,
+): SubsystemComponent[] {
+  return spec.map(([id, name, construct, file, purl, purpose, symbol, detail]) => ({
+    id,
+    name,
+    construct,
+    file,
+    purl,
+    purpose,
+    symbol,
+    detail,
+  }));
+}
+
+export function edges(
+  spec: Array<[from: string, to: string, mechanism: SubsystemComponentEdge['mechanism'], refs?: string[]]>,
+): SubsystemComponentEdge[] {
+  return spec.map(([from, to, mechanism, refs], i) => ({
+    id: `e${i}`,
+    from,
+    to,
+    mechanism,
+    refs,
+  }));
+}
+
+export const readerDetail: GraphifyComponentDetail = {
+  kind: 'class',
+  methods: [
+    { nodeId: 'm1', name: 'normalize', returnType: 'SessionEvent[]' },
+    { nodeId: 'm2', name: 'readSession', parameters: [{ type: 'string' }], returnType: 'SessionRecord' },
+    { nodeId: 'm3', name: 'toUniversalEvents', returnType: 'UniversalEvent[]' },
+  ],
+  properties: [{ name: 'sessionId', type: 'string' }],
+  extends: [],
+  implements: ['SessionReaderLike'],
+  instantiations: [{ nodeId: 'caller1', name: 'capture-session' }],
+  references: [{ nodeId: 'ref1', name: 'supported-agents', context: 'type' }],
+};
+
+// ---------------------------------------------------------------------------
+// Single package (no consumers) - the investigate-and-pin pattern.
+// Conveys the idea via LAYERS: readers (input) → accumulator (processing).
+// ---------------------------------------------------------------------------
+export const investigateOnlyComponents: SubsystemComponent[] = [
+  {
+    id: 'v1',
+    name: 'V1EventBridgeProcessor',
+    construct: 'class',
+    file: 'src/event-processing/V1EventBridge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'normalizes V1 DB rows into universal events',
+    symbol: 'V1EventBridgeProcessor',
+  },
+  {
+    id: 'v2',
+    name: 'V2EventBridgeProcessor',
+    construct: 'class',
+    file: 'src/event-processing/V2EventBridge.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'normalizes V2 durable events into universal events',
+    symbol: 'V2EventBridgeProcessor',
+  },
+  {
+    id: 'input',
+    name: 'RepoNormalizedUniversalAgentSessionEvent',
+    construct: 'interface',
+    file: 'types/RepoNormalizedUniversalAgentSessionEvent.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'the subsystem\u2019s input type — a repo-normalized universal event the readers produce and the accumulator consumes',
+    symbol: 'RepoNormalizedUniversalAgentSessionEvent',
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'eventType', type: 'NormalizedEventType' },
+        { name: 'sessionId', type: 'string' },
+        { name: 'timestamp', type: 'number' },
+      ],
+      usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'parameter_type' }],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+  {
+    id: 'acc',
+    name: 'accumulateToAgentSessionEvents',
+    construct: 'function',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'accumulates normalized events into agent session events',
+    symbol: 'accumulateToAgentSessionEvents',
+  },
+  {
+    id: 'out',
+    name: 'AgentSessionEvent',
+    construct: 'interface',
+    file: 'src/event-processing/accumulator.ts',
+    purl: 'pkg:github/principal-ai/agent-monitoring',
+    purpose: 'the subsystem\u2019s output type — an accumulated agent-session event',
+    symbol: 'AgentSessionEvent',
+    detail: {
+      kind: 'type',
+      properties: [
+        { name: 'sessionName', type: 'string' },
+        { name: 'operation', type: 'AgentSessionEventOperation' },
+        { name: 'description', type: 'string' },
+      ],
+      usedBy: [{ nodeId: 'acc', name: 'accumulateToAgentSessionEvents', context: 'return_type' }],
+      implementors: [],
+    } satisfies GraphifyComponentDetail,
+  },
+];
+
+export const investigateOnlyEdges: SubsystemComponentEdge[] = edges([
+  // Concept-level data flow — the LLM's semantic intent.
+  ['v1', 'input', 'produces'],
+  ['v2', 'input', 'produces'],
+  ['input', 'acc', 'feeds'],
+  ['acc', 'out', 'produces'],
+]);

package/src/stories/__traces__/test-run.canvas.json

@@ -0,0 +1,241 @@
+{
+  "name": "Trace: principal-view-core-tests",
+  "description": "Exported at 2025-12-26T01:11:11.110Z",
+  "nodeTypes": {
+    "span": {
+      "description": "OpenTelemetry span from trace",
+      "shape": "rectangle"
+    },
+    "service": {
+      "description": "Service grouping",
+      "icon": "server",
+      "shape": "rectangle"
+    }
+  },
+  "edgeTypes": {
+    "span-child": {
+      "label": "Child span",
+      "directed": true
+    }
+  },
+  "display": {
+    "layout": "manual",
+    "animations": {
+      "enabled": true,
+      "speed": 1
+    }
+  },
+  "nodes": [
+    {
+      "id": "service-principal-view-core-tests",
+      "type": "group",
+      "x": -20,
+      "y": -50,
+      "width": 1490,
+      "height": 130,
+      "label": "principal-view-core-tests",
+      "pv": {
+        "nodeType": "service",
+        "name": "principal-view-core-tests",
+        "icon": "server"
+      }
+    },
+    {
+      "id": "ac239f825108da25",
+      "type": "text",
+      "x": 0,
+      "y": 0,
+      "width": 200,
+      "height": 60,
+      "text": "test:basic-traced",
+      "pv": {
+        "nodeType": "span",
+        "name": "test:basic-traced",
+        "description": "11.75ms",
+        "shape": "circle",
+        "fill": "#6b7280",
+        "states": {
+          "OK": {
+            "color": "#22c55e",
+            "label": "OK"
+          }
+        },
+        "otel": {
+          "kind": "instance",
+          "category": "span"
+        },
+        "dataSchema": {
+          "test.type": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    {
+      "id": "a2ec37169e76db0a",
+      "type": "text",
+      "x": 250,
+      "y": 0,
+      "width": 200,
+      "height": 60,
+      "text": "operation:validate",
+      "pv": {
+        "nodeType": "span",
+        "name": "operation:validate",
+        "description": "5.63ms",
+        "shape": "circle",
+        "fill": "#6b7280",
+        "states": {
+          "OK": {
+            "color": "#22c55e",
+            "label": "OK"
+          }
+        },
+        "otel": {
+          "kind": "instance",
+          "category": "span"
+        },
+        "dataSchema": {
+          "operation.type": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    {
+      "id": "4cc98464bf2a78b6",
+      "type": "text",
+      "x": 500,
+      "y": 0,
+      "width": 200,
+      "height": 60,
+      "text": "operation:process",
+      "pv": {
+        "nodeType": "span",
+        "name": "operation:process",
+        "description": "5.78ms",
+        "shape": "circle",
+        "fill": "#6b7280",
+        "states": {
+          "OK": {
+            "color": "#22c55e",
+            "label": "OK"
+          }
+        },
+        "otel": {
+          "kind": "instance",
+          "category": "span"
+        },
+        "dataSchema": {
+          "operation.type": {
+            "type": "string",
+            "required": false
+          },
+          "input": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    {
+      "id": "c6354fc184a8d56a",
+      "type": "text",
+      "x": 750,
+      "y": 0,
+      "width": 200,
+      "height": 60,
+      "text": "test:nested-spans",
+      "pv": {
+        "nodeType": "span",
+        "name": "test:nested-spans",
+        "description": "11.60ms",
+        "shape": "circle",
+        "fill": "#6b7280",
+        "states": {
+          "OK": {
+            "color": "#22c55e",
+            "label": "OK"
+          }
+        },
+        "otel": {
+          "kind": "instance",
+          "category": "span"
+        },
+        "dataSchema": {
+          "test.type": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    {
+      "id": "3884b9ed9e60a5c9",
+      "type": "text",
+      "x": 1000,
+      "y": 0,
+      "width": 200,
+      "height": 60,
+      "text": "child:computation",
+      "pv": {
+        "nodeType": "span",
+        "name": "child:computation",
+        "description": "5.55ms",
+        "shape": "circle",
+        "fill": "#6b7280",
+        "states": {
+          "UNSET": {
+            "color": "#6b7280",
+            "label": "UNSET"
+          }
+        },
+        "otel": {
+          "kind": "instance",
+          "category": "span"
+        },
+        "dataSchema": {
+          "computation.type": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    {
+      "id": "ffede854df0d18bc",
+      "type": "text",
+      "x": 1250,
+      "y": 0,
+      "width": 200,
+      "height": 60,
+      "text": "test:manual-span",
+      "pv": {
+        "nodeType": "span",
+        "name": "test:manual-span",
+        "description": "5.64ms",
+        "shape": "circle",
+        "fill": "#6b7280",
+        "states": {
+          "UNSET": {
+            "color": "#6b7280",
+            "label": "UNSET"
+          }
+        },
+        "otel": {
+          "kind": "instance",
+          "category": "span"
+        },
+        "dataSchema": {
+          "manual": {
+            "type": "boolean",
+            "required": false
+          }
+        }
+      }
+    }
+  ],
+  "edges": []
+}

package/src/stories/data/activity-feed-analytics.dashboard.json

@@ -0,0 +1,300 @@
+{
+  "$schema": "https://principal.ai/schemas/dashboard.v1.json",
+  "id": "activity-feed-analytics",
+  "name": "Activity Feed Analytics",
+  "description": "User engagement metrics for the activity feed home page",
+  "owner": "web-ade-team",
+
+  "externalLinks": {
+    "grafana": "https://grafana.internal/d/activity-feed",
+    "runbook": "https://wiki.internal/runbooks/activity-feed"
+  },
+
+  "metrics": [
+    {
+      "id": "mobile-view-percentage",
+      "name": "Mobile View %",
+      "description": "Percentage of activity feed loads on mobile devices",
+      "type": "gauge",
+      "unit": "%",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "feed-load",
+        "nodes": ["init-started"],
+        "event": "activity-feed.init.started"
+      }],
+
+      "query": {
+        "derivation": "percentage",
+        "filter": "isMobile = true",
+        "window": "1h"
+      },
+
+      "display": {
+        "component": "MetricCard",
+        "size": "medium",
+        "showTrend": true,
+        "showSparkline": true
+      },
+
+      "_mockData": {
+        "current": 34.2,
+        "previous": 31.8,
+        "trend": "up",
+        "series": [
+          { "date": "2024-03-27T00:00", "value": 31.2 },
+          { "date": "2024-03-27T01:00", "value": 32.1 },
+          { "date": "2024-03-27T02:00", "value": 33.0 },
+          { "date": "2024-03-27T03:00", "value": 32.5 },
+          { "date": "2024-03-27T04:00", "value": 33.8 },
+          { "date": "2024-03-27T05:00", "value": 34.2 }
+        ]
+      }
+    },
+    {
+      "id": "total-page-views",
+      "name": "Total Page Views",
+      "description": "Total home page views in the last hour",
+      "type": "counter",
+      "unit": "views",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "feed-load",
+        "event": "activity-feed.init.started"
+      }],
+
+      "query": {
+        "derivation": "count",
+        "window": "1h"
+      },
+
+      "display": {
+        "component": "MetricCard",
+        "size": "medium",
+        "showSparkline": true
+      },
+
+      "_mockData": {
+        "current": 28493,
+        "previous": 26102,
+        "trend": "up",
+        "series": [
+          { "date": "2024-03-27T00:00", "value": 25102 },
+          { "date": "2024-03-27T01:00", "value": 26234 },
+          { "date": "2024-03-27T02:00", "value": 25890 },
+          { "date": "2024-03-27T03:00", "value": 27102 },
+          { "date": "2024-03-27T04:00", "value": 28100 },
+          { "date": "2024-03-27T05:00", "value": 28493 }
+        ]
+      }
+    },
+    {
+      "id": "error-rate",
+      "name": "Error Rate",
+      "description": "Percentage of feed loads that resulted in errors",
+      "type": "gauge",
+      "unit": "%",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "feed-load",
+        "nodes": ["init-error"]
+      }],
+
+      "query": {
+        "derivation": "error_rate",
+        "window": "1h"
+      },
+
+      "thresholds": {
+        "warning": 2.0,
+        "critical": 5.0
+      },
+
+      "display": {
+        "component": "MetricCard",
+        "size": "medium",
+        "showTrend": true,
+        "showSparkline": true
+      },
+
+      "_mockData": {
+        "current": 0.8,
+        "previous": 1.2,
+        "trend": "down",
+        "series": [
+          { "date": "2024-03-27T00:00", "value": 1.4 },
+          { "date": "2024-03-27T01:00", "value": 1.2 },
+          { "date": "2024-03-27T02:00", "value": 1.1 },
+          { "date": "2024-03-27T03:00", "value": 0.9 },
+          { "date": "2024-03-27T04:00", "value": 0.85 },
+          { "date": "2024-03-27T05:00", "value": 0.8 }
+        ]
+      }
+    },
+    {
+      "id": "daily-home-page-views",
+      "name": "Daily Page Views",
+      "description": "Home page views per day for the last 7 days",
+      "type": "counter",
+      "unit": "views",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "feed-load",
+        "event": "activity-feed.init.started"
+      }],
+
+      "query": {
+        "derivation": "count",
+        "timeGroup": "day"
+      },
+
+      "display": {
+        "component": "LineChart",
+        "size": "large"
+      },
+
+      "_mockData": {
+        "series": [
+          { "date": "2024-03-21", "value": 28493 },
+          { "date": "2024-03-22", "value": 31247 },
+          { "date": "2024-03-23", "value": 29102 },
+          { "date": "2024-03-24", "value": 27856 },
+          { "date": "2024-03-25", "value": 30421 },
+          { "date": "2024-03-26", "value": 32109 },
+          { "date": "2024-03-27", "value": 29876 }
+        ]
+      }
+    },
+    {
+      "id": "views-by-viewport",
+      "name": "Views by Viewport",
+      "description": "Daily page views split by mobile vs desktop",
+      "type": "counter",
+      "unit": "views",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "feed-load",
+        "event": "activity-feed.init.started"
+      }],
+
+      "query": {
+        "derivation": "count",
+        "groupBy": ["isMobile"],
+        "timeGroup": "day"
+      },
+
+      "display": {
+        "component": "StackedBarChart",
+        "size": "large"
+      },
+
+      "_mockData": {
+        "series": [
+          { "date": "2024-03-21", "mobile": 9847, "desktop": 18646 },
+          { "date": "2024-03-22", "mobile": 11023, "desktop": 20224 },
+          { "date": "2024-03-23", "mobile": 10156, "desktop": 18946 },
+          { "date": "2024-03-24", "mobile": 9234, "desktop": 18622 },
+          { "date": "2024-03-25", "mobile": 10567, "desktop": 19854 },
+          { "date": "2024-03-26", "mobile": 11234, "desktop": 20875 },
+          { "date": "2024-03-27", "mobile": 10423, "desktop": 19453 }
+        ]
+      }
+    },
+    {
+      "id": "mobile-interaction-rate",
+      "name": "Mobile Interactions/Session",
+      "description": "Average number of interactions per mobile session",
+      "type": "gauge",
+      "unit": "interactions",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "mobile-interaction",
+        "nodes": ["card-swipe", "commit-browse"]
+      }],
+
+      "query": {
+        "derivation": "avg",
+        "window": "1h"
+      },
+
+      "display": {
+        "component": "MetricCard",
+        "size": "medium"
+      },
+
+      "_mockData": {
+        "current": 4.7,
+        "previous": 4.2,
+        "trend": "up"
+      }
+    },
+    {
+      "id": "desktop-search-usage",
+      "name": "Search Usage Rate",
+      "description": "Percentage of desktop sessions that use search",
+      "type": "gauge",
+      "unit": "%",
+
+      "sources": [{
+        "storyboard": "activity-feed",
+        "workflow": "desktop-interaction",
+        "nodes": ["search-and-select"]
+      }],
+
+      "query": {
+        "derivation": "percentage",
+        "window": "1h"
+      },
+
+      "display": {
+        "component": "MetricCard",
+        "size": "medium"
+      },
+
+      "_mockData": {
+        "current": 23.4,
+        "previous": 21.8,
+        "trend": "up"
+      }
+    }
+  ],
+
+  "layout": {
+    "columns": 12,
+    "gap": 16,
+    "breakpoints": {
+      "mobile": 768,
+      "tablet": 1024
+    },
+    "rows": [
+      {
+        "title": "Overview",
+        "panels": [
+          { "id": "mobile-view-percentage", "span": 4, "spanMobile": 12 },
+          { "id": "total-page-views", "span": 4, "spanMobile": 12 },
+          { "id": "error-rate", "span": 4, "spanMobile": 12 }
+        ]
+      },
+      {
+        "title": "Traffic Trends",
+        "panels": [
+          { "id": "daily-home-page-views", "span": 6, "spanMobile": 12, "minHeight": 280 },
+          { "id": "views-by-viewport", "span": 6, "spanMobile": 12, "minHeight": 280 }
+        ]
+      },
+      {
+        "title": "Engagement",
+        "panels": [
+          { "id": "mobile-interaction-rate", "span": 6, "spanMobile": 12 },
+          { "id": "desktop-search-usage", "span": 6, "spanMobile": 12 }
+        ]
+      }
+    ]
+  }
+}