Goal: one table stack for backend CMS surfaces (entry-list, media, users) and frontend design-system tables (ui/table) — less duplication, more flexibility, performance, features, and security.

P0 building blocks (implemented)

Entry-list UX (P1 wired)

<SmartTableShell
  empty={rows.length === 0}
  emptyTitle="No results"
  {currentPage} {rowsPerPage} {pagesCount} {totalItems}
  onUpdatePage={(p) => table.setPage(p)}
  onUpdateRowsPerPage={(n) => table.setPageSize(n)}
>
  <table class={SMART_TABLE}>…</table>
</SmartTableShell>

Architecture

Modes

// CMS / entry-list (server mode)
const table = createSmartTable({
  mode: "server",
  onQueryChange: (updates) => updateURL(updates),
  getRowId: (row) => String(row._id),
});
table.setRows(serverEntries);
table.setPaginationMeta(serverPagination);

// Design system (client mode)
const table = createSmartTable({ mode: "client", pageSize: 10 });
table.setRows(localRows);

Advanced UX Capabilities

1. Multi-Column Sorting & Ordinal Ranks

Smart Table supports multi-tier sorting, both client-side and serialized for server queries.

• Interaction: Single-clicking a sortable column header replaces the sort order. Holding Shift while clicking appends or toggles the column in the multi-sort chain.
• Visual Ranks: When multiple columns are sorted, secondary and tertiary columns display ordinal rank indicators (1, 2, 3) alongside the direction arrow.
• Controller API:
  • table.setSort(field, { multi: true }): Toggles sort direction for field while keeping existing sorts.
  • table.getSortRank(field): Returns 1-based priority rank or null if not sorted.
  • table.clearSorts(): Resets all active sort descriptors.
  • table.multiSort: Readonly reactive array of active ColumnSortDescriptor[].
• Query Serialization: In server mode, multiple sorts serialize into the URL parameter format sort=priority:desc,status:asc,title:asc.
• Persistence: Saved with the view or stored in localStorage under layoutKey.

2. Responsive Card Mode

For mobile viewports or data presentation emphasizing rich item cards:

• View Mode Toggle: Users can switch between standard tabular grid (viewMode: 'table') and responsive card deck (viewMode: 'card').
• Persistence: Preserved per collection or view in SmartTableLayoutPrefs (viewMode).
• Accessibility: View toggle buttons carry aria-pressed states and clear accessible labels.
• Cards Grid: When viewMode === 'card', entries render as responsive cards with status badges, thumbnail previews, inline selection checkboxes, and full row activation.

3. Keyboard Grid Navigation (WCAG 2.2 AA / ATAG 2.0)

Smart Table implements the WAI-ARIA Data Grid keyboard navigation pattern with a roving tabindex:

• Focus Management: Only the currently active cell has tabindex="0"; all other cells have tabindex="-1".
• Arrow Keys:
  • ArrowDown / ArrowUp: Move focus between rows within the same column.
  • ArrowRight / ArrowLeft: Move focus between columns within the same row (RTL-aware).
  • Home / End: Jump to the first or last cell in the active row.
• Row Selection & Activation:
  • Space: Toggles row selection without navigating away.
  • Enter: Navigates to the entry editor or triggers the row’s primary action.
• Screen Reader Announcements: Uses role="grid", role="row", and role="gridcell" with live selection status updates.

4. Advanced Filter Modal

A compound filter builder powered by advanced-filter-modal.svelte:

• Rule Clauses: Allows chaining multiple field criteria with comparison operators (contains, equals, starts_with, ends_with, gt, lt, is_empty, is_not_empty).
• Conjunction Groups: Supports compound AND / OR condition logic.
• Schema-Aware Inputs: Automatically renders appropriate inputs (text, number, date, select) based on collection field widget types.
• URL & Engine Integration: AND groups serialize as ?filter_<field>=.... OR groups use ?filterLogic= JSON (size-capped), compiled to whereIn (same field) or QueryBuilder.orWhere (mixed fields), still FLAC-whitelisted.

5. Filtered Selection & Export Data Streaming

Exporting dataset slices without client memory bottlenecks:

• Shortcut: Alt + X triggers export on the active collection.
• Selection-Aware: If entries are selected via checkboxes, exports the selected rows. If no selection is active, exports all entries matching the current filter and search query.
• Streaming Delivery: Downloads data as UTF-8 encoded CSV with proper escaping and column headers.

What was unified

Security (CMS tables)

Filtering/sorting must not be trusted from the client alone:

1. UI sends ?filter_* / sort / page
2. parseCollectionListQuery + schema whitelist
3. compileSecureFilters + FLAC
4. applyFiltersToQueryBuilder portable IR
5. Cache key uses compiled hash + user id

See Collection Filtering Platform.

Migration guide

Other <table> UIs (not full smart-table yet): permissions matrix, media details mini-tables, migration wizard field map, accessibility help, ui/table.svelte design shell.

Shared visual chrome

import {
  createSmartTable,
  SMART_TABLE,
  SMART_TABLE_THEAD,
  SMART_TABLE_TH,
  SMART_TABLE_TD,
  SMART_TABLE_SCROLL,
  SMART_TABLE_PAGINATION_BAR,
  SMART_TABLE_TOOLBAR,
  SMART_TABLE_ROW_SELECTED,
  SMART_TABLE_ROW_HOVER,
} from "@components/ui/smart-table";

SMART_TABLE now carries the shared body baseline: font-sans, text-sm, and text-(--admin-text-body). Primary cells inherit that color so dark mode stays white; only genuinely secondary metadata (paths, sizes, token secrets, muted hints) should add text-(--admin-text-muted). Let SMART_TABLE_TH own the header size rather than a nested text-xs button, otherwise that one table’s headers render a step smaller than the other Smart Tables.

Import map

// Preferred
import { createSmartTable } from "@components/ui/smart-table";
import Pagination from "@components/ui/table/pagination.svelte";

// cms variant:
<Pagination variant="cms" … />

Performance

• Virtualization threshold: VIRTUALIZATION_THRESHOLD (25) via @utils/table-constants
• Server mode: only current page in memory; SWR on service layer
• Client mode: local sort/page without network
• Id selection avoids virtual-index desync bugs

Related

• entry-list
• Collection Filtering
• Cache System

Last Updated: 2026-09-20