@beyondwork/docx-react-component 1.0.47 → 1.0.48

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

@@ -0,0 +1,277 @@
+/**
+ * Parse chart axis elements.
+ *
+ * OOXML defines four axis element names:
+ *   c:catAx (category)  c:valAx (value)  c:dateAx (date)  c:serAx (series)
+ *
+ * They share a common set of child elements (c:axId, c:delete, c:axPos,
+ * c:title, c:majorGridlines, c:minorGridlines, c:numFmt, c:crossAx, etc.)
+ * plus axis-specific extensions. This parser produces a discriminated
+ * `Axis` union that records which root element was seen.
+ *
+ * Note: c:delete has inverted semantics — `val="1"` means *invisible* and
+ * a missing element means *visible*. We store the normal-sense boolean
+ * on `AxisBase.visible`.
+ */
+
+import {
+  findChildOptional,
+  localName,
+  readFloatVal,
+  readIntVal,
+  readStringAttr,
+  textContent,
+} from "../xml-attr-helpers.ts";
+import type { XmlElementNode } from "../xml-element.ts";
+import { parseXml } from "../xml-parser.ts";
+
+import type {
+  Axis,
+  AxisBase,
+  CategoryAxis,
+  DateAxis,
+  SeriesAxis,
+  Title,
+  ValueAxis,
+} from "./types.ts";
+
+const AXIS_LOCAL_NAMES = new Set(["catAx", "valAx", "dateAx", "serAx"]);
+
+/** Parse an axis element from raw XML. Throws if the root is not a known axis. */
+export function parseAxis(xml: string): Axis {
+  const root = parseXml(xml);
+  let axisNode: XmlElementNode | undefined;
+  for (const child of root.children) {
+    if (child.type !== "element") continue;
+    if (AXIS_LOCAL_NAMES.has(localName(child.name))) {
+      axisNode = child;
+      break;
+    }
+  }
+  if (!axisNode) {
+    throw new Error(
+      `parseAxis: expected one of catAx/valAx/dateAx/serAx at root`,
+    );
+  }
+  return parseAxisNode(axisNode);
+}
+
+/** Dispatch to the axis-kind-specific parser based on the element name. */
+export function parseAxisNode(node: XmlElementNode): Axis {
+  const base = parseAxisBase(node);
+  switch (localName(node.name)) {
+    case "catAx":
+      return parseCategoryAxisFields(node, base);
+    case "valAx":
+      return parseValueAxisFields(node, base);
+    case "dateAx":
+      return parseDateAxisFields(node, base);
+    case "serAx":
+      return { ...base, kind: "series" } satisfies SeriesAxis;
+    default:
+      throw new Error(`parseAxisNode: unsupported axis element ${node.name}`);
+  }
+}
+
+function parseAxisBase(node: XmlElementNode): AxisBase {
+  const axIdNode = findChildOptional(node, "axId");
+  const id = axIdNode ? (readStringAttr(axIdNode, "val") ?? "") : "";
+  const deleteNode = findChildOptional(node, "delete");
+  // c:delete has inverted semantics.
+  const deleteVal = deleteNode?.attributes["val"] ?? "0";
+  const visible = deleteVal !== "1" && deleteVal.toLowerCase() !== "true";
+
+  const positionRaw = findChildOptional(node, "axPos")?.attributes["val"] ?? "b";
+  const position: AxisBase["position"] =
+    positionRaw === "b" || positionRaw === "t" || positionRaw === "l" || positionRaw === "r"
+      ? positionRaw
+      : "b";
+
+  const crossAxisId = findChildOptional(node, "crossAx")?.attributes["val"];
+  const crossesAt = parseCrossesAt(findChildOptional(node, "crosses"));
+
+  const base: AxisBase = {
+    id,
+    position,
+    visible,
+  };
+  if (crossAxisId !== undefined) base.crossAxisId = crossAxisId;
+  if (crossesAt !== undefined) base.crossesAt = crossesAt;
+
+  const title = parseAxisTitle(findChildOptional(node, "title"));
+  if (title) base.title = title;
+
+  if (findChildOptional(node, "majorGridlines")) base.majorGridlines = true;
+  if (findChildOptional(node, "minorGridlines")) base.minorGridlines = true;
+
+  const majorUnit = readFloatVal(findChildOptional(node, "majorUnit"));
+  if (majorUnit !== undefined) base.majorUnit = majorUnit;
+  const minorUnit = readFloatVal(findChildOptional(node, "minorUnit"));
+  if (minorUnit !== undefined) base.minorUnit = minorUnit;
+
+  const numFmtNode = findChildOptional(node, "numFmt");
+  if (numFmtNode) {
+    const formatCode = numFmtNode.attributes["formatCode"];
+    if (formatCode !== undefined) base.numberFormat = formatCode;
+  }
+
+  return base;
+}
+
+function parseCrossesAt(
+  crossesNode: XmlElementNode | undefined,
+): number | "autoZero" | "max" | "min" | undefined {
+  if (!crossesNode) return undefined;
+  const val = crossesNode.attributes["val"];
+  if (val === undefined) return undefined;
+  if (val === "autoZero" || val === "max" || val === "min") return val;
+  const n = Number.parseFloat(val);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function parseAxisTitle(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 texts: string[] = [];
+      const collectT = (children: XmlElementNode["children"]): void => {
+        for (const c of children) {
+          if (c.type !== "element") continue;
+          if (localName(c.name) === "t") {
+            texts.push(textContent(c));
+          } else {
+            collectT(c.children);
+          }
+        }
+      };
+      collectT(rich.children);
+      text = texts.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;
+}
+
+// ---------------------------------------------------------------------------
+// Category axis
+// ---------------------------------------------------------------------------
+
+function parseCategoryAxisFields(
+  node: XmlElementNode,
+  base: AxisBase,
+): CategoryAxis {
+  const auto = findChildOptional(node, "auto")?.attributes["val"] === "1";
+  const labelAlignRaw = findChildOptional(node, "lblAlgn")?.attributes["val"];
+  const labelAlign =
+    labelAlignRaw === "ctr" || labelAlignRaw === "l" || labelAlignRaw === "r"
+      ? labelAlignRaw
+      : undefined;
+  const labelOffset = readIntVal(findChildOptional(node, "lblOffset"));
+  const tickMarkRaw = findChildOptional(node, "majorTickMark")?.attributes["val"];
+  const tickMark =
+    tickMarkRaw === "none" ||
+    tickMarkRaw === "in" ||
+    tickMarkRaw === "out" ||
+    tickMarkRaw === "cross"
+      ? tickMarkRaw
+      : undefined;
+  const tickLabelSkip = readIntVal(findChildOptional(node, "tickLblSkip"));
+  const tickMarkSkip = readIntVal(findChildOptional(node, "tickMarkSkip"));
+
+  const axis: CategoryAxis = {
+    ...base,
+    kind: "category",
+    auto,
+    categoryLabels: [],
+  };
+  if (labelAlign) axis.labelAlign = labelAlign;
+  if (labelOffset !== undefined) axis.labelOffset = labelOffset;
+  if (tickMark) axis.tickMark = tickMark;
+  if (tickLabelSkip !== undefined) axis.tickLabelSkip = tickLabelSkip;
+  if (tickMarkSkip !== undefined) axis.tickMarkSkip = tickMarkSkip;
+  return axis;
+}
+
+// ---------------------------------------------------------------------------
+// Value axis
+// ---------------------------------------------------------------------------
+
+function parseValueAxisFields(
+  node: XmlElementNode,
+  base: AxisBase,
+): ValueAxis {
+  const scaling = findChildOptional(node, "scaling");
+  const min = readFloatVal(scaling ? findChildOptional(scaling, "min") : undefined);
+  const max = readFloatVal(scaling ? findChildOptional(scaling, "max") : undefined);
+  const logBase = readFloatVal(
+    scaling ? findChildOptional(scaling, "logBase") : undefined,
+  );
+  const orientation = scaling
+    ? findChildOptional(scaling, "orientation")?.attributes["val"]
+    : undefined;
+  const reverse = orientation === "maxMin";
+
+  const crossBetweenRaw = findChildOptional(node, "crossBetween")?.attributes["val"];
+  const crossBetween =
+    crossBetweenRaw === "between" || crossBetweenRaw === "midCat"
+      ? crossBetweenRaw
+      : undefined;
+
+  const axis: ValueAxis = {
+    ...base,
+    kind: "value",
+    reverse,
+  };
+  if (min !== undefined) axis.min = min;
+  if (max !== undefined) axis.max = max;
+  if (logBase !== undefined) axis.logBase = logBase;
+  if (crossBetween) axis.crossBetween = crossBetween;
+  return axis;
+}
+
+// ---------------------------------------------------------------------------
+// Date axis
+// ---------------------------------------------------------------------------
+
+function parseDateAxisFields(
+  node: XmlElementNode,
+  base: AxisBase,
+): DateAxis {
+  const scaling = findChildOptional(node, "scaling");
+  const min = readFloatVal(scaling ? findChildOptional(scaling, "min") : undefined);
+  const max = readFloatVal(scaling ? findChildOptional(scaling, "max") : undefined);
+  const baseTimeUnit = asTimeUnit(
+    findChildOptional(node, "baseTimeUnit")?.attributes["val"],
+  );
+  const majorTimeUnit = asTimeUnit(
+    findChildOptional(node, "majorTimeUnit")?.attributes["val"],
+  );
+  const minorTimeUnit = asTimeUnit(
+    findChildOptional(node, "minorTimeUnit")?.attributes["val"],
+  );
+  const axis: DateAxis = {
+    ...base,
+    kind: "date",
+  };
+  if (min !== undefined) axis.min = min;
+  if (max !== undefined) axis.max = max;
+  if (baseTimeUnit) axis.baseTimeUnit = baseTimeUnit;
+  if (majorTimeUnit) axis.majorTimeUnit = majorTimeUnit;
+  if (minorTimeUnit) axis.minorTimeUnit = minorTimeUnit;
+  return axis;
+}
+
+function asTimeUnit(
+  raw: string | undefined,
+): "days" | "months" | "years" | undefined {
+  if (raw === "days" || raw === "months" || raw === "years") return raw;
+  return undefined;
+}