@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/core/column.d.ts

@@ -1,4 +1,5 @@
 import type { Cell } from './cell.ts';
+import { type AssertNever } from './internal.ts';
 import type { Alignment, Border, Fill, Font, Protection } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { ColumnProperties, Worksheet } from './worksheet.ts';
@@ -6,12 +7,12 @@ export declare class Column {
     #private;
     /** 1-based column index. Fixed for this handle's lifetime. */
     readonly index: number;
-    /** @throws {RangeError} if the index is not a positive integer. */
+    /** @throws {RangeError} unless the index is an integer within Excel's column grid (1..16384). */
     constructor(sheet: Worksheet, index: number);
-    /** The column's letters (`"B"`) — the spreadsheet-facing name for {@link index}. */
+    /** The column's letters (`"B"`): the spreadsheet-facing name for {@link index}. */
     get letter(): string;
     /**
-     * The column's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * 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.
@@ -19,12 +20,12 @@ export declare class Column {
     get properties(): Readonly<ColumnProperties> | undefined;
     /**
      * 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.
+     * value under it by name rather than position. In-memory only: never serialized to OOXML.
      */
     get key(): string | undefined;
     set key(key: string | undefined);
     /**
-     * Column width in character units — digits of the workbook default font's maximum digit width,
+     * Column width in character units: digits of the workbook default font's maximum digit width,
      * so what one unit measures moves with that font. `undefined` leaves the sheet default in force.
      *
      * Not bounded here, for the same reason {@link Row.height} is not, and for a stronger one:
@@ -79,17 +80,15 @@ export declare class Column {
      * 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
+     * {@link Row.values}: a hole or an explicit `undefined` skips that row, and a shorter array does
      * not clear the tail.
      */
     get values(): (CellValue | undefined)[];
     set values(values: (CellValue | undefined)[]);
 }
-type AssertNever<T extends never> = T;
 /**
- * Compile-time proof that {@link Column} mirrors every {@link ColumnProperties} field — including
+ * Compile-time proof that {@link Column} mirrors every {@link ColumnProperties} field, including
  * the six inherited `CellStyle` facets, so a seventh facet reaches this handle the moment it joins
  * the tuple. See the counterpart on `Row` for why the mirror needs proving rather than reviewing.
  */
 export type EveryColumnPropertyIsMirrored = AssertNever<Exclude<keyof ColumnProperties, keyof Column & keyof ColumnProperties>>;
-export {};

package/dist/core/column.js

@@ -1,12 +1,10 @@
-import { encodeAddress, numberToColumn } from './address.js';
+import { assertColumnInBounds, encodeAddress, numberToColumn } from './address.js';
 import { INTERNAL } from './internal.js';
 export class Column {
     #sheet;
     index;
     constructor(sheet, index) {
-        if (!Number.isInteger(index) || index < 1) {
-            throw new RangeError(`column ${index} is out of bounds — columns start at 1`);
-        }
+        assertColumnInBounds(index);
         this.#sheet = sheet;
         this.index = index;
     }

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

@@ -1,47 +1,56 @@
 /**
- * A registered identity a threaded comment can point at — an author, or someone `@mentioned` in a
+ * 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 —
+ * 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. */
+    /** 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
+    /** 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.
+ * An `@mention` as the file spells it: 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
+ * The offsets are only meaningful against that exact text: shift either and a spreadsheet app
  * highlights the wrong words.
+ *
+ * This is the wire shape, shared with the codec that reads it. {@link Mention} is this plus the
+ * identity we resolved the id to, which is the one thing the file does not carry.
  */
-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;
+export interface MentionRef {
     /** 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. */
+    /**
+     * 0-based character offset into {@link Comment.text} where the mention starts. Verified against
+     * desktop Excel by rendering: the chip covers exactly `[startIndex, startIndex + length)`.
+     */
     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. */
+/** A {@link MentionRef} with its identity resolved against the workbook's person registry. */
+export interface Mention extends MentionRef {
+    /**
+     * 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;
+}
+/** 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;
@@ -54,7 +63,7 @@ export interface Comment {
     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
+     * 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;
@@ -67,7 +76,7 @@ export interface Comment {
  * 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
+ * mention's `mentionpersonId`/`mentionId` to exactly `\{[0-9A-F]{8}-…\}`, so 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.
  *
@@ -82,7 +91,7 @@ export declare function commentThreadGuid(value: string, what: string): string;
  * `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
+ * 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.
@@ -91,8 +100,8 @@ 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
+ * 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.
@@ -101,8 +110,8 @@ 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
+     * A1 reference of the single cell the conversation hangs off, canonicalised with no `$` anchors and
+     * 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;

package/dist/core/comment-thread.js

@@ -2,16 +2,16 @@ const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a
 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}"`);
+        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()}}`;
 }
 export const MENTION_OFFSET_MAX = 0xffff_ffff;
 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}`);
+        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

@@ -2,7 +2,7 @@ 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
+     * 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.
@@ -10,6 +10,11 @@ export declare class ConditionalFormattingOverlay {
     add(formatting: ConditionalFormatting): void;
     /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
     get entries(): readonly ConditionalFormatting[];
+    /**
+     * Re-anchor every rule set through a row or column splice, so a highlight keeps covering the cells
+     * it was written for. A rule set whose every target area fell inside a deleted span goes with them.
+     */
+    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
     /** Drop every conditional formatting, leaving the overlay empty. */
     clear(): void;
 }

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

@@ -1,4 +1,6 @@
 import { cloneConditionalFormatting } from './conditional-formatting.js';
+import { replaceContents } from './containers.js';
+import { shiftSqref } from './merge.js';
 export class ConditionalFormattingOverlay {
     #entries = [];
     add(formatting) {
@@ -7,6 +9,15 @@ export class ConditionalFormattingOverlay {
     get entries() {
         return this.#entries;
     }
+    shift(axis, start, count, delta) {
+        const entries = [];
+        for (const entry of this.#entries) {
+            const ref = shiftSqref(entry.ref, axis, start, count, delta);
+            if (ref !== undefined)
+                entries.push({ ...entry, ref });
+        }
+        replaceContents(this.#entries, entries);
+    }
     clear() {
         this.#entries.length = 0;
     }

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

@@ -1,26 +1,66 @@
 import type { Color, DifferentialStyle } from './style.ts';
+/** How a {@link CfValueObject} reads its `value`: `ST_CfvoType` verbatim. */
+export type CfValueObjectType = 'num' | 'percent' | 'max' | 'min' | 'percentile' | 'formula';
+/** Narrow a raw `<cfvo type>` token to a known {@link CfValueObjectType}. */
+export declare function isCfValueObjectType(value: string): value is CfValueObjectType;
 /**
- * One anchor of a colour-scale, data-bar, or icon-set scale — a "conditional format value object".
+ * 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';
+    type: CfValueObjectType;
     value?: number | string;
 }
+/**
+ * What a rule tests, as `<cfRule type>` carries it: `ST_CfType` verbatim.
+ *
+ * Closed, and stated in full rather than left as `string`, even though the library models only some
+ * of these in depth. Depth of modelling and legality are different questions: a `timePeriod` rule
+ * whose operands the library never inspects still round-trips, while a token outside this list is one
+ * Excel refuses to open, so it is refused on the way in and on the way out alike.
+ */
+export type ConditionalFormattingType = 'expression' | 'cellIs' | 'colorScale' | 'dataBar' | 'iconSet' | 'top10' | 'uniqueValues' | 'duplicateValues' | 'containsText' | 'notContainsText' | 'beginsWith' | 'endsWith' | 'containsBlanks' | 'notContainsBlanks' | 'containsErrors' | 'notContainsErrors' | 'timePeriod' | 'aboveAverage';
+/** Narrow a raw `<cfRule type>` token to a known {@link ConditionalFormattingType}. */
+export declare function isConditionalFormattingType(value: string): value is ConditionalFormattingType;
+/**
+ * How a `cellIs` or text rule compares, as `ST_ConditionalFormattingOperator` enumerates it.
+ *
+ * Overlaps {@link import('./data-validation.ts').DataValidationOperator} in four members and diverges
+ * in the rest: this one has the text comparisons a validation has no use for, and spells "does not
+ * contain" as `notContains` where nothing else in the format does.
+ */
+export type ConditionalFormattingOperator = 'lessThan' | 'lessThanOrEqual' | 'equal' | 'notEqual' | 'greaterThanOrEqual' | 'greaterThan' | 'between' | 'notBetween' | 'containsText' | 'notContains' | 'beginsWith' | 'endsWith';
+/** Narrow a raw `<cfRule operator>` token to a known {@link ConditionalFormattingOperator}. */
+export declare function isConditionalFormattingOperator(value: string): value is ConditionalFormattingOperator;
+/** The window a `timePeriod` rule matches against, relative to the day the sheet is recalculated. */
+export type CfTimePeriod = 'today' | 'yesterday' | 'tomorrow' | 'last7Days' | 'thisMonth' | 'lastMonth' | 'nextMonth' | 'thisWeek' | 'lastWeek' | 'nextWeek';
+/** Narrow a raw `<cfRule timePeriod>` token to a known {@link CfTimePeriod}. */
+export declare function isCfTimePeriod(value: string): value is CfTimePeriod;
+/**
+ * The named icon family an `iconSet` rule draws from, as `ST_IconSetType` enumerates it. The leading
+ * digit is the number of icons, which is also how many {@link CfValueObject} anchors the rule needs.
+ *
+ * The 2009 extension adds three more families (`3Stars`, `3Triangles`, `5Boxes`) under its own
+ * namespace. They are absent here because the classic `<iconSet>` element this list types cannot
+ * carry them; a file using one states it in the extension, which the library round-trips verbatim.
+ */
+export type IconSetType = '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters';
+/** Narrow a raw `<iconSet iconSet>` token to a known {@link IconSetType}. */
+export declare function isIconSetType(value: string): value is IconSetType;
 /**
  * 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. */
+    type: ConditionalFormattingType;
+    /** Evaluation precedence; lower wins. Excel requires one, so 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;
+    operator?: ConditionalFormattingOperator;
     /** Formula operands: cellIs bounds, an expression predicate, a containsText target formula, … */
     formulae?: (string | number)[];
     /** The literal a containsText / beginsWith / endsWith rule searches for. */
@@ -42,7 +82,7 @@ export interface ConditionalFormattingRule {
     /** 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;
+    iconSet?: IconSetType;
     /** top10 rank cutoff. */
     rank?: number;
     /** top10: the rank is a percentage rather than a count. */
@@ -56,9 +96,9 @@ export interface ConditionalFormattingRule {
     /** aboveAverage: match beyond this many standard deviations. */
     stdDev?: number;
     /** timePeriod window (`today`, `lastWeek`, …). */
-    timePeriod?: string;
+    timePeriod?: CfTimePeriod;
 }
-/** A set of rules bound to the range(s) they cover. `ref` is an OOXML `sqref` — one or more
+/** 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 {

package/dist/core/conditional-formatting.js

@@ -1,3 +1,91 @@
+const CF_VALUE_OBJECT_TYPES = {
+    num: true,
+    percent: true,
+    max: true,
+    min: true,
+    percentile: true,
+    formula: true,
+};
+export function isCfValueObjectType(value) {
+    return Object.hasOwn(CF_VALUE_OBJECT_TYPES, value);
+}
+const CONDITIONAL_FORMATTING_TYPES = {
+    expression: true,
+    cellIs: true,
+    colorScale: true,
+    dataBar: true,
+    iconSet: true,
+    top10: true,
+    uniqueValues: true,
+    duplicateValues: true,
+    containsText: true,
+    notContainsText: true,
+    beginsWith: true,
+    endsWith: true,
+    containsBlanks: true,
+    notContainsBlanks: true,
+    containsErrors: true,
+    notContainsErrors: true,
+    timePeriod: true,
+    aboveAverage: true,
+};
+export function isConditionalFormattingType(value) {
+    return Object.hasOwn(CONDITIONAL_FORMATTING_TYPES, value);
+}
+const CONDITIONAL_FORMATTING_OPERATORS = {
+    lessThan: true,
+    lessThanOrEqual: true,
+    equal: true,
+    notEqual: true,
+    greaterThanOrEqual: true,
+    greaterThan: true,
+    between: true,
+    notBetween: true,
+    containsText: true,
+    notContains: true,
+    beginsWith: true,
+    endsWith: true,
+};
+export function isConditionalFormattingOperator(value) {
+    return Object.hasOwn(CONDITIONAL_FORMATTING_OPERATORS, value);
+}
+const CF_TIME_PERIODS = {
+    today: true,
+    yesterday: true,
+    tomorrow: true,
+    last7Days: true,
+    thisMonth: true,
+    lastMonth: true,
+    nextMonth: true,
+    thisWeek: true,
+    lastWeek: true,
+    nextWeek: true,
+};
+export function isCfTimePeriod(value) {
+    return Object.hasOwn(CF_TIME_PERIODS, value);
+}
+const ICON_SET_TYPES = {
+    '3Arrows': true,
+    '3ArrowsGray': true,
+    '3Flags': true,
+    '3TrafficLights1': true,
+    '3TrafficLights2': true,
+    '3Signs': true,
+    '3Symbols': true,
+    '3Symbols2': true,
+    '4Arrows': true,
+    '4ArrowsGray': true,
+    '4RedToBlack': true,
+    '4Rating': true,
+    '4TrafficLights': true,
+    '5Arrows': true,
+    '5ArrowsGray': true,
+    '5Rating': true,
+    '5Quarters': true,
+};
+export function isIconSetType(value) {
+    return Object.hasOwn(ICON_SET_TYPES, value);
+}
 export function cloneConditionalFormatting(cf) {
     return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
 }

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

@@ -8,9 +8,14 @@ export declare class DataValidationOverlay {
      * 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
+     * (`<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.
+     *
+     * @throws {AuthoringError} when `sqref` names no area at all. A rule attached to nothing covers no
+     * cell and is written back as the same unreadable text, so it is a mistake worth surfacing at the
+     * call. The reader does not reach this: it drops such an entry at its own boundary, where a foreign
+     * file's malformed attribute is supposed to be dropped.
      */
     add(sqref: string, rule: DataValidation, options?: {
         extended?: boolean;
@@ -23,6 +28,12 @@ export declare class DataValidationOverlay {
      * validations.
      */
     at(col: number, row: number): DataValidation | undefined;
+    /**
+     * Re-anchor every rule through a row or column splice, so a dropdown stays on the cells it was
+     * attached to rather than on whatever moved into their place. A rule whose every target area fell
+     * inside a deleted span is dropped with them.
+     */
+    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
     /** Drop every validation, leaving the overlay empty. */
     clear(): void;
 }

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

@@ -1,15 +1,21 @@
+import { AuthoringError } from '../errors.js';
+import { replaceContents } from './containers.js';
 import { cloneDataValidation, } from './data-validation.js';
-import { decodeSqrefRects } from './merge.js';
+import { decodeSqrefRects, shiftSqref } from './merge.js';
 export class DataValidationOverlay {
     #entries = [];
     #rects = [];
     add(sqref, rule, options = {}) {
+        const rects = decodeSqrefRects(sqref);
+        if (rects.length === 0) {
+            throw new AuthoringError(`data validation range "${sqref}" names no cells`);
+        }
         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 });
+        this.#rects.push({ rects, rule: stored });
     }
     get entries() {
         return this.#entries;
@@ -24,6 +30,19 @@ export class DataValidationOverlay {
         }
         return undefined;
     }
+    shift(axis, start, count, delta) {
+        const entries = [];
+        const rects = [];
+        for (const entry of this.#entries) {
+            const sqref = shiftSqref(entry.sqref, axis, start, count, delta);
+            if (sqref === undefined)
+                continue;
+            entries.push({ ...entry, sqref });
+            rects.push({ rects: decodeSqrefRects(sqref), rule: entry.rule });
+        }
+        replaceContents(this.#entries, entries);
+        replaceContents(this.#rects, rects);
+    }
     clear() {
         this.#entries.length = 0;
         this.#rects.length = 0;

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

@@ -1,12 +1,19 @@
 /** 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';
+ * boolean formula; `none` constrains nothing and exists only to carry the rule's messages; the rest
+ * bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
+export type DataValidationType = 'none' | 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+/** Narrow a raw `<dataValidation type>` token to a known {@link DataValidationType}. */
+export declare function isDataValidationType(value: string): value is DataValidationType;
 /** 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';
+/** Narrow a raw `<dataValidation operator>` token to a known {@link DataValidationOperator}. */
+export declare function isDataValidationOperator(value: string): value is DataValidationOperator;
 /** 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
+/** Narrow a raw `<dataValidation errorStyle>` token to a known {@link DataValidationErrorStyle}. */
+export declare function isDataValidationErrorStyle(value: string): value is DataValidationErrorStyle;
+/** 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 {
@@ -22,9 +29,9 @@ export interface DataValidation {
     prompt?: string;
     promptTitle?: string;
 }
-/** A validation bound to the range(s) it covers. `sqref` is an OOXML `sqref` — one or more
+/** 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
+ * (`<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). */

package/dist/core/data-validation.js

@@ -1,3 +1,37 @@
+const DATA_VALIDATION_TYPES = {
+    none: true,
+    list: true,
+    whole: true,
+    decimal: true,
+    date: true,
+    time: true,
+    textLength: true,
+    custom: true,
+};
+export function isDataValidationType(value) {
+    return Object.hasOwn(DATA_VALIDATION_TYPES, value);
+}
+const DATA_VALIDATION_OPERATORS = {
+    between: true,
+    notBetween: true,
+    equal: true,
+    notEqual: true,
+    greaterThan: true,
+    lessThan: true,
+    greaterThanOrEqual: true,
+    lessThanOrEqual: true,
+};
+export function isDataValidationOperator(value) {
+    return Object.hasOwn(DATA_VALIDATION_OPERATORS, value);
+}
+const DATA_VALIDATION_ERROR_STYLES = {
+    stop: true,
+    warning: true,
+    information: true,
+};
+export function isDataValidationErrorStyle(value) {
+    return Object.hasOwn(DATA_VALIDATION_ERROR_STYLES, value);
+}
 export function cloneDataValidation(rule) {
     return {
         ...rule,

package/dist/core/date.d.ts

@@ -1,6 +1,6 @@
 /**
  * The number format applied to a `Date` cell that carries no explicit format of its own,
- * so the value renders — and reads back — as a date rather than a bare serial number.
+ * so the value renders, and reads back, as a date rather than a bare serial number.
  */
 export declare const DEFAULT_DATE_NUMFMT = "yyyy-mm-dd";
 /**
@@ -17,8 +17,8 @@ export declare function dateToSerial(date: Date): number;
 export declare function serialToDate(serial: number): Date;
 /**
  * Whether a number-format code renders its value as a date or time. A format is a date
- * format when, once its non-formatting sections are removed — bracketed color/locale/
- * condition directives, quoted literals, and escaped characters — any of the date/time
+ * format when, once its non-formatting sections are removed (bracketed color/locale/
+ * condition directives, quoted literals, and escaped characters) any of the date/time
  * placeholder letters (`y m d h s`) remain. So `"$"#,##0.00` and `0.00%` are not dates
  * while `yyyy-mm-dd`, `dd/mm/yyyy`, and `[$-409]mmmm d, yyyy` are.
  */