@beyondwork/docx-react-component 1.0.29 → 1.0.31

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

@@ -0,0 +1,326 @@
+/**
+ * Sheet model for the canonical workbook.
+ *
+ * Sheets use sparse cell storage: only cells with a non-empty value or
+ * explicit style are stored. Row and column metadata is also sparse.
+ */
+
+import type { CellAddress, CellKey, CellValue, ColIndex, RowIndex, StyleRef } from "./cell.ts";
+import { cellKey } from "./cell.ts";
+
+export type { ColIndex, RowIndex } from "./cell.ts";
+
+// ---------------------------------------------------------------------------
+// Row and column metadata (sparse)
+// ---------------------------------------------------------------------------
+
+export interface RowProperties {
+  /** Zero-based row index. */
+  rowIndex: RowIndex;
+  /** Row height in points, if explicitly set. */
+  heightPt?: number;
+  /** Whether the row is hidden. */
+  hidden?: boolean;
+  /** Whether the row height was set via customHeight attribute. */
+  customHeight?: boolean;
+  /** Style index reference applied at the row level, if present. */
+  styleRef?: StyleRef;
+}
+
+export interface ColProperties {
+  /** Zero-based column index (min == max for single-column entries). */
+  colIndex: ColIndex;
+  /** Column width in characters (Excel's default character unit). */
+  widthChars?: number;
+  /** Whether the column is hidden. */
+  hidden?: boolean;
+  /** Whether the width was explicitly customized. */
+  customWidth?: boolean;
+  /** Style index reference applied at the column level, if present. */
+  styleRef?: StyleRef;
+}
+
+// ---------------------------------------------------------------------------
+// Merge ranges
+// ---------------------------------------------------------------------------
+
+/**
+ * A rectangular merge range in zero-based coordinates.
+ * Stored as a separate collection, not embedded in cell records.
+ */
+export interface MergeRange {
+  /** Inclusive top-left row. */
+  startRow: RowIndex;
+  /** Inclusive top-left column. */
+  startCol: ColIndex;
+  /** Inclusive bottom-right row. */
+  endRow: RowIndex;
+  /** Inclusive bottom-right column. */
+  endCol: ColIndex;
+}
+
+// ---------------------------------------------------------------------------
+// Sheet pane state (freeze/split)
+// ---------------------------------------------------------------------------
+
+export interface SheetPaneState {
+  /** Number of frozen rows from the top. */
+  frozenRows: number;
+  /** Number of frozen columns from the left. */
+  frozenCols: number;
+}
+
+// ---------------------------------------------------------------------------
+// Canonical sheet record
+// ---------------------------------------------------------------------------
+
+/**
+ * A single worksheet in the canonical workbook model.
+ *
+ * - `cells` is sparse: only cells with a value or explicit style are present.
+ * - `rowProps` and `colProps` are sparse: only rows/cols with non-default
+ *   metadata are stored.
+ * - `merges` is a flat list of merge ranges for this sheet.
+ */
+export interface CanonicalSheet {
+  /** Stable sheet identifier used internally (not the display name). */
+  sheetId: string;
+  /** Display name shown in the tab bar. */
+  name: string;
+  /** Position in the workbook sheet order (zero-based). */
+  orderIndex: number;
+  /** Whether the sheet tab is hidden. */
+  hidden: boolean;
+  /**
+   * Sparse cell storage.
+   * Key format: `"<rowIndex>:<colIndex>"` (via `cellKey()`).
+   */
+  cells: Map<CellKey, CellValue>;
+  /**
+   * Sparse row metadata.
+   * Key is the zero-based row index.
+   */
+  rowProps: Map<RowIndex, RowProperties>;
+  /**
+   * Sparse column metadata.
+   * Key is the zero-based column index.
+   */
+  colProps: Map<ColIndex, ColProperties>;
+  /**
+   * Merge ranges on this sheet.
+   * Each entry covers the rectangular region where cells are merged.
+   */
+  merges: MergeRange[];
+  /**
+   * Pane freeze/split state, if any.
+   */
+  paneState?: SheetPaneState;
+}
+
+// ---------------------------------------------------------------------------
+// Sheet factory and mutation helpers
+// ---------------------------------------------------------------------------
+
+export function createSheet(
+  sheetId: string,
+  name: string,
+  orderIndex: number,
+): CanonicalSheet {
+  return {
+    sheetId,
+    name,
+    orderIndex,
+    hidden: false,
+    cells: new Map(),
+    rowProps: new Map(),
+    colProps: new Map(),
+    merges: [],
+  };
+}
+
+/**
+ * Set a cell value in the sparse cell map.
+ * Passing `undefined` removes the cell entry (makes it empty).
+ */
+export function setCell(
+  sheet: CanonicalSheet,
+  row: RowIndex,
+  col: ColIndex,
+  value: CellValue | undefined,
+): void {
+  const key = cellKey(row, col);
+  if (value === undefined) {
+    sheet.cells.delete(key);
+  } else {
+    sheet.cells.set(key, value);
+  }
+}
+
+/**
+ * Get a cell value from the sparse cell map.
+ * Returns `undefined` for empty (absent) cells.
+ */
+export function getCell(
+  sheet: CanonicalSheet,
+  row: RowIndex,
+  col: ColIndex,
+): CellValue | undefined {
+  return sheet.cells.get(cellKey(row, col));
+}
+
+/**
+ * Set sparse row metadata.
+ * Passing `undefined`, or only default fields, removes the row entry.
+ */
+export function setRowProperties(
+  sheet: CanonicalSheet,
+  rowIndex: RowIndex,
+  props: Omit<RowProperties, "rowIndex"> | undefined,
+): void {
+  if (!props || isDefaultRowProperties(props)) {
+    sheet.rowProps.delete(rowIndex);
+    return;
+  }
+
+  sheet.rowProps.set(rowIndex, {
+    rowIndex,
+    ...props,
+  });
+}
+
+export function getRowProperties(
+  sheet: CanonicalSheet,
+  rowIndex: RowIndex,
+): RowProperties | undefined {
+  return sheet.rowProps.get(rowIndex);
+}
+
+/**
+ * Set sparse column metadata.
+ * Passing `undefined`, or only default fields, removes the column entry.
+ */
+export function setColProperties(
+  sheet: CanonicalSheet,
+  colIndex: ColIndex,
+  props: Omit<ColProperties, "colIndex"> | undefined,
+): void {
+  if (!props || isDefaultColProperties(props)) {
+    sheet.colProps.delete(colIndex);
+    return;
+  }
+
+  sheet.colProps.set(colIndex, {
+    colIndex,
+    ...props,
+  });
+}
+
+export function getColProperties(
+  sheet: CanonicalSheet,
+  colIndex: ColIndex,
+): ColProperties | undefined {
+  return sheet.colProps.get(colIndex);
+}
+
+/**
+ * Return the effective address bounds for all occupied cells.
+ * Returns `null` when the sheet has no cells.
+ */
+export function getSheetExtent(sheet: CanonicalSheet): {
+  minRow: RowIndex;
+  maxRow: RowIndex;
+  minCol: ColIndex;
+  maxCol: ColIndex;
+} | null {
+  if (sheet.cells.size === 0) return null;
+
+  let minRow = Infinity;
+  let maxRow = -Infinity;
+  let minCol = Infinity;
+  let maxCol = -Infinity;
+
+  for (const addr of iterateCellAddresses(sheet)) {
+    if (addr.row < minRow) minRow = addr.row;
+    if (addr.row > maxRow) maxRow = addr.row;
+    if (addr.col < minCol) minCol = addr.col;
+    if (addr.col > maxCol) maxCol = addr.col;
+  }
+
+  return { minRow, maxRow, minCol, maxCol };
+}
+
+/**
+ * Iterate over all occupied cell addresses in the sheet.
+ */
+export function* iterateCellAddresses(
+  sheet: CanonicalSheet,
+): Generator<CellAddress> {
+  for (const key of sheet.cells.keys()) {
+    const colon = key.indexOf(":");
+    yield {
+      row: parseInt(key.slice(0, colon), 10),
+      col: parseInt(key.slice(colon + 1), 10),
+    };
+  }
+}
+
+/**
+ * Add a merge range to the sheet. Does not validate for overlaps.
+ */
+export function addMerge(sheet: CanonicalSheet, merge: MergeRange): void {
+  sheet.merges.push(merge);
+}
+
+/**
+ * Remove all merges that match the given range exactly.
+ */
+export function removeMerge(sheet: CanonicalSheet, merge: MergeRange): boolean {
+  const before = sheet.merges.length;
+  sheet.merges = sheet.merges.filter(
+    (m) =>
+      m.startRow !== merge.startRow ||
+      m.startCol !== merge.startCol ||
+      m.endRow !== merge.endRow ||
+      m.endCol !== merge.endCol,
+  );
+  return sheet.merges.length < before;
+}
+
+/**
+ * Find merge ranges that contain the given cell address.
+ */
+export function findMergesContaining(
+  sheet: CanonicalSheet,
+  row: RowIndex,
+  col: ColIndex,
+): MergeRange[] {
+  return sheet.merges.filter(
+    (m) =>
+      row >= m.startRow &&
+      row <= m.endRow &&
+      col >= m.startCol &&
+      col <= m.endCol,
+  );
+}
+
+function isDefaultRowProperties(
+  props: Omit<RowProperties, "rowIndex">,
+): boolean {
+  return (
+    props.heightPt === undefined &&
+    props.hidden === undefined &&
+    props.customHeight === undefined &&
+    props.styleRef === undefined
+  );
+}
+
+function isDefaultColProperties(
+  props: Omit<ColProperties, "colIndex">,
+): boolean {
+  return (
+    props.widthChars === undefined &&
+    props.hidden === undefined &&
+    props.customWidth === undefined &&
+    props.styleRef === undefined
+  );
+}

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

@@ -0,0 +1,118 @@
+/**
+ * Style registry for the canonical workbook model.
+ *
+ * This is intentionally a thin reference layer: the canonical model stores
+ * style indices (xfIndex) on cells and row/column properties. The full
+ * resolved style definitions are stored as preserve-only raw XML until a
+ * proper style engine is built.
+ *
+ * Phase 1 goal: represent enough to round-trip style indices through
+ * import → model → export without losing them.
+ */
+
+// ---------------------------------------------------------------------------
+// Style registry
+// ---------------------------------------------------------------------------
+
+/**
+ * A single cell format record (xf entry from cellXfs in styles.xml).
+ * Kept as an opaque entry so import/export can pass through without loss.
+ */
+export interface XfRecord {
+  /** Original zero-based index in the cellXfs list. */
+  xfIndex: number;
+  /** Font index reference (-1 = not set). */
+  fontId: number;
+  /** Fill index reference (-1 = not set). */
+  fillId: number;
+  /** Border index reference (-1 = not set). */
+  borderId: number;
+  /** Format id (numFmt) reference (-1 = not set). */
+  numFmtId: number;
+  /** Raw xf attributes for round-trip preservation. */
+  rawAttributes: Record<string, string>;
+}
+
+/**
+ * A number format entry from the numFmts table.
+ */
+export interface NumFmtRecord {
+  numFmtId: number;
+  formatCode: string;
+}
+
+/**
+ * The workbook-level style registry.
+ *
+ * In the sparse workbook model, cells store only the xfIndex as a StyleRef.
+ * This registry maps those indices to the underlying format information.
+ * The raw styles.xml bytes are kept in the preservation layer.
+ */
+export interface WorkbookStyleRegistry {
+  /**
+   * Cell format records indexed by xfIndex.
+   * Populated from the cellXfs section of styles.xml during import.
+   */
+  cellFormats: XfRecord[];
+
+  /**
+   * Number format records from the numFmts section.
+   * Keyed by numFmtId.
+   */
+  numFormats: Map<number, NumFmtRecord>;
+
+  /**
+   * Total number of xf records as read from the file.
+   * Used for validation and round-trip fidelity checks.
+   */
+  cellFormatCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function createEmptyStyleRegistry(): WorkbookStyleRegistry {
+  return {
+    cellFormats: [],
+    numFormats: new Map(),
+    cellFormatCount: 0,
+  };
+}
+
+export function getXfRecord(
+  registry: WorkbookStyleRegistry,
+  xfIndex: number,
+): XfRecord | undefined {
+  return registry.cellFormats[xfIndex];
+}
+
+export function getNumFmtRecord(
+  registry: WorkbookStyleRegistry,
+  numFmtId: number,
+): NumFmtRecord | undefined {
+  return registry.numFormats.get(numFmtId);
+}
+
+/**
+ * Returns true when the given xfIndex references a date-formatted cell.
+ * Uses the built-in Excel numFmt IDs 14–17, 22 as heuristic.
+ * Full date detection requires a proper style engine.
+ */
+export function isDateFormatHeuristic(
+  registry: WorkbookStyleRegistry,
+  xfIndex: number,
+): boolean {
+  const xf = getXfRecord(registry, xfIndex);
+  if (!xf) return false;
+  const numFmtId = xf.numFmtId;
+  // Built-in Excel date numFmt IDs
+  if (numFmtId >= 14 && numFmtId <= 17) return true;
+  if (numFmtId === 22) return true;
+  // Custom format?
+  const fmt = getNumFmtRecord(registry, numFmtId);
+  if (!fmt) return false;
+  // Very rough heuristic: contains "y", "m", "d" date tokens
+  const code = fmt.formatCode.toLowerCase();
+  return (code.includes("y") || code.includes("d")) && code.includes("m");
+}