@opendata-ai/openchart-engine 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "2.9.0",
+    "@opendata-ai/openchart-core": "2.10.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -24,6 +24,8 @@ export function makeFullStrategy(): LayoutStrategy {
     legendPosition: 'right',
     annotationPosition: 'inline',
     axisLabelDensity: 'full',
+    chromeMode: 'full',
+    legendMaxHeight: -1,
   };
 }
 
@@ -34,6 +36,8 @@ export function makeCompactStrategy(): LayoutStrategy {
     legendPosition: 'top',
     annotationPosition: 'tooltip-only',
     axisLabelDensity: 'minimal',
+    chromeMode: 'full',
+    legendMaxHeight: -1,
   };
 }
 

package/src/__tests__/axes.test.ts

@@ -32,6 +32,8 @@ const fullStrategy: LayoutStrategy = {
   legendPosition: 'right',
   annotationPosition: 'inline',
   axisLabelDensity: 'full',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 const minimalStrategy: LayoutStrategy = {
@@ -39,6 +41,8 @@ const minimalStrategy: LayoutStrategy = {
   legendPosition: 'top',
   annotationPosition: 'tooltip-only',
   axisLabelDensity: 'minimal',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 describe('computeAxes', () => {

package/src/__tests__/legend.test.ts

@@ -40,6 +40,8 @@ const fullStrategy: LayoutStrategy = {
   legendPosition: 'right',
   annotationPosition: 'inline',
   axisLabelDensity: 'full',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 const compactStrategy: LayoutStrategy = {
@@ -47,6 +49,8 @@ const compactStrategy: LayoutStrategy = {
   legendPosition: 'top',
   annotationPosition: 'tooltip-only',
   axisLabelDensity: 'minimal',
+  chromeMode: 'full',
+  legendMaxHeight: -1,
 };
 
 describe('computeLegend', () => {

package/src/compile.ts

@@ -28,6 +28,7 @@ import {
   generateAltText,
   generateDataTable,
   getBreakpoint,
+  getHeightClass,
   getLayoutStrategy,
   resolveTheme,
 } from '@opendata-ai/openchart-core';
@@ -163,7 +164,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 
   // Responsive strategy
   const breakpoint = getBreakpoint(options.width);
-  const strategy = getLayoutStrategy(breakpoint);
+  const heightClass = getHeightClass(options.height);
+  const strategy = getLayoutStrategy(breakpoint, heightClass);
 
   // Apply breakpoint-conditional overrides from the original spec
   const rawSpec = spec as Record<string, unknown>;
@@ -230,8 +232,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   };
   const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea);
 
-  // Compute dimensions (accounts for chrome + legend)
-  const dims = computeDimensions(chartSpec, options, legendLayout, theme);
+  // Compute dimensions (accounts for chrome + legend + responsive strategy)
+  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy);
   const chartArea = dims.chartArea;
 
   // Recompute legend bounds relative to actual chart area.

package/src/layout/axes.ts

@@ -18,6 +18,7 @@ import type {
 import {
   abbreviateNumber,
   buildD3Formatter,
+  estimateTextWidth,
   formatDate,
   formatNumber,
 } from '@opendata-ai/openchart-core';
@@ -234,13 +235,33 @@ export function computeAxes(
       major: true,
     }));
 
+    // Auto-rotate labels when band scale labels would overlap.
+    // Uses max label width (not average) since one long label is enough to overlap.
+    let tickAngle = scales.x.channel.axis?.tickAngle;
+    if (tickAngle === undefined && scales.x.type === 'band' && ticks.length > 1) {
+      const bandwidth = (scales.x.scale as ScaleBand<string>).bandwidth();
+      let maxLabelWidth = 0;
+      for (const t of ticks) {
+        const w = estimateTextWidth(
+          t.label,
+          theme.fonts.sizes.axisTick,
+          theme.fonts.weights.normal,
+        );
+        if (w > maxLabelWidth) maxLabelWidth = w;
+      }
+      // If the widest label exceeds 85% of the bandwidth, rotate to avoid overlap
+      if (maxLabelWidth > bandwidth * 0.85) {
+        tickAngle = -45;
+      }
+    }
+
     result.x = {
       ticks,
       gridlines: scales.x.channel.axis?.grid ? gridlines : [],
       label: scales.x.channel.axis?.label,
       labelStyle: axisLabelStyle,
       tickLabelStyle,
-      tickAngle: scales.x.channel.axis?.tickAngle,
+      tickAngle,
       start: { x: chartArea.x, y: chartArea.y + chartArea.height },
       end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
     };

package/src/layout/dimensions.ts

@@ -5,11 +5,16 @@
  * LayoutDimensions with the total area, chrome layout, chart drawing area,
  * and margins. The chart area is what's left after subtracting chrome,
  * legend space, and axis margins.
+ *
+ * Padding and chrome scale down at smaller container sizes to maximize
+ * the usable chart area. When the chart area is still too small after
+ * scaling, chrome is progressively stripped as a fallback.
  */
 
 import type {
   CompileOptions,
   Encoding,
+  LayoutStrategy,
   LegendLayout,
   Margins,
   Rect,
@@ -53,6 +58,23 @@ function chromeToInput(chrome: NormalizedChrome): import('@opendata-ai/openchart
   };
 }
 
+/**
+ * Scale padding based on the smaller container dimension.
+ * At >= 500px, padding is unchanged. At <= 200px, padding is halved (min 4px).
+ * Linear interpolation between 200-500px.
+ */
+function scalePadding(basePadding: number, width: number, height: number): number {
+  const minDim = Math.min(width, height);
+  if (minDim >= 500) return basePadding;
+  if (minDim <= 200) return Math.max(Math.round(basePadding * 0.5), 4);
+  const t = (minDim - 200) / 300;
+  return Math.max(Math.round(basePadding * (0.5 + t * 0.5)), 4);
+}
+
+/** Minimum chart area dimensions before guardrails kick in. */
+const MIN_CHART_WIDTH = 60;
+const MIN_CHART_HEIGHT = 40;
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -64,6 +86,7 @@ function chromeToInput(chrome: NormalizedChrome): import('@opendata-ai/openchart
  * @param options - Compile options (width, height, theme, darkMode).
  * @param legendLayout - Pre-computed legend layout (used to reserve space).
  * @param theme - Already-resolved theme (resolved once in compileChart).
+ * @param strategy - Responsive layout strategy (controls chrome mode).
  * @returns LayoutDimensions with chart area rect.
  */
 export function computeDimensions(
@@ -71,14 +94,23 @@ export function computeDimensions(
   options: CompileOptions,
   legendLayout: LegendLayout,
   theme: ResolvedTheme,
+  strategy?: LayoutStrategy,
 ): LayoutDimensions {
   const { width, height } = options;
 
-  const padding = theme.spacing.padding;
+  const padding = scalePadding(theme.spacing.padding, width, height);
   const axisMargin = theme.spacing.axisMargin;
+  const chromeMode = strategy?.chromeMode ?? 'full';
 
-  // Compute chrome
-  const chrome = computeChrome(chromeToInput(spec.chrome), theme, width, options.measureText);
+  // Compute chrome with mode and scaled padding
+  const chrome = computeChrome(
+    chromeToInput(spec.chrome),
+    theme,
+    width,
+    options.measureText,
+    chromeMode,
+    padding,
+  );
 
   // Start with the total rect
   const total: Rect = { x: 0, y: 0, width, height };
@@ -216,12 +248,53 @@ export function computeDimensions(
   }
 
   // Chart area is what's left after margins
-  const chartArea: Rect = {
+  let chartArea: Rect = {
     x: margins.left,
     y: margins.top,
     width: Math.max(0, width - margins.left - margins.right),
     height: Math.max(0, height - margins.top - margins.bottom),
   };
 
+  // Guardrail: if chart area is too small, progressively strip chrome
+  if (
+    (chartArea.width < MIN_CHART_WIDTH || chartArea.height < MIN_CHART_HEIGHT) &&
+    chromeMode !== 'hidden'
+  ) {
+    // Try compact first, then hidden
+    const fallbackMode = chromeMode === 'full' ? 'compact' : 'hidden';
+    const fallbackChrome = computeChrome(
+      chromeToInput(spec.chrome),
+      theme,
+      width,
+      options.measureText,
+      fallbackMode as 'compact' | 'hidden',
+      padding,
+    );
+
+    // Recalculate top/bottom margins with stripped chrome
+    const newTop = padding + fallbackChrome.topHeight + axisMargin;
+    const topDelta = margins.top - newTop;
+    const newBottom = padding + fallbackChrome.bottomHeight + xAxisHeight;
+    const bottomDelta = margins.bottom - newBottom;
+
+    if (topDelta > 0 || bottomDelta > 0) {
+      margins.top =
+        newTop +
+        (legendLayout.entries.length > 0 && legendLayout.position === 'top'
+          ? legendLayout.bounds.height + 4
+          : 0);
+      margins.bottom = newBottom;
+
+      chartArea = {
+        x: margins.left,
+        y: margins.top,
+        width: Math.max(0, width - margins.left - margins.right),
+        height: Math.max(0, height - margins.top - margins.bottom),
+      };
+
+      return { total, chrome: fallbackChrome, chartArea, margins, theme };
+    }
+  }
+
   return { total, chrome, chartArea, margins, theme };
 }

package/src/legend/compute.ts

@@ -7,6 +7,9 @@
  *
  * The legend is computed early (before marks) so the chartArea accounts
  * for legend space. Entries come from data + encoding, not marks.
+ *
+ * Overflow protection: when there are too many entries for the available
+ * space, entries are truncated and a "+N more" indicator is appended.
  */
 
 import type {
@@ -31,6 +34,12 @@ const ENTRY_GAP = 16;
 const LEGEND_PADDING = 8;
 const LEGEND_RIGHT_WIDTH = 120;
 
+/** Max fraction of chart area height for right-positioned legends. */
+const RIGHT_LEGEND_MAX_HEIGHT_RATIO = 0.4;
+
+/** Max number of rows for top-positioned legends before truncation. */
+const TOP_LEGEND_MAX_ROWS = 2;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -68,6 +77,57 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
   }));
 }
 
+/**
+ * Calculate how many entries fit within a given number of horizontal rows.
+ */
+function entriesThatFit(
+  entries: LegendEntry[],
+  maxWidth: number,
+  maxRows: number,
+  labelStyle: TextStyle,
+): number {
+  let row = 1;
+  let rowWidth = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    const labelWidth = estimateTextWidth(
+      entries[i].label,
+      labelStyle.fontSize,
+      labelStyle.fontWeight,
+    );
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+
+    if (rowWidth + entryWidth > maxWidth && rowWidth > 0) {
+      row++;
+      rowWidth = entryWidth;
+      if (row > maxRows) return i;
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+
+  return entries.length;
+}
+
+/**
+ * Truncate entries and add a "+N more" indicator if needed.
+ */
+function truncateEntries(entries: LegendEntry[], maxCount: number): LegendEntry[] {
+  if (maxCount >= entries.length || maxCount <= 0) return entries;
+
+  const truncated = entries.slice(0, maxCount);
+  const remaining = entries.length - maxCount;
+  truncated.push({
+    label: `+${remaining} more`,
+    color: '#999999',
+    shape: 'square',
+    active: false,
+    overflow: true,
+  });
+
+  return truncated;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -87,8 +147,8 @@ export function computeLegend(
   theme: ResolvedTheme,
   chartArea: Rect,
 ): LegendLayout {
-  // Legend explicitly hidden via show: false
-  if (spec.legend?.show === false) {
+  // Legend explicitly hidden via show: false, or height strategy says no legend
+  if (spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return {
       position: 'top',
       entries: [],
@@ -106,7 +166,7 @@ export function computeLegend(
     };
   }
 
-  const entries = extractColorEntries(spec, theme);
+  let entries = extractColorEntries(spec, theme);
 
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
@@ -143,6 +203,21 @@ export function computeLegend(
       SWATCH_SIZE + SWATCH_GAP + maxLabelWidth + LEGEND_PADDING * 2,
     );
     const entryHeight = Math.max(SWATCH_SIZE, labelStyle.fontSize * labelStyle.lineHeight);
+
+    // Apply max height ratio (default 40% of chart area, strategy can override)
+    const maxHeightRatio =
+      strategy.legendMaxHeight > 0 ? strategy.legendMaxHeight : RIGHT_LEGEND_MAX_HEIGHT_RATIO;
+    const maxLegendHeight = chartArea.height * maxHeightRatio;
+
+    // Calculate how many entries fit
+    const maxEntries = Math.max(
+      1,
+      Math.floor((maxLegendHeight - LEGEND_PADDING * 2) / (entryHeight + 4)),
+    );
+    if (entries.length > maxEntries) {
+      entries = truncateEntries(entries, maxEntries);
+    }
+
     const legendHeight =
       entries.length * entryHeight + (entries.length - 1) * 4 + LEGEND_PADDING * 2;
     const clampedHeight = Math.min(legendHeight, chartArea.height);
@@ -173,13 +248,35 @@ export function computeLegend(
     };
   }
 
-  // Top/bottom-positioned legend: horizontal flow
+  // Top/bottom-positioned legend: horizontal flow with overflow protection
+  const availableWidth = chartArea.width - LEGEND_PADDING * 2;
+  const maxFit = entriesThatFit(entries, availableWidth, TOP_LEGEND_MAX_ROWS, labelStyle);
+
+  if (maxFit < entries.length) {
+    entries = truncateEntries(entries, maxFit);
+  }
+
   const totalWidth = entries.reduce((sum, entry) => {
     const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
     return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
   }, 0);
 
-  const legendHeight = SWATCH_SIZE + LEGEND_PADDING * 2;
+  // Calculate actual row count for height
+  let rowCount = 1;
+  let rowWidth = 0;
+  for (const entry of entries) {
+    const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+    if (rowWidth + entryWidth > availableWidth && rowWidth > 0) {
+      rowCount++;
+      rowWidth = entryWidth;
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+
+  const rowHeight = SWATCH_SIZE + 4;
+  const legendHeight = rowCount * rowHeight + LEGEND_PADDING * 2;
 
   // Apply user-provided legend offset
   const offsetDx = spec.legend?.offset?.dx ?? 0;