@opendata-ai/openchart-engine 7.11.0 → 8.0.0-rc.2

package/src/annotations/compute.ts

@@ -24,9 +24,10 @@ import {
   nudgeAnnotationFromObstacles,
   resolveAnnotationCollisions,
 } from './collisions';
-import { DEFAULT_ANNOTATION_FONT_WEIGHT, SUBTITLE_FONT_SIZE_RATIO } from './constants';
+import { SUBTITLE_FONT_WEIGHT, subtitleFontSize } from './constants';
 import type { AnnotationMeasureTextFn } from './geometry';
 import { heuristicMeasure } from './geometry';
+import { moveAnnotationTo } from './move';
 import {
   findBestPlacement,
   isAutoPlacement,
@@ -36,7 +37,11 @@ import {
 import { resolvePosition } from './position';
 import { resolveRangeAnnotation } from './resolve-range';
 import { resolveRefLineAnnotation } from './resolve-refline';
-import { makeAnnotationLabelStyle, resolveTextAnnotation } from './resolve-text';
+import {
+  makeAnnotationLabelStyle,
+  resolveLedeFontWeight,
+  resolveTextAnnotation,
+} from './resolve-text';
 
 export interface AnnotationContext {
   scales: ResolvedScales;
@@ -46,6 +51,8 @@ export interface AnnotationContext {
   obstacles: PlacementObstacle[];
   svg: { width: number; height: number };
   measure: AnnotationMeasureTextFn;
+  /** Theme font stack, so annotation text is measured and rendered in the same face. */
+  fontFamily?: string;
   debugPlacement?: boolean;
   /** When true, annotations that overlap are demoted to footnote markers instead of being hidden. */
   autoThin?: boolean;
@@ -122,7 +129,7 @@ export function computeAnnotations(
   }> = [];
 
   // ---- Pass 1: resolve explicit annotations and queue auto ones ----
-  for (const annotation of spec.annotations) {
+  for (const [specIndex, annotation] of spec.annotations.entries()) {
     if (isCompact && annotation.responsive !== false) {
       continue;
     }
@@ -136,6 +143,7 @@ export function computeAnnotations(
           ctx.chartArea,
           ctx.isDark,
           ctx.measure,
+          ctx.fontFamily,
         );
         if (resolved && ctx.svg.width > 0 && ctx.svg.height > 0 && isAutoPlacement(annotation)) {
           const px = resolvePosition(annotation.x, ctx.scales.x);
@@ -148,16 +156,30 @@ export function computeAnnotations(
               resolved,
               index: annotations.length,
             });
+            // Same contract as the push below -- this branch `continue`s past it.
+            resolved.specIndex = specIndex;
             annotations.push(resolved);
             continue;
           }
         }
         break;
       case 'range':
-        resolved = resolveRangeAnnotation(annotation, ctx.scales, ctx.chartArea, ctx.isDark);
+        resolved = resolveRangeAnnotation(
+          annotation,
+          ctx.scales,
+          ctx.chartArea,
+          ctx.isDark,
+          ctx.fontFamily,
+        );
         break;
       case 'refline':
-        resolved = resolveRefLineAnnotation(annotation, ctx.scales, ctx.chartArea, ctx.isDark);
+        resolved = resolveRefLineAnnotation(
+          annotation,
+          ctx.scales,
+          ctx.chartArea,
+          ctx.isDark,
+          ctx.fontFamily,
+        );
         break;
     }
 
@@ -172,6 +194,10 @@ export function computeAnnotations(
           ctx.measure,
         );
       }
+      // The resolved array is filtered (an out-of-domain annotation resolves to
+      // nothing), so carry the spec index along -- it's the only stable way back
+      // to the authored annotation from here on.
+      resolved.specIndex = specIndex;
       annotations.push(resolved);
     }
   }
@@ -189,18 +215,23 @@ export function computeAnnotations(
 
     for (const entry of autoQueue) {
       const { annotation, anchorX, anchorY, resolved } = entry;
+      // Must mirror resolveTextAnnotation exactly (lede weight, theme font):
+      // findBestPlacement measures with this style, and the resolved annotation
+      // renders with the other one. Any drift and the scored bounds are a lie.
       const labelStyle = makeAnnotationLabelStyle(
         annotation.fontSize,
-        annotation.fontWeight,
+        resolveLedeFontWeight(annotation),
         undefined,
         ctx.isDark,
+        ctx.fontFamily,
       );
 
       const subtitleStyle = annotation.subtitle
         ? {
-            fontSize: labelStyle.fontSize * SUBTITLE_FONT_SIZE_RATIO,
-            fontWeight: DEFAULT_ANNOTATION_FONT_WEIGHT,
+            fontSize: subtitleFontSize(labelStyle.fontSize),
+            fontWeight: SUBTITLE_FONT_WEIGHT,
             lineHeight: labelStyle.lineHeight,
+            fontFamily: labelStyle.fontFamily,
           }
         : undefined;
 
@@ -212,6 +243,7 @@ export function computeAnnotations(
           fontSize: labelStyle.fontSize,
           fontWeight: Number(labelStyle.fontWeight) || 400,
           lineHeight: labelStyle.lineHeight,
+          fontFamily: labelStyle.fontFamily,
         },
         annotation.subtitle,
         subtitleStyle,
@@ -222,46 +254,29 @@ export function computeAnnotations(
         ctx.debugPlacement,
       );
 
-      // Apply placement result to the resolved annotation
+      // Commit the placement. `moveAnnotationTo` owns every piece of the block's
+      // geometry -- label, subtitle, both bounds caches, connector -- so this pass
+      // does not get to invent its own copy of any of them. It used to, and the
+      // copies drifted: this one re-derived the subtitle's baseline from a font-metric
+      // sum spelled `+ 2` while the resolver spelled it `SUBTITLE_GAP`, so a subtitled
+      // callout rendered 3px off from where the search had actually scored it.
       if (resolved.label) {
-        resolved.label.x = result.labelX;
-        resolved.label.y = result.labelY;
-        resolved.label.style = {
-          ...resolved.label.style,
-          textAnchor: result.textAnchor,
-        };
-        resolved.label.bounds = result.bounds;
-
-        if (resolved.label.connector) {
-          const box = result.bounds;
-          const cx = box.x + box.width / 2;
-          const cy = box.y + box.height / 2;
-          const isCurve = resolved.label.connector.style === 'curve';
-          if (isCurve) {
-            resolved.label.connector.from = { x: box.x + box.width, y: cy };
-          } else {
-            const halfW = box.width / 2 || 1;
-            const halfH = box.height / 2 || 1;
-            const ndx = (anchorX - cx) / halfW;
-            const ndy = (anchorY - cy) / halfH;
-            if (Math.abs(ndy) >= Math.abs(ndx)) {
-              resolved.label.connector.from = {
-                x: cx,
-                y: ndy < 0 ? box.y : box.y + box.height,
-              };
-            } else {
-              resolved.label.connector.from = {
-                x: ndx < 0 ? box.x : box.x + box.width,
-                y: cy,
-              };
-            }
-          }
-        }
+        moveAnnotationTo(
+          resolved,
+          resolved.label,
+          result.labelX,
+          result.labelY,
+          ctx.measure,
+          result.textAnchor,
+        );
       }
-      resolved.bounds = result.bounds;
 
-      // Add this annotation's bounds as obstacle for subsequent auto annotations
-      workingObstacles.push({ ...result.bounds, kind: 'annotation' } as PlacementObstacle);
+      // Add this annotation's bounds as obstacle for subsequent auto annotations.
+      // Read it back off the annotation rather than reusing `result.bounds`: the
+      // mover is the authority on the block's extent, and `result.bounds` is the
+      // search's own estimate of it. One of them has to be the source of truth.
+      const placedBounds = resolved.bounds ?? result.bounds;
+      workingObstacles.push({ ...placedBounds, kind: 'annotation' } as PlacementObstacle);
     }
   } else if (autoQueue.length > 0) {
     // Fallback: no SVG dimensions, use legacy nudge for auto annotations
@@ -282,46 +297,29 @@ export function computeAnnotations(
   // Resolve annotation-to-annotation collisions for non-auto-placed annotations.
   // When auto placement ran, those annotations already avoid each other via the
   // obstacle-accumulation loop above, so only explicitly placed ones need this.
-  if (autoQueue.length > 0) {
-    // Build aligned pairs of explicit annotations + their specs
-    const autoIndices = new Set(autoQueue.map((q) => q.index));
-    const explicitAnnotations: ResolvedAnnotation[] = [];
-    const explicitSpecs: NormalizedChartSpec['annotations'] = [];
-    let specIdx = 0;
-    for (let i = 0; i < annotations.length; i++) {
-      // Walk specIdx past any compact-skipped specs
-      while (specIdx < spec.annotations.length) {
-        const s = spec.annotations[specIdx];
-        if (!isCompact || s.responsive === false) break;
-        specIdx++;
-      }
-      if (specIdx >= spec.annotations.length) break;
-      if (autoIndices.has(i)) {
-        specIdx++;
-        continue;
-      }
-      explicitAnnotations.push(annotations[i]);
-      explicitSpecs.push(spec.annotations[specIdx]);
-      specIdx++;
-    }
-    if (explicitAnnotations.length > 1) {
-      resolveAnnotationCollisions(
-        explicitAnnotations,
-        explicitSpecs,
-        ctx.scales,
-        ctx.chartArea,
-        ctx.measure,
-      );
-    }
-  } else {
-    resolveAnnotationCollisions(
-      annotations,
-      spec.annotations,
-      ctx.scales,
-      ctx.chartArea,
-      ctx.measure,
-    );
-  }
+  //
+  // There used to be a hand-rolled walk here that built a *compacted* pair of
+  // arrays (explicit annotations + their specs) and passed those. It was the
+  // second representation of the same list, and once `resolveAnnotationCollisions`
+  // started keying on the stamped `specIndex` — a GLOBAL index — the compacted
+  // spec array no longer matched it. Every lookup was off by the number of auto
+  // annotations, and the `type === 'text'` guard swallowed the resulting
+  // `undefined`, so collision avoidance silently did nothing the moment a single
+  // auto-placed annotation was present. Which is the *encouraged* authoring style:
+  // a bare `{ type: 'text' }` is auto-placed by definition.
+  //
+  // So don't rebuild the list. Pass the real one, and let the pass skip the
+  // auto-placed entries itself — `specIndex` already tells it which spec each
+  // resolved annotation came from.
+  const autoIndices = new Set(autoQueue.map((q) => q.index));
+  resolveAnnotationCollisions(
+    annotations,
+    spec.annotations,
+    ctx.scales,
+    ctx.chartArea,
+    ctx.measure,
+    autoQueue.length > 0 ? (i) => autoIndices.has(i) : undefined,
+  );
 
   // Clamp labels that overflow the SVG boundary back inside
   if (ctx.svg.width > 0 && ctx.svg.height > 0) {

package/src/annotations/constants.ts

@@ -1,9 +1,24 @@
 /** Default font size for annotation labels. */
-export const DEFAULT_ANNOTATION_FONT_SIZE = 12;
+export const DEFAULT_ANNOTATION_FONT_SIZE = 13;
 
-/** Default font weight for annotation labels. */
+/**
+ * Default font weight for annotation labels. Regular, not bold: emphasis comes
+ * from inline `**bold**` spans, per the NYT/Datawrapper voice.
+ */
 export const DEFAULT_ANNOTATION_FONT_WEIGHT = 400;
 
+/**
+ * Weight the primary text takes when a subtitle is present and the author set no
+ * explicit `fontWeight` — the "Feb. 25 / 2015 maximum" lede + context stack.
+ */
+export const LEDE_FONT_WEIGHT = 700;
+
+/** Subtitles are always regular, so they never inherit a lede weight. */
+export const SUBTITLE_FONT_WEIGHT = 400;
+
+/** Font stack used when the theme font isn't threaded through (SSR/legacy paths). */
+export const FALLBACK_FONT_FAMILY = 'Inter, system-ui, sans-serif';
+
 /** Default line height multiplier for annotation text. */
 export const DEFAULT_LINE_HEIGHT = 1.3;
 
@@ -22,6 +37,12 @@ export const DARK_TEXT_FILL = '#d1d5db';
 export const LIGHT_REFLINE_STROKE = '#888888';
 export const DARK_REFLINE_STROKE = '#9ca3af';
 
+// Quiet connector voice: gray hairline leaders (non-arrowed straight, drop-line).
+// Arrowed connectors take the label's text ink instead, so the emphasis callout
+// reads as one gesture with the words.
+export const LIGHT_CONNECTOR_STROKE = '#8f8f8f';
+export const DARK_CONNECTOR_STROKE = '#9aa0a6';
+
 // Muted text fill for annotation subtitles (~60% perceived contrast vs primary)
 export const LIGHT_MUTED_TEXT_FILL = '#6b7280';
 export const DARK_MUTED_TEXT_FILL = '#9ca3af';
@@ -30,11 +51,17 @@ export const DARK_MUTED_TEXT_FILL = '#9ca3af';
 export const LIGHT_DOT_FILL = '#ffffff';
 export const DARK_DOT_FILL = '#0a0a0a';
 
+// Surface fills for the text-annotation background plate (the mask that hides
+// chart lines behind label text). `background: true` resolves to these, so
+// authors don't hardcode '#ffffff' and get light-gray-on-white in dark mode.
+export const LIGHT_LABEL_BACKGROUND = '#ffffff';
+export const DARK_LABEL_BACKGROUND = '#0a0a0a';
+
 /** Default annotation dot radius in pixels. */
-export const DEFAULT_DOT_RADIUS = 5;
+export const DEFAULT_DOT_RADIUS = 4;
 
 /** Default annotation dot stroke width in pixels. */
-export const DEFAULT_DOT_STROKE_WIDTH = 2;
+export const DEFAULT_DOT_STROKE_WIDTH = 1.5;
 
 /** Vertical gap (px) between the primary annotation text and its subtitle. */
 export const SUBTITLE_GAP = 2;
@@ -42,8 +69,91 @@ export const SUBTITLE_GAP = 2;
 /** Subtitle font size multiplier (relative to primary annotation font size). */
 export const SUBTITLE_FONT_SIZE_RATIO = 0.85;
 
-/** Default label offset when using anchor directions. */
-export const ANCHOR_OFFSET = 8;
+/**
+ * The subtitle's resolved font size. Rounded, and shared by every caller: the
+ * auto-placement pass measures the subtitle to score candidate bounds while the
+ * resolver sets the size that actually renders. If one rounds and the other
+ * doesn't (13 * 0.85 = 11.05 vs 11), the scored bounds are a lie and the drift
+ * flows into collisions and thinning.
+ */
+export function subtitleFontSize(primaryFontSize: number): number {
+  return Math.round(primaryFontSize * SUBTITLE_FONT_SIZE_RATIO);
+}
+
+/**
+ * The subtitle's baseline, given the label's. Same contract as `subtitleFontSize`,
+ * and shared for the same reason: the auto-placement pass SCORES a candidate
+ * subtitle position and the resolver STAMPS the one that renders. Two copies of
+ * this sum is two chances to disagree -- and they did, one spelling the gap
+ * `SUBTITLE_GAP` and the other a bare `+ 2`.
+ *
+ * `primaryLineHeightPx` is the line's height in PIXELS, not the ratio -- so a caller
+ * holding a ratio multiplies by the font size on the way in. Taking the two factors
+ * separately meant the one caller that already had the product had to pass a magic
+ * `1` for the font size, and a signature you have to outsmart is a signature that
+ * will eventually be outsmarted wrong.
+ */
+export function subtitleBaselineY(
+  labelY: number,
+  primaryLineHeightPx: number,
+  primaryLineCount: number,
+): number {
+  return labelY + primaryLineHeightPx * primaryLineCount + SUBTITLE_GAP;
+}
+
+/** Gap (px) between the label bounding box and the start of its connector. */
+export const CONNECTOR_STANDOFF = 6;
+
+/**
+ * Connectors shorter than this are suppressed: a nub between a label and the
+ * marker it's already touching reads as noise, not as a leader.
+ *
+ * Keep this well under the standoff + marker-pullback overhead (~18px), which
+ * is spent before the line is drawn at all. Setting it near or above that
+ * overhead makes the default annotation structurally unable to draw a
+ * connector, however far the author offsets the label.
+ */
+export const MIN_CONNECTOR_LENGTH = 8;
+
+/**
+ * Arrowhead length along the tangent. The renderer pulls the connector's line end
+ * back by exactly this much so the stroke stops at the open V instead of poking
+ * through its tip — a hand-copied duplicate on the vanilla side would silently
+ * drift the next time this changes.
+ */
+export const ARROWHEAD_LENGTH = 7;
+
+/** Arrowhead half-width perpendicular to the tangent. */
+export const ARROWHEAD_HALF_WIDTH = 3.5;
+
+/**
+ * Is a connector of this length worth drawing?
+ *
+ * An arrowed connector doesn't stroke its full length: the renderer stops the line
+ * `ARROWHEAD_LENGTH` short and spends that budget on the head. So a bare
+ * `length >= MIN_CONNECTOR_LENGTH` test is arrow-blind — an 8.1px arrowed
+ * connector clears it, and then ships a 1.1px stub with an arrowhead stuck on the
+ * end. The minimum has to be measured against the part that actually gets stroked,
+ * which means the gate has to know about the head.
+ *
+ * Both suppression sites (`resolveTextAnnotation`, `refreshConnector`) call this
+ * instead of comparing against the constant themselves.
+ */
+export function connectorIsDrawable(length: number, arrow: boolean | undefined): boolean {
+  return length - (arrow ? ARROWHEAD_LENGTH : 0) >= MIN_CONNECTOR_LENGTH;
+}
+
+/**
+ * Default label setback from the data point when using anchor directions.
+ *
+ * Sized so a bare `{ type: 'text' }` annotation lands clear of its marker and
+ * draws a real leader with no offset authoring — a minimal spec should render
+ * publication-ready. Authors tighten it with `offset`.
+ */
+export const ANCHOR_OFFSET = 28;
+
+/** Vertical gap between the top of a drop-line and the top of its label box. */
+export const DROP_LINE_TOP_GAP = 4;
 
 /** Padding between annotation and obstacle when nudging. */
 export const NUDGE_PADDING = 6;