@transitrix/diagrams 1.8.13 → 1.8.19

package/dist/webview/render-activities.js

@@ -18,7 +18,7 @@
  */
 import { layoutActivities } from '../activities/layout.js';
 import { computeCpm } from '../activities/cpm.js';
-import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
+import { horizontalCubicEdgePath, bowedCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
 import { parseNodeSizePreset, resolveActionNodeSize } from '../node-size-presets.js';
 import { generateSvgEmbedCss } from '../theme/index.js';
 import { emitCenteredTextSvg, layoutCenteredEntityText } from './entity-text-layout.js';
@@ -46,6 +46,68 @@ export const ACTIVITIES_NETWORK_DEFS = `<defs>
     <path d="M0,0 L0,6 L8,3 z" class="arrow-fill-critical"/>
   </marker>
 </defs>`;
+/**
+ * Nodes horizontally between `source` and `target` (a "skip" edge passes over
+ * their column) whose vertical span overlaps the edge's Y band. A
+ * straight-tangent cubic (`horizontalCubicEdgePath`) stays within
+ * [min(sourceCenterY,targetCenterY), max(...)] by convex hull, so any such
+ * node sits directly on the edge's path — the "arrow goes straight through
+ * the node" bug reported against a linear PSND chain where a multi-predecessor
+ * activity's nearer predecessor shares a row with an intermediate column.
+ */
+function blockingNodes(nodes, source, target) {
+    const sCenterY = source.y + source.height / 2;
+    const tCenterY = target.y + target.height / 2;
+    const loY = Math.min(sCenterY, tCenterY);
+    const hiY = Math.max(sCenterY, tCenterY);
+    const sRight = source.x + source.width;
+    const tLeft = target.x;
+    return nodes.filter((n) => {
+        if (n.id === source.id || n.id === target.id)
+            return false;
+        if (n.x + n.width <= sRight || n.x >= tLeft)
+            return false; // not between the two columns
+        return n.y < hiY && n.y + n.height > loY; // vertical overlap with the edge's band
+    });
+}
+/**
+ * Pre-offset bow-control-point Y for a skip edge arcing over `blockers`: one
+ * full node-height of clearance above the topmost blocker's top edge. A
+ * cubic's apex only reaches part-way toward its control point (see
+ * `bowedCubicEdgePath` doc), so this generous margin is what actually keeps
+ * the visible curve clear of the box — verified numerically in
+ * `render-activities.test.ts`.
+ */
+function bowY(blockers) {
+    const topY = Math.min(...blockers.map((n) => n.y));
+    const clearance = Math.max(...blockers.map((n) => n.height));
+    return topY - clearance;
+}
+/**
+ * Extra top padding (px) a network-view canvas must add so skip-edge bows
+ * (see `blockingNodes`/`bowY` above) never draw above the SVG's y=0 and get
+ * clipped. `oyBase` is the canvas's Y offset *before* this padding — the
+ * historical `-bounds.y + N_PAD + titleH` both hosts compute — since a bow
+ * near the topmost row can reach above the diagram's own node bounds.
+ * Callers add the returned value to both `oyBase` and the canvas height.
+ */
+export function computeNetworkTopPad(layout, oyBase) {
+    const nodeMap = new Map(layout.nodes.map((n) => [n.id, n]));
+    let pad = 0;
+    for (const e of layout.edges) {
+        const s = nodeMap.get(e.sourceId);
+        const t = nodeMap.get(e.targetId);
+        if (!s || !t)
+            continue;
+        const blockers = blockingNodes(layout.nodes, s, t);
+        if (blockers.length === 0)
+            continue;
+        const shortfall = -(oyBase + bowY(blockers));
+        if (shortfall > pad)
+            pad = shortfall;
+    }
+    return pad;
+}
 function activityNodeSvg(n, x, y, isCritical, isMilestone, durLabel) {
     const cls = `diagram-node act-node ${isCritical ? 'critical-node' : ''} ${isMilestone ? 'milestone-node' : ''}`.trim();
     const specs = layoutCenteredEntityText({
@@ -92,7 +154,11 @@ export function renderActivitiesNetworkBody(layout, cpm, ox, oy, curvature, entr
         const ty = t.y + oy + t.height / 2;
         const cls = e.isCritical ? 'diagram-edge critical-edge' : 'diagram-edge';
         const marker = `url(#${e.isCritical ? 'arrow-crit' : 'arrow'})`;
-        return `<path d="${horizontalCubicEdgePath(sx, sy, tx, ty, curvature, entryCurvature)}" class="${cls}" marker-end="${marker}"/>`;
+        const blockers = blockingNodes(layout.nodes, s, t);
+        const d = blockers.length > 0
+            ? bowedCubicEdgePath(sx, sy, tx, ty, bowY(blockers) + oy, curvature)
+            : horizontalCubicEdgePath(sx, sy, tx, ty, curvature, entryCurvature);
+        return `<path d="${d}" class="${cls}" marker-end="${marker}"/>`;
     })
         .join('\n');
     const nodeSvg = layout.nodes
@@ -142,10 +208,12 @@ export function renderActivitiesSvg(doc, options = {}) {
     }
     const cpm = computeCpm(renderDoc.activities ?? []);
     const titleH = title ? 24 : 0;
+    const oyBase = -layout.bounds.y + N_PAD + titleH;
+    const topPad = computeNetworkTopPad(layout, oyBase);
     const w = layout.bounds.width + N_PAD * 2;
-    const h = layout.bounds.height + N_PAD * 2 + titleH;
+    const h = layout.bounds.height + N_PAD * 2 + titleH + topPad;
     const ox = -layout.bounds.x + N_PAD;
-    const oy = -layout.bounds.y + N_PAD + titleH;
+    const oy = oyBase + topPad;
     const body = renderActivitiesNetworkBody(layout, cpm, ox, oy, curvature, entryCurvature);
     const titleSvg = title
         ? `<text class="text-header" x="${N_PAD}" y="${N_PAD - 6}">${escXml(title)}</text>`

package/dist/webview/render-blocks.d.ts

@@ -1,4 +1,4 @@
-import type { BlocksFile, BlocksLayout, BlocksLayoutOptions } from '../blocks/types.js';
+import type { BlocksFile, BlocksLayout, BlocksLayoutOptions, GridFile, GridLayout, GridLayoutOptions } from '../blocks/types.js';
 import { type NodeSizePreset } from '../node-size-presets.js';
 import { type ThemeId } from '../theme/index.js';
 export interface RenderBlocksOptions {
@@ -29,3 +29,25 @@ export declare function renderBlocksLayoutSvg(layout: BlocksLayout, options?: Re
  * with the shared theme CSS embedded so the output is self-contained.
  */
 export declare function renderBlocksSvg(doc: BlocksFile, options?: RenderBlocksOptions): string;
+/**
+ * Emit the grid body (headers, cells, grid lines) at the given origin offset.
+ * Shared by the host-neutral wrapper below; VS Code's blocks preview wraps
+ * this the same way it wraps {@link renderBlocksLayoutSvg} for the tree form.
+ */
+export declare function renderGridBody(layout: GridLayout, ox: number, oy: number): string;
+export interface RenderGridLayoutOptions {
+    /** Extra vertical space reserved at the top of the canvas (e.g. for a title block). */
+    topInset?: number;
+    /** Raw SVG injected immediately after the opening tag — a header line or a full title block. */
+    title?: string;
+    /** When set, the theme CSS is embedded as `<style>` so the SVG is self-contained. */
+    embedCssTheme?: ThemeId;
+}
+/** The single grid (matrix subset) SVG emitter shared by every host. */
+export declare function renderGridLayoutSvg(layout: GridLayout, options?: RenderGridLayoutOptions): string;
+export interface RenderGridOptions {
+    title?: string;
+    layoutOptions?: GridLayoutOptions;
+}
+/** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
+export declare function renderGridSvg(doc: GridFile, options?: RenderGridOptions): string;

package/dist/webview/render-blocks.js

@@ -12,10 +12,10 @@
  * the shared theme CSS embedded in a `<style>` element and a simple optional
  * title `<text>`.
  */
-import { layoutNestedBlocks } from '../blocks/layout.js';
+import { layoutNestedBlocks, layoutGrid } from '../blocks/layout.js';
 import { parseNodeSizePreset, resolveBlocksLeafSize } from '../node-size-presets.js';
 import { generateSvgEmbedCss } from '../theme/index.js';
-import { emitCenteredTextSvg, layoutHeaderBlockText, layoutLeafBlockText, } from './entity-text-layout.js';
+import { CHAR_W_PRIMARY, emitCenteredTextSvg, layoutHeaderBlockText, layoutLeafBlockText, maxCharsForInnerWidth, wrapWords, } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 import { ENTITY_NODE_RX } from './notation-style.js';
 const PAD = 24;
@@ -105,3 +105,101 @@ export function renderBlocksSvg(doc, options = {}) {
         : '';
     return renderBlocksLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
 }
+/**
+ * Matrix subset (08-blocks.md §4a) — first cut: a single-layer rectangular
+ * `grid:` document (the RACI-style matrix case) rendered as a plain
+ * HTML/CSS-table-like SVG grid. Layers, arbitrary
+ * (non-rectangular) cell sets, and nested sub-grids belong to the general
+ * layered-grid superset, which is still in design upstream (methodology) and
+ * out of scope here — see 08-blocks.md §4a / §8.
+ */
+const GRID_CELL_PAD_X = 8;
+const GRID_LINE_HEIGHT = 15;
+const GRID_EMBED_CSS = `
+.blocks-grid-border { fill: none; stroke: var(--ts-border, #cbd5e1); }`;
+function centeredGridCellTextSvg(lines, cls, cx, cellTop, cellHeight) {
+    const ls = lines.length > 0 ? lines : [''];
+    const firstY = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * GRID_LINE_HEIGHT;
+    const tspans = ls
+        .map((ln, i) => `<tspan x="${cx}" y="${firstY + i * GRID_LINE_HEIGHT}">${escXml(ln)}</tspan>`)
+        .join('');
+    return `<text class="${cls}" text-anchor="middle" dominant-baseline="central">${tspans}</text>`;
+}
+/**
+ * Emit the grid body (headers, cells, grid lines) at the given origin offset.
+ * Shared by the host-neutral wrapper below; VS Code's blocks preview wraps
+ * this the same way it wraps {@link renderBlocksLayoutSvg} for the tree form.
+ */
+export function renderGridBody(layout, ox, oy) {
+    const tw = layout.bounds.width;
+    const th = layout.bounds.height;
+    const parts = [];
+    parts.push(`<rect class="diagram-node level-0" x="${ox}" y="${oy}" width="${tw}" height="${th}" stroke="none"/>`);
+    // Corner cell (above the row headers, left of the column headers).
+    parts.push(`<rect class="diagram-node level-1" x="${ox}" y="${oy}" width="${layout.rowHeaderWidth}" height="${layout.headerHeight}" stroke="none"/>`);
+    for (const col of layout.columns) {
+        const x = col.x + ox;
+        parts.push(`<rect class="diagram-node level-1" x="${x}" y="${oy}" width="${col.width}" height="${layout.headerHeight}" stroke="none"/>`);
+        const maxChars = maxCharsForInnerWidth(col.width - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+        const lines = wrapWords(col.name, maxChars, 2);
+        parts.push(centeredGridCellTextSvg(lines, 'text-header', x + col.width / 2, oy, layout.headerHeight));
+    }
+    for (const row of layout.rows) {
+        const y = row.y + oy;
+        parts.push(`<rect class="diagram-node level-2" x="${ox}" y="${y}" width="${layout.rowHeaderWidth}" height="${row.height}" stroke="none"/>`);
+        const maxChars = maxCharsForInnerWidth(layout.rowHeaderWidth - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+        const lines = wrapWords(row.name, maxChars, 2);
+        parts.push(centeredGridCellTextSvg(lines, 'text-primary', ox + layout.rowHeaderWidth / 2, y, row.height));
+    }
+    for (const cell of layout.cells) {
+        if (cell.value === undefined)
+            continue;
+        const cx = cell.x + ox + cell.width / 2;
+        const cy = cell.y + oy + cell.height / 2;
+        parts.push(`<text class="text-secondary" x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="central">${escXml(cell.value)}</text>`);
+    }
+    const gridX1 = ox;
+    const gridX2 = ox + tw;
+    const gridY1 = oy;
+    const gridY2 = oy + th;
+    const headerBottomY = oy + layout.headerHeight;
+    parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${headerBottomY}" x2="${gridX2}" y2="${headerBottomY}"/>`);
+    for (const row of layout.rows) {
+        const rowBottomY = oy + row.y + row.height;
+        parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${rowBottomY}" x2="${gridX2}" y2="${rowBottomY}"/>`);
+    }
+    const rowHeaderLineX = ox + layout.rowHeaderWidth;
+    parts.push(`<line class="diagram-edge" x1="${rowHeaderLineX}" y1="${gridY1}" x2="${rowHeaderLineX}" y2="${gridY2}"/>`);
+    for (const col of layout.columns) {
+        const colLineX = ox + col.x + col.width;
+        parts.push(`<line class="diagram-edge" x1="${colLineX}" y1="${gridY1}" x2="${colLineX}" y2="${gridY2}"/>`);
+    }
+    parts.push(`<rect class="blocks-grid-border" x="${ox}" y="${oy}" width="${tw}" height="${th}"/>`);
+    return parts.join('\n');
+}
+/** The single grid (matrix subset) SVG emitter shared by every host. */
+export function renderGridLayoutSvg(layout, options = {}) {
+    const { topInset = 0, title = '', embedCssTheme } = options;
+    const w = layout.bounds.width + PAD * 2;
+    const h = layout.bounds.height + PAD * 2 + topInset;
+    const ox = PAD;
+    const oy = PAD + topInset;
+    const body = renderGridBody(layout, ox, oy);
+    const styleLine = embedCssTheme ? `\n<style>${generateSvgEmbedCss(embedCssTheme)}${GRID_EMBED_CSS}</style>` : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${styleLine}
+${title}
+${body}
+</svg>`;
+}
+/** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
+export function renderGridSvg(doc, options = {}) {
+    const { title = '', layoutOptions } = options;
+    const layout = layoutGrid(doc, layoutOptions);
+    if (layout.columns.length === 0 || layout.rows.length === 0) {
+        return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
+    }
+    const titleSvg = title
+        ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Nested Blocks — ${title}`)}</text>`
+        : '';
+    return renderGridLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.8.13",
+  "version": "1.8.19",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/activities/validate.ts

@@ -19,7 +19,15 @@ export function validateActivities(input: unknown): ActivityValidationResult {
 
   const raw = input as Record<string, unknown>;
 
-  // ACT-001: notation must be "action"
+  // ACT-001: notation must be "action". ACT-020 is deliberately NOT ported
+  // here (DSM's api02/internal/importer/activities.go ValidateActivities
+  // still accepts the pre-2026-06-25 "activities" notation/root-key alias
+  // with a warning) — PR #320 ("drop deprecated notation aliases
+  // fgca/fga/activities/activity-card") already removed that leniency from
+  // this validator on purpose, with tests asserting it is "no longer
+  // accepted". Re-introducing it would reverse a deliberate, shipped
+  // decision, not fill a gap; flagged in the PR for a call rather than
+  // silently reversed either way.
   if (raw.notation === undefined) {
     errors.push({ code: 'ACT-001', message: 'notation field is required' });
     return { valid: false, errors, warnings };

package/src/blocks/index.ts

@@ -5,13 +5,27 @@ export type {
   BlocksLayoutOptions,
   LaidOutBlock,
   BlocksLayout,
+  GridColumn,
+  GridRow,
+  GridHeader,
+  GridFile,
+  GridLayoutOptions,
+  LaidOutGridColumn,
+  LaidOutGridRow,
+  LaidOutGridCell,
+  GridLayout,
 } from './types.js';
 
-export { validateNestedBlocks, isWellFormedBlock } from './validate.js';
+export { validateNestedBlocks, validateGrid, validateBlocks, isWellFormedBlock } from './validate.js';
 export type {
   ValidationError as BlocksValidationError,
   ValidationWarning as BlocksValidationWarning,
   ValidationResult as BlocksValidationResult,
+  GridRule,
+  ValidateGridOptions,
+  ValidateBlocksOptions,
 } from './validate.js';
 
-export { layoutNestedBlocks, iterateBlocks } from './layout.js';
+export { layoutNestedBlocks, layoutGrid, iterateBlocks } from './layout.js';
+
+export { GRID_TEMPLATE_RULES } from './templates/index.js';

package/src/blocks/layout.ts

@@ -3,7 +3,13 @@ import type {
   BlocksFile,
   BlocksLayout,
   BlocksLayoutOptions,
+  GridFile,
+  GridLayout,
+  GridLayoutOptions,
   LaidOutBlock,
+  LaidOutGridCell,
+  LaidOutGridColumn,
+  LaidOutGridRow,
 } from './types.js';
 import { ENTITY_NODE_SIZE } from '../node-size-presets.js';
 
@@ -16,6 +22,13 @@ const DEFAULTS: Required<BlocksLayoutOptions> = {
   topLevelGap: 24,
 };
 
+const GRID_DEFAULTS: Required<GridLayoutOptions> = {
+  columnWidth: 130,
+  rowHeight: 44,
+  rowHeaderWidth: 200,
+  headerHeight: 56,
+};
+
 interface MeasuredBlock {
   width: number;
   height: number;
@@ -185,3 +198,60 @@ export function* iterateBlocks(layout: BlocksLayout): Iterable<LaidOutBlock> {
   }
   for (const b of layout.blocks) yield* walk(b);
 }
+
+/**
+ * Matrix subset (08-blocks.md §4a): lay out a `grid:` root document as a
+ * single-layer rectangular table — a row-header column, a column-header row,
+ * and one cell per `(row, column)` pair. Assumes the document is already
+ * well-formed ({@link validateGrid}); callers validate first.
+ */
+export function layoutGrid(file: GridFile, options?: GridLayoutOptions): GridLayout {
+  const opts = { ...GRID_DEFAULTS, ...(options ?? {}) };
+  const grid = file?.grid;
+  const rawColumns = Array.isArray(grid?.columns) ? grid.columns : [];
+  const rawRows = Array.isArray(grid?.rows) ? grid.rows : [];
+
+  const columns: LaidOutGridColumn[] = rawColumns.map((c, i) => ({
+    id: c.id,
+    name: c.name,
+    x: opts.rowHeaderWidth + i * opts.columnWidth,
+    width: opts.columnWidth,
+  }));
+
+  const rows: LaidOutGridRow[] = rawRows.map((r, i) => ({
+    id: r.id,
+    name: r.name,
+    y: opts.headerHeight + i * opts.rowHeight,
+    height: opts.rowHeight,
+  }));
+
+  const cells: LaidOutGridCell[] = [];
+  for (let ri = 0; ri < rawRows.length; ri++) {
+    const row = rawRows[ri];
+    for (let ci = 0; ci < rawColumns.length; ci++) {
+      const col = rawColumns[ci];
+      const raw = row.assign?.[col.id];
+      cells.push({
+        rowId: row.id,
+        colId: col.id,
+        x: columns[ci].x,
+        y: rows[ri].y,
+        width: opts.columnWidth,
+        height: opts.rowHeight,
+        value: raw === undefined ? undefined : String(raw),
+      });
+    }
+  }
+
+  const width = opts.rowHeaderWidth + rawColumns.length * opts.columnWidth;
+  const height = opts.headerHeight + rawRows.length * opts.rowHeight;
+
+  return {
+    bounds: { x: 0, y: 0, width, height },
+    rowHeaderWidth: opts.rowHeaderWidth,
+    headerHeight: opts.headerHeight,
+    columns,
+    rows,
+    cells,
+  };
+}

package/src/blocks/templates/index.ts

@@ -0,0 +1,13 @@
+import type { GridRule } from '../validate.js';
+import { RACI_GRID_RULES } from './raci.js';
+
+/**
+ * Closed registry of built-in grid templates (§6a): each entry is a template
+ * name (as passed to `--template <name>`) mapped to its `GridRule`s. Adding a
+ * new template means adding one rule module + one entry here — the same
+ * shape as adding a new notation validator, not a plugin/config-loading
+ * mechanism (deliberately out of scope — see the design note on `RACI-001`).
+ */
+export const GRID_TEMPLATE_RULES: Record<string, GridRule[]> = {
+  raci: RACI_GRID_RULES,
+};

package/src/blocks/templates/raci.ts

@@ -0,0 +1,28 @@
+import type { GridRule } from '../validate.js';
+
+/**
+ * RACI-as-matrix template (methodology `templates/raci/`), built on the
+ * `blocks` matrix subset (08-blocks.md §4a). The base grid validator does not
+ * fix a cell-value vocabulary, so this invariant — exactly one Accountable
+ * owner per row — lives here, not in `validateGrid` (see §6a).
+ */
+export const raciExactlyOneAccountableRule: GridRule = {
+  ruleId: 'RACI-001',
+  severity: 'error',
+  check(grid) {
+    const findings: Array<{ message: string; path?: string }> = [];
+    grid.rows.forEach((row, i) => {
+      const accountableCount = Object.values(row.assign ?? {}).filter((v) => v === 'A').length;
+      if (accountableCount !== 1) {
+        findings.push({
+          message:
+            `Row "${row.name}" (${row.id}) must have exactly one column assigned "A" (Accountable); found ${accountableCount}`,
+          path: `grid.rows[${i}]`,
+        });
+      }
+    });
+    return findings;
+  },
+};
+
+export const RACI_GRID_RULES: GridRule[] = [raciExactlyOneAccountableRule];

package/src/blocks/types.ts

@@ -21,6 +21,73 @@ export interface BlocksFile {
   nested_blocks: NestedBlocksHeader;
 }
 
+export interface GridColumn {
+  id: string;
+  name: string;
+}
+
+export interface GridRow {
+  id: string;
+  name: string;
+  assign?: Record<string, unknown>;
+}
+
+export interface GridHeader {
+  columns: GridColumn[];
+  rows: GridRow[];
+}
+
+export interface GridFile {
+  notation: string;
+  spec_version?: string;
+  grid: GridHeader;
+}
+
+export interface GridLayoutOptions {
+  /** Width of each data column (px). */
+  columnWidth?: number;
+  /** Height of each data row (px). */
+  rowHeight?: number;
+  /** Width of the row-header column carrying each row's name (px). */
+  rowHeaderWidth?: number;
+  /** Height of the column-header row carrying each column's name (px). */
+  headerHeight?: number;
+}
+
+export interface LaidOutGridColumn {
+  id: string;
+  name: string;
+  x: number;
+  width: number;
+}
+
+export interface LaidOutGridRow {
+  id: string;
+  name: string;
+  y: number;
+  height: number;
+}
+
+export interface LaidOutGridCell {
+  rowId: string;
+  colId: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** The cell's `assign` value, stringified; omitted (blank) when unassigned. */
+  value?: string;
+}
+
+export interface GridLayout {
+  bounds: LayoutBounds;
+  rowHeaderWidth: number;
+  headerHeight: number;
+  columns: LaidOutGridColumn[];
+  rows: LaidOutGridRow[];
+  cells: LaidOutGridCell[];
+}
+
 export interface BlocksLayoutOptions {
   /** Width of a leaf block (a block with no children). */
   leafWidth?: number;