Data Tables — vyuh_table

vyuh_table is the CDX data-table package. It composes CDX UI tokens and controls, but it is imported directly rather than re-exported by vyuh_cdx_ui.

import 'package:vyuh_table/vyuh_table.dart';

Live Example

Open the full route: Data Table.

TableWidget

TableWidget<T> renders generic tabular data with column resizing, column reordering, pinned leading columns, row selection, expansion rows, loading / error / empty states, and optional pagination.

TableWidget<Area>(
  columns: [
    TableColumn.text(
      field: 'name',
      label: 'Name',
      getValue: (area) => area.name,
      widthFactor: 0.30,
      minWidth: 220,
    ),
    TableColumn.badge(
      field: 'status',
      label: 'Status',
      getValue: (area) => area.statusLabel,
      getColor: (area) => area.statusColor,
      widthFactor: 160,
    ),
    TableColumn.number(
      field: 'capacity',
      label: 'Capacity',
      getValue: (area) => area.capacity,
      suffix: ' units',
      widthFactor: 140,
    ),
  ],
  items: pageItems,
  totalCount: totalCount,
  currentPage: page,
  pageSize: pageSize,
  enablePagination: true,
  onPageChanged: (nextPage) => setState(() => page = nextPage),
  onPageSizeChanged: (nextSize) => setState(() => pageSize = nextSize),
  selectedItem: selectedArea,
  onRowTap: (area) => context.go('/areas/${area.id}'),
)

Column Model

TableColumn<T> is intentionally generic and has no entity-system dependency. Width is expressed through widthFactor:

• 0 < widthFactor < 1 means a fraction of the available table width.
• widthFactor >= 1 means a fixed logical-pixel width.
• null means no declared width; the column relies on minWidth.

Factories:

Factory	Use
TableColumn.text	Simple text cells with maxLines and ellipsis
TableColumn.badge	Inline colored badge cells with optional icon
TableColumn.number	Numeric cells with optional prefix / suffix
TableColumn.custom	Full custom cell builder plus optional custom header

Header extension points include headerBuilder, onHeaderTap, headerActionsBuilder, and menuItemsBuilder.

Column Menus

ColumnMenuItem is a sealed model rendered by the table header chrome:

Type	Use
ColumnMenuAction	Tappable row with optional icon
ColumnMenuSubmenu	Nested menu section
ColumnMenuCheckbox	Toggleable menu item
ColumnMenuDivider	Visual divider

Behavior And State

Key TableWidget behavior flags:

Param	Default	Purpose
enableColumnResize	true	Drag column edges to resize
enableColumnReorder	true	Drag headers to reorder
showCellBorders	true	Vertical cell borders
enablePagination	false	Render pagination bar and slice rows
showRowNumbers	false	Add global row-number column
pinnedColumnCount	0	Freeze leading data columns during horizontal scroll
expansionBuilder	null	Enables expandable rows

When enablePagination is true and onPageChanged is provided, the caller owns pagination and supplies the current page's items. Without onPageChanged, the widget can self-manage pagination from the full items list.

API Parameters

Type	Parameter	Purpose
TableWidget	columns, items	Required column model and rows to display.
TableWidget	currentPage, pageSize, totalCount	Controlled pagination state when onPageChanged is set.
TableWidget	enablePagination	Shows pagination and slices rows in self-managed mode.
TableWidget	onColumnReordered, onColumnResized	Persist saved-view order and width changes.
TableWidget	pinnedColumnCount, showRowNumbers	Freeze leading data columns and optionally add global row numbers.
TableWidget	expansionBuilder, expansionMaxHeight	Enable expandable row details.
TableColumn	widthFactor, minWidth	Fractional/fixed width and per-column floor.
TableColumn	headerActionsBuilder, menuItemsBuilder	Header action slots and column context menu items.
TableConfig	theme, density, state builders	Reusable visual/behavior bundle for table families.

TableConfig, Density, Theme

Use TableConfig when a table type has stable visual and behavior settings:

const tableConfig = TableConfig(
  rowHeight: 56,
  pinnedColumnCount: 1,
  enablePagination: true,
  showRowNumbers: true,
  density: TableDensity.normal,
);

TableWidget<Area>(
  config: tableConfig,
  columns: columns,
  items: areas,
)

TableDensity values are compact, normal, and relaxed. Passing density derives a TableTheme from the ambient ThemeData and CdxConfig; passing theme gives full visual override control.

Edge inset

Nothing a table draws touches its container's edge. The header and row bands run full-bleed, but the text of the first and last columns, a group band's label and the footer's ends keep TableTheme.edgeInset from the edge: CdxConfig.containerPadding, the inset of every CDX card and panel (tableEdgeInset(config)). Inner columns keep their own cell padding, so the gutter between two columns does not change. DataTableView insets its toolbar, a load failure and its pager by the same amount, so the search box, the first column's text and the range under the table line up.

Resize Infrastructure

HoverColumnResizer and TableResizeStore are public so custom table headers can share the same resize behavior and state model as TableWidget.

Cross-links

• Theming — table theme derives from CdxConfig
• Buttons — header actions reuse CDX buttons
• Field Formatting — format values before rendering custom cells