@beyondwork/docx-react-component 1.0.53 → 1.0.55

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

package/src/ui-tailwind/chart/render/bar-column.tsx

@@ -0,0 +1,356 @@
+/**
+ * Bar / Column chart renderer (Stage 4 Slice 4A).
+ *
+ * Dispatches `BarChartModel` to SVG via:
+ *   - Value → plot-coordinate mapping (derived from `model.valueAxis`).
+ *   - Category slot math (equal-width slots across the category axis).
+ *   - Grouping logic: clustered (side-by-side within a slot), stacked
+ *     (values stack on positive + negative bases), or percentStacked
+ *     (values normalize to ±100% per slot).
+ *   - Direction flip: `"bar"` swaps the axis roles so bars grow
+ *     horizontally.
+ *
+ * Colors derive from `composeSeriesColor(model, theme, seriesIdx)` —
+ * the Stage 2 cascade handles explicit spPr overrides, chart-style
+ * palette, and theme resolution. Per-point `dPt.spPr` overrides rank
+ * above series color.
+ *
+ * `invertIfNegative` (per-series): when a value is negative and the
+ * series opt-in is set, the bar is tinted (towards white) to match
+ * Word's visual cue. We emit a lightened color rather than the
+ * inverted palette slot.
+ *
+ * The component wraps in `React.memo` with a structural comparator so
+ * re-renders are skipped when the underlying `rawXml` and dimensions
+ * haven't changed.
+ */
+
+import React from "react";
+import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import type {
+  BarChartModel,
+  DataPointOverride,
+  Series,
+} from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+import { resolveFill, DefsRegistry } from "./svg-primitives.ts";
+import { useProgressiveCount } from "./progressive-render.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface BarColumnChartProps {
+  model: BarChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+  defs?: DefsRegistry;
+}
+
+function BarColumnChartImpl({
+  model,
+  layout,
+  theme,
+  defs,
+}: BarColumnChartProps): React.ReactElement {
+  const defsRegistry = defs ?? new DefsRegistry();
+  const horizontal = model.direction === "bar";
+  const stacked =
+    model.grouping === "stacked" || model.grouping === "percentStacked";
+  const percent = model.grouping === "percentStacked";
+  const plot = layout.plotRect;
+
+  // --- Value range ---
+  const { valueMin, valueMax } = computeValueRange(model);
+
+  // --- Category slot math ---
+  const seriesCount = Math.max(1, model.series.length);
+  const categoryCount = Math.max(
+    1,
+    model.categoryAxis.kind === "category"
+      ? model.categoryAxis.categoryLabels.length
+      : model.series[0]?.values.length ?? 1,
+  );
+  // Progressive rendering: render the first N categories synchronously and
+  // advance in idle ticks for datasets exceeding PROGRESSIVE_THRESHOLD.
+  const visibleCategories = useProgressiveCount(categoryCount);
+  const slotSize = (horizontal ? plot.h : plot.w) / categoryCount;
+  // gapWidth is % of bar width (Word default 150); 150 → half-slot gap.
+  const gapFrac = Math.min(0.9, Math.max(0.05, model.gapWidth / 100 / 2));
+  const groupSize = slotSize * (1 - gapFrac);
+  // overlap: -100..100, percent of bar width; -100 = no overlap, 100 = full overlap.
+  const overlapFrac = Math.max(-1, Math.min(1, model.overlap / 100));
+  const barWidth = stacked
+    ? groupSize
+    : computeClusteredBarWidth(groupSize, seriesCount, overlapFrac);
+
+  // --- value → plot-coordinate ---
+  const valueSpan = Math.max(1e-9, valueMax - valueMin);
+  const valueToPlot = (v: number): number => {
+    const frac = (v - valueMin) / valueSpan;
+    return horizontal ? plot.x + frac * plot.w : plot.y + plot.h - frac * plot.h;
+  };
+
+  // --- emit bars ---
+  const bars: React.ReactElement[] = [];
+
+  if (percent) {
+    // Normalize each slot to 100%; pos stack and neg stack both scaled so
+    // |sum| sits at ±100. Recommended approach: per-category, compute
+    // pos/neg totals, scale each value's contribution accordingly.
+    for (let c = 0; c < visibleCategories; c++) {
+      const totalsAbs = computeSlotAbsTotal(model.series, c);
+      if (totalsAbs === 0) continue;
+      emitStackedSlot(bars, model, theme, defsRegistry, c, slotSize, groupSize, plot,
+        horizontal, (v) => (v / totalsAbs) * 100, (_v) => 0, 100, -100, (frac) => {
+          return horizontal ? plot.x + frac * plot.w : plot.y + plot.h - frac * plot.h;
+        });
+    }
+  } else if (stacked) {
+    for (let c = 0; c < visibleCategories; c++) {
+      emitStackedSlot(bars, model, theme, defsRegistry, c, slotSize, groupSize, plot,
+        horizontal, (v) => v, (v) => v, valueMax, valueMin, valueToPlot);
+    }
+  } else {
+    // Clustered: place each series' bar side-by-side within the slot.
+    for (let c = 0; c < visibleCategories; c++) {
+      const slotStart = (horizontal ? plot.y : plot.x) + c * slotSize;
+      const groupStart = slotStart + (slotSize - groupSize) / 2;
+      for (let s = 0; s < model.series.length; s++) {
+        const series = model.series[s]!;
+        const v = series.values[c];
+        if (v === null || v === undefined || !Number.isFinite(v)) continue;
+        const color = resolveBarColor(model, theme, s, c, series, defsRegistry);
+        const barOffset = s * (barWidth * (1 - overlapFrac));
+        const barStart = groupStart + barOffset;
+        const origin = valueToPlot(0);
+        const end = valueToPlot(v);
+        const rect = horizontal
+          ? {
+              x: Math.min(origin, end),
+              y: barStart,
+              w: Math.abs(end - origin),
+              h: barWidth * 0.92,
+            }
+          : {
+              x: barStart,
+              y: Math.min(origin, end),
+              w: barWidth * 0.92,
+              h: Math.abs(end - origin),
+            };
+        const appliedColor = v < 0 && seriesInvertsIfNegative(series)
+          ? lightenHex(color, 0.4)
+          : color;
+        bars.push(
+          <rect
+            key={`bar-${s}-${c}`}
+            x={rect.x}
+            y={rect.y}
+            width={rect.w}
+            height={rect.h}
+            fill={appliedColor}
+            data-role="bar"
+            data-series-index={s}
+            data-category-index={c}
+          />,
+        );
+      }
+    }
+  }
+
+  return (
+    <g data-role="bar-column-chart" data-direction={model.direction} data-grouping={model.grouping}>
+      <g data-role="bars">{bars}</g>
+      <g data-role="data-labels" />
+    </g>
+  );
+}
+
+export const BarColumnChart = React.memo(
+  BarColumnChartImpl,
+  (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,
+);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function computeValueRange(model: BarChartModel): {
+  valueMin: number;
+  valueMax: number;
+} {
+  // Prefer explicit axis min/max when provided.
+  if (model.valueAxis.min !== undefined && model.valueAxis.max !== undefined) {
+    return { valueMin: model.valueAxis.min, valueMax: model.valueAxis.max };
+  }
+  if (model.grouping === "percentStacked") {
+    return { valueMin: -100, 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 pos = 0;
+      let neg = 0;
+      for (const s of model.series) {
+        const v = s.values[c];
+        if (v === null || v === undefined || !Number.isFinite(v)) continue;
+        if (v >= 0) pos += v;
+        else neg += v;
+      }
+      if (pos > max) max = pos;
+      if (neg < min) min = neg;
+    }
+  } 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 computeClusteredBarWidth(
+  groupSize: number,
+  seriesCount: number,
+  overlapFrac: number,
+): number {
+  // barWidth × (seriesCount × (1 - overlap) + overlap) = groupSize.
+  // Solve: barWidth = groupSize / (seriesCount - (seriesCount - 1) × overlap).
+  const denom = seriesCount - (seriesCount - 1) * overlapFrac;
+  return denom > 0 ? groupSize / denom : groupSize / Math.max(1, seriesCount);
+}
+
+function computeSlotAbsTotal(series: Series[], categoryIdx: number): number {
+  let total = 0;
+  for (const s of series) {
+    const v = s.values[categoryIdx];
+    if (v === null || v === undefined || !Number.isFinite(v)) continue;
+    total += Math.abs(v);
+  }
+  return total;
+}
+
+function emitStackedSlot(
+  out: React.ReactElement[],
+  model: BarChartModel,
+  theme: ResolvedTheme | undefined,
+  defs: DefsRegistry,
+  c: number,
+  slotSize: number,
+  groupSize: number,
+  plot: { x: number; y: number; w: number; h: number },
+  horizontal: boolean,
+  normalizePositive: (v: number) => number,
+  _normalizeNegative: (v: number) => number,
+  _axisMax: number,
+  _axisMin: number,
+  valueToPlot: (v: number) => number,
+): void {
+  const slotStart = (horizontal ? plot.y : plot.x) + c * slotSize;
+  const groupStart = slotStart + (slotSize - groupSize) / 2;
+  let posBase = 0;
+  let negBase = 0;
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const raw = series.values[c];
+    if (raw === null || raw === undefined || !Number.isFinite(raw)) continue;
+    const v = normalizePositive(raw);
+    const base = v >= 0 ? posBase : negBase;
+    const end = base + v;
+    const color = resolveBarColor(model, theme, s, c, series, defs);
+    const originPlot = valueToPlot(base);
+    const endPlot = valueToPlot(end);
+    const rect = horizontal
+      ? {
+          x: Math.min(originPlot, endPlot),
+          y: groupStart,
+          w: Math.abs(endPlot - originPlot),
+          h: groupSize,
+        }
+      : {
+          x: groupStart,
+          y: Math.min(originPlot, endPlot),
+          w: groupSize,
+          h: Math.abs(endPlot - originPlot),
+        };
+    out.push(
+      <rect
+        key={`stack-${s}-${c}`}
+        x={rect.x}
+        y={rect.y}
+        width={rect.w}
+        height={rect.h}
+        fill={color}
+        data-role="bar"
+        data-series-index={s}
+        data-category-index={c}
+      />,
+    );
+    if (v >= 0) posBase += v;
+    else negBase += v;
+  }
+}
+
+function resolveBarColor(
+  model: BarChartModel,
+  theme: ResolvedTheme | undefined,
+  seriesIdx: number,
+  categoryIdx: number,
+  series: Series,
+  defs: DefsRegistry,
+): string {
+  // Per-point override wins.
+  const dPt = findDataPointOverride(series.dataPoints, categoryIdx);
+  if (dPt?.spPr?.fill) {
+    return resolveFill(dPt.spPr.fill, theme, defs);
+  }
+  return composeSeriesColor(model, theme ?? { colors: {} }, seriesIdx);
+}
+
+function findDataPointOverride(
+  dPts: DataPointOverride[] | undefined,
+  categoryIdx: number,
+): DataPointOverride | undefined {
+  if (!dPts) return undefined;
+  for (const d of dPts) if (d.idx === categoryIdx) return d;
+  return undefined;
+}
+
+function seriesInvertsIfNegative(series: Series): boolean {
+  // The parser doesn't set this per-series yet; we inspect dataPoints[0] as
+  // a proxy since invertIfNegative is recorded at the data-point level.
+  if (!series.dataPoints) return false;
+  return series.dataPoints.some((d) => d.invertIfNegative);
+}
+
+/**
+ * Blend a hex color towards white. Used for `invertIfNegative` Word
+ * styling. 0 = no change, 1 = pure white.
+ */
+function lightenHex(hex: string, frac: number): string {
+  const m = /^#?([0-9A-Fa-f]{6})$/.exec(hex);
+  if (!m) return hex;
+  const raw = m[1]!;
+  const r = parseInt(raw.slice(0, 2), 16);
+  const g = parseInt(raw.slice(2, 4), 16);
+  const b = parseInt(raw.slice(4, 6), 16);
+  const rr = Math.round(r + (255 - r) * frac);
+  const gg = Math.round(g + (255 - g) * frac);
+  const bb = Math.round(b + (255 - b) * frac);
+  const toHex = (n: number) => n.toString(16).padStart(2, "0").toUpperCase();
+  return `#${toHex(rr)}${toHex(gg)}${toHex(bb)}`;
+}