@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

package/types/src/listener/ListenerEmitter.d.ts

@@ -0,0 +1,47 @@
+import { ITransaction } from '../transaction';
+import { IListener } from './IListener';
+export interface NotifyOptions<T = any> {
+    params?: T | null;
+    source?: any;
+    async?: boolean;
+    transactional?: boolean;
+}
+/**
+ * Manages Listeners
+ *
+ * @remarks
+ * A few rules to know:
+ *
+ * * non-transactional listeners are fired after the commit end and are conflated.
+ */
+export declare class ListenerEmitter<SOURCE, EVENTS> {
+    protected _transactions: ITransaction.IStore;
+    protected _transactionsRemoveListener: IListener.Remove;
+    /** The store-issued id for this emitter's (transactional listeners) record. */
+    protected _stateId: string;
+    protected _src: SOURCE;
+    protected _listeners: EntrySet<SOURCE, EVENTS>;
+    protected _pending: Pending<any, SOURCE>[] | null;
+    constructor(src: SOURCE, transactions?: ITransaction.IStore);
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IListener.Callbacks<SOURCE, EVENTS>, options?: IListener.Options): IListener.Remove;
+    protected _doNotify<T = unknown>(listeners: IListener.Callback<SOURCE>[], removes?: IListener.Remove[] | null, options?: NotifyOptions<T>, fired?: Set<IListener.Callback<SOURCE>>): Promise<any>;
+    /**
+     * Notify listeners.
+     */
+    notify<T = unknown>(key: keyof EVENTS, options?: NotifyOptions<T>): void | Promise<any>;
+    close(): void;
+}
+interface Entry<SOURCE, EVENTS> {
+    remove?: IListener.Remove | null;
+    listeners: IListener.Callbacks<SOURCE, EVENTS>;
+}
+type EntrySet<SOURCE = any, EVENTS = any> = Set<Entry<SOURCE, EVENTS>>;
+interface Pending<T, SOURCE> {
+    commitId: string;
+    listeners: IListener.Callback<SOURCE>[];
+    removes: IListener.Remove[] | null;
+    options?: NotifyOptions<T>;
+}
+export {};
+//# sourceMappingURL=ListenerEmitter.d.ts.map

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

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

package/types/src/model/AbstractModel.d.ts

@@ -0,0 +1,90 @@
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { IModel } from './IModel';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+/**
+ * Abstract implement of `IModel`.
+ */
+export declare abstract class AbstractModel<STATE extends AbstractModel.State = AbstractModel.State, JSON extends any = any, VIEW extends AbstractModel.CommitView = AbstractModel.CommitView, EVENTS extends IModel.Events = IModel.Events> implements IModel {
+    protected _emitter: ListenerEmitter<AbstractModel, EVENTS>;
+    protected _options: IModel.ConstructorOptions<JSON>;
+    protected _transactions: ITransaction.IStore;
+    protected _id: string;
+    protected _transactionsRemoveListener: IListener.Remove;
+    protected _closed: boolean;
+    constructor(options: IModel.ConstructorOptions<JSON>);
+    /** @internal */
+    protected _fromJSON(_json: JSON): void;
+    isReadOnly(): boolean;
+    isDeleted(): boolean;
+    getType(): string;
+    get isIModel(): true;
+    /** @internal */
+    protected _processTransactionDone(_transaction: ITransaction): void;
+    /** @internal */
+    /**
+     * A COMPLETE undo description for `action`, or null for the generic one.
+     *
+     * Whole sentences, not a noun: the old hook returned `Data Validation` and the caller wrote
+     * `Delete ${noun}`, which cannot be translated — verb/noun order and the noun's case move with
+     * the language. Return a `messageKey` (static, follows a language switch) or, only when the text
+     * carries per-instance data, a `t()`-formatted string.
+     */
+    protected _getActionDescription(_action: 'delete'): string | null;
+    /** @internal */
+    protected _getState(): Readonly<STATE>;
+    /** @internal */
+    protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    /** @internal */
+    protected _getTransactions(): ITransaction.IStore;
+    /** @internal */
+    protected _updateState(updateState?: Partial<STATE>, //(prevState: STATE) => STATE,
+    options?: ITransaction.StoreOperationOptions, events?: (keyof EVENTS)[]): this;
+    /** @internal */
+    protected _getEmitter<SOURCE, E extends EVENTS>(): ListenerEmitter<SOURCE, E>;
+    /** @internal */
+    protected _processInit(): void;
+    /** @internal */
+    protected _processAfterStateChange(_state: STATE, _view: VIEW, _commit: ITransaction.ICommit): void;
+    /** @internal */
+    protected _processRestoreOrRevert(_state: STATE, _view: VIEW, _commit: ITransaction.ICommit): void;
+    delete(options?: ITransaction.OperationOptions): void;
+    /** @internal */
+    protected _delete(options?: ITransaction.OperationOptions): void;
+    /** @internal */
+    protected _processOnContainerDeleted(): void;
+    /** @internal */
+    protected _processDelete(): void;
+    /** @internal */
+    protected _processOnContainerReadOnly(): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IListener.Callbacks<IModel, EVENTS>, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ITransaction.ITransactional.getId} */
+    getId(): string;
+    /** {@inheritDoc ITransaction.ITransactional.getVersionId} */
+    getVersionId(): number;
+    /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
+    beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    /** {@inheritDoc ITransaction.ITransactional.doBatch} */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => Promise<R> | R, options?: string | ITransaction.OperationOptions): Promise<R> | R;
+    /** {@inheritDoc ITransaction.ITransactional.isClosed} */
+    isClosed(): boolean;
+    /** {@inheritDoc ITransaction.ITransactional.close} */
+    close(): void;
+}
+/**
+ * Interfaces for creating `IAnchored`.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link AbstractModel}
+ */
+export declare namespace AbstractModel {
+    interface State extends ITransaction.StateRecord {
+        isDeleted: boolean;
+    }
+    interface CommitView {
+    }
+}
+//# sourceMappingURL=AbstractModel.d.ts.map

package/types/src/model/IModel.d.ts

@@ -0,0 +1,108 @@
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+/**
+ * A model interface is a interface that has:
+ *
+ * 1. Eventing
+ * 2. Transactional
+ * 3. Potentially delete
+ * 4. Potentially readonly
+ */
+export interface IModel<L extends IModel.IListeners = IModel.IListeners> extends ITransaction.ITransactional {
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: L, options?: IListener.Options): IListener.Remove;
+    /**
+     * Delete the item.
+     *
+     * @remarks
+     * Not all objects can be deleted.
+     */
+    delete?(options?: ITransaction.OperationOptions): void;
+    /**
+     * If the model unable to be modified.
+     */
+    isReadOnly(): boolean;
+    /**
+     * If the model unable to be modified.
+     */
+    isDeleted(): boolean;
+    /**
+     * Returns an immutable type string.
+     */
+    getType(): string;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIModel: true;
+}
+/**
+ * {@inheritDoc IModel}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IModel}
+ */
+export declare namespace IModel {
+    /**
+     * IListener for {@link IModel} events.
+     */
+    interface Events {
+        /**
+         * Called when any state has been modified.
+         */
+        onAnyChange?(source: IModel): void;
+        /**
+         * Called when the readOnly status is updated.
+         */
+        onReadOnlyChange?(source: IModel): void;
+        /**
+         * Called when the model has been deleted.
+         */
+        onDelete?(source: IModel): void;
+        /**
+         * Called when the transaction is closed.
+         */
+        onClose?(source: IModel): void;
+        /**
+         * Called when the state has been updated due to a undo/redo and a rerender is required.
+         */
+        onInvalidated?(source: IModel): void;
+    }
+    interface IListeners extends IListener.Callbacks<IModel, IModel.Events> {
+    }
+    type DeletedCallback = () => void;
+    type ReadOnlyCallback = () => void;
+    interface ConstructorOptions<J> {
+        /**
+         * The type of the model.
+         */
+        type?: string;
+        /**
+         * If the item is readonly.
+         */
+        isReadOnly?(): boolean;
+        /**
+         * Notify if the readonly has been updated from the container.
+         * @param callback
+         */
+        setContainerReadOnlyCallback?(callback: IModel.ReadOnlyCallback): void;
+        /**
+         * Delete from the container.
+         */
+        deleteFromContainer?(options?: ITransaction.OperationOptions): void;
+        /**
+         * A transaction store that can be used to undo/redo changes to the model.
+         */
+        transactions?: ITransaction.IStore;
+        /**
+         * JSON state to load.
+         */
+        json?: J;
+    }
+}
+//# sourceMappingURL=IModel.d.ts.map

package/types/src/model/_ModelMessages.d.ts

@@ -0,0 +1,2 @@
+export declare const CREATE_DESCRIPTION = "Create Model";
+//# sourceMappingURL=_ModelMessages.d.ts.map

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

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

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

@@ -0,0 +1,42 @@
+import { IResource, IResourceCollection } from '../resource';
+import { IModel, AbstractModel } from '../model';
+import { ICustomElement } from './ICustomElement';
+interface State extends AbstractModel.State {
+    data?: any;
+    type: string;
+}
+/**
+ * Implementation for {@link ICustomElement}.
+ */
+export declare class CustomElement extends AbstractModel<State, ICustomElement.JSON> implements ICustomElement {
+    constructor(options: CustomElement.ConstructorOptions);
+    getType(): string;
+    getDescription(): string;
+    toJSON(_toResourceId?: (resource: IResource) => number | null): ICustomElement.JSON | null;
+    getTypeDescription(): string;
+}
+/**
+ * Interfaces for creating `CustomElement` items.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link CustomElement}
+ */
+export declare namespace CustomElement {
+    /**
+     * Options for creating a Custom Element.
+     */
+    interface ConstructorOptions extends IModel.ConstructorOptions<ICustomElement.JSON> {
+        /**
+         * Returns an IResource from the resourceId or null if not found.
+         */
+        fromResourceId?: (resourceId: number) => IResource;
+        /**
+         * Useful for load/save/copying.
+         */
+        beginPersistResource: () => IResourceCollection.IPersistScope<IResource.JSON>;
+    }
+}
+export {};
+//# sourceMappingURL=CustomElement.d.ts.map

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

@@ -0,0 +1,29 @@
+import { IListener } from '../listener';
+import { IResource } from '../resource';
+import { IModel } from '../model';
+/**
+ * Interface for working with CustomMovables.
+
+ * **PLACEHOLDER**
+ */
+export interface ICustomElement extends IModel {
+    toJSON(toResourceId?: (resource: IResource) => number | null): ICustomElement.JSON | null;
+    getDescription(): string;
+}
+/**
+ * {@inheritDoc ICustomElement}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICustomElement}
+ */
+export declare namespace ICustomElement {
+    interface JSON {
+        type?: string;
+    }
+    interface Events extends IModel.Events {
+    }
+    interface IListeners extends IListener.Callbacks<ICustomElement, ICustomElement.Events> {
+    }
+}
+//# sourceMappingURL=ICustomElement.d.ts.map

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

@@ -0,0 +1,30 @@
+import { IListener } from '../listener';
+import { IResource } from '../resource';
+import { IModel } from '../model';
+/**
+ * Interface for working with Groups.
+ *
+ * @remarks
+ * **PLACEHOLDER**
+ */
+export interface IGroup extends IModel {
+    toJSON(toResourceId?: (resource: IResource) => number): IGroup.JSON;
+    getDescription(): string;
+}
+/**
+ * {@inheritDoc IGroup}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IGroup}
+ */
+export declare namespace IGroup {
+    interface JSON {
+        grpSp?: any;
+    }
+    interface Events extends IModel.Events {
+    }
+    interface IListeners extends IListener.Callbacks<IGroup, IGroup.Events> {
+    }
+}
+//# sourceMappingURL=IGroup.d.ts.map

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

@@ -0,0 +1,327 @@
+import { Bounds, Point, ReferenceableClipboard } from '@sheetxl/utils';
+import { ITypes } from '../type';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { IListener } from '../listener';
+import { IModel } from '../model';
+import { ICellRange } from '../cellRange';
+import { IHistory } from '../history';
+import { IAnchored } from '../anchored';
+import { IMovableCollection } from './IMovableCollection';
+/**
+ * Capabilities for working with graphical elements that can be
+ * arbitrarily placed (floated) within a virtual 'canvas'.
+ *
+ * Encompasses objects like images, charts, shapes, and custom widgets.
+ *
+ * Key features include:
+ * - Inserting, positioning, resizing, and scaling movables.
+ * - Grouping and layering multiple movables.
+ * - Loading, saving, and copy/pasting movables.
+ */
+export interface IMovable extends IAnchored, ITransaction.ITransactional, IHistory.ISnapshotSource<IMovable.SnapshotDestination, IMovable, Bounds> {
+    /**
+     * Returns the range this movable is anchored to.
+     *
+     * @remarks
+     * A movable occupies exactly one rectangle, which is why the singular lives here rather than on
+     * {@link IAnchored}. Invalid, never `null`, once the movable is no longer anchored.
+     */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns the content of the movable.
+     */
+    getContent<T extends IModel>(): T;
+    /**
+     * Selects the current movable.
+     *
+     * @returns An async boolean indicating the movable was selected.
+     */
+    select(options?: IMovable.SelectOptions): Promise<boolean>;
+    /**
+     * Remove the movable the current selection.
+     * @returns A flag indicating if it was previously in the selection.
+     */
+    unselect: () => boolean;
+    /**
+     * Returns a flag indicating if the movable is selected.
+     */
+    isSelected: () => boolean;
+    /**
+     * Set the absolution position of a movable in pixels.
+     * @param bounds The new bounds.
+     *
+     * @remarks
+     * If only some of the points are provided then only those will be moved.
+     */
+    setBounds(bounds: Partial<Bounds>, options?: ITransaction.OperationOptions): IMovable;
+    /**
+     * Scroll the movable into the viewport.
+     *
+     * @returns A promise that resolve to a `boolean` when the scroll is complete.
+     *
+     * @remarks
+     * This will return when the scroll view is loaded but before any scroll animations have started or finished.
+     */
+    scrollIntoView: (options?: globalThis.ScrollIntoViewOptions | boolean) => Promise<boolean>;
+    /**
+     * Returns the absolute bounds of the movable object in pixels or `null` if not yet laid out.
+     */
+    getBounds(): Bounds | null;
+    /**
+     * Set the name for a movable object.
+     *
+     * @param name The name of the IMovable.
+     */
+    setName(name: string): IMovable;
+    /**
+     * @see
+     * {@link setName}
+     *
+     * @returns The name or `null` if the movable has been deleted.
+     */
+    getName(): string | null;
+    /**
+     * This is the alternative text use for assistive technologies.
+     */
+    setDescription(description: string | null): IMovable;
+    /**
+     * @see
+     * {@link setDescription}
+     *
+     * @returns The description or `null` if none has been set (or the movable has been deleted).
+     */
+    getDescription(): string | null;
+    /**
+     * If true then the movable object is hidden.
+     */
+    setHidden(hidden: boolean): IMovable;
+    /**
+     * @see
+     * {@link setHidden}
+     */
+    isHidden(): boolean;
+    /**
+     * Set the rotation in degrees.
+     */
+    setRotation(rotation: number): IMovable;
+    /**
+     * @see
+     * {@link setHidden}
+     */
+    getRotation(): number;
+    /**
+     * If true then the aspect should be maintained during resize if using the corners or if
+     * the api only specifies one dimension.
+     *
+     * @remarks
+     * Lock aspect ratio will have different default values depending on the movable type.
+     */
+    setLockAspectRatio(locked: boolean): IMovable;
+    /**
+     * @see
+     * {@link setLockAspectRatio}
+     */
+    isLockAspectRatio(): boolean;
+    /**
+     * Ses the anchor type.
+     */
+    setAnchorType(anchorType: IAnchored.Type): IMovable;
+    /**
+     * The order in the z plane. To adjust this use the move methods.
+     */
+    getZIndex(): number;
+    /**
+     * Move movable to the back in the zIndex.
+     */
+    moveToBack(): this;
+    /**
+     * Move movable backward one layer in the zIndex.
+     */
+    moveBackward(): this;
+    /**
+     * Move movable to the font in the zIndex.
+     */
+    moveToFront(): this;
+    /**
+     * Move movable forward one layer in the zIndex.
+     */
+    moveForward(): this;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IMovable.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * If defined this will be called when the containing sheet is being
+     * serialized.
+     */
+    toJSON?(toResourceId?: (resource: IResource) => number | null): IMovable.JSON;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIMovable: true;
+}
+/**
+ * {@inheritDoc IMovable}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IMovable}
+ */
+export declare namespace IMovable {
+    /**
+     * Extends {@link ITypes.SelectOptions} to include options for `IMovable`.
+     */
+    interface SelectOptions extends ITypes.SelectOptions {
+        /**
+         * Flag to indicate the the movable should be added to the selection
+         * or should replace the existing selection.
+         *
+         * @remarks
+         * Setting this to true is the equivalent of press the Ctrl in the UI.
+         */
+        addToSelection?: boolean;
+    }
+    /**
+     * `Events` for {@link IMovable} events.
+     */
+    interface Events extends IAnchored.Events {
+        /**
+         * Called when the isSelect status has changed.
+         */
+        onSelectionChange?(source: IMovable): void;
+        /**
+         * Called when the name has changed.
+         */
+        onNameChange?(source: IMovable): void;
+        /**
+         * Called when selection changes.
+         */
+        onBoundsChange?(source: IMovable): void;
+        /**
+         * Called when the anchor type is updated.
+         */
+        onAnchorTypeChange?(source: IMovable): void;
+        /**
+         * Called when any property has changed.
+         */
+        onAnyChange?(source: IMovable): void;
+        /**
+         * Request that the movable become focused.
+         *
+         * @returns A promise indicating if the focus was honored.
+         *
+         * @remarks
+         * This should only be handled by one consumer.
+         */
+        onRequestFocus?(source: IMovable): Promise<boolean>;
+    }
+    interface IListeners extends IListener.Callbacks<IMovable, IMovable.Events> {
+    }
+    /**
+     * Provides destination details for the Snapshot when using {@link IHistory.ISnapshot.copyTo}.
+     */
+    interface SnapshotDestination {
+        /**
+         * The movable collection to copy to.
+         */
+        movables: IMovableCollection;
+        /**
+         * The bounds to copy to.
+         */
+        bounds: Bounds;
+    }
+    interface ISnapshot extends IHistory.ISnapshot<IMovable.SnapshotDestination, IMovable, Bounds> {
+        /**
+         * Called when the movable is copied to a new container.
+         */
+        copyTo(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Promise<Bounds> | Bounds;
+    }
+    interface CopyOptions extends ReferenceableClipboard.CopyOptions {
+        /** {@inheritDoc IMovable.SelectOptions} */
+        autoSelect?: boolean | IMovable.SelectOptions;
+    }
+    interface OffsetCoords extends Partial<Point> {
+        /** The row index */
+        r?: number;
+        /** The column index */
+        c?: number;
+    }
+    interface AnchorOffset {
+        tl: OffsetCoords;
+        br: OffsetCoords;
+    }
+    interface ClientData {
+        /**
+         * disable selection on movable elements when the sheet is protected
+         * @defaultValue false
+         */
+        fLocksWithSheet?: boolean;
+        /**
+         * print movable elements when printing the sheet
+         * @defaultValue true
+         */
+        fPrintsWithSheet?: boolean;
+    }
+    interface ContentJSON<J> {
+        /**
+         * Identifies the type of movable object.
+         *
+         * @remarks
+         * This must align to a known movable object type. Defined in the IEmbeddedDrawing interface.
+         */
+        type: string;
+        /**
+         * Underlying json.
+         */
+        json: J;
+    }
+    interface JSON<J = any> {
+        /**
+         * The anchor for the movable object.
+         */
+        anchor: IMovable.AnchorOffset;
+        /**
+         * The content of the movable object.
+         */
+        content: ContentJSON<J>;
+        /**
+         * The behavior of how the movable resizes as the anchor/cells change.
+         */
+        anchorType?: IAnchored.Type;
+        /**
+         * The name of the movable object.
+         */
+        name?: string;
+        /**
+         * This is the alternative text use for assistive technologies.
+         *
+         * @defaultValue null
+         */
+        description?: string;
+        /**
+         * If true then the movable object is hidden.
+         *
+         * @defaultValue false
+         */
+        hidden?: boolean;
+        /**
+         * The rotation in degrees.
+         *
+         * @defaultValue 0
+         */
+        rotation?: number;
+        /**
+         * Whether resizing should keep the aspect ratio.
+         */
+        lockAspect?: boolean;
+        /**
+         * lock specific fields*/
+        locks?: any;
+        clientData?: IMovable.ClientData;
+    }
+}
+//# sourceMappingURL=IMovable.d.ts.map