@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/movable/FormControl.d.ts

@@ -0,0 +1,285 @@
+import { Scalar } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { ICellRange } from '../cellRange';
+import { IFormControl, ICaptioned, ILinked, IButton, ICheckBox, IOptionButton, IGroupBox, ILabel, IRangedControl, IScrollBar, ISpinner, IListControl, IListBox, IDropDown } from './IFormControl';
+import { AbstractMovableContent } from './AbstractMovableContent';
+/** The fields that name cells: held by the engine, so they follow the cells they name. */
+declare const REFERENCE_FIELDS: readonly ["linkedCell", "listFillRange"];
+type ReferenceField = typeof REFERENCE_FIELDS[number];
+interface State<J extends IFormControl.JSON> extends AbstractMovableContent.State {
+    data?: J;
+}
+/**
+ * Implementation for {@link IFormControl}: what every kind shares. On its own it is the kinds with
+ * nothing of their own (edit box, dialog, and a kind this version does not know), told apart by
+ * the type they are created with.
+ */
+export declare class FormControl<J extends IFormControl.JSON = IFormControl.JSON> extends AbstractMovableContent<State<J>, J> implements IFormControl {
+    private readonly _type;
+    private readonly _typeDescription;
+    /**
+     * Every reference ever set on a field, one per text. A reference no field reads is released
+     * but kept: its formula still reads the engine's grid, which an undo brings back with the value
+     * it puts back, so the field answers right away and the reference is held again from it.
+     */
+    private readonly _references;
+    constructor(options: FormControl.ConstructorOptions<J>);
+    /** {@inheritDoc IModel.getType} */
+    getType(): string;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
+    getTypeDescription(): string;
+    /** {@inheritDoc IFormControl.getShapeId} */
+    getShapeId(): number | null;
+    /** A control's twin is numbered by the control's shape id, as Excel numbers it. @internal */
+    _getSourceId(): number | undefined;
+    /** @internal */
+    _ensureSourceId(next: () => number): number;
+    /** {@inheritDoc IFormControl.getMacro} */
+    getMacro(): string | null;
+    /** {@inheritDoc IFormControl.setMacro} */
+    setMacro(macro: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc Movable.Content.toJSON} */
+    toJSON(_toResourceId?: (resource: IResource) => number | null): J | null;
+    /** {@inheritDoc IFormControl.isIFormControl} */
+    get isIFormControl(): true;
+    protected _data(): J | null;
+    /**
+     * A reference field as it reads now: the engine's copy once something has moved the cells it
+     * names, else the text as set.
+     */
+    protected _reference(field: ReferenceField): string | null;
+    /**
+     * The range a reference names — by default the linked cell — or `null` when there is none or
+     * it no longer resolves. An unqualified reference is on the control's own sheet.
+     */
+    protected _linkedRange(address?: string | null): ICellRange | null;
+    /** The linked cell's value, or `undefined` when the control mirrors none. */
+    protected _linkedValue(): Scalar | undefined;
+    /**
+     * The fields of the control's state as its linked cell says them, or `null` when it mirrors
+     * none. A field answered `undefined` is cleared.
+     */
+    protected _linkedState(): Partial<J> | null;
+    private _referenceOf;
+    /**
+     * Brings the watches in line with the reference fields: what a field reads is held, what no
+     * field reads any more is released.
+     */
+    private _reconcileReferences;
+    /** Held from the engine's own formula when it has one, so a reference an undo put back is held as it reads now. */
+    private _watch;
+    /** @internal */
+    protected _processRestoreOrRevert(state: State<J>, commit: ITransaction.ICommit): void;
+    /**
+     * Writes fields into the control's data as one operation. A field set to `undefined` is
+     * removed, so the JSON only ever says what differs from the default.
+     */
+    protected _set(fields: Partial<J>, message: string, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * The kinds that show text ({@link ICaptioned}): a button, a group box, a label.
+ */
+export declare abstract class CaptionedControl<J extends IFormControl.JSON & ICaptioned.JSON> extends FormControl<J> implements ICaptioned {
+    /** {@inheritDoc ICaptioned.getCaption} */
+    getCaption(): string | null;
+    /** {@inheritDoc ICaptioned.setCaption} */
+    setCaption(caption: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICaptioned.getFont} */
+    getFont(): ICaptioned.Font | null;
+}
+/**
+ * The kinds a cell mirrors ({@link ILinked}) that show no text: scroll bars, spinners, lists.
+ */
+export declare abstract class LinkedControl<J extends IFormControl.JSON & ILinked.JSON> extends FormControl<J> implements ILinked {
+    /** {@inheritDoc ILinked.getLinkedCell} */
+    getLinkedCell(): string | null;
+    /** {@inheritDoc ILinked.getLinkedRange} */
+    getLinkedRange(): ICellRange | null;
+    /** {@inheritDoc ILinked.setLinkedCell} */
+    setLinkedCell(address: string | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * The kinds that both show text and are mirrored by a cell: a check box, an option button.
+ */
+export declare abstract class CaptionedLinkedControl<J extends IFormControl.JSON & ICaptioned.JSON & ILinked.JSON> extends CaptionedControl<J> implements ILinked {
+    /** {@inheritDoc ILinked.getLinkedCell} */
+    getLinkedCell(): string | null;
+    /** {@inheritDoc ILinked.getLinkedRange} */
+    getLinkedRange(): ICellRange | null;
+    /** {@inheritDoc ILinked.setLinkedCell} */
+    setLinkedCell(address: string | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * Implementation for {@link IButton}.
+ */
+export declare class Button extends CaptionedControl<IButton.JSON> implements IButton {
+    constructor(options: FormControl.KindOptions<IButton.JSON>);
+}
+/**
+ * Implementation for {@link IGroupBox}.
+ */
+export declare class GroupBox extends CaptionedControl<IGroupBox.JSON> implements IGroupBox {
+    constructor(options: FormControl.KindOptions<IGroupBox.JSON>);
+}
+/**
+ * Implementation for {@link ILabel}.
+ */
+export declare class Label extends CaptionedControl<ILabel.JSON> implements ILabel {
+    constructor(options: FormControl.KindOptions<ILabel.JSON>);
+}
+/**
+ * Implementation for {@link ICheckBox}.
+ */
+export declare class CheckBox extends CaptionedLinkedControl<ICheckBox.JSON> implements ICheckBox {
+    constructor(options: FormControl.KindOptions<ICheckBox.JSON>);
+    /** {@inheritDoc ICheckBox.isChecked} */
+    isChecked(): boolean;
+    /** {@inheritDoc ICheckBox.setChecked} */
+    setChecked(checked: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICheckBox.isMixed} */
+    isMixed(): boolean;
+    /** {@inheritDoc ICheckBox.setMixed} */
+    setMixed(mixed: boolean, options?: ITransaction.OperationOptions): this;
+    /** @internal */
+    protected _linkedState(): Partial<ICheckBox.JSON> | null;
+}
+/**
+ * Implementation for {@link IOptionButton}.
+ */
+export declare class OptionButton extends CaptionedLinkedControl<IOptionButton.JSON> implements IOptionButton {
+    constructor(options: FormControl.KindOptions<IOptionButton.JSON>);
+    /**
+     * {@inheritDoc ILinked.getLinkedCell}
+     *
+     * @remarks
+     * A group has one linked cell, written on its first button; every button in the group answers
+     * it.
+     */
+    getLinkedCell(): string | null;
+    /** {@inheritDoc IOptionButton.isChecked} */
+    isChecked(): boolean;
+    /** {@inheritDoc IOptionButton.setChecked} */
+    setChecked(checked: boolean, options?: ITransaction.OperationOptions): this;
+    /** @internal */
+    protected _linkedState(): Partial<IOptionButton.JSON> | null;
+    /** The link this button carries itself, shifted as it reads now. */
+    private _ownLinkedCell;
+    /**
+     * The buttons of this one's group, in sheet order: a group runs from a button marked as its
+     * first (`firstButton`, as the file marks it) to the next, and the buttons before any mark are
+     * one group.
+     */
+    private _group;
+}
+/**
+ * What {@link ScrollBar} and {@link Spinner} share.
+ */
+export declare abstract class RangedControl<J extends IRangedControl.JSON> extends LinkedControl<J> implements IRangedControl {
+    /** {@inheritDoc IRangedControl.getValue} */
+    getValue(): number | null;
+    /** {@inheritDoc IRangedControl.setValue} */
+    setValue(value: number | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * @internal
+     * The cell's number, held to the control's range as Excel holds it; anything else leaves the
+     * value as stored.
+     */
+    protected _linkedState(): Partial<J> | null;
+    /** {@inheritDoc IRangedControl.getMin} */
+    getMin(): number | null;
+    /** {@inheritDoc IRangedControl.setMin} */
+    setMin(min: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IRangedControl.getMax} */
+    getMax(): number | null;
+    /** {@inheritDoc IRangedControl.setMax} */
+    setMax(max: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IRangedControl.getIncrement} */
+    getIncrement(): number | null;
+    /** {@inheritDoc IRangedControl.setIncrement} */
+    setIncrement(increment: number | null, options?: ITransaction.OperationOptions): this;
+}
+/**
+ * Implementation for {@link IScrollBar}.
+ */
+export declare class ScrollBar extends RangedControl<IScrollBar.JSON> implements IScrollBar {
+    constructor(options: FormControl.KindOptions<IScrollBar.JSON>);
+    /** {@inheritDoc IScrollBar.getPageIncrement} */
+    getPageIncrement(): number | null;
+    /** {@inheritDoc IScrollBar.setPageIncrement} */
+    setPageIncrement(increment: number | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IScrollBar.isHorizontal} */
+    isHorizontal(): boolean;
+    /** {@inheritDoc Movable.Content.toJSON} */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IScrollBar.JSON | null;
+}
+/**
+ * Implementation for {@link ISpinner}.
+ */
+export declare class Spinner extends RangedControl<ISpinner.JSON> implements ISpinner {
+    constructor(options: FormControl.KindOptions<ISpinner.JSON>);
+}
+/**
+ * What {@link ListBox} and {@link DropDown} share.
+ */
+export declare abstract class ListControl<J extends IListControl.JSON> extends LinkedControl<J> implements IListControl {
+    /** {@inheritDoc IListControl.getItems} */
+    getItems(): readonly string[];
+    /** {@inheritDoc IListControl.setItems} */
+    setItems(items: readonly string[], options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IListControl.getListItems} */
+    getListItems(): readonly string[];
+    /** {@inheritDoc IListControl.getListFillRange} */
+    getListFillRange(): string | null;
+    /** {@inheritDoc IListControl.getListSourceRange} */
+    getListSourceRange(): ICellRange | null;
+    /** {@inheritDoc IListControl.setListFillRange} */
+    setListFillRange(address: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IListControl.getSelectedIndex} */
+    getSelectedIndex(): number | null;
+    /** {@inheritDoc IListControl.setSelectedIndex} */
+    setSelectedIndex(index: number | null, options?: ITransaction.OperationOptions): this;
+    /** @internal */
+    protected _linkedState(): Partial<J> | null;
+}
+/**
+ * Implementation for {@link IListBox}.
+ */
+export declare class ListBox extends ListControl<IListBox.JSON> implements IListBox {
+    constructor(options: FormControl.KindOptions<IListBox.JSON>);
+}
+/**
+ * Implementation for {@link IDropDown}.
+ */
+export declare class DropDown extends ListControl<IDropDown.JSON> implements IDropDown {
+    constructor(options: FormControl.KindOptions<IDropDown.JSON>);
+    /** {@inheritDoc IDropDown.getDropStyle} */
+    getDropStyle(): IDropDown.DropStyle | null;
+    /** {@inheritDoc IDropDown.getDropLines} */
+    getDropLines(): number | null;
+}
+/**
+ * Interfaces for creating form controls.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link FormControl}
+ */
+export declare namespace FormControl {
+    /**
+     * Options for creating a kind of form control, which knows its own type.
+     */
+    type KindOptions<J extends IFormControl.JSON> = AbstractMovableContent.ConstructorOptions<J>;
+    /**
+     * Options for creating a form control of a kind with nothing of its own.
+     */
+    interface ConstructorOptions<J extends IFormControl.JSON> extends KindOptions<J> {
+        /** The content type ({@link IFormControl.Type}). */
+        type: string;
+        /** What the kind is called to a person: `Edit Box`. */
+        typeDescription?: string;
+    }
+}
+export {};
+//# sourceMappingURL=FormControl.d.ts.map

package/types/src/movable/GroupMember.d.ts

@@ -0,0 +1,87 @@
+import { Bounds } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IAnchored } from '../anchored';
+import { IMovable } from './IMovable';
+import { Movable } from './Movable';
+/**
+ * A movable inside a group.
+ *
+ * @remarks
+ * Its container is the group, not the canvas. What it keeps is its placement in the group's
+ * child space, as the file states it; what it answers is where it is drawn, through the mapping
+ * the group handed it when it was made, and what it is told is where it is drawn, taken back
+ * through the inverse. The cells it is over are its root's, and so is its protection. Its
+ * z-order is its place among the group's members.
+ */
+export declare class GroupMember extends Movable {
+    protected _optionsMember: GroupMember.ConstructorOptions;
+    constructor(options: GroupMember.ConstructorOptions);
+    /** {@inheritDoc IMovable.getParent} */
+    getParent(): IMovable | null;
+    /** {@inheritDoc IMovable.getRange} */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /** {@inheritDoc IAnchored.getRanges} */
+    getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
+    /** {@inheritDoc IAnchored.isDeleted} */
+    isDeleted(): boolean;
+    /** {@inheritDoc IAnchored.getAnchorType} */
+    getAnchorType(): IAnchored.Type;
+    /**
+     * {@inheritDoc IMovable.setAnchorType}
+     *
+     * @remarks
+     * A member is placed in its group's child space, where there are no cells to anchor to; the
+     * group's own movable takes the anchor type. Nothing changes.
+     */
+    setAnchorType(_type: IAnchored.Type): this;
+    /**
+     * The placement kept: in the child space of the group that holds this member.
+     * @internal
+     */
+    _getLocalPlacement(): Movable.Placement | null;
+    /** Where the member is drawn; `null` before it or its group is laid out. */
+    private _getDrawnPlacement;
+    /** {@inheritDoc IMovable.getBounds} */
+    getBounds(): Bounds | null;
+    /** {@inheritDoc IMovable.getRotation} */
+    getRotation(): number;
+    /** {@inheritDoc IMovable.getFlip} */
+    getFlip(): IMovable.Flip;
+    /**
+     * {@inheritDoc IMovable.setRotation}
+     *
+     * @remarks
+     * The member keeps the size it is drawn at, as Excel keeps it: under an uneven scale a turn
+     * into or out of a quarter turn restates its frame in the child space with the other factors.
+     * The group fits itself to its members afterwards.
+     */
+    setRotation(rotation?: number): this;
+    /** {@inheritDoc IMovable.setFlip} */
+    setFlip(flip: Partial<IMovable.Flip>, options?: ITransaction.OperationOptions): this;
+    /** The box the member occupies as drawn, as rotated. */
+    protected _getAnchorBounds(): Bounds | null;
+    protected _setAnchorBounds(anchorBounds: Bounds): void;
+    /** Where the member is drawn changed: no cells to find again, only listeners to tell. */
+    protected _processContainerLayout(): void;
+    protected _fromJSON(json: IMovable.JSON): void;
+    /** @internal */
+    _getAnchorJSON(): IMovable.AnchorOffset;
+    toJSON(toResourceId?: Parameters<Movable['toJSON']>[0]): IMovable.JSON;
+}
+export declare namespace GroupMember {
+    interface ConstructorOptions extends Movable.ConstructorOptions {
+        /** The movable of the group that holds this member. */
+        getParent: () => IMovable;
+        /**
+         * Where a placement in the group's child space is drawn; `null` while the group is not laid
+         * out.
+         */
+        place: (local: Movable.Placement) => Movable.Placement | null;
+        /** The placement in the child space that is drawn at `drawn`; `null` as {@link place}. */
+        unplace: (drawn: Movable.Placement) => Movable.Placement | null;
+        /** The member's frame or rotation changed, as part of the open operation: the group refits. */
+        onMemberPlacementChange?: () => void;
+    }
+}
+//# sourceMappingURL=GroupMember.d.ts.map

package/types/src/movable/ICustomElement.d.ts

@@ -1,14 +1,19 @@
 import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IModel } from '../model';
+import { IMovable } from './IMovable';
 /**
  * Interface for working with CustomMovables.
 
  * **PLACEHOLDER**
  */
-export interface ICustomElement extends IModel {
+export interface ICustomElement extends IModel, IMovable.IContent {
     toJSON(toResourceId?: (resource: IResource) => number | null): ICustomElement.JSON | null;
-    getDescription(): string;
+    /**
+     * Deletes the element, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
 }
 /**
  * {@inheritDoc ICustomElement}

package/types/src/movable/IErrorContent.d.ts

@@ -0,0 +1,23 @@
+import { IMovable } from './IMovable';
+/**
+ * The content of a movable whose own content could not be made: its kind failed to load, or threw
+ * when it was created.
+ *
+ * @remarks
+ * Its type is `'error'`, so it is drawn by the `'error'` renderer, never by its kind's. The movable
+ * is still placed, and is saved as it was read, under its original type, so nothing is lost. It
+ * cannot be edited.
+ */
+export interface IErrorContent extends IMovable.IContent {
+    /**
+     * Returns why the content could not be made.
+     */
+    getError(): unknown;
+    /**
+     * Returns the type the content was saved as: the kind that could not be made.
+     */
+    getOriginalType(): string;
+    /** For runtime type checking. */
+    readonly isIErrorContent: true;
+}
+//# sourceMappingURL=IErrorContent.d.ts.map