@sheetxl/sdk 0.8.0-beta.5 → 0.8.0-beta.7

package/types/scripting.d.ts

@@ -1058,6 +1058,14 @@ declare global {
          * This is useful for validation
          */
         disableBundle?: boolean;
+        /**
+         * If true, the bundle is minified. For a module that is stored (a workbook's scripts, a `.sxlm`).
+         *
+         * @remarks
+         * Off by default: code that is only run keeps its own names, so a runtime error reads as the
+         * author wrote it (`wb.getSheet is not a function`, not `a.getSheet`).
+         */
+        minify?: boolean;
         /**
          * If true, this will not include the source map in the compiled module.
          */
@@ -1116,16 +1124,11 @@ declare global {
          * Check the source as code that runs once, not as code kept to be run again.
          *
          * @remarks
-         * For an agent's ad hoc run. Only a finding that would fail at run time stops the run; the rest
-         * are reported as warnings:
-         *
-         * - Annotations are not required: an untyped parameter is `any` (no `noImplicitAny`), and a
-         *   missing type on an entry is not reported.
-         * - A member the receiver does not have, read where a missing member is expected - `r.getFormat?.()`,
-         *   `r.getFormulas ? … : …`, `typeof r.x` - is a probe, and a warning: it reads `undefined`.
-         * - A condition on a function that is never called (TS2774) is a warning.
+         * For an ad hoc run (`sheetxl -e`, the MCP `run` tool). Annotations are not required: a default
+         * export's untyped first parameter is the script context, and a missing type is not reported.
          *
-         * Only meaningful with {@link ambientTypes}; without them there is no semantic check to relax.
+         * A run is not type-checked before it executes - leave {@link ambientTypes} out. The types are
+         * there to explain a run that went wrong, which is `diagnoseRun` in `@sheetxl/runner`.
          */
         lenient?: boolean;
     }
@@ -4818,10 +4821,13 @@ declare global {
         /**
          * Creates a temporary copy of the cell with the specified updates applied.
          *
+         * @param modifiers The update.
+         * @param options How the update is read. See {@link ICell.CreateCellOptions}.
+         *
          * @remarks
          * The original cell remains unchanged, making this useful for temporary modifications.
          */
-        createCell(modifiers: ICell.Update): ICell;
+        createCell(modifiers: ICell.Update, options?: ICell.CreateCellOptions): ICell;
         /**
          * Returns the `CellCoords`.
          */
@@ -4968,6 +4974,23 @@ declare global {
              */
             comments?: IComment.Update;
         }
+        /**
+         * Options for {@link ICell.createCell} and {@link ISheet.createCell}.
+         */
+        interface CreateCellOptions {
+            /**
+             * Whether a text value is read as a typed entry is — `9/23/95` a date, `12.3%` a number —
+             * rather than taken as the text it is. `true` reads it with the defaults; an
+             * {@link ICell.ModifiersFromStringOptions} customizes the reading.
+             *
+             * @defaultValue false
+             *
+             * @remarks
+             * The same reading {@link ICellRange.setValues} gives text, where it is the default. Here it
+             * is opt-in: a cell created from a value keeps that value.
+             */
+            textParser?: boolean | ICell.ModifiersFromStringOptions;
+        }
         /**
          * Configuration options for customizing the parsing of a string into an `ICell.Update` object.
          * Commonly used for processing CSV imports and other string-based data sources.
@@ -9294,11 +9317,11 @@ declare global {
      * Interface for working with a chart.
      *
      * @remarks
-     * A chart is the content of a movable, which places and names it — see {@link IChart.getMovable}.
+     * A chart is the content of a movable, which places it — see {@link IChart.getMovable}.
      * Until the chart is modeled it is carried as the markup it was read from and written back
      * unchanged; {@link IChart.getXML} is the read-only view of that markup.
      */
-    export interface IChart extends IModel {
+    export interface IChart extends IModel, IMovable.IContent {
         /**
          * Returns the chart's title, or `null` if it has none.
          *
@@ -9340,17 +9363,17 @@ declare global {
          */
         getPivotSource(): string | null;
         /**
-         * Returns a description for assistive technologies.
-         */
-        getDescription(): string;
-        /**
-         * Returns the movable that places the chart on the sheet.
+         * Returns the movable that places the chart on the sheet, or `null` if it is not placed by one.
          *
          * @remarks
-         * The movable holds the chart's position, size and name; the chart keeps no copy of any of
-         * them. Deleting the movable deletes the chart.
+         * The movable holds the chart's position and size; the chart keeps no copy of either.
+         * Deleting the chart removes its movable.
          */
-        getMovable(): IMovable;
+        getMovable(): IMovable | null;
+        /**
+         * Deletes the chart, and with it the movable that places it.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
         /**
          * Returns the chart's own markup, or `null` if none was captured.
          *
@@ -9485,8 +9508,8 @@ declare global {
      *
      * @remarks
      * A view over the sheet's movables: a chart is the content of a movable, and the movable is what
-     * places, names and deletes it — see {@link IChart.getMovable}. Read-only for now; a chart is
-     * added by adding a movable with chart content.
+     * places it — see {@link IChart.getMovable}. Read-only for now; a chart is added by adding a
+     * movable with chart content.
      */
     export interface IChartCollection extends ICollection<IChart> {
         /**
@@ -9494,7 +9517,7 @@ declare global {
          */
         getItems(options?: ICollection.GetItemsOptions): IChart[];
         /**
-         * Returns the chart whose movable has the given name, or `null` if there is none.
+         * Returns the chart with the given name, or `null` if there is none.
          *
          * @param name The name of the chart. This is case insensitive.
          */
@@ -10850,12 +10873,47 @@ declare global {
      *
      * Anchored to its cell, so it follows a row or column insert or delete and is deleted when its
      * cell is.
+     *
+     * A note is also the content of a {@link getMovable | movable}: the box it is shown in.
      */
-    export interface IComment extends IAnchored {
+    export interface IComment extends IAnchored, IMovable.IContent {
         /**
          * The comment's identifier, unique within the workbook.
          */
         getId(): string;
+        /**
+         * `'note'` for a note, `'comment'` for a threaded comment.
+         */
+        getType(): string;
+        /**
+         * The box a note is shown in, or `null` for a threaded comment, which has none.
+         *
+         * @remarks
+         * The box is an ordinary movable: it is selected, moved and resized like a picture's, and is
+         * among the sheet's `getMovables()`. Its content is this comment.
+         *
+         * * **Placement.** A box that has not been moved sits where Excel puts a new note, beside its
+         *   cell, and stores nothing. Moving or resizing it stores where it is, relative to its cell,
+         *   so a note copied to another cell keeps its box beside it.
+         * * **Shown or on hover.** `isHidden()` is `true` for a box that appears only while its cell is
+         *   pointed at, which is how a note starts and which a view decides. `setHidden(false)` keeps
+         *   it on the sheet.
+         *
+         * A reply converts a note to a threaded comment, and its box goes with it.
+         *
+         * @example
+         * ```ts
+         * const note = sheet.getComments().add('B2', 'Check this', { asNote: true });
+         * const box = note.getMovable();
+         * box.setHidden(false); // always shown
+         * box.setBounds({ width: 240 });
+         * ```
+         */
+        getMovable(): IMovable | null;
+        /**
+         * Deletes the comment: its replies with it, or a note's box.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
         /**
          * The sheet the comment is on.
          */
@@ -10878,12 +10936,15 @@ declare global {
          * Replaces the content.
          *
          * @param content Plain text, or formatting runs for a note.
+         *
+         * @remarks
+         * Drops the comment's mentions: each names a span of the text it was made in.
          */
         setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
         /**
          * The content with its formatting runs, or `null` when it is plain text.
          */
-        getRichContent(): IComment.RichContent | null;
+        getRichContent(): IRichText.JSON | null;
         /**
          * The person who wrote the comment, or `null` if the workbook does not know them.
          */
@@ -10986,7 +11047,7 @@ declare global {
              */
             getContent(): string;
             /**
-             * Replaces the content.
+             * Replaces the content, dropping the reply's mentions.
              */
             setContent(content: IComment.Content, options?: ITransaction.OperationOptions): this;
             /**
@@ -11019,42 +11080,12 @@ declare global {
             readonly isICommentReply: true;
         }
         /**
-         * One formatted span of a note's content.
+         * What a comment says: plain text, or formatting runs for a note.
          *
          * @remarks
-         * A note keeps Excel's rich text; a threaded comment is plain text and never carries these.
-         * Every property but `text` is optional and inherits the note's default when absent.
-         */
-        interface Run {
-            /**
-             * The text of the span.
-             */
-            text: string;
-            /**
-             * The font name.
-             */
-            font?: string;
-            /**
-             * The font size in points.
-             */
-            size?: number;
-            bold?: boolean;
-            italic?: boolean;
-            /**
-             * The color as a hex string.
-             */
-            color?: string;
-        }
-        /**
-         * Content with formatting: a list of {@link Run | runs}.
+         * A note keeps Excel's rich text; a threaded comment is plain text and never carries runs.
          */
-        interface RichContent {
-            runs: Run[];
-        }
-        /**
-         * What a comment says: plain text, or formatting runs for a note.
-         */
-        type Content = string | RichContent;
+        type Content = string | IRichText.JSON;
         /**
          * The values that can be set on a comment.
          */
@@ -11153,23 +11184,22 @@ declare global {
         interface ReplyJSON extends EntryJSON {
         }
         /**
-         * The note's box: the shape Excel draws the note in, held as it was read.
-         *
-         * @remarks
-         * Only ever present on a comment read from a file. A comment authored here has none, and is
-         * written with Excel's default box (hidden until hovered, hung to the right of its cell); a
-         * comment that has one is written with that box, its cell rewritten from the comment's so it
-         * stays with the note, its size, fill and offsets replayed as they were.
-         *
-         * Opaque markup, as a half-house — the VML `<v:shape>`, not a {@link IShape.JSON}, whose own
-         * `xml` is DrawingML. What it holds is a movable's worth: the cells and offsets of its corners
-         * (an {@link IMovable.AnchorOffset}), whether it is hidden, and a shape's fill and size. That
-         * is where it graduates to — an anchor, a `hidden` flag and an {@link IShape.JSON} — once the
-         * VML can be read into them; the offsets are the authoring machine's pixels, which is what
-         * keeps them opaque today.
+         * A note's box, where it differs from the default.
          */
         interface BoxJSON {
-            xml: string;
+            /**
+             * Where the box is: the cells and pixel offsets of its top-left and bottom-right corners,
+             * the cells counted from the note's own (`r: -1` is the row above it).
+             *
+             * @remarks
+             * Absent for a box that has not been moved or resized, which is placed beside its cell.
+             */
+            anchor?: IMovable.AnchorOffset;
+            /**
+             * How the box is drawn when that is not Excel's default, held as it was read: the VML
+             * `<v:shape>` without its id, its position or its cell.
+             */
+            xml?: string;
         }
         /**
          * A comment, for persisting.
@@ -11187,6 +11217,16 @@ declare global {
              * The replies, oldest first.
              */
             replies?: ReplyJSON[];
+            /**
+             * Whether a note's box stays on the sheet rather than appearing on hover.
+             *
+             * @defaultValue false
+             */
+            shown?: boolean;
+            /**
+             * The alternative text of a note's box.
+             */
+            description?: string;
             /**
              * {@inheritDoc IComment.BoxJSON}
              */
@@ -11356,6 +11396,18 @@ declare global {
          * - Hide for ConditionalFormat/TableFilter (default behavior is usually correct)
          */
         isIncludeBlanks(): boolean;
+        /**
+         * Whether the condition can be authored as it is.
+         *
+         * @returns A message key naming the first problem — an operand not yet given, bounds the wrong
+         * way around, a whole-number rule holding a fraction — or `null` when there is none.
+         *
+         * @remarks
+         * Advisory, and what an editor asks before it saves: the rules are the ones Excel's dialogs
+         * refuse on. A condition read from a file is kept and evaluated whatever this answers; a
+         * comparison missing an operand evaluates as inert rather than as wrong.
+         */
+        validate(): string | null;
         /**
          * Returns a string representation of the selector, operator, and param.
          */
@@ -11607,16 +11659,22 @@ declare global {
              * @remarks
              * A formula is authored as a `=`-prefixed string or an {@link ICalculation.IFormula}; a resolved
              * condition holds it as an `IFormula`.
+             *
+             * `null` while not yet given. The comparison matches nothing, and excludes nothing, until both
+             * bounds are.
              */
-            from: number | string | ICalculation.IFormula;
+            from: number | string | ICalculation.IFormula | null;
             /**
              * The upper bound value — a number, or a formula whose result is compared per cell.
              *
              * @remarks
              * A formula is authored as a `=`-prefixed string or an {@link ICalculation.IFormula}; a resolved
              * condition holds it as an `IFormula`.
+             *
+             * `null` while not yet given. The comparison matches nothing, and excludes nothing, until both
+             * bounds are.
              */
-            to: number | string | ICalculation.IFormula;
+            to: number | string | ICalculation.IFormula | null;
         }
         interface ColorOption {
             /**
@@ -11835,6 +11893,18 @@ declare global {
              * Convert the value to the specified scalar type.
              */
             toType<T extends InteropScalar>(value: Scalar, type: InteropScalarType): T;
+            /**
+             * The text the current cell shows, when the evaluation matches by text; `null` otherwise.
+             *
+             * @remarks
+             * A filter matches by shown text unless asked not to ({@link ICondition.RangeOptions.match}):
+             * a cell holding `1.5` and showing `1.50` is the item `1.50`. Conditional formats and data
+             * validations match by value, so this answers `null` for them. An operator that compares
+             * text reads `ctx.getText() ?? value`.
+             *
+             * Formatted on demand, so an operator that never asks pays nothing.
+             */
+            getText(): string | null;
             /**
              * Resolves a condition input to a fully-built ICondition instance.
              *
@@ -12013,6 +12083,13 @@ declare global {
              * Creates the default param for this operator type.
              */
             createDefaultParam?(lhsSelector?: ICondition.ISelector): P | null | undefined;
+            /**
+             * Whether `param` is one this operator can be authored with under `lhsSelector`.
+             *
+             * @returns A message key naming the first problem, or `null` when there is none. Omitted, any
+             * param is taken. See {@link ICondition.validate}.
+             */
+            validateParam?(param: P, lhsSelector?: ICondition.ISelector | null): string | null;
             /**
              * Returns a human-readable title of the operator.
              */
@@ -12254,6 +12331,26 @@ declare global {
              * with no explicit `hasHeader` evaluates the entire range, header row included.
              */
             hasHeader?: boolean;
+            /**
+             * What a filter's list items and `equalTo` text are compared with: the text a cell shows, or
+             * the value it holds.
+             *
+             * @defaultValue `'text'`
+             *
+             * @remarks
+             * `'text'` is a spreadsheet's AutoFilter: the item `1.50` keeps a cell holding `1.5` under the
+             * format `0.00`, and the item `1.5` does not. A number passed as an item or operand still
+             * matches the cells holding that number, however they are formatted.
+             *
+             * `'value'` compares typed values only, so the text `"1"` never matches the number `1`.
+             *
+             * Comparisons (`>`, `between`), Top N, averages, date periods and date groups read the value
+             * either way, and the text operators (contains, starts with, ends with) only ever match a
+             * cell that holds text.
+             *
+             * Read by filters. Conditional formats and data validations match by value.
+             */
+            match?: 'text' | 'value';
         }
         /**
          * JSON for serialization and round-tripping.
@@ -12852,11 +12949,7 @@ declare global {
      *
      * **PLACEHOLDER** - This is under development and not made public yet.
      */
-    export interface IControl extends IModel {
-        /**
-         * Returns a description for assistive technologies.
-         */
-        getDescription(): string;
+    export interface IControl extends IModel, IMovable.IContent {
         /**
          * Returns the id of the shape that draws this control, or `null` if it has none.
          *
@@ -12876,6 +12969,10 @@ declare global {
          */
         getXML(): string | null;
         toJSON(toResourceId?: (resource: IResource) => number | null): IControl.JSON | null;
+        /**
+         * Deletes the control, and with it the movable that places it.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
         /** For runtime type checking. */
         readonly isIControl: true;
     }
@@ -14840,6 +14937,36 @@ declare global {
          * This is relative to the table.
          */
         getIndex(): number;
+        /**
+         * The column's distinct values, as a filter menu lists them.
+         *
+         * @param options See {@link IFilter.GetItemsOptions}.
+         *
+         * @remarks
+         * Which rows are read depends on the column:
+         * - With no condition on it, the rows that are showing. A row hidden by another column's filter,
+         *   or by hand, is not listed.
+         * - With a condition on it, the rows every *other* column's filter passes, so a value this
+         *   column's own condition hides is listed too, unchecked.
+         *
+         * An item is `checked` when at least one row holding it passes the filters, so a column filtered
+         * by any condition (`> 5`, say) lists the passing values checked. A row hidden by hand does not
+         * uncheck its value.
+         *
+         * Reads the stored values in one pass; the cost follows the column's content, not its extent.
+         *
+         * @example
+         * ```ts
+         * const filter = table.getColumnAt(1).getFilter();
+         * const { items } = await filter.getItems();
+         * // keep the first two values
+         * await filter.setCondition({
+         *   operator: ICondition.BuiltInOperatorNames.InSet,
+         *   param: { items: items.slice(0, 2).map((item) => item.text) }
+         * });
+         * ```
+         */
+        getItems(options?: IFilter.GetItemsOptions): Promise<IFilter.Items>;
         /** For runtime type checking. */
         readonly isIFilter: true;
     }
@@ -14856,6 +14983,51 @@ declare global {
             conditions?: ICondition.JSON[];
             axis?: IRange.Axis;
         }
+        /**
+         * Options for {@link IFilter.getItems}.
+         */
+        interface GetItemsOptions {
+            /**
+             * The distinct values to stop at.
+             *
+             * @defaultValue `10000`
+             */
+            limit?: number;
+        }
+        /**
+         * One distinct value of a filtered column.
+         */
+        interface Item {
+            /**
+             * The text the cells show. This is the item an `InSet` condition holds: a filter matches by
+             * shown text ({@link ICondition.RangeOptions.match}).
+             */
+            text: string;
+            /** The value of the first cell showing `text`; the item's place in the order. */
+            value: Scalar;
+            /** The rows holding the value. */
+            count: number;
+            /** Whether at least one row holding the value passes the filters. */
+            checked: boolean;
+        }
+        /**
+         * What {@link IFilter.getItems} answers.
+         */
+        interface Items {
+            /**
+             * The distinct texts, ascending by the workbook's comparison of their values. Values that
+             * show alike are one item. Blanks are not an item.
+             */
+            items: readonly Item[];
+            /** Whether a listed row is blank. */
+            hasBlanks: boolean;
+            /** Whether at least one blank row passes the filters. */
+            blanksChecked: boolean;
+            /** Whether the column has more distinct values than `limit`; the rest are not listed. */
+            truncated: boolean;
+            /** The rows read. */
+            total: number;
+        }
         /**
          * Interface indicating the ability to filter data.
          */
@@ -15438,16 +15610,30 @@ declare global {
          */
         getSheetIndex(sheet?: string | IReferenceRange): number;
         /**
-         * Returns a copy of a range with hidden rows or columns removed.
+         * Returns a range as it reads without its hidden rows or columns.
          *
          * @param range The range to filter.
-         * @param axes Which axis to filter on. Default is `IRange.AxisSelection.Row`.
-         * @returns A new range without the hidden rows or columns.
+         * @param options See {@link IFormulaContext.FilterHiddenOptions}.
+         * @returns `range` itself when nothing in it is hidden; otherwise the same range reading with
+         * the hidden rows or columns skipped ({@link IRange.IteratorOptions.processRowSkip}).
          *
          * @remarks
          * Use this for functions that ignore hidden data, such as `SUBTOTAL`.
+         *
+         * Nothing is copied. The shape of `range` is kept, and a reference stays a reference: a hidden
+         * cell is not visited and reads as empty, so every position still means the cell it meant, and
+         * an aggregate that ignores blanks ignores it. A computed array has no rows or columns to hide
+         * and is returned as it is.
+         *
+         * A hidden row is a hidden row, whoever hid it: a filter and the user leave the same mark, and
+         * nothing here tells them apart. What a filter adds is a state of the range's SHEET, which
+         * {@link IFormulaContext.FilterHiddenOptions.onlyWhileFiltered} reads.
+         *
+         * A formula that calls `SUBTOTAL` or `AGGREGATE` is recalculated when a row or column is hidden
+         * or shown, and when a filter is set or cleared. One that reaches this only through a custom
+         * function is not: it reads the state when it is next calculated.
          */
-        filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+        filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
         /**
          * Returns a copy of a range with any cell whose formula is a nested total removed.
          *
@@ -15786,6 +15972,28 @@ declare global {
      * {@link IFormulaContext}
      */
     export namespace IFormulaContext {
+        /**
+         * Options for {@link IFormulaContext.filterHidden}.
+         */
+        interface FilterHiddenOptions {
+            /**
+             * Which axis to filter on.
+             * @defaultValue `IRange.AxisSelection.Row`
+             */
+            axes?: IRange.AxisSelection;
+            /**
+             * Skip the hidden rows or columns only while the range's sheet is filtered: while some
+             * AutoFilter or table on that sheet holds a condition, whether or not it hides a row. Until
+             * then `range` is returned as it is, hidden rows included.
+             *
+             * @remarks
+             * This is `SUBTOTAL` 1-11 (Excel: they "include manually hidden rows", which is what an
+             * unfiltered sheet reads as). `SUBTOTAL` 101-111 and `AGGREGATE` leave it off and skip
+             * always.
+             * @defaultValue false
+             */
+            onlyWhileFiltered?: boolean;
+        }
         /**
          * Options for {@link IFormulaContext.parseAsNumber}.
          */
@@ -18162,7 +18370,10 @@ declare global {
          * | `'control'` | {@link IControl} — a form control |
          *
          * Anything else is content that is positioned and saved but not modeled; it answers
-         * `getType()` and nothing more.
+         * {@link IMovable.IContent} and nothing more.
+         *
+         * The content owns what identifies it: its name, its description and its id. The movable owns
+         * where it is drawn. To remove both, delete the content.
          *
          * @example
          * ```ts
@@ -18170,9 +18381,14 @@ declare global {
          * if (content.getType() === 'shape') {
          *   const text = (content as IShape).getTextFrame()?.getText();
          * }
+         * content.delete();
          * ```
          */
-        getContent<T extends IModel>(): T;
+        getContent<T extends IMovable.IContent = IMovable.IContent>(): T;
+        /**
+         * Deletes the content, which removes this movable. The same as `getContent().delete()`.
+         */
+        delete(): void;
         /**
          * Selects the current movable.
          *
@@ -18209,30 +18425,6 @@ declare global {
          * Returns the absolute bounds of the movable object in pixels or `null` if not yet laid out.
          */
         getBounds(): Bounds | null;
-        /**
-         * Set the name for a movable object.
-         *
-         * @param name The name of the IMovable.
-         */
-        setName(name: string): IMovable;
-        /**
-         * @see
-         * {@link setName}
-         *
-         * @returns The name or `null` if the movable has been deleted.
-         */
-        getName(): string | null;
-        /**
-         * This is the alternative text use for assistive technologies.
-         */
-        setDescription(description: string | null): IMovable;
-        /**
-         * @see
-         * {@link setDescription}
-         *
-         * @returns The description or `null` if none has been set (or the movable has been deleted).
-         */
-        getDescription(): string | null;
         /**
          * If true then the movable object is hidden.
          */
@@ -18314,6 +18506,61 @@ declare global {
      * {@link IMovable}
      */
     export namespace IMovable {
+        /**
+         * What a movable draws: a chart, a picture, a shape, a slicer, a control.
+         *
+         * @remarks
+         * Content owns what identifies it, and the movable owns where it is drawn. Content can exist
+         * with no movable: a picture used as a sheet background is not placed by one.
+         */
+        interface IContent {
+            /**
+             * Returns an immutable type string.
+             */
+            getType(): string;
+            /**
+             * Returns the id of the content.
+             */
+            getId(): string;
+            /**
+             * Returns the name, or `null` if the content has none.
+             *
+             * @remarks
+             * Not defined for content that is never named.
+             */
+            getName?(): string | null;
+            /**
+             * Set the name.
+             *
+             * @param name The name of the content.
+             */
+            setName?(name: string): this;
+            /**
+             * Returns the alternative text used by assistive technologies, or `null` if none has been set.
+             */
+            getDescription(): string | null;
+            /**
+             * Set the alternative text used by assistive technologies.
+             */
+            setDescription(description: string | null): this;
+            /**
+             * Returns a label for the kind of content, such as `Chart` or `Picture`.
+             */
+            getTypeDescription(): string;
+            /**
+             * Returns the movable that places the content on the sheet, or `null` if it is not placed by
+             * one.
+             */
+            getMovable(): IMovable | null;
+            /**
+             * Deletes the content, and with it the movable that places it.
+             */
+            delete(options?: ITransaction.OperationOptions): void;
+            /**
+             * Returns `true` if the content has been deleted.
+             */
+            isDeleted(): boolean;
+        }
         /**
          * Extends {@link ITypes.SelectOptions} to include options for `IMovable`.
          */
@@ -18336,11 +18583,7 @@ declare global {
              */
             onSelectionChange?(source: IMovable): void;
             /**
-             * Called when the name has changed.
-             */
-            onNameChange?(source: IMovable): void;
-            /**
-             * Called when selection changes.
+             * Called when the bounds have changed.
              */
             onBoundsChange?(source: IMovable): void;
             /**
@@ -18416,6 +18659,14 @@ declare global {
              * This must align to a known movable object type. Defined in the IEmbeddedDrawing interface.
              */
             type: string;
+            /**
+             * The name of the content.
+             */
+            name?: string;
+            /**
+             * The alternative text used by assistive technologies.
+             */
+            description?: string;
             /**
              * Underlying json.
              */
@@ -18434,16 +18685,6 @@ declare global {
              * The behavior of how the movable resizes as the anchor/cells change.
              */
             anchorType?: IAnchored.Type;
-            /**
-             * The name of the movable object.
-             */
-            name?: string;
-            /**
-             * This is the alternative text use for assistive technologies.
-             *
-             * @defaultValue null
-             */
-            description?: string;
             /**
              * If true then the movable object is hidden.
              *
@@ -18561,6 +18802,12 @@ declare global {
              * Initial json value.
              */
             json?: J;
+            /**
+             * The name of the content.
+             *
+             * @defaultValue A name made from the type, such as `Chart 3`.
+             */
+            name?: string;
             /**
              * If a referenceId is provided then the movable will be linked to the resource.
              * @param resourceId
@@ -19638,8 +19885,12 @@ declare global {
     /**
      * Interface for working with Pictures (both Images and SVG).
      */
-    export interface IPicture extends IModel {
+    export interface IPicture extends IModel, IMovable.IContent {
         toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
+        /**
+         * Deletes the picture, and with it the movable that places it.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
         /**
          * Returns the resource associated with this picture.
          */
@@ -21398,6 +21649,24 @@ declare global {
              * If passing a large bound care must be taken.
              */
             includeEmpty?: boolean;
+            /**
+             * Skips rows of the range: given the next row that would be read, answers the row to read
+             * instead - the same row when it is read, or the next one that is (the previous, when
+             * `reverse`).
+             *
+             * @param index The 0-based row about to be read.
+             * @param reverse Whether the read runs from the last row back.
+             * @returns The row to read, at or past `index`.
+             *
+             * @remarks
+             * A skipped cell is not visited, reads as empty and is left out of the statistics; the shape
+             * of the range is unchanged. `SUBTOTAL` reads a range this way when it skips hidden rows.
+             */
+            processRowSkip?: (index: number, reverse?: boolean) => number;
+            /**
+             * Skips columns of the range, as {@link processRowSkip} skips rows.
+             */
+            processColumnSkip?: (index: number, reverse?: boolean) => number;
             /**
              * Useful for callback functions that want a this.
              */
@@ -22306,7 +22575,8 @@ declare global {
          *
          * - Every requested type (all types when omitted) is present with an explicit count —
          *   a `0` is a fact about the range, a missing key would be ambiguous.
-         * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values.
+         * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values. A cell the
+         *   range skips ({@link IRange.IteratorOptions.processRowSkip}) is not a blank; it is not counted.
          * - Never throws on error values — errors are population here, not faults — regardless of
          *   the `onError` iterator policy the stats were created with.
          */
@@ -22948,6 +23218,41 @@ declare global {
         }
     }
 
+    /**
+     * Text with formatting: a list of {@link IRichText.Run | runs}, each a span of text with the font
+     * properties it sets.
+     *
+     * @remarks
+     * A run records only what it sets. Everything it leaves out is inherited from the font of whatever
+     * holds the text (a note's default, a cell's style).
+     */
+    export namespace IRichText {
+        /**
+         * One formatted span.
+         */
+        interface Run {
+            /**
+             * The text of the span.
+             */
+            text: string;
+            /**
+             * The font properties this span sets, or nothing when it has none of its own.
+             *
+             * @remarks
+             * The same properties a cell's font has, so a bold span is `{ weight: 700 }`, italic is
+             * `{ style: 'italic' }`. The color is any string a font's color takes; one read from a file keeps
+             * its theme or indexed color that way.
+             */
+            font?: IStyledFont.JSON;
+        }
+        /**
+         * The serialized form: the runs, in order.
+         */
+        interface JSON {
+            runs: Run[];
+        }
+    }
+
     /**
      * Describes the host environment the calculation engine is running in.
      *
@@ -23346,16 +23651,16 @@ declare global {
      * Reading only: a shape's preset and its text. An imported shape is otherwise kept as the source
      * wrote it and saved back unchanged.
      */
-    export interface IShape extends IModel {
+    export interface IShape extends IModel, IMovable.IContent {
         toJSON(toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
         /**
          * Returns the name of the shape.
          */
-        getName(): string;
+        getName(): string | null;
         /**
-         * Returns the description of the shape.
+         * Deletes the shape, and with it the movable that places it.
          */
-        getDescription(): string;
+        delete(options?: ITransaction.OperationOptions): void;
         /**
          * Returns the kind of shape this is: its preset geometry.
          *
@@ -23983,14 +24288,15 @@ declare global {
          *
          * @param update Cell Update
          * @param coords Optional CellCoord
+         * @param options How the update is read. See {@link ICell.CreateCellOptions}.
          * @returns A detached ICell
          *
          * @remarks
-         * * Useful for previewing values such as tooltip.
+         * * Useful for previewing values such as tooltip, or what typed text would be entered as.
          * * Does not add to the sheet but provides a standalone ICell.
          * * If the coords are passed it will return disconnect cell update for that value.
          */
-        createCell(update: ICell.Update, coords?: IRange.FixableCellCoords): ICell;
+        createCell(update: ICell.Update, coords?: IRange.FixableCellCoords, options?: ICell.CreateCellOptions): ICell;
         /**
          * Parses a formula expression and returns a *transient* formula object anchored to this sheet.
          *
@@ -25068,6 +25374,23 @@ declare global {
          * Returns true if any of the headers have the isHidden flag set to true or if any sizes are 0.
          */
         hasHidden(): boolean;
+        /**
+         * Returns the ranges of headers a filter holds a condition over: on the row axis, the data rows
+         * of the AutoTable and of every table whose {@link ITable.getActiveFilters} is not empty; on
+         * the column axis none, as nothing filters columns.
+         *
+         * @param coords Only the ranges that meet this run, when given (a viewport).
+         *
+         * @remarks
+         * A sheet with any is "filtered", as Excel has it: `SUBTOTAL` 1-11 leave out every hidden row
+         * of a filtered sheet, hand-hidden ones included, and count them all on an unfiltered one; the
+         * visible headers of these ranges are the ones drawn as filtered. A condition counts whether
+         * or not it hides a row.
+         *
+         * A row hidden by hand and a row hidden by a filter are the same hidden row; nothing records
+         * which, and clearing a filter shows both ({@link ITable.deleteFilters}).
+         */
+        getFilteredRanges(coords?: Readonly<RunCoords>): readonly ICellHeaderRange[];
         /**
          * Returns true if header has a max selection at the given index.
          */
@@ -25832,9 +26155,12 @@ declare global {
      * @hidden
      * @internal
      */
-    export interface ISlicer extends IModel {
+    export interface ISlicer extends IModel, IMovable.IContent {
         toJSON(toResourceId?: (resource: IResource) => number | null): ISlicer.JSON | null;
-        getDescription(): string;
+        /**
+         * Deletes the slicer, and with it the movable that places it.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
         /** For runtime type checking. */
         readonly isISlicer: true;
     }
@@ -27970,11 +28296,20 @@ declare global {
          */
         interface SnapshotDestination {
             tables: ITableCollection;
+            /** Where the table lands: its top-left is used, its size is the table's own. */
             range: IRange.Coords;
         }
         interface ISnapshot extends IHistory.ISnapshot<ITable.SnapshotDestination, ITable, IRange.Coords> {
             /**
-             * Called when the table is copied to a new collection.
+             * Copies, or moves, the table to the destination.
+             *
+             * @remarks
+             * The table's cells are expected at the destination already: the table takes its header,
+             * body and totals rows from what is there.
+             *
+             * With `isCut` the source table is moved. Within its own sheet it is the same table at a new
+             * place, so its name and the references to it stay as they are; anywhere else it is removed
+             * and added again under its name.
              */
             copyTo(destination: ITable.SnapshotDestination, options?: ReferenceableClipboard.CopyOptions): Promise<IRange.Coords>;
         }
@@ -28579,8 +28914,18 @@ declare global {
              * A default value of false will create a new row.
              */
             hasHeader?: boolean;
+            /**
+             * Whether the range already ends with the totals row the `properties` ask for. The table then
+             * takes those cells as its totals row rather than adding one below the range.
+             *
+             * @defaultValue false
+             */
+            hasTotals?: boolean;
             /**
              * Properties to set on the table when created.
+             *
+             * @remarks
+             * With `headerRowCount: 0` the range has no header row: all of it is data.
              */
             properties?: ITable.Properties;
             /**
@@ -30403,6 +30748,17 @@ declare global {
              * needs to know that the change it is hearing about is a restore, not an operation.
              */
             isRestoring(): boolean;
+            /**
+             * Returns `true` while the open operation is an {@link amend} of a commit other than the one
+             * the store is at.
+             *
+             * @remarks
+             * Its writes land in that commit's snapshot alone, and the current state does not change. So
+             * anything made inside it that is not versioned by this store - a resource held outside it,
+             * once for every snapshot - would exist where the current snapshot has no record of it. Code
+             * that makes such a thing asks this first.
+             */
+            isAmendingOtherCommit(): boolean;
             /**
              * The root transaction of the operation that is open.
              *