@beyondwork/docx-react-component 1.0.50 → 1.0.52

package/src/ui-tailwind/chart/layout/plot-area.ts

@@ -0,0 +1,344 @@
+/**
+ * Plot-area layout: partition the canvas into title / legend / axis /
+ * plot rectangles (Stage 3A, pure math).
+ *
+ * Call shape:
+ *
+ *   layoutPlotArea({ w, h }, model, theme) → PlotAreaLayout
+ *
+ * Algorithm (Word's observed order):
+ *   1. Reserve title band at top (if `model.title` present and not overlaid).
+ *   2. Reserve legend band on the declared side (b/t/l/r/tr).
+ *   3. Reserve Y-axis band on the left (and right if secondary axis).
+ *   4. Reserve X-axis band on the bottom.
+ *   5. Remaining rectangle is the plot area.
+ *
+ * **Text measurement is a fixed-stub at Slice 3A.** `measureTextWidth`
+ * and `measureTextHeight` use a deterministic avg-glyph / line-height
+ * approximation so the layout math is unit-testable without a browser.
+ * Slice 3B swaps in the real `measureText(text, txPr, theme)` helper
+ * that calls `ctx.measureText` (browser) or an empirical LRU (SSR) —
+ * the stub keeps the public API stable so Slice 3B is a pure
+ * implementation swap.
+ */
+
+import type { ChartModel } from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import {
+  generateCategoryTicks,
+  generateValueTicks,
+  type TickResult,
+} from "./axis-layout.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface PlotAreaLayout {
+  plotRect: Rect;
+  titleRect?: Rect;
+  legendRect?: Rect;
+  xAxisRect?: Rect;
+  yAxisRect?: Rect;
+  secondaryYAxisRect?: Rect;
+}
+
+export interface CanvasRect {
+  w: number;
+  h: number;
+}
+
+/**
+ * Partition the canvas into labelled sub-rectangles. The returned
+ * `plotRect` is the rectangle the chart-type renderer draws into.
+ *
+ * The current implementation uses the fixed-stub text measurement
+ * (`GLYPH_WIDTH_PX` × font size, `LINE_HEIGHT_RATIO` × font size). Slice
+ * 3B replaces those constants with a call-through to the real
+ * font-metrics helper.
+ */
+export function layoutPlotArea(
+  canvas: CanvasRect,
+  model: ChartModel,
+  theme: ResolvedTheme | undefined,
+): PlotAreaLayout {
+  void theme; // consumed by Slice 3B's real font-metrics wrapper.
+
+  let top = 0;
+  let bottom = canvas.h;
+  let left = 0;
+  let right = canvas.w;
+
+  const out: PlotAreaLayout = {
+    plotRect: { x: 0, y: 0, w: canvas.w, h: canvas.h },
+  };
+
+  // 1. Title band (top).
+  if (model.kind !== "unsupported" && model.title && !model.title.overlay) {
+    const titleHeight = measureTitleHeight(model.title.text ?? "");
+    out.titleRect = { x: 0, y: 0, w: canvas.w, h: titleHeight };
+    top += titleHeight + BAND_GAP_PX;
+  }
+
+  // 2. Legend band — on the side indicated by `legend.position`.
+  if (model.kind !== "unsupported" && model.legend && !model.legend.overlay) {
+    const entryCount = countLegendEntries(model);
+    const { w: legendW, h: legendH } = measureLegendBox(entryCount);
+    switch (model.legend.position) {
+      case "t":
+        out.legendRect = { x: 0, y: top, w: canvas.w, h: legendH };
+        top += legendH + BAND_GAP_PX;
+        break;
+      case "b":
+        out.legendRect = {
+          x: 0,
+          y: bottom - legendH,
+          w: canvas.w,
+          h: legendH,
+        };
+        bottom -= legendH + BAND_GAP_PX;
+        break;
+      case "l":
+        out.legendRect = { x: left, y: top, w: legendW, h: bottom - top };
+        left += legendW + BAND_GAP_PX;
+        break;
+      case "r":
+      case "tr":
+      default:
+        out.legendRect = {
+          x: right - legendW,
+          y: top,
+          w: legendW,
+          h: bottom - top,
+        };
+        right -= legendW + BAND_GAP_PX;
+        break;
+    }
+  }
+
+  // 3. Axis bands. Only cartesian families (bar/line/area/scatter/bubble/
+  // combo) reserve axis space; pie/doughnut/unsupported skip this entirely.
+  const axes = pickAxes(model);
+  if (axes) {
+    // Y-axis on the left: width = max(tick label width) + axis-title
+    // rotated height.
+    const yTickLabels = axisTickLabels(axes.y);
+    const yWidth =
+      maxLabelWidth(yTickLabels) + (axes.yTitle ? AXIS_TITLE_BAND_PX : 0);
+    out.yAxisRect = { x: left, y: top, w: yWidth, h: bottom - top };
+    left += yWidth + BAND_GAP_PX;
+
+    // Secondary Y-axis on the right.
+    if (axes.secondaryY) {
+      const y2TickLabels = axisTickLabels(axes.secondaryY);
+      const y2Width =
+        maxLabelWidth(y2TickLabels) + (axes.secondaryYTitle ? AXIS_TITLE_BAND_PX : 0);
+      out.secondaryYAxisRect = {
+        x: right - y2Width,
+        y: top,
+        w: y2Width,
+        h: bottom - top,
+      };
+      right -= y2Width + BAND_GAP_PX;
+    }
+
+    // X-axis on the bottom: height = label height + axis-title band.
+    const xLabelHeight = X_AXIS_LABEL_HEIGHT_PX;
+    const xHeight = xLabelHeight + (axes.xTitle ? AXIS_TITLE_BAND_PX : 0);
+    out.xAxisRect = {
+      x: left,
+      y: bottom - xHeight,
+      w: right - left,
+      h: xHeight,
+    };
+    bottom -= xHeight + BAND_GAP_PX;
+  }
+
+  out.plotRect = {
+    x: left,
+    y: top,
+    w: Math.max(0, right - left),
+    h: Math.max(0, bottom - top),
+  };
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Text measurement — fixed stub (Slice 3B replaces with real metrics)
+// ---------------------------------------------------------------------------
+
+/**
+ * Approximate glyph width in pixels at font size 1. The real value
+ * depends on font + character; Calibri averages ~0.44 em for narrow
+ * body text, but chart labels tend to be digits which are monospace-
+ * like. 0.55 em is a conservative average that matches Word's default
+ * axis-label font (Calibri 10pt ≈ 13.3px) well enough for layout
+ * reservation. Replaced in Slice 3B.
+ */
+const GLYPH_WIDTH_EM = 0.55;
+
+const LINE_HEIGHT_RATIO = 1.2;
+const BAND_GAP_PX = 4;
+const AXIS_TITLE_BAND_PX = 14;
+const X_AXIS_LABEL_HEIGHT_PX = 14;
+const DEFAULT_AXIS_FONT_PX = 10;
+const DEFAULT_TITLE_FONT_PX = 14;
+const DEFAULT_LEGEND_FONT_PX = 10;
+const LEGEND_SWATCH_WIDTH_PX = 16;
+const LEGEND_SWATCH_GAP_PX = 6;
+const LEGEND_ENTRY_GAP_PX = 12;
+const LEGEND_MIN_WIDTH_PX = 80;
+
+function measureTitleHeight(text: string): number {
+  if (!text) return 0;
+  return DEFAULT_TITLE_FONT_PX * LINE_HEIGHT_RATIO;
+}
+
+function measureLegendBox(entryCount: number): { w: number; h: number } {
+  if (entryCount <= 0) return { w: 0, h: 0 };
+  const avgLabelChars = 8;
+  const entryWidth =
+    LEGEND_SWATCH_WIDTH_PX +
+    LEGEND_SWATCH_GAP_PX +
+    GLYPH_WIDTH_EM * DEFAULT_LEGEND_FONT_PX * avgLabelChars;
+  // Reserve a one-column stack: width = entryWidth, height = N lines.
+  return {
+    w: Math.max(LEGEND_MIN_WIDTH_PX, entryWidth + LEGEND_ENTRY_GAP_PX),
+    h: entryCount * DEFAULT_LEGEND_FONT_PX * LINE_HEIGHT_RATIO,
+  };
+}
+
+function maxLabelWidth(labels: ReadonlyArray<string>): number {
+  if (labels.length === 0) return 0;
+  let maxChars = 0;
+  for (const label of labels) {
+    if (label.length > maxChars) maxChars = label.length;
+  }
+  return maxChars * GLYPH_WIDTH_EM * DEFAULT_AXIS_FONT_PX;
+}
+
+// ---------------------------------------------------------------------------
+// Model introspection helpers
+// ---------------------------------------------------------------------------
+
+interface AxisBundle {
+  y: TickResult;
+  yTitle: boolean;
+  x?: TickResult;
+  xTitle: boolean;
+  secondaryY?: TickResult;
+  secondaryYTitle: boolean;
+}
+
+/**
+ * Inspect the model and produce tick lists for each axis position so
+ * the layout can reserve space based on the widest label. Pie /
+ * doughnut / unsupported return null (no axis bands).
+ */
+function pickAxes(model: ChartModel): AxisBundle | null {
+  switch (model.kind) {
+    case "bar":
+    case "line":
+    case "area": {
+      const yTicks = axisTicks(model.valueAxis);
+      const y2Ticks = model.secondaryValueAxis
+        ? axisTicks(model.secondaryValueAxis)
+        : undefined;
+      const bundle: AxisBundle = {
+        y: yTicks,
+        yTitle: !!model.valueAxis.title,
+        xTitle: model.categoryAxis.kind === "category"
+          ? !!model.categoryAxis.title
+          : !!model.categoryAxis.title,
+        secondaryYTitle: !!model.secondaryValueAxis?.title,
+      };
+      if (y2Ticks) bundle.secondaryY = y2Ticks;
+      return bundle;
+    }
+    case "scatter":
+    case "bubble": {
+      return {
+        y: axisTicks(model.yAxis),
+        yTitle: !!model.yAxis.title,
+        x: axisTicks(model.xAxis),
+        xTitle: !!model.xAxis.title,
+        secondaryYTitle: false,
+      };
+    }
+    case "combo": {
+      // Use the first group's axes as representative.
+      const first = model.groups[0];
+      if (!first) return null;
+      return pickAxes(first);
+    }
+    case "pie":
+    case "unsupported":
+      return null;
+  }
+}
+
+function axisTicks(axis: {
+  kind: string;
+  min?: number;
+  max?: number;
+  majorUnit?: number;
+  categoryLabels?: ReadonlyArray<string>;
+}): TickResult {
+  if (axis.kind === "category") {
+    const cat = generateCategoryTicks({
+      labels: axis.categoryLabels ?? [],
+    });
+    return {
+      major: cat.ticks.map((t) => t.index),
+      minor: [],
+    };
+  }
+  const min = axis.min ?? 0;
+  const max = axis.max ?? 1;
+  return generateValueTicks({
+    min,
+    max,
+    ...(axis.majorUnit !== undefined ? { majorUnit: axis.majorUnit } : {}),
+  });
+}
+
+/**
+ * Produce string labels for an axis's major ticks. Category axis uses
+ * the source labels directly; value axis stringifies numeric positions.
+ * Real number-format handling lands in Slice 4G via `number-format.ts`;
+ * the fixed-width stub here is sufficient for plot-area reservation
+ * (within ~1 glyph-width of the real rendered size).
+ */
+function axisTickLabels(ticks: TickResult): string[] {
+  return ticks.major.map((t) => String(t));
+}
+
+function countLegendEntries(model: ChartModel): number {
+  switch (model.kind) {
+    case "bar":
+    case "line":
+    case "area":
+    case "scatter":
+    case "bubble":
+      return model.series.length;
+    case "pie": {
+      // Pie legends show one entry per slice.
+      const first = model.series[0];
+      return first ? first.values.length : 0;
+    }
+    case "combo": {
+      let total = 0;
+      for (const g of model.groups) total += g.series.length;
+      return total;
+    }
+    case "unsupported":
+      return 0;
+  }
+}

package/src/ui-tailwind/chart/render/number-format.ts

@@ -0,0 +1,287 @@
+/**
+ * Excel-style number-format engine for chart tick labels + data labels
+ * (Stage 3A, pure math).
+ *
+ * Supports the top ~20 real-world format codes:
+ *   - Digit placeholders: `0` (required digit), `#` (optional digit).
+ *   - Decimal point: `.`.
+ *   - Thousands separator: `,` between digit placeholders.
+ *   - Percent: `%` — scales value by 100 and appends `%`.
+ *   - Currency: `$` and quoted literals like `"$"`.
+ *   - Scientific: `0.00E+00` style.
+ *   - Date tokens: `yyyy` `yy` `mm` `m` `mmm` `mmmm` `dd` `d`.
+ *   - Time tokens: `hh` `h` `mm` (contextual) `ss`.
+ *   - `General`: fall back to JavaScript's default `toString()`.
+ *   - `@`: text placeholder — returns the value verbatim (stringified).
+ *
+ * Out of scope (deferred post-v1):
+ *   - Conditional formats (`[>100]...;...`).
+ *   - Locale-specific formats (`[$-409]`).
+ *   - Color tokens (`[Red]`, `[Blue]`).
+ *   - Fraction formats (`# ?/?`).
+ *
+ * Unknown / malformed codes fall through to `String(value)` so the
+ * renderer never produces `NaN` or an exception at render time.
+ */
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function formatNumber(value: number, code: string | undefined): string {
+  if (code === undefined || code === "" || code.toLowerCase() === "general") {
+    return Number.isFinite(value) ? String(value) : "";
+  }
+  if (code === "@") return String(value);
+
+  if (!Number.isFinite(value)) return "";
+
+  // Date/time codes contain y/m/d/h/s letter tokens outside literals.
+  // Detect and route to the date formatter.
+  if (isDateFormatCode(code)) {
+    return formatDate(value, code);
+  }
+
+  // Scientific: "0.00E+00" / "0E+0"
+  if (/E[+-]?0/iu.test(code)) {
+    return formatScientific(value, code);
+  }
+
+  return formatDecimal(value, code);
+}
+
+// ---------------------------------------------------------------------------
+// Decimal formatter
+// ---------------------------------------------------------------------------
+
+function formatDecimal(value: number, code: string): string {
+  // Extract percent, currency prefix, thousands separator, and decimal
+  // precision from the format code. We scan for digit placeholders
+  // (0, #) and the decimal point.
+  let working = value;
+  const tokens = tokenizeLiterals(code);
+
+  // Find a sample of the digit-placeholder substring to measure precision.
+  const digitRun = tokens
+    .filter((t) => t.kind === "digits")
+    .map((t) => t.value)
+    .join("");
+
+  // Percent is a separate token from the tokenizer; scale accordingly.
+  const hasPercent = tokens.some((t) => t.kind === "percent");
+  if (hasPercent) working *= 100;
+
+  const decimalIdx = digitRun.indexOf(".");
+  const fractionDigits = decimalIdx >= 0 ? digitRun.length - decimalIdx - 1 : 0;
+  const useThousands = /,(?=[0#])/.test(digitRun);
+  const absWorking = Math.abs(working);
+
+  const [intPart, fracPart] = absWorking
+    .toFixed(Math.max(0, fractionDigits))
+    .split(".");
+
+  const intGrouped = useThousands ? groupThousands(intPart!) : intPart!;
+  const formatted =
+    fracPart !== undefined && fracPart.length > 0
+      ? `${intGrouped}.${fracPart}`
+      : intGrouped;
+  const signed = working < 0 ? `-${formatted}` : formatted;
+
+  // Stitch back prefix/suffix literals around the numeric body. We
+  // replace the first run of digit placeholders with the formatted
+  // number; other literals (currency symbols, spaces, "%") stay.
+  let produced = false;
+  const parts: string[] = [];
+  for (const t of tokens) {
+    if (t.kind === "digits") {
+      if (!produced) {
+        parts.push(signed);
+        produced = true;
+      }
+      // drop subsequent digit runs — they were part of the numeric
+      // template we already substituted.
+    } else if (t.kind === "literal") {
+      parts.push(t.value);
+    } else if (t.kind === "percent") {
+      parts.push("%");
+    } else if (t.kind === "currency") {
+      parts.push(t.value);
+    }
+  }
+  if (!produced) parts.push(signed);
+  return parts.join("");
+}
+
+function groupThousands(intPart: string): string {
+  return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+// ---------------------------------------------------------------------------
+// Scientific formatter
+// ---------------------------------------------------------------------------
+
+function formatScientific(value: number, code: string): string {
+  const match = /(0+)(\.0+)?[eE]([+-]?)(0+)/u.exec(code);
+  if (!match) return value.toExponential();
+  const mantissaInt = match[1]!.length;
+  const mantissaFrac = match[2] ? match[2].length - 1 : 0;
+  const signToken = match[3] ?? "";
+  const fracDigits = mantissaInt + mantissaFrac - 1;
+  const exp = value === 0 ? 0 : Math.floor(Math.log10(Math.abs(value)));
+  const mantissa = value / Math.pow(10, exp);
+  const mantissaStr = mantissa.toFixed(Math.max(0, fracDigits));
+  const sign = signToken === "+" ? (exp >= 0 ? "+" : "-") : exp < 0 ? "-" : "";
+  const expStr = String(Math.abs(exp)).padStart(match[4]!.length, "0");
+  return `${mantissaStr}E${sign}${expStr}`;
+}
+
+// ---------------------------------------------------------------------------
+// Date formatter
+// ---------------------------------------------------------------------------
+
+const DATE_CODE_PATTERN = /\b(yyyy|yy|mmmm|mmm|mm|m|dd|d|hh|h|ss)\b/iu;
+
+function isDateFormatCode(code: string): boolean {
+  // Strip quoted literals to avoid false positives on quoted text.
+  const stripped = code.replace(/"[^"]*"/g, "");
+  return DATE_CODE_PATTERN.test(stripped);
+}
+
+function formatDate(serial: number, code: string): string {
+  // Excel serial → Date. Epoch 1899-12-30.
+  const ms = (serial - 25569) * 86_400_000;
+  const date = new Date(ms);
+  const y = date.getUTCFullYear();
+  const m = date.getUTCMonth() + 1;
+  const d = date.getUTCDate();
+  const hh = date.getUTCHours();
+  const mi = date.getUTCMinutes();
+  const ss = date.getUTCSeconds();
+
+  const MONTHS_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  const MONTHS_LONG = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+
+  // Parse the format by splitting on literal-vs-token boundaries.
+  // Process longest tokens first (yyyy before yy, mmmm before mmm/mm, etc.).
+  let out = "";
+  let i = 0;
+  let sawTime = false; // `mm` after h/hh means minutes
+  const lowered = code.toLowerCase();
+  while (i < code.length) {
+    const ch = code[i]!;
+    if (ch === '"') {
+      const end = code.indexOf('"', i + 1);
+      if (end === -1) { out += code.slice(i + 1); break; }
+      out += code.slice(i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    // Try 4/3/2/1-char tokens at this position.
+    const tok4 = lowered.slice(i, i + 4);
+    const tok3 = lowered.slice(i, i + 3);
+    const tok2 = lowered.slice(i, i + 2);
+    const tok1 = lowered.slice(i, i + 1);
+    if (tok4 === "yyyy") { out += String(y).padStart(4, "0"); i += 4; continue; }
+    if (tok4 === "mmmm") { out += MONTHS_LONG[m - 1]!; i += 4; continue; }
+    if (tok3 === "mmm") { out += MONTHS_SHORT[m - 1]!; i += 3; continue; }
+    if (tok2 === "yy") { out += String(y).slice(-2); i += 2; continue; }
+    if (tok2 === "hh") { out += pad2(hh); sawTime = true; i += 2; continue; }
+    if (tok2 === "mm") {
+      if (sawTime) {
+        out += pad2(mi);
+        sawTime = false;
+      } else {
+        out += pad2(m);
+      }
+      i += 2;
+      continue;
+    }
+    if (tok2 === "ss") { out += pad2(ss); i += 2; continue; }
+    if (tok2 === "dd") { out += pad2(d); i += 2; continue; }
+    if (tok1 === "h") { out += String(hh); sawTime = true; i += 1; continue; }
+    if (tok1 === "m") { out += sawTime ? String(mi) : String(m); if (sawTime) sawTime = false; i += 1; continue; }
+    if (tok1 === "d") { out += String(d); i += 1; continue; }
+    if (tok1 === "y") { out += String(y); i += 1; continue; }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+// ---------------------------------------------------------------------------
+// Literal tokenization for decimal format codes
+// ---------------------------------------------------------------------------
+
+interface FormatToken {
+  kind: "digits" | "literal" | "percent" | "currency";
+  value: string;
+}
+
+/**
+ * Split a decimal format code into a stream of tokens so the formatter
+ * can re-stitch prefix/suffix literals around the formatted number.
+ *
+ * Examples:
+ *   `"$#,##0.00"` → [{currency "$"}, {digits "#,##0.00"}]
+ *   `"0.00%"`     → [{digits "0.00"}, {percent}]
+ *   `"\"Total: \"0"` → [{literal "Total: "}, {digits "0"}]
+ */
+function tokenizeLiterals(code: string): FormatToken[] {
+  const out: FormatToken[] = [];
+  let i = 0;
+  let digitBuf = "";
+  const flushDigits = () => {
+    if (digitBuf) {
+      out.push({ kind: "digits", value: digitBuf });
+      digitBuf = "";
+    }
+  };
+  while (i < code.length) {
+    const ch = code[i]!;
+    if (ch === '"') {
+      flushDigits();
+      const end = code.indexOf('"', i + 1);
+      const lit = end === -1 ? code.slice(i + 1) : code.slice(i + 1, end);
+      out.push({ kind: "literal", value: lit });
+      i = end === -1 ? code.length : end + 1;
+      continue;
+    }
+    if (ch === "\\") {
+      flushDigits();
+      if (i + 1 < code.length) {
+        out.push({ kind: "literal", value: code[i + 1]! });
+        i += 2;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+    if (ch === "$") {
+      flushDigits();
+      out.push({ kind: "currency", value: "$" });
+      i += 1;
+      continue;
+    }
+    if (ch === "%") {
+      flushDigits();
+      out.push({ kind: "percent", value: "%" });
+      i += 1;
+      continue;
+    }
+    if (ch === "0" || ch === "#" || ch === "." || ch === "," || ch === " ") {
+      digitBuf += ch;
+      i += 1;
+      continue;
+    }
+    // Unknown char — treat as literal.
+    flushDigits();
+    out.push({ kind: "literal", value: ch });
+    i += 1;
+  }
+  flushDigits();
+  return out;
+}