@opendata-ai/openchart-vanilla 6.19.2 → 6.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-vanilla",
-  "version": "6.19.2",
+  "version": "6.20.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.2",
-    "@opendata-ai/openchart-engine": "6.19.2",
+    "@opendata-ai/openchart-core": "6.20.0",
+    "@opendata-ai/openchart-engine": "6.20.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/sankey-renderer.ts

@@ -15,7 +15,12 @@ import type {
   SankeyNodeMark,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { BRAND_FONT_SIZE, BRAND_MIN_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
+import {
+  BRAND_FONT_SIZE,
+  BRAND_MIN_WIDTH,
+  estimateTextWidth,
+  wrapText,
+} from '@opendata-ai/openchart-core';
 import { clampStaggerDelay } from '@opendata-ai/openchart-engine';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
@@ -79,48 +84,6 @@ function stampAnimationAttrs(
 // Chrome rendering
 // ---------------------------------------------------------------------------
 
-/**
- * Break text into lines that fit within maxWidth using word wrapping.
- */
-function wrapText(text: string, fontSize: number, fontWeight: number, maxWidth: number): string[] {
-  if (maxWidth <= 0) return [text];
-
-  const AVG_CHAR_WIDTH = 0.57;
-  const WEIGHT_FACTORS: Record<number, number> = {
-    100: 0.9,
-    200: 0.92,
-    300: 0.95,
-    400: 1.0,
-    500: 1.02,
-    600: 1.05,
-    700: 1.08,
-    800: 1.1,
-    900: 1.12,
-  };
-  const weightFactor = WEIGHT_FACTORS[fontWeight] ?? 1.0;
-  const charWidth = fontSize * AVG_CHAR_WIDTH * weightFactor;
-  const maxChars = Math.floor(maxWidth / charWidth);
-
-  if (text.length <= maxChars) return [text];
-
-  const words = text.split(' ');
-  const lines: string[] = [];
-  let current = '';
-
-  for (const word of words) {
-    const candidate = current ? `${current} ${word}` : word;
-    if (candidate.length > maxChars && current) {
-      lines.push(current);
-      current = word;
-    } else {
-      current = candidate;
-    }
-  }
-  if (current) lines.push(current);
-
-  return lines;
-}
-
 function renderChromeElement(
   parent: SVGElement,
   element: ResolvedChromeElement,

package/src/svg-ids.ts

@@ -0,0 +1,18 @@
+/**
+ * Monotonic SVG ID generator shared by gradient and clipPath defs.
+ *
+ * Why a single counter: SVG `url(#id)` references resolve against the full
+ * document, so any ID collision (across charts on the same page) silently
+ * cross-wires one chart's fill/clip into another. Random-hex suffixes have a
+ * small-but-real collision probability that surfaced in production; a global
+ * monotonic counter makes uniqueness unconditional.
+ *
+ * Gradient and clip-path IDs share one counter so we can't regress one half of
+ * the system by accident. Consumers just pick a prefix.
+ */
+
+let counter = 0;
+
+export function nextSvgId(prefix: string): string {
+  return `${prefix}-${counter++}`;
+}

package/src/svg-renderer.ts

@@ -29,9 +29,15 @@ import type {
   TextStyle,
   TickMarkLayout,
 } from '@opendata-ai/openchart-core';
-import { BRAND_FONT_SIZE, BRAND_MIN_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
+import {
+  BRAND_FONT_SIZE,
+  BRAND_MIN_WIDTH,
+  estimateTextWidth,
+  wrapText,
+} from '@opendata-ai/openchart-core';
 import { clampStaggerDelay } from '@opendata-ai/openchart-engine';
 import { buildGradientDefs, resolveMarkFill } from './gradient-utils';
+import { nextSvgId } from './svg-ids';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
 
@@ -132,88 +138,6 @@ function applyTextStyle(el: SVGElement, style: TextStyle): void {
 // Chrome rendering
 // ---------------------------------------------------------------------------
 
-/**
- * Break text into lines that fit within maxWidth using word wrapping.
- * Uses a character-width heuristic (same as text-measure.ts).
- */
-function wrapText(
-  text: string,
-  fontSize: number,
-  fontWeight: number,
-  maxWidth: number,
-  measureText?: MeasureTextFn,
-): string[] {
-  if (maxWidth <= 0) return [text];
-
-  // Split on explicit newlines first
-  const segments = text.split('\n');
-  if (segments.length > 1) {
-    return segments.flatMap((segment) =>
-      segment.length === 0 ? [''] : wrapText(segment, fontSize, fontWeight, maxWidth, measureText),
-    );
-  }
-
-  // Use real text measurement when available
-  if (measureText) {
-    const textWidth = measureText(text, fontSize, fontWeight).width;
-    if (textWidth <= maxWidth) return [text];
-
-    const words = text.split(' ');
-    const lines: string[] = [];
-    let current = '';
-
-    for (const word of words) {
-      const candidate = current ? `${current} ${word}` : word;
-      const candidateWidth = measureText(candidate, fontSize, fontWeight).width;
-      if (candidateWidth > maxWidth && current) {
-        lines.push(current);
-        current = word;
-      } else {
-        current = candidate;
-      }
-    }
-    if (current) lines.push(current);
-
-    return lines;
-  }
-
-  // Heuristic character width matching text-measure.ts
-  const AVG_CHAR_WIDTH = 0.57;
-  const WEIGHT_FACTORS: Record<number, number> = {
-    100: 0.9,
-    200: 0.92,
-    300: 0.95,
-    400: 1.0,
-    500: 1.02,
-    600: 1.05,
-    700: 1.08,
-    800: 1.1,
-    900: 1.12,
-  };
-  const weightFactor = WEIGHT_FACTORS[fontWeight] ?? 1.0;
-  const charWidth = fontSize * AVG_CHAR_WIDTH * weightFactor;
-  const maxChars = Math.floor(maxWidth / charWidth);
-
-  if (text.length <= maxChars) return [text];
-
-  const words = text.split(' ');
-  const lines: string[] = [];
-  let current = '';
-
-  for (const word of words) {
-    const candidate = current ? `${current} ${word}` : word;
-    if (candidate.length > maxChars && current) {
-      lines.push(current);
-      current = word;
-    } else {
-      current = candidate;
-    }
-  }
-  if (current) lines.push(current);
-
-  return lines;
-}
-
 function renderChromeElement(
   parent: SVGElement,
   element: ResolvedChromeElement,
@@ -1321,7 +1245,7 @@ export function renderChartSVG(
   // Clip path to prevent marks (especially area fills) from overflowing
   // into the chrome region (title/subtitle). Extends full width so
   // end-of-line labels aren't clipped, but constrains vertically.
-  const clipId = `oc-clip-${Math.random().toString(36).slice(2, 8)}`;
+  const clipId = nextSvgId('oc-clip');
   const defs = createSVGElement('defs');
   const clipPath = createSVGElement('clipPath');
   clipPath.setAttribute('id', clipId);