@opendata-ai/openchart-engine 7.6.1 → 7.7.0

package/src/layout/__tests__/scales-highlight.test.ts

@@ -0,0 +1,192 @@
+import type { ChartSpec, LineMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../compile';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const MUTED_COLOR = '#bfc3c8';
+
+const data = [
+  { date: '2020', country: 'Germany', value: 100 },
+  { date: '2020', country: 'France', value: 90 },
+  { date: '2020', country: 'Italy', value: 80 },
+  { date: '2020', country: 'Spain', value: 70 },
+  { date: '2020', country: 'Poland', value: 60 },
+  { date: '2021', country: 'Germany', value: 110 },
+  { date: '2021', country: 'France', value: 95 },
+  { date: '2021', country: 'Italy', value: 85 },
+  { date: '2021', country: 'Spain', value: 75 },
+  { date: '2021', country: 'Poland', value: 65 },
+  { date: '2022', country: 'Germany', value: 120 },
+  { date: '2022', country: 'France', value: 100 },
+  { date: '2022', country: 'Italy', value: 90 },
+  { date: '2022', country: 'Spain', value: 80 },
+  { date: '2022', country: 'Poland', value: 70 },
+];
+
+const compileOptions = { width: 600, height: 400 };
+
+function makeSpec(highlight?: string | string[]): ChartSpec {
+  const colorChannel: Record<string, unknown> = {
+    field: 'country',
+    type: 'nominal',
+  };
+  if (highlight !== undefined) {
+    colorChannel.highlight = highlight;
+  }
+  return {
+    mark: 'line',
+    data,
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+      color: colorChannel,
+    },
+  } as ChartSpec;
+}
+
+// ---------------------------------------------------------------------------
+// Color partitioning
+// ---------------------------------------------------------------------------
+
+describe('highlight — color partitioning', () => {
+  it('assigns palette color to highlighted series and muted color to others', () => {
+    const layout = compileChart(makeSpec(['Germany']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    const germany = marks.find((m) => m.seriesKey === 'Germany');
+    const france = marks.find((m) => m.seriesKey === 'France');
+    const italy = marks.find((m) => m.seriesKey === 'Italy');
+
+    expect(germany).toBeDefined();
+    expect(france).toBeDefined();
+    expect(italy).toBeDefined();
+
+    // Germany should have a real palette color (not the muted gray)
+    expect(germany!.stroke).not.toBe(MUTED_COLOR);
+
+    // Non-highlighted series should get the muted color
+    expect(france!.stroke).toBe(MUTED_COLOR);
+    expect(italy!.stroke).toBe(MUTED_COLOR);
+  });
+
+  it('assigns palette colors to multiple highlighted series', () => {
+    const layout = compileChart(makeSpec(['Germany', 'France']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    const germany = marks.find((m) => m.seriesKey === 'Germany');
+    const france = marks.find((m) => m.seriesKey === 'France');
+    const italy = marks.find((m) => m.seriesKey === 'Italy');
+
+    // Both highlighted series should have distinct palette colors
+    expect(germany!.stroke).not.toBe(MUTED_COLOR);
+    expect(france!.stroke).not.toBe(MUTED_COLOR);
+    expect(germany!.stroke).not.toBe(france!.stroke);
+
+    // Non-highlighted series should be muted
+    expect(italy!.stroke).toBe(MUTED_COLOR);
+  });
+
+  it('assigns all series palette colors when no highlight is active', () => {
+    const layout = compileChart(makeSpec(), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    // Every series should get a real palette color
+    for (const mark of marks) {
+      expect(mark.stroke).not.toBe(MUTED_COLOR);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Z-order: muted marks sort before highlighted marks
+// ---------------------------------------------------------------------------
+
+describe('highlight — z-order', () => {
+  it('places muted series marks before highlighted series marks', () => {
+    const layout = compileChart(makeSpec(['Germany']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    // Find the index of the first highlighted mark and the last muted mark
+    const germanyIndex = marks.findIndex((m) => m.seriesKey === 'Germany');
+    const lastMutedIndex = marks.reduce(
+      (maxIdx, m, i) => (m.seriesKey !== 'Germany' ? Math.max(maxIdx, i) : maxIdx),
+      -1,
+    );
+
+    // All muted marks should come before the highlighted mark in the array
+    expect(germanyIndex).toBeGreaterThan(lastMutedIndex);
+  });
+
+  it('places all muted marks before all highlighted marks with multiple highlights', () => {
+    const layout = compileChart(makeSpec(['Germany', 'France']), compileOptions);
+    const marks = layout.marks as LineMark[];
+    const highlightSet = new Set(['Germany', 'France']);
+
+    const firstHighlightIndex = marks.findIndex((m) => highlightSet.has(m.seriesKey ?? ''));
+    const lastMutedIndex = marks.reduce(
+      (maxIdx, m, i) => (!highlightSet.has(m.seriesKey ?? '') ? Math.max(maxIdx, i) : maxIdx),
+      -1,
+    );
+
+    expect(firstHighlightIndex).toBeGreaterThan(lastMutedIndex);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Muted line stroke width
+// ---------------------------------------------------------------------------
+
+describe('highlight — muted line stroke width', () => {
+  it('reduces stroke width for muted series', () => {
+    const layout = compileChart(makeSpec(['Germany']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    const germany = marks.find((m) => m.seriesKey === 'Germany');
+    const france = marks.find((m) => m.seriesKey === 'France');
+
+    expect(germany).toBeDefined();
+    expect(france).toBeDefined();
+
+    expect(germany!.strokeWidth).toBeDefined();
+    expect(france!.strokeWidth).toBeDefined();
+    expect(france!.strokeWidth).toBeLessThan(germany!.strokeWidth);
+    expect(france!.strokeWidth).toBeGreaterThanOrEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Endpoint label suppression
+// ---------------------------------------------------------------------------
+
+describe('highlight — endpoint labels', () => {
+  it('only includes highlighted series in endpoint labels', () => {
+    const spec = { ...makeSpec(['Germany']), endpointLabels: { show: true } } as ChartSpec;
+    const layout = compileChart(spec, compileOptions);
+
+    expect(layout.endpointLabels).toBeDefined();
+    expect(layout.endpointLabels!.entries.length).toBeGreaterThan(0);
+    const labelSeriesKeys = layout.endpointLabels!.entries.map((e) => e.seriesKey);
+
+    expect(labelSeriesKeys).toContain('Germany');
+    expect(labelSeriesKeys).not.toContain('France');
+    expect(labelSeriesKeys).not.toContain('Italy');
+    expect(labelSeriesKeys).not.toContain('Spain');
+    expect(labelSeriesKeys).not.toContain('Poland');
+  });
+
+  it('includes all series in endpoint labels when no highlight is active', () => {
+    const spec = makeSpec();
+    const layout = compileChart(spec, compileOptions);
+
+    expect(layout.endpointLabels).toBeDefined();
+    expect(layout.endpointLabels!.entries.length).toBeGreaterThan(0);
+    const labelSeriesKeys = layout.endpointLabels!.entries.map((e) => e.seriesKey);
+
+    expect(labelSeriesKeys).toContain('Germany');
+    expect(labelSeriesKeys).toContain('France');
+    expect(labelSeriesKeys).toContain('Italy');
+  });
+});

package/src/layout/axes.ts

@@ -73,6 +73,9 @@ const WIDTH_REDUCED_THRESHOLD = 300;
 /** Ordered densities from most to fewest ticks. */
 const DENSITY_ORDER: AxisLabelDensity[] = ['full', 'reduced', 'minimal'];
 
+/** Marks grounded on the x baseline that warrant a domain line. */
+const GROUNDED_MARKS = new Set(['bar', 'tick', 'lollipop']);
+
 /**
  * Compute effective axis tick density by considering available space.
  *
@@ -460,9 +463,12 @@ export function computeAxes(
     // because tick labels need horizontal room around their x position).
     const xTickPosition = axisConfig?.tickPosition ?? 'gutter';
 
+    const xDomainLine =
+      axisConfig?.domain ?? (GROUNDED_MARKS.has(dataContext?.markType ?? '') ? undefined : false);
+
     result.x = {
       ticks,
-      gridlines: axisConfig?.grid ? gridlines : [],
+      gridlines: (axisConfig?.grid ?? dataContext?.markType === 'point') ? gridlines : [],
       label: axisTitle,
       labelStyle: xLabelColor ? { ...axisLabelStyle, fill: xLabelColor } : axisLabelStyle,
       tickLabelStyle: xLabelColor ? { ...tickLabelStyle, fill: xLabelColor } : tickLabelStyle,
@@ -470,7 +476,7 @@ export function computeAxes(
       start: { x: chartArea.x, y: chartArea.y + chartArea.height },
       end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
       orient: axisConfig?.orient,
-      domainLine: axisConfig?.domain,
+      domainLine: xDomainLine,
       tickMarks: axisConfig?.ticks,
       offset: axisConfig?.offset,
       titlePadding: axisConfig?.titlePadding,

package/src/layout/dimensions.ts

@@ -42,7 +42,7 @@ import {
 import { format as d3Format } from 'd3-format';
 
 import type { NormalizedChartSpec } from '../compiler/types';
-import { predictEndpointLabelsWidth } from '../endpoint-labels/predict';
+import { isEndsBoth, predictEndpointLabelsWidth } from '../endpoint-labels/predict';
 import { countColorSeries, resolveSuppression } from '../legend/suppression';
 import { legendGap } from '../legend/wrap';
 import { computeMetricBar, type MetricFontSizes, metricBarHeight } from './metrics';
@@ -362,6 +362,7 @@ export function computeDimensions(
     seriesCount,
     labelsHiddenByStrategy,
     labelsDensityNone: labelDensity === 'none',
+    endpointLabelsDemoted: plan?.endpointLabelsDemoted,
   });
 
   // (1) Endpoint-labels column reservation. predictEndpointLabelsWidth returns 0
@@ -373,6 +374,10 @@ export function computeDimensions(
     if (endpointWidth > 0) {
       // 16px gap between chart area edge and the column.
       margins.right = Math.max(margins.right, hPad) + endpointWidth + 16;
+      // Both-ends mode: mirror the column on the left for first-value labels.
+      if (isEndsBoth(spec)) {
+        margins.left = Math.max(margins.left, hPad) + endpointWidth + 16;
+      }
     }
   }
 

package/src/layout/facet.ts

@@ -0,0 +1,80 @@
+import type { Rect } from '@opendata-ai/openchart-core';
+
+const MIN_PANEL_WIDTH = 200;
+const PANEL_GAP = 12;
+const HEADER_HEIGHT = 20;
+
+export interface FacetGridPanel {
+  key: string;
+  area: Rect;
+  headerPos: { x: number; y: number };
+  row: number;
+  col: number;
+}
+
+export interface FacetGridResult {
+  panels: FacetGridPanel[];
+  columns: number;
+  rows: number;
+}
+
+export function autoColumns(panelCount: number, availableWidth: number): number {
+  const sqrtCols = Math.ceil(Math.sqrt(panelCount));
+  const fitCols = Math.max(1, Math.floor(availableWidth / MIN_PANEL_WIDTH));
+  return Math.min(sqrtCols, fitCols, panelCount);
+}
+
+export function computeFacetGrid(
+  facetValues: string[],
+  requestedColumns: number | undefined,
+  totalArea: Rect,
+  outerAxisReservation: { left: number; bottom: number },
+): FacetGridResult {
+  const n = facetValues.length;
+  if (n === 0) return { panels: [], columns: 0, rows: 0 };
+
+  const usableWidth = totalArea.width - outerAxisReservation.left;
+  let columns = Math.min(requestedColumns ?? autoColumns(n, usableWidth), n);
+
+  // Responsive degradation: reduce columns until panels are wide enough
+  while (columns > 1) {
+    const panelWidth = (usableWidth - (columns - 1) * PANEL_GAP) / columns;
+    if (panelWidth >= MIN_PANEL_WIDTH) break;
+    columns--;
+  }
+
+  const rows = Math.ceil(n / columns);
+  const panelWidth = Math.max(0, (usableWidth - (columns - 1) * PANEL_GAP) / columns);
+  const usableHeight = totalArea.height - outerAxisReservation.bottom;
+  const panelHeight = Math.max(
+    0,
+    (usableHeight - rows * HEADER_HEIGHT - (rows - 1) * PANEL_GAP) / rows,
+  );
+
+  const panels: FacetGridPanel[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const col = i % columns;
+    const row = Math.floor(i / columns);
+    const x = totalArea.x + outerAxisReservation.left + col * (panelWidth + PANEL_GAP);
+    const y = totalArea.y + row * (HEADER_HEIGHT + panelHeight + PANEL_GAP);
+
+    panels.push({
+      key: facetValues[i],
+      area: {
+        x,
+        y: y + HEADER_HEIGHT,
+        width: panelWidth,
+        height: panelHeight,
+      },
+      headerPos: {
+        x: x + panelWidth / 2,
+        y: y + HEADER_HEIGHT * 0.6,
+      },
+      row,
+      col,
+    });
+  }
+
+  return { panels, columns, rows };
+}

package/src/layout/plan.ts

@@ -30,6 +30,7 @@ import {
 import { format as d3Format } from 'd3-format';
 
 import type { NormalizedChartSpec } from '../compiler/types';
+import { predictEndpointLabelsWidth } from '../endpoint-labels/predict';
 import { computeLegendContent, type LegendContent } from '../legend/compute';
 import { legendGap } from '../legend/wrap';
 import { resolveBandTickAngle } from './axes/rotation';
@@ -58,6 +59,8 @@ export interface LayoutPlan {
   yTickCount: number;
   converged: boolean;
   inlineYLabelInset: number;
+  /** True when endpoint labels were demoted by auto-thinning (don't fit at current width). */
+  endpointLabelsDemoted?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -291,6 +294,17 @@ export function resolveLayoutPlan(
   let prev: { gutter: number; rowCount: number; xAxisExtent: number } | null = null;
   let finalPlan: LayoutPlan | null = null;
 
+  // Endpoint-label fit check: when autoThin is on, demote endpoint labels to
+  // legend if the column would consume more than 30% of the total width.
+  const MAX_ENDPOINT_FRACTION = 0.3;
+  let endpointLabelsDemoted = false;
+  if (chartSpec.autoThin) {
+    const epWidth = predictEndpointLabelsWidth(chartSpec, theme);
+    if (epWidth > 0 && epWidth / width > MAX_ENDPOINT_FRACTION) {
+      endpointLabelsDemoted = true;
+    }
+  }
+
   for (let iter = 0; iter < 2; iter++) {
     // Legend content
     const legendAvailWidth = width - padding - leftGutter;
@@ -302,6 +316,7 @@ export function resolveLayoutPlan(
       height,
       watermark,
       measure,
+      endpointLabelsDemoted,
     );
 
     // Chrome
@@ -537,6 +552,7 @@ export function resolveLayoutPlan(
         yTickCount,
         converged: prev === null || converged,
         inlineYLabelInset,
+        endpointLabelsDemoted,
       };
       break;
     }

package/src/legend/__tests__/redundancy.test.ts

@@ -0,0 +1,108 @@
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import { computeLegendContent } from '../compute';
+
+const theme = resolveTheme({});
+const strategy = {
+  axisLabelDensity: 'full' as const,
+  labelMode: 'all' as const,
+  legendPosition: 'top' as const,
+  legendMaxHeight: 1,
+  fontScale: 1,
+};
+
+function makeBarSpec(overrides: Partial<NormalizedChartSpec> = {}): NormalizedChartSpec {
+  return {
+    markType: 'bar',
+    markDef: { type: 'bar' },
+    data: [
+      { category: 'A', value: 10 },
+      { category: 'B', value: 20 },
+      { category: 'C', value: 30 },
+    ],
+    encoding: {
+      x: { field: 'category', type: 'nominal' },
+      y: { field: 'value', type: 'quantitative' },
+      color: { field: 'category', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '', prefix: '' },
+    hiddenSeries: [],
+    seriesStyles: {},
+    watermark: true,
+    display: 'full',
+    userExplicit: {
+      chrome: false,
+      legend: false,
+      endpointLabels: false,
+      xAxis: false,
+      yAxis: false,
+      labels: false,
+      animation: false,
+      watermark: false,
+      crosshair: false,
+    },
+    ...overrides,
+  };
+}
+
+describe('bar/column legend redundancy rule', () => {
+  it('hides legend when color.field matches the category axis field', () => {
+    const spec = makeBarSpec();
+    const content = computeLegendContent(spec, strategy, theme, 600, 400);
+    expect(content.entries).toHaveLength(0);
+  });
+
+  it('shows legend when user explicitly sets legend config', () => {
+    const spec = makeBarSpec({
+      legend: { show: true },
+      userExplicit: {
+        chrome: false,
+        legend: true,
+        endpointLabels: false,
+        xAxis: false,
+        yAxis: false,
+        labels: false,
+        animation: false,
+        watermark: false,
+        crosshair: false,
+      },
+    });
+    const content = computeLegendContent(spec, strategy, theme, 600, 400);
+    expect(content.entries.length).toBeGreaterThan(0);
+  });
+
+  it('shows legend when color.field differs from category axis field', () => {
+    const spec = makeBarSpec({
+      data: [
+        { category: 'A', value: 10, series: 'X' },
+        { category: 'B', value: 20, series: 'Y' },
+      ],
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'series', type: 'nominal' },
+      },
+    });
+    const content = computeLegendContent(spec, strategy, theme, 600, 400);
+    expect(content.entries.length).toBeGreaterThan(0);
+  });
+
+  it('works for horizontal bars (y is category, x is quantitative)', () => {
+    const spec = makeBarSpec({
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'category', type: 'nominal' },
+        color: { field: 'category', type: 'nominal' },
+      },
+    });
+    const content = computeLegendContent(spec, strategy, theme, 600, 400);
+    expect(content.entries).toHaveLength(0);
+  });
+});

package/src/legend/__tests__/suppression.test.ts

@@ -291,4 +291,76 @@ describe('resolveSuppression - special cases', () => {
     // Legend auto-suppressed
     expect(result.showTraditionalLegend).toBe(false);
   });
+
+  it('endpointLabels: { maxSeries: 12 } alone does NOT count as explicit on', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: { maxSeries: 12 } });
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 14 });
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showTraditionalLegend).toBe(true);
+  });
+});
+
+describe('resolveSuppression - series-count cutoff', () => {
+  it('10-series line chart exceeds default cutoff (8): legend shown, endpoint labels hidden', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 10 });
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showTraditionalLegend).toBe(true);
+  });
+
+  it('7-series line chart within default cutoff: endpoint labels shown', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 7 });
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showTraditionalLegend).toBe(false);
+  });
+
+  it('8-series line chart at exact cutoff: endpoint labels shown', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 8 });
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showTraditionalLegend).toBe(false);
+  });
+
+  it('10-series with endpointLabels: true overrides cutoff', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: true });
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 10 });
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showTraditionalLegend).toBe(false);
+  });
+
+  it('10-series with endpointLabels: { show: true } overrides cutoff', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: { show: true } });
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 10 });
+    expect(result.showEndpointLabels).toBe(true);
+  });
+
+  it('custom maxSeries: 12 allows up to 12 series', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: { maxSeries: 12 } });
+    const result12 = resolveSuppression(spec, { ...baseCtx, seriesCount: 12 });
+    expect(result12.showEndpointLabels).toBe(true);
+
+    const result13 = resolveSuppression(spec, { ...baseCtx, seriesCount: 13 });
+    expect(result13.showEndpointLabels).toBe(false);
+    expect(result13.showTraditionalLegend).toBe(true);
+  });
+
+  it('endpointLabelsDemoted hides endpoint labels and shows legend', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, {
+      ...baseCtx,
+      endpointLabelsDemoted: true,
+    });
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showTraditionalLegend).toBe(true);
+  });
+
+  it('endpointLabelsDemoted does not override explicit endpointLabels: true', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: true });
+    const result = resolveSuppression(spec, {
+      ...baseCtx,
+      endpointLabelsDemoted: true,
+    });
+    expect(result.showEndpointLabels).toBe(true);
+  });
 });

package/src/legend/compute.ts

@@ -260,6 +260,7 @@ export function computeLegendContent(
   availableHeight: number,
   watermark: boolean = true,
   measure?: MeasureFn,
+  endpointLabelsDemoted?: boolean,
 ): LegendContent {
   const measureWidth = measure ?? estimateTextWidth;
 
@@ -284,11 +285,28 @@ export function computeLegendContent(
     seriesCount,
     labelsHiddenByStrategy: strategy.labelMode === 'none',
     labelsDensityNone: spec.labels.density === 'none',
+    endpointLabelsDemoted,
   });
   if (!suppression.showTraditionalLegend) {
     entries = [];
   }
 
+  // Bar/column/lollipop redundancy rule: when color.field matches the category
+  // axis field, the legend just repeats the axis labels. Hide it unless the
+  // user explicitly configured the legend.
+  const hasRedundantLegend = spec.markType === 'bar' || spec.markType === 'lollipop';
+  if (hasRedundantLegend && entries.length > 0 && !spec.userExplicit?.legend) {
+    const colorEnc = spec.encoding.color;
+    const colorField = colorEnc && 'field' in colorEnc ? colorEnc.field : undefined;
+    if (colorField) {
+      const categoryField =
+        spec.encoding.y?.type === 'quantitative' ? spec.encoding.x?.field : spec.encoding.y?.field;
+      if (colorField === categoryField) {
+        entries = [];
+      }
+    }
+  }
+
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,

package/src/legend/suppression.ts

@@ -51,6 +51,8 @@ export interface SuppressionContext {
   labelsHiddenByStrategy: boolean;
   /** True when spec.labels.density === 'none'. */
   labelsDensityNone: boolean;
+  /** When true, endpoint labels are demoted because they don't fit at the current width. */
+  endpointLabelsDemoted?: boolean;
 }
 
 /**
@@ -69,18 +71,21 @@ function legendHiddenExplicitly(spec: NormalizedChartSpec): boolean {
   return spec.legend?.show === false;
 }
 
+/** Keys on EndpointLabelsConfig that configure behavior but don't signal show intent. */
+const EP_CONFIG_ONLY_KEYS = new Set(['show', 'maxSeries']);
+
 /**
  * Did the user explicitly set endpointLabels: true?
- * Either the bare boolean or `{ show: true }` or any other config keys count.
+ * Either the bare boolean or `{ show: true }` or any display-affecting config keys count.
+ * Config-only keys like `maxSeries` don't count as show intent.
  */
-function endpointLabelsExplicitlyOn(spec: NormalizedChartSpec): boolean {
+export function endpointLabelsExplicitlyOn(spec: NormalizedChartSpec): boolean {
   const ep = spec.endpointLabels;
   if (ep === true) return true;
   if (ep === false || ep == null) return false;
-  // Object form: explicit when show: true or any non-show key set.
   if (ep.show === true) return true;
   if (ep.show === false) return false;
-  return Object.keys(ep).some((k) => k !== 'show');
+  return Object.keys(ep).some((k) => !EP_CONFIG_ONLY_KEYS.has(k));
 }
 
 /** Did the user explicitly set endpointLabels: false (or { show: false })? */
@@ -91,6 +96,15 @@ function endpointLabelsExplicitlyOff(spec: NormalizedChartSpec): boolean {
   return false;
 }
 
+const DEFAULT_MAX_SERIES = 8;
+
+/** Read the maxSeries cutoff from the spec's endpointLabels config. */
+function getMaxSeries(spec: NormalizedChartSpec): number {
+  const ep = spec.endpointLabels;
+  if (typeof ep === 'object' && ep != null && ep.maxSeries != null) return ep.maxSeries;
+  return DEFAULT_MAX_SERIES;
+}
+
 /**
  * Resolve the three booleans from spec + context.
  *
@@ -148,13 +162,20 @@ export function resolveSuppression(
     };
   }
 
+  // Series-count cutoff: above maxSeries (default 8), treat as if endpoint
+  // labels are off so a legend shows instead. Explicit user opt-in overrides.
+  const exceedsCutoff = !endpointLabelsExplicitlyOn(spec) && ctx.seriesCount > getMaxSeries(spec);
+
+  // Auto-thinning demotion: endpoint labels don't fit at the current width.
+  const demoted = !endpointLabelsExplicitlyOn(spec) && !!ctx.endpointLabelsDemoted;
+
   // The eight-cell truth table for ≥2-series overlap line/area charts.
-  const epExplicitOff = endpointLabelsExplicitlyOff(spec);
+  const epExplicitOff = endpointLabelsExplicitlyOff(spec) || exceedsCutoff || demoted;
   const legShown = legendShownExplicitly(spec);
   const legHidden = legendHiddenExplicitly(spec);
 
   // Endpoint column: on by default; only `endpointLabels: false` (or
-  // `{ show: false }`) turns it off.
+  // `{ show: false }`) or series-count cutoff turns it off.
   const showEndpointLabels = !epExplicitOff;
 
   // Traditional legend: