@opendata-ai/openchart-engine 6.28.6 → 7.0.2

package/src/endpoint-labels/compute.ts

@@ -0,0 +1,417 @@
+/**
+ * Endpoint labels: per-series right-side label column for multi-series
+ * line/area charts. Each entry pairs the series name with its last formatted
+ * value, optionally anchored to the line by an open-circle marker.
+ *
+ * Single-pass design: this is the only place that resolves entries to pixel
+ * positions. `predictEndpointLabelsWidth` (in `predict.ts`) runs before marks
+ * to reserve right margin space, but only computes width — never positions.
+ *
+ * Layout pipeline:
+ *   1. Filter marks to line/area marks with seriesKey + dataPoints.
+ *   2. For each series take the last data point, format the value, wrap the label.
+ *   3. Bidirectional collision sweep on labelY: forward pass pushes overlapping
+ *      entries down, reverse pass pushes them up; final = midpoint, clamped.
+ *   4. Mark `showLeader` true when displacement exceeds threshold.
+ *   5. Optionally attach the open-circle marker on the line at the right edge.
+ */
+
+import type {
+  AreaMark,
+  EndpointLabelEntry,
+  EndpointLabelsLayout,
+  LayoutStrategy,
+  LineMark,
+  Mark,
+  Rect,
+  ResolvedTheme,
+  TextStyle,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+import { countColorSeries, resolveSuppression } from '../legend/suppression';
+import {
+  ENDPOINT_COLUMN_GAP,
+  ENDPOINT_ENTRY_GAP,
+  ENDPOINT_GAP,
+  ENDPOINT_LABEL_FONT_SIZE,
+  ENDPOINT_LABEL_FONT_WEIGHT,
+  ENDPOINT_LEADER_THRESHOLD,
+  ENDPOINT_LINE_HEIGHT,
+  ENDPOINT_MARKER_RADIUS,
+  ENDPOINT_MARKER_STROKE_WIDTH,
+  ENDPOINT_SWATCH_SIZE,
+  ENDPOINT_VALUE_FONT_SIZE,
+  ENDPOINT_VALUE_FONT_WEIGHT,
+  ENDPOINT_VALUE_GAP,
+  ENDPOINT_WRAP_WIDTH_DEFAULT,
+} from './constants';
+import { formatEndpointValue } from './format';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Empty layout used as the "column suppressed" return value. */
+function emptyLayout(theme: ResolvedTheme): EndpointLabelsLayout {
+  const labelStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: ENDPOINT_LABEL_FONT_SIZE,
+    fontWeight: ENDPOINT_LABEL_FONT_WEIGHT,
+    fill: theme.colors.text,
+    lineHeight: ENDPOINT_LINE_HEIGHT,
+  };
+  const valueStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: ENDPOINT_VALUE_FONT_SIZE,
+    fontWeight: ENDPOINT_VALUE_FONT_WEIGHT,
+    fill: theme.colors.annotationText ?? theme.colors.text,
+    lineHeight: ENDPOINT_LINE_HEIGHT,
+  };
+  return {
+    entries: [],
+    bounds: { x: 0, y: 0, width: 0, height: 0 },
+    labelStyle,
+    valueStyle,
+    swatchSize: ENDPOINT_SWATCH_SIZE,
+    gap: ENDPOINT_GAP,
+    valueGap: ENDPOINT_VALUE_GAP,
+    swatchChipFill: theme.colors.annotationFill ?? theme.colors.background,
+  };
+}
+
+function isLineOrArea(mark: Mark): mark is LineMark | AreaMark {
+  return mark.type === 'line' || mark.type === 'area';
+}
+
+/** Get the last data-point pixel position for a line/area mark. */
+function lastDataPoint(mark: LineMark | AreaMark): { x: number; y: number } | null {
+  if (mark.dataPoints && mark.dataPoints.length > 0) {
+    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 };
+  }
+  if (mark.type === 'area' && mark.topPoints.length > 0) {
+    const last = mark.topPoints[mark.topPoints.length - 1];
+    return { x: last.x, y: last.y };
+  }
+  return null;
+}
+
+/** Get the value to display from a data row. */
+function readValue(
+  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[dp.length - 1].datum;
+    const v = datum[valueField];
+    return typeof v === 'number' || typeof v === 'string' ? v : null;
+  }
+  if (mark.data.length > 0) {
+    const v = mark.data[mark.data.length - 1][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.
+ *
+ * Each entry's "natural" top is `naturalTop` (typically `dataY - fontSize/2`
+ * so the label's first-line baseline-center aligns with the data point). We
+ * only push neighbors apart when their stacks would collide, by the minimum
+ * amount needed. This preserves the line-tracking behavior the design calls
+ * for: when lines are well-separated, labels sit at their lines; when close
+ * together, the sweep nudges them apart while staying near their data points.
+ *
+ * Algorithm:
+ *   1. Sort by naturalTop ascending.
+ *   2. Forward pass (top→bottom): push i down if it overlaps i-1, then clamp
+ *      to `areaBottom - height` so an entry never lands below the chart.
+ *   3. Reverse pass (bottom→top): push i up if it overlaps i+1, then clamp
+ *      to `areaTop` so an entry never lands above the chart.
+ *
+ * Both passes cascade the clamp through neighbors, so a clamp at one end can
+ * propagate all the way to the other when the chart is too short to fit every
+ * label without overlap. (When the total stack is taller than the area, the
+ * earliest entries get pinned to areaTop and overlap is unavoidable — the
+ * caller has to drop entries or shrink them.)
+ */
+export function bidirectionalSweep(
+  entries: { naturalTop: number; height: number; index: number }[],
+  areaTop: number,
+  areaBottom: number,
+): number[] {
+  const n = entries.length;
+  if (n === 0) return [];
+
+  // Sort by naturalTop ascending so neighbors in the chart are neighbors here.
+  const sorted = [...entries].sort((a, b) => a.naturalTop - b.naturalTop);
+
+  // Initialize tops at the natural (anchored-to-dataY) positions.
+  const tops = sorted.map((e) => e.naturalTop);
+
+  // Forward pass: push down only when overlapping the previous entry, then
+  // cap at the chart's bottom edge so we don't run off the canvas.
+  for (let i = 0; i < n; i++) {
+    if (i > 0) {
+      const minTop = tops[i - 1] + sorted[i - 1].height;
+      if (tops[i] < minTop) tops[i] = minTop;
+    }
+    const maxTop = areaBottom - sorted[i].height;
+    if (tops[i] > maxTop) tops[i] = maxTop;
+  }
+
+  // Reverse pass: when the forward pass clamped a tail entry up to fit the
+  // bottom edge, propagate that displacement back through the predecessors so
+  // they don't overlap the now-raised tail. Then clamp at areaTop.
+  for (let i = n - 1; i >= 0; i--) {
+    if (i < n - 1) {
+      const maxTop = tops[i + 1] - sorted[i].height;
+      if (tops[i] > maxTop) tops[i] = maxTop;
+    }
+    if (tops[i] < areaTop) tops[i] = areaTop;
+  }
+
+  // Write back in original index order.
+  const result = new Array<number>(n);
+  for (let i = 0; i < n; i++) {
+    result[sorted[i].index] = tops[i];
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the resolved endpoint-labels layout for a chart.
+ *
+ * Returns an empty layout (entries: []) when:
+ *   - The chart isn't a multi-series line/area.
+ *   - The user opted out via `endpointLabels: false`.
+ *   - Responsive strategy strips inline labels (compact breakpoint).
+ *   - Suppression truth table resolves to "endpoint column off".
+ *
+ * Otherwise produces fully-positioned entries with bidirectional collision
+ * sweep applied to labelY and optional open-circle markers on the line.
+ */
+export function computeEndpointLabels(
+  spec: NormalizedChartSpec,
+  marks: Mark[],
+  theme: ResolvedTheme,
+  chartArea: Rect,
+  strategy?: LayoutStrategy,
+): 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 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',
+  });
+  if (!sup.showEndpointLabels) return emptyLayout(theme);
+
+  // Dedupe by seriesKey: for area charts, the engine emits BOTH an AreaMark
+  // and a derived LineMark per series (see `linesFromAreas` in
+  // `charts/line/index.ts`). Without dedupe each series would produce two
+  // endpoint entries. Prefer the line mark — its `stroke` is the canonical
+  // series color and matches the visible line, whereas the area mark's
+  // `stroke` may be derived from a gradient via `getRepresentativeColor`.
+  // Same-type collisions (area→area, line→line) keep the first mark; the
+  // engine never emits two of the same type per seriesKey.
+  const bySeriesKey = new Map<string, LineMark | AreaMark>();
+  for (const mark of marks) {
+    if (!isLineOrArea(mark) || !mark.seriesKey) continue;
+    const existing = bySeriesKey.get(mark.seriesKey);
+    if (!existing || (existing.type === 'area' && mark.type === 'line')) {
+      bySeriesKey.set(mark.seriesKey, mark);
+    }
+  }
+  const lineOrAreaMarks = Array.from(bySeriesKey.values());
+  if (lineOrAreaMarks.length < 2) return emptyLayout(theme);
+
+  const config = typeof spec.endpointLabels === 'object' ? spec.endpointLabels : undefined;
+  const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
+  const valueField = config?.valueField ?? spec.encoding.y?.field;
+  const formatString =
+    config?.format ??
+    ((spec.encoding.y?.axis as Record<string, unknown> | undefined)?.format as string | undefined);
+  const showMarker = config?.showMarker !== false;
+  const markerRadius = config?.markerStyle?.radius ?? ENDPOINT_MARKER_RADIUS;
+  const markerStrokeWidth = config?.markerStyle?.strokeWidth ?? ENDPOINT_MARKER_STROKE_WIDTH;
+  const markerFill = config?.markerStyle?.fill ?? theme.colors.background;
+
+  // Resolve the styles once.
+  const labelStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: ENDPOINT_LABEL_FONT_SIZE,
+    fontWeight: ENDPOINT_LABEL_FONT_WEIGHT,
+    fill: theme.colors.text,
+    lineHeight: ENDPOINT_LINE_HEIGHT,
+  };
+  const valueStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: ENDPOINT_VALUE_FONT_SIZE,
+    fontWeight: ENDPOINT_VALUE_FONT_WEIGHT,
+    fill: theme.colors.annotationText ?? theme.colors.text,
+    lineHeight: ENDPOINT_LINE_HEIGHT,
+  };
+
+  // First pass: build entries with wrapped labels and dataY (no positions yet).
+  type Provisional = {
+    seriesKey: string;
+    labelLines: string[];
+    value: string;
+    color: string;
+    dataX: number;
+    dataY: number;
+    height: number;
+    width: number;
+  };
+  const provisional: Provisional[] = [];
+  const labelLineHeight = ENDPOINT_LABEL_FONT_SIZE * ENDPOINT_LINE_HEIGHT;
+  const valueLineHeight = ENDPOINT_VALUE_FONT_SIZE * ENDPOINT_LINE_HEIGHT;
+
+  for (const mark of lineOrAreaMarks) {
+    const seriesKey = mark.seriesKey;
+    if (!seriesKey) continue;
+    const last = lastDataPoint(mark);
+    if (!last) continue;
+
+    const labelLines = wrapText(
+      seriesKey,
+      ENDPOINT_LABEL_FONT_SIZE,
+      ENDPOINT_LABEL_FONT_WEIGHT,
+      wrapWidth,
+    );
+    const rawValue = readValue(mark, valueField);
+    const value = formatEndpointValue(rawValue, formatString);
+
+    // Width of the widest line in this entry (used to size the column).
+    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;
+
+    // Determine the line stroke color. AreaMark may have a string fill; prefer
+    // mark.stroke for visual continuity with the line drawn on top of the area.
+    const color =
+      mark.type === 'line'
+        ? mark.stroke
+        : (mark.stroke ??
+          (typeof mark.fill === 'string' ? mark.fill : theme.colors.categorical[0]));
+
+    provisional.push({
+      seriesKey,
+      labelLines,
+      value,
+      color,
+      dataX: last.x,
+      dataY: last.y,
+      height: entryHeight,
+      width: entryWidth,
+    });
+  }
+
+  if (provisional.length < 2) 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.
+  // The marker sits on this same baseline-center row, putting the open ring directly
+  // where the line terminates when undisplaced.
+  // Add ENDPOINT_ENTRY_GAP to each entry's claimed height so the sweep leaves
+  // breathing room between stacked labels. The renderer doesn't draw the gap,
+  // so it's invisible when entries are well-separated.
+  const sweepInput = provisional.map((p, i) => ({
+    naturalTop: p.dataY - ENDPOINT_LABEL_FONT_SIZE / 2,
+    height: p.height + ENDPOINT_ENTRY_GAP,
+    index: i,
+  }));
+  const sweptTops = bidirectionalSweep(sweepInput, chartArea.y, chartArea.y + chartArea.height);
+
+  // Build final entries.
+  const columnWidth = Math.max(
+    ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + Math.max(...provisional.map((p) => p.width), 0) + 4,
+    32,
+  );
+  const columnX = chartArea.x + chartArea.width + ENDPOINT_COLUMN_GAP;
+  const markerX = chartArea.x + chartArea.width;
+
+  // The marker is the line's visual terminator — always at (chartRightX, dataY).
+  // The swatch + label first-line baseline-center sit at `labelY + fontSize/2`.
+  // The sweep uses naturalTop = `dataY - fontSize/2` so that, when undisplaced,
+  // the swatch row and the marker share the same y, producing the clean
+  // single-row look from the mocks.
+  //
+  // Leader lines are off by default. The marker on the line plus the swatch in
+  // the column already tie label to data; a connecting line adds noise without
+  // adding information for the small displacements the sweep produces. Users
+  // who want them can opt in via `endpointLabels.showLeader: true`.
+  const showLeader = config?.showLeader === true;
+  const entries: EndpointLabelEntry[] = provisional.map((p, i) => {
+    const labelY = sweptTops[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: markerX,
+        y: p.dataY,
+        fill: markerFill,
+        stroke: config?.markerStyle?.stroke ?? p.color,
+        strokeWidth: markerStrokeWidth,
+        radius: markerRadius,
+      };
+    }
+    return entry;
+  });
+
+  return {
+    entries,
+    bounds: {
+      x: columnX,
+      y: chartArea.y,
+      width: columnWidth,
+      height: chartArea.height,
+    },
+    labelStyle,
+    valueStyle,
+    swatchSize: ENDPOINT_SWATCH_SIZE,
+    gap: ENDPOINT_GAP,
+    valueGap: ENDPOINT_VALUE_GAP,
+    swatchChipFill: theme.colors.annotationFill ?? theme.colors.background,
+  };
+}

package/src/endpoint-labels/constants.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared constants for endpoint-labels prediction and computation.
+ *
+ * Both `predict.ts` (width-only, runs before marks) and `compute.ts` (full
+ * layout, runs after marks) read from these so the predicted width can never
+ * drift from the eventual rendered geometry.
+ */
+
+/** Series-name label font size. Matches body text for editorial prominence. */
+export const ENDPOINT_LABEL_FONT_SIZE = 13;
+
+/** Series-name label font weight (semibold for visual prominence). */
+export const ENDPOINT_LABEL_FONT_WEIGHT = 600;
+
+/** Last-value label font size (slightly smaller than the series name). */
+export const ENDPOINT_VALUE_FONT_SIZE = 12;
+
+/** Last-value label font weight (regular, muted text tone). */
+export const ENDPOINT_VALUE_FONT_WEIGHT = 400;
+
+/** Default wrap width for long series names, in pixels. */
+export const ENDPOINT_WRAP_WIDTH_DEFAULT = 110;
+
+/** Width of the colored swatch chip drawn left of the label. */
+export const ENDPOINT_SWATCH_SIZE = 18;
+
+/** Gap between swatch, label, and value. */
+export const ENDPOINT_GAP = 8;
+
+/** Line height multiplier for wrapped label lines. */
+export const ENDPOINT_LINE_HEIGHT = 1.25;
+
+/** Pixel padding between the chart area's right edge and the column. */
+export const ENDPOINT_COLUMN_GAP = 18;
+
+/** Vertical pad between the last wrapped label line and the value text. */
+export const ENDPOINT_VALUE_GAP = 4;
+
+/**
+ * Vertical breathing room between adjacent stacked entries during the
+ * collision sweep. The renderer doesn't draw this gap — it's purely a
+ * sweep-time cushion so that the value text of entry N doesn't hug the
+ * label text of entry N+1 when the sweep has packed them tightly.
+ */
+export const ENDPOINT_ENTRY_GAP = 6;
+
+/** Default open-circle marker radius on the line. */
+export const ENDPOINT_MARKER_RADIUS = 4;
+
+/** Default open-circle marker stroke width. */
+export const ENDPOINT_MARKER_STROKE_WIDTH = 2;
+
+/** Threshold (px) above which a leader line connects label back to data point. */
+export const ENDPOINT_LEADER_THRESHOLD = 8;

package/src/endpoint-labels/format.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared value-formatting helpers for the endpoint-labels predictor and
+ * compute pass. Keeping the format-string path in one place guarantees
+ * predicted column width matches the eventual rendered text.
+ */
+
+import { format as d3Format } from 'd3-format';
+
+/**
+ * Format a value with a d3-format string, falling back to String() on
+ * unknown specifiers. When no format string is supplied, applies a
+ * sensible default: integers under 1000 render as-is, anything else gets
+ * two decimals.
+ */
+export function formatEndpointValue(
+  value: number | string | null,
+  formatString: string | undefined,
+): string {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  if (formatString) {
+    try {
+      return d3Format(formatString)(value);
+    } catch {
+      return String(value);
+    }
+  }
+  if (Number.isInteger(value) && Math.abs(value) < 1000) return String(value);
+  return value.toFixed(2);
+}

package/src/endpoint-labels/predict.ts

@@ -0,0 +1,108 @@
+/**
+ * Width-only predictor for the endpoint labels column.
+ *
+ * `computeDimensions` runs BEFORE marks are computed, so it can't read
+ * `mark.dataPoints[-1].y` to lay out the column. But it still needs to reserve
+ * the right margin so marks render inside the data area instead of underneath
+ * the column.
+ *
+ * Single-pass design: this predictor returns ONLY the column's width. The full
+ * entry positions are computed exactly once, in `computeEndpointLabels`, after
+ * dimensions settle. Both call sites use the same wrapping math (font size,
+ * weight, max width) so the predicted width matches the eventual layout.
+ */
+
+import type { ResolvedTheme } from '@opendata-ai/openchart-core';
+import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+import {
+  ENDPOINT_GAP,
+  ENDPOINT_LABEL_FONT_SIZE,
+  ENDPOINT_LABEL_FONT_WEIGHT,
+  ENDPOINT_SWATCH_SIZE,
+  ENDPOINT_VALUE_FONT_SIZE,
+  ENDPOINT_VALUE_FONT_WEIGHT,
+  ENDPOINT_WRAP_WIDTH_DEFAULT,
+} from './constants';
+import { formatEndpointValue } from './format';
+
+/**
+ * Predict the pixel width the endpoint-labels column will need, including
+ * swatch + label + value + padding. Returns 0 when the column would be empty
+ * (single series, opt-out, non-line/area, etc.).
+ *
+ * Does NOT do collision sweep or full layout. Does the same `wrapText` math
+ * as `computeEndpointLabels` so the two stay aligned by construction.
+ */
+export function predictEndpointLabelsWidth(
+  spec: NormalizedChartSpec,
+  _theme: ResolvedTheme,
+): number {
+  if (spec.endpointLabels === false) return 0;
+  if (spec.markType !== 'line' && spec.markType !== 'area') return 0;
+  const colorEnc = spec.encoding.color;
+  if (!colorEnc) return 0;
+  if ('condition' in colorEnc) return 0;
+  if (colorEnc.type === 'quantitative') return 0;
+
+  // Distinct series count.
+  const colorField = 'field' in colorEnc ? colorEnc.field : undefined;
+  if (!colorField) return 0;
+  const seriesNames = new Set<string>();
+  for (const row of spec.data) {
+    seriesNames.add(String(row[colorField]));
+  }
+  if (seriesNames.size < 2) return 0;
+
+  // When the user passed `endpointLabels: false`, predict 0. (Already handled above
+  // for the bare boolean; also handle the object form `{ show: false }`.)
+  if (typeof spec.endpointLabels === 'object' && spec.endpointLabels?.show === false) return 0;
+
+  const config = typeof spec.endpointLabels === 'object' ? spec.endpointLabels : undefined;
+  const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
+
+  // Wrap each series name and find the widest wrapped line.
+  let maxLabelWidth = 0;
+  for (const name of seriesNames) {
+    const lines = wrapText(name, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT, wrapWidth);
+    for (const line of lines) {
+      const w = estimateTextWidth(line, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+      if (w > maxLabelWidth) maxLabelWidth = w;
+    }
+  }
+
+  // Estimate value width from the spec's data + format. We don't know which row
+  // is "last" without computing scales/marks, so we sample the largest absolute
+  // value to bound the formatted width.
+  const yField = config?.valueField ?? spec.encoding.y?.field;
+  const yFormat =
+    config?.format ??
+    ((spec.encoding.y?.axis as Record<string, unknown> | undefined)?.format as string | undefined);
+  let valueWidth = 0;
+  if (yField) {
+    let maxAbs = 0;
+    for (const row of spec.data) {
+      const v = Number(row[yField]);
+      if (Number.isFinite(v) && Math.abs(v) > maxAbs) maxAbs = Math.abs(v);
+    }
+    // When the user supplied a format string, run it through the same
+    // formatter compute.ts will use so width prediction matches reality.
+    // Without one, fall back to a magnitude-aware sample that bounds the
+    // expected unformatted value width (compute.ts uses toFixed(2) here,
+    // which is roughly the same character count as "1.5K"-style abbreviations
+    // for the upper end of each band).
+    let sample: string;
+    if (yFormat) {
+      sample = formatEndpointValue(maxAbs, yFormat);
+    } else if (maxAbs >= 1_000_000_000) sample = '1.5B';
+    else if (maxAbs >= 1_000_000) sample = '1.5M';
+    else if (maxAbs >= 1_000) sample = '1.5K';
+    else sample = String(Math.round(maxAbs * 100) / 100);
+    valueWidth = estimateTextWidth(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
+  }
+
+  // Column = swatch + gap + max(label width, value width) + small trailing pad.
+  const textColumn = Math.max(maxLabelWidth, valueWidth);
+  return ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + textColumn + 4;
+}

package/src/graphs/compile-graph.ts

@@ -109,6 +109,7 @@ function buildGraphLegend(
     swatchSize: SWATCH_SIZE,
     swatchGap: SWATCH_GAP,
     entryGap: ENTRY_GAP,
+    swatchChipFill: theme.colors.annotationFill,
   };
 }
 

package/src/layout/axes.ts

@@ -213,6 +213,12 @@ export interface AxesDataContext {
   skipX?: boolean;
   /** Same as skipX, for the y-axis. */
   skipY?: boolean;
+  /**
+   * The chart's primary mark type. Used to default tickPosition: line and area
+   * y-axes default to `'inline'` (labels above gridlines, no gutter); other
+   * marks default to `'gutter'`.
+   */
+  markType?: import('@opendata-ai/openchart-core').MarkType;
 }
 
 /**
@@ -352,6 +358,9 @@ export function computeAxes(
 
     const axisTitle = axisConfig?.title;
     const xLabelColor = axisConfig?.labelColor;
+    // X-axis defaults to gutter (no inline mode is sensible for the x axis
+    // because tick labels need horizontal room around their x position).
+    const xTickPosition = axisConfig?.tickPosition ?? 'gutter';
 
     result.x = {
       ticks,
@@ -370,6 +379,7 @@ export function computeAxes(
       labelPadding: axisConfig?.labelPadding,
       labelOverlap: axisConfig?.labelOverlap,
       labelFlush: axisConfig?.labelFlush,
+      tickPosition: xTickPosition,
     };
   }
 
@@ -440,6 +450,20 @@ export function computeAxes(
     const axisTitle = axisConfig?.title;
     const tickAngle = axisConfig?.labelAngle;
     const yLabelColor = axisConfig?.labelColor;
+    // Editorial line/area y-axes default to inline tick labels above their
+    // gridlines. Other mark types keep the classic gutter placement. Right-side
+    // y-axes (dual-axis) always use gutter.
+    const isContinuousYAxis =
+      scales.y.type !== 'band' && scales.y.type !== 'point' && scales.y.type !== 'ordinal';
+    const isLineOrArea = dataContext?.markType === 'line' || dataContext?.markType === 'area';
+    const yTickPosition: 'inline' | 'gutter' =
+      axisConfig?.tickPosition ??
+      (isLineOrArea && isContinuousYAxis && axisConfig?.orient !== 'right' ? 'inline' : 'gutter');
+
+    // Inline mode hides the axis line and tick marks by default; the gridlines
+    // themselves serve as the visual axis. Explicit user overrides win.
+    const yDomainLine = axisConfig?.domain ?? (yTickPosition === 'inline' ? false : undefined);
+    const yTickMarks = axisConfig?.ticks ?? (yTickPosition === 'inline' ? false : undefined);
 
     result.y = {
       ticks,
@@ -452,13 +476,14 @@ export function computeAxes(
       start: { x: chartArea.x, y: chartArea.y },
       end: { x: chartArea.x, y: chartArea.y + chartArea.height },
       orient: axisConfig?.orient,
-      domainLine: axisConfig?.domain,
-      tickMarks: axisConfig?.ticks,
+      domainLine: yDomainLine,
+      tickMarks: yTickMarks,
       offset: axisConfig?.offset,
       titlePadding: axisConfig?.titlePadding,
       labelPadding: axisConfig?.labelPadding,
       labelOverlap: axisConfig?.labelOverlap,
       labelFlush: axisConfig?.labelFlush,
+      tickPosition: yTickPosition,
     };
   }