@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/outline/IOutline.d.ts

@@ -0,0 +1,186 @@
+import { IRange } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+/**
+ * The row and column groups on a sheet, and how they are laid out.
+ *
+ * @remarks
+ * There is no group object to create or delete. Every row and column carries an outline level,
+ * `0` to `7` ({@link ICellHeader.getOutlineLevel}), and a group at level *n* is a run of
+ * consecutive rows (or columns) whose level is *n* or more. Its summary row is the one just past
+ * the run, on the side {@link getSummaryDirection} names. Collapsing a group hides its detail rows.
+ *
+ * Groups are made and removed with {@link ICellRange.group} and {@link ICellRange.ungroup}, or
+ * from the sheet's formulas with {@link autoOutline}, and collapsed and expanded with
+ * {@link ICellRange.hideGroupDetails} and {@link ICellRange.showGroupDetails}. Whether the symbols are drawn
+ * is the view's: {@link IWorksheetView.setShowOutlineSymbols}.
+ *
+ * The counterpart of Excel's `Worksheet.Outline`.
+ */
+export interface IOutline extends IListener.ISource<IOutline, IOutline.Events> {
+    /**
+     * Where a group's summary sits: `down` or `up` for rows, `right` or `left` for columns.
+     *
+     * @defaultValue `down` for rows, `right` for columns.
+     */
+    getSummaryDirection(axis: IRange.Axis): IRange.Direction;
+    /**
+     * Sets where a group's summary sits.
+     *
+     * @throws `Error` If the direction does not belong to the axis (`left` for rows).
+     */
+    setSummaryDirection(axis: IRange.Axis, direction: IRange.Direction, options?: ITransaction.OperationOptions): this;
+    /**
+     * Whether the automatic outline styles are applied to summary rows and columns.
+     *
+     * @defaultValue false
+     */
+    isAutomaticStyles(): boolean;
+    /**
+     * Sets whether the automatic outline styles are applied.
+     */
+    setAutomaticStyles(automatic: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * The deepest outline level in use on the axis; `0` when nothing is grouped.
+     */
+    getLevelCount(axis: IRange.Axis): number;
+    /**
+     * The groups on an axis, outermost level first and in order within a level.
+     *
+     * @param axis The axis.
+     * @param options Limits the groups returned.
+     */
+    getGroups(axis: IRange.Axis, options?: IOutline.GetGroupsOptions): readonly IOutline.Group[];
+    /**
+     * Expands the groups up to a level and collapses everything deeper, as the level buttons do.
+     *
+     * @param axis The axis.
+     * @param levels How many levels stay visible, from `1` (only the outermost summaries); more levels
+     * than exist shows every row or column.
+     *
+     * @remarks
+     * The counterpart of Excel's `Outline.ShowLevels` and Office Scripts' `showOutlineLevels`, one
+     * axis at a time.
+     */
+    setVisibleLevels(axis: IRange.Axis, levels: number, options?: ITransaction.OperationOptions): this;
+    /**
+     * Removes every outline level from the sheet. Hidden rows and columns stay hidden.
+     *
+     * @param axes Which levels to remove. Default `IRange.AxisSelection.Both`.
+     * @returns The current `IOutline`.
+     * @throws `Error` If the sheet is protected.
+     *
+     * @remarks
+     * The whole-sheet form of {@link ICellRange.clearGroups}, which is what Excel's Clear Outline
+     * does with one cell selected.
+     */
+    clear(axes?: IRange.AxisSelection, options?: ITransaction.OperationOptions): this;
+    /**
+     * Outlines the sheet from its formulas: a cell whose formula totals the cells on one side of it
+     * in its own column makes its row a summary row and those rows a group, and the same for
+     * columns.
+     *
+     * @returns The current `IOutline`.
+     * @throws `Error` If no summary rows or columns are found, or the sheet is protected.
+     *
+     * @remarks
+     * The counterpart of Excel's `Range.AutoOutline`, which outlines the whole sheet whatever the
+     * range. Any outline the sheet already has is removed first, and the summary direction of each
+     * axis is set to where its first summary sits: below and right, or above and left.
+     */
+    autoOutline(options?: ITransaction.OperationOptions): this;
+    /**
+     * The settings that differ from their defaults, or `null` when none do.
+     *
+     * @remarks
+     * The levels themselves are saved with the rows and columns, not here.
+     */
+    toJSON(): IOutline.JSON | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIOutline: true;
+}
+/**
+ * {@inheritDoc IOutline}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IOutline}
+ */
+export declare namespace IOutline {
+    /**
+     * A group of rows or columns.
+     */
+    interface Group {
+        /**
+         * The level, from `1`; level 1 is the outermost.
+         */
+        level: number;
+        /**
+         * The first detail row or column.
+         */
+        start: number;
+        /**
+         * The last detail row or column, inclusive.
+         */
+        end: number;
+        /**
+         * The summary row or column, or `null` when the group runs to the edge of the sheet on the
+         * summary side.
+         */
+        summary: number | null;
+        /**
+         * Whether the details are collapsed: every one of them is hidden, whoever hid them.
+         *
+         * @remarks
+         * Read from the hidden details, as Excel reads it. A group whose summary is itself hidden,
+         * inside a collapsed outer group, reads collapsed only when it was collapsed before the outer
+         * one; expanding the outer group leaves such a group collapsed and opens the rest.
+         */
+        collapsed: boolean;
+    }
+    /**
+     * Options for {@link IOutline.getGroups}.
+     */
+    interface GetGroupsOptions {
+        /**
+         * Only this level. Omitted returns every level.
+         */
+        level?: number;
+        /**
+         * Only groups that meet the span from here (a viewport). Includes the summary.
+         */
+        from?: number;
+        /**
+         * Only groups that meet the span to here, inclusive.
+         */
+        to?: number;
+    }
+    /**
+     * The outline settings that differ from their defaults.
+     */
+    interface JSON {
+        /**
+         * Present, as `up`, when a group's summary row sits above its details.
+         */
+        summaryRow?: 'up';
+        /**
+         * Present, as `left`, when a group's summary column sits left of its details.
+         */
+        summaryColumn?: 'left';
+        /**
+         * Present, as `true`, when the automatic outline styles are applied.
+         */
+        automaticStyles?: true;
+    }
+    interface Events {
+        /**
+         * Called when the outline changes: its settings, a level, or which details are shown.
+         */
+        onOutlineChange?(source: IOutline): void;
+    }
+    interface IListeners extends IListener.Callbacks<IOutline, IOutline.Events> {
+    }
+}
+//# sourceMappingURL=IOutline.d.ts.map

package/types/src/outline/Outline.d.ts

@@ -0,0 +1,157 @@
+import { IRange } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
+import { ITypes } from '../type';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { IWorksheet } from '../sheet/IWorksheet';
+import { IOutline } from './IOutline';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { SheetHeader } from '../sheetHeader/SheetHeader';
+import type * as _HeaderUtils from '../sheetHeader/_HeaderUtils';
+type HeaderRun = ITypes.RunCoordValue<_HeaderUtils.CellHeaderState>;
+/**
+ * The groups on one axis, derived from that axis's header runs.
+ */
+interface AxisGroups {
+    runs: readonly HeaderRun[];
+    direction: IRange.Direction;
+    entireMax: number;
+    /** Per level, `byLevel[level - 1]`, ordered and non-overlapping within a level. */
+    byLevel: IOutline.Group[][];
+}
+interface State {
+    summaryRow: IRange.Direction;
+    summaryColumn: IRange.Direction;
+    automaticStyles: boolean;
+}
+/** A summary line and the detail lines it totals, found by {@link Outline.autoOutline}. */
+interface SummarySpan {
+    summary: number;
+    start: number;
+    end: number;
+}
+/**
+ * The outline of a sheet.
+ *
+ * @remarks
+ * Holds only the settings. The levels and collapsed flags live on the header runs, and the groups
+ * are derived from those runs (runs × levels, never a row walk), cached against the run array,
+ * which the headers replace rather than mutate.
+ *
+ * Whether a group is collapsed is derived too, as Excel derives it: its details are all hidden,
+ * and either its summary is showing or the summary carries the collapsed flag. The flag is what
+ * tells an inner group that was collapsed from one that was merely hidden with its outer group,
+ * so it is recorded on every collapsed inner summary before an outer group hides it.
+ */
+export declare class Outline implements IOutline {
+    protected _options: Outline.ConstructorOptions;
+    protected _transactions: ITransaction.IStore;
+    protected _id: string;
+    protected _emitter: ListenerEmitter<IOutline, IOutline.IListeners>;
+    protected _removeListeners: IListener.Remove[];
+    protected _closed: boolean;
+    protected _rowGroups: AxisGroups | null;
+    protected _columnGroups: AxisGroups | null;
+    constructor(options: Outline.ConstructorOptions);
+    protected _getState(): Readonly<State>;
+    protected _updateState(update: Partial<State>, options?: ITransaction.OperationOptions): void;
+    protected _header(axis: IRange.Axis): SheetHeader;
+    protected _sheet(): IWorksheet;
+    /**
+     * The structure of an outline and its settings need an unprotected sheet, whatever the
+     * protection allows; only showing and hiding details goes by Format Rows / Format Columns.
+     */
+    protected _assertUnlocked(): void;
+    /** {@inheritDoc IOutline.getSummaryDirection} */
+    getSummaryDirection(axis: IRange.Axis): IRange.Direction;
+    /** {@inheritDoc IOutline.setSummaryDirection} */
+    setSummaryDirection(axis: IRange.Axis, direction: IRange.Direction, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IOutline.isAutomaticStyles} */
+    isAutomaticStyles(): boolean;
+    /** {@inheritDoc IOutline.setAutomaticStyles} */
+    setAutomaticStyles(automatic: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IOutline.getLevelCount} */
+    getLevelCount(axis: IRange.Axis): number;
+    /** {@inheritDoc IOutline.getGroups} */
+    getGroups(axis: IRange.Axis, options?: IOutline.GetGroupsOptions): readonly IOutline.Group[];
+    /** {@inheritDoc IOutline.setVisibleLevels} */
+    setVisibleLevels(axis: IRange.Axis, levels: number, options?: ITransaction.OperationOptions): this;
+    protected _setVisibleLevels(axis: IRange.Axis, levels: number): void;
+    /**
+     * Adds `delta` to the outline level of every header in `coords`.
+     *
+     * @internal
+     */
+    _changeLevels(axis: IRange.Axis, coords: RunCoords, delta: 1 | -1, options?: ITransaction.OperationOptions): void;
+    /**
+     * Throws if any header in `coords` is already at the deepest outline level.
+     *
+     * @internal
+     */
+    _assertNotDeepest(axis: IRange.Axis, coords: RunCoords): void;
+    /** {@inheritDoc IOutline.clear} */
+    clear(axes?: IRange.AxisSelection, options?: ITransaction.OperationOptions): this;
+    protected _clearAxis(axis: IRange.Axis): void;
+    /**
+     * Removes the outline levels and collapsed flags from the headers in `coords`.
+     *
+     * @internal
+     */
+    _clear(axis: IRange.Axis, coords: RunCoords, options?: ITransaction.OperationOptions): void;
+    /**
+     * Collapses or expands the groups a span selects: those whose summary falls in it, or, when there
+     * are none, the deepest groups whose details meet it.
+     *
+     * @internal
+     */
+    _setGroupDetails(axis: IRange.Axis, coords: RunCoords, show: boolean, options?: ITransaction.OperationOptions): void;
+    protected _selectGroups(axis: IRange.Axis, coords: RunCoords): IOutline.Group[];
+    /**
+     * The groups nested in `group`, deeper levels only, excluding those that share its summary (one
+     * flag cannot tell the two apart).
+     */
+    protected _innerGroups(axis: IRange.Axis, group: IOutline.Group): IOutline.Group[];
+    protected _hideGroupDetails(axis: IRange.Axis, group: IOutline.Group): void;
+    protected _showGroupDetails(axis: IRange.Axis, group: IOutline.Group): void;
+    /** {@inheritDoc IOutline.autoOutline} */
+    autoOutline(options?: ITransaction.OperationOptions): this;
+    /**
+     * The summary lines of one axis within `scope`, and the direction their details lie in.
+     */
+    protected _findSummaries(scope: IRange.Coords, axis: IRange.Axis): {
+        direction: IRange.Direction;
+        spans: SummarySpan[];
+    };
+    protected _groups(axis: IRange.Axis): AxisGroups;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IOutline.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IOutline.toJSON} */
+    toJSON(): IOutline.JSON | null;
+    /**
+     * Stops listening and drops the state. Terminal and not undoable.
+     *
+     * @internal
+     */
+    close(): void;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** {@inheritDoc IOutline.isIOutline} */
+    get isIOutline(): true;
+}
+/**
+ * {@inheritDoc Outline}
+ * @see
+ * ### **Interface**
+ *
+ * {@link Outline}
+ */
+export declare namespace Outline {
+    interface ConstructorOptions {
+        rowHeaders: SheetHeader;
+        columnHeaders: SheetHeader;
+        transactions?: ITransaction.IStore;
+        json?: IOutline.JSON | null;
+    }
+}
+export {};
+//# sourceMappingURL=Outline.d.ts.map

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

@@ -0,0 +1,2 @@
+export * from './IOutline';
+//# sourceMappingURL=index.d.ts.map

package/types/src/person/IPerson.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A person known to the workbook: the author of a comment, or someone mentioned in one.
+ *
+ * @remarks
+ * Excel keeps these in a workbook-wide list (`xl/persons/person.xml`) and refers to each by id
+ * from every threaded comment. A legacy note names its author by display name alone; the reader
+ * mints a person for it so both kinds answer {@link IComment.getAuthor} the same way.
+ *
+ * A person is added when a comment names an author the workbook has not seen, and removed with
+ * {@link delete}; a comment whose author was removed answers `null` for them.
+ */
+export interface IPerson {
+    /**
+     * The unique identifier.
+     *
+     * @remarks
+     * A GUID in files Excel wrote; anything unique within the workbook otherwise.
+     */
+    getId(): string;
+    /**
+     * The name shown beside the person's comments.
+     */
+    getDisplayName(): string;
+    /**
+     * The id the person is known by to their identity provider, or `null` if there is none.
+     *
+     * @remarks
+     * Excel keeps an email address here for a person signed in to an organization. Nothing in
+     * SheetXL resolves it.
+     */
+    getUserId(): string | null;
+    /**
+     * The identity provider that vouches for the {@link getUserId | user id}, or `null` if there is
+     * none.
+     *
+     * @remarks
+     * Excel writes `AD` for a directory account, `Windows Live` for a personal one, and `None` for
+     * a name typed with no account behind it.
+     */
+    getProviderId(): string | null;
+    /**
+     * Removes the person from the workbook.
+     *
+     * @remarks
+     * Comments they wrote keep their text and lose their author.
+     */
+    delete(): void;
+    /**
+     * Returns `true` once the person has been removed.
+     */
+    isDeleted(): boolean;
+    /**
+     * @returns The current state as a JSON object.
+     */
+    toJSON(): IPerson.JSON;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIPerson: true;
+}
+/**
+ * {@inheritDoc IPerson}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IPerson}
+ *
+ * **Additional Interfaces**
+ * * {@link IPersonCollection}
+ */
+export declare namespace IPerson {
+    /**
+     * The values that describe a person.
+     */
+    interface Properties {
+        /**
+         * {@inheritDoc IPerson.getDisplayName}
+         */
+        displayName: string;
+        /**
+         * {@inheritDoc IPerson.getUserId}
+         */
+        userId?: string;
+        /**
+         * {@inheritDoc IPerson.getProviderId}
+         */
+        providerId?: string;
+    }
+    /**
+     * A JSON representation useful for persistence.
+     */
+    interface JSON extends Properties {
+        /**
+         * {@inheritDoc IPerson.getId}
+         */
+        id: string;
+    }
+}
+//# sourceMappingURL=IPerson.d.ts.map

package/types/src/person/IPersonCollection.d.ts

@@ -0,0 +1,51 @@
+import { ICollection } from '../type';
+import { IPerson } from './IPerson';
+/**
+ * Holds the {@link IPerson | people} a workbook knows: everyone who authored or is mentioned in
+ * a comment.
+ *
+ * @remarks
+ * Keyed by id. Adding a person whose id, or whose display name, is already here returns the
+ * existing one rather than a second copy, which is what lets a legacy note's author (a display
+ * name with no id) and a threaded comment's author (an id) land on one person.
+ */
+export interface IPersonCollection extends ICollection<IPerson> {
+    /**
+     * Adds a person, or returns the one already here with the same id or display name.
+     *
+     * @param person The person's properties, or a display name alone.
+     */
+    add(person: IPerson.Properties | string): IPerson;
+    /**
+     * Returns the person with the given id, or `null` if there is none.
+     */
+    getById(id: string): IPerson | null;
+    /**
+     * Returns the person with the given display name, or `null` if there is none.
+     *
+     * @param displayName The display name. Case sensitive, as Excel keeps it.
+     */
+    getByDisplayName(displayName: string): IPerson | null;
+    /**
+     * The person a new comment is authored by when none is named.
+     *
+     * @remarks
+     * Excel uses the signed-in user; SheetXL has no user, so this is whoever {@link setCurrent}
+     * named, and otherwise a person called `Author`, added on first use.
+     */
+    getCurrent(): IPerson;
+    /**
+     * Names the person new comments are authored by.
+     *
+     * @param person A person, a person's properties, a display name, or `null` to forget the
+     * choice. A person not yet in the collection is added.
+     */
+    setCurrent(person: IPerson | IPerson.Properties | string | null): void;
+    /**
+     * Serializes to JSON, or `null` if there is no one to write.
+     */
+    toJSON(): IPerson.JSON[] | null;
+    /** For runtime type checking. */
+    readonly isIPersonCollection: true;
+}
+//# sourceMappingURL=IPersonCollection.d.ts.map

package/types/src/person/Person.d.ts

@@ -0,0 +1,32 @@
+import { IPerson } from './IPerson';
+/**
+ * Implementation of {@link IPerson}.
+ *
+ * @remarks
+ * Immutable: a person is never edited, only added and removed.
+ */
+export declare class Person implements IPerson {
+    private readonly _json;
+    private readonly _deleteFromCollection;
+    private _deleted;
+    constructor(json: IPerson.JSON, deleteFromCollection?: (person: Person) => void);
+    /** {@inheritDoc IPerson.getId} */
+    getId(): string;
+    /** {@inheritDoc IPerson.getDisplayName} */
+    getDisplayName(): string;
+    /** {@inheritDoc IPerson.getUserId} */
+    getUserId(): string | null;
+    /** {@inheritDoc IPerson.getProviderId} */
+    getProviderId(): string | null;
+    /** {@inheritDoc IPerson.delete} */
+    delete(): void;
+    /** {@inheritDoc IPerson.isDeleted} */
+    isDeleted(): boolean;
+    /** {@inheritDoc IPerson.toJSON} */
+    toJSON(): IPerson.JSON;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** {@inheritDoc IPerson.isIPerson} */
+    get isIPerson(): true;
+}
+//# sourceMappingURL=Person.d.ts.map

package/types/src/person/PersonCollection.d.ts

@@ -0,0 +1,49 @@
+import { AbstractCollection } from '../type';
+import { IPerson } from './IPerson';
+import { IPersonCollection } from './IPersonCollection';
+/**
+ * The display name of the person minted when a comment is added and nobody was named.
+ *
+ * @remarks
+ * Data, not UI text: it is written into the file as the author, so it is not localized.
+ */
+export declare const DEFAULT_AUTHOR_NAME = "Author";
+/**
+ * Implementation for {@link IPersonCollection}.
+ *
+ * @remarks
+ * Not transactional: a person is added as a side effect of authoring a comment, and a removal is
+ * not something Excel offers to undo either. Announces `onCollectionChange` on each change.
+ */
+export declare class PersonCollection extends AbstractCollection<IPerson> implements IPersonCollection {
+    private _byId;
+    private _byDisplayName;
+    private _items;
+    private _current;
+    constructor(json?: IPerson.JSON[] | null);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(): IPerson[];
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IPersonCollection.add} */
+    add(person: IPerson.Properties | string): IPerson;
+    /** {@inheritDoc IPersonCollection.getById} */
+    getById(id: string): IPerson | null;
+    /** {@inheritDoc IPersonCollection.getByDisplayName} */
+    getByDisplayName(displayName: string): IPerson | null;
+    /** {@inheritDoc IPersonCollection.getCurrent} */
+    getCurrent(): IPerson;
+    /** {@inheritDoc IPersonCollection.setCurrent} */
+    setCurrent(person: IPerson | IPerson.Properties | string | null): void;
+    /** @internal */
+    protected _remove(person: IPerson): void;
+    /** {@inheritDoc IPersonCollection.toJSON} */
+    toJSON(): IPerson.JSON[] | null;
+    /**
+     * Loads people from JSON, keeping any already here.
+     */
+    fromJSON(json: IPerson.JSON[] | null | undefined): void;
+    /** {@inheritDoc IPersonCollection.isIPersonCollection} */
+    get isIPersonCollection(): true;
+}
+//# sourceMappingURL=PersonCollection.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './IPerson';
+export * from './IPersonCollection';
+export { PersonCollection } from './PersonCollection';
+//# sourceMappingURL=index.d.ts.map