@excalidraw/excalidraw 0.17.1-1d71f84 → 0.17.1-22b3927

package/dist/excalidraw/fractionalIndex.js

@@ -0,0 +1,239 @@
+import { generateNKeysBetween } from "fractional-indexing";
+import { mutateElement } from "./element/mutateElement";
+import { InvalidFractionalIndexError } from "./errors";
+/**
+ * Envisioned relation between array order and fractional indices:
+ *
+ * 1) Array (or array-like ordered data structure) should be used as a cache of elements order, hiding the internal fractional indices implementation.
+ * - it's undesirable to to perform reorder for each related operation, thefeore it's necessary to cache the order defined by fractional indices into an ordered data structure
+ * - it's easy enough to define the order of the elements from the outside (boundaries), without worrying about the underlying structure of fractional indices (especially for the host apps)
+ * - it's necessary to always keep the array support for backwards compatibility (restore) - old scenes, old libraries, supporting multiple excalidraw versions etc.
+ * - it's necessary to always keep the fractional indices in sync with the array order
+ * - elements with invalid indices should be detected and synced, without altering the already valid indices
+ *
+ * 2) Fractional indices should be used to reorder the elements, whenever the cached order is expected to be invalidated.
+ * - as the fractional indices are encoded as part of the elements, it opens up possibilties for incremental-like APIs
+ * - re-order based on fractional indices should be part of (multiplayer) operations such as reconcillitation & undo/redo
+ * - technically all the z-index actions could perform also re-order based on fractional indices,but in current state it would not bring much benefits,
+ *   as it's faster & more efficient to perform re-order based on array manipulation and later synchronisation of moved indices with the array order
+ */
+/**
+ * Ensure that all elements have valid fractional indices.
+ *
+ * @throws `InvalidFractionalIndexError` if invalid index is detected.
+ */
+export const validateFractionalIndices = (indices) => {
+    for (const [i, index] of indices.entries()) {
+        const predecessorIndex = indices[i - 1];
+        const successorIndex = indices[i + 1];
+        if (!isValidFractionalIndex(index, predecessorIndex, successorIndex)) {
+            throw new InvalidFractionalIndexError(`Fractional indices invariant for element has been compromised - ["${predecessorIndex}", "${index}", "${successorIndex}"] [predecessor, current, successor]`);
+        }
+    }
+};
+/**
+ * Order the elements based on the fractional indices.
+ * - when fractional indices are identical, break the tie based on the element id
+ * - when there is no fractional index in one of the elements, respect the order of the array
+ */
+export const orderByFractionalIndex = (elements) => {
+    return elements.sort((a, b) => {
+        // in case the indices are not the defined at runtime
+        if (isOrderedElement(a) && isOrderedElement(b)) {
+            if (a.index < b.index) {
+                return -1;
+            }
+            else if (a.index > b.index) {
+                return 1;
+            }
+            // break ties based on the element id
+            return a.id < b.id ? -1 : 1;
+        }
+        // defensively keep the array order
+        return 1;
+    });
+};
+/**
+ * Synchronizes invalid fractional indices of moved elements with the array order by mutating passed elements.
+ * If the synchronization fails or the result is invalid, it fallbacks to `syncInvalidIndices`.
+ */
+export const syncMovedIndices = (elements, movedElements) => {
+    try {
+        const indicesGroups = getMovedIndicesGroups(elements, movedElements);
+        // try generatating indices, throws on invalid movedElements
+        const elementsUpdates = generateIndices(elements, indicesGroups);
+        // ensure next indices are valid before mutation, throws on invalid ones
+        validateFractionalIndices(elements.map((x) => elementsUpdates.get(x)?.index || x.index));
+        // split mutation so we don't end up in an incosistent state
+        for (const [element, update] of elementsUpdates) {
+            mutateElement(element, update, false);
+        }
+    }
+    catch (e) {
+        // fallback to default sync
+        syncInvalidIndices(elements);
+    }
+    return elements;
+};
+/**
+ * Synchronizes all invalid fractional indices with the array order by mutating passed elements.
+ *
+ * WARN: in edge cases it could modify the elements which were not moved, as it's impossible to guess the actually moved elements from the elements array itself.
+ */
+export const syncInvalidIndices = (elements) => {
+    const indicesGroups = getInvalidIndicesGroups(elements);
+    const elementsUpdates = generateIndices(elements, indicesGroups);
+    for (const [element, update] of elementsUpdates) {
+        mutateElement(element, update, false);
+    }
+    return elements;
+};
+/**
+ * Get contiguous groups of indices of passed moved elements.
+ *
+ * NOTE: First and last elements within the groups are indices of lower and upper bounds.
+ */
+const getMovedIndicesGroups = (elements, movedElements) => {
+    const indicesGroups = [];
+    let i = 0;
+    while (i < elements.length) {
+        if (movedElements.has(elements[i].id)) {
+            const indicesGroup = [i - 1, i]; // push the lower bound index as the first item
+            while (++i < elements.length) {
+                if (!movedElements.has(elements[i].id)) {
+                    break;
+                }
+                indicesGroup.push(i);
+            }
+            indicesGroup.push(i); // push the upper bound index as the last item
+            indicesGroups.push(indicesGroup);
+        }
+        else {
+            i++;
+        }
+    }
+    return indicesGroups;
+};
+/**
+ * Gets contiguous groups of all invalid indices automatically detected inside the elements array.
+ *
+ * WARN: First and last items within the groups do NOT have to be contiguous, those are the found lower and upper bounds!
+ */
+const getInvalidIndicesGroups = (elements) => {
+    const indicesGroups = [];
+    // once we find lowerBound / upperBound, it cannot be lower than that, so we cache it for better perf.
+    let lowerBound = undefined;
+    let upperBound = undefined;
+    let lowerBoundIndex = -1;
+    let upperBoundIndex = 0;
+    /** @returns maybe valid lowerBound */
+    const getLowerBound = (index) => {
+        const lowerBound = elements[lowerBoundIndex]
+            ? elements[lowerBoundIndex].index
+            : undefined;
+        // we are already iterating left to right, therefore there is no need for additional looping
+        const candidate = elements[index - 1]?.index;
+        if ((!lowerBound && candidate) || // first lowerBound
+            (lowerBound && candidate && candidate > lowerBound) // next lowerBound
+        ) {
+            // WARN: candidate's index could be higher or same as the current element's index
+            return [candidate, index - 1];
+        }
+        // cache hit! take the last lower bound
+        return [lowerBound, lowerBoundIndex];
+    };
+    /** @returns always valid upperBound */
+    const getUpperBound = (index) => {
+        const upperBound = elements[upperBoundIndex]
+            ? elements[upperBoundIndex].index
+            : undefined;
+        // cache hit! don't let it find the upper bound again
+        if (upperBound && index < upperBoundIndex) {
+            return [upperBound, upperBoundIndex];
+        }
+        // set the current upperBoundIndex as the starting point
+        let i = upperBoundIndex;
+        while (++i < elements.length) {
+            const candidate = elements[i]?.index;
+            if ((!upperBound && candidate) || // first upperBound
+                (upperBound && candidate && candidate > upperBound) // next upperBound
+            ) {
+                return [candidate, i];
+            }
+        }
+        // we reached the end, sky is the limit
+        return [undefined, i];
+    };
+    let i = 0;
+    while (i < elements.length) {
+        const current = elements[i].index;
+        [lowerBound, lowerBoundIndex] = getLowerBound(i);
+        [upperBound, upperBoundIndex] = getUpperBound(i);
+        if (!isValidFractionalIndex(current, lowerBound, upperBound)) {
+            // push the lower bound index as the first item
+            const indicesGroup = [lowerBoundIndex, i];
+            while (++i < elements.length) {
+                const current = elements[i].index;
+                const [nextLowerBound, nextLowerBoundIndex] = getLowerBound(i);
+                const [nextUpperBound, nextUpperBoundIndex] = getUpperBound(i);
+                if (isValidFractionalIndex(current, nextLowerBound, nextUpperBound)) {
+                    break;
+                }
+                // assign bounds only for the moved elements
+                [lowerBound, lowerBoundIndex] = [nextLowerBound, nextLowerBoundIndex];
+                [upperBound, upperBoundIndex] = [nextUpperBound, nextUpperBoundIndex];
+                indicesGroup.push(i);
+            }
+            // push the upper bound index as the last item
+            indicesGroup.push(upperBoundIndex);
+            indicesGroups.push(indicesGroup);
+        }
+        else {
+            i++;
+        }
+    }
+    return indicesGroups;
+};
+const isValidFractionalIndex = (index, predecessor, successor) => {
+    if (!index) {
+        return false;
+    }
+    if (predecessor && successor) {
+        return predecessor < index && index < successor;
+    }
+    if (!predecessor && successor) {
+        // first element
+        return index < successor;
+    }
+    if (predecessor && !successor) {
+        // last element
+        return predecessor < index;
+    }
+    // only element in the array
+    return !!index;
+};
+const generateIndices = (elements, indicesGroups) => {
+    const elementsUpdates = new Map();
+    for (const indices of indicesGroups) {
+        const lowerBoundIndex = indices.shift();
+        const upperBoundIndex = indices.pop();
+        const fractionalIndices = generateNKeysBetween(elements[lowerBoundIndex]?.index, elements[upperBoundIndex]?.index, indices.length);
+        for (let i = 0; i < indices.length; i++) {
+            const element = elements[indices[i]];
+            elementsUpdates.set(element, {
+                index: fractionalIndices[i],
+            });
+        }
+    }
+    return elementsUpdates;
+};
+const isOrderedElement = (element) => {
+    // for now it's sufficient whether the index is there
+    // meaning, the element was already ordered in the past
+    // meaning, it is not a newly inserted element, not an unrestored element, etc.
+    // it does not have to mean that the index itself is valid
+    if (element.index) {
+        return true;
+    }
+    return false;
+};

package/dist/excalidraw/frame.d.ts

@@ -1,8 +1,8 @@
-import { ElementsMap, ElementsMapOrArray, ExcalidrawElement, ExcalidrawFrameLikeElement, NonDeleted, NonDeletedExcalidrawElement } from "./element/types";
-import { AppClassProperties, AppState, StaticCanvasAppState } from "./types";
+import type { ElementsMap, ElementsMapOrArray, ExcalidrawElement, ExcalidrawFrameLikeElement, NonDeleted, NonDeletedExcalidrawElement } from "./element/types";
+import type { AppClassProperties, AppState, StaticCanvasAppState } from "./types";
 import type { ExcalidrawElementsIncludingDeleted } from "./scene/Scene";
-import { ReadonlySetLike } from "./utility-types";
-export declare const bindElementsToFramesAfterDuplication: (nextElements: ExcalidrawElement[], oldElements: readonly ExcalidrawElement[], oldIdToDuplicatedId: Map<ExcalidrawElement["id"], ExcalidrawElement["id"]>) => void;
+import type { ReadonlySetLike } from "./utility-types";
+export declare const bindElementsToFramesAfterDuplication: (nextElements: readonly ExcalidrawElement[], oldElements: readonly ExcalidrawElement[], oldIdToDuplicatedId: Map<ExcalidrawElement["id"], ExcalidrawElement["id"]>) => void;
 export declare function isElementIntersectingFrame(element: ExcalidrawElement, frame: ExcalidrawFrameLikeElement, elementsMap: ElementsMap): boolean;
 export declare const getElementsCompletelyInFrame: (elements: readonly ExcalidrawElement[], frame: ExcalidrawFrameLikeElement, elementsMap: ElementsMap) => ExcalidrawElement[];
 export declare const isElementContainingFrame: (elements: readonly ExcalidrawElement[], element: ExcalidrawElement, frame: ExcalidrawFrameLikeElement, elementsMap: ElementsMap) => boolean;

package/dist/excalidraw/gatransforms.d.ts

@@ -1,4 +1,4 @@
-import { Line, Direction, Point } from "./ga";
+import type { Line, Direction, Point } from "./ga";
 /**
  * TODO: docs
  */

package/dist/excalidraw/gesture.d.ts

@@ -1,4 +1,4 @@
-import { PointerCoords } from "./types";
+import type { PointerCoords } from "./types";
 export declare const getCenter: (pointers: Map<number, PointerCoords>) => {
     x: number;
     y: number;

package/dist/excalidraw/groups.d.ts

@@ -1,6 +1,6 @@
-import { GroupId, ExcalidrawElement, NonDeleted, NonDeletedExcalidrawElement, ElementsMapOrArray, ElementsMap } from "./element/types";
-import { AppClassProperties, AppState, InteractiveCanvasAppState } from "./types";
-import { Mutable } from "./utility-types";
+import type { GroupId, ExcalidrawElement, NonDeleted, NonDeletedExcalidrawElement, ElementsMapOrArray, ElementsMap } from "./element/types";
+import type { AppClassProperties, AppState, InteractiveCanvasAppState } from "./types";
+import type { Mutable } from "./utility-types";
 export declare const selectGroup: (groupId: GroupId, appState: InteractiveCanvasAppState, elements: readonly NonDeleted<ExcalidrawElement>[]) => Pick<InteractiveCanvasAppState, "selectedGroupIds" | "selectedElementIds" | "editingGroupId">;
 export declare const selectGroupsForSelectedElements: {
     (appState: Pick<AppState, "selectedElementIds" | "editingGroupId">, elements: readonly NonDeletedExcalidrawElement[], prevAppState: InteractiveCanvasAppState, app: AppClassProperties | null): Mutable<Pick<InteractiveCanvasAppState, "selectedGroupIds" | "editingGroupId" | "selectedElementIds">>;
@@ -28,4 +28,6 @@ export declare const removeFromSelectedGroups: (groupIds: ExcalidrawElement["gro
     [groupId: string]: boolean;
 }) => string[];
 export declare const getMaximumGroups: (elements: ExcalidrawElement[], elementsMap: ElementsMap) => ExcalidrawElement[][];
+export declare const getNonDeletedGroupIds: (elements: ElementsMap) => Set<string>;
 export declare const elementsAreInSameGroup: (elements: ExcalidrawElement[]) => boolean;
+export declare const isInGroup: (element: NonDeletedExcalidrawElement) => boolean;

package/dist/excalidraw/groups.js

@@ -219,6 +219,20 @@ export const getMaximumGroups = (elements, elementsMap) => {
     });
     return Array.from(groups.values());
 };
+export const getNonDeletedGroupIds = (elements) => {
+    const nonDeletedGroupIds = new Set();
+    for (const [, element] of elements) {
+        // defensive check
+        if (element.isDeleted) {
+            continue;
+        }
+        // defensive fallback
+        for (const groupId of element.groupIds ?? []) {
+            nonDeletedGroupIds.add(groupId);
+        }
+    }
+    return nonDeletedGroupIds;
+};
 export const elementsAreInSameGroup = (elements) => {
     const allGroups = elements.flatMap((element) => element.groupIds);
     const groupCount = new Map();
@@ -231,3 +245,6 @@ export const elementsAreInSameGroup = (elements) => {
     }
     return maxGroup === elements.length;
 };
+export const isInGroup = (element) => {
+    return element.groupIds.length > 0;
+};

package/dist/excalidraw/history.d.ts

@@ -1,52 +1,40 @@
-import { AppState } from "./types";
-import { ExcalidrawElement } from "./element/types";
-export interface HistoryEntry {
-    appState: ReturnType<typeof clearAppStatePropertiesForHistory>;
-    elements: ExcalidrawElement[];
+import type { AppStateChange, ElementsChange } from "./change";
+import type { SceneElementsMap } from "./element/types";
+import { Emitter } from "./emitter";
+import type { Snapshot } from "./store";
+import type { AppState } from "./types";
+export declare class HistoryChangedEvent {
+    readonly isUndoStackEmpty: boolean;
+    readonly isRedoStackEmpty: boolean;
+    constructor(isUndoStackEmpty?: boolean, isRedoStackEmpty?: boolean);
 }
-declare const clearAppStatePropertiesForHistory: (appState: AppState) => {
-    selectedElementIds: Readonly<{
-        [id: string]: true;
-    }>;
-    selectedGroupIds: {
-        [groupId: string]: boolean;
-    };
-    viewBackgroundColor: string;
-    editingLinearElement: import("./element/linearElementEditor").LinearElementEditor | null;
-    editingGroupId: string | null;
-    name: string | null;
-};
-declare class History {
-    private elementCache;
-    private recording;
-    private stateHistory;
-    private redoStack;
-    private lastEntry;
-    private hydrateHistoryEntry;
-    private dehydrateHistoryEntry;
-    getSnapshotForTest(): {
-        recording: boolean;
-        stateHistory: HistoryEntry[];
-        redoStack: HistoryEntry[];
-    };
+export declare class History {
+    readonly onHistoryChangedEmitter: Emitter<[HistoryChangedEvent]>;
+    private readonly undoStack;
+    private readonly redoStack;
+    get isUndoStackEmpty(): boolean;
+    get isRedoStackEmpty(): boolean;
     clear(): void;
-    private generateEntry;
-    shouldCreateEntry(nextEntry: HistoryEntry): boolean;
-    pushEntry(appState: AppState, elements: readonly ExcalidrawElement[]): void;
-    clearRedoStack(): void;
-    redoOnce(): HistoryEntry | null;
-    undoOnce(): HistoryEntry | null;
     /**
-     * Updates history's `lastEntry` to latest app state. This is necessary
-     *  when doing undo/redo which itself doesn't commit to history, but updates
-     *  app state in a way that would break `shouldCreateEntry` which relies on
-     *  `lastEntry` to reflect last comittable history state.
-     * We can't update `lastEntry` from within history when calling undo/redo
-     *  because the action potentially mutates appState/elements before storing
-     *  it.
+     * Record a local change which will go into the history
      */
-    setCurrentState(appState: AppState, elements: readonly ExcalidrawElement[]): void;
-    resumeRecording(): void;
-    record(state: AppState, elements: readonly ExcalidrawElement[]): void;
+    record(elementsChange: ElementsChange, appStateChange: AppStateChange): void;
+    undo(elements: SceneElementsMap, appState: AppState, snapshot: Readonly<Snapshot>): void | [SceneElementsMap, AppState];
+    redo(elements: SceneElementsMap, appState: AppState, snapshot: Readonly<Snapshot>): void | [SceneElementsMap, AppState];
+    private perform;
+    private static pop;
+    private static push;
+}
+export declare class HistoryEntry {
+    readonly appStateChange: AppStateChange;
+    readonly elementsChange: ElementsChange;
+    private constructor();
+    static create(appStateChange: AppStateChange, elementsChange: ElementsChange): HistoryEntry;
+    inverse(): HistoryEntry;
+    applyTo(elements: SceneElementsMap, appState: AppState, snapshot: Readonly<Snapshot>): [SceneElementsMap, AppState, boolean];
+    /**
+     * Apply latest (remote) changes to the history entry, creates new instance of `HistoryEntry`.
+     */
+    applyLatestChanges(elements: SceneElementsMap): HistoryEntry;
+    isEmpty(): boolean;
 }
-export default History;