@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/annotations/position.ts

@@ -0,0 +1,131 @@
+/**
+ * Data-coordinate to pixel-coordinate resolution for annotations.
+ */
+
+import type { ScaleBand, ScaleLinear, ScalePoint, 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;
+}
+
+/**
+ * Like resolvePosition, but extends the result to the visual edge of the column
+ * for band and point scales. Used by range annotations to span complete columns.
+ *
+ * For point scales: shifts by ±step/2 using scalePoint.step()
+ * For band scales: shifts from center (what resolvePosition returns) to the band edge
+ * For all other scales: identical to resolvePosition
+ */
+export function resolvePositionEdge(
+  value: string | number,
+  scale: ResolvedScales['x'] | ResolvedScales['y'],
+  edge: 'start' | 'end',
+): number | null {
+  const center = resolvePosition(value, scale);
+  if (center === null || !scale) return null;
+
+  const type = scale.type;
+
+  if (type === 'point') {
+    const s = scale.scale as ScalePoint<string>;
+    const halfStep = (s.step?.() ?? 0) / 2;
+    return edge === 'start' ? center - halfStep : center + halfStep;
+  }
+
+  if (type === 'band') {
+    // center = bandStart + bandwidth/2
+    // edge 'start' => bandStart   = center - bandwidth/2
+    // edge 'end'   => bandEnd     = center + bandwidth/2
+    const s = scale.scale as ScaleBand<string>;
+    const halfBw = (s.bandwidth?.() ?? 0) / 2;
+    return edge === 'start' ? center - halfBw : center + halfBw;
+  }
+
+  return center;
+}

package/src/annotations/resolve-range.ts

@@ -0,0 +1,117 @@
+/**
+ * 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, resolvePositionEdge } from './position';
+import { makeAnnotationLabelStyle } from './resolve-text';
+
+export function resolveRangeAnnotation(
+  annotation: RangeAnnotation,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  isDark: boolean,
+  fontFamily?: string,
+): ResolvedAnnotation | null {
+  let x = chartArea.x;
+  let y = chartArea.y;
+  let width = chartArea.width;
+  let height = chartArea.height;
+
+  // When extendToEdges is false, anchor at the data point's exact position
+  // (band/point center) instead of extending to the band/step edge. This insets
+  // the range from the axis so it starts at the first data point rather than
+  // flush against the axis guide. No effect on linear/time scales.
+  const extend = annotation.extendToEdges !== false;
+  const resolveEdge = (
+    value: string | number,
+    scale: typeof scales.x,
+    edge: 'start' | 'end',
+  ): number | null =>
+    extend ? resolvePositionEdge(value, scale, edge) : resolvePosition(value, scale);
+
+  // X-range (vertical band)
+  if (annotation.x1 !== undefined && annotation.x2 !== undefined) {
+    const x1px = resolveEdge(annotation.x1, scales.x, 'start');
+    const x2px = resolveEdge(annotation.x2, scales.x, 'end');
+    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 = resolveEdge(annotation.y1, scales.y, 'end');
+    const y2px = resolveEdge(annotation.y2, scales.y, 'start');
+    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(
+      annotation.fontSize ?? 11,
+      annotation.fontWeight ?? 500,
+      undefined,
+      isDark,
+      fontFamily,
+    );
+    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,157 @@
+/**
+ * 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,
+  fontFamily?: string,
+): 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: strokeDash array wins, then style string
+  let strokeDasharray: string | undefined;
+  if (annotation.strokeDash && annotation.strokeDash.length > 0) {
+    strokeDasharray = annotation.strokeDash.join(' ');
+  } else 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(
+      annotation.fontSize ?? 11,
+      annotation.fontWeight ?? 400,
+      annotation.stroke ?? defaultStroke,
+      isDark,
+      fontFamily,
+    );
+    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,
+  };
+}