grid-mapper-utils v1.0.0

Grid Management Functions in TypeScript

This documentation provides an overview of TypeScript functions for managing grid-based layouts. These functions offer utilities for mapping and sorting grid items, finding empty cells, and more.

Table of Contents

• mapGridItems
• calculateTotalGridRows
• findEmptyCells
• findPositionsForYxZBlocks
• mergeAndOrderBlocks
• mapCoordinates
• mapGrid

EXAMPLE OF A BLOCK

"block1": {
     "blockName": "ExampleBlockName",
     "displayDetails": {
        "rows": 2, 
        "cols": 6
     }
}

mapGridItems Function

The mapGridItems function maps a list of items to grid positions, considering item dimensions and available grid space. It takes the following parameters:

function mapGridItems(
    items: any[],
    TOTAL_COLS: number = 12,
    MIN_COLS: number = 4,
    paths: Paths = {
        cols: 'displayDetails.cols',
        rows: 'displayDetails.rows',
        name: 'blockName'
    }
): MapGridItemsResult {
    // Implementation...
}

This function returns a MapGridItemsResult object with two properties: mapped and occupied, which represent the mapped grid items and the occupied grid positions, respectively.

calculateTotalGridRows Function

The calculateTotalGridRows function calculates the total number of rows required for the grid based on the mapped grid items.

function calculateTotalGridRows(gridMap: GridItem[] = []): number {
    // Implementation...
}

It takes the gridMap as input, which is an array of GridItem objects representing the mapped grid items.

findEmptyCells Function

The findEmptyCells function identifies and returns a list of empty cells within the grid. It takes into account the total number of rows and columns and considers the occupied cells.

function findEmptyCells(cols: number = 12, rows: number, occupiedCells: OccupiedCell[] = []): OccupiedCell[] {
    // Implementation...
}

This function returns an array of OccupiedCell objects representing the coordinates of empty cells.

findPositionsForYxZBlocks Function

The findPositionsForYxZBlocks function finds positions within the grid suitable for inserting blocks of specific dimensions. It considers the available space and avoids collisions with occupied cells.

function findPositionsForYxZBlocks(
    cols: number,
    rows: number,
    occupiedCells: OccupiedCell[],
    consecutiveEmptyCells: number = 4,
    objectToInsert: GridItem = { w: 4, h: 1, item: null }
): GridItem[] {
    // Implementation...
}

It returns an array of GridItem objects representing the positions for blocks.

mergeAndOrderBlocks Function

The mergeAndOrderBlocks function merges grid positions and block positions and orders them by x-coordinate and then y-coordinate.

function mergeAndOrderBlocks(gridMap: GridItem[], blockPositions: GridItem[]): GridItem[] {
    // Implementation...
}

It takes two arrays, gridMap and blockPositions, and returns a sorted array of GridItem objects.

mapCoordinates Function

The mapCoordinates function maps a list of GridItem objects to a dictionary for easy retrieval.

function mapCoordinates(dataArray: GridItem[]): Record<string, string | null> {
    // Implementation...
}

It returns a dictionary where the keys represent the coordinates of grid items, and the values represent the associated item names.

mapGrid Function

The mapGrid function combines the functionality of the previous functions to map, sort, and organize grid items within a specified grid layout.

function mapGrid(items: any[], options: GridMapOptions = {
    totalCols: 12,
    minCols: 4,
    paths: {
        cols: 'displayDetails.cols',
        rows: 'displayDetails.rows',
        name: 'blockName'
    },
    replaceEmptyCells: false,
    emptyCellReplacement: { w: 4, h: 1, item: null }
}): Record<string, string | null> {
    // Implementation...
}

Example

const items = [
    {
        blockName: "Item A",
        displayDetails: {
            cols: 6,
            rows: 2,
        },
    },
    {
        blockName: "Item B",
        displayDetails: {
            cols: 4,
            rows: 1,
        },
    },
    {
        blockName: "Item C",
        displayDetails: {
            cols: 4,
            rows: 1,
        },
    },
    {
        blockName: "Item D",
        displayDetails: {
            cols: 6,
            rows: 1,
        },
    },
];

const mappedAndSorted = mapGrid(items);

console.log(mappedAndSorted);

// Output:
// {
//     "0_0_6_2": "Item A",
//     "6_0_4_1": "Item B",
//     "0_2_4_1": "Item C",
//     "0_2_4_1": "Item D"
// }

It returns a dictionary that maps grid positions to item names, providing an organized grid layout.

These TypeScript functions can be used to efficiently manage grid-based layouts in various applications.