@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.3

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,57 @@ 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.
      *
-     * @returns An iterator that yields `ICellRange.Entry<IDataValidation.Results>` tuples for each value within the range.
+     * @param options `axis` and `reverse` set the order within each of the validation's ranges; the
+     * ranges are visited in their own order.
+     *
+     * @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 items in source order, duplicates kept; empty when this is not a list validation or
+     *          its source 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 literal list.
+     */
+    getListItemsAt(rowIndex: number, columnIndex: number): Promise<readonly IDataValidation.ListItem[]>;
     /**
      * Set whether to suppress the in-cell dropdown arrow for a list validation.
      *
@@ -59,10 +98,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 +120,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 +132,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 +150,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 +162,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 +183,11 @@ 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
+     * From the condition's selector. A list rule answers `list`, which is what an in-cell dropdown
+     * is shown for. Empty when the rule has no condition or nothing to ask for.
      */
     getRenderHints(): readonly string[];
     /**
@@ -154,12 +211,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 +260,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 +276,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 +305,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.
  */

package/types/src/externalBook/ExternalBookCollection.d.ts

@@ -1,36 +1,169 @@
+import { IRange } from '@sheetxl/primitives';
+import { AbstractCollection } from '../type';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ICellRange } from '../cellRange';
 import { IExternalBook } from './IExternalBook';
 import { IExternalBookCollection } from './IExternalBookCollection';
 /**
- * Implementation for {@link IExternalBookCollection}.
+ * A single cached snapshot of another workbook — the read-only view over one {@link IExternalBook.JSON}.
  */
-export declare class ExternalBookCollection implements IExternalBookCollection {
+declare class ExternalBook implements IExternalBook {
+    private _json;
+    private _id;
+    /** The owner, for the `[n]` projection — a book's position is the collection's fact, not its own. */
+    private _collection;
+    constructor(json: IExternalBook.JSON, id: string, collection: ExternalBookCollection);
+    getId(): string;
+    getDisplayName(sheetName?: string | null): string;
+    getSources(): readonly IExternalBook.SourceEntry[];
+    getSheetNames(): readonly string[];
+    getDefinedNames(): readonly IExternalBook.DefinedNameEntry[];
+    getSheetData(sheetIndex: number): IExternalBook.SheetData | null;
+    getDependents(): readonly IRange.Coords[];
+    delete(txOptions?: ITransaction.OperationOptions): void;
+    breakLink(txOptions?: ITransaction.OperationOptions): void;
+    refresh(): Promise<IExternalBook.RefreshResult>;
+    toJSON(): IExternalBook.JSON | null;
+    /** A copy holding a source's current contents in place of the cache; the sources stay. */
+    _withSnapshot(snapshot: IExternalBook.Snapshot): ExternalBook;
+    /** A copy with every cached sheet marked `refreshError` — the values themselves untouched. */
+    _withRefreshError(): ExternalBook;
+    /** A copy with one more sheet name — the book is immutable; the collection swaps it. */
+    _withSheetName(sheetName: string): ExternalBook;
+    readonly isIExternalBook: true;
+}
+interface State {
     /**
-     * Positional, `[n]`-indexed (`_items[0]` is `[1]`) — `null` at a position is a DDE/OLE link or
+     * Positional, `[n]`-indexed (`items[0]` is `[1]`) — `null` at a position is a DDE/OLE link or
      * otherwise unmodeled. Gaps carry meaning (the position still counts), so this is never compacted.
      */
-    private _items;
+    items: readonly (ExternalBook | null)[];
+    /**
+     * Runtime ids, parallel to {@link items} and one per POSITION — a `null` DDE/OLE slot gets one
+     * too, so a formula citing it keeps its place when a book in front of it is removed.
+     */
+    ids: readonly string[];
+}
+/**
+ * Implementation for {@link IExternalBookCollection}.
+ *
+ * @remarks
+ * The positional list lives in the transaction store rather than in fields, so `add`, `delete` and
+ * `breakLink` undo — and an undo brings a slot's id back with it, which is what heals the formulas
+ * that kept citing it (see {@link _remove}).
+ */
+export declare class ExternalBookCollection extends AbstractCollection<IExternalBook> implements IExternalBookCollection {
+    protected _transactions: ITransaction.IStore;
+    private _stateId;
+    private _transactionsRemoveListener;
+    private _getDependentsById;
+    private _getSheetRange;
+    private readonly _resolver;
     constructor(options?: ExternalBookCollection.ConstructorOptions);
-    [Symbol.iterator](): IterableIterator<IExternalBook>;
-    /** Only the modeled books — gaps (DDE/OLE) are omitted, not positional. Use {@link getByIndex} for `[n]` lookup. */
-    getItems(): IExternalBook[];
-    getCount(): number;
-    getByIndex(n: number): IExternalBook | null;
+    /**
+     * @internal
+     * The runtime id at `[n]` (1-based), including a DDE/OLE gap's, or `null` if there is no such
+     * position. `[n]` is where the SOURCE FILE stores a book — it renumbers when another is broken,
+     * and no surface a reader sees spells one — so this and its inverse are the compiler's, for
+     * parsing a typed `[7]` and for imaging an id back into canonical text. Not on
+     * {@link IExternalBookCollection}: a consumer wanting one book wants `getById`.
+     */
+    _getIdByIndex(n: number): string | null;
+    /**
+     * @internal
+     * The 1-based `[n]` a runtime id currently sits at, or `-1` — the inverse of
+     * {@link _getIdByIndex}. Linear: a workbook has a handful of books.
+     */
+    _getIndexById(id: string): number;
+    getById(id: string): IExternalBook | null;
+    /** Only the modeled books — gaps (DDE/OLE) are omitted, not positional. */
+    protected _getItems(): IExternalBook[];
+    /**
+     * @internal
+     * The book at `[n]` (1-based), or `null` where `n` is past the end or holds a DDE/OLE gap.
+     * Slot-numbered, so it is the compiler's and the tests' — not on
+     * {@link IExternalBookCollection}, where `at()` gives position among the books that exist and
+     * `toJSON()` gives the slots with their gaps.
+     */
+    _getByIndex(n: number): IExternalBook | null;
+    /** {@inheritDoc IExternalBookCollection.add} */
+    add(options: IExternalBookCollection.AddOptions, txOptions?: ITransaction.OperationOptions): IExternalBook;
+    /**
+     * @internal
+     * {@link IExternalBook.delete} — the book delegates here, where the state lives. Takes an id
+     * rather than a book so a DDE/OLE gap, which has no book object, can go too.
+     *
+     * @returns `false` if nothing was at that id.
+     */
+    _remove(id: string, txOptions?: ITransaction.OperationOptions): boolean;
+    /** @internal {@link IExternalBook.breakLink} — the book delegates here, where the state lives. */
+    _breakLink(id: string, txOptions?: ITransaction.OperationOptions): boolean;
+    /** {@inheritDoc IExternalBookCollection.breakAll} */
+    breakAll(txOptions?: ITransaction.OperationOptions): number;
+    /** {@inheritDoc IExternalBookCollection.refreshAll} */
+    refreshAll(): Promise<IExternalBook.RefreshResult[]>;
+    /**
+     * @internal
+     * {@link IExternalBook.refresh}: the resolver is asked, and its answer replaces the book's cache
+     * in one transaction — the engine rebuilds the book's grids from it on the change notification.
+     */
+    _refresh(bookId: string): Promise<IExternalBook.RefreshResult>;
+    /** Excel's record of a refresh that could not complete: `refreshError` on each cached sheet. */
+    protected _markRefreshError(bookId: string): void;
+    /**
+     * The value pass in front of a removal: every cell block that cites the book becomes its current
+     * values — the WHOLE formula, as Excel does, not only the external operand.
+     *
+     * @remarks
+     * A dependent that is a NAME (its scope is the name's virtual grid, not a sheet) is left as it
+     * is. Its citation then images as `#REF!` once the slot goes, which is one of the three outcomes
+     * DESIGN-EXTERNAL-LINKS §6 item 8 lists for Excel; the measurement that picks between them has
+     * not been taken, and a name has no computed value to write back until phase D in any case.
+     */
+    protected _breakDependents(book: IExternalBook): void;
+    /** @internal Backs {@link IExternalBook.getDependents}; empty without an engine to ask. */
+    _getDependents(bookId: string): readonly IRange.Coords[];
+    /**
+     * @internal
+     * Records a sheet name a formula cited on a book that did not list it — the authoring half of
+     * the bind rule (DESIGN-EXTERNAL-LINKS §5 step 13). Returns the sheet's index in the book.
+     */
+    _addSheetName(bookId: string, sheetName: string): number;
     toJSON(): (IExternalBook.JSON | null)[] | null;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IExternalBookCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    close(): void;
+    protected _assertWritable(): void;
+    protected _getState(): State;
+    protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    protected _updateState(state: (prevState: State) => State, options: ITransaction.OperationOptions): void;
     readonly isIExternalBookCollection: true;
 }
 export declare namespace ExternalBookCollection {
     interface ConstructorOptions {
         /**
          * Books to hydrate at construction, in `IWorkbook.JSON.externalBooks` order — which IS `[n]`
-         * order (1-based). A `null` entry is a preserved gap (see {@link IExternalBookCollection.getByIndex}).
+         * order (1-based). A `null` entry is a preserved gap.
          *
          * @remarks
          * Taken here rather than through a separate `fromJSON()` call — mirrors
          * `NamedFormulaCollection`'s reasoning: this collection owns the items, so hydrating at
-         * construction avoids a pre-load lifecycle state. Unlike named formulas, nothing here is
-         * mutable yet, so there is no transactional persist scope to speak of either.
+         * construction avoids a pre-load lifecycle state.
          */
         json?: (IExternalBook.JSON | null)[];
+        /** Shared with the workbook so `add`/`delete`/`breakLink` undo with everything else. */
+        transactions?: ITransaction.IStore;
+        /** The engine's citation index — backs {@link IExternalBook.getDependents}. */
+        getDependents?: (bookId: string) => readonly IRange.Coords[];
+        /** Opens a source on refresh — `ICellContainerOptions.externalBookResolver`, for the collection's life. */
+        resolver?: IExternalBook.IResolver | null;
+        /**
+         * A range over a dependent's coords, whose `scope` is a sheet's stable id — or `null` for a
+         * scope that is not a sheet (a name's virtual grid). Backs the value pass of `breakLink`.
+         */
+        getSheetRange?: (coords: IRange.Coords) => ICellRange | null;
     }
 }
+export {};
 //# sourceMappingURL=ExternalBookCollection.d.ts.map