@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/conditionalFormat/IConditionalFormatCollection.d.ts

@@ -27,6 +27,8 @@ export interface IConditionalFormatCollection extends ICollection<IConditionalFo
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IConditionalFormat): IConditionalFormat;
+    /** For runtime type checking. */
+    readonly isIConditionalFormatCollection: true;
 }
 /**
  * {@inheritDoc IConditionalFormatCollection}

package/types/src/dataValidation/DataValidation.d.ts

@@ -1,14 +1,18 @@
+import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
 import { ReferenceableClipboard } from '@sheetxl/utils';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IGrid } from '../collections';
 import { ICellRange } from '../cellRange';
+import { ICondition } from '../condition';
+import { ListSourceFormula } from '../condition/_ConditionFormula';
+import { BlankResolver } from '../condition/_ConditionUtils';
 import { AnchoredConditional } from '../condition/AnchoredConditional';
 import { IDataValidation } from './IDataValidation';
 /**
  * Implementation of {@link IDataValidation}.
  */
-export declare class DataValidation extends AnchoredConditional<State, CommitView, IDataValidation.Events> implements IDataValidation {
+export declare class DataValidation extends AnchoredConditional<State, IDataValidation.Events> implements IDataValidation {
     /**
      * Cache of failing cells for quick reads in {@link getAlertAt} — a plain field, NOT transactional
      * state, mirroring ConditionalFormat's `_matches`.
@@ -20,6 +24,21 @@ export declare class DataValidation extends AnchoredConditional<State, CommitVie
      * commit onto the undo stack for a change no user made.
      */
     protected _results: IGrid<boolean> | null;
+    /**
+     * How the EMPTY cells answer, one reader per anchored area, or `null` when every blank passes
+     * (Ignore blank on, or no condition). Swapped with {@link _results}, never materialized into it:
+     * a whole-column rule is one entry here, not a million there.
+     */
+    protected _blankAreas: BlankArea[] | null;
+    /**
+     * Whether the rule's answer for a blank can differ by position (it reads a formula). When it
+     * cannot, one question per area answers every blank in it.
+     */
+    protected _blankPerCell: boolean;
+    /** {@link _blankAreas} split into disjoint pieces, built on the first count or entries read. */
+    protected _blankPieces: BlankPiece[] | null;
+    /** {@link getAlertCount}'s answer for the current results, or `null` until asked. */
+    protected _alertCount: number | null;
     /**
      * Which evaluation round is current. Bumped once per {@link _processValueUpdates}; a round
      * writes its results only if it is still the newest when it finishes. Same shape and reason as
@@ -34,12 +53,50 @@ export declare class DataValidation extends AnchoredConditional<State, CommitVie
     protected _getDefaultState(options: DataValidation.ConstructorOptions): Readonly<State>;
     /** @internal */
     protected _processValueUpdates(_range?: ICellRange | null): void;
+    /** Swaps in one evaluation's answers; everything derived from the previous ones goes with them. */
+    protected _setResults(results: IGrid<boolean> | null, blankAreas: BlankArea[] | null, blankPerCell?: boolean): void;
+    /** Whether an EMPTY cell of `areas` fails. Every area covering the cell has a say, as for values. */
+    protected _isBlankFailing(areas: readonly BlankArea[], rowIndex: number, columnIndex: number): boolean;
+    /** One area's answer for a blank. A rule reading no formula answers once for the whole area. */
+    protected _isBlankPassing(blankArea: BlankArea, rowIndex: number, columnIndex: number): boolean;
+    /**
+     * The blank areas as disjoint pieces, each knowing every area that covers it — so an overlap is
+     * counted once and still answered by all of its rules. Disjoint areas are their own pieces.
+     */
+    protected _getBlankPieces(): BlankPiece[];
+    /** How many cells of `coords` hold a value — off the value grid's runs, never its cells. */
+    protected _countValues(coords: IRange.Coords): number;
     /** {@inheritDoc IDataValidation.getAlertAt} */
     getAlertAt(rowIndex: number, columnIndex: number): boolean;
     /** {@inheritDoc IDataValidation.getAlertEntries} */
     getAlertEntries(options?: ICellRange.IteratorOptions): IGrid.EntryIterator<boolean>;
+    /**
+     * Each piece in axis order: its stored results and its blanks, merged as the caller reads. A
+     * piece whose blanks pass is read off the results grid alone; one whose blanks fail walks its
+     * values, yielding the gaps between them without asking; one read per cell asks per gap cell.
+     */
+    protected _pieceEntries(pieces: readonly BlankPiece[], results: IGrid<boolean> | null, axis: IRange.Axis, reverse: boolean): Generator<IGrid.Entry<boolean>, undefined, undefined>;
     /** {@inheritDoc IDataValidation.getAlertCount} */
     getAlertCount(): number;
+    /** {@inheritDoc IDataValidation.getListItemsAt} */
+    getListItemsAt(rowIndex: number, columnIndex: number): Promise<readonly IDataValidation.ListItem[]>;
+    /**
+     * Appends what a live base lists at a cell to `listed`: its values, duplicates kept. Returns
+     * whether the base holds a blank (an empty cell or a `""` result), which is listed by the caller.
+     */
+    protected _listSourceItemsAt(condition: ICondition, source: ListSourceFormula, rowIndex: number, columnIndex: number, listed: IDataValidation.ListItem[]): Promise<boolean>;
+    /** {@inheritDoc IDataValidation.validateInputAt} */
+    validateInputAt(input: string | Scalar, rowIndex: number, columnIndex: number): Promise<boolean>;
+    /**
+     * The value an entry would leave in a cell: text read as typed text is, a formula evaluated at
+     * the cell. `null` for a blank entry.
+     */
+    protected _resolveEntryAt(input: string | Scalar, cell: IRange.CellCoords): Promise<Scalar>;
+    /**
+     * A list source's check for one entry: `MATCH` against the source as filled to the cell, the
+     * same check the rule watches per cell (P6), answered as a one-cell range at `cell`.
+     */
+    protected _checkListEntryAt(source: ListSourceFormula, value: Scalar, cell: IRange.CellCoords, runtime: IRuntime): Promise<IRange | null>;
     /** {@inheritDoc IDataValidation.setHideDropdown} */
     setHideDropdown(hide: boolean, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc IDataValidation.isHideDropdown} */
@@ -114,8 +171,17 @@ interface State extends AnchoredConditional.State {
     /** Opaque third-party payload. Carried, never interpreted. */
     ext: Record<string, unknown> | null;
 }
-/** @internal */
-interface CommitView extends AnchoredConditional.CommitView {
+/** One anchored area's reader for its empty cells. */
+interface BlankArea {
+    area: IRange.Coords;
+    resolve: BlankResolver;
+    /** The area's one answer when it cannot vary by position; `null` until asked. */
+    passes: boolean | null;
+}
+/** A disjoint piece of the blank areas, with every area that covers all of it. */
+interface BlankPiece {
+    coords: IRange.Coords;
+    areas: readonly BlankArea[];
 }
 export {};
 //# sourceMappingURL=DataValidation.d.ts.map

package/types/src/dataValidation/DataValidationCollection.d.ts

@@ -1,20 +1,31 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IDataValidationCollection } from './IDataValidationCollection';
 import { IDataValidation } from './IDataValidation';
-export declare class DataValidationCollection implements IDataValidationCollection {
+/**
+ * Implementation for {@link IDataValidationCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own data-validation state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onDataValidationsChange`, forwarded with this collection as the source.
+ */
+export declare class DataValidationCollection extends AbstractCollection<IDataValidation, IDataValidationCollection.GetItemsOptions> implements IDataValidationCollection {
     private _add;
     private _get;
     private _createItem;
-    constructor(add: (address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions) => IDataValidation, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IDataValidation[], createItem: (template?: IDataValidation | null) => IDataValidation);
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions) => IDataValidation, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IDataValidation[], createItem: (template?: IDataValidation | null) => IDataValidation, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@inheritDoc IDataValidationCollection.add} */
     add(address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions): IDataValidation;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IDataValidation>;
-    /** {@inheritDoc IDataValidationCollection.getItems} */
-    getItems(options?: IDataValidationCollection.GetItemsOptions): IDataValidation[];
-    /** {@inheritDoc IDataValidationCollection.getCount} */
-    getCount(): number;
-    /** {@inheritDoc IDataValidationCollection.getCount} */
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IDataValidationCollection.GetItemsOptions): IDataValidation[];
+    /** {@inheritDoc IDataValidationCollection.createItem} */
     createItem(template?: IDataValidation | null): IDataValidation;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IDataValidationCollection.isIDataValidationCollection} */
+    get isIDataValidationCollection(): true;
 }
 //# sourceMappingURL=DataValidationCollection.d.ts.map

package/types/src/dataValidation/IDataValidation.d.ts

@@ -1,4 +1,4 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { ReferenceableClipboard } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { IHistory } from '../history';
@@ -9,10 +9,19 @@ import { ICondition } from '../condition';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { IDataValidationCollection } from './IDataValidationCollection';
 /**
- * Represents a data validation range.
+ * A data validation: a rule that a cell's value must satisfy, over one or more ranges of a sheet,
+ * with the prompt shown when the cell is selected and the alert for a value that fails.
  *
  * @remarks
- * Used for modifying the type and rules of a data validation entry.
+ * Validations may overlap, and every one covering a cell applies: the cell is valid only when each
+ * of them accepts its value. Where a single answer is needed, the rule with the lowest
+ * {@link getIndex} wins: the prompt is the first covering rule's that has one, the alert the first
+ * failing rule's, and the dropdown offers the items every covering list rule accepts. Excel keeps
+ * one validation per cell, and when it opens a file whose validations overlap it honors only the
+ * first; see {@link ICell.getDataValidation}.
+ *
+ * The rule judges the value a cell holds, whatever wrote it. A value set through the API, pasted
+ * or filled is never refused; it is simply invalid, and {@link getAlertAt} says so.
  */
 export interface IDataValidation extends IAnchored, ICondition.Stateful {
     /** @inheritdoc ICondition.Stateful.getCondition */
@@ -22,27 +31,83 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     setCondition(condition: ICondition.Input | null, options?: ITransaction.OperationOptions): this;
     /**
-     * Creates a default condition for the data validation based on its range and the data.
-     */
-    createDefaultCondition(): ICondition;
-    /**
-     * Returns the validation results at the specified cell coordinates.
+     * Whether the cell at the specified coordinates fails this validation.
+     *
+     * @param rowIndex The sheet row.
+     * @param columnIndex The sheet column.
      *
      * @remarks
-     * If there are multiple validations this will return the first one to fail.
+     * This validation's answer alone. Where validations overlap, a cell is invalid when any of the
+     * ones covering it fails ({@link ICellRange.getDataValidations}).
+     *
+     * An empty cell fails when Ignore blank is off ({@link isIncludeBlanks} is `false`) and the rule
+     * rejects a blank there, as Excel's Circle Invalid Data circles it. With Ignore blank on, an
+     * empty cell never fails. A cell holding `""` (a formula's empty text) is a value, and is judged.
      */
     getAlertAt(rowIndex: number, columnIndex: number): boolean;
     /**
-     * Returns an iterator that allows you to iterate over the individual alert entries within the range,
-     * yielding pairs of `IteratorContext` and a `Value`.
+     * The cells that fail this validation, each as a `[coords, true]` entry, empty cells included.
+     *
+     * @param options `axis` and `reverse` set the order within each of the validation's ranges; the
+     * ranges are visited in their own order.
      *
-     * @returns An iterator that yields `ICellRange.Entry<IDataValidation.Results>` tuples for each value within the range.
+     * @remarks
+     * Lazy: the cost is what the caller reads. Stop early to pay for the first few entries only. When
+     * empty cells pass (Ignore blank on), they are skipped without being visited. When they fail, a
+     * whole-column rule yields every one of its empty cells, so take what you need.
      */
     getAlertEntries(options?: ICellRange.IteratorOptions): IGrid.EntryIterator<boolean>;
     /**
-     * Returns the count of alert entries within the range.
+     * The number of cells that fail this validation, empty cells included.
+     *
+     * @remarks
+     * A rule that judges every empty cell alike (no formula) counts them without visiting any. A rule
+     * with a formula, a custom formula or a range list source, reads each empty cell's answer, so
+     * the first call over a large range can be slow. The answer is kept until the values change.
      */
     getAlertCount(): number;
+    /**
+     * The items a list validation offers at a cell: what its in-cell dropdown lists.
+     *
+     * @param rowIndex The cell's row.
+     * @param columnIndex The cell's column. A relative source (`$F1:$G1`, `INDIRECT($E1)`) gives each
+     *                    cell its own list, as it does in Excel.
+     *
+     * @returns The set's members: its `items`, then what its `source` lists in source order,
+     *          duplicates kept, then its typed `additions`, with any `subtractions` left out. Empty
+     *          when this is not a list validation or the set lists nothing. Blank source cells are
+     *          not listed.
+     *
+     * @remarks
+     * Evaluated when asked, for one cell — the check itself does not need the items, so nothing is
+     * resolved until a dropdown or a preview asks. `text` is what a source cell shows (a date list
+     * reads as dates), the item itself for a typed one.
+     */
+    getListItemsAt(rowIndex: number, columnIndex: number): Promise<readonly IDataValidation.ListItem[]>;
+    /**
+     * Whether an entry would pass this validation if it were typed into a cell: the check a cell
+     * editor makes before it writes.
+     *
+     * @param input What would be written, as `setValue` takes it. Text is read as typed text is: a
+     *              number, a date or a boolean when it reads as one, a formula when it starts with
+     *              `=`. Any other value is taken as is.
+     * @param rowIndex The cell's row.
+     * @param columnIndex The cell's column.
+     *
+     * @returns `false` when the entry fails. `true` when it passes, when the cell is outside this
+     *          validation, or when the validation has no condition.
+     *
+     * @remarks
+     * Nothing is written. A formula is judged by its result at that cell (`=9` fails a whole number
+     * between 1 and 5). A blank entry passes whatever {@link isIncludeBlanks} says, as typed entry does
+     * in Excel. Everything else is read as it stands, so a rule that reads the cell itself
+     * (`=COUNTIF($A:$A,A1)=1`) sees the value the cell holds now, not the entry — as Excel does.
+     *
+     * This validation's answer alone, whatever {@link isShowAlertMessage} says: the caller decides
+     * which validations to ask and what to show. Excel asks the active cell's rule only, and only for
+     * what is typed or picked; a value set through the API, pasted or filled is never checked.
+     */
+    validateInputAt(input: string | Scalar, rowIndex: number, columnIndex: number): Promise<boolean>;
     /**
      * Set whether to suppress the in-cell dropdown arrow for a list validation.
      *
@@ -59,10 +124,11 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     isHideDropdown(): boolean;
     /**
-     * Message for a user prompt.
+     * The message shown while a cell the rule covers is selected (Excel's *Input Message*).
      *
      * @remarks
-     * This may be a tooltip or other indicator depending on the client.
+     * Shown only while {@link isShowPromptMessage} is on. Where validations overlap, the first
+     * covering rule with a prompt shows its own.
      */
     setPromptMessage(message: string, options?: ITransaction.OperationOptions): this;
     /**
@@ -80,7 +146,11 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     getPromptTitle(): string;
     /**
-     * Sets whether to show the prompt message when the cell is selected.
+     * Sets whether to show the prompt when a cell the rule covers is selected.
+     *
+     * @remarks
+     * Separate from the prompt's text, as in Excel: turning the prompt off keeps its title and
+     * message, and turning it back on shows them again.
      */
     setShowPromptMessage(show: boolean, options?: ITransaction.OperationOptions): this;
     /**
@@ -88,7 +158,7 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     isShowPromptMessage(): boolean;
     /**
-     * Message text of the alert.
+     * The message of the alert raised for a value that fails the rule (Excel's *Error Message*).
      */
     setAlertMessage(message: string, options?: ITransaction.OperationOptions): this;
     /**
@@ -106,7 +176,11 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     getAlertTitle(): string;
     /**
-     * Sets whether to show the alert message when the cell is selected.
+     * Sets whether a value that fails the rule raises the alert when a user enters it.
+     *
+     * @remarks
+     * With the alert off, a failing entry is accepted silently, whatever the {@link getAlertStyle}.
+     * It is still invalid: {@link getAlertAt} reports it either way.
      */
     setShowAlertMessage(show: boolean, options?: ITransaction.OperationOptions): this;
     /**
@@ -114,12 +188,20 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     isShowAlertMessage(): boolean;
     /**
-     * Sets the style of the alert shown when validation fails.
+     * Sets the style of the alert raised when a user enters a value that fails the rule.
      *
      * @remarks
-     * This controls whether alert values are blocked (`Stop`),
-     * allowed with a warning (`Warning`), or allowed with an informational
-     * message (`Information`).
+     * `Stop` refuses the entry, `Warning` asks before accepting it, and `Information` accepts it with
+     * a message. Where validations overlap, the first failing rule's style is the one used.
+     *
+     * The alert answers what a user types or picks, as in Excel. A value written through the API,
+     * pasted or filled raises no alert and is never refused.
+     *
+     * The style applies only while {@link setShowAlertMessage} is on. With it off, an invalid entry
+     * is accepted without a word whatever the style, as in Excel, so a rule meant to refuse entry
+     * needs both.
+     *
+     * @defaultValue `Stop`
      */
     setAlertStyle(alertStyle: IDataValidation.AlertStyle, options?: ITransaction.OperationOptions): this;
     /**
@@ -127,10 +209,15 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     getAlertStyle(): IDataValidation.AlertStyle;
     /**
-     * If the cell has custom rendering.
+     * How a cell the rule covers asks to be drawn and edited, as keywords a client may honor.
      *
      * @remarks
-     * This could be a list or a checkbox or a custom editor
+     * Derived from the condition, never stored on it: a rule whose param carries candidates (its
+     * operator {@link ICondition.IOperator.getCandidates | lists them}, as `inSet` does under any
+     * selector) answers `list`, which is what an in-cell dropdown is shown for; a rule under a date selector
+     * answers `date` and `calendar`, under the time selector `time` and `clock`. Whether the
+     * dropdown is actually shown is the rule's own {@link isHideDropdown}. Empty when the rule has
+     * no condition or nothing to ask for.
      */
     getRenderHints(): readonly string[];
     /**
@@ -154,12 +241,16 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     update(update: Partial<IDataValidation.Properties> | IDataValidation, options?: ITransaction.OperationOptions): this;
     /**
-     * Returns the index of this data validation within its container.
+     * Returns the index of this data validation within its container: its priority, `0` first.
+     *
+     * @remarks
+     * Where validations overlap, the lowest index supplies the prompt and the alert style; see
+     * {@link IDataValidation}. The writer saves the rules in this order.
      */
     getIndex(): number;
     /**
      * Sets the index of this data validation within its container.
-     * @param index The new index to set.
+     * @param index The new index to set. See {@link getIndex}.
      */
     setIndex(index: number): this;
     /**
@@ -199,7 +290,7 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
     readonly isIDataValidation: true;
 }
 /**
- * Capabilities for working with conditional styling ranges.
+ * Types for working with data validations.
  *
  * @see
  * ### **Interface**
@@ -215,19 +306,28 @@ export declare namespace IDataValidation {
      */
     const AlertStyle: {
         /**
-         * Stops the user from entering alert data.
+         * Refuses an invalid entry.
          */
         readonly Stop: "stop";
         /**
-         * Shows a warning message when the user enters alert data.
+         * Warns about an invalid entry and asks whether to keep it.
          */
         readonly Warning: "warning";
         /**
-         * Shows an information message when the user enters alert data.
+         * Accepts an invalid entry with an informational message.
          */
         readonly Information: "information";
     };
     type AlertStyle = typeof AlertStyle[keyof typeof AlertStyle];
+    /**
+     * One item a list validation offers. See {@link IDataValidation.getListItemsAt}.
+     */
+    interface ListItem {
+        /** The value a pick enters. */
+        value: Scalar;
+        /** The item as shown. */
+        text: string;
+    }
     /**
      * A set of values that can be set on a IDataValidation.
      *
@@ -235,12 +335,31 @@ export declare namespace IDataValidation {
      * {@link IDataValidation}
      */
     interface Properties {
+        /** See {@link IDataValidation.setPromptMessage}. */
         prompt?: string;
+        /** See {@link IDataValidation.setPromptTitle}. */
         promptTitle?: string;
+        /**
+         * See {@link IDataValidation.setShowPromptMessage}.
+         *
+         * @defaultValue false
+         */
         showPromptMessage?: boolean;
+        /** See {@link IDataValidation.setAlertMessage}. */
         alert?: string;
+        /** See {@link IDataValidation.setAlertTitle}. */
         alertTitle?: string;
+        /**
+         * See {@link IDataValidation.setShowAlertMessage}.
+         *
+         * @defaultValue false
+         */
         showAlertMessage?: boolean;
+        /**
+         * See {@link IDataValidation.setAlertStyle}.
+         *
+         * @defaultValue `Stop`
+         */
         alertStyle?: IDataValidation.AlertStyle;
         /**
          * The predicate a value must satisfy to be valid.

package/types/src/dataValidation/IDataValidationCollection.d.ts

@@ -7,7 +7,8 @@ import { IDataValidation } from './IDataValidation';
  */
 export interface IDataValidationCollection extends ICollection<IDataValidation> {
     /**
-     * Returns items that match the filter criteria.
+     * Returns items that match the filter criteria, in priority order
+     * ({@link IDataValidation.getIndex}).
      *
      * If no filter criteria is provided, all items will be returned.
      *
@@ -18,7 +19,12 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
      * Add an `IDataValidation` to the container.
      *
      * @param address The address of the item. May name several discontiguous ranges.
-     * @param options Additional options available when adding a table or a `boolean` that indicates if the table has headers.
+     * @param options The new validation's properties, and where it goes in priority order.
+     *
+     * @remarks
+     * A validation already covering some of the cells keeps them, and both apply there (see
+     * {@link IDataValidation}); Excel's dialog would replace it. To take cells away from an existing
+     * validation, clear them first with `ICellRange.clear(ICell.Content.DataValidations)`.
      */
     add(address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions): IDataValidation;
     /**
@@ -27,6 +33,8 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IDataValidation): IDataValidation;
+    /** For runtime type checking. */
+    readonly isIDataValidationCollection: true;
 }
 /**
  * {@inheritDoc IDataValidationCollection}

package/types/src/date/DateUtils.d.ts

@@ -1,3 +1,23 @@
+/**
+ * The unit a date step counts — what makes one date series a different series from another.
+ *
+ * @remarks
+ * `Weekday` is a BUSINESS day: Saturday and Sunday are not units of it, so `Fri` plus one weekday
+ * is the following Monday.
+ *
+ * @see {@link IAutoFill.DateSeries}, which reports the unit a template turns out to hold.
+ */
+export declare const DateUnit: {
+    /** A calendar day. */
+    readonly Day: "d";
+    /** A business day — Saturday and Sunday are skipped. */
+    readonly Weekday: "wd";
+    /** A calendar month, the day-of-month carried across it. */
+    readonly Month: "m";
+    /** A calendar year. */
+    readonly Year: "y";
+};
+export type DateUnit = typeof DateUnit[keyof typeof DateUnit];
 /**
  * Returns Date.now() rounded to a nearest time.
  *

package/types/src/date/_DateUtils.d.ts

@@ -1,5 +1,6 @@
 import { NumberFormatRef } from '../numFmt/BuiltInFormats';
 import { IRuntime } from '@sheetxl/primitives';
+import { DateUnit } from './DateUtils';
 export declare const MAX_SERIAL_DATE = 2958465;
 export declare function isValidDate(d: any, jsDateOnly?: boolean): boolean;
 export declare function minutesSinceMidnight(date: Date): number;
@@ -7,12 +8,82 @@ export declare function dayDiff(d1: Date, d2: Date): number;
 export declare function monthDiff(startDate: Date, endDate: Date): number;
 export declare function yearDiff(d1: Date, d2: Date): number;
 export declare function dateUnitDiff(d1: Date, d2: Date, unit: DateUnit | string): number | undefined;
-export declare const DateUnit: {
-    readonly Day: "d";
-    readonly Month: "m";
-    readonly Year: "y";
-};
-export type DateUnit = typeof DateUnit[keyof typeof DateUnit];
+/**
+ * Days in a 1-based `month` — the real calendar. Excel's phantom `1900-02-29` is not modelled here;
+ * `serialFromCivil` carries it in serial space, which is where it matters.
+ */
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * The month a serial falls in, as a single ordinal, so a whole-month delta is plain subtraction.
+ * `NaN` for a serial outside the calendar.
+ */
+export declare function serialMonthOrdinal(serial: number, date1904?: boolean): number;
+/** The day-of-month a serial falls on, or `NaN` for a serial outside the calendar. */
+export declare function serialDayOfMonth(serial: number, date1904?: boolean): number;
+/** `true` when the serial falls on the last day of its own month. */
+export declare function serialIsMonthEnd(serial: number, date1904?: boolean): boolean;
+/**
+ * Step `count` whole months in SERIAL space — no `Date` is constructed. The day-of-month is kept
+ * where the target month is long enough and clamped where it is not (Excel's `EDATE`: Jan 31 plus
+ * one month is Feb 28), and because every step is measured from the same anchor serial a day
+ * clamped through a short month recovers afterwards (Dec 29 → Feb 28 → Mar 29).
+ *
+ * @param monthEnd Land on the target month's LAST day instead — Excel's end-of-month series, where
+ * Feb 28 continues Mar 31, Apr 30 rather than Mar 28, Apr 28.
+ *
+ * @remarks
+ * The time-of-day fraction rides along untouched.
+ */
+export declare function addMonthsToSerial(serial: number, count: number, monthEnd?: boolean, date1904?: boolean): number;
+/**
+ * `true` when the serial falls on a Saturday or a Sunday.
+ *
+ * @remarks
+ * A weekend serial has no business day of its own, so this is what a caller checks before reading
+ * {@link serialWeekdayOrdinal} as a position: the ordinal rounds a weekend forward to the following
+ * Monday, which is right for stepping and wrong for deciding whether a template is a weekday series.
+ */
+export declare function serialIsWeekend(serial: number, date1904?: boolean): boolean;
+/**
+ * A serial's position in the run of BUSINESS days, so a difference of two of these is a count of
+ * weekdays — `Fri` to the following `Mon` is `1`, not `3`.
+ *
+ * @remarks
+ * A weekend serial has no business day of its own and takes the following Monday's, which makes
+ * this monotonic but not injective: `Sat`, `Sun` and `Mon` all report the same ordinal, so a
+ * template of weekend dates reads as a step of zero rather than as a series.
+ */
+export declare function serialWeekdayOrdinal(serial: number, date1904?: boolean): number;
+/**
+ * Step `count` BUSINESS days in SERIAL space — Saturday and Sunday are skipped, and no `Date` is
+ * constructed. The time-of-day fraction rides along untouched.
+ *
+ * @remarks
+ * A weekend anchor is not a business day, so it steps off in the direction of travel first: a
+ * Saturday going forward is one step from Monday (Excel's `Fri + 1` and `Sat + 1` are both Monday),
+ * and going back is one step from Friday. A `count` of zero simply lands on the next business day,
+ * which is what Excel's weekday series does from a weekend.
+ */
+export declare function addWeekdaysToSerial(serial: number, count: number, date1904?: boolean): number;
+/** The number of days in `month` (0-based) of `year` — JS day `0` is the previous month's last. */
+export declare function lastDayOfMonth(year: number, month: number): number;
+/** `true` when `date` falls on the last day of its own month. */
+export declare function isMonthEnd(date: Date): boolean;
+/** A date's month as a single ordinal, so a whole-month delta is plain subtraction. */
+export declare function monthOrdinal(date: Date): number;
+/**
+ * Step `count` whole months from `date`, keeping the day-of-month where the target month is long
+ * enough and clamping it where it is not — Excel's `EDATE`: Jan 31 plus one month is Feb 28, NOT
+ * March 3. Because every step is measured from the same anchor, a day clamped through a short month
+ * recovers afterwards (Dec 29 → Feb 28 → Mar 29).
+ *
+ * @param monthEnd Land on the target month's LAST day instead of the anchor's day — Excel's
+ * end-of-month series, where Feb 28 continues Mar 31, Apr 30 rather than Mar 28, Apr 28.
+ *
+ * @remarks
+ * Time-of-day is carried through untouched.
+ */
+export declare function addMonthsClamped(date: Date, count: number, monthEnd?: boolean): Date;
 export declare function addDateUnit(date: Date, count: number, unit: DateUnit | string): Date | null;
 export declare function stringToLocalDate(value: string): Date | null;
 export declare function isISODateString(value: string): boolean;
@@ -46,6 +117,19 @@ export interface ParsedDateTime {
 /**
  * Splits a serial date into its calendar and clock fields.
  *
+ * @remarks
+ * Excel resolves a serial to whole seconds by adding HALF A SECOND TO THE SERIAL and then
+ * truncating — not by rounding the seconds themselves. The distinction is measurable, because
+ * the addition happens at the serial's magnitude, where a day is ~3e-7 s wide in the last bit:
+ * 12:30:30.5 comes back as :30 (the half second is lost in the sum) while 23:59:59.5 comes back
+ * as the next day's midnight. So a serial within half a second of midnight belongs to the NEXT
+ * day, in every field at once — `DAY`, `MONTH`, `YEAR` and `WEEKDAY` move together with the
+ * clock.
+ *
+ * Not every date function reads its argument through this. `WEEKNUM`, `ISOWEEKNUM`, `DAYS`,
+ * `EDATE`, `EOMONTH`, `WORKDAY` and `NETWORKDAYS` TRUNCATE the same serial instead, and each
+ * floors before it gets here — a per-function fact, not a rule with exceptions.
+ *
  * @param reuseParts Avoids allocating a fresh `ParsedDateTime`:
  * - An object: the fields are written into THIS object, which is returned. The caller owns the
  *   buffer's lifetime — do not hold onto a previous result across a reused call, each call
@@ -60,7 +144,7 @@ export declare function parseSerialDate(serialDate: number, date1904?: boolean,
  * Serial date from parsed date/time fields.
  *
  * Computed directly from the fields (see {@link serialFromFields}) rather than
- * by building a JS `Date` and converting it — that round trip was both lossy
+ * by building a JS `Date` and converting it — that round trip is both lossy
  * (~1e-12, catastrophic for bare times) and unable to express Excel's phantom
  * `1900-02-29`, which a `Date` normalizes away.
  */