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

package/types/src/sheet/_ListenerAnchor.d.ts

@@ -4,6 +4,7 @@ import { IListener } from '../listener';
 import { IAnchored } from '../anchored/IAnchored';
 import { Anchored } from '../anchored/Anchored';
 import { ICellRange, ICellRanges } from '../cellRange';
+import { IWorksheet } from './IWorksheet';
 /**
  * The reference a range listener watches, as an entry in a versioned anchored map.
  *
@@ -44,6 +45,19 @@ export declare class ListenerAnchor implements IAnchored {
     /**
      * What the listener asked for when it registered.
      */
+    /** The edits since the last `'address'` delivery, for a listener that asked for them. */
+    protected _edits: ICellRange.Edit[];
+    /**
+     * Told of each band of a structural edit that reaches the node, before the map moves it; kept
+     * for a listener that asked for the edits ({@link ICellRange.ListenerOptions.edits}).
+     */
+    noteShift(details: ISpatialMap.ShiftDetails): void;
+    /** Told of a cut that takes some or all of the node's cells; `toSheet` when it went to another sheet. */
+    noteMove(from: IRange.Coords, to: IRange.Coords, toSheet?: IWorksheet): void;
+    /** Whether edits wait to be delivered, so a cut that left the reference where it was is told. */
+    hasEdits(): boolean;
+    /** The edits waiting, handed over once. */
+    takeEdits(): readonly ICellRange.Edit[];
     getListenerOptions(): ICellRange.ListenerOptions;
     /** {@inheritDoc IAnchored.getRanges} */
     getRanges(): ICellRanges;

package/types/src/sheet/_SheetStateTypes.d.ts

@@ -14,6 +14,7 @@ import { IConditionalFormat } from '../conditionalFormat';
 import { IDataValidation } from '../dataValidation';
 import { IProtectedRange } from '../protectedRange';
 import { ICellControl } from '../cellControl';
+import { ISparklineGroup } from '../sparkline';
 import { IPivotTable } from '../pivot';
 import { ICell } from '../cell';
 import { IgnoredErrors } from './_IgnoredErrors';
@@ -165,6 +166,10 @@ export declare namespace RangeState {
          * first wins (`ICell.getControl`).
          */
         cellControls?: ICellControl | ICellControl[];
+        /**
+         * The cell's sparkline group. A cell has at most one sparkline.
+         */
+        sparklineGroups?: ISparklineGroup | ISparklineGroup[];
         /**
          * The per-feature direct styles for a collection of cells (SHEET-STYLE-SPLIT). These are the
          * user-authored style, kept DISCRETE — `borderStyle` carries `borders`, `fillStyle` carries `fill`,
@@ -296,6 +301,7 @@ export declare namespace RangeState {
         readonly Contentful: "contentful";
         readonly Conditionals: "conditionals";
         readonly CellControls: "cellControls";
+        readonly Sparklines: "sparklineGroups";
         /**
          * Has a formula
          */
@@ -480,6 +486,13 @@ export interface State {
      * Read through `RangeState.Type.CellControls` — see {@link RangeState.Intersection.cellControls}.
      */
     cellControls: IAnchoredMap<ICellControl, ICellControl.JSON>;
+    /**
+     * The sparkline groups.
+     *
+     * @remarks
+     * Read through `RangeState.Type.Sparklines` — see {@link RangeState.Intersection.sparklineGroups}.
+     */
+    sparklineGroups: IAnchoredMap<ISparklineGroup, ISparklineGroup.JSON>;
     /**
      * The reference each range listener watches.
      *

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

@@ -0,0 +1,338 @@
+import { Size } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { IAnchored } from '../anchored';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IColor } from '../color';
+import { IListener } from '../listener';
+import { SparklineLayout } from './layout';
+/**
+ * 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 declare 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> {
+    }
+}
+//# sourceMappingURL=ISparklineGroup.d.ts.map

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

@@ -0,0 +1,68 @@
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ICollection } from '../type';
+import { ITransaction } from '../transaction';
+import { ISparklineGroup } from './ISparklineGroup';
+/**
+ * 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 declare 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;
+    }
+}
+//# sourceMappingURL=ISparklineGroupCollection.d.ts.map