@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/utils/note-box/metrics.ts

@@ -1,90 +0,0 @@
-// ============================================================
-// Shared note-box primitive — geometry / wrapping
-// ============================================================
-//
-// Pure measurement: turns a note body string into wrapped lines and
-// a box width/height. Layout-agnostic — used both to reserve space
-// pre-layout and to draw the box. Reuses the canonical text measurer
-// and the bullet-aware wrapper so note text wraps identically to
-// every other rich-text field in the library.
-
-import { wrapDescriptionLines, type WrappedDescLine } from '../wrapped-desc';
-import { measureText } from '../text-measure';
-import {
-  NOTE_MAX_W,
-  NOTE_PAD_H,
-  NOTE_PAD_V,
-  NOTE_FOLD,
-  NOTE_FONT_SIZE,
-  NOTE_LINE_H,
-  NOTE_BULLET_INDENT,
-} from './constants';
-
-export interface NoteBoxSize {
-  /** Box width in px (clamped to `maxW`). */
-  readonly width: number;
-  /** Box height in px. */
-  readonly height: number;
-  /** Wrapped, bullet-classified body lines ready for drawing. */
-  readonly lines: WrappedDescLine[];
-}
-
-export interface NoteBoxSizeOptions {
-  readonly fontSize?: number;
-  readonly maxW?: number;
-}
-
-/**
- * Normalize a source body line's leading bullet marker (`- ` / `* `) to
- * the canonical `• ` that {@link wrapDescriptionLines} recognizes for
- * hanging-indent rendering.
- */
-function normalizeBulletLine(line: string): string {
-  return line.replace(/^\s*[-*]\s+/, '• ');
-}
-
-/**
- * Wrap a note body (lines joined by `\n`) into bullet-classified display
- * lines. Wrapping happens in pixel space via {@link measureText} so the
- * boundary matches the rendered glyph widths.
- */
-export function wrapNoteBody(
-  body: string,
-  textMaxWidth: number,
-  fontSize: number = NOTE_FONT_SIZE
-): WrappedDescLine[] {
-  const sourceLines = body.split('\n').map(normalizeBulletLine);
-  return wrapDescriptionLines(sourceLines, textMaxWidth, (s) =>
-    measureText(s, fontSize)
-  );
-}
-
-/**
- * Compute a note box's wrapped lines and outer dimensions.
- *
- * width  = min(maxW, max(80, longestLine + padH*2 + fold))
- * height = lineCount * lineH + padV*2
- */
-export function noteBoxSize(
-  body: string,
-  opts: NoteBoxSizeOptions = {}
-): NoteBoxSize {
-  const fontSize = opts.fontSize ?? NOTE_FONT_SIZE;
-  const maxW = opts.maxW ?? NOTE_MAX_W;
-  const textMaxWidth = maxW - NOTE_PAD_H * 2;
-  const lines = wrapNoteBody(body, textMaxWidth, fontSize);
-
-  let maxLineW = 0;
-  for (const line of lines) {
-    const indent = line.kind === 'plain' ? 0 : NOTE_BULLET_INDENT;
-    const w = measureText(line.text, fontSize) + indent;
-    if (w > maxLineW) maxLineW = w;
-  }
-
-  const width = Math.min(
-    maxW,
-    Math.max(80, maxLineW + NOTE_PAD_H * 2 + NOTE_FOLD)
-  );
-  const height = Math.max(1, lines.length) * NOTE_LINE_H + NOTE_PAD_V * 2;
-  return { width, height, lines };
-}

package/src/utils/note-box/svg.ts

@@ -1,331 +0,0 @@
-// ============================================================
-// Shared note-box primitive — SVG drawing
-// ============================================================
-//
-// A pure `(parent, rect, lines) → <g class="note">` drawer. Takes a
-// final position and knows nothing about charts, layout, or anchoring.
-// Folded-corner box (palette-themed via `mix`, resvg-safe — never CSS
-// color-mix) + inline-markdown body. Carries the `data-note-toggle`
-// hook + line-number attrs for a future collapse enhancement; decorative
-// sub-paths are `pointer-events:none` so they never steal interactivity.
-
-import type * as d3Selection from 'd3-selection';
-import type { PaletteColors } from '../../palettes';
-import { mix } from '../../palettes/color-utils';
-import { renderInlineText } from '../inline-markdown';
-import type { WrappedDescLine } from '../wrapped-desc';
-import {
-  NOTE_FOLD,
-  NOTE_PAD_H,
-  NOTE_PAD_V,
-  NOTE_FONT_SIZE,
-  NOTE_LINE_H,
-  NOTE_BULLET_INDENT,
-} from './constants';
-
-type GSelection = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
-
-// Subdued stroke styling for the note box, fold, and leader line — thin and
-// a little lighter so the annotation stays quiet next to the diagram.
-const NOTE_STROKE_WIDTH = 0.6;
-const NOTE_STROKE_OPACITY = 0.6;
-
-export interface NoteRect {
-  /** Left edge of the box, in the parent group's coordinate space. */
-  readonly x: number;
-  /** Top edge of the box. */
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-}
-
-export interface RenderNoteBoxOptions {
-  readonly isDark: boolean;
-  readonly fontSize?: number;
-  /** Resolved hex accent (border + faded fill); default yellow if absent. */
-  readonly color?: string;
-  /** 1-based source line of the note (drives the toggle hook). */
-  readonly lineNumber?: number;
-  /** 1-based last source line of the note body. */
-  readonly endLineNumber?: number;
-  /**
-   * When true, the box is a click target that collapses the note (the app
-   * wires `data-note-toggle`): the group gets `cursor:pointer` + button
-   * a11y and the box fill catches pointer events. When false (the default,
-   * e.g. static export contexts), the box is inert.
-   */
-  readonly interactive?: boolean;
-}
-
-/**
- * Draw the solid "tether" connecting a node to its note box so the
- * annotation reads as belonging to that node. The note floats beside the
- * shape WITHOUT moving it, so the tether spans the gap between them.
- * Coordinates are in the parent group's space. Decorative —
- * `pointer-events:none`.
- */
-export function renderNoteConnector(
-  parent: GSelection,
-  x1: number,
-  y1: number,
-  x2: number,
-  y2: number,
-  palette: PaletteColors
-): void {
-  parent
-    .append('line')
-    .attr('x1', x1)
-    .attr('y1', y1)
-    .attr('x2', x2)
-    .attr('y2', y2)
-    .attr('stroke', palette.textMuted)
-    .attr('stroke-width', NOTE_STROKE_WIDTH)
-    .attr('stroke-opacity', NOTE_STROKE_OPACITY)
-    .attr('class', 'note-connector')
-    .style('pointer-events', 'none');
-}
-
-/**
- * Connector endpoints `[x1, y1, x2, y2]` (node-center-local) from the
- * shape edge to the note's near edge, for the side the note sits on.
- */
-export function noteConnectorPoints(
-  node: { width: number; height: number },
-  note: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    side: 'above' | 'below' | 'left' | 'right';
-  }
-): [number, number, number, number] {
-  const clampX = Math.max(note.x, Math.min(0, note.x + note.width));
-  switch (note.side) {
-    case 'right':
-      return [node.width / 2, 0, note.x, note.y + note.height / 2];
-    case 'left':
-      return [
-        -node.width / 2,
-        0,
-        note.x + note.width,
-        note.y + note.height / 2,
-      ];
-    case 'below':
-      return [clampX, node.height / 2, clampX, note.y];
-    case 'above':
-    default:
-      return [clampX, -node.height / 2, clampX, note.y + note.height];
-  }
-}
-
-/** Note accent (border) colour — the note's color, else the palette yellow. */
-export function noteAccent(palette: PaletteColors, color?: string): string {
-  return color ?? palette.colors.yellow;
-}
-
-/** Faded note fill (resvg-safe — `mix`, never CSS color-mix). */
-export function noteBoxFill(
-  palette: PaletteColors,
-  isDark: boolean,
-  color?: string
-): string {
-  const accent = noteAccent(palette, color);
-  return isDark ? mix(accent, palette.bg, 24) : mix(accent, palette.bg, 16);
-}
-
-/**
- * Append a folded-corner note box to `parent` at `rect`, with `lines`
- * (from {@link noteBoxSize}) as the body. Returns the created group.
- */
-export function renderNoteBox(
-  parent: GSelection,
-  rect: NoteRect,
-  lines: readonly WrappedDescLine[],
-  palette: PaletteColors,
-  opts: RenderNoteBoxOptions
-): GSelection {
-  const fontSize = opts.fontSize ?? NOTE_FONT_SIZE;
-  const interactive = opts.interactive ?? false;
-  const { x, y, width, height } = rect;
-  const fill = noteBoxFill(palette, opts.isDark, opts.color);
-  const accent = noteAccent(palette, opts.color);
-
-  const noteG = parent
-    .append('g')
-    .attr('class', 'note')
-    .attr('data-note-toggle', '');
-  if (opts.lineNumber !== undefined) {
-    noteG.attr('data-line-number', String(opts.lineNumber));
-  }
-  if (opts.endLineNumber !== undefined) {
-    noteG.attr('data-line-end', String(opts.endLineNumber));
-  }
-  if (interactive) {
-    noteG
-      .style('cursor', 'pointer')
-      .attr('role', 'button')
-      .attr('tabindex', '0')
-      .attr('aria-expanded', 'true')
-      .attr('aria-label', 'Collapse note');
-  }
-
-  // Folded-corner body path. When interactive it doubles as the click
-  // target (default pointer-events); otherwise it's inert.
-  const boxPath = noteG
-    .append('path')
-    .attr(
-      'd',
-      [
-        `M ${x} ${y}`,
-        `L ${x + width - NOTE_FOLD} ${y}`,
-        `L ${x + width} ${y + NOTE_FOLD}`,
-        `L ${x + width} ${y + height}`,
-        `L ${x} ${y + height}`,
-        'Z',
-      ].join(' ')
-    )
-    .attr('fill', fill)
-    .attr('stroke', accent)
-    .attr('stroke-width', NOTE_STROKE_WIDTH)
-    .attr('stroke-opacity', NOTE_STROKE_OPACITY)
-    .attr('class', 'note-box');
-  if (!interactive) boxPath.style('pointer-events', 'none');
-
-  // Fold triangle.
-  noteG
-    .append('path')
-    .attr(
-      'd',
-      [
-        `M ${x + width - NOTE_FOLD} ${y}`,
-        `L ${x + width - NOTE_FOLD} ${y + NOTE_FOLD}`,
-        `L ${x + width} ${y + NOTE_FOLD}`,
-      ].join(' ')
-    )
-    .attr('fill', 'none')
-    .attr('stroke', accent)
-    .attr('stroke-width', NOTE_STROKE_WIDTH)
-    .attr('stroke-opacity', NOTE_STROKE_OPACITY)
-    .attr('class', 'note-fold')
-    .style('pointer-events', 'none');
-
-  // Body text — bullet first-lines get a "•" glyph at the left edge with
-  // the body hanging-indented; continuation lines align under the body.
-  lines.forEach((line, li) => {
-    const textY = y + NOTE_PAD_V + (li + 1) * NOTE_LINE_H - 3;
-    const indent = line.kind === 'plain' ? 0 : NOTE_BULLET_INDENT;
-    if (line.kind === 'bullet-first') {
-      noteG
-        .append('text')
-        .attr('x', x + NOTE_PAD_H)
-        .attr('y', textY)
-        .attr('fill', palette.text)
-        .attr('font-size', fontSize)
-        .text('•');
-    }
-    const textEl = noteG
-      .append('text')
-      .attr('x', x + NOTE_PAD_H + indent)
-      .attr('y', textY)
-      .attr('fill', palette.text)
-      .attr('font-size', fontSize)
-      .attr('class', 'note-text');
-    renderInlineText(textEl, line.text, palette, fontSize);
-  });
-
-  return noteG;
-}
-
-export interface RenderNoteBadgeOptions {
-  readonly isDark: boolean;
-  /** Resolved hex accent; default yellow if absent. */
-  readonly color?: string;
-  /** 1-based source line of the note (drives the toggle hook). */
-  readonly lineNumber?: number;
-  readonly endLineNumber?: number;
-}
-
-/** Half the badge's footprint (px) — for callers reserving corner space. */
-export const NOTE_BADGE_RADIUS = 7;
-
-/** Overall opacity of the collapsed badge — kept quiet so it reads as a
- *  subtle affordance, not a loud icon competing with the node. */
-const NOTE_BADGE_OPACITY = 0.6;
-
-/**
- * Draw the collapsed-note badge: a small comment bubble pinned at `center`
- * (parent-group coords). Carries the same `data-note-toggle` + line attrs
- * as the expanded box, so clicking it re-expands the note. Interactive by
- * design (button a11y + `cursor:pointer`).
- */
-export function renderNoteBadge(
-  parent: GSelection,
-  center: { readonly x: number; readonly y: number },
-  palette: PaletteColors,
-  opts: RenderNoteBadgeOptions
-): GSelection {
-  const fill = noteBoxFill(palette, opts.isDark, opts.color);
-  const accent = noteAccent(palette, opts.color);
-  const g = parent
-    .append('g')
-    .attr('class', 'note note-badge')
-    .attr('data-note-toggle', '')
-    .attr('transform', `translate(${center.x}, ${center.y})`)
-    .attr('opacity', NOTE_BADGE_OPACITY)
-    .style('cursor', 'pointer')
-    .attr('role', 'button')
-    .attr('tabindex', '0')
-    .attr('aria-expanded', 'false')
-    .attr('aria-label', 'Expand note');
-  if (opts.lineNumber !== undefined) {
-    g.attr('data-line-number', String(opts.lineNumber));
-  }
-  if (opts.endLineNumber !== undefined) {
-    g.attr('data-line-end', String(opts.endLineNumber));
-  }
-
-  // Comment bubble: small rounded body (13×9) with a tail at the
-  // bottom-left. Single path so body + tail share one seamless outline.
-  g.append('path')
-    .attr(
-      'd',
-      [
-        'M -6.5 -4',
-        'Q -6.5 -6 -4.5 -6',
-        'L 4.5 -6',
-        'Q 6.5 -6 6.5 -4',
-        'L 6.5 1',
-        'Q 6.5 3 4.5 3',
-        'L -1 3',
-        'L -4 6',
-        'L -2.5 3',
-        'L -4.5 3',
-        'Q -6.5 3 -6.5 1',
-        'Z',
-      ].join(' ')
-    )
-    .attr('fill', fill)
-    .attr('stroke', accent)
-    .attr('stroke-width', 0.55)
-    .attr('class', 'note-badge-bubble');
-
-  // Two short "text" strokes inside the bubble (group opacity tones them).
-  g.append('line')
-    .attr('x1', -3.5)
-    .attr('y1', -3)
-    .attr('x2', 3.5)
-    .attr('y2', -3)
-    .attr('stroke', palette.textMuted)
-    .attr('stroke-width', 0.75)
-    .style('pointer-events', 'none');
-  g.append('line')
-    .attr('x1', -3.5)
-    .attr('y1', -0.5)
-    .attr('x2', 1.5)
-    .attr('y2', -0.5)
-    .attr('stroke', palette.textMuted)
-    .attr('stroke-width', 0.75)
-    .style('pointer-events', 'none');
-
-  return g;
-}

package/src/utils/notes/bounds.ts

@@ -1,30 +0,0 @@
-// ============================================================
-// Generic diagram note — canvas shift
-// ============================================================
-//
-// A note floated above/left of its node can land at negative coordinates.
-// After a chart computes its content bbox (INCLUDING note rects), it passes
-// the bbox min corner here to learn how much to translate every node, edge,
-// and group so nothing clips on export. Charts with no off-canvas note get
-// `{shiftX:0, shiftY:0}` and stay byte-for-byte unchanged.
-
-export interface NoteCanvasShift {
-  readonly shiftX: number;
-  readonly shiftY: number;
-}
-
-/**
- * Translation needed to bring content that ran off the top/left back into
- * the canvas with a `margin` gutter. Only shifts when a min coord is
- * negative; otherwise returns 0 on that axis.
- */
-export function noteCanvasShift(
-  minX: number,
-  minY: number,
-  margin = 20
-): NoteCanvasShift {
-  return {
-    shiftX: minX < 0 ? margin - minX : 0,
-    shiftY: minY < 0 ? margin - minY : 0,
-  };
-}

package/src/utils/notes/build.ts

@@ -1,131 +0,0 @@
-// ============================================================
-// Generic diagram note — layout assembly
-// ============================================================
-//
-// Turns resolved notes + positioned anchor rects into render-ready
-// {@link PlacedNote}s (box geometry LOCAL to each node's center, or a
-// collapsed flag). A chart's layout calls this once, attaches each
-// PlacedNote to its layout node, then extends its content bbox with the
-// note rects and applies `noteCanvasShift`. Keeps every adopting chart's
-// note wiring to a few lines.
-
-import { noteBoxSize } from '../note-box';
-import type { WrappedDescLine } from '../wrapped-desc';
-import { placeNotes, type NoteSide, type PlaceableNode } from './place';
-import type { DiagramNote } from './model';
-
-/** A resolved, placed note ready for the note-box drawer. */
-export interface PlacedNote {
-  /** Box left, LOCAL to the node center (add node.x). Unused if collapsed. */
-  readonly x: number;
-  /** Box top, LOCAL to the node center (add node.y). Unused if collapsed. */
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-  readonly side: NoteSide;
-  /** Resolved hex accent (border + faded fill); default yellow if absent. */
-  readonly color?: string;
-  readonly lines: readonly WrappedDescLine[];
-  readonly lineNumber: number;
-  readonly endLineNumber: number;
-  /** Collapsed → renderer draws a corner badge; box geometry is unused. */
-  readonly collapsed?: boolean;
-}
-
-/** A positioned anchor node: its id plus its center rect. */
-export interface NoteAnchor extends PlaceableNode {
-  readonly id: string;
-}
-
-/**
- * Build a map of node id → {@link PlacedNote} for every anchor that has a
- * resolved note. Measures each note, runs the shared collision placer, and
- * assembles render-ready geometry. Collapsed notes (lineNumber ∈
- * `collapsedNotes`) reserve no space.
- */
-export function buildPlacedNotes(
-  anchors: readonly NoteAnchor[],
-  noteByNode: ReadonlyMap<string, DiagramNote>,
-  direction: 'TB' | 'LR',
-  collapsedNotes?: ReadonlySet<number>
-): Map<string, PlacedNote> {
-  const placed = new Map<string, PlacedNote>();
-  if (noteByNode.size === 0) return placed;
-
-  interface Geom {
-    readonly noteW: number;
-    readonly noteH: number;
-    readonly color?: string;
-    readonly lines: readonly WrappedDescLine[];
-    readonly lineNumber: number;
-    readonly endLineNumber: number;
-  }
-  const geoms = new Map<string, Geom>();
-  const requests: {
-    key: string;
-    node: PlaceableNode;
-    noteW: number;
-    noteH: number;
-    collapsed: boolean;
-  }[] = [];
-
-  for (const a of anchors) {
-    const note = noteByNode.get(a.id);
-    if (!note) continue;
-    const size = noteBoxSize(note.body);
-    geoms.set(a.id, {
-      noteW: size.width,
-      noteH: size.height,
-      ...(note.color && { color: note.color }),
-      lines: size.lines,
-      lineNumber: note.lineNumber,
-      endLineNumber: note.endLineNumber,
-    });
-    requests.push({
-      key: a.id,
-      node: { x: a.x, y: a.y, width: a.width, height: a.height },
-      noteW: size.width,
-      noteH: size.height,
-      collapsed: collapsedNotes?.has(note.lineNumber) ?? false,
-    });
-  }
-
-  const placements = placeNotes(
-    anchors.map((a) => ({ x: a.x, y: a.y, width: a.width, height: a.height })),
-    requests,
-    direction
-  );
-
-  for (const [id, g] of geoms) {
-    const p = placements.get(id)!;
-    placed.set(
-      id,
-      p.collapsed
-        ? {
-            x: 0,
-            y: 0,
-            width: 0,
-            height: 0,
-            side: 'right',
-            ...(g.color && { color: g.color }),
-            lines: [],
-            lineNumber: g.lineNumber,
-            endLineNumber: g.endLineNumber,
-            collapsed: true,
-          }
-        : {
-            x: p.x,
-            y: p.y,
-            width: g.noteW,
-            height: g.noteH,
-            side: p.side,
-            ...(g.color && { color: g.color }),
-            lines: g.lines,
-            lineNumber: g.lineNumber,
-            endLineNumber: g.endLineNumber,
-          }
-    );
-  }
-
-  return placed;
-}

package/src/utils/notes/index.ts

@@ -1,18 +0,0 @@
-// ============================================================
-// Generic diagram notes — barrel
-// ============================================================
-//
-// One chart-neutral note pipeline: model → parse → resolve → place →
-// shift, plus the shared `note-box` drawer. A node-based chart adopts
-// notes by importing from here and supplying only an anchor list and the
-// per-chart layout wiring. See the cross-chart rollout tech spec.
-
-export * from './model';
-export * from './parse';
-export * from './resolve';
-export * from './place';
-export * from './build';
-export * from './bounds';
-
-// Re-export the drawer so charts have one import site for the whole feature.
-export * from '../note-box';

package/src/utils/notes/model.ts

@@ -1,19 +0,0 @@
-// ============================================================
-// Generic diagram note — chart-neutral model
-// ============================================================
-//
-// One annotation attachable to any node-based chart. The parser collects
-// raw `{ref, body, color?}`; a shared resolver binds `ref` to a concrete
-// node, and a shared placer + the `utils/note-box` drawer render it. Each
-// chart adds only a note-line handler + an anchor (id/label) list.
-
-export interface DiagramNote {
-  /** Author-typed node id/label the note attaches to. */
-  readonly ref: string;
-  /** Body text (inline + indented lines, joined with `\n`). */
-  readonly body: string;
-  /** Resolved hex accent (border + faded fill); default yellow if absent. */
-  readonly color?: string;
-  readonly lineNumber: number;
-  readonly endLineNumber: number;
-}