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

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

@@ -0,0 +1,96 @@
+import { IExternalBook } from './IExternalBook';
+/**
+ * The two halves of a scope that names an external book: how the book was written, and the sheet
+ * (if any) after it.
+ *
+ * @remarks
+ * `[1]Sheet1` -> `{ book: '1', positional: true, sheetName: 'Sheet1' }`
+ * `[1]`       -> `{ book: '1', positional: true, sheetName: null }` — the `[1]!Name` form
+ * `[Budget.xlsx]Sheet1`        -> `{ book: 'Budget.xlsx', positional: false, ... }`
+ * `C:\d\[Budget.xlsx]Sheet1`   -> `{ book: 'Budget.xlsx', dir: 'C:\d\', positional: false, ... }`
+ */
+export interface ExternalScopeParts {
+    /** The text inside the brackets — a position (`1`) or a file name (`Budget.xlsx`). */
+    book: string;
+    /** Whether {@link book} is a `[n]` position rather than a file name. */
+    positional: boolean;
+    /** Anything before the `[`, kept verbatim — a directory or URL prefix, `''` when there is none. */
+    dir: string;
+    /** The sheet after the `]`, or `null` for the book-scoped `[1]!Name` form. */
+    sheetName: string | null;
+}
+/**
+ * Splits a sheet scope that carries an external book prefix, or `null` if it carries none.
+ *
+ * @remarks
+ * Quotes are the caller's problem: the scope reaching here has already been unquoted by the parser
+ * (`'[1]P3.1'!` and `[1]P3.1!` both arrive as `[1]P3.1`), which is the whole reason a book and its
+ * sheet are ONE symbol rather than two.
+ */
+export declare function parseExternalScope(scope: string): ExternalScopeParts | null;
+/**
+ * The name Excel writes INSIDE the brackets — `Budget.xlsx` in `[Budget.xlsx]Sheet1`: the last
+ * segment of the book's first source, URL-decoded.
+ *
+ * @remarks
+ * A free function rather than a member of {@link IExternalBook}, deliberately. It is a projection of
+ * `getSources()`, and "the file's name" is already `IWorkbookIO.Origin`'s vocabulary, where
+ * `getName()` is the name WITHOUT its extension and `getExtension()` is separate. A second,
+ * conflicting spelling of that noun on a neighbouring interface is how the two get confused.
+ *
+ * The `book` role entry is the path the source is opened from and is sorted first by the reader, so
+ * the first entry is the one to read. An `xlPathMissing` target is a bare name rather than a URI and
+ * has no separator to split on, which this handles by finding none.
+ */
+export declare function externalBookFileName(book: IExternalBook): string;
+/**
+ * Excel's source-CLOSED spelling of a scope into this book: `C:\dir\[Book.xlsx]Sheet1`, unquoted.
+ *
+ * @remarks
+ * This is the form Excel's own formula bar shows for a book it cannot see, which is the state every
+ * book is in until a resolver opens one (DESIGN-EXTERNAL-LINKS §4B). The caller quotes it —
+ * `sheetNameToString` does, since a path carries separators no sheet name may.
+ *
+ * The directory is the first source that carries one: a book Excel recorded by a RELATIVE path
+ * (`NamesSource.xlsx`, a sibling of the host) keeps its absolute location in the xxl21
+ * `alternateUrls` companion, and Excel's formula bar shows that location, not the bare name — a
+ * bare name is the OPEN spelling ({@link externalBookOpenName}).
+ *
+ * @param sheetName Omitted for the book-scoped `[1]!Name` form, which shows as `C:\dir\[Book.xlsx]`.
+ */
+export declare function externalBookClosedName(book: IExternalBook, sheetName?: string | null): string;
+/**
+ * The relationship type a book's own part records for the path it is opened from — what
+ * {@link sourceEntryFromPath} writes, and what the xlsx reader finds on nearly every book.
+ */
+export declare const EXTERNAL_LINK_PATH_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLinkPath";
+/**
+ * The source entry Excel would record for a path a user typed — the inverse of
+ * {@link externalBookClosedName}'s directory half, so a minted book displays back as it was typed.
+ *
+ * @remarks
+ * A Windows path becomes a `file:///` URI with forward slashes and percent-encoding, a UNC path a
+ * `file://server/share/…` one, and a URL or a bare relative name is kept verbatim — the three
+ * target shapes measured in the corpus (DESIGN-EXTERNAL-LINKS §2.2).
+ */
+export declare function sourceEntryFromPath(path: string): IExternalBook.SourceEntry;
+/**
+ * WHERE the source file is, as a path a reader can act on: `C:\dir\Book.xlsx`,
+ * `\server\share\Book.xlsx`, `https://host/Book.xlsx`. `null` when no source carries a
+ * location at all.
+ *
+ * @remarks
+ * NOT {@link externalBookClosedName}, which is a formula SPELLING (bracketed, and about the book's
+ * own recorded path). This answers the different question a links pane asks — "which file is
+ * this?" — and so it skips a source that records only a bare name: an `xlPathMissing` rel, or a
+ * relative `book` path whose absolute companion (the xxl21 `alternateUrls` extension) is the entry
+ * that actually locates the file. Sources are searched in order, so the book's own path still wins
+ * whenever it carries a directory.
+ */
+export declare function externalBookLocation(book: IExternalBook): string | null;
+/**
+ * Excel's source-OPEN spelling: `[Book.xlsx]Sheet1`. Used once a resolver holds the book, and as
+ * the form a user may type in either state.
+ */
+export declare function externalBookOpenName(book: IExternalBook, sheetName?: string | null): string;
+//# sourceMappingURL=ExternalBookName.d.ts.map

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

@@ -1,24 +1,50 @@
+import { IRange } from '@sheetxl/primitives';
 import { Tuple } from '../collections';
 import { ICell } from '../cell';
+import { ITransaction } from '../transaction';
 /**
  * A cached snapshot of another workbook, referenced from a formula as `[n]Sheet1!$A$1`.
  *
  * @remarks
- * Excel's external link is not a live reference — it is the cache plus enough identity to go
- * re-fetch the source. See the design doc for the full model:
+ * Excel's external link is not a live reference — it is the cache plus enough to go re-fetch the
+ * source. See the design doc for the full model:
  * `private-assets/design/calc/DESIGN-EXTERNAL-LINKS.md`.
  *
- * Read-only. There is no `setPath`/`breakLinks` here yet — authoring lands with the resolver API
- * (design doc §4C), not this phase.
+ * Two members read as "which book is this", and they answer different questions:
+ *
+ * | member | answers | persisted | unique |
+ * | --- | --- | --- | --- |
+ * | {@link getSources} | WHERE the source file is | yes, in the file | **no** — two books can both be `Budget.xlsx` |
+ * | {@link getId} | WHICH book this is, to us | no, minted per load | yes |
+ *
+ * They cannot collapse into one: a path cannot be the key, because two books may share one — hence
+ * a runtime id that is not one. {@link getDisplayName} is a projection of {@link getSources}, not a
+ * third identity.
+ *
+ * A book has no position member. The `n` in `[n]` is where the SOURCE FILE stores this book in its
+ * list, it renumbers when another book is removed, and no surface the reader sees spells one — so
+ * it belongs to {@link IExternalBookCollection}, which is what orders them, and not to the book.
+ *
+ * A book is immutable. Adding, removing and breaking one are the collection's operations
+ * ({@link IExternalBookCollection}); what a book itself answers beyond its snapshot is
+ * {@link getDependents} — which formulas cite it.
  */
 export interface IExternalBook {
     /**
-     * The book's identity, as read from its part's own relationships — an ORDERED list, not a single
-     * path with optional alternates. A book can carry several of these at once (`externalLinkPath`,
-     * `xlExternalLinkPath/xlPathMissing`, `externalLinkLongPath`, and the xxl21 `alternateUrls`
-     * extension are all instances of this one shape).
+     * Where the source workbook is — read from this book's own part relationships.
+     *
+     * @remarks
+     * An ORDERED list, not one path with optional alternates: a book can carry several at once
+     * (`externalLinkPath`, `xlExternalLinkPath/xlPathMissing`, `externalLinkLongPath` and the xxl21
+     * `alternateUrls` extension are all instances of this one shape), and the entry the book is opened
+     * from is sorted first. A LOCATION, never a key — two books can both be `Budget.xlsx`, which is
+     * exactly why {@link getId} exists.
+     *
+     * Deliberately NOT an {@link IWorkbookIO.Origin}: an origin is a live, listenable handle the IO
+     * layer owns and can write back to, and this is a dead `(relType, target)` pair the source file
+     * recorded. Turning one into the other is what a phase-E locator does.
      */
-    getIdentity(): readonly IExternalBook.IdentityEntry[];
+    getSources(): readonly IExternalBook.SourceEntry[];
     /**
      * The source book's sheet names, in its own order — the ONLY names the book is known by.
      *
@@ -28,23 +54,94 @@ export interface IExternalBook {
      */
     getSheetNames(): readonly string[];
     /**
-     * The source book's own defined names, as seen at cache time — raw, uncompiled text.
+     * The source book's own defined names, as seen at cache time — raw text, as the part spells it.
      *
      * @remarks
-     * Parsing `refersTo` into something evaluable is phase 2/3's job (design doc §5). Kept verbatim
-     * here so nothing is lost between read and then.
+     * `refersTo` is what Excel cached: a leading `=` and quoted sheet names of the SOURCE
+     * (`='Data Sheet'!$B$2`), `#REF!` for a name that held an expression rather than a reference, and
+     * never a `sheetId` — Excel flattens a sheet-scoped source name into the book's namespace. Kept
+     * verbatim; the engine compiles it inside the book (`[1]!Name` computes from the cache).
      */
     getDefinedNames(): readonly IExternalBook.DefinedNameEntry[];
     /**
      * The cached cell values for one of the book's sheets, or `null` if that sheet was never cached.
      *
      * @remarks
-     * **Sparse, and uncached is not the same as empty.** Values only — no format, no style, no
-     * comment; a cached date is a plain serial (design doc §2.5).
+     * **Sparse.** A cell the cache does not hold — and a sheet it holds nothing for — reads as a
+     * BLANK cell, which is what Excel computes with the source closed (design doc §6 items 1/2).
+     * Values only — no format, no style, no comment; a cached date is a plain serial (§2.5).
      *
      * @param sheetIndex Position in {@link getSheetNames}, matching the XML's `sheetId` (0-based).
      */
     getSheetData(sheetIndex: number): IExternalBook.SheetData | null;
+    /**
+     * Which book this is, to us — stable for the life of the workbook and **never persisted**.
+     *
+     * @remarks
+     * `[n]` is a POSITION, not a key: removing a book renumbers every citation after it. So a compiled
+     * formula stores this id, and the `[n]` is projected from the collection's ordering
+     * (the collection's ordering) whenever canonical text is produced. Same arrangement
+     * `NamedFormulaCollection` uses for a named formula. Minted at
+     * construction; a `.sxl` round trip mints new ones.
+     */
+    getId(): string;
+    /**
+     * How a scope into this book SPELLS, unquoted — Excel's source-closed form
+     * (`C:\dir\[Budget.xlsx]Sheet1`) while the book is closed, its source-open form
+     * (`[Budget.xlsx]Sheet1`) once a resolver holds it.
+     *
+     * @remarks
+     * A readout of the book's state, not a preference — see DESIGN-EXTERNAL-LINKS §4B. Until phase E
+     * there is no resolver, so this is always the closed form. The caller quotes it.
+     *
+     * @param sheetName Omitted for the book-scoped `[1]!Name` form.
+     */
+    getDisplayName(sheetName?: string | null): string;
+    /**
+     * Every formula block that cites this book — directly, through a sheet of it, or as `[n]!Name`.
+     *
+     * @remarks
+     * Derived from the compiled formulas, never stored: the same index a defined name's dependents
+     * come from, so it is exact and current after any edit. A block on a sheet has that sheet's
+     * stable id as its `scope`; a block whose `scope` is a defined name's id is that name's body,
+     * which cites the book on behalf of everything that uses the name. A block citing the book
+     * through two sheets is listed once.
+     *
+     * Empty until the calculation engine has compiled the workbook's formulas.
+     */
+    getDependents(): readonly IRange.Coords[];
+    /**
+     * Removes this book, renumbering every later `[n]`. One undoable step.
+     *
+     * @remarks
+     * A formula still citing the book is NOT rewritten: it keeps the slot's id, images as `#REF!`
+     * and computes `#REF!` — so an undo, which brings the slot and its id back, heals it. To turn
+     * citations into values first, as Excel's Break Links does, use {@link breakLink}. A book that
+     * is already gone is left alone.
+     */
+    delete(txOptions?: ITransaction.OperationOptions): void;
+    /**
+     * Excel's Break Link: every cell formula that cites this book becomes its current values (the
+     * whole formula, not only the external operand), then the book is removed. One undoable step.
+     *
+     * @remarks
+     * A defined name that cites the book is left as it is and images as `#REF!` afterwards.
+     * {@link IExternalBookCollection.breakAll} is this for every book. A book that is already gone
+     * is left alone.
+     */
+    breakLink(txOptions?: ITransaction.OperationOptions): void;
+    /**
+     * Re-reads this book from its source and replaces the cache — Excel's Refresh on a row of the
+     * Workbook Links pane.
+     *
+     * @remarks
+     * Needs a resolver (`ICellContainerOptions.externalBookResolver`, given when the workbook is
+     * built); without one every book is `'unavailable'` and nothing changes, which is the state a
+     * workbook is in until a host supplies one (DESIGN-EXTERNAL-LINKS §4D). A replaced cache is one undoable step, and every formula
+     * citing the book reads the new values. A resolver that throws leaves the cache as it was and
+     * marks each cached sheet `refreshError`, as Excel records a refresh it could not complete.
+     */
+    refresh(): Promise<IExternalBook.RefreshResult>;
     /**
      * For runtime type checking.
      */
@@ -53,7 +150,8 @@ export interface IExternalBook {
 }
 export declare namespace IExternalBook {
     /**
-     * One `(relTypeUri, target)` pair from the book part's own relationships.
+     * One `(relTypeUri, target)` pair from the book part's own relationships — one place the source
+     * workbook may be found.
      *
      * @remarks
      * `type` is the full relationship-type URI (not a shorthand) — it is what tells apart an
@@ -61,9 +159,20 @@ export declare namespace IExternalBook {
      * `externalLinkLongPath`, and an xxl21 `alternateUrls` entry. Emitting one under a hard-coded rel
      * type would silently rewrite what the source file said.
      */
-    interface IdentityEntry {
+    interface SourceEntry {
         type: string;
         target: string;
+        /**
+         * How the book's own XML refers to this entry, when it refers to it at all: `book` is the path
+         * the book is opened from, `absoluteUrl` its 2021 cloud-URL companion.
+         *
+         * @remarks
+         * Not derivable from {@link type} — the two can carry the SAME relationship type (measured on
+         * task 40234, where a relative and an absolute `externalLinkPath` sit on one part). Absent for
+         * an entry nothing points at, which is a real shape too: an `xlPathMissing` or
+         * `externalLinkLongPath` rel rides along on the part without being referenced from it.
+         */
+        role?: 'book' | 'absoluteUrl';
     }
     interface DefinedNameEntry {
         name: string;
@@ -72,6 +181,45 @@ export declare namespace IExternalBook {
         /** Position in {@link IExternalBook.getSheetNames}, when the name is sheet-scoped. */
         sheetIndex?: number;
     }
+    /**
+     * A source book's current contents, as a resolver answers them — the cache that replaces the
+     * book's. The same three parts the file caches; the book's sources are not part of it.
+     */
+    interface Snapshot {
+        sheetNames: readonly string[];
+        definedNames?: readonly DefinedNameEntry[];
+        /** One entry per sheet the source holds values for; a sheet absent here reads blank. */
+        sheetDataSet?: readonly SheetData[];
+    }
+    /** What one {@link IExternalBook.refresh} came to. */
+    interface RefreshResult {
+        bookId: string;
+        /**
+         * `'refreshed'` — the cache was replaced from the source. `'unavailable'` — nothing could open
+         * the source: no resolver is installed, or the resolver declined this book; the cache stands.
+         * `'failed'` — the resolver threw; the cache stands and its sheets are marked `refreshError`.
+         */
+        status: 'refreshed' | 'unavailable' | 'failed';
+        /** For `'failed'`: what went wrong. */
+        error?: string;
+    }
+    /**
+     * Opens a book's source and answers its current contents, or declines.
+     *
+     * @remarks
+     * DESIGN-EXTERNAL-LINKS §4D: the default one (phase E) is `WorkbookIO.read` with
+     * `calcOnLoad: 'none'`, taking the source's own cached values and never evaluating it — that is
+     * what Excel's cache holds, and it keeps A-cites-B-cites-C from becoming a crawl. An extension
+     * point for a source that is not a workbook file. WHETHER a source may be opened at all — an
+     * untrusted file naming an arbitrary path or URL — is the host's decision, made before this is
+     * asked; a resolver never fetches on its own initiative, only on {@link IExternalBook.refresh}.
+     */
+    interface IResolver {
+        /** The name to show for a book, overriding its own spelling. Sync, fetches nothing. */
+        displayName?(book: IExternalBook): string | null;
+        /** The source's current contents, or `null` to decline (the cache stands). */
+        resolve(book: IExternalBook): Promise<Snapshot | null>;
+    }
     interface SheetData {
         /** Position in {@link IExternalBook.getSheetNames} this cache belongs to — the XML's `sheetId`, 0-based. */
         sheetIndex: number;
@@ -85,10 +233,14 @@ export declare namespace IExternalBook {
         data: Tuple.GridTuple<ICell.JSON>;
     }
     interface JSON {
-        identity: IdentityEntry[];
+        /**
+         * Absent between the link visitor and `XLSXReader`: a visitor never sees its own part's sibling
+         * `.rels` file, so the reader attaches these afterwards. `getSources()` reads it as empty.
+         */
+        sources?: SourceEntry[];
         sheetNames: string[];
         definedNames?: DefinedNameEntry[];
-        /** One entry per CACHED sheet, not per sheet — a sheet absent here was never cached (not empty). */
+        /** One entry per CACHED sheet, not per sheet — a sheet absent here was never cached, and reads blank. */
         sheetDataSet?: SheetData[];
         /** `mc:Ignorable="x14 xxl21"` was present on the part root — preserved so a future writer round-trips it. */
         mceIgnorable?: boolean;

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

@@ -1,20 +1,47 @@
 import { ICollection } from '../type';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
 import { IExternalBook } from './IExternalBook';
 /**
  * The workbook's external books, in `[n]` order.
  *
  * @remarks
- * **Positional, not an identity — see {@link IExternalBook}.** `[n]` in a formula is this
- * collection's index at read time; nothing in the source file names a book any other way. Read-only
- * for now: there is no `add`/`remove` here yet, matching the design doc's phase 1 scope (authoring
- * arrives with the resolver API in a later phase).
+ * **Positional, not a key — see {@link IExternalBook}.** `[n]` in a formula is this
+ * collection's index at read time; nothing in the source file names a book any other way.
+ *
+ * A link is created by a formula and removed by breaking it — Excel's model, and ours. Typing
+ * `'C:\path\[Budget.xlsx]Sheet1'!A1` into a cell adds a book here with an empty cache; {@link add}
+ * is the same step without the formula. {@link IExternalBook.breakLink} is what Excel's Workbook
+ * Links pane does: every citing formula becomes its values, then the slot goes.
  */
 export interface IExternalBookCollection extends ICollection<IExternalBook> {
     /**
-     * The book that formula text `[n]` (1-based) addresses, or `null` if `n` is beyond what was
-     * preserved on read, or its position is a DDE/OLE link (unmodeled — see {@link getItems}).
+     * The book carrying a runtime id, or `null` — for an unknown id and for a DDE/OLE gap alike,
+     * since a gap has an id but no book.
+     */
+    getById(id: string): IExternalBook | null;
+    /**
+     * Adds a book at the end — the next `[n]` — with an empty cache.
+     *
+     * @remarks
+     * This is the state Excel is in when it cannot find a link's source: the file round-trips, and
+     * Excel opens it and offers to update. Undoable.
+     *
+     * @param options Where the source is and, optionally, which sheets it has.
+     */
+    add(options: IExternalBookCollection.AddOptions, txOptions?: ITransaction.OperationOptions): IExternalBook;
+    /**
+     * {@link IExternalBook.breakLink} for every book, in one undoable step — the pane's Break all.
+     *
+     * @returns How many books were broken. Gaps stay: a DDE/OLE slot has nothing to value.
+     */
+    breakAll(txOptions?: ITransaction.OperationOptions): number;
+    /**
+     * {@link IExternalBook.refresh} for every book, in order — the pane's Refresh all.
+     *
+     * @returns One result per book. Without a resolver every one is `'unavailable'`.
      */
-    getByIndex(n: number): IExternalBook | null;
+    refreshAll(): Promise<IExternalBook.RefreshResult[]>;
     /**
      * @returns The positional array, gaps included — `null` at index `i` means `[i+1]` is a DDE/OLE
      * link or otherwise unmodeled, not that it is absent. `null` overall if there are no entries at
@@ -25,5 +52,50 @@ export interface IExternalBookCollection extends ICollection<IExternalBook> {
      * For runtime type checking.
      */
     readonly isIExternalBookCollection: true;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IExternalBookCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** Closes the collection; the workbook's to call. */
+    close(): void;
+}
+export declare namespace IExternalBookCollection {
+    /**
+     * When the cached values of these books should be re-read from their sources, on open.
+     *
+     * @remarks
+     * `userSet` asks the user on open, `always` refreshes without asking, `never` uses the cache.
+     *
+     * The mode governs the books as a SET — no single book carries one — but it is read and written
+     * on the workbook (`IWorkbook.getUpdateLinks`), where Excel's object model and the file both
+     * keep it.
+     */
+    type UpdateLinks = 'always' | 'never' | 'userSet';
+    interface AddOptions {
+        /**
+         * Where the source workbook is: a path or URL (`C:\dir\Budget.xlsx`, `\\server\share\Budget.xlsx`,
+         * `https://host/Budget.xlsx`, or a bare `Budget.xlsx` relative to this workbook), or the
+         * full `(relType, target)` entries a file would record.
+         */
+        sources: string | readonly IExternalBook.SourceEntry[];
+        /** The source's sheet names, if known. A formula citing a sheet not listed here adds it. */
+        sheetNames?: readonly string[];
+    }
+    interface Events {
+        /**
+         * A book was added, removed or refreshed, or a sheet name was recorded on one. Fires once per
+         * change, and on the undo or redo of one.
+         */
+        onCollectionChange?(source: IExternalBookCollection): void;
+        /**
+         * Called once, when the workbook that owns these books closes.
+         */
+        onClose?(source: IExternalBookCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IExternalBookCollection, IExternalBookCollection.Events> {
+    }
 }
 //# sourceMappingURL=IExternalBookCollection.d.ts.map

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

@@ -1,3 +1,4 @@
 export * from './IExternalBook';
 export * from './IExternalBookCollection';
+export * from './ExternalBookName';
 //# sourceMappingURL=index.d.ts.map

package/types/src/fill/IStroke.d.ts

@@ -238,7 +238,7 @@ export declare namespace IStroke {
         readonly Single: "none";
         readonly Double: "double";
         readonly ThickThin: "thickThin";
-        readonly ThinThick: "thickThin";
+        readonly ThinThick: "thinThick";
     };
     type PresetMarkerShape = typeof PresetMarkerShape[keyof typeof PresetMarkerShape];
     const StrokeStyle: {

package/types/src/filter/IFilter.d.ts

@@ -4,10 +4,16 @@ import { ICondition } from '../condition';
 import { ICellRange } from '../cellRange';
 /**
  * Filters are used to hide spans (rows or columns). that do not match a set of conditions.
+ *
+ * @remarks
+ * A column's filter ANDs with the other columns' (Excel's AutoFilter): setting one leaves the
+ * rest in place unless `replace` says otherwise. Every write returns a Promise that resolves once
+ * the rows are hidden; the criteria are written in the same transaction, so an `await` is what
+ * makes a read after the call see them.
  */
 export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
     /**
-     * Returns the range this filter applies to.
+     * Returns the range this filter applies to: the column's data rows, header and totals excluded.
      *
      * @remarks
      * A filter is exactly one column of its table, which is why the singular is declared here rather
@@ -15,9 +21,24 @@ export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
      */
     getRange(): ICellRange;
     /**
-     * Set the condition.
+     * Set the condition, `null` to clear this column's.
+     *
+     * @param condition The condition, or `null` to clear.
+     * @param replace If `true`, every other column's filter is dropped; omitted, they stay and this
+     * one ANDs with them. A column already filtered keeps its place in the level order.
+     * @param options Transaction options.
+     *
+     * @returns Resolves once the rows are hidden; one transaction, one undo step.
+     */
+    setCondition(condition: ICondition.Input | null, replace?: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Re-runs every filter on the table with its current criteria.
+     */
+    apply(options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Clears this column's condition. The other columns' filters stay.
      */
-    setCondition(condition: ICondition.Input, append?: boolean, options?: ITransaction.OperationOptions): void;
+    delete(options?: ITransaction.OperationOptions): Promise<this>;
     /**
      * The offset index from the range
      *
@@ -25,6 +46,8 @@ export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
      * This is relative to the table.
      */
     getIndex(): number;
+    /** For runtime type checking. */
+    readonly isIFilter: true;
 }
 /**
  * {@inheritDoc IFilter}
@@ -76,8 +99,10 @@ export declare namespace IFilter {
          * ``` ts
          * sheet.getRange('E:E').filter('>= 30');
          * ```
+         *
+         * @returns Resolves once the rows are hidden.
          */
-        filter(condition?: ICondition.Input, options?: ITransaction.OperationOptions): this;
+        filter(condition?: ICondition.Input, options?: ITransaction.OperationOptions): Promise<this>;
     }
 }
 //# sourceMappingURL=IFilter.d.ts.map

package/types/src/font/IFont.d.ts

@@ -152,9 +152,26 @@ export declare namespace IFont {
         readonly strikePosition?: number;
         readonly strikeThickness?: number;
         readonly italicAngle?: number;
+        /**
+         * The line pitch in px — what a line of this font advances by, and the height of a row sized
+         * to it: `ascent + descent + 2` (Excel's standard row height for the font; the 2 is the
+         * gridline gutter above and below the font box). Includes {@link lineGap}.
+         */
         readonly lineHeight: number;
+        /**
+         * The baseline's offset from the top of a {@link lineHeight} box, in px: where a renderer that
+         * paints the line as a box (a CSS line box) puts the alphabetic baseline.
+         */
         readonly baseline: number;
         readonly lineGap: number;
+        /**
+         * The font's ascent above the baseline in whole px at the measured size — GDI's `tmAscent`,
+         * which is what Excel lays text out with (the OS/2 `winAscent`, hinted where the font has a
+         * VDMX table).
+         */
+        readonly ascent: number;
+        /** The font's descent below the baseline in whole px — GDI's `tmDescent` (OS/2 `winDescent`). */
+        readonly descent: number;
     }
     interface MetricOptions {
         isBold?: boolean;

package/types/src/history/IHistory.d.ts

@@ -22,8 +22,9 @@ export declare namespace IHistory {
      * @template S The type of the source for `getSource``.
      * @template C The type of the coordinates the snapshot is bound to.
      * @template J The type of the JSON for `toJSON`.
+     * @template R What `copyTo` resolves with; the coordinates unless the source has more to report.
      */
-    interface ISnapshot<D = any, S = any, C = any, J = any> {
+    interface ISnapshot<D = any, S = any, C = any, J = any, R = C> {
         /**
          * Copies the snapshot to the specified range.
          *
@@ -32,7 +33,7 @@ export declare namespace IHistory {
          *
          * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required.
          */
-        copyTo(destination: D, options?: IHistory.CopyToOptions): Promise<C> | C;
+        copyTo(destination: D, options?: IHistory.CopyToOptions): Promise<R> | R;
         /**
          * The source that created the snapshot.
          * This is used to quickly do comparisons.

package/types/src/i18n/LanguagePack.d.ts

@@ -1,5 +1,5 @@
 import { FormulaError } from '@sheetxl/primitives';
-import { MinifiedDescriptor } from '@sheetxl/scripting';
+import { MinifiedDescriptor, MinifiedEnumDescriptors } from '@sheetxl/scripting';
 import { LanguagePack as BaseLanguagePack, LanguageTag } from '@sheetxl/utils';
 /**
  * The **spreadsheet-language plane** of a language pack (I18N-DESIGN.md Plane 3): function names,
@@ -56,10 +56,18 @@ export interface LanguagePack extends BaseLanguagePack {
      * descriptor. Values are {@link MinifiedDescriptor}s — the SAME shape the built-in
      * descriptor modules compile to, so a generated per-locale module IS a pack chunk with
      * no reshaping; `initializeFunctions` overlays it per-field over the built-in English.
+     *
+     * The module form may also carry `enums` — the copy for enum parameters, again the shape the
+     * descriptor modules compile to. A key is an enum id (`MatchMode`), which serves every function
+     * that declares an enum of that name, or `FUNCTION:EnumId` (`TEXTAFTER:MatchMode`) for the one
+     * function where the same name means something else. The qualified entry wins, per field.
      */
-    functionHelp?: () => Promise<Record<string, MinifiedDescriptor> | {
-        default: Record<string, MinifiedDescriptor>;
-    }>;
+    functionHelp?: () => Promise<Record<string, MinifiedDescriptor> | FunctionHelpModule>;
+}
+/** The module form of a {@link LanguagePack.functionHelp} chunk. */
+export interface FunctionHelpModule {
+    default: Record<string, MinifiedDescriptor>;
+    enums?: MinifiedEnumDescriptors;
 }
 /**
  * The active (or `tag`'s) spreadsheet-language pack — the MERGE of every contributor's plane: the

package/types/src/index.d.ts

@@ -22,6 +22,7 @@ export * from './text';
 export * from './condition';
 export * from './sort';
 export * from './filter';
+export * from './person';
 export * from './comment';
 export * from './hyperlink';
 export * from './numFmt';
@@ -30,7 +31,9 @@ export * from './resource';
 export * from './string';
 export * from './anchored';
 export * from './chart';
+export * from './pivot';
 export * from './picture';
+export * from './shape';
 export * from './scripting';
 export * from './calculation';
 export * from './address';