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

package/types/src/calculation/symbol/ExternalSheetSymbols.d.ts

@@ -0,0 +1,80 @@
+import { IExternalBookCollection, ExternalScopeParts } from '../../externalBook';
+import { ExternalBookCollection } from '../../externalBook/ExternalBookCollection';
+import { SheetSymbolHandle } from './SheetSymbolProvider';
+/**
+ * The stable-id prefix that marks a sheet symbol as living in an external book.
+ *
+ * @remarks
+ * `ext:<bookId>` is the book-scoped form (`[1]!Name`); `ext:<bookId>:<sheetIndex>` adds a sheet, and
+ * `ext:<bookId>:<first>:<last>` is a 3-D span across the book's sheets (`[1]Alpha:Data Sheet`). The
+ * prefix is the test every consumer uses — "is this scope external" is a `startsWith`, which is why
+ * external books needed no new {@link SymbolType} and no new branch in the twenty-odd places that
+ * ask the Sheet provider (DESIGN-EXTERNAL-LINKS §4B).
+ */
+export declare const EXTERNAL_ID_PREFIX = "ext:";
+/** Is this stable id an external sheet or book? */
+export declare const isExternalSymbolId: (stableId: string | null | undefined) => boolean;
+/**
+ * The book id and sheet positions inside an `ext:` stable id, or `null` if it is not one.
+ *
+ * @remarks
+ * A book is `sheetIndex` and `sheetEnd` of `-1`; a sheet has both equal; a 3-D span has the first and
+ * last sheet. A uuid carries no `:`, so every `:` after the book id is a separator.
+ */
+export declare function splitExternalSymbolId(stableId: string): {
+    bookId: string;
+    sheetIndex: number;
+    sheetEnd: number;
+} | null;
+/**
+ * The stable id of a book (`sheetIndex < 0`), of one of its sheets, or of a 3-D span from
+ * `sheetIndex` to `sheetEnd` — the inverse of {@link splitExternalSymbolId}.
+ */
+export declare const externalSymbolId: (bookId: string, sheetIndex: number, sheetEnd?: number) => string;
+/**
+ * The authoring half of {@link bindExternalScope}: how a scope that names no existing book, or a
+ * sheet no book lists, becomes one. Supplied by the engine from the collection it owns.
+ */
+export interface ExternalBookMinter {
+    /** A new book for a typed `<dir>[<file>]` — answers its id. */
+    addBook(parts: ExternalScopeParts): string;
+    /** Records `sheetName` on an existing book — answers the sheet's index. */
+    addSheet(bookId: string, sheetName: string): number;
+}
+/**
+ * Binds a sheet scope that names an external book, or `null` if it names none of this workbook's.
+ *
+ * @remarks
+ * Every spelling a book answers to binds to the SAME id, so the storage form (`[1]Sheet1`), the
+ * closed display form (`C:\dir\[Book.xlsx]Sheet1`) and the open one (`[Book.xlsx]Sheet1`) are three
+ * ways of writing one symbol — which is the invariant that lets a handle's `toString()` be fed
+ * straight back to `bind` (see {@link SheetSymbolProvider}).
+ *
+ * A position that does not exist (`[7]` of three books) answers `null`: the typed image is kept
+ * verbatim, the reference is `#REF!`, and the writer warns. A file name matching more than one book
+ * answers `null` too — the citation is genuinely ambiguous and `[n]` is the only spelling that is
+ * not — unless the typed directory picks one of them out.
+ *
+ * A 3-D span (`[1]Alpha:Data Sheet`) binds to one id with its sheets in the book's own order, so
+ * `[1]Data Sheet:Alpha` is the same symbol; both sheets must be listed.
+ *
+ * With a `minter`, a file name no book carries MINTS one (DESIGN-EXTERNAL-LINKS §4C): typing
+ * `'C:\dir\[Book.xlsx]Sheet1'!A1` creates the link, cache empty, exactly as Excel does when it cannot
+ * see the source. A sheet a known book does not list is recorded on it the same way. A `[n]` is never
+ * minted — a position is a citation of something that exists, and a directory that differs from a
+ * same-named book's is a different book, not a respelling of it. A span never mints either.
+ */
+export declare function bindExternalScope(books: ExternalBookCollection | null | undefined, displayName: string, minter?: ExternalBookMinter | null, withinBook?: string | null): string | null;
+/**
+ * Resolves an `ext:` stable id to a sheet handle, or `null` if the book has since been removed.
+ *
+ * @remarks
+ * `toString()` is the projection DESIGN-EXTERNAL-LINKS §4B describes: `[n]Sheet1` by default — the
+ * form a formula is STORED as, read off the book's current position — and the book's display name
+ * when the caller asks for one. Both bind back. A span spells both sheets after one book prefix
+ * (`[1]Alpha:Data Sheet`), as Excel writes it.
+ */
+export declare function resolveExternalSymbol(books: ExternalBookCollection | null | undefined, stableId: string, display: boolean): SheetSymbolHandle | null;
+/** The `AddOptions` a minted book starts from: the typed directory and file, the typed sheet. */
+export declare function mintedBookOptions(parts: ExternalScopeParts): IExternalBookCollection.AddOptions;
+//# sourceMappingURL=ExternalSheetSymbols.d.ts.map

package/types/src/calculation/symbol/ISymbolRegistry.d.ts

@@ -10,6 +10,29 @@ export declare const SymbolType: {
 };
 export type SymbolType = typeof SymbolType[keyof typeof SymbolType];
 export interface SheetCtx {
+    /**
+     * Resolve to the form a READER sees rather than the form a formula is stored as.
+     *
+     * @remarks
+     * The two differ only for an external book: stored is `[n]Sheet1`, where `n` is a position
+     * projected from the book's place in the collection, and display is the book's own spelling
+     * (`'C:\dir\[Book.xlsx]Sheet1'`). A local sheet has one name and ignores this.
+     */
+    display?: boolean;
+    /**
+     * Bind is AUTHORING: a scope that names an external book this workbook has none of may create
+     * one (`'C:\dir\[Book.xlsx]Sheet1'` typed into a cell is how a link is made — DESIGN-EXTERNAL-LINKS
+     * §5 step 13). Off by default, and off for an editing compile, so a keystroke mints nothing; a
+     * local sheet is never minted.
+     */
+    mint?: boolean;
+    /**
+     * The formula being linked belongs to an external BOOK — a cached defined name's body — so a
+     * plain sheet name (`Alpha`) is that book's sheet, never one of this workbook's, and a `[n]`
+     * position cites the source's own links, which this workbook cannot see (`null`). Nothing is
+     * minted inside a book.
+     */
+    book?: string;
 }
 export interface NamedFormulaCtx {
     /** The stableId of the sheet that owns the formula scope, if any. */

package/types/src/calculation/symbol/IndirectSymbolProvider.d.ts

@@ -57,6 +57,11 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      */
     private readonly _getByName;
     private readonly _getById;
+    /**
+     * The name an item goes by for this provider's reader - what a bind matches and a resolve
+     * displays. The item's own name unless the reader holds a copy of the names of its own.
+     */
+    private readonly _nameOf;
     private _byName;
     private _byId;
     /**
@@ -79,7 +84,12 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      * shadowing (a name scoped to that sheet beats a global of the same name). Providers with no
      * scoped items — tables — may ignore it.
      */
-    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null);
+    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null, 
+    /**
+     * The name an item goes by for this provider's reader - what a bind matches and a resolve
+     * displays. The item's own name unless the reader holds a copy of the names of its own.
+     */
+    _nameOf?: (item: T) => string);
     /**
      * @inheritdoc ISymbolProvider.bind
      *
@@ -98,8 +108,12 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      * it heals to turns out to be scoped.
      *
      * A miss on `_byName` is not proof the item has no proxy — see {@link _byRealId}.
+     *
+     * `ctx.existing: true` asks only whether the name is an item NOW: it answers `null` rather than
+     * minting a proxy for a name nothing holds. For a caller deciding what a spelling IS (a bare name
+     * that may be a table) — a proxy minted for every other name would never heal into anything.
      */
-    bind(displayName: string, ctx?: Record<string, unknown>): string;
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
     /** Points a proxy at its real item, keeping {@link _byRealId} in step. */
     private _adopt;
     /** Moves a proxy to the `_byName` key its current name/scope spell. */

package/types/src/calculation/symbol/SheetSymbolProvider.d.ts

@@ -2,17 +2,77 @@ import { IRange } from '@sheetxl/primitives';
 import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
 /**
  * Strict provider for sheet symbols.
+ *
+ * @remarks
+ * An EXTERNAL sheet is a sheet symbol too. A scope this workbook has no sheet for, and which names
+ * a book (`[1]Sheet1`, `C:\dir\[Book.xlsx]Sheet1`), falls through to `_getExternal` rather than to a
+ * `SymbolType` of its own — the twenty-odd consumers of a scope all ask this provider, and teaching
+ * one provider a second spelling touches none of them (DESIGN-EXTERNAL-LINKS §4B).
+ *
+ * So is a 3-D span (`Alpha:Gamma`, PLAN-3D-REFS §2.1): one symbol naming its two endpoint sheets,
+ * `<firstId>:<lastId>`, with the endpoints in tab order.
  */
 export declare class SheetSymbolProvider implements ISymbolProvider {
     private readonly _getId;
     private readonly _getById;
-    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null);
+    private readonly _external?;
+    /** A sheet's position in tab order, hidden sheets included, or `-1`. */
+    private readonly _getIndexById?;
+    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null, _external?: (ExternalSheetSymbols | null) | undefined, 
+    /** A sheet's position in tab order, hidden sheets included, or `-1`. */
+    _getIndexById?: ((sheetId: string) => number) | null | undefined);
     /** @inheritdoc ISymbolProvider.bind */
-    bind(displayName: string, _ctx: Record<string, unknown>): string | null;
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
     /** @inheritdoc ISymbolProvider.resolve */
-    resolve(stableId: string, _ctx: Record<string, unknown>): SheetSymbolHandle | null;
+    resolve(stableId: string, ctx?: Record<string, unknown>): SheetSymbolHandle | null;
+    /**
+     * `First:Last` (names or ids) to a span id with the endpoints in tab order, the plain sheet id when
+     * both ends are one sheet (`Alpha:Alpha` is `Alpha`, as Excel normalizes it), or `null` when either
+     * end is not a sheet of this workbook.
+     */
+    private _bindSpan;
+    /** One end of a span: a sheet's id or name, never a virtual grid (which has no name). */
+    private _bindEndpoint;
+    private _resolveSpan;
+}
+/**
+ * The two endpoint sheet ids of a LOCAL span id (`<firstId>:<lastId>`), or `null` if it is not one.
+ *
+ * @remarks
+ * A sheet id is `<name>-<uuid>` and a sheet name cannot contain `:`, so a `:` in a non-external id is
+ * the separator. Both halves must end in a uuid: typed text that never bound (`Alpha:Nope`) reaches
+ * `resolve` too, and must not be mistaken for a span whose sheets are gone.
+ */
+export declare function splitSheetSpanSymbolId(stableId: string | null | undefined): [string, string] | null;
+/**
+ * What a local span id becomes when tab order changes from `before` to `after` — `undefined` when it
+ * stands.
+ *
+ * @remarks
+ * An endpoint that is gone, or that `movedId` carried across the other endpoint, is replaced by its
+ * inward neighbor in `before`: the nearest sheet between the endpoints that is still there. When both
+ * ends land on one sheet the answer is that sheet's plain id, as Excel collapses `Alpha:Beta` to
+ * `Beta!A1`. A span that lost every sheet stands too; it has nothing to shrink to.
+ */
+export declare function replaceSheetSpanEndpoints(spanId: string, before: readonly string[], after: readonly string[], movedId?: string): string | undefined;
+/** Whether a sheet stable id is a 3-D span — local `<firstId>:<lastId>` or external `ext:<bookId>:<i>:<j>`. */
+export declare function isSpanSymbolId(stableId: string | null | undefined): boolean;
+/** The external-book half of {@link SheetSymbolProvider}, supplied by `Calculation`. */
+export interface ExternalSheetSymbols {
+    /**
+     * `mint`: a scope naming a book this workbook has none of may CREATE one — see {@link SheetCtx.mint}.
+     * `withinBook`: the id of the book a plain sheet name belongs to — see {@link SheetCtx.book}.
+     */
+    bind(displayName: string, mint: boolean, withinBook?: string | null): string | null;
+    resolve(stableId: string, display: boolean): SheetSymbolHandle | null;
 }
 export interface SheetSymbolHandle extends SymbolHandle {
     getEntireCoords(): IRange.Coords | null;
+    /**
+     * The sheet's own name, `null` for a sheet that has none. `toString` is the DISPLAY form and
+     * substitutes a placeholder for a nameless sheet; a caller that means to bind or compare a
+     * name reads this instead. Absent on a handle that is not a sheet (a virtual grid).
+     */
+    getName?(): string | null;
 }
 //# sourceMappingURL=SheetSymbolProvider.d.ts.map

package/types/src/calculation/symbol/SymbolRegistry.d.ts

@@ -16,4 +16,24 @@ export declare class SymbolRegistry implements ISymbolRegistry {
     /** @inheritdoc ISymbolRegistry.resolve */
     resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
 }
+/**
+ * A registry that answers some symbol types from providers of its own and every other from a base.
+ *
+ * @remarks
+ * The model's symbol map (DESIGN-CALC-SERVICE §8) is this over the engine's: the types the engine
+ * keeps a copy of resolve through the model's live items here, while the rest resolve through the
+ * engine's providers. Registering a provider registers it on the base, so a provider that arrives
+ * late (the functions, once their module loads) is seen by both.
+ */
+export declare class OverlaidSymbolRegistry implements ISymbolRegistry {
+    private readonly _base;
+    private readonly _overrides;
+    constructor(_base: ISymbolRegistry, _overrides: ReadonlyMap<SymbolType, ISymbolProvider>);
+    /** @inheritdoc ISymbolRegistry.registerProvider */
+    registerProvider(type: SymbolType, provider: ISymbolProvider): void;
+    /** @inheritdoc ISymbolRegistry.bind */
+    bind(type: SymbolType, displayName: string, ctx?: Record<string, unknown>): string | null;
+    /** @inheritdoc ISymbolRegistry.resolve */
+    resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
+}
 //# sourceMappingURL=SymbolRegistry.d.ts.map

package/types/src/calculation/symbol/index.d.ts

@@ -1,7 +1,8 @@
 export { type ISymbolRegistry, type ISymbolProvider, type SymbolHandle, SymbolType } from './ISymbolRegistry';
 export { type SheetCtx, type NamedFormulaCtx, type TableCtx, type ColumnCtx, type FunctionCtx } from './ISymbolRegistry';
-export { SymbolRegistry } from './SymbolRegistry';
-export { SheetSymbolProvider } from './SheetSymbolProvider';
+export { SymbolRegistry, OverlaidSymbolRegistry } from './SymbolRegistry';
+export { SheetSymbolProvider, isSpanSymbolId, splitSheetSpanSymbolId, replaceSheetSpanEndpoints, type SheetSymbolHandle, type ExternalSheetSymbols } from './SheetSymbolProvider';
+export { EXTERNAL_ID_PREFIX, isExternalSymbolId, splitExternalSymbolId, externalSymbolId, bindExternalScope, resolveExternalSymbol, mintedBookOptions, type ExternalBookMinter } from './ExternalSheetSymbols';
 export { TableSymbolProvider } from './TableSymbolProvider';
 export { IndirectSymbolProvider, IndirectProxy } from './IndirectSymbolProvider';
 export { TableColumnSymbolProvider } from './TableColumnSymbolProvider';

package/types/src/cell/ICell.d.ts

@@ -1,7 +1,7 @@
 import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange } from '@sheetxl/primitives';
 import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
-import { ITextFrame, TextRotation } from '../text';
+import { ITextFrame, TextRotation, TextStacked } from '../text';
 import { NumberFormat } from '../numFmt';
 import { ITable } from '../table';
 import { IDataValidation } from '../dataValidation';
@@ -53,16 +53,21 @@ export interface ICell {
      * Returns the formula assigned to the cell.
      *
      * @remarks
-     * Returns `null` if the cell has no formula.
+     * Returns `null` if the cell has no formula, or if its protection hides the formula (see
+     * {@link ICell.isFormulaHidden}).
      */
     getFormula(options?: ICalculation.FormulaTextOptions): ICalculation.IFormula | null;
     /**
-     * Returns the formula text assigned to the cell, WITHOUT a leading `=`.
+     * Returns the formula text assigned to the cell, with its leading `=` (`'=SUM(A1:A3)'`).
      *
      * @remarks
-     * A convenience for `getFormula()?.getExpression()` — the stored shape, so `null` and `''` stay
-     * distinguishable from a formula and the text can be re-parsed as-is. Displaying it the way
-     * Excel's API answers means prefixing `'=' +`; see {@link ICalculation.IFormula.getExpression}.
+     * The form a formula is entered in and the form Excel's API answers, so it can be written back
+     * with {@link ICellRange.setValue}. The `=` is what keeps a formula like `=+A1` apart from the
+     * text `+A1`. For the stored form without the `=`, use
+     * {@link ICalculation.IFormula.getExpression} on {@link ICell.getFormula}.
+     *
+     * Returns `null` for a cell without a formula, and when protection hides the formula, like
+     * {@link ICell.getFormula}.
      */
     getFormulaText(options?: ICalculation.FormulaTextOptions): string | null;
     /**
@@ -77,35 +82,37 @@ export interface ICell {
      *
      * @remarks
      * These represent the direct inputs required to compute the cell's value.
-     * Returns `null` if the cell has no precedents.
+     * Resolves `null` if the cell has no precedents.
+     * A question for the calculation engine: it resolves once the engine has answered, in order
+     * behind the writes made before it, and with `null` while the engine is `Off`.
      */
-    getDirectPrecedents(): ICellRanges;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns the cells that directly reference this cell in their own formulas.
      *
      * @remarks
      * These represent the immediate consumers of this cell's value.
-     * Returns `null` if the cell has no dependents.
+     * Resolves `null` if the cell has no dependents.
      */
-    getDirectDependents(): ICellRanges;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /**
      * Returns all ranges that contribute to this cell's value, including
      * those referenced indirectly through the full calculation chain.
      *
      * @remarks
      * This performs a recursive search upstream to find all root data sources.
-     * Returns `null` if the cell has no precedents.
+     * Resolves `null` if the cell has no precedents.
      */
-    getPrecedents(): ICellRanges;
+    getPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns all cells that are eventually affected by this cell, including
      * those that depend on it indirectly through the full calculation chain.
      *
      * @remarks
      * This performs a recursive search downstream to find the total impact of a value change.
-     * Returns `null` if the cell has no dependents.
+     * Resolves `null` if the cell has no dependents.
      */
-    getDependents(): ICellRanges;
+    getDependents(): Promise<ICellRanges | null>;
     /**
      * Returns the hyperlink assigned to the cell.
      *
@@ -114,11 +121,13 @@ export interface ICell {
      */
     getHyperlink(): IHyperlink | null;
     /**
-     * Retrieves a list of comments associated with the cell.
+     * Returns the comment on the cell, or `null` if there is none.
      *
-     * **Note**: This feature is not yet implemented.
+     * @remarks
+     * One per cell — the thread's root, with its replies, or a note. The sheet's
+     * {@link ISheet.getComments} is where one is added.
      */
-    getComments(): Readonly<IComment.Properties>;
+    getComments(): IComment | null;
     /**
      * Retrieves any warnings attached to the cell.
      *
@@ -215,7 +224,11 @@ export interface ICell {
      */
     getBestFit(colWidth?: number, minContent?: boolean): Readonly<Partial<Size>> | null;
     /**
-     * Returns protection information.
+     * Returns the cell's protection format, the same as `getStyle().getProtection()`.
+     *
+     * @remarks
+     * Whether the cell can be edited right now also depends on its sheet and its unlocked ranges; see
+     * {@link ICell.isEditAllowed}.
      */
     getProtection(): ICellProtection;
     /**
@@ -237,6 +250,15 @@ export interface ICell {
      * Returns the range of the cell if it is a spill cell.
      */
     getSpill(): ICellRange | null;
+    /**
+     * Returns which {@link ITypes.FormulaArrayKind | kind} of array block the cell belongs to, or
+     * `null` if it is not part of one.
+     *
+     * @remarks
+     * Answers for every cell of the block, not only the anchor — a `fixed` (array-entered) block
+     * shows `{=…}` on all of its cells, as Excel does.
+     */
+    getSpillKind(): ITypes.FormulaArrayKind | null;
     /**
      * Returns `true` if the cell is a spill and not the top left.
      */
@@ -270,10 +292,13 @@ export interface ICell {
      */
     getColumn(): ITable.IColumn | null;
     /**
-     * Returns the data validation assigned to the cell if there is one.
+     * Returns the cell's primary data validation: the highest-priority one that covers it, or `null`
+     * when none does.
      *
      * @remarks
-     * Will return null if there is no data validation assigned.
+     * Validations may overlap, and every one that covers the cell applies; see
+     * {@link ICellRange.getDataValidations} for all of them. The primary one is also the one Excel
+     * honors when it opens a file whose validations overlap.
      */
     getDataValidation(): IDataValidation | null;
     /**
@@ -322,7 +347,13 @@ export interface ICell {
      */
     isEditAllowed(): boolean;
     /**
-     * Returns `true` if the formula is hidden.
+     * Returns `true` if protection hides this cell's formula.
+     *
+     * @remarks
+     * The sheet is protected (not paused), and neither the sheet's `showFormulas` nor the cell style's
+     * allows it.
+     * A hidden formula reads as no formula: {@link ICell.getFormula} and {@link ICell.getFormulaText}
+     * return `null`. It still calculates, and is still saved with the workbook.
      */
     isFormulaHidden(): boolean;
     /**
@@ -452,6 +483,13 @@ export declare namespace ICell {
          * horizontally. See {@link TextRotation.layoutLines} for the model.
          */
         rotation?: TextRotation.Layout;
+        /**
+         * Present when the cell's text is stacked ("vertical text"): per-column slot geometry — every
+         * glyph upright in its own slot of the line pitch, columns from line breaks (and from wrapping
+         * against the content height), each column aligned on its own. See
+         * {@link TextStacked.layoutColumns} for the model. {@link bounds} is then the column group.
+         */
+        stacked?: TextStacked.Layout;
     }
     /**
      * Expansive way to set cell updates options.
@@ -475,6 +513,10 @@ export declare namespace ICell {
          * Allow to to set a hyperlink to this value.
          */
         hyperlink?: IHyperlink.Update;
+        /**
+         * Update the comment: modifiers, a plain string as the content, or `null` to remove.
+         */
+        comments?: IComment.Update;
     }
     /**
      * Configuration options for customizing the parsing of a string into an `ICell.Update` object.
@@ -675,13 +717,26 @@ export declare namespace ICell {
         /**
          * Represents notes associated with the cells.
          * @remarks
-         * **NOT IMPLEMENTED**
+         * A note is a comment carrying `asNote` — the two share one store — so this selects the
+         * notes out of a range rather than naming a store of its own. Displaying a note as Excel's
+         * simple yellow box, rather than as a comment, is **NOT IMPLEMENTED**.
          */
         readonly Notes: "notes";
         /**
-         * Represents comments attached to the cells.
+         * Represents comments attached to the cells, notes included.
+         * @remarks
+         * Excel offers a single `Clear Comments and Notes`, and this is it. {@link Content.Notes}
+         * is the narrower one, for the notes alone.
          */
         readonly Comments: "comments";
+        /**
+         * Represents the data validations covering the cells.
+         * @remarks
+         * A clear cuts the cells out of every validation covering them; a validation left covering
+         * nothing is deleted, and one that also covers other cells keeps them. Office Scripts'
+         * `range.getDataValidation().clear()`.
+         */
+        readonly DataValidations: "dataValidations";
     };
     type Content = typeof Content[keyof typeof Content];
 }

package/types/src/cell/ICellProtection.d.ts

@@ -1,20 +1,52 @@
+import { IStyle } from '../style';
 /**
- * Additional cell protection properties.
+ * The protection format of a cell: whether it stays editable, and whether it shows its formula,
+ * while its sheet is protected.
  *
+ * @remarks
+ * * Part of the style, so it travels with the format — copy, paste, fill and named styles carry it,
+ *   and clearing formats resets it.
+ * * Only consulted while the sheet is protected. {@link ICell.isEditAllowed} and
+ *   {@link ICell.isFormulaHidden} combine it with the sheet's protection and its unlocked ranges.
  */
 export interface ICellProtection {
     /**
-     * This is specified in ooxml but not sure what behavior it has.
-     * @defaultValue true
+     * Returns `true` if the cell stays editable when its sheet is protected.
+     *
+     * @remarks
+     * * This is Excel's *Locked* format, inverted.
+     * * It never asks for a password, even inside a password-protected unlocked range. An unlocked
+     *   range is the other way to make a cell editable; either one is enough.
+     *
+     * @defaultValue false
      */
-    isEditAllowed(): boolean;
+    isAlwaysUnlocked(): boolean;
     /**
-     * If the formula will be hidden when the worksheet is protected.
+     * Sets whether the cell stays editable when its sheet is protected.
+     *
+     * @param alwaysUnlocked `true` to keep the cell editable. `null` to clear.
+     */
+    setAlwaysUnlocked(alwaysUnlocked: boolean | null, options?: IStyle.UpdateOptions): ICellProtection;
+    /**
+     * Returns `true` if the cell's formula stays visible on a protected sheet that hides formulas.
+     *
      * @remarks
-     * This is called hidden in ooxml but in Excel object model it is formulaHidden.
+     * * An exception, like {@link isAlwaysUnlocked}: a formula shows when the sheet
+     *   (`ISheetProtection.isShowFormulasAllowed`) or the cell allows it, so this only matters while
+     *   the sheet hides them.
+     * * A hidden formula reads as no formula ({@link ICell.getFormula} is `null`), but it still
+     *   calculates and is still saved with the workbook. It is a view rule, not secrecy.
+     *
      * @defaultValue false
      */
-    isFormulaHidden(): boolean;
+    isShowFormulas(): boolean;
+    /**
+     * Sets whether the cell's formula stays visible on a protected sheet that hides formulas.
+     *
+     * @param showFormulas `true` to keep the formula visible. `null` to clear.
+     */
+    setShowFormulas(showFormulas: boolean | null, options?: IStyle.UpdateOptions): ICellProtection;
+    toJSON(): ICellProtection.JSON;
     /**
      * For runtime type checking.
      */
@@ -29,13 +61,21 @@ export interface ICellProtection {
  */
 export declare namespace ICellProtection {
     /**
-     * Properties for ICellProperties.
+     * Properties for ICellProtection.
      */
     interface Properties {
-        edit?: boolean;
-        formulaHidden?: boolean;
+        alwaysUnlocked?: boolean;
+        showFormulas?: boolean;
     }
     interface JSON extends Properties {
     }
+    /**
+     * Modifiers describe a partial list of properties that can be set.
+     */
+    type Modifiers = Partial<ICellProtection.Properties>;
+    /**
+     * Options for updating an ICellProtection.
+     */
+    type Update = ICellProtection | Modifiers | null;
 }
 //# sourceMappingURL=ICellProtection.d.ts.map