@beyondwork/docx-react-component 1.0.29 → 1.0.30

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

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