# Registry tables

Registry tables are the canonical pattern for scanning, comparing, and acting on collections of records. The contract applies equally to a native table and an application-owned data-table library.

## Anatomy

1. Optional search and structured filters.
2. Column headers with visible sort direction when sortable.
3. Rows with one primary destination and optional secondary actions.
4. Status, identity, and tag cells using their dedicated shared patterns.
5. A stable footer with result range and pagination.

## Applied filters

- Keep the filter count in the Filters trigger.
- When structured filters are applied, render removable chips immediately below the toolbar and outside the filter popover so their labels and values remain visible while the popover is closed.
- Format each chip as `Label: Value`, give its remove button an explicit accessible name, and update the results immediately when it is removed.
- The global Clear action may also clear search; the visible chips represent structured filters only.

## Density and alignment

- Use the compact 36px control height in the table toolbar and 48px minimum rows.
- Align text left, numeric values right, and compact statuses consistently by column.
- Keep the first meaningful column visible; allow horizontal scrolling before hiding data.
- Use truncation only when the complete value remains available through a link, title, or detail view.

## Sorting and actions

- Put sortable labels inside buttons and set `aria-sort` on the owning header cell.
- A row can have one primary link. Do not make both the row and several cells competing links.
- Put infrequent secondary operations in an overflow action menu.
- Bulk actions appear only after selection and must state the selected count.

## Pagination

- Always show the result range when results exist.
- Use Previous and Next at minimum. Numbered pages are optional for large, directly navigable collections.
- Preserve search, filters, and sort when changing pages.
- Keep the footer height stable while data reloads.

## States

- Loading keeps the table footprint stable and exposes `aria-busy="true"`.
- When the underlying collection has no records and no query is active, hide the search and filter toolbar.
- Keep the toolbar visible when an active search or filter yields no results so the user can revise or clear the query.
- No results with active filters offers a clear-filters action.
- First-use empty states may offer one primary creation action.
- Recoverable failures show an inline retry action without discarding the current query.

## Application boundary

Query serialization, permissions, row destinations, server pagination, selection rules, and data-table library adapters remain product-owned.