@diagrammo/dgmo 0.25.5 → 0.27.0

package/src/utils/legend-constants.ts

@@ -19,61 +19,15 @@ export const LEGEND_ICON_W = 20;
 export const LEGEND_MAX_ENTRY_ROWS = 3;
 
 // ── Proportional text measurement ────────────────────────────
-// Helvetica character width ratios (fraction of fontSize).
-// Replaces the naive `chars * 0.6 * fontSize` estimate with
-// per-character proportional widths for accurate legend sizing.
-// prettier-ignore
-const CHAR_W: Record<string, number> = {
-  ' ':.28,'!': .28,'"': .36,'#': .56,'$': .56,'%': .89,'&': .67,"'":.19,
-  '(':.33,')':.33,'*': .39,'+':.58,',':.28,'-':.33,'.':.28,'/':.28,
-  '0':.56,'1':.56,'2':.56,'3':.56,'4':.56,'5':.56,'6':.56,'7':.56,'8':.56,'9':.56,
-  ':':.28,';':.28,'<':.58,'=':.58,'>':.58,'?':.56,'@':1.02,
-  A:.67,B:.67,C:.72,D:.72,E:.67,F:.61,G:.78,H:.72,I:.28,J:.50,K:.67,L:.56,M:.83,
-  N:.72,O:.78,P:.67,Q:.78,R:.72,S:.67,T:.61,U:.72,V:.67,W:.94,X:.67,Y:.67,Z:.61,
-  a:.56,b:.56,c:.50,d:.56,e:.56,f:.28,g:.56,h:.56,i:.22,j:.22,k:.50,l:.22,m:.83,
-  n:.56,o:.56,p:.56,q:.56,r:.33,s:.50,t:.28,u:.56,v:.50,w:.72,x:.50,y:.50,z:.50,
-};
-const DEFAULT_W = 0.56;
+// The canonical glyph-table measurer now lives in `./text-measure`.
+// Re-exported here under the legacy names so existing legend call
+// sites keep working; new code should import from `./text-measure`.
+import { measureText, truncateText } from './text-measure';
 
-/** Estimate rendered text width using Helvetica proportional character widths. */
-export function measureLegendText(text: string, fontSize: number): number {
-  let w = 0;
-  for (let i = 0; i < text.length; i++) {
-    // charAt returns '' for out-of-bounds, never undefined.
-    w += (CHAR_W[text.charAt(i)] ?? DEFAULT_W) * fontSize;
-  }
-  return w;
-}
-
-/**
- * Truncate text with a trailing ellipsis to fit within maxWidth.
- * Returns the original text if it already fits, or '' if even the
- * ellipsis alone won't fit.
- */
-export function truncateLegendText(
-  text: string,
-  fontSize: number,
-  maxWidth: number
-): string {
-  if (measureLegendText(text, fontSize) <= maxWidth) return text;
-  const ellipsis = '…';
-  const ellipsisW = measureLegendText(ellipsis, fontSize);
-  if (ellipsisW > maxWidth) return '';
-  let lo = 0;
-  let hi = text.length;
-  while (lo < hi) {
-    const mid = Math.ceil((lo + hi) / 2);
-    if (
-      measureLegendText(text.slice(0, mid), fontSize) + ellipsisW <=
-      maxWidth
-    ) {
-      lo = mid;
-    } else {
-      hi = mid - 1;
-    }
-  }
-  return lo === 0 ? ellipsis : text.slice(0, lo) + ellipsis;
-}
+/** @deprecated import `measureText` from `./text-measure`. */
+export const measureLegendText = measureText;
+/** @deprecated import `truncateText` from `./text-measure`. */
+export const truncateLegendText = truncateText;
 
 // Eye icon SVG paths (14×14 viewBox)
 // Present only in org and sitemap legends (metadata visibility toggle)

package/src/utils/legend-d3.ts

@@ -15,7 +15,7 @@ import {
   measureLegendText,
 } from './legend-constants';
 import { computeLegendLayout } from './legend-layout';
-import { mix } from '../palettes/color-utils';
+import { mix, valueRampStops } from '../palettes/color-utils';
 import { FONT_FAMILY } from '../fonts';
 import type {
   LegendConfig,
@@ -158,7 +158,7 @@ function renderCapsule(
   palette: LegendPalette,
   groupBg: string,
   pillBorder: string,
-  _isDark: boolean,
+  isDark: boolean,
   callbacks?: LegendCallbacks
 ): void {
   const g = parent
@@ -213,11 +213,14 @@ function renderCapsule(
     const gr = capsule.gradient;
     const gradId = `dgmo-legend-ramp-${capsule.groupName.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
     const def = g.append('defs').append('linearGradient').attr('id', gradId);
-    def
-      .append('stop')
-      .attr('offset', '0%')
-      .attr('stop-color', mix(gr.hue, gr.base, 15));
-    def.append('stop').attr('offset', '100%').attr('stop-color', gr.hue);
+    // Sample the SAME ramp the fills use (direct = 2 endpoints; diverging =
+    // stops through the neutral midpoint), so the legend matches the basemap.
+    for (const stop of valueRampStops(gr.low, gr.high, { isDark })) {
+      def
+        .append('stop')
+        .attr('offset', `${stop.offset * 100}%`)
+        .attr('stop-color', stop.color);
+    }
     g.append('text')
       .attr('x', gr.minX)
       .attr('y', gr.textY)

package/src/utils/legend-layout.ts

@@ -20,6 +20,7 @@ import {
   truncateLegendText,
 } from './legend-constants';
 
+import { compactNumber } from './number-format';
 import type { LegendGroupData } from './legend-types';
 import type {
   LegendConfig,
@@ -47,9 +48,11 @@ const RAMP_LEGEND_W = 80;
 const RAMP_LEGEND_H = 8;
 const RAMP_LABEL_GAP = 6;
 
-/** Compact numeric label for a ramp end (integers bare; else 1 decimal). */
+/** Compact numeric label for a ramp end — shared with the map's on-region value
+ *  labels (`compactNumber`) so the gradient ends and region values read the same
+ *  (`40M` legend end ↔ a `39.5M` region). */
 function fmtRamp(n: number): string {
-  return Number.isInteger(n) ? String(n) : String(Math.round(n * 10) / 10);
+  return compactNumber(n);
 }
 
 /** Width of a gradient group's capsule: pill + min label + ramp + max label. */
@@ -114,8 +117,8 @@ function buildGradientCapsuleLayout(
       maxText,
       maxX,
       textY: LEGEND_HEIGHT / 2,
-      hue: gradient.hue,
-      base: gradient.base,
+      low: gradient.low,
+      high: gradient.high,
     },
   };
 }

package/src/utils/legend-types.ts

@@ -88,8 +88,12 @@ export interface LegendGroupData {
   readonly gradient?: {
     readonly min: number;
     readonly max: number;
-    readonly hue: string;
-    readonly base: string;
+    /** Resolved hex of the LOW (t=0) endpoint. For a single-colour ramp this is
+     *  the floored neutral (`mix(hue, base, RAMP_FLOOR)`); for an explicit
+     *  two-colour ramp it is the user's low colour. */
+    readonly low: string;
+    /** Resolved hex of the HIGH (t=1) endpoint (the named hue). */
+    readonly high: string;
   };
 }
 
@@ -179,8 +183,10 @@ export interface LegendCapsuleLayout {
     maxText: string;
     maxX: number;
     textY: number;
-    hue: string;
-    base: string;
+    /** Resolved hex endpoints (low = t0, high = t1); the renderer samples the
+     *  ramp between them via `valueRampStops`. */
+    low: string;
+    high: string;
   };
 }
 

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

@@ -0,0 +1,25 @@
+// ============================================================
+// Shared note-box primitive — constants
+// ============================================================
+//
+// Lifted verbatim from the sequence renderer's note constants
+// (sequence/renderer.ts) so any chart type can draw the same
+// folded-corner annotation box. Pure values — no chart coupling.
+
+/** Hard ceiling on a note box's width (px) before text wraps. */
+export const NOTE_MAX_W = 200;
+/** Size of the folded top-right corner (px). */
+export const NOTE_FOLD = 10;
+/** Horizontal padding inside the box (px). */
+export const NOTE_PAD_H = 8;
+/** Vertical padding inside the box (px). */
+export const NOTE_PAD_V = 6;
+/** Note body font size (px). */
+export const NOTE_FONT_SIZE = 10;
+/** Line height for wrapped body lines (px). */
+export const NOTE_LINE_H = 14;
+/** Gap between an anchor shape's edge and its floated note box (px). The
+ *  note is tethered to its node with a solid connector across this gap. */
+export const NOTE_GAP = 22;
+/** Hanging-indent width for bullet body text past the "•" glyph (px). */
+export const NOTE_BULLET_INDENT = 10;

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

@@ -0,0 +1,11 @@
+// ============================================================
+// Shared note-box primitive — barrel
+// ============================================================
+//
+// Generic folded-corner annotation box, extracted from the sequence
+// renderer so any node/edge chart type can adopt notes by writing only
+// an anchor resolver + placement policy — never re-implementing the box.
+
+export * from './constants';
+export * from './metrics';
+export * from './svg';

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

@@ -0,0 +1,90 @@
+// ============================================================
+// 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

@@ -0,0 +1,331 @@
+// ============================================================
+// 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

@@ -0,0 +1,30 @@
+// ============================================================
+// 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,
+  };
+}