@odoo/o-spreadsheet 19.2.0-alpha.4 → 19.3.2

package/dist/types/history/branch.d.ts

@@ -0,0 +1,63 @@
+import { Transformation, TransformationFactory } from "../types/history";
+import { UID } from "../types/misc";
+import { Operation } from "./operation";
+/**
+ * A branch holds a sequence of operations.
+ * It can be represented as "A - B - C - D" if A, B, C and D are executed one
+ * after the other.
+ *
+ * @param buildTransformation Factory to build transformations
+ * @param operations initial operations
+ */
+export declare class Branch<T> {
+    private readonly buildTransformation;
+    private operations;
+    constructor(buildTransformation: TransformationFactory<T>, operations?: Operation<T>[]);
+    getOperations(): readonly Operation<T>[];
+    getOperation(operationId: UID): Operation<T>;
+    getLastOperationId(): UID | undefined;
+    /**
+     * Get the id of the operation appears first in the list of operations
+     */
+    getFirstOperationAmong(op1: UID, op2: UID): UID;
+    contains(operationId: UID): boolean;
+    /**
+     * Add the given operation as the first operation
+     */
+    prepend(operation: Operation<T>): void;
+    /**
+     * add the given operation after the given predecessorOpId
+     */
+    insert(newOperation: Operation<T>, predecessorOpId: UID): void;
+    /**
+     * Add the given operation as the last operation
+     */
+    append(operation: Operation<T>): void;
+    /**
+     * Append operations in the given branch to this branch.
+     */
+    appendBranch(branch: Branch<T>): void;
+    /**
+     * Create and return a copy of this branch, starting after the given operationId
+     */
+    fork(operationId: UID): Branch<T>;
+    /**
+     * Transform all the operations in this branch with the given transformation
+     */
+    transform(transformation: Transformation<T>): void;
+    /**
+     * Cut the branch before the operation, meaning the operation
+     * and all following operations are dropped.
+     */
+    cutBefore(operationId: UID): void;
+    /**
+     * Cut the branch after the operation, meaning all following operations are dropped.
+     */
+    cutAfter(operationId: UID): void;
+    /**
+     * Find an operation in this branch based on its id.
+     * This returns the operation itself, operations which comes before it
+     * and operation which comes after it.
+     */
+    private locateOperation;
+}

package/dist/types/history/factory.d.ts

@@ -0,0 +1,10 @@
+import { Revision } from "../collaborative/revisions";
+import { StateObserver } from "../state_observer";
+import { CoreCommand } from "../types/commands";
+import { UID } from "../types/misc";
+import { SelectiveHistory } from "./selective_history";
+export declare function buildRevisionLog(args: {
+    initialRevisionId: UID;
+    recordChanges: StateObserver["recordChanges"];
+    dispatch: (command: CoreCommand) => void;
+}): SelectiveHistory<Revision>;

package/dist/types/history/operation.d.ts

@@ -0,0 +1,18 @@
+import { Transformation } from "../types/history";
+import { UID } from "../types/misc";
+/**
+ * An Operation can be executed to change a data structure from state A
+ * to state B.
+ * It should hold the necessary data used to perform this transition.
+ * It should be possible to revert the changes made by this operation.
+ *
+ * In the context of o-spreadsheet, the data from an operation would
+ * be a revision (the commands are used to execute it, the `changes` are used
+ * to revert it).
+ */
+export declare class Operation<T> {
+    readonly id: UID;
+    readonly data: T;
+    constructor(id: UID, data: T);
+    transformed(transformation: Transformation<T>): Operation<T>;
+}

package/dist/types/history/operation_sequence.d.ts

@@ -0,0 +1,32 @@
+import { OperationSequenceNode } from "../types/history";
+import { UID } from "../types/misc";
+/**
+ * An execution object is a sequence of executionSteps (each execution step is an operation in a branch).
+ *
+ * You can iterate over the steps of an execution
+ * ```js
+ * for (const operation of execution) {
+ *   // ... do something
+ * }
+ * ```
+ */
+export declare class OperationSequence<T> implements Iterable<OperationSequenceNode<T>> {
+    private readonly operations;
+    constructor(operations: Iterable<OperationSequenceNode<T>>);
+    [Symbol.iterator](): Iterator<OperationSequenceNode<T>, void>;
+    /**
+     * Stop the operation sequence at a given operation
+     * @param operationId included
+     */
+    stopWith(operationId: UID): OperationSequence<T>;
+    /**
+     * Stop the operation sequence before a given operation
+     * @param operationId excluded
+     */
+    stopBefore(operationId: UID): OperationSequence<T>;
+    /**
+     * Start the operation sequence at a given operation
+     * @param operationId excluded
+     */
+    startAfter(operationId: UID): OperationSequence<T>;
+}

package/dist/types/history/repeat_commands/repeat_commands_generic.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "../../types/commands";
+import { Getters } from "../../types/getters";
+export declare const genericRepeatsTransforms: (typeof repeatSheetDependantCommand)[];
+export declare function repeatSheetDependantCommand<T extends Command>(getters: Getters, command: T): T;
+export declare function repeatTargetDependantCommand<T extends Command>(getters: Getters, command: T): T;
+export declare function repeatZoneDependantCommand<T extends Command>(getters: Getters, command: T): T;
+export declare function repeatPositionDependantCommand<T extends Command>(getters: Getters, command: T): T;
+export declare function repeatRangeDependantCommand<T extends Command>(getters: Getters, command: T): T;

package/dist/types/history/repeat_commands/repeat_commands_specific.d.ts

@@ -0,0 +1,13 @@
+import { AddColumnsRowsCommand, AutoresizeColumnsCommand, AutoresizeRowsCommand, CreateChartCommand, CreateFigureCommand, CreateImageOverCommand, CreateSheetCommand, DeleteCellCommand, GroupHeadersCommand, HideColumnsRowsCommand, InsertCellCommand, PasteCommand, RemoveColumnsRowsCommand, RepeatPasteCommand, ResizeColumnsRowsCommand, SortCommand, UnGroupHeadersCommand } from "../../types/commands";
+import { Getters } from "../../types/getters";
+export declare function repeatCreateChartCommand(getters: Getters, cmd: CreateChartCommand): CreateChartCommand;
+export declare function repeatCreateImageCommand(getters: Getters, cmd: CreateImageOverCommand): CreateImageOverCommand;
+export declare function repeatCreateFigureCommand(getters: Getters, cmd: CreateFigureCommand): CreateFigureCommand;
+export declare function repeatCreateSheetCommand(getters: Getters, cmd: CreateSheetCommand): CreateSheetCommand;
+export declare function repeatAddColumnsRowsCommand(getters: Getters, cmd: AddColumnsRowsCommand): AddColumnsRowsCommand;
+export declare function repeatHeaderElementCommand<T extends RemoveColumnsRowsCommand | HideColumnsRowsCommand | ResizeColumnsRowsCommand>(getters: Getters, cmd: T): T;
+export declare function repeatInsertOrDeleteCellCommand<T extends InsertCellCommand | DeleteCellCommand>(getters: Getters, cmd: T): T;
+export declare function repeatAutoResizeCommand<T extends AutoresizeColumnsCommand | AutoresizeRowsCommand>(getters: Getters, cmd: T): T;
+export declare function repeatSortCellsCommand(getters: Getters, cmd: SortCommand): SortCommand;
+export declare function repeatPasteCommand(getters: Getters, cmd: PasteCommand): RepeatPasteCommand;
+export declare function repeatGroupHeadersCommand<T extends GroupHeadersCommand | UnGroupHeadersCommand>(getters: Getters, cmd: T): T;

package/dist/types/history/repeat_commands/repeat_revision.d.ts

@@ -0,0 +1,5 @@
+import { Revision } from "../../collaborative/revisions";
+import { Command, CoreCommand } from "../../types/commands";
+import { Getters } from "../../types/getters";
+export declare function canRepeatRevision(revision: Revision | undefined): boolean;
+export declare function repeatRevision(revision: Revision, getters: Getters): CoreCommand[] | Command | undefined;

package/dist/types/history/selective_history.d.ts

@@ -0,0 +1,81 @@
+import { TransformationFactory } from "../types/history";
+import { UID } from "../types/misc";
+export declare class SelectiveHistory<T = unknown> {
+    private HEAD_BRANCH;
+    private HEAD_OPERATION;
+    private tree;
+    private readonly applyOperation;
+    private readonly revertOperation;
+    private readonly buildEmpty;
+    private readonly buildTransformation;
+    /**
+     * The selective history is a data structure used to register changes/updates of a state.
+     * Each change/update is called an "operation".
+     * The data structure allows to easily cancel (and redo) any operation individually.
+     * An operation can be represented by any data structure. It can be a "command", a "diff", etc.
+     * However it must have the following properties:
+     * - it can be applied to modify the state
+     * - it can be reverted on the state such that it was never executed.
+     * - it can be transformed given other operation (Operational Transformation)
+     *
+     * Since this data structure doesn't know anything about the state nor the structure of
+     * operations, the actual work must be performed by external functions given as parameters.
+     * @param initialOperationId
+     * @param applyOperation a function which can apply an operation to the state
+     * @param revertOperation  a function which can revert an operation from the state
+     * @param buildEmpty  a function returning an "empty" operation.
+     *                    i.e an operation that leaves the state unmodified once applied or reverted
+     *                    (used for internal implementation)
+     * @param buildTransformation Factory used to build transformations
+     */
+    constructor(args: {
+        initialOperationId: UID;
+        applyOperation: (data: T) => void;
+        revertOperation: (data: T) => void;
+        buildEmpty: (id: UID) => T;
+        buildTransformation: TransformationFactory<T>;
+    });
+    /**
+     * Return the operation identified by its id.
+     */
+    get(operationId: UID): T;
+    /**
+     * Append a new operation as the last one
+     */
+    append(operationId: UID, data: T): void;
+    /**
+     * Insert a new operation after a specific operation (may not be the last operation).
+     * Following operations will be transformed according
+     * to the new operation.
+     */
+    insert(operationId: UID, data: T, insertAfter: UID): void;
+    /**
+     * @param operationId operation to undo
+     * @param undoId the id of the "undo operation"
+     * @param insertAfter the id of the operation after which to insert the undo
+     */
+    undo(operationId: UID, undoId: UID, insertAfter: UID): void;
+    /**
+     * @param operationId operation to redo
+     * @param redoId the if of the "redo operation"
+     * @param insertAfter the id of the operation after which to insert the redo
+     */
+    redo(operationId: UID, redoId: UID, insertAfter: UID): void;
+    rebase(operationId: UID): void;
+    /**
+     * Revert the state as it was *before* the given operation was executed.
+     */
+    private revertBefore;
+    /**
+     * Revert the state as it was *after* the given operation was executed.
+     */
+    private revertTo;
+    /**
+     * Revert an execution
+     */
+    private revert;
+    /**
+     * Replay the operations between the current HEAD_BRANCH and the end of the tree
+     */
+    private fastForward;
+}

package/dist/types/history/tree.d.ts

@@ -0,0 +1,176 @@
+import { OperationSequenceNode, TransformationFactory } from "../types/history";
+import { UID } from "../types/misc";
+import { Branch } from "./branch";
+import { Operation } from "./operation";
+import { OperationSequence } from "./operation_sequence";
+/**
+ * The tree is a data structure used to maintain the different branches of the
+ * SelectiveHistory.
+ *
+ * Branches can be "stacked" on each other and an execution path can be derived
+ * from any stack of branches. The rules to derive this path is explained below.
+ *
+ * An operation can be cancelled/undone by inserting a new branch below
+ * this operation.
+ * e.g
+ *    Given the branch A    B   C
+ *    To undo B, a new branching branch is inserted at operation B.
+ *    ```txt
+ *    A   B   C   D
+ *        >   C'  D'
+ *    ```
+ *    A new execution path can now be derived. At each operation:
+ *    - if there is a lower branch, don't execute it and go to the operation below
+ *    - if not, execute it and go to the operation on the right.
+ *    The execution path is   A   C'    D'
+ *    Operation C and D have been adapted (transformed) in the lower branch
+ *    since operation B is not executed in this branch.
+ *
+ */
+export declare class Tree<T = unknown> {
+    private readonly buildTransformation;
+    private readonly branches;
+    private branchingOperationIds;
+    constructor(buildTransformation: TransformationFactory<T>, initialBranch: Branch<T>);
+    /**
+     * Return the last branch of the entire stack of branches.
+     */
+    getLastBranch(): Branch<T>;
+    /**
+     * Return the sequence of operations from this branch
+     * until the very last branch.
+     */
+    execution(branch: Branch<T>): OperationSequence<T>;
+    /**
+     * Return the sequence of operations from this branch
+     * to the very first branch.
+     */
+    revertedExecution(branch: Branch<T>): OperationSequence<T>;
+    /**
+     * Append an operation to the end of the tree.
+     * Also insert the (transformed) operation in all previous branches.
+     *
+     * Adding operation `D` to the last branch
+     * ```txt
+     *  A1   B1   C1
+     *  >    B2   C2
+     * ```
+     * will give
+     * ```txt
+     *  A1   B1   C1   D'   with D' = D transformed with A1
+     *  >    B2   C2   D
+     * ```
+     */
+    insertOperationLast(branch: Branch<T>, operation: Operation<T>): void;
+    /**
+     * Insert a new operation after an other operation.
+     * The operation will be inserted in this branch, in next branches (transformed)
+     * and in previous branches (also transformed).
+     *
+     * Given
+     * ```txt
+     *  1: A1   B1   C1
+     *  2: >    B2   C2
+     *  3:      >    C3
+     * ```
+     * Inserting D to branch 2 gives
+     * ```txt
+     *  1: A1   B1   C1   D1          D1 = D transformed with A1
+     *  2: >    B2   C2   D     with  D  = D
+     *  3:      >    C3   D2          D2 = D transformed without B2 (B2⁻¹)
+     * ```
+     */
+    insertOperationAfter(branch: Branch<T>, operation: Operation<T>, predecessorOpId: UID): void;
+    /**
+     * Create a new branching branch at the given operation.
+     * This cancels the operation from the execution path.
+     */
+    undo(branch: Branch<T>, operation: Operation<T>): void;
+    /**
+     * Remove the branch just after this one. This un-cancels (redo) the branching
+     * operation. Lower branches will be transformed accordingly.
+     *
+     * Given
+     * ```txt
+     *  1: A1   B1   C1
+     *  2: >    B2   C2
+     *  3:      >    C3
+     * ```
+     * removing the next branch of 1 gives
+     *
+     * ```txt
+     *  1: A1   B1   C1
+     *  2:      >    C3'   with  C3' = C1 transformed without B1 (B1⁻¹)
+     * ```
+     */
+    redo(branch: Branch<T>): void;
+    /**
+     * Drop the operation and all following operations in every
+     * branches
+     */
+    drop(operationId: UID): void;
+    /**
+     * Find the operation in the execution path.
+     */
+    findOperation(branch: Branch<T>, operationId: UID): OperationSequenceNode<T>;
+    /**
+     * Rebuild transformed operations of this branch based on the upper branch.
+     *
+     * Given the following structure:
+     * ```txt
+     *  1: A1   B1    C1
+     *  2: >    B2    C2
+     *  3:      >     C3
+     * ```
+     * Rebasing branch "2" gives
+     * ```txt
+     *  1: A1   B1    C1
+     *  2: >    B2'   C2'  With  B2' = B1 transformed without A1 and C2' = C1 transformed without A1
+     *  3:      >     C3'        C3' = C2' transformed without B2'
+     * ```
+     */
+    private rebaseUp;
+    private removeBranchFromTree;
+    private insertBranchAfter;
+    /**
+     * Update the branching branch of this branch, either by (1) inserting the new
+     * operation in it or (2) by transforming it.
+     * (1) If the operation is positioned before the branching branch, the branching
+     *     branch should be transformed with this operation.
+     * (2) If it's positioned after, the operation should be inserted in the
+     *     branching branch.
+     */
+    private updateNextWith;
+    private addToNextBranch;
+    private getTransformedOperation;
+    /**
+     * Check if this branch should execute the given operation.
+     * i.e. If the operation is not cancelled by a branching branch.
+     */
+    private shouldExecute;
+    private transform;
+    /**
+     * Insert a new operation in previous branches. The operations which are
+     * positioned after the inserted operations are transformed with the newly
+     * inserted operations. This one is also transformed, with the branching
+     * operation.
+     */
+    private insertPrevious;
+    private findPreviousBranchingOperation;
+    /**
+     * Retrieve the next branch of the given branch
+     */
+    private nextBranch;
+    /**
+     * Retrieve the previous branch of the given branch
+     */
+    private previousBranch;
+    /**
+     * Yields the sequence of operations to execute, in reverse order.
+     */
+    private _revertedExecution;
+    /**
+     * Yields the sequence of operations to execute
+     */
+    private _execution;
+}