@opendata-ai/openchart-core 7.2.4 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "7.2.4",
+  "version": "7.3.0",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/index.ts

@@ -60,6 +60,8 @@ export {
   COMPACT_WIDTH,
   computeChrome,
   estimateTextWidth,
+  heuristicMeasure,
+  resolveMeasurer,
   wrapText,
 } from './layout/index';
 
@@ -76,6 +78,7 @@ export type {
   LabelMode,
   LayoutStrategy,
   LegendPosition,
+  XAxisExtentInput,
 } from './responsive/index';
 export {
   AXIS_TITLE_GAP,
@@ -85,6 +88,7 @@ export {
   axisTitleOffset,
   BREAKPOINT_COMPACT_MAX,
   BREAKPOINT_MEDIUM_MAX,
+  computeXAxisExtentFromLabels,
   getAxisTitleOffset,
   getBreakpoint,
   getHeightClass,
@@ -104,6 +108,9 @@ export {
   TICK_LABEL_OFFSET,
   TOP_PAD_EXTRA_NARROW,
   TOP_PAD_NARROW_MAX,
+  X_AXIS_BAND_HEIGHT,
+  X_AXIS_TITLE_BAND,
+  X_AXIS_TITLE_BAND_ROTATED,
 } from './responsive/index';
 
 // ---------------------------------------------------------------------------
@@ -120,6 +127,7 @@ export {
   detectCollision,
   EXTENDED_OFFSET_STRATEGIES,
   OFFSET_STRATEGIES,
+  overlapArea,
   resolveCollisions,
 } from './labels/index';
 

package/src/labels/collision.ts

@@ -3,7 +3,6 @@
  *
  * Greedy algorithm: sort by priority, place in order, try offset
  * positions for conflicts, demote to tooltip-only if no position works.
- * Targeting ~60% of Infrographic quality for Phase 0.
  */
 
 import { estimateTextWidth } from '../layout/text-measure';
@@ -55,6 +54,13 @@ export function detectCollision(a: Rect, b: Rect): boolean {
   return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
 }
 
+/** Compute the area of intersection between two axis-aligned rectangles. Returns 0 if disjoint. */
+export function overlapArea(a: Rect, b: Rect): number {
+  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+  return w > 0 && h > 0 ? w * h : 0;
+}
+
 // ---------------------------------------------------------------------------
 // Offset strategies
 // ---------------------------------------------------------------------------

package/src/labels/index.ts

@@ -8,5 +8,6 @@ export {
   detectCollision,
   EXTENDED_OFFSET_STRATEGIES,
   OFFSET_STRATEGIES,
+  overlapArea,
   resolveCollisions,
 } from './collision';

package/src/layout/__tests__/text-measure.test.ts

@@ -7,8 +7,8 @@ describe('estimateTextWidth', () => {
   });
 
   it('scales linearly with text length', () => {
-    const w5 = estimateTextWidth('hello', 14);
-    const w10 = estimateTextWidth('helloworld', 14);
+    const w5 = estimateTextWidth('abcde', 14);
+    const w10 = estimateTextWidth('abcdeabcde', 14);
     expect(w10).toBeCloseTo(w5 * 2, 1);
   });
 
@@ -31,13 +31,12 @@ describe('estimateTextWidth', () => {
     expect(width).toBeLessThan(250);
   });
 
-  // Characterization test (refactor/v7-cohesion step 1):
-  // Pins the AVG_CHAR_WIDTH_RATIO = 0.57 constant introduced in commit e7b98f9.
-  // Any future tuning of the ratio changes layout-wide text wrapping decisions,
-  // so we freeze the exact numeric output of the canonical call.
+  // Pins the per-character width table output. Any change to the tables
+  // shifts layout-wide text wrapping decisions, so we freeze the exact value.
   it('estimateTextWidth("sample", 14, 400) returns the locked numeric value', () => {
-    // 6 chars * (14 * 0.57 * 1.0) = 6 * 7.98 = 47.88
-    expect(estimateTextWidth('sample', 14, 400)).toBeCloseTo(47.88, 5);
+    // Per-char lookup: s(0.5) + a(0.556) + m(0.833) + p(0.556) + l(0.222) + e(0.556) = 3.223
+    // 3.223 * 14 * 1.0 = 45.122
+    expect(estimateTextWidth('sample', 14, 400)).toBeCloseTo(45.122, 2);
   });
 });
 

package/src/layout/index.ts

@@ -11,5 +11,7 @@ export {
   estimateCharWidth,
   estimateTextHeight,
   estimateTextWidth,
+  heuristicMeasure,
+  resolveMeasurer,
 } from './text-measure';
 export { wrapText } from './text-wrap';

package/src/layout/text-measure.ts

@@ -1,20 +1,268 @@
 /**
- * Heuristic text measurement for environments without a DOM.
+ * 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.
+ * Uses per-character advance-width tables measured from Inter (the default
+ * chart font) for ~2-3% accuracy on Latin text at weights 400/700.
+ * Other fonts set via theme.fonts.family still get a better-than-flat-ratio
+ * approximation but no accuracy guarantee.
+ *
+ * Tables generated by scripts/generate-char-widths.mjs — regenerate, don't
+ * hand-edit.
  */
 
-/**
- * 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.57;
+import type { MeasureTextFn } from '../types/layout';
+
+// ---------------------------------------------------------------------------
+// Per-character advance widths for Inter, normalized to fontSize = 1.
+// Generated by scripts/generate-char-widths.mjs from Chromium canvas metrics.
+// ---------------------------------------------------------------------------
+
+const CHAR_WIDTHS_400: Record<string, number> = {
+  ' ': 0.278,
+  '!': 0.278,
+  '"': 0.355,
+  '#': 0.556,
+  $: 0.556,
+  '%': 0.889,
+  '&': 0.667,
+  "'": 0.191,
+  '(': 0.333,
+  ')': 0.333,
+  '*': 0.389,
+  '+': 0.584,
+  ',': 0.278,
+  '-': 0.333,
+  '.': 0.278,
+  '/': 0.278,
+  '0': 0.556,
+  '1': 0.556,
+  '2': 0.556,
+  '3': 0.556,
+  '4': 0.556,
+  '5': 0.556,
+  '6': 0.556,
+  '7': 0.556,
+  '8': 0.556,
+  '9': 0.556,
+  ':': 0.278,
+  ';': 0.278,
+  '<': 0.584,
+  '=': 0.584,
+  '>': 0.584,
+  '?': 0.556,
+  '@': 1.015,
+  A: 0.667,
+  B: 0.667,
+  C: 0.722,
+  D: 0.722,
+  E: 0.667,
+  F: 0.611,
+  G: 0.778,
+  H: 0.722,
+  I: 0.278,
+  J: 0.5,
+  K: 0.667,
+  L: 0.556,
+  M: 0.833,
+  N: 0.722,
+  O: 0.778,
+  P: 0.667,
+  Q: 0.778,
+  R: 0.722,
+  S: 0.667,
+  T: 0.611,
+  U: 0.722,
+  V: 0.667,
+  W: 0.944,
+  X: 0.667,
+  Y: 0.667,
+  Z: 0.611,
+  '[': 0.278,
+  '\\': 0.278,
+  ']': 0.278,
+  '^': 0.469,
+  _: 0.556,
+  '`': 0.333,
+  a: 0.556,
+  b: 0.556,
+  c: 0.5,
+  d: 0.556,
+  e: 0.556,
+  f: 0.278,
+  g: 0.556,
+  h: 0.556,
+  i: 0.222,
+  j: 0.222,
+  k: 0.5,
+  l: 0.222,
+  m: 0.833,
+  n: 0.556,
+  o: 0.556,
+  p: 0.556,
+  q: 0.556,
+  r: 0.333,
+  s: 0.5,
+  t: 0.278,
+  u: 0.556,
+  v: 0.5,
+  w: 0.722,
+  x: 0.5,
+  y: 0.5,
+  z: 0.5,
+  '{': 0.334,
+  '|': 0.26,
+  '}': 0.334,
+  '~': 0.584,
+  '₹': 0.52,
+  '₩': 1.022,
+  '¥': 0.556,
+  '￥': 1,
+  '€': 0.744,
+  '£': 0.556,
+  '¢': 0.556,
+  '§': 0.556,
+  '©': 0.737,
+  '®': 0.737,
+  '™': 1,
+  '°': 0.4,
+  '–': 0.556,
+  '—': 1,
+  '‘': 0.222,
+  '’': 0.222,
+  '“': 0.333,
+  '”': 0.333,
+  '…': 1,
+  '±': 0.549,
+  '×': 0.584,
+  '÷': 0.549,
+};
 
-/** Narrower characters (i, l, t, etc.) bring the average down. */
+const AVG_CHAR_WIDTH_400 = 0.53;
+
+const CHAR_WIDTHS_700: Record<string, number> = {
+  ' ': 0.278,
+  '!': 0.333,
+  '"': 0.474,
+  '#': 0.556,
+  $: 0.556,
+  '%': 0.889,
+  '&': 0.722,
+  "'": 0.238,
+  '(': 0.333,
+  ')': 0.333,
+  '*': 0.389,
+  '+': 0.584,
+  ',': 0.278,
+  '-': 0.333,
+  '.': 0.278,
+  '/': 0.278,
+  '0': 0.556,
+  '1': 0.556,
+  '2': 0.556,
+  '3': 0.556,
+  '4': 0.556,
+  '5': 0.556,
+  '6': 0.556,
+  '7': 0.556,
+  '8': 0.556,
+  '9': 0.556,
+  ':': 0.333,
+  ';': 0.333,
+  '<': 0.584,
+  '=': 0.584,
+  '>': 0.584,
+  '?': 0.611,
+  '@': 0.975,
+  A: 0.722,
+  B: 0.722,
+  C: 0.722,
+  D: 0.722,
+  E: 0.667,
+  F: 0.611,
+  G: 0.778,
+  H: 0.722,
+  I: 0.278,
+  J: 0.556,
+  K: 0.722,
+  L: 0.611,
+  M: 0.833,
+  N: 0.722,
+  O: 0.778,
+  P: 0.667,
+  Q: 0.778,
+  R: 0.722,
+  S: 0.667,
+  T: 0.611,
+  U: 0.722,
+  V: 0.667,
+  W: 0.944,
+  X: 0.667,
+  Y: 0.667,
+  Z: 0.611,
+  '[': 0.333,
+  '\\': 0.278,
+  ']': 0.333,
+  '^': 0.584,
+  _: 0.556,
+  '`': 0.333,
+  a: 0.556,
+  b: 0.611,
+  c: 0.556,
+  d: 0.611,
+  e: 0.556,
+  f: 0.333,
+  g: 0.611,
+  h: 0.611,
+  i: 0.278,
+  j: 0.278,
+  k: 0.556,
+  l: 0.278,
+  m: 0.889,
+  n: 0.611,
+  o: 0.611,
+  p: 0.611,
+  q: 0.611,
+  r: 0.389,
+  s: 0.556,
+  t: 0.333,
+  u: 0.611,
+  v: 0.556,
+  w: 0.778,
+  x: 0.556,
+  y: 0.556,
+  z: 0.5,
+  '{': 0.389,
+  '|': 0.28,
+  '}': 0.389,
+  '~': 0.584,
+  '₹': 0.553,
+  '₩': 1.024,
+  '¥': 0.556,
+  '￥': 1,
+  '€': 0.744,
+  '£': 0.556,
+  '¢': 0.556,
+  '§': 0.556,
+  '©': 0.737,
+  '®': 0.737,
+  '™': 1,
+  '°': 0.4,
+  '–': 0.556,
+  '—': 1,
+  '‘': 0.278,
+  '’': 0.278,
+  '“': 0.5,
+  '”': 0.5,
+  '…': 1,
+  '±': 0.549,
+  '×': 0.584,
+  '÷': 0.549,
+};
+
+const AVG_CHAR_WIDTH_700 = 0.554;
+
+// Weights < 650 scale the CHAR_WIDTHS_400 table; weights >= 650 scale
+// CHAR_WIDTHS_700. The factor is 1.0 at each table's native weight.
 const WEIGHT_ADJUSTMENT: Record<number, number> = {
   100: 0.9,
   200: 0.92,
@@ -22,48 +270,88 @@ const WEIGHT_ADJUSTMENT: Record<number, number> = {
   400: 1.0,
   500: 1.02,
   600: 1.05,
-  700: 1.08,
+  700: 1.0, // uses CHAR_WIDTHS_700 directly
   800: 1.1,
   900: 1.12,
 };
 
+function resolveTable(fontWeight: number): {
+  table: Record<string, number>;
+  avg: number;
+  scale: number;
+} {
+  if (fontWeight >= 650) {
+    return {
+      table: CHAR_WIDTHS_700,
+      avg: AVG_CHAR_WIDTH_700,
+      scale: WEIGHT_ADJUSTMENT[fontWeight] ?? 1.0,
+    };
+  }
+  return {
+    table: CHAR_WIDTHS_400,
+    avg: AVG_CHAR_WIDTH_400,
+    scale: WEIGHT_ADJUSTMENT[fontWeight] ?? 1.0,
+  };
+}
+
+function charWidthRatio(ch: string, table: Record<string, number>, avg: number): number {
+  const direct = table[ch];
+  if (direct !== undefined) return direct;
+  const code = ch.codePointAt(0) ?? 0;
+  // Combining marks (diacritics) have zero advance width
+  if ((code >= 0x0300 && code <= 0x036f) || (code >= 0x1ab0 && code <= 0x1aff)) return 0;
+  // CJK ideographs, kana, hangul, and fullwidth forms are full-em
+  if (
+    (code >= 0x1100 && code <= 0x11ff) ||
+    (code >= 0x2e80 && code <= 0x9fff) ||
+    (code >= 0xac00 && code <= 0xd7af) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xff00 && code <= 0xff60)
+  )
+    return 1.0;
+  return avg;
+}
+
 /**
  * Estimate the average character width for a given font size and weight.
  * Used by both text width estimation and word-wrap line counting.
  */
 export function estimateCharWidth(fontSize: number, fontWeight = 400): number {
-  const weightFactor = WEIGHT_ADJUSTMENT[fontWeight] ?? 1.0;
-  return fontSize * AVG_CHAR_WIDTH_RATIO * weightFactor;
+  const { avg, scale } = resolveTable(fontWeight);
+  return fontSize * avg * scale;
 }
 
 /**
  * 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.
+ * Uses per-character advance widths measured from Inter (the default chart
+ * font). Accurate to ~2-3% for Latin text at weights 400/700; other weights
+ * are interpolated from the nearest table.
  */
 export function estimateTextWidth(text: string, fontSize: number, fontWeight = 400): number {
-  const charWidth = estimateCharWidth(fontSize, fontWeight);
-  // For multiline text, measure the longest line
+  const { table, avg, scale } = resolveTable(fontWeight);
+
+  const measureLine = (line: string): number => {
+    let sum = 0;
+    for (const ch of line) {
+      sum += charWidthRatio(ch, table, avg);
+    }
+    return sum * fontSize * scale;
+  };
+
   if (text.includes('\n')) {
-    let maxLen = 0;
+    let maxWidth = 0;
     for (const line of text.split('\n')) {
-      if (line.length > maxLen) maxLen = line.length;
+      const w = measureLine(line);
+      if (w > maxWidth) maxWidth = w;
     }
-    return maxLen * charWidth;
+    return maxWidth;
   }
-  return text.length * charWidth;
+  return measureLine(text);
 }
 
 /**
  * Width reserved for the "tryOpenData.ai" brand watermark in the bottom-right corner.
- * Accounts for ~14 chars at font size 12 with mixed weights, plus a gap
- * so adjacent text doesn't crowd it. Used by chrome and legend layout to avoid
- * overlapping the brand.
  */
 export const BRAND_RESERVE_WIDTH = 130;
 
@@ -73,10 +361,6 @@ export const BRAND_FONT_SIZE = 12;
 /** Minimum chart width to render the brand watermark (px). */
 export const BRAND_MIN_WIDTH = 120;
 
-// ---------------------------------------------------------------------------
-// Responsive breakpoints
-// ---------------------------------------------------------------------------
-
 /**
  * Width threshold below which layout tightens spacing (legend gaps, chrome
  * padding, label gaps) to maximize data area on small screens.
@@ -85,11 +369,20 @@ export const COMPACT_WIDTH = 420;
 
 /**
  * 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;
 }
+
+// ---------------------------------------------------------------------------
+// Measurer resolver — bridges heuristic ↔ injected canvas measurer
+// ---------------------------------------------------------------------------
+
+export const heuristicMeasure: MeasureTextFn = (text, fontSize, fontWeight) => ({
+  width: estimateTextWidth(text, fontSize, fontWeight),
+  height: estimateTextHeight(fontSize),
+});
+
+export function resolveMeasurer(measureText?: MeasureTextFn): MeasureTextFn {
+  return measureText ?? heuristicMeasure;
+}

package/src/responsive/index.ts

@@ -21,12 +21,14 @@ export {
   HEIGHT_CRAMPED_MAX,
   HEIGHT_SHORT_MAX,
 } from './breakpoints';
+export type { XAxisExtentInput } from './metrics';
 export {
   AXIS_TITLE_GAP,
   AXIS_TITLE_OFFSET_COMPACT,
   AXIS_TITLE_OFFSET_DEFAULT,
   AXIS_TITLE_TRAILING_PAD,
   axisTitleOffset,
+  computeXAxisExtentFromLabels,
   getAxisTitleOffset,
   HPAD_COMPACT_FRACTION,
   HPAD_COMPACT_MIN,
@@ -41,4 +43,7 @@ export {
   TICK_LABEL_OFFSET,
   TOP_PAD_EXTRA_NARROW,
   TOP_PAD_NARROW_MAX,
+  X_AXIS_BAND_HEIGHT,
+  X_AXIS_TITLE_BAND,
+  X_AXIS_TITLE_BAND_ROTATED,
 } from './metrics';

package/src/responsive/metrics.ts

@@ -8,6 +8,7 @@
  * LayoutStrategy is semantic (what to show), this module is metric (how much space).
  */
 
+import { estimateTextWidth } from '../layout/text-measure';
 import { BREAKPOINT_COMPACT_MAX } from './breakpoints';
 
 // ---------------------------------------------------------------------------
@@ -153,3 +154,39 @@ export const MAX_LEFT_LABEL_FRACTION_MEDIUM = 0.55;
 
 /** Max fraction of container width reservable for left category labels (standard). */
 export const MAX_LEFT_LABEL_FRACTION_DEFAULT = 1;
+
+// ---------------------------------------------------------------------------
+// X-axis extent (height below chart area)
+// ---------------------------------------------------------------------------
+
+export const X_AXIS_BAND_HEIGHT = 26;
+export const X_AXIS_TITLE_BAND = 22;
+export const X_AXIS_TITLE_BAND_ROTATED = 20;
+
+export interface XAxisExtentInput {
+  labels: string[];
+  tickAngle?: number;
+  hasTitle: boolean;
+  tickFontSize: number;
+  tickFontWeight: number;
+  xAxisHeight?: number;
+  measure?: (text: string, fontSize: number, fontWeight: number) => number;
+}
+
+export function computeXAxisExtentFromLabels(input: XAxisExtentInput): number {
+  const measure = input.measure ?? estimateTextWidth;
+  const baseHeight = input.xAxisHeight ?? X_AXIS_BAND_HEIGHT;
+
+  if (input.tickAngle && Math.abs(input.tickAngle) > 10) {
+    const angleRad = Math.abs(input.tickAngle) * (Math.PI / 180);
+    let maxLabelWidth = 40;
+    for (const label of input.labels) {
+      const w = measure(label, input.tickFontSize, input.tickFontWeight);
+      if (w > maxLabelWidth) maxLabelWidth = w;
+    }
+    const rotatedHeight = Math.min(maxLabelWidth * Math.sin(angleRad) + 6, 120);
+    return input.hasTitle ? rotatedHeight + X_AXIS_TITLE_BAND_ROTATED : rotatedHeight;
+  }
+
+  return input.hasTitle ? baseHeight + X_AXIS_TITLE_BAND : baseHeight;
+}

package/src/theme/defaults.ts

@@ -10,6 +10,7 @@
  */
 
 import { CATEGORICAL_PALETTE, DIVERGING_PALETTES, SEQUENTIAL_PALETTES } from '../colors/palettes';
+import { X_AXIS_BAND_HEIGHT } from '../responsive/metrics';
 import type { Theme } from '../types/theme';
 
 /**
@@ -58,7 +59,7 @@ export const DEFAULT_THEME: Theme = {
     chromeToChart: 8,
     chartToFooter: 8,
     axisMargin: 6,
-    xAxisHeight: 26,
+    xAxisHeight: X_AXIS_BAND_HEIGHT,
     // Gap (px) between the x-axis line and the TOP of the tick labels. The
     // renderer anchors x-tick labels at their top edge (hanging baseline), so
     // this is a literal top gap that holds regardless of font size.

package/src/types/index.ts

@@ -54,6 +54,7 @@ export type {
   HeatmapTableCell,
   ImageTableCell,
   LegendEntry,
+  LegendEntryPosition,
   LegendLayout,
   LineMark,
   Margins,