@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/formats/xlsx/io/xlsx-session.ts

@@ -0,0 +1,314 @@
+/**
+ * SpreadsheetML import session.
+ *
+ * Orchestrates the OPC package reader, per-part parsers, and canonical workbook
+ * model construction into a single import entry point.
+ *
+ * Architecture:
+ *   readOpcPackage → find workbook part via officeDocument relationship
+ *     → parseWorkbookXml (sheet registry, date1904)
+ *     → parseSharedStringsXml (shared string table)
+ *     → parseStylesXml → buildStyleRegistry (cell format + numFmt records)
+ *     → parseSheetXml per sheet → populate CanonicalSheet cells/merges
+ *   → return XlsxImportResult
+ */
+
+import { readOpcPackage } from "../../../io/opc/package-reader.ts";
+import { resolveRelationshipTarget } from "../../../io/ooxml/part-manifest.ts";
+import type { CanonicalWorkbook } from "../model/workbook.ts";
+import { addSheet, createWorkbook } from "../model/workbook.ts";
+import { addMerge, setCell } from "../model/sheet.ts";
+import type { CellValue, CellErrorCode, CachedFormulaValue, StyleRef } from "../model/cell.ts";
+import {
+  makeBlankCell,
+  makeBooleanCell,
+  makeErrorCell,
+  makeFormulaCell,
+  makeNumberCell,
+  makeTextCell,
+} from "../model/cell.ts";
+import type { WorkbookStyleRegistry, NumFmtRecord, XfRecord } from "../model/styles.ts";
+import { createEmptyStyleRegistry } from "../model/styles.ts";
+import { parseWorkbookXml } from "./parse-workbook.ts";
+import { parseSharedStringsXml } from "./parse-shared-strings.ts";
+import { parseStylesXml, parseXmlAttributes } from "./parse-styles.ts";
+import { parseSheetXml } from "./parse-sheet.ts";
+import type { XlsxParsedCellValue, XlsxParsedFormulaCachedValue } from "./parse-sheet.ts";
+
+// ---------------------------------------------------------------------------
+// Relationship type constants (SpreadsheetML / OPC)
+// ---------------------------------------------------------------------------
+
+export const XLSX_OFFICE_DOCUMENT_REL_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+const XLSX_WORKSHEET_REL_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
+const XLSX_SHARED_STRINGS_REL_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings";
+const XLSX_STYLES_REL_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface XlsxImportResult {
+  workbook: CanonicalWorkbook;
+  /** Non-fatal issues encountered during import (missing optional parts, etc.). */
+  warnings: string[];
+}
+
+/**
+ * Import a .xlsx package from raw bytes into a canonical workbook model.
+ *
+ * Throws on fatal structural errors (invalid OPC, missing workbook part).
+ * Non-fatal issues (missing optional parts) are collected in `warnings`.
+ *
+ * @param source Raw xlsx bytes (Uint8Array or ArrayBuffer).
+ */
+export function loadXlsxWorkbook(source: Uint8Array | ArrayBuffer): XlsxImportResult {
+  const pkg = readOpcPackage(source);
+  const warnings: string[] = [];
+
+  // 1. Locate the workbook part via the officeDocument package relationship.
+  const workbookRel = pkg.manifest.packageRelationships.find(
+    (r) => r.type === XLSX_OFFICE_DOCUMENT_REL_TYPE,
+  );
+  if (!workbookRel) {
+    throw new Error("XLSX package missing officeDocument relationship.");
+  }
+
+  const workbookPath = resolveRelationshipTarget(null, workbookRel);
+  const workbookPart = pkg.parts.get(workbookPath);
+  if (!workbookPart) {
+    throw new Error(`Workbook part not found at ${workbookPath}.`);
+  }
+
+  const workbookXml = decodePartBytes(workbookPart.bytes);
+  const workbookData = parseWorkbookXml(workbookXml);
+
+  // 2. Parse shared strings (optional part — many xlsx files omit it entirely).
+  let sharedStrings: string[] = [];
+  const ssRel = workbookPart.relationships.find((r) => r.type === XLSX_SHARED_STRINGS_REL_TYPE);
+  if (ssRel) {
+    const ssPath = resolveRelationshipTarget(workbookPath, ssRel);
+    const ssPart = pkg.parts.get(ssPath);
+    if (ssPart) {
+      sharedStrings = parseSharedStringsXml(decodePartBytes(ssPart.bytes));
+    } else {
+      warnings.push(`Shared strings part declared but missing: ${ssPath}`);
+    }
+  }
+
+  // 3. Parse styles (optional — absent means no cell format references).
+  let styleRegistry: WorkbookStyleRegistry = createEmptyStyleRegistry();
+  const stylesRel = workbookPart.relationships.find((r) => r.type === XLSX_STYLES_REL_TYPE);
+  if (stylesRel) {
+    const stylesPath = resolveRelationshipTarget(workbookPath, stylesRel);
+    const stylesPart = pkg.parts.get(stylesPath);
+    if (stylesPart) {
+      styleRegistry = buildStyleRegistry(decodePartBytes(stylesPart.bytes));
+    } else {
+      warnings.push(`Styles part declared but missing: ${stylesPath}`);
+    }
+  }
+
+  // 4. Build the canonical workbook.
+  const workbook = createWorkbook({ date1904: workbookData.date1904 });
+  workbook.sharedStrings = { strings: sharedStrings };
+  workbook.styles = styleRegistry;
+
+  // 5. Import each sheet in declared order.
+  for (const entry of workbookData.sheets) {
+    const sheetRel = workbookPart.relationships.find((r) => r.id === entry.relationshipId);
+    if (!sheetRel) {
+      warnings.push(
+        `No relationship found for sheet "${entry.name}" (r:id=${entry.relationshipId}).`,
+      );
+      continue;
+    }
+
+    const sheetPath = resolveRelationshipTarget(workbookPath, sheetRel);
+    const sheetPart = pkg.parts.get(sheetPath);
+    if (!sheetPart) {
+      warnings.push(`Sheet part not found at ${sheetPath} for sheet "${entry.name}".`);
+      continue;
+    }
+
+    const sheet = addSheet(workbook, entry.sheetId, entry.name);
+    if (entry.state !== "visible") {
+      sheet.hidden = true;
+    }
+
+    const sheetData = parseSheetXml(decodePartBytes(sheetPart.bytes), sharedStrings);
+
+    for (const parsedCell of sheetData.cells) {
+      const styleRef: StyleRef | undefined =
+        parsedCell.styleIndex !== null ? { xfIndex: parsedCell.styleIndex } : undefined;
+      const cellValue = convertParsedCellValue(parsedCell.value, styleRef);
+      if (cellValue !== null) {
+        setCell(sheet, parsedCell.row, parsedCell.col, cellValue);
+      }
+    }
+
+    for (const merge of sheetData.merges) {
+      addMerge(sheet, {
+        startRow: merge.startRow,
+        startCol: merge.startCol,
+        endRow: merge.endRow,
+        endCol: merge.endCol,
+      });
+    }
+  }
+
+  return { workbook, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// Style registry builder
+// ---------------------------------------------------------------------------
+
+function buildStyleRegistry(stylesXml: string): WorkbookStyleRegistry {
+  const entries = parseStylesXml(stylesXml);
+  const cellFormats: XfRecord[] = entries.map(
+    (entry, index): XfRecord => ({
+      xfIndex: index,
+      fontId: entry.fontId,
+      fillId: entry.fillId,
+      borderId: entry.borderId,
+      numFmtId: entry.numFmtId,
+      rawAttributes: entry.rawAttributes,
+    }),
+  );
+
+  return {
+    cellFormats,
+    numFormats: parseNumFmtRecords(stylesXml),
+    cellFormatCount: entries.length,
+  };
+}
+
+/**
+ * Extracts custom numFmt records from the <numFmts> section of styles.xml.
+ * Built-in Excel numFmt IDs (0–163) are not stored here; they are resolved
+ * by the style engine's built-in table when needed.
+ */
+function parseNumFmtRecords(xml: string): Map<number, NumFmtRecord> {
+  const result = new Map<number, NumFmtRecord>();
+  const numFmtsMatch = /<numFmts\b[^>]*>([\s\S]*?)<\/numFmts>/i.exec(xml);
+  if (!numFmtsMatch) {
+    return result;
+  }
+
+  const numFmtPattern = /<numFmt\b([^>]*?)(?:\/>|>[\s\S]*?<\/numFmt>)/g;
+  let match: RegExpExecArray | null;
+  while ((match = numFmtPattern.exec(numFmtsMatch[1] ?? "")) !== null) {
+    const attrs = parseXmlAttributes(match[1] ?? "");
+    const rawId = attrs["numFmtId"];
+    const formatCode = attrs["formatCode"] ?? "";
+    if (rawId === undefined) {
+      continue;
+    }
+    const numFmtId = parseInt(rawId, 10);
+    if (!Number.isNaN(numFmtId)) {
+      result.set(numFmtId, { numFmtId, formatCode });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Cell value conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a parse-layer cell value to a canonical CellValue.
+ *
+ * Returns null for blank cells without a style reference — these are omitted
+ * from sparse storage. Blank cells WITH a style reference are preserved as
+ * BlankCell so the style index is not lost.
+ */
+function convertParsedCellValue(
+  parsed: XlsxParsedCellValue,
+  styleRef: StyleRef | undefined,
+): CellValue | null {
+  switch (parsed.type) {
+    case "blank":
+      // Only store blank if it carries a style (e.g. formatted empty cell).
+      return styleRef ? makeBlankCell(styleRef) : null;
+
+    case "text":
+      return makeTextCell(parsed.value, parsed.fromSharedString, styleRef);
+
+    case "number":
+      return makeNumberCell(parsed.value, styleRef);
+
+    case "boolean":
+      return makeBooleanCell(parsed.value, styleRef);
+
+    case "error":
+      return makeErrorCell(normalizeErrorCode(parsed.errorCode), styleRef);
+
+    case "formula":
+      return makeFormulaCell(
+        parsed.formula,
+        convertCachedFormulaValue(parsed.cachedValue),
+        styleRef,
+        parsed.referenceTokens,
+      );
+  }
+}
+
+/** Normalize a raw error string to the canonical CellErrorCode union. */
+function normalizeErrorCode(raw: string): CellErrorCode {
+  const known: CellErrorCode[] = [
+    "#NULL!", "#DIV/0!", "#VALUE!", "#REF!", "#NAME?",
+    "#NUM!", "#N/A", "#GETTING_DATA", "#SPILL!",
+  ];
+  const upper = raw.toUpperCase();
+  for (const code of known) {
+    if (code === upper) return code;
+  }
+  // Unknown error code: fall back to #VALUE! to avoid crashing.
+  return "#VALUE!";
+}
+
+/**
+ * Convert a raw cached-value string from the parse layer into a typed
+ * CachedFormulaValue for the canonical model.
+ *
+ * Phase-1 heuristic: try to parse as a number first, otherwise treat as text.
+ * More precise type inference requires the cell's `t` attribute, which the
+ * parse layer does not currently surface for formula cells.
+ */
+function convertCachedFormulaValue(
+  cachedValue: XlsxParsedFormulaCachedValue | null,
+): CachedFormulaValue | undefined {
+  if (cachedValue === null) {
+    return undefined;
+  }
+
+  switch (cachedValue.type) {
+    case "blank":
+      return { type: "blank" };
+    case "number":
+      return { type: "number", value: cachedValue.value };
+    case "text":
+      return { type: "text", value: cachedValue.value };
+    case "boolean":
+      return { type: "boolean", value: cachedValue.value };
+    case "error":
+      return { type: "error", errorCode: normalizeErrorCode(cachedValue.errorCode) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const UTF8_DECODER = new TextDecoder("utf-8");
+
+function decodePartBytes(bytes: Uint8Array): string {
+  return UTF8_DECODER.decode(bytes);
+}

package/src/formats/xlsx/model/cell.ts

@@ -0,0 +1,189 @@
+/**
+ * Cell value types for the canonical workbook model.
+ *
+ * Canonical cell state preserves semantic type without coercing everything
+ * into a single JavaScript value shape. Empty cells are omitted from canonical
+ * storage — this file defines what IS stored when a cell is present.
+ */
+
+// ---------------------------------------------------------------------------
+// Cell addresses
+// ---------------------------------------------------------------------------
+
+/** Zero-based row index. */
+export type RowIndex = number;
+
+/** Zero-based column index. */
+export type ColIndex = number;
+
+/**
+ * A cell address expressed as a zero-based (row, col) pair.
+ * Sparse storage uses this as the logical key.
+ */
+export interface CellAddress {
+  row: RowIndex;
+  col: ColIndex;
+}
+
+/** Compact string key for use in Maps/Records: `"<row>:<col>"`. */
+export type CellKey = string;
+
+export function cellKey(row: RowIndex, col: ColIndex): CellKey {
+  return `${row}:${col}`;
+}
+
+export function parseCellKey(key: CellKey): CellAddress {
+  const colon = key.indexOf(":");
+  if (colon === -1) {
+    throw new Error(`Invalid cell key: ${key}`);
+  }
+  return {
+    row: parseInt(key.slice(0, colon), 10),
+    col: parseInt(key.slice(colon + 1), 10),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Cell value families
+// ---------------------------------------------------------------------------
+
+export interface BlankCell {
+  kind: "blank";
+  styleRef?: StyleRef;
+}
+
+export interface TextCell {
+  kind: "text";
+  /** Raw string value or a shared-string index if sharedStringIndex is set. */
+  value: string;
+  /** When true, `value` is the resolved string from the shared-string table. */
+  fromSharedString: boolean;
+  styleRef?: StyleRef;
+}
+
+export interface NumberCell {
+  kind: "number";
+  value: number;
+  styleRef?: StyleRef;
+}
+
+export interface BooleanCell {
+  kind: "boolean";
+  value: boolean;
+  styleRef?: StyleRef;
+}
+
+export interface ErrorCell {
+  kind: "error";
+  errorCode: CellErrorCode;
+  styleRef?: StyleRef;
+}
+
+export interface FormulaCell {
+  kind: "formula";
+  formula: string;
+  /**
+   * Reference tokens extracted from the formula string for remapping.
+   * Examples: ["A1", "B2:C3", "Sheet1!A1"] from `=SUM(A1,Sheet1!A1)+B2:C3`.
+   * Populated during import; required for safe row/column/range structural edits.
+   * Empty array means the formula has no cell references (e.g. `=TODAY()`).
+   */
+  referenceTokens: string[];
+  /** Cached display value, if available from the parsed file. */
+  cachedValue?: CachedFormulaValue;
+  styleRef?: StyleRef;
+}
+
+/** Standard Excel error codes. */
+export type CellErrorCode =
+  | "#NULL!"
+  | "#DIV/0!"
+  | "#VALUE!"
+  | "#REF!"
+  | "#NAME?"
+  | "#NUM!"
+  | "#N/A"
+  | "#GETTING_DATA"
+  | "#SPILL!";
+
+/** The cached value that was stored alongside a formula at last save. */
+export type CachedFormulaValue =
+  | { type: "number"; value: number }
+  | { type: "text"; value: string }
+  | { type: "boolean"; value: boolean }
+  | { type: "error"; errorCode: CellErrorCode }
+  | { type: "blank" };
+
+/**
+ * The union of all canonical cell value kinds.
+ * Every present cell in sparse storage is one of these.
+ */
+export type CellValue =
+  | BlankCell
+  | TextCell
+  | NumberCell
+  | BooleanCell
+  | ErrorCell
+  | FormulaCell;
+
+// ---------------------------------------------------------------------------
+// Style reference (intentionally thin — full style engine is later work)
+// ---------------------------------------------------------------------------
+
+/**
+ * A reference into the workbook's style registry.
+ * Index corresponds to a style record in the styles table.
+ * The full style definition is preserve-only until a style engine is built.
+ */
+export interface StyleRef {
+  /** Zero-based index into the workbook style table (xf index from styles.xml). */
+  xfIndex: number;
+}
+
+// ---------------------------------------------------------------------------
+// Cell helpers
+// ---------------------------------------------------------------------------
+
+export function makeBlankCell(styleRef?: StyleRef): BlankCell {
+  return styleRef ? { kind: "blank", styleRef } : { kind: "blank" };
+}
+
+export function makeTextCell(value: string, fromSharedString: boolean, styleRef?: StyleRef): TextCell {
+  const cell: TextCell = { kind: "text", value, fromSharedString };
+  if (styleRef) cell.styleRef = styleRef;
+  return cell;
+}
+
+export function makeNumberCell(value: number, styleRef?: StyleRef): NumberCell {
+  const cell: NumberCell = { kind: "number", value };
+  if (styleRef) cell.styleRef = styleRef;
+  return cell;
+}
+
+export function makeBooleanCell(value: boolean, styleRef?: StyleRef): BooleanCell {
+  const cell: BooleanCell = { kind: "boolean", value };
+  if (styleRef) cell.styleRef = styleRef;
+  return cell;
+}
+
+export function makeErrorCell(errorCode: CellErrorCode, styleRef?: StyleRef): ErrorCell {
+  const cell: ErrorCell = { kind: "error", errorCode };
+  if (styleRef) cell.styleRef = styleRef;
+  return cell;
+}
+
+export function makeFormulaCell(
+  formula: string,
+  cachedValue?: CachedFormulaValue,
+  styleRef?: StyleRef,
+  referenceTokens?: string[],
+): FormulaCell {
+  const cell: FormulaCell = {
+    kind: "formula",
+    formula,
+    referenceTokens: referenceTokens ?? [],
+  };
+  if (cachedValue !== undefined) cell.cachedValue = cachedValue;
+  if (styleRef) cell.styleRef = styleRef;
+  return cell;
+}