@transitrix/diagrams 1.8.1 → 1.8.3

package/dist/webview/entity-text-layout.d.ts

@@ -6,6 +6,14 @@
  * Capability Map renderers.
  */
 export declare const TEXT_MARGIN_X = 8;
+/**
+ * Minimum reserved vertical padding (px) between the box's top/bottom edge and
+ * the nearest line's outer extent. Always enforced — see
+ * {@link layoutCenteredEntityText}'s adaptive line-count reduction, which
+ * trades name-line count for this padding rather than letting text touch or
+ * cross the box border.
+ */
+export declare const TEXT_MARGIN_Y = 4;
 /** Approximate character width (px) at text-primary size (12px/600). */
 export declare const CHAR_W_PRIMARY = 7;
 /** Approximate character width (px) at text-id size (10px/600). */
@@ -18,10 +26,15 @@ export declare const LINE_H_PRIMARY = 14;
 export declare const LINE_H_SECONDARY = 14;
 /** Vertical advance between id line centres (text-id). */
 export declare const LINE_H_ID = 12;
-/** Gap between the name block and the id block in leaf-style layouts. */
+/**
+ * Gap between the name block and the id block in leaf-style layouts — used as
+ * a direct centre-to-centre distance there, so keep it >= ~11px (half of
+ * text-primary's 12px font + half of text-id's 10px font) to avoid the
+ * overlap regressed in #419. Do not tighten without re-checking that test.
+ */
 export declare const NAME_ID_GAP = 14;
 /** Gap between stacked row groups (name → type → id). */
-export declare const ROW_GROUP_GAP = 9;
+export declare const ROW_GROUP_GAP = 4;
 export declare function maxCharsForInnerWidth(innerWidth: number, charWidth: number): number;
 /** Word-wrap `text` to at most `maxLines` lines of `maxChars` each. */
 export declare function wrapWords(text: string, maxChars: number, maxLines: number): string[];
@@ -55,10 +68,20 @@ export interface LayoutCenteredEntityOptions {
     nameMaxLines?: number;
     idMaxLines?: number;
     marginX?: number;
+    marginY?: number;
 }
 /**
  * Layout centred entity text (name → optional type → id) inside a fixed box.
  * Returns absolute SVG y-positions (line centres) for each rendered row.
+ *
+ * Guarantees, in order of priority:
+ *   1. Content never crosses the box's top/bottom edge.
+ *   2. At least `marginY` (default {@link TEXT_MARGIN_Y}) of padding is kept
+ *      above the first line's glyphs and below the last line's glyphs.
+ *   3. The name gets as many lines as `nameMaxLines` allows (2 by default)
+ *      when the box is tall enough; on short/compact boxes (e.g. with a type
+ *      row present) it degrades to fewer name lines — trading line count,
+ *      not padding — rather than letting text overflow.
  */
 export declare function layoutCenteredEntityText(opts: LayoutCenteredEntityOptions): TextLineSpec[];
 /** Emit centred `<text>` elements from {@link layoutCenteredEntityText} specs. */
@@ -73,7 +96,12 @@ export interface LayoutLeafBlockTextOptions {
     nameMaxLines?: number;
     marginX?: number;
 }
-/** Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred. */
+/**
+ * Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred.
+ * Degrades name line count (never below 1) when the box is too short to hold
+ * the requested max plus {@link TEXT_MARGIN_Y} padding on both edges, so text
+ * never crosses the box border.
+ */
 export declare function layoutLeafBlockText(opts: LayoutLeafBlockTextOptions): TextLineSpec[];
 export interface LayoutHeaderBlockTextOptions {
     boxX: number;

package/dist/webview/entity-text-layout.js

@@ -6,6 +6,14 @@
  * Capability Map renderers.
  */
 export const TEXT_MARGIN_X = 8;
+/**
+ * Minimum reserved vertical padding (px) between the box's top/bottom edge and
+ * the nearest line's outer extent. Always enforced — see
+ * {@link layoutCenteredEntityText}'s adaptive line-count reduction, which
+ * trades name-line count for this padding rather than letting text touch or
+ * cross the box border.
+ */
+export const TEXT_MARGIN_Y = 4;
 /** Approximate character width (px) at text-primary size (12px/600). */
 export const CHAR_W_PRIMARY = 7;
 /** Approximate character width (px) at text-id size (10px/600). */
@@ -18,10 +26,15 @@ export const LINE_H_PRIMARY = 14;
 export const LINE_H_SECONDARY = 14;
 /** Vertical advance between id line centres (text-id). */
 export const LINE_H_ID = 12;
-/** Gap between the name block and the id block in leaf-style layouts. */
+/**
+ * Gap between the name block and the id block in leaf-style layouts — used as
+ * a direct centre-to-centre distance there, so keep it >= ~11px (half of
+ * text-primary's 12px font + half of text-id's 10px font) to avoid the
+ * overlap regressed in #419. Do not tighten without re-checking that test.
+ */
 export const NAME_ID_GAP = 14;
 /** Gap between stacked row groups (name → type → id). */
-export const ROW_GROUP_GAP = 9;
+export const ROW_GROUP_GAP = 4;
 export function maxCharsForInnerWidth(innerWidth, charWidth) {
     return Math.max(4, Math.floor(Math.max(0, innerWidth) / charWidth));
 }
@@ -136,69 +149,100 @@ export function truncateId(id, maxChars) {
     const sepIdx = Math.max(cut.lastIndexOf('_'), cut.lastIndexOf('-'));
     return `${sepIdx > safeMax / 3 ? cut.slice(0, sepIdx) : cut}…`;
 }
-function totalVerticalSpan(groups) {
-    let span = 0;
-    for (let i = 0; i < groups.length; i++) {
-        const g = groups[i];
-        if (g.lines.length > 1)
-            span += (g.lines.length - 1) * g.lineHeight;
-        if (i < groups.length - 1)
-            span += g.gapAfter;
+/**
+ * Half-extent (px) of rendered glyphs around their centre y — approximately
+ * font-size / 2, the same heuristic the #419 non-overlap regression test
+ * uses. Used only to keep the *outermost* line's visual extent (not just its
+ * centre) inside the box when computing edge padding; inter-line spacing
+ * between adjacent rows is governed separately by the LINE_H_ constants,
+ * NAME_ID_GAP and ROW_GROUP_GAP, which already keep centres far enough apart
+ * to avoid overlap.
+ */
+const HALF_EXTENT_PRIMARY = 6; // text-primary, 12px font
+const HALF_EXTENT_ID = 5; // text-id, 10px font
+/** Place `groups`' lines starting at `startY`, advancing by each line's own height and gap. */
+function placeLines(groups, startY) {
+    const out = [];
+    let y = startY;
+    for (let gi = 0; gi < groups.length; gi++) {
+        const g = groups[gi];
+        for (let li = 0; li < g.lines.length; li++) {
+            out.push({ cls: g.cls, text: g.lines[li], y });
+            y += g.lineHeight;
+        }
+        if (gi < groups.length - 1)
+            y += g.gapAfter;
     }
-    return span;
+    return out;
+}
+/** Centre-to-centre distance from the first to the last placed line. */
+function centerSpan(groups) {
+    const ys = placeLines(groups, 0).map((s) => s.y);
+    return ys[ys.length - 1] - ys[0];
 }
 /**
  * Layout centred entity text (name → optional type → id) inside a fixed box.
  * Returns absolute SVG y-positions (line centres) for each rendered row.
+ *
+ * Guarantees, in order of priority:
+ *   1. Content never crosses the box's top/bottom edge.
+ *   2. At least `marginY` (default {@link TEXT_MARGIN_Y}) of padding is kept
+ *      above the first line's glyphs and below the last line's glyphs.
+ *   3. The name gets as many lines as `nameMaxLines` allows (2 by default)
+ *      when the box is tall enough; on short/compact boxes (e.g. with a type
+ *      row present) it degrades to fewer name lines — trading line count,
+ *      not padding — rather than letting text overflow.
  */
 export function layoutCenteredEntityText(opts) {
     const marginX = opts.marginX ?? TEXT_MARGIN_X;
+    const marginY = opts.marginY ?? TEXT_MARGIN_Y;
     const innerW = Math.max(0, opts.boxWidth - marginX * 2);
-    const cx = opts.boxX + opts.boxWidth / 2;
     const maxCharsName = maxCharsForInnerWidth(innerW, CHAR_W_PRIMARY);
     const maxCharsType = maxCharsForInnerWidth(innerW, CHAR_W_SECONDARY);
     const maxCharsId = maxCharsForInnerWidth(innerW, CHAR_W_ID);
-    const nameLines = wrapWords(opts.name, maxCharsName, opts.nameMaxLines ?? 2);
     const typeLine = opts.type?.trim() ? truncateLine(opts.type, maxCharsType) : undefined;
     const idMaxLines = opts.idMaxLines ?? 1;
     const idLines = idMaxLines <= 1 ? [truncateId(opts.id, maxCharsId)] : wrapId(opts.id, maxCharsId, idMaxLines);
-    const groups = [
-        {
-            cls: 'text-primary',
-            lines: nameLines,
-            lineHeight: LINE_H_PRIMARY,
-            gapAfter: typeLine ? ROW_GROUP_GAP : NAME_ID_GAP,
-        },
-    ];
-    if (typeLine) {
+    function buildGroups(nameLines) {
+        const groups = [
+            {
+                cls: 'text-primary',
+                lines: nameLines,
+                lineHeight: LINE_H_PRIMARY,
+                gapAfter: typeLine ? ROW_GROUP_GAP : NAME_ID_GAP,
+            },
+        ];
+        if (typeLine) {
+            groups.push({
+                cls: 'text-secondary',
+                lines: [typeLine],
+                lineHeight: LINE_H_SECONDARY,
+                gapAfter: NAME_ID_GAP,
+            });
+        }
         groups.push({
-            cls: 'text-secondary',
-            lines: [typeLine],
-            lineHeight: LINE_H_SECONDARY,
-            gapAfter: NAME_ID_GAP,
+            cls: 'text-id',
+            lines: idLines,
+            lineHeight: LINE_H_ID,
+            gapAfter: 0,
         });
+        return groups;
     }
-    groups.push({
-        cls: 'text-id',
-        lines: idLines,
-        lineHeight: LINE_H_ID,
-        gapAfter: 0,
-    });
-    const span = totalVerticalSpan(groups);
-    const firstY = Math.round(opts.boxY + (opts.boxHeight - span) / 2);
-    const out = [];
-    let y = firstY;
-    for (let gi = 0; gi < groups.length; gi++) {
-        const g = groups[gi];
-        for (let li = 0; li < g.lines.length; li++) {
-            out.push({ cls: g.cls, text: g.lines[li], y });
-            if (li < g.lines.length - 1)
-                y += g.lineHeight;
-        }
-        if (gi < groups.length - 1)
-            y += g.gapAfter;
+    // groups[0] is always the name (text-primary) and the last group is always
+    // the id (text-id), so the edge-padding half-extents below are fixed.
+    const requestedNameMaxLines = Math.max(1, opts.nameMaxLines ?? 2);
+    const availableHeight = Math.max(0, opts.boxHeight - marginY * 2);
+    let nameLines = wrapWords(opts.name, maxCharsName, requestedNameMaxLines);
+    let groups = buildGroups(nameLines);
+    let contentSpan = centerSpan(groups) + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    for (let cap = requestedNameMaxLines - 1; cap >= 1 && contentSpan > availableHeight; cap--) {
+        nameLines = wrapWords(opts.name, maxCharsName, cap);
+        groups = buildGroups(nameLines);
+        contentSpan = centerSpan(groups) + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
     }
-    return out;
+    const margin = Math.max(0, (opts.boxHeight - contentSpan) / 2);
+    const firstY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
+    return placeLines(groups, firstY);
 }
 /** Emit centred `<text>` elements from {@link layoutCenteredEntityText} specs. */
 export function emitCenteredTextSvg(specs, centerX, esc) {
@@ -210,28 +254,48 @@ export function emitCenteredTextSvg(specs, centerX, esc) {
     })
         .join('\n');
 }
-/** Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred. */
+/**
+ * Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred.
+ * Degrades name line count (never below 1) when the box is too short to hold
+ * the requested max plus {@link TEXT_MARGIN_Y} padding on both edges, so text
+ * never crosses the box border.
+ */
 export function layoutLeafBlockText(opts) {
     const marginX = opts.marginX ?? TEXT_MARGIN_X;
     const innerW = Math.max(0, opts.boxWidth - marginX * 2);
     const maxCharsName = maxCharsForInnerWidth(innerW, CHAR_W_PRIMARY);
     const maxCharsId = maxCharsForInnerWidth(innerW, CHAR_W_ID);
-    const nameLines = wrapWords(opts.name, maxCharsName, opts.nameMaxLines ?? 3);
     const idLines = wrapId(opts.id, maxCharsId, 2);
-    const nameSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
-    const idSpan = (idLines.length - 1) * LINE_H_ID;
-    const totalSpan = nameSpan + NAME_ID_GAP + idSpan;
-    const firstY = Math.round(opts.boxY + (opts.boxHeight - totalSpan) / 2);
+    const idCenterSpan = (idLines.length - 1) * LINE_H_ID;
+    const requestedNameMaxLines = Math.max(1, opts.nameMaxLines ?? 3);
+    const availableHeight = Math.max(0, opts.boxHeight - TEXT_MARGIN_Y * 2);
+    let nameLines = wrapWords(opts.name, maxCharsName, requestedNameMaxLines);
+    let nameCenterSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+    let contentSpan = nameCenterSpan + NAME_ID_GAP + idCenterSpan + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    for (let cap = requestedNameMaxLines - 1; cap >= 1 && contentSpan > availableHeight; cap--) {
+        nameLines = wrapWords(opts.name, maxCharsName, cap);
+        nameCenterSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+        contentSpan = nameCenterSpan + NAME_ID_GAP + idCenterSpan + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    }
+    const margin = Math.max(0, (opts.boxHeight - contentSpan) / 2);
+    const firstY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
     const out = [];
     for (let i = 0; i < nameLines.length; i++) {
         out.push({ cls: 'text-primary', text: nameLines[i], y: firstY + i * LINE_H_PRIMARY });
     }
-    const idFirstY = firstY + nameSpan + NAME_ID_GAP;
+    const idFirstY = firstY + nameCenterSpan + NAME_ID_GAP;
     for (let i = 0; i < idLines.length; i++) {
         out.push({ cls: 'text-id', text: idLines[i], y: idFirstY + i * LINE_H_ID });
     }
     return out;
 }
+/**
+ * Direct centre-to-centre gap between the header's name and id lines.
+ * Safely above the ~11px non-overlap floor (half of text-primary's 12px font
+ * + half of text-id's 10px font, per the #419 regression) but tighter than
+ * {@link NAME_ID_GAP} to fit the compact header strip.
+ */
+const HEADER_NAME_ID_GAP = 12;
 /** Container header: single-line name + id stacked in the header strip. */
 export function layoutHeaderBlockText(opts) {
     const marginX = opts.marginX ?? TEXT_MARGIN_X;
@@ -240,11 +304,13 @@ export function layoutHeaderBlockText(opts) {
     const maxCharsId = maxCharsForInnerWidth(innerW, CHAR_W_ID);
     const nameText = truncateLine(opts.name, maxCharsName);
     const idText = truncateId(opts.id, maxCharsId);
-    const headerMid = opts.boxY + opts.headerHeight / 2;
-    const halfSpan = (LINE_H_PRIMARY + LINE_H_ID) / 4;
+    const contentSpan = HEADER_NAME_ID_GAP + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    const margin = Math.max(0, (opts.headerHeight - contentSpan) / 2);
+    const nameY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
+    const idY = nameY + HEADER_NAME_ID_GAP;
     return [
-        { cls: 'text-primary', text: nameText, y: Math.round(headerMid - halfSpan) },
-        { cls: 'text-id', text: idText, y: Math.round(headerMid + halfSpan) },
+        { cls: 'text-primary', text: nameText, y: nameY },
+        { cls: 'text-id', text: idText, y: idY },
     ];
 }
 /**

package/package.json

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

package/src/__tests__/node-size-presets.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  ACTION_NODE_SIZE,
+  BLOCKS_LEAF_SIZE,
+  CAPABILITY_MAP_NODE_SIZE,
+  DGCA_NODE_SIZE,
+  ENTITY_NODE_HEIGHT,
+  ENTITY_NODE_SIZE,
+  ENTITY_NODE_WIDTH,
+  GOALS_NODE_SIZE,
+  PROCESS_BLUEPRINT_SIZE,
+  resolveGoalsNodeSize,
+} from '../node-size-presets.js';
+
+describe('node-size-presets', () => {
+  it('uses shared width and height tiers for entity nodes', () => {
+    expect(ENTITY_NODE_WIDTH).toEqual({ compact: 200, normal: 250, wide: 320 });
+    expect(ENTITY_NODE_HEIGHT).toEqual({ compact: 72, normal: 80, wide: 96 });
+    expect(ENTITY_NODE_SIZE.normal).toEqual({ width: 250, height: 80 });
+    expect(ENTITY_NODE_SIZE.compact).toEqual({ width: 200, height: 72 });
+    expect(ENTITY_NODE_SIZE.wide).toEqual({ width: 320, height: 96 });
+  });
+
+  it('exposes the same entity sizes for every box-based notation', () => {
+    for (const table of [GOALS_NODE_SIZE, DGCA_NODE_SIZE, BLOCKS_LEAF_SIZE, ACTION_NODE_SIZE]) {
+      expect(table).toBe(ENTITY_NODE_SIZE);
+      expect(table.normal).toEqual(ENTITY_NODE_SIZE.normal);
+    }
+    expect(CAPABILITY_MAP_NODE_SIZE.normal).toEqual({
+      nodeWidth: ENTITY_NODE_WIDTH.normal,
+      nodeHeight: ENTITY_NODE_HEIGHT.normal,
+    });
+  });
+
+  it('scales wide above normal and compact below', () => {
+    expect(resolveGoalsNodeSize('wide').height).toBeGreaterThan(resolveGoalsNodeSize('normal').height);
+    expect(resolveGoalsNodeSize('compact').height).toBeLessThan(resolveGoalsNodeSize('normal').height);
+    expect(resolveGoalsNodeSize('wide').width).toBeGreaterThan(resolveGoalsNodeSize('normal').width);
+  });
+
+  it('scales process blueprint from the same tier ratios', () => {
+    expect(PROCESS_BLUEPRINT_SIZE.wide.stageColumnWidth).toBeGreaterThan(
+      PROCESS_BLUEPRINT_SIZE.normal.stageColumnWidth,
+    );
+    expect(PROCESS_BLUEPRINT_SIZE.compact.goalRowHeight).toBeLessThan(
+      PROCESS_BLUEPRINT_SIZE.normal.goalRowHeight,
+    );
+  });
+});

package/src/activities/layout.ts

@@ -1,7 +1,7 @@
 import type { ActivityDoc, Activity, ActivitiesLayout, ActivitiesLayoutOptions, LayoutNode, LayoutEdge } from './types.js';
 import { computeCpm } from './cpm.js';
 
-const DEFAULT_NODE_W = 200;
+const DEFAULT_NODE_W = 250;
 const DEFAULT_NODE_H = 80;
 const H_GAP = 80;
 const V_GAP = 24;

package/src/blocks/__tests__/layout.test.ts

@@ -118,8 +118,8 @@ describe('layoutNestedBlocks', () => {
       },
     });
     const a = layout.blocks[0];
-    expect(a.width).toBe(160);
-    expect(a.height).toBe(72);
+    expect(a.width).toBe(250);
+    expect(a.height).toBe(80);
   });
 
   it('honours custom layout options', () => {

package/src/blocks/layout.ts

@@ -5,12 +5,13 @@ import type {
   BlocksLayoutOptions,
   LaidOutBlock,
 } from './types.js';
+import { ENTITY_NODE_SIZE } from '../node-size-presets.js';
 
 const DEFAULTS: Required<BlocksLayoutOptions> = {
-  leafWidth: 160,
-  leafHeight: 72,
+  leafWidth: ENTITY_NODE_SIZE.normal.width,
+  leafHeight: ENTITY_NODE_SIZE.normal.height,
   padding: 12,
-  headerHeight: 28,
+  headerHeight: 32,
   childGap: 12,
   topLevelGap: 24,
 };

package/src/capability-map/dsm-layout.ts

@@ -2,7 +2,7 @@ import type { CapabilityMap, LayoutOptions, CapabilityMapLayout, LaidOutNode, La
 import { getLevel, getParentAddress } from './address.js';
 
 const DEFAULT_NODE_WIDTH = 250;
-const DEFAULT_NODE_HEIGHT = 64;
+const DEFAULT_NODE_HEIGHT = 80;
 const DEFAULT_RANK_SEP = 80;
 const DEFAULT_NODE_SEP = 24;
 /** Width of the virtual organisation-root node — narrower than a capability

package/src/capability-map/layout-tree.ts

@@ -1,7 +1,7 @@
 import type { CapabilityNode, CapabilityMapHeader } from './types.js';
 
 export const TREE_NODE_WIDTH = 250;
-export const TREE_NODE_HEIGHT = 64;
+export const TREE_NODE_HEIGHT = 80;
 /** Gap between sibling columns (node width + rank sep = 330px, matching DSM). */
 export const TREE_RANK_SEP = 80;
 /** Vertical gap between sibling nodes. */

package/src/fgca/preview-layout.ts

@@ -8,6 +8,7 @@
 // No React, no DOM, no vscode. Safe to call in Node.js or a test environment.
 
 import type { Scope } from '../scope.js';
+import { ENTITY_NODE_SIZE } from '../node-size-presets.js';
 
 export type FGCAPreviewColumn = 'driver' | 'goal' | 'change' | 'activity';
 
@@ -125,8 +126,8 @@ export interface FGCAPreviewLayout {
 
 // Default node + frame geometry. Inter-node gaps are user-configurable via
 // Inter-node gaps are user-configurable via spacing settings; node size uses presets.
-export const FGCA_NODE_W = 220;
-export const FGCA_NODE_H = 72;
+export const FGCA_NODE_W = ENTITY_NODE_SIZE.normal.width;
+export const FGCA_NODE_H = ENTITY_NODE_SIZE.normal.height;
 export const FGCA_HEADER_H = 32;
 export const FGCA_PAD = 20;
 export const FGCA_DEFAULT_COL_GAP = 160;