@opendata-ai/openchart-engine 6.12.0 → 6.15.0

package/src/compile.ts

@@ -13,18 +13,22 @@
 
 import type {
   AnimationSpec,
+  BinParams,
+  BinTransform,
   ChartLayout,
   ChartSpec,
   CompileOptions,
   CompileTableOptions,
+  EncodingChannel,
   LayerSpec,
   Mark,
-  PointMark,
   Rect,
-  RectMark,
   ResolvedAnnotation,
   ResolvedTheme,
   TableLayout,
+  TimeUnit,
+  TimeUnitTransform,
+  Transform,
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
@@ -43,6 +47,11 @@ import { columnRenderer } from './charts/column';
 import { dotRenderer } from './charts/dot';
 import { areaRenderer, lineRenderer } from './charts/line';
 import { donutRenderer, pieRenderer } from './charts/pie';
+import {
+  assignAnimationIndices,
+  computeMarkObstacles,
+  resolveRendererKey,
+} from './charts/post-process';
 import { type ChartRenderer, getChartRenderer, registerChartRenderer } from './charts/registry';
 import { ruleRenderer } from './charts/rule';
 import { scatterRenderer } from './charts/scatter';
@@ -90,7 +99,7 @@ import type { GraphCompilation } from './graphs/types';
 import { computeAxes } from './layout/axes';
 import { computeDimensions } from './layout/dimensions';
 import { computeGridlines } from './layout/gridlines';
-import { computeScales, type ResolvedScales } from './layout/scales';
+import { computeScales } from './layout/scales';
 import { computeLegend } from './legend/compute';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
@@ -98,93 +107,77 @@ import { computeTooltipDescriptors } from './tooltips/compute';
 import { runTransforms } from './transforms';
 
 // ---------------------------------------------------------------------------
-// Mark obstacles for annotation collision avoidance
+// Encoding sugar expansion (bin, timeUnit on encoding channels)
 // ---------------------------------------------------------------------------
 
 /**
- * Compute bounding rects from marks to use as obstacles for annotation nudging.
+ * Expand encoding-level `bin` and `timeUnit` shorthand into explicit transforms.
  *
- * For band-scale charts (bar, dot): groups marks by band row and returns
- * a single obstacle per row spanning the full band height and x-range.
+ * Vega-Lite allows `encoding.x.bin: true` as sugar for a BinTransform.
+ * This function detects those shorthands, generates the corresponding transforms,
+ * updates encoding field references to the output field names, and prepends the
+ * transforms to the spec's transform array.
  *
- * For other charts (column, scatter): returns individual mark bounds so
- * annotations avoid overlapping any visible data mark.
+ * Mutates nothing; returns a new spec object (shallow copy).
  */
-function computeMarkObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
-  // Band-scale y-axis: group marks by row for efficient obstacle computation
-  if (scales.y?.type === 'band') {
-    return computeBandRowObstacles(marks, scales);
-  }
+export function expandEncodingSugar(spec: Record<string, unknown>): Record<string, unknown> {
+  const encoding = spec.encoding as Record<string, EncodingChannel | undefined> | undefined;
+  if (!encoding) return spec;
+
+  const generatedTransforms: Transform[] = [];
+  const updatedEncoding = { ...encoding };
+  let changed = false;
+
+  for (const channel of Object.keys(encoding)) {
+    const ch = encoding[channel];
+    if (!ch || !ch.field) continue;
+
+    // Expand bin shorthand
+    if (ch.bin != null && ch.bin !== false) {
+      const field = ch.field;
+      const outputField = `bin_${field}`;
+      const binTransform: BinTransform = {
+        bin: ch.bin === true ? true : (ch.bin as BinParams),
+        field,
+        as: outputField,
+      };
+      generatedTransforms.push(binTransform);
 
-  // All other charts: use individual rect/point mark bounds as obstacles
-  const obstacles: Rect[] = [];
-  for (const mark of marks) {
-    if (mark.type === 'rect') {
-      const rm = mark as RectMark;
-      obstacles.push({ x: rm.x, y: rm.y, width: rm.width, height: rm.height });
-    } else if (mark.type === 'point') {
-      const pm = mark as PointMark;
-      obstacles.push({
-        x: pm.cx - pm.r,
-        y: pm.cy - pm.r,
-        width: pm.r * 2,
-        height: pm.r * 2,
-      });
+      // Update encoding to reference binned output field, remove bin property
+      const { bin: _bin, ...rest } = ch;
+      updatedEncoding[channel] = { ...rest, field: outputField } as EncodingChannel;
+      changed = true;
     }
-  }
-  return obstacles;
-}
-
-/** Group band-scale marks by row, returning one obstacle per band. */
-function computeBandRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
-  const rows = new Map<number, { minX: number; maxX: number; bandY: number }>();
 
-  for (const mark of marks) {
-    let cy: number;
-    let left: number;
-    let right: number;
-
-    if (mark.type === 'point') {
-      const pm = mark as PointMark;
-      cy = pm.cy;
-      left = pm.cx - pm.r;
-      right = pm.cx + pm.r;
-    } else if (mark.type === 'rect') {
-      const rm = mark as RectMark;
-      cy = rm.y + rm.height / 2;
-      left = rm.x;
-      right = rm.x + rm.width;
-    } else {
-      continue;
-    }
+    // Expand timeUnit shorthand (read from updated encoding in case bin already ran)
+    const current = updatedEncoding[channel] ?? ch;
+    if (current.timeUnit) {
+      const field = current.field;
+      const unit = current.timeUnit as TimeUnit;
+      const outputField = `${unit}_${field}`;
+      const timeUnitTransform: TimeUnitTransform = {
+        timeUnit: unit,
+        field,
+        as: outputField,
+      };
+      generatedTransforms.push(timeUnitTransform);
 
-    // Round cy to group marks on the same band
-    const key = Math.round(cy);
-    const existing = rows.get(key);
-    if (existing) {
-      existing.minX = Math.min(existing.minX, left);
-      existing.maxX = Math.max(existing.maxX, right);
-    } else {
-      rows.set(key, { minX: left, maxX: right, bandY: cy });
+      // Update encoding to reference timeUnit output field, remove timeUnit property
+      const { timeUnit: _tu, ...rest } = current;
+      updatedEncoding[channel] = { ...rest, field: outputField } as EncodingChannel;
+      changed = true;
     }
   }
 
-  // Get bandwidth from the band scale
-  const bandScale = scales.y!.scale as { bandwidth?: () => number };
-  const bandwidth = bandScale.bandwidth?.() ?? 0;
-  if (bandwidth === 0) return [];
+  if (!changed) return spec;
 
-  const obstacles: Rect[] = [];
-  for (const { minX, maxX, bandY } of rows.values()) {
-    obstacles.push({
-      x: minX,
-      y: bandY - bandwidth / 2,
-      width: maxX - minX,
-      height: bandwidth,
-    });
-  }
-
-  return obstacles;
+  // Prepend generated transforms before any user-defined transforms
+  const existingTransforms = (spec.transform as Transform[] | undefined) ?? [];
+  return {
+    ...spec,
+    encoding: updatedEncoding,
+    transform: [...generatedTransforms, ...existingTransforms],
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -204,8 +197,15 @@ function computeBandRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[]
  * @throws Error if spec is invalid or not a chart type.
  */
 export function compileChart(spec: unknown, options: CompileOptions): ChartLayout {
+  // Expand encoding-level bin/timeUnit sugar before validation + normalization.
+  // This converts shorthand (e.g. encoding.x.bin: true) into explicit transforms.
+  const expandedSpec =
+    spec && typeof spec === 'object' && !Array.isArray(spec)
+      ? expandEncodingSugar(spec as Record<string, unknown>)
+      : spec;
+
   // Validate + normalize
-  const { spec: normalized } = compileSpec(spec);
+  const { spec: normalized } = compileSpec(expandedSpec);
 
   if ('type' in normalized && (normalized as unknown as Record<string, unknown>).type === 'table') {
     throw new Error('compileChart received a table spec. Use compileTable instead.');
@@ -223,13 +223,14 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   let chartSpec = normalized as NormalizedChartSpec;
 
   // Resolve watermark: explicit spec value wins, then options fallback, then default true.
-  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const rawWatermark = (expandedSpec as Record<string, unknown>).watermark;
   const watermark = rawWatermark !== undefined ? chartSpec.watermark : (options.watermark ?? true);
 
   // Run data transforms (filter, bin, calculate, timeUnit) before any other data processing.
-  // Transforms are defined on the original spec, not the normalized spec, since
-  // NormalizedChartSpec doesn't carry the transform field.
-  const rawTransforms = (spec as Record<string, unknown>).transform as
+  // Transforms are defined on the expanded spec (which includes any auto-generated
+  // transforms from encoding-level bin/timeUnit sugar), not the normalized spec,
+  // since NormalizedChartSpec doesn't carry the transform field.
+  const rawTransforms = (expandedSpec as Record<string, unknown>).transform as
     | import('@opendata-ai/openchart-core').Transform[]
     | undefined;
   if (rawTransforms && rawTransforms.length > 0) {
@@ -241,8 +242,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const heightClass = getHeightClass(options.height);
   const strategy = getLayoutStrategy(breakpoint, heightClass);
 
-  // Apply breakpoint-conditional overrides from the original spec
-  const rawSpec = spec as Record<string, unknown>;
+  // Apply breakpoint-conditional overrides from the expanded spec
+  const rawSpec = expandedSpec as Record<string, unknown>;
   const overrides = rawSpec.overrides as
     | Partial<
         Record<
@@ -408,26 +409,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
 
   // Get chart renderer and compute marks (using filtered data).
-  // For 'bar' mark, resolve orientation to pick horizontal vs vertical renderer.
-  // For 'arc' mark, resolve innerRadius to pick pie vs donut renderer.
-  let rendererKey = renderSpec.markType as string;
-  if (rendererKey === 'bar') {
-    // Infer orientation from encoding: if x is quantitative and y is categorical, horizontal (default)
-    // If x is categorical and y is quantitative, vertical (old 'column')
-    const xType = renderSpec.encoding.x?.type;
-    const yType = renderSpec.encoding.y?.type;
-    const isVertical =
-      (xType === 'nominal' || xType === 'ordinal' || xType === 'temporal') &&
-      yType === 'quantitative';
-    if (isVertical) {
-      rendererKey = 'bar:vertical';
-    }
-  } else if (rendererKey === 'arc') {
-    const innerRadius = renderSpec.markDef.innerRadius;
-    if (innerRadius && innerRadius > 0) {
-      rendererKey = 'arc:donut';
-    }
-  }
+  const rendererKey = resolveRendererKey(
+    renderSpec.markType,
+    renderSpec.encoding,
+    renderSpec.markDef,
+  );
   const renderer = getChartRenderer(rendererKey);
   const marks: Mark[] = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme) : [];
 
@@ -491,44 +477,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   );
 
   // Assign animationIndex for stagger ordering when animation is enabled
-  // Assign animationIndex for value-based stagger ordering. Skip stacked rects
-  // since they get group-based indices below (avoids wasted work that gets overwritten).
-  if (resolvedAnimation?.enabled && resolvedAnimation.staggerOrder === 'value') {
-    const indexed = marks.map((m, i) => ({ mark: m, idx: i }));
-    indexed.sort((a, b) => {
-      const av = getMarkPrimaryValue(a.mark);
-      const bv = getMarkPrimaryValue(b.mark);
-      return av - bv;
-    });
-    for (let i = 0; i < indexed.length; i++) {
-      const m = indexed[i].mark;
-      if (m.type === 'rect' && (m as RectMark).stackGroup) continue;
-      m.animationIndex = i;
-    }
-  }
-
-  // For stacked bars/columns, assign the same animationIndex to all segments
-  // sharing a stackGroup so they animate as one contiguous bar per category.
-  // Also compute stackPos (segment position within each group: 0, 1, 2...)
-  // so the renderer can chain segment animations sequentially.
-  if (resolvedAnimation?.enabled) {
-    const groupIndexMap = new Map<string, number>();
-    const groupStackPos = new Map<string, number>();
-    let nextGroupIndex = 0;
-    for (const mark of marks) {
-      if (mark.type === 'rect' && (mark as RectMark).stackGroup) {
-        const rect = mark as RectMark;
-        const group = rect.stackGroup!;
-        if (!groupIndexMap.has(group)) {
-          groupIndexMap.set(group, nextGroupIndex++);
-        }
-        rect.animationIndex = groupIndexMap.get(group)!;
-        const pos = groupStackPos.get(group) ?? 0;
-        rect.stackPos = pos;
-        groupStackPos.set(group, pos + 1);
-      }
-    }
-  }
+  assignAnimationIndices(marks, resolvedAnimation);
 
   return {
     area: chartArea,
@@ -554,26 +503,10 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     },
     animation: resolvedAnimation,
     watermark,
+    measureText: options.measureText,
   };
 }
 
-/** Extract the primary quantitative value from a mark for value-based stagger ordering. */
-function getMarkPrimaryValue(mark: Mark): number {
-  switch (mark.type) {
-    case 'rect':
-      return mark.height; // bar height is the primary value encoding
-    case 'point':
-      return mark.cy; // y position for scatter
-    case 'arc':
-      return mark.endAngle - mark.startAngle; // arc angle extent
-    case 'line':
-    case 'area':
-      return 0; // series marks don't have individual values
-    default:
-      return 0;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Layer compilation
 // ---------------------------------------------------------------------------

package/src/compiler/normalize.ts

@@ -69,8 +69,8 @@ function normalizeChrome(chrome: Chrome | undefined): NormalizedChrome {
 
 /** Sample values from a data column and infer the field type. */
 function inferFieldType(data: DataRow[], field: string): FieldType {
-  // Sample up to 10 rows
-  const sampleSize = Math.min(10, data.length);
+  // Sample up to 50 rows for more reliable inference on mixed/messy data
+  const sampleSize = Math.min(50, data.length);
   let numericCount = 0;
   let dateCount = 0;
   let totalNonNull = 0;

package/src/layout/axes.ts

@@ -38,8 +38,8 @@ import type {
 
 /** Base tick counts by axis label density. */
 const TICK_COUNTS: Record<AxisLabelDensity, number> = {
-  full: 8,
-  reduced: 5,
+  full: 10,
+  reduced: 7,
   minimal: 3,
 };
 
@@ -399,8 +399,7 @@ export function computeAxes(
 
     // Auto-rotate labels when band scale labels would overlap.
     // Uses max label width (not average) since one long label is enough to overlap.
-    // Prefer labelAngle over deprecated tickAngle
-    let tickAngle = axisConfig?.labelAngle ?? axisConfig?.tickAngle;
+    let tickAngle = axisConfig?.labelAngle;
     if (tickAngle === undefined && scales.x.type === 'band' && ticks.length > 1) {
       const bandwidth = (scales.x.scale as ScaleBand<string>).bandwidth();
       let maxLabelWidth = 0;
@@ -414,8 +413,7 @@ export function computeAxes(
       }
     }
 
-    // Prefer title over deprecated label
-    const axisTitle = axisConfig?.title ?? axisConfig?.label;
+    const axisTitle = axisConfig?.title;
 
     result.x = {
       ticks,
@@ -454,21 +452,20 @@ export function computeAxes(
       allTicks = continuousTicks(scales.y, yDensity);
     }
 
-    // Gridlines use the full tick set (label thinning shouldn't remove gridlines).
-    const gridlines: Gridline[] = allTicks.map((t) => ({
-      position: t.position,
-      major: true,
-    }));
-
     // Thin tick labels to prevent overlap (skip for band scales, explicit tickCount, and values).
     const shouldThin = scales.y.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
     const ticks = shouldThin
       ? thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText)
       : allTicks;
 
-    // Prefer title over deprecated label, labelAngle over deprecated tickAngle
-    const axisTitle = axisConfig?.title ?? axisConfig?.label;
-    const tickAngle = axisConfig?.labelAngle ?? axisConfig?.tickAngle;
+    // Gridlines match the tick set so every gridline has a label.
+    const gridlines: Gridline[] = ticks.map((t) => ({
+      position: t.position,
+      major: true,
+    }));
+
+    const axisTitle = axisConfig?.title;
+    const tickAngle = axisConfig?.labelAngle;
 
     result.y = {
       ticks,

package/src/layout/dimensions.ts

@@ -125,9 +125,9 @@ export function computeDimensions(
   // Estimate x-axis height below chart area: tick labels sit 14px below,
   // axis title sits 35px below. These extend past the chart area bottom
   // and source/footer chrome must be positioned below them.
-  const xAxis = encoding.x?.axis as (Record<string, unknown> & { tickAngle?: number }) | undefined;
-  const hasXAxisLabel = !!xAxis?.label;
-  const xTickAngle = xAxis?.tickAngle;
+  const xAxis = encoding.x?.axis as (Record<string, unknown> & { labelAngle?: number }) | undefined;
+  const hasXAxisLabel = !!xAxis?.title;
+  const xTickAngle = xAxis?.labelAngle;
 
   let xAxisHeight: number;
   if (isRadial) {