@qrvey/utils 1.15.0-9 → 1.16.0-0

package/dist/elements/helpers/fixed.js

@@ -0,0 +1,236 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import { CanvasDevice } from "../interfaces/ICanvasGrid";
+import { VemPositionType } from "../interfaces/IVemPosition";
+import { dxGetFixedGridItemDevice, hasOverflow, hasOverlap, } from "../utils/fixed.position";
+import { sortByDistanceFunction } from "../utils/general";
+import { OverlapIntervalTree } from "../utils/overlap";
+import { setElementPosition } from "../utils/position";
+const SPACE_DELTA = 10;
+/**
+ * update the position for a specific device
+ * @param element element to be updated
+ * @param newDevicePosition new position attributes for the element
+ * @param device device for the update
+ * @returns new element with its position updated
+ */
+export function updateFixedPosition(element, newDevicePosition, device) {
+    var _a;
+    return Object.assign(Object.assign({}, element), { position: Object.assign(Object.assign({}, element.position), { fixed: Object.assign(Object.assign({}, element.position.fixed), { [device]: Object.assign(Object.assign({}, (_a = element.position.fixed) === null || _a === void 0 ? void 0 : _a[device]), newDevicePosition) }) }) });
+}
+/**
+ * Finds the first available position within a canvas where a new element can be placed without overlapping existing elements.
+ * @param canvasWidth - The width of the canvas in pixels.
+ * @param newElement - The new element to be placed, with fixed position properties.
+ * @param elements - The list of existing elements on the canvas.
+ * @param device - The device type (e.g., desktop, tablet, mobile) for determining element positions.
+ * @param [options] - Additional options for position finding.
+ * @param [options.canvasHeight] - The maximum height of the canvas in pixels. Defaults to `Infinity`.
+ * @param [options.findRightToLeft] - Whether to search for positions from right to left. Defaults to `false`.
+ * @param [options.initialY] - The initial Y-coordinate to start the search. Defaults to `0`.
+ * @returns - The x and y coordinates of the first available position.
+ * @throws {Error} - Throws an error if no valid position is found and `canvasHeight` is not specified.
+ */
+export function findAvailablePosition(canvasWidth, newElement, elements, device, options = {}) {
+    var _a, _b;
+    const { width: newWidth, height: newHeight } = getFixedPositionByDevice(newElement, device);
+    const canvasHeight = (_a = options.canvasHeight) !== null && _a !== void 0 ? _a : Infinity;
+    const sortedElements = options.findRightToLeft
+        ? elements
+            .slice()
+            .sort((b, a) => b.position.fixed[device].x - a.position.fixed[device].x)
+        : elements
+            .slice()
+            .sort((a, b) => a.position.fixed[device].y - b.position.fixed[device].y);
+    const intervalTree = new OverlapIntervalTree();
+    for (const element of sortedElements) {
+        const elemPosition = element.position.fixed[device];
+        intervalTree.insert(elemPosition.x, elemPosition.x + elemPosition.width, elemPosition.y, elemPosition.y + elemPosition.height);
+    }
+    let startX = options.findRightToLeft ? canvasWidth - newWidth : 0;
+    const initialY = (_b = options.initialY) !== null && _b !== void 0 ? _b : 0;
+    let increment = options.findRightToLeft ? -SPACE_DELTA : SPACE_DELTA;
+    for (let y = initialY; y <= canvasHeight - newHeight; y += SPACE_DELTA) {
+        let x = startX;
+        while (x >= 0 && x <= canvasWidth - newWidth) {
+            if (!intervalTree.overlaps(x, x + newWidth, y, y + newHeight)) {
+                return { x, y };
+            }
+            x += increment;
+        }
+        if (options.findRightToLeft) {
+            startX = 0;
+            increment = SPACE_DELTA;
+        }
+    }
+    if (options.canvasHeight)
+        return { x: 0, y: 0 };
+    throw new Error("No valid position found");
+}
+export const getFixedPositionByDevice = (item, device) => {
+    const fixedPosition = item.position.fixed;
+    const devicePosition = fixedPosition[device];
+    return isValidPosition(devicePosition) ? devicePosition : undefined;
+};
+const isValidPosition = (position) => {
+    return ((position === null || position === void 0 ? void 0 : position.y) !== undefined &&
+        position.x !== undefined &&
+        position.z !== undefined &&
+        position.height !== undefined &&
+        position.width !== undefined);
+};
+/**
+ * Finds available positions for multiple new elements within a canvas, ensuring they do not overlap with existing elements.
+ * @param canvasWidth - The width of the canvas in pixels.
+ * @param newElements - The list of new elements to be positioned, each with fixed position properties.
+ * @param elements - The list of existing elements on the canvas.
+ * @param device - The device type (e.g., desktop, tablet, mobile) for determining element positions.
+ * @param [startWithPositionY] - Whether to start the position search for each new element based on its initial Y-coordinate. Defaults to `false`.
+ * @param [findRightToLeft] - Whether to search for positions from right to left. Defaults to `false`.
+ * @param [canvasHeight] - The maximum height of the canvas in pixels. If not provided, the search height is unlimited.
+ * @returns List of elements with their recalculated positions.
+ */
+export function findFixedAvailablePositions(canvasWidth, newElements, elements, device, startWithPositionY = false, findRightToLeft = false, canvasHeight) {
+    const processedElements = elements.slice();
+    const resultElems = [];
+    newElements.forEach((nElement) => {
+        const initialY = startWithPositionY
+            ? nElement.position.fixed[device].y
+            : 0;
+        const newElement = updateFixedElementWidth(nElement, canvasWidth, device);
+        const availablePosition = findAvailablePosition(canvasWidth, newElement, processedElements, device, { initialY, findRightToLeft, canvasHeight });
+        const newElemWithPosition = updateFixedPosition(newElement, availablePosition, device);
+        resultElems.push(newElemWithPosition);
+        processedElements.push(newElemWithPosition);
+    });
+    return resultElems;
+}
+/**
+ * Recalculates the positions of elements on the canvas, preserving the position of those
+ * that meet certain conditions (no overflow or overlap). Elements that do not meet these
+ * conditions are recalculated to find a new valid position.
+ * @param elements - List of elements to recalculate.
+ * @param device - The device on which the canvas is being rendered.
+ * @param resolution - The resolution of the canvas.
+ * @param [canvasHeight] - Optional height of the canvas.
+ * @returns - List of elements with their recalculated positions.
+ */
+export const recalculatePreservingPositions = (elements, device, resolution, canvasHeight) => {
+    const keepElementPositions = getElementsWithKeepPosition([...elements], device, resolution, canvasHeight);
+    const elementIds = keepElementPositions.map((element) => element.elementId);
+    const elementsToCalculate = elements.filter((cElement) => !elementIds.includes(cElement.elementId));
+    const defaultElements = keepElementPositions.length
+        ? keepElementPositions
+        : [];
+    const currentElements = canvasHeight ? defaultElements : elements;
+    const newElements = findFixedAvailablePositions(resolution, elementsToCalculate, currentElements, device, false, false, canvasHeight);
+    return [...keepElementPositions, ...newElements];
+};
+/**
+ * Filters elements that should retain their current position on the canvas by checking
+ * that they do not have overflow (spilling outside the canvas) or overlap (colliding with other elements).
+ * @param elements - List of elements to check.
+ * @param device - The device on which the canvas is being rendered.
+ * @param resolution - The resolution of the canvas.
+ * @param [canvasHeight] - Optional height of the canvas.
+ * @returns - List of elements that can retain their current position.
+ */
+const getElementsWithKeepPosition = (elements, device, resolution, canvasHeight) => {
+    const calculatedElements = elements.map((mElement) => {
+        const desktopPosition = dxGetFixedGridItemDevice(mElement, CanvasDevice.DESKTOP);
+        return updateFixedPosition(mElement, desktopPosition, device);
+    });
+    return calculatedElements.filter((cElement) => {
+        const currentElements = calculatedElements.filter((fElement) => fElement.elementId !== cElement.elementId);
+        const overflow = hasOverflow(cElement, device, resolution, canvasHeight);
+        const overlap = hasOverlap(cElement, currentElements, device);
+        return !overflow && !overlap;
+    });
+};
+/**
+ * Adjusts the `width` of a fixed element to fit within the specified canvas width and updates its position.
+ * @param element - The fixed element to adjust.
+ * @param canvasWidth - The width of the canvas in grid columns.
+ * @param canvasDevice - The target device type (e.g., desktop, tablet, mobile).
+ * @returns - The updated responsive element with an adjusted `width`.
+ */
+export function updateFixedElementWidth(element, canvasWidth, canvasDevice) {
+    const currentPosition = element.position.fixed[canvasDevice];
+    const fixedWidth = Math.min(currentPosition === null || currentPosition === void 0 ? void 0 : currentPosition.width, canvasWidth);
+    const position = Object.assign(Object.assign({}, currentPosition), { width: fixedWidth });
+    return setElementPosition(element, VemPositionType.FIXED, canvasDevice, position);
+}
+/**
+ * Retrieves the Y-coordinate of a fixed grid element for a specific device.
+ * If `allowNegative` is false (default), the function ensures the Y-coordinate is non-negative.
+ * @param element - The element to retrieve the Y-coordinate from.
+ * @param device - The device for which the Y-coordinate is calculated.
+ * @param [allowNegative] - Whether to allow negative Y-coordinates.
+ * @returns - The Y-coordinate of the element.
+ */
+const getFixedGridElementY = (element, device, allowNegative = false) => {
+    var _a;
+    const position = element.position.fixed[device];
+    const itemY = (_a = position === null || position === void 0 ? void 0 : position.y) !== null && _a !== void 0 ? _a : 0;
+    if (!allowNegative) {
+        return itemY >= 0 ? itemY : 0;
+    }
+    return itemY;
+};
+/**
+ * Retrieves the height of a fixed grid element for a specific device.
+ * @param element - The element to retrieve the height from.
+ * @param device - The device for which the height is calculated.
+ * @returns - The height of the element, or undefined if not defined.
+ */
+const getFixedGridElementHeight = (element, device) => {
+    const position = element.position.fixed[device];
+    return position === null || position === void 0 ? void 0 : position.height;
+};
+/**
+ * @param elements elements to calculate
+ * @param device  current device
+ * @returns height
+ */
+export const getFixedGridElementsBottomLimit = (elements, device) => {
+    if (!elements.length)
+        return 0;
+    return Math.max(...elements.map((element) => getFixedGridElementY(element, device) +
+        getFixedGridElementHeight(element, device)));
+};
+/**
+ * Calculates distances of elements from a given reference point on the canvas device.
+ * @param elements - Array of `VemFixed` elements to calculate distances for.
+ * @param device - Canvas device providing the coordinates of the elements.
+ * @param referencePoint - The reference point to calculate distances from.
+ * @param referencePoint.x
+ * @param referencePoint.y
+ * @returns An array of objects containing the original elements and their calculated distances from the reference point.
+ */
+export const calculateDistancesToReferencePoint = (elements, device, referencePoint) => {
+    return elements.map((element) => {
+        const elementPosition = getFixedPositionByDevice(element, device);
+        if (!elementPosition) {
+            throw new Error(`Position for device ${device} is undefined for element with Id ${element.elementId}.`);
+        }
+        const distance = Math.pow(referencePoint.x - elementPosition.x, 2) +
+            Math.pow(referencePoint.y - elementPosition.y, 2);
+        return {
+            distance,
+            element,
+        };
+    });
+};
+/**
+ * Sorts elements based on their distance from a reference point on the canvas.
+ * @param elements - Array of `VemFixed` elements to be sorted.
+ * @param device - Canvas device providing the coordinates of the elements.
+ * @param referencePoint - The reference point to calculate distances from.
+ * @param referencePoint.x
+ * @param referencePoint.y
+ * @returns An array of `VemFixed` elements sorted by their distance from the reference point (0, 0).
+ */
+export const sortElementsFromReferencePoint = (elements, device, referencePoint) => {
+    const calculatedElements = calculateDistancesToReferencePoint(elements, device, referencePoint);
+    const sortedElements = [...calculatedElements].sort(sortByDistanceFunction);
+    return sortedElements.map((element) => element.element);
+};

package/dist/elements/helpers/gridStrategy.d.ts

@@ -0,0 +1,29 @@
+import { CanvasDevice, Vem } from "../interfaces";
+interface RecalculateOptions {
+    canvasHeight?: number;
+    sort?: CanvasDevice;
+    allowCopy?: boolean;
+    keepPosition?: boolean;
+}
+/**
+ * Recalculates the positions of elements on a canvas based on the canvas type.
+ * @param newElements - The list of elements to be recalculated. Each element has properties based on its type.
+ * @param currentElements - The list of elements to be recalculated. Each element has properties based on its type.
+ * @param canvasWidth - The width of the canvas in pixels.
+ * @param canvasType - The type of canvas (e.g., "fixed") that determines how positions are recalculated.
+ * @param device - The device type (e.g., desktop, tablet, mobile) for determining element positions.
+ * @param canvasHeight -  variable for the canvas with header component
+ * @param options
+ * @returns - A list of elements with updated positions if the canvas type is "fixed" or "responsive".
+ */
+export declare function recalculateElements(newElements: Vem[], currentElements: Vem[], canvasWidth: number, canvasType: string, device: CanvasDevice, options?: RecalculateOptions): Vem[];
+/**
+ * The calculation is delegated to a specific strategy based on the `canvasType`.
+ * @param elements - The list of elements in the canvas.
+ * @param canvasType - The type of canvas (e.g., "fixed", "responsive").
+ * @param device - The target device type (e.g., desktop, tablet, mobile).
+ * @param [rowGap] - The optional gap (in pixels) between rows in the canvas.
+ * @returns - The calculated canvas height based on the selected strategy. Returns an empty array if no strategy is found.
+ */
+export declare function calculateCanvasHeight(elements: Vem[], canvasType: string, device: CanvasDevice, rowGap?: number): number;
+export {};

package/dist/elements/helpers/gridStrategy.js

@@ -0,0 +1,78 @@
+import { findFixedAvailablePositions, getFixedGridElementsBottomLimit, recalculatePreservingPositions, sortElementsFromReferencePoint, } from "./fixed";
+import { findResponsiveAvailablePositions, getResponsiveGridElementsBottomLimit, sortResponsiveElements, } from "./responsive";
+import { CanvasDevice, VemPositionType, } from "../interfaces";
+import { copyDesktopPositionToDevice } from "../utils/element";
+const recalculateStrategies = {
+    fixed: (elements, currentElements, canvasWidth, device, options) => {
+        const isSorted = !currentElements.length;
+        const changedElements = (options.allowCopy
+            ? copyDesktopPositionToDevice(elements, device, VemPositionType.FIXED)
+            : elements);
+        // sort elements
+        const orderedElements = isSorted
+            ? sortElementsFromReferencePoint(changedElements, options.sort, {
+                x: 0,
+                y: 0,
+            })
+            : changedElements;
+        return options.canvasHeight
+            ? recalculatePreservingPositions(orderedElements, device, canvasWidth, options.canvasHeight)
+            : findFixedAvailablePositions(canvasWidth, orderedElements, currentElements, device, false, false, options === null || options === void 0 ? void 0 : options.canvasHeight);
+    },
+    responsive: (elements, currentElements, canvasWidth, device, options) => {
+        const isSorted = !currentElements.length;
+        const changedElements = (options.allowCopy
+            ? copyDesktopPositionToDevice(elements, device, VemPositionType.RESPONSIVE)
+            : elements);
+        const orderedElements = isSorted
+            ? sortResponsiveElements(changedElements, options.sort)
+            : changedElements;
+        return findResponsiveAvailablePositions(canvasWidth, orderedElements, currentElements, device);
+    },
+};
+const calculateCanvasHeightStrategies = {
+    fixed: (elements, device) => {
+        return getFixedGridElementsBottomLimit(elements, device);
+    },
+    responsive: (elements, device, rowGap) => {
+        return getResponsiveGridElementsBottomLimit(elements, device, rowGap);
+    },
+};
+/**
+ * Recalculates the positions of elements on a canvas based on the canvas type.
+ * @param newElements - The list of elements to be recalculated. Each element has properties based on its type.
+ * @param currentElements - The list of elements to be recalculated. Each element has properties based on its type.
+ * @param canvasWidth - The width of the canvas in pixels.
+ * @param canvasType - The type of canvas (e.g., "fixed") that determines how positions are recalculated.
+ * @param device - The device type (e.g., desktop, tablet, mobile) for determining element positions.
+ * @param canvasHeight -  variable for the canvas with header component
+ * @param options
+ * @returns - A list of elements with updated positions if the canvas type is "fixed" or "responsive".
+ */
+export function recalculateElements(newElements, currentElements, canvasWidth, canvasType, device, options) {
+    const strategy = recalculateStrategies[canvasType];
+    if (!strategy) {
+        return [];
+    }
+    const defaultOptions = {
+        sort: CanvasDevice.DESKTOP,
+        allowCopy: true,
+    };
+    const calculatedOptions = Object.assign(Object.assign({}, defaultOptions), options);
+    return strategy(newElements, currentElements, canvasWidth, device, calculatedOptions);
+}
+/**
+ * The calculation is delegated to a specific strategy based on the `canvasType`.
+ * @param elements - The list of elements in the canvas.
+ * @param canvasType - The type of canvas (e.g., "fixed", "responsive").
+ * @param device - The target device type (e.g., desktop, tablet, mobile).
+ * @param [rowGap] - The optional gap (in pixels) between rows in the canvas.
+ * @returns - The calculated canvas height based on the selected strategy. Returns an empty array if no strategy is found.
+ */
+export function calculateCanvasHeight(elements, canvasType, device, rowGap) {
+    const strategy = calculateCanvasHeightStrategies[canvasType];
+    if (!strategy) {
+        return 0;
+    }
+    return strategy(elements, device, rowGap);
+}

package/dist/elements/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./gridStrategy";
+export { updateFixedElementWidth } from "./fixed";
+export { updateResponsiveElementColSpan } from "./responsive";

package/dist/elements/helpers/index.js

@@ -0,0 +1,3 @@
+export * from "./gridStrategy";
+export { updateFixedElementWidth } from "./fixed";
+export { updateResponsiveElementColSpan } from "./responsive";

package/dist/elements/helpers/responsive.d.ts

@@ -0,0 +1,87 @@
+import { CanvasDevice } from "../interfaces/ICanvasGrid";
+import { VemResponsive } from "../interfaces/IVemCore";
+import { VemPositionResponsive } from "../interfaces/IVemPosition";
+/**
+ * Finds the first available position for a new responsive element within a canvas.
+ * @param canvasWidth - The width of the canvas in terms of columns.
+ * @param newElement - The new responsive element to place on the canvas.
+ * @param elements - The existing elements on the canvas.
+ * @param device - The target device type (e.g., desktop, tablet, mobile) to calculate responsive positions.
+ * @returns - The column and row start positions for the new element, or `undefined` if no valid position is found.
+ */
+export declare function findAvailablePosition(canvasWidth: number, newElement: VemResponsive, elements: VemResponsive[], device: CanvasDevice): {
+    colStart: number;
+    rowStart: number;
+} | undefined;
+/**
+ * Updates the responsive position of a given element for a specified device.
+ * @param element - The responsive element to update.
+ * @param newPosition - The new position values to update for the element.
+ * @param device - The target device type (e.g., desktop, tablet, mobile) for which the position is updated.
+ * @returns - A new `VemResponsive` object with the updated responsive position for the specified device.
+ */
+export declare function updateResponsivePosition(element: VemResponsive, newPosition: Partial<VemPositionResponsive>, device: CanvasDevice): VemResponsive;
+/**
+ * Finds available positions for a list of responsive elements on a canvas and updates their positions.
+ * @param canvasWidth - The width of the canvas in grid columns.
+ * @param newElements - The list of new responsive elements to position.
+ * @param elements - The list of existing responsive elements already positioned on the canvas.
+ * @param device - The target device type (e.g., desktop, tablet, mobile) for which positions are calculated.
+ * @returns - A list of responsive elements with updated positions for the specified device.
+ */
+export declare function findResponsiveAvailablePositions(canvasWidth: number, newElements: VemResponsive[], elements: VemResponsive[], device: CanvasDevice): VemResponsive[];
+/**
+ * Adjusts the `colSpan` of a responsive element to fit within the specified canvas width and updates its position.
+ * @param element - The responsive element to adjust.
+ * @param canvasWidth - The width of the canvas in grid columns.
+ * @param canvasDevice - The target device type (e.g., desktop, tablet, mobile).
+ * @returns - The updated responsive element with an adjusted `colSpan`.
+ */
+export declare function updateResponsiveElementColSpan(element: VemResponsive, canvasWidth: number, canvasDevice: CanvasDevice): VemResponsive;
+export declare const getResponsiveGridElementsBottomLimit: (elements: VemResponsive[], device: CanvasDevice, rowGap: number) => number;
+/**
+ * Calculates the distances of elements from a reference point and returns a list of objects
+ * containing the calculated distance and the corresponding element.
+ * @param elements - An array of `VemResponsive` objects. Each object represents an element with
+ *                   a `position` property that contains responsive positions for various devices.
+ * @param device - The specific device type (key of `CanvasDevice`) to determine the responsive position.
+ * @param referencePoint - An object representing the reference point with `x` and `y` coordinates.
+ * @param referencePoint.x
+ * @param referencePoint.y
+ * @returns - An array of objects, where each object contains:
+ *            - `distance`: The squared Euclidean distance from the reference point.
+ *            - `element`: The corresponding `VemResponsive` object.
+ */
+export declare const calculateDistancesToReferencePoint: (elements: VemResponsive[], device: CanvasDevice, referencePoint: {
+    x: number;
+    y: number;
+}) => {
+    distance: number;
+    element: VemResponsive;
+}[];
+/**
+/**
+Sorts objects containing a `distance` and `element` by distance in ascending order.
+If two objects have the same distance, it resolves the tie by comparing the `colStart` property
+of their responsive positions for the `DESKTOP` device.
+ * @param a - An object containing:
+ *            - `distance`: The calculated distance from a reference point.
+ *            - `element`: A `VemResponsive` object with responsive position data.
+ * @param b - Another object with the same structure as `a`.
+ * @param a.element
+ * @param a.distance
+ * @param _device - The device type (of type `CanvasDevice`). Currently unused in this function.
+ * @param b.distance
+ * @param b.element
+ * @returns - A negative number if `a` should come before `b`,
+ *            a positive number if `a` should come after `b`,
+ *            or 0 if they have the same distance and `colStart` values.
+ */
+export declare const sortByDistanceInResponsiveFunction: (a: {
+    distance: number;
+    element: VemResponsive;
+}, b: {
+    distance: number;
+    element: VemResponsive;
+}, _device: CanvasDevice) => number;
+export declare const sortResponsiveElements: (elements: VemResponsive<unknown>[], sortByDevice?: CanvasDevice) => VemResponsive<unknown>[];

package/dist/elements/helpers/responsive.js

@@ -0,0 +1,155 @@
+import { CanvasDevice } from "../interfaces/ICanvasGrid";
+import { VemPositionType, } from "../interfaces/IVemPosition";
+import { OverlapIntervalTree } from "../utils/overlap";
+import { setElementPosition } from "../utils/position";
+const SPACE_DELTA = 1;
+const HEIGHT_DELTA = 32;
+/**
+ * Finds the first available position for a new responsive element within a canvas.
+ * @param canvasWidth - The width of the canvas in terms of columns.
+ * @param newElement - The new responsive element to place on the canvas.
+ * @param elements - The existing elements on the canvas.
+ * @param device - The target device type (e.g., desktop, tablet, mobile) to calculate responsive positions.
+ * @returns - The column and row start positions for the new element, or `undefined` if no valid position is found.
+ */
+export function findAvailablePosition(canvasWidth, newElement, elements, device) {
+    const { colSpan: newWidth, rowSpan: newHeight } = newElement.position.responsive[device];
+    const sortedElements = elements
+        .slice()
+        .sort((a, b) => a.position.responsive[device].rowStart -
+        b.position.responsive[device].rowStart);
+    const intervalTree = new OverlapIntervalTree();
+    for (const element of sortedElements) {
+        const elemPosition = element.position.responsive[device];
+        const colEnd = elemPosition.colStart + (elemPosition.colSpan - 1);
+        const rowEnd = elemPosition.rowStart + elemPosition.rowSpan - 1;
+        if (!intervalTree.overlaps(elemPosition.colStart, colEnd, elemPosition.rowStart, rowEnd)) {
+            intervalTree.insert(elemPosition.colStart, colEnd, elemPosition.rowStart, rowEnd);
+        }
+    }
+    for (let rowStart = 1; rowStart <= Infinity - newHeight; rowStart += SPACE_DELTA) {
+        // height iteration will be until it finds a result
+        for (let colStart = 1; colStart <= canvasWidth - newWidth + 1; colStart += SPACE_DELTA) {
+            if (!intervalTree.overlaps(colStart, colStart + newWidth - 1, rowStart, rowStart + newHeight - 1)) {
+                const col = colStart === 0 ? 1 : colStart;
+                const row = rowStart === 0 ? 1 : rowStart;
+                return { colStart: col, rowStart: row };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Updates the responsive position of a given element for a specified device.
+ * @param element - The responsive element to update.
+ * @param newPosition - The new position values to update for the element.
+ * @param device - The target device type (e.g., desktop, tablet, mobile) for which the position is updated.
+ * @returns - A new `VemResponsive` object with the updated responsive position for the specified device.
+ */
+export function updateResponsivePosition(element, newPosition, device) {
+    var _a;
+    return Object.assign(Object.assign({}, element), { position: Object.assign(Object.assign({}, element.position), { responsive: Object.assign(Object.assign({}, element.position.responsive), { [device]: Object.assign(Object.assign({}, (_a = element.position.responsive) === null || _a === void 0 ? void 0 : _a[device]), newPosition) }) }) });
+}
+/**
+ * Finds available positions for a list of responsive elements on a canvas and updates their positions.
+ * @param canvasWidth - The width of the canvas in grid columns.
+ * @param newElements - The list of new responsive elements to position.
+ * @param elements - The list of existing responsive elements already positioned on the canvas.
+ * @param device - The target device type (e.g., desktop, tablet, mobile) for which positions are calculated.
+ * @returns - A list of responsive elements with updated positions for the specified device.
+ */
+export function findResponsiveAvailablePositions(canvasWidth, newElements, elements, device) {
+    const processedElements = elements.slice();
+    const resultElems = [];
+    newElements.forEach((nElement) => {
+        const newElement = updateResponsiveElementColSpan(nElement, canvasWidth, device);
+        const availablePosition = findAvailablePosition(canvasWidth, newElement, processedElements, device);
+        const newElemWithPosition = updateResponsivePosition(newElement, availablePosition, device);
+        resultElems.push(newElemWithPosition);
+        processedElements.push(newElemWithPosition);
+    });
+    return resultElems;
+}
+/**
+ * Adjusts the `colSpan` of a responsive element to fit within the specified canvas width and updates its position.
+ * @param element - The responsive element to adjust.
+ * @param canvasWidth - The width of the canvas in grid columns.
+ * @param canvasDevice - The target device type (e.g., desktop, tablet, mobile).
+ * @returns - The updated responsive element with an adjusted `colSpan`.
+ */
+export function updateResponsiveElementColSpan(element, canvasWidth, canvasDevice) {
+    const currentPosition = element.position.responsive[canvasDevice];
+    const fixedColSpan = Math.min(currentPosition.colSpan, canvasWidth);
+    const position = Object.assign(Object.assign({}, currentPosition), { colSpan: fixedColSpan });
+    return setElementPosition(element, VemPositionType.RESPONSIVE, canvasDevice, position);
+}
+export const getResponsiveGridElementsBottomLimit = (elements, device, rowGap) => {
+    if (!elements.length)
+        return 0;
+    const mappedElements = elements.map((element) => {
+        const elementPosition = element.position.responsive;
+        const maxRows = elementPosition[device].rowStart + elementPosition[device].rowSpan;
+        return maxRows * HEIGHT_DELTA + (maxRows - 1) * rowGap;
+    });
+    return Math.max(...mappedElements);
+};
+/**
+ * Calculates the distances of elements from a reference point and returns a list of objects
+ * containing the calculated distance and the corresponding element.
+ * @param elements - An array of `VemResponsive` objects. Each object represents an element with
+ *                   a `position` property that contains responsive positions for various devices.
+ * @param device - The specific device type (key of `CanvasDevice`) to determine the responsive position.
+ * @param referencePoint - An object representing the reference point with `x` and `y` coordinates.
+ * @param referencePoint.x
+ * @param referencePoint.y
+ * @returns - An array of objects, where each object contains:
+ *            - `distance`: The squared Euclidean distance from the reference point.
+ *            - `element`: The corresponding `VemResponsive` object.
+ */
+export const calculateDistancesToReferencePoint = (elements, device, referencePoint) => {
+    return elements.map((element) => {
+        var _a, _b;
+        const position = (_b = (_a = element.position) === null || _a === void 0 ? void 0 : _a.responsive) === null || _b === void 0 ? void 0 : _b[device];
+        if (!position) {
+            throw new Error(`Position for device ${device} is undefined for element with Id ${element.elementId}.`);
+        }
+        const distance = Math.pow(referencePoint.x - position.colStart, 2) +
+            Math.pow(referencePoint.y - position.rowStart, 2);
+        return {
+            distance,
+            element,
+        };
+    });
+};
+/**
+/**
+Sorts objects containing a `distance` and `element` by distance in ascending order.
+If two objects have the same distance, it resolves the tie by comparing the `colStart` property
+of their responsive positions for the `DESKTOP` device.
+ * @param a - An object containing:
+ *            - `distance`: The calculated distance from a reference point.
+ *            - `element`: A `VemResponsive` object with responsive position data.
+ * @param b - Another object with the same structure as `a`.
+ * @param a.element
+ * @param a.distance
+ * @param _device - The device type (of type `CanvasDevice`). Currently unused in this function.
+ * @param b.distance
+ * @param b.element
+ * @returns - A negative number if `a` should come before `b`,
+ *            a positive number if `a` should come after `b`,
+ *            or 0 if they have the same distance and `colStart` values.
+ */
+export const sortByDistanceInResponsiveFunction = (a, b, _device) => {
+    if (a.distance === b.distance) {
+        return (a.element.position.responsive[CanvasDevice.DESKTOP].colStart -
+            b.element.position.responsive[CanvasDevice.DESKTOP].colStart);
+    }
+    return a.distance - b.distance;
+};
+export const sortResponsiveElements = (elements, sortByDevice) => {
+    const sortedElements = calculateDistancesToReferencePoint(elements, sortByDevice, {
+        x: 1,
+        y: 1,
+    }).sort((a, b) => sortByDistanceInResponsiveFunction(a, b, sortByDevice));
+    return sortedElements.map((element) => element.element);
+};

package/dist/elements/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./helpers/index";
+export * from "./interfaces/index";

package/dist/elements/index.js

@@ -0,0 +1,2 @@
+export * from "./helpers/index";
+export * from "./interfaces/index";

package/dist/elements/interfaces/ICanvasGrid.d.ts

@@ -0,0 +1,5 @@
+export declare enum CanvasDevice {
+    DESKTOP = "desktop",
+    TABLET = "tablet",
+    MOBILE = "mobile"
+}

package/dist/elements/interfaces/ICanvasGrid.js

@@ -0,0 +1,6 @@
+export var CanvasDevice;
+(function (CanvasDevice) {
+    CanvasDevice["DESKTOP"] = "desktop";
+    CanvasDevice["TABLET"] = "tablet";
+    CanvasDevice["MOBILE"] = "mobile";
+})(CanvasDevice || (CanvasDevice = {}));

package/dist/elements/interfaces/IFixedPosition.d.ts

@@ -0,0 +1,5 @@
+export interface FindAvailablePositionOptions {
+    initialY?: number;
+    findRightToLeft?: boolean;
+    canvasHeight?: number;
+}

package/dist/elements/interfaces/IFixedPosition.js

@@ -0,0 +1 @@
+export {};

package/dist/elements/interfaces/IVemCore.d.ts

@@ -0,0 +1,29 @@
+import { VemPositionConfigFixed, VemPositionConfigMap, VemPositionConfigResponsive, VemPositionType } from "./IVemPosition";
+interface VemBase {
+    elementId: string;
+    type: string;
+    contentId?: string;
+}
+export interface VemCorePosition {
+    fixed?: VemPositionConfigFixed;
+    responsive?: VemPositionConfigResponsive;
+}
+interface VemCore<TPosition extends VemPositionType | unknown, TItemData = unknown> extends VemBase {
+    itemData: TItemData;
+    /** Indicates if its a personalized Vem */
+    isEup?: boolean;
+    /** Data to be saved in the client chart when it's saved by EUP (Only applies for VemAnalytics) */
+    chartBody?: unknown;
+    /** Dashboard Actions in the element */
+    actions?: unknown[];
+    position: TPosition extends VemPositionType ? VemCorePosition & Record<TPosition, VemPositionConfigMap[TPosition]> : VemCorePosition;
+}
+export type Vem<T = unknown, TPosition extends VemPositionType = VemPositionType> = VemCore<TPosition, T>;
+export type VemPos<TPosition extends VemPositionType> = VemCore<TPosition>;
+export type VemResponsive<T = unknown> = VemCore<VemPositionType.RESPONSIVE, T>;
+export type VemFixed<T = unknown> = VemCore<VemPositionType.FIXED, T>;
+export interface VemElementMap<T = unknown> {
+    [VemPositionType.FIXED]: VemFixed<T>;
+    [VemPositionType.RESPONSIVE]: VemResponsive<T>;
+}
+export {};