@opendata-ai/openchart-vanilla 6.19.3 → 6.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-vanilla",
-  "version": "6.19.3",
+  "version": "6.21.0",
   "description": "Vanilla JS renderer for openchart: SVG charts, HTML tables, force-directed graphs",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -50,8 +50,8 @@
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",
-    "@opendata-ai/openchart-core": "6.19.3",
-    "@opendata-ai/openchart-engine": "6.19.3",
+    "@opendata-ai/openchart-core": "6.21.0",
+    "@opendata-ai/openchart-engine": "6.21.0",
     "d3-force": "^3.0.0",
     "d3-quadtree": "^3.0.1"
   },

package/src/__tests__/gradient-ids.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Multi-chart SVG ID uniqueness: gradients AND clip-paths.
+ *
+ * Originally locked gradient-counter behavior from commit 73ef048 (fix for
+ * random-hex gradient collisions). Step 6 of refactor/v7-cohesion unified
+ * gradient and clip-path ID generation under `nextSvgId` in `svg-ids.ts`,
+ * so this test now guards both halves.
+ *
+ * Why it matters: SVG `url(#id)` resolves against the full document. If two
+ * charts on the same page generate overlapping IDs, one chart silently
+ * inherits the other's gradient fill or clip region. The shared monotonic
+ * counter makes uniqueness unconditional.
+ */
+
+import type { ChartSpec, LinearGradient } from '@opendata-ai/openchart-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createContainer } from '../__test-fixtures__/dom';
+import { createChart } from '../mount';
+
+const barGradient: LinearGradient = {
+  gradient: 'linear',
+  x1: 0,
+  y1: 0,
+  x2: 1,
+  y2: 0,
+  stops: [
+    { offset: 0, color: '#1b7fa3', opacity: 0.4 },
+    { offset: 1, color: '#1b7fa3' },
+  ],
+};
+
+// A visibly different gradient so charts have distinct gradient defs, not
+// identical ones that could be deduped by the gradient key system.
+const altGradient: LinearGradient = {
+  gradient: 'linear',
+  x1: 0,
+  y1: 0,
+  x2: 1,
+  y2: 0,
+  stops: [
+    { offset: 0, color: '#cc3366', opacity: 0.2 },
+    { offset: 1, color: '#cc3366' },
+  ],
+};
+
+function makeBarSpec(fill: LinearGradient): ChartSpec {
+  return {
+    mark: { type: 'bar', fill },
+    data: [
+      { category: 'A', value: 10 },
+      { category: 'B', value: 20 },
+      { category: 'C', value: 30 },
+    ],
+    encoding: {
+      x: { field: 'value', type: 'quantitative' },
+      y: { field: 'category', type: 'nominal' },
+    },
+  };
+}
+
+function collectGradientIds(root: HTMLElement): string[] {
+  const ids: string[] = [];
+  for (const el of root.querySelectorAll('linearGradient, radialGradient')) {
+    const id = el.getAttribute('id');
+    if (id) ids.push(id);
+  }
+  return ids;
+}
+
+function collectClipPathIds(root: HTMLElement): string[] {
+  const ids: string[] = [];
+  for (const el of root.querySelectorAll('clipPath')) {
+    const id = el.getAttribute('id');
+    if (id) ids.push(id);
+  }
+  return ids;
+}
+
+describe('SVG ID uniqueness across charts', () => {
+  let a: HTMLDivElement;
+  let b: HTMLDivElement;
+
+  beforeEach(() => {
+    a = createContainer();
+    b = createContainer();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('two charts produce disjoint gradient IDs', () => {
+    const chartA = createChart(a, makeBarSpec(barGradient));
+    const chartB = createChart(b, makeBarSpec(altGradient));
+
+    const idsA = collectGradientIds(a);
+    const idsB = collectGradientIds(b);
+
+    // Each chart must have produced at least one gradient def.
+    expect(idsA.length).toBeGreaterThan(0);
+    expect(idsB.length).toBeGreaterThan(0);
+
+    // Union has no duplicates: size of the Set equals the total count.
+    const all = [...idsA, ...idsB];
+    expect(new Set(all).size).toBe(all.length);
+
+    // Every generated id follows the locked "oc-grad-N" shape.
+    for (const id of all) {
+      expect(id).toMatch(/^oc-grad-\d+$/);
+    }
+
+    chartA.destroy();
+    chartB.destroy();
+  });
+
+  it('two charts produce disjoint clip-path IDs', () => {
+    // Every chart render creates a <clipPath> for the plot area, so any spec
+    // works here. Reuse the gradient specs for consistency.
+    const chartA = createChart(a, makeBarSpec(barGradient));
+    const chartB = createChart(b, makeBarSpec(altGradient));
+
+    const idsA = collectClipPathIds(a);
+    const idsB = collectClipPathIds(b);
+
+    expect(idsA.length).toBeGreaterThan(0);
+    expect(idsB.length).toBeGreaterThan(0);
+
+    const all = [...idsA, ...idsB];
+    expect(new Set(all).size).toBe(all.length);
+
+    for (const id of all) {
+      expect(id).toMatch(/^oc-clip-\d+$/);
+    }
+
+    chartA.destroy();
+    chartB.destroy();
+  });
+
+  it('gradient and clip-path IDs never collide across two charts', () => {
+    // Core guarantee of the unified nextSvgId counter: even though gradients
+    // and clip-paths use different prefixes, the counter values are shared.
+    // Collecting every ID from both <defs> trees should yield a strict set.
+    const chartA = createChart(a, makeBarSpec(barGradient));
+    const chartB = createChart(b, makeBarSpec(altGradient));
+
+    const all = [
+      ...collectGradientIds(a),
+      ...collectClipPathIds(a),
+      ...collectGradientIds(b),
+      ...collectClipPathIds(b),
+    ];
+
+    expect(all.length).toBeGreaterThan(0);
+    expect(new Set(all).size).toBe(all.length);
+
+    chartA.destroy();
+    chartB.destroy();
+  });
+});

package/src/__tests__/resize-timing.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Resize timing behavior.
+ *
+ * These tests verify that:
+ * 1. The inner observer's 16ms debounce coalesces a rapid burst of
+ *    ResizeObserver entries into a single render (no thrash).
+ * 2. First ResizeObserver fire does not blank-flash (SVG stays mounted).
+ * 3. Resize events during an entrance animation are deferred and replayed
+ *    on animation end.
+ *
+ * happy-dom ships a ResizeObserver stub that does not auto-fire on layout,
+ * so we override it with a controllable mock that lets us invoke the
+ * observer callback synchronously.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createContainer } from '../__test-fixtures__/dom';
+import { lineSpec } from '../__test-fixtures__/specs';
+import { createChart } from '../mount';
+
+// ---------------------------------------------------------------------------
+// Controllable ResizeObserver mock
+// ---------------------------------------------------------------------------
+
+type ObserverCallback = (entries: ResizeObserverEntry[]) => void;
+
+interface FakeObserver {
+  element: Element | null;
+  callback: ObserverCallback;
+  disconnected: boolean;
+}
+
+const observers: FakeObserver[] = [];
+
+class MockResizeObserver {
+  private readonly record: FakeObserver;
+
+  constructor(callback: ObserverCallback) {
+    this.record = { element: null, callback, disconnected: false };
+    observers.push(this.record);
+  }
+
+  observe(element: Element): void {
+    this.record.element = element;
+  }
+
+  disconnect(): void {
+    this.record.disconnected = true;
+  }
+
+  unobserve(): void {
+    // no-op
+  }
+}
+
+/** Fire a ResizeObserver callback for the given element with width/height. */
+function fireResize(element: Element, width: number, height: number): void {
+  for (const o of observers) {
+    if (o.element === element && !o.disconnected) {
+      const entry = {
+        contentRect: { width, height, top: 0, left: 0, right: width, bottom: height, x: 0, y: 0 },
+        target: element,
+      } as unknown as ResizeObserverEntry;
+      o.callback([entry]);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('chart resize timing', () => {
+  let container: HTMLDivElement;
+  let originalRO: typeof globalThis.ResizeObserver;
+
+  beforeEach(() => {
+    observers.length = 0;
+    originalRO = globalThis.ResizeObserver;
+    // Use MockResizeObserver so tests can drive observer fires deterministically.
+    // Cast via unknown to satisfy the stricter ResizeObserver type.
+    globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+    vi.useFakeTimers();
+    container = createContainer();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    globalThis.ResizeObserver = originalRO;
+    document.body.innerHTML = '';
+  });
+
+  it('coalesces a rapid burst of resize events into a single render', async () => {
+    const chart = createChart(container, lineSpec);
+    const initialSvg = container.querySelector('svg');
+    expect(initialSvg).not.toBeNull();
+
+    // Track SVG node identity across renders: each render() replaces the SVG,
+    // so counting how many distinct SVG nodes appear tells us how many renders ran.
+    let renderCount = 0;
+    const mo = new MutationObserver((records) => {
+      for (const r of records) {
+        for (let i = 0; i < r.addedNodes.length; i++) {
+          const node = r.addedNodes[i];
+          if (node instanceof Element && node.tagName.toLowerCase() === 'svg') {
+            renderCount++;
+          }
+        }
+      }
+    });
+    mo.observe(container, { childList: true });
+
+    // Fire 20 resize events within a tight window.
+    for (let i = 0; i < 20; i++) {
+      fireResize(container, 600 + i, 400);
+    }
+
+    // Before the debounce window elapses, no new SVG has been appended.
+    expect(renderCount).toBe(0);
+
+    // Run all pending timers (16ms inner debounce + any outer delay).
+    await vi.runAllTimersAsync();
+
+    // MutationObserver records are delivered as microtasks; flush them.
+    mo.takeRecords().forEach((r) => {
+      for (let i = 0; i < r.addedNodes.length; i++) {
+        const node = r.addedNodes[i];
+        if (node instanceof Element && node.tagName.toLowerCase() === 'svg') {
+          renderCount++;
+        }
+      }
+    });
+
+    // Exactly one re-render should have run for the whole burst (no thrash).
+    expect(renderCount).toBe(1);
+
+    mo.disconnect();
+    chart.destroy();
+  });
+
+  it('does not blank-flash: SVG remains mounted through first observer fire', async () => {
+    const chart = createChart(container, lineSpec);
+
+    // SVG is painted immediately on mount, before the observer fires.
+    const svgBefore = container.querySelector('svg');
+    expect(svgBefore).not.toBeNull();
+
+    // Fire the observer as it would on first layout.
+    fireResize(container, 600, 400);
+
+    // Even before the debounce elapses, the SVG must still be in the DOM.
+    expect(container.querySelector('svg')).not.toBeNull();
+
+    // And after timers flush, the SVG is still there (possibly a new node).
+    await vi.runAllTimersAsync();
+    expect(container.querySelector('svg')).not.toBeNull();
+
+    chart.destroy();
+  });
+
+  it('disconnects the observer on destroy', () => {
+    const chart = createChart(container, lineSpec);
+    expect(observers.length).toBe(1);
+    expect(observers[0].disconnected).toBe(false);
+
+    chart.destroy();
+
+    expect(observers[0].disconnected).toBe(true);
+  });
+
+  it('clears any pending resize timer on destroy (no callback after teardown)', async () => {
+    const chart = createChart(container, lineSpec);
+
+    fireResize(container, 700, 500);
+    // Destroy before the debounce elapses.
+    chart.destroy();
+
+    await vi.runAllTimersAsync();
+
+    // destroy() removes the SVG; if the timer fired after destroy it would
+    // try to render a new one. No SVG should be present.
+    expect(container.querySelector('svg')).toBeNull();
+  });
+});

package/src/gradient-utils.ts

@@ -5,6 +5,7 @@
 
 import type { GradientDef, LinearGradient, RadialGradient } from '@opendata-ai/openchart-core';
 import { isGradientDef } from '@opendata-ai/openchart-core';
+import { nextSvgId } from './svg-ids';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
 
@@ -89,18 +90,15 @@ function appendStop(
   parent.appendChild(stopEl);
 }
 
-/**
- * Global counter for gradient IDs. Ensures uniqueness across all charts
- * on the same page, since SVG url(#id) resolves globally in the document.
- */
-let globalGradientCounter = 0;
-
 /**
  * Scan all marks for GradientDef fill values, create SVG gradient elements
  * in the provided <defs> node, and return a map from gradient key to element ID.
  *
  * Identical gradients (by key) share a single SVG element within one chart.
- * IDs are globally unique across charts to avoid SVG url(#id) collisions.
+ * IDs come from `nextSvgId` so they're globally unique across charts and
+ * share the counter with clip-path IDs (see svg-ids.ts). Gradient ID numbers
+ * may skip values when clip-paths consume counter slots - still monotonic,
+ * still unique.
  */
 export function buildGradientDefs(
   marks: Array<{ fill?: unknown }>,
@@ -113,7 +111,7 @@ export function buildGradientDefs(
     if (fill && isGradientDef(fill)) {
       const key = gradientKey(fill);
       if (!map.has(key)) {
-        const id = `oc-grad-${globalGradientCounter++}`;
+        const id = nextSvgId('oc-grad');
         const el = createGradientElement(fill, id);
         defs.appendChild(el);
         map.set(key, id);

package/src/mount.ts

@@ -1798,7 +1798,6 @@ export function createChart(
   let destroyed = false;
   let isDragging = false;
   let pendingRender = false;
-  let resizeTimer: ReturnType<typeof setTimeout> | null = null;
 
   // Animation state
   let isFirstRender = true;
@@ -2393,10 +2392,6 @@ export function createChart(
     }
     cancelAnimations(svgElement);
 
-    if (resizeTimer !== null) {
-      clearTimeout(resizeTimer);
-      resizeTimer = null;
-    }
     if (cleanupTooltipEvents) {
       cleanupTooltipEvents();
       cleanupTooltipEvents = null;
@@ -2463,14 +2458,12 @@ export function createChart(
   // Initial render
   render();
 
-  // Set up responsive resize with debounce to avoid full SVG rebuild on every frame
+  // Set up responsive resize. The observeResize helper already debounces at
+  // ~60fps (16ms) internally, which is sufficient to coalesce a drag-burst
+  // into a single render without additive delay.
   if (options?.responsive !== false) {
     disconnectResize = observeResize(container, () => {
-      if (resizeTimer !== null) clearTimeout(resizeTimer);
-      resizeTimer = setTimeout(() => {
-        resizeTimer = null;
-        resize();
-      }, 100);
+      resize();
     });
   }
 

package/src/renderers/annotations.ts

@@ -0,0 +1,212 @@
+/**
+ * Annotation rendering: range rects, reference lines, labels with connectors.
+ */
+
+import type { ChartLayout, Point, ResolvedAnnotation } from '@opendata-ai/openchart-core';
+import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
+
+/**
+ * Render a curved arrow connector from a label to a data point.
+ * Uses a cubic bezier that sweeps outward then curves toward the
+ * target, with a triangular arrowhead at the tip.
+ */
+function renderCurvedArrow(parent: SVGElement, from: Point, to: Point, stroke: string): void {
+  // Pad above the target so the arrow doesn't sit right on the element.
+  const pad = 6;
+  const tipY = to.y - pad;
+
+  const dy = tipY - from.y;
+  const dist = Math.sqrt((to.x - from.x) ** 2 + dy ** 2) || 1;
+
+  // Arrowhead geometry
+  const arrowLen = 8;
+  const arrowWidth = 4;
+
+  // cp2 directly above target so arrow arrives pointing straight down.
+  const bulge = Math.max(dist * 0.4, 35);
+  const cp1x = from.x + bulge;
+  const cp1y = from.y + dy * 0.35;
+  const cp2x = to.x;
+  const cp2y = tipY - Math.abs(dy) * 0.25;
+
+  // Tangent at the tip (from cp2 → tip), used for arrowhead direction.
+  const tx = to.x - cp2x;
+  const ty = tipY - cp2y;
+  const tLen = Math.sqrt(tx * tx + ty * ty) || 1;
+  const ux = tx / tLen;
+  const uy = ty / tLen;
+
+  // End the curve path at the arrowhead BASE so the stroke doesn't
+  // poke through the filled triangle.
+  const baseX = to.x - ux * arrowLen;
+  const baseY = tipY - uy * arrowLen;
+
+  const path = createSVGElement('path');
+  path.setAttribute('class', 'oc-annotation-connector');
+  setAttrs(path, {
+    d: `M ${from.x} ${from.y} C ${cp1x} ${cp1y}, ${cp2x} ${cp2y}, ${baseX} ${baseY}`,
+    fill: 'none',
+    stroke,
+    'stroke-width': 1.5,
+  });
+  parent.appendChild(path);
+
+  // Arrowhead triangle: perpendicular to tangent direction.
+  const px = -uy;
+  const py = ux;
+
+  const arrow = createSVGElement('polygon');
+  arrow.setAttribute('class', 'oc-annotation-connector');
+  setAttrs(arrow, {
+    points: [
+      `${to.x},${tipY}`,
+      `${baseX + px * arrowWidth},${baseY + py * arrowWidth}`,
+      `${baseX - px * arrowWidth},${baseY - py * arrowWidth}`,
+    ].join(' '),
+    fill: stroke,
+  });
+  parent.appendChild(arrow);
+}
+
+function renderAnnotation(
+  parent: SVGElement,
+  annotation: ResolvedAnnotation,
+  index: number,
+  bgColor?: string,
+): void {
+  const g = createSVGElement('g');
+  g.setAttribute('class', `oc-annotation oc-annotation-${annotation.type}`);
+  g.setAttribute('data-annotation-index', String(index));
+  if (annotation.id) {
+    g.setAttribute('data-annotation-id', annotation.id);
+  }
+
+  // Range rect
+  if (annotation.rect) {
+    const rect = createSVGElement('rect');
+    rect.setAttribute('class', 'oc-annotation-range');
+    setAttrs(rect, {
+      x: annotation.rect.x,
+      y: annotation.rect.y,
+      width: annotation.rect.width,
+      height: annotation.rect.height,
+    });
+    if (annotation.fill) rect.setAttribute('fill', annotation.fill);
+    if (annotation.opacity !== undefined) {
+      rect.setAttribute('fill-opacity', String(annotation.opacity));
+    }
+    g.appendChild(rect);
+  }
+
+  // Reference line
+  if (annotation.line) {
+    const line = createSVGElement('line');
+    line.setAttribute('class', 'oc-annotation-line');
+    setAttrs(line, {
+      x1: annotation.line.start.x,
+      y1: annotation.line.start.y,
+      x2: annotation.line.end.x,
+      y2: annotation.line.end.y,
+      'stroke-width': annotation.strokeWidth ?? 1,
+    });
+    if (annotation.stroke) line.setAttribute('stroke', annotation.stroke);
+    if (annotation.strokeDasharray) {
+      line.setAttribute('stroke-dasharray', annotation.strokeDasharray);
+    }
+    g.appendChild(line);
+  }
+
+  // Label with optional connector line
+  if (annotation.label?.visible) {
+    // Render connector first (behind the label text)
+    if (annotation.label.connector) {
+      const c = annotation.label.connector;
+      if (c.style === 'curve') {
+        renderCurvedArrow(g, c.from, c.to, c.stroke);
+      } else {
+        const connector = createSVGElement('line');
+        connector.setAttribute('class', 'oc-annotation-connector');
+        setAttrs(connector, {
+          x1: c.from.x,
+          y1: c.from.y,
+          x2: c.to.x,
+          y2: c.to.y,
+          stroke: c.stroke,
+          'stroke-width': 1,
+          'stroke-opacity': 0.5,
+        });
+        g.appendChild(connector);
+      }
+    }
+
+    const text = createSVGElement('text');
+    text.setAttribute('class', 'oc-annotation-label');
+    setAttrs(text, { x: annotation.label.x, y: annotation.label.y });
+    applyTextStyle(text, annotation.label.style);
+
+    const lines = annotation.label.text.split('\n');
+    const fontSize = annotation.label.style.fontSize ?? 12;
+    const lineHeight = fontSize * (annotation.label.style.lineHeight ?? 1.3);
+    const isMultiLine = lines.length > 1;
+
+    // Multi-line text uses center alignment for a cleaner look
+    if (isMultiLine) {
+      text.setAttribute('text-anchor', 'middle');
+      for (let i = 0; i < lines.length; i++) {
+        const tspan = createSVGElement('tspan');
+        setAttrs(tspan, { x: annotation.label.x, dy: i === 0 ? 0 : lineHeight });
+        tspan.textContent = lines[i];
+        text.appendChild(tspan);
+      }
+    } else {
+      text.textContent = annotation.label.text;
+    }
+
+    // Render background rect behind text if specified, otherwise use
+    // paint-order stroke halo to knock out lines behind text
+    if (annotation.label.background) {
+      const charWidth = fontSize * 0.55;
+      const maxLineWidth = Math.max(...lines.map((l) => l.length)) * charWidth;
+      const totalHeight = lines.length * lineHeight;
+      const pad = 3;
+      const bgX = isMultiLine
+        ? annotation.label.x - maxLineWidth / 2 - pad
+        : annotation.label.x - pad;
+      const bgRect = createSVGElement('rect');
+      bgRect.setAttribute('class', 'oc-annotation-bg');
+      setAttrs(bgRect, {
+        x: bgX,
+        y: annotation.label.y - fontSize + (lineHeight - fontSize) / 2 - pad,
+        width: maxLineWidth + pad * 2,
+        height: totalHeight + pad * 2,
+        fill: annotation.label.background,
+        rx: 2,
+      });
+      g.appendChild(bgRect);
+    } else if (bgColor) {
+      text.style.paintOrder = 'stroke';
+      text.style.stroke = bgColor;
+      text.style.strokeWidth = `${Math.round(fontSize * 0.3)}px`;
+      text.style.strokeLinejoin = 'round';
+    }
+
+    g.appendChild(text);
+  }
+
+  parent.appendChild(g);
+}
+
+export function renderAnnotations(parent: SVGElement, layout: ChartLayout): void {
+  if (layout.annotations.length === 0) return;
+
+  const g = createSVGElement('g');
+  g.setAttribute('class', 'oc-annotations');
+
+  // Annotations are already sorted by zIndex from the engine, so render in order
+  const bgColor = layout.theme.colors.background;
+  for (let i = 0; i < layout.annotations.length; i++) {
+    renderAnnotation(g, layout.annotations[i], i, bgColor);
+  }
+
+  parent.appendChild(g);
+}