@opendata-ai/openchart-vanilla 7.10.0 → 7.11.0

package/package.json

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

package/src/__test-fixtures__/dom.ts

@@ -29,6 +29,34 @@ export function createContainer(width = 600, height = 400): HTMLDivElement {
   return container;
 }
 
+/**
+ * Create an auto-height container: its measured height is 0 until a chart
+ * SVG is mounted, then tracks the SVG's own style.height — mimicking a real
+ * DOM container with no explicit height that wraps its content.
+ */
+export function createAutoHeightContainer(width = 390): HTMLDivElement {
+  const container = document.createElement('div');
+  Object.defineProperty(container, 'getBoundingClientRect', {
+    value: () => {
+      const svg = container.querySelector('svg');
+      const height = svg ? Number.parseFloat((svg as SVGElement).style.height) || 0 : 0;
+      return {
+        width,
+        height,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: height,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      };
+    },
+  });
+  document.body.appendChild(container);
+  return container;
+}
+
 /**
  * Create a MouseEvent with clientX/clientY coordinates.
  * happy-dom supports basic MouseEvent construction.

package/src/__test-fixtures__/specs.ts

@@ -31,6 +31,33 @@ export const lineSpec: ChartSpec = {
   },
 };
 
+/**
+ * Multi-series line with wrapping chrome and an explicit top legend — the
+ * mobile auto-height growth scenario (long title + subtitle + legend +
+ * source all stack above/below the plot).
+ */
+export const longChromeLineSpec: ChartSpec = {
+  mark: 'line',
+  data: [
+    { date: '2020-01-01', value: 10, country: 'US' },
+    { date: '2021-01-01', value: 40, country: 'US' },
+    { date: '2020-01-01', value: 15, country: 'UK' },
+    { date: '2021-01-01', value: 35, country: 'UK' },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' },
+    y: { field: 'value', type: 'quantitative' },
+    color: { field: 'country', type: 'nominal' },
+  },
+  legend: { show: true, position: 'top' },
+  chrome: {
+    title:
+      'An intentionally long editorial chart title that wraps to several lines at phone widths',
+    subtitle: 'A methodological subtitle that provides additional context for readers',
+    source: 'World Bank',
+  },
+};
+
 export const singleSeriesLineSpec: ChartSpec = {
   mark: 'line',
   data: [

package/src/__tests__/mount.test.ts

@@ -1,6 +1,13 @@
+import type { ChartLayout } from '@opendata-ai/openchart-core';
+import { legendGap } from '@opendata-ai/openchart-engine';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { createContainer } from '../__test-fixtures__/dom';
-import { barSpec, lineSpec } from '../__test-fixtures__/specs';
+import { createAutoHeightContainer, createContainer } from '../__test-fixtures__/dom';
+import {
+  barSpec,
+  lineSpec,
+  longChromeLineSpec,
+  singleSeriesLineSpec,
+} from '../__test-fixtures__/specs';
 import { createChart } from '../mount';
 
 // ---------------------------------------------------------------------------
@@ -236,3 +243,89 @@ describe('resize observer integration', () => {
     chart.destroy();
   });
 });
+
+describe('auto-height container growth', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  /** The chrome/legend/metrics blocks the mount grows the figure by. */
+  function overheadsOf(layout: ChartLayout, width: number): number {
+    const topLegendBlock =
+      layout.legend.position === 'top' &&
+      'entries' in layout.legend &&
+      layout.legend.entries.length > 0
+        ? layout.legend.bounds.height + legendGap(width)
+        : 0;
+    return (
+      layout.chrome.topHeight +
+      layout.chrome.bottomHeight +
+      topLegendBlock +
+      (layout.metrics?.height ?? 0)
+    );
+  }
+
+  it('grows the figure beyond the 400px budget by the measured overheads', () => {
+    const container = createAutoHeightContainer(390);
+    const chart = createChart(container, longChromeLineSpec);
+
+    const height = chart.layout.dimensions.height;
+    expect(height).toBeGreaterThan(400);
+    expect(height).toBeCloseTo(400 + overheadsOf(chart.layout, 390), 5);
+
+    // The rendered SVG is sized to the grown figure, not the 400 fallback.
+    const svg = container.querySelector('svg');
+    expect(svg?.getAttribute('viewBox')).toBe(`0 0 390 ${height}`);
+    expect((svg as SVGElement).style.height).toBe(`${height}px`);
+
+    chart.destroy();
+  });
+
+  it('keeps explicit-height containers at the host height', () => {
+    const container = createContainer(390, 500);
+    const chart = createChart(container, longChromeLineSpec);
+
+    // Host constrains the box; chrome must fit inside it, not grow it.
+    expect(chart.layout.dimensions.height).toBe(500);
+
+    chart.destroy();
+  });
+
+  it('re-renders against the 400 budget, not the grown height (no re-pin)', () => {
+    const container = createAutoHeightContainer(390);
+    const chart = createChart(container, longChromeLineSpec);
+
+    const grownHeight = chart.layout.dimensions.height;
+    expect(grownHeight).toBeGreaterThan(400);
+
+    // Same spec again: the container now measures at the grown SVG height,
+    // but the latched-auto mount keeps compiling against the 400 budget, so
+    // the figure height is stable.
+    chart.update(longChromeLineSpec);
+    expect(chart.layout.dimensions.height).toBe(grownHeight);
+
+    // Shorter chrome: the figure must shrink toward the budget instead of
+    // staying pinned at the previously grown container height.
+    chart.update(singleSeriesLineSpec);
+    const shrunkHeight = chart.layout.dimensions.height;
+    expect(shrunkHeight).toBeLessThan(grownHeight);
+    expect(shrunkHeight).toBeCloseTo(400 + overheadsOf(chart.layout, 390), 5);
+
+    chart.destroy();
+  });
+
+  it('does not grow sparkline mounts', () => {
+    const container = createAutoHeightContainer(200);
+    const chart = createChart(container, {
+      mark: 'line',
+      data: lineSpec.data,
+      encoding: lineSpec.encoding,
+      display: 'sparkline',
+    });
+
+    // Sparkline auto-height fallback stays at the tiny 40px default.
+    expect(chart.layout.dimensions.height).toBe(40);
+
+    chart.destroy();
+  });
+});

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

@@ -14,8 +14,8 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createContainer } from '../__test-fixtures__/dom';
-import { lineSpec } from '../__test-fixtures__/specs';
+import { createAutoHeightContainer, createContainer } from '../__test-fixtures__/dom';
+import { lineSpec, longChromeLineSpec } from '../__test-fixtures__/specs';
 import { createChart } from '../mount';
 
 // ---------------------------------------------------------------------------
@@ -181,4 +181,38 @@ describe('chart resize timing', () => {
     // try to render a new one. No SVG should be present.
     expect(container.querySelector('svg')).toBeNull();
   });
+
+  describe('auto-height observer feedback guard', () => {
+    it('ignores the observer echo from the figure growing itself', async () => {
+      const autoContainer = createAutoHeightContainer(390);
+      const chart = createChart(autoContainer, longChromeLineSpec);
+
+      const grownHeight = chart.layout.dimensions.height;
+      expect(grownHeight).toBeGreaterThan(400);
+      const genBefore = autoContainer.dataset.ocRenderGen;
+
+      // Growing the SVG grows the container, which fires the observer with
+      // our own dimensions. That echo must not trigger a re-render (the
+      // re-render would grow again and loop).
+      fireResize(autoContainer, 390, grownHeight);
+      await vi.runAllTimersAsync();
+      expect(autoContainer.dataset.ocRenderGen).toBe(genBefore);
+
+      chart.destroy();
+    });
+
+    it('still re-renders when the width changes', async () => {
+      const autoContainer = createAutoHeightContainer(390);
+      const chart = createChart(autoContainer, longChromeLineSpec);
+
+      const grownHeight = chart.layout.dimensions.height;
+      const genBefore = autoContainer.dataset.ocRenderGen;
+
+      fireResize(autoContainer, 340, grownHeight);
+      await vi.runAllTimersAsync();
+      expect(autoContainer.dataset.ocRenderGen).not.toBe(genBefore);
+
+      chart.destroy();
+    });
+  });
 });

package/src/mount.ts

@@ -21,7 +21,7 @@ import type {
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
 import { isGraphSpec, isLayerSpec } from '@opendata-ai/openchart-core';
-import { compileChart, compileLayer } from '@opendata-ai/openchart-engine';
+import { compileChart, compileLayer, legendGap } from '@opendata-ai/openchart-engine';
 import { cancelAnimations, setupAnimationCleanup } from './animation';
 import {
   exportCSV,
@@ -120,6 +120,18 @@ export interface ChartInstance {
   setHighlight(values: string[] | null): void;
 }
 
+// ---------------------------------------------------------------------------
+// Container sizing
+// ---------------------------------------------------------------------------
+
+/**
+ * Fallback height when the container doesn't constrain height. For
+ * auto-height ChartSpec mounts this is the fixed budget for the
+ * visualization itself (padding + axes + plot); chrome, the top legend
+ * block, and the metrics bar grow the figure on top of it.
+ */
+const FALLBACK_HEIGHT = 400;
+
 // ---------------------------------------------------------------------------
 // Dark mode resolution
 // ---------------------------------------------------------------------------
@@ -194,6 +206,19 @@ export function createChart<TData extends DataRow = DataRow>(
   let cleanupAnimations: (() => void) | null = null;
   let pendingResize = false;
 
+  // Auto-height sizing state. `isAutoHeight` latches whether the host
+  // constrains the container's height:
+  //   null  = unknown — every measurement so far was an all-zero rect
+  //           (display:none / detached); keep re-checking each measure.
+  //   true  = auto-height — the figure grows with chrome (ChartSpec only).
+  //   false = explicit height — fit inside the host's box (today's behavior).
+  // The latch matters because the SVG's own style.height gives the container
+  // a nonzero rect after the first render, so auto-height cannot be
+  // re-derived per measure.
+  let isAutoHeight: boolean | null = null;
+  let lastRenderedWidth: number | null = null;
+  let lastRenderedSvgHeight: number | null = null;
+
   // Data-update transition state
   let transitionHandle: import('./transition').TransitionHandle | null = null;
   let transitionSnapshot: GeometrySnapshot | null = null;
@@ -239,8 +264,7 @@ export function createChart<TData extends DataRow = DataRow>(
   // Compilation
   // ---------------------------------------------------------------------------
 
-  function compile(): ChartLayout {
-    const { width, height } = getContainerDimensions();
+  function compileAt(width: number, height: number): ChartLayout {
     const darkMode = resolveDarkMode(options?.darkMode);
 
     const compileOpts: CompileOptions = {
@@ -258,6 +282,61 @@ export function createChart<TData extends DataRow = DataRow>(
     return compileChart(withRuntimeHidden(currentSpec) as ChartSpec | GraphSpec, compileOpts);
   }
 
+  /**
+   * Vertical overheads that grow an auto-height figure beyond the
+   * FALLBACK_HEIGHT budget: top+bottom chrome (bottom chrome already includes
+   * a bottom legend's reservation), the top legend block (height + gap), and
+   * the KPI metrics bar. topPad and the axis gap are plot clearance, not
+   * chrome — they stay inside the budget.
+   */
+  function verticalOverheads(layout: ChartLayout, width: number): number {
+    const topLegendBlock =
+      layout.legend.position === 'top' &&
+      'entries' in layout.legend &&
+      layout.legend.entries.length > 0
+        ? layout.legend.bounds.height + legendGap(width)
+        : 0;
+    return (
+      layout.chrome.topHeight +
+      layout.chrome.bottomHeight +
+      topLegendBlock +
+      (layout.metrics?.height ?? 0)
+    );
+  }
+
+  function compile(): ChartLayout {
+    const { width, height } = getContainerDimensions();
+
+    // Auto-height growth applies to ChartSpec mounts only. GraphSpec,
+    // LayerSpec, and sparkline mounts keep the fixed-fallback behavior.
+    const growsWithChrome =
+      isAutoHeight === true &&
+      !isLayerSpec(currentSpec) &&
+      !isGraphSpec(currentSpec as unknown as Record<string, unknown>) &&
+      (currentSpec as ChartSpec).display !== 'sparkline';
+    if (!growsWithChrome) {
+      return compileAt(width, height);
+    }
+
+    // Bounded convergence loop, max 3 compiles. Chrome height depends on
+    // width (text wrap), not height — but the engine's chrome-strip guardrail
+    // strips chrome when the residual plot is too small, which makes chrome
+    // height-dependent at the budget boundary: growing the figure can
+    // un-strip chrome, changing the overheads once more. (Height classes are
+    // not the issue — they only strip below 200/350px, and growing from 400
+    // moves away from those thresholds.) Pass 3 is accepted unconditionally.
+    let layout = compileAt(width, height);
+    const overheads = verticalOverheads(layout, width);
+    if (overheads > 0) {
+      layout = compileAt(width, height + overheads);
+      const overheads2 = verticalOverheads(layout, width);
+      if (overheads2 !== overheads) {
+        layout = compileAt(width, height + overheads2);
+      }
+    }
+    return layout;
+  }
+
   function withRuntimeHidden<T extends { hiddenSeries?: string[]; annotations?: Annotation[] }>(
     spec: T,
   ): T {
@@ -366,9 +445,21 @@ export function createChart<TData extends DataRow = DataRow>(
         height: Math.max(height || 40, 20),
       };
     }
+    // Latch auto-height on the first NONZERO measurement: height 0 with a
+    // real width means the host doesn't constrain height. An all-zero rect
+    // (display:none / detached) stays "unknown" — keep re-checking until the
+    // container produces a real measurement.
+    if (isAutoHeight === null && (rect.width > 0 || rect.height > 0)) {
+      isAutoHeight = rect.height === 0 && rect.width > 0;
+    }
+
     return {
       width: Math.max(rect.width || 600, 100),
-      height: Math.max(rect.height || 400, 100),
+      // Latched-auto mounts always compile against the fixed budget: after
+      // the first render the container's measured height is just our own
+      // SVG, so reading it back would re-pin whatever we rendered last.
+      height:
+        isAutoHeight === true ? FALLBACK_HEIGHT : Math.max(rect.height || FALLBACK_HEIGHT, 100),
     };
   }
 
@@ -676,6 +767,9 @@ export function createChart<TData extends DataRow = DataRow>(
     }
 
     currentLayout = compile();
+    // Recorded for the ResizeObserver's self-induced-resize guard.
+    lastRenderedWidth = currentLayout.dimensions.width;
+    lastRenderedSvgHeight = currentLayout.dimensions.height;
     const shouldAnimate = isFirstRender && !!currentLayout.animation?.enter;
     const crosshair = !!currentLayout.crosshair;
     svgElement = renderChartSVG(currentLayout, container, {
@@ -1050,7 +1144,27 @@ export function createChart<TData extends DataRow = DataRow>(
 
   // Set up responsive resize
   if (options?.responsive !== false) {
-    disconnectResize = observeResize(container, () => {
+    disconnectResize = observeResize(container, (width, height) => {
+      // Self-induced-resize guard, scoped to latched-auto mounts: growing
+      // the SVG grows the container, which re-fires this observer. A fire
+      // whose height matches the SVG we just rendered (and whose width is
+      // unchanged) is our own echo — re-rendering on it would loop; the
+      // 16ms debounce alone doesn't break the cycle.
+      if (isAutoHeight === true) {
+        const widthChanged = width !== lastRenderedWidth;
+        const selfInducedHeight = height === lastRenderedSvgHeight;
+        if (!widthChanged && selfInducedHeight) return;
+        if (!selfInducedHeight) {
+          // Any other height delta is host-driven: un-latch so the next
+          // measure re-derives (and re-latches explicit if the container
+          // now reports a height that isn't ours).
+          isAutoHeight = null;
+        }
+        resize();
+        return;
+      }
+      // Explicit-height (and not-yet-latched) mounts keep today's
+      // re-render-on-every-fire behavior.
       resize();
     });
   }