@opendata-ai/openchart-core 2.0.0

package/src/layout/chrome.ts

@@ -0,0 +1,223 @@
+/**
+ * Chrome layout computation.
+ *
+ * Takes a Chrome spec + resolved theme and produces a ResolvedChrome
+ * with computed text positions, styles, and total chrome heights.
+ */
+
+import type {
+  MeasureTextFn,
+  ResolvedChrome,
+  ResolvedChromeElement,
+  TextStyle,
+} from '../types/layout';
+import type { Chrome, ChromeText } from '../types/spec';
+import type { ChromeDefaults, ResolvedTheme } from '../types/theme';
+import { estimateTextHeight, estimateTextWidth } from './text-measure';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Normalize a chrome field to text + optional style and offset overrides. */
+function normalizeChromeText(
+  value: string | ChromeText | undefined,
+): { text: string; style?: ChromeText['style']; offset?: ChromeText['offset'] } | null {
+  if (value === undefined) return null;
+  if (typeof value === 'string') return { text: value };
+  return { text: value.text, style: value.style, offset: value.offset };
+}
+
+/** Build a TextStyle from chrome defaults + optional overrides. */
+function buildTextStyle(
+  defaults: ChromeDefaults,
+  fontFamily: string,
+  textColor: string,
+  overrides?: ChromeText['style'],
+): TextStyle {
+  return {
+    fontFamily: overrides?.fontFamily ?? fontFamily,
+    fontSize: overrides?.fontSize ?? defaults.fontSize,
+    fontWeight: overrides?.fontWeight ?? defaults.fontWeight,
+    fill: overrides?.color ?? textColor ?? defaults.color,
+    lineHeight: defaults.lineHeight,
+    textAnchor: 'start',
+    dominantBaseline: 'hanging',
+  };
+}
+
+/** Measure text width using the provided function or heuristic fallback. */
+function measureWidth(text: string, style: TextStyle, measureText?: MeasureTextFn): number {
+  if (measureText) {
+    return measureText(text, style.fontSize, style.fontWeight).width;
+  }
+  return estimateTextWidth(text, style.fontSize, style.fontWeight);
+}
+
+/**
+ * Estimate how many lines text will wrap to, given a max width.
+ * Returns at least 1.
+ */
+function estimateLineCount(
+  text: string,
+  style: TextStyle,
+  maxWidth: number,
+  measureText?: MeasureTextFn,
+): number {
+  const fullWidth = measureWidth(text, style, measureText);
+  if (fullWidth <= maxWidth) return 1;
+  return Math.ceil(fullWidth / maxWidth);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute resolved chrome layout from a Chrome spec and resolved theme.
+ *
+ * Produces positioned text elements and total chrome heights (top and bottom).
+ * Top chrome: title, subtitle. Bottom chrome: source, byline, footer.
+ *
+ * @param chrome - The Chrome spec from the user's VizSpec.
+ * @param theme - The fully resolved theme.
+ * @param width - Total available width in pixels.
+ * @param measureText - Optional real text measurement function from the adapter.
+ */
+export function computeChrome(
+  chrome: Chrome | undefined,
+  theme: ResolvedTheme,
+  width: number,
+  measureText?: MeasureTextFn,
+): ResolvedChrome {
+  if (!chrome) {
+    return { topHeight: 0, bottomHeight: 0 };
+  }
+
+  const padding = theme.spacing.padding;
+  const chromeGap = theme.spacing.chromeGap;
+  const maxWidth = width - padding * 2;
+  const fontFamily = theme.fonts.family;
+
+  // Track vertical cursor for top elements
+  let topY = padding;
+  const topElements: Partial<Pick<ResolvedChrome, 'title' | 'subtitle'>> = {};
+
+  // Title
+  const titleNorm = normalizeChromeText(chrome.title);
+  if (titleNorm) {
+    const style = buildTextStyle(
+      theme.chrome.title,
+      fontFamily,
+      theme.chrome.title.color,
+      titleNorm.style,
+    );
+    const lineCount = estimateLineCount(titleNorm.text, style, maxWidth, measureText);
+    const element: ResolvedChromeElement = {
+      text: titleNorm.text,
+      x: padding + (titleNorm.offset?.dx ?? 0),
+      y: topY + (titleNorm.offset?.dy ?? 0),
+      maxWidth,
+      style,
+    };
+    topElements.title = element;
+    topY += estimateTextHeight(style.fontSize, lineCount, style.lineHeight) + chromeGap;
+  }
+
+  // Subtitle
+  const subtitleNorm = normalizeChromeText(chrome.subtitle);
+  if (subtitleNorm) {
+    const style = buildTextStyle(
+      theme.chrome.subtitle,
+      fontFamily,
+      theme.chrome.subtitle.color,
+      subtitleNorm.style,
+    );
+    const lineCount = estimateLineCount(subtitleNorm.text, style, maxWidth, measureText);
+    const element: ResolvedChromeElement = {
+      text: subtitleNorm.text,
+      x: padding + (subtitleNorm.offset?.dx ?? 0),
+      y: topY + (subtitleNorm.offset?.dy ?? 0),
+      maxWidth,
+      style,
+    };
+    topElements.subtitle = element;
+    topY += estimateTextHeight(style.fontSize, lineCount, style.lineHeight) + chromeGap;
+  }
+
+  // Add chromeToChart gap if there are any top elements
+  const hasTopChrome = titleNorm || subtitleNorm;
+  const topHeight = hasTopChrome ? topY - padding + theme.spacing.chromeToChart - chromeGap : 0;
+
+  // Bottom elements: source, byline, footer
+  // We compute heights bottom-up but position them after knowing total
+  const bottomElements: Partial<Pick<ResolvedChrome, 'source' | 'byline' | 'footer'>> = {};
+  let bottomHeight = 0;
+
+  const bottomItems: Array<{
+    key: 'source' | 'byline' | 'footer';
+    norm: { text: string; style?: ChromeText['style']; offset?: ChromeText['offset'] };
+    defaults: ChromeDefaults;
+  }> = [];
+
+  const sourceNorm = normalizeChromeText(chrome.source);
+  if (sourceNorm) {
+    bottomItems.push({
+      key: 'source',
+      norm: sourceNorm,
+      defaults: theme.chrome.source,
+    });
+  }
+
+  const bylineNorm = normalizeChromeText(chrome.byline);
+  if (bylineNorm) {
+    bottomItems.push({
+      key: 'byline',
+      norm: bylineNorm,
+      defaults: theme.chrome.byline,
+    });
+  }
+
+  const footerNorm = normalizeChromeText(chrome.footer);
+  if (footerNorm) {
+    bottomItems.push({
+      key: 'footer',
+      norm: footerNorm,
+      defaults: theme.chrome.footer,
+    });
+  }
+
+  if (bottomItems.length > 0) {
+    bottomHeight += theme.spacing.chartToFooter;
+
+    for (const item of bottomItems) {
+      const style = buildTextStyle(item.defaults, fontFamily, item.defaults.color, item.norm.style);
+      const lineCount = estimateLineCount(item.norm.text, style, maxWidth, measureText);
+      const height = estimateTextHeight(style.fontSize, lineCount, style.lineHeight);
+
+      // y positions will be computed relative to the bottom of the
+      // chart area by the engine. We store offsets from bottom start.
+      bottomElements[item.key] = {
+        text: item.norm.text,
+        x: padding + (item.norm.offset?.dx ?? 0),
+        y: bottomHeight + (item.norm.offset?.dy ?? 0), // offset from where bottom chrome starts
+        maxWidth,
+        style,
+      };
+
+      bottomHeight += height + chromeGap;
+    }
+
+    // Remove trailing gap
+    bottomHeight -= chromeGap;
+    // Add bottom padding
+    bottomHeight += padding;
+  }
+
+  return {
+    topHeight,
+    bottomHeight,
+    ...topElements,
+    ...bottomElements,
+  };
+}

package/src/layout/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Layout module barrel export.
+ */
+
+export { computeChrome } from './chrome';
+export { estimateTextHeight, estimateTextWidth } from './text-measure';

package/src/layout/text-measure.ts

@@ -0,0 +1,54 @@
+/**
+ * Heuristic text measurement for environments without a DOM.
+ *
+ * These are intentionally approximate. Adapters can provide a real
+ * measureText function via CompileOptions for higher accuracy.
+ * The engine uses the real function when available, falls back to
+ * these heuristics when not.
+ */
+
+/**
+ * Average character width as a fraction of font size for Inter.
+ * Inter is slightly wider than Helvetica, narrower than Courier.
+ * This is a reasonable middle ground.
+ */
+const AVG_CHAR_WIDTH_RATIO = 0.55;
+
+/** Narrower characters (i, l, t, etc.) bring the average down. */
+const WEIGHT_ADJUSTMENT: Record<number, number> = {
+  100: 0.9,
+  200: 0.92,
+  300: 0.95,
+  400: 1.0,
+  500: 1.02,
+  600: 1.05,
+  700: 1.08,
+  800: 1.1,
+  900: 1.12,
+};
+
+/**
+ * Estimate the rendered width of a text string.
+ *
+ * Uses a per-character average width based on font size, adjusted
+ * for font weight. Accurate to within ~20% for Latin text in Inter.
+ *
+ * @param text - The text string to measure.
+ * @param fontSize - Font size in pixels.
+ * @param fontWeight - Font weight (100-900). Defaults to 400.
+ */
+export function estimateTextWidth(text: string, fontSize: number, fontWeight = 400): number {
+  const weightFactor = WEIGHT_ADJUSTMENT[fontWeight] ?? 1.0;
+  return text.length * fontSize * AVG_CHAR_WIDTH_RATIO * weightFactor;
+}
+
+/**
+ * Estimate the rendered height of a text block.
+ *
+ * @param fontSize - Font size in pixels.
+ * @param lineCount - Number of lines. Defaults to 1.
+ * @param lineHeight - Line height multiplier. Defaults to 1.3.
+ */
+export function estimateTextHeight(fontSize: number, lineCount = 1, lineHeight = 1.3): number {
+  return fontSize * lineHeight * lineCount;
+}

package/src/locale/__tests__/format.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { abbreviateNumber, formatDate, formatNumber } from '../format';
+
+describe('formatNumber', () => {
+  it('formats integers with commas', () => {
+    expect(formatNumber(1500000)).toBe('1,500,000');
+  });
+
+  it('formats decimals to 2 places', () => {
+    expect(formatNumber(42.567)).toBe('42.57');
+  });
+
+  it('handles zero', () => {
+    expect(formatNumber(0)).toBe('0');
+  });
+
+  it('handles negative numbers', () => {
+    // d3-format uses unicode minus sign (U+2212), not ASCII hyphen-minus
+    expect(formatNumber(-1234)).toBe('\u22121,234');
+  });
+
+  it('handles Infinity', () => {
+    expect(formatNumber(Infinity)).toBe('Infinity');
+  });
+
+  it('handles NaN', () => {
+    expect(formatNumber(NaN)).toBe('NaN');
+  });
+});
+
+describe('abbreviateNumber', () => {
+  it('abbreviates millions', () => {
+    expect(abbreviateNumber(1500000)).toBe('1.5M');
+  });
+
+  it('abbreviates billions', () => {
+    expect(abbreviateNumber(2300000000)).toBe('2.3B');
+  });
+
+  it('abbreviates thousands', () => {
+    expect(abbreviateNumber(2300)).toBe('2.3K');
+  });
+
+  it('drops trailing .0', () => {
+    expect(abbreviateNumber(1000000)).toBe('1M');
+    expect(abbreviateNumber(2000)).toBe('2K');
+  });
+
+  it('does not abbreviate small numbers', () => {
+    expect(abbreviateNumber(42)).toBe('42');
+  });
+
+  it('handles negative numbers', () => {
+    expect(abbreviateNumber(-1500000)).toBe('-1.5M');
+  });
+
+  it('abbreviates trillions', () => {
+    expect(abbreviateNumber(1_200_000_000_000)).toBe('1.2T');
+  });
+});
+
+describe('formatDate', () => {
+  it('formats a Date object', () => {
+    const result = formatDate(new Date('2020-06-15'), undefined, 'day');
+    expect(result).toContain('2020');
+    expect(result).toContain('Jun');
+    expect(result).toContain('15');
+  });
+
+  it('formats an ISO string', () => {
+    const result = formatDate('2020-01-01', undefined, 'year');
+    expect(result).toBe('2020');
+  });
+
+  it('formats quarters', () => {
+    const result = formatDate(new Date('2020-04-15'), undefined, 'quarter');
+    expect(result).toBe('Q2 2020');
+  });
+
+  it('formats months', () => {
+    const result = formatDate(new Date('2020-03-01'), undefined, 'month');
+    expect(result).toContain('Mar');
+    expect(result).toContain('2020');
+  });
+
+  it('handles invalid dates gracefully', () => {
+    const result = formatDate('not-a-date');
+    expect(result).toBe('not-a-date');
+  });
+});

package/src/locale/format.ts

@@ -0,0 +1,132 @@
+/**
+ * Locale-aware number and date formatting utilities.
+ *
+ * Uses d3-format and d3-time-format for formatting,
+ * with convenience wrappers for common patterns.
+ */
+
+import { format as d3Format } from 'd3-format';
+import { timeFormat, utcFormat } from 'd3-time-format';
+
+// ---------------------------------------------------------------------------
+// Number formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a number with locale-appropriate separators.
+ *
+ * Uses d3-format under the hood. Default format: comma-separated
+ * with auto-precision (e.g. 1500000 -> "1,500,000").
+ *
+ * @param value - The number to format.
+ * @param locale - Locale string (currently unused, reserved for i18n).
+ */
+export function formatNumber(value: number, _locale?: string): string {
+  if (!Number.isFinite(value)) return String(value);
+  // Auto-detect: use integer format for whole numbers, 2dp for decimals
+  if (Number.isInteger(value)) {
+    return d3Format(',')(value);
+  }
+  return d3Format(',.2f')(value);
+}
+
+// ---------------------------------------------------------------------------
+// Number abbreviation
+// ---------------------------------------------------------------------------
+
+/** Suffixes for abbreviated numbers. */
+const ABBREVIATIONS: Array<{ threshold: number; suffix: string; divisor: number }> = [
+  { threshold: 1_000_000_000_000, suffix: 'T', divisor: 1_000_000_000_000 },
+  { threshold: 1_000_000_000, suffix: 'B', divisor: 1_000_000_000 },
+  { threshold: 1_000_000, suffix: 'M', divisor: 1_000_000 },
+  { threshold: 1_000, suffix: 'K', divisor: 1_000 },
+];
+
+/**
+ * Abbreviate a large number with a suffix.
+ *
+ * Examples:
+ * - 1500000 -> "1.5M"
+ * - 2300 -> "2.3K"
+ * - 42 -> "42"
+ * - 1000000000 -> "1B"
+ */
+export function abbreviateNumber(value: number): string {
+  if (!Number.isFinite(value)) return String(value);
+
+  const absValue = Math.abs(value);
+  const sign = value < 0 ? '-' : '';
+
+  for (const { threshold, suffix, divisor } of ABBREVIATIONS) {
+    if (absValue >= threshold) {
+      const abbreviated = absValue / divisor;
+      // Use .1f precision, drop trailing .0
+      const formatted = abbreviated % 1 === 0 ? String(abbreviated) : d3Format('.1f')(abbreviated);
+      return `${sign}${formatted}${suffix}`;
+    }
+  }
+
+  return formatNumber(value);
+}
+
+// ---------------------------------------------------------------------------
+// Date formatting
+// ---------------------------------------------------------------------------
+
+/** Granularity levels for date formatting. */
+export type DateGranularity = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute';
+
+/** Format strings for each granularity level. */
+const GRANULARITY_FORMATS: Record<DateGranularity, string> = {
+  year: '%Y',
+  quarter: '', // Quarter is always special-cased in formatDate() below
+  month: '%b %Y',
+  week: '%b %d',
+  day: '%b %d, %Y',
+  hour: '%b %d %H:%M',
+  minute: '%H:%M',
+};
+
+/**
+ * Format a date value for display.
+ *
+ * @param value - Date object, ISO string, or timestamp number.
+ * @param locale - Locale string (currently unused, reserved for i18n).
+ * @param granularity - Time granularity for format selection.
+ */
+export function formatDate(
+  value: Date | string | number,
+  _locale?: string,
+  granularity?: DateGranularity,
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+
+  const gran = granularity ?? inferGranularity(date);
+
+  // Special handling for quarter (not a d3 format token)
+  if (gran === 'quarter') {
+    const q = Math.ceil((date.getMonth() + 1) / 3);
+    return `Q${q} ${date.getFullYear()}`;
+  }
+
+  const formatStr = GRANULARITY_FORMATS[gran];
+  // Use UTC format for year/month/day to avoid timezone shifts
+  if (['year', 'month', 'day'].includes(gran)) {
+    return utcFormat(formatStr)(date);
+  }
+  return timeFormat(formatStr)(date);
+}
+
+/**
+ * Infer the appropriate granularity from a date value.
+ * If time components are all zero, assume day or higher.
+ */
+function inferGranularity(date: Date): DateGranularity {
+  if (date.getHours() !== 0 || date.getMinutes() !== 0) {
+    return date.getMinutes() !== 0 ? 'minute' : 'hour';
+  }
+  if (date.getDate() !== 1) return 'day';
+  if (date.getMonth() !== 0) return 'month';
+  return 'year';
+}

package/src/locale/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Locale module barrel export.
+ */
+
+export type { DateGranularity } from './format';
+export { abbreviateNumber, formatDate, formatNumber } from './format';

package/src/responsive/__tests__/breakpoints.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { getBreakpoint, getLayoutStrategy } from '../breakpoints';
+
+describe('getBreakpoint', () => {
+  it('returns compact for widths below 400', () => {
+    expect(getBreakpoint(320)).toBe('compact');
+    expect(getBreakpoint(399)).toBe('compact');
+  });
+
+  it('returns medium for widths 400-700', () => {
+    expect(getBreakpoint(400)).toBe('medium');
+    expect(getBreakpoint(550)).toBe('medium');
+    expect(getBreakpoint(700)).toBe('medium');
+  });
+
+  it('returns full for widths above 700', () => {
+    expect(getBreakpoint(701)).toBe('full');
+    expect(getBreakpoint(1200)).toBe('full');
+  });
+
+  it('handles edge cases', () => {
+    expect(getBreakpoint(0)).toBe('compact');
+    expect(getBreakpoint(5000)).toBe('full');
+  });
+});
+
+describe('getLayoutStrategy', () => {
+  it('compact has no labels and minimal axes', () => {
+    const strategy = getLayoutStrategy('compact');
+    expect(strategy.labelMode).toBe('none');
+    expect(strategy.legendPosition).toBe('top');
+    expect(strategy.annotationPosition).toBe('tooltip-only');
+    expect(strategy.axisLabelDensity).toBe('minimal');
+  });
+
+  it('medium has important labels and reduced axes', () => {
+    const strategy = getLayoutStrategy('medium');
+    expect(strategy.labelMode).toBe('important');
+    expect(strategy.legendPosition).toBe('top');
+    expect(strategy.annotationPosition).toBe('inline');
+    expect(strategy.axisLabelDensity).toBe('reduced');
+  });
+
+  it('full has all labels and legend on right', () => {
+    const strategy = getLayoutStrategy('full');
+    expect(strategy.labelMode).toBe('all');
+    expect(strategy.legendPosition).toBe('right');
+    expect(strategy.annotationPosition).toBe('inline');
+    expect(strategy.axisLabelDensity).toBe('full');
+  });
+
+  it('different widths produce different strategies', () => {
+    const compact = getLayoutStrategy(getBreakpoint(320));
+    const full = getLayoutStrategy(getBreakpoint(800));
+    expect(compact.legendPosition).not.toBe(full.legendPosition);
+    expect(compact.labelMode).not.toBe(full.labelMode);
+  });
+});

package/src/responsive/breakpoints.ts

@@ -0,0 +1,92 @@
+/**
+ * Responsive breakpoints and layout strategies.
+ *
+ * Three breakpoints based on container width:
+ * - compact: < 400px (mobile, small embeds)
+ * - medium: 400-700px (tablet, sidebars)
+ * - full: > 700px (desktop, full-width)
+ */
+
+// ---------------------------------------------------------------------------
+// Breakpoint type and detection
+// ---------------------------------------------------------------------------
+
+/** Responsive breakpoint based on container width. */
+export type Breakpoint = 'compact' | 'medium' | 'full';
+
+/** Breakpoint thresholds in pixels. */
+export const BREAKPOINT_COMPACT_MAX = 400;
+export const BREAKPOINT_MEDIUM_MAX = 700;
+
+/**
+ * Determine the breakpoint for a given container width.
+ */
+export function getBreakpoint(width: number): Breakpoint {
+  if (width < BREAKPOINT_COMPACT_MAX) return 'compact';
+  if (width <= BREAKPOINT_MEDIUM_MAX) return 'medium';
+  return 'full';
+}
+
+// ---------------------------------------------------------------------------
+// Layout strategy
+// ---------------------------------------------------------------------------
+
+/** Label display mode at a given breakpoint. */
+export type LabelMode = 'all' | 'important' | 'none';
+
+/** Legend position at a given breakpoint. */
+export type LegendPosition = 'top' | 'right' | 'bottom' | 'bottom-right' | 'inline';
+
+/** Annotation position strategy. */
+export type AnnotationPosition = 'inline' | 'tooltip-only';
+
+/** Axis label density (controls tick count reduction). */
+export type AxisLabelDensity = 'full' | 'reduced' | 'minimal';
+
+/**
+ * Layout strategy defining how the visualization adapts to available space.
+ * Returned by getLayoutStrategy() based on the current breakpoint.
+ */
+export interface LayoutStrategy {
+  /** How data labels are displayed. */
+  labelMode: LabelMode;
+  /** Where the legend is positioned. */
+  legendPosition: LegendPosition;
+  /** How annotations are displayed. */
+  annotationPosition: AnnotationPosition;
+  /** Axis tick density. */
+  axisLabelDensity: AxisLabelDensity;
+}
+
+/**
+ * Get the layout strategy for a given breakpoint.
+ *
+ * Compact: minimal chrome, no inline labels, legend on top, reduced axes.
+ * Medium: moderate labels, legend on top, reduced axes.
+ * Full: all labels, legend on right, full axes.
+ */
+export function getLayoutStrategy(breakpoint: Breakpoint): LayoutStrategy {
+  switch (breakpoint) {
+    case 'compact':
+      return {
+        labelMode: 'none',
+        legendPosition: 'top',
+        annotationPosition: 'tooltip-only',
+        axisLabelDensity: 'minimal',
+      };
+    case 'medium':
+      return {
+        labelMode: 'important',
+        legendPosition: 'top',
+        annotationPosition: 'inline',
+        axisLabelDensity: 'reduced',
+      };
+    case 'full':
+      return {
+        labelMode: 'all',
+        legendPosition: 'right',
+        annotationPosition: 'inline',
+        axisLabelDensity: 'full',
+      };
+  }
+}

package/src/responsive/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Responsive module barrel export.
+ */
+
+export type {
+  AnnotationPosition,
+  AxisLabelDensity,
+  Breakpoint,
+  LabelMode,
+  LayoutStrategy,
+  LegendPosition,
+} from './breakpoints';
+export {
+  BREAKPOINT_COMPACT_MAX,
+  BREAKPOINT_MEDIUM_MAX,
+  getBreakpoint,
+  getLayoutStrategy,
+} from './breakpoints';