@beyondwork/docx-react-component 1.0.52 → 1.0.54

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

@@ -0,0 +1,275 @@
+/**
+ * Pie / doughnut chart renderer (Stage 4 Slice 4C, B6).
+ *
+ * Each slice is rendered as an SVG arc path. Doughnuts punch an inner
+ * circular void via `holeSizePercent`. Per-slice `explosion` offsets
+ * the slice radially along its bisector.
+ *
+ * Angle conventions (B6):
+ *   - OOXML's `c:firstSliceAngle` is degrees clockwise from 12 o'clock.
+ *   - SVG's math convention is counter-clockwise from 3 o'clock.
+ *   - Conversion: `svgDeg = wordDeg - 90`.
+ *
+ * `varyColors`:
+ *   - `true` (Word pie default): each slice draws from the chart-style
+ *     palette via `paletteColorRef(seriesColorMode, sliceIdx)` +
+ *     `resolveColor(ref, theme)`.
+ *   - `false`: every slice shares the series color.
+ *
+ * Zero or negative values render no slice (pies reject negatives per
+ * Word's observed behavior).
+ */
+
+import React from "react";
+import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import { paletteColorRef } from "../../../io/ooxml/chart/color-palette.ts";
+import { resolveColor } from "../../../io/ooxml/chart/resolve-color.ts";
+import {
+  getChartStyle,
+  resolveChartStyleId,
+} from "../../../io/ooxml/chart/chart-style-table.ts";
+import type {
+  DataPointOverride,
+  PieChartModel,
+  PieSeries,
+} from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+import { DefsRegistry, resolveFill } from "./svg-primitives.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface PieChartProps {
+  model: PieChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+  defs?: DefsRegistry;
+}
+
+function PieChartImpl({ model, layout, theme, defs }: PieChartProps): React.ReactElement {
+  const defsRegistry = defs ?? new DefsRegistry();
+  const plot = layout.plotRect;
+
+  const series = model.series[0];
+  if (!series) {
+    return <g data-role="pie-chart" data-empty="true" />;
+  }
+
+  // --- Pie geometry ---
+  const cx = plot.x + plot.w / 2;
+  const cy = plot.y + plot.h / 2;
+  const rOuter = Math.max(0, Math.min(plot.w, plot.h) / 2);
+  const rInner = model.doughnut
+    ? (rOuter * Math.max(10, Math.min(90, model.holeSizePercent ?? 50))) / 100
+    : 0;
+
+  // --- Compute slice angles ---
+  const values = series.values;
+  const total = values.reduce<number>((sum, v) => {
+    if (v === null || v === undefined || !Number.isFinite(v) || v <= 0) return sum;
+    return sum + v;
+  }, 0);
+
+  if (total === 0) {
+    return <g data-role="pie-chart" data-empty="true" />;
+  }
+
+  // --- B6 angle conversion ---
+  const startDegWord = model.firstSliceAngle ?? 0;
+  let currentAngleWord = startDegWord;
+
+  const slices: React.ReactElement[] = [];
+  const palette = computePalette(model);
+
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (v === null || v === undefined || !Number.isFinite(v) || v <= 0) continue;
+    const sweep = (v / total) * 360;
+    const startWord = currentAngleWord;
+    const endWord = currentAngleWord + sweep;
+    currentAngleWord = endWord;
+
+    const color = resolveSliceColor(model, theme, series, i, palette, defsRegistry);
+
+    const explosionPct = resolveExplosion(series, i);
+    const midWord = (startWord + endWord) / 2;
+    const { cx: ecx, cy: ecy } = applyExplosion(cx, cy, rOuter, midWord, explosionPct);
+
+    const d = buildSlicePath(ecx, ecy, rOuter, rInner, startWord, endWord);
+    slices.push(
+      <path
+        key={`slice-${i}`}
+        d={d}
+        fill={color}
+        data-role="slice"
+        data-slice-index={i}
+      />,
+    );
+  }
+
+  return (
+    <g data-role="pie-chart" data-doughnut={model.doughnut} data-vary-colors={model.varyColors}>
+      <g data-role="slices">{slices}</g>
+      <g data-role="data-labels" />
+    </g>
+  );
+}
+
+export const PieChart = React.memo(
+  PieChartImpl,
+  (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,
+);
+
+// ---------------------------------------------------------------------------
+// Geometry helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert an OOXML "clockwise from 12 o'clock" degree angle to SVG
+ * math-convention "counter-clockwise from 3 o'clock" radians (B6).
+ *
+ * Word: 0° → top; 90° → right; 180° → bottom; 270° → left.
+ * SVG pixel space: +x right, +y down. To place points correctly we
+ * compute `cos`/`sin` with (wordDeg - 90) degrees — this preserves the
+ * clockwise direction visually because pixel y grows downward.
+ */
+function polarToCartesian(
+  cx: number,
+  cy: number,
+  r: number,
+  wordDeg: number,
+): { x: number; y: number } {
+  const svgDeg = wordDeg - 90;
+  const rad = (svgDeg * Math.PI) / 180;
+  return {
+    x: cx + r * Math.cos(rad),
+    y: cy + r * Math.sin(rad),
+  };
+}
+
+/**
+ * Build the SVG path d-string for a single slice.
+ *
+ * Pie (rInner=0):   `M cx cy L p0 A r r 0 large 1 p1 Z`
+ * Doughnut (rInner>0):
+ *                   `M p0Outer A rOut rOut 0 large 1 p1Outer L p1Inner
+ *                    A rIn rIn 0 large 0 p0Inner Z`
+ *
+ * The large-arc flag is `1` when the slice sweeps > 180°.
+ * The sweep flag is `1` for the outer arc (clockwise in SVG), `0` for
+ * the inner arc (reverse direction to close the annulus correctly).
+ */
+function buildSlicePath(
+  cx: number,
+  cy: number,
+  rOuter: number,
+  rInner: number,
+  startWord: number,
+  endWord: number,
+): string {
+  const sweep = endWord - startWord;
+  const largeArc = sweep > 180 ? 1 : 0;
+  const p0Outer = polarToCartesian(cx, cy, rOuter, startWord);
+  const p1Outer = polarToCartesian(cx, cy, rOuter, endWord);
+
+  if (rInner <= 0) {
+    // Full pie slice.
+    return (
+      `M ${fmt(cx)} ${fmt(cy)} ` +
+      `L ${fmt(p0Outer.x)} ${fmt(p0Outer.y)} ` +
+      `A ${fmt(rOuter)} ${fmt(rOuter)} 0 ${largeArc} 1 ${fmt(p1Outer.x)} ${fmt(p1Outer.y)} Z`
+    );
+  }
+
+  // Doughnut slice: outer arc forward, inner arc backward.
+  const p0Inner = polarToCartesian(cx, cy, rInner, startWord);
+  const p1Inner = polarToCartesian(cx, cy, rInner, endWord);
+  return (
+    `M ${fmt(p0Outer.x)} ${fmt(p0Outer.y)} ` +
+    `A ${fmt(rOuter)} ${fmt(rOuter)} 0 ${largeArc} 1 ${fmt(p1Outer.x)} ${fmt(p1Outer.y)} ` +
+    `L ${fmt(p1Inner.x)} ${fmt(p1Inner.y)} ` +
+    `A ${fmt(rInner)} ${fmt(rInner)} 0 ${largeArc} 0 ${fmt(p0Inner.x)} ${fmt(p0Inner.y)} Z`
+  );
+}
+
+/**
+ * Offset a slice center radially outward along its bisector by the
+ * explosion percentage (0 = no offset, 100 = push out by full radius;
+ * Word visually caps the real-rendered effect at ~35% of radius).
+ */
+function applyExplosion(
+  cx: number,
+  cy: number,
+  rOuter: number,
+  midAngleWord: number,
+  explosionPct: number,
+): { cx: number; cy: number } {
+  if (explosionPct === 0) return { cx, cy };
+  const dist = rOuter * Math.min(1, explosionPct / 100) * 0.35;
+  const p = polarToCartesian(0, 0, dist, midAngleWord);
+  return { cx: cx + p.x, cy: cy + p.y };
+}
+
+// ---------------------------------------------------------------------------
+// Color & explosion resolution
+// ---------------------------------------------------------------------------
+
+function computePalette(
+  model: PieChartModel,
+): (sliceIdx: number) => string | null {
+  // Returns null to indicate "fall through to series color" when
+  // varyColors is false and no palette path is taken.
+  const style = getChartStyle(resolveChartStyleId(model.styleId));
+  const mode = style.seriesColorMode;
+  return (sliceIdx: number) => paletteColorRef(mode, sliceIdx).kind === "scheme" ? null : null;
+}
+
+function resolveSliceColor(
+  model: PieChartModel,
+  theme: ResolvedTheme | undefined,
+  series: PieSeries,
+  sliceIdx: number,
+  _palette: (i: number) => string | null,
+  defs: DefsRegistry,
+): string {
+  // Per-slice dPt override wins.
+  const dPt = findDataPointOverride(series.dataPoints, sliceIdx);
+  if (dPt?.spPr?.fill) {
+    return resolveFill(dPt.spPr.fill, theme, defs);
+  }
+  if (model.varyColors) {
+    // Per-slice palette color.
+    const style = getChartStyle(resolveChartStyleId(model.styleId));
+    const ref = paletteColorRef(style.seriesColorMode, sliceIdx);
+    return resolveColor(ref, theme ?? { colors: {} });
+  }
+  // Single series color.
+  return composeSeriesColor(model, theme ?? { colors: {} }, 0);
+}
+
+function resolveExplosion(series: PieSeries, sliceIdx: number): number {
+  const dPt = findDataPointOverride(series.dataPoints, sliceIdx);
+  if (dPt?.explosion !== undefined) return dPt.explosion;
+  return series.explosion ?? 0;
+}
+
+function findDataPointOverride(
+  dPts: DataPointOverride[] | undefined,
+  idx: number,
+): DataPointOverride | undefined {
+  if (!dPts) return undefined;
+  for (const d of dPts) if (d.idx === idx) return d;
+  return undefined;
+}
+
+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/progressive-render.ts

@@ -0,0 +1,103 @@
+/**
+ * Progressive rendering hook for large chart datasets (Stage 5).
+ *
+ * Charts with ≤ PROGRESSIVE_THRESHOLD data points render all points
+ * synchronously. Larger charts start by rendering the first threshold points
+ * and advance in PROGRESSIVE_BATCH_SIZE increments per idle tick so the
+ * main thread stays responsive (no web workers — platform constraint).
+ *
+ * In SSR / Node.js test environments (no `document`) all points are returned
+ * immediately so `renderToStaticMarkup` produces a complete SVG.
+ *
+ * Scheduling: prefers `requestIdleCallback` (chromium, Safari 17+) with a
+ * 100 ms deadline, falls back to `setTimeout(0)` for Firefox / older Safari.
+ */
+
+import { useReducer, useEffect } from "react";
+
+// ---------------------------------------------------------------------------
+// Constants (exported so callers can reference them in assertions)
+// ---------------------------------------------------------------------------
+
+/** Maximum data-point count that renders synchronously (≤ this → no chunking). */
+export const PROGRESSIVE_THRESHOLD = 500;
+
+/** Points added per idle tick when total count exceeds PROGRESSIVE_THRESHOLD. */
+export const PROGRESSIVE_BATCH_SIZE = 100;
+
+// ---------------------------------------------------------------------------
+// SSR detection (evaluated once at module load — stable across renders)
+// ---------------------------------------------------------------------------
+
+/**
+ * True when running in a browser environment. In SSR / Node.js test
+ * environments this is false and `useProgressiveCount` returns `totalCount`
+ * immediately.
+ */
+export const IS_BROWSER: boolean =
+  typeof document !== "undefined" && typeof window !== "undefined";
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+type Action =
+  | { type: "advance"; to: number }
+  | { type: "reset"; initialCount: number };
+
+function countReducer(_state: number, action: Action): number {
+  switch (action.type) {
+    case "advance":
+      return action.to;
+    case "reset":
+      return action.initialCount;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the number of data points to render in the current React frame.
+ *
+ * Usage in a chart renderer:
+ * ```tsx
+ * const visibleCount = useProgressiveCount(categoryCount);
+ * for (let c = 0; c < visibleCount; c++) { ... }
+ * ```
+ *
+ * @param totalCount - Total number of data points to eventually render.
+ * @param threshold  - Points below this count render synchronously (default: 500).
+ * @param batchSize  - Points added per idle tick above the threshold (default: 100).
+ */
+export function useProgressiveCount(
+  totalCount: number,
+  threshold = PROGRESSIVE_THRESHOLD,
+  batchSize = PROGRESSIVE_BATCH_SIZE,
+): number {
+  const initialCount = IS_BROWSER ? Math.min(threshold, totalCount) : totalCount;
+
+  const [visibleCount, dispatch] = useReducer(countReducer, initialCount);
+
+  useEffect(() => {
+    // SSR or already fully rendered — nothing to schedule.
+    if (!IS_BROWSER || visibleCount >= totalCount) return;
+
+    const next = Math.min(visibleCount + batchSize, totalCount);
+
+    if (typeof requestIdleCallback !== "undefined") {
+      const h = requestIdleCallback(
+        () => dispatch({ type: "advance", to: next }),
+        { timeout: 100 },
+      );
+      return () => cancelIdleCallback(h);
+    } else {
+      const h = setTimeout(() => dispatch({ type: "advance", to: next }), 0);
+      return () => clearTimeout(h);
+    }
+  }, [visibleCount, totalCount, batchSize]);
+
+  // Guard: if totalCount shrinks (e.g. model update) clamp to valid range.
+  return Math.min(visibleCount, totalCount);
+}

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

@@ -0,0 +1,228 @@
+/**
+ * Scatter chart renderer (Stage 4 Slice 4E).
+ *
+ * Scatter charts use numeric (value) x-axis, unlike bar/line/area which
+ * use categorical x-axes. Supports 5 scatter styles (OOXML `c:scatterStyle`):
+ *
+ *   - `"line"`         — connected polyline, no markers.
+ *   - `"lineMarker"`   — connected polyline + markers at each point.
+ *   - `"marker"`       — markers only (default scatter appearance).
+ *   - `"smooth"`       — smoothed line through points, no markers.
+ *   - `"smoothMarker"` — smoothed line + markers.
+ *
+ * Null x or y values skip that data point.
+ */
+
+import React from "react";
+import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import type {
+  ScatterChartModel,
+  ScatterSeries,
+  MarkerSpec,
+} from "../../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { PlotAreaLayout } from "../layout/plot-area.ts";
+import { smoothPath, type Point } from "./smooth-curve.ts";
+import { useProgressiveCount } from "./progressive-render.ts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ScatterChartProps {
+  model: ScatterChartModel;
+  layout: PlotAreaLayout;
+  theme: ResolvedTheme | undefined;
+}
+
+function ScatterChartImpl({ model, layout, theme }: ScatterChartProps): React.ReactElement {
+  const plot = layout.plotRect;
+  const { xMin, xMax, yMin, yMax } = computeRange(model);
+  const xSpan = Math.max(1e-9, xMax - xMin);
+  const ySpan = Math.max(1e-9, yMax - yMin);
+
+  const totalPoints = Math.max(0, ...model.series.map(s => s.xValues.length));
+  const visiblePoints = useProgressiveCount(totalPoints);
+
+  const toPoint = (x: number, y: number): Point => [
+    plot.x + ((x - xMin) / xSpan) * plot.w,
+    plot.y + plot.h - ((y - yMin) / ySpan) * plot.h,
+  ];
+
+  const style = model.style;
+  const showLine = style === "line" || style === "lineMarker" || style === "smooth" || style === "smoothMarker";
+  const smooth = style === "smooth" || style === "smoothMarker";
+  const showMarkers = style === "marker" || style === "lineMarker" || style === "smoothMarker";
+
+  const lines: React.ReactElement[] = [];
+  const markers: React.ReactElement[] = [];
+
+  for (let s = 0; s < model.series.length; s++) {
+    const series = model.series[s]!;
+    const color = composeSeriesColor(model, theme ?? { colors: {} }, s);
+    const points = collectPoints(series, toPoint, visiblePoints);
+    if (points.length === 0) continue;
+
+    if (showLine && points.length >= 2) {
+      const d = smooth ? smoothPath(points) : polylinePath(points);
+      lines.push(
+        <path
+          key={`scatter-line-${s}`}
+          d={d}
+          fill="none"
+          stroke={color}
+          strokeWidth={2}
+          data-role="scatter-line"
+          data-series-index={s}
+        />,
+      );
+    }
+
+    if (showMarkers) {
+      for (const [i, pt] of points.entries()) {
+        markers.push(
+          renderMarker({
+            key: `m-${s}-${i}`,
+            spec: series.marker,
+            point: pt,
+            color,
+            seriesIdx: s,
+            dataIdx: i,
+          }),
+        );
+      }
+    }
+  }
+
+  return (
+    <g data-role="scatter-chart" data-style={style}>
+      <g data-role="scatter-lines">{lines}</g>
+      <g data-role="markers">{markers}</g>
+      <g data-role="data-labels" />
+    </g>
+  );
+}
+
+export const ScatterChart = React.memo(
+  ScatterChartImpl,
+  (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 computeRange(model: ScatterChartModel): {
+  xMin: number; xMax: number; yMin: number; yMax: number;
+} {
+  const xAxisMin = model.xAxis.min;
+  const xAxisMax = model.xAxis.max;
+  const yAxisMin = model.yAxis.min;
+  const yAxisMax = model.yAxis.max;
+  if (
+    xAxisMin !== undefined && xAxisMax !== undefined &&
+    yAxisMin !== undefined && yAxisMax !== undefined
+  ) {
+    return { xMin: xAxisMin, xMax: xAxisMax, yMin: yAxisMin, yMax: yAxisMax };
+  }
+  let xMin = Infinity, xMax = -Infinity;
+  let yMin = Infinity, yMax = -Infinity;
+  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];
+      if (x === null || y === null || !Number.isFinite(x) || !Number.isFinite(y)) continue;
+      if (x < xMin) xMin = x;
+      if (x > xMax) xMax = x;
+      if (y < yMin) yMin = y;
+      if (y > yMax) yMax = y;
+    }
+  }
+  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 };
+}
+
+function collectPoints(
+  series: ScatterSeries,
+  toPoint: (x: number, y: number) => Point,
+  limit = Infinity,
+): Point[] {
+  const out: Point[] = [];
+  const n = Math.min(series.xValues.length, series.yValues.length, limit);
+  for (let i = 0; i < n; i++) {
+    const x = series.xValues[i];
+    const y = series.yValues[i];
+    if (x === null || y === null || !Number.isFinite(x) || !Number.isFinite(y)) continue;
+    out.push(toPoint(x, y));
+  }
+  return out;
+}
+
+function polylinePath(points: ReadonlyArray<Point>): string {
+  if (points.length === 0) return "";
+  let d = `M ${points[0]![0]} ${points[0]![1]}`;
+  for (let i = 1; i < points.length; i++) {
+    d += ` L ${points[i]![0]} ${points[i]![1]}`;
+  }
+  return d;
+}
+
+interface MarkerRenderInput {
+  key: string;
+  spec: MarkerSpec | undefined;
+  point: Point;
+  color: string;
+  seriesIdx: number;
+  dataIdx: number;
+}
+
+function renderMarker({ key, spec, point, color, seriesIdx, dataIdx }: MarkerRenderInput): React.ReactElement {
+  const symbol = spec?.symbol && spec.symbol !== "auto" ? spec.symbol : "circle";
+  const size = spec?.size ?? 5;
+  const [cx, cy] = point;
+  const shared = {
+    fill: color,
+    stroke: color,
+    strokeWidth: 1,
+    "data-role": "marker",
+    "data-series-index": seriesIdx,
+    "data-point-index": dataIdx,
+  } as const;
+
+  switch (symbol) {
+    case "square":
+      return <rect key={key} x={cx - size / 2} y={cy - size / 2} width={size} height={size} {...shared} />;
+    case "diamond":
+      return <polygon key={key} points={`${cx},${cy - size / 2} ${cx + size / 2},${cy} ${cx},${cy + size / 2} ${cx - size / 2},${cy}`} {...shared} />;
+    case "triangle":
+      return <polygon key={key} points={`${cx},${cy - size / 2} ${cx + size / 2},${cy + size / 2} ${cx - size / 2},${cy + size / 2}`} {...shared} />;
+    case "x":
+    case "plus": {
+      const half = size / 2;
+      const rot = symbol === "x" ? 45 : 0;
+      return (
+        <g key={key} transform={rot === 0 ? undefined : `rotate(${rot} ${cx} ${cy})`} data-role="marker" data-series-index={seriesIdx} data-point-index={dataIdx}>
+          <line x1={cx - half} y1={cy} x2={cx + half} y2={cy} stroke={color} strokeWidth={1.5} />
+          <line x1={cx} y1={cy - half} x2={cx} y2={cy + half} stroke={color} strokeWidth={1.5} />
+        </g>
+      );
+    }
+    case "dot":
+      return <circle key={key} cx={cx} cy={cy} r={Math.max(1, size / 4)} {...shared} />;
+    case "dash":
+      return <line key={key} x1={cx - size / 2} y1={cy} x2={cx + size / 2} y2={cy} stroke={color} strokeWidth={2} data-role="marker" data-series-index={seriesIdx} data-point-index={dataIdx} />;
+    case "star":
+    case "picture":
+    case "circle":
+    case "none":
+    default:
+      return <circle key={key} cx={cx} cy={cy} r={size / 2} {...shared} />;
+  }
+}