@qrvey/utils 1.15.0-2 → 1.15.0-20

package/dist/cjs/elements/helpers/fixed.d.ts

@@ -0,0 +1,85 @@
+import { CanvasDevice } from "../interfaces/ICanvasGrid";
+import { FindAvailablePositionOptions } from "../interfaces/IFixedPosition";
+import { VemFixed } from "../interfaces/IVemCore";
+import { VemPositionFixed } from "../interfaces/IVemPosition";
+/**
+ * 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 declare function updateFixedPosition(element: VemFixed, newDevicePosition: Partial<VemPositionFixed>, device: CanvasDevice): VemFixed;
+/**
+ * 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 declare function findAvailablePosition(canvasWidth: number, newElement: VemFixed, elements: VemFixed[], device: CanvasDevice, options?: FindAvailablePositionOptions): {
+    x: number;
+    y: number;
+};
+export declare const getFixedPositionByDevice: (item: VemFixed, device: CanvasDevice) => VemPositionFixed | 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
+ */
+export declare function findFixedAvailablePositions(canvasWidth: number, newElements: VemFixed[], elements: VemFixed[], device: CanvasDevice, startWithPositionY?: boolean, findRightToLeft?: boolean, canvasHeight?: number): VemFixed[];
+/**
+ * Adjusts the `width` of a responsive 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 declare function calculateWidth(element: VemFixed, canvasWidth: number, canvasDevice: CanvasDevice): VemFixed;
+/**
+ * @param elements elements to calculate
+ * @param device  current device
+ * @returns height
+ */
+export declare const getFixedGridElementsBottomLimit: (elements: VemFixed[], device: CanvasDevice) => number;
+/**
+ * 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 declare const calculateDistancesToReferencePoint: (elements: VemFixed[], device: CanvasDevice, referencePoint: {
+    x: number;
+    y: number;
+}) => {
+    distance: number;
+    element: VemFixed;
+}[];
+/**
+ * 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 declare const sortElementsFromReferencePoint: (elements: VemFixed<unknown>[], device: CanvasDevice, referencePoint: {
+    x: number;
+    y: number;
+}) => VemFixed<unknown>[];

package/dist/cjs/elements/helpers/fixed.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortElementsFromReferencePoint = exports.calculateDistancesToReferencePoint = exports.getFixedGridElementsBottomLimit = exports.calculateWidth = exports.findFixedAvailablePositions = exports.getFixedPositionByDevice = exports.findAvailablePosition = exports.updateFixedPosition = void 0;
+const IVemPosition_1 = require("../interfaces/IVemPosition");
+const general_1 = require("../utils/general");
+const overlap_1 = require("../utils/overlap");
+const position_1 = require("../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
+ */
+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) }) }) });
+}
+exports.updateFixedPosition = updateFixedPosition;
+/**
+ * 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.
+ */
+function findAvailablePosition(canvasWidth, newElement, elements, device, options = {}) {
+    var _a, _b;
+    const { width: newWidth, height: newHeight } = (0, exports.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 overlap_1.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");
+}
+exports.findAvailablePosition = findAvailablePosition;
+const getFixedPositionByDevice = (item, device) => {
+    const fixedPosition = item.position.fixed;
+    const devicePosition = fixedPosition[device];
+    return isValidPosition(devicePosition) ? devicePosition : undefined;
+};
+exports.getFixedPositionByDevice = getFixedPositionByDevice;
+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
+ */
+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 = calculateWidth(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;
+}
+exports.findFixedAvailablePositions = findFixedAvailablePositions;
+/**
+ * Adjusts the `width` of a responsive 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`.
+ */
+function calculateWidth(element, canvasWidth, canvasDevice) {
+    const currentPosition = element.position.fixed[canvasDevice];
+    const fixedWidth = Math.min(currentPosition.width, canvasWidth);
+    const position = Object.assign(Object.assign({}, currentPosition), { width: fixedWidth });
+    return (0, position_1.setElementPosition)(element, IVemPosition_1.VemPositionType.FIXED, canvasDevice, position);
+}
+exports.calculateWidth = calculateWidth;
+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;
+};
+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
+ */
+const getFixedGridElementsBottomLimit = (elements, device) => {
+    if (!elements.length)
+        return 0;
+    return Math.max(...elements.map((element) => getFixedGridElementY(element, device) +
+        getFixedGridElementHeight(element, device)));
+};
+exports.getFixedGridElementsBottomLimit = getFixedGridElementsBottomLimit;
+/**
+ * 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.
+ */
+const calculateDistancesToReferencePoint = (elements, device, referencePoint) => {
+    return elements.map((element) => {
+        const elementPosition = (0, exports.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,
+        };
+    });
+};
+exports.calculateDistancesToReferencePoint = calculateDistancesToReferencePoint;
+/**
+ * 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).
+ */
+const sortElementsFromReferencePoint = (elements, device, referencePoint) => {
+    const calculatedElements = (0, exports.calculateDistancesToReferencePoint)(elements, device, referencePoint);
+    const sortedElements = [...calculatedElements].sort(general_1.sortByDistanceFunction);
+    return sortedElements.map((element) => element.element);
+};
+exports.sortElementsFromReferencePoint = sortElementsFromReferencePoint;

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

@@ -0,0 +1,28 @@
+import { CanvasDevice, Vem } from "../interfaces";
+interface RecalculateOptions {
+    canvasHeight?: number;
+    sort?: CanvasDevice;
+    allowCopy?: 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/cjs/elements/helpers/gridStrategy.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCanvasHeight = exports.recalculateElements = void 0;
+const fixed_1 = require("./fixed");
+const responsive_1 = require("./responsive");
+const interfaces_1 = require("../interfaces");
+const element_1 = require("../utils/element");
+const recalculateStrategies = {
+    fixed: (elements, currentElements, canvasWidth, device, options) => {
+        const isSorted = !currentElements.length;
+        const changedElements = (options.allowCopy
+            ? (0, element_1.copyDesktopPositionToDevice)(elements, device, interfaces_1.VemPositionType.FIXED)
+            : elements);
+        // sort elements
+        const orderedElements = isSorted
+            ? (0, fixed_1.sortElementsFromReferencePoint)(changedElements, options.sort, {
+                x: 0,
+                y: 0,
+            })
+            : changedElements;
+        return (0, fixed_1.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
+            ? (0, element_1.copyDesktopPositionToDevice)(elements, device, interfaces_1.VemPositionType.RESPONSIVE)
+            : elements);
+        const orderedElements = isSorted
+            ? (0, responsive_1.sortResponsiveElements)(changedElements, options.sort)
+            : changedElements;
+        return (0, responsive_1.findResponsiveAvailablePositions)(canvasWidth, orderedElements, currentElements, device);
+    },
+};
+const calculateCanvasHeightStrategies = {
+    fixed: (elements, device) => {
+        return (0, fixed_1.getFixedGridElementsBottomLimit)(elements, device);
+    },
+    responsive: (elements, device, rowGap) => {
+        return (0, responsive_1.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".
+ */
+function recalculateElements(newElements, currentElements, canvasWidth, canvasType, device, options) {
+    const strategy = recalculateStrategies[canvasType];
+    if (!strategy) {
+        return [];
+    }
+    const defaultOptions = {
+        sort: interfaces_1.CanvasDevice.DESKTOP,
+        allowCopy: true,
+    };
+    const calculatedOptions = Object.assign(Object.assign({}, defaultOptions), options);
+    return strategy(newElements, currentElements, canvasWidth, device, calculatedOptions);
+}
+exports.recalculateElements = recalculateElements;
+/**
+ * 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.
+ */
+function calculateCanvasHeight(elements, canvasType, device, rowGap) {
+    const strategy = calculateCanvasHeightStrategies[canvasType];
+    if (!strategy) {
+        return 0;
+    }
+    return strategy(elements, device, rowGap);
+}
+exports.calculateCanvasHeight = calculateCanvasHeight;

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

@@ -0,0 +1 @@
+export * from "./gridStrategy";

package/dist/cjs/elements/helpers/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./gridStrategy"), exports);

package/dist/cjs/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 calculateColSpan(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/cjs/elements/helpers/responsive.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortResponsiveElements = exports.sortByDistanceInResponsiveFunction = exports.calculateDistancesToReferencePoint = exports.getResponsiveGridElementsBottomLimit = exports.calculateColSpan = exports.findResponsiveAvailablePositions = exports.updateResponsivePosition = exports.findAvailablePosition = void 0;
+const ICanvasGrid_1 = require("../interfaces/ICanvasGrid");
+const IVemPosition_1 = require("../interfaces/IVemPosition");
+const overlap_1 = require("../utils/overlap");
+const position_1 = require("../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.
+ */
+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 overlap_1.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;
+}
+exports.findAvailablePosition = findAvailablePosition;
+/**
+ * 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.
+ */
+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) }) }) });
+}
+exports.updateResponsivePosition = updateResponsivePosition;
+/**
+ * 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.
+ */
+function findResponsiveAvailablePositions(canvasWidth, newElements, elements, device) {
+    const processedElements = elements.slice();
+    const resultElems = [];
+    newElements.forEach((nElement) => {
+        const newElement = calculateColSpan(nElement, canvasWidth, device);
+        const availablePosition = findAvailablePosition(canvasWidth, newElement, processedElements, device);
+        const newElemWithPosition = updateResponsivePosition(newElement, availablePosition, device);
+        resultElems.push(newElemWithPosition);
+        processedElements.push(newElemWithPosition);
+    });
+    return resultElems;
+}
+exports.findResponsiveAvailablePositions = findResponsiveAvailablePositions;
+/**
+ * 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`.
+ */
+function calculateColSpan(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 (0, position_1.setElementPosition)(element, IVemPosition_1.VemPositionType.RESPONSIVE, canvasDevice, position);
+}
+exports.calculateColSpan = calculateColSpan;
+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);
+};
+exports.getResponsiveGridElementsBottomLimit = getResponsiveGridElementsBottomLimit;
+/**
+ * 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.
+ */
+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,
+        };
+    });
+};
+exports.calculateDistancesToReferencePoint = calculateDistancesToReferencePoint;
+/**
+/**
+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.
+ */
+const sortByDistanceInResponsiveFunction = (a, b, _device) => {
+    if (a.distance === b.distance) {
+        return (a.element.position.responsive[ICanvasGrid_1.CanvasDevice.DESKTOP].colStart -
+            b.element.position.responsive[ICanvasGrid_1.CanvasDevice.DESKTOP].colStart);
+    }
+    return a.distance - b.distance;
+};
+exports.sortByDistanceInResponsiveFunction = sortByDistanceInResponsiveFunction;
+const sortResponsiveElements = (elements, sortByDevice) => {
+    const sortedElements = (0, exports.calculateDistancesToReferencePoint)(elements, sortByDevice, {
+        x: 1,
+        y: 1,
+    }).sort((a, b) => (0, exports.sortByDistanceInResponsiveFunction)(a, b, sortByDevice));
+    return sortedElements.map((element) => element.element);
+};
+exports.sortResponsiveElements = sortResponsiveElements;