igniteui-cli 15.1.0 → 15.2.1-alpha.3

package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/paging-remote.md

@@ -0,0 +1,299 @@
+# Paging, Remote Data & Virtualization
+
+> **Part of the [`igniteui-blazor-grids`](../SKILL.md) skill hub.**
+> For grid setup and column configuration — see [`structure.md`](./structure.md).
+
+## Contents
+
+- [Paging with `IgbPaginator`](#paging-with-igbpaginator)
+- [Remote Paging](#remote-paging)
+- [Remote Data Operations](#remote-data-operations)
+- [Virtualization](#virtualization)
+- [Key Rules](#key-rules)
+
+---
+
+## Paging with `IgbPaginator`
+
+The grid does not have built-in paging. Instead, place an `IgbPaginator` component inside the grid:
+
+### Basic paging
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" AutoGenerate="false"
+         Width="100%" Height="500px">
+    <IgbColumn Field="Id" Header="ID" />
+    <IgbColumn Field="Name" Header="Name" />
+    <IgbColumn Field="Department" Header="Department" />
+    <IgbPaginator PerPage="10" />
+</IgbGrid>
+```
+
+### Paginator parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `PerPage` | `int` | `15` | Rows per page |
+| `TotalRecords` | `int` | - | Total record count (required for remote paging) |
+| `SelectOptions` | `int[]` | `[5, 10, 15, 25, 50]` | Page size dropdown options |
+
+### Paginator events
+
+| Event | Type | Description |
+|---|---|---|
+| `PerPageChanged` | `EventCallback<int>` | Fires when page size changes |
+| `PageChanged` | `EventCallback<int>` | Fires when current page changes |
+| `PagingDone` | `EventCallback<IgbPagingEventArgs>` | Fires after paging completes |
+
+### Programmatic paging
+
+```razor
+<IgbGrid @ref="grid" Data="data" PrimaryKey="Id">
+    <IgbPaginator @ref="paginator" PerPage="10" />
+    ...
+</IgbGrid>
+
+<IgbButton @onclick="GoToFirstPage">First Page</IgbButton>
+<IgbButton @onclick="GoToNextPage">Next Page</IgbButton>
+
+@code {
+    private IgbGrid grid = default!;
+    private IgbPaginator paginator = default!;
+
+    private async Task GoToFirstPage()
+    {
+        await paginator.PaginateAsync(0);
+    }
+
+    private async Task GoToNextPage()
+    {
+        await paginator.NextPageAsync();
+    }
+}
+```
+
+### Paginator navigation methods
+
+| Method | Description |
+|---|---|
+| `PaginateAsync(int page)` | Go to a specific page (0-based index) |
+| `NextPageAsync()` | Go to the next page |
+| `PreviousPageAsync()` | Go to the previous page |
+
+---
+
+## Remote Paging
+
+When data lives on a server, fetch only the current page:
+
+```razor
+<IgbGrid @ref="grid" Data="currentPageData" PrimaryKey="Id"
+         AutoGenerate="false" Width="100%" Height="500px">
+    <IgbColumn Field="Id" Header="ID" />
+    <IgbColumn Field="Name" Header="Name" />
+    <IgbColumn Field="Department" Header="Department" />
+    <IgbPaginator PerPage="@pageSize"
+                   TotalRecords="@totalRecords"
+                   PageChanged="OnPageChanged"
+                   PerPageChanged="OnPerPageChanged" />
+</IgbGrid>
+
+@code {
+    private IgbGrid grid = default!;
+    private List<Employee> currentPageData = new();
+    private int totalRecords = 0;
+    private int pageSize = 20;
+    private int currentPage = 0;
+
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadPageAsync();
+    }
+
+    private async Task OnPageChanged(int page)
+    {
+        currentPage = page;
+        await LoadPageAsync();
+    }
+
+    private async Task OnPerPageChanged(int newPageSize)
+    {
+        pageSize = newPageSize;
+        currentPage = 0;
+        await LoadPageAsync();
+    }
+
+    private async Task LoadPageAsync()
+    {
+        var result = await Api.GetEmployeesPagedAsync(currentPage, pageSize);
+        currentPageData = result.Items;
+        totalRecords = result.TotalCount;
+        StateHasChanged();
+    }
+}
+```
+
+### Key points for remote paging
+
+1. **Set `TotalRecords`** on the paginator - this tells it the total number of records on the server.
+2. **Bind `Data` to the current page** - only the current page's data is in memory.
+3. **Handle `PageChanged` and `PerPageChanged`** - fetch new data from the server on each event.
+
+---
+
+## Remote Data Operations
+
+For large datasets, disable client-side sorting/filtering and handle them on the server.
+
+### Remote sorting
+
+```razor
+<IgbGrid @ref="grid" Data="data" PrimaryKey="Id"
+         SortingDone="OnSortingDone">
+    <IgbColumn Field="Name" Sortable="true" />
+    <IgbColumn Field="Department" Sortable="true" />
+    <IgbColumn Field="Salary" Sortable="true" DataType="GridColumnDataType.Number" />
+    <IgbPaginator PerPage="@pageSize" TotalRecords="@totalRecords"
+                   PageChanged="OnPageChanged" />
+</IgbGrid>
+
+@code {
+    private IgbGrid grid = default!;
+    private List<Employee> data = new();
+    private int totalRecords = 0;
+    private int pageSize = 20;
+    private int currentPage = 0;
+    private IgbSortingExpression[]? currentSort;
+
+    private async Task OnSortingDone(IgbSortingEventArgs args)
+    {
+        currentSort = args.SortingExpressions;
+        currentPage = 0;
+        await LoadDataAsync();
+    }
+
+    private async Task OnPageChanged(int page)
+    {
+        currentPage = page;
+        await LoadDataAsync();
+    }
+
+    private async Task LoadDataAsync()
+    {
+        var result = await Api.GetEmployeesAsync(
+            page: currentPage,
+            pageSize: pageSize,
+            sortField: currentSort?.FirstOrDefault()?.FieldName,
+            sortDir: currentSort?.FirstOrDefault()?.Dir.ToString()
+        );
+        data = result.Items;
+        totalRecords = result.TotalCount;
+        StateHasChanged();
+    }
+}
+```
+
+### Remote filtering
+
+```razor
+<IgbGrid @ref="grid" Data="data" PrimaryKey="Id"
+         AllowFiltering="true"
+         FilteringDone="OnFilteringDone">
+    <IgbColumn Field="Name" Filterable="true" DataType="GridColumnDataType.String" />
+    <IgbColumn Field="Department" Filterable="true" DataType="GridColumnDataType.String" />
+</IgbGrid>
+
+@code {
+    private IgbGrid grid = default!;
+    private List<Employee> data = new();
+
+    private async Task OnFilteringDone(IgbFilteringEventArgs args)
+    {
+        // Extract filter information and send to server
+        var filterExpressions = args.FilteringExpressions;
+        var result = await Api.GetEmployeesFilteredAsync(filterExpressions);
+        data = result.Items;
+        StateHasChanged();
+    }
+}
+```
+
+### Combined remote operations pattern
+
+For production apps, combine paging, sorting, and filtering into a single server call:
+
+```razor
+@code {
+    private int currentPage = 0;
+    private int pageSize = 20;
+    private int totalRecords = 0;
+    private IgbSortingExpression[]? currentSort;
+    private string? filterField;
+    private string? filterValue;
+
+    private async Task LoadDataAsync()
+    {
+        var result = await Api.QueryAsync(new QueryRequest
+        {
+            Page = currentPage,
+            PageSize = pageSize,
+            SortField = currentSort?.FirstOrDefault()?.FieldName,
+            SortDirection = currentSort?.FirstOrDefault()?.Dir.ToString(),
+            FilterField = filterField,
+            FilterValue = filterValue
+        });
+
+        data = result.Items;
+        totalRecords = result.TotalCount;
+        StateHasChanged();
+    }
+}
+```
+
+---
+
+## Virtualization
+
+### How virtualization works
+
+Virtualization is **built-in and automatic**. The grid only renders DOM elements for the visible viewport. As the user scrolls, rows and cells are recycled.
+
+### Requirements
+
+1. **The grid must have a fixed `Height`** - set `Height="500px"` or `Height="80vh"`. Without a height, the grid renders all rows and virtualization is disabled.
+2. **Column widths help column virtualization** - when total column width exceeds the grid width, columns outside the viewport are not rendered.
+
+### Row virtualization
+
+```razor
+<IgbGrid Data="largeDataSet" PrimaryKey="Id"
+         Width="100%" Height="600px" AutoGenerate="true" />
+```
+
+Even with 100,000+ rows, only ~20-30 (depending on row height and grid height) are rendered at any time.
+
+### Column virtualization
+
+```razor
+<IgbGrid Data="wideData" PrimaryKey="Id" Width="800px" Height="600px">
+    @for (int i = 0; i < 50; i++)
+    {
+        <IgbColumn Field="@($"Col{i}")" Header="@($"Column {i}")" Width="150px" />
+    }
+</IgbGrid>
+```
+
+With 50 columns at 150px each (7500px total) in an 800px wide grid, only the visible columns are rendered.
+
+---
+
+## Key Rules
+
+1. **`IgbPaginator` goes inside the grid** - it is a child component, not a sibling.
+2. **Remote paging requires `TotalRecords`** - without it, the paginator cannot calculate page count.
+3. **Handle events for remote operations** - `SortingDone`, `FilteringDone`, `PageChanged` are your hooks to fetch server data.
+4. **Virtualization needs a fixed `Height`** - this is the #1 performance requirement.
+5. **Do not use `.Skip().Take()` on `IQueryable` directly on the grid** - the grid expects a materialized collection (`List<T>` or `T[]`). Fetch data asynchronously and set it as the `Data` property.
+6. **`StateHasChanged()` after data updates** - call it after reassigning the `Data` property from an async operation.
+7. **Remote operations override client-side** - when using remote sorting/filtering, the grid still shows sort/filter UI, but you handle the actual data transformation on the server.
+8. **Paging is not available on IgbPivotGrid** - the Pivot Grid does not support pagination.

package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/sizing.md

@@ -0,0 +1,284 @@
+# Sizing - Grid Width, Height, Column Sizing & Cell Spacing
+
+> **Part of the [`igniteui-blazor-grids`](../SKILL.md) skill hub.**
+> For grid setup and column configuration — see [`structure.md`](./structure.md).
+
+## Contents
+
+- [Grid Width](#grid-width)
+- [Grid Height](#grid-height)
+- [Column Sizing](#column-sizing)
+- [Row Height](#row-height)
+- [Cell Spacing (CSS Variables)](#cell-spacing-css-variables)
+- [Key Rules](#key-rules)
+
+---
+
+## Grid Width
+
+### Pixel width
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" Width="800px" Height="500px">
+    ...
+</IgbGrid>
+```
+
+### Percentage width
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="500px">
+    ...
+</IgbGrid>
+```
+
+### Default width
+
+When `Width` is not set, the grid defaults to `100%` of its parent container.
+
+### Key behavior
+
+- If the total column width exceeds the grid width, a horizontal scrollbar appears and column virtualization activates.
+- If the total column width is less than the grid width, columns stretch to fill (unless explicit widths are set).
+
+---
+
+## Grid Height
+
+### Pixel height
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="600px">
+    ...
+</IgbGrid>
+```
+
+### Percentage height
+
+```razor
+<!-- Parent must have a defined height for percentage to work -->
+<div style="height: 80vh;">
+    <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="100%">
+        ...
+    </IgbGrid>
+</div>
+```
+
+### No height (null/unset)
+
+When `Height` is not set, the grid renders **all rows** without a vertical scrollbar. This disables row virtualization.
+
+```razor
+<!-- No Height: renders all rows, no virtualization -->
+<IgbGrid Data="data" PrimaryKey="Id" Width="100%">
+    ...
+</IgbGrid>
+```
+
+> **Warning:** Without a height, large datasets will render all rows to the DOM, causing severe performance degradation. Always set `Height` for datasets with more than 50 rows.
+
+### Auto height
+
+The grid does not have a built-in "auto height" mode. To fit a limited number of rows, calculate the height:
+
+```razor
+@{
+    var rowCount = Math.Min(data.Count, 20);
+    var gridHeight = $"{50 + rowCount * 50}px"; // 50px header + 50px per row
+}
+
+<IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="@gridHeight">
+    ...
+</IgbGrid>
+```
+
+---
+
+## Column Sizing
+
+### Fixed pixel width
+
+```razor
+<IgbColumn Field="Id" Header="ID" Width="80px" />
+<IgbColumn Field="Name" Header="Name" Width="250px" />
+<IgbColumn Field="Department" Header="Department" Width="200px" />
+```
+
+### Percentage width
+
+```razor
+<IgbColumn Field="Id" Header="ID" Width="10%" />
+<IgbColumn Field="Name" Header="Name" Width="40%" />
+<IgbColumn Field="Department" Header="Department" Width="25%" />
+<IgbColumn Field="Salary" Header="Salary" Width="25%" />
+```
+
+### Auto-size (fit content)
+
+No explicit width - the column auto-sizes:
+
+```razor
+<IgbColumn Field="Name" Header="Name" />
+```
+
+Without a `Width`, the grid distributes available space proportionally among columns.
+
+### Min/Max width constraints
+
+```razor
+<IgbColumn Field="Name" Header="Name" Width="200px" MinWidth="100px" MaxWidth="400px" Resizable="true" />
+```
+
+- `MinWidth` prevents the column from shrinking below a threshold (useful with resizing).
+- `MaxWidth` prevents the column from growing beyond a threshold.
+
+### Column resizing
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id">
+    <IgbColumn Field="Name" Header="Name" Width="200px" Resizable="true" />
+    <IgbColumn Field="Department" Header="Department" Width="200px" Resizable="true" />
+    <IgbColumn Field="Salary" Header="Salary" Width="150px" Resizable="true" />
+</IgbGrid>
+```
+
+Users can drag column borders to resize. Combine with `MinWidth` and `MaxWidth` for constrained resizing.
+
+### Auto-size column to fit content
+
+Programmatically auto-size a column to fit its longest cell value:
+
+```razor
+@code {
+    private IgbGrid grid = default!;
+
+    private async Task AutoSizeNameColumn()
+    {
+        var column = grid.GetColumnByName("Name");
+        await grid.AutoSizeColumnWidthAsync(column);
+    }
+
+    private async Task AutoSizeAllColumns()
+    {
+        await grid.AutoSizeColumnsWidthAsync();
+    }
+}
+```
+
+### Column auto-width on init
+
+```razor
+<IgbColumn Field="Name" Header="Name" AutoSize="true" />
+```
+
+When `AutoSize="true"`, the column width adjusts on initial render to fit the header and visible content.
+
+---
+
+## Row Height
+
+### Default row height
+
+The default row height depends on the theme's display density. Use `DisplayDensity` on the grid:
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" DisplayDensity="DisplayDensity.Comfortable">
+    ...
+</IgbGrid>
+```
+
+| Display Density | Approximate Row Height |
+|---|---|
+| `Comfortable` | 50px (default) |
+| `Cosy` | 40px |
+| `Compact` | 32px |
+
+### Custom row height
+
+Use CSS to override row height:
+
+```css
+igc-grid::part(tbody-content) igc-grid-row {
+    height: 60px;
+}
+```
+
+Or use `RowHeight` parameter:
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" RowHeight="60">
+    ...
+</IgbGrid>
+```
+
+---
+
+## Cell Spacing (CSS Variables)
+
+Control cell padding and spacing using CSS custom properties:
+
+```css
+igc-grid {
+    --ig-grid-cell-padding-block: 12px;     /* top and bottom padding */
+    --ig-grid-cell-padding-inline: 16px;    /* left and right padding */
+}
+```
+
+### Available CSS variables for grid spacing
+
+| CSS Variable | Description | Default |
+|---|---|---|
+| `--ig-grid-cell-padding-block` | Vertical cell padding | Theme-dependent |
+| `--ig-grid-cell-padding-inline` | Horizontal cell padding | Theme-dependent |
+| `--ig-size` | Overall component size (affects row height, cell padding) | `var(--ig-size-large)` |
+
+### Sizing via `--ig-size`
+
+The grid respects the global `--ig-size` CSS variable for responsive sizing:
+
+```css
+/* Compact grid */
+igc-grid {
+    --ig-size: var(--ig-size-small);
+}
+
+/* Medium grid */
+igc-grid {
+    --ig-size: var(--ig-size-medium);
+}
+
+/* Large grid (default) */
+igc-grid {
+    --ig-size: var(--ig-size-large);
+}
+```
+
+### Scoped sizing
+
+Apply different sizing to a specific grid:
+
+```razor
+<IgbGrid Data="data" PrimaryKey="Id" class="compact-grid">
+    ...
+</IgbGrid>
+
+<style>
+    .compact-grid {
+        --ig-size: var(--ig-size-small);
+    }
+</style>
+```
+
+---
+
+## Key Rules
+
+1. **Always set `Height` for performance** - without it, virtualization is disabled and all rows render to the DOM.
+2. **Percentage height needs a sized parent** - `Height="100%"` only works if the parent element has an explicit height.
+3. **Box model is border-box** - column widths include padding and borders.
+4. **Horizontal scroll triggers when columns overflow** - if total column width > grid width, a horizontal scrollbar appears.
+5. **`MinWidth` and `MaxWidth` constrain resizing** - always set them when `Resizable="true"` for predictable UX.
+6. **`--ig-size` controls the overall density** - it affects row height, cell padding, header height, and internal spacing.
+7. **Column virtualization requires column widths** - without widths, the grid cannot calculate which columns are outside the viewport.
+8. **Auto-size is a one-time operation** - `AutoSize="true"` on a column fits content at initial render; it doesn't update dynamically as data changes.
+9. **Row height consistency** - all rows in a grid have the same height. Variable row height is not supported.