Crate datagrid_core

Expand description

Framework-agnostic data grid logic.

This crate contains the pure, deterministic half of the data grid: sorting, filtering, paging, selection, virtualization math and keyboard navigation. It has no UI framework dependency and can be unit-tested and benchmarked on its own.

The Dioxus bindings live in the companion crate dioxus-datagrid.

§The shape of it

Rows stay where they are. compute_view takes a row slice, the column specs and the current GridState, and returns a View of indices into the original slice. Nothing is cloned, so a view over a hundred thousand expensive rows costs a vector of usize.

use datagrid_core::{compute_view, ColumnSpec, GridState, GridRow};

#[derive(Clone)]
struct User {
    id: u32,
    name: String,
    age: u32,
}

impl GridRow for User {
    type Key = u32;
    fn key(&self) -> u32 {
        self.id
    }
}

let rows = vec![
    User { id: 1, name: "Zoe".into(), age: 30 },
    User { id: 2, name: "adam".into(), age: 25 },
    User { id: 3, name: "Mia".into(), age: 30 },
];

let columns = vec![
    ColumnSpec::new("name")
        .sort_by_text(|user: &User| user.name.as_str())
        .filter_by(|user: &User| user.name.clone()),
    ColumnSpec::new("age").sort_by_value(|user: &User| user.age),
];

let mut state = GridState::new();
state.toggle_sort("name", false);

let view = compute_view(&rows, &columns, &state);

// Sorting is case-insensitive by default, so "adam" comes first.
let names: Vec<&str> = view
    .indices
    .iter()
    .filter_map(|&i| rows.get(i))
    .map(|user| user.name.as_str())
    .collect();
assert_eq!(names, ["adam", "Mia", "Zoe"]);

Structs§

AggregateValue: One aggregate’s result.
CellFocus: Which cell currently holds focus, in view coordinates.
CellRange: A rectangle of cells, held as the two corners the user made it from.
Changes: Edits collected but not saved yet: the rows changed, added and deleted, as a batch edit keeps them until the user saves or discards.
ColumnFilter: The conditions on one column: all of them (AND) or any of them (OR).
ColumnId: A stable, human-readable column identifier.
ColumnSpec: Everything the core logic needs to know about one column.
Condition: One condition: an operator and its operands.
DistinctValues: The values of one column, each with how many rows hold it: what a value list in a filter menu offers to tick.
ExportAggregate: One aggregate in an export: a column’s sum, count or the like.
ExportCell: One cell: the value, and the text the grid shows for it.
ExportColumn: One column of an export.
ExportTable: A table ready to be written: the columns, and the rows under them.
GridLocale: The texts and formats of one language.
GridQuery: Everything a server needs to produce one page of rows.
GridState: Everything the user can change about how rows are presented.
Group: A group of rows sharing a value in a grouped column.
GroupKey: Where a group sits: the value of each grouped column, from the outermost group down to this one. Identifies a group across recomputations, which is what remembering whether it is expanded needs.
GroupSpan: One cell of a group header row: a label over a run of columns.
GroupSummary: One group as a server counts it: its key, how many rows it holds, and its aggregates. A server gets these from one GROUP BY per grouped column; see GroupedPage::plan.
GroupedPage: Which group rows fall on a page of a grouped query, and which data rows a server still has to fetch for it.
Page: One page of rows from a server, and how many rows match in total.
PageState: Which page of the filtered rows is shown.
RequestId: Identifies one request issued through a RequestTracker.
RequestTracker: Decides whether a response is still wanted.
RowSpans: Which cell covers each column of one row.
Selection: The set of selected row keys, plus the anchor a shift-range extends from.
SortState: One entry of the sort. Within GridState::sort the position in the vector is the priority — earlier entries win.
View: The result of compute_view.

Enums§

Aggregate: An aggregate of one column: what a footer shows below it.
AggregateKind: What an aggregate computes, without the closure a custom one carries: what a result is labelled with, and what a server is asked for.
CellAlign: Horizontal alignment of a cell’s content.
CellFormat: How a column’s value is turned into text.
CellOverflow: What happens to cell content wider than its column.
CellSelectionMode: How the user may select cells, independent of row selection.
CellValue: A typed value read from one cell of a row.
ColumnWidth: How wide a column should be laid out.
Direction: Which way a grid reads: the direction its first column is at, and its arrow keys point to.
EditError: Why an edit was refused.
ExportRow: One row of an export.
ExportScope: Which rows an export takes.
FilterOp: How a condition compares a cell with its operand.
NavKey: A navigation key press, already resolved from the raw keyboard event.
PagePart: One part of a grouped page, in display order.
Pinned: Where a column is held in place while the grid scrolls sideways.
SelectionExtent: How much of a set of rows is selected: what a “select all” checkbox shows, and what a click on it should do.
SelectionMode: How many rows the user may select.
SortDirection: The direction a column is sorted in.
TextCollation: How text is compared when sorting.
Value: An owned value: what a filter compares against and what an edit writes. The owned counterpart of CellValue, so that it can live in GridState and travel to a server.
ValueKind: What kind of value a column holds, which decides the operators a filter menu offers and how typed text is read.
ViewRow: One row of a View, in display order.

Constants§

DEFAULT_AUTO_COLUMN_WIDTH: The width of an automatically sized column that sets no min_width, in CSS pixels, where the grid has to know a width without laying the column out: 6rem at the browser’s default font size.
DEFAULT_MIN_COLUMN_WIDTH: The narrowest a column can be resized to when it sets no min_width, in CSS pixels. Wide enough for a short label and the resize handle.
DEFAULT_REMOTE_PAGE_SIZE: Rows per page when a remote grid is not given a page size. A server must page, so “no paging” is not an option there.

Traits§

DataSource: Where a remote grid gets its rows from.
FromValue: Turns an edited value into the type of a row’s field, for ColumnSpec::editable.
GridRow: A row the grid can identify across sorting, filtering and paging.

Functions§

changed_columns: The columns whose value differs between two versions of a row.
column_offset: How far from the start edge column index begins: the widths before it.
compute_view: Filters, sorts and pages rows, in that order.
compute_view_with_details: Filters, sorts and pages rows as compute_view does, and puts a Detail row under every row in expanded.
distinct_values: The distinct values of column among the rows that pass every other filter and the search.
export_table: Builds the table an export writes.
find_aggregate: The aggregate of kind over column among aggregates.
from_tsv: Reads tab-separated text back into rows of cells, the way a spreadsheet writes it to the clipboard.
group_header_rows: The group header rows above the columns, outermost first.
group_levels: How deep the group header is: the longest group path among the columns.
layout_order: The columns of a grid in the order it lays them out, as indices into specs: the visible ones, in the state’s column order, with the pinned ones gathered at their edges.
move_row: Moves the row at from so that it ends up at to, and says whether anything moved.
navigate: Moves the focus according to the ARIA grid pattern.
offset_of: The offset of the first rendered row, in CSS pixels.
reveal_scroll_left: The horizontal scroll position that brings a column fully into view, or None when it already is.
reveal_scroll_top: The scroll position that brings row index fully into view, or None when it already is.
rows_per_viewport: How many whole rows fit in the viewport; what PageUp and PageDown move by.
to_tsv: Joins rows of cells into tab-separated text.
total_height: The total scrollable height of total_rows rows, in CSS pixels.
tsv_field: Quotes a field if it would otherwise be misread.
visible_columns: Which columns a column-virtualized body should render.
visible_range: Which rows a virtualized body should render.

Type Aliases§

AggregateFn: Computes a custom aggregate from the rows it covers.
FilterTextFn: Extracts the text a column filters and searches on.
FilterValueDeprecated: The name Value had while only filters used it.
SetFn: Writes an edited value into a row. None is an empty cell.
SortKeyFn: The name ValueFn had while it was only used for sorting.
SortValue: The value a column sorts by.
SpanFn: How many columns a column’s cell covers in one row; see ColumnSpec::span.
ValidateFn: Checks a row after an edit, returning a message for the user if it is not acceptable.
ValueFn: Reads a column’s typed value from a row, borrowing from it where it can.