@opendata-ai/openchart-engine 6.28.6 → 7.0.2

package/src/layout/dimensions.ts

@@ -19,6 +19,7 @@ import type {
   Margins,
   Rect,
   ResolvedChrome,
+  ResolvedMetricBar,
   ResolvedTheme,
 } from '@opendata-ai/openchart-core';
 import {
@@ -41,7 +42,10 @@ import {
 import { format as d3Format } from 'd3-format';
 
 import type { NormalizedChartSpec, NormalizedChrome } from '../compiler/types';
+import { predictEndpointLabelsWidth } from '../endpoint-labels/predict';
+import { countColorSeries, resolveSuppression } from '../legend/suppression';
 import { legendGap } from '../legend/wrap';
+import { computeMetricBar, metricBarHeight } from './metrics';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -59,6 +63,17 @@ export interface LayoutDimensions {
   margins: Margins;
   /** Resolved theme used for this layout. */
   theme: ResolvedTheme;
+  /**
+   * Resolved metric bar (KPI cells above the chart area). Present only when
+   * spec.metrics is supplied AND the bar fits the container.
+   */
+  metrics?: ResolvedMetricBar;
+  /**
+   * Height reserved below the chart area for x-axis tick labels and the
+   * (optional) axis title. Exposed so downstream layout code (e.g. the
+   * second legend pass) can position elements below the axis row.
+   */
+  xAxisHeight: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -68,11 +83,13 @@ export interface LayoutDimensions {
 /** Convert NormalizedChrome back to a Chrome-compatible shape for computeChrome. */
 function chromeToInput(chrome: NormalizedChrome): import('@opendata-ai/openchart-core').Chrome {
   return {
+    eyebrow: chrome.eyebrow,
     title: chrome.title,
     subtitle: chrome.subtitle,
     source: chrome.source,
     byline: chrome.byline,
     footer: chrome.footer,
+    brand: chrome.brand,
   };
 }
 
@@ -93,6 +110,13 @@ function scalePadding(basePadding: number, width: number, height: number): numbe
 const MIN_CHART_WIDTH = 60;
 const MIN_CHART_HEIGHT = 40;
 
+/**
+ * Vertical breathing room added to the inline-tick label height so the
+ * topmost tick has clearance from chrome. Inline ticks sit above their
+ * gridline by `axisTick + INLINE_TICK_OVERHANG_PAD` pixels.
+ */
+const INLINE_TICK_OVERHANG_PAD = 6;
+
 /**
  * Per-display minimum chart dimensions. Sparkline mode allows much smaller
  * containers (down to ~30x20px) since the entire chart is just the mark.
@@ -107,16 +131,36 @@ function getMinChartDims(display: import('@opendata-ai/openchart-core').Display)
 }
 
 /**
- * Resolve the per-side safety padding for sparkline mode. Padding scales with
- * the user-configured mark stroke width so a thick line doesn't clip at the
- * container edge. Per-side padding = max(strokeWidth/2 + 1, 2) so even a 1px
- * stroke gets at least 2px breathing room.
+ * Resolve per-side safety padding for sparkline mode. Stroke-based padding
+ * applies to every side so a thick line doesn't clip at the container edge.
+ * Endpoint-dot padding applies only to the side that actually carries a dot:
+ * `point: 'last'` reserves space on the right, `'first'` on the left, and
+ * `true | 'endpoints' | 'transparent'` on both. This keeps tiny sparklines
+ * flush left when the endpoint dot only renders at the right edge.
  */
-function getSparklinePad(spec: NormalizedChartSpec): number {
+function getSparklinePad(spec: NormalizedChartSpec): {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+} {
   const strokeWidth = (spec.markDef as { strokeWidth?: number }).strokeWidth ?? 2;
-  const hasPoints = !!(spec.markDef as { point?: unknown }).point;
-  const pointRadius = hasPoints ? 3 : 0;
-  return Math.max(strokeWidth / 2 + 1, pointRadius + 1, 2);
+  const point = (spec.markDef as { point?: unknown }).point;
+  const strokePad = Math.max(strokeWidth / 2 + 1, 2);
+  const dotPad = 4; // r=3.5 + 0.5 — matches the terminator dot size
+
+  const dotRight =
+    point === 'last' || point === true || point === 'endpoints' || point === 'transparent';
+  const dotLeft =
+    point === 'first' || point === true || point === 'endpoints' || point === 'transparent';
+  const hasDots = dotRight || dotLeft;
+
+  return {
+    left: dotLeft ? Math.max(strokePad, dotPad) : strokePad,
+    right: dotRight ? Math.max(strokePad, dotPad) : strokePad,
+    top: hasDots ? Math.max(strokePad, dotPad) : strokePad,
+    bottom: hasDots ? Math.max(strokePad, dotPad) : strokePad,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -162,7 +206,35 @@ export function computeDimensions(
     chromeMode = 'hidden';
   }
 
-  // Compute chrome with mode and scaled padding
+  // Pre-compute the bottom-legend reservation (legend height + gap) so the
+  // chrome layout can stack source/byline/footer below the legend band.
+  // Chart-side bottom legends only — right/top/bottom-right legends don't
+  // share vertical space with bottom chrome.
+  //
+  // We narrow on `'entries' in` (a structural brand) rather than the
+  // `legendLayout.type` discriminator because `type` is optional on
+  // CategoricalLegendLayout for back-compat with older legend payloads.
+  // Once the discriminator is required everywhere, this can collapse to
+  // `legendLayout.type !== 'gradient'`.
+  const bottomLegendReservation =
+    'entries' in legendLayout &&
+    legendLayout.entries.length > 0 &&
+    legendLayout.position === 'bottom'
+      ? legendLayout.bounds.height + legendGap(width)
+      : 0;
+
+  // Compute chrome with mode and scaled padding. `bottomLegendReservation`
+  // pushes bottom chrome below the legend band; the returned bottomHeight
+  // already accounts for it, so margin math below must not re-add it.
+  //
+  // Invariant: bottom-legend space is owned by `chrome.bottomHeight`, not
+  // `margins.bottom`. The legend reservation flows like this:
+  //   bottomLegendReservation = legend.height + legendGap(width)
+  //   chrome.bottomHeight     ⊇ bottomLegendReservation  (via computeChrome)
+  //   margins.bottom          = padding + chrome.bottomHeight + xAxisHeight
+  // So the legend band is implicitly inside margins.bottom exactly once.
+  // The legend-reservation block further down explicitly skips position
+  // 'bottom' to avoid double-counting.
   const chrome = computeChrome(
     chromeToInput(spec.chrome),
     theme,
@@ -171,6 +243,7 @@ export function computeDimensions(
     chromeMode,
     padding,
     watermark,
+    bottomLegendReservation,
   );
 
   // Sparkline mode: produce a near-edge-to-edge layout. Only stroke-width-based
@@ -186,10 +259,10 @@ export function computeDimensions(
     const yAxisSpace = userExplicit.yAxis ? 30 : 0;
 
     const margins: Margins = {
-      top: chrome.topHeight + sparkPad,
-      right: sparkPad,
-      bottom: chrome.bottomHeight + sparkPad + xAxisSpace,
-      left: sparkPad + yAxisSpace,
+      top: chrome.topHeight + sparkPad.top,
+      right: sparkPad.right,
+      bottom: chrome.bottomHeight + sparkPad.bottom + xAxisSpace,
+      left: sparkPad.left + yAxisSpace,
     };
 
     // Reserve legend space only when user explicitly opted into a legend.
@@ -211,7 +284,7 @@ export function computeDimensions(
       height: Math.max(0, height - margins.top - margins.bottom),
     };
 
-    return { total, chrome, chartArea, margins, theme };
+    return { total, chrome, chartArea, margins, theme, xAxisHeight: xAxisSpace };
   }
 
   // Start with the total rect
@@ -256,31 +329,92 @@ export function computeDimensions(
     xAxisHeight = hasXAxisLabel ? 48 : 26;
   }
 
+  // Resolve effective y-axis tickPosition early so margin math can account
+  // for the inline-tick overhang. Inline y-tick labels render above their
+  // gridline inside the chart area; the topmost tick text extends roughly
+  // (tickFontSize + INLINE_TICK_OVERHANG_PAD) pixels above area.y, which
+  // would otherwise crowd the chrome→chart gap.
+  const yAxisCfgPre = (encoding.y?.axis as Record<string, unknown> | undefined) ?? undefined;
+  const yTickPositionExplicitPre = yAxisCfgPre?.tickPosition as 'inline' | 'gutter' | undefined;
+  const yIsContinuousPre = encoding.y?.type === 'quantitative' || encoding.y?.type === 'temporal';
+  const yIsLineOrAreaPre = spec.markType === 'line' || spec.markType === 'area';
+  const yAxisOrientPre = yAxisCfgPre?.orient as 'left' | 'right' | 'top' | 'bottom' | undefined;
+  const yIsInlinePre =
+    (yTickPositionExplicitPre ??
+      (yIsLineOrAreaPre && yIsContinuousPre && yAxisOrientPre !== 'right'
+        ? 'inline'
+        : 'gutter')) === 'inline';
+  const inlineTickOverhang = yIsInlinePre
+    ? theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD
+    : 0;
+
   // Build margins: padding + chrome + axis space.
   // For radial charts (arc/donut), axes don't exist, so axisMargin is only
   // added when there's actual chrome content that needs separation from the
   // chart area. When chrome is empty the margin is just padding.
-  const topAxisGap = isRadial && chrome.topHeight === 0 ? 0 : axisMargin;
+  const topAxisGap = isRadial && chrome.topHeight === 0 ? 0 : axisMargin + inlineTickOverhang;
   // Extra top padding on narrow viewports prevents iOS Safari from clipping
   // the title chrome behind the browser UI.
   const topPad = width < NARROW_VIEWPORT_MAX ? padding + TOP_PAD_EXTRA_NARROW : padding;
+  // Tentative metric-bar reservation. The bar's final inclusion is decided
+  // below by computeMetricBar, which can strip it on overflow / narrow areas.
+  // We reserve optimistically so the chart-area math is correct when the bar
+  // is kept; the rollback path subtracts it back when stripped.
+  const wantsMetrics = !!spec.metrics && spec.metrics.length > 0 && chromeMode !== 'hidden';
+  const tentativeMetricsHeight = wantsMetrics ? metricBarHeight() : 0;
+  // topAxisGap sits between the legend (or chrome, if no legend) and the
+  // chart area. It accounts for the general axis margin plus any inline
+  // tick-label overhang. Placing it after the legend (below) keeps the
+  // subtitle-to-legend gap tight while reserving physical space for ticks
+  // that protrude above the chart area.
   const margins: Margins = {
-    top: topPad + chrome.topHeight + topAxisGap,
+    top: topPad + chrome.topHeight + tentativeMetricsHeight,
     right: hPad + (isRadial ? hPad : axisMargin),
     bottom: padding + chrome.bottomHeight + xAxisHeight,
     left: hPad + (isRadial ? hPad : axisMargin),
   };
 
-  // Dynamic right margin for line/area end-of-line labels.
-  // Only reserve space when labels will actually render.
+  // Right-margin reservation for the three-way label suppression truth table:
+  //
+  //   1. Endpoint-labels column (predicted width, default ON for ≥2-series
+  //      line/area). Reserves chart-width + ENDPOINT_COLUMN_GAP + col-width.
+  //   2. Legacy end-of-line labels — only when the truth table resolves to
+  //      `showEndOfLineLabels: true` (legend hidden AND endpoint column off).
+  //   3. Right-edge text annotations — stack ADDITIVELY on top of (1) and (2)
+  //      so a callout at maxX lands between the chart area and any column to
+  //      its right.
   const labelDensity = spec.labels.density;
   const labelsHiddenByStrategy = strategy?.labelMode === 'none';
+  const seriesCount = countColorSeries(spec);
+  const sup = resolveSuppression(spec, {
+    seriesCount,
+    labelsHiddenByStrategy,
+    labelsDensityNone: labelDensity === 'none',
+  });
+
+  // (1) Endpoint-labels column reservation. predictEndpointLabelsWidth returns 0
+  // when the column would be suppressed. `labels.density` is intentionally
+  // not checked here — that switch controls only the legacy end-of-line labels.
+  let endpointWidth = 0;
+  if (sup.showEndpointLabels && !labelsHiddenByStrategy) {
+    endpointWidth = predictEndpointLabelsWidth(spec, theme);
+    if (endpointWidth > 0) {
+      // 16px gap between chart area edge and the column.
+      margins.right = Math.max(margins.right, hPad) + endpointWidth + 16;
+    }
+  }
+
+  // (2) Legacy end-of-line label reservation — fires only in the truth-table
+  // cell where end-of-line labels still render (legend hidden AND endpoint
+  // column off AND ≥2 series AND labels visible). When the endpoint column
+  // is on, this reservation is redundant and is skipped.
   if (
+    endpointWidth === 0 &&
+    sup.showEndOfLineLabels &&
     (spec.markType === 'line' || spec.markType === 'area') &&
     labelDensity !== 'none' &&
     !labelsHiddenByStrategy
   ) {
-    // Estimate label width from longest series name (color encoding domain)
     const colorEnc = encoding.color;
     const colorField = colorEnc && 'field' in colorEnc ? colorEnc.field : undefined;
     if (colorField) {
@@ -300,10 +434,10 @@ export function computeDimensions(
     }
   }
 
-  // Reserve right margin for text annotations near the chart's right edge.
-  // Without this, annotation text at the last data point clips outside the SVG.
-  // Account for anchor direction and offset.dx to avoid over-reserving space.
-  // Skip when annotations are hidden (tooltip-only at compact breakpoints).
+  // (3) Right-edge text annotations. Stacks ADDITIVELY on top of any
+  // endpoint-labels reservation so the annotation text lands between the
+  // chart area's right edge and the endpoint column. When no endpoint column
+  // is reserved, behaves as before (max-of with the existing margin).
   if (
     strategy?.annotationPosition !== 'tooltip-only' &&
     spec.annotations.length > 0 &&
@@ -336,16 +470,25 @@ export function computeDimensions(
                   textWidth / 2; // centered (top/bottom/auto)
           const rightOverflow = Math.max(0, baseRightExtent + dx);
           if (rightOverflow > 0) {
-            margins.right = Math.max(margins.right, hPad + rightOverflow + 12);
+            if (endpointWidth > 0) {
+              // Endpoint column already reserved space at the far right; the
+              // annotation lands BETWEEN the chart edge and the column, so
+              // stack additively rather than max-of.
+              margins.right += rightOverflow + 12;
+            } else {
+              margins.right = Math.max(margins.right, hPad + rightOverflow + 12);
+            }
           }
         }
       }
     }
   }
 
-  // Dynamic left margin for y-axis labels
+  // Dynamic left margin for y-axis labels (yIsInline already resolved above
+  // for inline-tick top-margin reservation).
   const yAxisSuppressed = encoding.y?.axis === false;
-  if (encoding.y && !isRadial && !yAxisSuppressed) {
+  const yIsInline = yIsInlinePre;
+  if (encoding.y && !isRadial && !yAxisSuppressed && !yIsInline) {
     if (
       spec.markType === 'bar' ||
       spec.markType === 'circle' ||
@@ -454,18 +597,28 @@ export function computeDimensions(
     margins.right = Math.max(margins.right, hPad + options.rightAxisReserve);
   }
 
-  // Reserve legend space
+  // Reserve legend space.
+  //
+  // Bottom legend: reservation is already baked into `chrome.bottomHeight`
+  // via `bottomLegendReservation`, so no additional bottom margin is needed
+  // here. The legend lands below the x-axis tick row (which is reserved via
+  // `xAxisHeight` in the base bottom margin) and source/byline/footer chrome
+  // stacks underneath the legend band rather than colliding with it.
   if ('entries' in legendLayout && legendLayout.entries.length > 0) {
     const gap = legendGap(width);
     if (legendLayout.position === 'right' || legendLayout.position === 'bottom-right') {
       margins.right += legendLayout.bounds.width + 8;
     } else if (legendLayout.position === 'top') {
       margins.top += legendLayout.bounds.height + gap;
-    } else if (legendLayout.position === 'bottom') {
-      margins.bottom += legendLayout.bounds.height + gap;
     }
+    // 'bottom' is intentionally not handled here — see bottomLegendReservation
+    // above.
   }
 
+  // Add topAxisGap after legend so it sits between the legend (or chrome
+  // when there's no legend) and the chart area.
+  margins.top += topAxisGap;
+
   // Chart area is what's left after margins
   let chartArea: Rect = {
     x: margins.left,
@@ -490,12 +643,17 @@ export function computeDimensions(
       fallbackMode as 'compact' | 'hidden',
       padding,
       watermark,
+      bottomLegendReservation,
     );
 
     // Recalculate top/bottom margins with stripped chrome.
     // Use topPad (not padding) to preserve the iOS Safari clearance on narrow viewports.
-    const fallbackTopAxisGap = isRadial && fallbackChrome.topHeight === 0 ? 0 : axisMargin;
-    const newTop = topPad + fallbackChrome.topHeight + fallbackTopAxisGap;
+    // Include the tentative metric reservation so the rollback below mirrors
+    // the primary path's invariant (margins.top includes tentativeMetricsHeight
+    // until resolveMetrics decides otherwise).
+    const fallbackTopAxisGap =
+      isRadial && fallbackChrome.topHeight === 0 ? 0 : axisMargin + inlineTickOverhang;
+    const newTop = topPad + fallbackChrome.topHeight + tentativeMetricsHeight;
     const topDelta = margins.top - newTop;
     const newBottom = padding + fallbackChrome.bottomHeight + xAxisHeight;
     const bottomDelta = margins.bottom - newBottom;
@@ -508,7 +666,8 @@ export function computeDimensions(
         legendLayout.entries.length > 0 &&
         legendLayout.position === 'top'
           ? legendLayout.bounds.height + gap
-          : 0);
+          : 0) +
+        fallbackTopAxisGap;
       margins.bottom = newBottom;
 
       chartArea = {
@@ -518,9 +677,98 @@ export function computeDimensions(
         height: Math.max(0, height - margins.top - margins.bottom),
       };
 
-      return { total, chrome: fallbackChrome, chartArea, margins, theme };
+      // Same chrome-anchored positioning as the primary path; see comment
+      // near the primary `metricsTopY` for the full stacking order.
+      const fallbackMetricsTopY = topPad + fallbackChrome.topHeight;
+      const fallbackMetricsArea = { x: hPad, width: Math.max(0, width - hPad * 2) };
+      const fallbackMetrics = wantsMetrics
+        ? resolveMetrics(
+            spec,
+            fallbackMetricsTopY,
+            fallbackMetricsArea,
+            chartArea.height,
+            options.measureText,
+          )
+        : undefined;
+      if (wantsMetrics && !fallbackMetrics) {
+        // Bar was tentatively reserved but didn't fit — roll back the top margin.
+        // Clamp at 0 as a defensive guard: even though the reservation was
+        // additive (margins.top = topPad + chrome + tentative + axisGap [+ legend])
+        // and so subtraction is mathematically safe, a negative top margin would
+        // shift the chart above the SVG viewport if any future change ever
+        // reordered the additions.
+        margins.top = Math.max(0, margins.top - tentativeMetricsHeight);
+        chartArea = {
+          ...chartArea,
+          y: margins.top,
+          height: Math.max(0, height - margins.top - margins.bottom),
+        };
+      }
+      return {
+        total,
+        chrome: fallbackChrome,
+        chartArea,
+        margins,
+        theme,
+        metrics: fallbackMetrics,
+        xAxisHeight,
+      };
     }
   }
 
-  return { total, chrome, chartArea, margins, theme };
+  // Vertical stacking order from the SVG top edge:
+  //   topPad
+  //   chrome.topHeight              (title / subtitle / eyebrow)
+  //   tentativeMetricsHeight        (KPI bar — placed here)
+  //   [optional top legend band]
+  //   topAxisGap                    (axisMargin + inlineTickOverhang)
+  //   chartArea
+  // The metric bar belongs with chrome, above the legend, so its y is
+  // computed off chrome.topHeight only — not the full legend-inclusive
+  // margins.top.
+  const metricsTopY = topPad + chrome.topHeight;
+  const metricsArea = { x: hPad, width: Math.max(0, width - hPad * 2) };
+  const resolvedMetrics = wantsMetrics
+    ? resolveMetrics(spec, metricsTopY, metricsArea, chartArea.height, options.measureText)
+    : undefined;
+  if (wantsMetrics && !resolvedMetrics) {
+    // See fallback path above for the clamp rationale.
+    margins.top = Math.max(0, margins.top - tentativeMetricsHeight);
+    chartArea = {
+      ...chartArea,
+      y: margins.top,
+      height: Math.max(0, height - margins.top - margins.bottom),
+    };
+  }
+  return {
+    total,
+    chrome,
+    chartArea,
+    margins,
+    theme,
+    metrics: resolvedMetrics,
+    xAxisHeight,
+  };
+}
+
+/**
+ * Resolve the metric bar layout. The bar spans the full chrome content width
+ * (from hPad to width - hPad), aligning with the title/eyebrow rather than
+ * indenting to the chart area's left gutter. Its `y` sits directly below
+ * chrome and above any top legend.
+ */
+function resolveMetrics(
+  spec: NormalizedChartSpec,
+  metricsTopY: number,
+  metricsArea: { x: number; width: number },
+  remainingChartHeight: number,
+  measureText: import('@opendata-ai/openchart-core').MeasureTextFn | undefined,
+): ResolvedMetricBar | undefined {
+  return computeMetricBar(
+    spec.metrics,
+    metricsTopY,
+    metricsArea,
+    remainingChartHeight,
+    measureText,
+  );
 }

package/src/layout/metrics.ts

@@ -0,0 +1,118 @@
+/**
+ * Metric bar layout: a row of KPI cells rendered above the chart area.
+ *
+ * Cells lay out evenly across the chart width. The bar is auto-stripped when
+ * the container is too narrow, when the chart area would be left too short,
+ * or when value text would overflow its allotted cell width. Sparkline mode
+ * never reserves space for metrics.
+ */
+import type {
+  MeasureTextFn,
+  Metric,
+  ResolvedMetricBar,
+  ResolvedMetricCell,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+
+// Visual constants. Sized to match the editorial KPI mock: a 10px uppercase
+// label sits above a 22px primary value, with breathing room below before the
+// chart area starts. Derived from the 4px grid.
+const LABEL_FONT_SIZE = 10;
+const VALUE_FONT_SIZE = 22;
+const LABEL_LINE_HEIGHT_RATIO = 1.4; // 14px
+const VALUE_LINE_HEIGHT_RATIO = 1.15; // ~25.3px
+const INTER_ROW_GAP = 4;
+// Breathing room above labels (separates metric row from the subtitle).
+const TOP_GAP = 16;
+// Breathing room below values (separates metric row from legend / chart top).
+const BOTTOM_GAP = 20;
+
+/** Minimum container width that can fit a metric bar. */
+const MIN_BAR_WIDTH = 480;
+/** Minimum chart-area height after metric reservation. */
+const MIN_CHART_HEIGHT = 150;
+/** Inner cell gutter so adjacent cells don't visually touch. */
+const CELL_INNER_PAD = 8;
+
+/**
+ * Total height the metric bar reserves above the chart area.
+ * Always derived from the constants above; never hardcoded at the call site.
+ */
+export function metricBarHeight(): number {
+  const labelLine = LABEL_FONT_SIZE * LABEL_LINE_HEIGHT_RATIO;
+  const valueLine = VALUE_FONT_SIZE * VALUE_LINE_HEIGHT_RATIO;
+  return TOP_GAP + labelLine + INTER_ROW_GAP + valueLine + BOTTOM_GAP;
+}
+
+/**
+ * Concatenate the visible value text used for overflow detection. Joined with
+ * single spaces because the renderer separates the spans with `dx` attributes
+ * that consume roughly a space's worth of width.
+ */
+function valueRunText(metric: Metric): string {
+  const parts = [metric.value];
+  if (metric.delta) parts.push(metric.delta);
+  if (metric.secondary) parts.push(metric.secondary);
+  return parts.join(' ');
+}
+
+/**
+ * Compute the metric bar layout. Returns `undefined` when the bar should be
+ * stripped (too narrow, chart too short, or any cell would overflow).
+ */
+export function computeMetricBar(
+  metrics: Metric[] | undefined,
+  metricsTopY: number,
+  metricsArea: { x: number; width: number },
+  remainingChartHeight: number,
+  measureText?: MeasureTextFn,
+): ResolvedMetricBar | undefined {
+  if (!metrics || metrics.length === 0) return undefined;
+  if (metricsArea.width < MIN_BAR_WIDTH) return undefined;
+  if (remainingChartHeight < MIN_CHART_HEIGHT) return undefined;
+
+  const cellWidth = metricsArea.width / metrics.length;
+
+  // Bail if any cell's value run can't fit. Half-rendered metric rows look
+  // worse than no row at all on small viewports.
+  for (const metric of metrics) {
+    const text = valueRunText(metric);
+    const measured = measureText
+      ? measureText(text, VALUE_FONT_SIZE, 510).width
+      : estimateTextWidth(text, VALUE_FONT_SIZE, 510);
+    if (measured > cellWidth - CELL_INNER_PAD) return undefined;
+  }
+
+  const labelLine = LABEL_FONT_SIZE * LABEL_LINE_HEIGHT_RATIO;
+  const labelY = metricsTopY + TOP_GAP + LABEL_FONT_SIZE; // baseline for uppercase label
+  const valueY = metricsTopY + TOP_GAP + labelLine + INTER_ROW_GAP + VALUE_FONT_SIZE;
+
+  const cells: ResolvedMetricCell[] = metrics.map((metric, i) => ({
+    x: metricsArea.x + i * cellWidth,
+    cellWidth,
+    labelY,
+    valueY,
+    metric,
+    overflowed: false,
+  }));
+
+  return {
+    y: metricsTopY,
+    height: metricBarHeight(),
+    cells,
+  };
+}
+
+// Exposed for tests and consumers needing the same constants.
+export const METRIC_BAR_INTERNALS = {
+  LABEL_FONT_SIZE,
+  VALUE_FONT_SIZE,
+  LABEL_LINE_HEIGHT_RATIO,
+  VALUE_LINE_HEIGHT_RATIO,
+  INTER_ROW_GAP,
+  TOP_GAP,
+  BOTTOM_GAP,
+  MIN_BAR_WIDTH,
+  MIN_CHART_HEIGHT,
+  CELL_INNER_PAD,
+};

package/src/layout/scales.ts

@@ -738,13 +738,50 @@ export function computeScales(
       spec.markType === 'bar' &&
       (encoding.x?.type === 'nominal' || encoding.x?.type === 'ordinal') &&
       encoding.y.type === 'quantitative';
-    const yStackDisabled = encoding.y.stack === null || encoding.y.stack === false;
+    // Bar default is stacked, so undefined counts as stacked. Area default is
+    // overlap (v6), so the stacked-domain expansion only applies when the user
+    // explicitly opts into stacking.
+    const stackProp = encoding.y.stack;
+    const isExplicitlyStacked =
+      stackProp === true ||
+      stackProp === 'zero' ||
+      stackProp === 'normalize' ||
+      stackProp === 'center';
+    const isAreaStacked = spec.markType === 'area' && isExplicitlyStacked;
+    const isBarStacked = isVerticalBar && stackProp !== null && stackProp !== false;
+
+    // Sparkline tightening: drop the default `zero: true` baseline so the
+    // y-domain hugs the actual data range. Without this, a series with
+    // values in the 4000s renders as a near-flat line because most of the
+    // chart area gets reserved for the gap between zero and the data.
+    //
+    // Applies to:
+    //   - Line / area sparklines (always — variation is the whole point)
+    //   - Vertical bar sparklines, but ONLY when no real stacking is in
+    //     play. Two ways to opt OUT of bar tightening:
+    //       1. Real stacking — color/group encoding plus a non-disabled
+    //          stack — needs the zero baseline to keep segment arithmetic
+    //          summing.
+    //       2. Any explicit `encoding.y.stack` value signals the user
+    //          wants stack semantics even on a single series; respect that.
+    const hasStackingGroup = isBarStacked && encoding.color !== undefined;
+    const userRequestedStack = isExplicitlyStacked;
+    const isLineOrArea = spec.markType === 'line' || spec.markType === 'area';
+    const sparklineTightenBar =
+      isVerticalBar && !hasStackingGroup && !userRequestedStack && !isAreaStacked;
+    const sparklineTightenLineArea = isLineOrArea && !isAreaStacked;
     if (
-      (isVerticalBar || spec.markType === 'area') &&
-      encoding.color &&
+      spec.display === 'sparkline' &&
+      (sparklineTightenBar || sparklineTightenLineArea) &&
       encoding.y.type === 'quantitative' &&
-      !yStackDisabled
+      encoding.y.scale?.zero === undefined
     ) {
+      yChannel = {
+        ...encoding.y,
+        scale: { ...encoding.y.scale, zero: false },
+      };
+    }
+    if ((isBarStacked || isAreaStacked) && encoding.color && encoding.y.type === 'quantitative') {
       if (encoding.y.stack === 'normalize') {
         // Normalize: domain is [0, 1] (VL convention)
         yChannel = { ...encoding.y, scale: { ...encoding.y.scale, domain: [0, 1], nice: false } };