@beyondwork/docx-react-component 1.0.52 → 1.0.54

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

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

@@ -0,0 +1,134 @@
+/**
+ * Bubble chart renderer (Stage 4 Slice 4E).
+ *
+ * Each data point is drawn as a circle whose radius is proportional to
+ * `sqrt(|size|)` (the classic bubble scaling that maps size → area).
+ * Null x/y/size values skip the point. Negative sizes use |size|
+ * (matching Excel's observed behavior).
+ *
+ * `bubble3D` is collapsed to 2D per the lane non-goal.
+ */
+
+import React from "react";
+import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import type {
+  BubbleChartModel,
+  BubbleSeries,
+} from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface BubbleChartProps {
+  model: BubbleChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+}
+
+function BubbleChartImpl({ model, layout, theme }: BubbleChartProps): React.ReactElement {
+  const plot = layout.plotRect;
+  const { xMin, xMax, yMin, yMax, maxSize } = computeRange(model);
+  const xSpan = Math.max(1e-9, xMax - xMin);
+  const ySpan = Math.max(1e-9, yMax - yMin);
+
+  // Max bubble radius = ~6% of the smaller plot dimension so bubbles
+  // don't dominate.  Scale radius linearly with sqrt(size).
+  const maxRadius = Math.max(4, Math.min(plot.w, plot.h) * 0.06);
+  const sizeScaleFactor = maxSize > 0 ? maxRadius / Math.sqrt(maxSize) : 0;
+
+  const bubbles: React.ReactElement[] = [];
+
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const color = composeSeriesColor(model, theme ?? { colors: {} }, s);
+    const n = Math.min(series.xValues.length, series.yValues.length, series.sizes.length);
+    for (let i = 0; i < n; i++) {
+      const x = series.xValues[i];
+      const y = series.yValues[i];
+      const size = series.sizes[i];
+      if (
+        x === null || y === null || size === null ||
+        !Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(size)
+      ) continue;
+      const cx = plot.x + ((x - xMin) / xSpan) * plot.w;
+      const cy = plot.y + plot.h - ((y - yMin) / ySpan) * plot.h;
+      const r = Math.sqrt(Math.abs(size)) * sizeScaleFactor * (series.bubbleScale ?? 1);
+      bubbles.push(
+        <circle
+          key={`bubble-${s}-${i}`}
+          cx={cx}
+          cy={cy}
+          r={Math.max(1, r)}
+          fill={color}
+          fillOpacity={0.7}
+          stroke={color}
+          strokeWidth={1}
+          data-role="bubble"
+          data-series-index={s}
+          data-point-index={i}
+        />,
+      );
+    }
+  }
+
+  return (
+    <g data-role="bubble-chart" data-bubble3d={model.bubble3D}>
+      <g data-role="bubbles">{bubbles}</g>
+      <g data-role="data-labels" />
+    </g>
+  );
+}
+
+export const BubbleChart = React.memo(
+  BubbleChartImpl,
+  (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,
+);
+
+// ---------------------------------------------------------------------------
+// Range computation
+// ---------------------------------------------------------------------------
+
+function computeRange(model: BubbleChartModel): {
+  xMin: number; xMax: number; yMin: number; yMax: number; maxSize: number;
+} {
+  const ax = model.xAxis;
+  const ay = model.yAxis;
+  let xMin = ax.min ?? Infinity;
+  let xMax = ax.max ?? -Infinity;
+  let yMin = ay.min ?? Infinity;
+  let yMax = ay.max ?? -Infinity;
+  let maxSize = 0;
+  const dataFillX = ax.min === undefined || ax.max === undefined;
+  const dataFillY = ay.min === undefined || ay.max === undefined;
+
+  for (const s of model.series) {
+    for (let i = 0; i < s.xValues.length; i++) {
+      const x = s.xValues[i];
+      const y = s.yValues[i];
+      const size = s.sizes[i];
+      if (x === null || y === null || size === null) continue;
+      if (dataFillX) {
+        if (x < xMin) xMin = x;
+        if (x > xMax) xMax = x;
+      }
+      if (dataFillY) {
+        if (y < yMin) yMin = y;
+        if (y > yMax) yMax = y;
+      }
+      const absSize = Math.abs(size);
+      if (absSize > maxSize) maxSize = absSize;
+    }
+  }
+  if (!Number.isFinite(xMin)) xMin = 0;
+  if (!Number.isFinite(xMax)) xMax = 1;
+  if (!Number.isFinite(yMin)) yMin = 0;
+  if (!Number.isFinite(yMax)) yMax = 1;
+  return { xMin, xMax, yMin, yMax, maxSize };
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Combo chart renderer (Stage 4 Slice 4F).
+ *
+ * Combo charts pack multiple chart-type groups (bar/line/area) into a
+ * single plot area. Each group is a full `BarChartModel`,
+ * `LineChartModel`, or `AreaChartModel` that was produced by the
+ * parser with per-group axis objects (already cloned by
+ * `parse-chart-space.ts` so mutation in one group doesn't bleed into
+ * another).
+ *
+ * Draw order: groups render in declaration order so later groups
+ * visually stack on top. The convention is bar → line (line renders
+ * atop bar), which matches Word's observed behavior when a combo's
+ * type-group nodes appear in XML order.
+ *
+ * Secondary axes: when a group has `secondaryValueAxis`, its bars /
+ * lines project onto the secondary scale. Because per-group renderers
+ * already honor `valueAxis.min/max` when computing their range, this
+ * works without special wiring — the combo just hands each group its
+ * own layout and model.
+ */
+
+import React from "react";
+import type { ComboChartModel } from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+import { BarColumnChart } from "./bar-column.tsx";
+import { LineChart } from "./line.tsx";
+import { AreaChart } from "./area.tsx";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ComboChartProps {
+  model: ComboChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+}
+
+function ComboChartImpl({ model, layout, theme }: ComboChartProps): React.ReactElement {
+  // Groups render in declaration order → last group paints on top.
+  return (
+    <g
+      data-role="combo-chart"
+      data-group-count={model.groups.length}
+      data-has-secondary-axis={model.hasSecondaryAxis}
+    >
+      {model.groups.map((group, i) => (
+        <g key={`combo-group-${i}`} data-role="combo-group" data-group-index={i}>
+          {renderGroup(group, layout, theme)}
+        </g>
+      ))}
+      <g data-role="data-labels" />
+    </g>
+  );
+}
+
+export const ComboChart = React.memo(
+  ComboChartImpl,
+  (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,
+);
+
+// ---------------------------------------------------------------------------
+// Group dispatch
+// ---------------------------------------------------------------------------
+
+function renderGroup(
+  group: ComboChartModel["groups"][number],
+  layout: PlotAreaLayout,
+  theme: ResolvedTheme | undefined,
+): React.ReactElement {
+  switch (group.kind) {
+    case "bar":
+      return <BarColumnChart model={group} layout={layout} theme={theme} />;
+    case "line":
+      return <LineChart model={group} layout={layout} theme={theme} />;
+    case "area":
+      return <AreaChart model={group} layout={layout} theme={theme} />;
+  }
+}