@casualoffice/sheets 0.9.0

package/dist/xlsx.d.cts

@@ -0,0 +1,383 @@
+import { IWorkbookData, IStyleData, IRange } from '@univerjs/core';
+import * as ExcelJS from 'exceljs';
+import ExcelJS__default from 'exceljs';
+
+/**
+ * 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.
+ */
+type ImportedWorkbook = IWorkbookData;
+declare function xlsxToWorkbookData(buffer: ArrayBuffer): Promise<ImportedWorkbook>;
+
+declare function excelStyleToUniver(cell: ExcelJS.Cell): IStyleData | undefined;
+declare function univerStyleToExcel(style: IStyleData): Partial<ExcelJS.Style>;
+
+/**
+ * Name of a hidden worksheet we use to stash JSON we can't represent
+ * natively in xlsx (Univer plugin state — e.g. table definitions, outline
+ * groups). On open we recognize and consume it, never showing it to the
+ * user. Defined in its own module so both the parser worker and the
+ * exporter worker can import it without dragging the other one's
+ * ExcelJS code into their bundle.
+ */
+declare const RESOURCES_SHEET = "__casual_sheets_resources__";
+
+/**
+ * xlsx-native `cell.note` ⇄ Univer `thread-comment` resource bridge.
+ *
+ * Comments in xlsx live on the cell itself (`xl/comments<N>.xml`).
+ * Univer's thread-comment plugin stores them in a workbook-level
+ * resource keyed by sheet id under the name below — same
+ * registration pattern as defined-names. Each side of the round-trip
+ * has to translate to the shape the other one expects:
+ *
+ *   xlsx cell.note (string | { texts: [{ text }] })
+ *     ⇅
+ *   { dataStream: "<text>\r\n" }  (Univer IDocumentBody minimal form)
+ *
+ * Why this exists separately from the parser/exporter modules:
+ *   1. Two-sided code lives next to itself so the inverse stays
+ *      obvious. The audit test fails the moment one side drifts.
+ *   2. The `IThreadComment` row builder is non-trivial and reused
+ *      verbatim on both sides — extracting it keeps parse-impl and
+ *      export-impl from carrying near-duplicate shape definitions.
+ */
+declare const THREAD_COMMENT_RESOURCE = "SHEET_UNIVER_THREAD_COMMENT_PLUGIN";
+type SynthComment = {
+    id: string;
+    threadId: string;
+    ref: string;
+    dT: string;
+    personId: string;
+    text: {
+        dataStream: string;
+    };
+    unitId: string;
+    subUnitId: string;
+    children?: never[];
+};
+/**
+ * Walk every worksheet and collect xlsx-native `cell.note` entries
+ * into a Univer thread-comment resource payload. The synthesised IDs
+ * and dates aren't stable — re-opening the same file produces new
+ * ones — which is fine for the use cases we care about (comments
+ * survive the round-trip; nobody is referring to them by id).
+ */
+declare function readCommentsFromXlsx(wb: ExcelJS__default.Workbook, unitId: string, sheetIdForExcel: (excelId: number) => string): Record<string, SynthComment[]>;
+/**
+ * Merge a synthesised comment payload into the workbook's `resources`
+ * array. Skipped when the workbook already carries a thread-comment
+ * resource from our hidden sidecar (`__casual_sheets_resources__`) —
+ * that one has the full plugin shape; we shouldn't clobber it with a
+ * lossy xlsx-native re-derivation.
+ */
+declare function mergeCommentsIntoResources(resources: IWorkbookData['resources'], comments: Record<string, SynthComment[]>): IWorkbookData['resources'];
+/**
+ * Read the thread-comment resource off a snapshot. Tolerant of older
+ * / missing / malformed payloads — those cases return `{}` so the
+ * exporter just skips writing notes rather than throwing on save.
+ */
+declare function readCommentsFromSnapshot(data: IWorkbookData): Record<string, SynthComment[]>;
+/**
+ * Extract the plain string from a Univer comment body. Strips the
+ * trailing `\r\n` (or `\n`) that the body convention appends so the
+ * xlsx-side note doesn't show as a blank line below the text in
+ * Excel's pop-up.
+ */
+declare function commentBodyToString(body: SynthComment['text']): string;
+/**
+ * Parse an "A1"-style ref back to a zero-based (row, col). Falls back
+ * to (-1, -1) on malformed input — exporter callers should skip in
+ * that case.
+ */
+declare function refToRowCol(ref: string): {
+    row: number;
+    column: number;
+};
+
+/**
+ * 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.
+ */
+declare const PAGE_SETUP_RESOURCE = "__casual_sheets_page_setup__";
+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;
+    };
+};
+/**
+ * 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.
+ */
+declare function readPageSetupFromXlsx(wb: ExcelJS__default.Workbook, sheetIdForExcel: (excelId: number) => string): Record<string, SheetPageSetupV1>;
+/** Merge a synthesised page-setup map into the snapshot resources. */
+declare function mergePageSetupIntoResources(resources: IWorkbookData['resources'], payload: Record<string, SheetPageSetupV1>): IWorkbookData['resources'];
+/** Read the page-setup resource off a snapshot. Tolerant of older /
+ *  missing / malformed payloads. */
+declare function readPageSetupFromSnapshot(data: IWorkbookData): Record<string, SheetPageSetupV1>;
+/** Apply a per-sheet entry onto an ExcelJS worksheet. */
+declare function applyPageSetupToXlsxWorksheet(ws: any, entry: SheetPageSetupV1): void;
+
+/**
+ * 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.
+ */
+declare const DATA_VALIDATION_RESOURCE = "SHEET_DATA_VALIDATION_PLUGIN";
+type SynthDvRule = {
+    uid: string;
+    type: string;
+    ranges: IRange[];
+    formula1?: string;
+    formula2?: string;
+    operator?: string;
+    allowBlank?: boolean;
+    error?: string;
+    errorTitle?: string;
+    showErrorMessage?: boolean;
+    errorStyle?: string;
+    prompt?: string;
+    promptTitle?: string;
+    showInputMessage?: boolean;
+};
+/**
+ * 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.
+ */
+declare function readDataValidationFromXlsx(wb: ExcelJS__default.Workbook, sheetIdForExcel: (excelId: number) => string): Record<string, SynthDvRule[]>;
+/**
+ * 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.
+ */
+declare function mergeDataValidationIntoResources(resources: IWorkbookData['resources'], payload: Record<string, SynthDvRule[]>): IWorkbookData['resources'];
+/** Read the DV resource off a snapshot. Tolerant of older / missing /
+ *  malformed payloads. */
+declare function readDataValidationFromSnapshot(data: IWorkbookData): Record<string, SynthDvRule[]>;
+/** Apply a per-sheet rule set onto an ExcelJS worksheet. */
+declare function applyDataValidationToXlsxWorksheet(ws: any, rules: SynthDvRule[]): void;
+
+/**
+ * Passthrough preservation for xlsx ListObjects (a.k.a. Excel Tables).
+ * Univer doesn't model tables as first-class objects — autofilters and
+ * structured-reference parsing aren't there yet — so without a
+ * passthrough, opening an xlsx that ships a defined table and saving
+ * it again would silently strip the table back to plain cells.
+ *
+ * Data lives in our own sidecar (`__casual_sheets_tables__`); on
+ * export we replay `ws.addTable(...)` so the saved file shows the
+ * table to any reader (real Excel, gsheets, LibreOffice).
+ *
+ * When/if Univer grows native table support, this resource is the
+ * place to switch from sidecar to plugin shape — readers of older
+ * files keep working because the sidecar is forward-compatible.
+ */
+declare const TABLES_RESOURCE = "__casual_sheets_tables__";
+type SynthTableColumn = {
+    name: string;
+    filterButton?: boolean;
+    totalsRowFunction?: string;
+    totalsRowLabel?: string;
+    totalsRowFormula?: string;
+    style?: any;
+};
+type SynthTableV1 = {
+    name: string;
+    ref: string;
+    displayName?: string;
+    headerRow?: boolean;
+    totalsRow?: boolean;
+    style?: {
+        theme?: string;
+        name?: string;
+        showRowStripes?: boolean;
+        showColumnStripes?: boolean;
+        showFirstColumn?: boolean;
+        showLastColumn?: boolean;
+    };
+    columns: SynthTableColumn[];
+    rows: unknown[][];
+};
+/**
+ * Walk every worksheet and lift any defined tables into the sidecar
+ * payload. ExcelJS stores tables on `ws.tables` keyed by table name;
+ * each value is a Table *instance* whose actual fields hang off
+ * `t.model` (`node_modules/exceljs/lib/doc/table.js:275`). Two
+ * gotchas the parser must handle:
+ *
+ *   1. After `xlsx.load`, the model uses `tableRef` (full range) and
+ *      drops `ref` (the original top-left author hint). We coalesce
+ *      onto `ref` as a single canonical full-range string.
+ *   2. The loaded model never carries `rows` — table cell data is
+ *      already on the worksheet. We don't need rows to round-trip.
+ */
+declare function readTablesFromXlsx(wb: ExcelJS__default.Workbook, sheetIdForExcel: (excelId: number) => string): Record<string, SynthTableV1[]>;
+/** Merge a synthesised table map into the snapshot resources. */
+declare function mergeTablesIntoResources(resources: IWorkbookData['resources'], payload: Record<string, SynthTableV1[]>): IWorkbookData['resources'];
+/** Read the tables resource off a snapshot. */
+declare function readTablesFromSnapshot(data: IWorkbookData): Record<string, SynthTableV1[]>;
+/**
+ * Apply a per-sheet table set onto an ExcelJS worksheet.
+ *
+ * Why this bypasses `ws.addTable(...)`:
+ *
+ *   `Table.validate()` (`node_modules/exceljs/lib/doc/table.js:129`)
+ *   throws when `table.rows` is missing — but our round-trip case
+ *   doesn't carry rows (cell data already lives in `cellData`). And
+ *   `Table.store()` would *re-write* every cell from the rows
+ *   array, clobbering whatever the user had set after the table was
+ *   created. So instead of going through `addTable`, we attach the
+ *   load-shape model directly the same way ExcelJS's worksheet xform
+ *   setter does on load (`node_modules/exceljs/lib/doc/worksheet.js:
+ *   917`). The serializer then walks `Object.values(ws.tables).map(t
+ *   => t.model)` (`worksheet.js:856`) and writes the table parts —
+ *   `target` + `id` are filled in by `xlsx.js:632` during prepare.
+ */
+declare function applyTablesToXlsxWorksheet(ws: any, tables: SynthTableV1[]): void;
+
+type PivotPassthroughPayload = {
+    /** Every captured part — pivotCaches/**, pivotTables/**, and any
+     *  per-part `.rels` files — keyed by zip path; base64 contents. */
+    parts: Record<string, string>;
+    /** The raw `<pivotCaches>…</pivotCaches>` block extracted from
+     *  `xl/workbook.xml` at parse time. The `r:id` refs inside get
+     *  remapped at inject time. */
+    workbookPivotCachesXml: string;
+    /** Workbook-level pivotCacheDefinition relationships. `origId` is
+     *  the captured rId — used to remap the `r:id` references inside
+     *  `workbookPivotCachesXml`. */
+    workbookCacheRels: Array<{
+        origId: string;
+        target: string;
+    }>;
+    /** Pivot tables, grouped by the sheet they belong to. Sheets are
+     *  identified by NAME (not rId) because ExcelJS may reorder files. */
+    perSheet: Array<{
+        sheetName: string;
+        /** sheet's pivotTable rels. `origId` is the captured rId in the
+         *  ORIGINAL sheet rels file; we assign fresh rIds at inject time. */
+        pivotTableRels: Array<{
+            origId: string;
+            target: string;
+        }>;
+    }>;
+};
+
+/**
+ * Sidecar resource that carries raw OOXML parts ExcelJS silently drops.
+ *
+ * Today we passthrough:
+ *  - `xl/vbaProject.bin` — `.xlsm` macros round-trip byte-equal.
+ *  - `xl/pivotCaches/**` + `xl/pivotTables/**` — pivot definitions
+ *    survive a round-trip so Excel still sees the file as having
+ *    pivot tables (the materialised cells already survive via the
+ *    normal cell pipeline; this re-instates the metadata Excel
+ *    needs to render filter dropdowns, refresh, etc).
+ *
+ * We never execute VBA. The pivot OOXML is treated as opaque bytes —
+ * Univer doesn't render pivots from the OOXML, only the cells; this
+ * preserves the metadata for Excel's benefit.
+ */
+declare const XLSX_PASSTHROUGH_RESOURCE = "__casual_sheets_xlsx_passthrough__";
+type XlsxPassthroughPayload = {
+    /** base64-encoded contents of xl/vbaProject.bin */
+    vba?: {
+        binBase64: string;
+    };
+    /** raw OOXML pivot machinery — see pivot-passthrough.ts */
+    pivots?: PivotPassthroughPayload;
+};
+declare const XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+declare const XLSM_MIME = "application/vnd.ms-excel.sheet.macroEnabled.12";
+declare function mimeForPassthrough(payload: XlsxPassthroughPayload | undefined): string;
+declare function extensionForPassthrough(payload: XlsxPassthroughPayload | undefined): 'xlsx' | 'xlsm';
+declare function capturePassthroughFromBuffer(buffer: ArrayBuffer): Promise<XlsxPassthroughPayload | undefined>;
+declare function mergePassthroughIntoResources(resources: IWorkbookData['resources'], payload: XlsxPassthroughPayload | undefined): IWorkbookData['resources'];
+declare function readPassthroughFromSnapshot(data: IWorkbookData): XlsxPassthroughPayload | undefined;
+/**
+ * Re-inject every captured OOXML payload into the ExcelJS-written
+ * buffer in one pass. VBA + pivots share a single JSZip session so
+ * the [Content_Types].xml + workbook.xml.rels patches compose cleanly
+ * (each patch sees the previous step's writes).
+ *
+ * The input buffer is read but not mutated; a fresh ArrayBuffer is
+ * returned. No-op when the payload is empty.
+ */
+declare function applyPassthroughToXlsxBuffer(excelJsBuffer: ArrayBuffer | Uint8Array, payload: XlsxPassthroughPayload | undefined): Promise<ArrayBuffer>;
+
+export { DATA_VALIDATION_RESOURCE, type ImportedWorkbook, PAGE_SETUP_RESOURCE, RESOURCES_SHEET, type SheetPageSetupV1, type SynthComment, type SynthDvRule, type SynthTableColumn, type SynthTableV1, TABLES_RESOURCE, THREAD_COMMENT_RESOURCE, XLSM_MIME, XLSX_MIME, XLSX_PASSTHROUGH_RESOURCE, type XlsxPassthroughPayload, applyDataValidationToXlsxWorksheet, applyPageSetupToXlsxWorksheet, applyPassthroughToXlsxBuffer, applyTablesToXlsxWorksheet, capturePassthroughFromBuffer, commentBodyToString, excelStyleToUniver, extensionForPassthrough, mergeCommentsIntoResources, mergeDataValidationIntoResources, mergePageSetupIntoResources, mergePassthroughIntoResources, mergeTablesIntoResources, mimeForPassthrough, readCommentsFromSnapshot, readCommentsFromXlsx, readDataValidationFromSnapshot, readDataValidationFromXlsx, readPageSetupFromSnapshot, readPageSetupFromXlsx, readPassthroughFromSnapshot, readTablesFromSnapshot, readTablesFromXlsx, refToRowCol, univerStyleToExcel, xlsxToWorkbookData };