@opendata-ai/openchart-engine 6.12.0 → 6.13.0

package/src/annotations/constants.ts

@@ -0,0 +1,32 @@
+/** Default font size for annotation labels. */
+export const DEFAULT_ANNOTATION_FONT_SIZE = 12;
+
+/** Default font weight for annotation labels. */
+export const DEFAULT_ANNOTATION_FONT_WEIGHT = 400;
+
+/** Default line height multiplier for annotation text. */
+export const DEFAULT_LINE_HEIGHT = 1.3;
+
+/** Default fill color for range annotations. */
+export const DEFAULT_RANGE_FILL = '#f0c040';
+
+/** Default opacity for range annotations. */
+export const DEFAULT_RANGE_OPACITY = 0.15;
+
+/** Default dash pattern for reference lines. */
+export const DEFAULT_REFLINE_DASH = '4 3';
+
+// Theme-aware defaults for text and stroke colors
+export const LIGHT_TEXT_FILL = '#333333';
+export const DARK_TEXT_FILL = '#d1d5db';
+export const LIGHT_REFLINE_STROKE = '#888888';
+export const DARK_REFLINE_STROKE = '#9ca3af';
+
+/** Default label offset when using anchor directions. */
+export const ANCHOR_OFFSET = 8;
+
+/** Padding between annotation and obstacle when nudging. */
+export const NUDGE_PADDING = 6;
+
+/** Small inset margin so labels don't touch the SVG edge. */
+export const CLAMP_MARGIN = 4;

package/src/annotations/geometry.ts

@@ -0,0 +1,167 @@
+/**
+ * Geometry utilities for annotation text bounds, connector origins, and offsets.
+ */
+
+import type {
+  AnnotationAnchor,
+  AnnotationOffset,
+  Rect,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import {
+  ANCHOR_OFFSET,
+  DEFAULT_ANNOTATION_FONT_SIZE,
+  DEFAULT_ANNOTATION_FONT_WEIGHT,
+  DEFAULT_LINE_HEIGHT,
+} from './constants';
+
+/**
+ * Compute the bounding box of annotation text at a given label position.
+ * Multi-line text is centered at labelX; single-line starts at labelX.
+ */
+export function computeTextBounds(
+  labelX: number,
+  labelY: number,
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+): Rect {
+  const lines = text.split('\n');
+  const isMultiLine = lines.length > 1;
+  const maxWidth = Math.max(...lines.map((line) => estimateTextWidth(line, fontSize, fontWeight)));
+  const totalHeight = lines.length * fontSize * DEFAULT_LINE_HEIGHT;
+  const x = isMultiLine ? labelX - maxWidth / 2 : labelX;
+
+  return {
+    x,
+    y: labelY - fontSize,
+    width: maxWidth,
+    height: totalHeight,
+  };
+}
+
+/**
+ * Apply anchor direction to compute label offset from data point.
+ * Returns { dx, dy } pixel offsets.
+ */
+export function computeAnchorOffset(
+  anchor: AnnotationAnchor | undefined,
+  _px: number,
+  py: number,
+  chartArea: Rect,
+): { dx: number; dy: number } {
+  if (!anchor || anchor === 'auto') {
+    // Auto: place above if in the lower half, below if upper half
+    const isUpperHalf = py < chartArea.y + chartArea.height / 2;
+    return isUpperHalf
+      ? { dx: ANCHOR_OFFSET, dy: ANCHOR_OFFSET } // below-right
+      : { dx: ANCHOR_OFFSET, dy: -ANCHOR_OFFSET }; // above-right
+  }
+
+  switch (anchor) {
+    case 'top':
+      return { dx: 0, dy: -ANCHOR_OFFSET };
+    case 'bottom':
+      return { dx: 0, dy: ANCHOR_OFFSET };
+    case 'left':
+      return { dx: -ANCHOR_OFFSET, dy: 0 };
+    case 'right':
+      return { dx: ANCHOR_OFFSET, dy: 0 };
+  }
+}
+
+/** Apply user offset on top of computed anchor offset. */
+export function applyOffset(
+  base: { dx: number; dy: number },
+  offset: AnnotationOffset | undefined,
+): { dx: number; dy: number } {
+  if (!offset) return base;
+  return {
+    dx: base.dx + (offset.dx ?? 0),
+    dy: base.dy + (offset.dy ?? 0),
+  };
+}
+
+/**
+ * Compute the connector origin point on the text bounding box.
+ * For straight connectors, finds the edge midpoint (top, bottom, left, right)
+ * closest to the data point. For curve connectors, always uses the right edge.
+ */
+export function computeConnectorOrigin(
+  labelX: number,
+  labelY: number,
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+  targetX: number,
+  targetY: number,
+  connectorStyle: 'straight' | 'curve',
+): { x: number; y: number } {
+  const box = computeTextBounds(labelX, labelY, text, fontSize, fontWeight);
+  const boxCenterX = box.x + box.width / 2;
+  const boxCenterY = box.y + box.height / 2;
+
+  // Curve connectors always start from the right edge
+  if (connectorStyle === 'curve') {
+    return {
+      x: box.x + box.width,
+      y: boxCenterY,
+    };
+  }
+
+  // Normalize the vector from box center to target by the box half-dimensions.
+  // This accounts for the box aspect ratio: a wide text box should prefer
+  // top/bottom exits even when the target is also offset horizontally.
+  const halfW = box.width / 2 || 1;
+  const halfH = box.height / 2 || 1;
+  const ndx = (targetX - boxCenterX) / halfW;
+  const ndy = (targetY - boxCenterY) / halfH;
+
+  if (Math.abs(ndy) >= Math.abs(ndx)) {
+    // Target is more above/below than left/right → use top or bottom edge
+    return ndy < 0
+      ? { x: boxCenterX, y: box.y } // top
+      : { x: boxCenterX, y: box.y + box.height }; // bottom
+  }
+  // Target is more left/right → use left or right edge
+  return ndx < 0
+    ? { x: box.x, y: boxCenterY } // left
+    : { x: box.x + box.width, y: boxCenterY }; // right
+}
+
+/** Estimate the bounding box of an annotation label. */
+export function estimateLabelBounds(label: ResolvedLabel): Rect {
+  const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+  const fontWeight = label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+  return computeTextBounds(label.x, label.y, label.text, fontSize, fontWeight);
+}
+
+/**
+ * Recompute the connector origin for a label after it has been repositioned.
+ * Encapsulates the pattern of recalculating which edge of the text box the
+ * connector should exit from based on the target data point.
+ */
+export function recomputeConnector(
+  label: ResolvedLabel,
+  targetX: number,
+  targetY: number,
+): ResolvedLabel['connector'] {
+  const connector = label.connector;
+  if (!connector) return connector;
+
+  const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+  const fontWeight = label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+  const connStyle = connector.style === 'curve' ? ('curve' as const) : ('straight' as const);
+  const newFrom = computeConnectorOrigin(
+    label.x,
+    label.y,
+    label.text,
+    fontSize,
+    fontWeight,
+    targetX,
+    targetY,
+    connStyle,
+  );
+  return { ...connector, from: newFrom };
+}

package/src/annotations/position.ts

@@ -0,0 +1,95 @@
+/**
+ * Data-coordinate to pixel-coordinate resolution for annotations.
+ */
+
+import type { ScaleBand, ScaleLinear, ScaleTime } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+
+/**
+ * Interpolate a numeric value between sorted domain entries.
+ * Used when an annotation references a value not present in a categorical domain
+ * (e.g. "2008" on an axis with data points at "2007" and "2009").
+ * Returns null if domain values aren't numeric or the domain is too small.
+ */
+export function interpolateInDomain(
+  numValue: number,
+  domain: string[],
+  positionOf: (entry: string) => number,
+): number | null {
+  if (domain.length < 2) return null;
+  const nums = domain.map(Number);
+  if (!nums.every(Number.isFinite)) return null;
+
+  // Sort by numeric value so bracket-finding works regardless of data order
+  const sorted = nums.map((n, i) => ({ n, i })).sort((a, b) => a.n - b.n);
+
+  // Find the two sorted neighbors that bracket this value
+  let lower = 0;
+  let upper = sorted.length - 1;
+  for (let i = 0; i < sorted.length; i++) {
+    if (sorted[i].n <= numValue) lower = i;
+    if (sorted[i].n >= numValue) {
+      upper = i;
+      break;
+    }
+  }
+
+  const lowerPos = positionOf(domain[sorted[lower].i]);
+  const upperPos = positionOf(domain[sorted[upper].i]);
+  if (lower === upper) return lowerPos;
+  const t = (numValue - sorted[lower].n) / (sorted[upper].n - sorted[lower].n);
+  return lowerPos + t * (upperPos - lowerPos);
+}
+
+/** Resolve a data value to a pixel position on a given axis. */
+export function resolvePosition(
+  value: string | number,
+  scale: ResolvedScales['x'] | ResolvedScales['y'],
+): number | null {
+  if (!scale) return null;
+
+  const s = scale.scale;
+  const type = scale.type;
+
+  if (type === 'time') {
+    const date = new Date(String(value));
+    if (Number.isNaN(date.getTime())) return null;
+    return (s as ScaleTime<number, number>)(date);
+  }
+
+  if (type === 'linear' || type === 'log') {
+    const num = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(num)) return null;
+    return (s as ScaleLinear<number, number>)(num);
+  }
+
+  if (type === 'band') {
+    const bandScale = s as ScaleBand<string>;
+    const strValue = String(value);
+    const pos = bandScale(strValue);
+    if (pos !== undefined) return pos + (bandScale.bandwidth?.() ?? 0) / 2;
+
+    const bw = bandScale.bandwidth?.() ?? 0;
+    return interpolateInDomain(
+      Number(strValue),
+      bandScale.domain(),
+      (entry) => (bandScale(entry) ?? 0) + bw / 2,
+    );
+  }
+
+  // point or ordinal: try direct lookup, fall back to interpolation
+  const strValue = String(value);
+  const directResult = (s as (v: string) => number | undefined)(strValue);
+  if (directResult !== undefined) return directResult;
+
+  if (type === 'point' || type === 'ordinal') {
+    const domain = (s as { domain(): string[] }).domain();
+    return interpolateInDomain(
+      Number(strValue),
+      domain,
+      (entry) => (s as (v: string) => number)(entry) ?? 0,
+    );
+  }
+
+  return null;
+}

package/src/annotations/resolve-range.ts

@@ -0,0 +1,98 @@
+/**
+ * Range annotation resolver: creates a highlighted rectangular band
+ * between two data values on x or y axis.
+ */
+
+import type {
+  RangeAnnotation,
+  Rect,
+  ResolvedAnnotation,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import type { ResolvedScales } from '../layout/scales';
+import { DEFAULT_RANGE_FILL, DEFAULT_RANGE_OPACITY } from './constants';
+import { applyOffset } from './geometry';
+import { resolvePosition } from './position';
+import { makeAnnotationLabelStyle } from './resolve-text';
+
+export function resolveRangeAnnotation(
+  annotation: RangeAnnotation,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  isDark: boolean,
+): ResolvedAnnotation | null {
+  let x = chartArea.x;
+  let y = chartArea.y;
+  let width = chartArea.width;
+  let height = chartArea.height;
+
+  // X-range (vertical band)
+  if (annotation.x1 !== undefined && annotation.x2 !== undefined) {
+    const x1px = resolvePosition(annotation.x1, scales.x);
+    const x2px = resolvePosition(annotation.x2, scales.x);
+    if (x1px === null || x2px === null) return null;
+
+    x = Math.min(x1px, x2px);
+    width = Math.abs(x2px - x1px);
+  }
+
+  // Y-range (horizontal band)
+  if (annotation.y1 !== undefined && annotation.y2 !== undefined) {
+    const y1px = resolvePosition(annotation.y1, scales.y);
+    const y2px = resolvePosition(annotation.y2, scales.y);
+    if (y1px === null || y2px === null) return null;
+
+    y = Math.min(y1px, y2px);
+    height = Math.abs(y2px - y1px);
+  }
+
+  const rect: Rect = { x, y, width, height };
+
+  // Label positioned within the range, with optional offset.
+  // labelAnchor controls horizontal placement:
+  //   "top" (default): horizontally centered, text-anchor middle
+  //   "left": left edge, text-anchor start
+  //   "right": right edge, text-anchor end
+  //   "bottom"/"auto": horizontally centered, text-anchor middle
+  let label: ResolvedLabel | undefined;
+  if (annotation.label) {
+    const anchor = annotation.labelAnchor ?? 'top';
+    const centered = anchor === 'top' || anchor === 'bottom' || anchor === 'auto';
+    const baseDx = centered ? 0 : anchor === 'right' ? -4 : 4;
+    const baseDy = 14;
+    const labelDelta = applyOffset({ dx: baseDx, dy: baseDy }, annotation.labelOffset);
+
+    const style = makeAnnotationLabelStyle(11, 500, undefined, isDark);
+    if (centered) {
+      style.textAnchor = 'middle';
+    } else if (anchor === 'right') {
+      style.textAnchor = 'end';
+    }
+
+    // Position label horizontally centered within the range band by default.
+    // For left/right anchors, position at the respective edge.
+    const baseX = centered ? x + width / 2 : anchor === 'right' ? x + width : x;
+
+    label = {
+      text: annotation.label,
+      x: baseX + labelDelta.dx,
+      y: y + labelDelta.dy,
+      style,
+      visible: true,
+    };
+  }
+
+  // In dark mode, boost range opacity slightly for better visibility
+  const defaultOpacity = isDark ? 0.2 : DEFAULT_RANGE_OPACITY;
+
+  return {
+    type: 'range',
+    id: annotation.id,
+    rect,
+    label,
+    fill: annotation.fill ?? DEFAULT_RANGE_FILL,
+    opacity: annotation.opacity ?? defaultOpacity,
+    stroke: annotation.stroke,
+    zIndex: annotation.zIndex,
+  };
+}

package/src/annotations/resolve-refline.ts

@@ -0,0 +1,148 @@
+/**
+ * Reference line annotation resolver: creates a horizontal or vertical
+ * reference line at a data value with optional label.
+ */
+
+import type {
+  Point,
+  Rect,
+  RefLineAnnotation,
+  ResolvedAnnotation,
+  ResolvedLabel,
+} from '@opendata-ai/openchart-core';
+import type { ResolvedScales } from '../layout/scales';
+import { DARK_REFLINE_STROKE, DEFAULT_REFLINE_DASH, LIGHT_REFLINE_STROKE } from './constants';
+import { applyOffset } from './geometry';
+import { resolvePosition } from './position';
+import { makeAnnotationLabelStyle } from './resolve-text';
+
+export function resolveRefLineAnnotation(
+  annotation: RefLineAnnotation,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  isDark: boolean,
+): ResolvedAnnotation | null {
+  let start: Point;
+  let end: Point;
+
+  if (annotation.y !== undefined) {
+    // Horizontal reference line
+    const yPx = resolvePosition(annotation.y, scales.y);
+    if (yPx === null) return null;
+
+    start = { x: chartArea.x, y: yPx };
+    end = { x: chartArea.x + chartArea.width, y: yPx };
+  } else if (annotation.x !== undefined) {
+    // Vertical reference line
+    const xPx = resolvePosition(annotation.x, scales.x);
+    if (xPx === null) return null;
+
+    start = { x: xPx, y: chartArea.y };
+    end = { x: xPx, y: chartArea.y + chartArea.height };
+  } else {
+    return null;
+  }
+
+  // Determine dash pattern from style
+  let strokeDasharray: string | undefined;
+  if (annotation.style === 'dashed' || annotation.style === undefined) {
+    strokeDasharray = DEFAULT_REFLINE_DASH;
+  } else if (annotation.style === 'dotted') {
+    strokeDasharray = '2 2';
+  }
+  // 'solid' gets no dasharray
+
+  // Label placement on reflines. labelAnchor controls position:
+  //
+  // Horizontal reflines (y set):
+  //   "left":   left end of line, above        "right"/"top" (default): right end, above
+  //   "bottom": right end of line, below
+  //
+  // Vertical reflines (x set):
+  //   "right": label to the left of the line, near top
+  //   "bottom": label to the right of the line, near bottom
+  //   "left"/"top" (default): label to the right of the line, near top
+  let label: ResolvedLabel | undefined;
+  if (annotation.label) {
+    const isHorizontal = annotation.y !== undefined;
+    const anchor = annotation.labelAnchor ?? (isHorizontal ? 'top' : 'left');
+
+    let baseDx: number;
+    let baseDy: number;
+    let labelX: number;
+    let labelY: number;
+    let textAnchor: 'start' | 'middle' | 'end';
+
+    if (isHorizontal) {
+      if (anchor === 'left') {
+        baseDx = 4;
+        baseDy = -4;
+        labelX = start.x;
+        labelY = start.y;
+        textAnchor = 'start';
+      } else if (anchor === 'bottom') {
+        baseDx = -4;
+        baseDy = 14;
+        labelX = end.x;
+        labelY = end.y;
+        textAnchor = 'end';
+      } else {
+        // 'right', 'top' (default), 'auto'
+        baseDx = -4;
+        baseDy = -4;
+        labelX = end.x;
+        labelY = end.y;
+        textAnchor = 'end';
+      }
+    } else {
+      // Vertical refline
+      if (anchor === 'right') {
+        baseDx = -4;
+        baseDy = 14;
+        labelX = start.x;
+        labelY = start.y;
+        textAnchor = 'end';
+      } else if (anchor === 'bottom') {
+        baseDx = 4;
+        baseDy = -4;
+        labelX = start.x;
+        labelY = end.y;
+        textAnchor = 'start';
+      } else {
+        // 'left', 'top' (default), 'auto' — label to the right of the line, near top
+        baseDx = 4;
+        baseDy = 14;
+        labelX = start.x;
+        labelY = start.y;
+        textAnchor = 'start';
+      }
+    }
+
+    const labelDelta = applyOffset({ dx: baseDx, dy: baseDy }, annotation.labelOffset);
+
+    const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
+    const style = makeAnnotationLabelStyle(11, 400, annotation.stroke ?? defaultStroke, isDark);
+    style.textAnchor = textAnchor;
+
+    label = {
+      text: annotation.label,
+      x: labelX + labelDelta.dx,
+      y: labelY + labelDelta.dy,
+      style,
+      visible: true,
+    };
+  }
+
+  const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
+
+  return {
+    type: 'refline',
+    id: annotation.id,
+    line: { start, end },
+    label,
+    stroke: annotation.stroke ?? defaultStroke,
+    strokeDasharray,
+    strokeWidth: annotation.strokeWidth ?? 1,
+    zIndex: annotation.zIndex,
+  };
+}

package/src/annotations/resolve-text.ts

@@ -0,0 +1,134 @@
+/**
+ * Text annotation resolver: positions a label at data coordinates with an
+ * optional callout connector to the data point.
+ */
+
+import type {
+  Rect,
+  ResolvedAnnotation,
+  ResolvedLabel,
+  TextAnnotation,
+  TextStyle,
+} from '@opendata-ai/openchart-core';
+import type { ResolvedScales } from '../layout/scales';
+import {
+  DARK_TEXT_FILL,
+  DEFAULT_ANNOTATION_FONT_SIZE,
+  DEFAULT_ANNOTATION_FONT_WEIGHT,
+  DEFAULT_LINE_HEIGHT,
+  LIGHT_TEXT_FILL,
+} from './constants';
+import { applyOffset, computeAnchorOffset, computeConnectorOrigin } from './geometry';
+import { resolvePosition } from './position';
+
+export function makeAnnotationLabelStyle(
+  fontSize?: number,
+  fontWeight?: number,
+  fill?: string,
+  isDark?: boolean,
+): TextStyle {
+  const defaultFill = isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL;
+  return {
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSize: fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE,
+    fontWeight: fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT,
+    fill: fill ?? defaultFill,
+    lineHeight: DEFAULT_LINE_HEIGHT,
+    textAnchor: 'start',
+  };
+}
+
+export function resolveTextAnnotation(
+  annotation: TextAnnotation,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  isDark: boolean,
+): ResolvedAnnotation | null {
+  const px = resolvePosition(annotation.x, scales.x);
+  const py = resolvePosition(annotation.y, scales.y);
+
+  if (px === null || py === null) return null;
+
+  const defaultTextFill = isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL;
+  const labelStyle = makeAnnotationLabelStyle(
+    annotation.fontSize,
+    annotation.fontWeight,
+    annotation.fill ?? defaultTextFill,
+    isDark,
+  );
+
+  // Compute position from anchor direction + user offset
+  const anchorDelta = computeAnchorOffset(annotation.anchor, px, py, chartArea);
+  const finalDelta = applyOffset(anchorDelta, annotation.offset);
+
+  const labelX = px + finalDelta.dx;
+  const labelY = py + finalDelta.dy;
+
+  // Connector: draw unless explicitly disabled
+  const showConnector = annotation.connector !== false;
+  const connectorStyle = annotation.connector === 'curve' ? 'curve' : 'straight';
+
+  // Compute connector origin: pick the edge midpoint closest to the data point
+  const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+  const fontWeight = annotation.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+  const { x: connectorFromX, y: connectorFromY } = computeConnectorOrigin(
+    labelX,
+    labelY,
+    annotation.text,
+    fontSize,
+    fontWeight,
+    px,
+    py,
+    connectorStyle,
+  );
+
+  // Apply user-provided connector endpoint offsets
+  const baseFrom = { x: connectorFromX, y: connectorFromY };
+  const baseTo = { x: px, y: py };
+  const adjustedFrom = {
+    x: baseFrom.x + (annotation.connectorOffset?.from?.dx ?? 0),
+    y: baseFrom.y + (annotation.connectorOffset?.from?.dy ?? 0),
+  };
+  const adjustedToRaw = {
+    x: baseTo.x + (annotation.connectorOffset?.to?.dx ?? 0),
+    y: baseTo.y + (annotation.connectorOffset?.to?.dy ?? 0),
+  };
+
+  // Pull the "to" endpoint back along the connector direction so the
+  // line doesn't touch the data point directly (leaves a small gap).
+  const GAP = 4;
+  const cdx = adjustedToRaw.x - adjustedFrom.x;
+  const cdy = adjustedToRaw.y - adjustedFrom.y;
+  const dist = Math.sqrt(cdx * cdx + cdy * cdy);
+  const adjustedTo =
+    dist > GAP * 2
+      ? { x: adjustedToRaw.x - (cdx / dist) * GAP, y: adjustedToRaw.y - (cdy / dist) * GAP }
+      : adjustedToRaw;
+
+  const label: ResolvedLabel = {
+    text: annotation.text,
+    x: labelX,
+    y: labelY,
+    style: labelStyle,
+    visible: true,
+    connector: showConnector
+      ? {
+          from: adjustedFrom,
+          to: adjustedTo,
+          stroke: annotation.stroke ?? '#999999',
+          style: connectorStyle,
+        }
+      : undefined,
+    background: annotation.background,
+  };
+
+  return {
+    type: 'text',
+    id: annotation.id,
+    label,
+    stroke: annotation.stroke,
+    fill: annotation.fill,
+    opacity: annotation.opacity,
+    zIndex: annotation.zIndex,
+  };
+}