@qrvey/utils 1.15.0-13 → 1.15.0-15

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

@@ -40,9 +40,46 @@ export declare const getFixedPositionByDevice: (item: VemFixed, device: CanvasDe
  * @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

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFixedGridElementsBottomLimit = exports.findFixedAvailablePositions = exports.getFixedPositionByDevice = exports.findAvailablePosition = exports.updateFixedPosition = void 0;
+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
@@ -96,14 +99,29 @@ function findFixedAvailablePositions(canvasWidth, newElements, elements, device,
         const initialY = startWithPositionY
             ? nElement.position.fixed[device].y
             : 0;
-        const availablePosition = findAvailablePosition(canvasWidth, nElement, processedElements, device, { initialY, findRightToLeft, canvasHeight });
-        const newElemWithPosition = updateFixedPosition(nElement, availablePosition, device);
+        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];
@@ -129,3 +147,42 @@ const getFixedGridElementsBottomLimit = (elements, 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

@@ -1,13 +1,19 @@
 import { CanvasDevice, Vem } from "../interfaces";
+interface RecalculateOptions {
+    canvasHeight?: number;
+    sort?: CanvasDevice;
+}
 /**
  * Recalculates the positions of elements on a canvas based on the canvas type.
  * @param elements - 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(elements: Vem[], canvasWidth: number, canvasType: string, device: CanvasDevice): Vem[];
+export declare function recalculateElements(elements: 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.
@@ -17,3 +23,4 @@ export declare function recalculateElements(elements: Vem[], canvasWidth: number
  * @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

@@ -6,13 +6,16 @@ const responsive_1 = require("./responsive");
 const interfaces_1 = require("../interfaces");
 const element_1 = require("../utils/element");
 const recalculateStrategies = {
-    fixed: (elements, canvasWidth, device) => {
+    fixed: (elements, canvasWidth, device, options) => {
         const changedElements = (0, element_1.copyDesktopPositionToDevice)(elements, device, interfaces_1.VemPositionType.FIXED);
-        return (0, fixed_1.findFixedAvailablePositions)(canvasWidth, changedElements, [], device);
+        // sort elements
+        const orderedElements = (0, fixed_1.sortElementsFromReferencePoint)(changedElements, options.sort, { x: 0, y: 0 });
+        return (0, fixed_1.findFixedAvailablePositions)(canvasWidth, orderedElements, [], device, false, false, options === null || options === void 0 ? void 0 : options.canvasHeight);
     },
-    responsive: (elements, canvasWidth, device) => {
+    responsive: (elements, canvasWidth, device, options) => {
         const changedElements = (0, element_1.copyDesktopPositionToDevice)(elements, device, interfaces_1.VemPositionType.RESPONSIVE);
-        return (0, responsive_1.findResponsiveAvailablePositions)(canvasWidth, changedElements, [], device);
+        const orderedElements = (0, responsive_1.sortResponsiveElements)(changedElements, options.sort);
+        return (0, responsive_1.findResponsiveAvailablePositions)(canvasWidth, orderedElements, [], device);
     },
 };
 const calculateCanvasHeightStrategies = {
@@ -29,14 +32,20 @@ const calculateCanvasHeightStrategies = {
  * @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(elements, canvasWidth, canvasType, device) {
+function recalculateElements(elements, canvasWidth, canvasType, device, options) {
     const strategy = recalculateStrategies[canvasType];
     if (!strategy) {
         return [];
     }
-    return strategy(elements, canvasWidth, device);
+    const defaultOptions = {
+        sort: interfaces_1.CanvasDevice.DESKTOP,
+    };
+    const calculatedOptions = Object.assign(Object.assign({}, defaultOptions), options);
+    return strategy(elements, canvasWidth, device, calculatedOptions);
 }
 exports.recalculateElements = recalculateElements;
 /**

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

@@ -39,3 +39,49 @@ export declare function findResponsiveAvailablePositions(canvasWidth: number, ne
  */
 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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getResponsiveGridElementsBottomLimit = exports.calculateColSpan = exports.findResponsiveAvailablePositions = exports.updateResponsivePosition = exports.findAvailablePosition = void 0;
+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");
@@ -100,3 +101,66 @@ const getResponsiveGridElementsBottomLimit = (elements, device, 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;

package/dist/cjs/elements/utils/general.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compares two objects based on their `distance` property and determines their relative order.
+ * @param a - An object with a `distance` property (number).
+ * @param b - Another object with a `distance` property (number).
+ * @param a.distance
+ * @param b.distance
+ * @returns - A negative number if `a` has a smaller distance than `b`,
+ *            a positive number if `a` has a larger distance than `b`,
+ *            or 0 if both have equal distances.
+ */
+export declare const sortByDistanceFunction: (a: {
+    distance: number;
+}, b: {
+    distance: number;
+}) => 0 | 1 | -1;

package/dist/cjs/elements/utils/general.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortByDistanceFunction = void 0;
+/**
+ * Compares two objects based on their `distance` property and determines their relative order.
+ * @param a - An object with a `distance` property (number).
+ * @param b - Another object with a `distance` property (number).
+ * @param a.distance
+ * @param b.distance
+ * @returns - A negative number if `a` has a smaller distance than `b`,
+ *            a positive number if `a` has a larger distance than `b`,
+ *            or 0 if both have equal distances.
+ */
+const sortByDistanceFunction = (a, b) => {
+    if (a.distance === b.distance) {
+        return 0;
+    }
+    return a.distance < b.distance ? -1 : 1;
+};
+exports.sortByDistanceFunction = sortByDistanceFunction;

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

@@ -40,9 +40,46 @@ export declare const getFixedPositionByDevice: (item: VemFixed, device: CanvasDe
  * @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/elements/helpers/fixed.js

@@ -1,4 +1,7 @@
+import { VemPositionType } from "../interfaces/IVemPosition";
+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
@@ -90,13 +93,27 @@ export function findFixedAvailablePositions(canvasWidth, newElements, elements,
         const initialY = startWithPositionY
             ? nElement.position.fixed[device].y
             : 0;
-        const availablePosition = findAvailablePosition(canvasWidth, nElement, processedElements, device, { initialY, findRightToLeft, canvasHeight });
-        const newElemWithPosition = updateFixedPosition(nElement, availablePosition, device);
+        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;
 }
+/**
+ * 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 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 setElementPosition(element, VemPositionType.FIXED, canvasDevice, position);
+}
 const getFixedGridElementY = (element, device, allowNegative = false) => {
     var _a;
     const position = element.position.fixed[device];
@@ -121,3 +138,40 @@ export const getFixedGridElementsBottomLimit = (elements, device) => {
     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

@@ -1,13 +1,19 @@
 import { CanvasDevice, Vem } from "../interfaces";
+interface RecalculateOptions {
+    canvasHeight?: number;
+    sort?: CanvasDevice;
+}
 /**
  * Recalculates the positions of elements on a canvas based on the canvas type.
  * @param elements - 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(elements: Vem[], canvasWidth: number, canvasType: string, device: CanvasDevice): Vem[];
+export declare function recalculateElements(elements: 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.
@@ -17,3 +23,4 @@ export declare function recalculateElements(elements: Vem[], canvasWidth: number
  * @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

@@ -1,15 +1,18 @@
-import { findFixedAvailablePositions, getFixedGridElementsBottomLimit, } from "./fixed";
-import { findResponsiveAvailablePositions, getResponsiveGridElementsBottomLimit, } from "./responsive";
-import { VemPositionType, } from "../interfaces";
+import { findFixedAvailablePositions, getFixedGridElementsBottomLimit, sortElementsFromReferencePoint, } from "./fixed";
+import { findResponsiveAvailablePositions, getResponsiveGridElementsBottomLimit, sortResponsiveElements, } from "./responsive";
+import { CanvasDevice, VemPositionType, } from "../interfaces";
 import { copyDesktopPositionToDevice } from "../utils/element";
 const recalculateStrategies = {
-    fixed: (elements, canvasWidth, device) => {
+    fixed: (elements, canvasWidth, device, options) => {
         const changedElements = copyDesktopPositionToDevice(elements, device, VemPositionType.FIXED);
-        return findFixedAvailablePositions(canvasWidth, changedElements, [], device);
+        // sort elements
+        const orderedElements = sortElementsFromReferencePoint(changedElements, options.sort, { x: 0, y: 0 });
+        return findFixedAvailablePositions(canvasWidth, orderedElements, [], device, false, false, options === null || options === void 0 ? void 0 : options.canvasHeight);
     },
-    responsive: (elements, canvasWidth, device) => {
+    responsive: (elements, canvasWidth, device, options) => {
         const changedElements = copyDesktopPositionToDevice(elements, device, VemPositionType.RESPONSIVE);
-        return findResponsiveAvailablePositions(canvasWidth, changedElements, [], device);
+        const orderedElements = sortResponsiveElements(changedElements, options.sort);
+        return findResponsiveAvailablePositions(canvasWidth, orderedElements, [], device);
     },
 };
 const calculateCanvasHeightStrategies = {
@@ -26,14 +29,20 @@ const calculateCanvasHeightStrategies = {
  * @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(elements, canvasWidth, canvasType, device) {
+export function recalculateElements(elements, canvasWidth, canvasType, device, options) {
     const strategy = recalculateStrategies[canvasType];
     if (!strategy) {
         return [];
     }
-    return strategy(elements, canvasWidth, device);
+    const defaultOptions = {
+        sort: CanvasDevice.DESKTOP,
+    };
+    const calculatedOptions = Object.assign(Object.assign({}, defaultOptions), options);
+    return strategy(elements, canvasWidth, device, calculatedOptions);
 }
 /**
  * The calculation is delegated to a specific strategy based on the `canvasType`.

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

@@ -39,3 +39,49 @@ export declare function findResponsiveAvailablePositions(canvasWidth: number, ne
  */
 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/elements/helpers/responsive.js

@@ -1,3 +1,4 @@
+import { CanvasDevice } from "../interfaces/ICanvasGrid";
 import { VemPositionType, } from "../interfaces/IVemPosition";
 import { OverlapIntervalTree } from "../utils/overlap";
 import { setElementPosition } from "../utils/position";
@@ -92,3 +93,63 @@ export const getResponsiveGridElementsBottomLimit = (elements, device, 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/utils/general.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compares two objects based on their `distance` property and determines their relative order.
+ * @param a - An object with a `distance` property (number).
+ * @param b - Another object with a `distance` property (number).
+ * @param a.distance
+ * @param b.distance
+ * @returns - A negative number if `a` has a smaller distance than `b`,
+ *            a positive number if `a` has a larger distance than `b`,
+ *            or 0 if both have equal distances.
+ */
+export declare const sortByDistanceFunction: (a: {
+    distance: number;
+}, b: {
+    distance: number;
+}) => 0 | 1 | -1;

package/dist/elements/utils/general.js

@@ -0,0 +1,16 @@
+/**
+ * Compares two objects based on their `distance` property and determines their relative order.
+ * @param a - An object with a `distance` property (number).
+ * @param b - Another object with a `distance` property (number).
+ * @param a.distance
+ * @param b.distance
+ * @returns - A negative number if `a` has a smaller distance than `b`,
+ *            a positive number if `a` has a larger distance than `b`,
+ *            or 0 if both have equal distances.
+ */
+export const sortByDistanceFunction = (a, b) => {
+    if (a.distance === b.distance) {
+        return 0;
+    }
+    return a.distance < b.distance ? -1 : 1;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qrvey/utils",
-  "version": "1.15.0-13",
+  "version": "1.15.0-15",
   "description": "Helper, Utils for all Qrvey Projects",
   "homepage": "https://bitbucket.org/qrvey/qrvey_utils/wiki/Home",
   "main": "dist/index.js",