feat: centralize responsive layout metrics and fix mobile chart alignment

Fixes axis title clipping, bar label overlap, and right-axis margin stacking
on narrow viewports. Responsive pixel constants (axis title offsets, tick
label gaps, horizontal padding fractions) are now in a single module
(packages/core/src/responsive/metrics.ts) so the engine and renderer can
never drift apart on these values.

- Add TICK_LABEL_OFFSET, AXIS_TITLE_OFFSET_*, AXIS_TITLE_TRAILING_PAD,
  NARROW_VIEWPORT_MAX, HPAD_COMPACT_*, LABEL_GAP_*, MAX_LEFT_LABEL_FRACTION_*
  constants to core/responsive
- Replace all inline width < 400/500/600 checks and raw px values with named
  imports in dimensions.ts, compile.ts, and axes.ts
- Fix Math.max (not +=) for right-axis margin reserve to avoid stacking
- Fix guardrail fallback path to use topPad so iOS Safari clearance is
  preserved even when chrome is stripped
- Thin band-scale x-axis labels at reduced/minimal density (mobile) to
  prevent overlapping tick labels on narrow containers
- Use d3Format for accurate y-axis label width estimation when a format
  string is specified

Author: rileyhilliard

packages/core/src/index.ts

@@ -77,9 +77,30 @@ export type {
   LegendPosition,
 } from './responsive/index';
 export {
+  AXIS_TITLE_OFFSET_COMPACT,
+  AXIS_TITLE_OFFSET_DEFAULT,
+  AXIS_TITLE_TRAILING_PAD,
+  BREAKPOINT_COMPACT_MAX,
+  BREAKPOINT_MEDIUM_MAX,
+  getAxisTitleOffset,
   getBreakpoint,
   getHeightClass,
   getLayoutStrategy,
+  HEIGHT_CRAMPED_MAX,
+  HEIGHT_SHORT_MAX,
+  HPAD_COMPACT_FRACTION,
+  HPAD_COMPACT_MIN,
+  LABEL_GAP_COMPACT,
+  LABEL_GAP_DEFAULT,
+  LABEL_GAP_NARROW_MAX,
+  MAX_LEFT_LABEL_FRACTION_COMPACT,
+  MAX_LEFT_LABEL_FRACTION_DEFAULT,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  NARROW_VIEWPORT_MAX,
+  TICK_LABEL_OFFSET,
+  TOP_PAD_EXTRA_NARROW,
+  TOP_PAD_NARROW_MAX,
 } from './responsive/index';
 
 // ---------------------------------------------------------------------------

packages/core/src/responsive/index.ts

@@ -21,3 +21,22 @@ export {
   HEIGHT_CRAMPED_MAX,
   HEIGHT_SHORT_MAX,
 } from './breakpoints';
+export {
+  AXIS_TITLE_OFFSET_COMPACT,
+  AXIS_TITLE_OFFSET_DEFAULT,
+  AXIS_TITLE_TRAILING_PAD,
+  getAxisTitleOffset,
+  HPAD_COMPACT_FRACTION,
+  HPAD_COMPACT_MIN,
+  LABEL_GAP_COMPACT,
+  LABEL_GAP_DEFAULT,
+  LABEL_GAP_NARROW_MAX,
+  MAX_LEFT_LABEL_FRACTION_COMPACT,
+  MAX_LEFT_LABEL_FRACTION_DEFAULT,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  NARROW_VIEWPORT_MAX,
+  TICK_LABEL_OFFSET,
+  TOP_PAD_EXTRA_NARROW,
+  TOP_PAD_NARROW_MAX,
+} from './metrics';

packages/core/src/responsive/metrics.ts

@@ -0,0 +1,114 @@
+/**
+ * Pixel-level responsive metrics for chart layout.
+ *
+ * These are the numeric tuning values that correspond to the semantic decisions
+ * in LayoutStrategy. Centralizing them here ensures the engine and renderer
+ * always agree on the same thresholds and offsets without duplicating raw numbers.
+ *
+ * LayoutStrategy is semantic (what to show), this module is metric (how much space).
+ */
+
+import { BREAKPOINT_COMPACT_MAX } from './breakpoints';
+
+// ---------------------------------------------------------------------------
+// Y-axis title offsets
+// ---------------------------------------------------------------------------
+
+/** Distance from the chart edge to the rotated y-axis title center (compact viewports). */
+export const AXIS_TITLE_OFFSET_COMPACT = 35;
+
+/** Distance from the chart edge to the rotated y-axis title center (standard viewports). */
+export const AXIS_TITLE_OFFSET_DEFAULT = 45;
+
+/** Returns the y-axis title offset appropriate for the given container width. */
+export function getAxisTitleOffset(width: number): number {
+  return width < BREAKPOINT_COMPACT_MAX ? AXIS_TITLE_OFFSET_COMPACT : AXIS_TITLE_OFFSET_DEFAULT;
+}
+
+// ---------------------------------------------------------------------------
+// Horizontal padding
+// ---------------------------------------------------------------------------
+
+/**
+ * On compact viewports axis titles and tick labels tolerate closer container edges
+ * than chrome text (title, subtitle). Reduce horizontal padding to reclaim space.
+ */
+export const HPAD_COMPACT_FRACTION = 0.5;
+
+/** Minimum horizontal padding regardless of scaling. */
+export const HPAD_COMPACT_MIN = 4;
+
+// ---------------------------------------------------------------------------
+// Tick label offset
+// ---------------------------------------------------------------------------
+
+/**
+ * Horizontal gap between the chart edge and the near edge of y-axis tick labels.
+ * The engine uses this to reserve right-axis margin; the renderer uses it to position labels.
+ * Both must agree on this value — do not change one without the other.
+ */
+export const TICK_LABEL_OFFSET = 6;
+
+// ---------------------------------------------------------------------------
+// Axis title trailing padding
+// ---------------------------------------------------------------------------
+
+/**
+ * Extra padding beyond half-glyph height added to the rotated axis title margin on
+ * standard (non-compact) viewports. Omitted on compact viewports to save space.
+ */
+export const AXIS_TITLE_TRAILING_PAD = 4;
+
+// ---------------------------------------------------------------------------
+// Narrow viewport threshold (between compact and medium)
+// ---------------------------------------------------------------------------
+
+/**
+ * Width below which "narrow" adjustments apply: extra iOS Safari top padding and
+ * tighter category label gaps. Sits between compact (< 400) and medium (400–700).
+ * Not a semantic breakpoint — a layout heuristic for narrow-but-not-compact containers.
+ */
+export const NARROW_VIEWPORT_MAX = 500;
+
+// ---------------------------------------------------------------------------
+// Top padding (iOS Safari address bar / notch clearance)
+// ---------------------------------------------------------------------------
+
+/** Extra top padding added below NARROW_VIEWPORT_MAX to clear iOS Safari browser chrome. */
+export const TOP_PAD_EXTRA_NARROW = 10;
+
+/** @deprecated Use NARROW_VIEWPORT_MAX instead. */
+export const TOP_PAD_NARROW_MAX = NARROW_VIEWPORT_MAX;
+
+// ---------------------------------------------------------------------------
+// Category label gaps (left-axis bar/dot charts)
+// ---------------------------------------------------------------------------
+
+/** Gap between category label text and chart edge on narrow viewports (< NARROW_VIEWPORT_MAX). */
+export const LABEL_GAP_COMPACT = 8;
+
+/** Gap between category label text and chart edge on standard viewports. */
+export const LABEL_GAP_DEFAULT = 12;
+
+/** @deprecated Use NARROW_VIEWPORT_MAX instead. */
+export const LABEL_GAP_NARROW_MAX = NARROW_VIEWPORT_MAX;
+
+// ---------------------------------------------------------------------------
+// Max left-axis label fraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Width threshold for the medium left-label fraction cap.
+ * Sits between medium (400-700) and full (> 700) to prevent wide category labels
+ * from consuming too much horizontal space at mid-range widths.
+ */
+export const MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX = 600;
+
+/** Max fraction of container width reservable for left category labels (compact). */
+export const MAX_LEFT_LABEL_FRACTION_COMPACT = 0.45;
+
+/** Max fraction of container width reservable for left category labels (mid-range). */
+export const MAX_LEFT_LABEL_FRACTION_MEDIUM = 0.55;
+
+/** Max fraction of container width reservable for left category labels (standard). */
+export const MAX_LEFT_LABEL_FRACTION_DEFAULT = 1;

packages/engine/src/compile.ts

@@ -33,16 +33,21 @@ import type {
   Transform,
 } from '@opendata-ai/openchart-core';
 import {
+  AXIS_TITLE_TRAILING_PAD,
   adaptTheme,
+  BREAKPOINT_COMPACT_MAX,
   computeLabelBounds,
   estimateTextWidth,
   generateAltText,
   generateDataTable,
+  getAxisTitleOffset,
   getBreakpoint,
   getHeightClass,
   getLayoutStrategy,
   resolveTheme,
+  TICK_LABEL_OFFSET,
 } from '@opendata-ai/openchart-core';
+import { format as d3Format } from 'd3-format';
 import { scaleLinear } from 'd3-scale';
 import { curveMonotoneX, area as d3area, line as d3line } from 'd3-shape';
 import { computeAnnotations } from './annotations/compute';
@@ -548,18 +553,30 @@ function estimateYAxisLabelWidth(
   }
 
   // Quantitative/temporal: estimate from the largest value
+  const yAxisFormat = (encoding.y.axis as Record<string, unknown> | undefined)?.format as
+    | string
+    | undefined;
   let maxAbsVal = 0;
   for (const row of data) {
     const v = Number(row[yField]);
     if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
   }
   let sampleLabel: string;
-  if (maxAbsVal >= 1_000_000_000) sampleLabel = '1.5B';
-  else if (maxAbsVal >= 1_000_000) sampleLabel = '1.5M';
-  else if (maxAbsVal >= 1_000) sampleLabel = '1.5K';
-  else if (maxAbsVal >= 100) sampleLabel = '100';
-  else if (maxAbsVal >= 10) sampleLabel = '10';
-  else sampleLabel = '0.0';
+  if (yAxisFormat) {
+    try {
+      const fmt = d3Format(yAxisFormat);
+      sampleLabel = fmt(maxAbsVal);
+    } catch {
+      sampleLabel = String(maxAbsVal);
+    }
+  } else {
+    if (maxAbsVal >= 1_000_000_000) sampleLabel = '1.5B';
+    else if (maxAbsVal >= 1_000_000) sampleLabel = '1.5M';
+    else if (maxAbsVal >= 1_000) sampleLabel = '1.5K';
+    else if (maxAbsVal >= 100) sampleLabel = '100';
+    else if (maxAbsVal >= 10) sampleLabel = '10';
+    else sampleLabel = '0.0';
+  }
   const hasNeg = data.some((r) => Number(r[yField]) < 0);
   const labelEst = (hasNeg ? '-' : '') + sampleLabel;
   return estimateTextWidth(labelEst, baseFontSize, 400) + 10;
@@ -596,13 +613,24 @@ function compileLayerIndependent(
     );
   }
 
-  // Estimate right-axis label width to reserve margin space
+  // Estimate right-axis label width to reserve margin space.
+  // Tick labels sit at chartEdge+6 and extend rightward by their width.
+  // The rotated title sits at chartEdge+45 and extends by half the font height.
+  // These overlap spatially, so use max (not sum) to mirror the left-margin pattern.
   const theme = resolveTheme(layerSpec.theme ?? leaf1.theme);
   const axisFontSize = theme.fonts?.sizes?.axisTick ?? 11;
   const rightAxisWidth = estimateYAxisLabelWidth(leaf1.data, leaf1.encoding, axisFontSize);
-  // Add space for the rotated axis title if present (match left-axis 45px clearance)
   const hasRightAxisTitle = !!leaf1.encoding?.y?.axis?.title;
-  const rightReserve = rightAxisWidth + (hasRightAxisTitle ? 45 : 0);
+  const tickExtent = TICK_LABEL_OFFSET + rightAxisWidth;
+  const bodyFontSize = theme.fonts?.sizes?.body ?? 13;
+  const axisTitleOffset = getAxisTitleOffset(options.width);
+  const halfGlyph = Math.ceil(bodyFontSize / 2);
+  const titleExtent = hasRightAxisTitle
+    ? axisTitleOffset +
+      halfGlyph +
+      (options.width < BREAKPOINT_COMPACT_MAX ? 0 : AXIS_TITLE_TRAILING_PAD)
+    : 0;
+  const rightReserve = Math.max(tickExtent, titleExtent);
 
   const optionsWithReserve: CompileOptions = {
     ...options,
@@ -960,6 +988,7 @@ function buildPrimarySpec(leaves: ChartSpec[], layerSpec: LayerSpec): ChartSpec
     data: allData,
     // Layer-level chrome overrides leaf chrome
     chrome: layerSpec.chrome ?? leaves[0].chrome,
+    annotations: layerSpec.annotations ?? leaves[0].annotations,
     labels: layerSpec.labels ?? leaves[0].labels,
     legend: layerSpec.legend ?? leaves[0].legend,
     responsive: layerSpec.responsive ?? leaves[0].responsive,

packages/engine/src/layout/axes/ticks.ts

@@ -211,10 +211,11 @@ export function categoricalTicks(
   const explicitTickCount = resolvedScale.channel.axis?.tickCount;
   const maxTicks = explicitTickCount ?? TICK_COUNTS[density];
 
-  // Band scales (bar charts) show all category labels by default.
-  // Only thin when there's an explicit tickCount override or for point/ordinal scales.
+  // Band scales show all labels at full density but thin at reduced/minimal
+  // to prevent overlap on narrow containers (e.g. 17 bars on mobile).
   let selectedValues = domain;
-  if ((resolvedScale.type !== 'band' || explicitTickCount) && domain.length > maxTicks) {
+  const shouldThinBand = resolvedScale.type === 'band' && (explicitTickCount || density !== 'full');
+  if ((resolvedScale.type !== 'band' || shouldThinBand) && domain.length > maxTicks) {
     const step = Math.ceil(domain.length / maxTicks);
     selectedValues = domain.filter((_: string, i: number) => i % step === 0);
   }