@opendata-ai/openchart-engine 7.6.1 → 7.8.0

package/src/compiler/normalize.ts

@@ -217,6 +217,43 @@ function normalizeLabels(labels?: LabelSpec): NormalizedChartSpec['labels'] {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Highlight normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize `encoding.color.highlight` to a flat string array.
+ * Warns when highlight values don't appear in the data.
+ */
+function normalizeHighlight(encoding: Encoding, data: DataRow[], warnings: string[]): string[] {
+  const color = encoding.color;
+  if (!color || !('field' in color)) return [];
+  const raw = (color as { highlight?: string | string[] }).highlight;
+  if (raw == null) return [];
+  const highlight = Array.isArray(raw) ? raw : [raw];
+
+  // Warn on unknown values
+  if (highlight.length > 0 && data.length > 0) {
+    const colorField = color.field;
+    const knownValues = new Set(data.map((row) => String(row[colorField])));
+    for (const v of highlight) {
+      if (!knownValues.has(v)) {
+        warnings.push(
+          `[openchart] encoding.color.highlight value "${v}" does not match any value in the "${colorField}" data column`,
+        );
+      }
+    }
+  }
+
+  if (highlight.length > 0 && color.scale?.range) {
+    warnings.push(
+      '[openchart] encoding.color.highlight has no effect on color assignment when encoding.color.scale.range is explicitly provided',
+    );
+  }
+
+  return highlight;
+}
+
 // ---------------------------------------------------------------------------
 // Spec-level normalization
 // ---------------------------------------------------------------------------
@@ -250,13 +287,19 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     labels: normalizeLabels(spec.labels),
     legend: spec.legend,
     endpointLabels: spec.endpointLabels,
-    responsive: spec.responsive ?? true,
+    responsive: typeof spec.responsive === 'object' ? true : (spec.responsive ?? true),
+    autoThin:
+      typeof spec.responsive === 'object'
+        ? (spec.responsive.autoThin ?? true)
+        : (spec.responsive ?? true),
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? 'off',
     hiddenSeries: spec.hiddenSeries ?? [],
     seriesStyles: spec.seriesStyles ?? {},
     watermark: spec.watermark ?? true,
+    highlight: normalizeHighlight(encoding, spec.data, warnings),
     display,
+    resolve: spec.resolve,
     // Default empty userExplicit; compileChart overwrites this with the real
     // descriptor built from the raw expanded spec before normalize runs.
     userExplicit: {
@@ -353,15 +396,36 @@ function normalizeTileMapSpec(spec: TileMapSpec, warnings: string[]): Normalized
     data = Object.entries(spec.data).map(([state, value]) => ({ state, value }));
   }
 
+  // Detect categorical mode: colors map provided, color encoding channel, or string values
+  const hasStringValues =
+    !Array.isArray(spec.data) && Object.values(spec.data).some((v) => typeof v === 'string');
+  const isCategorical =
+    spec.colors !== undefined || spec.encoding?.color !== undefined || hasStringValues;
+
+  // Warn on mixed number/string values in record map (likely a data quality issue)
+  if (hasStringValues && !Array.isArray(spec.data)) {
+    const hasNumericValues = Object.values(spec.data).some((v) => typeof v === 'number');
+    if (hasNumericValues) {
+      warnings.push(
+        'TileMap data: record map contains mixed number and string values. Treating as categorical. Use all numbers for quantitative or all strings for categorical.',
+      );
+    }
+  }
+
   // Auto-generate encoding if not provided
   let encoding = spec.encoding;
   if (!encoding) {
     encoding = {
       state: { field: 'state', type: 'nominal' },
-      value: { field: 'value', type: 'quantitative' },
+      value: { field: 'value', type: isCategorical ? 'nominal' : 'quantitative' },
     };
   }
 
+  // For categorical record maps without explicit color encoding, use value as color channel
+  if (isCategorical && !encoding.color) {
+    encoding = { ...encoding, color: encoding.value };
+  }
+
   // Count matched states and warn if low match ratio
   let matchedCount = 0;
   for (const row of data) {
@@ -383,6 +447,7 @@ function normalizeTileMapSpec(spec: TileMapSpec, warnings: string[]): Normalized
     data,
     encoding,
     palette: spec.palette ?? 'blue',
+    colors: spec.colors,
     chrome: normalizeChrome(spec.chrome),
     legend: spec.legend,
     theme: spec.theme ?? {},

package/src/compiler/types.ts

@@ -116,6 +116,8 @@ export interface NormalizedChartSpec {
   /** Right-side endpoint labels column config (multi-series line/area only). */
   endpointLabels?: boolean | import('@opendata-ai/openchart-core').EndpointLabelsConfig;
   responsive: boolean;
+  /** Whether auto-thinning of annotations at narrow widths is enabled. Resolved from `responsive.autoThin`. */
+  autoThin: boolean;
   theme: ThemeConfig;
   darkMode: DarkMode;
   /** Whether the tryOpenData.ai watermark is enabled. */
@@ -126,12 +128,20 @@ export interface NormalizedChartSpec {
   seriesStyles: Record<string, import('@opendata-ai/openchart-core').SeriesStyle>;
   /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
   display: Display;
+  /** Resolve configuration for independent/shared scales in faceted charts. */
+  resolve?: import('@opendata-ai/openchart-core').ResolveConfig;
   /**
    * Which top-level fields the user explicitly set. Populated by compileChart
    * from the raw expanded spec before normalization. NormalizeChartSpec runs
    * with a default-empty descriptor; compileChart overwrites it post-normalize.
    */
   userExplicit: UserExplicit;
+  /**
+   * Series values to visually emphasize. Non-highlighted series are muted to
+   * a neutral gray. Normalized from `encoding.color.highlight` (always an
+   * array; empty when no highlight is active).
+   */
+  highlight: string[];
 }
 
 /** A TableSpec with all optional fields filled with sensible defaults. */

package/src/compiler/validate.ts

@@ -11,6 +11,7 @@
 
 import {
   type FieldType,
+  inferFieldType,
   MARK_ENCODING_RULES,
   MARK_TYPES,
   type MarkType,
@@ -269,6 +270,84 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
     }
   }
 
+  // Validate highlight on the color channel
+  if (encoding) {
+    const colorCh = (encoding as Record<string, Record<string, unknown> | undefined>).color;
+    if (colorCh && colorCh.highlight != null) {
+      const hlVal = colorCh.highlight;
+      const isValidType =
+        typeof hlVal === 'string' ||
+        (Array.isArray(hlVal) && hlVal.every((v: unknown) => typeof v === 'string'));
+      if (!isValidType) {
+        errors.push({
+          message: 'Spec error: encoding.color.highlight must be a string or array of strings',
+          path: 'encoding.color.highlight',
+          code: 'INVALID_TYPE',
+          suggestion: 'Provide a series name (string) or an array of series names.',
+        });
+      } else {
+        const colorType =
+          (colorCh.type as string | undefined) ??
+          (colorCh.field && Array.isArray(spec.data) && spec.data.length > 0
+            ? inferFieldType(spec.data as Record<string, unknown>[], colorCh.field as string)
+            : undefined);
+        if (colorType === 'quantitative') {
+          errors.push({
+            message:
+              'Spec error: encoding.color.highlight is not supported on quantitative color channels',
+            path: 'encoding.color.highlight',
+            code: 'INVALID_VALUE',
+            suggestion:
+              'Highlight works with nominal/ordinal color (categorical series). Remove highlight or change encoding.color.type to nominal.',
+          });
+        }
+      }
+    }
+  }
+
+  // Validate facet channel if provided
+  if (encoding.facet && typeof encoding.facet === 'object') {
+    const facet = encoding.facet as Record<string, unknown>;
+    if (!facet.field || typeof facet.field !== 'string') {
+      errors.push({
+        message: 'Spec error: encoding.facet.field is required and must be a non-empty string',
+        path: 'encoding.facet.field',
+        code: 'MISSING_FIELD',
+        suggestion:
+          'Add a field property to encoding.facet (e.g. { field: "category", type: "nominal" })',
+      });
+    } else if (
+      !dataColumns.has(facet.field as string) &&
+      !transformFields.has(facet.field as string)
+    ) {
+      errors.push({
+        message: `Spec error: encoding.facet.field "${facet.field}" does not exist in data. Available columns: ${availableColumns}`,
+        path: 'encoding.facet.field',
+        code: 'DATA_FIELD_MISSING',
+        suggestion: `Use one of the available data columns: ${availableColumns}`,
+      });
+    }
+    if (!facet.type || (facet.type !== 'nominal' && facet.type !== 'ordinal')) {
+      errors.push({
+        message: `Spec error: encoding.facet.type must be "nominal" or "ordinal"${facet.type ? `, got "${facet.type}"` : ''}`,
+        path: 'encoding.facet.type',
+        code: facet.type ? 'INVALID_VALUE' : 'MISSING_FIELD',
+        suggestion: 'Set encoding.facet.type to "nominal" or "ordinal"',
+      });
+    }
+    if (facet.columns !== undefined) {
+      const cols = Number(facet.columns);
+      if (!Number.isInteger(cols) || cols < 1) {
+        errors.push({
+          message: 'Spec error: encoding.facet.columns must be a positive integer',
+          path: 'encoding.facet.columns',
+          code: 'INVALID_VALUE',
+          suggestion: 'Set columns to a positive integer (e.g. 3)',
+        });
+      }
+    }
+  }
+
   // Validate darkMode if provided
   if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
     errors.push({

package/src/endpoint-labels/__tests__/compute.test.ts

@@ -439,4 +439,61 @@ describe('computeEndpointLabels', () => {
       expect(entry.color).toBe(lineColor);
     }
   });
+
+  it('produces leading entries when ends: "both"', () => {
+    const spec = makeSpec({ endpointLabels: { ends: 'both' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    expect(layout.entries).toHaveLength(2);
+    expect(layout.leading).toBeDefined();
+    expect(layout.leading).toHaveLength(2);
+    const leadingKeys = layout.leading!.map((e) => e.seriesKey).sort();
+    expect(leadingKeys).toEqual(['UK', 'US']);
+  });
+
+  it('positions leading column to the left of the chart area', () => {
+    const spec = makeSpec({ endpointLabels: { ends: 'both' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    expect(layout.leadingBounds).toBeDefined();
+    expect(layout.leadingBounds!.x + layout.leadingBounds!.width).toBeLessThanOrEqual(chartArea.x);
+    expect(layout.leadingBounds!.width).toBeGreaterThan(0);
+  });
+
+  it('leading entries use the first data point value', () => {
+    const spec = makeSpec({ endpointLabels: { ends: 'both' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    const usTrailing = layout.entries.find((e) => e.seriesKey === 'US');
+    const usLeading = layout.leading!.find((e) => e.seriesKey === 'US');
+    expect(usTrailing).toBeDefined();
+    expect(usLeading).toBeDefined();
+    // The first data point has value - 5 (35 for US), the last has the full value (40).
+    expect(usLeading!.value).not.toBe(usTrailing!.value);
+  });
+
+  it('does not produce leading entries when ends is unset (default)', () => {
+    const spec = makeSpec();
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    expect(layout.leading).toBeUndefined();
+    expect(layout.leadingBounds).toBeUndefined();
+  });
+
+  it('leading entries get markers at the first data point', () => {
+    const spec = makeSpec({ endpointLabels: { ends: 'both' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    for (const entry of layout.leading!) {
+      expect(entry.marker).toBeDefined();
+      expect(entry.marker!.dataX).toBe(chartArea.x);
+      // Leading marker offset: x = dataX - radius (left side).
+      expect(entry.marker!.x).toBe(chartArea.x - ENDPOINT_MARKER_RADIUS);
+    }
+  });
 });

package/src/endpoint-labels/compute.ts

@@ -68,6 +68,7 @@ function emptyLayout(theme: ResolvedTheme): EndpointLabelsLayout {
     fontWeight: ENDPOINT_VALUE_FONT_WEIGHT,
     fill: theme.colors.annotationText ?? theme.colors.text,
     lineHeight: ENDPOINT_LINE_HEIGHT,
+    fontVariant: 'tabular-nums',
   };
   return {
     entries: [],
@@ -91,8 +92,6 @@ function lastDataPoint(mark: LineMark | AreaMark): { x: number; y: number } | nu
     const last = mark.dataPoints[mark.dataPoints.length - 1];
     return { x: last.x, y: last.y };
   }
-  // Fallback for marks compiled without dataPoints (rare): use the last
-  // geometry point. For areas this is the top boundary.
   if (mark.type === 'line' && mark.points.length > 0) {
     const last = mark.points[mark.points.length - 1];
     return { x: last.x, y: last.y };
@@ -104,7 +103,24 @@ function lastDataPoint(mark: LineMark | AreaMark): { x: number; y: number } | nu
   return null;
 }
 
-/** Get the value to display from a data row. */
+/** Get the first data-point pixel position for a line/area mark. */
+function firstDataPoint(mark: LineMark | AreaMark): { x: number; y: number } | null {
+  if (mark.dataPoints && mark.dataPoints.length > 0) {
+    const first = mark.dataPoints[0];
+    return { x: first.x, y: first.y };
+  }
+  if (mark.type === 'line' && mark.points.length > 0) {
+    const first = mark.points[0];
+    return { x: first.x, y: first.y };
+  }
+  if (mark.type === 'area' && mark.topPoints.length > 0) {
+    const first = mark.topPoints[0];
+    return { x: first.x, y: first.y };
+  }
+  return null;
+}
+
+/** Get the value to display from the last data row. */
 function readValue(
   mark: LineMark | AreaMark,
   valueField: string | undefined,
@@ -123,6 +139,25 @@ function readValue(
   return null;
 }
 
+/** Get the value to display from the first data row. */
+function readFirstValue(
+  mark: LineMark | AreaMark,
+  valueField: string | undefined,
+): number | string | null {
+  if (!valueField) return null;
+  const dp = mark.dataPoints;
+  if (dp && dp.length > 0) {
+    const datum = dp[0].datum;
+    const v = datum[valueField];
+    return typeof v === 'number' || typeof v === 'string' ? v : null;
+  }
+  if (mark.data.length > 0) {
+    const v = mark.data[0][valueField];
+    return typeof v === 'number' || typeof v === 'string' ? v : null;
+  }
+  return null;
+}
+
 /**
  * Local collision sweep: keep each label anchored to its line's `dataY` and
  * only displace neighbors that actually overlap.
@@ -213,19 +248,26 @@ export function computeEndpointLabels(
   theme: ResolvedTheme,
   chartArea: Rect,
   strategy?: LayoutStrategy,
+  endpointLabelsDemoted?: boolean,
 ): EndpointLabelsLayout {
   // Compact strategy: drop the column entirely. The traditional legend takes
   // over series identification at the compact breakpoint.
   if (strategy?.labelMode === 'none') return emptyLayout(theme);
 
+  const highlight = spec.highlight ?? [];
+  const highlightActive = highlight.length > 0;
   const seriesCount = countColorSeries(spec);
   const sup = resolveSuppression(spec, {
     seriesCount,
     // The 'none' branch above returned; by here labelMode is not 'none'.
     labelsHiddenByStrategy: false,
     labelsDensityNone: spec.labels.density === 'none',
+    endpointLabelsDemoted,
   });
-  if (!sup.showEndpointLabels) return emptyLayout(theme);
+  const epExplicitlyOff =
+    spec.endpointLabels === false ||
+    (typeof spec.endpointLabels === 'object' && spec.endpointLabels?.show === false);
+  if (!sup.showEndpointLabels && !(highlightActive && !epExplicitlyOff)) return emptyLayout(theme);
 
   // Dedupe by seriesKey: for area charts, the engine emits BOTH an AreaMark
   // and a derived LineMark per series (see `linesFromAreas` in
@@ -271,6 +313,7 @@ export function computeEndpointLabels(
     fontWeight: ENDPOINT_VALUE_FONT_WEIGHT,
     fill: theme.colors.annotationText ?? theme.colors.text,
     lineHeight: ENDPOINT_LINE_HEIGHT,
+    fontVariant: 'tabular-nums',
   };
 
   // First pass: build entries with wrapped labels and dataY (no positions yet).
@@ -291,6 +334,9 @@ export function computeEndpointLabels(
   for (const mark of lineOrAreaMarks) {
     const seriesKey = mark.seriesKey;
     if (!seriesKey) continue;
+
+    if (highlightActive && !highlight.includes(seriesKey)) continue;
+
     const last = lastDataPoint(mark);
     if (!last) continue;
 
@@ -338,7 +384,8 @@ export function computeEndpointLabels(
     });
   }
 
-  if (provisional.length < 2) return emptyLayout(theme);
+  if (provisional.length === 0) return emptyLayout(theme);
+  if (provisional.length < 2 && !highlightActive) return emptyLayout(theme);
 
   // Bidirectional collision sweep. Each entry's natural top is `dataY - labelFontSize/2`
   // so the label's first-line baseline-center aligns with the line's last data point.
@@ -401,6 +448,131 @@ export function computeEndpointLabels(
     return entry;
   });
 
+  // Leading column (left side) for `ends: 'both'` mode.
+  const endsBoth = config?.ends === 'both';
+  let leading: EndpointLabelEntry[] | undefined;
+  let leadingBounds: { x: number; y: number; width: number; height: number } | undefined;
+
+  if (endsBoth) {
+    type LeadingProvisional = {
+      seriesKey: string;
+      labelLines: string[];
+      value: string;
+      color: string;
+      dataX: number;
+      dataY: number;
+      height: number;
+      width: number;
+    };
+    const leadingProvisional: LeadingProvisional[] = [];
+
+    for (const mark of lineOrAreaMarks) {
+      const seriesKey = mark.seriesKey;
+      if (!seriesKey) continue;
+
+      if (highlightActive && !highlight.includes(seriesKey)) continue;
+
+      const first = firstDataPoint(mark);
+      if (!first) continue;
+
+      const labelLines = wrapText(
+        seriesKey,
+        ENDPOINT_LABEL_FONT_SIZE,
+        ENDPOINT_LABEL_FONT_WEIGHT,
+        wrapWidth,
+      );
+      const rawValue = readFirstValue(mark, valueField);
+      const value = formatEndpointValue(rawValue, formatString);
+
+      let entryWidth = 0;
+      for (const line of labelLines) {
+        const w = estimateTextWidth(line, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+        if (w > entryWidth) entryWidth = w;
+      }
+      const valueWidth = value
+        ? estimateTextWidth(value, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT)
+        : 0;
+      if (valueWidth > entryWidth) entryWidth = valueWidth;
+
+      const labelHeight = labelLines.length * labelLineHeight;
+      const valueHeight = value ? valueLineHeight : 0;
+      const entryHeight = labelHeight + (value ? ENDPOINT_VALUE_GAP : 0) + valueHeight;
+
+      const color =
+        mark.type === 'line'
+          ? mark.stroke
+          : (mark.stroke ??
+            (typeof mark.fill === 'string' ? mark.fill : theme.colors.categorical[0]));
+
+      leadingProvisional.push({
+        seriesKey,
+        labelLines,
+        value,
+        color,
+        dataX: first.x,
+        dataY: first.y,
+        height: entryHeight,
+        width: entryWidth,
+      });
+    }
+
+    if (leadingProvisional.length >= 2 || (leadingProvisional.length === 1 && highlightActive)) {
+      const leadingSweepInput = leadingProvisional.map((p, i) => ({
+        naturalTop: p.dataY - ENDPOINT_LABEL_FONT_SIZE / 2,
+        height: p.height + ENDPOINT_ENTRY_GAP,
+        index: i,
+      }));
+      const leadingSweptTops = bidirectionalSweep(
+        leadingSweepInput,
+        chartArea.y,
+        chartArea.y + chartArea.height,
+      );
+
+      const leadingColumnWidth = Math.max(
+        ENDPOINT_SWATCH_SIZE +
+          ENDPOINT_GAP +
+          Math.max(...leadingProvisional.map((p) => p.width), 0) +
+          4,
+        32,
+      );
+      const leadingColumnX = chartArea.x - ENDPOINT_COLUMN_GAP - leadingColumnWidth;
+
+      leading = leadingProvisional.map((p, i) => {
+        const labelY = leadingSweptTops[i];
+        const swatchRowY = labelY + ENDPOINT_LABEL_FONT_SIZE / 2;
+        const displaced = Math.abs(swatchRowY - p.dataY) > ENDPOINT_LEADER_THRESHOLD;
+        const entry: EndpointLabelEntry = {
+          seriesKey: p.seriesKey,
+          labelLines: p.labelLines,
+          value: p.value,
+          color: p.color,
+          dataY: p.dataY,
+          labelY,
+          showLeader: showLeader && displaced,
+        };
+        if (showMarker) {
+          entry.marker = {
+            x: p.dataX - markerRadius,
+            y: p.dataY,
+            dataX: p.dataX,
+            fill: markerFill,
+            stroke: config?.markerStyle?.stroke ?? p.color,
+            strokeWidth: markerStrokeWidth,
+            radius: markerRadius,
+          };
+        }
+        return entry;
+      });
+
+      leadingBounds = {
+        x: leadingColumnX,
+        y: chartArea.y,
+        width: leadingColumnWidth,
+        height: chartArea.height,
+      };
+    }
+  }
+
   return {
     entries,
     bounds: {
@@ -415,5 +587,7 @@ export function computeEndpointLabels(
     gap: ENDPOINT_GAP,
     valueGap: ENDPOINT_VALUE_GAP,
     swatchChipFill: theme.colors.annotationFill ?? theme.colors.background,
+    leading,
+    leadingBounds,
   };
 }

package/src/endpoint-labels/predict.ts

@@ -16,6 +16,7 @@ import type { ResolvedTheme } from '@opendata-ai/openchart-core';
 import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
+import { endpointLabelsExplicitlyOn } from '../legend/suppression';
 import {
   ENDPOINT_GAP,
   ENDPOINT_LABEL_FONT_SIZE,
@@ -59,6 +60,13 @@ export function predictEndpointLabelsWidth(
   // for the bare boolean; also handle the object form `{ show: false }`.)
   if (typeof spec.endpointLabels === 'object' && spec.endpointLabels?.show === false) return 0;
 
+  // Series-count cutoff: above maxSeries (default 8), skip endpoint labels
+  // unless the user explicitly enabled them. Uses the same explicit-on logic
+  // as suppression.ts to keep predict and render decisions aligned.
+  const maxSeries =
+    (typeof spec.endpointLabels === 'object' && spec.endpointLabels?.maxSeries) || 8;
+  if (!endpointLabelsExplicitlyOn(spec) && seriesNames.size > maxSeries) return 0;
+
   const config = typeof spec.endpointLabels === 'object' ? spec.endpointLabels : undefined;
   const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
 
@@ -106,3 +114,12 @@ export function predictEndpointLabelsWidth(
   const textColumn = Math.max(maxLabelWidth, valueWidth);
   return ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + textColumn + 4;
 }
+
+/**
+ * Returns true when the spec requests both-ends endpoint labels.
+ * Used by `computeDimensions` to also reserve left margin space.
+ */
+export function isEndsBoth(spec: NormalizedChartSpec): boolean {
+  const ep = spec.endpointLabels;
+  return typeof ep === 'object' && ep != null && ep.ends === 'both';
+}