@beyondwork/docx-react-component 1.0.27 → 1.0.29

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

@@ -1,314 +0,0 @@
-/**
- * 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

@@ -1,189 +0,0 @@
-/**
- * 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;
-}