@beyondwork/docx-react-component 1.0.53 → 1.0.55

package/src/ui-tailwind/chart/render/font-metrics.ts

@@ -0,0 +1,298 @@
+/**
+ * Chart-side text measurement helper (Stage 3B).
+ *
+ * Exposes `measureText(text, txPr, theme): TextMetrics` with two backends:
+ *   - **Canvas** (`CanvasRenderingContext2D.measureText`) when
+ *     `globalThis.document` is defined (real browser / jsdom with canvas).
+ *   - **Empirical** glyph-width lookup table when running in SSR or Node
+ *     test environments without a real DOM.
+ *
+ * Results are LRU-cached by (text × fontFamily × sizeHalfPoints × bold ×
+ * italic) so repeated calls in a single render cycle are effectively free.
+ * The cache is intentionally module-level (shared across renders) because
+ * chart font choices are low-cardinality.
+ *
+ * The canvas backend is NOT created on module import — it's lazy-created on
+ * the first measurement call so the module can be imported in SSR without
+ * side-effects.
+ */
+
+import type { TextProperties } from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ChartTextMetrics {
+  width: number;
+  /** Cap-height approximation — useful for vertical centering. */
+  ascent: number;
+  descent: number;
+  lineHeight: number;
+}
+
+/**
+ * Measure `text` rendered with `txPr` (chart text properties) in the
+ * given `theme`. Falls back to the empirical backend when a canvas context
+ * is not available (SSR, Node tests).
+ *
+ * `theme` is accepted for future font-fallback resolution; currently only
+ * `txPr.fontFamily` / `txPr.fontSizePt` / `txPr.bold` / `txPr.italic` are
+ * used (theme-linked font schemes deferred to Stage 6).
+ */
+export function measureText(
+  text: string,
+  txPr: TextProperties | undefined,
+  _theme: ResolvedTheme | undefined,
+): ChartTextMetrics {
+  const family = txPr?.fontFamily ?? DEFAULT_FONT_FAMILY;
+  const sizePt = txPr?.fontSizePt ?? DEFAULT_FONT_SIZE_PT;
+  const bold = txPr?.bold ?? false;
+  const italic = txPr?.italic ?? false;
+
+  const key = cacheKey(text, family, sizePt, bold, italic);
+  const cached = lruGet(key);
+  if (cached) return cached;
+
+  const result = canvasContext
+    ? measureViaCanvas(text, family, sizePt, bold, italic)
+    : measureEmpirical(text, family, sizePt, bold, italic);
+
+  lruSet(key, result);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_FONT_FAMILY = "Calibri, Carlito, 'Segoe UI', 'Liberation Sans', Arial, sans-serif";
+const DEFAULT_FONT_SIZE_PT = 10;
+/** pt → px at 96 DPI: 1pt = 96/72 px. */
+const PT_TO_PX = 96 / 72;
+const LINE_HEIGHT_RATIO = 1.2;
+
+// ---------------------------------------------------------------------------
+// Canvas backend (lazy init)
+// ---------------------------------------------------------------------------
+
+let canvasContext: CanvasRenderingContext2D | null = null;
+
+function getCanvasContext(): CanvasRenderingContext2D | null {
+  if (canvasContext !== null) return canvasContext;
+  if (typeof globalThis.document === "undefined") return null;
+  try {
+    const canvas = globalThis.document.createElement("canvas");
+    canvasContext = canvas.getContext("2d");
+  } catch {
+    canvasContext = null;
+  }
+  return canvasContext;
+}
+
+// Initialise lazily on first call (not at import time).
+function ensureCanvas(): void {
+  if (canvasContext === null) getCanvasContext();
+}
+
+function measureViaCanvas(
+  text: string,
+  family: string,
+  sizePt: number,
+  bold: boolean,
+  italic: boolean,
+): ChartTextMetrics {
+  const ctx = getCanvasContext();
+  if (!ctx) return measureEmpirical(text, family, sizePt, bold, italic);
+
+  const sizePx = sizePt * PT_TO_PX;
+  const weight = bold ? "bold" : "normal";
+  const style = italic ? "italic" : "normal";
+  ctx.font = `${style} ${weight} ${sizePx}px ${family}`;
+  const m = ctx.measureText(text);
+
+  const ascent = m.actualBoundingBoxAscent ?? sizePx * 0.75;
+  const descent = m.actualBoundingBoxDescent ?? sizePx * 0.2;
+  return {
+    width: m.width,
+    ascent,
+    descent,
+    lineHeight: sizePx * LINE_HEIGHT_RATIO,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Empirical backend — glyph-width tables
+// ---------------------------------------------------------------------------
+
+/**
+ * Average character width in em units per font-family (normalised to 1 em).
+ * Values derived from Calibri / Arial measurements at regular weight.
+ * Bold adds ~12%; italic is nearly identical in advance width.
+ */
+const GLYPH_AVG_EM: Record<string, number> = {
+  calibri: 0.44,
+  carlito: 0.44,
+  arial: 0.50,
+  helvetica: 0.50,
+  "segoe ui": 0.48,
+  "liberation sans": 0.50,
+  times: 0.46,
+  "times new roman": 0.46,
+};
+
+/** Per-glyph width table (em units, Calibri-like proportions). */
+const GLYPH_EM: Readonly<Record<string, number>> = {
+  // Digits (monospace-like in Calibri)
+  "0": 0.50, "1": 0.44, "2": 0.50, "3": 0.50, "4": 0.50,
+  "5": 0.50, "6": 0.50, "7": 0.46, "8": 0.50, "9": 0.50,
+  // Common punctuation / symbols
+  " ": 0.26, ".": 0.22, ",": 0.22, "-": 0.30, "+": 0.52,
+  "%": 0.68, "$": 0.50, "€": 0.56, "£": 0.48, "/": 0.30,
+  ":": 0.22, ";": 0.22, "(": 0.28, ")": 0.28, "[": 0.26, "]": 0.26,
+  // Upper-case
+  A: 0.60, B: 0.58, C: 0.58, D: 0.64, E: 0.52, F: 0.50,
+  G: 0.64, H: 0.64, I: 0.22, J: 0.40, K: 0.58, L: 0.50,
+  M: 0.72, N: 0.64, O: 0.68, P: 0.56, Q: 0.68, R: 0.60,
+  S: 0.52, T: 0.54, U: 0.64, V: 0.60, W: 0.82, X: 0.56,
+  Y: 0.56, Z: 0.54,
+  // Lower-case
+  a: 0.46, b: 0.50, c: 0.42, d: 0.50, e: 0.46, f: 0.28,
+  g: 0.50, h: 0.50, i: 0.22, j: 0.22, k: 0.48, l: 0.22,
+  m: 0.74, n: 0.50, o: 0.48, p: 0.50, q: 0.50, r: 0.30,
+  s: 0.40, t: 0.34, u: 0.50, v: 0.46, w: 0.64, x: 0.46,
+  y: 0.46, z: 0.40,
+};
+
+function avgGlyphEm(family: string): number {
+  const key = family.toLowerCase().split(",")[0]!.trim().replace(/^['"]|['"]$/g, "");
+  return GLYPH_AVG_EM[key] ?? 0.50;
+}
+
+function measureEmpirical(
+  text: string,
+  family: string,
+  sizePt: number,
+  bold: boolean,
+  _italic: boolean,
+): ChartTextMetrics {
+  const sizePx = sizePt * PT_TO_PX;
+  const boldFactor = bold ? 1.12 : 1.0;
+  const fallbackEm = avgGlyphEm(family);
+
+  let widthEm = 0;
+  for (const ch of text) {
+    widthEm += GLYPH_EM[ch] ?? fallbackEm;
+  }
+
+  const width = widthEm * sizePx * boldFactor;
+  return {
+    width,
+    ascent: sizePx * 0.75,
+    descent: sizePx * 0.2,
+    lineHeight: sizePx * LINE_HEIGHT_RATIO,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// LRU cache (simple doubly-linked-list, capacity 256)
+// ---------------------------------------------------------------------------
+
+const LRU_CAPACITY = 256;
+
+interface LRUNode {
+  key: string;
+  value: ChartTextMetrics;
+  prev: LRUNode | null;
+  next: LRUNode | null;
+}
+
+const lruMap = new Map<string, LRUNode>();
+let lruHead: LRUNode | null = null; // most-recently used
+let lruTail: LRUNode | null = null; // least-recently used
+
+function cacheKey(
+  text: string,
+  family: string,
+  sizePt: number,
+  bold: boolean,
+  italic: boolean,
+): string {
+  // Half-points to avoid float key drift (1.5pt → "3").
+  const halfPts = Math.round(sizePt * 2);
+  return `${text}\x00${family}\x00${halfPts}\x00${bold ? 1 : 0}\x00${italic ? 1 : 0}`;
+}
+
+function lruGet(key: string): ChartTextMetrics | undefined {
+  const node = lruMap.get(key);
+  if (!node) return undefined;
+  moveToHead(node);
+  return node.value;
+}
+
+function lruSet(key: string, value: ChartTextMetrics): void {
+  const existing = lruMap.get(key);
+  if (existing) {
+    existing.value = value;
+    moveToHead(existing);
+    return;
+  }
+  const node: LRUNode = { key, value, prev: null, next: null };
+  lruMap.set(key, node);
+  insertHead(node);
+  if (lruMap.size > LRU_CAPACITY) evictTail();
+}
+
+function insertHead(node: LRUNode): void {
+  node.next = lruHead;
+  node.prev = null;
+  if (lruHead) lruHead.prev = node;
+  lruHead = node;
+  if (!lruTail) lruTail = node;
+}
+
+function moveToHead(node: LRUNode): void {
+  if (node === lruHead) return;
+  if (node.prev) node.prev.next = node.next;
+  if (node.next) node.next.prev = node.prev;
+  if (node === lruTail) lruTail = node.prev;
+  node.prev = null;
+  node.next = lruHead;
+  if (lruHead) lruHead.prev = node;
+  lruHead = node;
+}
+
+function evictTail(): void {
+  if (!lruTail) return;
+  lruMap.delete(lruTail.key);
+  if (lruTail.prev) lruTail.prev.next = null;
+  lruTail = lruTail.prev;
+  if (!lruTail) lruHead = null;
+}
+
+/**
+ * Flush the module-level LRU cache. Called by tests to ensure isolation
+ * between test cases that change backend availability.
+ */
+export function _flushMetricsCache(): void {
+  lruMap.clear();
+  lruHead = null;
+  lruTail = null;
+}
+
+/**
+ * Override the canvas context for testing. Pass `null` to force the
+ * empirical backend; pass a mock `CanvasRenderingContext2D` to exercise
+ * the canvas path without a real DOM.
+ */
+export function _setCanvasContextForTesting(
+  ctx: CanvasRenderingContext2D | null,
+): void {
+  canvasContext = ctx;
+}
+
+// Eagerly try to acquire the canvas context if a document is already
+// available (e.g. jsdom in test environments that mount a DOM). A failure
+// here is fine — the empirical backend kicks in.
+ensureCanvas();

package/src/ui-tailwind/chart/render/gridlines.ts

@@ -0,0 +1,228 @@
+/**
+ * Gridline generator — major / minor lines for cartesian chart axes (Stage 3C).
+ *
+ * Gridlines visualize the tick lattice inside the plot area. Major lines
+ * sit at every major tick; minor lines sit at each intermediate minor
+ * tick. Word's default appearance:
+ *
+ *   - Color: theme `tx1` with `lumMod 15000 + lumOff 85000` (≈ 15% grey on
+ *     a white background). Renders as `#D9D9D9` on the default Office theme.
+ *   - Stroke width: 0.75 pt.
+ *   - No dash (solid).
+ *
+ * The generator emits pure geometric line descriptors (x1, y1, x2, y2)
+ * so renderers can compose them via `svgLine` from `svg-primitives.ts`.
+ * Gridline **rendering** — turning the descriptors into SVG elements —
+ * is the renderer's responsibility; this module is pure math.
+ *
+ * Axis orientation rules (for value axes):
+ *   - Y-axis (left side of plot): horizontal gridlines at each y tick
+ *     position, spanning the full plot width.
+ *   - X-axis (bottom of plot): vertical gridlines at each x tick
+ *     position, spanning the full plot height.
+ *
+ * `crossBetween` (B5 fix) applies to *category* axes on bar/column charts
+ * only. When `"between"` (bar default), gridlines fall between categories
+ * (at category edges), not at category centers. When `"midCat"` (line
+ * default), gridlines align with category centers. For value axes this
+ * setting has no effect.
+ */
+
+import type { Rect } from "../layout/plot-area.ts";
+import type { TickResult } from "../layout/axis-layout.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type GridlineAxis = "x" | "y";
+
+export interface GridlineSegment {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  major: boolean;
+}
+
+export interface GridlineInput {
+  /** "x" = vertical lines at x-tick positions; "y" = horizontal at y-tick. */
+  axis: GridlineAxis;
+  plotRect: Rect;
+  /** Major + minor tick positions (from generateValueTicks / etc.). */
+  ticks: TickResult;
+  /** Data-range bounds that the plot mapping uses. */
+  min: number;
+  max: number;
+  /**
+   * Reverse flag from `ValueAxis.reverse` (`c:scaling/orientation=maxMin`).
+   * When true, the max end sits at the low-coordinate side and the
+   * mapping flips.
+   */
+  reverse?: boolean;
+}
+
+export interface CategoryGridlineInput {
+  plotRect: Rect;
+  /** Number of categories (bar/line/area x-axis slot count). */
+  categoryCount: number;
+  /**
+   * `c:crossBetween` from the value axis that crosses this category axis.
+   * `"between"` → lines at category edges (bar/column convention).
+   * `"midCat"` → lines at category centers (line/area convention).
+   * Undefined defaults to `"midCat"` per Word's observed behavior.
+   */
+  crossBetween?: "between" | "midCat";
+  /** Optional skip factor to match tick-mark-skip on dense axes. */
+  tickMarkSkip?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Value-axis gridlines
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate major + minor gridline segments for a value or date axis.
+ * Output order: majors first (ascending tick position), then minors.
+ */
+export function generateValueGridlines(input: GridlineInput): GridlineSegment[] {
+  const out: GridlineSegment[] = [];
+  const span = input.max - input.min;
+  if (span === 0 || !Number.isFinite(span)) return out;
+
+  const mapPosition = makeMapPosition(input);
+  for (const pos of input.ticks.major) {
+    out.push(buildSegment(mapPosition(pos), input.axis, input.plotRect, true));
+  }
+  for (const pos of input.ticks.minor) {
+    out.push(buildSegment(mapPosition(pos), input.axis, input.plotRect, false));
+  }
+  return out;
+}
+
+/**
+ * Build a single gridline descriptor at the given coordinate.
+ *   - x-axis: vertical line, spans full plot height at this x-coord.
+ *   - y-axis: horizontal line, spans full plot width at this y-coord.
+ */
+function buildSegment(
+  coord: number,
+  axis: GridlineAxis,
+  plotRect: Rect,
+  major: boolean,
+): GridlineSegment {
+  if (axis === "x") {
+    return {
+      x1: coord,
+      y1: plotRect.y,
+      x2: coord,
+      y2: plotRect.y + plotRect.h,
+      major,
+    };
+  }
+  return {
+    x1: plotRect.x,
+    y1: coord,
+    x2: plotRect.x + plotRect.w,
+    y2: coord,
+    major,
+  };
+}
+
+/**
+ * Build a value→plot-coordinate mapper for the given axis. `reverse`
+ * flips the mapping so `max` sits at the low-coordinate side.
+ *
+ * For y-axis (axis='y'), pixel Y grows downward but data typically
+ * grows upward, so the default mapping inverts: `min` at `y + h`,
+ * `max` at `y`. `reverse=true` flips that back.
+ */
+function makeMapPosition(input: GridlineInput): (value: number) => number {
+  const { axis, plotRect, min, max, reverse } = input;
+  const span = max - min;
+
+  if (axis === "x") {
+    if (reverse) {
+      return (v) => plotRect.x + ((max - v) / span) * plotRect.w;
+    }
+    return (v) => plotRect.x + ((v - min) / span) * plotRect.w;
+  }
+  // y
+  if (reverse) {
+    return (v) => plotRect.y + ((v - min) / span) * plotRect.h;
+  }
+  return (v) => plotRect.y + plotRect.h - ((v - min) / span) * plotRect.h;
+}
+
+// ---------------------------------------------------------------------------
+// Category-axis gridlines (B5 — crossBetween honored)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate gridlines for a category axis. Category axes live under
+ * bar/column/line/area charts; `crossBetween` decides whether lines
+ * fall between categories (at slot edges) or at slot centers.
+ *
+ * - `"between"` (bar default): N+1 edge lines at slot boundaries.
+ * - `"midCat"` (line default): N center lines at slot mid-points.
+ *
+ * `tickMarkSkip` (Word's `c:tickMarkSkip`) thins out dense axes by
+ * emitting every Nth line. Defaults to 1 (all lines).
+ */
+export function generateCategoryGridlines(
+  input: CategoryGridlineInput,
+): GridlineSegment[] {
+  const { plotRect, categoryCount } = input;
+  if (categoryCount <= 0) return [];
+  const mode = input.crossBetween ?? "midCat";
+  const skip = Math.max(1, Math.floor(input.tickMarkSkip ?? 1));
+  const out: GridlineSegment[] = [];
+  const slotWidth = plotRect.w / categoryCount;
+
+  if (mode === "between") {
+    // Edges at 0, 1, 2, …, categoryCount → N+1 positions.
+    for (let i = 0; i <= categoryCount; i += skip) {
+      const x = plotRect.x + i * slotWidth;
+      out.push({
+        x1: x,
+        y1: plotRect.y,
+        x2: x,
+        y2: plotRect.y + plotRect.h,
+        major: true,
+      });
+    }
+    return out;
+  }
+  // midCat: centers at 0.5, 1.5, …
+  for (let i = 0; i < categoryCount; i += skip) {
+    const x = plotRect.x + (i + 0.5) * slotWidth;
+    out.push({
+      x1: x,
+      y1: plotRect.y,
+      x2: x,
+      y2: plotRect.y + plotRect.h,
+      major: true,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Default appearance helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Word-default gridline color (theme `tx1` with `lumMod 15000 +
+ * lumOff 85000` on a black `tx1`, which evaluates to `#D9D9D9`). Kept
+ * as a helper so renderers can ask for the default or substitute a
+ * theme-resolved alternative.
+ */
+export const DEFAULT_MAJOR_GRIDLINE_COLOR = "#D9D9D9";
+
+/**
+ * Minor gridline color is lighter than major. Word renders minor lines
+ * at `tx1 + lumMod 5000 + lumOff 95000` which resolves to `#F2F2F2`.
+ */
+export const DEFAULT_MINOR_GRIDLINE_COLOR = "#F2F2F2";
+
+export const DEFAULT_GRIDLINE_STROKE_WIDTH_PT = 0.75;