@beyondwork/docx-react-component 1.0.47 → 1.0.48

package/src/io/ooxml/chart/parse-chart-space.ts

@@ -0,0 +1,813 @@
+/**
+ * Top-level chart-space parser (Stage 1, bar/column end-to-end).
+ *
+ * Dispatches `<c:chartSpace>` XML into a `ChartModel` discriminated union.
+ * This slice implements the `barChart` / `bar3DChart` branch in full; every
+ * other chart family returns an `UnsupportedChartModel` with a specific
+ * `reason` (either `not-yet-implemented` for families a subsequent slice
+ * will fill in, or a permanent-defer reason like `stock` / `surface`).
+ *
+ * Design notes:
+ *
+ * - Every return path preserves the raw input XML on `model.rawXml`. The
+ *   export path re-emits the original drawing verbatim regardless of
+ *   renderer coverage, so the round-trip guarantee survives even when a
+ *   chart family isn't parsed yet.
+ * - The outermost try/catch catches unexpected parse failures and returns
+ *   `{ kind: "unsupported", reason: "parse-error", detail: err.message }`.
+ *   Callers never observe a thrown exception from parseChartSpace.
+ * - 3D variants (bar3DChart) intentionally collapse to the 2D model. Stage
+ *   1 does not distinguish 3D from 2D; renderer stages may re-introduce
+ *   the distinction later if needed.
+ */
+
+import {
+  findChildOptional,
+  findFirstDescendant,
+  localName,
+  readIntVal,
+  textContent,
+} from "../xml-attr-helpers.ts";
+import type { XmlElementNode } from "../xml-element.ts";
+import { parseXml } from "../xml-parser.ts";
+
+import { parseAxisNode } from "./parse-axis.ts";
+import {
+  extractStrCache,
+  parseBarSeriesNode,
+  parseBubbleSeriesNode,
+  parseLineSeriesNode,
+  parsePieSeriesNode,
+  parseScatterSeriesNode,
+  parseSeriesBase,
+  parseShapeProperties,
+} from "./parse-series.ts";
+import type {
+  AreaChartModel,
+  Axis,
+  BarChartModel,
+  BubbleChartModel,
+  BubbleSeries,
+  CategoryAxis,
+  ChartCommon,
+  ChartModel,
+  ComboChartModel,
+  Legend,
+  LineChartModel,
+  LineSeries,
+  PieChartModel,
+  PieSeries,
+  ScatterChartModel,
+  ScatterSeries,
+  Series,
+  Title,
+  UnsupportedChartModel,
+  UnsupportedReason,
+  ValueAxis,
+} from "./types.ts";
+
+// The set of OOXML chart-type elements we recognise. Everything else under
+// `c:plotArea` is ignored (c:layout, c:dTable, c:valAx, etc.) when scanning
+// for type groups.
+const TYPE_GROUP_LOCAL_NAMES = new Set<string>([
+  "barChart",
+  "bar3DChart",
+  "lineChart",
+  "line3DChart",
+  "pieChart",
+  "pie3DChart",
+  "doughnutChart",
+  "areaChart",
+  "area3DChart",
+  "scatterChart",
+  "bubbleChart",
+  "stockChart",
+  "radarChart",
+  "surfaceChart",
+  "surface3DChart",
+  "ofPieChart",
+]);
+
+const AXIS_LOCAL_NAMES = new Set<string>(["catAx", "valAx", "dateAx", "serAx"]);
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export function parseChartSpace(rawXml: string): ChartModel {
+  try {
+    const root = parseXml(rawXml);
+    const chartSpace = findFirstDescendant(root, "chartSpace");
+    if (!chartSpace) {
+      return makeUnsupported("no-plot-area", rawXml, "No <c:chartSpace> root");
+    }
+    const chart = findChildOptional(chartSpace, "chart");
+    if (!chart) {
+      return makeUnsupported("no-plot-area", rawXml, "No <c:chart> child");
+    }
+    const plotArea = findChildOptional(chart, "plotArea");
+    if (!plotArea) {
+      return makeUnsupported("no-plot-area", rawXml, "No <c:plotArea> child");
+    }
+
+    const typeGroups = plotArea.children.filter(
+      (c): c is XmlElementNode =>
+        c.type === "element" && TYPE_GROUP_LOCAL_NAMES.has(localName(c.name)),
+    );
+    if (typeGroups.length === 0) {
+      return makeUnsupported("no-plot-area", rawXml, "No chart-type group in plotArea");
+    }
+
+    const common = buildChartCommon(chart, rawXml);
+
+    const axes = parsePlotAreaAxes(plotArea);
+
+    if (typeGroups.length > 1) {
+      return parseComboPlotArea(typeGroups, axes, common, rawXml);
+    }
+
+    const group = typeGroups[0]!;
+    const groupLocal = localName(group.name);
+
+    switch (groupLocal) {
+      case "barChart":
+      case "bar3DChart":
+        return parseBarGroup(group, axes, common, rawXml);
+
+      case "lineChart":
+      case "line3DChart":
+        return parseLineGroup(group, axes, common);
+
+      case "areaChart":
+      case "area3DChart":
+        return parseAreaGroup(group, axes, common);
+
+      case "pieChart":
+      case "pie3DChart":
+      case "doughnutChart":
+        return parsePieGroup(group, common, groupLocal === "doughnutChart");
+
+      case "scatterChart":
+        return parseScatterGroup(group, axes, common);
+
+      case "bubbleChart":
+        return parseBubbleGroup(group, axes, common);
+
+      case "radarChart":
+        return makeUnsupported(
+          "not-yet-implemented",
+          rawXml,
+          `Chart family ${groupLocal} not yet implemented`,
+          common,
+        );
+
+      case "stockChart":
+        return makeUnsupported("stock", rawXml, "Stock chart not supported", common);
+
+      case "surfaceChart":
+      case "surface3DChart":
+        return makeUnsupported("surface", rawXml, "Surface chart not supported", common);
+
+      case "ofPieChart":
+        // Pie-of-pie / bar-of-pie — deferred with pie family.
+        return makeUnsupported(
+          "not-yet-implemented",
+          rawXml,
+          "ofPieChart not yet implemented",
+          common,
+        );
+
+      default:
+        return makeUnsupported(
+          "parse-error",
+          rawXml,
+          `Unrecognised chart-type element ${groupLocal}`,
+          common,
+        );
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return makeUnsupported("parse-error", rawXml, message);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Chart-common fields (title, legend, plotVisOnly, dispBlanksAs, styleId)
+// ---------------------------------------------------------------------------
+
+function buildChartCommon(
+  chart: XmlElementNode,
+  rawXml: string,
+): ChartCommon {
+  const plotVisOnlyNode = findChildOptional(chart, "plotVisOnly");
+  const plotVisOnly =
+    plotVisOnlyNode === undefined
+      ? true
+      : plotVisOnlyNode.attributes["val"] !== "0";
+
+  const dispBlanksRaw = findChildOptional(chart, "dispBlanksAs")?.attributes["val"];
+  const dispBlanksAs: ChartCommon["dispBlanksAs"] =
+    dispBlanksRaw === "zero" || dispBlanksRaw === "span"
+      ? dispBlanksRaw
+      : "gap";
+
+  const styleNode = findChildOptional(chart, "style");
+  const styleId = styleNode ? readIntVal(styleNode) : undefined;
+
+  const title = parseTitle(findChildOptional(chart, "title"));
+  const legend = parseLegend(findChildOptional(chart, "legend"));
+
+  const common: ChartCommon = {
+    plotVisOnly,
+    dispBlanksAs,
+    rawXml,
+  };
+  if (title) common.title = title;
+  if (legend) common.legend = legend;
+  if (styleId !== undefined) common.styleId = styleId;
+  return common;
+}
+
+function parseTitle(titleNode: XmlElementNode | undefined): Title | undefined {
+  if (!titleNode) return undefined;
+  let text: string | undefined;
+  const tx = findChildOptional(titleNode, "tx");
+  if (tx) {
+    const rich = findChildOptional(tx, "rich");
+    if (rich) {
+      const parts: string[] = [];
+      const walk = (children: XmlElementNode["children"]): void => {
+        for (const c of children) {
+          if (c.type !== "element") continue;
+          if (localName(c.name) === "t") parts.push(textContent(c));
+          else walk(c.children);
+        }
+      };
+      walk(rich.children);
+      text = parts.join("");
+    } else {
+      const v = findChildOptional(tx, "v");
+      if (v) text = textContent(v);
+    }
+  }
+  const overlay = findChildOptional(titleNode, "overlay")?.attributes["val"] === "1";
+  const title: Title = { overlay };
+  if (text) title.text = text;
+  return title;
+}
+
+function parseLegend(legendNode: XmlElementNode | undefined): Legend | undefined {
+  if (!legendNode) return undefined;
+  const posRaw = findChildOptional(legendNode, "legendPos")?.attributes["val"] ?? "r";
+  const position: Legend["position"] =
+    posRaw === "b" || posRaw === "t" || posRaw === "l" || posRaw === "r" || posRaw === "tr"
+      ? posRaw
+      : "r";
+  const overlay = findChildOptional(legendNode, "overlay")?.attributes["val"] === "1";
+  return { position, overlay };
+}
+
+// ---------------------------------------------------------------------------
+// Axes
+// ---------------------------------------------------------------------------
+
+function parsePlotAreaAxes(plotArea: XmlElementNode): Map<string, Axis> {
+  const out = new Map<string, Axis>();
+  for (const child of plotArea.children) {
+    if (child.type !== "element") continue;
+    if (!AXIS_LOCAL_NAMES.has(localName(child.name))) continue;
+    const axis = parseAxisNode(child);
+    if (axis.id) out.set(axis.id, axis);
+  }
+  return out;
+}
+
+/**
+ * Find the primary category and value axes that a type group binds to. The
+ * group declares its binding via two or more `<c:axId val="…"/>` children
+ * (typically exactly two: category axis id + value axis id). Shared by
+ * bar/line/area since they all have the same category-axis + value-axis
+ * topology.
+ */
+function resolveCategoryValueAxes(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+): { categoryAxis: CategoryAxis; valueAxis: ValueAxis } {
+  const ids: string[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "axId") continue;
+    const id = child.attributes["val"];
+    if (id) ids.push(id);
+  }
+
+  let categoryAxis: CategoryAxis | undefined;
+  let valueAxis: ValueAxis | undefined;
+  for (const id of ids) {
+    const ax = axes.get(id);
+    if (!ax) continue;
+    if (ax.kind === "category") categoryAxis = ax;
+    // Date axes can bind where a category axis would go; treat as category.
+    else if (ax.kind === "date" && !categoryAxis) {
+      categoryAxis = dateAxisToCategory(ax);
+    } else if (ax.kind === "value" && !valueAxis) valueAxis = ax;
+  }
+
+  if (!categoryAxis) categoryAxis = placeholderCategoryAxis();
+  if (!valueAxis) valueAxis = placeholderValueAxis();
+  return { categoryAxis, valueAxis };
+}
+
+/** Narrow a date axis into a CategoryAxis shape so bar/line/area models
+ *  can expose a uniform `categoryAxis` field. Date-specific fields are
+ *  dropped here; Stage 2/3 can preserve them via a dedicated route. */
+function dateAxisToCategory(ax: Axis & { kind: "date" }): CategoryAxis {
+  return {
+    kind: "category",
+    id: ax.id,
+    position: ax.position,
+    visible: ax.visible,
+    auto: true,
+    categoryLabels: [],
+    ...(ax.crossAxisId !== undefined ? { crossAxisId: ax.crossAxisId } : {}),
+    ...(ax.crossesAt !== undefined ? { crossesAt: ax.crossesAt } : {}),
+    ...(ax.majorGridlines !== undefined ? { majorGridlines: ax.majorGridlines } : {}),
+    ...(ax.minorGridlines !== undefined ? { minorGridlines: ax.minorGridlines } : {}),
+    ...(ax.numberFormat !== undefined ? { numberFormat: ax.numberFormat } : {}),
+  };
+}
+
+function placeholderCategoryAxis(): CategoryAxis {
+  return {
+    kind: "category",
+    id: "",
+    position: "b",
+    visible: true,
+    auto: true,
+    categoryLabels: [],
+  };
+}
+
+function placeholderValueAxis(): ValueAxis {
+  return {
+    kind: "value",
+    id: "",
+    position: "l",
+    visible: true,
+    reverse: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Bar / column
+// ---------------------------------------------------------------------------
+
+function parseBarGroup(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+  common: ChartCommon,
+  rawXml: string,
+): BarChartModel {
+  void rawXml; // rawXml is already carried on common
+  const dirRaw = findChildOptional(groupNode, "barDir")?.attributes["val"] ?? "col";
+  const direction: BarChartModel["direction"] = dirRaw === "bar" ? "bar" : "column";
+
+  const groupingRaw = findChildOptional(groupNode, "grouping")?.attributes["val"];
+  const grouping: BarChartModel["grouping"] =
+    groupingRaw === "stacked" ||
+    groupingRaw === "percentStacked" ||
+    groupingRaw === "standard"
+      ? groupingRaw
+      : "clustered";
+
+  const gapWidth = readIntVal(findChildOptional(groupNode, "gapWidth")) ?? 150;
+  const overlap = readIntVal(findChildOptional(groupNode, "overlap")) ?? 0;
+
+  const series: Series[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "ser") continue;
+    series.push(parseBarSeriesNode(child));
+  }
+
+  const { categoryAxis, valueAxis } = resolveCategoryValueAxes(groupNode, axes);
+
+  // Promote category labels from the first series onto the axis if they
+  // aren't already populated (typical for Word-authored charts).
+  if (categoryAxis.categoryLabels.length === 0 && series.length > 0) {
+    categoryAxis.categoryLabels = series[0]!.categories;
+  }
+
+  // spPr on the group itself (rare, but legal — e.g. global series fill
+  // override) is not part of BarChartModel today; ignored.
+  void parseShapeProperties;
+
+  const model: BarChartModel = {
+    ...common,
+    kind: "bar",
+    direction,
+    grouping,
+    gapWidth,
+    overlap,
+    series,
+    categoryAxis,
+    valueAxis,
+  };
+  return model;
+}
+
+// ---------------------------------------------------------------------------
+// Line
+// ---------------------------------------------------------------------------
+
+function parseLineGroup(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+  common: ChartCommon,
+): LineChartModel {
+  const groupingRaw = findChildOptional(groupNode, "grouping")?.attributes["val"];
+  const grouping: LineChartModel["grouping"] =
+    groupingRaw === "stacked" || groupingRaw === "percentStacked"
+      ? groupingRaw
+      : "standard";
+
+  // c:smooth / c:marker at the GROUP level are booleans (val="0" | "1").
+  // Per-series <c:smooth>/<c:marker> under each <c:ser> override.
+  const smooth = readGroupBoolean(groupNode, "smooth");
+  const marker = readGroupBoolean(groupNode, "marker");
+
+  const series: LineSeries[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "ser") continue;
+    series.push(parseLineSeriesNode(child));
+  }
+
+  const { categoryAxis, valueAxis } = resolveCategoryValueAxes(groupNode, axes);
+  if (categoryAxis.categoryLabels.length === 0 && series.length > 0) {
+    categoryAxis.categoryLabels = series[0]!.categories;
+  }
+
+  return {
+    ...common,
+    kind: "line",
+    grouping,
+    smooth,
+    marker,
+    series,
+    categoryAxis,
+    valueAxis,
+  };
+}
+
+/**
+ * Read a boolean flag from a group-level child element with a `val`
+ * attribute. Unset → false (matching Word's default for lineChart
+ * c:smooth and c:marker).
+ */
+function readGroupBoolean(groupNode: XmlElementNode, local: string): boolean {
+  const node = findChildOptional(groupNode, local);
+  if (!node) return false;
+  const raw = node.attributes["val"];
+  if (raw === undefined) return true; // bare <c:smooth/> treated as true
+  return raw !== "0" && raw.toLowerCase() !== "false";
+}
+
+// ---------------------------------------------------------------------------
+// Pie / Doughnut
+// ---------------------------------------------------------------------------
+
+/** OOXML's angle unit is 1/60000 of a degree (sixtyThousandths). */
+const OOXML_ANGLE_UNIT = 60000;
+
+function parsePieGroup(
+  groupNode: XmlElementNode,
+  common: ChartCommon,
+  doughnut: boolean,
+): PieChartModel {
+  // Pie's varyColors default is true (unlike bar/line/area where it's
+  // false). When the flag is absent we assume the Word default.
+  const varyColorsRaw = findChildOptional(groupNode, "varyColors")?.attributes["val"];
+  const varyColors =
+    varyColorsRaw === undefined
+      ? true
+      : varyColorsRaw !== "0" && varyColorsRaw.toLowerCase() !== "false";
+
+  // c:firstSliceAngle is in 1/60000 of a degree, clockwise from 12 o'clock.
+  // ECMA-376 defines 0–360 range; we perform the unit conversion and leave
+  // clamping to the renderer so out-of-range values stay recoverable.
+  const firstSliceAngleRaw = readIntVal(findChildOptional(groupNode, "firstSliceAngle"));
+  const firstSliceAngle =
+    firstSliceAngleRaw !== undefined ? firstSliceAngleRaw / OOXML_ANGLE_UNIT : 0;
+
+  // Doughnut hole size is a percent (0–99 typical). Missing on pieChart.
+  const holeSizePercent = doughnut
+    ? readIntVal(findChildOptional(groupNode, "holeSize"))
+    : undefined;
+
+  // Collect series — pieChart typically has exactly one, but ECMA-376
+  // technically allows more (pie-of-pie uses 2 but that's the ofPieChart
+  // element, not pieChart; remaining scope is deferred).
+  const series: PieSeries[] = [];
+  let categoryLabels: string[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "ser") continue;
+    const pieSeries = parsePieSeriesNode(child);
+    series.push(pieSeries);
+    // Category labels come from the first series' c:cat cache.
+    if (categoryLabels.length === 0) {
+      const cat = findChildOptional(child, "cat");
+      categoryLabels = extractCategoryLabels(cat);
+    }
+  }
+
+  const model: PieChartModel = {
+    ...common,
+    kind: "pie",
+    doughnut,
+    firstSliceAngle,
+    varyColors,
+    series,
+    categoryLabels,
+  };
+  if (holeSizePercent !== undefined) model.holeSizePercent = holeSizePercent;
+  return model;
+}
+
+/**
+ * Extract category labels from a `<c:cat>` container. Reuses the sparse-
+ * point string-cache extractor from parse-series.ts so the algorithm has a
+ * single source of truth.
+ */
+function extractCategoryLabels(
+  catNode: XmlElementNode | undefined,
+): string[] {
+  if (!catNode) return [];
+  return extractStrCache(catNode);
+}
+
+// ---------------------------------------------------------------------------
+// Area
+// ---------------------------------------------------------------------------
+
+function parseAreaGroup(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+  common: ChartCommon,
+): AreaChartModel {
+  const groupingRaw = findChildOptional(groupNode, "grouping")?.attributes["val"];
+  const grouping: AreaChartModel["grouping"] =
+    groupingRaw === "stacked" || groupingRaw === "percentStacked"
+      ? groupingRaw
+      : "standard";
+
+  const series: Series[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "ser") continue;
+    series.push(parseSeriesBase(child));
+  }
+
+  const { categoryAxis, valueAxis } = resolveCategoryValueAxes(groupNode, axes);
+  if (categoryAxis.categoryLabels.length === 0 && series.length > 0) {
+    categoryAxis.categoryLabels = series[0]!.categories;
+  }
+
+  return {
+    ...common,
+    kind: "area",
+    grouping,
+    series,
+    categoryAxis,
+    valueAxis,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Combo (multi-group plot area)
+// ---------------------------------------------------------------------------
+
+/**
+ * The cartesian chart families that can compose into a combo: bar, line,
+ * area. Pie/doughnut/scatter/bubble don't share the category+value axis
+ * topology, so a plot area that mixes them falls back to unsupported.
+ */
+const COMBO_SUPPORTED_LOCAL_NAMES = new Set<string>([
+  "barChart",
+  "bar3DChart",
+  "lineChart",
+  "line3DChart",
+  "areaChart",
+  "area3DChart",
+]);
+
+function parseComboPlotArea(
+  typeGroups: XmlElementNode[],
+  axes: Map<string, Axis>,
+  common: ChartCommon,
+  rawXml: string,
+): ChartModel {
+  // Reject combos that contain non-cartesian families; a bar + pie plot
+  // area is not a combo we can reason about with the current ComboChart
+  // model (groups array only accepts bar/line/area).
+  for (const g of typeGroups) {
+    if (!COMBO_SUPPORTED_LOCAL_NAMES.has(localName(g.name))) {
+      return makeUnsupported(
+        "not-yet-implemented",
+        rawXml,
+        `Combo with ${localName(g.name)} — only bar/line/area combos supported`,
+        common,
+      );
+    }
+  }
+
+  // Track which value axes are bound across the combo. A combo is "dual-
+  // axis" when a group references a value axis distinct from the one the
+  // first group uses.
+  let primaryValueAxisId: string | undefined;
+  let hasSecondaryAxis = false;
+  const groups: ComboChartModel["groups"] = [];
+
+  for (const group of typeGroups) {
+    const groupLocal = localName(group.name);
+    let model: BarChartModel | LineChartModel | AreaChartModel;
+    switch (groupLocal) {
+      case "barChart":
+      case "bar3DChart":
+        model = parseBarGroup(group, axes, common, rawXml);
+        break;
+      case "lineChart":
+      case "line3DChart":
+        model = parseLineGroup(group, axes, common);
+        break;
+      case "areaChart":
+      case "area3DChart":
+        model = parseAreaGroup(group, axes, common);
+        break;
+      default:
+        // Should be unreachable — gate above filters non-cartesian.
+        return makeUnsupported(
+          "parse-error",
+          rawXml,
+          `Combo: unexpected group ${groupLocal}`,
+          common,
+        );
+    }
+    groups.push(model);
+
+    const thisGroupValueAxisId = model.valueAxis.id;
+    if (!primaryValueAxisId) {
+      primaryValueAxisId = thisGroupValueAxisId;
+    } else if (
+      thisGroupValueAxisId &&
+      thisGroupValueAxisId !== primaryValueAxisId
+    ) {
+      hasSecondaryAxis = true;
+    }
+  }
+
+  return {
+    ...common,
+    kind: "combo",
+    groups,
+    hasSecondaryAxis,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scatter
+// ---------------------------------------------------------------------------
+
+const SCATTER_STYLES: ReadonlySet<ScatterChartModel["style"]> = new Set<
+  ScatterChartModel["style"]
+>(["line", "lineMarker", "marker", "smooth", "smoothMarker"]);
+
+function parseScatterGroup(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+  common: ChartCommon,
+): ScatterChartModel {
+  const styleRaw = findChildOptional(groupNode, "scatterStyle")?.attributes["val"];
+  const style: ScatterChartModel["style"] =
+    styleRaw && SCATTER_STYLES.has(styleRaw as ScatterChartModel["style"])
+      ? (styleRaw as ScatterChartModel["style"])
+      : "marker";
+
+  const series: ScatterSeries[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "ser") continue;
+    series.push(parseScatterSeriesNode(child));
+  }
+
+  const { xAxis, yAxis } = resolveXYValueAxes(groupNode, axes);
+
+  return {
+    ...common,
+    kind: "scatter",
+    style,
+    series,
+    xAxis,
+    yAxis,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Bubble
+// ---------------------------------------------------------------------------
+
+function parseBubbleGroup(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+  common: ChartCommon,
+): BubbleChartModel {
+  // c:bubble3D is a group-level flag (distinct from c:dPt/c:bubble3D).
+  // We render as 2D regardless, but capture the flag for agent parity.
+  const bubble3DRaw = findChildOptional(groupNode, "bubble3D")?.attributes["val"];
+  const bubble3D = bubble3DRaw === "1" || bubble3DRaw?.toLowerCase() === "true";
+
+  const series: BubbleSeries[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "ser") continue;
+    series.push(parseBubbleSeriesNode(child));
+  }
+
+  const { xAxis, yAxis } = resolveXYValueAxes(groupNode, axes);
+
+  return {
+    ...common,
+    kind: "bubble",
+    bubble3D,
+    series,
+    xAxis,
+    yAxis,
+  };
+}
+
+/**
+ * Scatter and bubble charts bind to two VALUE axes (not category + value
+ * like bar/line/area). The group still declares its binding via two c:axId
+ * children; we resolve each to a ValueAxis, falling back to a placeholder
+ * if the axis wasn't found or wasn't a value axis.
+ *
+ * Axis placement (which is x vs y) is determined by position attribute:
+ * "b" or "t" → x-axis (horizontal), "l" or "r" → y-axis (vertical).
+ * If both axes share the same orientation the first-declared gets x.
+ */
+function resolveXYValueAxes(
+  groupNode: XmlElementNode,
+  axes: Map<string, Axis>,
+): { xAxis: ValueAxis; yAxis: ValueAxis } {
+  const ids: string[] = [];
+  for (const child of groupNode.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) !== "axId") continue;
+    const id = child.attributes["val"];
+    if (id) ids.push(id);
+  }
+
+  let xAxis: ValueAxis | undefined;
+  let yAxis: ValueAxis | undefined;
+  for (const id of ids) {
+    const ax = axes.get(id);
+    if (!ax || ax.kind !== "value") continue;
+    if (ax.position === "b" || ax.position === "t") {
+      if (!xAxis) xAxis = ax;
+      else if (!yAxis) yAxis = ax;
+    } else {
+      if (!yAxis) yAxis = ax;
+      else if (!xAxis) xAxis = ax;
+    }
+  }
+
+  if (!xAxis) xAxis = placeholderValueAxis();
+  if (!yAxis) yAxis = placeholderValueAxis();
+  // Normalise the placeholder positions so the returned pair is visually
+  // distinguishable (b for x, l for y) when both were placeholders.
+  if (xAxis.position !== "b" && xAxis.position !== "t") xAxis = { ...xAxis, position: "b" };
+  if (yAxis.position !== "l" && yAxis.position !== "r") yAxis = { ...yAxis, position: "l" };
+  return { xAxis, yAxis };
+}
+
+// ---------------------------------------------------------------------------
+// Unsupported
+// ---------------------------------------------------------------------------
+
+function makeUnsupported(
+  reason: UnsupportedReason,
+  rawXml: string,
+  detail: string,
+  common?: ChartCommon,
+): UnsupportedChartModel {
+  const base: ChartCommon = common ?? {
+    plotVisOnly: true,
+    dispBlanksAs: "gap",
+    rawXml,
+  };
+  return {
+    ...base,
+    rawXml, // always keep the original regardless of common.rawXml
+    kind: "unsupported",
+    reason,
+    detail,
+  };
+}