@beyondwork/docx-react-component 1.0.53 → 1.0.55

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

@@ -1,6 +1,6 @@
 /**
  * Plot-area layout: partition the canvas into title / legend / axis /
- * plot rectangles (Stage 3A, pure math).
+ * plot rectangles (Stage 3A + 3B update).
  *
  * Call shape:
  *
@@ -13,21 +13,23 @@
  *   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.
+ * Slice 3B: text measurement now uses the real `measureText` helper
+ * (`src/ui-tailwind/chart/render/font-metrics.ts`) which calls
+ * `ctx.measureText` in a browser and falls back to an empirical glyph-width
+ * table in SSR / Node test environments. The public `layoutPlotArea`
+ * signature is unchanged.
  */
 
 import type { ChartModel } from "../../../io/ooxml/chart/types.ts";
 import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import { measureText } from "../render/font-metrics.ts";
+import { formatNumber } from "../render/number-format.ts";
 import {
   generateCategoryTicks,
+  generateDateTicks,
   generateValueTicks,
   type TickResult,
+  type TimeUnit,
 } from "./axis-layout.ts";
 
 // ---------------------------------------------------------------------------
@@ -69,7 +71,6 @@ export function layoutPlotArea(
   model: ChartModel,
   theme: ResolvedTheme | undefined,
 ): PlotAreaLayout {
-  void theme; // consumed by Slice 3B's real font-metrics wrapper.
 
   let top = 0;
   let bottom = canvas.h;
@@ -82,7 +83,7 @@ export function layoutPlotArea(
 
   // 1. Title band (top).
   if (model.kind !== "unsupported" && model.title && !model.title.overlay) {
-    const titleHeight = measureTitleHeight(model.title.text ?? "");
+    const titleHeight = measureTitleHeight(model.title.text ?? "", theme);
     out.titleRect = { x: 0, y: 0, w: canvas.w, h: titleHeight };
     top += titleHeight + BAND_GAP_PX;
   }
@@ -90,7 +91,8 @@ export function layoutPlotArea(
   // 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);
+    const legendLabels = collectLegendLabels(model);
+    const { w: legendW, h: legendH } = measureLegendBox(entryCount, legendLabels, theme);
     switch (model.legend.position) {
       case "t":
         out.legendRect = { x: 0, y: top, w: canvas.w, h: legendH };
@@ -128,18 +130,19 @@ export function layoutPlotArea(
   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);
+    // rotated height. Numeric tick values are passed through
+    // `formatNumber(value, formatCode)` so layout reserves real label width.
+    const yTickLabels = axisTickLabels(axes.y, axes.yFormatCode);
     const yWidth =
-      maxLabelWidth(yTickLabels) + (axes.yTitle ? AXIS_TITLE_BAND_PX : 0);
+      maxLabelWidth(yTickLabels, theme) + (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 y2TickLabels = axisTickLabels(axes.secondaryY, axes.secondaryYFormatCode);
       const y2Width =
-        maxLabelWidth(y2TickLabels) + (axes.secondaryYTitle ? AXIS_TITLE_BAND_PX : 0);
+        maxLabelWidth(y2TickLabels, theme) + (axes.secondaryYTitle ? AXIS_TITLE_BAND_PX : 0);
       out.secondaryYAxisRect = {
         x: right - y2Width,
         y: top,
@@ -150,7 +153,16 @@ export function layoutPlotArea(
     }
 
     // X-axis on the bottom: height = label height + axis-title band.
-    const xLabelHeight = X_AXIS_LABEL_HEIGHT_PX;
+    // For category axes, sample the widest category label so tall rotated
+    // labels reserve enough vertical space; for value/date axes use a
+    // numeric sample run through formatNumber.
+    const xTickLabels = axes.x
+      ? axisTickLabels(axes.x, axes.xFormatCode)
+      : axes.categoryLabels
+        ? Array.from(axes.categoryLabels)
+        : yTickLabels;
+    const xSampleLabel = xTickLabels.length > 0 ? xTickLabels[0]! : "0";
+    const xLabelHeight = measureText(xSampleLabel, AXIS_TXP, theme).lineHeight;
     const xHeight = xLabelHeight + (axes.xTitle ? AXIS_TITLE_BAND_PX : 0);
     out.xAxisRect = {
       x: left,
@@ -171,57 +183,57 @@ export function layoutPlotArea(
 }
 
 // ---------------------------------------------------------------------------
-// Text measurement — fixed stub (Slice 3B replaces with real metrics)
+// Text measurement — real metrics via font-metrics.ts (Slice 3B)
 // ---------------------------------------------------------------------------
 
-/**
- * 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 {
+const TITLE_TXP = { fontSizePt: 14 };
+const AXIS_TXP = { fontSizePt: 10 };
+const LEGEND_TXP = { fontSizePt: 10 };
+
+function measureTitleHeight(text: string, theme: ResolvedTheme | undefined): number {
   if (!text) return 0;
-  return DEFAULT_TITLE_FONT_PX * LINE_HEIGHT_RATIO;
+  return measureText(text, TITLE_TXP, theme).lineHeight;
 }
 
-function measureLegendBox(entryCount: number): { w: number; h: number } {
+function measureLegendBox(
+  entryCount: number,
+  labels: ReadonlyArray<string>,
+  theme: ResolvedTheme | undefined,
+): { 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.
+  // Measure the widest label; fall back to an 8-char estimate when no labels.
+  const sampleLabels = labels.length > 0 ? labels : ["MMMMMMMM"];
+  let maxW = 0;
+  for (const label of sampleLabels) {
+    const w = measureText(label, LEGEND_TXP, theme).width;
+    if (w > maxW) maxW = w;
+  }
+  const entryWidth = LEGEND_SWATCH_WIDTH_PX + LEGEND_SWATCH_GAP_PX + maxW;
+  const lineH = measureText(sampleLabels[0]!, LEGEND_TXP, theme).lineHeight;
   return {
     w: Math.max(LEGEND_MIN_WIDTH_PX, entryWidth + LEGEND_ENTRY_GAP_PX),
-    h: entryCount * DEFAULT_LEGEND_FONT_PX * LINE_HEIGHT_RATIO,
+    h: entryCount * lineH,
   };
 }
 
-function maxLabelWidth(labels: ReadonlyArray<string>): number {
+function maxLabelWidth(
+  labels: ReadonlyArray<string>,
+  theme: ResolvedTheme | undefined,
+): number {
   if (labels.length === 0) return 0;
-  let maxChars = 0;
+  let maxW = 0;
   for (const label of labels) {
-    if (label.length > maxChars) maxChars = label.length;
+    const w = measureText(label, AXIS_TXP, theme).width;
+    if (w > maxW) maxW = w;
   }
-  return maxChars * GLYPH_WIDTH_EM * DEFAULT_AXIS_FONT_PX;
+  return maxW;
 }
 
 // ---------------------------------------------------------------------------
@@ -230,11 +242,20 @@ function maxLabelWidth(labels: ReadonlyArray<string>): number {
 
 interface AxisBundle {
   y: TickResult;
+  yFormatCode?: string;
   yTitle: boolean;
   x?: TickResult;
+  xFormatCode?: string;
   xTitle: boolean;
   secondaryY?: TickResult;
+  secondaryYFormatCode?: string;
   secondaryYTitle: boolean;
+  /**
+   * Category axis labels (for bar/line/area/combo) — pre-resolved
+   * category-axis label strings. When present, the x-axis tick band
+   * measurement uses these strings rather than numeric tick indices.
+   */
+  categoryLabels?: ReadonlyArray<string>;
 }
 
 /**
@@ -254,23 +275,33 @@ function pickAxes(model: ChartModel): AxisBundle | null {
       const bundle: AxisBundle = {
         y: yTicks,
         yTitle: !!model.valueAxis.title,
-        xTitle: model.categoryAxis.kind === "category"
-          ? !!model.categoryAxis.title
-          : !!model.categoryAxis.title,
+        x: axisTicks(model.categoryAxis),
+        xTitle: !!model.categoryAxis.title,
         secondaryYTitle: !!model.secondaryValueAxis?.title,
       };
+      if (model.valueAxis.numberFormat) bundle.yFormatCode = model.valueAxis.numberFormat;
+      if (model.categoryAxis.numberFormat) bundle.xFormatCode = model.categoryAxis.numberFormat;
       if (y2Ticks) bundle.secondaryY = y2Ticks;
+      if (model.secondaryValueAxis?.numberFormat) {
+        bundle.secondaryYFormatCode = model.secondaryValueAxis.numberFormat;
+      }
+      if (model.categoryAxis.kind === "category") {
+        bundle.categoryLabels = model.categoryAxis.categoryLabels;
+      }
       return bundle;
     }
     case "scatter":
     case "bubble": {
-      return {
+      const bundle: AxisBundle = {
         y: axisTicks(model.yAxis),
         yTitle: !!model.yAxis.title,
         x: axisTicks(model.xAxis),
         xTitle: !!model.xAxis.title,
         secondaryYTitle: false,
       };
+      if (model.yAxis.numberFormat) bundle.yFormatCode = model.yAxis.numberFormat;
+      if (model.xAxis.numberFormat) bundle.xFormatCode = model.xAxis.numberFormat;
+      return bundle;
     }
     case "combo": {
       // Use the first group's axes as representative.
@@ -289,6 +320,10 @@ function axisTicks(axis: {
   min?: number;
   max?: number;
   majorUnit?: number;
+  majorTimeUnit?: TimeUnit;
+  minorUnit?: number;
+  minorTimeUnit?: TimeUnit;
+  baseTimeUnit?: TimeUnit;
   categoryLabels?: ReadonlyArray<string>;
 }): TickResult {
   if (axis.kind === "category") {
@@ -300,6 +335,20 @@ function axisTicks(axis: {
       minor: [],
     };
   }
+  // C8: DateAxis (kind === "date") must route to generateDateTicks so Excel
+  // serial dates produce properly-stepped tick positions rather than treating
+  // serials as raw numbers and calling generateValueTicks on them.
+  if (axis.kind === "date") {
+    return generateDateTicks({
+      min: axis.min ?? 0,
+      max: axis.max ?? 1,
+      ...(axis.majorUnit !== undefined ? { majorUnit: axis.majorUnit } : {}),
+      ...(axis.majorTimeUnit !== undefined ? { majorTimeUnit: axis.majorTimeUnit } : {}),
+      ...(axis.minorUnit !== undefined ? { minorUnit: axis.minorUnit } : {}),
+      ...(axis.minorTimeUnit !== undefined ? { minorTimeUnit: axis.minorTimeUnit } : {}),
+      ...(axis.baseTimeUnit !== undefined ? { baseTimeUnit: axis.baseTimeUnit } : {}),
+    });
+  }
   const min = axis.min ?? 0;
   const max = axis.max ?? 1;
   return generateValueTicks({
@@ -310,14 +359,25 @@ function axisTicks(axis: {
 }
 
 /**
- * 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).
+ * Produce string labels for an axis's major ticks.
+ *
+ * - Value / date axes: each tick numeric value is passed through
+ *   `formatNumber(value, formatCode)` so layout reserves width for the
+ *   real rendered string (e.g. `"$1,234"`, `"45%"`, `"Jan-24"`) not the
+ *   raw `String(1234)` approximation.
+ * - Category axes: when categoryLabels are provided, return them verbatim
+ *   (tick indices 0..N-1 map 1:1 to labels). This avoids reserving space
+ *   for "0", "1", "2" when the real rendered label is "Q1", "Q2", "Q3".
  */
-function axisTickLabels(ticks: TickResult): string[] {
-  return ticks.major.map((t) => String(t));
+function axisTickLabels(
+  ticks: TickResult,
+  formatCode: string | undefined,
+  categoryLabels?: ReadonlyArray<string>,
+): string[] {
+  if (categoryLabels && categoryLabels.length > 0) {
+    return ticks.major.map((i) => categoryLabels[i] ?? "");
+  }
+  return ticks.major.map((t) => formatNumber(t, formatCode));
 }
 
 function countLegendEntries(model: ChartModel): number {
@@ -329,7 +389,9 @@ function countLegendEntries(model: ChartModel): number {
     case "bubble":
       return model.series.length;
     case "pie": {
-      // Pie legends show one entry per slice.
+      // Pie legends show one entry per slice. Prefer categoryLabels when
+      // resolved; fall back to series value count for degenerate inputs.
+      if (model.categoryLabels.length > 0) return model.categoryLabels.length;
       const first = model.series[0];
       return first ? first.values.length : 0;
     }
@@ -342,3 +404,34 @@ function countLegendEntries(model: ChartModel): number {
       return 0;
   }
 }
+
+function collectLegendLabels(model: ChartModel): ReadonlyArray<string> {
+  switch (model.kind) {
+    case "bar":
+    case "line":
+    case "area":
+    case "scatter":
+    case "bubble":
+      return model.series.map((s) => s.name ?? `Series ${s.idx + 1}`);
+    case "pie": {
+      // PieChartModel exposes categoryLabels at the model level (resolved
+      // from the first series' c:cat cache during parsing). Each slice
+      // in the legend corresponds 1:1 to a category label. Fall back to
+      // synthetic "Slice N" only when the parser saw no category cache
+      // (degenerate data-only DOCX).
+      if (model.categoryLabels.length > 0) return model.categoryLabels;
+      const first = model.series[0];
+      if (!first) return [];
+      return first.values.map((_, i) => `Slice ${i + 1}`);
+    }
+    case "combo": {
+      const labels: string[] = [];
+      for (const g of model.groups) {
+        for (const s of g.series) labels.push(s.name ?? `Series ${s.idx + 1}`);
+      }
+      return labels;
+    }
+    case "unsupported":
+      return [];
+  }
+}

package/src/ui-tailwind/chart/layout/title-layout.ts

@@ -0,0 +1,184 @@
+/**
+ * Title layout — chart title + axis titles (Stage 3C).
+ *
+ * Chart title:
+ *   - Centered horizontally within the reserved title band.
+ *   - Vertical baseline respects the title font's ascent/descent.
+ *   - Rich text (c:tx/c:rich) is not yet unpacked — the title.text
+ *     string from the parser is treated as the full title. Rich runs
+ *     land in Stage 4G alongside data labels.
+ *
+ * Axis titles:
+ *   - Y-axis: rotated −90° (anti-clockwise). Title sits in the leftmost
+ *     column of the y-axis band, vertically centered on the plot area.
+ *   - Secondary y-axis: rotated +90° so the baseline reads top-to-bottom
+ *     on the right side. Title sits in the rightmost column of the
+ *     secondary y-axis band.
+ *   - X-axis: no rotation. Title sits below the tick-label band,
+ *     horizontally centered on the plot area.
+ *
+ * The helpers return text-placement descriptors (x/y position, font
+ * size, rotation, anchor) rather than SVG elements — renderers compose
+ * these via `svgText` from `svg-primitives.ts`.
+ */
+
+import type { Rect } from "./plot-area.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import { measureText } from "../render/font-metrics.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export type AxisTitleKind = "x" | "y" | "secondaryY";
+
+export interface TitlePlacement {
+  text: string;
+  x: number;
+  y: number;
+  fontSizePt: number;
+  bold: boolean;
+  /** SVG rotation in degrees, clockwise. 0 = upright. */
+  rotate: number;
+  /** SVG text-anchor: where the (x,y) anchor point lies on the glyph run. */
+  anchor: "start" | "middle" | "end";
+  /** Vertical alignment of the (x,y) point to the glyph row. */
+  baseline: "hanging" | "middle" | "auto";
+}
+
+export interface TitleLayoutOptions {
+  /** Font size in points. Word default: 14pt for chart title, 10pt for axis titles. */
+  fontSizePt?: number;
+  /** Whether the title is rendered in bold. Word chart title default: true. */
+  bold?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Chart title
+// ---------------------------------------------------------------------------
+
+/**
+ * Place a chart title centered horizontally inside `titleRect`. The
+ * returned placement anchors at the middle of the title band and uses
+ * `text-anchor: middle` so the glyph run spans equally on each side.
+ *
+ * Returns `null` when text is empty — callers should not emit a title
+ * element at all in that case.
+ */
+export function layoutTitle(
+  text: string,
+  titleRect: Rect,
+  theme: ResolvedTheme | undefined,
+  options: TitleLayoutOptions = {},
+): TitlePlacement | null {
+  if (!text) return null;
+  const fontSizePt = options.fontSizePt ?? 14;
+  const bold = options.bold ?? true;
+  // Consume theme for future font-fallback resolution.
+  void theme;
+  const centerX = titleRect.x + titleRect.w / 2;
+  const centerY = titleRect.y + titleRect.h / 2;
+  return {
+    text,
+    x: centerX,
+    y: centerY,
+    fontSizePt,
+    bold,
+    rotate: 0,
+    anchor: "middle",
+    baseline: "middle",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Axis titles
+// ---------------------------------------------------------------------------
+
+/**
+ * Place an axis title inside the axis-title band. The `kind` determines
+ * rotation:
+ *   - `"y"` → −90° (baseline reads bottom-to-top on the left)
+ *   - `"secondaryY"` → +90° (baseline reads top-to-bottom on the right)
+ *   - `"x"` → 0° (no rotation)
+ *
+ * `bandRect` is the rectangle the plot-area reserved for the axis title
+ * itself (NOT the full axis band — just the title sliver). For y / sY
+ * this is typically ~14px wide (the `AXIS_TITLE_BAND_PX` constant from
+ * plot-area.ts); for x it's ~14px tall.
+ *
+ * `plotRect` is the plot area the title labels. The title is visually
+ * centered against the plot area (not the band) so it aligns with the
+ * mid-point of the axis data range.
+ */
+export function layoutAxisTitle(
+  text: string,
+  kind: AxisTitleKind,
+  bandRect: Rect,
+  plotRect: Rect,
+  theme: ResolvedTheme | undefined,
+  options: TitleLayoutOptions = {},
+): TitlePlacement | null {
+  if (!text) return null;
+  const fontSizePt = options.fontSizePt ?? 10;
+  const bold = options.bold ?? false;
+
+  switch (kind) {
+    case "y": {
+      // Vertical center on the plot, rotated -90°. Anchor at band center x.
+      // Consume theme to keep signature future-proof.
+      void theme;
+      return {
+        text,
+        x: bandRect.x + bandRect.w / 2,
+        y: plotRect.y + plotRect.h / 2,
+        fontSizePt,
+        bold,
+        rotate: -90,
+        anchor: "middle",
+        baseline: "middle",
+      };
+    }
+    case "secondaryY": {
+      return {
+        text,
+        x: bandRect.x + bandRect.w / 2,
+        y: plotRect.y + plotRect.h / 2,
+        fontSizePt,
+        bold,
+        rotate: 90,
+        anchor: "middle",
+        baseline: "middle",
+      };
+    }
+    case "x": {
+      return {
+        text,
+        x: plotRect.x + plotRect.w / 2,
+        y: bandRect.y + bandRect.h / 2,
+        fontSizePt,
+        bold,
+        rotate: 0,
+        anchor: "middle",
+        baseline: "middle",
+      };
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Measurement helper for band sizing
+// ---------------------------------------------------------------------------
+
+/**
+ * Measure the title height for the given text + font size, matching the
+ * row height a single-line title would occupy. Callers can use this to
+ * validate `titleRect.h` was reserved adequately before rendering.
+ */
+export function measureTitleBandHeight(
+  text: string,
+  fontSizePt: number,
+  theme: ResolvedTheme | undefined,
+): number {
+  if (!text) return 0;
+  return measureText(text, { fontSizePt, bold: true }, theme).lineHeight;
+}