@opendata-ai/openchart-core 7.2.4 → 7.4.0

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,
+};
+
+const AVG_CHAR_WIDTH_400 = 0.53;
 
-/** Narrower characters (i, l, t, etc.) bring the average down. */
+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,36 @@ 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;
 }
+
+/**
+ * Distance from the top of a text box to its alphabetic baseline.
+ *
+ * Layout stores text positions as top-edge coordinates; renderers convert to
+ * baseline coordinates with this ratio instead of `dominant-baseline: hanging`.
+ * WebKit computes the hanging baseline from different font metrics than Blink
+ * and never inherits dominant-baseline into tspans (WebKit bugs 139258 /
+ * 297455), which shifted whole titles above the container on iOS Safari.
+ * The 0.8 ratio matches Blink's rendered hanging position for typical UI
+ * fonts (hanging sits at ~0.8 x ascent, Inter ascent ~= 0.97em) and the
+ * Highcharts fontMetrics convention.
+ */
+export function textAscent(fontSize: number): number {
+  return fontSize * 0.8;
+}
+
+// ---------------------------------------------------------------------------
+// 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,53 @@ 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;
+    }
+    // Vertical extent of a rotated label = the projection of its bounding box
+    // onto the vertical axis: textWidth*|sin θ| (the tilted length) plus
+    // lineHeight*|cos θ| (the label's own height, which still contributes
+    // 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 * 1.2;
+    // 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,
+      120,
+    );
+    return input.hasTitle ? rotatedHeight + X_AXIS_TITLE_BAND_ROTATED : rotatedHeight;
+  }
+
+  return input.hasTitle ? baseHeight + X_AXIS_TITLE_BAND : baseHeight;
+}

package/src/styles/tokens.css

@@ -14,6 +14,10 @@
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 
+  /* Opt out of iOS text auto-inflation so measured widths match rendered text. */
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+
   --oc-font-family:
     "Inter Variable", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
   --oc-font-mono: "JetBrains Mono", "Fira Code", "Cascadia Code", monospace;

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,10 +59,12 @@ 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.
+    // renderer treats this as a literal top gap and then shifts the label down
+    // by textAscent() to land it on the alphabetic baseline (rather than
+    // dominant-baseline:hanging, which WebKit positions from different metrics),
+    // so the gap holds regardless of font size.
     xAxisLabelPadding: 4,
   },
   borderRadius: 2,

package/src/types/index.ts

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

package/src/types/layout.ts

@@ -109,6 +109,8 @@ export interface ResolvedChrome {
   byline?: ResolvedChromeElement;
   footer?: ResolvedChromeElement;
   brand?: ResolvedChromeElement;
+  /** Absolute y at which bottom-chrome relative offsets are anchored: area.y + area.height + x-axis extent. */
+  bottomAnchorY?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -176,6 +178,10 @@ export interface AxisLayout {
    * classic outside-the-area placement.
    */
   tickPosition?: 'inline' | 'gutter';
+  /** Extent in px beyond the chart-area edge occupied by tick labels + title. Engine-resolved from the final (post-thinning) tick set. */
+  extent?: number;
+  /** Absolute anchor for the axis title. Replaces renderer-side offset math. */
+  titlePosition?: { x: number; y: number; angle?: number };
 }
 
 // ---------------------------------------------------------------------------
@@ -546,6 +552,10 @@ export interface ResolvedLabel {
   background?: string;
   /** Whether to show the paint-order stroke halo. Default true. */
   halo?: boolean;
+  /** Engine-measured text-block bounds. Renderers should use this for background rects instead of re-estimating. */
+  bounds?: Rect;
+  /** Source index carried through from the LabelCandidate, if the caller set one. */
+  index?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -598,6 +608,8 @@ export interface ResolvedAnnotation {
     y: number;
     style: TextStyle;
   };
+  /** Full placed extent: label bounds unioned with subtitle bounds. Collision and placement source of truth. */
+  bounds?: Rect;
 }
 
 // ---------------------------------------------------------------------------
@@ -628,6 +640,16 @@ export interface BaseLegendLayout {
   labelStyle: TextStyle;
 }
 
+/** Engine-resolved absolute position for a single legend entry. */
+export interface LegendEntryPosition {
+  x: number;
+  y: number;
+  labelX: number;
+  labelY: number;
+  width: number;
+  row: number;
+}
+
 /** Categorical legend with discrete swatch entries. */
 export interface CategoricalLegendLayout extends BaseLegendLayout {
   /** Discriminant for legend type. Omitted means categorical (backwards compat). */
@@ -642,6 +664,10 @@ export interface CategoricalLegendLayout extends BaseLegendLayout {
   entryGap: number;
   /** Fill color for the rounded chip background behind the colored bar. */
   swatchChipFill: string;
+  /** Engine-resolved absolute positions, parallel to `entries`. */
+  entryPositions?: LegendEntryPosition[];
+  /** Row advance used to build entryPositions (single source of truth). */
+  rowHeight?: number;
 }
 
 /** A color stop in a gradient legend. */