@sheetxl/sdk 0.8.0-beta.16 → 0.8.0-beta.18

package/types/scripting.d.ts

@@ -136,6 +136,8 @@ declare global {
         const refToRun: <T = any>(ref: IRange.JSONReference<T>, isColumn: boolean) => RunCoordValue<T> | null;
         /** {@inheritDoc runToRef} */
         const runsToRefs: <T = any>(runs: readonly Readonly<RunCoordValue<T>>[], isColumn: boolean) => IRange.JSONReferenceEntry<T>[];
+        /** Splits an address list at its `,` separators, skipping those in a quoted sheet name or brackets. */
+        const splitAddressList: (address: string) => string[];
         /** {@inheritDoc refToRun} */
         const refsToRuns: <T = any>(refs: readonly IRange.JSONReference<T>[], isColumn: boolean) => RunCoordValue<T>[];
     }
@@ -6990,6 +6992,15 @@ declare global {
          * checkbox cell holding `2` has a control and draws `2`.
          */
         getControl(): ICellControl | null;
+        /**
+         * Returns the cell's sparkline, or `null` when it has none.
+         *
+         * @remarks
+         * The sparkline is the cell's view of its group: what it draws
+         * ({@link ISparklineGroup.ISparkline.getDataRange}) and how ({@link ISparklineGroup.ISparkline.getGroup}).
+         * A cell has at most one. It is drawn over the cell's value, which it leaves as it is.
+         */
+        getSparkline(): ISparklineGroup.ISparkline | null;
         /**
          * Returns `true` if the cell contains a value.
          *
@@ -7403,6 +7414,14 @@ declare global {
              * `range.getDataValidation().clear()`.
              */
             readonly DataValidations: "dataValidations";
+            /**
+             * Represents the sparklines drawn in the cells.
+             * @remarks
+             * A clear takes the cells out of their sparkline groups; a group left with no cell is
+             * deleted. Excel's Sparkline > Clear. Clear Contents and Clear Formats leave a sparkline, as in
+             * Excel; Clear All removes it.
+             */
+            readonly Sparklines: "sparklines";
         };
         type Content = typeof Content[keyof typeof Content];
         /**
@@ -7512,6 +7531,10 @@ declare global {
             readonly TwinBlockDivergence: "twinBlockDivergence";
             /** A typed number an order of magnitude or more off the numbers typed in its format on the sheet. */
             readonly ScaleOutlier: "scaleOutlier";
+            /** A typed number beside a label that no formula in the workbook reads: an assumption the model never uses. */
+            readonly UnreferencedInput: "unreferencedInput";
+            /** A labeled row with nothing where the rows above and below hold values: a line left out, or a period of it. */
+            readonly RowGap: "rowGap";
             /** A constant typed into a formula — a number, a string or a boolean — and how often the workbook types it. */
             readonly ConstantFrequency: "constantFrequency";
         };
@@ -7551,6 +7574,8 @@ declare global {
          * | `literalMatchesInput` | `literal`, the number as the formula types it; `inputAt`, the nearest typed number of that value no formula reads; `label` / `labelAt`, that input's label, when it has one; `matches`, the places the value is typed unread |
          * | `twinBlockDivergence` | `part` (`'literal'` / `'sign'`); for a literal, `literal` and `expected`, this formula's number and its twins'; for a sign, `term` of `terms`, the term that differs, `references`, how many the shape holds, and `sign`, how this formula adds it; `twins`, how many formulas carry the other side; `twinAt`, one of them |
          * | `scaleOutlier` | `format` (`'percent'`); `times`, the power of ten the value is off by; `typical`, the median of the sheet's typed numbers in that format; `of`, how many there are |
+         * | `unreferencedInput` | `label` / `labelAt`, the line's label; `cells`, the typed numbers on the line nothing reads; `value`, the number as shown, for a line of one cell |
+         * | `rowGap` | `label` / `labelAt`, the row's label; `missing` of `of`, the empty cells among those filled in both neighbor rows; `kind` (`'cells'`, some of the row is filled; `'row'`, none of it); `above` / `aboveAt` and `below` / `belowAt`, the neighbor rows' labels, where text; `labelFont: 'own'` when neither neighbor's label shares the label's font |
          * | `constantFrequency` | `kind` (`'number'`, `'string'`, `'boolean'`); `value`, a number without its sign; `uses`, the places in the workbook that type it; `of`, the workbook's constant uses |
          *
          * **Runs.** `formula`, `hardcodeInRun` and `styleBreak` are one rule over different layers of
@@ -7606,6 +7631,17 @@ declare global {
          * places in the workbook type it (`uses`) and of how many constant uses (`of`). The rarer the
          * constant, the higher it ranks. A finding's `uses` and `of` change when another sheet changes.
          *
+         * **What is left out.** `unreferencedInput` reads the typed numbers beside a label that no
+         * formula on any sheet reads: an assumption the model never uses, which in a model being built
+         * is the item still to build. A labeled line fires only when none of its numbers is read, so a
+         * historical row whose last period feeds a forecast is data in use; a line of numbers at one
+         * step (years) is a header. The rank is divided by the line's cells: a lone cell is an
+         * assumption, a long row is data. `rowGap` reads a labeled row against the rows above and
+         * below it (within one spacer row): the cells filled in both neighbors and empty here are the
+         * line left out, or its missing periods. A row that is partly filled ranks in full, an empty row
+         * at half, and a row whose label is in a font neither neighbor shares (a heading) at a third.
+         * Both findings change when another sheet starts or stops reading the cell.
+         *
          * A label's position is absolute (`R12C3`), since it stays put whichever cell of a region reads
          * it; its text is the one read at the region's first cell.
          */
@@ -8702,6 +8738,53 @@ declare global {
          * by {@link clear} of formats, and carried by a paste of formats.
          */
         setControl(control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): this;
+        /**
+         * Draws a sparkline in each cell of the range, from its share of `data`, as one new group; `null`
+         * removes the cells' sparklines.
+         *
+         * @param data The cells the sparklines draw: one area, on this sheet when not qualified, or a
+         * defined name for one (read as the cells it names now, as Excel does).
+         * @param properties How they draw. A new group starts as Excel's does: empty cells as gaps,
+         * Excel's colors, and negative points colored for win/loss.
+         * @returns The new group, or `null` for a removal.
+         *
+         * @remarks
+         * Excel's Insert > Sparklines, and VBA's `Range.SparklineGroups.Add(Type, SourceData)`. The range
+         * is the location: one cell, or one row or one column of cells. The cells pair with the data as
+         * Excel pairs them:
+         * - One cell draws all of `data`, which must be one row or one column.
+         * - A column of cells draws a row of `data` each, its first cell the first row: `F2:F4` over
+         *   `A2:E4` draws `A2:E2`, `A3:E3`, `A4:E4`.
+         * - A row of cells draws a column each, the same way.
+         *
+         * Refused, as Excel refuses them: a location of several rows and columns, data that is a union
+         * or a table's structured reference, two-dimensional data for one cell, and data whose rows or
+         * columns do not number the cells. Also refused: a row of cells over data that only pairs by
+         * rows, which Excel draws a row each, transposed.
+         *
+         * A cell has one sparkline, so the cells leave any group they were in. Sparklines are drawn over
+         * the cells' values, which stay; refused on a protected sheet unless formatting cells is allowed.
+         *
+         * @example
+         * ```ts
+         * sheet.getRange('F2:F4').setSparkline('A2:E4', { type: 'column', high: true });
+         * sheet.getRange('F2:F4').setSparkline(null);
+         * ```
+         */
+        /**
+         * Returns the {@link ISparklineGroup}s with a sparkline in the range.
+         *
+         * @param options The filters of {@link ISparklineGroupCollection.getItems} without `address`;
+         * this range is the address.
+         *
+         * @remarks
+         * See {@link getConditionalFormats} for the overlap and one-entry-per-item rules, which are the
+         * same for every ranged item lookup. The groups, never one entry per sparkline: a column of a
+         * million sparklines is one group. Ask a cell for its own with {@link ICell.getSparkline}.
+         * VBA's `Range.SparklineGroups`.
+         */
+        getSparklineGroups(options?: ICellRange.GetItemsOptions<ISparklineGroupCollection.GetItemsOptions>): ISparklineGroup[];
+        setSparkline(data: ICellRange.Address | null, properties?: ISparklineGroup.Modifiers, options?: ITransaction.OperationOptions): ISparklineGroup | null;
         /**
          * Returns the {@link IDataValidation}s that overlap the range, in priority order.
          *
@@ -11407,6 +11490,11 @@ declare global {
              * question: ask for both to split a column of checkboxes from the text cells among them.
              */
             readonly CellControl: "cellControl";
+            /**
+             * Cells with a sparkline ({@link IWorksheet.getSparklineGroups}). Regions group by the
+             * sparkline group, so two groups side by side are two regions.
+             */
+            readonly Sparkline: "sparkline";
             /**
              * Cells where an error check fires — what breaks the pattern around it. Regions group by the
              * check and its evidence, so a filled row that breaks the same way is one region; the anchor
@@ -11733,6 +11821,18 @@ declare global {
              * An address rather than a range, because the cells at it now are other cells.
              */
             getPreviousAddress(): string | null;
+            /**
+             * The edits that changed the range's cells, in the order they were made, for an `'address'`
+             * event of a listener that asked for them ({@link ListenerOptions.edits}); empty otherwise.
+             *
+             * @remarks
+             * Where {@link getSource} says where the range landed, these say what happened to its cells on
+             * the way: each band inserted or deleted, and each cut that took some of them. A listener that
+             * keeps something per cell of the range - a reference, a mark - reads these to take each cell
+             * through on its own. An undo or a redo restores a revision rather than repeating the edits,
+             * so it has none.
+             */
+            getEdits(): readonly ICellRange.Edit[];
             /**
              * What happened to the range.
              *
@@ -11779,6 +11879,35 @@ declare global {
              */
             type Trigger = 'data' | 'address' | 'restore';
         }
+        /**
+         * One edit that changed a listened range's cells. See {@link ICellRange.Event.getEdits}.
+         */
+        type Edit = Edit.Shift | Edit.Move;
+        namespace Edit {
+            /**
+             * Cells inserted or deleted: `range` is the band, and `direction` the way the cells beside it
+             * shifted (`Down` or `Right` for an insert, `Up` or `Left` for a delete).
+             */
+            interface Shift {
+                readonly type: 'shift';
+                readonly range: IRange.Coords;
+                readonly direction: IRange.Direction;
+            }
+            /**
+             * Cells cut from `from` to `to`, taking all of the listened range or only some of it.
+             *
+             * @remarks
+             * A cut to another sheet names it as `toSheet`. A listener whose whole range was cut there
+             * goes with it: its source is on that sheet from then on.
+             */
+            interface Move {
+                readonly type: 'move';
+                readonly from: IRange.Coords;
+                readonly to: IRange.Coords;
+                /** The sheet the cells went to, when it is not the sheet they came from. */
+                readonly toSheet?: IWorksheet;
+            }
+        }
         /**
          * Called with what changed at a listened range. See {@link ICellRange.addListener}.
          *
@@ -11843,6 +11972,18 @@ declare global {
              * @defaultValue false
              */
             ignoreAddressChanges?: boolean;
+            /**
+             * Whether an `'address'` event carries the edits that changed the range's cells
+             * ({@link Event.getEdits}).
+             *
+             * @defaultValue false
+             *
+             * @remarks
+             * With it, the listener is also told of a cut that takes only some of its cells: the range
+             * itself stays (a cut moves a reference only when it takes all of it), but the cells it
+             * names were moved, and the event says where.
+             */
+            edits?: boolean;
             /**
              * How the listened range follows rows and columns inserted or deleted around it.
              *
@@ -37017,6 +37158,403 @@ declare global {
         }
     }
 
+    /**
+     * A group of sparklines drawn with the same properties: Excel's sparkline group.
+     *
+     * @remarks
+     * A sparkline is a small chart drawn in a cell, over the cell's own value. A group shares one
+     * type, one set of colors and markers, and one axis rule (`'group'` scales its sparklines
+     * together). It is anchored to its sparklines' cells, and moves and shrinks with them as rows and
+     * columns are inserted and deleted; each sparkline's data follows its own cells the way a formula
+     * does.
+     *
+     * * A cell has at most one sparkline.
+     * * The data is kept per range, relative to each cell: a column of 10,000 sparklines each reading
+     *   the five cells to its left is one range, and {@link getSparklines} answers each cell's own data.
+     */
+    export interface ISparklineGroup extends IAnchored {
+        /**
+         * The kind of chart the group draws.
+         */
+        getType(): ISparklineGroup.Type;
+        /**
+         * The properties every sparkline of the group draws with. Absent properties are their defaults.
+         */
+        getProperties(): Readonly<ISparklineGroup.Properties>;
+        /**
+         * The first range the group covers.
+         *
+         * @remarks
+         * See {@link IAnchored.getRanges} for all of them.
+         */
+        getRange(): ICellRange;
+        /**
+         * One sparkline per cell, in the order of the group's ranges.
+         */
+        getSparklines(): readonly ISparklineGroup.ISparkline[];
+        /**
+         * The sparkline at `index` in {@link getSparklines}, or `null` past the end.
+         */
+        getSparklineAt(index: number): ISparklineGroup.ISparkline | null;
+        /**
+         * The sparkline in `cell`, or `null` when the group has none there.
+         */
+        getSparkline(cell: ICellRange.Address): ISparklineGroup.ISparkline | null;
+        /**
+         * Changes the properties every sparkline of the group draws with.
+         *
+         * @param properties The properties to change; a property left out is left as it is, and `null`
+         * returns one to its default.
+         *
+         * @remarks
+         * Excel's Sparkline tab edits a group this way: a type, a color or a marker is the group's, never
+         * one sparkline's. Refused on a protected sheet unless formatting cells is allowed.
+         *
+         * @example
+         * ```ts
+         * group.update({ type: 'column', high: true, colorHigh: 'accent2' });
+         * group.update({ colorHigh: null }); // back to the default
+         * ```
+         */
+        update(properties: ISparklineGroup.Modifiers, options?: ITransaction.OperationOptions): this;
+        /**
+         * The cells the first range's sparklines draw.
+         *
+         * @remarks
+         * See {@link getDataRanges} for all of them.
+         */
+        getDataRange(): ICellRange;
+        /**
+         * The cells each range's sparklines draw, paired by position with {@link IAnchored.getRanges}:
+         * the cells they read together (`A2:E4` for `F2:F4` reading a row each), as Excel's Edit
+         * Sparklines dialog shows them.
+         *
+         * @remarks
+         * * **Never `null` entries.** Data whose cells are deleted is an *invalid* range; ask
+         *   {@link ICellRange.isInvalid}.
+         * * Each range is on its own sheet: one may read this sheet and another a different one.
+         * * {@link setDataRanges} and {@link setRanges} take this list back.
+         */
+        getDataRanges(): readonly ICellRange[];
+        /**
+         * Gives the group's cells new data, as Excel's `ModifySourceData` does.
+         *
+         * @param data The cells to draw, paired with the group's cells as {@link setRanges} pairs them.
+         *
+         * @remarks
+         * The group keeps its cells and properties. Refused, and the group left as it was, when the data
+         * does not pair with its cells.
+         */
+        setDataRanges(data: ICellRanges.Address, options?: ITransaction.OperationOptions): this;
+        /**
+         * Moves the group's sparklines to new cells, and optionally gives them new data, as Excel's Edit
+         * Sparklines dialog does (`ModifyLocation`, `Modify`).
+         *
+         * @param address The cells to draw in: one or more areas, each a cell, a row or a column of cells.
+         * @param data The cells to draw. Left out, the group's own data ({@link getDataRanges}) is paired
+         * with the new cells. Give both to change both at once: growing `F2:F4` reading `A2:E4` to `F2:F5`
+         * reading `A2:E5` pairs as one change and as neither change alone.
+         *
+         * @remarks
+         * The location's cells are taken in order, and the data pairs with them in one of three ways:
+         *
+         * * **One data area** goes to all of them together, as {@link ICellRange.setSparkline} pairs it:
+         *   `F2:F3,G5` with `A2:E4` reads a row each.
+         * * **One data area per location area**: `F2:F4,H6` with `A2:E4,A6:E6`.
+         * * **One data area per cell**: `F2:F4` with `A2:E2,A9:E9,A4:E4`.
+         *
+         * The group keeps its properties. A cell has one sparkline, so the new cells leave any other
+         * group they were in. Refused, and the group left as it was, when the data does not pair with the
+         * cells; refused on a protected sheet unless formatting cells is allowed.
+         *
+         * @example
+         * ```ts
+         * group.setRanges('H2:H4'); // the same data, drawn in H2:H4
+         * group.setRanges('F2:F5', 'A2:E5'); // one more sparkline
+         * ```
+         */
+        setRanges(address: ICellRanges.Address, data?: ICellRanges.Address | null, options?: ITransaction.OperationOptions): this;
+        /**
+         * Add Listeners.
+         *
+         * @see
+         * {@link IListener.ISource.addListeners}
+         */
+        addListeners(listeners: ISparklineGroup.IListeners, options?: IListener.Options): IListener.Remove;
+        /**
+         * The group as JSON: its properties and the data of each of its ranges, in order.
+         */
+        toJSON(): ISparklineGroup.JSON;
+        /**
+         * For runtime type checking.
+         */
+        readonly isISparklineGroup: true;
+    }
+
+    /**
+     * {@inheritDoc ISparklineGroup}
+     * @see
+     * ### **Interface**
+     *
+     * {@link ISparklineGroup}
+     *
+     * **Additional Interfaces**
+     * * {@link ISparklineGroup.ISparkline}
+     * * {@link ISparklineGroupCollection}
+     */
+    export namespace ISparklineGroup {
+        /**
+         * The kind of chart a group draws.
+         */
+        const Type: {
+            /** A line through the points. */
+            readonly Line: "line";
+            /** A column per point. */
+            readonly Column: "column";
+            /** A column up for a positive point and down for a negative one, all the same height. Excel's file calls it `stacked`. */
+            readonly WinLoss: "winLoss";
+        };
+        type Type = typeof Type[keyof typeof Type];
+        /**
+         * How the minimum or maximum of the vertical axis is chosen.
+         */
+        const AxisType: {
+            /** Each sparkline's own data. */
+            readonly Individual: "individual";
+            /** The data of every sparkline in the group, so they scale together. */
+            readonly Group: "group";
+            /** The value in `manualMin` or `manualMax`. */
+            readonly Custom: "custom";
+        };
+        type AxisType = typeof AxisType[keyof typeof AxisType];
+        /**
+         * How an empty cell in the data draws.
+         */
+        const EmptyCellsAs: {
+            /** A gap in the line. */
+            readonly Gap: "gap";
+            /** A zero. */
+            readonly Zero: "zero";
+            /** A line straight across to the next point. */
+            readonly Span: "span";
+        };
+        type EmptyCellsAs = typeof EmptyCellsAs[keyof typeof EmptyCellsAs];
+        /**
+         * What a group draws with. Every property is optional; an absent one is its default.
+         *
+         * @remarks
+         * The names are the file's (`CT_SparklineGroup`). Colors are color strings, theme-aware as the
+         * file is (`accent1 tint 0.4`).
+         */
+        interface Properties {
+            /** @defaultValue `'line'` */
+            type?: Type;
+            /** The line's weight in points. @defaultValue `0.75` */
+            lineWeight?: number;
+            /** @defaultValue `'zero'` */
+            displayEmptyCellsAs?: EmptyCellsAs;
+            /** A marker on every point of a line. @defaultValue `false` */
+            markers?: boolean;
+            /** The highest point in `colorHigh`. @defaultValue `false` */
+            high?: boolean;
+            /** The lowest point in `colorLow`. @defaultValue `false` */
+            low?: boolean;
+            /** The first point in `colorFirst`. @defaultValue `false` */
+            first?: boolean;
+            /** The last point in `colorLast`. @defaultValue `false` */
+            last?: boolean;
+            /** Negative points in `colorNegative`. @defaultValue `false` */
+            negative?: boolean;
+            /** A horizontal axis at zero, when zero is within the vertical range. @defaultValue `false` */
+            displayXAxis?: boolean;
+            /** Draw the values of hidden rows and columns. @defaultValue `false` */
+            displayHidden?: boolean;
+            /** Draw from right to left. @defaultValue `false` */
+            rightToLeft?: boolean;
+            /** @defaultValue `'individual'` */
+            minAxisType?: AxisType;
+            /** @defaultValue `'individual'` */
+            maxAxisType?: AxisType;
+            /** The minimum, when `minAxisType` is `'custom'`. */
+            manualMin?: number;
+            /** The maximum, when `maxAxisType` is `'custom'`. */
+            manualMax?: number;
+            /** Space the points by the dates in `dateRange`. @defaultValue `false` */
+            dateAxis?: boolean;
+            /** The cells holding the date of each point, as a formula; read when `dateAxis` is on. */
+            dateRange?: string;
+            colorSeries?: string;
+            colorNegative?: string;
+            colorAxis?: string;
+            colorMarkers?: string;
+            colorFirst?: string;
+            colorLast?: string;
+            colorHigh?: string;
+            colorLow?: string;
+            /**
+             * Attributes a file gave the group that are not modeled here, kept so a resave writes them back.
+             */
+            rest?: Record<string, string>;
+        }
+        /** The properties that are colors. */
+        type ColorKey = 'colorSeries' | 'colorNegative' | 'colorAxis' | 'colorMarkers' | 'colorFirst' | 'colorLast' | 'colorHigh' | 'colorLow';
+        /**
+         * What {@link ISparklineGroup.update} and a new group take: any of the {@link Properties}, a
+         * color as an {@link IColor} or a color string, and `null` to return a property to its default.
+         */
+        type Modifiers = {
+            [K in Exclude<keyof Properties, ColorKey | 'rest'>]?: Properties[K] | null;
+        } & {
+            [K in ColorKey]?: IColor | string | null;
+        };
+        /**
+         * A sparkline: one cell's view of its group.
+         *
+         * @remarks
+         * Transient and read-only, as `ITable.IColumn` is: it answers for the group as the group is when
+         * asked, and changes go through the group.
+         */
+        interface ISparkline {
+            /**
+             * The cell the sparkline draws in.
+             */
+            getRange(): ICellRange;
+            /**
+             * The cells the sparkline draws.
+             *
+             * @remarks
+             * * **Never `null`.** Once its cells are deleted it is an *invalid* range; ask
+             *   {@link ICellRange.isInvalid}.
+             * * The data follows its cells as a formula does, so this answers where they are now.
+             */
+            getDataRange(): ICellRange;
+            /**
+             * The sparkline laid out in a box: its line or columns, markers and axis, in px, with every
+             * color concrete. What a painter draws.
+             *
+             * @param size The box in px, unzoomed: the cell's.
+             *
+             * @remarks
+             * Read from its data now: the hidden rows and columns left out unless the group shows them,
+             * text and errors as empty cells. An axis whose type is `'group'` reads the data of the whole
+             * group.
+             *
+             * @example
+             * ```ts
+             * const layout = sheet.getSparklineGroups().getItems()[0].getSparklineAt(0)!.getLayout({ width: 64, height: 20 });
+             * console.log(layout.min, layout.max, layout.line?.runs.length);
+             * ```
+             */
+            getLayout(size: Size): SparklineLayout;
+            /**
+             * The group whose properties the sparkline draws with.
+             */
+            getGroup(): ISparklineGroup;
+            /**
+             * For runtime type checking.
+             */
+            readonly isISparkline: true;
+        }
+        /**
+         * A group as JSON.
+         */
+        interface JSON extends Properties {
+            /**
+             * The data, as a list of areas paired by position with the group's ranges: each the data the
+             * range's first cell draws (`A2:E2,A9:E9` for `F2:F4,G3`).
+             *
+             * @remarks
+             * Every other cell of a range draws the same area moved by its offset from the first cell, as a
+             * conditional format's formula is written for the first cell of its range: in `F2:F4` reading
+             * `A2:E2`, F3 draws `A3:E3`. An area on the group's own sheet is written without a sheet name.
+             * An empty area is a range with no data, which draws nothing (`F2:F4,G5` with `A2:E2,`).
+             */
+            data: string;
+        }
+        /**
+         * IListener for {@link ISparklineGroup} events.
+         */
+        interface Events extends IAnchored.Events<ISparklineGroup> {
+            /**
+             * Called when what {@link ISparklineGroup.ISparkline.getLayout} returns may have changed for any
+             * sparkline of the group: the group changed, a cell it reads changed (its value, or whether its
+             * row or column is hidden), or its theme changed. Call `getLayout` again to see the new layout.
+             *
+             * @remarks
+             * Cell changes are announced once per commit, after every cell of it has landed, so a
+             * `getLayout` from the listener reads the new values.
+             */
+            onLayoutChange?(source: ISparklineGroup): void;
+        }
+        interface IListeners extends IListener.Callbacks<ISparklineGroup, ISparklineGroup.Events> {
+        }
+    }
+
+    /**
+     * Holds a sheet's {@link ISparklineGroup}s.
+     *
+     * @remarks
+     * Most code reaches sparklines through the range instead: {@link ICellRange.setSparkline} puts them
+     * on cells. The collection is for listing every group, and for adding one at an address.
+     */
+    export interface ISparklineGroupCollection extends ICollection<ISparklineGroup> {
+        /**
+         * Adds a group of sparklines in the cells of `location`, each drawing its share of `data`, and
+         * returns it.
+         *
+         * @param location The cells the sparklines draw in: one row or one column of cells, or one cell.
+         * @param data The cells they draw. See {@link ICellRange.setSparkline} for how they pair.
+         * @param properties How they draw. A new group starts as Excel's does: empty cells as gaps,
+         * Excel's colors, and negative points colored for win/loss.
+         *
+         * @remarks
+         * The same write as {@link ICellRange.setSparkline}. A cell has one sparkline, so the cells leave
+         * any group they were in.
+         */
+        add(location: ICellRanges.Address, data: ICellRange.Address, properties?: ISparklineGroup.Modifiers, options?: ITransaction.OperationOptions): ISparklineGroup;
+        /**
+         * Returns items that match the filter criteria.
+         *
+         * If no filter criteria is provided, all items will be returned.
+         *
+         * @param options {@link ISparklineGroupCollection.GetItemsOptions}
+         */
+        getItems(options?: ISparklineGroupCollection.GetItemsOptions): ISparklineGroup[];
+        /** For runtime type checking. */
+        readonly isISparklineGroupCollection: true;
+    }
+
+    /**
+     * {@inheritDoc ISparklineGroupCollection}
+     * @see
+     * ### **Interface**
+     *
+     * {@link ISparklineGroupCollection}
+     */
+    export namespace ISparklineGroupCollection {
+        /**
+         * Options for searching for {@link ISparklineGroup}s.
+         */
+        interface GetItemsOptions extends ICollection.GetItemsOptions {
+            /**
+             * If provided, the search will be limited to groups with a sparkline in the range.
+             */
+            address?: ICellRange.Address;
+            /**
+             * Indicate if items that are in hidden headers should be returned.
+             *
+             * @defaultValue false
+             */
+            ignoreHidden?: boolean;
+            /**
+             * Only return items that are completely contained with the search bounds.
+             *
+             * @defaultValue false
+             */
+            fullyContained?: boolean;
+        }
+    }
+
     /**
      * A spinner: two arrows. Content type `'spinner'`.
      */
@@ -44750,6 +45288,14 @@ declare global {
          * {@link ICellRange.setControl} and {@link ICellRange.getControls}.
          */
         getCellControls(): ICellControlCollection;
+        /**
+         * Returns the sparkline groups on this sheet.
+         *
+         * @remarks
+         * A sparkline is a small chart drawn in a cell, over its value. Each group shares one type and
+         * one set of properties across its sparklines.
+         */
+        getSparklineGroups(): ISparklineGroupCollection;
         /**
          * Returns the comments and notes on this sheet.
          *
@@ -45540,6 +46086,10 @@ declare global {
              * Always accompanied by the coarse {@link onStyleChange}: a control is a format.
              */
             onCellControlsChange?(source: IWorksheet): void;
+            /**
+             * Called when a sparkline group is added, removed or re-anchored.
+             */
+            onSparklineGroupsChange?(source: IWorksheet): void;
             /**
              * Called when a comment is added, removed, edited, resolved, replied to or re-anchored.
              *
@@ -45984,6 +46534,10 @@ declare global {
             validationSettings?: IDataValidationCollection.Settings;
             protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
             cellControls?: IRange.JSONReference<ICellControl.JSON>[];
+            /**
+             * The sparkline groups. Each group's ranges pair by position with the areas of its `data`.
+             */
+            sparklineGroups?: IRange.JSONReference<ISparklineGroup.JSON>[];
             movables?: IMovable.JSON[];
             /**
              * The sheet's VBA code name. Absent when it has none.
@@ -50423,6 +50977,75 @@ declare global {
      */
     export function sourceEntryFromPath(path: string): IExternalBook.SourceEntry;
 
+    /**
+     * A sparkline laid out: its line, columns, markers and axis, in px from the cell's top-left. A
+     * painter translates it and decides nothing.
+     *
+     * @remarks
+     * Plain data, never stored on the model: it is computed from the sparkline's values, its group's
+     * properties, the theme and a size.
+     *
+     * - Every color is an {@link IColor} resolved against the workbook's theme. A painter draws it for
+     *   its mode, as cells are drawn: `color.toCSS()`, or `color.toRGBA(darkMode)` for a dark grid.
+     * - Every length is in px, a line's width included, which the group states in points.
+     * - What is drawn later is drawn over what is drawn earlier: the axis, then the columns or the
+     *   line, then the markers.
+     */
+    export interface SparklineLayout {
+        /** The cell's box in px. */
+        width: number;
+        height: number;
+        type: ISparklineGroup.Type;
+        /** Where the points are drawn: the box less its margins. */
+        plot: Bounds;
+        /** The axis at zero, when the group shows one and zero is within the vertical range. */
+        axis: SparklineLayout.Line | null;
+        /**
+         * The line through the points, broken where an empty cell is a gap: one array of points per
+         * unbroken run. `null` for columns and win/loss.
+         */
+        line: SparklineLayout.Polyline | null;
+        /** One per point drawn, for columns and win/loss; empty for a line. */
+        columns: SparklineLayout.Column[];
+        /** The line's markers and its highlighted points; empty for columns and win/loss. */
+        markers: SparklineLayout.Marker[];
+        /** The vertical range the values were scaled to; `null` when there is nothing to draw. */
+        min: number | null;
+        max: number | null;
+    }
+
+    export namespace SparklineLayout {
+        /** A straight line. */
+        interface Line {
+            from: Point;
+            to: Point;
+            color: IColor;
+            width: number;
+        }
+        /** A line through runs of points. */
+        interface Polyline {
+            /** Each unbroken run, in drawing order (left to right, or right to left). */
+            runs: Point[][];
+            color: IColor;
+            width: number;
+        }
+        /** A column (or a win/loss block). */
+        interface Column {
+            /** Which value of the sparkline's data it draws, in data order. */
+            index: number;
+            rect: Bounds;
+            color: IColor;
+        }
+        /** A marker on a point of a line. */
+        interface Marker {
+            /** Which value of the sparkline's data it marks, in data order. */
+            index: number;
+            center: Point;
+            radius: number;
+            color: IColor;
+        }
+    }
+
     /**
      * The **spreadsheet-language plane** of a language pack (I18N-DESIGN.md Plane 3): function names,
      * error values, boolean literals, and function help.