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

package/types/src/sparkline/SparklineGroup.d.ts

@@ -0,0 +1,271 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IWorksheet } from '../sheet';
+import { IStyleCollection } from '../style';
+import { IColor } from '../color';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { ISparklineGroup } from './ISparklineGroup';
+import * as SparklineRanges from './SparklineRanges';
+type SparklineRange = SparklineRanges.SparklineRange;
+/**
+ * Implementation of {@link ISparklineGroup}.
+ *
+ * @remarks
+ * The map anchors the group to its ranges' cells; the group keeps each range's location itself
+ * too, paired by position with the map's ranges, and the data each cell of it reads as an offset
+ * from that cell (`SparklineRanges`). A structural edit on the group's sheet, a cut of the data
+ * and a paste or fill rewrite the ranges here, a block at a time. Data on another sheet is
+ * listened to there (one range listener per sheet, over the cells the group reads on it, asking
+ * for the edits), which tells the group of each edit that reaches those cells.
+ */
+export declare class SparklineGroup extends AbstractAnchored<State, ISparklineGroup.Events> implements ISparklineGroup {
+    /** Per-entry moves of the shift in progress, read once the map makes its one write. */
+    private _pendingMoves;
+    /** The ranges once the structural edit in progress has gone through; `null` when it reaches none. */
+    private _plannedShift;
+    /** One listener per other sheet the data is on, over the cells the group reads there. */
+    private _dataListeners;
+    /** A sheet the data names that was not loaded yet when the group was made is looked for once more. */
+    private _lookedAgain;
+    constructor(options: SparklineGroup.ConstructorOptions);
+    /** @internal */
+    protected _initialize(options: SparklineGroup.ConstructorOptions): void;
+    /** Each of `coords` paired by position with the data its first cell reads, as the JSON states them. */
+    private _parseRanges;
+    /**
+     * Gives the group new ranges, each of `coords` reading `data` (its first cell's, paired by
+     * position as the JSON states them). The cells must not be another group's.
+     * @internal
+     */
+    _restate(coords: readonly IRange.Coords[], data: readonly string[]): void;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /**
+     * Always: a sparkline is the cell's, as a cell control is.
+     * @internal
+     */
+    protected _isAnchorAbsolute(): boolean;
+    private get _sparklineRanges();
+    private get _properties();
+    /** Puts `ranges` in the state, the map's ranges with them when they are not already. */
+    private _setRanges;
+    /** The worksheet a range's data names, when it is another sheet that is there. */
+    private _worksheetOf;
+    /** Listens to each other sheet the data is on, over the cells read there; lets go of the rest. */
+    private _syncDataListeners;
+    private _releaseDataListeners;
+    /** Each edit on `sheet` that reached the data read there, a sparkline at a time. */
+    private _onDataEdits;
+    /** How many listeners want `onLayoutChange`. */
+    private _layoutListeners;
+    /** What the layouts depend on, listened to only while something listens for `onLayoutChange`. */
+    private _layoutSources;
+    /** The cells the group reads, per sheet (its own included), listened to for their values. */
+    private _layoutCells;
+    /** The sheets those cells are on, listened to for their hidden rows and columns. */
+    private _layoutSheets;
+    /** An `onLayoutChange` is queued: one per commit, however many cells it reached. */
+    private _layoutQueued;
+    /**
+     * The extent of the group's values, for a `'group'` axis; `undefined` until read. Kept only while
+     * the layout is watched: nothing else says when it is stale.
+     */
+    private _extent;
+    /**
+     * Listens to the group, its theme, and the cells and sheets it reads while `onLayoutChange` has
+     * listeners.
+     */
+    private _watchLayout;
+    private _releaseLayoutSources;
+    /**
+     * What a layout reads may now read differently. The extent is dropped at once; listeners are
+     * told once the commit has landed every cell.
+     */
+    private _layoutChanged;
+    /**
+     * Listens to the cells the group reads on each sheet (a block per sheet: the union of its ranges'
+     * data there, and the date range), and to each such sheet's hidden rows and columns.
+     */
+    private _syncLayoutCells;
+    /** @internal */
+    protected _processDelete(): void;
+    /** @internal */
+    protected _processAfterStateChange(state: State, commit: ITransaction.ICommit, isRevert?: boolean, isRestore?: boolean): void;
+    /** @internal */
+    protected _isAnyChangeFromState(): boolean;
+    /** @internal */
+    protected _processRestoreOrRevert(state: State, commit: ITransaction.ICommit): void;
+    /** @internal */
+    protected _processClose(): void;
+    /** @internal */
+    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** @internal */
+    protected _processAfterContainerShift(before: IRange.Coords[] | null, after: IRange.Coords[] | null): void;
+    /**
+     * The group's sparklines within `coords` as ranges: each the part of one range there, reading as
+     * it does. A copy, a cut and a fill carry these.
+     * @internal
+     */
+    _rangesWithin(coords: IRange.Coords): SparklineRange[];
+    /**
+     * Adds `ranges` to the group, each joined to a range it continues (a fill down a range's column
+     * extends that range). The cells must not be the group's already.
+     * @internal
+     */
+    _addRanges(ranges: readonly SparklineRange[]): void;
+    /** The group's ranges as they are now, for a cut to put its own back in order. @internal */
+    _rangesNow(): readonly SparklineRange[];
+    /**
+     * Puts back the ranges a cut on the group's sheet moved `rows` down and `cols` across, each where
+     * its cells stood in `order` (the group's ranges when the cut was marked), as Excel keeps a cut
+     * sparkline's place in its group.
+     * @internal
+     */
+    _putBackCut(ranges: readonly SparklineRange[], order: readonly SparklineRange[], rows: number, cols: number): void;
+    /**
+     * Takes the ranges through a structural edit on the group's sheet, before the map applies it;
+     * {@link _settleShift} puts them in place once it has.
+     * @internal
+     */
+    _planShift(edits: readonly SparklineRanges.Edit[]): void;
+    /**
+     * The ranges {@link _planShift} planned, in place of the map's own shift of them.
+     *
+     * @returns The group's ranges when the edit reached it, for the map to take; `null` otherwise.
+     * @internal
+     */
+    _settleShift(): IRange.Coords[] | null;
+    /** `sheet` as a range's data names it: `null` for the group's own sheet. */
+    private _dataSheetOf;
+    /**
+     * After a cut on the group's sheet that left the group's cells where they are: each cell whose
+     * data the cut enclosed reads it where it went, on `toSheet` when it went to another sheet.
+     * @internal
+     */
+    _moveData(from: IRange.Coords, to: IRange.Coords, toSheet?: IWorksheet): void;
+    /** {@inheritDoc ISparklineGroup.getType} */
+    getType(): ISparklineGroup.Type;
+    /** {@inheritDoc ISparklineGroup.getProperties} */
+    getProperties(): Readonly<ISparklineGroup.Properties>;
+    /** {@inheritDoc ISparklineGroup.update} */
+    update(properties: ISparklineGroup.Modifiers, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ISparklineGroup.getDataRange} */
+    getDataRange(): ICellRange;
+    /** {@inheritDoc ISparklineGroup.getDataRanges} */
+    getDataRanges(): readonly ICellRange[];
+    /** Every cell `range`'s sparklines read: the union of their data, as one block. */
+    private _dataRangeOf;
+    /** {@inheritDoc ISparklineGroup.setDataRanges} */
+    setDataRanges(data: ICellRanges.Address, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ISparklineGroup.setRanges} */
+    setRanges(address: ICellRanges.Address, data?: ICellRanges.Address | null, options?: ITransaction.OperationOptions): this;
+    private _modify;
+    /** {@inheritDoc ISparklineGroup.getSparklines} */
+    getSparklines(): readonly ISparklineGroup.ISparkline[];
+    /** {@inheritDoc ISparklineGroup.getSparklineAt} */
+    getSparklineAt(index: number): ISparklineGroup.ISparkline | null;
+    /** {@inheritDoc ISparklineGroup.getSparkline} */
+    getSparkline(cell: ICellRange.Address): ISparklineGroup.ISparkline | null;
+    private _sparklineOf;
+    /** The cells of `coords` on the sheet `range`'s data is on; `null` when that sheet is gone. */
+    private _dataCells;
+    /** An address the group states (its `dateRange`): bare on its own sheet. */
+    private _resolve;
+    /**
+     * The extent of every value the group draws, for an axis whose type is `'group'`: one read of each
+     * range's data block, never one per sparkline. A range's block is exactly the cells its
+     * sparklines read, since each reads the same shape moved a cell at a time.
+     */
+    private _groupExtent;
+    /** The group's extent: kept while the layout is watched, read afresh otherwise. */
+    private _watchedExtent;
+    private _layoutOf;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: ISparklineGroup.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ISparklineGroup.toJSON} */
+    toJSON(): ISparklineGroup.JSON;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** {@inheritDoc ISparklineGroup.isISparklineGroup} */
+    get isISparklineGroup(): true;
+}
+/**
+ * Interfaces for creating a {@link SparklineGroup}.
+ */
+export declare namespace SparklineGroup {
+    interface ConstructorOptions extends Anchored.ConstructorOptions<ISparklineGroup.JSON> {
+        /** The group's sheet's name: data naming it is the group's own, and saved bare. */
+        getSheetName?: () => string;
+        /** The sheet a data area's prefix names, for data on another sheet. */
+        resolveSheet?: (name: string) => IWorksheet | null;
+        /** Resolves a data area against the workbook, for data on another sheet. */
+        resolveRange?: (address: string) => ICellRange | null;
+        /** The workbook's styles, whose theme the group's colors resolve against. */
+        getStyles?: () => IStyleCollection | null;
+        /**
+         * The sheet's write behind {@link ISparklineGroup.setRanges}: it pairs the cells with the
+         * data and takes them out of the sheet's other groups.
+         */
+        modify?: (group: SparklineGroup, location: ICellRanges.Address | null, data: ICellRanges.Address | null, options?: ITransaction.OperationOptions) => void;
+    }
+    /**
+     * The values in `cells`, row by row, as a sparkline draws them: hidden rows and columns left out
+     * unless the group shows them; each cell as a chart plots it ({@link plotValue}).
+     */
+    function readValues(cells: ICellRange, properties: Readonly<ISparklineGroup.Properties>): (number | null)[];
+    /**
+     * A cell as a point, as a chart plots it (measured for charts, 2026-10-16): a blank and `#N/A` are
+     * empty cells, drawn by the group's empty-cell rule; `TRUE` is 1; text and any other error are 0.
+     * Text as 0 is measured for sparklines too (a group over `a, 1` draws a line up from 0, whatever
+     * the empty-cell rule, Michael 2026-11-07).
+     */
+    function plotValue(cell: Scalar): number | null;
+    /**
+     * What Excel's `SparklineGroups.Add` writes for a new group (measured, DESIGN-SPARKLINES §1):
+     * empty cells as gaps, its eight colors, and negative points colored for win/loss.
+     */
+    function freshProperties(type?: ISparklineGroup.Type): Readonly<ISparklineGroup.Properties>;
+    /**
+     * `properties` with `modifiers` applied: a property named is set, `null` removes it (back to its
+     * default), a color is kept as its string. Refuses a value the property cannot take.
+     */
+    function applyModifiers(properties: Readonly<ISparklineGroup.Properties>, modifiers: ISparklineGroup.Modifiers): Readonly<ISparklineGroup.Properties>;
+    /** A color as the group states it, resolved against the theme; an unreadable one is black. */
+    function toColor(color: string, styles: IStyleCollection | null): IColor;
+    /**
+     * A group's JSON as its frozen properties and the data of each range.
+     *
+     * @throws when `json` has no data.
+     */
+    function splitJSON(json: ISparklineGroup.JSON | null | undefined): {
+        properties: Readonly<ISparklineGroup.Properties>;
+        data: readonly string[];
+    };
+    /** @internal */
+    function locationsOf(ranges: readonly SparklineRange[]): IRange.Coords[];
+    /**
+     * The ranges once the map has replaced the group's ranges with a part of themselves: each piece
+     * reads as the range it is a piece of. A range with no piece left is gone.
+     * @internal
+     */
+    function followTrim(ranges: readonly SparklineRange[], after: readonly IRange.Coords[]): readonly SparklineRange[];
+    /**
+     * The ranges once a shift has moved their cells: each found by its location in `moves`. When the
+     * result does not account for every range, the ranges pair with `after` by position instead.
+     * @internal
+     */
+    function followShift(ranges: readonly SparklineRange[], moves: readonly {
+        before: IRange.Coords;
+        after: IRange.Coords | null;
+    }[], after: readonly IRange.Coords[]): readonly SparklineRange[];
+}
+/** @internal */
+interface State extends AbstractAnchored.State {
+    json: Readonly<ISparklineGroup.Properties>;
+    ranges: readonly SparklineRange[];
+}
+export {};
+//# sourceMappingURL=SparklineGroup.d.ts.map

package/types/src/sparkline/SparklineGroupCollection.d.ts

@@ -0,0 +1,25 @@
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ISparklineGroupCollection } from './ISparklineGroupCollection';
+import { ISparklineGroup } from './ISparklineGroup';
+/**
+ * Implementation for {@link ISparklineGroupCollection}: a front over the sheet's own state, as
+ * the cell-control collection is.
+ */
+export declare class SparklineGroupCollection extends AbstractCollection<ISparklineGroup, ISparklineGroupCollection.GetItemsOptions> implements ISparklineGroupCollection {
+    private _add;
+    private _get;
+    private _addListeners;
+    constructor(add: (location: ICellRanges.Address, data: ICellRange.Address, properties?: ISparklineGroup.Modifiers, options?: ITransaction.OperationOptions) => ISparklineGroup, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => ISparklineGroup[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
+    /** {@inheritDoc ISparklineGroupCollection.add} */
+    add(location: ICellRanges.Address, data: ICellRange.Address, properties?: ISparklineGroup.Modifiers, options?: ITransaction.OperationOptions): ISparklineGroup;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ISparklineGroupCollection.GetItemsOptions): ISparklineGroup[];
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ISparklineGroupCollection.isISparklineGroupCollection} */
+    get isISparklineGroupCollection(): true;
+}
+//# sourceMappingURL=SparklineGroupCollection.d.ts.map

package/types/src/sparkline/SparklineRanges.d.ts

@@ -0,0 +1,195 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * A group's ranges and the data each cell of them reads.
+ *
+ * A range is a block of sparkline cells - a column, a row or 2D - and its data is an offset from
+ * the cell: F2 reading `A2:E2` reads rows `+0..+0` and columns `-5..-1` of itself, and so does
+ * every other cell of its range. What a cell reads is its position plus the offset, so nothing
+ * absolute is kept per cell, and every operation here costs the number of ranges and edits, never
+ * the number of cells.
+ */
+/** The sheet a range's data is on, when it is not the group's own. */
+export interface DataSheet {
+    getName(): string;
+    isDeleted?(): boolean;
+}
+/** Data each cell finds at its own position plus `offset`; `sheet` is `null` for the group's own sheet. */
+export interface OffsetData {
+    offset: IRange.Coords;
+    sheet: DataSheet | null;
+}
+/** Data that is not a plain area (a name, `#REF!`): every cell reads `text`. */
+export interface TextData {
+    text: string;
+}
+export type Data = OffsetData | TextData;
+/** A block of sparkline cells and the data each of them reads. */
+export interface SparklineRange {
+    location: IRange.Coords;
+    data: Data;
+}
+/** A plain area as text: the sheet prefix as written (`'Q1 Data'!`, or empty) and the area. */
+export interface Area {
+    /** The text before the area, its `!` included; empty when the area names no sheet. */
+    prefix: string;
+    coords: IRange.FixableCoords;
+}
+/** One band of a structural edit, as the sheet's shift applies it. */
+export interface Edit {
+    range: IRange.Coords;
+    direction: IRange.Direction;
+}
+export declare const isOffsetData: (data: Data) => data is OffsetData;
+/** `text` as one plain area, or `null` for anything else: a name, a union, a function, `#REF!`. */
+export declare function parseArea(text: string | null | undefined): Area | null;
+/** The sheet name a prefix (`'Q1 ''Data'''!`, `Sheet1!`) spells, unquoted; `null` for none. */
+export declare function sheetNameOf(prefix: string): string | null;
+/**
+ * The data `text` names, read at the cell `at`.
+ *
+ * @param sheetOf The sheet a prefix names: `null` for the group's own, so own data is bare.
+ */
+export declare function toData(text: string, at: IRange.CellCoords, sheetOf: (name: string) => DataSheet | null): Data;
+/** The cells `data` names for the cell `at`; `null` when they are off the sheet. */
+export declare function dataCoordsAt(data: OffsetData, at: IRange.CellCoords): IRange.Coords | null;
+/** What the cell `at` reads, as text: bare on the group's own sheet, as Excel's dialog shows it. */
+export declare function dataText(data: Data, at: IRange.CellCoords): string;
+/** What the range's first cell reads: the range's data as the JSON spells it. */
+export declare function firstText(range: SparklineRange): string;
+/** How many sparklines a range holds. */
+export declare function cellCount(location: IRange.Coords): number;
+/** The cell `index` names within `location`, row by row. */
+export declare function cellAt(location: IRange.Coords, index: number): IRange.CellCoords;
+/** The position of `cell` within `location`, row by row. */
+export declare function indexOf(location: IRange.Coords, cell: IRange.CellCoords): number;
+/** Whether every cell reads the same way under `a` as under `b`. */
+export declare function isSameData(a: Data, b: Data): boolean;
+/** `a` and `b` as one range: their cells make one block and read alike. `null` otherwise. */
+export declare function joinRanges(a: SparklineRange, b: SparklineRange): SparklineRange | null;
+/** `ranges` with each joined to the one before it where they make one range; in order. */
+export declare function fold(ranges: readonly SparklineRange[]): SparklineRange[];
+/** `existing` with `added` appended, each joined to a range it continues (a fill down a column). */
+export declare function addRanges(existing: readonly SparklineRange[], added: readonly SparklineRange[]): SparklineRange[];
+/**
+ * Where `cell` stands in the order of `ranges`' sparklines (ranges in order, row by row within
+ * each); `Infinity` when no range holds it.
+ */
+export declare function orderOf(ranges: readonly SparklineRange[], cell: IRange.CellCoords): number;
+/**
+ * `current` with `moved` put back where their cells stood in `order`, as Excel keeps a cut
+ * sparkline's place in its group. `rows` and `cols` are how far the cut moved them.
+ */
+export declare function putBack(current: readonly SparklineRange[], moved: readonly SparklineRange[], order: readonly SparklineRange[], rows: number, cols: number): SparklineRange[];
+/** `range` clipped to `within`; `null` when none of its cells are there. */
+export declare function clipRange(range: SparklineRange, within: IRange.Coords): SparklineRange | null;
+/** The ranges within `coords`: each the part of one range there, reading as it does. */
+export declare function rangesWithin(ranges: readonly SparklineRange[], coords: IRange.Coords): SparklineRange[];
+/**
+ * Copies `first` through `first + count - 1` of `range`, each `step` cells further along `axis`;
+ * the data reads the same way from each copy, as a copied formula's relative references do. One
+ * range when the copies abut - a column repeated down its own column - however many there are;
+ * one per copy otherwise, each its own range as it is in `getRanges()`.
+ */
+export declare function repeatRange(range: SparklineRange, first: number, count: number, step: number, axis: 'row' | 'col'): SparklineRange[];
+/**
+ * `ranges`, marked within `from`, pasted over `to`.
+ *
+ * @remarks
+ * A copy tiles with the source's period and is clipped to `to`, as a paste tiles cells; each cell
+ * reads relative to itself, as a copied formula does, so the data offset is unchanged. A cut lands
+ * once and keeps each cell's data where it was, unless the cut encloses that data on the source
+ * sheet: then the data goes with the cut.
+ *
+ * @param options.sourceSheet The source sheet, for a paste onto another sheet: data on the
+ * source's own sheet names it there.
+ */
+export declare function pasteRanges(ranges: readonly SparklineRange[], from: IRange.Coords, to: IRange.Coords, options: {
+    isCut: boolean;
+    sourceSheet: DataSheet | null;
+}): SparklineRange[];
+/**
+ * `range` once a cut on the sheet its data is on has moved the cells `from` to `to` and left the
+ * range's own cells where they are: a cell whose data the cut encloses reads it where it went.
+ * `null` when the cut encloses none of its data.
+ *
+ * @param toSheet The sheet the cells went to, when the cut took them to another sheet: `null`
+ * for the group's own sheet.
+ */
+export declare function moveData(range: SparklineRange, from: IRange.Coords, to: IRange.Coords, toSheet?: DataSheet | null): SparklineRange[] | null;
+/**
+ * `coords` through `edit` as the engine rewrites a reference to them: moved, grown or trimmed on
+ * the shifted axis, `null` when the delete takes all of it, the same object when the edit does not
+ * reach it. The edit reaches a reference that meets the band's span across and lies at or past
+ * the band along the shift.
+ */
+export declare function shiftCoords(coords: IRange.Coords, edit: Edit): IRange.Coords | null;
+/**
+ * `range` through `edits` on its own sheet, as Excel takes each sparkline through them - its cell
+ * moves with the cell, its data is rewritten on its own (`#REF!` when the edit deletes it) - as
+ * ranges again, joined where they read alike. `null` when the edits reach neither its cells nor
+ * its data. Data on another sheet is not rewritten by them.
+ */
+export declare function followEdits(range: SparklineRange, edits: readonly Edit[]): SparklineRange[] | null;
+/**
+ * `range` through `edits` on the other sheet its data is on: its cells stay, each cell's data is
+ * rewritten on its own. `null` when the edits reach none of its data.
+ */
+export declare function followDataEdits(range: SparklineRange, edits: readonly Edit[]): SparklineRange[] | null;
+/** The cells every cell of `range` reads, as one block; `null` for data that is not an area. */
+export declare function dataBlock(range: SparklineRange): IRange.Coords | null;
+/** Why a location and its data do not make sparklines, as {@link pairData} answers. */
+export type PairRefusal = 
+/** The location is more than one row and more than one column. */
+'location2D'
+/** One sparkline over data that is more than one row and more than one column. */
+ | 'data2D'
+/** Neither the data's rows nor its columns number the location's cells. */
+ | 'count'
+/** Excel pairs each sparkline with a row of the data across a row of cells (or a column down a column): no one offset. */
+ | 'transposed';
+/**
+ * The cells `location`'s first cell reads when `data` is given to the whole location, as Excel's
+ * `SparklineGroups.Add` pairs them (measured, DESIGN-SPARKLINES §1); each other cell reads it moved
+ * by its offset from the first. Or why they do not pair.
+ *
+ * @remarks
+ * One sparkline reads all of a one-row or one-column `data`. Several pair with the data's rows
+ * when they are as many, else with its columns, so a square block pairs by rows. One column longer
+ * than a column of cells gives each a window of it, one row further down per cell (`A1:A7` over
+ * `F2:F4` reads `A1:A5`, `A2:A6`, `A3:A7`), and a row across a row of cells likewise: what Excel
+ * refuses, and what a group of such windows reads back as.
+ */
+export declare function pairData(location: IRange.Coords, data: IRange.Coords): {
+    first: IRange.Coords;
+} | {
+    refused: PairRefusal;
+};
+/** A location paired with its data: the cells its first cell reads, in `data[dataIndex]`'s sheet. */
+export interface AreaPair {
+    location: IRange.Coords;
+    first: IRange.Coords;
+    dataIndex: number;
+}
+/**
+ * Pairs a list of location areas with a list of data areas, as Excel's Edit Sparklines dialog
+ * (`SparklineGroup.Modify`) does where it answers (measured, DESIGN-SPARKLINES §1):
+ *
+ * * **One data area** is given to all the location cells together, in order, by {@link pairData}'s
+ *   rule: `F2:F3,G5` with `A2:E4` reads a row each.
+ * * **As many data areas as location areas** pair area by area: `F2:F4,H6` with `A2:E4,A6:E6`
+ *   (Excel crashes on this one).
+ * * **As many data areas as location cells** give one to each: `F2:F4` with
+ *   `A2:E2,A9:E9,A4:E4`.
+ *
+ * Anything else is refused as `count`, where Excel drops the extra data areas without a word.
+ *
+ * @remarks
+ * Costs the areas given, never the cells: a location area that the data names cell by cell is
+ * split, but then the data lists every one of its cells already.
+ */
+export declare function pairAreas(locations: readonly IRange.Coords[], data: readonly IRange.Coords[]): {
+    pairs: AreaPair[];
+} | {
+    refused: PairRefusal;
+};
+//# sourceMappingURL=SparklineRanges.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './ISparklineGroup';
+export * from './ISparklineGroupCollection';
+export type { SparklineLayout } from './layout';
+//# sourceMappingURL=index.d.ts.map

package/types/src/sparkline/layout/SparklineLayout.d.ts

@@ -0,0 +1,71 @@
+import { Bounds, Point } from '@sheetxl/utils';
+import { IColor } from '../../color';
+import { ISparklineGroup } from '../ISparklineGroup';
+/**
+ * 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 declare 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;
+    }
+}
+//# sourceMappingURL=SparklineLayout.d.ts.map

package/types/src/sparkline/layout/_layoutSparkline.d.ts

@@ -0,0 +1,42 @@
+import { IColor } from '../../color';
+import { ISparklineGroup } from '../ISparklineGroup';
+import { SparklineLayout } from './SparklineLayout';
+/** What a sparkline draws: its values, in data order. */
+export interface SparklineData {
+    /**
+     * A number per cell of the data, hidden cells already left out unless the group shows them;
+     * `null` for an empty cell (a blank, `#N/A`), which the empty-cell rule draws.
+     */
+    values: readonly (number | null)[];
+    /** Per value, its date when the group spaces points by date. Absent: evenly spaced. */
+    dates?: readonly (number | null)[] | null;
+}
+export interface SparklineLayoutOptions {
+    /** The cell's box in px. */
+    width: number;
+    height: number;
+    properties: Readonly<ISparklineGroup.Properties>;
+    /** A color as the group states it (`accent1 tint 0.4`, `#376092`), resolved against the theme. */
+    color: (color: string) => IColor;
+    /**
+     * The extent of the group's values, used for an axis whose type is `'group'`; see
+     * {@link sparklineExtent}. Absent, such an axis scales to the sparkline's own values.
+     */
+    groupExtent?: {
+        min: number;
+        max: number;
+    } | null;
+}
+/** The colors Excel's fresh group writes, for a group that states none. */
+export declare const DEFAULT_SPARKLINE_COLORS: Readonly<Record<'colorSeries' | 'colorNegative' | 'colorAxis' | 'colorMarkers' | 'colorFirst' | 'colorLast' | 'colorHigh' | 'colorLow', string>>;
+/**
+ * The min and max of the values a sparkline draws, `null` when it draws none: what a group whose
+ * axis type is `'group'` folds over its sparklines.
+ */
+export declare function sparklineExtent(data: SparklineData, properties: Readonly<ISparklineGroup.Properties>): {
+    min: number;
+    max: number;
+} | null;
+/** Lays out one sparkline. */
+export declare function layoutSparkline(data: SparklineData, options: SparklineLayoutOptions): SparklineLayout;
+//# sourceMappingURL=_layoutSparkline.d.ts.map

package/types/src/sparkline/layout/index.d.ts

@@ -0,0 +1,2 @@
+export type { SparklineLayout } from './SparklineLayout';
+//# sourceMappingURL=index.d.ts.map