@diagrammo/dgmo 0.30.0 → 0.31.0

package/src/sitemap/renderer.ts

@@ -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
 
 // ============================================================
@@ -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/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/tag-groups.ts

@@ -9,7 +9,11 @@ import {
   tagShorthandRemovedMessage,
   type DgmoError,
 } from '../diagnostics';
-import { RECOGNIZED_COLOR_NAMES, resolveColor } from '../colors';
+import {
+  CATEGORICAL_COLOR_ORDER,
+  RECOGNIZED_COLOR_NAMES,
+  resolveColor,
+} from '../colors';
 import type { PaletteColors } from '../palettes/types';
 import type { Writable } from './brand';
 
@@ -91,16 +95,12 @@ export const AUTO_TAG_COLOR_SENTINEL = '';
 
 /**
  * The categorical name cycle used to auto-assign colors to bare tag values,
- * in deterministic order. Drawn from `RECOGNIZED_COLOR_NAMES` but excludes
- * the non-categorical neutrals (`gray`/`black`/`white`) so auto-picked
- * colors are visually distinct legend swatches. If a group has more
- * colorless entries than free categorical names, the cycle wraps.
+ * in deterministic order. Aliased to the shared {@link CATEGORICAL_COLOR_ORDER}
+ * (RGB-seeded, max-contrast, neutrals excluded) so tag swatches and data-chart
+ * series colors share one canonical rotation. If a group has more colorless
+ * entries than free categorical names, the cycle wraps.
  */
-export const autoTagColorCycle: readonly string[] = Object.freeze(
-  RECOGNIZED_COLOR_NAMES.filter(
-    (n) => n !== 'gray' && n !== 'black' && n !== 'white'
-  )
-);
+export const autoTagColorCycle: readonly string[] = CATEGORICAL_COLOR_ORDER;
 
 /**
  * Finalize a tag group's auto-color assignment.

package/src/utils/visual-conventions.ts

@@ -0,0 +1,61 @@
+// ============================================================
+// Visual conventions — shared card/group/collapse constants (Story 111.1)
+// ============================================================
+//
+// Single source of truth for the structured-diagram visual constants described
+// in docs/architecture/diagram-visual-conventions.md. Before this module these
+// values were re-declared in every renderer (NODE_STROKE_WIDTH in 13 files,
+// HEADER_HEIGHT in 12, ...), so a convention change meant editing N files and
+// hoping the snapshots agreed.
+//
+// Two tiers, because the renderers do NOT all agree:
+//
+//   1. UNIVERSAL — identical at every call site. Import these everywhere; never
+//      re-declare. Changing one of these is a deliberate cross-chart change.
+//
+//   2. CONVENTION DEFAULTS — the org/sitemap baseline from the convention. Most
+//      card-shaped renderers match these and should import them. A few have a
+//      DOCUMENTED intentional deviation and keep a local override (with a
+//      comment saying why):
+//        - infra: META_FONT_SIZE 10 / META_LINE_HEIGHT 14 (denser meta rows)
+//        - boxes-and-lines: COLLAPSE_BAR_HEIGHT 4 / SEPARATOR_GAP 4
+//        - cycle, raci: HEADER_HEIGHT 36 (not label+meta cards)
+//      Those overrides are the exception that proves the rule — they stay local
+//      and visible, not hidden inside a re-declared full constant set.
+
+// ── Universal (same value at every site) ──
+
+/** Node card + group border stroke width. */
+export const NODE_STROKE_WIDTH = 1.5;
+/** Edge / connector stroke width. */
+export const EDGE_STROKE_WIDTH = 1.5;
+/** Node card corner radius. */
+export const CARD_RADIUS = 6;
+/** Group / container corner radius. */
+export const CONTAINER_RADIUS = 8;
+/** Collapse accent bar horizontal inset from the card edges. */
+export const COLLAPSE_BAR_INSET = 0;
+
+// ── Convention defaults (org/sitemap baseline; see deviations above) ──
+
+/** Node card header band height. */
+export const HEADER_HEIGHT = 28;
+/** Node card label font size. */
+export const LABEL_FONT_SIZE = 13;
+/** Node card metadata-row font size. */
+export const META_FONT_SIZE = 11;
+/** Node card metadata-row line height. */
+export const META_LINE_HEIGHT = 16;
+/** Gap between the header separator and the first metadata row. */
+export const SEPARATOR_GAP = 6;
+/** Collapse accent bar height. */
+export const COLLAPSE_BAR_HEIGHT = 6;
+
+/** Group / container reserved header band height. */
+export const CONTAINER_HEADER_HEIGHT = 28;
+/** Group / container label font size. */
+export const CONTAINER_LABEL_FONT_SIZE = 13;
+/** Group / container metadata-row font size. */
+export const CONTAINER_META_FONT_SIZE = 11;
+/** Group / container metadata-row line height. */
+export const CONTAINER_META_LINE_HEIGHT = 16;