0.6.0-beta

Released 2026-05-19 · Sprint 4.1 release

Sprint 4.1 ships <Table> — the central piece of the data layer for @dashforge/tw. Built from scratch with zero new runtime deps, market-grounded design (Stripe visuals, Atlassian column UX, Pencil & Paper density tiers, W3C WAI Table a11y), full RBAC integration, full i18n surface, and a cell renderer library ready out of the box.

This release also codifies two architectural rules that emerged during Sprint 4.1 development — both now Dashforge persistent memory:

1. The dashforgePreset default IS the visual identity — consumer apps consume it as-is. Adding dark: variants on the neutral palette = double inversion = breaks dark mode (canonical pattern: auto-invert via CSS var swap; selected states use bg-primary-100 text-primary-900 à la LeftNav itemActive).
2. The library never picks a font family for the consumer — tabular-nums (font-feature setting for digit grid alignment) yes, font-mono (font family override) only on explicit consumer opt-in via col.monospace: true.

The first rule is enforced in the Table sources via a regression test (themeIdentity.test.ts). The second is encoded in the tabularNums / monospace split on TableColumn<T>.

Strictly additive minor bump. Drop-in upgrade from 0.5.0-beta — zero breaking changes.

Affected packages

Unchanged (independent versioning):

Added

<Table> — the central data-display primitive

import { Table } from '@dashforge/tw';

<Table
  rows={users}
  cols={[
    { field: 'name',  header: 'Name',  sortable: true, searchable: true },
    { field: 'email', header: 'Email', searchable: true },
    { field: 'age',   header: 'Age',   sortable: true },
  ]}
  getRowId={(row) => row.id}
/>

Smart defaults — column types auto-detected

tabular-nums is a font-feature setting that makes every digit the same width — currency / metric columns align cleanly without imposing a font family on the consumer. The library never changes the font family (see "font family rule" above); monospace: true is an explicit per-column opt-in.

Sort: single + multi-column

• Click a sortable header → asc · click again → desc · click again → cleared (3-state cycle)
• Shift-click adds the column to a multi-sort model
• Null-last invariant (direction-independent): null / undefined always sort to the end, regardless of asc/desc. Avoids the "null at the top in desc" surprise
• Custom comparator per column: sortable: (a, b) => a.name.length - b.name.length
• Controlled via sortModel + onSortChange or uncontrolled internal state

Search: debounced + nested keys

• enableSearch renders a debounced input above the table (default 200 ms)
• Matches any column flagged searchable: true
• Nested keys supported at runtime via getNestedValue (the type-level autocomplete from NestedKeyOf<T> matches the runtime behavior — field: 'address.city' resolves correctly)
• Stringification handles string / number / boolean / Date / Array / object (JSON.stringify)

Selection: bulk actions when selected

• rowSelection: 'none' | 'single' | 'multiple'
• Optional select-all checkbox in the header (multiple mode)
• Controlled via selectedRowIds + onSelectionChange
• Sticky bulk-action footer rendered ONLY when at least one row is selected (Pencil & Paper UX pattern: "appear only when selected")
• aria-selected on selected rows; default a11y labels translatable via labels.ariaSelectRow / ariaSelectAllRows

Expandable rows

<Table
  expandable={{
    render: (row) => <UserDetail user={row} />,
    expandedRowIds: expanded,
    onExpandChange: setExpanded,
  }}
/>

Chevron toggle in a dedicated column · aria-expanded on the button · expanded detail renders as a full-width sibling <tr>.

Row actions revealed on hover (Stripe pattern)

<Table
  rowActions={(row) => (
    <RowActionsMenu
      row={row}
      actions={[
        { label: 'Edit',   onClick: edit },
        { label: 'Delete', onClick: del, color: 'danger',
          access: { resource: 'user', action: 'delete', onUnauthorized: 'hide' } },
      ]}
    />
  )}
/>

Actions hidden by default via opacity, revealed on tr:hover or tr:focus-within. Reduces visual density while keeping actions keyboard-accessible.

RBAC at 3 levels

i18n surface

Column headers accept plain strings (pass t('users.name') directly). All internal default strings (search placeholder, a11y announcements, selection counter, density / filter labels) configurable via labels prop. Same pattern as <Pagination>.

<Table
  cols={[{ field: 'name', header: t('users.name'), sortable: true }]}
  labels={{
    searchPlaceholder:  t('table.search.placeholder'),
    selectedCount:      t('table.selection.count'),    // {count} placeholder
    ariaSelectRow:      t('table.a11y.selectRow'),
    ariaSortAscending:  t('table.a11y.sortAsc'),
    // …all 17 strings translatable
  }}
/>

5 variants × 3 sizes × 3 densities

• Variants: plain · lines (default — Stripe-style clean dividers) · striped · bordered · card
• Sizes: sm · md (default) · lg
• Densities: compact (40px row) · comfortable (default 48px) · spacious (56px) — Pencil & Paper UX research

Sticky header by default · loading skeleton · empty state

• Sticky header pinned during scroll (override via stickyHeader={false})
• loading={true} renders N <Skeleton> rows (Sprint 4 component) with aria-busy="true"; loadingRowCount configurable
• Custom emptyState ReactNode for no-data placeholders

Customization escape hatches

• sx for root override
• 15 named slots via slotProps: root, toolbar, search, scroll, table, thead, tbody, headerRow, headerCell, row, cell, selectionCell, expandToggleCell, expandedRow, rowActionsCell, emptyState, loadingOverlay, bulkActionFooter

Cell renderer library

5 pre-built renderers exported from @dashforge/tw:

import {
  RenderText,        // one-line, optionally truncated / muted
  RenderTwoLine,     // bold primary + muted secondary (name + email)
  RenderChip,        // status badge: 7 intents × 3 variants × 2 sizes
  RenderButton,      // inline button (ghost / sm defaults)
  RowActionsMenu,    // 3-dot Popover menu + per-action RBAC
} from '@dashforge/tw';

RowActionsMenu reuses the <Popover> component (Sprint 3) — no new deps.

getNestedValue helper exported

import { getNestedValue } from '@dashforge/tw';

getNestedValue({ user: { name: 'Jane' } }, 'user.name')  // 'Jane'
getNestedValue({ user: null }, 'user.name')              // undefined
getNestedValue({ a: { b: 0 } }, 'a.b')                   // 0 (preserved)

Same helper powers Table's cell rendering. Useful in your own custom renderers that need to look up the value with a different transform.

Internal

Theme identity regression guard

New test _internal/themeIdentity.test.ts scans every Table source file and fails if dark:*-neutral-N Tailwind classes are introduced. The dashforgePreset auto-inverts the neutral palette via CSS var swap; adding dark: variants on neutral creates double inversion and breaks dark mode. The guard catches the anti-pattern at test time.

The canonical patterns Table now uses:

// surface (auto-inverts via CSS var swap)
'bg-neutral-50'

// elevated surface (one tier up)
'bg-neutral-100'

// primary text (auto-inverts)
'text-neutral-900'

// secondary text (auto-inverts)
'text-neutral-500'

// selected state (LeftNav `itemActive` — primary palette
// doesn't auto-invert, so dark-navy text on light-blue bg
// works in BOTH modes; guaranteed contrast).
'data-[selected=true]:bg-primary-100',
'data-[selected=true]:text-primary-900',
'data-[selected=true]:font-medium',

Sprint 4.3 (0.7.0-beta) will sweep the rest of the catalog (Typography, Box, etc. carry the same latent bug) and add the guard at package level.

Font family rule

The TypeScript surface of TableColumn<T> splits the previously-conflated monospace axis into two:

• tabularNums?: boolean — auto-true for number / date columns. Applies tabular-nums (font-feature setting, does not change the font family).
• monospace?: boolean — explicit consumer opt-in only. Applies font-mono. The dashforgePreset does not own the fontFamily axis; the consumer configures their mono stack in their own tailwind.config.ts theme.extend.fontFamily.mono.

Smoke-test page

~/projects/web/learn/dash/src/pages/TestTable.tsx exercises every Table feature with 30 realistic users + nested meta + chip-rendered status + RBAC per-column + Italian i18n labels + 5×3×3 variant/size/density switcher.

Tests

+147 new unit tests for Sprint 4.1:

• getNestedValue — 11 (nested keys, null-safety, zero / empty string / false preservation, mid-tree returns)
• useTableSearch — 16 (stringification across primitive types, nested keys, edge cases)
• useTableSort — 15 (null-last invariant, multi-column tie-breaking, custom comparator, locale-aware string compare)
• useTableSelection — 13 (single / multiple / none modes, select-all, indeterminate state)
• useColumnAutoDetect — 14 (type inference + align / tabularNums / monospace resolution)
• themeIdentity — 18 (file scanner regression guard)
• Table.test.tsx — 57 (rendering, smart defaults, sort, search, selection, expandable, row actions, RBAC, variants, densities, sizes, sx + slotProps, i18n)

Full @dashforge/tw suite at 828/828 passing across 46 files.

Migration

No code changes required:

pnpm up @dashforge/tw@^0.6.0-beta

To adopt the new Table:

import {
  Table,
  RenderTwoLine,
  RenderChip,
  RowActionsMenu,
  Button,
} from '@dashforge/tw';

<Table
  rows={users}
  cols={[
    {
      field: 'name',
      header: 'Name',
      sortable: true,
      searchable: true,
      cellRenderer: ({ row }) => (
        <RenderTwoLine primary={row.name} secondary={row.email} />
      ),
    },
    {
      field: 'status',
      header: 'Status',
      cellRenderer: ({ value }) => (
        <RenderChip color={value === 'active' ? 'success' : 'warning'}>
          {String(value)}
        </RenderChip>
      ),
    },
  ]}
  getRowId={(r) => r.id}
  enableSearch
  rowSelection="multiple"
  bulkActions={(rows) => (
    <Button color="danger">Delete {rows.length}</Button>
  )}
  rowActions={(row) => (
    <RowActionsMenu
      row={row}
      actions={[
        { label: 'Edit',   onClick: edit },
        { label: 'Delete', onClick: del, color: 'danger' },
      ]}
    />
  )}
/>

Compatibility

Bundle regression sign-off: the +23% gz delta is above the 10% reviewer-sign-off threshold defined in PERFORMANCE.md. Justification: <Table> is the central data-display primitive — the highest-leverage addition before 1.0. Sprint 4.3 (0.7.0-beta) is expected to shrink the bundle by 1-3 KB gz by removing redundant dark: variants across the catalog.

Looking ahead