@opendata-ai/openchart-core 7.11.0 → 8.0.0-rc.10

package/src/locale/format.ts

@@ -23,10 +23,12 @@ import { timeFormat, utcFormat } from 'd3-time-format';
  */
 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);
   }
+  if (Math.abs(value) < 0.005) {
+    return d3Format('.2~r')(value);
+  }
   return d3Format(',.2f')(value);
 }
 
@@ -34,41 +36,75 @@ export function formatNumber(value: number, _locale?: string): string {
 // Number abbreviation
 // ---------------------------------------------------------------------------
 
-/** Suffixes for abbreviated numbers. */
-const ABBREVIATIONS: Array<{ threshold: number; suffix: string; divisor: number }> = [
+const UNIT_TABLE: 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 },
+  { 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"
- */
+function unitFor(abs: number): { suffix: string; divisor: number } {
+  for (const entry of UNIT_TABLE) {
+    if (abs >= entry.threshold) return entry;
+  }
+  return { suffix: '', divisor: 1 };
+}
+
+function fractionDigits(x: number): number {
+  const a = Math.abs(x);
+  for (let p = 0; p <= 3; p++) {
+    const scaled = a * 10 ** p;
+    if (Math.abs(scaled - Math.round(scaled)) < 1e-9) return p;
+  }
+  return 4;
+}
+
 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) {
+  for (let i = 0; i < UNIT_TABLE.length; i++) {
+    const { threshold, suffix, divisor } = UNIT_TABLE[i];
     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}`;
+      const mantissa = d3Format('.1~f')(absValue / divisor);
+      // Roll-up: if mantissa rounds to 1000, use the next unit up.
+      // When i === 0 (T), there's no larger unit so we emit "1000T".
+      if (mantissa === '1000' && i > 0) {
+        return `${sign}1${UNIT_TABLE[i - 1].suffix}`;
+      }
+      return `${sign}${mantissa}${suffix}`;
     }
   }
 
   return formatNumber(value);
 }
 
+// ---------------------------------------------------------------------------
+// Ordinal formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a number as an English ordinal: 1 -> "1st", 2 -> "2nd", 3 -> "3rd",
+ * 11 -> "11th", 22 -> "22nd". Values are rounded to the nearest integer first;
+ * intended for rank axes where the domain is integer positions.
+ */
+export function formatOrdinal(value: number): string {
+  if (!Number.isFinite(value)) return String(value);
+  const n = Math.round(value);
+  const abs = Math.abs(n);
+  const rem100 = abs % 100;
+  const rem10 = abs % 10;
+  let suffix: string;
+  if (rem100 >= 11 && rem100 <= 13) suffix = 'th';
+  else if (rem10 === 1) suffix = 'st';
+  else if (rem10 === 2) suffix = 'nd';
+  else if (rem10 === 3) suffix = 'rd';
+  else suffix = 'th';
+  return `${n}${suffix}`;
+}
+
 // ---------------------------------------------------------------------------
 // d3-format with suffix support
 // ---------------------------------------------------------------------------
@@ -89,11 +125,17 @@ const D3_FORMAT_SUFFIX_RE = /^(.*~?[efgsrdxXobcnp%])(.+)$/;
  * Build a number formatter from a d3-format string, with support for a
  * trailing literal suffix that d3-format itself would reject.
  *
+ * Also accepts the OpenChart extension `'ordinal'`, which renders English
+ * ordinals ("1st", "2nd", "3rd") for rank axes.
+ *
  * Returns null if the format string is falsy or unparseable.
  */
 export function buildD3Formatter(formatStr: string | undefined): ((v: number) => string) | null {
   if (!formatStr) return null;
 
+  // OpenChart extension: rank-axis ordinals ("1st", "2nd", "3rd").
+  if (formatStr === 'ordinal') return formatOrdinal;
+
   try {
     const fmt = d3Format(formatStr);
     // Replace SI prefix "G" (giga) with "B" (billion) for financial readability
@@ -117,6 +159,189 @@ export function buildD3Formatter(formatStr: string | undefined): ((v: number) =>
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Number formatter type + semantic formatters
+// ---------------------------------------------------------------------------
+
+export type NumberFormatter = (value: number) => string;
+
+export function formatPercent(value: number, options?: { fraction?: boolean }): string {
+  const fraction = options?.fraction ?? true;
+  if (fraction) {
+    return d3Format('.1~%')(value);
+  }
+  return `${d3Format(',.1~f')(value)}%`;
+}
+
+export function formatCurrency(value: number, options?: { compact?: boolean }): string {
+  const compact = options?.compact ?? false;
+  const abs = Math.abs(value);
+  const sign = value < 0 ? '-' : '';
+
+  if (compact) {
+    if (abs >= 1000) {
+      return `${sign}$${abbreviateNumber(abs)}`;
+    }
+    return `${sign}$${formatNumber(abs)}`;
+  }
+  if (Number.isInteger(value)) {
+    return sign + d3Format('$,')(abs);
+  }
+  return sign + d3Format('$,.2f')(abs);
+}
+
+// ---------------------------------------------------------------------------
+// Years guard
+// ---------------------------------------------------------------------------
+
+export function isYearLikeValues(values: readonly number[]): boolean {
+  if (values.length === 0) return false;
+  for (const v of values) {
+    if (!Number.isFinite(v) || !Number.isInteger(v) || v < 1500 || v > 2500) return false;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Field format context
+// ---------------------------------------------------------------------------
+
+export interface FieldFormatContext {
+  extent?: [number, number];
+  allIntegers?: boolean;
+  surface?: 'chart' | 'table';
+  step?: number;
+  stepReference?: number;
+}
+
+export function computeFieldFormatContext(
+  values: Iterable<unknown>,
+  surface?: 'chart' | 'table',
+): FieldFormatContext {
+  let min = Infinity;
+  let max = -Infinity;
+  let allIntegers = true;
+  let hasFinite = false;
+
+  for (const raw of values) {
+    const v = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : NaN;
+    if (!Number.isFinite(v)) continue;
+    hasFinite = true;
+    if (v < min) min = v;
+    if (v > max) max = v;
+    if (allIntegers && !Number.isInteger(v)) allIntegers = false;
+  }
+
+  const ctx: FieldFormatContext = {};
+  if (hasFinite) {
+    ctx.extent = [min, max];
+    ctx.allIntegers = allIntegers;
+  }
+  if (surface) ctx.surface = surface;
+  return ctx;
+}
+
+export function isYearContext(ctx: FieldFormatContext | undefined): boolean {
+  if (!ctx?.extent || !ctx.allIntegers) return false;
+  const [min, max] = ctx.extent;
+  return min >= 1500 && max <= 2500;
+}
+
+// ---------------------------------------------------------------------------
+// Keyword-aware formatter resolution
+// ---------------------------------------------------------------------------
+
+export function resolveNumberFormatter(
+  formatStr: string | undefined,
+  ctx?: FieldFormatContext,
+): NumberFormatter | null {
+  if (!formatStr) return null;
+
+  if (formatStr === 'ordinal') return formatOrdinal;
+
+  if (formatStr === 'percent') {
+    // Heuristic: if all values fit in [0,1] (maxAbs <= 1), treat them as
+    // fractions (0.45 -> "45%"). Values > 1 are treated as pre-scaled
+    // (45 -> "45%"). Datasets like [0, 0.5, 1.1] are ambiguous; the <= 1
+    // threshold errs on the side of the most common convention (fractions).
+    const fraction = ctx?.extent
+      ? Math.max(Math.abs(ctx.extent[0]), Math.abs(ctx.extent[1])) <= 1
+      : true;
+    return (v: number) => formatPercent(v, { fraction });
+  }
+
+  if (formatStr === 'currency') {
+    const isTable = ctx?.surface === 'table';
+    if (!isTable && ctx?.step != null && (ctx.stepReference ?? 0) >= 1000) {
+      const stepFmt = buildCompactStepFormatter(ctx.step);
+      return (v: number) => {
+        const sign = v < 0 ? '-' : '';
+        return `${sign}$${stepFmt(Math.abs(v))}`;
+      };
+    }
+    return (v: number) => formatCurrency(v, { compact: !isTable });
+  }
+
+  return buildD3Formatter(formatStr);
+}
+
+// ---------------------------------------------------------------------------
+// Default number formatter
+// ---------------------------------------------------------------------------
+
+export function defaultNumberFormatter(ctx?: FieldFormatContext): NumberFormatter {
+  if (isYearContext(ctx)) {
+    return (v: number) => String(Math.round(v));
+  }
+
+  if (ctx?.surface === 'table') {
+    return formatNumber;
+  }
+
+  if (ctx?.step != null && (ctx.stepReference ?? maxAbs(ctx.extent)) >= 1000) {
+    return buildCompactStepFormatter(ctx.step);
+  }
+
+  return (v: number) => {
+    if (!Number.isFinite(v)) return String(v);
+    // When no context is provided (ARIA marks, standalone helpers) we
+    // fall back to a per-value year heuristic: integers in [1500, 2500]
+    // render bare. This trades false positives on non-year integers
+    // (e.g. "connections: 2024") for avoiding "2k" on actual year axes.
+    // Callers with field context should always pass it to get the
+    // field-level isYearContext check instead.
+    if (ctx?.extent === undefined && ctx?.allIntegers === undefined) {
+      if (Number.isInteger(v) && v >= 1500 && v <= 2500) return String(v);
+    }
+    return Math.abs(v) >= 1000 ? abbreviateNumber(v) : formatNumber(v);
+  };
+}
+
+function maxAbs(extent: [number, number] | undefined): number {
+  if (!extent) return 0;
+  return Math.max(Math.abs(extent[0]), Math.abs(extent[1]));
+}
+
+// ---------------------------------------------------------------------------
+// Step-aware compact tick formatter
+// ---------------------------------------------------------------------------
+
+export function buildCompactStepFormatter(step: number): NumberFormatter {
+  return (v: number) => {
+    if (v === 0) return '0';
+    if (!Number.isFinite(v)) return String(v);
+    const abs = Math.abs(v);
+    if (abs < 1000) return formatNumber(v);
+    const { suffix, divisor } = unitFor(abs);
+    const p = fractionDigits(step / divisor);
+    if (p > 2) {
+      return Number.isInteger(v) ? d3Format(',')(v) : d3Format(',.2f')(v);
+    }
+    const sign = v < 0 ? '-' : '';
+    return sign + d3Format(`.${p}~f`)(abs / divisor) + suffix;
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Date formatting
 // ---------------------------------------------------------------------------

package/src/locale/index.ts

@@ -2,11 +2,20 @@
  * Locale module barrel export.
  */
 
-export type { DateGranularity } from './format';
+export type { DateGranularity, FieldFormatContext, NumberFormatter } from './format';
 export {
   abbreviateNumber,
+  buildCompactStepFormatter,
   buildD3Formatter,
   buildTemporalFormatter,
+  computeFieldFormatContext,
+  defaultNumberFormatter,
+  formatCurrency,
   formatDate,
   formatNumber,
+  formatOrdinal,
+  formatPercent,
+  isYearContext,
+  isYearLikeValues,
+  resolveNumberFormatter,
 } from './format';

package/src/responsive/breakpoints.ts

@@ -59,8 +59,13 @@ export function getHeightClass(height: number): HeightClass {
 /** 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';
+/**
+ * Legend position at a given breakpoint. `'top-left'` is a map-only overlay
+ * position: the legend floats inside the map area's top-left corner (with its
+ * own backdrop) instead of reserving a block of figure height. Charts treat
+ * it as the default position.
+ */
+export type LegendPosition = 'top' | 'top-left' | 'right' | 'bottom' | 'bottom-right' | 'inline';
 
 /** Annotation position strategy. */
 export type AnnotationPosition = 'inline' | 'tooltip-only';

package/src/responsive/index.ts

@@ -39,11 +39,13 @@ export {
   MAX_LEFT_LABEL_FRACTION_DEFAULT,
   MAX_LEFT_LABEL_FRACTION_MEDIUM,
   MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  maxRotatedLabelWidth,
   NARROW_VIEWPORT_MAX,
   TICK_LABEL_OFFSET,
   TICK_LINE_HEIGHT_FACTOR,
   TOP_PAD_EXTRA_NARROW,
   TOP_PAD_NARROW_MAX,
+  truncateRotatedLabel,
   X_AXIS_BAND_HEIGHT,
   X_AXIS_ROTATED_EXTENT_CAP,
   X_AXIS_TITLE_BAND,

package/src/responsive/metrics.ts

@@ -174,10 +174,13 @@ export const X_AXIS_TITLE_BAND = 22;
 export const X_AXIS_TITLE_BAND_ROTATED = 20;
 
 /**
- * Ceiling on the vertical extent reserved for rotated x tick labels. Labels
- * whose rotated projection exceeds this clip at the reservation edge, so the
- * angle ladder (engine layout/axes/rotation) avoids -90° for labels longer
- * than this.
+ * Ceiling on the vertical extent reserved for rotated x tick labels. The angle
+ * ladder (engine layout/axes/rotation) avoids -90° for labels longer than this.
+ *
+ * The cap bounds the RESERVATION, so a label whose rotated projection exceeds it
+ * must be truncated to fit — see `truncateRotatedLabel`. Reserving a capped band
+ * while drawing the full string is what let long ticks spill past the axis and
+ * collide with the source line.
  */
 export const X_AXIS_ROTATED_EXTENT_CAP = 120;
 
@@ -189,6 +192,15 @@ export const X_AXIS_ROTATED_EXTENT_CAP = 120;
  */
 export const TICK_LINE_HEIGHT_FACTOR = 1.2;
 
+/**
+ * Gap between the axis line and the top of the rotated label band. Mirrors the
+ * tick-mark-to-label offset used for flat labels; keeps the reservation matched
+ * to the drawn footprint across Blink and WebKit, whose rotated-glyph metrics
+ * differ by a couple of pixels. Shared by the extent reservation and the
+ * truncation budget so they stay in lockstep.
+ */
+const AXIS_TO_LABEL_GAP = 3;
+
 export interface XAxisExtentInput {
   labels: string[];
   tickAngle?: number;
@@ -216,11 +228,6 @@ export function computeXAxisExtentFromLabels(input: XAxisExtentInput): number {
     // unless the text is fully vertical). Measuring only the sin term
     // under-reserved space, letting rotated ticks spill into the source line.
     const lineHeight = input.tickFontSize * TICK_LINE_HEIGHT_FACTOR;
-    // Small gap between the axis line and the top of the rotated label band.
-    // Mirrors the tick-mark-to-label offset used for flat labels; keeps the
-    // reservation matched to the drawn footprint across Blink and WebKit,
-    // whose rotated-glyph metrics differ by a couple of pixels.
-    const AXIS_TO_LABEL_GAP = 3;
     const rotatedHeight = Math.min(
       maxLabelWidth * Math.sin(angleRad) + lineHeight * Math.cos(angleRad) + AXIS_TO_LABEL_GAP,
       X_AXIS_ROTATED_EXTENT_CAP,
@@ -228,5 +235,65 @@ export function computeXAxisExtentFromLabels(input: XAxisExtentInput): number {
     return input.hasTitle ? rotatedHeight + X_AXIS_TITLE_BAND_ROTATED : rotatedHeight;
   }
 
-  return input.hasTitle ? baseHeight + X_AXIS_TITLE_BAND : baseHeight;
+  const tickExtent = 4 + input.tickFontSize + Math.max(11, Math.ceil(input.tickFontSize * 0.7));
+  const flatHeight = Math.max(baseHeight, tickExtent);
+  return input.hasTitle ? flatHeight + X_AXIS_TITLE_BAND : flatHeight;
+}
+
+/**
+ * The widest a rotated tick label may be before its vertical projection exceeds
+ * `X_AXIS_ROTATED_EXTENT_CAP`.
+ *
+ * Inverts the rotated-extent formula in `computeXAxisExtentFromLabels`:
+ *
+ *   extent = width*sin(θ) + lineHeight*cos(θ) + gap
+ *   width  = (cap - lineHeight*cos(θ) - gap) / sin(θ)
+ *
+ * Deriving it from the same terms (rather than hardcoding a second number) keeps
+ * the truncation budget and the space reservation locked together — if one
+ * changes, the other follows.
+ */
+export function maxRotatedLabelWidth(tickAngle: number, tickFontSize: number): number {
+  const angleRad = Math.abs(tickAngle) * (Math.PI / 180);
+  const sin = Math.sin(angleRad);
+  // A flat (or near-flat) label has no vertical projection to bound.
+  if (sin <= 0.001) return Number.POSITIVE_INFINITY;
+  const lineHeight = tickFontSize * TICK_LINE_HEIGHT_FACTOR;
+  const usable = X_AXIS_ROTATED_EXTENT_CAP - lineHeight * Math.cos(angleRad) - AXIS_TO_LABEL_GAP;
+  return Math.max(0, usable / sin);
+}
+
+/**
+ * Truncate a rotated tick label with an ellipsis so it fits inside the capped
+ * reservation. Returns the label unchanged when it already fits.
+ *
+ * Binary-search on character count against the real measure function, so it
+ * respects proportional fonts rather than assuming a fixed character width.
+ */
+export function truncateRotatedLabel(
+  label: string,
+  tickAngle: number,
+  tickFontSize: number,
+  tickFontWeight: number,
+  measure: (text: string, fontSize: number, fontWeight?: number) => number = estimateTextWidth,
+): string {
+  const budget = maxRotatedLabelWidth(tickAngle, tickFontSize);
+  if (!Number.isFinite(budget)) return label;
+  if (measure(label, tickFontSize, tickFontWeight) <= budget) return label;
+
+  const ELLIPSIS = '…';
+  // Nothing sensible fits: keep a single character + ellipsis rather than
+  // returning an empty tick.
+  let lo = 0;
+  let hi = label.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    const candidate = label.slice(0, mid) + ELLIPSIS;
+    if (measure(candidate, tickFontSize, tickFontWeight) <= budget) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return lo > 0 ? label.slice(0, lo).trimEnd() + ELLIPSIS : ELLIPSIS;
 }

package/src/schema/__tests__/generated-artifacts.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Smoke test that the generated LLM-facing artifacts cover every mark type.
+ *
+ * `scripts/generate-schema.mjs` and `scripts/generate-llms.mjs` emit the
+ * committed `packages/core/schema/*.json` and root `llms.txt`. This test
+ * asserts the two artifacts reference all 16 declared mark types, so adding a
+ * mark to MARK_TYPES without regenerating (or a generator regression that drops
+ * a mark) is caught here rather than shipping a schema/doc that silently omits
+ * it. CI's `check:generated` step guarantees the artifacts are fresh; this test
+ * guarantees they are complete.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { MARK_TYPES } from '../../types/spec';
+
+const coreRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const repoRoot = join(coreRoot, '..', '..');
+
+const chartSchema = readFileSync(join(coreRoot, 'schema', 'chart.schema.json'), 'utf8');
+const llmsTxt = readFileSync(join(repoRoot, 'llms.txt'), 'utf8');
+
+describe('generated artifacts cover every mark type', () => {
+  it('chart.schema.json references all 16 mark types', () => {
+    for (const mark of MARK_TYPES) {
+      expect(chartSchema, `chart.schema.json is missing mark "${mark}"`).toContain(`"${mark}"`);
+    }
+  });
+
+  it('llms.txt documents all 16 mark types in the grammar table', () => {
+    for (const mark of MARK_TYPES) {
+      // The generated mark table renders each mark as an inline-code cell.
+      expect(llmsTxt, `llms.txt is missing mark "${mark}"`).toContain(`\`${mark}\``);
+    }
+  });
+
+  it('MARK_TYPES has exactly 16 entries (the surface this plan targets)', () => {
+    expect(MARK_TYPES.size).toBe(16);
+  });
+});