# XWUIDataGrid

Advanced data grid with custom cell renderers, sortable / filterable columns, pagination, row selection.

## Row virtualization

`conf_comp.virtualize` (`true | false | 'auto'`, default `'auto'`) decides
whether rows render through a pooled virtual viewport or as a plain `<table>`.

- `'auto'` virtualizes once the row count passes `virtualizeThreshold`
  (default 200). Below it the grid renders exactly the `<table>` it always did.
- The virtual path renders only the visible window plus `overscanRows`
  (default 6) at each edge, into pooled row nodes that are re-bound on scroll -
  100k rows cost the same DOM as 100.
- `rowHeight` (default 36) drives the row axis; `viewportHeight` (default 420)
  is the scroll-viewport height used when the element has not been laid out.

The virtual path is a `role="table"` flex structure rather than a `<table>`
(the scroll surface is absolutely positioned, and `<tr>` cannot live inside a
`<div>`). Class names are unchanged, so component CSS and consumer selectors
carry over.

```ts
new XWUIDataGrid(host, { columns, data: hundredThousandRows }, {
  virtualize: 'auto',   // default
  rowHeight: 36,
  overscanRows: 6,
});
```

## Server row model

`conf_comp.rowModel: 'client' | 'server'` (default `'client'`). In server mode
the grid fetches only the windows it paints, through `data.dataSource` (a
`RowDataSource` from `_shared/data-source/`), in blocks of `serverBlockSize`
(default 100). Rows whose block has not landed render as skeleton placeholders
and are replaced in place when it does. Overlapping windows share one fetch per
block. Sorting is pushed down as a `RowRequest.sort` on the column's
`dataIndex`.

```ts
new XWUIDataGrid(host, {
  columns,
  data: [],
  dataSource: myRowDataSource,
  totalRows: 1_000_000,   // optional hint; otherwise learned from the first block
}, { rowModel: 'server' });
```

`data.totalRows` is optional: without it the grid paints nothing until the
first block reports the real total, then fills in.

## Basic Usage

Three-column grid with a handful of rows.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: Three-column grid with a handful of rows.
```

## Sortable And Paginated

20 rows, 5 per page, click-to-sort headers.

```example
file: examples/SortableAndPaginated.ts
html: examples/SortableAndPaginated.html
title: Sortable And Paginated
description: 20 rows, 5 per page, click-to-sort headers.
```

## Custom Renderers

Per-column `render(row)` embeds badges / links.

```example
file: examples/CustomRenderers.ts
html: examples/CustomRenderers.html
title: Custom Renderers
description: Per-column `render(row)` embeds badges / links.
```

## Selectable

Checkboxes + select-all + selection events.

```example
file: examples/Selectable.ts
html: examples/Selectable.html
title: Selectable
description: Checkboxes + select-all + selection events.
```

## Editable Cells

Actions column with +/- buttons that mutate the rows and re-render.

```example
file: examples/EditableCells.ts
html: examples/EditableCells.html
title: Editable Cells
description: Actions column with +/- buttons that mutate the rows and re-render.
```

## Row Grouping

Rows grouped by department into captioned sections with subtotals.

```example
file: examples/RowGrouping.ts
html: examples/RowGrouping.html
title: Row Grouping
description: Rows grouped by department into captioned sections with subtotals.
```

## Filterable

Search box + status dropdown that filter the rows live.

```example
file: examples/Filterable.ts
html: examples/Filterable.html
title: Filterable
description: Search box + status dropdown that filter the rows live.
```

## Admin Dashboard

Data-dense orders grid combining sort + selection + pagination.

```example
file: examples/Dashboard.ts
html: examples/Dashboard.html
title: Admin Dashboard
description: Data-dense orders grid combining sort + selection + pagination.
```

```api
```