@opendata-ai/openchart-engine 6.28.5 → 7.0.0

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

@@ -0,0 +1,294 @@
+/**
+ * Truth-table tests for the centralized legend / endpoint / end-of-line label
+ * suppression helper. Covers all 8 cells of the matrix described in
+ * `suppression.ts`, plus the special cases (single-series, stacked area,
+ * compact strategy).
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import { countColorSeries, resolveSuppression } from '../suppression';
+
+// ---------------------------------------------------------------------------
+// Spec factory
+// ---------------------------------------------------------------------------
+
+function makeMultiSeriesLineSpec(
+  overrides: Partial<NormalizedChartSpec> = {},
+): NormalizedChartSpec {
+  return {
+    markType: 'line',
+    markDef: { type: 'line' },
+    data: [
+      { date: '2020', value: 10, country: 'US' },
+      { date: '2021', value: 20, country: 'US' },
+      { date: '2020', value: 5, country: 'UK' },
+      { date: '2021', value: 15, country: 'UK' },
+    ],
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+      color: { field: 'country', 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,
+  };
+}
+
+const baseCtx = {
+  seriesCount: 2,
+  labelsHiddenByStrategy: false,
+  labelsDensityNone: false,
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('countColorSeries', () => {
+  it('returns the number of distinct values in the color field', () => {
+    const spec = makeMultiSeriesLineSpec();
+    expect(countColorSeries(spec)).toBe(2);
+  });
+
+  it('returns 0 when no color encoding is set', () => {
+    const spec = makeMultiSeriesLineSpec({
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    });
+    expect(countColorSeries(spec)).toBe(0);
+  });
+
+  it('returns 0 when color is quantitative', () => {
+    const spec = makeMultiSeriesLineSpec({
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'value', type: 'quantitative' },
+      },
+    });
+    expect(countColorSeries(spec)).toBe(0);
+  });
+});
+
+describe('resolveSuppression - 8-cell truth table', () => {
+  // Cell 1: legend unset, endpointLabels unset
+  //   -> traditional legend hidden, endpoint column shown, end-of-line hidden
+  it('cell 1 (unset, unset): hides legend, shows endpoint column', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(false);
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  // Cell 2: legend: { show: true }, endpointLabels unset
+  //   -> traditional legend shown, endpoint column shown, end-of-line hidden
+  it('cell 2 (legend: true, unset): shows both legend and endpoint column', () => {
+    const spec = makeMultiSeriesLineSpec({ legend: { show: true } });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(true);
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  // Cell 3: legend unset, endpointLabels: false
+  //   -> traditional legend shown (auto-revoked), column hidden, end-of-line hidden
+  it('cell 3 (unset, endpointLabels: false): auto-revokes legend, hides column', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: false });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(true);
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  // Cell 4: legend: { show: false }, endpointLabels: false
+  //   -> all legend surfaces off, end-of-line labels are last resort
+  it('cell 4 (legend: false, endpointLabels: false): only end-of-line labels show', () => {
+    const spec = makeMultiSeriesLineSpec({
+      legend: { show: false },
+      endpointLabels: false,
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(false);
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(true);
+  });
+
+  // Cell 5: legend: { show: true }, endpointLabels: false
+  //   -> legend shown, column hidden, end-of-line hidden
+  it('cell 5 (legend: true, endpointLabels: false): legend only', () => {
+    const spec = makeMultiSeriesLineSpec({
+      legend: { show: true },
+      endpointLabels: false,
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(true);
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  // Cell 6: legend: { show: false }, endpointLabels: true
+  //   -> legend off, column on, end-of-line hidden
+  it('cell 6 (legend: false, endpointLabels: true): column only', () => {
+    const spec = makeMultiSeriesLineSpec({
+      legend: { show: false },
+      endpointLabels: true,
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(false);
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  // Cell 7: legend: { show: true }, endpointLabels: true
+  //   -> both surfaces shown, end-of-line hidden
+  it('cell 7 (legend: true, endpointLabels: true): both shown', () => {
+    const spec = makeMultiSeriesLineSpec({
+      legend: { show: true },
+      endpointLabels: true,
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(true);
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  // Cell 8 (the implicit eighth cell): unset + endpointLabels: true
+  //   matches cell 1's column-on behavior, legend auto-suppressed.
+  it('cell 8 (unset, endpointLabels: true): legend auto-suppressed, column on', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: true });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(false);
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+});
+
+describe('resolveSuppression - special cases', () => {
+  it('single-series chart: column always off, legend follows its own rules', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, { ...baseCtx, seriesCount: 1 });
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(false);
+    expect(result.showTraditionalLegend).toBe(true);
+  });
+
+  it('non-line/area mark: column always off', () => {
+    const spec = makeMultiSeriesLineSpec({ markType: 'bar' });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  it('compact strategy (labelsHiddenByStrategy): column off, end-of-line off', () => {
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, {
+      ...baseCtx,
+      labelsHiddenByStrategy: true,
+    });
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  it('labels.density === none: scoped to end-of-line labels only (column + legend follow truth table)', () => {
+    // labels.density: 'none' is the legacy switch for end-of-line labels.
+    // It must NOT suppress the endpoint column or the traditional legend —
+    // those follow the truth table independently. End-of-line labels stay off.
+    const spec = makeMultiSeriesLineSpec();
+    const result = resolveSuppression(spec, { ...baseCtx, labelsDensityNone: true });
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+    // Cell 1 (legend unset, endpointLabels unset): traditional legend hidden.
+    expect(result.showTraditionalLegend).toBe(false);
+  });
+
+  it('labels.density === none + legend.show: true: legend stays shown', () => {
+    const spec = makeMultiSeriesLineSpec({ legend: { show: true } });
+    const result = resolveSuppression(spec, { ...baseCtx, labelsDensityNone: true });
+    expect(result.showTraditionalLegend).toBe(true);
+    expect(result.showEndpointLabels).toBe(true);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  it('stacked area: legend shown by default, column off', () => {
+    const spec = makeMultiSeriesLineSpec({
+      markType: 'area',
+      markDef: { type: 'area' },
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative', stack: 'zero' },
+        color: { field: 'country', type: 'nominal' },
+      },
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showTraditionalLegend).toBe(true);
+    expect(result.showEndpointLabels).toBe(false);
+    expect(result.showEndOfLineLabels).toBe(false);
+  });
+
+  it('stacked area with explicit endpointLabels: true: column shown', () => {
+    const spec = makeMultiSeriesLineSpec({
+      markType: 'area',
+      markDef: { type: 'area' },
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative', stack: 'zero' },
+        color: { field: 'country', type: 'nominal' },
+      },
+      endpointLabels: true,
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showEndpointLabels).toBe(true);
+  });
+
+  it('overlap area (no stack): runs through 8-cell table', () => {
+    const spec = makeMultiSeriesLineSpec({
+      markType: 'area',
+      markDef: { type: 'area' },
+    });
+    const result = resolveSuppression(spec, baseCtx);
+    // Cell 1 behavior: legend hidden, column on
+    expect(result.showTraditionalLegend).toBe(false);
+    expect(result.showEndpointLabels).toBe(true);
+  });
+
+  it('endpointLabels: { show: false } counts as explicit off', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: { show: false } });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showEndpointLabels).toBe(false);
+    // Auto-revoke legend
+    expect(result.showTraditionalLegend).toBe(true);
+  });
+
+  it('endpointLabels: { width: 120 } counts as explicit on', () => {
+    const spec = makeMultiSeriesLineSpec({ endpointLabels: { width: 120 } });
+    const result = resolveSuppression(spec, baseCtx);
+    expect(result.showEndpointLabels).toBe(true);
+    // Legend auto-suppressed
+    expect(result.showTraditionalLegend).toBe(false);
+  });
+});

package/src/legend/compute.ts

@@ -23,6 +23,7 @@ import type {
 import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
+import { countColorSeries, resolveSuppression } from './suppression';
 import { ENTRY_GAP, ENTRY_GAP_COMPACT, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from './wrap';
 
 // ---------------------------------------------------------------------------
@@ -42,6 +43,25 @@ const TOP_LEGEND_MAX_ROWS = 2;
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve the constant fields every CategoricalLegendLayout return shares
+ * (swatch geometry + chip fill). Pulled out so each early-return branch
+ * doesn't re-spell the same five fields.
+ */
+function categoricalDefaults(theme: ResolvedTheme): {
+  swatchSize: number;
+  swatchGap: number;
+  entryGap: number;
+  swatchChipFill: string;
+} {
+  return {
+    swatchSize: SWATCH_SIZE,
+    swatchGap: SWATCH_GAP,
+    entryGap: ENTRY_GAP,
+    swatchChipFill: theme.colors.annotationFill,
+  };
+}
+
 /** Determine the swatch shape based on mark type. */
 function swatchShapeForType(markType: string): LegendEntry['shape'] {
   switch (markType) {
@@ -84,6 +104,10 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
     : dataValues;
 
   const excludeSet = new Set(spec.legend?.exclude ?? []);
+  // Hidden series stay in the legend (dimmed) so the user can toggle them
+  // back on. `active: false` is the renderer's signal to apply the dimmed
+  // visual state.
+  const hiddenSet = new Set(spec.hiddenSeries);
 
   return uniqueValues
     .map((value, i) => {
@@ -98,7 +122,7 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
         label: value,
         color: palette[colorIndex % palette.length],
         shape,
-        active: true,
+        active: !hiddenSet.has(value),
       };
     })
     .filter((entry) => !excludeSet.has(entry.label));
@@ -151,6 +175,7 @@ export function computeLegend(
   // Legend explicitly hidden via show: false, or height strategy says no legend
   if (sparklineHidden || spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return {
+      type: 'categorical' as const,
       position: 'top',
       entries: [],
       bounds: { x: 0, y: 0, width: 0, height: 0 },
@@ -161,43 +186,24 @@ export function computeLegend(
         fill: theme.colors.text,
         lineHeight: 1.3,
       },
-      swatchSize: SWATCH_SIZE,
-      swatchGap: SWATCH_GAP,
-      entryGap: ENTRY_GAP,
+      ...categoricalDefaults(theme),
     };
   }
 
   let entries = extractColorEntries(spec, theme);
 
-  // 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 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;
-  // 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';
-    const quantChannel =
-      spec.encoding.y?.type === 'quantitative' ? spec.encoding.y : spec.encoding.x;
-    const stackValue = quantChannel?.stack;
-    const isStacked = stackValue !== null && stackValue !== false;
-
-    if (!isArea || !isStacked) {
-      entries = [];
-    }
+  // Consult the shared suppression truth table so the legend, endpoint column,
+  // and end-of-line labels stay in sync. The helper returns
+  // `showTraditionalLegend: false` when the endpoint column auto-takes over
+  // for ≥2-series line/area charts (and the user hasn't forced the legend on).
+  const seriesCount = countColorSeries(spec);
+  const suppression = resolveSuppression(spec, {
+    seriesCount,
+    labelsHiddenByStrategy: strategy.labelMode === 'none',
+    labelsDensityNone: spec.labels.density === 'none',
+  });
+  if (!suppression.showTraditionalLegend) {
+    entries = [];
   }
 
   const labelStyle: TextStyle = {
@@ -215,13 +221,12 @@ export function computeLegend(
   // No entries = empty legend with no space
   if (entries.length === 0) {
     return {
+      type: 'categorical' as const,
       position: resolvedPosition,
       entries: [],
       bounds: { x: 0, y: 0, width: 0, height: 0 },
       labelStyle,
-      swatchSize: SWATCH_SIZE,
-      swatchGap: SWATCH_GAP,
-      entryGap: ENTRY_GAP,
+      ...categoricalDefaults(theme),
     };
   }
 
@@ -268,6 +273,7 @@ export function computeLegend(
     const offsetDy = spec.legend?.offset?.dy ?? 0;
 
     return {
+      type: 'categorical' as const,
       position: resolvedPosition,
       entries,
       bounds: {
@@ -277,8 +283,10 @@ export function computeLegend(
         height: clampedHeight,
       },
       labelStyle,
-      swatchSize: SWATCH_SIZE,
-      swatchGap: SWATCH_GAP,
+      ...categoricalDefaults(theme),
+      // Right-positioned legends pack rows tighter than the default entryGap
+      // because each row is its own swatch+label and the gap controls
+      // vertical breathing room rather than horizontal spacing.
       entryGap: 4,
     };
   }
@@ -343,6 +351,7 @@ export function computeLegend(
   const offsetDy = spec.legend?.offset?.dy ?? 0;
 
   return {
+    type: 'categorical' as const,
     position: resolvedPosition,
     entries,
     bounds: {
@@ -355,8 +364,9 @@ export function computeLegend(
       height: legendHeight,
     },
     labelStyle,
-    swatchSize: SWATCH_SIZE,
-    swatchGap: SWATCH_GAP,
+    ...categoricalDefaults(theme),
+    // Top/bottom legends honor the compact-viewport-aware entry gap so
+    // chips stay readable on narrow widths.
     entryGap: effectiveEntryGap,
   };
 }

package/src/legend/suppression.ts

@@ -0,0 +1,204 @@
+/**
+ * Single source of truth for legend / endpoint-column / end-of-line label
+ * suppression on multi-series line/area charts.
+ *
+ * Three independent toggles drive the chart's series identification surface:
+ *
+ *   - `legend.show` — the traditional swatch legend (top/bottom/right).
+ *   - `endpointLabels` — the right-side per-series column with last value.
+ *   - end-of-line labels — the legacy series-name label glued to the last point.
+ *
+ * For ≥2-series line/area charts the resolution table is:
+ *
+ * | `legend.show` | `endpointLabels` | Traditional legend | Endpoint column | End-of-line labels |
+ * |--|--|--|--|--|
+ * | unset | unset | hidden (auto-suppressed) | shown                  | hidden |
+ * | true  | unset | shown                    | shown                  | hidden |
+ * | unset | false | shown (auto-revoked)     | hidden                 | hidden |
+ * | false | false | hidden                   | hidden                 | shown  |
+ * | true  | false | shown                    | hidden                 | hidden |
+ * | false | true  | hidden                   | shown                  | hidden |
+ * | true  | true  | shown                    | shown                  | hidden |
+ *
+ * Single-series and non-line/area charts: column always hidden, legend hidden
+ * (single-series rule), end-of-line labels never render.
+ *
+ * Rule of thumb: end-of-line labels are the fallback identifier of last resort.
+ * They render only when neither the traditional legend nor the endpoint column
+ * is showing. The endpoint column "owns" the right zone and absorbs the
+ * suppression role the traditional legend used to have for end-of-line labels.
+ */
+
+import type { Encoding } from '@opendata-ai/openchart-core';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+
+/** Result of the suppression resolution. */
+export interface SuppressionResult {
+  /** Whether the traditional swatch legend should render. */
+  showTraditionalLegend: boolean;
+  /** Whether the right-side endpoint column should render. */
+  showEndpointLabels: boolean;
+  /** Whether the legacy end-of-line labels should render. */
+  showEndOfLineLabels: boolean;
+}
+
+/** Inputs needed by the resolution helper. */
+export interface SuppressionContext {
+  /** Number of distinct series (color-encoding domain values). 0 if no color encoding. */
+  seriesCount: number;
+  /** True when responsive strategy strips inline labels (compact breakpoint). */
+  labelsHiddenByStrategy: boolean;
+  /** True when spec.labels.density === 'none'. */
+  labelsDensityNone: boolean;
+}
+
+/**
+ * Did the user write `legend.show: true` or any non-`show` legend config?
+ * (Used by the truth table to decide between the "unset" and "true" rows.)
+ */
+function legendShownExplicitly(spec: NormalizedChartSpec): boolean {
+  if (spec.legend == null) return false;
+  if (spec.legend.show === true) return true;
+  // Any non-`show` legend property counts as opt-in to render the legend.
+  return Object.keys(spec.legend).some((k) => k !== 'show');
+}
+
+/** Did the user write `legend.show: false` explicitly? */
+function legendHiddenExplicitly(spec: NormalizedChartSpec): boolean {
+  return spec.legend?.show === false;
+}
+
+/**
+ * Did the user explicitly set endpointLabels: true?
+ * Either the bare boolean or `{ show: true }` or any other config keys count.
+ */
+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');
+}
+
+/** Did the user explicitly set endpointLabels: false (or { show: false })? */
+function endpointLabelsExplicitlyOff(spec: NormalizedChartSpec): boolean {
+  const ep = spec.endpointLabels;
+  if (ep === false) return true;
+  if (typeof ep === 'object' && ep != null && ep.show === false) return true;
+  return false;
+}
+
+/**
+ * Resolve the three booleans from spec + context.
+ *
+ * Pure: no theme, no chart area, no scales. Both `computeLegend` and
+ * `computeLineLabels` and `computeEndpointLabels` share this exact logic.
+ */
+export function resolveSuppression(
+  spec: NormalizedChartSpec,
+  ctx: SuppressionContext,
+): SuppressionResult {
+  const isLineOrArea = spec.markType === 'line' || spec.markType === 'area';
+  const hasColorEncoding = spec.encoding.color != null;
+  const isMultiSeries = isLineOrArea && hasColorEncoding && ctx.seriesCount >= 2;
+
+  // Single-series, non-line/area, or compact strategy: never show endpoint
+  // column or end-of-line labels. Legend follows its own rules elsewhere.
+  //
+  // Note: `labelsDensityNone` is intentionally NOT in this short-circuit.
+  // `labels.density: 'none'` is the legacy switch for end-of-line labels and
+  // must not affect the endpoint column or the traditional legend (those
+  // are independent concerns governed by the truth table below).
+  if (!isMultiSeries || ctx.labelsHiddenByStrategy) {
+    return {
+      // Defer the legend's own show/hide rules to computeLegend; this helper
+      // doesn't override the existing legend behavior for non-multi-series.
+      showTraditionalLegend: !legendHiddenExplicitly(spec),
+      showEndpointLabels: false,
+      showEndOfLineLabels: false,
+    };
+  }
+
+  // Stacked-area branch: gradient fills overlap, so endpoint labels at the
+  // last data point would land on top of each other. Don't auto-enable the
+  // column for stacked areas. Users can still force it with `endpointLabels: true`.
+  const isArea = spec.markType === 'area';
+  const quantChannel = (
+    spec.encoding.y?.type === 'quantitative' ? spec.encoding.y : spec.encoding.x
+  ) as Encoding[keyof Encoding] | undefined;
+  const stackValue = quantChannel && 'stack' in quantChannel ? quantChannel.stack : undefined;
+  const isStacked = isArea
+    ? stackValue === true ||
+      stackValue === 'zero' ||
+      stackValue === 'normalize' ||
+      stackValue === 'center'
+    : false;
+
+  // Stacked area: revert to the pre-v6 behavior — show legend, no endpoint column.
+  if (isStacked) {
+    // Allow explicit user opt-in via endpointLabels: true even on stacked areas.
+    const explicitOn = endpointLabelsExplicitlyOn(spec);
+    return {
+      showTraditionalLegend: !legendHiddenExplicitly(spec),
+      showEndpointLabels: explicitOn,
+      showEndOfLineLabels: false,
+    };
+  }
+
+  // The eight-cell truth table for ≥2-series overlap line/area charts.
+  const epExplicitOff = endpointLabelsExplicitlyOff(spec);
+  const legShown = legendShownExplicitly(spec);
+  const legHidden = legendHiddenExplicitly(spec);
+
+  // Endpoint column: on by default; only `endpointLabels: false` (or
+  // `{ show: false }`) turns it off.
+  const showEndpointLabels = !epExplicitOff;
+
+  // Traditional legend:
+  //   - explicit hide  -> hidden
+  //   - explicit show  -> shown
+  //   - unset          -> hidden when endpoint column is on, shown otherwise
+  let showTraditionalLegend: boolean;
+  if (legHidden) {
+    showTraditionalLegend = false;
+  } else if (legShown) {
+    showTraditionalLegend = true;
+  } else {
+    showTraditionalLegend = !showEndpointLabels;
+  }
+
+  // End-of-line labels are the last-resort series identifier: they render
+  // only when both the traditional legend and the endpoint column are off.
+  // `labels.density: 'none'` is the legacy switch that explicitly disables
+  // end-of-line labels regardless of the other toggles.
+  const showEndOfLineLabels =
+    !showTraditionalLegend && !showEndpointLabels && !ctx.labelsDensityNone;
+
+  return {
+    showTraditionalLegend,
+    showEndpointLabels,
+    showEndOfLineLabels,
+  };
+}
+
+/**
+ * Count distinct series for the color encoding (for use in
+ * SuppressionContext.seriesCount). Returns 0 when no color encoding is set
+ * or when the encoding is conditional/quantitative.
+ */
+export function countColorSeries(spec: NormalizedChartSpec): number {
+  const colorEnc = spec.encoding.color;
+  if (!colorEnc) return 0;
+  if ('condition' in colorEnc) return 0;
+  if (colorEnc.type === 'quantitative') return 0;
+  const field = colorEnc.field;
+  if (!field) return 0;
+  const seen = new Set<string>();
+  for (const row of spec.data) {
+    seen.add(String(row[field]));
+  }
+  return seen.size;
+}

package/src/sankey/compile-sankey.ts

@@ -590,6 +590,7 @@ function buildSankeyLegend(
     swatchSize: SWATCH_SIZE,
     swatchGap: SWATCH_GAP,
     entryGap: ENTRY_GAP,
+    swatchChipFill: theme.colors.annotationFill,
   };
 }
 
@@ -674,6 +675,7 @@ function emptyLayout(
       swatchSize: SWATCH_SIZE,
       swatchGap: SWATCH_GAP,
       entryGap: ENTRY_GAP,
+      swatchChipFill: theme.colors.annotationFill,
     },
     tooltipDescriptors: new Map(),
     a11y: {