@opendata-ai/openchart-engine 6.23.1 → 6.24.1

package/src/legend/compute.ts

@@ -20,10 +20,10 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { BRAND_RESERVE_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
-import { ENTRY_GAP, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from './wrap';
+import { ENTRY_GAP, ENTRY_GAP_COMPACT, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from './wrap';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -67,27 +67,41 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
   // Sequential (quantitative) color doesn't produce discrete legend entries
   if (colorEnc.type === 'quantitative') return [];
 
-  const uniqueValues = [...new Set(spec.data.map((d) => String(d[colorEnc.field])))];
+  const dataValues = [...new Set(spec.data.map((d) => String(d[colorEnc.field])))];
   const explicitDomain = colorEnc.scale?.domain as string[] | undefined;
   const explicitRange = colorEnc.scale?.range as string[] | undefined;
   const palette = explicitRange ?? theme.colors.categorical;
   const shape = swatchShapeForType(spec.markType);
 
-  return uniqueValues.map((value, i) => {
-    // When explicit domain+range are provided, look up the color by domain index
-    // so legend colors match the mark colors exactly.
-    let colorIndex = i;
-    if (explicitDomain && explicitRange) {
-      const domainIdx = explicitDomain.indexOf(value);
-      if (domainIdx >= 0) colorIndex = domainIdx;
-    }
-    return {
-      label: value,
-      color: palette[colorIndex % palette.length],
-      shape,
-      active: true,
-    };
-  });
+  // Order legend entries by explicit domain when provided so the author
+  // controls which entries render first (and which get truncated last when
+  // symbolLimit applies). Without explicit domain, preserve data order.
+  const uniqueValues = explicitDomain
+    ? [
+        ...explicitDomain.filter((v) => dataValues.includes(v)),
+        ...dataValues.filter((v) => !explicitDomain.includes(v)),
+      ]
+    : dataValues;
+
+  const excludeSet = new Set(spec.legend?.exclude ?? []);
+
+  return uniqueValues
+    .map((value, i) => {
+      // When explicit domain+range are provided, look up the color by domain index
+      // so legend colors match the mark colors exactly.
+      let colorIndex = i;
+      if (explicitDomain && explicitRange) {
+        const domainIdx = explicitDomain.indexOf(value);
+        if (domainIdx >= 0) colorIndex = domainIdx;
+      }
+      return {
+        label: value,
+        color: palette[colorIndex % palette.length],
+        shape,
+        active: true,
+      };
+    })
+    .filter((entry) => !excludeSet.has(entry.label));
 }
 
 /**
@@ -152,12 +166,22 @@ export function computeLegend(
 
   // Auto-suppress legend when endpoint labels identify series on line/area charts.
   // Guards: keep legend at compact breakpoints (labels hidden), for stacked areas
-  // (endpoint labels overlap), and when user explicitly forces legend on.
+  // (endpoint labels overlap), and when user has configured any legend property
+  // (position, columns, maxRows, etc.) — any explicit legend config signals intent
+  // to show a legend, not just show: true.
   const isLineOrArea = spec.markType === 'line' || spec.markType === 'area';
   const hasLabels = spec.labels.density !== 'none';
   const labelsWillRender = strategy.labelMode !== 'none';
   const hasColorEncoding = spec.encoding.color != null;
-  const legendNotForced = spec.legend?.show !== true;
+  // Legend is "forced" when the user set show: true OR specified any legend config
+  // other than show: false. Vega-Lite convention: legend is shown by default for
+  // multi-series charts; auto-suppression only fires when no legend config is present.
+  const userConfiguredLegend =
+    spec.legend != null &&
+    Object.keys(spec.legend).some(
+      (k) => k !== 'show' || spec.legend![k as keyof typeof spec.legend] !== false,
+    );
+  const legendNotForced = !userConfiguredLegend;
 
   if (isLineOrArea && hasLabels && labelsWillRender && hasColorEncoding && legendNotForced) {
     const isArea = spec.markType === 'area';
@@ -258,8 +282,12 @@ export function computeLegend(
   // Reserve space on the right for bottom legends so they don't overlap the brand
   // watermark. Top legends don't need this since the brand renders at the bottom.
   const reserveBrand = watermark && resolvedPosition === 'bottom';
+  // Tighten gaps on narrow viewports so horizontal legends keep fitting on one row.
+  const isCompact = chartArea.width < COMPACT_WIDTH;
+  const effectivePadding = isCompact ? 2 : LEGEND_PADDING;
+  const effectiveEntryGap = isCompact ? ENTRY_GAP_COMPACT : ENTRY_GAP;
   const availableWidth =
-    chartArea.width - LEGEND_PADDING * 2 - (reserveBrand ? BRAND_RESERVE_WIDTH : 0);
+    chartArea.width - effectivePadding * 2 - (reserveBrand ? BRAND_RESERVE_WIDTH : 0);
 
   // Apply symbolLimit first if set (minimum 1), then fit remaining entries to available rows.
   if (spec.legend?.symbolLimit != null) {
@@ -276,7 +304,13 @@ export function computeLegend(
       : spec.legend?.columns != null
         ? Math.ceil(entries.length / spec.legend.columns)
         : TOP_LEGEND_MAX_ROWS;
-  const { fittingCount } = measureLegendWrap(entries, availableWidth, labelStyle, maxRows);
+  const { fittingCount } = measureLegendWrap(
+    entries,
+    availableWidth,
+    labelStyle,
+    maxRows,
+    effectiveEntryGap,
+  );
 
   if (fittingCount < entries.length) {
     entries = truncateEntries(entries, fittingCount);
@@ -284,14 +318,20 @@ export function computeLegend(
 
   const totalWidth = entries.reduce((sum, entry) => {
     const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
-    return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+    return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + effectiveEntryGap;
   }, 0);
 
   // Calculate actual row count for height (recompute after truncation).
-  const { rowCount } = measureLegendWrap(entries, availableWidth, labelStyle);
+  const { rowCount } = measureLegendWrap(
+    entries,
+    availableWidth,
+    labelStyle,
+    undefined,
+    effectiveEntryGap,
+  );
 
   const rowHeight = SWATCH_SIZE + 4;
-  const legendHeight = rowCount * rowHeight + LEGEND_PADDING * 2;
+  const legendHeight = rowCount * rowHeight + effectivePadding * 2;
 
   // Apply user-provided legend offset
   const offsetDx = spec.legend?.offset?.dx ?? 0;
@@ -312,6 +352,6 @@ export function computeLegend(
     labelStyle,
     swatchSize: SWATCH_SIZE,
     swatchGap: SWATCH_GAP,
-    entryGap: ENTRY_GAP,
+    entryGap: effectiveEntryGap,
   };
 }

package/src/legend/wrap.ts

@@ -15,7 +15,7 @@
  */
 
 import type { LegendEntry, TextStyle } from '@opendata-ai/openchart-core';
-import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { COMPACT_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -28,6 +28,16 @@ import { estimateTextWidth } from '@opendata-ai/openchart-core';
 export const SWATCH_SIZE = 12;
 export const SWATCH_GAP = 6;
 export const ENTRY_GAP = 16;
+/** Tighter inter-entry gap for narrow viewports where every pixel matters. */
+export const ENTRY_GAP_COMPACT = 10;
+
+/** Default gap between legend bounds and chart area. Zero on narrow viewports. */
+export const LEGEND_GAP = 4;
+
+/** Gap between legend and chart area, responsive to container width. */
+export function legendGap(width: number): number {
+  return width < COMPACT_WIDTH ? 0 : LEGEND_GAP;
+}
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -55,6 +65,7 @@ export function measureLegendWrap(
   maxWidth: number,
   labelStyle: TextStyle,
   maxRows?: number,
+  entryGap: number = ENTRY_GAP,
 ): LegendWrapResult {
   if (entries.length === 0) {
     return { rowCount: 0, fittingCount: 0, rowWidths: [] };
@@ -72,7 +83,7 @@ export function measureLegendWrap(
       labelStyle.fontSize,
       labelStyle.fontWeight,
     );
-    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + entryGap;
 
     if (rowWidth + entryWidth > maxWidth && rowWidth > 0) {
       rowWidths.push(rowWidth);

package/src/sankey/compile-sankey.ts

@@ -507,6 +507,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     },
     animation: resolvedAnimation,
     watermark,
+    measureText: options.measureText,
   };
 }