@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/xlsx-document.d.ts

@@ -0,0 +1,108 @@
+/**
+ * A sheet document as an .xlsx file, both ways.
+ *
+ * The grid's own exporter writes rows; this writes and reads the DOCUMENT:
+ * every sheet's cells with formulas as formulas, the formats, column widths
+ * and row heights, hidden lines and sheets, frozen panes, merges, the
+ * AutoFilter's region, data validation, conditional formatting, sheet
+ * protection, comments (a note as a legacy note, a thread as Excel's
+ * threaded comment with its persons part) and the defined names. What comes back through
+ * `documentFromXlsxParts(documentToXlsxParts(doc))` is the document that
+ * went in, and a workbook Excel or Google Sheets saved opens with the same
+ * parts read the same way.
+ *
+ * Two conventions bridge the engine and the file. Dates are `yyyy-mm-dd`
+ * text in the engine and serial numbers in the file: a text date goes out
+ * as a serial with a date format, and a serial under a date format comes
+ * back as text. Formulas carry a leading `=` in the engine and none in the
+ * file, and Excel's `_xlfn.` prefix on newer functions is dropped on the
+ * way in.
+ *
+ * `documentToXlsxParts` and `documentFromXlsxParts` work on the package's
+ * XML parts and are pure; `documentToXlsx` and `documentFromXlsx` zip and
+ * unzip them with jszip, an optional peer loaded on demand.
+ */
+import type { SheetDocument, SheetState } from './document.js';
+export declare const isoToSerial: (iso: string) => number | null;
+export declare const serialToIso: (serial: number) => string;
+/** Excel's built-in number formats, the ones a file names by id alone. */
+export declare const BUILTIN_NUMFMT: Record<number, string>;
+/** Is this a date pattern: date tokens outside quotes, no digit placeholders. */
+export declare function isDateFormat(fmt: string | undefined): boolean;
+/**
+ * A date format that shows a day (a year, month or day token), as against
+ * a time alone. The reader turns a whole serial under one of these into the
+ * sheet's yyyy-mm-dd text; under h:mm the fraction stays a number, which
+ * the sheet shows as the time it is.
+ */
+export declare function isDayFormat(fmt: string | undefined): boolean;
+/** Excel column width units from pixels, and back. Excel's unit is the
+ *  width of a digit in the default font, close to seven pixels. */
+export declare const pxToWidth: (px: number) => number;
+export declare const widthToPx: (w: number) => number;
+export declare const pxToPt: (px: number) => number;
+export declare const ptToPx: (pt: number) => number;
+/** A string cell's text as the workbook stores it. Text that would be read
+ *  back as a number, a date, a boolean or a formula takes Excel's apostrophe,
+ *  which says "this is text" and is not part of the value. */
+export declare function asText(text: string): string;
+/**
+ * The package parts of an .xlsx holding the whole document, keyed by path,
+ * ready to zip. Pure: nothing here touches the DOM or the network.
+ */
+export declare function documentToXlsxParts(doc: SheetDocument): Record<string, string>;
+/**
+ * Future functions this engine does NOT evaluate but still spells the way
+ * the file wants.
+ *
+ * A cell this engine answers with `#NAME?` is one Excel can still work
+ * out, so dropping the prefix on the way back out would turn a formula
+ * that merely looks broken here into one that is broken there too. Keeping
+ * the name here costs nothing and makes the round trip lossless.
+ *
+ * Anything on this list is a candidate for implementing later; nothing
+ * should arrive here by accident, which is what the test that reads it
+ * guards.
+ */
+export declare const PRESERVED_ONLY: readonly ["RANDARRAY"];
+export declare const XLFN_FUNCTIONS: Set<string>;
+/**
+ * A formula as the FILE spells it: the future functions prefixed.
+ *
+ * Scanned rather than replaced by a regular expression, so that a name
+ * inside a string literal (`="SORT(x)"`) is left alone, and one that is
+ * part of a longer name (`MYSORT(`) is too.
+ */
+export declare function xlsxFormula(text: string, inTable?: string): string;
+/**
+ * The document a package holds, as a saved state: hand it to
+ * `createSheetDocument({ state })` or a shell's `setState`.
+ */
+export declare function documentFromXlsxParts(parts: Record<string, string>): SheetState;
+export type ZipCtor = {
+    new (): {
+        file(path: string, data: string, options?: {
+            base64?: boolean;
+            compression?: 'STORE' | 'DEFLATE';
+        }): void;
+        generateAsync(opts: {
+            type: 'blob';
+            mimeType?: string;
+        }): Promise<Blob>;
+    };
+    loadAsync(data: ArrayBuffer | Blob | Uint8Array): Promise<{
+        file(path: string): {
+            async(type: 'string' | 'base64'): Promise<string>;
+        } | null;
+        forEach(fn: (path: string, entry: {
+            dir: boolean;
+            async(type: 'string' | 'base64'): Promise<string>;
+        }) => void): void;
+    }>;
+};
+/** The jszip a caller gave, the one on the page, or the optional peer. */
+export declare function loadZip(given?: ZipCtor): Promise<ZipCtor>;
+/** The document as an .xlsx Blob. */
+export declare function documentToXlsx(doc: SheetDocument, JSZip?: ZipCtor): Promise<Blob>;
+/** The document an .xlsx file holds, as a saved state. */
+export declare function documentFromXlsx(file: Blob | ArrayBuffer | Uint8Array, JSZip?: ZipCtor): Promise<SheetState>;