@beyondwork/docx-react-component 1.0.52 → 1.0.54

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;
+}

package/src/ui-tailwind/chart/render/area.tsx

@@ -0,0 +1,277 @@
+/**
+ * Area chart renderer (Stage 4 Slice 4D, B3).
+ *
+ * Renders filled closed polygons for each series. Handles:
+ *   - `grouping: "standard"` — each series' area spans from the x-axis
+ *     (y = 0) up to its values.
+ *   - `grouping: "stacked"` — each series' area spans from the running
+ *     cumulative base up to the cumulative top.
+ *   - `grouping: "percentStacked"` — values normalize to 100% per
+ *     category; cumulative stacking as above.
+ *
+ * `dispBlanksAs` (B3):
+ *   - `"zero"` — null becomes 0; single polygon closed along the x-axis.
+ *   - `"gap"`   — null splits the area polygon into multiple pieces,
+ *     closing the current piece at the last valid point and reopening
+ *     at the next valid point.
+ *   - `"span"`  — nulls dropped; the polygon connects valid neighbors
+ *     directly (creating a single continuous polygon).
+ *
+ * Emits `<g data-role="area-chart">` containing `<g data-role="areas">`
+ * with one or more `<path>` per series plus a `data-labels` placeholder.
+ */
+
+import React from "react";
+import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import type {
+  AreaChartModel,
+  Series,
+} from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+import { useProgressiveCount } from "./progressive-render.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface AreaChartProps {
+  model: AreaChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+}
+
+function AreaChartImpl({ model, layout, theme }: AreaChartProps): React.ReactElement {
+  const plot = layout.plotRect;
+  const percent = model.grouping === "percentStacked";
+  const stacked = model.grouping === "stacked" || percent;
+
+  const categoryCount = Math.max(
+    1,
+    model.categoryAxis.kind === "category"
+      ? model.categoryAxis.categoryLabels.length
+      : model.series[0]?.values.length ?? 1,
+  );
+  const visibleCategories = useProgressiveCount(categoryCount);
+  const slotWidth = plot.w / categoryCount;
+  const { valueMin, valueMax } = computeValueRange(model);
+  const valueSpan = Math.max(1e-9, valueMax - valueMin);
+
+  const toX = (c: number): number => plot.x + (c + 0.5) * slotWidth;
+  const toY = (v: number): number => plot.y + plot.h - ((v - valueMin) / valueSpan) * plot.h;
+
+  // Pre-compute per-category cumulative bases (for stacked) + tops.
+  const lowerBounds = new Array<number>(categoryCount).fill(valueMin);
+  const paths: React.ReactElement[] = [];
+
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const color = composeSeriesColor(model, theme ?? { colors: {} }, s);
+
+    // Compute this series' upper-boundary values and lower-boundary values.
+    const upper: Array<number | null> = [];
+    const lower: Array<number | null> = [];
+    for (let c = 0; c < visibleCategories; c++) {
+      const raw = series.values[c];
+      if (raw === null || raw === undefined || !Number.isFinite(raw)) {
+        upper.push(null);
+        lower.push(null);
+        continue;
+      }
+      let valueContribution = raw;
+      if (percent) {
+        const total = sumAbsAtCategory(model.series, c);
+        valueContribution = total === 0 ? 0 : (raw / total) * 100;
+      }
+      if (stacked) {
+        const lo = lowerBounds[c]!;
+        upper.push(lo + valueContribution);
+        lower.push(lo);
+        lowerBounds[c] = lo + valueContribution;
+      } else {
+        // Standard: every series sits on the axis (y=0) up to its value.
+        upper.push(valueContribution);
+        lower.push(0);
+      }
+    }
+
+    // Apply dispBlanksAs to decide how to close polygons at nulls.
+    const segments = partitionForDispBlanksAs(upper, lower, model.dispBlanksAs);
+    for (let segIdx = 0; segIdx < segments.length; segIdx++) {
+      const seg = segments[segIdx]!;
+      const d = buildAreaPath(seg, toX, toY);
+      if (!d) continue;
+      paths.push(
+        <path
+          key={`area-${s}-${segIdx}`}
+          d={d}
+          fill={color}
+          fillOpacity={model.grouping === "standard" ? 0.6 : 1}
+          stroke={color}
+          strokeWidth={1}
+          data-role="area"
+          data-series-index={s}
+          data-segment-index={segIdx}
+        />,
+      );
+    }
+  }
+
+  return (
+    <g data-role="area-chart" data-grouping={model.grouping}>
+      <g data-role="areas">{paths}</g>
+      <g data-role="data-labels" />
+    </g>
+  );
+}
+
+export const AreaChart = React.memo(
+  AreaChartImpl,
+  (prev, next) =>
+    prev.model.rawXml === next.model.rawXml &&
+    prev.layout.plotRect.w === next.layout.plotRect.w &&
+    prev.layout.plotRect.h === next.layout.plotRect.h &&
+    prev.theme === next.theme,
+);
+
+// ---------------------------------------------------------------------------
+// Value range
+// ---------------------------------------------------------------------------
+
+function computeValueRange(model: AreaChartModel): { valueMin: number; valueMax: number } {
+  if (model.valueAxis.min !== undefined && model.valueAxis.max !== undefined) {
+    return { valueMin: model.valueAxis.min, valueMax: model.valueAxis.max };
+  }
+  if (model.grouping === "percentStacked") return { valueMin: 0, valueMax: 100 };
+  const stacked = model.grouping === "stacked";
+  const categoryCount = Math.max(1, model.series[0]?.values.length ?? 1);
+  let min = 0;
+  let max = 0;
+  if (stacked) {
+    for (let c = 0; c < categoryCount; c++) {
+      let sum = 0;
+      for (const s of model.series) {
+        const v = s.values[c];
+        if (v === null || v === undefined || !Number.isFinite(v)) continue;
+        sum += v;
+      }
+      if (sum > max) max = sum;
+      if (sum < min) min = sum;
+    }
+  } else {
+    for (const s of model.series) {
+      for (const v of s.values) {
+        if (v === null || v === undefined || !Number.isFinite(v)) continue;
+        if (v > max) max = v;
+        if (v < min) min = v;
+      }
+    }
+  }
+  return { valueMin: min, valueMax: max };
+}
+
+function sumAbsAtCategory(series: Series[], c: number): number {
+  let total = 0;
+  for (const s of series) {
+    const v = s.values[c];
+    if (v === null || v === undefined || !Number.isFinite(v)) continue;
+    total += Math.abs(v);
+  }
+  return total;
+}
+
+// ---------------------------------------------------------------------------
+// dispBlanksAs partition (B3) + polygon path builder
+// ---------------------------------------------------------------------------
+
+interface AreaPoint {
+  c: number;
+  upper: number;
+  lower: number;
+}
+
+/**
+ * Partition a series' (upper, lower) boundary arrays into contiguous
+ * polygon segments based on `dispBlanksAs`.
+ *
+ *   - `"zero"`: null → 0 on upper, 0 on lower; single segment.
+ *   - `"gap"`:  null splits into multiple segments. Each segment is a
+ *               contiguous run of non-null categories.
+ *   - `"span"`: nulls dropped from the sequence; single segment.
+ */
+function partitionForDispBlanksAs(
+  upper: ReadonlyArray<number | null>,
+  lower: ReadonlyArray<number | null>,
+  mode: "gap" | "zero" | "span",
+): AreaPoint[][] {
+  const n = upper.length;
+  switch (mode) {
+    case "zero": {
+      const out: AreaPoint[] = [];
+      for (let c = 0; c < n; c++) {
+        const u = upper[c];
+        const l = lower[c];
+        out.push({
+          c,
+          upper: u === null ? 0 : u,
+          lower: l === null ? 0 : l,
+        });
+      }
+      return [out];
+    }
+    case "gap": {
+      const segments: AreaPoint[][] = [];
+      let cur: AreaPoint[] = [];
+      for (let c = 0; c < n; c++) {
+        const u = upper[c];
+        const l = lower[c];
+        if (u === null || l === null) {
+          if (cur.length > 0) {
+            segments.push(cur);
+            cur = [];
+          }
+          continue;
+        }
+        cur.push({ c, upper: u, lower: l });
+      }
+      if (cur.length > 0) segments.push(cur);
+      return segments;
+    }
+    case "span": {
+      const out: AreaPoint[] = [];
+      for (let c = 0; c < n; c++) {
+        const u = upper[c];
+        const l = lower[c];
+        if (u === null || l === null) continue;
+        out.push({ c, upper: u, lower: l });
+      }
+      return out.length > 0 ? [out] : [];
+    }
+  }
+}
+
+function buildAreaPath(
+  seg: ReadonlyArray<AreaPoint>,
+  toX: (c: number) => number,
+  toY: (v: number) => number,
+): string {
+  if (seg.length < 2) return "";
+  const parts: string[] = [];
+  // Walk the upper boundary left → right.
+  parts.push(`M ${fmt(toX(seg[0]!.c))} ${fmt(toY(seg[0]!.upper))}`);
+  for (let i = 1; i < seg.length; i++) {
+    parts.push(`L ${fmt(toX(seg[i]!.c))} ${fmt(toY(seg[i]!.upper))}`);
+  }
+  // Then the lower boundary right → left to close.
+  for (let i = seg.length - 1; i >= 0; i--) {
+    parts.push(`L ${fmt(toX(seg[i]!.c))} ${fmt(toY(seg[i]!.lower))}`);
+  }
+  parts.push("Z");
+  return parts.join(" ");
+}
+
+function fmt(n: number): string {
+  if (!Number.isFinite(n)) return "0";
+  const r = Math.round(n * 1000) / 1000;
+  return r === 0 ? "0" : String(r);
+}