Skip to content

Migrating Hand-Rolled Tables

How to replace a raw <table>, and how to pick what it becomes.

waldur-custom/no-hand-rolled-table is an error: every raw <table> that predates it has been migrated, so a new one fails lint.

Not every table should become @/table/Table: a short read-only list gains nothing from a fetch cycle, a Redux table store and five props to switch its chrome off. Pick the target by what the table is, not by the fact that it is a <table>.


Decision tree

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
Is it a list of records (one row per item, same columns)?
├─ No — label/value pairs about one thing ............ 1. Label/value block
├─ No — form grid, custom footer, or preview ......... 2. Table primitives
└─ Yes
   ├─ Does ANY of these hold?
   │    • the rows come from a paginated list endpoint (it takes page /
   │      page_size), so the server has to page them
   │    • users need to search, sort or filter the rows
   │    • it needs selection, expandable rows or a menu of row actions
   │    • it needs export, or an empty state with a call to action (NoResult)
   │  └─ Yes ............................................. 3. @/table/Table
   └─ No: standard in-memory list rendered with consistent columns
      (dialog summary, reference list, review step, docs table)
                                                       ... 4. SimpleTable

Row count alone is not a reason to use Table. If the rows are already in memory (one detail or aggregate response, a form value, static data), paging them in the browser adds clicks and a fetch cycle but saves nothing: render them with SimpleTable, and if the list can be long, cap its height with a scroll container. Page in the browser (createClientPaginatedFetcher) only when a list in memory runs to hundreds of rows and needs Table's other features.

Conversely, a list read with a hook that calls a paginated endpoint without page/page_size silently shows only the backend's first page. That is the clearest case for Table with createFetcher: the server pages, and the table shows every page.

A single button that is the purpose of each row (Link, Select, Retry) is a column, not a row action, and can stay in SimpleTable. Use Table's 3-dots menu when a row has several actions or ones that are secondary to reading it.

SimpleTable takes the same Column<T> definitions as Table, so moving a list from 4 to 3 later is a component swap plus useTable, not a rewrite.


1. Label/value block

A details panel, an expandable-row summary or a "Connection" card: each row is one label and one value about a single object. This is not tabular data.

Use PropertyList, PropertyItem, and PropertyCard from waldur-ui (which renders accessible <dl>/<dt>/<dd> markup across both Homeport and standalone micro-apps). Do not hand-roll raw <dl> grids, local DetailRow / InfoRow wrappers, or borderless <table> markup. Choose the variant by what the rows do, not by where the block sits:

1
2
3
4
5
6
7
Can the user act on a row (an edit button, an inline control, an action)?
├─ Yes .................................................... PropertyList (variant="divided") + PropertyItem / *EditField
└─ No: read-only
   ├─ Must every property show, even when it has no value
   │  (a settings or configuration overview, where "not set" is information)?
   │  └─ Yes ............................................... PropertyList (variant="divided") + PropertyItem
   └─ No: a summary that leaves out what is empty ......... PropertyList (variant="summary") + PropertyItem, or ExpandableContainer asTable
PropertyList (variant="divided") + PropertyItem PropertyItem (variant="summary", or inside ExpandableContainer asTable)
For Editable details and settings panels; read-only configuration overviews Read-only summaries: expanded rows, detail dialogs, preview cards
Empty value Row stays; pass renderFieldOrDash(value) so it reads as a dash Row is left out; pass the raw value
Row actions actions column; *EditField adds the edit button None
Controls in rows Label is a <label> pointing at the row's control; required, description, warnTooltip Not for controls
Extras PropertyCard (title, refresh, toolbar), grouped rows, detailsMode hasCopy, help tooltip, colon and long-label tooltip added for you

When a block is half and half (read-only rows plus one editable row), wrap it in <PropertyList> (variant="divided").

Rows always sit in a list. A PropertyItem outside one wraps itself in its own <dl>, so loose rows read to a screen reader as a run of one-item lists, and a grid of <div> cells with one row each is as many lists as cells: make the PropertyList the grid instead (className="grid sm:grid-cols-2 gap-x-5"). waldur-custom/property-item-in-list flags rows that render inside another element before reaching a list. A component that returns only rows (a fragment of PropertyItems) is fine: its caller holds the list.

An expanded row whose rows sit in columns or sections of their own takes <ExpandableContainer alignRows> rather than asTable: it lines the labels up the same way, without wrapping the columns in a list, and each column holds its own <PropertyList variant="summary">.

PropertyList, a page's settings panel with every property shown:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import { PropertyItem, PropertyList } from 'waldur-ui';

<PropertyList>
  <PropertyItem
    label={translate('Partner Name')}
    value={renderFieldOrDash(settings.partner_name)}
  />
  <PropertyItem
    label={translate('Sync Enabled')}
    value={settings.sync_enabled ? translate('Yes') : translate('No')}
  />
</PropertyList>;

With editable rows, use the *EditField exports inside an EditFieldProvider instead of PropertyItem (docs/forms.md → Edit Field Architecture). References: src/administration/arrow/settings/ArrowSettingsCard.tsx (read-only overview), src/customer/details/CustomerDetailsPanel.tsx (editable).

PropertyItem (summary mode), a read-only summary; in an expandable row, wrapped so labels and values line up in columns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import { PropertyItem } from 'waldur-ui';

import { ExpandableContainer } from '@/table/ExpandableContainer';

const RecordDetail = ({ row }) => (
  <ExpandableContainer asTable>
    <PropertyItem label={translate('Resource')} value={row.resource_name} />
    <PropertyItem
      label={translate('Created')}
      value={formatDateTime(row.created)}
    />
    <PropertyItem
      label={translate('Final (Sell)')}
      value={row.final_sell ? defaultCurrency(row.final_sell) : null}
      valueClass="font-medium"
    />
  </ExpandableContainer>
);

In a dialog or card, list the PropertyItems directly. References: ConsumptionRecordDetail in src/administration/arrow/consumption/ConsumptionRecordsList.tsx (expandable row), the header of src/administration/arrow/mappings/CustomerBillingSummaryDialog.tsx (dialog).

What Field does for you, so callers do not repeat it:

  • Empty values: a row whose value is undefined, null, '' or false is left out. Pass the raw value; do not add renderFieldOrDash or a dash fallback. 0 is a value and is shown, so pass counts as numbers rather than wrapping them in String(...). The one exception is a property whose absence is itself information (a final amount not confirmed yet): pass DASH_ESCAPE_CODE for it, with a comment, so the row stays.
  • Labels: a string label gets its colon, and a long one a tooltip; do not add : to the translation.
  • Extras: hasCopy for a copy button, tooltip for a help icon, valueClass / labelClass for emphasis or a fixed label width.

2. Table primitives (form grids, custom footers, previews)

When a table is not a standard paginated record list, but rather:

  • A grid of form inputs: a price editor (PricesTable), quota limits (QuotasTable), security group rules (RulesList), or mapping step in a wizard (Step2CustomerDiscovery).
  • A table with totals or footers: invoice summaries (InvoiceDetails), cost breakdowns.
  • An inline preview or compact history: command previews (SlurmPolicyPreview), card state history (PubSubCircuitBreakerCard), or sub-tables in expandable rows.

@/table/Table fights these shapes: it brings a fetch cycle, a Redux store, pages rows (hiding fields with errors), reserves min-height, and sizes columns for paginated data. SimpleTable also fights them when you need custom colspans, form controls, or footer rows.

Build them with waldur-ui's Table primitives:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import {
  Table,
  TableBody,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from 'waldur-ui';

<Table density="compact">
  <TableHeader>
    <TableRow>
      <TableHead>{translate('Component')}</TableHead>
      <TableHead>{translate('Limit')}</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {components.map((component) => (
      <TableRow key={component.type}>
        <TableCell>{component.name}</TableCell>
        <TableCell>
          <Field name={`limits.${component.type}`} component={NumberField} />
        </TableCell>
      </TableRow>
    ))}
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell>{translate('Total')}</TableCell>
      <TableCell>{totalLimit}</TableCell>
    </TableRow>
  </TableFooter>
</Table>;

Key props on the primitives:

  • <Table density="compact" | "normal" | "spacious">: Controls cell padding and typography.
  • <Table scrollable={false}>: Drops the outer overflow wrapper when the parent container (e.g. modal body) already handles scrolling.
  • <TableRow hoverable={false}>: Disables row hover highlight for static read-only tables.
  • <TableRow divided={false}>: Drops the bottom border.
  • <TableFooter>: Semantic <tfoot> with token borders and background for summary/totals rows.

3. @/table/Table

A list that needs the server to page it, or needs search, sorting, filters, selection, expandable rows or a menu of row actions. Follow the other table guides; the parts specific to migrating:

  • Server data: createFetcher(sdkFunction) with a memoized filter, as in fetching.md. This replaces a useQuery hook that read the list endpoint itself; drop the hook if nothing else uses it.
1
2
3
4
5
6
7
8
9
const filter = useMemo(
  () => ({ resource_uuid: resource.uuid }),
  [resource.uuid],
);
const tableProps = useTable({
  table: `arrow-consumption-history-${resource.uuid}`,
  fetchData: createFetcher(adminArrowConsumptionRecordsList),
  filter,
});

Reference: src/administration/arrow/resources/ViewConsumptionHistoryDialog.tsx.

  • Rows already in memory that still need Table (hundreds of rows with search or sorting): createClientPaginatedFetcher(rows). The fetcher closes over the rows and useTable does not key its query on them, so refetch when they change, or the table keeps its first (often empty) result:
1
2
3
4
5
6
7
const tableProps = useTable({
  table: `my-local-list-${scopeUuid}`,
  fetchData: createClientPaginatedFetcher(rows),
});
useEffect(() => {
  tableProps.fetch();
}, [rows]);
  • The table id is global. A table rendered once per row, per dialog or per scope needs the scope's uuid in its id (arrow-consumption-lines-${uuid}), or two copies share one store entry.
  • Nested in a dialog, tab or expandable row: drop the chrome the parent already provides:
1
2
3
4
5
6
7
8
9
<Table
  {...tableProps}
  columns={columns}
  verboseName={translate('billing lines')}
  hideTitle
  hasActionBar={false}
  placeholderHasRetry={false}
  minHeight="auto"
/>
  • Several or secondary buttons in a row become row actions (ActionsDropdown + ActionItem, see row-actions.md).
  • Tests that render the list need a table store:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { Provider } from 'react-redux';

import { createTablesStore } from '@/table/store';

renderWithProviders(
  <Provider store={createTablesStore()}>
    <DrawerProvider>
      <MyList />
    </DrawerProvider>
  </Provider>,
);

Rows arrive asynchronously: use findBy*, not getBy*.

4. SimpleTable

A list already in memory, with the main table's look and none of its fetching, paging, sorting or filters. No store, no id, no fetch cycle, and new rows show on the next render with no refetch; tests render it without providers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import { SimpleTable } from '@/table/SimpleTable';
import { Column } from '@/table/types';

const columns: Column<ExportType>[] = [
  { title: translate('Export type'), render: ({ row }) => <>{row.name}</> },
  {
    title: translate('Fields'),
    render: ({ row }) => <>{row.required_fields_found}</>,
    className: 'text-end',
    headerClassName: 'text-end',
  },
];

<SimpleTable columns={columns} rows={exportTypes} rowKey="reference" />;

It renders only the header when rows is empty, so keep the caller's own empty message (rows.length === 0 ? <p>…</p> : <SimpleTable … />). It has no footer row: put a total in the surrounding card header or below the table.

  • A list that can be long keeps every row and caps its height instead of paging (the header scrolls with the rows):
1
2
3
<div className="max-h-[300px] overflow-y-auto">
  <SimpleTable columns={columns} rows={licenses} />
</div>
  • A button that is the point of the row is a column:
1
2
3
4
5
6
7
8
{
  title: translate('Action'),
  headerClassName: 'text-end',
  className: 'text-end',
  render: ({ row }) => (
    <BaseButton label={translate('Link')} onClick={() => link(row)} />
  ),
}

References: src/administration/arrow/mappings/SuggestedMatches.tsx (button column), src/administration/arrow/mappings/ArrowLicensesList.tsx (capped height).


Behaviour changes to call out

Migrating is not a pure restyle. List each of these in the MR when it happens:

Change Why it matters
A capped list (slice(0, 10) + "Showing 10 of N") now shows every row Cap the height with a scroll container if it can be long
A list read from a paginated endpoint now pages on the server It showed only the first page before; now it shows every row
A <tfoot> total is dropped Table and SimpleTable have no footer row; show the total above
A row button moves into the 3-dots menu One more click; tests that clicked the button must open the menu
A form grid gains a pager Rows being edited can be paged out of view; use a form grid (2)
An empty table now shows NoResult Check the caller does not also render its own empty message

Working a batch

One MR per area (Arrow, Matrix, marketplace policies, proposals, reporting, OpenStack), as #563 proposes.

  1. Inventory the area. Search for raw tables:
1
grep -rl "<table" src/<area> --include=*.tsx
  1. Classify every site with the decision tree and write the table into the MR description: file, shape, target (1–4), behaviour changes.
  2. Migrate. Keep translations, cell content and badges as they are; change the container, not the content.
  3. Verify: yarn tsgo --noEmit, yarn lint:check, targeted vitest for the area, and before/after screenshots of each dialog or page touched.
  4. Confirm the area is clean: no <table or table-* class left in it outside files on the rule's allowed list.

Framework work before the remaining batches

These remove the workarounds above; each one is cheaper to do once than to repeat across the remaining batches.

  • In-memory rows in useTable: accept the rows directly and refetch when they change, so the useEffect refetch and the hand-scoped id go away.
  • An embedded preset for Table: one prop in place of hideTitle, hasActionBar={false}, placeholderHasRetry={false} and minHeight="auto".
  • SimpleTable: an empty message and an optional footer row for totals.
  • Field in the table module next to SimpleTable, as the app's general property list rather than a resource-summary part.
  • The hand-rolled property lists outside Arrow moved to Field: local ClusterInfoRow (RabbitMQClusterOverview.tsx) and DetailRow (InvitationDetailsCard.tsx), and the <dl> blocks in TicketDraftCard.tsx, RuleTestMatchDialog.tsx, MergeCheckDetailsDialog.tsx and ResourceLimitDetails.tsx.
  • A renderWithProviders option that supplies the table store.