@diagrammo/dgmo 0.30.0 → 0.32.0

package/src/sequence/renderer.ts

@@ -4,7 +4,7 @@
 
 import * as d3Selection from 'd3-selection';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill } from '../palettes/color-utils';
+import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
 import {
   parseInlineMarkdown,
   truncateBareUrl,
@@ -2010,7 +2010,7 @@ export function renderSequenceDiagram(
     const fillColor = groupTagColor
       ? mix(
           groupTagColor,
-          isDark ? palette.surface : palette.bg,
+          themeBaseBg(palette, isDark),
           isDark ? 15 : 20
         )
       : isDark
@@ -2139,7 +2139,7 @@ export function renderSequenceDiagram(
       const pFill = effectiveTagColor
         ? mix(
             effectiveTagColor,
-            isDark ? palette.surface : palette.bg,
+            themeBaseBg(palette, isDark),
             isDark ? 30 : 40
           )
         : isDark
@@ -2507,7 +2507,7 @@ export function renderSequenceDiagram(
       .attr('y', y1)
       .attr('width', sActivationWidth)
       .attr('height', y2 - y1)
-      .attr('fill', isDark ? palette.surface : palette.bg);
+      .attr('fill', themeBaseBg(palette, isDark));
 
     // Canonical 25% tint via shapeFill() (or full intent when solid-fill is on).
     const actFill = shapeFill(palette, actBaseColor, isDark, { solid });

package/src/sitemap/parser.ts

@@ -8,6 +8,7 @@ import {
   descriptionBareRemovedMessage,
   formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
   suggest,
@@ -165,12 +166,7 @@ export function parseSitemap(
     error: null,
   };
 
-  const fail = (line: number, message: string): ParsedSitemap => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   const pushError = (line: number, message: string): void => {
     const diag = makeDgmoError(line, message);
@@ -324,7 +320,12 @@ export function parseSitemap(
       const indent = measureIndent(line);
       if (indent > 0) {
         const { text: cleanEntry, isDefault } = stripDefaultModifier(trimmed);
-        const { label, color } = extractColor(cleanEntry, palette);
+        const { label, color } = extractColor(
+          cleanEntry,
+          palette,
+          result.diagnostics,
+          lineNumber
+        );
         // Bare value (no explicit color) → keep it; finalized below.
         currentTagGroup.entries.push({
           value: label,

package/src/sitemap/renderer.ts

@@ -6,7 +6,7 @@ import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill } from '../palettes/color-utils';
+import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
 import type { ParsedSitemap } from './types';
 import type { SitemapLayoutResult, SitemapLegendGroup } from './layout';
 import { renderInlineText } from '../utils/inline-markdown';
@@ -23,6 +23,7 @@ import {
 import { renderIntegratedLegend } from '../utils/legend-integration';
 import { getMaxLegendReservedHeight } from '../utils/legend-layout';
 import { ScaleContext } from '../utils/scaling';
+import { renderNodeCard } from '../utils/card';
 
 // ============================================================
 // Constants
@@ -32,26 +33,28 @@ const DIAGRAM_PADDING = 20;
 const MAX_SCALE = 3;
 import { TITLE_FONT_SIZE, TITLE_FONT_WEIGHT } from '../utils/title-constants';
 const TITLE_HEIGHT = 30;
-const LABEL_FONT_SIZE = 13;
-const META_FONT_SIZE = 11;
-const META_LINE_HEIGHT = 16;
-const HEADER_HEIGHT = 28;
-const SEPARATOR_GAP = 6;
-const EDGE_STROKE_WIDTH = 1.5;
-const NODE_STROKE_WIDTH = 1.5;
-const CARD_RADIUS = 6;
-const CONTAINER_RADIUS = 8;
-const CONTAINER_LABEL_FONT_SIZE = 13;
-const CONTAINER_META_FONT_SIZE = 11;
-const CONTAINER_META_LINE_HEIGHT = 16;
-const CONTAINER_HEADER_HEIGHT = 28;
+// Shared card / group / collapse constants (Story 111.1). sitemap matches every
+// convention default, so it imports the full set.
+import {
+  LABEL_FONT_SIZE,
+  META_FONT_SIZE,
+  META_LINE_HEIGHT,
+  HEADER_HEIGHT,
+  SEPARATOR_GAP,
+  EDGE_STROKE_WIDTH,
+  NODE_STROKE_WIDTH,
+  CARD_RADIUS,
+  CONTAINER_RADIUS,
+  CONTAINER_LABEL_FONT_SIZE,
+  CONTAINER_META_FONT_SIZE,
+  CONTAINER_META_LINE_HEIGHT,
+  CONTAINER_HEADER_HEIGHT,
+  COLLAPSE_BAR_HEIGHT,
+} from '../utils/visual-conventions';
 const ARROWHEAD_W = 10;
 const ARROWHEAD_H = 7;
 const EDGE_LABEL_FONT_SIZE = 11;
 
-// Collapsed-node accent bar
-const COLLAPSE_BAR_HEIGHT = 6;
-
 const LEGEND_FIXED_GAP = 8; // gap between fixed legend and scaled diagram — local, not shared
 
 // ============================================================
@@ -80,7 +83,7 @@ function containerFill(
   nodeColor?: string
 ): string {
   if (nodeColor) {
-    return mix(nodeColor, isDark ? palette.surface : palette.bg, 10);
+    return mix(nodeColor, themeBaseBg(palette, isDark), 10);
   }
   return mix(palette.surface, palette.bg, 40);
 }
@@ -492,32 +495,27 @@ export function renderSitemap(
     const fill = nodeFill(palette, isDark, node.color, solid);
     const stroke = nodeStroke(palette, node.color);
 
-    // Card background
-    nodeG
-      .append('rect')
-      .attr('x', 0)
-      .attr('y', 0)
-      .attr('width', node.width)
-      .attr('height', node.height)
-      .attr('rx', CARD_RADIUS)
-      .attr('fill', fill)
-      .attr('stroke', stroke)
-      .attr('stroke-width', sNodeStrokeWidth);
-
+    // Card background + label via the shared card door (Story 111.1). sitemap's
+    // metadata, description lines, and collapse bar diverge from the convention
+    // (different meta baseline; semi-transparent collapse bar + "+N" badge), so
+    // they stay inline below — see conventions §1/§3 deviations log.
     const labelColor = contrastText(
       fill,
       palette.textOnFillLight,
       palette.textOnFillDark
     );
-    nodeG
-      .append('text')
-      .attr('x', node.width / 2)
-      .attr('y', sHeaderHeight / 2 + sLabelFontSize / 2 - 2)
-      .attr('text-anchor', 'middle')
-      .attr('fill', labelColor)
-      .attr('font-size', sLabelFontSize)
-      .attr('font-weight', 'bold')
-      .text(node.label);
+    renderNodeCard(nodeG, {
+      width: node.width,
+      height: node.height,
+      rx: CARD_RADIUS,
+      fill,
+      stroke,
+      strokeWidth: sNodeStrokeWidth,
+      label: node.label,
+      labelColor,
+      labelFontSize: sLabelFontSize,
+      headerHeight: sHeaderHeight,
+    });
 
     const metaEntries = Object.entries(node.metadata);
     if (metaEntries.length > 0) {

package/src/tech-radar/parser.ts

@@ -1,6 +1,6 @@
 import {
-  formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
   suggest,
@@ -72,12 +72,7 @@ export function parseTechRadar(content: string): ParsedTechRadar {
     error: null,
   };
 
-  const fail = (line: number, message: string): ParsedTechRadar => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   const warn = (line: number, message: string): void => {
     result.diagnostics.push(makeDgmoError(line, message, 'warning'));

package/src/timeline/renderer.ts

@@ -24,7 +24,7 @@ import type {
 import { parseTimelineDate } from '../timeline/parser';
 import type { PaletteColors } from '../palettes';
 import { getSeriesColors } from '../palettes';
-import { mix, shapeFill } from '../palettes/color-utils';
+import { mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
 import { resolveTagColor } from '../utils/tag-groups';
 import type { TagGroup } from '../utils/tag-groups';
 import {
@@ -808,7 +808,7 @@ function setupTimeline(
   const textColor = palette.text;
   const mutedColor = palette.border;
   const bgColor = palette.bg;
-  const bg = isDark ? palette.surface : palette.bg;
+  const bg = themeBaseBg(palette, isDark);
   const colors = getSeriesColors(palette);
 
   const groupColorMap = new Map<string, string>();
@@ -1451,7 +1451,7 @@ function renderTimelineHorizontalTimeSort(
   setup: TimelineSetup,
   hovers: TimelineHoverHelpers,
   onClickItem: ((lineNumber: number) => void) | undefined,
-  _exportDims: D3ExportDimensions | undefined,
+  exportDims: D3ExportDimensions | undefined,
   _swimlaneTagGroup: string | null | undefined,
   _activeTagGroup: string | null | undefined,
   _onTagStateChange:
@@ -1461,6 +1461,7 @@ function renderTimelineHorizontalTimeSort(
 ): void {
   const {
     width,
+    height,
     tooltip,
     solid,
     textColor,
@@ -1538,6 +1539,15 @@ function renderTimelineHorizontalTimeSort(
   const innerHeight = rowH * sorted.length;
   const usedHeight = margin.top + innerHeight + margin.bottom;
 
+  // On-screen (non-export) the content can be taller than the host pane. Rather
+  // than overflow it (forcing the user to scroll), scale the whole SVG down to
+  // fit the available height: the viewBox keeps the natural content geometry
+  // while the rendered height is clamped to the container, and
+  // preserveAspectRatio uniformly shrinks + centers it. Export keeps the full
+  // natural height so the image is never compressed.
+  const fitToContainer = !exportDims && height > 0 && usedHeight > height;
+  const svgHeight = fitToContainer ? height : usedHeight;
+
   const xScale = d3Scale
     .scaleLinear()
     .domain([minDate - datePadding, maxDate + datePadding])
@@ -1547,12 +1557,12 @@ function renderTimelineHorizontalTimeSort(
     .select(container)
     .append('svg')
     .attr('width', width)
-    .attr('height', usedHeight)
+    .attr('height', svgHeight)
     .attr('viewBox', `0 0 ${width} ${usedHeight}`)
     .attr('preserveAspectRatio', 'xMidYMin meet')
     .style('background', bgColor);
 
-  if (ctx.isBelowFloor) {
+  if (ctx.isBelowFloor && !fitToContainer) {
     svg.attr('width', '100%');
   }
 

package/src/utils/card.ts

@@ -0,0 +1,183 @@
+// ============================================================
+// Node-card door (Story 111.1)
+// ============================================================
+//
+// The node card described in docs/architecture/diagram-visual-conventions.md §1
+// (rect → label → header separator → metadata rows) and the collapse accent bar
+// (§3) were hand-rolled inline in every structured-diagram renderer. This module
+// owns that drawing behind one interface, mirroring the `renderIntegratedLegend`
+// door (utils/legend-integration.ts): the renderer creates its wrapper `<g>` and
+// resolves geometry + colors (scaling and palette stay the renderer's job — see
+// ScaleContext / 111.3), then makes one call.
+//
+// Output is byte-identical to the prior inline code: same element order, same
+// attributes, same values. Scaled numbers are passed IN (the door never calls
+// ScaleContext), so rounding order is unchanged.
+
+import type { D3Sel } from './legend-types';
+import { measureText } from './text-measure';
+
+/** One resolved metadata row: a display key (already mapped) and its value. */
+export type CardMetaRow = readonly [displayKey: string, value: string];
+
+export interface CardMetaOptions {
+  /** Rows in display order. */
+  rows: readonly CardMetaRow[];
+  /** Scaled metadata font size. */
+  fontSize: number;
+  /** Scaled metadata line height. */
+  lineHeight: number;
+  /** Scaled gap between the header separator and the first row baseline. */
+  separatorGap: number;
+  /** Header separator stroke color (callers pass `solid ? labelColor : stroke`). */
+  separatorColor: string;
+  /** Fill for both key and value text (node cards use the label color for both). */
+  textColor: string;
+  /** Left inset for the key column (defaults to 10, the convention value). */
+  keyX?: number;
+}
+
+export interface NodeCardOptions {
+  /** Card width (already laid out). */
+  width: number;
+  /** Card height (already laid out). */
+  height: number;
+  /** Scaled corner radius. */
+  rx: number;
+  /** Resolved card fill. */
+  fill: string;
+  /** Resolved card stroke. */
+  stroke: string;
+  /** Scaled stroke width. */
+  strokeWidth: number;
+  /** Dashed border (e.g. org `isContainer`); uses the `'6 3'` convention pattern. */
+  dashed?: boolean;
+  /** Label text. */
+  label: string;
+  /** Resolved label color (also used for metadata text). */
+  labelColor: string;
+  /** Scaled label font size. */
+  labelFontSize: number;
+  /** Scaled header band height (positions the label and the separator). */
+  headerHeight: number;
+  /** Metadata block; omit (or pass empty rows) for a card with no separator/meta. */
+  meta?: CardMetaOptions;
+}
+
+/**
+ * Draw a node card (rect → label → optional separator + metadata rows) into
+ * `container` (the renderer's wrapper `<g>`). Reproduces conventions §1 exactly.
+ */
+export function renderNodeCard(container: D3Sel, opts: NodeCardOptions): void {
+  const rect = container
+    .append('rect')
+    .attr('x', 0)
+    .attr('y', 0)
+    .attr('width', opts.width)
+    .attr('height', opts.height)
+    .attr('rx', opts.rx)
+    .attr('fill', opts.fill)
+    .attr('stroke', opts.stroke)
+    .attr('stroke-width', opts.strokeWidth);
+
+  if (opts.dashed) {
+    rect.attr('stroke-dasharray', '6 3');
+  }
+
+  container
+    .append('text')
+    .attr('x', opts.width / 2)
+    .attr('y', opts.headerHeight / 2 + opts.labelFontSize / 2 - 2)
+    .attr('text-anchor', 'middle')
+    .attr('fill', opts.labelColor)
+    .attr('font-size', opts.labelFontSize)
+    .attr('font-weight', 'bold')
+    .text(opts.label);
+
+  const meta = opts.meta;
+  if (!meta || meta.rows.length === 0) return;
+
+  container
+    .append('line')
+    .attr('x1', 0)
+    .attr('y1', opts.headerHeight)
+    .attr('x2', opts.width)
+    .attr('y2', opts.headerHeight)
+    .attr('stroke', meta.separatorColor)
+    .attr('stroke-opacity', 0.3)
+    .attr('stroke-width', 1);
+
+  const keyX = meta.keyX ?? 10;
+  const maxKeyWidth = Math.max(
+    ...meta.rows.map(([key]) => measureText(`${key}: `, meta.fontSize))
+  );
+  const valueX = keyX + maxKeyWidth;
+  const metaStartY = opts.headerHeight + meta.separatorGap + meta.fontSize;
+
+  for (let i = 0; i < meta.rows.length; i++) {
+    const [displayKey, value] = meta.rows[i]!;
+    const rowY = metaStartY + i * meta.lineHeight;
+
+    container
+      .append('text')
+      .attr('x', keyX)
+      .attr('y', rowY)
+      .attr('fill', meta.textColor)
+      .attr('font-size', meta.fontSize)
+      .text(`${displayKey}: `);
+
+    container
+      .append('text')
+      .attr('x', valueX)
+      .attr('y', rowY)
+      .attr('fill', meta.textColor)
+      .attr('font-size', meta.fontSize)
+      .text(value);
+  }
+}
+
+export interface CollapseBarOptions {
+  /** Card width. */
+  width: number;
+  /** Card height (the bar sits at the bottom). */
+  height: number;
+  /** Scaled bar height. */
+  barHeight: number;
+  /** Scaled horizontal inset from each edge (usually 0). */
+  inset: number;
+  /** Scaled corner radius for the clip rect (matches the card). */
+  rx: number;
+  /** Bar fill (callers pass `solid ? labelColor : stroke`). */
+  fill: string;
+  /** Unique clip-path id (kept renderer-local to avoid collisions). */
+  clipId: string;
+  /** Wrapper class for the bar rect (e.g. `org-collapse-bar`). */
+  className: string;
+}
+
+/**
+ * Draw the collapse accent bar (conventions §3) at the bottom of a card,
+ * clipped to the card's rounded corners. Reproduces the prior inline code.
+ */
+export function renderCollapseBar(
+  container: D3Sel,
+  opts: CollapseBarOptions
+): void {
+  container
+    .append('clipPath')
+    .attr('id', opts.clipId)
+    .append('rect')
+    .attr('width', opts.width)
+    .attr('height', opts.height)
+    .attr('rx', opts.rx);
+
+  container
+    .append('rect')
+    .attr('x', opts.inset)
+    .attr('y', opts.height - opts.barHeight)
+    .attr('width', opts.width - opts.inset * 2)
+    .attr('height', opts.barHeight)
+    .attr('fill', opts.fill)
+    .attr('clip-path', `url(#${opts.clipId})`)
+    .attr('class', opts.className);
+}

package/src/utils/parsing.ts

@@ -8,6 +8,7 @@ import {
   RECOGNIZED_COLOR_NAMES,
   resolveColor,
   resolveColorWithDiagnostic,
+  invalidColorDiagnostic,
 } from '../colors';
 import {
   emptyMetadataValueMessage,
@@ -122,7 +123,18 @@ export function extractColor(
   if (lastSpaceIdx < 0) return { label };
   const trailing = label.substring(lastSpaceIdx + 1);
   // Case-sensitive lowercase match against the closed 11-name palette.
-  if (!RECOGNIZED_COLOR_SET.has(trailing)) return { label };
+  if (!RECOGNIZED_COLOR_SET.has(trailing)) {
+    // Not a valid color. If it nonetheless LOOKS like an intended color (a hex
+    // literal or a CSS color name like `pink`), flag it — otherwise the
+    // trailing-token rule would silently swallow it into the label with no
+    // diagnostic, and the MCP color gate would have nothing to block on. A
+    // genuine label word (`Zinfandel`) is not color-like, so it stays as-is.
+    if (diagnostics && line !== undefined) {
+      const diag = invalidColorDiagnostic(trailing, line);
+      if (diag) diagnostics.push(diag);
+    }
+    return { label };
+  }
   let color: string | undefined;
   if (diagnostics && line !== undefined) {
     color = resolveColorWithDiagnostic(trailing, line, diagnostics, palette);

package/src/utils/scaling.ts

@@ -21,6 +21,41 @@ export class ScaleContext {
     return new ScaleContext(clamped, minScaleFactor);
   }
 
+  /**
+   * Fit content into a bounding box, scaling by whichever dimension is more
+   * constraining (the smaller of the width- and height-fit ratios) so the
+   * diagram never overflows the canvas in either axis. Like {@link from}, the
+   * factor is clamped to `[minScaleFactor, 1]` (content is never enlarged, and
+   * never shrunk past the readability floor).
+   */
+  static fromBox(
+    containerWidth: number,
+    idealWidth: number,
+    containerHeight: number,
+    idealHeight: number,
+    minScaleFactor = DEFAULT_MIN_SCALE_FACTOR
+  ): ScaleContext {
+    const wRaw = idealWidth > 0 ? containerWidth / idealWidth : 1;
+    const hRaw = idealHeight > 0 ? containerHeight / idealHeight : 1;
+    const raw = Math.min(wRaw, hRaw);
+    const clamped = Math.max(Math.min(raw, 1), minScaleFactor);
+    return new ScaleContext(clamped, minScaleFactor);
+  }
+
+  /**
+   * Build a context from an explicit raw factor (clamped to
+   * `[minScaleFactor, 1]`). Used to refine a fit iteratively: layout scaling is
+   * non-linear (gaps shrink faster than floored text), so the first-pass factor
+   * can still overflow — re-measure the laid-out result and tighten.
+   */
+  static fromFactor(
+    rawFactor: number,
+    minScaleFactor = DEFAULT_MIN_SCALE_FACTOR
+  ): ScaleContext {
+    const clamped = Math.max(Math.min(rawFactor, 1), minScaleFactor);
+    return new ScaleContext(clamped, minScaleFactor);
+  }
+
   static identity(): ScaleContext {
     return new ScaleContext(1, DEFAULT_MIN_SCALE_FACTOR);
   }
@@ -42,7 +77,9 @@ export class ScaleContext {
 }
 
 // ============================================================
-// Minimum dimensions formula table
+// ContentCounts — per-chart-type content tallies that feed the registry's
+// `minDims` formulas (chart-type-registry.ts). The formulas themselves moved
+// there (Story 111.5) so a chart type's sizing is defined in one descriptor.
 // ============================================================
 
 export interface ContentCounts {
@@ -57,83 +94,3 @@ export interface ContentCounts {
   roles?: number;
   blips?: number;
 }
-
-const DEFAULT_MIN = { width: 300, height: 200 };
-
-export function computeMinDimensions(
-  chartType: string,
-  counts: ContentCounts
-): { width: number; height: number } {
-  switch (chartType) {
-    case 'sequence':
-      return {
-        width: Math.max((counts.participants ?? 2) * 80, 320),
-        height: Math.max((counts.messages ?? 1) * 20 + 120, 200),
-      };
-    case 'raci':
-      return {
-        width: Math.max((counts.roles ?? 2) * 50 + 180, 300),
-        height: Math.max((counts.tasks ?? 1) * 28 + 80, 200),
-      };
-    case 'mindmap':
-      return {
-        width: Math.max((counts.nodes ?? 3) * 30, 300),
-        height: Math.max((counts.depth ?? 2) * 60, 200),
-      };
-    case 'tech-radar':
-      return { width: 360, height: 400 };
-    case 'heatmap':
-      return {
-        width: Math.max((counts.columns ?? 3) * 40, 300),
-        height: Math.max((counts.rows ?? 3) * 30 + 60, 200),
-      };
-    case 'arc':
-      return {
-        width: 300,
-        height: Math.max((counts.nodes ?? 3) * 20 + 120, 200),
-      };
-    case 'org':
-      return {
-        width: Math.max((counts.nodes ?? 3) * 60, 300),
-        height: Math.max((counts.depth ?? 2) * 80, 200),
-      };
-    case 'gantt':
-      return {
-        width: 400,
-        height: Math.max((counts.tasks ?? 3) * 24 + 80, 200),
-      };
-    case 'kanban':
-      return {
-        width: Math.max((counts.columns ?? 3) * 120, 360),
-        height: 300,
-      };
-    case 'er':
-      return {
-        width: Math.max((counts.nodes ?? 2) * 140, 300),
-        height: Math.max((counts.nodes ?? 2) * 80, 200),
-      };
-    case 'class':
-      return {
-        width: Math.max((counts.nodes ?? 2) * 140, 300),
-        height: Math.max((counts.nodes ?? 2) * 80, 200),
-      };
-    case 'flowchart':
-    case 'state':
-      return {
-        width: Math.max((counts.nodes ?? 3) * 60, 300),
-        height: Math.max((counts.nodes ?? 3) * 50, 200),
-      };
-    case 'pert':
-      return {
-        width: Math.max((counts.tasks ?? 3) * 80, 340),
-        height: Math.max((counts.tasks ?? 3) * 40 + 80, 200),
-      };
-    case 'infra':
-      return {
-        width: Math.max((counts.nodes ?? 3) * 80, 300),
-        height: Math.max((counts.nodes ?? 3) * 60, 200),
-      };
-    default:
-      return { ...DEFAULT_MIN };
-  }
-}