@dwelle/excalidraw 0.5.0-bb58eff → 0.5.0-bcfbd91

package/dist/excalidraw/fractionalIndex.js

@@ -1,241 +0,0 @@
-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) &&
-            !isValidFractionalIndex(elements[i]?.index, elements[i - 1]?.index, elements[i + 1]?.index)) {
-            const indicesGroup = [i - 1, i]; // push the lower bound index as the first item
-            while (++i < elements.length) {
-                if (!(movedElements.has(elements[i].id) &&
-                    !isValidFractionalIndex(elements[i]?.index, elements[i - 1]?.index, elements[i + 1]?.index))) {
-                    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;
-};