@shbernal/ts-xlsx 1.0.0

package/dist/core/column.js

@@ -0,0 +1,167 @@
+// A handle on one column of a worksheet: its formatting and its cells, reached by column index.
+//
+// The other axis of `Row`, and the same contract — a live view over the worksheet's stores, position
+// fixed at construction, formatting created on write rather than on read. See `core/row.ts` for why
+// it is a handle rather than a record.
+//
+// A column carries more than a row does: besides the geometry (width, visibility, outline) it holds
+// the six `CellStyle` facets as *defaults* for its cells, which is why the mirror below is twice the
+// length of the row's.
+import { encodeAddress, numberToColumn } from "./address.js";
+import { INTERNAL } from "./internal.js";
+export class Column {
+    #sheet;
+    /** 1-based column index. Fixed for this handle's lifetime. */
+    index;
+    /** @throws {RangeError} if the index is not a positive integer. */
+    constructor(sheet, index) {
+        if (!Number.isInteger(index) || index < 1) {
+            throw new RangeError(`column ${index} is out of bounds — columns start at 1`);
+        }
+        this.#sheet = sheet;
+        this.index = index;
+    }
+    /** The column's letters (`"B"`) — the spreadsheet-facing name for {@link index}. */
+    get letter() {
+        return numberToColumn(this.index);
+    }
+    /**
+     * The column's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * serializer can ask every column it visits whether there are attributes to emit without giving
+     * each one an empty record. Read-only on purpose: {@link width} and its siblings are how a column
+     * is formatted, and they create the record on first write.
+     */
+    get properties() {
+        return this.#sheet[INTERNAL].columnPropertiesOf(this.index);
+    }
+    /**
+     * Stable key naming this column so a keyed-object row (see {@link Worksheet.addRow}) can place a
+     * value under it by name rather than position. In-memory only — never serialized to OOXML.
+     */
+    get key() {
+        return this.#read('key');
+    }
+    set key(key) {
+        this.#write('key', key);
+    }
+    /** Column width in character units; `undefined` leaves the sheet default in force. */
+    get width() {
+        return this.#read('width');
+    }
+    set width(width) {
+        this.#write('width', width);
+    }
+    /** Whether the column is hidden. */
+    get hidden() {
+        return this.#read('hidden');
+    }
+    set hidden(hidden) {
+        this.#write('hidden', hidden);
+    }
+    /** Outline (grouping) depth; 0 or `undefined` means ungrouped. */
+    get outlineLevel() {
+        return this.#read('outlineLevel');
+    }
+    set outlineLevel(outlineLevel) {
+        this.#write('outlineLevel', outlineLevel);
+    }
+    /** Whether this column is the collapsed summary of an outline group. */
+    get collapsed() {
+        return this.#read('collapsed');
+    }
+    set collapsed(collapsed) {
+        this.#write('collapsed', collapsed);
+    }
+    /** Default fill for the column's cells that set none of their own. */
+    get fill() {
+        return this.#read('fill');
+    }
+    set fill(fill) {
+        this.#write('fill', fill);
+    }
+    /** Default number format for the column's cells that set none of their own. */
+    get numFmt() {
+        return this.#read('numFmt');
+    }
+    set numFmt(numFmt) {
+        this.#write('numFmt', numFmt);
+    }
+    /** Default font for the column's cells that set none of their own. */
+    get font() {
+        return this.#read('font');
+    }
+    set font(font) {
+        this.#write('font', font);
+    }
+    /** Default border for the column's cells that set none of their own. */
+    get border() {
+        return this.#read('border');
+    }
+    set border(border) {
+        this.#write('border', border);
+    }
+    /** Default alignment for the column's cells that set none of their own. */
+    get alignment() {
+        return this.#read('alignment');
+    }
+    set alignment(alignment) {
+        this.#write('alignment', alignment);
+    }
+    /** Default protection flags for the column's cells that set none of their own. */
+    get protection() {
+        return this.#read('protection');
+    }
+    set protection(protection) {
+        this.#write('protection', protection);
+    }
+    /**
+     * The cell at a 1-based row number in this column, creating it on first access. Resolves through
+     * merges exactly as {@link Worksheet.getCell} does.
+     *
+     * @throws {RangeError} if the row is not a positive integer.
+     */
+    getCell(row) {
+        return this.#sheet.getCell(encodeAddress(this.index, row));
+    }
+    /**
+     * The column's materialised cells in ascending row order. Sparse: a row that never wrote to this
+     * column has no cell here.
+     */
+    get cells() {
+        return this.#sheet[INTERNAL].columnCells(this.index);
+    }
+    /**
+     * The column's values by position, index 0 being row 1. Sparse in the same way {@link cells} is:
+     * a row with no cell in this column is a hole, which is what distinguishes "never written" from a
+     * cell holding `null`.
+     *
+     * Assigning places each value it names and leaves every other row untouched, mirroring
+     * {@link Row.values} — a hole or an explicit `undefined` skips that row, and a shorter array does
+     * not clear the tail.
+     */
+    get values() {
+        const values = [];
+        for (const cell of this.cells)
+            values[cell.row - 1] = cell.value;
+        return values;
+    }
+    set values(values) {
+        values.forEach((value, index) => {
+            if (value !== undefined)
+                this.getCell(index + 1).value = value;
+        });
+    }
+    #read(key) {
+        return this.#sheet[INTERNAL].columnPropertiesOf(this.index)?.[key];
+    }
+    // `undefined` clears rather than stores — see the note on `Row`'s counterpart.
+    #write(key, value) {
+        if (value === undefined) {
+            const properties = this.#sheet[INTERNAL].columnPropertiesOf(this.index);
+            if (properties !== undefined)
+                delete properties[key];
+            return;
+        }
+        this.#sheet[INTERNAL].ensureColumnProperties(this.index)[key] = value;
+    }
+}

package/dist/core/comment-thread.d.ts

@@ -0,0 +1,116 @@
+/**
+ * A registered identity a threaded comment can point at — an author, or someone `@mentioned` in a
+ * message. One `<person>` of the workbook's `xl/persons/person.xml` registry.
+ *
+ * A single human legitimately has **several** entries: Excel registers a mentioned identity separately
+ * from that person's authoring identity, with the same {@link displayName} and {@link userId} but a
+ * different {@link id} and a different {@link providerId}. The id is therefore the only identity —
+ * see {@link Workbook.getPerson}.
+ */
+export interface Person {
+    /** Brace-wrapped GUID this identity is referenced by. The only field that identifies it. */
+    readonly id: string;
+    /** The name a spreadsheet app shows — not unique, and not an identity. */
+    readonly displayName: string;
+    /** Identity-provider handle, `S::<email>::<tenant-guid>` for an AzureAD account. */
+    readonly userId?: string;
+    /** The provider that registered this entry — `AD` for a directory account, `PeoplePicker` for an
+     * identity interned by being mentioned. */
+    readonly providerId?: string;
+}
+/**
+ * An `@mention` inside a message: who was named, and the run of {@link Comment.text} that renders as the
+ * mention chip.
+ *
+ * The offsets are only meaningful against that exact text — shift either and a spreadsheet app
+ * highlights the wrong words.
+ */
+export interface Mention {
+    /**
+     * The mentioned identity, resolved through the workbook registry. Absent when the file names an id
+     * the registry does not hold (a mention left dangling by a foreign generator); {@link personId}
+     * still says who was meant.
+     */
+    readonly person?: Person;
+    /** The mentioned {@link Person.id} exactly as written, so a dangling mention stays diagnosable. */
+    readonly personId: string;
+    /** Excel's own id for this mention, preserved so re-emitting it does not invent a new one. */
+    readonly mentionId?: string;
+    /** 0-based character offset into {@link Comment.text} where the mention starts. */
+    readonly startIndex: number;
+    /** Length of the mention in characters, **counting the leading `@`** (`@Grace Hopper` is 13). */
+    readonly length: number;
+}
+/** One message of a {@link CommentThread} — what a single person wrote, once. */
+export interface Comment {
+    /** Brace-wrapped GUID identifying this message, preserved verbatim from the file. */
+    readonly id: string;
+    /**
+     * Who wrote it, resolved through the workbook registry. Absent when the file recorded no author or
+     * named an id the registry does not hold; {@link personId} distinguishes those two cases.
+     */
+    readonly author?: Person;
+    /** The author's {@link Person.id} exactly as written; absent when the file recorded no author. */
+    readonly personId?: string;
+    /**
+     * When it was written, verbatim. Excel writes local wall-clock with fractional seconds and no
+     * timezone (`2026-07-24T10:56:41.72`), which is not a round-trippable instant — keeping the string
+     * spares the reader from inventing a zone the file never stated.
+     */
+    readonly date?: string;
+    /** The message body as plain text. Mention chips are part of it; {@link mentions} spans it. */
+    readonly text: string;
+    /** The `@mentions` this message carries, in document order. Empty for a message that names no one. */
+    readonly mentions: readonly Mention[];
+}
+/**
+ * The one spelling every threaded-comment identifier must take on the wire: brace-wrapped, upper-case hex.
+ *
+ * Verified against the OOXML schema, which pins `person/@id`, a message's `id`/`personId`/`parentId`, and a
+ * mention's `mentionpersonId`/`mentionId` to exactly `\{[0-9A-F]{8}-…\}` — a bare GUID and a lower-case one
+ * are each rejected outright. So this normalises rather than merely checking: a caller passing
+ * `crypto.randomUUID()` gets a valid file instead of one Excel offers to repair.
+ *
+ * The authoring path alone goes through here. A file's own ids are re-emitted as the file wrote them, since
+ * a reader that rewrote them would break every reference pointing at them.
+ *
+ * @throws {SyntaxError} if the value is not a GUID in any spelling.
+ */
+export declare function commentThreadGuid(value: string, what: string): string;
+/**
+ * The largest value a mention offset can take on the wire. Verified against the OOXML schema: both
+ * `startIndex` and `length` are `xsd:unsignedInt`, so `4294967295` validates and `4294967296` is rejected
+ * as "not a valid 'UInt32' value".
+ *
+ * Wildly beyond any real message, and that is the point — the ceiling exists so a value from a hostile
+ * part can never reach the serialiser. JavaScript spells a large enough number in exponent form
+ * (`String(1e21)` is `"1e+21"`), which is not a numeric literal any schema accepts, and one invalid
+ * attribute is enough for Excel to offer to repair the whole conversation away.
+ */
+export declare const MENTION_OFFSET_MAX = 4294967295;
+/**
+ * A mention offset as the wire accepts it: a whole number within {@link MENTION_OFFSET_MAX}.
+ *
+ * The authoring path alone throws. A file's own mentions are read leniently — one carrying an unusable
+ * offset is dropped, keeping the message text and losing only the chip — because a foreign generator's
+ * arithmetic is not something a caller can fix, whereas their own is.
+ *
+ * @throws {SyntaxError} if the value is negative, fractional, or beyond the wire's ceiling.
+ */
+export declare function commentThreadOffset(value: number, what: string): number;
+/** A conversation anchored to one cell: what was asked, every reply, and whether it was resolved. */
+export interface CommentThread {
+    /**
+     * A1 reference of the single cell the conversation hangs off, canonicalised — no `$` anchors, always
+     * a column and a row — so two anchors compare as plain strings and a writer can resolve it without
+     * re-validating it.
+     */
+    readonly ref: string;
+    /**
+     * Whether the conversation was marked resolved. A property of the *thread*: only the head carries
+     * the flag on the wire, so a reply never disagrees with the thread it belongs to.
+     */
+    readonly resolved: boolean;
+    /** The opening message first, then its replies in the order they were written. Never empty. */
+    readonly comments: readonly Comment[];
+}

package/dist/core/comment-thread.js

@@ -0,0 +1,62 @@
+// Modern threaded comments in the model — the review-style conversations Excel has written since 2018:
+// an anchored discussion of authored messages with timestamps, replies, a resolved state, and
+// @mentions. Distinct from a legacy note (`cell.note`), which is a single anonymous annotation; Excel's
+// own UI draws the same line, calling these "comments" and those "notes". A cell carries one or the
+// other, never both.
+//
+// The wire form lives in two parts (see `io/xlsx/threaded-comments.ts`): the messages per sheet, and a
+// workbook-level identity registry the messages point into. The model mirrors that split — a thread's
+// authors and mentioned people are {@link Person} entries resolved through
+// {@link Workbook.getPerson}, not names duplicated onto every message.
+// A GUID in any of the spellings a caller plausibly has one in — braced or bare, upper or lower case.
+// `crypto.randomUUID()` produces the bare lower-case form, so accepting only the canonical spelling would
+// reject the one obvious way to make an id in JavaScript.
+const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})\}?$/i;
+/**
+ * The one spelling every threaded-comment identifier must take on the wire: brace-wrapped, upper-case hex.
+ *
+ * Verified against the OOXML schema, which pins `person/@id`, a message's `id`/`personId`/`parentId`, and a
+ * mention's `mentionpersonId`/`mentionId` to exactly `\{[0-9A-F]{8}-…\}` — a bare GUID and a lower-case one
+ * are each rejected outright. So this normalises rather than merely checking: a caller passing
+ * `crypto.randomUUID()` gets a valid file instead of one Excel offers to repair.
+ *
+ * The authoring path alone goes through here. A file's own ids are re-emitted as the file wrote them, since
+ * a reader that rewrote them would break every reference pointing at them.
+ *
+ * @throws {SyntaxError} if the value is not a GUID in any spelling.
+ */
+export function commentThreadGuid(value, what) {
+    const match = GUID.exec(value.trim());
+    if (match === null) {
+        throw new SyntaxError(`${what} must be a GUID — Excel writes threaded-comment ids as ` +
+            `"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}" — but got "${value}"`);
+    }
+    return `{${match.slice(1).join('-').toUpperCase()}}`;
+}
+/**
+ * The largest value a mention offset can take on the wire. Verified against the OOXML schema: both
+ * `startIndex` and `length` are `xsd:unsignedInt`, so `4294967295` validates and `4294967296` is rejected
+ * as "not a valid 'UInt32' value".
+ *
+ * Wildly beyond any real message, and that is the point — the ceiling exists so a value from a hostile
+ * part can never reach the serialiser. JavaScript spells a large enough number in exponent form
+ * (`String(1e21)` is `"1e+21"`), which is not a numeric literal any schema accepts, and one invalid
+ * attribute is enough for Excel to offer to repair the whole conversation away.
+ */
+export const MENTION_OFFSET_MAX = 0xffff_ffff;
+/**
+ * A mention offset as the wire accepts it: a whole number within {@link MENTION_OFFSET_MAX}.
+ *
+ * The authoring path alone throws. A file's own mentions are read leniently — one carrying an unusable
+ * offset is dropped, keeping the message text and losing only the chip — because a foreign generator's
+ * arithmetic is not something a caller can fix, whereas their own is.
+ *
+ * @throws {SyntaxError} if the value is negative, fractional, or beyond the wire's ceiling.
+ */
+export function commentThreadOffset(value, what) {
+    if (!Number.isInteger(value) || value < 0 || value > MENTION_OFFSET_MAX) {
+        throw new SyntaxError(`${what} must be a whole number between 0 and ${MENTION_OFFSET_MAX} — a mention's span is ` +
+            `written as an unsigned 32-bit integer — but got ${value}`);
+    }
+    return value;
+}

package/dist/core/conditional-formatting-overlay.d.ts

@@ -0,0 +1,15 @@
+import { type ConditionalFormatting } from './conditional-formatting.ts';
+export declare class ConditionalFormattingOverlay {
+    #private;
+    /**
+     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref` — one
+     * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
+     * rule set. The block is stored once against the range, defensively copied so the getter never hands
+     * back a reference into the caller's object.
+     */
+    add(formatting: ConditionalFormatting): void;
+    /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
+    get entries(): readonly ConditionalFormatting[];
+    /** Drop every conditional formatting, leaving the overlay empty. */
+    clear(): void;
+}

package/dist/core/conditional-formatting-overlay.js

@@ -0,0 +1,24 @@
+// The conditional-formatting overlay a Worksheet owns: an insertion-ordered, defensively-copied list
+// of range-bound rule sets. Kept as its own class, the sibling to {@link DataValidationOverlay}, so
+// Worksheet delegates the collection's storage and cloning rather than managing the array itself.
+import { cloneConditionalFormatting } from "./conditional-formatting.js";
+export class ConditionalFormattingOverlay {
+    #entries = [];
+    /**
+     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref` — one
+     * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
+     * rule set. The block is stored once against the range, defensively copied so the getter never hands
+     * back a reference into the caller's object.
+     */
+    add(formatting) {
+        this.#entries.push(cloneConditionalFormatting(formatting));
+    }
+    /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
+    get entries() {
+        return this.#entries;
+    }
+    /** Drop every conditional formatting, leaving the overlay empty. */
+    clear() {
+        this.#entries.length = 0;
+    }
+}

package/dist/core/conditional-formatting.d.ts

@@ -0,0 +1,70 @@
+import type { Color, DifferentialStyle } from './style.ts';
+/**
+ * One anchor of a colour-scale, data-bar, or icon-set scale — a "conditional format value object".
+ * `type` names how `value` is read: a literal `num`, a `percent`/`percentile` of the range, a
+ * `formula`, or the range's own `min`/`max` (which carry no value).
+ */
+export interface CfValueObject {
+    type: 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+    value?: number | string;
+}
+/**
+ * A single conditional-formatting rule. `type` is the OOXML cfRule type; the remaining fields carry
+ * the operands that type needs and are absent otherwise. A rule the library does not model in depth
+ * still preserves `type`, `priority`, `operator`, `formulae`, and `dxfId` across a round-trip.
+ */
+export interface ConditionalFormattingRule {
+    type: string;
+    /** Evaluation precedence; lower wins. Excel requires one — the writer supplies it when absent. */
+    priority?: number;
+    /** Halt evaluation of lower-priority rules on any cell this rule matches. */
+    stopIfTrue?: boolean;
+    /** cellIs / text comparison operator (`greaterThan`, `between`, `beginsWith`, …). */
+    operator?: string;
+    /** Formula operands: cellIs bounds, an expression predicate, a containsText target formula, … */
+    formulae?: (string | number)[];
+    /** The literal a containsText / beginsWith / endsWith rule searches for. */
+    text?: string;
+    /** A differential style authored inline, serialised into `<dxfs>` and referenced by the cfRule. */
+    style?: DifferentialStyle;
+    /** A differential-style reference by `<dxfs>` index, as read from a file (kept verbatim). */
+    dxfId?: string;
+    /** colorScale / dataBar / iconSet scale anchors, in order. */
+    cfvo?: CfValueObject[];
+    /** A dataBar's bar colour. */
+    color?: Color;
+    /** A colorScale's colours, one per {@link cfvo}. */
+    colors?: Color[];
+    /** A dataBar's gradient-fill flag. Lives only in the x14 extension, not the classic element. */
+    gradient?: boolean;
+    /** A dataBar's fill colour for negative values. An x14 extension property. */
+    negativeFillColor?: Color;
+    /** A dataBar's axis colour (the zero line between positive and negative bars). An x14 property. */
+    axisColor?: Color;
+    /** An iconSet's named icon family (e.g. `3TrafficLights1`). */
+    iconSet?: string;
+    /** top10 rank cutoff. */
+    rank?: number;
+    /** top10: the rank is a percentage rather than a count. */
+    percent?: boolean;
+    /** top10: rank from the bottom rather than the top. */
+    bottom?: boolean;
+    /** aboveAverage: match above (default) or below the average. */
+    aboveAverage?: boolean;
+    /** aboveAverage: include cells equal to the average. */
+    equalAverage?: boolean;
+    /** aboveAverage: match beyond this many standard deviations. */
+    stdDev?: number;
+    /** timePeriod window (`today`, `lastWeek`, …). */
+    timePeriod?: string;
+}
+/** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref` — one or more
+ * space-separated areas (`"A1:C1 A3:C3 A5:C5"`), the shape Excel writes when one rule is applied to
+ * several non-contiguous selections at once. */
+export interface ConditionalFormatting {
+    ref: string;
+    rules: ConditionalFormattingRule[];
+}
+/** A defensive deep copy, so a stored conditional formatting never aliases the caller's object nor
+ * any of its nested arrays (rules, formulae, cfvo, colours) or the differential style. */
+export declare function cloneConditionalFormatting(cf: ConditionalFormatting): ConditionalFormatting;

package/dist/core/conditional-formatting.js

@@ -0,0 +1,35 @@
+// Conditional formatting — the rules that restyle a cell based on its value (a data bar, a colour
+// scale, a "highlight cells greater than 10", a formula-driven expression). Like a data validation,
+// it is a worksheet-level overlay keyed by a target range, not a facet owned by one cell: one rule
+// covers a whole range, and several rules can layer on the same cells with an evaluation precedence.
+//
+// The model carries the operands each rule type needs and otherwise leaves them absent. A rule type
+// the library does not interpret in depth still round-trips its `type`, `priority`, `operator`,
+// `formulae`, and differential-style reference — so a read/write cycle never silently drops a rule.
+/** A defensive deep copy, so a stored conditional formatting never aliases the caller's object nor
+ * any of its nested arrays (rules, formulae, cfvo, colours) or the differential style. */
+export function cloneConditionalFormatting(cf) {
+    return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
+}
+function cloneRule(rule) {
+    return {
+        ...rule,
+        ...(rule.formulae !== undefined ? { formulae: [...rule.formulae] } : {}),
+        ...(rule.cfvo !== undefined ? { cfvo: rule.cfvo.map((v) => ({ ...v })) } : {}),
+        ...(rule.color !== undefined ? { color: { ...rule.color } } : {}),
+        ...(rule.negativeFillColor !== undefined
+            ? { negativeFillColor: { ...rule.negativeFillColor } }
+            : {}),
+        ...(rule.axisColor !== undefined ? { axisColor: { ...rule.axisColor } } : {}),
+        ...(rule.colors !== undefined ? { colors: rule.colors.map((c) => ({ ...c })) } : {}),
+        ...(rule.style !== undefined ? { style: cloneStyle(rule.style) } : {}),
+    };
+}
+function cloneStyle(style) {
+    return {
+        ...style,
+        ...(style.font !== undefined ? { font: { ...style.font } } : {}),
+        ...(style.fill !== undefined ? { fill: { ...style.fill } } : {}),
+        ...(style.border !== undefined ? { border: { ...style.border } } : {}),
+    };
+}

package/dist/core/containers.d.ts

@@ -0,0 +1,2 @@
+export declare function overwrite<T extends object>(target: T, source: T): void;
+export declare function replaceContents<T>(array: T[], next: readonly T[]): void;

package/dist/core/containers.js

@@ -0,0 +1,25 @@
+// Identity-preserving replacement of a container's contents.
+//
+// Several model fields are `readonly` fields holding a mutable object or array: a caller (or a live
+// getter) may hold a durable reference to the container, so importing a model must replace what the
+// container *holds* without swapping the container itself. These two primitives do that — one for an
+// object's keys, one for an array's elements — so the field's identity survives a wholesale reload.
+// Replace an object's contents in place: clear every own key, then copy `source`'s keys over. Used for
+// fields like a worksheet's `properties`/`pageSetup`/`headerFooter`, which are `readonly` fields holding
+// mutable objects, so importing a model must overwrite them rather than reassign — and clear any stale
+// key the incoming model does not carry. `Reflect` deletes each existing key without pretending the
+// object carries a string index signature.
+export function overwrite(target, source) {
+    for (const key of Reflect.ownKeys(target))
+        Reflect.deleteProperty(target, key);
+    Object.assign(target, source);
+}
+// Replace an array's contents in place: clear it, then append `next` element by element. Appends
+// individually rather than spreading `next` into a single `push(...next)` call, whose argument count the
+// JS engine bounds by its call-stack limit — these arrays are filled from parsed files, so a hostile
+// input must not be able to overflow that limit.
+export function replaceContents(array, next) {
+    array.length = 0;
+    for (const item of next)
+        array.push(item);
+}

package/dist/core/data-validation-overlay.d.ts

@@ -0,0 +1,28 @@
+import { type DataValidation, type DataValidationEntry } from './data-validation.ts';
+export declare class DataValidationOverlay {
+    #private;
+    /**
+     * Attach a rule to a target range (`"B2:B20"`, a whole column `"B2:B1048576"`, or a space-separated
+     * `sqref` of several ranges). The rule is stored once against the range, not copied per covered
+     * cell, so a whole-column dropdown stays a single entry. A cell inside the range reports the rule
+     * through {@link at}.
+     *
+     * Pass `{extended: true}` to mark a rule that belongs in the 2009 extension form
+     * (`<x14:dataValidation>`) — the carrier Excel uses for a list source on another sheet and other
+     * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
+     * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
+     */
+    add(sqref: string, rule: DataValidation, options?: {
+        extended?: boolean;
+    }): void;
+    /** The data validations on this sheet, each bound to its target range, in insertion order. */
+    get entries(): readonly DataValidationEntry[];
+    /**
+     * The validation covering the 1-based `col`/`row`, or `undefined` when none does. The first added
+     * rule whose range contains the cell wins, mirroring how a spreadsheet resolves overlapping
+     * validations.
+     */
+    at(col: number, row: number): DataValidation | undefined;
+    /** Drop every validation, leaving the overlay empty. */
+    clear(): void;
+}

package/dist/core/data-validation-overlay.js

@@ -0,0 +1,56 @@
+// The data-validation overlay a Worksheet owns: an insertion-ordered list of range-bound rules, plus
+// the decoded rectangles a point-in-rect lookup ({@link DataValidationOverlay.at}) tests against. Kept
+// as its own class — the sibling to {@link GridEdits} that owns splice arithmetic — rather than inline
+// on Worksheet, since a validation's storage (a rule plus its decoded ranges) is a self-contained unit
+// Worksheet only ever adds to, reads, or clears wholesale.
+import { cloneDataValidation, } from "./data-validation.js";
+import { decodeSqrefRects } from "./merge.js";
+export class DataValidationOverlay {
+    #entries = [];
+    #rects = [];
+    /**
+     * Attach a rule to a target range (`"B2:B20"`, a whole column `"B2:B1048576"`, or a space-separated
+     * `sqref` of several ranges). The rule is stored once against the range, not copied per covered
+     * cell, so a whole-column dropdown stays a single entry. A cell inside the range reports the rule
+     * through {@link at}.
+     *
+     * Pass `{extended: true}` to mark a rule that belongs in the 2009 extension form
+     * (`<x14:dataValidation>`) — the carrier Excel uses for a list source on another sheet and other
+     * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
+     * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
+     */
+    add(sqref, rule, options = {}) {
+        // One defensive copy, shared by the serialisable entry and the lookup index, so the getter never
+        // hands back a reference into the caller's object.
+        const stored = cloneDataValidation(rule);
+        const entry = { sqref, rule: stored };
+        if (options.extended)
+            entry.extended = true;
+        this.#entries.push(entry);
+        this.#rects.push({ rects: decodeSqrefRects(sqref), rule: stored });
+    }
+    /** The data validations on this sheet, each bound to its target range, in insertion order. */
+    get entries() {
+        return this.#entries;
+    }
+    /**
+     * The validation covering the 1-based `col`/`row`, or `undefined` when none does. The first added
+     * rule whose range contains the cell wins, mirroring how a spreadsheet resolves overlapping
+     * validations.
+     */
+    at(col, row) {
+        for (const { rects, rule } of this.#rects) {
+            for (const rect of rects) {
+                if (col >= rect.left && col <= rect.right && row >= rect.top && row <= rect.bottom) {
+                    return rule;
+                }
+            }
+        }
+        return undefined;
+    }
+    /** Drop every validation, leaving the overlay empty. */
+    clear() {
+        this.#entries.length = 0;
+        this.#rects.length = 0;
+    }
+}

package/dist/core/data-validation.d.ts

@@ -0,0 +1,38 @@
+/** The kind of constraint a validation enforces. `list` is a dropdown; `custom` is an arbitrary
+ * boolean formula; the rest bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
+export type DataValidationType = 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+/** How a typed validation compares its operand(s). Absent on a `list`/`custom` rule; defaults to
+ * `between` on a typed rule (the value Excel omits from the XML). */
+export type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
+/** How Excel reacts to input that fails the rule. */
+export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
+/** One validation rule. `formulae` holds the operand(s) — `formula1` then optional `formula2`: a
+ * numeric literal is stored as a number, while a cell reference, defined name, or list source keeps
+ * its verbatim string. */
+export interface DataValidation {
+    type: DataValidationType;
+    operator?: DataValidationOperator;
+    formulae?: (string | number)[];
+    allowBlank?: boolean;
+    showInputMessage?: boolean;
+    showErrorMessage?: boolean;
+    errorStyle?: DataValidationErrorStyle;
+    error?: string;
+    errorTitle?: string;
+    prompt?: string;
+    promptTitle?: string;
+}
+/** A validation bound to the range(s) it covers. `sqref` is an OOXML `sqref` — one or more
+ * space-separated ranges. `extended` marks a rule stored in the 2009 extension form
+ * (`<x14:dataValidation>` inside the worksheet `<extLst>`) — Excel's carrier for validations a
+ * legacy `<dataValidation>` cannot express, such as a list source on another sheet. The flag is how
+ * a rule read from that form remembers to be written back to it, rather than downgraded to the
+ * standard element (which would corrupt a cross-sheet reference). */
+export interface DataValidationEntry {
+    sqref: string;
+    rule: DataValidation;
+    extended?: boolean;
+}
+/** A defensive copy of a rule, so a stored validation never aliases the caller's object (nor its
+ * `formulae` array). */
+export declare function cloneDataValidation(rule: DataValidation): DataValidation;