@casualoffice/sheets 0.9.0

package/src/xlsx/data-validation-resource.ts

@@ -0,0 +1,219 @@
+import type ExcelJS from 'exceljs';
+import type { IRange, IWorkbookData } from '@univerjs/core';
+
+/**
+ * xlsx-native `worksheet.dataValidations` ⇄ Univer
+ * `SHEET_DATA_VALIDATION_PLUGIN` resource bridge.
+ *
+ * Data-validation rules live on the worksheet in xlsx (`xl/worksheets/
+ * sheetN.xml` `<dataValidations>` element). Univer's data-validation
+ * plugin keeps them in a resource keyed by sheet id under the name
+ * below — same registration pattern as defined-names and
+ * thread-comments. We mirror in both directions so:
+ *
+ *   - a file authored in real Excel keeps its list / whole / date /
+ *     decimal constraints when opened here (parser fall-back)
+ *   - our save round-trip preserves the rule even when the exporter
+ *     is called without the live `extras` from the running app — eg.
+ *     the audit harness drives `parse → snapshot → export` only.
+ *
+ * Resource name matches Univer's plugin (`vendor/univer/packages/
+ * data-validation/src/controllers/dv-resource.controller.ts:23`) so
+ * the rules live-load into the plugin on re-open instead of just
+ * sitting in our sidecar — bonus on top of the round-trip.
+ */
+
+export const DATA_VALIDATION_RESOURCE = 'SHEET_DATA_VALIDATION_PLUGIN';
+
+export type SynthDvRule = {
+  uid: string;
+  type: string; // 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom' | 'any'
+  ranges: IRange[];
+  formula1?: string;
+  formula2?: string;
+  operator?: string;
+  allowBlank?: boolean;
+  error?: string;
+  errorTitle?: string;
+  showErrorMessage?: boolean;
+  errorStyle?: string;
+  prompt?: string;
+  promptTitle?: string;
+  showInputMessage?: boolean;
+};
+
+function lettersToCol(letters: string): number {
+  let col = 0;
+  for (let i = 0; i < letters.length; i++) col = col * 26 + (letters.charCodeAt(i) - 64);
+  return col - 1;
+}
+
+function colToLetters(n: number): string {
+  let out = '';
+  let v = n;
+  while (v >= 0) {
+    out = String.fromCharCode(65 + (v % 26)) + out;
+    v = Math.floor(v / 26) - 1;
+  }
+  return out;
+}
+
+/**
+ * Parse a single ExcelJS range token (`'D2:D4'` or `'$A$1'`) into an
+ * IRange. Returns null on malformed input — callers should skip.
+ */
+function rangeStrToIRange(s: string): IRange | null {
+  const part = s.includes('!') ? (s.split('!').pop() ?? s) : s;
+  const m = /^\$?([A-Z]+)\$?(\d+)(?::\$?([A-Z]+)\$?(\d+))?$/.exec(part.trim());
+  if (!m) return null;
+  const c0 = lettersToCol(m[1]);
+  const r0 = Number(m[2]) - 1;
+  const c1 = m[3] ? lettersToCol(m[3]) : c0;
+  const r1 = m[4] ? Number(m[4]) - 1 : r0;
+  return { startRow: r0, endRow: r1, startColumn: c0, endColumn: c1 };
+}
+
+function iRangeToStr(r: IRange): string {
+  const a = `${colToLetters(r.startColumn)}${r.startRow + 1}`;
+  const b = `${colToLetters(r.endColumn)}${r.endRow + 1}`;
+  return a === b ? a : `${a}:${b}`;
+}
+
+/**
+ * Walk every worksheet and lift its `dataValidations.model` into the
+ * synthesised plugin shape. ExcelJS stores rules keyed by a range
+ * string that may be space-separated when a single rule covers
+ * multiple ranges; we expand those into the `ranges` array.
+ */
+export function readDataValidationFromXlsx(
+  wb: ExcelJS.Workbook,
+  sheetIdForExcel: (excelId: number) => string,
+): Record<string, SynthDvRule[]> {
+  const out: Record<string, SynthDvRule[]> = {};
+  let seq = 0;
+  for (const ws of wb.worksheets) {
+    const dv = (ws as unknown as { dataValidations?: { model?: Record<string, unknown> } })
+      .dataValidations;
+    const model = dv?.model;
+    if (!model || typeof model !== 'object') continue;
+
+    const rules: SynthDvRule[] = [];
+    for (const [rangeStr, specUnknown] of Object.entries(model)) {
+      const spec = specUnknown as Record<string, unknown>;
+      if (!spec || typeof spec !== 'object') continue;
+      const ranges: IRange[] = [];
+      // ExcelJS keys can be `'D2:D4'`, `'D2:D4 F2:F4'`, or comma-joined.
+      for (const piece of rangeStr.split(/[\s,]+/)) {
+        const r = rangeStrToIRange(piece);
+        if (r) ranges.push(r);
+      }
+      if (ranges.length === 0) continue;
+
+      const formulae = Array.isArray(spec.formulae) ? (spec.formulae as unknown[]) : undefined;
+      const rule: SynthDvRule = {
+        uid: `dv-${seq++}`,
+        type: typeof spec.type === 'string' ? spec.type : 'any',
+        ranges,
+        ...(typeof formulae?.[0] === 'string' ? { formula1: formulae[0] } : {}),
+        ...(typeof formulae?.[1] === 'string' ? { formula2: formulae[1] } : {}),
+        ...(typeof spec.operator === 'string' ? { operator: spec.operator } : {}),
+        ...(typeof spec.allowBlank === 'boolean' ? { allowBlank: spec.allowBlank } : {}),
+        ...(typeof spec.error === 'string' ? { error: spec.error } : {}),
+        ...(typeof spec.errorTitle === 'string' ? { errorTitle: spec.errorTitle } : {}),
+        ...(typeof spec.showErrorMessage === 'boolean'
+          ? { showErrorMessage: spec.showErrorMessage }
+          : {}),
+        ...(typeof spec.errorStyle === 'string' ? { errorStyle: spec.errorStyle } : {}),
+        ...(typeof spec.prompt === 'string' ? { prompt: spec.prompt } : {}),
+        ...(typeof spec.promptTitle === 'string' ? { promptTitle: spec.promptTitle } : {}),
+        ...(typeof spec.showInputMessage === 'boolean'
+          ? { showInputMessage: spec.showInputMessage }
+          : {}),
+      };
+      rules.push(rule);
+    }
+    if (rules.length > 0) out[sheetIdForExcel(ws.id)] = rules;
+  }
+  return out;
+}
+
+/**
+ * Merge a synthesised DV map into the workbook's `resources` array.
+ * Skipped when the workbook already carries the plugin resource (from
+ * our hidden sidecar) — that one came through Univer's model and has
+ * the full rule shape; xlsx-derived rules are a strict subset.
+ */
+export function mergeDataValidationIntoResources(
+  resources: IWorkbookData['resources'],
+  payload: Record<string, SynthDvRule[]>,
+): IWorkbookData['resources'] {
+  if (Object.keys(payload).length === 0) return resources;
+  const existing = resources?.find((r) => r.name === DATA_VALIDATION_RESOURCE);
+  if (existing) return resources;
+  const next = [...(resources ?? [])];
+  next.push({ name: DATA_VALIDATION_RESOURCE, data: JSON.stringify(payload) });
+  return next;
+}
+
+/** Read the DV resource off a snapshot. Tolerant of older / missing /
+ *  malformed payloads. */
+export function readDataValidationFromSnapshot(
+  data: IWorkbookData,
+): Record<string, SynthDvRule[]> {
+  const entry = data.resources?.find((r) => r.name === DATA_VALIDATION_RESOURCE);
+  if (!entry?.data) return {};
+  try {
+    const parsed = JSON.parse(entry.data) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== 'object') return {};
+    const out: Record<string, SynthDvRule[]> = {};
+    for (const [sheetId, value] of Object.entries(parsed)) {
+      if (!Array.isArray(value)) continue;
+      const bucket: SynthDvRule[] = [];
+      for (const r of value) {
+        if (!r || typeof r !== 'object') continue;
+        const obj = r as Record<string, unknown>;
+        if (!Array.isArray(obj.ranges) || typeof obj.type !== 'string') continue;
+        bucket.push(r as SynthDvRule);
+      }
+      if (bucket.length > 0) out[sheetId] = bucket;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** Apply a per-sheet rule set onto an ExcelJS worksheet. */
+export function applyDataValidationToXlsxWorksheet(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ws: any,
+  rules: SynthDvRule[],
+): void {
+  if (!rules?.length) return;
+  for (const rule of rules) {
+    const formulae: string[] = [];
+    if (rule.formula1 !== undefined) formulae.push(rule.formula1);
+    if (rule.formula2 !== undefined) formulae.push(rule.formula2);
+    const spec: Record<string, unknown> = {
+      type: rule.type,
+      ...(formulae.length ? { formulae } : {}),
+      ...(rule.operator ? { operator: rule.operator } : {}),
+      ...(rule.allowBlank !== undefined ? { allowBlank: rule.allowBlank } : {}),
+      ...(rule.error !== undefined ? { error: rule.error } : {}),
+      ...(rule.errorTitle !== undefined ? { errorTitle: rule.errorTitle } : {}),
+      ...(rule.showErrorMessage !== undefined ? { showErrorMessage: rule.showErrorMessage } : {}),
+      ...(rule.errorStyle !== undefined ? { errorStyle: rule.errorStyle } : {}),
+      ...(rule.prompt !== undefined ? { prompt: rule.prompt } : {}),
+      ...(rule.promptTitle !== undefined ? { promptTitle: rule.promptTitle } : {}),
+      ...(rule.showInputMessage !== undefined ? { showInputMessage: rule.showInputMessage } : {}),
+    };
+    for (const range of rule.ranges) {
+      try {
+        ws.dataValidations.add(iRangeToStr(range), spec);
+      } catch {
+        // Bad ranges (eg. references into a now-deleted sheet) shouldn't
+        // kill the export. Drop the entry quietly; the rest still ship.
+      }
+    }
+  }
+}

package/src/xlsx/import.ts

@@ -0,0 +1,35 @@
+import type { IWorkbookData } from '@univerjs/core';
+import { timeItAsync } from './_perf';
+import { parseXlsxInWorker } from './parse-in-worker';
+
+/**
+ * Public entry point for xlsx import. The actual ExcelJS work lives in a
+ * Web Worker (`parser.worker.ts` → `parse-impl.ts`) so the main thread
+ * stays responsive while a multi-MB workbook is being parsed. This file
+ * stays type-only on the main bundle — ExcelJS doesn't get pulled in
+ * here.
+ *
+ * Fidelity scope (MVP):
+ *   - Values + formulas (cell.value / cell.formula)
+ *   - Font (family, size, bold, italic, underline, color)
+ *   - Fill (solid background)
+ *   - Alignment (horizontal, vertical, wrap)
+ *   - Number format
+ *   - Borders (thin, per side, color preserved)
+ *   - Merges
+ *   - Sheet order + names
+ *
+ * Accepts loss: charts, drawings, pivots, validation, conditional formatting,
+ * data tables, comments, hyperlinks, advanced borders (dashed/double), themes.
+ */
+
+/**
+ * Workbook data ready to mount. Stage 5 of the pipeline folded
+ * hyperlinks into `cell.p.body.customRanges` inline, so no more
+ * `__pendingHyperlinks` side-channel — the snapshot is self-contained.
+ */
+export type ImportedWorkbook = IWorkbookData;
+
+export async function xlsxToWorkbookData(buffer: ArrayBuffer): Promise<ImportedWorkbook> {
+  return timeItAsync('parse-xlsx', () => parseXlsxInWorker(buffer));
+}

package/src/xlsx/index.ts

@@ -0,0 +1,40 @@
+/**
+ * xlsx — `.xlsx` ↔ Univer IWorkbookData converters.
+ *
+ * Phase-A surface (this release): IMPORT only.
+ *
+ *   import { xlsxToWorkbookData } from '@casualoffice/sheets/xlsx';
+ *
+ * The parser runs in a Web Worker so multi-MB workbooks don't block
+ * the main thread; bundler must support the `new Worker(new URL(...),
+ * import.meta.url)` pattern (Vite, esbuild's bundler, modern webpack
+ * with worker-plugin).
+ *
+ * Fidelity scope:
+ *   - Values + formulas
+ *   - Font (family, size, bold, italic, underline, color)
+ *   - Fill (solid background)
+ *   - Alignment (horizontal, vertical, wrap)
+ *   - Number format
+ *   - Borders (thin, per side, color preserved)
+ *   - Merges
+ *   - Sheet order + names
+ *   - Tables, comments, data validation, page setup, named ranges (resources)
+ *
+ * Accepts loss: charts, drawings, pivots, sparklines, advanced borders
+ * (dashed/double), themes.
+ *
+ * The shared utilities below (style mappers + resource readers) are
+ * exposed for hosts that ship their own xlsx export path and want to
+ * stay in lockstep with this importer's shape. Casual Sheets' own
+ * apps/web uses them for that reason. Other consumers can ignore.
+ */
+
+export { xlsxToWorkbookData, type ImportedWorkbook } from './import';
+export * from './style-mapping';
+export * from './constants';
+export * from './comments-resource';
+export * from './page-setup-resource';
+export * from './data-validation-resource';
+export * from './tables-resource';
+export * from './passthrough-resource';

package/src/xlsx/page-setup-resource.ts

@@ -0,0 +1,205 @@
+import type ExcelJS from 'exceljs';
+import type { IWorkbookData } from '@univerjs/core';
+
+/**
+ * Passthrough preservation for xlsx-native page-setup chrome —
+ * orientation, paper size, margins, header/footer text. Univer
+ * doesn't model any of this; the print dialog uses a per-user
+ * localStorage slot. Without a passthrough, opening an xlsx that
+ * was authored to print landscape and saving it again silently
+ * resets to portrait.
+ *
+ * The round-trip stays inside our own resource sidecar
+ * (`__casual_sheets_page_setup__`) — the data never reaches Univer
+ * for editing; the parser stashes it on `IWorkbookData.resources`
+ * and the exporter reads it back and applies to ExcelJS's native
+ * `worksheet.pageSetup` + `worksheet.headerFooter`.
+ *
+ * If/when we add an in-app Page Setup editor, this resource is the
+ * authoritative store — the localStorage fallback is per-user and
+ * can't survive Save → Open in another tab.
+ */
+
+export const PAGE_SETUP_RESOURCE = '__casual_sheets_page_setup__';
+
+export type SheetPageSetupV1 = {
+  orientation?: 'landscape' | 'portrait';
+  paperSize?: number;
+  fitToPage?: boolean;
+  fitToWidth?: number;
+  fitToHeight?: number;
+  scale?: number;
+  printArea?: string;
+  margins?: {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+    header?: number;
+    footer?: number;
+  };
+  headerFooter?: {
+    oddHeader?: string;
+    oddFooter?: string;
+    evenHeader?: string;
+    evenFooter?: string;
+    differentFirst?: boolean;
+    differentOddEven?: boolean;
+  };
+};
+
+type Payload = {
+  v: 1;
+  sheets: Record<string, SheetPageSetupV1>;
+};
+
+function isLandscape(o: unknown): o is 'landscape' {
+  return o === 'landscape';
+}
+
+// ExcelJS materialises a default page-setup + margins object on every
+// worksheet during load, even when the source xlsx never authored one.
+// Capturing those defaults would write a `__casual_sheets_page_setup__`
+// resource to every workbook that opens here — visible noise in
+// snapshot diffs and a failing assertion in `xlsx-hyperlinks.spec.ts`'s
+// resources round-trip probe. Drop them so the sidecar only appears
+// when the user (or the source xlsx) authored a non-default value.
+const PAGE_SETUP_DEFAULTS = {
+  orientation: 'portrait' as const,
+  fitToPage: false,
+  fitToWidth: 1,
+  fitToHeight: 1,
+  scale: 100,
+};
+const MARGIN_DEFAULTS = {
+  top: 0.75,
+  bottom: 0.75,
+  left: 0.7,
+  right: 0.7,
+  header: 0.3,
+  footer: 0.3,
+};
+
+/**
+ * Walk the xlsx worksheets and pull each one's page-setup + header
+ * /footer into a sidecar payload. Empty entries are dropped so the
+ * resource isn't written for files that didn't carry any chrome.
+ */
+export function readPageSetupFromXlsx(
+  wb: ExcelJS.Workbook,
+  sheetIdForExcel: (excelId: number) => string,
+): Record<string, SheetPageSetupV1> {
+  const out: Record<string, SheetPageSetupV1> = {};
+  for (const ws of wb.worksheets) {
+    const ps = (ws as unknown as { pageSetup?: Record<string, unknown> }).pageSetup;
+    const hf = (ws as unknown as { headerFooter?: Record<string, unknown> }).headerFooter;
+    const entry: SheetPageSetupV1 = {};
+
+    if (ps && typeof ps === 'object') {
+      // Only `landscape` matters — `portrait` is the xlsx default and
+      // would otherwise tag every workbook with a sidecar.
+      if (isLandscape(ps.orientation)) entry.orientation = 'landscape';
+      if (typeof ps.paperSize === 'number') entry.paperSize = ps.paperSize;
+      if (ps.fitToPage === true) entry.fitToPage = true;
+      if (typeof ps.fitToWidth === 'number' && ps.fitToWidth !== PAGE_SETUP_DEFAULTS.fitToWidth) {
+        entry.fitToWidth = ps.fitToWidth as number;
+      }
+      if (typeof ps.fitToHeight === 'number' && ps.fitToHeight !== PAGE_SETUP_DEFAULTS.fitToHeight) {
+        entry.fitToHeight = ps.fitToHeight as number;
+      }
+      if (typeof ps.scale === 'number' && ps.scale !== PAGE_SETUP_DEFAULTS.scale) {
+        entry.scale = ps.scale as number;
+      }
+      if (typeof ps.printArea === 'string') entry.printArea = ps.printArea as string;
+      const margins = ps.margins as Record<string, unknown> | undefined;
+      if (margins && typeof margins === 'object') {
+        const m: SheetPageSetupV1['margins'] = {};
+        for (const k of ['top', 'bottom', 'left', 'right', 'header', 'footer'] as const) {
+          const v = margins[k];
+          if (typeof v === 'number' && v !== MARGIN_DEFAULTS[k]) m[k] = v;
+        }
+        if (Object.keys(m).length > 0) entry.margins = m;
+      }
+    }
+
+    if (hf && typeof hf === 'object') {
+      const headerFooter: SheetPageSetupV1['headerFooter'] = {};
+      for (const k of ['oddHeader', 'oddFooter', 'evenHeader', 'evenFooter'] as const) {
+        const v = hf[k];
+        if (typeof v === 'string' && v.length > 0) headerFooter[k] = v as string;
+      }
+      if (hf.differentFirst === true) headerFooter.differentFirst = true;
+      if (hf.differentOddEven === true) headerFooter.differentOddEven = true;
+      if (Object.keys(headerFooter).length > 0) entry.headerFooter = headerFooter;
+    }
+
+    if (Object.keys(entry).length > 0) {
+      out[sheetIdForExcel(ws.id)] = entry;
+    }
+  }
+  return out;
+}
+
+/** Merge a synthesised page-setup map into the snapshot resources. */
+export function mergePageSetupIntoResources(
+  resources: IWorkbookData['resources'],
+  payload: Record<string, SheetPageSetupV1>,
+): IWorkbookData['resources'] {
+  if (Object.keys(payload).length === 0) return resources;
+  const existing = resources?.find((r) => r.name === PAGE_SETUP_RESOURCE);
+  if (existing) return resources;
+  const body: Payload = { v: 1, sheets: payload };
+  const next = [...(resources ?? [])];
+  next.push({ name: PAGE_SETUP_RESOURCE, data: JSON.stringify(body) });
+  return next;
+}
+
+/** Read the page-setup resource off a snapshot. Tolerant of older /
+ *  missing / malformed payloads. */
+export function readPageSetupFromSnapshot(
+  data: IWorkbookData,
+): Record<string, SheetPageSetupV1> {
+  const entry = data.resources?.find((r) => r.name === PAGE_SETUP_RESOURCE);
+  if (!entry?.data) return {};
+  try {
+    const parsed = JSON.parse(entry.data) as Partial<Payload>;
+    if (parsed?.v !== 1 || !parsed.sheets) return {};
+    return parsed.sheets;
+  } catch {
+    return {};
+  }
+}
+
+/** Apply a per-sheet entry onto an ExcelJS worksheet. */
+export function applyPageSetupToXlsxWorksheet(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ws: any,
+  entry: SheetPageSetupV1,
+): void {
+  if (!entry) return;
+  ws.pageSetup = ws.pageSetup ?? {};
+  if (entry.orientation) ws.pageSetup.orientation = entry.orientation;
+  if (typeof entry.paperSize === 'number') ws.pageSetup.paperSize = entry.paperSize;
+  if (typeof entry.fitToPage === 'boolean') ws.pageSetup.fitToPage = entry.fitToPage;
+  if (typeof entry.fitToWidth === 'number') ws.pageSetup.fitToWidth = entry.fitToWidth;
+  if (typeof entry.fitToHeight === 'number') ws.pageSetup.fitToHeight = entry.fitToHeight;
+  if (typeof entry.scale === 'number') ws.pageSetup.scale = entry.scale;
+  if (typeof entry.printArea === 'string') ws.pageSetup.printArea = entry.printArea;
+  if (entry.margins) {
+    ws.pageSetup.margins = { ...(ws.pageSetup.margins ?? {}), ...entry.margins };
+  }
+
+  if (entry.headerFooter) {
+    ws.headerFooter = ws.headerFooter ?? {};
+    for (const k of ['oddHeader', 'oddFooter', 'evenHeader', 'evenFooter'] as const) {
+      const v = entry.headerFooter[k];
+      if (typeof v === 'string') ws.headerFooter[k] = v;
+    }
+    if (typeof entry.headerFooter.differentFirst === 'boolean') {
+      ws.headerFooter.differentFirst = entry.headerFooter.differentFirst;
+    }
+    if (typeof entry.headerFooter.differentOddEven === 'boolean') {
+      ws.headerFooter.differentOddEven = entry.headerFooter.differentOddEven;
+    }
+  }
+}