@ex-grid/sheet-xlsx 0.0.0-stage → 0.2.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AkiraMisawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @ex-grid/sheet-xlsx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An ExSheet Workbook opened from and saved to .xlsx, as ExSheet.Xlsx opens and saves it, over @ex-grid/data-xlsx: constants, Formulas, Cell Formats and column widths carried, everything that would change a Value refused by name, and what else the file held listed in an Open Report.
+
+It is one of the packages of the ExGrid family: Excel-like grids, sheets, pivot tables and charts for reading
+money and risk numbers, published to npm under `@ex-grid` and to NuGet for Blazor, at one shared version.
+
+## Install
+
+```sh
+npm install @ex-grid/sheet-xlsx
+```
+
+It depends on exactly the version of `@ex-grid/data-xlsx` and `@ex-grid/sheet-engine` it was built with, so upgrade the family's packages together.
+
+## Documentation
+
+[ExSheet on the documentation site](https://akiramisawa.github.io/ex-grid/exsheet/xlsx), read for React with the switch at the top, and every
+version's [Release Notes](https://akiramisawa.github.io/ex-grid/release-notes).
+
+> **The API may still change.** While the version is `0.x`, it may change from one version to the next; each
+> version's Release Notes say what changed. A prerelease, a version with a suffix such as `-rc.1`, passed every
+> test layer in CI on the commit it was built from. A version without a suffix is published only once the
+> project's [Definition of Done](https://github.com/AkiraMisawa/ex-grid/blob/main/docs/definition-of-done.md) is
+> signed off on it.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,368 @@
+import { Culture } from '@ex-grid/sheet-engine';
+import { Workbook } from '@ex-grid/sheet-engine';
+import type { WorkbookDocument } from '@ex-grid/sheet-engine';
+import { XlsxError } from '@ex-grid/data-xlsx';
+import { XlsxReadOptions } from '@ex-grid/data-xlsx';
+import { XlsxRefusal } from '@ex-grid/data-xlsx';
+
+/** The longest Formula Excel holds, in characters, without its `=`. */
+export declare const maxFormulaLength = 8192;
+
+/** The most rows a Linked Table written as an Excel Table holds: a worksheet's 1,048,576, less its header's. */
+export declare const maxLinkedTableRows: number;
+
+/** The longest text a cell of Excel holds, in characters. */
+export declare const maxTextLength = 32767;
+
+/** One thing the file held that was not carried (ADR-0330 §4). */
+export declare interface NotCarried {
+    /** What it is. */
+    readonly kind: NotCarriedKind;
+    /** The Sheet it was on, or `null` for what the workbook as a whole held. */
+    readonly sheet: string | null;
+    /** What names it more closely, where something does: a defined name, the first cell of rich text or of a format not
+     * carried (a cell as `B7`, columns as `B:C`, rows as `5:5`), an element's name; otherwise `null`. */
+    readonly detail: string | null;
+    /** One sentence an application can show as it stands. */
+    readonly description: string;
+}
+
+/** What kind of thing an `OpenReport` says was not carried (ADR-0330 §4). */
+export declare type NotCarriedKind = 
+/** A worksheet that is hidden: it opens shown (ADR-0331 §4). */
+'hiddenSheet'
+/** A sheet that is not a worksheet — a chart sheet, a dialog or macro sheet — which holds no cells. */
+| 'chartSheet'
+/** A defined name, which no Formula carried reads; `detail` is its name, and `sheet` the sheet it is local to, or `null`
+* for a name of the whole workbook. */
+| 'definedName'
+/** Rows given heights of their own. */
+| 'rowHeights'
+/** Rows that are hidden: they open shown. */
+| 'hiddenRows'
+/** Columns that are hidden: they open shown. */
+| 'hiddenColumns'
+/** Panes frozen in the Sheet's view. */
+| 'frozenPanes'
+/** Merged cells: each cell is carried on its own. */
+| 'mergedCells'
+/** Conditional formatting. */
+| 'conditionalFormatting'
+/** Data validation. */
+| 'dataValidation'
+/** Notes and comments. */
+| 'notesAndComments'
+/** Hyperlinks: the cells' text is carried. */
+| 'hyperlinks'
+/** Pictures, charts, shapes and controls drawn over the Sheet. */
+| 'picturesAndCharts'
+/** The Sheet's protection. */
+| 'protection'
+/** Print settings beyond Excel's defaults: margins, a page set-up of its own, headers and footers with text, page breaks,
+* printed gridlines or headings, a fit to pages, a print area or print titles. */
+| 'printSettings'
+/** An AutoFilter, and the sort state it keeps. */
+| 'autoFilter'
+/** The structure of an Excel Table that no Formula reads: its cells are carried. */
+| 'excelTable'
+/** The Sheet's tab colour. */
+| 'sheetProperties'
+/** Rich-text runs inside cells: the text is carried, the runs' own formatting is not. */
+| 'richText'
+/** A PivotTable: the cells it shows are carried as constants, the PivotTable is not. */
+| 'pivotTables'
+/** Links to other workbooks that no Formula carried reads. */
+| 'externalLinks'
+/** Connections to outside data, and the queries that read through them. */
+| 'dataConnections'
+/** Slicers and timelines. */
+| 'slicers'
+/** View settings that change how the Sheet looks: hidden gridlines, headings or zeros, Formulas shown, right to left, a
+* zoom, a page layout. */
+| 'view'
+/** Anything else a worksheet holds; `detail` names its element, as `customSheetViews`. */
+| 'other'
+/** Colours that name the workbook's theme: each is carried as the RGB value the file's theme gives it, and the link to the
+* theme is not, so another theme does not recolour them (ADR-0330 §8). Said once, of the whole workbook. */
+| 'themeColours'
+/** A typeface or a size other than the workbook's own font's: the cells open in the Sheet's one font (ADR-0071). */
+| 'fontNamesAndSizes'
+/** Vertical alignment other than bottom. */
+| 'verticalAlignment'
+/** Wrapped, indented, rotated or shrunk text. */
+| 'textLayout'
+/** A horizontal alignment a Sheet does not have — fill, justify, distributed, centred across the selection: the cells open
+* aligned as General. */
+| 'horizontalAlignment'
+/** A double or accounting underline: the cells open with a single underline. */
+| 'underline'
+/** A pattern or gradient fill, or a solid one of no colour: the cells open with no Fill. */
+| 'patternFills'
+/** Diagonal borders: the cells keep their four sides. */
+| 'diagonalBorders'
+/** A default column width of the Sheet's own: its columns without a width of their own open at the default width. */
+| 'defaultColumnWidth';
+
+/** What reading an .xlsx returns beside the Workbook Document (ADR-0330 §5). */
+export declare class OpenReport {
+    /**
+     * What the file held that changes how a Sheet looks, or what else the file held, and that ExSheet did not carry
+     * (ADR-0330 §4's "Not carried"), in the workbook's order: what the workbook holds first, then each Sheet's in turn. Saving
+     * the Workbook again will not keep any of it.
+     */
+    readonly notCarried: readonly NotCarried[];
+    /**
+     * The cells whose Formula names a function outside ExSheet's declared set (`DeclaredFunction`), in Sheet order and then
+     * row by row: each is carried, and shows `#NAME?` (ADR-0047, ADR-0330 §4).
+     */
+    readonly unsupportedFunctions: readonly UnsupportedFunctionCell[];
+    /** @internal */
+    constructor(notCarried: readonly NotCarried[], unsupportedFunctions: readonly UnsupportedFunctionCell[]);
+    /** Whether the file was carried whole: nothing left behind, and every function it names supported. */
+    get isEmpty(): boolean;
+}
+
+/**
+ * Reads the workbook in `file` into a Workbook Document under `culture`, with its Open Report, or refuses it by name
+ * (`XlsxOpenError`). The read goes a batch of cells at a time, reporting progress and yielding between slices as `options`
+ * says, so a browser keeps painting while a large file is read.
+ *
+ * @param file - The file's bytes.
+ * @param culture - The Workbook's culture, declared by the application as a CSV's encoding is (ADR-0330 §7): how typing is
+ *   read and Values are shown from here on. No Value read from the file depends on it, and nothing in the file is taken for
+ *   it. A locale the engine holds no data for throws a `RangeError` before the file is read.
+ * @param options - The file layer's limits, progress, pacing and cancellation (ADR-0330 §9); its defaults when left out. An
+ *   aborted `signal` is looked at between slices, and a cancelled read opens nothing.
+ * @returns The Workbook Document and its Open Report.
+ * @throws XlsxOpenError - The workbook is refused, and nothing opens.
+ */
+export declare function openXlsxWorkbook(file: Uint8Array | ArrayBuffer | Blob, culture: Culture | string, options?: XlsxReadOptions): Promise<XlsxOpenResult>;
+
+/**
+ * Writes `workbook` as it stands as an .xlsx, or refuses it by name (`XlsxSaveError`), returning nothing.
+ *
+ * The Workbook's snapshot is taken before the write first yields — every Sheet's document, every Value it shows, its spills
+ * and each Linked Table's rows — and the file is built from that snapshot while yielding (ADR-0330 §9): the file is the
+ * Workbook as it stood when the call was made, and the Workbook may change once the returned promise is under way. A Linked
+ * Table's worksheet is written for Excel, and is not read back as a Linked Table (ADR-0330 §6): opened again, it is a
+ * worksheet of the table's cells.
+ *
+ * @param workbook - The Workbook.
+ * @param options - What the write may produce, and how it paces itself; the defaults when left out.
+ * @returns The file, as a Blob of the spreadsheet's media type.
+ * @throws XlsxSaveError - The Workbook is refused, and nothing was written.
+ * @throws RangeError - `maxUncompressedBytes` lies outside 1 to `defaultMaxUncompressedBytes`, or `maxCells` is not a number.
+ */
+export declare function saveXlsxWorkbook(workbook: Workbook, options?: XlsxSaveOptions): Promise<Blob>;
+
+/** A cell whose Formula names a function ExSheet does not support (ADR-0330 §4, §5): the Formula is carried, and shows
+ * `#NAME?`. */
+export declare interface UnsupportedFunctionCell {
+    /** The Sheet's name. */
+    readonly sheet: string;
+    /** The cell, as `B7`. */
+    readonly cell: string;
+    /** The functions it names that are not supported, in the Formula's order. */
+    readonly functions: readonly string[];
+}
+
+/** A workbook refused by name, and nothing opened (ADR-0330 §4). */
+export declare class XlsxOpenError extends Error {
+    /** Why the workbook was refused. */
+    readonly reason: XlsxOpenRefusal;
+    /** The name of the Sheet the refusal met, or `undefined` when it is not about one Sheet. */
+    readonly sheet: string | undefined;
+    /** The cell the refusal met, as `B7`, or `undefined` when it is not about one cell. */
+    readonly cell: string | undefined;
+    /** What the cell held — a Formula's text with its `=`, or a constant — or `undefined` when the refusal is not about one
+     * cell. */
+    readonly held: string | undefined;
+    /**
+     * A refusal naming what it met.
+     * @param reason - Why the workbook is refused.
+     * @param message - What was wrong, as a sentence that follows the Sheet and the cell.
+     * @param where - The Sheet, the cell and what the cell held, as far as it is about one.
+     * @param options - What caused it, when it was another error.
+     */
+    constructor(reason: XlsxOpenRefusal, message: string, where?: XlsxOpenPlace, options?: ErrorOptions);
+    /** Why the file layer refused the file, when `reason` is `file`; otherwise `undefined`. */
+    get fileRefusal(): XlsxRefusal | undefined;
+    /** The file layer's refusal, with its Sheet and cell. @internal */
+    static fromFile(e: XlsxError): XlsxOpenError;
+}
+
+/** Where an open's refusal met what it refuses, as far as it is about one Sheet and cell. */
+export declare interface XlsxOpenPlace {
+    /** The name of the Sheet it met. */
+    readonly sheet?: string | undefined;
+    /** The cell it met, as `B7`. */
+    readonly cell?: string | undefined;
+    /** What the cell held, as a Formula's text with its `=` or a constant's. */
+    readonly held?: string | undefined;
+}
+
+/**
+ * Why a workbook was refused, and nothing opened (ADR-0330 §4): what it held would change a Value, or the number a cell
+ * shows, or it is not a file that can be read faithfully.
+ */
+export declare type XlsxOpenRefusal = 
+/** The file layer refused the file: not a plain .xlsx, damaged, or past a limit. `XlsxOpenError.fileRefusal` says why. */
+'file'
+/** A Formula the engine cannot read: a syntax it does not implement (an array constant, the union operator, `@`), or a
+* What-If data table. */
+| 'unreadableFormula'
+/** A Formula reads a defined name, which ExSheet does not define, so it would show `#NAME?` where Excel shows a Value. */
+| 'definedName'
+/** A Formula reads another workbook, which ExSheet cannot reach. */
+| 'otherWorkbook'
+/** A Formula reads an Excel Table, which ExSheet does not read yet (ADR-0330 §6). */
+| 'excelTable'
+/** A legacy array formula (Ctrl+Shift+Enter), whose cells Excel computes as one, and ExSheet would spill otherwise. */
+| 'legacyArrayFormula'
+/** A constant a cell cannot hold in ExSheet, such as an Error Value the engine does not read. */
+| 'unreadableConstant'
+/** A worksheet's name is not one a Sheet can have, or the workbook holds no worksheet at all. */
+| 'sheets'
+/**
+* A cell, a row or a column takes a Number Format the engine does not read, or a built-in one whose code follows the
+* computer's locale and that the file does not spell out: shown in General instead, a date would show as a serial, or a
+* currency lose its symbol (ADR-0330 §4). `XlsxOpenError.held` is the format's code as the file spells it, or
+* `Number Format N`, naming its id, where the file spells none.
+*/
+| 'numberFormat';
+
+/** A Workbook Document read from an .xlsx, and its Open Report (ADR-0330 §5). */
+export declare interface XlsxOpenResult {
+    /** The Workbook Document: every worksheet a Sheet, in the file's order, the one shown shown. */
+    readonly document: WorkbookDocument;
+    /** What was not carried, and the cells naming functions ExSheet does not support. */
+    readonly report: OpenReport;
+}
+
+/** A Workbook not written, refused by name (ADR-0330 §6). */
+export declare class XlsxSaveError extends Error {
+    /** Why the Workbook was not written. */
+    readonly reason: XlsxSaveRefusal;
+    /** The name of the Sheet the refusal met, or `undefined` when it is not about one Sheet. */
+    readonly sheet: string | undefined;
+    /** The cell the refusal met, as `B7`, or `undefined` when it is not about one cell. */
+    readonly cell: string | undefined;
+    /** What the cell held — a Formula's text with its `=` — or `undefined`. */
+    readonly held: string | undefined;
+    /**
+     * A refusal naming what it met.
+     * @param reason - Why the Workbook is not written.
+     * @param message - What was wrong, as a sentence that follows the Sheet and the cell.
+     * @param where - The Sheet, the cell and what the cell held, as far as it is about one.
+     */
+    constructor(reason: XlsxSaveRefusal, message: string, where?: XlsxSavePlace);
+}
+
+/**
+ * What a write may produce, and how it paces itself (ADR-0330 §6, §9). Beyond either limit the Workbook is refused by name,
+ * never written in part. The write takes its snapshot of the Workbook before it first yields, then builds the file from it in
+ * slices sized by time, yielding between them so that a browser keeps painting, and reports its progress after each, as a
+ * read does. A key left out takes the default its comment names.
+ */
+export declare interface XlsxSaveOptions {
+    /**
+     * The cells the whole workbook may write, every worksheet counted, each element a cell: the Sheets' own cells, the cells an
+     * array spills into, the cells of no value written where a formatted row crosses a formatted column, a Linked Table's cells
+     * and its header's, and each row a row format writes, which is an element of its own whether or not it holds a cell (a row
+     * format over every row writes 1,048,576). `defaultMaxCells` when left out, the most a file is read with by default, so
+     * that what is written opens again. Beyond it the write is refused by name (`tooManyCells`) before anything is written.
+     */
+    readonly maxCells?: number;
+    /**
+     * The uncompressed bytes the file's parts may hold together: 1 to `defaultMaxUncompressedBytes`, which it is when left
+     * out, the most a file is read with by default. Beyond it the write is refused by name (`tooLarge`).
+     */
+    readonly maxUncompressedBytes?: number;
+    /** Told how far the write has come after every slice, and once more when every element is written. */
+    readonly onProgress?: (progress: XlsxSaveProgress) => void;
+    /** How long one slice works, in milliseconds, before the write yields; 30 when left out, a read's. A slice always does
+     * some work, so 0 yields after every batch. */
+    readonly sliceBudgetMs?: number;
+    /** What the write awaits between slices; a macrotask (`setTimeout(…, 0)`) when left out, as a read's. */
+    readonly yield?: () => Promise<void>;
+    /** Cancels the write: it rejects with the signal's reason, looked at between slices. Cancelled, it writes nothing. */
+    readonly signal?: AbortSignal;
+}
+
+/** Where a save's refusal met what it refuses, as far as it is about one Sheet and cell. */
+export declare interface XlsxSavePlace {
+    /** The name of the Sheet it met. */
+    readonly sheet?: string | undefined;
+    /** The cell it met, as `B7`. */
+    readonly cell?: string | undefined;
+    /** What the cell held, as a Formula's text with its `=`. */
+    readonly held?: string | undefined;
+}
+
+/** How far a write has come (`XlsxSaveOptions.onProgress`): the Workbook's snapshot being planned, then the worksheets being
+ * written. */
+export declare interface XlsxSaveProgress {
+    /** The index of the worksheet being written, in the file's order, from zero, a Linked Table's after the Sheets'; -1 while
+     * the snapshot is planned: its cells counted against the limit and checked. */
+    readonly sheet: number;
+    /** The worksheets the file holds: one for each Sheet and one for each Linked Table. */
+    readonly sheets: number;
+    /** The elements written so far, counted as `maxCells` counts them; 0 while the snapshot is planned. */
+    readonly elements: number;
+    /** The elements the file writes, counted as `maxCells` counts them; 0 while the snapshot is planned. */
+    readonly totalElements: number;
+}
+
+/**
+ * Why a Workbook was not written, and nothing was (ADR-0330 §6): what it holds cannot be written as a file Excel reads with
+ * the Values the user saw, or would make a file too large to open again.
+ */
+export declare type XlsxSaveRefusal = 
+/**
+* A Linked Table cannot be written as an Excel Table on a worksheet of its name, holding its rows as they stand
+* (ADR-0330 §6): it has not answered (every Formula that reads it shows `#GETTING_DATA`), it holds no rows (an Excel Table
+* holds at least one, and its Formulas would answer otherwise over one empty row), it holds more rows than a worksheet's
+* 1,048,576 less its header's or more columns than its 16,384, or its name is already a Sheet's or is one a worksheet
+* cannot have (longer than 31 characters, holding `\`, or `History`). Or a cell shows `#GETTING_DATA`. The refusal names
+* the table, and a cell's refusal the Sheet and the cell.
+*/
+'linkedTable'
+/**
+* A cell shows `#CIRC!`: it is part of a circular reference, or depends on one. A file holds only Excel's Error Values, and
+* Excel shows 0 there, which ExSheet refuses to show (ADR-0047); no Value the file can hold is the one the user saw.
+*/
+| 'circularReference'
+/**
+* A Formula that cannot be written as Excel stores it, or as Excel takes it: its text is longer than Excel's 8,192
+* characters, holds a text constant longer than 255, nests its calls deeper than 64 levels or makes one with more than 255
+* arguments; it holds half of a surrogate pair, which a file cannot carry; it reads a Sheet the Workbook does not have
+* (Excel would read another workbook's); it calls a name a `LET` binds or a `LAMBDA` takes, which ExSheet reads as an
+* unknown function and Excel would call; it reads, by a structured reference, a Linked Table or a column the Workbook does
+* not declare, or a column whose name begins or ends with a space or holds `@`, a tab, a line break or one of
+* `, : . " { } $ ^ & * + = - < > /`, whose form Excel has not been seen to write; it reads a Linked Table's name as a name
+* of its own (`=SUM(Positions)`), which ExSheet shows as `#NAME?` and Excel would read as the table; or it does not read
+* back as the Formula it is.
+*/
+| 'formula'
+/**
+* A cell's text is longer than the 32,767 characters a cell of Excel holds, or holds half of a surrogate pair, which a file
+* cannot carry; or a Sheet's name holds a character a worksheet's name cannot carry in a file: a control character below
+* U+0020, U+FFFE or U+FFFF, or half of a surrogate pair. The refusal then names the Sheet and no cell.
+*/
+| 'text'
+/**
+* The workbook would write more elements than `XlsxSaveOptions.maxCells`, which counts each cell written and each row a
+* row format writes. A Sheet formatted on many rows and many columns writes a cell wherever a formatted row crosses a
+* formatted column that records a part the row does not, and a row format writes a row element for every row it covers,
+* holding a cell or not. The default limit is the cells a file is read with (`defaultMaxCells`); the reader counts cells
+* only, so a file within it opens again, and rows are counted here so that a row format over every row is bounded too.
+*/
+| 'tooManyCells'
+/**
+* The workbook would hold more uncompressed bytes than `XlsxSaveOptions.maxUncompressedBytes`: by default, more than a
+* file is read with (`defaultMaxUncompressedBytes`), so it would not open again. The refusal names the Sheet whose
+* worksheet went past it, when one did.
+*/
+| 'tooLarge';
+
+export { }