@opendata-ai/openchart-engine 7.10.0 → 8.0.0-rc.1

package/src/charts/calendar/compute.ts

@@ -0,0 +1,319 @@
+/**
+ * Calendar heatmap mark computation.
+ *
+ * GitHub-style layout: weeks as columns, weekdays as rows, month labels
+ * above each band, Mon/Wed/Fri weekday labels on the left. Multi-year data
+ * partitions into one full-year band per calendar year, stacked vertically
+ * with a year label per band; every band shares the figure's single color
+ * scale (built once from the full dataset by computeScales).
+ *
+ * The calendar owns its geometry: no positional scales or axes. All date
+ * math runs in UTC (d3-time utc* intervals) so the layout is deterministic
+ * regardless of the host machine's timezone -- ISO date strings like
+ * "2024-01-15" parse as UTC midnight, and a local-time week interval would
+ * shift them across day boundaries in western timezones.
+ *
+ * Days inside a band's year with no data row (or a non-numeric value)
+ * render as empty cells filled with the theme's achromatic surface tint
+ * (colors.annotationFill), visually distinct from the chromatic scale
+ * minimum in both light and dark modes. Days padding the first/last week
+ * but belonging to a neighboring year render nothing.
+ */
+
+import type {
+  Encoding,
+  Mark,
+  MarkAria,
+  Rect,
+  RectMark,
+  ResolvedTheme,
+  TextMarkLayout,
+} from '@opendata-ai/openchart-core';
+import { defaultNumberFormatter, formatDate } from '@opendata-ai/openchart-core';
+import { type CountableTimeInterval, utcDay, utcMonday, utcSunday } from 'd3-time';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getSequentialColor } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum day-cell size in pixels (the "never shrink marks below legibility"
+ * floor, extending the never-shrink-text house rule to marks). When the
+ * container is too narrow for 53 legible columns the grid keeps this floor
+ * and overflows the chart area instead of shrinking further; hosts that need
+ * every column visible at phone widths wrap the figure in a horizontal
+ * scroll container.
+ */
+export const MIN_CELL_SIZE = 7;
+
+/** Maximum grid step (cell + gap) so huge containers stay dense. */
+const MAX_STEP = 20;
+
+/** Minimum grid step: the cell floor plus a 1px gap. */
+const MIN_STEP = MIN_CELL_SIZE + 1;
+
+/** Vertical gap between stacked year bands. */
+const BAND_GAP = 18;
+
+/** Gap between the weekday labels and the first week column. */
+const WEEKDAY_LABEL_GAP = 6;
+
+/** Default corner radius for day cells (markDef.cellRadius overrides). */
+const DEFAULT_CELL_RADIUS = 1;
+
+/** Weekday labels shown on the left (day-of-week numbers, 0 = Sunday). */
+const WEEKDAY_LABELS: Array<{ dow: number; label: string }> = [
+  { dow: 1, label: 'Mon' },
+  { dow: 3, label: 'Wed' },
+  { dow: 5, label: 'Fri' },
+];
+
+/** Abbreviated month labels, January first. */
+const MONTH_LABELS = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec',
+];
+
+// ---------------------------------------------------------------------------
+// Date helpers
+// ---------------------------------------------------------------------------
+
+/** Parse a raw field value to a UTC-floored day, or null when unparseable. */
+export function parseUtcDay(value: unknown): Date | null {
+  if (value == null) return null;
+  const date = value instanceof Date ? value : new Date(value as string | number);
+  if (Number.isNaN(date.getTime())) return null;
+  return utcDay.floor(date);
+}
+
+/** ISO yyyy-mm-dd key for a UTC day. */
+function isoDayKey(day: Date): string {
+  return day.toISOString().slice(0, 10);
+}
+
+/** Week interval for a weekStart option. */
+function weekInterval(weekStart: 'monday' | 'sunday'): CountableTimeInterval {
+  return weekStart === 'sunday' ? utcSunday : utcMonday;
+}
+
+/** Weekday row index (0..6) for a UTC day under a weekStart option. */
+export function weekdayRow(day: Date, weekStart: 'monday' | 'sunday'): number {
+  const startDow = weekStart === 'sunday' ? 0 : 1;
+  return (day.getUTCDay() - startDow + 7) % 7;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute calendar heatmap marks from a normalized chart spec.
+ *
+ * Emits one RectMark per day of every calendar year present in the data
+ * (days without data get the empty-cell surface tint) plus TextMarkLayout
+ * marks for month, weekday, and (multi-year only) year labels.
+ */
+export function computeCalendarMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  theme: ResolvedTheme,
+): Mark[] {
+  const encoding = spec.encoding as Encoding;
+  const xEnc = encoding.x;
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  if (!xEnc || !colorEnc) return [];
+
+  const weekStart = spec.markDef.weekStart ?? 'monday';
+  const week = weekInterval(weekStart);
+  const cellRadius = spec.markDef.cellRadius ?? DEFAULT_CELL_RADIUS;
+
+  // Index rows by UTC day. Unparseable dates and non-numeric values were
+  // rejected (or warned about) at validation; anything that still slips
+  // through renders as an empty cell rather than corrupting the grid.
+  const dayData = new Map<string, { row: Record<string, unknown>; value: number }>();
+  const years = new Set<number>();
+  for (const row of spec.data) {
+    const day = parseUtcDay(row[xEnc.field]);
+    if (!day) continue;
+    years.add(day.getUTCFullYear());
+    const value = Number(row[colorEnc.field]);
+    if (!Number.isFinite(value)) continue;
+    dayData.set(isoDayKey(day), { row: row as Record<string, unknown>, value });
+  }
+  if (years.size === 0) return [];
+
+  const sortedYears = Array.from(years).sort((a, b) => a - b);
+
+  // Per-band week-column counts. A band always spans its full calendar year
+  // (Jan 1 through Dec 31), so partial-year data keeps the familiar 53-column
+  // silhouette and missing days read as gaps rather than a shifted grid.
+  const bandColumns = sortedYears.map((year) => {
+    const firstWeek = week.floor(new Date(Date.UTC(year, 0, 1)));
+    const lastDay = new Date(Date.UTC(year, 11, 31));
+    return week.count(firstWeek, lastDay) + 1;
+  });
+  const maxColumns = Math.max(...bandColumns);
+
+  // -------------------------------------------------------------------------
+  // Geometry
+  // -------------------------------------------------------------------------
+  const labelFont = theme.fonts.sizes.small;
+  const gutter = Math.ceil(labelFont * 2.6) + WEEKDAY_LABEL_GAP;
+  const monthRow = Math.ceil(labelFont * 1.3) + 2;
+  const bands = sortedYears.length;
+  const showYearLabels = bands > 1;
+
+  const availWidth = Math.max(0, chartArea.width - gutter);
+  const stepFromWidth = availWidth / maxColumns;
+  const availHeight = Math.max(0, chartArea.height - bands * monthRow - (bands - 1) * BAND_GAP);
+  const stepFromHeight = availHeight / (7 * bands);
+  // Square cells only: the calendar idiom reads as a grid of days, and
+  // wide cells would misalign weekday rows across stacked year bands. At
+  // narrow widths the step clamps to the MIN_CELL_SIZE floor instead of
+  // going sub-legible (the grid then overflows to the right).
+  const step = Math.min(
+    MAX_STEP,
+    Math.max(MIN_STEP, Math.floor(Math.min(stepFromWidth, stepFromHeight))),
+  );
+  const cellGap = step >= 14 ? 3 : step >= 10 ? 2 : 1;
+  const cell = step - cellGap;
+
+  const gridWidth = maxColumns * step - cellGap;
+  const bandHeight = monthRow + 7 * step - cellGap;
+  const totalHeight = bands * bandHeight + (bands - 1) * BAND_GAP;
+  const originX = chartArea.x + gutter + Math.max(0, (availWidth - gridWidth) / 2);
+  const originY = chartArea.y + Math.max(0, (chartArea.height - totalHeight) / 2);
+
+  // Month label thinning: when four week columns can't fit a three-letter
+  // label, keep every other month so labels never collide.
+  const monthLabelWidth = labelFont * 2.2;
+  const monthLabelEvery = step * 4.34 < monthLabelWidth + 4 ? 2 : 1;
+
+  const labelBaseline = labelFont; // baseline offset from the band top
+
+  const cellMarks: RectMark[] = [];
+  const labelMarks: TextMarkLayout[] = [];
+
+  const labelAria: MarkAria = { decorative: true };
+  const labelStyle = {
+    fill: theme.colors.axis,
+    fontSize: labelFont,
+    fontWeight: theme.fonts.weights.normal,
+    fontFamily: theme.fonts.family,
+  };
+
+  // -------------------------------------------------------------------------
+  // Bands
+  // -------------------------------------------------------------------------
+  const calendarFmt = defaultNumberFormatter();
+  for (let b = 0; b < bands; b++) {
+    const year = sortedYears[b];
+    const bandTop = originY + b * (bandHeight + BAND_GAP);
+    const gridTop = bandTop + monthRow;
+    const yearStart = new Date(Date.UTC(year, 0, 1));
+    const yearEnd = new Date(Date.UTC(year + 1, 0, 1));
+    const firstWeek = week.floor(yearStart);
+
+    // Year label (multi-year only), in the weekday gutter column.
+    if (showYearLabels) {
+      labelMarks.push({
+        type: 'textMark',
+        x: chartArea.x,
+        y: bandTop + labelBaseline,
+        text: String(year),
+        ...labelStyle,
+        fill: theme.colors.text,
+        fontWeight: theme.fonts.weights.semibold,
+        textAnchor: 'start',
+        data: {},
+        aria: labelAria,
+      });
+    }
+
+    // Month labels above the grid, at the column containing the 1st.
+    for (let m = 0; m < 12; m += monthLabelEvery) {
+      const col = week.count(firstWeek, new Date(Date.UTC(year, m, 1)));
+      labelMarks.push({
+        type: 'textMark',
+        x: originX + col * step,
+        y: bandTop + labelBaseline,
+        text: MONTH_LABELS[m],
+        ...labelStyle,
+        textAnchor: 'start',
+        data: {},
+        aria: labelAria,
+      });
+    }
+
+    // Weekday labels (Mon/Wed/Fri) left of the grid, centered on their row.
+    for (const { dow, label } of WEEKDAY_LABELS) {
+      const row = (dow - (weekStart === 'sunday' ? 0 : 1) + 7) % 7;
+      labelMarks.push({
+        type: 'textMark',
+        x: originX - WEEKDAY_LABEL_GAP,
+        y: gridTop + row * step + cell / 2 + labelFont * 0.35,
+        text: label,
+        ...labelStyle,
+        textAnchor: 'end',
+        data: {},
+        aria: labelAria,
+      });
+    }
+
+    // Day cells: every day of the calendar year.
+    for (const day of utcDay.range(yearStart, yearEnd)) {
+      const col = week.count(firstWeek, day);
+      const row = weekdayRow(day, weekStart);
+      const key = isoDayKey(day);
+      const datum = dayData.get(key);
+      const dateLabel = formatDate(day, undefined, 'day');
+
+      if (datum) {
+        cellMarks.push({
+          type: 'rect',
+          key,
+          x: originX + col * step,
+          y: gridTop + row * step,
+          width: cell,
+          height: cell,
+          fill: getSequentialColor(scales, datum.value),
+          cornerRadius: cellRadius,
+          data: datum.row,
+          aria: {
+            label: `${dateLabel}, ${colorEnc.field}: ${calendarFmt(datum.value)}`,
+          },
+        });
+      } else {
+        cellMarks.push({
+          type: 'rect',
+          key,
+          x: originX + col * step,
+          y: gridTop + row * step,
+          width: cell,
+          height: cell,
+          fill: theme.colors.annotationFill,
+          cornerRadius: cellRadius,
+          data: {},
+          aria: { decorative: true },
+        });
+      }
+    }
+  }
+
+  return [...cellMarks, ...labelMarks];
+}

package/src/charts/calendar/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Calendar heatmap chart module.
+ *
+ * Exports the calendar renderer and computation function. Calendars emit
+ * RectMark day cells plus decorative TextMarkLayout month/weekday/year
+ * labels; there are no positional scales or axes (the compile pipeline
+ * suppresses them, arc precedent). The quantitative color encoding drives
+ * both the cell fills and the default-on continuous color legend.
+ */
+
+import type { ChartRenderer } from '../registry';
+import { computeCalendarMarks } from './compute';
+
+// ---------------------------------------------------------------------------
+// Calendar chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Calendar heatmap renderer.
+ *
+ * Produces one rect per day of each calendar year in the data, plus text
+ * marks for the month/weekday/year labels.
+ */
+export const calendarRenderer: ChartRenderer = (spec, scales, chartArea, _strategy, theme) => {
+  return computeCalendarMarks(spec, scales, chartArea, theme);
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeCalendarMarks, MIN_CELL_SIZE, parseUtcDay, weekdayRow } from './compute';

package/src/charts/column/__tests__/compute.test.ts

@@ -1,4 +1,5 @@
 import type { LayoutStrategy, Rect } from '@opendata-ai/openchart-core';
+import { buildD3Formatter } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../../../compiler/types';
 import { computeScales } from '../../../layout/scales';
@@ -55,7 +56,9 @@ function makeGroupedColumnSpec(): NormalizedChartSpec {
     ],
     encoding: {
       x: { field: 'month', type: 'nominal' },
-      y: { field: 'sales', type: 'quantitative' },
+      // Grouped is opt-out since v8 (stacked is now the default): stamp
+      // stack: null explicitly so this fixture stays grouped.
+      y: { field: 'sales', type: 'quantitative', stack: null },
       color: { field: 'region', type: 'nominal' },
     },
     chrome: {},
@@ -193,7 +196,7 @@ describe('computeColumnMarks', () => {
     });
   });
 
-  describe('grouped columns (default)', () => {
+  describe('grouped columns (stack: null)', () => {
     it('produces marks for all data rows', () => {
       const spec = makeGroupedColumnSpec();
       const scales = computeScales(spec, chartArea, spec.data);
@@ -351,7 +354,7 @@ describe('computeColumnLabels', () => {
     const spec = makeSimpleColumnSpec();
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
-    const labels = computeColumnLabels(marks, chartArea, 'auto', '$,.0f');
+    const labels = computeColumnLabels(marks, chartArea, 'auto', buildD3Formatter('$,.0f'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('$120');
@@ -379,7 +382,7 @@ describe('computeColumnLabels', () => {
     };
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
-    const labels = computeColumnLabels(marks, chartArea, 'all', '$,.2~f');
+    const labels = computeColumnLabels(marks, chartArea, 'all', buildD3Formatter('$,.2~f'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('$3.1');
@@ -407,7 +410,7 @@ describe('computeColumnLabels', () => {
     };
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
-    const labels = computeColumnLabels(marks, chartArea, 'all', '$,.2~fT');
+    const labels = computeColumnLabels(marks, chartArea, 'all', buildD3Formatter('$,.2~fT'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('$3.75T');
@@ -418,7 +421,7 @@ describe('computeColumnLabels', () => {
     const spec = makeSimpleColumnSpec();
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
-    const labels = computeColumnLabels(marks, chartArea, 'auto', '.0f%');
+    const labels = computeColumnLabels(marks, chartArea, 'auto', buildD3Formatter('.0f%'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('120%');
@@ -432,7 +435,7 @@ describe('computeColumnLabels', () => {
 
 describe('stack modes', () => {
   function makeStackedSpec(
-    stackMode: boolean | 'zero' | 'normalize' | 'center' | null,
+    stackMode: boolean | 'zero' | 'normalize' | 'center' | null | undefined,
   ): NormalizedChartSpec {
     return {
       markType: 'bar',
@@ -523,4 +526,15 @@ describe('stack modes', () => {
       expect(mark.stackGroup).toBeUndefined();
     }
   });
+
+  it('undefined (omitted) stacks by default (v8 VL-aligned default)', () => {
+    const spec = makeStackedSpec(undefined);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+
+    expect(marks.length).toBe(4);
+    for (const mark of marks) {
+      expect(mark.stackGroup).toBeDefined();
+    }
+  });
 });

package/src/charts/column/__tests__/labels.test.ts

@@ -1,4 +1,5 @@
 import type { RectMark } from '@opendata-ai/openchart-core';
+import { buildD3Formatter } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import { computeColumnLabels } from '../labels';
 
@@ -98,7 +99,81 @@ describe('computeColumnLabels positioning', () => {
   });
 
   it('applies labelFormat to numeric values', () => {
-    const labels = computeColumnLabels([makeMark(0, 1234)], chartArea, 'all', ',.0f');
+    const labels = computeColumnLabels(
+      [makeMark(0, 1234)],
+      chartArea,
+      'all',
+      buildD3Formatter(',.0f'),
+    );
     expect(labels[0].text).toBe('1,234');
   });
 });
+
+describe('computeColumnLabels stacked segments', () => {
+  /** One segment of a stacked column, positioned by its top edge. */
+  function makeStackedMark(y: number, height: number, fill: string, value: number): RectMark {
+    return {
+      type: 'rect',
+      x: 0,
+      y,
+      width: 60,
+      height,
+      fill,
+      stackGroup: 'Cat0',
+      data: { category: 'Cat0', value },
+      aria: { label: `Cat0: ${value}` },
+    };
+  }
+
+  it('centers the label inside its own segment, not above it', () => {
+    // Above a stacked segment's top edge is the next segment up, not the
+    // background, so the label must stay within its own band.
+    const mark = makeStackedMark(100, 80, '#0e7490', 33);
+    const labels = computeColumnLabels([mark], chartArea, 'all');
+
+    expect(labels).toHaveLength(1);
+    expect(labels[0].y).toBeGreaterThan(mark.y);
+    expect(labels[0].y).toBeLessThan(mark.y + mark.height);
+  });
+
+  it('picks a fill that contrasts with its own segment', () => {
+    // A dark segment takes white text; a light segment takes near-black. The
+    // old code tinted the text with the segment's own series color, which put
+    // colored text on a colored fill.
+    const dark = computeColumnLabels([makeStackedMark(100, 80, '#0e7490', 33)], chartArea, 'all');
+    const light = computeColumnLabels([makeStackedMark(100, 80, '#e2e8f0', 33)], chartArea, 'all');
+
+    expect(dark[0].style.fill).toBe('#ffffff');
+    expect(light[0].style.fill).toBe('#111111');
+  });
+
+  it('hides the label when the segment is too short to hold it', () => {
+    // A ~4% segment (Nuclear in the energy-mix demo) can't fit a 10px label
+    // without spilling into its neighbours.
+    const labels = computeColumnLabels([makeStackedMark(100, 6, '#0e7490', 4)], chartArea, 'all');
+
+    expect(labels).toHaveLength(1);
+    expect(labels[0].visible).toBe(false);
+  });
+
+  it('an explicit labels.color still wins over the contrast pick', () => {
+    const labels = computeColumnLabels(
+      [makeStackedMark(100, 80, '#0e7490', 33)],
+      chartArea,
+      'all',
+      undefined,
+      undefined,
+      undefined,
+      '#ff00ff',
+    );
+
+    expect(labels[0].style.fill).toBe('#ff00ff');
+  });
+
+  it('leaves unstacked columns labeling above the bar', () => {
+    const mark = makeMark(0, 20);
+    const labels = computeColumnLabels([mark], chartArea, 'all');
+
+    expect(labels[0].y).toBeLessThan(mark.y);
+  });
+});

package/src/charts/column/compute.ts

@@ -95,12 +95,8 @@ export function computeColumnMarks(
     const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
 
     if (needsStacking) {
-      // stack: true/'zero'/'normalize'/'center' -> stacked; default (undefined/null/false) -> grouped
-      const stackEnabled =
-        yChannel.stack === true ||
-        yChannel.stack === 'zero' ||
-        yChannel.stack === 'normalize' ||
-        yChannel.stack === 'center';
+      // stack: undefined/true/'zero'/'normalize'/'center' -> stacked (default); null/false -> grouped
+      const stackEnabled = yChannel.stack !== null && yChannel.stack !== false;
 
       if (!stackEnabled) {
         marks = computeGroupedColumns(

package/src/charts/column/index.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Mark } from '@opendata-ai/openchart-core';
+import { resolveFieldFormatter } from '../../format/field-format';
 import type { ChartRenderer } from '../registry';
 import { computeColumnMarks } from './compute';
 import { computeColumnLabels } from './labels';
@@ -13,20 +14,27 @@ import { computeColumnLabels } from './labels';
 // Column chart renderer
 // ---------------------------------------------------------------------------
 
-export const columnRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+export const columnRenderer: ChartRenderer = (spec, scales, chartArea, strategy, theme) => {
   const marks = computeColumnMarks(spec, scales, chartArea, strategy);
 
   // Compute and attach value labels (respects spec.labels.density)
   const valueField =
     spec.encoding?.y && 'field' in spec.encoding.y ? spec.encoding.y.field : undefined;
+  const labelFormatter = resolveFieldFormatter({
+    surfaceFormat: spec.labels.format,
+    channelFormat:
+      spec.encoding?.y && 'format' in spec.encoding.y ? spec.encoding.y.format : undefined,
+    values: valueField ? spec.data.map((r) => r[valueField]) : [],
+  });
   const labels = computeColumnLabels(
     marks,
     chartArea,
     spec.labels.density,
-    spec.labels.format,
+    labelFormatter,
     spec.labels.prefix,
     valueField,
     spec.labels.color,
+    theme.isDark,
     spec.labels.fontSize,
     spec.labels.suffix,
   );