@transitrix/diagrams 1.3.0 → 1.4.0

package/src/webview/__tests__/render-blocks.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Unit tests for the host-neutral nested-blocks SVG renderer used by both the
+ * VS Code blocks preview and the IntelliJ JCEF webview bundle. These tests pin
+ * the per-node label rule (CLAUDE.md "Entity block layout"): leaf nodes wrap
+ * the name to at most 3 lines and the ID to at most 2 lines, with `…`
+ * truncation beyond that; container headers stack name + ID, each truncated
+ * with `…` to fit the block width. No label may extend past the rect.
+ */
+import { describe, expect, it } from 'vitest';
+
+import type { BlocksFile } from '../../blocks/types.js';
+import { renderBlocksSvg } from '../render-blocks.js';
+
+// Approximate character widths used by the renderer when sizing labels.
+// Kept in sync with `CHAR_W` / `CHAR_W_ID` in render-blocks.ts so the test
+// can compute the same overflow bounds the renderer uses.
+const CHAR_W = 7;
+const CHAR_W_ID = 6;
+
+// Same horizontal margin the renderer reserves so text never abuts the rect.
+const TEXT_MARGIN_X = 8;
+
+function leafDoc(name: string, id: string): BlocksFile {
+  return {
+    notation: 'blocks',
+    spec_version: '0.1',
+    nested_blocks: {
+      id: 'BLOCKS-T-1',
+      name: 'Test',
+      blocks: [{ id, name }],
+    },
+  };
+}
+
+function containerDoc(name: string, id: string, childId = 'CHILD', childName = 'Child'): BlocksFile {
+  return {
+    notation: 'blocks',
+    spec_version: '0.1',
+    nested_blocks: {
+      id: 'BLOCKS-T-1',
+      name: 'Test',
+      blocks: [
+        {
+          id,
+          name,
+          children: [{ id: childId, name: childName }],
+        },
+      ],
+    },
+  };
+}
+
+/** Pull every text-primary / text-id line out of an SVG, in document order. */
+function extractLabels(svg: string): Array<{ cls: string; text: string }> {
+  const re = /<text class="(text-(?:primary|id))"[^>]*>([^<]*)<\/text>/g;
+  const out: Array<{ cls: string; text: string }> = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(svg))) out.push({ cls: m[1], text: m[2] });
+  return out;
+}
+
+describe('renderBlocksSvg — leaf labels', () => {
+  it('wraps a long name to at most 3 lines and truncates with …', () => {
+    const longName =
+      'Personal data records that linger after consent withdrawal across many systems and ' +
+      'archives — known erasure gap';
+    const svg = renderBlocksSvg(leafDoc(longName, 'PII'));
+    const nameLines = extractLabels(svg).filter((l) => l.cls === 'text-primary');
+    expect(nameLines.length).toBeGreaterThan(0);
+    expect(nameLines.length).toBeLessThanOrEqual(3);
+    // If the name needed truncation, the final visible line must end with `…`.
+    if (nameLines.length === 3) {
+      expect(nameLines[2].text.endsWith('…')).toBe(true);
+    }
+  });
+
+  it('wraps a long ID to at most 2 lines and truncates with …', () => {
+    const longId = 'VERY_LONG_BLOCK_IDENTIFIER_WITH_MANY_SEGMENTS_AND_MORE_AND_MORE';
+    const svg = renderBlocksSvg(leafDoc('Short name', longId));
+    const idLines = extractLabels(svg).filter((l) => l.cls === 'text-id');
+    expect(idLines.length).toBeGreaterThan(0);
+    expect(idLines.length).toBeLessThanOrEqual(2);
+    if (idLines.length === 2) {
+      expect(idLines[1].text.endsWith('…')).toBe(true);
+    }
+  });
+
+  it('keeps every label inside the 160px leaf width (approximated by CHAR_W * length)', () => {
+    const svg = renderBlocksSvg(
+      leafDoc(
+        'Personal data records that linger after consent withdrawal across many systems',
+        'PII_RECORDS_WITH_A_FAIRLY_LONG_IDENTIFIER_HERE',
+      ),
+    );
+    const labels = extractLabels(svg);
+    const inner = 160 - TEXT_MARGIN_X * 2;
+    for (const l of labels) {
+      const cw = l.cls === 'text-primary' ? CHAR_W : CHAR_W_ID;
+      expect(l.text.length * cw).toBeLessThanOrEqual(inner);
+    }
+  });
+});
+
+describe('renderBlocksSvg — container headers', () => {
+  it('renders the name and ID as two separate stacked text elements', () => {
+    const svg = renderBlocksSvg(containerDoc('Active systems', 'ACTIVE_SYSTEMS'));
+    const labels = extractLabels(svg);
+    // Container header contributes one text-primary (name) and one text-id (id);
+    // the leaf child contributes another pair. So 2 of each kind in total.
+    const primaries = labels.filter((l) => l.cls === 'text-primary').map((l) => l.text);
+    const ids = labels.filter((l) => l.cls === 'text-id').map((l) => l.text);
+    expect(primaries).toContain('Active systems');
+    expect(ids).toContain('ACTIVE_SYSTEMS');
+    // The legacy "(id)" suffix on the name line must not appear — id has its own row.
+    for (const t of primaries) expect(t).not.toContain('(');
+  });
+
+  it('truncates a long container ID so it does not overflow the block width', () => {
+    const svg = renderBlocksSvg(
+      containerDoc(
+        'Short name',
+        'VERY_LONG_CONTAINER_IDENTIFIER_THAT_WOULD_OTHERWISE_OVERFLOW',
+        'CHILD',
+        'Child',
+      ),
+    );
+    const labels = extractLabels(svg);
+    // The container width derives from its single 160px child: 160 + 2*12 (padding) = 184.
+    const containerW = 160 + 24;
+    const inner = containerW - TEXT_MARGIN_X * 2;
+    for (const l of labels) {
+      const cw = l.cls === 'text-primary' ? CHAR_W : CHAR_W_ID;
+      expect(l.text.length * cw).toBeLessThanOrEqual(inner);
+    }
+    // The full ID was too long to fit on one line of `inner / CHAR_W_ID` chars, so
+    // the rendered ID must be the truncated form ending in `…`.
+    const renderedIds = labels.filter((l) => l.cls === 'text-id').map((l) => l.text);
+    expect(renderedIds.some((t) => t.endsWith('…'))).toBe(true);
+  });
+
+  it('truncates a long container name with … to fit the block width', () => {
+    const longName =
+      'Active systems that are erasure-reachable within the standard 30-day operational window';
+    const svg = renderBlocksSvg(containerDoc(longName, 'ACTIVE'));
+    const labels = extractLabels(svg);
+    const containerW = 160 + 24;
+    const inner = containerW - TEXT_MARGIN_X * 2;
+    const primaries = labels.filter((l) => l.cls === 'text-primary');
+    for (const l of primaries) {
+      expect(l.text.length * CHAR_W).toBeLessThanOrEqual(inner);
+    }
+    // At least one primary line must have been truncated.
+    expect(primaries.some((l) => l.text.endsWith('…'))).toBe(true);
+  });
+});

package/src/webview/entry.ts

@@ -93,10 +93,8 @@ export type NotationKind =
   | 'goals'
   | 'dgca'
   | 'dga'
-  | 'fgca'
-  | 'fga'
-  | 'activities'
-  | 'activity-card'
+  | 'action'
+  | 'action-card'
   | 'applications'
   | 'products'
   | 'process-map'
@@ -109,10 +107,8 @@ const SUPPORTED_KINDS: readonly NotationKind[] = [
   'goals',
   'dgca',
   'dga',
-  'fgca',
-  'fga',
-  'activities',
-  'activity-card',
+  'action',
+  'action-card',
   'applications',
   'products',
   'process-map',
@@ -186,11 +182,7 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       }
       return r;
     }
-    // DGCA and DGA are the canonical new names; FGCA/FGA are accepted as
-    // deprecated aliases. All four share the same parse + renderer; only the
-    // Change column visibility differs (DGA/FGA collapse it).
-    case 'dgca':
-    case 'fgca': {
+    case 'dgca': {
       const v = parseCanonicalFGCA(doc);
       const r = emptyResult(kind, v.valid ? 'ok' : 'error');
       r.errors.push(...v.errors);
@@ -200,8 +192,7 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       }
       return r;
     }
-    case 'dga':
-    case 'fga': {
+    case 'dga': {
       const v = parseCanonicalFGA(doc);
       const r = emptyResult(kind, v.valid ? 'ok' : 'error');
       r.errors.push(...v.errors);
@@ -211,12 +202,12 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       }
       return r;
     }
-    case 'activities':
-      return renderFromValidation('activities', validateActivities(doc), () =>
+    case 'action':
+      return renderFromValidation('action', validateActivities(doc), () =>
         renderActivitiesSvg(doc as ActivityDoc),
       );
-    case 'activity-card':
-      return renderFromValidation('activity-card', validateActivityCard(doc), () =>
+    case 'action-card':
+      return renderFromValidation('action-card', validateActivityCard(doc), () =>
         renderActivityCardSvg(doc as ActivityCardDoc),
       );
     case 'process-blueprint':

package/src/webview/render-activities.ts

@@ -144,6 +144,18 @@ export interface RenderActivitiesOptions {
   curvature?: number;
   /** Entry curvature at the target node; defaults to `curvature` when omitted. */
   entryCurvature?: number;
+  /**
+   * When true (the default), activities with `activity_type === 'project'` are
+   * excluded from the network layout. Project container nodes add visual noise
+   * in the PSND view because the diagram itself already represents the project
+   * scope; suppressing them declutters the network without altering canonical
+   * data. Set to false to render all activities regardless of type.
+   *
+   * Convention: Network/diagram views suppress project nodes by default.
+   * Text/document views (Tree) keep them visible and compensate with the
+   * Action name in the view header.
+   */
+  suppressProjectNodes?: boolean;
 }
 
 /**
@@ -161,15 +173,28 @@ export interface RenderActivitiesOptions {
  * than short-circuiting.
  */
 export function renderActivitiesSvg(doc: ActivityDoc, options: RenderActivitiesOptions = {}): string {
-  const { title = '', gaps = {}, curvature = DEFAULT_EDGE_CURVATURE, entryCurvature } = options;
-
-  const layout: ActivitiesLayout = layoutActivities(doc, gaps);
+  const {
+    title = '',
+    gaps = {},
+    curvature = DEFAULT_EDGE_CURVATURE,
+    entryCurvature,
+    suppressProjectNodes = true,
+  } = options;
+
+  // #421: Suppress project-type container nodes in the network layout by
+  // default (see suppressProjectNodes JSDoc). A shallow copy avoids mutating
+  // the caller's doc.
+  const renderDoc: ActivityDoc = suppressProjectNodes
+    ? { ...doc, activities: (doc.activities ?? []).filter((a) => a.activity_type?.toLowerCase() !== 'project') }
+    : doc;
+
+  const layout: ActivitiesLayout = layoutActivities(renderDoc, gaps);
 
   if (layout.nodes.length === 0) {
     return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
   }
 
-  const cpm = computeCpm(doc.activities ?? []);
+  const cpm = computeCpm(renderDoc.activities ?? []);
   const titleH = title ? 24 : 0;
   const w = layout.bounds.width + N_PAD * 2;
   const h = layout.bounds.height + N_PAD * 2 + titleH;

package/src/webview/render-blocks.ts

@@ -21,9 +21,53 @@ const PAD = 24;
 
 // Approximate character width (px) at text-primary size (12px/600).
 const CHAR_W = 7;
-// Approximate character width (px) at text-id size (10px/600) — used for ID suffix.
+// Approximate character width (px) at text-id size (10px/600).
 const CHAR_W_ID = 6;
 
+// Vertical spacing between line centres.
+const LINE_H = 14;    // name lines (text-primary)
+const LINE_H_ID = 12; // id lines (text-id)
+const NAME_ID_GAP = 6; // gap between last name centre and first ID centre
+
+/** Word-wrap `text` to at most `maxLines` lines of `maxChars` each. */
+function wrapWords(text: string, maxChars: number, maxLines: number): string[] {
+  const safeMax = Math.max(2, maxChars);
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let cur = '';
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    const next = cur ? `${cur} ${w}` : w;
+    if (next.length <= safeMax) {
+      cur = next;
+    } else {
+      if (cur) lines.push(cur);
+      cur = '';
+      if (lines.length >= maxLines) break;
+      if (lines.length === maxLines - 1) {
+        const rest = words.slice(i).join(' ');
+        lines.push(rest.length <= safeMax ? rest : rest.slice(0, safeMax - 1) + '…');
+        return lines;
+      }
+      cur = w.length <= safeMax ? w : w.slice(0, safeMax - 1) + '…';
+    }
+  }
+  if (cur && lines.length < maxLines) lines.push(cur);
+  return lines.length ? lines : [text.slice(0, safeMax - 1) + '…'];
+}
+
+/** Split an ID (no spaces) across at most 2 lines, breaking at `_` or `-`. */
+function wrapId(id: string, maxChars: number): string[] {
+  if (id.length <= maxChars) return [id];
+  const seg = id.slice(0, maxChars);
+  const sepIdx = Math.max(seg.lastIndexOf('_'), seg.lastIndexOf('-'));
+  const cut = sepIdx > Math.floor(maxChars / 3) ? sepIdx : maxChars - 1;
+  const isSep = id[cut] === '_' || id[cut] === '-';
+  const line1 = id.slice(0, cut);
+  const rest = id.slice(cut + (isSep ? 1 : 0));
+  return [line1, rest.length <= maxChars ? rest : rest.slice(0, maxChars - 1) + '…'];
+}
+
 export interface RenderBlocksOptions {
   title?: string;
 }
@@ -41,12 +85,25 @@ function levelClassForDepth(depth: number): string {
   return `level-${idx}`;
 }
 
-/** Truncate at a word boundary so labels never break in the middle of a word. */
-function wordTruncate(text: string, maxChars: number): string {
-  if (text.length <= maxChars) return text;
-  const cut = text.slice(0, maxChars - 1);
+// Reserve a small horizontal margin so text never abuts the rounded corners.
+const TEXT_MARGIN_X = 8;
+
+/** Truncate `text` to at most `maxChars` characters, at a word boundary when possible. */
+function truncateLine(text: string, maxChars: number): string {
+  const safeMax = Math.max(2, maxChars);
+  if (text.length <= safeMax) return text;
+  const cut = text.slice(0, safeMax - 1);
   const lastSpace = cut.lastIndexOf(' ');
-  return (lastSpace > maxChars / 2 ? cut.slice(0, lastSpace) : cut) + '…';
+  return (lastSpace > safeMax / 2 ? cut.slice(0, lastSpace) : cut) + '…';
+}
+
+/** Single-line ID truncation that prefers `_`/`-` separators before falling back to a hard cut. */
+function truncateId(id: string, maxChars: number): string {
+  const safeMax = Math.max(2, maxChars);
+  if (id.length <= safeMax) return id;
+  const cut = id.slice(0, safeMax - 1);
+  const sepIdx = Math.max(cut.lastIndexOf('_'), cut.lastIndexOf('-'));
+  return (sepIdx > safeMax / 3 ? cut.slice(0, sepIdx) : cut) + '…';
 }
 
 function emitBlockSvg(b: LaidOutBlock, ox: number, oy: number, parts: string[]): void {
@@ -56,25 +113,49 @@ function emitBlockSvg(b: LaidOutBlock, ox: number, oy: number, parts: string[]):
     `<rect class="diagram-node ${cls}" x="${b.x + ox}" y="${b.y + oy}" width="${b.width}" height="${b.height}" rx="6"/>`,
   );
 
+  const innerW = Math.max(0, b.width - TEXT_MARGIN_X * 2);
   const isLeaf = b.children.length === 0;
   if (isLeaf) {
-    // Leaf block: name on upper line, ID on lower line — both centred.
-    const nameY = b.y + oy + Math.round(b.height * 0.38);
-    const idY = b.y + oy + Math.round(b.height * 0.66);
-    const maxChars = Math.max(4, Math.floor(b.width / CHAR_W));
+    // Leaf block: name (up to 3 lines) then ID (up to 2 lines), centred vertically.
+    const maxCharsName = Math.max(4, Math.floor(innerW / CHAR_W));
+    const maxCharsId = Math.max(4, Math.floor(innerW / CHAR_W_ID));
+    const nameLines = wrapWords(b.name, maxCharsName, 3);
+    const idLines = wrapId(b.id, maxCharsId);
+    const nameTotalSpan = (nameLines.length - 1) * LINE_H;
+    const idTotalSpan = (idLines.length - 1) * LINE_H_ID;
+    const totalSpan = nameTotalSpan + NAME_ID_GAP + idTotalSpan;
+    const firstY = Math.round(b.y + oy + (b.height - totalSpan) / 2);
+    for (let i = 0; i < nameLines.length; i++) {
+      parts.push(
+        `<text class="text-primary" x="${cx}" y="${firstY + i * LINE_H}" text-anchor="middle" dominant-baseline="central">${escXml(nameLines[i])}</text>`,
+      );
+    }
+    const idFirstY = firstY + nameTotalSpan + NAME_ID_GAP;
+    for (let i = 0; i < idLines.length; i++) {
+      parts.push(
+        `<text class="text-id" x="${cx}" y="${idFirstY + i * LINE_H_ID}" text-anchor="middle" dominant-baseline="central">${escXml(idLines[i])}</text>`,
+      );
+    }
+  } else {
+    // Container block: name (text-primary) above, ID (text-id, grey) below — both
+    // single-line, truncated with `…` to fit within `b.width`. The header strip is
+    // only `headerHeight` tall (default 28px), which is enough for one line each at
+    // the configured text sizes. Stacking the ID as its own text-id element keeps
+    // the wrapping/truncation rule consistent with leaves and guarantees no overflow
+    // for any combination of name/ID length.
+    const maxCharsName = Math.max(4, Math.floor(innerW / CHAR_W));
+    const maxCharsId = Math.max(4, Math.floor(innerW / CHAR_W_ID));
+    const nameText = truncateLine(b.name, maxCharsName);
+    const idText = truncateId(b.id, maxCharsId);
+    const headerMid = b.y + oy + b.headerHeight / 2;
+    const halfSpan = (LINE_H + LINE_H_ID) / 4;
+    const nameY = Math.round(headerMid - halfSpan);
+    const idY = Math.round(headerMid + halfSpan);
     parts.push(
-      `<text class="text-primary" x="${cx}" y="${nameY}" text-anchor="middle" dominant-baseline="central">${escXml(wordTruncate(b.name, maxChars))}</text>`,
-      `<text class="text-id" x="${cx}" y="${idY}" text-anchor="middle" dominant-baseline="central">${escXml(b.id)}</text>`,
+      `<text class="text-primary" x="${cx}" y="${nameY}" text-anchor="middle" dominant-baseline="central">${escXml(nameText)}</text>`,
     );
-  } else {
-    // Container block: name + (ID) on the single header line; ID in grey.
-    const headerY = b.y + oy + b.headerHeight / 2;
-    const idSuffix = ` (${b.id})`;
-    const idSuffixW = idSuffix.length * CHAR_W_ID;
-    const nameMaxChars = Math.max(4, Math.floor((b.width - idSuffixW) / CHAR_W));
-    const nameText = wordTruncate(b.name, nameMaxChars);
     parts.push(
-      `<text class="text-primary" x="${cx}" y="${headerY}" text-anchor="middle" dominant-baseline="central">${escXml(nameText)}<tspan fill="var(--ts-text-secondary, #64748b)" font-size="10" font-weight="600">${escXml(idSuffix)}</tspan></text>`,
+      `<text class="text-id" x="${cx}" y="${idY}" text-anchor="middle" dominant-baseline="central">${escXml(idText)}</text>`,
     );
     for (const c of b.children) emitBlockSvg(c, ox, oy, parts);
   }