@lotics/xlsx 0.1.3 → 0.1.5

package/src/pivot_writer.ts

@@ -0,0 +1,340 @@
+// =============================================================================
+// OOXML Pivot Table Writer
+// =============================================================================
+//
+// Serializes AUTHORED pivots (built via `pivot_builder`) into the three OOXML
+// parts Excel expects: `pivotTableN.xml`, `pivotCacheDefinitionN.xml`, and
+// `pivotCacheRecordsN.xml`. The inverse of `ooxml_pivot.ts` (the parser); the
+// two are kept format-compatible so a build → write → parse round-trip is
+// lossless for the supported subset.
+//
+// Supported subset (v1): exactly one row field, one column field, one data
+// field, and zero or more page (report-filter) fields, with grand totals. This
+// is the 2D cross-tab shape; multi-level axes and multiple data fields are not
+// emitted (the builder rejects them) so the row/col item layout stays a flat,
+// verifiable list.
+//
+// Every authored cache carries `refreshOnLoad="1"`: the cache records below are
+// a faithful snapshot of the source range, AND Excel rebuilds them from the
+// live worksheet on open, so the pivot is correct in non-refreshing viewers and
+// stays in sync after edits.
+// =============================================================================
+
+import { escapeXml } from "./excel_utils";
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+  PivotCacheField,
+  PivotCacheItem,
+} from "./ooxml_pivot_types";
+import type { PivotSourceRecord } from "./pivot_recompute";
+
+const MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+const REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+// =============================================================================
+// Shared item helpers (used by both the builder and this writer)
+// =============================================================================
+
+/** Coerce a raw source cell value to its cache-item representation. */
+export function sourceValueToItem(
+  v: string | number | boolean | null | undefined,
+): PivotCacheItem {
+  if (v === undefined || v === null || v === "") return { kind: "missing" };
+  if (typeof v === "number") return { kind: "number", value: v };
+  if (typeof v === "boolean") return { kind: "boolean", value: v };
+  return { kind: "string", value: v };
+}
+
+/** Canonical key for de-duplicating / looking up a cache item. */
+export function cacheItemKey(item: PivotCacheItem): string {
+  switch (item.kind) {
+    case "missing":
+      return "m:";
+    case "number":
+      return `n:${item.value}`;
+    case "boolean":
+      return `b:${item.value}`;
+    case "string":
+      return `s:${item.value}`;
+    case "date":
+      return `d:${item.value}`;
+    case "error":
+      return `e:${item.value}`;
+  }
+}
+
+/** The label used for ordering — matches `pivot_recompute`'s String()-lexicographic
+ *  tuple sort so the cache item order equals the pivot's displayed row/col order. */
+export function cacheItemSortKey(item: PivotCacheItem): string {
+  return item.kind === "missing" ? "" : String(item.value);
+}
+
+/** Which fields sit on an axis (row/col/page) — i.e. carry enumerated shared
+ *  items and reference them by index in the cache records. The data/unused
+ *  columns inline their values instead. */
+export function enumerateFlags(table: ParsedPivotTable, fieldCount: number): boolean[] {
+  const axis = new Set([...table.rowFieldIndices, ...table.colFieldIndices, ...table.pageFieldIndices]);
+  return Array.from({ length: fieldCount }, (_, i) => axis.has(i));
+}
+
+// =============================================================================
+// pivotCacheRecords
+// =============================================================================
+
+/**
+ * One `<r>` per source row. A field carried on an axis (row/col/page) is
+ * "enumerated": its cells are written as `<x v="i"/>` indices into the cache
+ * field's shared items. Other fields (the measure, unused columns) are written
+ * inline (`<n>`, `<s>`, `<b>`, `<m/>`).
+ */
+export function buildPivotCacheRecordsXml(
+  records: PivotSourceRecord[],
+  cache: ParsedPivotCache,
+  enumerate: boolean[],
+): string {
+  // index map per enumerated field: item key → position in shared items.
+  const indexMaps = cache.fields.map((f, i) => {
+    if (!enumerate[i]) return undefined;
+    const m = new Map<string, number>();
+    f.items.forEach((item, idx) => m.set(cacheItemKey(item), idx));
+    return m;
+  });
+
+  const rows = records.map((rec) => {
+    const cells = cache.fields.map((_f, i) => {
+      const item = sourceValueToItem(rec[i]);
+      const map = indexMaps[i];
+      if (map) {
+        const idx = map.get(cacheItemKey(item));
+        // A value absent from the shared items means the cache is stale (the
+        // source range changed after buildPivotTable) or inconsistent. Fail loud
+        // rather than emit a dangling index or silently bucket the value as blank.
+        if (idx === undefined) {
+          throw new Error(
+            `buildPivotCacheRecordsXml: value ${JSON.stringify(rec[i])} for field "${cache.fields[i].name}" is missing from its cached shared items`,
+          );
+        }
+        return `<x v="${idx}"/>`;
+      }
+      return inlineRecordCell(item);
+    });
+    return `<r>${cells.join("")}</r>`;
+  });
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<pivotCacheRecords xmlns="${MAIN_NS}" xmlns:r="${REL_NS}" count="${records.length}">` +
+    rows.join("") +
+    `</pivotCacheRecords>`
+  );
+}
+
+function inlineRecordCell(item: PivotCacheItem): string {
+  switch (item.kind) {
+    case "missing":
+      return "<m/>";
+    case "number":
+      return `<n v="${item.value}"/>`;
+    case "boolean":
+      return `<b v="${item.value ? 1 : 0}"/>`;
+    case "date":
+      return `<d v="${escapeXml(item.value)}"/>`;
+    case "error":
+      return `<e v="${escapeXml(item.value)}"/>`;
+    case "string":
+      return `<s v="${escapeXml(item.value)}"/>`;
+  }
+}
+
+// =============================================================================
+// pivotCacheDefinition
+// =============================================================================
+
+export function buildPivotCacheDefinitionXml(
+  cache: ParsedPivotCache,
+  enumerate: boolean[],
+  recordCount: number,
+  recordsRelId: string,
+): string {
+  if (cache.source.type !== "worksheet") {
+    throw new Error("buildPivotCacheDefinitionXml: only worksheet sources are supported");
+  }
+  const src = cache.source;
+  const fields = cache.fields
+    .map((f, i) => cacheFieldXml(f, enumerate[i]))
+    .join("");
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<pivotCacheDefinition xmlns="${MAIN_NS}" xmlns:r="${REL_NS}" r:id="${recordsRelId}"` +
+    ` refreshOnLoad="1" refreshedBy="Lotics" createdVersion="6" refreshedVersion="6"` +
+    ` minRefreshableVersion="3" recordCount="${recordCount}">` +
+    `<cacheSource type="worksheet">` +
+    `<worksheetSource ref="${escapeXml(src.ref)}" sheet="${escapeXml(src.sheetName)}"/>` +
+    `</cacheSource>` +
+    `<cacheFields count="${cache.fields.length}">${fields}</cacheFields>` +
+    `</pivotCacheDefinition>`
+  );
+}
+
+function cacheFieldXml(field: PivotCacheField, enumerate: boolean): string {
+  const name = `name="${escapeXml(field.name)}" numFmtId="0"`;
+  if (!enumerate) {
+    // Measure / unused column: no enumerated items, just type hints. Excel
+    // refreshes the rest from the worksheet source.
+    const flags =
+      `containsBlank="${field.items.length === 0 ? 0 : 1}"` +
+      (field.containsNumber ? ` containsString="0" containsNumber="1"` : "");
+    return `<cacheField ${name}><sharedItems ${flags}/></cacheField>`;
+  }
+  const items = field.items.map(sharedItemXml).join("");
+  const hasString = field.items.some((i) => i.kind === "string");
+  const hasNumber = field.items.some((i) => i.kind === "number");
+  const hasBlank = field.items.some((i) => i.kind === "missing");
+  const attrs =
+    `count="${field.items.length}"` +
+    (hasBlank ? ` containsBlank="1"` : "") +
+    (hasNumber && !hasString ? ` containsString="0" containsNumber="1"` : "");
+  return `<cacheField ${name}><sharedItems ${attrs}>${items}</sharedItems></cacheField>`;
+}
+
+function sharedItemXml(item: PivotCacheItem): string {
+  switch (item.kind) {
+    case "missing":
+      return `<m/>`;
+    case "number":
+      return `<n v="${item.value}"/>`;
+    case "boolean":
+      return `<b v="${item.value ? 1 : 0}"/>`;
+    case "date":
+      return `<d v="${escapeXml(item.value)}"/>`;
+    case "error":
+      return `<e v="${escapeXml(item.value)}"/>`;
+    case "string":
+      return `<s v="${escapeXml(item.value)}"/>`;
+  }
+}
+
+// =============================================================================
+// pivotTable
+// =============================================================================
+
+const SUBTOTAL_FN_TO_ENUM: Record<string, string> = {
+  sum: "sum",
+  count: "count",
+  countNums: "countNums",
+  average: "average",
+  min: "min",
+  max: "max",
+  product: "product",
+};
+
+/**
+ * Serialize the pivot table definition. The axis fields (row/col/page) carry a
+ * `<pivotField>` with an `<items>` list; the data and unused fields are emitted
+ * without items. Axis roles are read from `table`, so no enumerate hint is needed.
+ */
+export function buildPivotTableXml(
+  table: ParsedPivotTable,
+  cache: ParsedPivotCache,
+): string {
+  const rowField = table.rowFieldIndices[0];
+  const colField = table.colFieldIndices[0];
+  if (rowField === undefined || colField === undefined) {
+    throw new Error("buildPivotTableXml: a row field and a column field are required");
+  }
+  const pageSet = new Set(table.pageFieldIndices);
+
+  const pivotFields = cache.fields
+    .map((f, i) => {
+      const onAxis =
+        i === rowField ? "axisRow" : i === colField ? "axisCol" : pageSet.has(i) ? "axisPage" : undefined;
+      if (onAxis) return axisPivotFieldXml(onAxis, f.items.length);
+      if (table.dataFields.some((d) => d.fieldIndex === i)) {
+        return `<pivotField dataField="1" showAll="0"/>`;
+      }
+      return `<pivotField showAll="0"/>`;
+    })
+    .join("");
+
+  const rowCount = cache.fields[rowField].items.length;
+  const colCount = cache.fields[colField].items.length;
+  // A bottom grand-total ROW is a colGrandTotals; a right grand-total COLUMN is
+  // a rowGrandTotals (OOXML's naming is "grand totals FOR rows/columns").
+  const rowItems = axisItemsXml("rowItems", rowCount, table.display.colGrandTotals);
+  const colItems = axisItemsXml("colItems", colCount, table.display.rowGrandTotals);
+
+  const pageFieldsXml = table.pageFieldIndices.length
+    ? `<pageFields count="${table.pageFieldIndices.length}">` +
+      table.pageFieldIndices
+        .map((fld) => {
+          const sel = table.fields[fld]?.selectedPageItem;
+          const item = sel === null || sel === undefined ? "" : ` item="${sel}"`;
+          return `<pageField fld="${fld}"${item} hier="-1"/>`;
+        })
+        .join("") +
+      `</pageFields>`
+    : "";
+
+  const dataFieldsXml =
+    `<dataFields count="${table.dataFields.length}">` +
+    table.dataFields
+      .map((d) => {
+        const fn = SUBTOTAL_FN_TO_ENUM[d.subtotal] ?? "sum";
+        const sub = fn === "sum" ? "" : ` subtotal="${fn}"`;
+        const numFmt = d.numFmt ? ` numFmtId="${escapeXml(d.numFmt)}"` : "";
+        return `<dataField name="${escapeXml(d.name)}" fld="${d.fieldIndex}"${sub} baseField="0" baseItem="0"${numFmt}/>`;
+      })
+      .join("") +
+    `</dataFields>`;
+
+  const style =
+    `<pivotTableStyleInfo name="${escapeXml(table.styleName ?? "PivotStyleLight16")}"` +
+    ` showRowHeaders="1" showColHeaders="1"` +
+    ` showRowStripes="${table.display.showRowStripes ? 1 : 0}"` +
+    ` showColStripes="${table.display.showColStripes ? 1 : 0}" showLastColumn="1"/>`;
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<pivotTableDefinition xmlns="${MAIN_NS}" xmlns:r="${REL_NS}"` +
+    ` name="${escapeXml(table.name)}" cacheId="${table.cacheId}"` +
+    ` applyNumberFormats="0" applyBorderFormats="0" applyFontFormats="0"` +
+    ` applyPatternFormats="0" applyAlignmentFormats="0" applyWidthHeightFormats="1"` +
+    ` dataCaption="Values" updatedVersion="6" minRefreshableVersion="3"` +
+    ` useAutoFormatting="1" itemPrintTitles="1" createdVersion="6" indent="0"` +
+    ` outline="1" outlineData="1" multipleFieldFilters="0"` +
+    ` rowGrandTotals="${table.display.rowGrandTotals ? 1 : 0}"` +
+    ` colGrandTotals="${table.display.colGrandTotals ? 1 : 0}">` +
+    // ref spans the body grid only; page-filter rows (if any) are laid out by
+    // Excel above it on refresh, so the location stays body-relative + consistent.
+    `<location ref="${escapeXml(table.ref)}" firstHeaderRow="${table.firstHeaderRow}"` +
+    ` firstDataRow="${table.firstDataRow}" firstDataCol="${table.firstDataCol}"/>` +
+    `<pivotFields count="${cache.fields.length}">${pivotFields}</pivotFields>` +
+    `<rowFields count="1"><field x="${rowField}"/></rowFields>` +
+    rowItems +
+    `<colFields count="1"><field x="${colField}"/></colFields>` +
+    colItems +
+    pageFieldsXml +
+    dataFieldsXml +
+    style +
+    `</pivotTableDefinition>`
+  );
+}
+
+/** A row/col axis field: items listed in shared-item order + a subtotal slot. */
+function axisPivotFieldXml(axis: string, itemCount: number): string {
+  const items: string[] = [];
+  for (let i = 0; i < itemCount; i++) items.push(`<item x="${i}"/>`);
+  items.push(`<item t="default"/>`);
+  return `<pivotField axis="${axis}" showAll="0"><items count="${items.length}">${items.join("")}</items></pivotField>`;
+}
+
+/** `<rowItems>`/`<colItems>`: one `<i>` per shared item (display order = shared
+ *  order, since the cache is pre-sorted) plus a trailing grand-total `<i>`. */
+function axisItemsXml(element: "rowItems" | "colItems", itemCount: number, grandTotal: boolean): string {
+  const items: string[] = [];
+  for (let i = 0; i < itemCount; i++) items.push(`<i><x v="${i}"/></i>`);
+  if (grandTotal) items.push(`<i t="grand"><x/></i>`);
+  return `<${element} count="${items.length}">${items.join("")}</${element}>`;
+}

package/src/xlsx_writer.ts

@@ -12,8 +12,15 @@ import type { WorkbookModel, SheetModel, CellModel } from "./workbook_model";
 import type { CellStyle, RichTextPart, RichTextFont } from "./types";
 import type { ParsedChart, ParsedTable, ParsedDrawing, ChartType, ChartSeries } from "./ooxml_chart_types";
 import type { ParsedConditionalFormat, ParsedCfStyle } from "./excel_cf_types";
-import { rowColToRef, refToRowCol, colNumToLetters } from "./excel_utils";
+import { rowColToRef, refToRowCol, colNumToLetters, escapeXml } from "./excel_utils";
 import { hexToArgb, hexToOoxmlRgb } from "./ooxml_color";
+import { readSourceData } from "./pivot_model";
+import {
+  buildPivotCacheDefinitionXml,
+  buildPivotCacheRecordsXml,
+  buildPivotTableXml,
+  enumerateFlags,
+} from "./pivot_writer";
 
 // =============================================================================
 // Pivot round-trip helpers
@@ -183,6 +190,78 @@ function pivotContentTypeFor(path: string): string | undefined {
   return undefined;
 }
 
+const REL_BASE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+function relsXml(rels: { id: string; type: string; target: string }[]): string {
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n` +
+    `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n` +
+    rels.map((r) => `<Relationship Id="${r.id}" Type="${r.type}" Target="${escapeXml(r.target)}"/>`).join("\n") +
+    `\n</Relationships>`
+  );
+}
+
+/**
+ * Serialize every AUTHORED pivot (built via `buildPivotTable`) into fresh OOXML
+ * parts written straight into `entries`, and return the cross-reference snapshot
+ * the regenerated workbook/sheet rels + content-types consume (same shape the
+ * round-trip path produces). Parsed/round-tripped pivots are skipped — they pass
+ * through verbatim. `startFileIndex` is the first pivotTableN/cacheN suffix,
+ * past any round-tripped pivot files, so paths never collide.
+ */
+function emitAuthoredPivots(
+  workbook: WorkbookModel,
+  entries: Record<string, Uint8Array>,
+  startFileIndex: number,
+): PivotRoundTripInfo {
+  const info: PivotRoundTripInfo = {
+    cachesByWorkbook: new Map(),
+    pivotTablesBySheetIndex: new Map(),
+    pivotXmlPaths: [],
+  };
+  let n = startFileIndex;
+  for (let i = 0; i < workbook.sheets.length; i++) {
+    for (const model of workbook.sheets[i].pivotTables) {
+      if (!model.authored) continue;
+      const idx = n++;
+      const enumerate = enumerateFlags(model.config, model.cache.fields.length);
+      const records = readSourceData(workbook, model.cache)?.records ?? [];
+
+      const cacheDefPath = `xl/pivotCache/pivotCacheDefinition${idx}.xml`;
+      const recordsPath = `xl/pivotCache/pivotCacheRecords${idx}.xml`;
+      const tablePath = `xl/pivotTables/pivotTable${idx}.xml`;
+
+      entries[cacheDefPath] = strToU8(buildPivotCacheDefinitionXml(model.cache, enumerate, records.length, "rId1"));
+      entries[`xl/pivotCache/_rels/pivotCacheDefinition${idx}.xml.rels`] = strToU8(
+        relsXml([{ id: "rId1", type: `${REL_BASE}/pivotCacheRecords`, target: `pivotCacheRecords${idx}.xml` }]),
+      );
+      entries[recordsPath] = strToU8(buildPivotCacheRecordsXml(records, model.cache, enumerate));
+      entries[tablePath] = strToU8(buildPivotTableXml(model.config, model.cache));
+      entries[`xl/pivotTables/_rels/pivotTable${idx}.xml.rels`] = strToU8(
+        relsXml([{ id: "rId1", type: `${REL_BASE}/pivotCacheDefinition`, target: `../pivotCache/pivotCacheDefinition${idx}.xml` }]),
+      );
+
+      info.cachesByWorkbook.set(model.cache.id, `pivotCache/pivotCacheDefinition${idx}.xml`);
+      const list = info.pivotTablesBySheetIndex.get(i) ?? [];
+      list.push(`../pivotTables/pivotTable${idx}.xml`);
+      info.pivotTablesBySheetIndex.set(i, list);
+      info.pivotXmlPaths.push(tablePath, cacheDefPath, recordsPath);
+    }
+  }
+  return info;
+}
+
+function mergePivotInfo(a: PivotRoundTripInfo, b: PivotRoundTripInfo): PivotRoundTripInfo {
+  const cachesByWorkbook = new Map(a.cachesByWorkbook);
+  for (const [k, v] of b.cachesByWorkbook) cachesByWorkbook.set(k, v);
+  const pivotTablesBySheetIndex = new Map<number, string[]>();
+  for (const [k, v] of a.pivotTablesBySheetIndex) pivotTablesBySheetIndex.set(k, [...v]);
+  for (const [k, v] of b.pivotTablesBySheetIndex) {
+    pivotTablesBySheetIndex.set(k, [...(pivotTablesBySheetIndex.get(k) ?? []), ...v]);
+  }
+  return { cachesByWorkbook, pivotTablesBySheetIndex, pivotXmlPaths: [...a.pivotXmlPaths, ...b.pivotXmlPaths] };
+}
+
 // =============================================================================
 // Main export function
 // =============================================================================
@@ -244,11 +323,14 @@ export function exportWorkbook(
     : buildStylesXml(workbook);
   if (!stylesPassthrough) entries["xl/styles.xml"] = strToU8(stylesResult.xml);
 
-  // Pivot round-trip: read original workbook.xml + sheet rels to recover the
-  // (cacheId → cacheDefinition path) and (sheet → pivotTable paths) mappings.
-  // The pivot xml files themselves pass through originalZip; we only need to
-  // re-emit the cross-references in the regenerated parts.
-  const pivotInfo = extractPivotRoundTripInfo(originalZip);
+  // Pivot cross-references. Two sources feed the regenerated workbook/sheet rels
+  // + content-types: pivots ROUND-TRIPPED from `originalZip` (their xml passes
+  // through verbatim) and pivots AUTHORED in the model (serialized fresh here,
+  // straight into `entries`).
+  const roundTripInfo = extractPivotRoundTripInfo(originalZip);
+  const authoredStartIndex =
+    roundTripInfo.pivotXmlPaths.filter((p) => p.startsWith("xl/pivotTables/")).length + 1;
+  const pivotInfo = mergePivotInfo(roundTripInfo, emitAuthoredPivots(workbook, entries, authoredStartIndex));
 
   // Build workbook.xml
   entries["xl/workbook.xml"] = strToU8(buildWorkbookXml(workbook, pivotInfo));
@@ -1539,11 +1621,3 @@ function dataUrlToBytes(dataUrl: string): Uint8Array | null {
 // Helpers
 // =============================================================================
 
-function escapeXml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}