# NeoUI -- DataGrid Quick Reference

The DataGrid is NeoUI's advanced data grid with sorting, filtering, pagination, inline editing,
server-side data loading, virtual scrolling, and full theming support.

## Installation & Import

```bash
dotnet add package NeoUI.Blazor --version 3.6.3
```

```razor
@using NeoUI.Blazor
```

## Service Registration

```csharp
// Program.cs -- basic (field-based rendering only)
builder.Services.AddNeoUIComponents();

// Full features (with template cell rendering)
builder.Services.AddNeoUIComponents();
builder.Services.AddScoped<IDataGridTemplateRenderer, DataGridTemplateRenderer>();
```

---

## Usage Patterns

### 1. Simple DataGrid

```razor
<DataGrid TItem="Product" Data="@products">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Sortable="true" />
 <DataGridColumn Field="@nameof(Product.Price)" Header="Price" Sortable="true" />
 <DataGridColumn Field="@nameof(Product.Stock)" Header="Stock" Filterable="true" />
</DataGrid>

@code {
 private List<Product> products = new();
 protected override async Task OnInitializedAsync() => products = await LoadProducts();
}
```

### 2. DataGrid with Custom Cell Templates

Requires `IDataGridTemplateRenderer` in DI.

```razor
<DataGrid TItem="Customer" Data="@customers">
 <DataGridColumn Field="@nameof(Customer.Name)" Header="Name">
  <CellTemplate Context="customer">
<div class="flex items-center gap-2">
 <Avatar><AvatarFallback>@customer.Name[0]</AvatarFallback></Avatar>
 <span class="font-medium">@customer.Name</span>
</div>
  </CellTemplate>
 </DataGridColumn>

 <DataGridColumn Field="@nameof(Customer.Status)" Header="Status">
  <CellTemplate Context="customer">
<Badge Variant="@(customer.IsActive ? BadgeVariant.Success : BadgeVariant.Secondary)">
 @customer.Status
</Badge>
  </CellTemplate>
 </DataGridColumn>
</DataGrid>
```

### 3. Server-Side DataGrid

```razor
<DataGrid TItem="Order"
 PagingMode="DataGridPagingMode.Server"
 PageSize="25"
 OnDataRequest="@LoadDataAsync">
 <DataGridColumn Field="@nameof(Order.Id)" Header="Order #" />
 <DataGridColumn Field="@nameof(Order.Customer)" Header="Customer" Sortable="true" />
 <DataGridColumn Field="@nameof(Order.Total)" Header="Total" Sortable="true" />
</DataGrid>

@code {
 private async Task<DataGridDataResponse<Order>> LoadDataAsync(DataGridDataRequest<Order> request)
 {
  var query = _context.Orders.AsQueryable();

  foreach (var sort in request.SortDescriptors)
  {
query = sort.Direction == DataGridSortDirection.Ascending
 ? query.OrderBy(o => EF.Property<object>(o, sort.Field))
 : query.OrderByDescending(o => EF.Property<object>(o, sort.Field));
  }

  var totalCount = await query.CountAsync();
  var items = await query.Skip(request.StartIndex).Take(request.Count).ToListAsync();

  return new DataGridDataResponse<Order> { Items = items, TotalCount = totalCount };
 }
}
```

### 4. Selection

```razor
<DataGrid TItem="Customer"
 Data="@customers"
 SelectionMode="DataGridSelectionMode.Multiple"
 OnSelectionChanged="@HandleSelectionChanged">
 <DataGridColumn Field="@nameof(Customer.Name)" Header="Name" />
 <DataGridColumn Field="@nameof(Customer.Email)" Header="Email" />
</DataGrid>

@code {
 private List<Customer> selectedCustomers = new();
 private void HandleSelectionChanged(IReadOnlyCollection<Customer> selection)
  => selectedCustomers = selection.ToList();
}
```
Selection modes: `None` | `Single` | `Multiple`

### 5. Inline Editing (Transactions)

```razor
<DataGrid TItem="Product"
 Data="@products"
 Editable="true"
 OnRowCommit="@SaveRow"
 OnRowCancel="@CancelRow">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Editable="true" />
 <DataGridColumn Field="@nameof(Product.Price)" Header="Price" Editable="true" />
</DataGrid>
```

### 6. State Persistence

```razor
<DataGrid TItem="Product"
 Data="@products"
 @bind-State="@gridState"
 OnStateChanged="@SaveState">
 <DataGridColumn Field="@nameof(Product.Name)" Header="Name" Sortable="true" />
</DataGrid>

@code {
 private DataGridState gridState = new();

 protected override async Task OnInitializedAsync()
  => gridState = await LocalStorage.GetItemAsync<DataGridState>("grid-state") ?? new();

 private async Task SaveState(DataGridState state)
  => await LocalStorage.SetItemAsync("grid-state", state);
}
```

### 7. Advanced: Frozen Columns, Row Grouping, Virtual Scrolling

```razor
<DataGrid TItem="Employee"
 Data="@employees"
 VirtualScrolling="true"
 RowGrouping="true"
 GroupField="@nameof(Employee.Department)">
 <DataGridColumn Field="@nameof(Employee.Name)" Header="Name" Frozen="true" />
 <DataGridColumn Field="@nameof(Employee.Department)" Header="Department" />
 <DataGridColumn Field="@nameof(Employee.Salary)" Header="Salary" />
</DataGrid>
```

---

## DataGridColumn Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `Field` | `string` | Property name to bind |
| `Header` | `string` | Column header text |
| `Sortable` | `bool` | Enable column sorting |
| `Filterable` | `bool` | Enable column filtering |
| `Editable` | `bool` | Enable inline editing |
| `Width` | `int?` | Column width in pixels |
| `MinWidth` | `int?` | Minimum width in pixels |
| `Frozen` | `bool` | Freeze column (left) |
| `FrozenRight` | `bool` | Freeze column (right) |
| `CellTemplate` | `RenderFragment<TItem>` | Custom cell renderer |
| `HeaderTemplate` | `RenderFragment` | Custom header renderer |
| `Class` | `string?` | CSS classes for cells |

---

## DataGrid Parameters (Key)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Data` | `IEnumerable<TItem>?` | | Client-side data |
| `PagingMode` | `DataGridPagingMode` | `Client` | Client or Server paging |
| `PageSize` | `int` | `20` | Rows per page |
| `SelectionMode` | `DataGridSelectionMode` | `None` | Row selection mode |
| `Sortable` | `bool` | `true` | Global sort toggle |
| `Filterable` | `bool` | `false` | Global filter toggle |
| `Editable` | `bool` | `false` | Inline editing |
| `VirtualScrolling` | `bool` | `false` | Virtual rows |
| `Density` | `DataGridDensity` | `Compact` | Row density (`Compact`, `Medium`, `Spacious`). `Comfortable` is an `[Obsolete]` alias for `Medium`. |
| `Theme` | `DataGridTheme` | `Shadcn` | Visual theme |
| `VisualStyle` | `DataGridStyle` | `Default` | Striped/Bordered/etc. |
| `OnDataRequest` | `Func<DataGridDataRequest<TItem>, Task<DataGridDataResponse<TItem>>>` | | Server-side handler |
| `OnSelectionChanged` | `EventCallback<IReadOnlyCollection<TItem>>` | | Selection callback |
| `@bind-State` | `DataGridState` | | State binding |
| `OnStateChanged` | `EventCallback<DataGridState>` | | State changed callback |

---

## Theming

### High-Level Presets

```razor
<DataGrid TItem="Order" Data="@orders"
 Theme="DataGridTheme.Shadcn"
 Density="DataGridDensity.Compact"
 VisualStyle="DataGridStyle.Striped">
 ...
</DataGrid>
```

Themes: `Shadcn` | `Alpine` | `Balham` | `Material` | `Quartz`
Density: `Compact` | `Medium` | `Spacious` (`Comfortable` is `[Obsolete]` alias for `Medium`)
VisualStyle: `Default` | `Striped` | `Bordered` | `Minimal`

### Fine-Grained Parameters

```razor
<DataGrid TItem="Order" Data="@orders">
 <DataGridThemeParameters
  AccentColor="var(--primary)"
  RowHeight="44"
  FontSize="14"
  BorderRadius="6"
  HeaderBackgroundColor="var(--muted)" />
 <DataGridColumn ... />
</DataGrid>
```

Key theme parameters: `AccentColor`, `BackgroundColor`, `ForegroundColor`, `BorderColor`,
`HeaderBackgroundColor`, `RowHoverColor`, `OddRowBackgroundColor`, `SelectedRowBackgroundColor`,
`RowHeight`, `HeaderHeight`, `FontSize`, `FontFamily`, `HeaderFontWeight`, `Spacing`, `BorderRadius`

### CSS Override

```razor
<DataGrid TItem="Order" Data="@orders" Class="my-grid">...</DataGrid>

<style>
.my-grid { --ag-cell-horizontal-padding: 20px; }
</style>
```

---

## Sub-Pages (Demo Site)

| Path | Description |
|------|-------------|
| `/components/datagrid` | Overview |
| `/components/datagrid/basic` | Basic usage |
| `/components/datagrid/templating` | Custom cell templates |
| `/components/datagrid/selection` | Row selection |
| `/components/datagrid/transactions` | Inline editing |
| `/components/datagrid/sorting` | Sorting & filtering |
| `/components/datagrid/state` | State persistence |
| `/components/datagrid/server-side` | Server-side loading |
| `/components/datagrid/advanced` | Frozen columns, grouping, virtual scroll |
| `/components/datagrid/theming` | Custom themes |