@datalayer/cells 0.0.0-stage → 0.0.2

package/lib/core/strings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The workbook's string pool: every string a cell holds, interned once and
+ * reference-counted, so a column of repeated labels costs one string.
+ *
+ * @module core/strings
+ */
+export declare class StringPool {
+    #private;
+    /** Take a reference to `text`; returns its index. */
+    intern(text: string): number;
+    /** Drop a reference; the string goes when the last one does. */
+    release(index: number): void;
+    get(index: number): string;
+    /** How many distinct strings are held. */
+    get size(): number;
+    /** How many references the string at `index` has. */
+    references(index: number): number;
+}
+//# sourceMappingURL=strings.d.ts.map

package/lib/core/strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/core/strings.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH,qBAAa,UAAU;;IAMrB,qDAAqD;IACrD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAgB5B,gEAAgE;IAChE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAa5B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAM1B,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qDAAqD;IACrD,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAGlC"}

package/lib/core/strings.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2022-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * The workbook's string pool: every string a cell holds, interned once and
+ * reference-counted, so a column of repeated labels costs one string.
+ *
+ * @module core/strings
+ */
+export class StringPool {
+    #strings = [];
+    #counts = new Int32Array(64);
+    #index = new Map();
+    #free = [];
+    /** Take a reference to `text`; returns its index. */
+    intern(text) {
+        let i = this.#index.get(text);
+        if (i === undefined) {
+            i = this.#free.pop() ?? this.#strings.length;
+            this.#strings[i] = text;
+            this.#index.set(text, i);
+            if (i >= this.#counts.length) {
+                const counts = new Int32Array(this.#counts.length * 2);
+                counts.set(this.#counts);
+                this.#counts = counts;
+            }
+        }
+        this.#counts[i] += 1;
+        return i;
+    }
+    /** Drop a reference; the string goes when the last one does. */
+    release(index) {
+        const text = this.#strings[index];
+        if (text === undefined || this.#counts[index] <= 0) {
+            throw new Error(`The string pool holds nothing at ${index}: released twice?`);
+        }
+        this.#counts[index] -= 1;
+        if (this.#counts[index] === 0) {
+            this.#strings[index] = undefined;
+            this.#index.delete(text);
+            this.#free.push(index);
+        }
+    }
+    get(index) {
+        const text = this.#strings[index];
+        if (text === undefined)
+            throw new Error(`The string pool holds nothing at ${index}.`);
+        return text;
+    }
+    /** How many distinct strings are held. */
+    get size() {
+        return this.#index.size;
+    }
+    /** How many references the string at `index` has. */
+    references(index) {
+        return this.#counts[index] ?? 0;
+    }
+}
+//# sourceMappingURL=strings.js.map

package/lib/core/strings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.js","sourceRoot":"","sources":["../../src/core/strings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AAEH,MAAM,OAAO,UAAU;IACrB,QAAQ,GAA2B,EAAE,CAAC;IACtC,OAAO,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAC7B,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACnC,KAAK,GAAa,EAAE,CAAC;IAErB,qDAAqD;IACrD,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC7C,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC7B,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACvD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;YACxB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,gEAAgE;IAChE,OAAO,CAAC,KAAa;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,mBAAmB,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAa;QACf,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,KAAK,GAAG,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0CAA0C;IAC1C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,qDAAqD;IACrD,UAAU,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;CACF"}

package/lib/core/styles.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cell styles, deduplicated by content into a table cells index with a
+ * `Uint16`. The table only grows, so an index is stable for the life of the
+ * workbook (undo and the file format rely on that); index 0 is the default.
+ *
+ * @module core/styles
+ */
+export type HorizontalAlign = 'left' | 'center' | 'right';
+export type VerticalAlign = 'top' | 'middle' | 'bottom';
+export type BorderStyle = 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double';
+export interface BorderSide {
+    readonly style: BorderStyle;
+    readonly color: string;
+}
+export interface Style {
+    readonly font?: string;
+    readonly size?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strike?: boolean;
+    /** Text colour; absent means the theme's text colour. */
+    readonly color?: string;
+    readonly fill?: string;
+    readonly align?: HorizontalAlign;
+    readonly valign?: VerticalAlign;
+    readonly wrap?: boolean;
+    readonly borders?: {
+        readonly top?: BorderSide;
+        readonly right?: BorderSide;
+        readonly bottom?: BorderSide;
+        readonly left?: BorderSide;
+    };
+    /** An Excel number format, such as `#,##0.00` or `yyyy-mm-dd`. */
+    readonly format?: string;
+}
+/** Throws a sentence naming the first thing wrong with a style. */
+export declare function checkStyle(style: unknown, where?: string): asserts style is Style;
+export declare class StyleTable {
+    #private;
+    /** The index of a style, adding it when new. Index 0 is the default style. */
+    intern(style: Style): number;
+    get(index: number): Style;
+    get size(): number;
+    /** Every style, in index order (the file format's `styles`). */
+    all(): readonly Style[];
+}
+//# sourceMappingURL=styles.d.ts.map

package/lib/core/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/core/styles.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;QAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;QAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;KAC5B,CAAC;IACF,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAsCD,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAU,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CA0BlF;AAED,qBAAa,UAAU;;IAIrB,8EAA8E;IAC9E,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAc5B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK;IAOzB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gEAAgE;IAChE,GAAG,IAAI,SAAS,KAAK,EAAE;CAGxB"}

package/lib/core/styles.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2022-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+const KEYS = [
+    'font',
+    'size',
+    'bold',
+    'italic',
+    'underline',
+    'strike',
+    'color',
+    'fill',
+    'align',
+    'valign',
+    'wrap',
+    'borders',
+    'format',
+];
+const KEY_SET = new Set(KEYS);
+const MAX_STYLES = 0xffff;
+/** A canonical text for a style: its set keys in a fixed order, falsy flags dropped. */
+function canonical(style) {
+    const out = {};
+    for (const key of KEYS) {
+        const value = style[key];
+        if (value === undefined || value === false)
+            continue;
+        out[key] = key === 'borders' ? canonicalBorders(value) : value;
+    }
+    return JSON.stringify(out);
+}
+function canonicalBorders(b) {
+    if (b === undefined)
+        return undefined;
+    const out = {};
+    for (const side of ['top', 'right', 'bottom', 'left'])
+        if (b[side])
+            out[side] = b[side];
+    return out;
+}
+/** Throws a sentence naming the first thing wrong with a style. */
+export function checkStyle(style, where = 'style') {
+    if (typeof style !== 'object' || style === null || Array.isArray(style)) {
+        throw new Error(`${where}: a style is an object.`);
+    }
+    for (const key of Object.keys(style)) {
+        if (!KEY_SET.has(key))
+            throw new Error(`${where}: '${key}' is not a style property (${KEYS.join(', ')}).`);
+    }
+    const s = style;
+    for (const key of ['bold', 'italic', 'underline', 'strike', 'wrap']) {
+        if (s[key] !== undefined && typeof s[key] !== 'boolean')
+            throw new Error(`${where}.${key}: true or false.`);
+    }
+    for (const key of ['font', 'color', 'fill', 'format']) {
+        if (s[key] !== undefined && typeof s[key] !== 'string')
+            throw new Error(`${where}.${key}: a string.`);
+    }
+    if (s.size !== undefined && !(typeof s.size === 'number' && s.size > 0)) {
+        throw new Error(`${where}.size: a positive number.`);
+    }
+    if (s.align !== undefined && !['left', 'center', 'right'].includes(s.align)) {
+        throw new Error(`${where}.align: left, center or right.`);
+    }
+    if (s.valign !== undefined && !['top', 'middle', 'bottom'].includes(s.valign)) {
+        throw new Error(`${where}.valign: top, middle or bottom.`);
+    }
+}
+export class StyleTable {
+    #styles = [{}];
+    #index = new Map([[canonical({}), 0]]);
+    /** The index of a style, adding it when new. Index 0 is the default style. */
+    intern(style) {
+        const key = canonical(style);
+        let i = this.#index.get(key);
+        if (i === undefined) {
+            if (this.#styles.length > MAX_STYLES) {
+                throw new Error(`A workbook holds at most ${MAX_STYLES + 1} distinct styles.`);
+            }
+            i = this.#styles.length;
+            this.#styles.push(JSON.parse(key));
+            this.#index.set(key, i);
+        }
+        return i;
+    }
+    get(index) {
+        const style = this.#styles[index];
+        if (style === undefined)
+            throw new Error(`No style ${index}; the workbook has ${this.#styles.length}.`);
+        return style;
+    }
+    get size() {
+        return this.#styles.length;
+    }
+    /** Every style, in index order (the file format's `styles`). */
+    all() {
+        return this.#styles;
+    }
+}
+//# sourceMappingURL=styles.js.map

package/lib/core/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/core/styles.ts"],"names":[],"mappings":"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"}

package/lib/core/values.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cell values and errors.
+ *
+ * @module core/values
+ */
+/** The errors a cell can hold, as Excel spells them (`#CYCLE!` and `#BUSY!` are ours). */
+export declare const CELL_ERRORS: readonly ["#DIV/0!", "#REF!", "#NAME?", "#VALUE!", "#N/A", "#NUM!", "#NULL!", "#CYCLE!", "#BUSY!", "#SPILL!"];
+export type CellErrorCode = (typeof CELL_ERRORS)[number];
+/** An error value, with an optional sentence saying why (shown in the cell's tooltip). */
+export interface CellError {
+    readonly error: CellErrorCode;
+    readonly message?: string;
+}
+/** What a cell evaluates to. `null` is empty. */
+export type CellValue = number | string | boolean | CellError | null;
+/** An error value; refuses a code that is not one of {@link CELL_ERRORS}. */
+export declare function cellError(code: CellErrorCode, message?: string): CellError;
+export declare function isCellError(value: unknown): value is CellError;
+export declare function isErrorCode(text: string): text is CellErrorCode;
+//# sourceMappingURL=values.d.ts.map

package/lib/core/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/core/values.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW,+GAWd,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iDAAiD;AACjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;AAIrE,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAI1E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAM9D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAE/D"}

package/lib/core/values.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2022-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Cell values and errors.
+ *
+ * @module core/values
+ */
+/** The errors a cell can hold, as Excel spells them (`#CYCLE!` and `#BUSY!` are ours). */
+export const CELL_ERRORS = [
+    '#DIV/0!',
+    '#REF!',
+    '#NAME?',
+    '#VALUE!',
+    '#N/A',
+    '#NUM!',
+    '#NULL!',
+    '#CYCLE!',
+    '#BUSY!',
+    '#SPILL!',
+];
+const ERROR_SET = new Set(CELL_ERRORS);
+/** An error value; refuses a code that is not one of {@link CELL_ERRORS}. */
+export function cellError(code, message) {
+    if (!ERROR_SET.has(code))
+        throw new Error(`'${code}' is not a cell error; there are ${CELL_ERRORS.join(' ')}.`);
+    return message === undefined ? { error: code } : { error: code, message };
+}
+export function isCellError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        ERROR_SET.has(value.error));
+}
+export function isErrorCode(text) {
+    return ERROR_SET.has(text);
+}
+//# sourceMappingURL=values.js.map

package/lib/core/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../../src/core/values.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,SAAS;IACT,OAAO;IACP,QAAQ;IACR,SAAS;IACT,MAAM;IACN,OAAO;IACP,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,SAAS;CACD,CAAC;AAaX,MAAM,SAAS,GAAwB,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;AAE5D,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,IAAmB,EAAE,OAAgB;IAC7D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,oCAAoC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxF,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,CAAC,GAAG,CAAE,KAA6B,CAAC,KAAe,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/lib/core/workbook.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The persisted state of a workbook: sheets, their axes and cells, merges and
+ * frozen panes, and the pools cells reference (strings, styles, formulas).
+ * Only patches write it (core/patches); the model reads it through getters.
+ *
+ * @module core/workbook
+ */
+import { Axis } from './axis.js';
+import { FormulaTable, SheetCells } from './cells.js';
+import { StringPool } from './strings.js';
+import { StyleTable } from './styles.js';
+import { type Zone } from './zone.js';
+/** The size limits of a sheet. Excel's by default. */
+export interface Limits {
+    readonly rows: number;
+    readonly cols: number;
+    readonly rowHeight: number;
+    readonly colWidth: number;
+}
+export declare const DEFAULT_LIMITS: Limits;
+export interface Frozen {
+    readonly rows: number;
+    readonly cols: number;
+}
+export declare class Sheet {
+    readonly id: string;
+    name: string;
+    readonly rows: Axis;
+    readonly cols: Axis;
+    readonly cells: SheetCells;
+    /** Merged zones, disjoint. */
+    merges: Zone[];
+    frozen: Frozen;
+    constructor(id: string, name: string, limits: Limits, cells: SheetCells);
+    /** The merge holding a position, or `undefined`. */
+    mergeAt(row: number, col: number): Zone | undefined;
+    /** Merges overlapping a zone. */
+    mergesIn(zone: Zone): Zone[];
+}
+export declare class Workbook {
+    #private;
+    readonly limits: Limits;
+    readonly strings: StringPool;
+    readonly styles: StyleTable;
+    readonly formulas: FormulaTable;
+    /** In tab order. */
+    readonly sheets: Sheet[];
+    constructor(limits?: Limits);
+    /** A new, detached sheet with a fresh id; `ADD_SHEET` attaches it through a patch. */
+    createSheet(name: string, id?: string): Sheet;
+    /** The sheet of that id; throws a sentence naming the ids there are. */
+    sheet(id: string): Sheet;
+    hasSheet(id: string): boolean;
+    /** The sheet of that name, case-insensitively, as Excel matches names. */
+    sheetByName(name: string): Sheet | undefined;
+    /** A name no sheet has: `Sheet1`, `Sheet2`, … */
+    freshSheetName(): string;
+}
+//# sourceMappingURL=workbook.d.ts.map

package/lib/core/workbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook.d.ts","sourceRoot":"","sources":["../../src/core/workbook.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,IAAI,EAAgB,MAAM,WAAW,CAAC;AAEpD,sDAAsD;AACtD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,cAAc,EAAE,MAK5B,CAAC;AAEF,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,8BAA8B;IAC9B,MAAM,EAAE,IAAI,EAAE,CAAM;IACpB,MAAM,EAAE,MAAM,CAAwB;gBAE1B,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAQvE,oDAAoD;IACpD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAMnD,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE;CAG7B;AAED,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,aAAoB;IACpC,QAAQ,CAAC,MAAM,aAAoB;IACnC,QAAQ,CAAC,QAAQ,eAAsB;IACvC,oBAAoB;IACpB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAM;gBAGlB,MAAM,GAAE,MAAuB;IAQ3C,sFAAsF;IACtF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK;IAY7C,wEAAwE;IACxE,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK;IAUxB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI7B,0EAA0E;IAC1E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAK5C,iDAAiD;IACjD,cAAc,IAAI,MAAM;CAUzB"}

package/lib/core/workbook.js

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2022-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * The persisted state of a workbook: sheets, their axes and cells, merges and
+ * frozen panes, and the pools cells reference (strings, styles, formulas).
+ * Only patches write it (core/patches); the model reads it through getters.
+ *
+ * @module core/workbook
+ */
+import { Axis } from './axis.js';
+import { FormulaTable, SheetCells } from './cells.js';
+import { StringPool } from './strings.js';
+import { StyleTable } from './styles.js';
+import { zonesOverlap } from './zone.js';
+export const DEFAULT_LIMITS = {
+    rows: 1_048_576,
+    cols: 16_384,
+    rowHeight: 21,
+    colWidth: 100,
+};
+export class Sheet {
+    id;
+    name;
+    rows;
+    cols;
+    cells;
+    /** Merged zones, disjoint. */
+    merges = [];
+    frozen = { rows: 0, cols: 0 };
+    constructor(id, name, limits, cells) {
+        this.id = id;
+        this.name = name;
+        this.rows = new Axis({ count: limits.rows, defaultSize: limits.rowHeight });
+        this.cols = new Axis({ count: limits.cols, defaultSize: limits.colWidth });
+        this.cells = cells;
+    }
+    /** The merge holding a position, or `undefined`. */
+    mergeAt(row, col) {
+        return this.merges.find((m) => row >= m.top && row <= m.bottom && col >= m.left && col <= m.right);
+    }
+    /** Merges overlapping a zone. */
+    mergesIn(zone) {
+        return this.merges.filter((m) => zonesOverlap(m, zone));
+    }
+}
+export class Workbook {
+    limits;
+    strings = new StringPool();
+    styles = new StyleTable();
+    formulas = new FormulaTable();
+    /** In tab order. */
+    sheets = [];
+    #nextSheet = 1;
+    constructor(limits = DEFAULT_LIMITS) {
+        for (const [key, value] of Object.entries(limits)) {
+            if (!(typeof value === 'number' && value > 0))
+                throw new Error(`limits.${key} must be positive; ${value} was given.`);
+        }
+        this.limits = limits;
+    }
+    /** A new, detached sheet with a fresh id; `ADD_SHEET` attaches it through a patch. */
+    createSheet(name, id) {
+        const sheetId = id ?? this.#freshSheetId();
+        if (this.sheets.some((s) => s.id === sheetId))
+            throw new Error(`A sheet with id '${sheetId}' exists already.`);
+        return new Sheet(sheetId, name, this.limits, new SheetCells({ strings: this.strings, formulas: this.formulas }));
+    }
+    /** The sheet of that id; throws a sentence naming the ids there are. */
+    sheet(id) {
+        const sheet = this.sheets.find((s) => s.id === id);
+        if (sheet === undefined) {
+            throw new Error(`No sheet '${id}'; the workbook has ${this.sheets.map((s) => s.id).join(', ') || 'none'}.`);
+        }
+        return sheet;
+    }
+    hasSheet(id) {
+        return this.sheets.some((s) => s.id === id);
+    }
+    /** The sheet of that name, case-insensitively, as Excel matches names. */
+    sheetByName(name) {
+        const lower = name.toLowerCase();
+        return this.sheets.find((s) => s.name.toLowerCase() === lower);
+    }
+    /** A name no sheet has: `Sheet1`, `Sheet2`, … */
+    freshSheetName() {
+        for (let i = 1;; i += 1)
+            if (this.sheetByName(`Sheet${i}`) === undefined)
+                return `Sheet${i}`;
+    }
+    #freshSheetId() {
+        for (;;) {
+            const id = `s${this.#nextSheet++}`;
+            if (!this.hasSheet(id))
+                return id;
+        }
+    }
+}
+//# sourceMappingURL=workbook.js.map

package/lib/core/workbook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook.js","sourceRoot":"","sources":["../../src/core/workbook.ts"],"names":[],"mappings":"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"}

package/lib/core/zone.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Positions, zones and A1 notation. Rows and columns are 0-based in memory;
+ * A1 is 1-based for rows and lettered for columns.
+ *
+ * @module core/zone
+ */
+/** A cell position: row and column, 0-based. */
+export interface Position {
+    readonly row: number;
+    readonly col: number;
+}
+/** A rectangle of cells, inclusive on both ends, 0-based. */
+export interface Zone {
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/** A position on a named sheet. */
+export interface CellAddress extends Position {
+    readonly sheet: string;
+}
+/** Column letters of a 0-based index: 0 → A, 25 → Z, 26 → AA. */
+export declare function columnLetters(col: number): string;
+/** The 0-based index of column letters: A → 0, AA → 26. Case-insensitive. */
+export declare function columnIndex(letters: string): number;
+/** `B3` for {row: 2, col: 1}. */
+export declare function toA1(p: Position): string;
+/** The position of `B3` (anchors ignored). Throws on anything else. */
+export declare function parseA1(text: string): Position;
+/** The zone of `A1:C4`, `B3` (one cell), in any corner order. */
+export declare function parseZone(text: string): Zone;
+/** `A1:C4`, or `B3` for a single cell. */
+export declare function zoneToA1(z: Zone): string;
+/** The smallest zone holding both positions. */
+export declare function zoneOf(a: Position, b?: Position): Zone;
+export declare function zoneContains(z: Zone, p: Position): boolean;
+export declare function zonesOverlap(a: Zone, b: Zone): boolean;
+export declare function zoneSize(z: Zone): {
+    rows: number;
+    cols: number;
+};
+/** A reference that may name a sheet: `Sheet2!B3`, `'My sheet'!A1:B2`. */
+export declare function splitSheet(ref: string): {
+    sheet?: string;
+    ref: string;
+};
+//# sourceMappingURL=zone.d.ts.map

package/lib/core/zone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone.d.ts","sourceRoot":"","sources":["../../src/core/zone.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH,gDAAgD;AAChD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,6DAA6D;AAC7D,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,iCAAiC;AACjC,wBAAgB,IAAI,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAExC;AAID,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAI9C;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAO5C;AAED,0CAA0C;AAC1C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAKxC;AAED,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAE,QAAY,GAAG,IAAI,CAOzD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAEtD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEhE;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAWvE"}

package/lib/core/zone.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2022-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/** Column letters of a 0-based index: 0 → A, 25 → Z, 26 → AA. */
+export function columnLetters(col) {
+    if (!Number.isInteger(col) || col < 0)
+        throw new Error(`No column at index ${col}.`);
+    let name = '';
+    let n = col + 1;
+    while (n > 0) {
+        const rest = (n - 1) % 26;
+        name = String.fromCharCode(65 + rest) + name;
+        n = Math.floor((n - 1) / 26);
+    }
+    return name;
+}
+/** The 0-based index of column letters: A → 0, AA → 26. Case-insensitive. */
+export function columnIndex(letters) {
+    if (!/^[A-Za-z]{1,3}$/.test(letters))
+        throw new Error(`'${letters}' is not a column (A to XFD).`);
+    let n = 0;
+    for (const ch of letters.toUpperCase())
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    return n - 1;
+}
+/** `B3` for {row: 2, col: 1}. */
+export function toA1(p) {
+    return `${columnLetters(p.col)}${p.row + 1}`;
+}
+const CELL = /^\$?([A-Za-z]{1,3})\$?([1-9][0-9]{0,6})$/;
+/** The position of `B3` (anchors ignored). Throws on anything else. */
+export function parseA1(text) {
+    const m = CELL.exec(text.trim());
+    if (!m)
+        throw new Error(`'${text}' is not a cell reference such as B3.`);
+    return { row: Number(m[2]) - 1, col: columnIndex(m[1]) };
+}
+/** The zone of `A1:C4`, `B3` (one cell), in any corner order. */
+export function parseZone(text) {
+    const parts = text.trim().split(':');
+    if (parts.length > 2 || parts[0] === '')
+        throw new Error(`'${text}' is not a range such as A1:C4.`);
+    const a = parseA1(parts[0]);
+    const b = parts.length === 2 ? parseA1(parts[1]) : a;
+    return zoneOf(a, b);
+}
+/** `A1:C4`, or `B3` for a single cell. */
+export function zoneToA1(z) {
+    const tl = toA1({ row: z.top, col: z.left });
+    return z.top === z.bottom && z.left === z.right
+        ? tl
+        : `${tl}:${toA1({ row: z.bottom, col: z.right })}`;
+}
+/** The smallest zone holding both positions. */
+export function zoneOf(a, b = a) {
+    return {
+        top: Math.min(a.row, b.row),
+        left: Math.min(a.col, b.col),
+        bottom: Math.max(a.row, b.row),
+        right: Math.max(a.col, b.col),
+    };
+}
+export function zoneContains(z, p) {
+    return p.row >= z.top && p.row <= z.bottom && p.col >= z.left && p.col <= z.right;
+}
+export function zonesOverlap(a, b) {
+    return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
+}
+export function zoneSize(z) {
+    return { rows: z.bottom - z.top + 1, cols: z.right - z.left + 1 };
+}
+/** A reference that may name a sheet: `Sheet2!B3`, `'My sheet'!A1:B2`. */
+export function splitSheet(ref) {
+    const bang = ref.lastIndexOf('!');
+    if (bang < 0)
+        return { ref };
+    let sheet = ref.slice(0, bang);
+    if (sheet.startsWith("'")) {
+        if (!sheet.endsWith("'") || sheet.length < 2)
+            throw new Error(`'${ref}' has an unclosed sheet name.`);
+        sheet = sheet.slice(1, -1).replace(/''/g, "'");
+    }
+    if (sheet === '')
+        throw new Error(`'${ref}' names an empty sheet.`);
+    return { sheet, ref: ref.slice(bang + 1) };
+}
+//# sourceMappingURL=zone.js.map

package/lib/core/zone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone.js","sourceRoot":"","sources":["../../src/core/zone.ts"],"names":[],"mappings":"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"}