Rows in memory
Sort, filter, search and page the rows you hold in the browser with one hook, or send the same state to your server.
The grid shows the rows it is given, in that order. The sort, the column filters, the search text
and the page are the grid's state, each kept by a feature:
sorting(), filtering(), search() and pagination(). When every row is in memory, one hook
does the rest: it applies the state of the features you install to your rows and hands the grid
the rows to show. A grid fed by a server never loads it: it sends the same state.
One hook
useLocalRows(rows, columns, options) comes from its own entry point,
@fragiola/data-grid-react/local. Give it the root's features (features): each of
sorting(), filtering(), search() and pagination() installed runs its stage, one left out
is skipped (its controls change nothing). Spread its props onto DataGrid.Root: the current
page's rows, and the state of those features, so a click on a sortable header sorts them. The
root's model holds that state, controlled by the hook: model.get("column-filters") reads it, and
a command run on the model (model.run("page.set", { pageIndex: 2 })) comes back to the hook.
Give its filter and page to your own controls.
import { filtering } from "@fragiola/data-grid-react/filtering";
import { useLocalRows } from "@fragiola/data-grid-react/local";
import { pagination } from "@fragiola/data-grid-react/pagination";
import { search } from "@fragiola/data-grid-react/search";
import { sorting } from "@fragiola/data-grid-react/sorting";
const features = [sorting(), filtering(), search(), pagination()];
const local = useLocalRows(people, columns, {
features,
pageSize: 50,
defaultSortColumns: [{ columnKey: "name", direction: "ascending" }],
});
<input
value={local.filter.search}
onChange={(event) => local.filter.setSearch(event.target.value)}
/>
<DataGrid.Root features={features} columns={columns} {...local.props}>
{/* … */}
</DataGrid.Root>
<button type="button" disabled={!local.page.canNext} onClick={local.page.next}>
{local.page.index + 1} / {local.page.count}
</button>It returns:
| field | holds |
|---|---|
props | rows, and the state of each feature given, for DataGrid.Root: sortColumns (sorting()), columnFilters (filtering()), searchText (search()), pageIndex, pageSize and totalRowCount (pagination()), each with its handler |
rows | the current page's rows |
total, filteredCount | every row given, and those passing the filters and the search |
sort | columns, set, clear |
filter | values, set(columnKey, value), clear, search, setSearch |
page | index, size, count, canPrevious, canNext, set, previous, next, first, last, setSize |
The options are where it starts: pageSize (none: a single page of every row),
defaultSortColumns, defaultFilters, defaultSearch, defaultPageIndex. A filter, the
search or the sort changing goes back to the first page. features is read once, as the root
reads its own. The hook controls the state it hands the root: with pagination() installed,
the page size is its pageSize option (page.setSize), never the root's defaultPageSize.
Keep rows and columns the same arrays between renders (outside the component, or memoised),
as DataGrid.Root wants its columns: the hook works again when they change.
In stages
The rows are filtered, then searched, then sorted, then grouped (with groupBy,
Row grouping) or shown as a tree (with getSubRows,
Tree data), then paged. Grouped, props carry the expanded groups
too (expandedGroupKeys, onExpandedGroupKeysChange) when features has rowGrouping(). A stage
whose feature is not in features is skipped. Each stage is worked out again only
when its own inputs change: turning a page sorts nothing again, a new sort filters nothing
again, and expanding a group groups nothing again.
Sorting
Without anything more, a column's values compare by type: numbers by value, dates by time,
false before true, text in the reader's order ("item 2" before "item 10", case and
accents aside). Empty values (undefined, null, NaN, "", an invalid date) go last, in
either direction. Ties go to the next sorted column, then keep their order.
When a column's values are not its order, give it compare:
{
key: "employees",
name: "Employees",
width: 150,
sortable: true,
// ranges sort by their scale, not as text
compare: (a, b) => SCALE.indexOf(a.employees) - SCALE.indexOf(b.employees),
}Filtering and search
filter.set(columnKey, value) filters a column by a value. What it matches depends on the value:
| filter value | a row passes when its cell |
|---|---|
| a text | contains it, case and accents aside |
| a list | is one of its values (or holds one, for a cell holding a list): facets |
| a number, a boolean, a date | equals it |
empty (undefined, null, "", []) | always: no filter |
Filters on several columns all apply. When a column needs another rule, a range for example,
give it filter: it receives the cell's value, the filter value and the row.
{
key: "salary",
name: "Salary",
width: 130,
// a minimum, not an equal value
filter: (value, minimum) =>
typeof value === "number" && typeof minimum === "number" && value >= minimum,
}filter.setSearch(text) keeps the rows where any column's value, as text, contains it.
Moving rows
The hook never changes the rows you give it. When people move rows,
moveRow(move) returns your rows with a move the grid told (onRowMove, with rowReorder()) applied: the moved row
goes beside the row it lands next to on screen, a filtered or paged grid's included. Set it as your
rows. It is stable (a function that never changes, reading your latest rows), and two moves told
before a render apply one after the other. The grid moves no row while it is sorted, nor while
the rows are grouped.
const [tasks, setTasks] = useState(initialTasks);
const local = useLocalRows(tasks, columns, { features });
<DataGrid.Root
features={features}
{...local.props}
columns={columns}
onRowMove={(move) => setTasks(local.moveRow(move))}
/>Without React
The same pipeline is framework-free in @fragiola/data-grid/local: createLocalRows(options)
keeps the state (stages, from localStagesOf(features), says which stages run: every one
without it) and derive(rows, columns, grouping?) returns the page and the counts (grouped,
its groups: the rows shown, their kinds and their keys), and sortRows,
filterRows, searchRows and pageRows work on any array, as moveRow(rows, fromIndex, toIndex) and moveShownRow(rows, rowIndexes, fromIndex, toIndex) do for a move (the rows
shown by their places among your rows, a view's rowIndexes, so equal rows are told apart).
On a server
With more rows than the browser should hold, install the same features and send their state: the
sort (sortColumns, the header toggles it), the column filters (columnFilters), the search text
(searchText) and the page (pageIndex, pageSize), controlled by your app or read from the
model (model.get("page-info")). Give the root the server's count (totalRowCount), so
get("page-count") counts its pages. No /local: the grid shows the page that comes back.
const features = [sorting(), filtering(), search(), pagination()];
<DataGrid.Root
features={features}
columns={columns}
rows={page.rows}
sortColumns={sortColumns}
onSortColumnsChange={setSortColumns}
columnFilters={columnFilters}
onColumnFiltersChange={setColumnFilters}
pageIndex={pageIndex}
onPageIndexChange={setPageIndex}
pageSize={50}
totalRowCount={page.total}
/>The model never moves one piece for another: going back to the first page when a filter changes
is your app's (/local does it in memory).