@omega/table (0.2.1)
Installation
@omega:registry=npm install @omega/table@0.2.1"@omega/table": "0.2.1"About this package
@omega/table
DataTable is the styled table facade over TanStack Table. Applications own
data loading and business behavior; the package owns table state, rendering,
accessibility, selection, filtering, column layout, and virtualization.
Styling contract
Import @omega/table/styles.css. Package styles consume the shared
--spp-ui-* theme tokens and expose stable semantic --spp-ui-table-*
properties. Add an application class through className and override tokens on
the same element:
<DataTable className="orders-table" data={rows} columns={columns} />
.orders-table {
--spp-ui-table-cell-px: 8px;
--spp-ui-table-cell-py: 4px;
--spp-ui-table-header-height: 36px;
--spp-ui-table-font-size: 13px;
--spp-ui-table-border-radius: 4px;
}
The defaults use :where(.spp-ui-table-root, .spp-ui-table__popover), so an
application class on the table root wins without !important. Portaled column
menu and filter popovers also carry the token defaults (and data-density)
because they render outside the table tree.
Public semantic tokens
- Surfaces:
--spp-ui-table-bg-surface,--spp-ui-table-bg-header,--spp-ui-table-bg-row,--spp-ui-table-bg-row-hover,--spp-ui-table-bg-row-selected,--spp-ui-table-bg-row-selected-hover,--spp-ui-table-bg-pinned. - Borders and typography:
--spp-ui-table-border-color,--spp-ui-table-border-radius,--spp-ui-table-font-size,--spp-ui-table-header-font-weight. - Density and spacing:
--spp-ui-table-row-height,--spp-ui-table-header-height,--spp-ui-table-cell-px,--spp-ui-table-cell-py,--spp-ui-table-header-cell-px,--spp-ui-table-floating-filter-py. - Controls and menus:
--spp-ui-table-header-action-size,--spp-ui-table-control-radius,--spp-ui-table-control-hover-bg,--spp-ui-table-menu-min-width,--spp-ui-table-menu-item-min-height,--spp-ui-table-menu-item-padding. - Feedback:
--spp-ui-table-highlight-duration,--spp-ui-table-highlight-added-bg,--spp-ui-table-highlight-updated-bg,--spp-ui-table-highlight-deleted-bg,--spp-ui-table-row-disabled-opacity,--spp-ui-table-row-removing-opacity,--spp-ui-table-row-placeholder-opacity. - Overlays and popovers:
--spp-ui-table-overlay-min-height,--spp-ui-table-overlay-padding,--spp-ui-table-popover-min-width,--spp-ui-table-popover-bg,--spp-ui-table-popover-shadow,--spp-ui-table-popover-padding,--spp-ui-table-popover-gap.
Sticky positioning, z-indexes, table layout, and virtualization geometry are implementation details and are intentionally not theme tokens.
Layout and sizing
DataTable fills the size of its container (the AG Grid / MUI DataGrid model):
the root is a flex column with flex: 1 1 0% and height: 100%, only the body
scrolls, and the header, footer, and state overlays (loading / empty / error)
stay pinned within the same region. This avoids layout shift when rows arrive
or the table becomes empty.
The container must provide a definite size — typically a flex chain with
min-height: 0 at every level:
.screen-root {
display: flex;
flex-direction: column;
height: 100%; /* not `max-height`: the table fills the screen, it does not grow with content */
}
If the container has no definite height, the table degrades gracefully to
content height (embedded scenarios). To keep a content-sized table inside a
flex container, opt out explicitly via className:
.embedded-table {
flex: 0 0 auto;
height: auto;
}
Density
density provides coherent compact, standard, and comfortable presets.
It changes semantic row/header tokens and the default virtualization estimate.
Header vertical size is owned by --spp-ui-table-header-height (not padding).
Explicit CSS token values can refine a preset; an explicit
virtualization.estimateRowHeight takes precedence over its estimate.
Locale
Package defaults are Russian (defaultDataTableLocaleText /
ruDataTableLocaleText). For English UI pass the EN pack:
import { DataTable, enDataTableLocaleText } from '@omega/table';
<DataTable data={rows} columns={columns} localeText={enDataTableLocaleText} />;
Partial overrides still work; nested filterOperators merges correctly via
resolveDataTableLocaleText(overrides) (or with an explicit base).
Tree Data
treeData turns the table into a treegrid: hierarchical rows expand in place,
compose with sorting, filtering, pinning, virtualization, and column management.
The hierarchy source is a discriminated union — exactly one of getSubRows
(nested data) or getParentId (flat relational data). In tree mode getRowId
is required at the type level, because expansion state is keyed by row id.
<DataTable
data={flatRows}
columns={columns}
getRowId={(row) => row.id}
treeData={{
column: 'name',
getParentId: (row) => row.parentId,
defaultExpandedDepth: 1,
}}
/>
getRowHasChildrenshows an expander for nodes whose children are not loaded yet;onRowExpandedChangeis the seam for lazy level loading.- Filtering follows the AG Grid default: a row is visible when it matches, any
ancestor matches, or any descendant matches — matching parents keep their
children, matching leaves keep their ancestor chain, and branches with
matches are derived-expanded while a filter is active (without overwriting
the user's
expandedstate). guidelines: truerenders opt-in hierarchy guides (VSCode / MUI X style indent lines with ├/└ connectors, terminated on last children). Styled via--spp-ui-table-tree-guide-color,--spp-ui-table-tree-guide-width, and--spp-ui-table-tree-guide-style.- Alt/Ctrl-click on an expander toggles the whole loaded branch; the tree column
menu adds "Expand all" / "Collapse all", and
apiRef.treeexposesexpandAll/collapseAll/expandRow/collapseRow/expandToDepth. - The tree column cannot be hidden; indentation is themed via
--spp-ui-table-tree-indent.
Customization levels
- CSS variables and
densityfor visual customization. - Column definitions, metadata, class/style resolvers, and locale text.
- Slots and column-menu command customization for structural replacement.
useDataTableInstance,tableRef, andapiReffor advanced integrations.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @dnd-kit/core | ^6.3.1 |
| @dnd-kit/sortable | ^10.0.0 |
| @dnd-kit/utilities | ^3.2.2 |
| @omega/icons | 0.2.0 |
| @omega/ui | 0.3.0 |
| classnames | 2.5.1 |
Development Dependencies
| ID | Version |
|---|---|
| @tanstack/react-table | 8.21.3 |
| @tanstack/react-virtual | 3.14.6 |
| react-aria-components | 1.19.0 |
Peer Dependencies
| ID | Version |
|---|---|
| @tanstack/react-table | >=8.20.0 |
| @tanstack/react-virtual | >=3.13.0 |
| react | >=18.3.0 |
| react-aria-components | >=1.19.0 |
| react-dom | >=18.3.0 |
Optional Dependencies
| ID | Version |
|---|---|
| @tanstack/react-table | 8.21.3 |
| @tanstack/react-virtual | 3.14.6 |