oxiui-table — Virtualized table / data-grid widget for OxiUI

oxiui-table is the table / data-grid widget of the COOLJAPAN OxiUI toolkit. It provides a Table<S> driven by a RowSource trait with viewport-based virtualization: only the rows visible in the current scroll window (plus a small overscan) are materialized per frame, keeping memory and CPU usage constant regardless of total row count. On top of that core it layers sorting, per-column filtering, pagination, multi-row selection, keyboard navigation, sticky/movable/pinned/resizable columns, zebra striping, tree/grouped rows, footer aggregates, cell formatting and alignment, clipboard (TSV) export, CSV export, async/prefetched data loading, and a typed cell model.

The data/logic layer is #![forbid(unsafe_code)] and 100% Pure Rust with no mandatory rendering dependency — it is fully unit-testable headlessly. Optional rendering backends for egui and iced, plus optional cross-crate bridges for rich text (text-table), theming (theme-table), accessibility (a11y-table), and state persistence (persist-table), are all gated behind feature flags.

Installation

[dependencies]
# Headless core only (default):
oxiui-table = "0.2.1"

# With the egui rendering backend:
oxiui-table = { version = "0.2.1", features = ["egui-table"] }

# With the iced rendering backend:
oxiui-table = { version = "0.2.1", features = ["iced-table"] }

Quick Start

Implement RowSource for your data, build a Table, and materialize only the visible rows:

use oxiui_table::{Table, RowSource, Cell, ColumnDef};

struct MyData;

impl RowSource for MyData {
    fn row_count(&self) -> usize { 1000 }
    fn row(&self, i: usize) -> Vec<Cell> {
        vec![Cell::Int(i as i64), Cell::Text(format!("row-{i}"))]
    }
    fn column_defs(&self) -> &[ColumnDef] { &[] }
}

// 240 px viewport at the default 24 px row height -> ~10 visible rows.
let table = Table::new(MyData).with_row_height(24.0);
let visible = table.materialize_visible(240.0, 0.0);
assert!(visible.len() <= 20);

Sorting and filtering

# use oxiui_table::{Table, RowSource, Cell, ColumnDef};
# struct MyData;
# impl RowSource for MyData {
#     fn row_count(&self) -> usize { 3 }
#     fn row(&self, i: usize) -> Vec<Cell> { vec![Cell::Int(i as i64)] }
#     fn column_defs(&self) -> &[ColumnDef] { &[] }
# }
let mut table = Table::new(MyData);
table.toggle_sort(0);                       // cycle the sort on column 0
table.set_column_filter(0, "1".to_string()); // substring filter on column 0
let view: Vec<usize> = table.filtered_sorted_indices();
let _ = view;

API Overview

Core widget (crate root)

Cell enum — typed cell model

Text, Int, Float, Bool, Empty, Date(i64 unix-ms → ISO-8601), Currency { amount_cents, code }, Link { label, url }, Image { uri }, Custom(Box<dyn CellRenderer>). Implements Display, a custom Clone (custom cells fall back to Empty), is_empty, and a panic-free total-order compare (cross-type comparisons use a stable type rank). From impls for &str, String, i64, i32, f64, bool.

ColumnDef and builder

ColumnDef — name, width, min_width, max_width, resizable, optional formatter, optional align. Construct with ColumnDef::new(name) or the fluent ColumnDefBuilder (width, min_width, max_width, resizable, formatter, align, build).

TableBuilder

Fluent builder for a Table from a RowSource: new(source), page_size, zebra_striping, build.

Aggregate helpers

aggregate_sum(cells), aggregate_count(cells), aggregate_avg(cells) — sum / non-empty count / average over numeric cells.

TableEvent enum

Interaction events for the caller: RowSelected(usize), CellEdited { row, col, new_value }, SortChanged { col, ascending }, ColumnResized { col, new_width }, FilterChanged { col, new_filter }.

sort module

SortState + SortDirection (Ascending, Descending, None; next() cycles). sort_indices(source, …) returns sorted row indices.

filter module

ColumnFilter — substring filter on a column: new(column, pattern), is_inactive, matches, apply. Free functions filter_indices(source, predicate) and apply_all(source, filters).

selection module

SelectionModel + SelectionMode (None, Single, Multi). click, ctrl_click, shift_click (range from anchor), select_all, is_selected, selected_sorted, clear.

nav module

TableNav — keyboard cursor: move_up/down/left/right, move_home_row, move_end_row, page_up, page_down, set_position.

pagination module

PaginationState — new(total_rows, page_size), total_pages, go_to, next/prev/first/last, row_range, apply(sorted_indices).

header module

height & height_cache modules

format & align modules

CellFormatter (trait) with DefaultFormatter, NumberFormatter, DateFormatter. CellAlign (Left, Center, Right; default_for(cell) — numbers default right).

clipboard module

ClipboardSink (trait) with NullClipboard and CaptureClipboard (records writes for tests). selection_to_tsv(cells) serializes a cell grid to tab-separated values.

csv module

to_csv(source, delimiter) — export the whole RowSource to a CSV/DSV string.

Backend integration (feature-gated)

async_source module — async data loading

Always available (no feature required). Re-exported at the crate root.

text_integration module (text-table feature)

RichCell/StyledSpan/CellRichExt are always compiled (so non-text callers are unaffected), but shaping needs the feature.

theme_integration module (theme-table feature)

accessibility module (a11y-table feature)

A dependency-free LightNode tree is always available; the full AccessKit-compatible tree needs the feature.

persistence module (persist-table feature)

Feature Flags

The default build has no rendering dependency and no optional integration dependency — the entire sort/filter/selection/virtualization core, plus the dependency-free parts of text_integration/theme_integration/accessibility/persistence, are headless and feature-free.

Error variants — TableError

Returned by RowSource::set_cell. Implements Display and std::error::Error.

Related crates

• oxiui-core — the only mandatory dependency
• oxiui — the OxiUI facade
• oxiui-accessibility — full a11y tree for table rows/cells/headers, behind a11y-table
• oxiui-text — rich-text span shaping/measurement for RichCell, behind text-table
• oxiui-theme — design tokens for TableTheme::from_palette/from_tokens, behind theme-table
• oxicode — COOLJAPAN binary codec used by TableState::encode_to_vec/decode_from_slice, behind persist-table
• oxiui-egui / oxiui-iced — the adapters matching the egui-table / iced-table backends

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)