@principal-ai/subsystems-react 0.24.26 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/dist/stories/Subsystem/ComponentGraph/fixtures.d.ts +1 -1
  2. package/dist/stories/Subsystem/ComponentGraph/fixtures.d.ts.map +1 -1
  3. package/dist/stories/Subsystem/ComponentGraph/fixtures.js +7 -7
  4. package/dist/stories/Subsystem/ComponentGraph/fixtures.js.map +1 -1
  5. package/dist/subsystem/ComponentDeclaration.d.ts +1 -1
  6. package/dist/subsystem/ComponentDeclaration.d.ts.map +1 -1
  7. package/dist/subsystem/ComponentDeclaration.js +1 -1
  8. package/dist/subsystem/ComponentDeclaration.js.map +1 -1
  9. package/dist/subsystem/ConstructsCatalog.d.ts +2 -2
  10. package/dist/subsystem/ConstructsCatalog.d.ts.map +1 -1
  11. package/dist/subsystem/ConstructsCatalog.js +62 -62
  12. package/dist/subsystem/ConstructsCatalog.js.map +1 -1
  13. package/dist/subsystem/SubsystemComponentGraph.d.ts +2 -2
  14. package/dist/subsystem/SubsystemComponentGraph.d.ts.map +1 -1
  15. package/dist/subsystem/SubsystemComponentGraph.js +27 -27
  16. package/dist/subsystem/SubsystemComponentGraph.js.map +1 -1
  17. package/dist/subsystem/model.d.ts +21 -5
  18. package/dist/subsystem/model.d.ts.map +1 -1
  19. package/dist/subsystem/model.js +72 -38
  20. package/dist/subsystem/model.js.map +1 -1
  21. package/dist/subsystem/nodes.d.ts +3 -3
  22. package/dist/subsystem/nodes.d.ts.map +1 -1
  23. package/dist/subsystem/nodes.js +39 -11
  24. package/dist/subsystem/nodes.js.map +1 -1
  25. package/dist/subsystem/paths.d.ts +1 -1
  26. package/dist/subsystem/paths.js +1 -1
  27. package/package.json +1 -1
  28. package/src/stories/Subsystem/ComponentGraph/ModuleBadges.stories.tsx +183 -0
  29. package/src/stories/Subsystem/ComponentGraph/fixtures.ts +8 -8
  30. package/src/subsystem/ComponentDeclaration.tsx +2 -2
  31. package/src/subsystem/ConstructsCatalog.tsx +71 -75
  32. package/src/subsystem/SubsystemComponentGraph.tsx +28 -28
  33. package/src/subsystem/model.test.ts +103 -51
  34. package/src/subsystem/model.ts +83 -43
  35. package/src/subsystem/nodes.tsx +57 -18
  36. package/src/subsystem/paths.ts +1 -1
@@ -5,7 +5,7 @@
5
5
  * by its `purl` (`pkg:github/<owner>/<name>[#<path>]`) — never to the machine.
6
6
  * When a graph spans several repos the sidebar tree needs synthetic
7
7
  * `<owner>/<name>/` prefixes to keep same-named paths apart; hosts resolve
8
- * each file against `repoRoots[purlRepo] ?? repoRoot`.
8
+ * each file against its own purl's checkout (via the Alexandria registry).
9
9
  */
10
10
  /** Normalize a purl to its repo key: fragment and surrounding whitespace stripped. */
11
11
  export function purlRepoKey(purl) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@principal-ai/subsystems-react",
3
- "version": "0.24.26",
3
+ "version": "0.25.0",
4
4
  "description": "React UI for Subsystem Models — graph, Pierre code views, and session-event feeds",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -0,0 +1,183 @@
1
+ import '@xyflow/react/dist/style.css';
2
+ import type { Meta, StoryObj } from '@storybook/react';
3
+ import { ReactFlowProvider, type NodeProps } from '@xyflow/react';
4
+ import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
5
+ import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
6
+ import { SubsystemGroupNode } from '../../../subsystem/nodes';
7
+ import type {
8
+ SubsystemComponent,
9
+ SubsystemGraphNode,
10
+ SubsystemProcessRegion,
11
+ } from '../../../subsystem/model';
12
+ import { graphSpecFromEdges } from './fixtures';
13
+
14
+ const meta = {
15
+ title: 'Subsystem/ComponentGraph/ModuleBadges',
16
+ parameters: { layout: 'fullscreen' },
17
+ tags: ['autodocs'],
18
+ decorators: [
19
+ (Story) => (
20
+ <ThemeProvider theme={defaultEditorTheme}>
21
+ <ReactFlowProvider>
22
+ <Story />
23
+ </ReactFlowProvider>
24
+ </ThemeProvider>
25
+ ),
26
+ ],
27
+ } satisfies Meta;
28
+
29
+ export default meta;
30
+ type Story = StoryObj<typeof meta>;
31
+
32
+ const PURL = 'pkg:github/principal-ai/subsystem-modeling';
33
+ const DEEP_NODES = 'packages/subsystems-react/src/subsystem/nodes.tsx';
34
+ const DEEP_VIEWS = 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx';
35
+
36
+ /**
37
+ * Components sharing a deep `module` path — long enough that the collapsed
38
+ * badge must flip to `first/…/last`; clicking grows the badge, not the frame.
39
+ */
40
+ const deepComponents: SubsystemComponent[] = [
41
+ {
42
+ id: 'node-comp',
43
+ name: 'SubsystemComponentNode',
44
+ construct: 'function',
45
+ symbol: 'SubsystemComponentNode',
46
+ file: DEEP_NODES,
47
+ module: DEEP_NODES,
48
+ purl: PURL,
49
+ purpose: 'Leaf component renderer',
50
+ },
51
+ {
52
+ id: 'group-comp',
53
+ name: 'SubsystemGroupNode',
54
+ construct: 'function',
55
+ symbol: 'SubsystemGroupNode',
56
+ file: DEEP_NODES,
57
+ module: DEEP_NODES,
58
+ purl: PURL,
59
+ purpose: 'Boundary frame renderer',
60
+ },
61
+ {
62
+ id: 'edge-comp',
63
+ name: 'SubsystemEdge',
64
+ construct: 'function',
65
+ symbol: 'SubsystemEdge',
66
+ file: DEEP_NODES,
67
+ module: DEEP_NODES,
68
+ purl: PURL,
69
+ purpose: 'Edge renderer',
70
+ },
71
+ {
72
+ id: 'analysis',
73
+ name: 'AnalysisView',
74
+ construct: 'function',
75
+ symbol: 'AnalysisView',
76
+ file: DEEP_VIEWS,
77
+ module: DEEP_VIEWS,
78
+ purl: PURL,
79
+ purpose: 'Renders an analysis',
80
+ },
81
+ {
82
+ id: 'layers',
83
+ name: 'LayersProvider',
84
+ construct: 'function',
85
+ symbol: 'LayersProvider',
86
+ file: DEEP_VIEWS,
87
+ module: DEEP_VIEWS,
88
+ purl: PURL,
89
+ purpose: 'Provides the layer UI',
90
+ },
91
+ {
92
+ id: 'use-drawings',
93
+ name: 'useDrawingsHost',
94
+ construct: 'function',
95
+ symbol: 'useDrawingsHost',
96
+ file: DEEP_VIEWS,
97
+ module: DEEP_VIEWS,
98
+ purl: PURL,
99
+ purpose: 'Subscribes to drawing updates',
100
+ framework: 'react',
101
+ stereotype: 'hook',
102
+ },
103
+ ];
104
+
105
+ const deepEdges = graphSpecFromEdges([
106
+ ['node-comp', 'group-comp', 'imports'],
107
+ ['edge-comp', 'group-comp', 'imports'],
108
+ ['analysis', 'layers', 'imports'],
109
+ ['use-drawings', 'analysis', 'imports'],
110
+ ['analysis', 'node-comp', 'imports'],
111
+ ]);
112
+
113
+ /** Collapsed module badges show `first/…/last`. Click one to expand the full
114
+ * path (just the badge grows — the module frame stays put). */
115
+ export const DeepModulePaths: Story = {
116
+ render: () => (
117
+ <div style={{ width: '100%', height: '100vh' }}>
118
+ <SubsystemComponentGraph
119
+ title="Deep module paths"
120
+ description={
121
+ 'Module badges never spill past their frame while collapsed. A path that would overflow collapses to `first/…/last`; ' +
122
+ 'click the badge to expand the full path (the badge widens past the frame edge — the frame itself stays put), click again to collapse it back.'
123
+ }
124
+ components={deepComponents}
125
+ relations={deepEdges.relations}
126
+ walkthroughs={deepEdges.walkthroughs}
127
+ />
128
+ </div>
129
+ ),
130
+ };
131
+
132
+ const HARNESS_FRAME_WIDTH = 360;
133
+
134
+ const harnessRegion: SubsystemProcessRegion = {
135
+ kind: 'module',
136
+ key: DEEP_NODES,
137
+ label: DEEP_NODES,
138
+ memberAliases: ['node-comp', 'group-comp', 'edge-comp'],
139
+ };
140
+
141
+ /** Fixed frame; the badge is the only thing that grows on click. */
142
+ function ModuleBadgeHarness() {
143
+ const nodeProps = {
144
+ id: `module:${harnessRegion.key}`,
145
+ data: { region: harnessRegion },
146
+ width: HARNESS_FRAME_WIDTH,
147
+ height: 180,
148
+ selected: false,
149
+ } as unknown as NodeProps<SubsystemGraphNode>;
150
+ return (
151
+ <div
152
+ style={{
153
+ padding: 56,
154
+ display: 'flex',
155
+ flexDirection: 'column',
156
+ gap: 16,
157
+ height: '100vh',
158
+ boxSizing: 'border-box',
159
+ fontFamily: 'ui-sans-serif, system-ui, sans-serif',
160
+ }}
161
+ >
162
+ <div style={{ fontSize: 13, color: '#8a90a0' }}>
163
+ The module frame stays at{' '}
164
+ <span style={{ fontFamily: 'monospace', color: '#d5d9e2' }}>
165
+ {HARNESS_FRAME_WIDTH}px
166
+ </span>
167
+ . Hover a badge and it widens to reveal more of the path text (no
168
+ stretch, no distortion) to show it's clickable. Click to expand the
169
+ full path past the frame's edge, click again to collapse back to{' '}
170
+ <code>first/…/last</code>.
171
+ </div>
172
+ <div style={{ position: 'relative', width: HARNESS_FRAME_WIDTH, minWidth: 0 }}>
173
+ <SubsystemGroupNode {...nodeProps} />
174
+ </div>
175
+ </div>
176
+ );
177
+ }
178
+
179
+ /** Isolated demo: only the badge grows — the module frame never moves. */
180
+ export const BadgeOnly: Story = {
181
+ parameters: { layout: 'fullscreen' },
182
+ render: () => <ModuleBadgeHarness />,
183
+ };
@@ -13,10 +13,10 @@ import type { GraphifyComponentDetail } from '../../../graphify';
13
13
  // Build a subsystem graph from a compact spec - helpers
14
14
  // ---------------------------------------------------------------------------
15
15
  export function components(
16
- spec: Array<[id: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, declaration?: GraphifyComponentDetail]>,
16
+ spec: Array<[alias: string, name: string, construct: SubsystemComponent['construct'], file: string, purl: string, purpose?: string, symbol?: string, declaration?: GraphifyComponentDetail]>,
17
17
  ): SubsystemComponent[] {
18
- return spec.map(([id, name, construct, file, purl, purpose, symbol, declaration]) => ({
19
- id,
18
+ return spec.map(([alias, name, construct, file, purl, purpose, symbol, declaration]) => ({
19
+ alias,
20
20
  name,
21
21
  construct,
22
22
  file,
@@ -135,7 +135,7 @@ export const readerDetail: GraphifyComponentDetail = {
135
135
  // ---------------------------------------------------------------------------
136
136
  export const investigateOnlyComponents: SubsystemComponent[] = [
137
137
  {
138
- id: 'v1',
138
+ alias: 'v1',
139
139
  name: 'V1EventBridgeProcessor',
140
140
  construct: 'class',
141
141
  file: 'src/event-processing/V1EventBridge.ts',
@@ -144,7 +144,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
144
144
  symbol: 'V1EventBridgeProcessor',
145
145
  },
146
146
  {
147
- id: 'v2',
147
+ alias: 'v2',
148
148
  name: 'V2EventBridgeProcessor',
149
149
  construct: 'class',
150
150
  file: 'src/event-processing/V2EventBridge.ts',
@@ -153,7 +153,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
153
153
  symbol: 'V2EventBridgeProcessor',
154
154
  },
155
155
  {
156
- id: 'input',
156
+ alias: 'input',
157
157
  name: 'RepoNormalizedUniversalAgentSessionEvent',
158
158
  construct: 'interface',
159
159
  file: 'types/RepoNormalizedUniversalAgentSessionEvent.ts',
@@ -162,7 +162,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
162
162
  symbol: 'RepoNormalizedUniversalAgentSessionEvent',
163
163
  },
164
164
  {
165
- id: 'acc',
165
+ alias: 'acc',
166
166
  name: 'accumulateToAgentSessionEvents',
167
167
  construct: 'function',
168
168
  file: 'src/accumulateToAgentSessionEvents.ts',
@@ -171,7 +171,7 @@ export const investigateOnlyComponents: SubsystemComponent[] = [
171
171
  symbol: 'accumulateToAgentSessionEvents',
172
172
  },
173
173
  {
174
- id: 'out',
174
+ alias: 'out',
175
175
  name: 'AgentSessionEvent',
176
176
  construct: 'interface',
177
177
  file: 'types/AgentSessionEvent.ts',
@@ -116,7 +116,7 @@ export interface ComponentDeclarationProps {
116
116
  /** Max width of the declaration panel (CSS value). Defaults to none. */
117
117
  maxWidth?: string | number;
118
118
  /** When set, shows a Verify control that calls back with the component id. */
119
- onVerify?: (componentId: string) => void;
119
+ onVerify?: (componentAlias: string) => void;
120
120
  /** Live verification status for the selected component. */
121
121
  verification?: ComponentVerificationState | null;
122
122
  /** Start with the file path row visible (catalog / source-first views). */
@@ -411,7 +411,7 @@ export function ComponentDeclaration({
411
411
  disabled={verifyBusy}
412
412
  onClick={(e) => {
413
413
  e.stopPropagation();
414
- onVerify(component.id);
414
+ onVerify(component.alias);
415
415
  }}
416
416
  style={{
417
417
  display: 'flex',
@@ -11,7 +11,7 @@ import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
11
11
  import type { ReactNode } from 'react';
12
12
  import { useTheme } from '@principal-ade/industry-theme';
13
13
  import { IndustryMarkdownSlide } from 'themed-markdown';
14
- import { ChevronDown, ChevronRight, ChevronUp, FileText, Folder } from 'lucide-react';
14
+ import { ChevronDown, ChevronRight, FileText, Folder } from 'lucide-react';
15
15
  import {
16
16
  constructBadgeColor,
17
17
  constructBadgeLabel,
@@ -29,7 +29,7 @@ import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
29
29
 
30
30
  export interface ConstructsCatalogProps {
31
31
  components: SubsystemComponent[];
32
- onSelect?: (componentId: string) => void;
32
+ onSelect?: (componentAlias: string) => void;
33
33
  title?: string;
34
34
  hideSidebar?: boolean;
35
35
  description?: string;
@@ -39,7 +39,7 @@ export interface ConstructsCatalogProps {
39
39
  renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
40
40
  renderFileView?: (component: SubsystemComponent) => ReactNode;
41
41
  onFileSelect?: (file: string) => void;
42
- onVerifyComponent?: (componentId: string) => void;
42
+ onVerifyComponent?: (componentAlias: string) => void;
43
43
  componentVerification?: ComponentVerificationState | null;
44
44
  }
45
45
 
@@ -111,7 +111,7 @@ function resolveRelated(
111
111
  const clean = ref.replace(/\(\)$/, '');
112
112
  return components.find(
113
113
  (c) =>
114
- c.id === clean ||
114
+ c.alias === clean ||
115
115
  c.name === clean ||
116
116
  c.symbol === clean ||
117
117
  c.symbol?.replace(/\(\)$/, '') === clean,
@@ -170,11 +170,11 @@ export function ConstructsCatalog({
170
170
  .map((x) => x.c);
171
171
  }, [components]);
172
172
 
173
- const [visibleIds, setVisibleIds] = useState<string[]>(() =>
174
- orderedComponents[0] ? [orderedComponents[0].id] : [],
173
+ const [visibleAliases, setVisibleAliases] = useState<string[]>(() =>
174
+ orderedComponents[0] ? [orderedComponents[0].alias] : [],
175
175
  );
176
- const [focusedId, setFocusedId] = useState<string | null>(
177
- () => orderedComponents[0]?.id ?? null,
176
+ const [focusedAlias, setFocusedAlias] = useState<string | null>(
177
+ () => orderedComponents[0]?.alias ?? null,
178
178
  );
179
179
  const [descriptionVisible, setDescriptionVisible] = useState(false);
180
180
  const [descToggleHover, setDescToggleHover] = useState(false);
@@ -186,12 +186,12 @@ export function ConstructsCatalog({
186
186
  const [drawer, setDrawer] = useState<{ file: string; startLine?: number } | null>(
187
187
  null,
188
188
  );
189
- const focusedRef = useRef<string | null>(focusedId);
190
- focusedRef.current = focusedId;
189
+ const focusedAliasRef = useRef<string | null>(focusedAlias);
190
+ focusedAliasRef.current = focusedAlias;
191
191
 
192
- const visibleSet = useMemo(() => new Set(visibleIds), [visibleIds]);
192
+ const visibleSet = useMemo(() => new Set(visibleAliases), [visibleAliases]);
193
193
  const visibleComponents = useMemo(
194
- () => orderedComponents.filter((c) => visibleSet.has(c.id)),
194
+ () => orderedComponents.filter((c) => visibleSet.has(c.alias)),
195
195
  [orderedComponents, visibleSet],
196
196
  );
197
197
 
@@ -213,7 +213,7 @@ export function ConstructsCatalog({
213
213
  }> = [];
214
214
  const index = new Map<string, number>();
215
215
  for (const c of visibleComponents) {
216
- const key = c.purl || c.id;
216
+ const key = c.purl || c.alias;
217
217
  let at = index.get(key);
218
218
  if (at == null) {
219
219
  at = groups.length;
@@ -227,17 +227,17 @@ export function ConstructsCatalog({
227
227
  }, [visibleComponents]);
228
228
 
229
229
  useEffect(() => {
230
- if (!focusedId) return;
231
- document.getElementById(`construct-${focusedId}`)?.scrollIntoView({ block: 'nearest' });
232
- }, [focusedId]);
230
+ if (!focusedAlias) return;
231
+ document.getElementById(`construct-${focusedAlias}`)?.scrollIntoView({ block: 'nearest' });
232
+ }, [focusedAlias]);
233
233
 
234
234
  useEffect(() => {
235
- const last = visibleIds[visibleIds.length - 1];
235
+ const last = visibleAliases[visibleAliases.length - 1];
236
236
  if (!last) return;
237
237
  document
238
238
  .getElementById(`construct-signature-${last}`)
239
239
  ?.scrollIntoView({ block: 'nearest' });
240
- }, [visibleIds]);
240
+ }, [visibleAliases]);
241
241
 
242
242
  // Keep the declaration whose file is open in view, so the source and its
243
243
  // signature stay legible together.
@@ -249,47 +249,47 @@ export function ConstructsCatalog({
249
249
  ) ?? orderedComponents.find((c) => c.file === drawer.file);
250
250
  if (!match) return;
251
251
  document
252
- .getElementById(`construct-signature-${match.id}`)
252
+ .getElementById(`construct-signature-${match.alias}`)
253
253
  ?.scrollIntoView({ block: 'nearest' });
254
254
  }, [orderedComponents, drawer]);
255
255
 
256
- // Drop ids that left the model; if nothing remains, show the first construct.
256
+ // Drop aliases that left the model; if nothing remains, show the first construct.
257
257
  useEffect(() => {
258
- const ids = new Set(orderedComponents.map((c) => c.id));
259
- setVisibleIds((prev) => {
260
- const next = prev.filter((id) => ids.has(id));
258
+ const aliases = new Set(orderedComponents.map((c) => c.alias));
259
+ setVisibleAliases((prev) => {
260
+ const next = prev.filter((alias) => aliases.has(alias));
261
261
  if (next.length > 0 || orderedComponents.length === 0) return next;
262
- return [orderedComponents[0]!.id];
262
+ return [orderedComponents[0]!.alias];
263
263
  });
264
- setFocusedId((prev) => {
265
- if (prev && ids.has(prev)) return prev;
266
- return orderedComponents[0]?.id ?? null;
264
+ setFocusedAlias((prev) => {
265
+ if (prev && aliases.has(prev)) return prev;
266
+ return orderedComponents[0]?.alias ?? null;
267
267
  });
268
268
  }, [orderedComponents]);
269
269
 
270
270
  const toggle = useCallback(
271
- (id: string) => {
272
- setFocusedId(id);
273
- setVisibleIds((prev) =>
274
- prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id],
271
+ (alias: string) => {
272
+ setFocusedAlias(alias);
273
+ setVisibleAliases((prev) =>
274
+ prev.includes(alias) ? prev.filter((x) => x !== alias) : [...prev, alias],
275
275
  );
276
- onSelect?.(id);
276
+ onSelect?.(alias);
277
277
  },
278
278
  [onSelect],
279
279
  );
280
280
 
281
281
  const show = useCallback(
282
- (id: string) => {
283
- setFocusedId(id);
284
- setVisibleIds((prev) => (prev.includes(id) ? prev : [...prev, id]));
285
- onSelect?.(id);
282
+ (alias: string) => {
283
+ setFocusedAlias(alias);
284
+ setVisibleAliases((prev) => (prev.includes(alias) ? prev : [...prev, alias]));
285
+ onSelect?.(alias);
286
286
  },
287
287
  [onSelect],
288
288
  );
289
289
 
290
290
  const focusAt = useCallback(
291
- (id: string) => {
292
- setFocusedId(id);
291
+ (alias: string) => {
292
+ setFocusedAlias(alias);
293
293
  },
294
294
  [],
295
295
  );
@@ -307,17 +307,17 @@ export function ConstructsCatalog({
307
307
  * all when they're already shown — mirroring a construct row toggle. */
308
308
  const toggleFile = useCallback(
309
309
  (comps: SubsystemComponent[]) => {
310
- const ids = comps.map((c) => c.id);
311
- setVisibleIds((prev) => {
310
+ const aliases = comps.map((c) => c.alias);
311
+ setVisibleAliases((prev) => {
312
312
  const set = new Set(prev);
313
- const allVisible = ids.every((id) => set.has(id));
314
- ids.forEach((id) => (allVisible ? set.delete(id) : set.add(id)));
315
- return orderedComponents.filter((c) => set.has(c.id)).map((c) => c.id);
313
+ const allVisible = aliases.every((alias) => set.has(alias));
314
+ aliases.forEach((alias) => (allVisible ? set.delete(alias) : set.add(alias)));
315
+ return orderedComponents.filter((c) => set.has(c.alias)).map((c) => c.alias);
316
316
  });
317
317
  const first = comps[0];
318
318
  if (first) {
319
- setFocusedId(first.id);
320
- onSelect?.(first.id);
319
+ setFocusedAlias(first.alias);
320
+ onSelect?.(first.alias);
321
321
  }
322
322
  },
323
323
  [orderedComponents, onSelect],
@@ -380,8 +380,8 @@ export function ConstructsCatalog({
380
380
  </li>
381
381
  );
382
382
  }
383
- const ids = child.components.map((c) => c.id);
384
- const allVisible = ids.length > 0 && ids.every((id) => visibleSet.has(id));
383
+ const aliases = child.components.map((c) => c.alias);
384
+ const allVisible = aliases.length > 0 && aliases.every((alias) => visibleSet.has(alias));
385
385
  const hovered = hoveredRow === child.path;
386
386
  const color = componentColor(child.components[0]!, pierreTheme);
387
387
  return (
@@ -438,7 +438,7 @@ export function ConstructsCatalog({
438
438
  color: allVisible ? color : muted,
439
439
  }}
440
440
  >
441
- {ids.length}
441
+ {aliases.length}
442
442
  </span>
443
443
  </button>
444
444
  </li>
@@ -473,7 +473,7 @@ export function ConstructsCatalog({
473
473
  (ref: string) => {
474
474
  const comp = resolveRelated(components, ref);
475
475
  if (!comp) return;
476
- show(comp.id);
476
+ show(comp.alias);
477
477
  },
478
478
  [components, show],
479
479
  );
@@ -505,13 +505,13 @@ export function ConstructsCatalog({
505
505
  if (orderedComponents.length === 0) return;
506
506
  const idx = Math.max(
507
507
  0,
508
- orderedComponents.findIndex((c) => c.id === focusedRef.current),
508
+ orderedComponents.findIndex((c) => c.alias === focusedAliasRef.current),
509
509
  );
510
510
  const next =
511
511
  orderedComponents[
512
512
  (idx + delta + orderedComponents.length) % orderedComponents.length
513
513
  ]!;
514
- focusAt(next.id);
514
+ focusAt(next.alias);
515
515
  },
516
516
  [orderedComponents, focusAt],
517
517
  );
@@ -537,15 +537,15 @@ export function ConstructsCatalog({
537
537
  moveFocus(-1);
538
538
  } else if (e.key === 'Home') {
539
539
  e.preventDefault();
540
- if (orderedComponents[0]) focusAt(orderedComponents[0].id);
540
+ if (orderedComponents[0]) focusAt(orderedComponents[0].alias);
541
541
  } else if (e.key === 'End') {
542
542
  e.preventDefault();
543
543
  const last = orderedComponents[orderedComponents.length - 1];
544
- if (last) focusAt(last.id);
544
+ if (last) focusAt(last.alias);
545
545
  } else if (e.key === ' ' || e.key === 'Enter') {
546
- if (focusedRef.current) {
546
+ if (focusedAliasRef.current) {
547
547
  e.preventDefault();
548
- toggle(focusedRef.current);
548
+ toggle(focusedAliasRef.current);
549
549
  }
550
550
  } else if (e.key === 'Escape' && drawer) {
551
551
  setDrawer(null);
@@ -646,16 +646,12 @@ export function ConstructsCatalog({
646
646
  padding: 0,
647
647
  border: 'none',
648
648
  borderRadius: 4,
649
- background: descToggleHover ? theme.colors.border : 'transparent',
650
- color: descToggleHover ? theme.colors.text : muted,
649
+ background: descriptionVisible || descToggleHover ? theme.colors.border : 'transparent',
650
+ color: descriptionVisible || descToggleHover ? theme.colors.text : muted,
651
651
  cursor: 'pointer',
652
652
  }}
653
653
  >
654
- {descriptionVisible ? (
655
- <ChevronUp size={14} />
656
- ) : (
657
- <ChevronDown size={14} />
658
- )}
654
+ <FileText size={14} />
659
655
  </button>
660
656
  )}
661
657
  </div>
@@ -728,7 +724,7 @@ export function ConstructsCatalog({
728
724
  role="listbox"
729
725
  aria-label="Constructs"
730
726
  aria-multiselectable="true"
731
- aria-activedescendant={focusedId ? `construct-${focusedId}` : undefined}
727
+ aria-activedescendant={focusedAlias ? `construct-${focusedAlias}` : undefined}
732
728
  style={{
733
729
  listStyle: 'none',
734
730
  margin: 0,
@@ -739,8 +735,8 @@ export function ConstructsCatalog({
739
735
  }}
740
736
  >
741
737
  {orderedComponents.map((c) => {
742
- const visible = visibleSet.has(c.id);
743
- const focused = c.id === focusedId;
738
+ const visible = visibleSet.has(c.alias);
739
+ const focused = c.alias === focusedAlias;
744
740
  const color = componentColor(c, pierreTheme);
745
741
  const badgeColor = constructBadgeColor(c) ?? color;
746
742
  const badgeLabel = constructBadgeLabel(c);
@@ -757,19 +753,19 @@ export function ConstructsCatalog({
757
753
  !!c.file &&
758
754
  c.file === drawer.file &&
759
755
  c.declarationRef?.startLine === drawer.startLine;
760
- const hovered = hoveredRow === c.id;
756
+ const hovered = hoveredRow === c.alias;
761
757
  return (
762
- <li key={c.id} role="presentation">
758
+ <li key={c.alias} role="presentation">
763
759
  <button
764
760
  type="button"
765
- id={`construct-${c.id}`}
761
+ id={`construct-${c.alias}`}
766
762
  role="option"
767
763
  aria-selected={visible}
768
- data-testid={`construct-row-${c.id}`}
769
- onClick={() => toggle(c.id)}
770
- onMouseEnter={() => setHoveredRow(c.id)}
764
+ data-testid={`construct-row-${c.alias}`}
765
+ onClick={() => toggle(c.alias)}
766
+ onMouseEnter={() => setHoveredRow(c.alias)}
771
767
  onMouseLeave={() =>
772
- setHoveredRow((h) => (h === c.id ? null : h))
768
+ setHoveredRow((h) => (h === c.alias ? null : h))
773
769
  }
774
770
  style={{
775
771
  display: 'flex',
@@ -938,8 +934,8 @@ export function ConstructsCatalog({
938
934
  c.declarationRef?.startLine === drawer.startLine;
939
935
  return (
940
936
  <div
941
- key={c.id}
942
- id={`construct-signature-${c.id}`}
937
+ key={c.alias}
938
+ id={`construct-signature-${c.alias}`}
943
939
  style={{
944
940
  border: `1px solid ${lineOpen ? accentColor : theme.colors.border}`,
945
941
  boxShadow: lineOpen ? `0 0 0 1px ${accentColor}` : undefined,
@@ -959,7 +955,7 @@ export function ConstructsCatalog({
959
955
  showRepoIdentity={false}
960
956
  fileBadgeChrome={!!fileViewer}
961
957
  verification={
962
- componentVerification && focusedId === c.id
958
+ componentVerification && focusedAlias === c.alias
963
959
  ? componentVerification
964
960
  : undefined
965
961
  }