@opendata-ai/openchart-engine 7.8.0 → 7.9.1

package/src/compiler/keys.ts

@@ -0,0 +1,54 @@
+/**
+ * Mark key utilities for data-update transitions.
+ *
+ * Keys uniquely identify marks across data updates so the renderer can
+ * match old marks to new marks and animate the difference. Each chart
+ * type stamps keys during its compute phase; these helpers provide the
+ * shared serialization and deduplication logic.
+ */
+
+/** Sentinel string for null/undefined values. Uses a Unicode symbol
+ *  that won't collide with real data values. */
+const NULL_KEY = '∅';
+
+/**
+ * Serialize a datum value into a stable key fragment.
+ * - Date -> epoch ms string (avoids locale-dependent Date.toString)
+ * - number/string/boolean -> String(v)
+ * - null/undefined -> null sentinel
+ */
+export function serializeKeyValue(v: unknown): string {
+  if (v === null || v === undefined) return NULL_KEY;
+  if (v instanceof Date) return String(v.getTime());
+  return String(v);
+}
+
+/**
+ * Append occurrence suffixes to duplicate keys, in order.
+ *
+ * Only keys that appear more than once get suffixed. Unique keys pass
+ * through unchanged so keys remain human-readable when possible.
+ * Uses SOH (\x01) as separator to avoid collisions with real data values.
+ */
+export function dedupeKeys(keys: string[]): string[] {
+  // Count occurrences
+  const counts = new Map<string, number>();
+  for (const k of keys) {
+    counts.set(k, (counts.get(k) ?? 0) + 1);
+  }
+
+  // Assign suffixes only to duplicates
+  const seen = new Map<string, number>();
+  const result: string[] = [];
+  for (const k of keys) {
+    if (counts.get(k)! > 1) {
+      const idx = seen.get(k) ?? 0;
+      result.push(`${k}\x01${idx}`);
+      seen.set(k, idx + 1);
+    } else {
+      result.push(k);
+    }
+  }
+
+  return result;
+}

package/src/compiler/normalize.ts

@@ -132,7 +132,7 @@ function inferFieldType(data: DataRow[], field: string): FieldType {
 function inferEncodingTypes(encoding: Encoding, data: DataRow[], warnings: string[]): Encoding {
   const result = { ...encoding };
 
-  for (const channel of ['x', 'y', 'color', 'size', 'detail'] as const) {
+  for (const channel of ['x', 'y', 'color', 'size', 'detail', 'key'] as const) {
     const spec = result[channel];
     if (!spec) continue;
 

package/src/index.ts

@@ -26,7 +26,25 @@ export {
 // Animation resolution
 // ---------------------------------------------------------------------------
 
-export { clampStaggerDelay, resolveAnimation } from './compiler/animation';
+export {
+  clampStaggerDelay,
+  ENTER_DEFAULTS,
+  EXIT_DEFAULTS,
+  resolveAnimation,
+  UPDATE_DEFAULTS,
+} from './compiler/animation';
+
+// ---------------------------------------------------------------------------
+// Mark keying for data-update transitions
+// ---------------------------------------------------------------------------
+
+export { dedupeKeys, serializeKeyValue } from './compiler/keys';
+
+// ---------------------------------------------------------------------------
+// Geometry helpers for path reconstruction
+// ---------------------------------------------------------------------------
+
+export { buildAreaPath, buildLinePath } from './charts/line/curves';
 
 // ---------------------------------------------------------------------------
 // Graph compilation types

package/src/layout/axes.ts

@@ -43,6 +43,59 @@ import type { ResolvedScales } from './scales';
 // them from './layout/axes'.
 export { thinTicksUntilFit, ticksOverlap } from './axes/thinning';
 
+/** Scale types that render as a categorical (non-continuous) y-axis. */
+const CATEGORICAL_SCALE_TYPES = new Set(['band', 'point', 'ordinal']);
+
+/**
+ * Whether the y-axis renders tick labels inline (above their gridline inside
+ * the plot) rather than in a left gutter.
+ *
+ * This is the single source of truth shared by margin reservation (plan.ts,
+ * dimensions.ts) and the renderer's title placement. All three must agree or
+ * the reserved left margin won't match where the title is drawn.
+ *
+ * Editorial line/area charts with a continuous y-axis default to inline ticks.
+ * Continuity is decided by the RESOLVED scale type, not the field type: an
+ * explicit `scale.type` override (e.g. a band scale forced onto a quantitative
+ * field) wins, mirroring buildPositionalScale() in scales.ts. Right-side
+ * (dual-axis) y-axes always use the gutter. An explicit axis.tickPosition wins
+ * over the default.
+ */
+export function yTickPositionIsInline(
+  yChannel:
+    | {
+        type?: string;
+        scale?: { type?: string };
+        axis?: unknown;
+      }
+    | undefined,
+  markType: string,
+  /**
+   * Resolved continuity of the y-scale, when the caller already has the built
+   * scale (computeAxes). When omitted, continuity is inferred from the encoding
+   * (explicit scale.type override, else field type) so the reservation paths
+   * predict the same answer computeAxes will produce.
+   */
+  resolvedContinuous?: boolean,
+): boolean {
+  if (!yChannel) return false;
+  const axisCfg = (yChannel.axis as Record<string, unknown> | undefined) ?? undefined;
+  const explicit = axisCfg?.tickPosition as 'inline' | 'gutter' | undefined;
+  if (explicit) return explicit === 'inline';
+
+  const isLineOrArea = markType === 'line' || markType === 'area';
+  if (!isLineOrArea) return false;
+  if ((axisCfg?.orient as string | undefined) === 'right') return false;
+
+  if (resolvedContinuous !== undefined) return resolvedContinuous;
+
+  // Predict the resolved scale type: explicit override wins, else field type.
+  const explicitScaleType = yChannel.scale?.type;
+  return explicitScaleType
+    ? !CATEGORICAL_SCALE_TYPES.has(explicitScaleType)
+    : yChannel.type === 'quantitative' || yChannel.type === 'temporal';
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -242,36 +295,46 @@ function fitContinuousTicks(
 }
 
 /**
- * Check whether band-scale tick labels overlap at a given rotation angle,
- * using position-based detection. Rotated labels extend diagonally past
- * their band boundaries without colliding, so we check actual footprint
- * along the axis rather than comparing against bandwidth.
+ * Horizontal footprint `[left, right]` of a rotated band tick label, in axis
+ * pixels. Rotated labels are anchored at the tick position (the rotation
+ * pivot), not centered on it: at a negative angle the renderer right-anchors
+ * the text so it extends left of the pivot; at a positive angle it left-anchors
+ * so it extends right. The horizontal projection is `width * cos(angle)`.
+ *
+ * Modeling the footprint as centered (the old behavior) over-estimates each
+ * label's reach by half its width in the wrong direction, which made a single
+ * wide label (e.g. "2026 (to wk 17)") report overlaps against neighbors that
+ * actually clear it — triggering needless thinning of the whole axis.
  */
-function bandTicksOverlapAtAngle(
-  ticks: AxisTick[],
+function labelSpanAtAngle(
+  tick: AxisTick,
   angleDeg: number,
   fontSize: number,
   fontWeight: number,
   measureText?: MeasureTextFn,
-): boolean {
-  if (ticks.length < 2) return false;
+): { left: number; right: number } {
   const angleRad = (Math.abs(angleDeg) * Math.PI) / 180;
   const cosA = angleRad > 0 ? Math.abs(Math.cos(angleRad)) : 1;
-  const minGap = fontSize * 0.5;
-  for (let i = 0; i < ticks.length - 1; i++) {
-    const aWidth = measureLabel(ticks[i].label, fontSize, fontWeight, measureText) * cosA;
-    const bWidth = measureLabel(ticks[i + 1].label, fontSize, fontWeight, measureText) * cosA;
-    const aRight = ticks[i].position + aWidth / 2;
-    const bLeft = ticks[i + 1].position - bWidth / 2;
-    if (aRight + minGap > bLeft) return true;
+  const projected = measureLabel(tick.label, fontSize, fontWeight, measureText) * cosA;
+  if (angleDeg === 0) {
+    // Horizontal labels are centered on the tick.
+    return { left: tick.position - projected / 2, right: tick.position + projected / 2 };
+  }
+  if (angleDeg < 0) {
+    // Right-anchored: pivot is the right edge, text extends left.
+    return { left: tick.position - projected, right: tick.position };
   }
-  return false;
+  // Left-anchored: pivot is the left edge, text extends right.
+  return { left: tick.position, right: tick.position + projected };
 }
 
 /**
- * Thin band-scale tick labels only when they actually overlap at their
- * effective angle. Most grouped bar charts keep every label even at -45°.
- * Only extremely dense charts (50+ categories) will thin.
+ * Thin band-scale tick labels only where they actually collide at their
+ * effective angle, greedily keeping every label that clears the last one
+ * retained. This preserves narrow labels that have room even when a single
+ * wide label elsewhere on the axis forces some thinning near it, instead of
+ * decimating the whole axis every-other. First and last labels are always
+ * kept. Most grouped bar charts keep every label even at -45°.
  */
 function thinBandTicksIfNeeded(
   ticks: AxisTick[],
@@ -280,19 +343,42 @@ function thinBandTicksIfNeeded(
   fontWeight: number,
   measureText?: MeasureTextFn,
 ): AxisTick[] {
-  if (!bandTicksOverlapAtAngle(ticks, angleDeg, fontSize, fontWeight, measureText)) return ticks;
+  if (ticks.length < 3) return ticks;
+  const minGap = fontSize * 0.5;
 
-  let current = ticks;
-  while (current.length > 2) {
-    const thinned = [current[0]];
-    for (let i = 2; i < current.length - 1; i += 2) {
-      thinned.push(current[i]);
+  const spans = ticks.map((t) => labelSpanAtAngle(t, angleDeg, fontSize, fontWeight, measureText));
+
+  // Greedy left-to-right retention: keep a label only if its footprint clears
+  // the last kept label's right edge by minGap. Always keep the first label.
+  const keep = new Array<boolean>(ticks.length).fill(false);
+  keep[0] = true;
+  let lastRight = spans[0].right;
+  for (let i = 1; i < ticks.length; i++) {
+    if (spans[i].left >= lastRight + minGap) {
+      keep[i] = true;
+      lastRight = spans[i].right;
     }
-    if (current.length > 1) thinned.push(current[current.length - 1]);
-    current = thinned;
-    if (!bandTicksOverlapAtAngle(current, angleDeg, fontSize, fontWeight, measureText)) break;
   }
-  return current;
+
+  // Always keep the last label. If keeping it collides with previously kept
+  // labels, drop each colliding neighbor so the endpoint stays labeled. A very
+  // wide final label (long category name) projects across several bands at an
+  // angle, so clear every kept label its footprint overlaps, not just the
+  // nearest one — otherwise an earlier kept label still overlaps the endpoint.
+  const lastIdx = ticks.length - 1;
+  if (!keep[lastIdx]) {
+    keep[lastIdx] = true;
+    for (let i = lastIdx - 1; i > 0; i--) {
+      if (!keep[i]) continue;
+      if (spans[i].right + minGap > spans[lastIdx].left) {
+        keep[i] = false;
+        continue;
+      }
+      break;
+    }
+  }
+
+  return ticks.filter((_, i) => keep[i]);
 }
 
 // ---------------------------------------------------------------------------
@@ -561,13 +647,18 @@ export function computeAxes(
     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.
+    // y-axes (dual-axis) always use gutter. Uses the shared predicate so the
+    // margin-reservation paths (plan.ts, dimensions.ts) agree with this; here
+    // we pass the RESOLVED scale continuity since the scale is already built.
     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');
+    const yTickPosition: 'inline' | 'gutter' = yTickPositionIsInline(
+      dataContext?.encoding.y,
+      dataContext?.markType ?? '',
+      isContinuousYAxis,
+    )
+      ? '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.

package/src/layout/dimensions.ts

@@ -45,6 +45,7 @@ import type { NormalizedChartSpec } from '../compiler/types';
 import { isEndsBoth, predictEndpointLabelsWidth } from '../endpoint-labels/predict';
 import { countColorSeries, resolveSuppression } from '../legend/suppression';
 import { legendGap } from '../legend/wrap';
+import { yTickPositionIsInline } from './axes';
 import { computeMetricBar, type MetricFontSizes, metricBarHeight } from './metrics';
 import type { LayoutPlan } from './plan';
 import { bottomMargin, chromeToInput, INLINE_TICK_OVERHANG_PAD, scalePadding } from './shared';
@@ -306,16 +307,9 @@ export function computeDimensions(
   // 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';
+  // Inline y-tick placement must match computeAxes exactly (shared predicate),
+  // or the reserved left margin won't line up with where the title is drawn.
+  const yIsInlinePre = yTickPositionIsInline(encoding.y, spec.markType);
   const inlineTickOverhang = yIsInlinePre
     ? theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD
     : 0;
@@ -571,8 +565,13 @@ export function computeDimensions(
     const yFieldForTitle = encoding.y?.field;
     const yAxisFormatForTitle = yAxis?.format as string | undefined;
     let estTickLabelWidth = 0;
+    // Inline y-tick labels render inside the chart area (above their gridlines),
+    // not in a left gutter, so they add no width the rotated title must clear.
+    // Counting them here would reserve a phantom gutter and leave a dead gap
+    // between the title and the plot.
     if (
       yFieldForTitle &&
+      !yIsInlinePre &&
       (encoding.y?.type === 'quantitative' || encoding.y?.type === 'temporal')
     ) {
       let maxAbsValForTitle = 0;
@@ -609,7 +608,7 @@ export function computeDimensions(
     // We add another halfGlyph here for the title glyph extending the other way,
     // toward the container edge, so the margin reaches the title's outer edge.
     const titleFontSize = theme.fonts.sizes.body;
-    const offset = axisTitleOffset(estTickLabelWidth, titleFontSize, width);
+    const offset = axisTitleOffset(estTickLabelWidth, titleFontSize, width, yIsInlinePre);
     const halfGlyph = Math.ceil(titleFontSize / 2);
     const rotatedLabelMargin =
       offset + halfGlyph + (width < BREAKPOINT_COMPACT_MAX ? 0 : AXIS_TITLE_TRAILING_PAD);

package/src/layout/plan.ts

@@ -33,6 +33,7 @@ import type { NormalizedChartSpec } from '../compiler/types';
 import { predictEndpointLabelsWidth } from '../endpoint-labels/predict';
 import { computeLegendContent, type LegendContent } from '../legend/compute';
 import { legendGap } from '../legend/wrap';
+import { yTickPositionIsInline } from './axes';
 import { resolveBandTickAngle } from './axes/rotation';
 import { buildContinuousTicks, scaleSupportsTickCount, targetTickCount } from './axes/ticks';
 import { computeScales, estimateBandwidth } from './scales';
@@ -177,17 +178,11 @@ export function resolveLayoutPlan(
   // Resolve y-axis inline status
   // -----------------------------------------------------------------------
   const yAxisCfg = (encoding.y?.axis as Record<string, unknown> | undefined) ?? undefined;
-  const yTickPositionExplicit = yAxisCfg?.tickPosition as 'inline' | 'gutter' | undefined;
   const yIsContinuous = encoding.y?.type === 'quantitative' || encoding.y?.type === 'temporal';
-  const yIsLineOrArea = renderSpec.markType === 'line' || renderSpec.markType === 'area';
-  const yAxisOrient = yAxisCfg?.orient as string | undefined;
-  // Sparkline display already returned early above, so no sparkline guard needed here.
-  const yIsInline =
-    yTickPositionExplicit === 'inline' ||
-    (yTickPositionExplicit === undefined &&
-      yIsLineOrArea &&
-      yIsContinuous &&
-      yAxisOrient !== 'right');
+  // Inline y-tick placement must match computeAxes exactly (shared predicate),
+  // or the reserved left margin won't line up with where the title is drawn.
+  // Sparkline display already returned early above, so no sparkline guard needed.
+  const yIsInline = yTickPositionIsInline(encoding.y, renderSpec.markType);
   const yAxisSuppressed = encoding.y?.axis === false;
 
   // -----------------------------------------------------------------------
@@ -517,7 +512,11 @@ export function resolveLayoutPlan(
       const yAxisDef = encoding.y?.axis as Record<string, unknown> | undefined;
       if (yAxisDef && (yAxisDef.title || yAxisDef.label) && !isRadial) {
         let estTickLabelWidth = 0;
-        if (encoding.y?.field && yIsContinuous) {
+        // Inline y-tick labels sit above their gridlines inside the chart area,
+        // not in a left gutter, so they add no width the title must clear.
+        // Reserving their width here would leave a dead gap between the title
+        // and the plot. Only gutter (non-inline) tick labels count.
+        if (encoding.y?.field && yIsContinuous && !yIsInline) {
           if (yTickValues.length > 0) {
             const titleProvArea: Rect = {
               x: finalGutter,
@@ -536,7 +535,7 @@ export function resolveLayoutPlan(
           }
         }
         const titleFontSize = theme.fonts.sizes.body;
-        const offset = axisTitleOffset(estTickLabelWidth, titleFontSize, width);
+        const offset = axisTitleOffset(estTickLabelWidth, titleFontSize, width, yIsInline);
         const halfGlyph = Math.ceil(titleFontSize / 2);
         const rotatedLabelMargin =
           offset + halfGlyph + (width < BREAKPOINT_COMPACT_MAX ? 0 : AXIS_TITLE_TRAILING_PAD);

package/src/tables/__tests__/compile-table.test.ts

@@ -209,9 +209,9 @@ describe('compileTable', () => {
   it('includes resolved animation when spec has animation: true', () => {
     const layout = compileTable({ ...baseSpec, animation: true }, baseOptions);
     expect(layout.animation).toBeDefined();
-    expect(layout.animation!.enabled).toBe(true);
-    expect(layout.animation!.duration).toBe(500);
-    expect(layout.animation!.staggerDelay).toBe(80);
+    expect(layout.animation!.enter).toBeDefined();
+    expect(layout.animation!.enter!.duration).toBe(500);
+    expect(layout.animation!.enter!.staggerDelay).toBe(80);
   });
 
   it('includes resolved animation with custom config', () => {
@@ -220,8 +220,8 @@ describe('compileTable', () => {
       baseOptions,
     );
     expect(layout.animation).toBeDefined();
-    expect(layout.animation!.duration).toBe(800);
-    expect(layout.animation!.ease).toBe('snappy');
+    expect(layout.animation!.enter!.duration).toBe(800);
+    expect(layout.animation!.enter!.ease).toBe('snappy');
   });
 
   it('does not include animation when spec omits it', () => {

package/src/tilemap/compile-tilemap.ts

@@ -38,6 +38,9 @@ import {
   computeChrome,
   estimateTextWidth,
   formatNumber,
+  getBreakpoint,
+  HPAD_COMPACT_FRACTION,
+  HPAD_COMPACT_MIN,
   pickLabelColor,
   resolveTheme,
   SEQUENTIAL_PALETTES,
@@ -59,6 +62,10 @@ const LEGEND_SWATCH_SIZE = 10;
 const LEGEND_SWATCH_GAP = 6;
 const LEGEND_ENTRY_GAP = 16;
 
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -118,7 +125,15 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
   );
 
   // 4. Compute drawing area (total space minus chrome)
-  const padding = theme.spacing.padding;
+  // On compact (mobile) widths, reclaim horizontal space by shrinking the
+  // padding — every reclaimed pixel widens the tiles, which are width-bound at
+  // these sizes. Mirrors how the chart pipeline uses HPAD_COMPACT_* on narrow
+  // viewports. The tile-area, chrome, and content-height math all read this one
+  // value, so overriding it here keeps every derived measurement consistent.
+  const padding =
+    getBreakpoint(options.width) === 'compact'
+      ? Math.max(HPAD_COMPACT_MIN, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION))
+      : theme.spacing.padding;
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
@@ -269,7 +284,9 @@ function compileQuantitative(
   };
 
   const resolvedAnimation: ResolvedAnimation | undefined = resolveAnimation(tilemapSpec.animation);
-  const padding = theme.spacing.padding;
+  // fullArea.x is the (possibly compact-reduced) padding chosen in compileTileMap;
+  // reuse it so contentHeight matches the drawing area exactly.
+  const padding = fullArea.x;
   const contentHeight =
     tileGridOffsetY +
     tilePositions.gridHeight +
@@ -354,11 +371,18 @@ function compileCategorical(
   }
 
   const showLegend = tilemapSpec.legend?.show !== false;
+  const legendLabelFontSize = 11;
   const legendRowHeight = LEGEND_SWATCH_SIZE + 6;
-  const legendTotalHeight = showLegend ? legendRowHeight : 0;
+  const legendLabels = categories.map(formatCategoryLabel);
 
+  // Estimate legend rows against the full width to reserve tile-area height.
+  // The renderer wraps against the (narrower) grid width, so we recompute the
+  // real row count below and use that for final placement — never under-reserve.
   const legendGap = showLegend ? 8 : 0;
-  const tileAreaHeight = fullArea.height - legendTotalHeight - legendGap;
+  const estimatedRows = showLegend
+    ? countLegendRows(legendLabels, fullArea.width, legendLabelFontSize)
+    : 0;
+  const tileAreaHeight = fullArea.height - legendRowHeight * estimatedRows - legendGap;
   const tilePositions = computeTilePositions(fullArea.width, tileAreaHeight, 5);
 
   const tileGridOffsetX = fullArea.x + (fullArea.width - tilePositions.gridWidth) / 2;
@@ -367,6 +391,13 @@ function compileCategorical(
   const legendY = tileGridOffsetY + tilePositions.gridHeight + legendGap;
   const legendWidth = tilePositions.gridWidth;
 
+  // Reserve height for every wrapped row so a legend that spills onto a second
+  // line (common on narrow mobile widths) doesn't collide with the source text.
+  const legendRows = showLegend
+    ? countLegendRows(legendLabels, legendWidth, legendLabelFontSize)
+    : 0;
+  const legendTotalHeight = showLegend ? legendRowHeight * legendRows : 0;
+
   const neutralFill = isDarkMode ? '#1e2a30' : '#e0e0e0';
   const neutralStroke = isDarkMode ? 'rgba(255,255,255,0.08)' : '#d0d0d0';
 
@@ -411,7 +442,7 @@ function compileCategorical(
   if (showLegend) {
     const labelStyle: TextStyle = {
       fontFamily: theme.fonts.family,
-      fontSize: 11,
+      fontSize: legendLabelFontSize,
       fontWeight: 400,
       fill: theme.colors.text,
       lineHeight: 1.2,
@@ -426,7 +457,7 @@ function compileCategorical(
     categoricalLegend = {
       type: 'categorical',
       position: 'bottom',
-      bounds: { x: legendX, y: legendY, width: legendWidth, height: legendRowHeight },
+      bounds: { x: legendX, y: legendY, width: legendWidth, height: legendTotalHeight },
       labelStyle,
       entries,
       swatchSize: LEGEND_SWATCH_SIZE,
@@ -446,7 +477,9 @@ function compileCategorical(
   };
 
   const resolvedAnimation: ResolvedAnimation | undefined = resolveAnimation(tilemapSpec.animation);
-  const padding = theme.spacing.padding;
+  // fullArea.x is the (possibly compact-reduced) padding chosen in compileTileMap;
+  // reuse it so contentHeight matches the drawing area exactly.
+  const padding = fullArea.x;
   const contentHeight =
     tileGridOffsetY +
     tilePositions.gridHeight +
@@ -518,9 +551,20 @@ function buildTileMark(opts: TileMarkOptions): TileMapTileMark {
   const textColor = hasData ? pickLabelColor(fill, isDarkMode) : '#ffffff';
   const isLightText = textColor === '#ffffff';
 
+  // A two-line layout (code over value) only fits once tiles are large enough;
+  // below that we drop the value and center the code so nothing overflows.
+  const showValue = tileSize >= 24;
+
+  // Scale the code font with the tile so a 2-char label always fits its box,
+  // rather than snapping between two fixed sizes. A 2-char string is ~1.2x the
+  // font size wide; capping font at ~0.5x tile width keeps it inside the tile
+  // with margin, then clamp to a legible [6.5, 11] range.
+  const codeFontSize = clamp(Math.round(tileSize * 0.5 * 10) / 10, 6.5, 11);
+  const valueFontSize = clamp(Math.round(tileSize * 0.42 * 10) / 10, 6.5, 10);
+
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
-    fontSize: tileSize > 24 ? 10 : 7,
+    fontSize: codeFontSize,
     fontWeight: 700,
     fill: textColor,
     lineHeight: 1.2,
@@ -528,22 +572,27 @@ function buildTileMark(opts: TileMarkOptions): TileMapTileMark {
 
   const valueLabelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
-    fontSize: tileSize > 24 ? 10 : 7,
+    fontSize: valueFontSize,
     fontWeight: 300,
     fill: isLightText ? 'rgba(255,255,255,0.6)' : 'rgba(0,0,0,0.45)',
     lineHeight: 1.2,
   };
 
-  const valueLabel =
-    tileSize < 24
-      ? { text: '', x: 0, y: 0, style: valueLabelStyle, visible: false }
-      : {
-          text: formattedValue,
-          x: tileCenterX,
-          y: tileTopY + tileSize * 0.78,
-          style: valueLabelStyle,
-          visible: true,
-        };
+  // Code sits in the upper third when paired with a value, otherwise centered.
+  const codeCenterY = showValue ? tileTopY + tileSize * 0.28 : tileTopY + tileSize * 0.5;
+
+  const valueLabel = showValue
+    ? {
+        text: formattedValue,
+        x: tileCenterX,
+        y: tileTopY + tileSize * 0.78,
+        style: valueLabelStyle,
+        visible: true,
+      }
+    : { text: '', x: 0, y: 0, style: valueLabelStyle, visible: false };
+
+  // Keep corners visibly rounded-rectangular, never near-circular on small tiles.
+  const cornerRadius = Math.min(TILE_CORNER_RADIUS, Math.round(tileSize * 0.22));
 
   const data: Record<string, unknown> = {
     state: stateCode,
@@ -564,14 +613,14 @@ function buildTileMark(opts: TileMarkOptions): TileMapTileMark {
     fillOpacity,
     stroke,
     strokeWidth: TILE_STROKE_WIDTH,
-    cornerRadius: TILE_CORNER_RADIUS,
+    cornerRadius,
     value,
     formattedValue,
     hasData,
     label: {
       text: stateCode,
       x: tileCenterX,
-      y: tileTopY + tileSize * 0.28,
+      y: codeCenterY,
       style: labelStyle,
       visible: true,
     },
@@ -617,6 +666,29 @@ function formatCategoryLabel(category: string): string {
   return category.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+/**
+ * Count how many rows a horizontal categorical legend wraps into for a given
+ * available width. Mirrors the wrap logic in the legend renderer so the compiler
+ * can reserve enough vertical space and avoid the legend overlapping the source
+ * line on narrow (mobile) containers.
+ */
+function countLegendRows(labels: string[], availableWidth: number, fontSize: number): number {
+  if (labels.length === 0) return 0;
+  let rows = 1;
+  let offsetX = 0;
+  for (let i = 0; i < labels.length; i++) {
+    const labelWidth = estimateTextWidth(labels[i], fontSize);
+    const entryWidth = LEGEND_SWATCH_SIZE + LEGEND_SWATCH_GAP + labelWidth + LEGEND_ENTRY_GAP;
+    if (i > 0 && offsetX + entryWidth > availableWidth) {
+      rows++;
+      offsetX = entryWidth;
+    } else {
+      offsetX += entryWidth;
+    }
+  }
+  return rows;
+}
+
 // ---------------------------------------------------------------------------
 // Empty layout fallback
 // ---------------------------------------------------------------------------