@beyondwork/docx-react-component 1.0.58 → 1.0.60

package/src/io/ooxml/chart/types.ts

@@ -1,439 +1,11 @@
 /**
  * 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.
+ * Re-export shim. The canonical chart type definitions live in
+ * `src/model/chart-types.ts` — that location avoids the former
+ * `model → io` backward dependency (see `docs/plans/architecture-lane.md`
+ * §F1). io/ooxml/chart and ui-tailwind/chart consumers can continue
+ * importing from this path unchanged.
  */
-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;
+export type * from "../../../model/chart-types.ts";

package/src/io/ooxml/comment-presentation-payload.ts

@@ -160,9 +160,9 @@ export function parseCommentPresentationXml(
   for (const commentEl of childrenOf(root, "comment")) {
     const commentId = commentEl.attributes["commentId"] ?? "";
     if (!commentId) continue;
-    const audienceAttr = commentEl.attributes["audience"] as CommentAudience;
-    const audience: CommentAudience = AUDIENCE_VOCAB.has(audienceAttr)
-      ? audienceAttr
+    const rawAudience = commentEl.attributes["audience"];
+    const audience: CommentAudience = AUDIENCE_VOCAB.has(rawAudience as CommentAudience)
+      ? (rawAudience as CommentAudience)
       : "internal"; // fail-closed per schema
     const bodyEl = firstChild(commentEl, "body");
     const body: CommentBody = bodyEl ? parseBody(bodyEl) : emptyBody();
@@ -246,9 +246,10 @@ function parseAttachments(
   const out: CommentAttachment[] = [];
   for (const el of childrenOf(container, "attachment")) {
     const id = el.attributes["id"];
-    const kind = el.attributes["kind"] as CommentAttachment["kind"];
+    const rawKind = el.attributes["kind"];
     const displayName = el.attributes["displayName"];
-    if (!id || !displayName || !ATTACHMENT_KIND_VOCAB.has(kind)) continue;
+    if (!id || !displayName || !ATTACHMENT_KIND_VOCAB.has(rawKind as CommentAttachment["kind"])) continue;
+    const kind = rawKind as CommentAttachment["kind"];
     const a: CommentAttachment = { id, kind, displayName };
     if (el.attributes["mimeType"] !== undefined) {
       a.mimeType = el.attributes["mimeType"];

package/src/io/ooxml/highlight-colors.ts

@@ -19,6 +19,10 @@ export const HIGHLIGHT_COLOR_MAP = {
 
 export type HighlightColorName = keyof typeof HIGHLIGHT_COLOR_MAP;
 
+const HIGHLIGHT_COLOR_VOCAB = new Set<HighlightColorName>(
+  Object.keys(HIGHLIGHT_COLOR_MAP) as HighlightColorName[],
+);
+
 export function resolveHighlightColor(
   value: string | null | undefined,
 ): { color: string; val: HighlightColorName } | undefined {
@@ -26,14 +30,13 @@ export function resolveHighlightColor(
     return undefined;
   }
 
-  const normalizedValue = value as HighlightColorName;
-  const color = HIGHLIGHT_COLOR_MAP[normalizedValue];
-  if (!color) {
+  if (!HIGHLIGHT_COLOR_VOCAB.has(value as HighlightColorName)) {
     return undefined;
   }
 
+  const name = value as HighlightColorName;
   return {
-    color,
-    val: normalizedValue,
+    color: HIGHLIGHT_COLOR_MAP[name],
+    val: name,
   };
 }

package/src/io/ooxml/parse-anchor.ts

@@ -1,18 +1,11 @@
 import type { AnchorGeometry } from "../../model/canonical-document.ts";
-
-interface XmlElementNode {
-  type: "element";
-  name: string;
-  attributes: Record<string, string>;
-  children: XmlNode[];
-}
-
-interface XmlTextNode {
-  type: "text";
-  text: string;
-}
-
-type XmlNode = XmlElementNode | XmlTextNode;
+import {
+  type XmlElementNode,
+  findFirstChild,
+  findFirstDescendant,
+  localName,
+  extractText,
+} from "./_mini-xml.ts";
 
 export function parseAnchorGeometry(container: XmlElementNode): AnchorGeometry {
   const tag = localName(container.name);
@@ -49,19 +42,33 @@ export function parseAnchorGeometry(container: XmlElementNode): AnchorGeometry {
 
   const docPrEl = findFirstChild(container, "docPr");
   const docPr = docPrEl
-    ? {
-        id: docPrEl.attributes.id ?? "",
-        ...(docPrEl.attributes.name ? { name: docPrEl.attributes.name } : {}),
-        ...(docPrEl.attributes.descr ? { descr: docPrEl.attributes.descr } : {}),
-      }
+    ? (() => {
+        const dp: NonNullable<AnchorGeometry["docPr"]> = {
+          id: docPrEl.attributes.id ?? "",
+        };
+        if (docPrEl.attributes.name) dp.name = docPrEl.attributes.name;
+        if (docPrEl.attributes.descr) dp.descr = docPrEl.attributes.descr;
+        // Phase 4.6 G8 — wp:docPr hidden flag
+        const hidden = readBoolAttr(docPrEl, "hidden");
+        if (hidden !== undefined) dp.hidden = hidden;
+        return dp;
+      })()
     : undefined;
 
+  // Phase 4.6 G8 — wp:cNvGraphicFramePr/a:graphicFrameLocks for object chrome.
+  const cNvPr = findFirstChild(container, "cNvGraphicFramePr");
+  const frameLocks = cNvPr ? readFrameLocks(cNvPr) : undefined;
+
+  // Phase 4.2 G1 — wrapPolygon coords for wrapTight / wrapThrough.
+  const wrapPolygon = readWrapPolygon(container);
+
   const geometry: AnchorGeometry = {
     display,
     extent,
     wrapMode,
   };
 
+  if (wrapPolygon) geometry.wrapPolygon = wrapPolygon;
   if (positionHEl) geometry.positionH = readAxisPosition(positionHEl);
   if (positionVEl) geometry.positionV = readAxisPosition(positionVEl);
   if (distMargins) geometry.distMargins = distMargins;
@@ -71,6 +78,7 @@ export function parseAnchorGeometry(container: XmlElementNode): AnchorGeometry {
   if (allowOverlap !== undefined) geometry.allowOverlap = allowOverlap;
   if (simplePos !== undefined) geometry.simplePos = simplePos;
   if (docPr) geometry.docPr = docPr;
+  if (frameLocks) geometry.frameLocks = frameLocks;
 
   return geometry;
 }
@@ -92,6 +100,47 @@ function readExtent(container: XmlElementNode): AnchorGeometry["extent"] {
   };
 }
 
+function readWrapPolygon(
+  container: XmlElementNode,
+): Array<{ x: number; y: number }> | undefined {
+  const wrapEl =
+    findFirstChild(container, "wrapTight") ??
+    findFirstChild(container, "wrapThrough");
+  if (!wrapEl) return undefined;
+  const polygon = findFirstChild(wrapEl, "wrapPolygon");
+  if (!polygon) return undefined;
+
+  const coords: Array<{ x: number; y: number }> = [];
+  const start = findFirstChild(polygon, "start");
+  if (start) {
+    const x = readIntAttr(start, "x");
+    const y = readIntAttr(start, "y");
+    coords.push({ x: x ?? 0, y: y ?? 0 });
+  }
+  for (const child of polygon.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "lineTo") continue;
+    const x = readIntAttr(child, "x");
+    const y = readIntAttr(child, "y");
+    coords.push({ x: x ?? 0, y: y ?? 0 });
+  }
+  return coords.length > 0 ? coords : undefined;
+}
+
+function readFrameLocks(
+  cNvPr: XmlElementNode,
+): NonNullable<AnchorGeometry["frameLocks"]> | undefined {
+  const locks = findFirstChild(cNvPr, "graphicFrameLocks");
+  if (!locks) return undefined;
+  const result: NonNullable<AnchorGeometry["frameLocks"]> = {};
+  const keys = ["noChangeAspect", "noResize", "noMove", "noRot", "noSelect", "noGrp"] as const;
+  for (const key of keys) {
+    const v = readBoolAttr(locks, key);
+    if (v !== undefined) result[key] = v;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 function readWrapMode(
   container: XmlElementNode,
 ): AnchorGeometry["wrapMode"] {
@@ -129,40 +178,6 @@ function readAxisPosition(
   return result;
 }
 
-function findFirstChild(
-  node: XmlElementNode,
-  local: string,
-): XmlElementNode | undefined {
-  for (const child of node.children) {
-    if (child.type === "element" && localName(child.name) === local) return child;
-  }
-  return undefined;
-}
-
-function findFirstDescendant(
-  node: XmlElementNode,
-  local: string,
-): XmlElementNode | undefined {
-  for (const child of node.children) {
-    if (child.type !== "element") continue;
-    if (localName(child.name) === local) return child;
-    const found = findFirstDescendant(child, local);
-    if (found) return found;
-  }
-  return undefined;
-}
-
-function localName(name: string): string {
-  const i = name.indexOf(":");
-  return i >= 0 ? name.slice(i + 1) : name;
-}
-
-function extractText(node: XmlElementNode): string {
-  return node.children
-    .map((c) => (c.type === "text" ? c.text : extractText(c as XmlElementNode)))
-    .join("");
-}
-
 function readIntAttr(node: XmlElementNode, name: string): number | undefined {
   const v = node.attributes[name] ?? node.attributes[`wp:${name}`];
   if (v === undefined) return undefined;