# Grid

# Description

The Grid component provides a flexible layout container that arranges its child components into a grid structure. It is used primarily for collections where items need to be aligned in rows and columns. You can define custom column and row sizes and adjust layout properties like gaps, alignment, and overflow.

# Usage

Instantiate a Grid using the helper method from Tesserae.UI and specify the column sizes. Items are added using the Add method, and you can customize grid behavior using chaining methods.

using System;
using Tesserae;
using static Tesserae.UI;

public class GridExample
{
    public void CreateGrid()
    {
        // Create a grid with three columns: two flexible and one fixed at 200px
        var grid = Grid(columns: new[] { 1.fr(), 1.fr(), 200.px() })
            .Gap(6.px())                     // Set gap between grid items to 6px
            .JustifyContent(ItemJustify.Start);

        // Add a button spanning 2 grid rows
        grid.Add(Button().SetText("this").WS().Primary().GridColumnStretch().GridRow(1, 2));

        // Add multiple buttons to grid
        for (int i = 1; i <= 12; i++)
        {
            grid.Add(Button().SetText($"Button {i}"));
        }

        // Render grid when needed using grid.Render()
        var element = grid.Render();
    }
}

# Methods

# Columns(params UnitSize[] columns)

Sets the grid's column definitions.
Parameters:
- columns: Array of UnitSize values representing column widths.
Returns: The Grid instance for chaining.

# Rows(UnitSize[] rows)

Sets the grid's row definitions.
Parameters:
- rows: Array of UnitSize values representing row heights.
Returns: The Grid instance for chaining.

# Add(IComponent component)

Adds a child component to the grid.
Parameters:
- component: The component to be added.
No return value.

# AlignItems(ItemAlign align)

Sets the CSS align-items property on the grid.
Parameters:
- align: An ItemAlign enum value.
Returns: The Grid instance for chaining.

# AlignContent(ItemAlign align)

Sets the CSS align-content property on the grid.
Parameters:
- align: An ItemAlign enum value.
Returns: The Grid instance for chaining.

# JustifyContent(ItemJustify justify)

Sets the CSS justify-content property on the grid.
Parameters:
- justify: An ItemJustify enum value.
Returns: The Grid instance for chaining.

# JustifyItems(ItemJustify justify)

Sets the CSS justify-items property on the grid.
Parameters:
- justify: An ItemJustify enum value.
Returns: The Grid instance for chaining.

# Relative()

Makes the grid container positioned relatively.
Returns: The Grid instance for chaining.

# AlignItemsCenter()

Shortcut to set align-items to center.
Returns: The Grid instance for chaining.

# OverflowHidden()

Sets the grid's CSS overflow to hidden.
Returns: The Grid instance for chaining.

# Gap(UnitSize gapSize)

Sets the overall grid gap.
Parameters:
- gapSize: UnitSize defining the gap.
Returns: The Grid instance for chaining.

# RowGap(UnitSize gapSize)

Sets the gap between grid rows.
Parameters:
- gapSize: UnitSize defining the row gap.
Returns: The Grid instance for chaining.

# ColumnGap(UnitSize gapSize)

Sets the gap between grid columns.
Parameters:
- gapSize: UnitSize defining the column gap.
Returns: The Grid instance for chaining.

# AutoRows(UnitSize autoRowValue)

Sets the auto-generated row size.
Parameters:
- autoRowValue: UnitSize value for auto rows.
Returns: The Grid instance for chaining.

# AutoColumn(UnitSize autoColumnValue)

Sets the auto-generated column size.
Parameters:
- autoColumnValue: UnitSize value for auto columns.
Returns: The Grid instance for chaining.

# FlowColumn()

Sets the grid auto-flow to column.
Returns: The Grid instance for chaining.

# Clear()

Removes all child components from the grid.
No parameters and no return value.

# RemovePropagation()

Disables style propagation to parent container items.
Returns: The Grid instance for chaining.

# NoDefaultMargin()

Removes the default margin by adding a specific CSS class.
Returns: The Grid instance for chaining.

# Replace(IComponent newComponent, IComponent oldComponent)

Replaces an existing component in the grid with a new one.
Parameters:
- newComponent: The component to insert.
- oldComponent: The component to be replaced.
No return value.

# Remove(IComponent component)

Removes the specified component from the grid.
Parameters:
- component: The component to remove.
No return value.

# Static Methods

# SetGridColumn(IComponent component, int start, int end)

Sets the grid column start and end positions for a given component.
Parameters:
- component: The component to adjust.
- start: The starting column index.
- end: The ending column index.
No return value.

# SetGridRow(IComponent component, int start, int end)

Sets the grid row start and end positions for a given component.
Parameters:
- component: The component to adjust.
- start: The starting row index.
- end: The ending row index.
No return value.

# Public Properties

Background
- Get or set the background CSS property value.
Margin
- Get or set the margin CSS property value.
Padding
- Get or set the padding CSS property value.
StylingContainer
- Gets the underlying HTMLElement used for styling.
PropagateToStackItemParent
- Indicates if style changes should propagate to the parent in stack items (read-only via chaining methods).

# Samples

# Basic Grid Sample

This sample demonstrates creating a simple grid with three columns, setting a gap between items, and adding multiple buttons.

using System;
using Tesserae;
using static Tesserae.UI;

public class BasicGridSample
{
    public HTMLElement Render()
    {
        // Create a grid with two flexible columns and one 200px fixed column.
        var grid = Grid(columns: new[] { 1.fr(), 1.fr(), 200.px() })
            .Gap(6.px())
            .JustifyContent(ItemJustify.Start);

        // Add a button that spans from column 1 to 2 rows.
        grid.Add(Button().SetText("this").WS().Primary().GridColumnStretch().GridRow(1, 2));

        // Add twelve buttons to the grid.
        for (int i = 1; i <= 12; i++)
        {
            grid.Add(Button().SetText($"Button {i}"));
        }

        // Return the rendered grid element.
        return grid.Render();
    }
}

# Auto Sizing Grid Sample

This sample shows how to create a grid with auto-sizing columns using CSS grid's repeat function.

using System;
using Tesserae;
using static Tesserae.UI;

public class AutoSizingGridSample
{
    public HTMLElement Render()
    {
        // Create a grid with auto-fit columns whose minimum size is 200px (or 100% if smaller)
        var gridAutoSize = Grid(new UnitSize("repeat(auto-fit, minmax(min(200px, 100%), 1fr))"));

        // Add twelve centered buttons to the grid.
        for (int i = 1; i <= 12; i++)
        {
            gridAutoSize.Add(Button().WS().TextCenter().SetText($"Button {i}"));
        }

        // Return the rendered grid element.
        return gridAutoSize.Render();
    }
}

# See Also

Stack – Use in scenarios where vertical or horizontal stacking is required.
Masonry – For alternative grid-based layouts with dynamic columns.
VirtualizedList – For performance optimized long lists.