@ai-matrx/office 0.3.1 → 0.5.2

package/dist/sheets-xlsx.d.cts

@@ -0,0 +1,153 @@
+import { WorkbookJson } from '@ai-matrx/alchemy/operate/read';
+import { IWorkbookData } from '@univerjs/core';
+
+/**
+ * Shared vocabulary between the xlsx importer and exporter: how Univer's
+ * style numbers, colours and units map to the xlsx file's.
+ *
+ * Univer enums are written as numbers here so these helpers stay free of any
+ * Univer import (they run in tests and in both directions).
+ */
+declare const RESOURCE: {
+    readonly validation: "SHEET_DATA_VALIDATION_PLUGIN";
+    readonly conditional: "SHEET_CONDITIONAL_FORMATTING_PLUGIN";
+    readonly filter: "SHEET_FILTER_PLUGIN";
+    readonly note: "SHEET_NOTE_PLUGIN";
+    readonly comments: "SHEET_UNIVER_THREAD_COMMENT_PLUGIN";
+    readonly drawing: "SHEET_DRAWING_PLUGIN";
+    readonly table: "SHEET_TABLE_PLUGIN";
+};
+type UniverResource = {
+    name: string;
+    data: string;
+};
+declare function readResource<T = unknown>(resources: readonly UniverResource[] | undefined, name: string): T | undefined;
+declare function writeResource(resources: UniverResource[], name: string, value: unknown): void;
+/** Excel column width (characters) <-> Univer pixels. */
+declare const colPxToChars: (px: number) => number;
+declare const colCharsToPx: (chars: number) => number;
+/** Excel row height (points) <-> Univer pixels. */
+declare const rowPxToPt: (px: number) => number;
+declare const rowPtToPx: (pt: number) => number;
+/** Univer colour ("#rrggbb", "rgb(r,g,b)", "rgba(...)") -> ARGB hex, or undefined. */
+declare function colorToArgb(input: string | undefined | null): string | undefined;
+/** ARGB (or RGB) hex from a file -> Univer "#rrggbb". */
+declare function argbToColor(argb: string | undefined | null): string | undefined;
+declare const borderToExcel: (n: number | undefined) => string | undefined;
+declare const borderFromExcel: (name: string | undefined) => number | undefined;
+declare const H_ALIGN_OUT: Record<number, string>;
+declare const V_ALIGN_OUT: Record<number, string>;
+declare const H_ALIGN_IN: Record<string, number>;
+declare const V_ALIGN_IN: Record<string, number>;
+/** 0-based (row, col) -> "A1" (no $). */
+declare function a1(row: number, col: number): string;
+type RangeLike = {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+};
+declare const rangeToA1: (r: RangeLike) => string;
+/** "A1" or "A1:C5" -> range (0-based), or null. */
+declare function parseA1Range(ref: string): RangeLike | null;
+
+/**
+ * univerToXlsx — convert a Univer IWorkbookData snapshot to an .xlsx file.
+ *
+ * Symmetric counterpart to `xlsx-to-univer.ts`. Carries everything the xlsx
+ * format can hold from what Univer holds: values, formulas, merged ranges,
+ * cell styles and number formats, column widths, row heights, frozen panes,
+ * data validation, conditional formatting, the header-row filter range,
+ * notes, comment threads (as notes), cell links, and pictures.
+ *
+ * What it cannot carry is NAMED in the returned report and shown to the person
+ * at export time — never dropped silently.
+ *
+ * Engine: ExcelJS (the xlsx reader/writer that holds styles, validation,
+ * conditional formatting, notes, links and images; the registered
+ * `xlsx-workbook` format writes values only). It is loaded on demand, so
+ * the editor bundle does not pay for it until someone exports or imports.
+ */
+
+type ExportXlsxOptions = {
+    /** File name without extension. Defaults to "workbook". */
+    filename?: string;
+    /** Reads a picture's bytes (a `matrx-file:` reference or a URL). Pictures it cannot read are reported. */
+    resolveImage?: ExportImagePort;
+};
+type ExportImagePort = (source: string) => Promise<{
+    bytes: Uint8Array;
+    extension: "png" | "jpeg" | "gif";
+} | null>;
+/** What an export could not carry, in words for the person. Empty when nothing was lost. */
+type XlsxExportReport = {
+    dropped: string[];
+};
+type Snapshot = Partial<IWorkbookData>;
+/** A Univer snapshot as the `xlsx-workbook` format's value (sheets of typed cells + merges). */
+declare function univerSnapshotToWorkbookJson(snapshot: Snapshot): WorkbookJson;
+/** Full-fidelity bytes. Does NOT trigger a download. */
+declare function univerSnapshotToXlsxBytes(snapshot: Snapshot, options?: Pick<ExportXlsxOptions, "resolveImage">): Promise<Uint8Array>;
+/** Convert + trigger a browser download; returns what could not be carried. */
+declare function downloadUniverAsXlsx(snapshot: Snapshot, options?: ExportXlsxOptions): Promise<XlsxExportReport>;
+declare function buildXlsxFromUniver(snapshot: Snapshot, options?: Pick<ExportXlsxOptions, "resolveImage">): Promise<{
+    bytes: Uint8Array;
+    report: XlsxExportReport;
+}>;
+declare function univerSnapshotToRegisteredXlsxBytes(snapshot: Snapshot): Promise<Uint8Array>;
+
+/**
+ * Full-fidelity .xlsx -> Univer reader (ExcelJS). The inverse of
+ * `univer-to-xlsx.ts`: styles, number formats, column widths, row heights,
+ * frozen panes, merges, data validation, conditional formatting, the filter
+ * range, notes, cell links and pictures. Free of Univer runtime imports (enums
+ * are numbers) so it runs under tests as well as in the browser.
+ */
+
+type XlsxImportOptions = {
+    /** Stores a picture and returns its file id; without it pictures are reported, not imported. */
+    uploadImage?: (bytes: Uint8Array, extension: string) => Promise<string>;
+    /** Called once per thing the file held that could not be carried. */
+    onDropped?: (what: string) => void;
+};
+
+/**
+ * xlsxToUniverWorkbook — parse a spreadsheet file into a Univer IWorkbookData
+ * suitable for `apiRef.createWorkbook(...)` and for persistence as the initial
+ * snapshot of a new workbook.
+ *
+ * ONE reader: ExcelJS (`xlsx-to-univer-excel`) holds styles, number formats,
+ * widths, heights, frozen panes, merges, validation, conditional formatting,
+ * filter range, notes, links and pictures. A file that is not already an
+ * .xlsx (.xls, .ods, .csv, .tsv) is first re-written as an .xlsx by the
+ * Alchemy workbook door — values, formulas and merges — and read by that same
+ * reader, so there is no second import path to drift.
+ */
+
+/**
+ * Parse a spreadsheet file into a Univer workbook. Whatever could not be
+ * carried is reported through `options.onDropped` (the caller tells the person).
+ */
+declare function xlsxToUniverWorkbook(file: File, options?: XlsxImportOptions): Promise<Partial<IWorkbookData>>;
+
+/**
+ * Spreadsheet file → a NEW workbook, the ONE import path: the Workbooks home and the editor's
+ * File → Import both run it. The file is parsed before anything is created (a malformed file leaves
+ * no empty workbook behind), the lossless original is stashed (non-fatal), and a failed save rolls
+ * the new row back.
+ */
+/**
+ * Pre-flight import file check. We deliberately do NOT use the `accept`
+ * attribute on the picker (it greys out everything in Drive / Google
+ * Sheets pickers on iOS and many Android pickers), so we validate after
+ * pick. Returns null when the file is accepted, or a short user-facing
+ * reason string when it isn't.
+ */
+declare function unsupportedFileReason(file: File): string | null;
+declare function importWorkbookFile(file: File, organizationId: string | null): Promise<{
+    id: string;
+    name: string;
+    notCarried: string[];
+}>;
+
+export { type ExportImagePort, type ExportXlsxOptions, H_ALIGN_IN, H_ALIGN_OUT, RESOURCE, type RangeLike, type UniverResource, V_ALIGN_IN, V_ALIGN_OUT, type XlsxExportReport, a1, argbToColor, borderFromExcel, borderToExcel, buildXlsxFromUniver, colCharsToPx, colPxToChars, colorToArgb, downloadUniverAsXlsx, importWorkbookFile, parseA1Range, rangeToA1, readResource, rowPtToPx, rowPxToPt, univerSnapshotToRegisteredXlsxBytes, univerSnapshotToWorkbookJson, univerSnapshotToXlsxBytes, unsupportedFileReason, writeResource, xlsxToUniverWorkbook };

package/dist/sheets-xlsx.d.ts

@@ -0,0 +1,153 @@
+import { WorkbookJson } from '@ai-matrx/alchemy/operate/read';
+import { IWorkbookData } from '@univerjs/core';
+
+/**
+ * Shared vocabulary between the xlsx importer and exporter: how Univer's
+ * style numbers, colours and units map to the xlsx file's.
+ *
+ * Univer enums are written as numbers here so these helpers stay free of any
+ * Univer import (they run in tests and in both directions).
+ */
+declare const RESOURCE: {
+    readonly validation: "SHEET_DATA_VALIDATION_PLUGIN";
+    readonly conditional: "SHEET_CONDITIONAL_FORMATTING_PLUGIN";
+    readonly filter: "SHEET_FILTER_PLUGIN";
+    readonly note: "SHEET_NOTE_PLUGIN";
+    readonly comments: "SHEET_UNIVER_THREAD_COMMENT_PLUGIN";
+    readonly drawing: "SHEET_DRAWING_PLUGIN";
+    readonly table: "SHEET_TABLE_PLUGIN";
+};
+type UniverResource = {
+    name: string;
+    data: string;
+};
+declare function readResource<T = unknown>(resources: readonly UniverResource[] | undefined, name: string): T | undefined;
+declare function writeResource(resources: UniverResource[], name: string, value: unknown): void;
+/** Excel column width (characters) <-> Univer pixels. */
+declare const colPxToChars: (px: number) => number;
+declare const colCharsToPx: (chars: number) => number;
+/** Excel row height (points) <-> Univer pixels. */
+declare const rowPxToPt: (px: number) => number;
+declare const rowPtToPx: (pt: number) => number;
+/** Univer colour ("#rrggbb", "rgb(r,g,b)", "rgba(...)") -> ARGB hex, or undefined. */
+declare function colorToArgb(input: string | undefined | null): string | undefined;
+/** ARGB (or RGB) hex from a file -> Univer "#rrggbb". */
+declare function argbToColor(argb: string | undefined | null): string | undefined;
+declare const borderToExcel: (n: number | undefined) => string | undefined;
+declare const borderFromExcel: (name: string | undefined) => number | undefined;
+declare const H_ALIGN_OUT: Record<number, string>;
+declare const V_ALIGN_OUT: Record<number, string>;
+declare const H_ALIGN_IN: Record<string, number>;
+declare const V_ALIGN_IN: Record<string, number>;
+/** 0-based (row, col) -> "A1" (no $). */
+declare function a1(row: number, col: number): string;
+type RangeLike = {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+};
+declare const rangeToA1: (r: RangeLike) => string;
+/** "A1" or "A1:C5" -> range (0-based), or null. */
+declare function parseA1Range(ref: string): RangeLike | null;
+
+/**
+ * univerToXlsx — convert a Univer IWorkbookData snapshot to an .xlsx file.
+ *
+ * Symmetric counterpart to `xlsx-to-univer.ts`. Carries everything the xlsx
+ * format can hold from what Univer holds: values, formulas, merged ranges,
+ * cell styles and number formats, column widths, row heights, frozen panes,
+ * data validation, conditional formatting, the header-row filter range,
+ * notes, comment threads (as notes), cell links, and pictures.
+ *
+ * What it cannot carry is NAMED in the returned report and shown to the person
+ * at export time — never dropped silently.
+ *
+ * Engine: ExcelJS (the xlsx reader/writer that holds styles, validation,
+ * conditional formatting, notes, links and images; the registered
+ * `xlsx-workbook` format writes values only). It is loaded on demand, so
+ * the editor bundle does not pay for it until someone exports or imports.
+ */
+
+type ExportXlsxOptions = {
+    /** File name without extension. Defaults to "workbook". */
+    filename?: string;
+    /** Reads a picture's bytes (a `matrx-file:` reference or a URL). Pictures it cannot read are reported. */
+    resolveImage?: ExportImagePort;
+};
+type ExportImagePort = (source: string) => Promise<{
+    bytes: Uint8Array;
+    extension: "png" | "jpeg" | "gif";
+} | null>;
+/** What an export could not carry, in words for the person. Empty when nothing was lost. */
+type XlsxExportReport = {
+    dropped: string[];
+};
+type Snapshot = Partial<IWorkbookData>;
+/** A Univer snapshot as the `xlsx-workbook` format's value (sheets of typed cells + merges). */
+declare function univerSnapshotToWorkbookJson(snapshot: Snapshot): WorkbookJson;
+/** Full-fidelity bytes. Does NOT trigger a download. */
+declare function univerSnapshotToXlsxBytes(snapshot: Snapshot, options?: Pick<ExportXlsxOptions, "resolveImage">): Promise<Uint8Array>;
+/** Convert + trigger a browser download; returns what could not be carried. */
+declare function downloadUniverAsXlsx(snapshot: Snapshot, options?: ExportXlsxOptions): Promise<XlsxExportReport>;
+declare function buildXlsxFromUniver(snapshot: Snapshot, options?: Pick<ExportXlsxOptions, "resolveImage">): Promise<{
+    bytes: Uint8Array;
+    report: XlsxExportReport;
+}>;
+declare function univerSnapshotToRegisteredXlsxBytes(snapshot: Snapshot): Promise<Uint8Array>;
+
+/**
+ * Full-fidelity .xlsx -> Univer reader (ExcelJS). The inverse of
+ * `univer-to-xlsx.ts`: styles, number formats, column widths, row heights,
+ * frozen panes, merges, data validation, conditional formatting, the filter
+ * range, notes, cell links and pictures. Free of Univer runtime imports (enums
+ * are numbers) so it runs under tests as well as in the browser.
+ */
+
+type XlsxImportOptions = {
+    /** Stores a picture and returns its file id; without it pictures are reported, not imported. */
+    uploadImage?: (bytes: Uint8Array, extension: string) => Promise<string>;
+    /** Called once per thing the file held that could not be carried. */
+    onDropped?: (what: string) => void;
+};
+
+/**
+ * xlsxToUniverWorkbook — parse a spreadsheet file into a Univer IWorkbookData
+ * suitable for `apiRef.createWorkbook(...)` and for persistence as the initial
+ * snapshot of a new workbook.
+ *
+ * ONE reader: ExcelJS (`xlsx-to-univer-excel`) holds styles, number formats,
+ * widths, heights, frozen panes, merges, validation, conditional formatting,
+ * filter range, notes, links and pictures. A file that is not already an
+ * .xlsx (.xls, .ods, .csv, .tsv) is first re-written as an .xlsx by the
+ * Alchemy workbook door — values, formulas and merges — and read by that same
+ * reader, so there is no second import path to drift.
+ */
+
+/**
+ * Parse a spreadsheet file into a Univer workbook. Whatever could not be
+ * carried is reported through `options.onDropped` (the caller tells the person).
+ */
+declare function xlsxToUniverWorkbook(file: File, options?: XlsxImportOptions): Promise<Partial<IWorkbookData>>;
+
+/**
+ * Spreadsheet file → a NEW workbook, the ONE import path: the Workbooks home and the editor's
+ * File → Import both run it. The file is parsed before anything is created (a malformed file leaves
+ * no empty workbook behind), the lossless original is stashed (non-fatal), and a failed save rolls
+ * the new row back.
+ */
+/**
+ * Pre-flight import file check. We deliberately do NOT use the `accept`
+ * attribute on the picker (it greys out everything in Drive / Google
+ * Sheets pickers on iOS and many Android pickers), so we validate after
+ * pick. Returns null when the file is accepted, or a short user-facing
+ * reason string when it isn't.
+ */
+declare function unsupportedFileReason(file: File): string | null;
+declare function importWorkbookFile(file: File, organizationId: string | null): Promise<{
+    id: string;
+    name: string;
+    notCarried: string[];
+}>;
+
+export { type ExportImagePort, type ExportXlsxOptions, H_ALIGN_IN, H_ALIGN_OUT, RESOURCE, type RangeLike, type UniverResource, V_ALIGN_IN, V_ALIGN_OUT, type XlsxExportReport, a1, argbToColor, borderFromExcel, borderToExcel, buildXlsxFromUniver, colCharsToPx, colPxToChars, colorToArgb, downloadUniverAsXlsx, importWorkbookFile, parseA1Range, rangeToA1, readResource, rowPtToPx, rowPxToPt, univerSnapshotToRegisteredXlsxBytes, univerSnapshotToWorkbookJson, univerSnapshotToXlsxBytes, unsupportedFileReason, writeResource, xlsxToUniverWorkbook };