@beyondwork/docx-react-component 1.0.58 → 1.0.59

package/src/model/chart-types.ts

@@ -0,0 +1,439 @@
+/**
+ * Chart data-model types (Stage 1).
+ *
+ * Pure type declarations. No runtime code, no imports from runtime modules.
+ * `ChartModel` is a discriminated union (by `kind`) covering every chart
+ * family we parse or intentionally mark as unsupported. Parsed models retain
+ * the source XML in `rawXml` so the export path (which re-emits the
+ * original drawing verbatim) stays byte-identical regardless of renderer
+ * coverage.
+ *
+ * Stage 2 will add the theme/colors/style cascade that turns `ColorRef`
+ * values into concrete sRGB strings. Until then, colors are declared as
+ * references; consumers of Stage 1 models should treat color resolution as
+ * "not yet available."
+ *
+ * See docs/plans/lane-5-charts.md §3 Task 1.1 for the full specification.
+ */
+
+// ---------------------------------------------------------------------------
+// Top-level union
+// ---------------------------------------------------------------------------
+
+export type ChartModel =
+  | BarChartModel
+  | LineChartModel
+  | PieChartModel
+  | AreaChartModel
+  | ScatterChartModel
+  | BubbleChartModel
+  | ComboChartModel
+  | UnsupportedChartModel;
+
+export interface ChartCommon {
+  /** Chart title, if present. */
+  title?: Title;
+  /** Legend configuration; absent if the chart has no legend. */
+  legend?: Legend;
+  /** Whether to plot only visible cells (c:plotVisOnly). */
+  plotVisOnly: boolean;
+  /** How to render blank/null values (c:dispBlanksAs). */
+  dispBlanksAs: "gap" | "zero" | "span";
+  /** Legacy chart style id (c:style val, 1–48), if present. */
+  styleId?: number;
+  /** Theme color scheme slot names available to this chart (accent1..6 etc.). */
+  themeColorScheme?: string[];
+  /**
+   * The raw chart-space XML that produced this model. Preserved so the
+   * export path can re-emit the original drawing without depending on the
+   * renderer's coverage of a given chart family.
+   */
+  rawXml: string;
+}
+
+/**
+ * Category-like axis binding for bar/line/area charts. Date axes are a
+ * legal substitute for a category axis at the XML level (c:dateAx replaces
+ * c:catAx) and we preserve the kind here so the renderer can format
+ * category labels as dates when the source authored them that way.
+ */
+export type CategoryLikeAxis = CategoryAxis | DateAxis;
+
+export interface BarChartModel extends ChartCommon {
+  kind: "bar";
+  /** "bar" = horizontal; "column" = vertical. */
+  direction: "bar" | "column";
+  grouping: "clustered" | "stacked" | "percentStacked" | "standard";
+  /** Gap between categories in percent of bar width (c:gapWidth). */
+  gapWidth: number;
+  /** Overlap within a category in percent, -100..100 (c:overlap). */
+  overlap: number;
+  series: Series[];
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  /** Present when any series/group targeted the secondary axis. */
+  secondaryValueAxis?: ValueAxis;
+}
+
+export interface LineChartModel extends ChartCommon {
+  kind: "line";
+  grouping: "standard" | "stacked" | "percentStacked";
+  /** Global smooth flag; per-series values can override. */
+  smooth: boolean;
+  /** Global marker flag; per-series values can override. */
+  marker: boolean;
+  series: LineSeries[];
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  secondaryValueAxis?: ValueAxis;
+}
+
+export interface PieChartModel extends ChartCommon {
+  kind: "pie";
+  doughnut: boolean;
+  /** Doughnut hole size in percent, typical 10–75 (c:holeSize). */
+  holeSizePercent?: number;
+  /** Clockwise degrees from 12 o'clock, 0–360 (c:firstSliceAngle / 60000). */
+  firstSliceAngle: number;
+  varyColors: boolean;
+  /** Almost always one series; pie-of-pie is length 2 (deferred). */
+  series: PieSeries[];
+  /** Category labels (from the first series' c:cat). */
+  categoryLabels: string[];
+}
+
+export interface AreaChartModel extends ChartCommon {
+  kind: "area";
+  grouping: "standard" | "stacked" | "percentStacked";
+  series: Series[];
+  categoryAxis: CategoryLikeAxis;
+  valueAxis: ValueAxis;
+  secondaryValueAxis?: ValueAxis;
+}
+
+export interface ScatterChartModel extends ChartCommon {
+  kind: "scatter";
+  style: "line" | "lineMarker" | "marker" | "smooth" | "smoothMarker";
+  series: ScatterSeries[];
+  /** Scatter uses a numeric x-axis, not a category axis. */
+  xAxis: ValueAxis;
+  yAxis: ValueAxis;
+}
+
+export interface BubbleChartModel extends ChartCommon {
+  kind: "bubble";
+  bubble3D: boolean;
+  series: BubbleSeries[];
+  xAxis: ValueAxis;
+  yAxis: ValueAxis;
+}
+
+export interface ComboChartModel extends ChartCommon {
+  kind: "combo";
+  /**
+   * Each type-group (bar/line/area) contributes its own series list. Axes
+   * may be shared or split into primary/secondary pairs.
+   */
+  groups: Array<BarChartModel | LineChartModel | AreaChartModel>;
+  /** True if any group targeted a secondary value axis. */
+  hasSecondaryAxis: boolean;
+}
+
+export interface UnsupportedChartModel extends ChartCommon {
+  kind: "unsupported";
+  reason: UnsupportedReason;
+  /** Human-readable detail (e.g. "Chart family lineChart not yet implemented"). */
+  detail: string;
+}
+
+/**
+ * Discriminator values for `UnsupportedChartModel.reason`.
+ *
+ * - `not-yet-implemented`: the parser recognises the chart family but a
+ *   subsequent slice is responsible for implementing it (line/pie/area/
+ *   scatter/bubble/combo in this slice).
+ * - `pivot`/`stock`/`surface`/…: families that are intentionally deferred
+ *   indefinitely per the plan's non-goals (rare in legal/finance corpora,
+ *   disproportionate renderer cost).
+ * - `no-plot-area`: the chart XML had no c:plotArea child.
+ * - `parse-error`: unexpected structure or exception during parse.
+ */
+export type UnsupportedReason =
+  | "not-yet-implemented"
+  | "pivot"
+  | "stock"
+  | "surface"
+  | "treemap"
+  | "sunburst"
+  | "histogram"
+  | "waterfall"
+  | "funnel"
+  | "map"
+  | "no-plot-area"
+  | "parse-error";
+
+// ---------------------------------------------------------------------------
+// Series
+// ---------------------------------------------------------------------------
+
+export interface SeriesBase {
+  /** c:idx — render order. */
+  idx: number;
+  /** c:order — data order. */
+  order: number;
+  /** Series display name (c:tx/c:strRef/c:strCache or c:v). */
+  name?: string;
+  /** Explicit fill/stroke overrides from c:spPr. */
+  spPr?: ShapeProperties;
+}
+
+export interface Series extends SeriesBase {
+  /** Category labels; string-form even when c:numRef was used. */
+  categories: string[];
+  /** Numeric values; `null` for blank/missing points (sparse cache). */
+  values: Array<number | null>;
+  dataLabels?: DataLabelsSpec;
+  /** Per-data-point overrides (c:dPt). */
+  dataPoints?: DataPointOverride[];
+}
+
+export interface LineSeries extends Series {
+  /** Per-series smooth override. */
+  smooth?: boolean;
+  marker?: MarkerSpec;
+}
+
+export interface PieSeries extends SeriesBase {
+  values: Array<number | null>;
+  /** Per-series default explosion percent. */
+  explosion?: number;
+  dataPoints?: DataPointOverride[];
+}
+
+export interface ScatterSeries extends SeriesBase {
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  smooth?: boolean;
+  marker?: MarkerSpec;
+}
+
+export interface BubbleSeries extends SeriesBase {
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  sizes: Array<number | null>;
+  bubbleScale?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Axes
+// ---------------------------------------------------------------------------
+
+export type Axis = CategoryAxis | ValueAxis | DateAxis | SeriesAxis;
+
+export interface AxisBase {
+  /** c:axId — unique within the plot area. */
+  id: string;
+  /** c:crossAx — the id of the perpendicular axis this one crosses. */
+  crossAxisId?: string;
+  /** Value at which the perpendicular axis crosses this one (c:crossesAt). */
+  crossesAt?: number | "autoZero" | "max" | "min";
+  /** c:axPos: b = bottom, t = top, l = left, r = right. */
+  position: "b" | "t" | "l" | "r";
+  /**
+   * Whether the axis is visible. Note: c:delete has inverted semantics —
+   * `val="1"` means invisible; we store the normal-sense boolean here.
+   */
+  visible: boolean;
+  title?: Title;
+  majorGridlines?: boolean;
+  minorGridlines?: boolean;
+  majorUnit?: number;
+  minorUnit?: number;
+  /** c:numFmt/@formatCode. */
+  numberFormat?: string;
+}
+
+export interface CategoryAxis extends AxisBase {
+  kind: "category";
+  /** c:auto — whether category width is chosen automatically. */
+  auto: boolean;
+  labelAlign?: "ctr" | "l" | "r";
+  labelOffset?: number;
+  tickMark?: "none" | "in" | "out" | "cross";
+  tickLabelSkip?: number;
+  tickMarkSkip?: number;
+  /** Category labels resolved from the first series' c:cat cache. */
+  categoryLabels: string[];
+}
+
+export interface ValueAxis extends AxisBase {
+  kind: "value";
+  min?: number;
+  max?: number;
+  logBase?: number;
+  /** True when c:scaling/c:orientation val="maxMin". */
+  reverse: boolean;
+  crossBetween?: "between" | "midCat";
+}
+
+export interface DateAxis extends AxisBase {
+  kind: "date";
+  baseTimeUnit?: "days" | "months" | "years";
+  /** Serial date (days since 1899-12-30). */
+  min?: number;
+  max?: number;
+  majorTimeUnit?: "days" | "months" | "years";
+  minorTimeUnit?: "days" | "months" | "years";
+}
+
+export interface SeriesAxis extends AxisBase {
+  kind: "series";
+}
+
+// ---------------------------------------------------------------------------
+// Other chart elements
+// ---------------------------------------------------------------------------
+
+export interface Title {
+  /**
+   * Plain-text rendering of the title. Rich-text formatting is not preserved
+   * at Stage 1; Stage 2/3 may extend this with per-run styling.
+   */
+  text?: string;
+  overlay: boolean;
+  spPr?: ShapeProperties;
+  txPr?: TextProperties;
+}
+
+export interface Legend {
+  position: "b" | "t" | "l" | "r" | "tr";
+  overlay: boolean;
+  spPr?: ShapeProperties;
+  txPr?: TextProperties;
+}
+
+export interface DataLabelsSpec {
+  showVal: boolean;
+  showCatName: boolean;
+  showSerName: boolean;
+  showPercent: boolean;
+  showBubbleSize: boolean;
+  showLegendKey: boolean;
+  position?: "b" | "ctr" | "l" | "r" | "t" | "bestFit" | "inBase" | "inEnd" | "outEnd";
+  separator?: string;
+  numberFormat?: string;
+  txPr?: TextProperties;
+}
+
+export interface MarkerSpec {
+  symbol:
+    | "circle"
+    | "square"
+    | "diamond"
+    | "triangle"
+    | "x"
+    | "star"
+    | "dot"
+    | "dash"
+    | "plus"
+    | "picture"
+    | "none"
+    | "auto";
+  /** Point size 2..72. */
+  size?: number;
+  spPr?: ShapeProperties;
+}
+
+export interface DataPointOverride {
+  /** Index of the data point within the series. */
+  idx: number;
+  spPr?: ShapeProperties;
+  marker?: MarkerSpec;
+  /** Pie only: per-slice explosion percent. */
+  explosion?: number;
+  /** Bar only: render negative values with inverted fill. */
+  invertIfNegative?: boolean;
+  /** Bubble only: 3D bubble flag (rendered as 2D regardless). */
+  bubble3D?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Shape / fill / stroke / color primitives
+// ---------------------------------------------------------------------------
+
+export interface ShapeProperties {
+  fill?: FillSpec;
+  stroke?: StrokeSpec;
+}
+
+export type FillSpec =
+  | { kind: "solid"; color: ColorRef }
+  | { kind: "gradient"; stops: Array<{ pos: number; color: ColorRef }>; angle?: number }
+  | { kind: "none" }
+  | { kind: "auto" };
+
+export interface StrokeSpec {
+  color?: ColorRef;
+  /** Stroke width in EMU (English Metric Units). */
+  widthEmu?: number;
+  dash?: "solid" | "dash" | "dashDot" | "lgDash" | "lgDashDot" | "sysDash" | "sysDashDot";
+  noFill?: boolean;
+}
+
+/**
+ * An unresolved color reference. Stage 2 adds `resolveColor(ref, theme)`
+ * which turns this into a concrete sRGB string via the chart-color cascade
+ * (explicit sRGB → scheme color → theme color scheme).
+ */
+export type ColorRef =
+  | { kind: "srgb"; value: string } // "#RRGGBB"
+  | { kind: "scheme"; value: string; mods?: ColorMod[] }
+  | { kind: "themeLinked"; value: string; mods?: ColorMod[] };
+
+export interface ColorMod {
+  kind: "lumMod" | "lumOff" | "shade" | "tint" | "satMod" | "hueMod" | "alpha";
+  /** Parts per 100,000 (OOXML convention). */
+  value: number;
+}
+
+export interface TextProperties {
+  fontFamily?: string;
+  fontSizePt?: number;
+  bold?: boolean;
+  italic?: boolean;
+  color?: ColorRef;
+}
+
+// ---------------------------------------------------------------------------
+// Exhaustiveness canary (compile-time only)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile-time assertion that `ChartModel["kind"]` equals the expected
+ * literal-union below. If a new variant is added to `ChartModel` without
+ * being listed in `_ExpectedKinds`, `_Equals` resolves to `false` and the
+ * subsequent `true` assignment fails at compile time. The previous
+ * dual-assign-cast pattern did not actually enforce union equality — any
+ * new kind silently passed through.
+ *
+ * Reference: the standard "exact type equality" trick using contravariance
+ * of conditional-type generic functions.
+ */
+type _Equals<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2)
+    ? true
+    : false;
+
+type _ExpectedKinds =
+  | "bar"
+  | "line"
+  | "pie"
+  | "area"
+  | "scatter"
+  | "bubble"
+  | "combo"
+  | "unsupported";
+
+type _ChartKindCheck = _Equals<ChartModel["kind"], _ExpectedKinds>;
+const _kindExhaustive: _ChartKindCheck = true;
+void _kindExhaustive;

package/src/model/snapshot.ts

@@ -30,7 +30,8 @@ export type EditorWarningCode =
   | "revision_anchor_detached"
   | "large_document_degraded"
   | "font_substitution"
-  | "image_missing";
+  | "image_missing"
+  | "review_target_not_found";
 
 export interface EditorWarning {
   warningId: string;
@@ -237,6 +238,7 @@ const EDITOR_WARNING_CODES = new Set<EditorWarningCode>([
   "large_document_degraded",
   "font_substitution",
   "image_missing",
+  "review_target_not_found",
 ]);
 const EDITOR_WARNING_SEVERITIES = new Set<EditorWarning["severity"]>(["info", "warning"]);
 const EDITOR_WARNING_SOURCES = new Set<EditorWarning["source"]>([

package/src/review/store/comment-remapping.ts

@@ -7,7 +7,10 @@ import {
   rangeStaysWithinCommentableStory,
   type ReviewAnchor,
 } from "../../core/selection/review-anchors.ts";
-import type { TransactionMapping } from "../../core/selection/mapping.ts";
+import {
+  anchorUnaffectedByMapping,
+  type TransactionMapping,
+} from "../../core/selection/mapping.ts";
 
 export interface RemapCommentThreadsOptions {
   comments: Record<string, CommentThreadRecord>;
@@ -25,12 +28,19 @@ export interface RemapCommentThreadsResult {
 export function remapCommentThreads(
   options: RemapCommentThreadsOptions,
 ): RemapCommentThreadsResult {
-  const comments = Object.fromEntries(
-    Object.entries(options.comments).map(([commentId, comment]) => [
-      commentId,
-      remapCommentThread(comment, options.mapping, options.nextContent),
-    ]),
-  );
+  // Only rebuild the record when at least one comment anchor actually changed.
+  const sourceComments = options.comments;
+  let comments = sourceComments;
+  let anyChanged = false;
+  const remappedEntries = Object.entries(sourceComments).map(([commentId, comment]) => {
+    const next = remapCommentThread(comment, options.mapping, options.nextContent);
+    if (next !== comment) anyChanged = true;
+    return [commentId, next] as const;
+  });
+  if (anyChanged) {
+    comments = Object.fromEntries(remappedEntries);
+  }
+
   const detachedCommentIds = Object.values(comments)
     .filter((comment) => comment.anchor.kind === "detached")
     .map((comment) => comment.commentId);
@@ -50,14 +60,17 @@ export function remapCommentThread(
   if (comment.anchor.kind === "detached") {
     return comment;
   }
+  // Skip the full remap + rangeStaysWithinCommentableStory walk when no step
+  // reaches this anchor's range — positions are provably unchanged.
+  if (anchorUnaffectedByMapping(comment.anchor, mapping)) {
+    return comment;
+  }
 
   const mappedAnchor = mapReviewAnchor(comment.anchor, mapping);
   const anchor = normalizeCommentAnchor(comment.anchor, mappedAnchor, mapping, nextContent);
 
-  return {
-    ...comment,
-    anchor,
-  };
+  if (anchor === comment.anchor) return comment;
+  return { ...comment, anchor };
 }
 
 function normalizeCommentAnchor(