@beyondwork/docx-react-component 1.0.27 → 1.0.29

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

@@ -1,453 +0,0 @@
-/**
- * Canonical workbook model.
- *
- * The workbook is the top-level state atom for the xlsx runtime.
- * It owns:
- *   - workbook metadata
- *   - sheet registry and ordering
- *   - shared string table
- *   - workbook-wide style registry
- *   - workbook-level named items (placeholder — expand later)
- *
- * Sheets own their own sparse cell storage, row/col metadata, and merges.
- * See sheet.ts for the CanonicalSheet type.
- *
- * Preservation of unknown workbook parts is handled by the shared OPC
- * preservation layer, not in this model.
- */
-
-import type { CanonicalSheet, ColIndex, ColProperties, MergeRange, RowIndex, RowProperties, SheetPaneState } from "./sheet.ts";
-import { createSheet } from "./sheet.ts";
-import type { WorkbookStyleRegistry, XfRecord, NumFmtRecord } from "./styles.ts";
-import { createEmptyStyleRegistry } from "./styles.ts";
-import type { CellKey, CellValue } from "./cell.ts";
-
-// ---------------------------------------------------------------------------
-// Workbook metadata
-// ---------------------------------------------------------------------------
-
-export interface WorkbookMetadata {
-  /** Application that last saved the file (from app.xml, if present). */
-  application?: string;
-  /** Document title from core properties, if present. */
-  title?: string;
-  /** ISO 8601 timestamp for last modified, if present. */
-  lastModifiedAt?: string;
-  /**
-   * The 1900/1904 date base used for date serial numbers.
-   * Most xlsx files use 1900 (false). Mac-originated files may use 1904 (true).
-   */
-  date1904: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Shared string table
-// ---------------------------------------------------------------------------
-
-/**
- * The workbook shared string table.
- *
- * In SpreadsheetML, text cells may reference an index into a shared strings
- * array rather than embedding the string inline. The canonical model stores
- * the resolved strings here for lookup during model construction.
- *
- * During import, cell values are resolved against this table and stored as
- * `TextCell` with `fromSharedString: true`.
- */
-export interface SharedStringTable {
-  /** The ordered list of shared strings. Index corresponds to xlsx t="s" cell value. */
-  strings: string[];
-}
-
-// ---------------------------------------------------------------------------
-// Named items (workbook-level)
-// ---------------------------------------------------------------------------
-
-/**
- * A workbook-level named range or named constant.
- * Intentionally minimal for phase 1; full formula scoping is later work.
- */
-export interface NamedItem {
-  name: string;
-  /** The formula or reference string as stored in the file. */
-  refersTo: string;
-  /** Sheet scope, if the name is scoped to a single sheet. */
-  localSheetId?: string;
-  hidden?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Canonical workbook
-// ---------------------------------------------------------------------------
-
-/**
- * The canonical workbook model.
- *
- * This is the single source of truth for the xlsx runtime. React renders
- * projections of this model and never mutates it directly. All mutations
- * must flow through typed commands that produce new workbook state.
- */
-export interface CanonicalWorkbook {
-  /**
-   * Workbook schema version for future migrations.
-   * Increment when the shape changes incompatibly.
-   */
-  schemaVersion: typeof WORKBOOK_SCHEMA_VERSION;
-  /** Workbook metadata from file properties. */
-  metadata: WorkbookMetadata;
-  /**
-   * Sheet registry.
-   * Key: sheetId (stable internal id, not the display name).
-   * Ordered access: use `sheetOrder` for tab order.
-   */
-  sheets: Map<string, CanonicalSheet>;
-  /**
-   * Sheet id order — determines tab bar order.
-   * Must stay in sync with `sheets`.
-   */
-  sheetOrder: string[];
-  /** Workbook shared string table. */
-  sharedStrings: SharedStringTable;
-  /** Workbook-level style registry. */
-  styles: WorkbookStyleRegistry;
-  /**
-   * Workbook-level named items (named ranges, named constants).
-   * Empty until a name resolution pass is implemented.
-   */
-  namedItems: NamedItem[];
-}
-
-export const WORKBOOK_SCHEMA_VERSION = "workbook/1" as const;
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-export function createWorkbook(
-  metadata?: Partial<WorkbookMetadata>,
-): CanonicalWorkbook {
-  return {
-    schemaVersion: WORKBOOK_SCHEMA_VERSION,
-    metadata: {
-      date1904: false,
-      ...metadata,
-    },
-    sheets: new Map(),
-    sheetOrder: [],
-    sharedStrings: { strings: [] },
-    styles: createEmptyStyleRegistry(),
-    namedItems: [],
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Sheet registry helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Add a new sheet to the workbook. Appends to end of sheet order by default.
- */
-export function addSheet(
-  workbook: CanonicalWorkbook,
-  sheetId: string,
-  name: string,
-  atIndex?: number,
-): CanonicalSheet {
-  if (workbook.sheets.has(sheetId)) {
-    throw new Error(`Sheet id already exists: ${sheetId}`);
-  }
-  const orderIndex =
-    atIndex !== undefined
-      ? clampSheetIndex(atIndex, workbook.sheetOrder.length)
-      : workbook.sheetOrder.length;
-  const sheet = createSheet(sheetId, name, orderIndex);
-  workbook.sheets.set(sheetId, sheet);
-
-  if (atIndex !== undefined && orderIndex < workbook.sheetOrder.length) {
-    workbook.sheetOrder.splice(orderIndex, 0, sheetId);
-    // Reindex sheets after the insertion point
-    for (let i = orderIndex + 1; i < workbook.sheetOrder.length; i++) {
-      const id = workbook.sheetOrder[i];
-      const s = workbook.sheets.get(id);
-      if (s) s.orderIndex = i;
-    }
-  } else {
-    workbook.sheetOrder.push(sheetId);
-  }
-
-  return sheet;
-}
-
-/**
- * Remove a sheet from the workbook by id.
- * Returns the removed sheet, or undefined if not found.
- */
-export function removeSheet(
-  workbook: CanonicalWorkbook,
-  sheetId: string,
-): CanonicalSheet | undefined {
-  const sheet = workbook.sheets.get(sheetId);
-  if (!sheet) return undefined;
-
-  workbook.sheets.delete(sheetId);
-  const idx = workbook.sheetOrder.indexOf(sheetId);
-  if (idx !== -1) {
-    workbook.sheetOrder.splice(idx, 1);
-    // Reindex remaining sheets
-    for (let i = idx; i < workbook.sheetOrder.length; i++) {
-      const id = workbook.sheetOrder[i];
-      const s = workbook.sheets.get(id);
-      if (s) s.orderIndex = i;
-    }
-  }
-  return sheet;
-}
-
-/**
- * Get a sheet by id. Returns undefined if not found.
- */
-export function getSheet(
-  workbook: CanonicalWorkbook,
-  sheetId: string,
-): CanonicalSheet | undefined {
-  return workbook.sheets.get(sheetId);
-}
-
-/**
- * Get a sheet by display name (case-sensitive). Returns undefined if not found.
- */
-export function getSheetByName(
-  workbook: CanonicalWorkbook,
-  name: string,
-): CanonicalSheet | undefined {
-  for (const sheet of workbook.sheets.values()) {
-    if (sheet.name === name) return sheet;
-  }
-  return undefined;
-}
-
-/**
- * Return sheets in tab order.
- */
-export function listSheets(workbook: CanonicalWorkbook): CanonicalSheet[] {
-  return workbook.sheetOrder
-    .map((id) => workbook.sheets.get(id))
-    .filter((s): s is CanonicalSheet => s !== undefined);
-}
-
-/**
- * Rename a sheet. Throws if the sheet is not found.
- */
-export function renameSheet(
-  workbook: CanonicalWorkbook,
-  sheetId: string,
-  newName: string,
-): void {
-  const sheet = workbook.sheets.get(sheetId);
-  if (!sheet) throw new Error(`Sheet not found: ${sheetId}`);
-  sheet.name = newName;
-}
-
-/**
- * Move a sheet to a new tab position.
- */
-export function moveSheet(
-  workbook: CanonicalWorkbook,
-  sheetId: string,
-  toIndex: number,
-): void {
-  const currentIndex = workbook.sheetOrder.indexOf(sheetId);
-  if (currentIndex === -1) throw new Error(`Sheet not found: ${sheetId}`);
-  const clampedTarget = clampSheetIndex(toIndex, workbook.sheetOrder.length - 1);
-  if (currentIndex === clampedTarget) return;
-
-  workbook.sheetOrder.splice(currentIndex, 1);
-  workbook.sheetOrder.splice(clampedTarget, 0, sheetId);
-
-  // Reindex all sheets
-  for (let i = 0; i < workbook.sheetOrder.length; i++) {
-    const id = workbook.sheetOrder[i];
-    const s = workbook.sheets.get(id);
-    if (s) s.orderIndex = i;
-  }
-}
-
-function clampSheetIndex(index: number, maxIndex: number): number {
-  return Math.max(0, Math.min(index, maxIndex));
-}
-
-// ---------------------------------------------------------------------------
-// Shared string table helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a shared string index to its string value.
- * Returns undefined for out-of-range indices.
- */
-export function resolveSharedString(
-  workbook: CanonicalWorkbook,
-  index: number,
-): string | undefined {
-  return workbook.sharedStrings.strings[index];
-}
-
-/**
- * Add a string to the shared string table and return its index.
- * Does not deduplicate — for import use only.
- */
-export function appendSharedString(
-  workbook: CanonicalWorkbook,
-  value: string,
-): number {
-  workbook.sharedStrings.strings.push(value);
-  return workbook.sharedStrings.strings.length - 1;
-}
-
-// ---------------------------------------------------------------------------
-// Serialization helpers
-//
-// The canonical workbook uses Map-backed stores for O(1) lookup. Since Map
-// is not JSON-serializable by default, these helpers convert to and from a
-// plain-object representation for snapshots and persistence.
-// ---------------------------------------------------------------------------
-
-/** Plain-object form of a sheet for JSON serialization. */
-export interface SerializedSheet {
-  sheetId: string;
-  name: string;
-  orderIndex: number;
-  hidden: boolean;
-  cells: Record<CellKey, CellValue>;
-  rowProps: Record<string, RowProperties>;
-  colProps: Record<string, ColProperties>;
-  merges: MergeRange[];
-  paneState?: SheetPaneState;
-}
-
-/** Plain-object form of the style registry for JSON serialization. */
-export interface SerializedStyleRegistry {
-  cellFormats: XfRecord[];
-  numFormats: Record<string, NumFmtRecord>;
-  cellFormatCount: number;
-}
-
-/** Plain-object form of the entire workbook for JSON serialization. */
-export interface SerializedWorkbook {
-  schemaVersion: typeof WORKBOOK_SCHEMA_VERSION;
-  metadata: WorkbookMetadata;
-  sheets: SerializedSheet[];
-  sheetOrder: string[];
-  sharedStrings: SharedStringTable;
-  styles: SerializedStyleRegistry;
-  namedItems: NamedItem[];
-}
-
-/**
- * Convert a CanonicalWorkbook to a plain JSON-serializable object.
- * Inverse of `workbookFromJson`.
- */
-export function workbookToJson(workbook: CanonicalWorkbook): SerializedWorkbook {
-  const sheets: SerializedSheet[] = [];
-  for (const [, sheet] of workbook.sheets) {
-    const cells: Record<CellKey, CellValue> = {};
-    for (const [key, value] of sheet.cells) {
-      cells[key] = value;
-    }
-    const rowProps: Record<string, RowProperties> = {};
-    for (const [idx, props] of sheet.rowProps) {
-      rowProps[String(idx)] = props;
-    }
-    const colProps: Record<string, ColProperties> = {};
-    for (const [idx, props] of sheet.colProps) {
-      colProps[String(idx)] = props;
-    }
-    sheets.push({
-      sheetId: sheet.sheetId,
-      name: sheet.name,
-      orderIndex: sheet.orderIndex,
-      hidden: sheet.hidden,
-      cells,
-      rowProps,
-      colProps,
-      merges: sheet.merges,
-      paneState: sheet.paneState,
-    });
-  }
-
-  const numFormats: Record<string, NumFmtRecord> = {};
-  for (const [id, fmt] of workbook.styles.numFormats) {
-    numFormats[String(id)] = fmt;
-  }
-
-  return {
-    schemaVersion: workbook.schemaVersion,
-    metadata: workbook.metadata,
-    sheets,
-    sheetOrder: workbook.sheetOrder,
-    sharedStrings: workbook.sharedStrings,
-    styles: {
-      cellFormats: workbook.styles.cellFormats,
-      numFormats,
-      cellFormatCount: workbook.styles.cellFormatCount,
-    },
-    namedItems: workbook.namedItems,
-  };
-}
-
-/**
- * Restore a CanonicalWorkbook from the plain-object form produced by `workbookToJson`.
- * Throws if the schema version does not match.
- */
-export function workbookFromJson(serialized: SerializedWorkbook): CanonicalWorkbook {
-  if (serialized.schemaVersion !== WORKBOOK_SCHEMA_VERSION) {
-    throw new Error(
-      `Unsupported workbook schema version: ${serialized.schemaVersion}. Expected: ${WORKBOOK_SCHEMA_VERSION}`,
-    );
-  }
-
-  const sheetsMap = new Map<string, CanonicalSheet>();
-  for (const s of serialized.sheets) {
-    const cells = new Map<CellKey, CellValue>();
-    for (const [key, value] of Object.entries(s.cells)) {
-      cells.set(key, value);
-    }
-    const rowProps = new Map<RowIndex, RowProperties>();
-    for (const [key, props] of Object.entries(s.rowProps)) {
-      rowProps.set(Number(key), props);
-    }
-    const colProps = new Map<ColIndex, ColProperties>();
-    for (const [key, props] of Object.entries(s.colProps)) {
-      colProps.set(Number(key), props);
-    }
-    sheetsMap.set(s.sheetId, {
-      sheetId: s.sheetId,
-      name: s.name,
-      orderIndex: s.orderIndex,
-      hidden: s.hidden,
-      cells,
-      rowProps,
-      colProps,
-      merges: s.merges,
-      paneState: s.paneState,
-    });
-  }
-
-  const numFormats = new Map<number, NumFmtRecord>();
-  for (const [key, fmt] of Object.entries(serialized.styles.numFormats)) {
-    numFormats.set(Number(key), fmt);
-  }
-
-  return {
-    schemaVersion: serialized.schemaVersion,
-    metadata: serialized.metadata,
-    sheets: sheetsMap,
-    sheetOrder: serialized.sheetOrder,
-    sharedStrings: serialized.sharedStrings,
-    styles: {
-      cellFormats: serialized.styles.cellFormats,
-      numFormats,
-      cellFormatCount: serialized.styles.cellFormatCount,
-    },
-    namedItems: serialized.namedItems,
-  };
-}