@spree/dashboard-core 0.13.0 → 1.0.0-beta.1

package/src/components/resource-table.tsx

@@ -17,7 +17,6 @@ import {
 import { CSS } from '@dnd-kit/utilities'
 import {
   Card,
-  CardContent,
   Checkbox,
   cn,
   DragHandle,
@@ -28,14 +27,21 @@ import {
   EmptyTitle,
   Pagination,
   type PaginationMeta,
+  Skeleton,
   Table,
   TableBody,
   TableCell,
   TableEmpty,
   TableHead,
   TableHeader,
+  TableHeaderRow,
   TableRow,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+  useIsMobile,
 } from '@spree/dashboard-ui'
+import { InfoIcon } from '@spree/dashboard-ui/icons'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 import { useNavigate } from '@tanstack/react-router'
 import {
@@ -45,24 +51,25 @@ import {
   useDeferredValue,
   useEffect,
   useMemo,
-  useRef,
   useState,
 } from 'react'
+import { createPortal } from 'react-dom'
 import { useTranslation } from 'react-i18next'
 import { z } from 'zod/v4'
 import { useAuth } from '../hooks/use-auth'
+import { useVisualViewportOffset } from '../hooks/use-visual-viewport-offset'
 import { filtersToRansack } from '../lib/filters-to-ransack'
 import { withStoreScope } from '../lib/query-keys'
 import {
   type ColumnDef,
   type FilterRule,
   getDefaultColumnKeys,
-  getDisplayableColumns,
   getTable,
   type SortOption,
 } from '../lib/table-registry'
-import { useStore } from '../providers/store-provider'
+import { useTenantId } from '../providers/tenant-provider'
 import { type BulkAction, BulkActionBar } from './bulk-action-bar'
+import { PageHeader } from './page-header'
 import { TableToolbar } from './table-toolbar'
 
 // ============================================================================
@@ -76,6 +83,39 @@ const filterSchema = z.object({
   value: z.string(),
 })
 
+/**
+ * A column header, with its explanation behind an info icon when it has one.
+ *
+ * Figures whose meaning is a definition rather than a word — available,
+ * reserved, incoming — need somewhere to say what they count. A tooltip keeps
+ * that out of the header row until it is asked for.
+ */
+function ColumnLabel({ column, hideHint }: { column: ColumnDef; hideHint?: boolean }) {
+  if (!column.labelHint || hideHint) return column.label
+
+  return (
+    <span className="inline-flex items-center gap-1">
+      {column.label}
+      <Tooltip>
+        <TooltipTrigger asChild>
+          {/* Focusable and named, so the explanation opens on focus as well as
+              hover and reaches a screen reader the same way. */}
+          <button
+            type="button"
+            className="cursor-help rounded-sm text-muted-foreground focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-2"
+            aria-label={column.labelHint}
+          >
+            <InfoIcon className="size-3.5" />
+          </button>
+        </TooltipTrigger>
+        <TooltipContent className="max-w-xs font-normal normal-case">
+          {column.labelHint}
+        </TooltipContent>
+      </Tooltip>
+    </span>
+  )
+}
+
 export const resourceSearchSchema = z.object({
   page: z.coerce.number().optional().default(1),
   limit: z.coerce.number().optional(),
@@ -129,9 +169,9 @@ interface ResourceTableProps<T> {
   /** Registry key (e.g., 'products') */
   tableKey: string
   /**
-   * TanStack Query key prefix. The table auto-injects the current storeId so
-   * mutation hooks that invalidate `['<key>', storeId]` always match — pages
-   * never need to thread storeId through themselves. A plain string is
+   * TanStack Query key prefix. The table auto-injects the current tenant id so
+   * mutation hooks that invalidate `['<key>', tenantId]` always match — pages
+   * never need to thread it through themselves. A plain string is
    * shorthand for `[string]`; pass an array to add further scope (e.g.
    * `[webhookDeliveriesTableKey(endpointId)]`).
    */
@@ -142,6 +182,21 @@ interface ResourceTableProps<T> {
   searchParams: ResourceSearch
   /** Title displayed in the toolbar header. Overrides the table definition's title. */
   title?: string
+  /**
+   * Set when the PAGE already renders its own `PageHeader` and this table is a
+   * panel inside it, so the table renders no heading of its own.
+   *
+   * Declared rather than detected. The shell tracks how many headers are
+   * mounted, but during a route change the outgoing page's header has not
+   * unregistered by the time the incoming table first renders — so a table
+   * reading that count saw a header that was on its way out and silently
+   * dropped its own. Only the page knows this, and it knows it statically.
+   */
+  hideHeader?: boolean
+  /** One line under the title. Overrides the table definition's description. */
+  description?: string
+  /** Docs for the feature, linked after the description. Overrides the table definition's. */
+  docsPath?: string
   /** Default params always sent with every request (e.g., { complete: 1 } for orders) */
   defaultParams?: Record<string, unknown>
   /**
@@ -174,6 +229,16 @@ interface ResourceTableProps<T> {
    * menu on the trailing edge.
    */
   rowActions?: (row: T) => ReactNode
+  /**
+   * Dynamic per-store columns derived from custom field definitions,
+   * merged into the registry columns for display (column selector +
+   * cells), sorting, and filtering. Keys are the definitions'
+   * `filter_key` (`cf_*`), which the backend accepts as sort and
+   * filter attributes.
+   */
+  customFieldColumns?: ColumnDef<T>[]
+  /** @deprecated Use `customFieldColumns` — removed in Spree 6.1. */
+  metafieldColumns?: ColumnDef<T>[]
 }
 
 export interface ReorderConfig<T> {
@@ -192,11 +257,16 @@ export function ResourceTable<T extends Record<string, any>>({
   queryFn,
   searchParams,
   title,
+  hideHeader = false,
+  description,
+  docsPath,
   defaultParams,
   actions,
   reorder,
   bulkActions,
   rowActions,
+  customFieldColumns,
+  metafieldColumns,
 }: ResourceTableProps<T>) {
   const table = getTable<T>(tableKey)
   const { t } = useTranslation()
@@ -207,9 +277,12 @@ export function ResourceTable<T extends Record<string, any>>({
   const selectionEnabled = !!bulkActions?.length && !reorder
   const rowActionsEnabled = !!rowActions
   const [selectedIds, setSelectedIds] = useState<Set<string>>(() => new Set())
-  // Used by +BulkActionBar+ to anchor itself within the table card on
-  // desktop (instead of free-floating at the viewport bottom).
-  const cardRef = useRef<HTMLDivElement | null>(null)
+  // Whether the bulk bar is covering the column labels.
+  const bulkActive = selectionEnabled && selectedIds.size > 0
+  // Only one bulk bar is mounted at a time. Rendering both and hiding one
+  // with `md:` leaves its text in the accessibility tree, so "2 selected"
+  // and every action label match twice.
+  const isMobile = useIsMobile()
 
   const {
     page,
@@ -236,27 +309,69 @@ export function ResourceTable<T extends Record<string, any>>({
   const [searchInput, setSearchInput] = useState(search ?? '')
   const deferredSearch = useDeferredValue(searchInput)
 
-  const displayableColumns = getDisplayableColumns(table)
+  // Registry columns + dynamic custom-field columns. Memoized so the toolbar's
+  // internal memos (FilterPanel `items` stability) keep stable deps.
+  const extraColumns = customFieldColumns ?? metafieldColumns
+  const allColumns = useMemo(
+    () => [...table.columns, ...(extraColumns ?? [])],
+    [table, extraColumns],
+  )
+  const displayableColumns = useMemo(
+    () => allColumns.filter((c) => c.displayable !== false),
+    [allColumns],
+  )
   const defaultColumnKeys = getDefaultColumnKeys(table)
   const visibleColumnKeys = urlColumns ?? defaultColumnKeys
 
-  const visibleColumns = displayableColumns.filter((c) => visibleColumnKeys.includes(c.key))
+  const visibleColumns = useMemo(
+    () => displayableColumns.filter((c) => visibleColumnKeys.includes(c.key)),
+    [displayableColumns, visibleColumnKeys],
+  )
+
+  // Built from every displayable column, not the visible subset: the column
+  // picker is a desktop control (it is hidden on a phone), so the card should
+  // not inherit a selection the merchant cannot see or change there.
+
+  // Expands requested by currently-visible columns (e.g. custom field
+  // columns need `expand=custom_fields` to render their values). Sorted so
+  // the query key stays stable regardless of column order.
+  const columnExpand = useMemo(
+    () => [...new Set(visibleColumns.flatMap((c) => (c.expand ? [c.expand] : [])))].sort(),
+    [visibleColumns],
+  )
 
   // Build API params
   const sortString = dir === 'desc' ? `-${sort}` : sort
 
-  const { storeId } = useStore()
-  // Auto-inject storeId so every list query — and the matching mutation
-  // invalidation — is store-scoped without each page re-implementing it.
+  const tenantId = useTenantId()
+  // Whether the PAGE mounted a header of its own, in which case this table is
+  // a panel inside it and renders no heading.
+  //
+  // Latched from the first render, before this component's own `PageHeader`
+  // can register: the flag counts every mounted header, so reading it live
+  // would see the one rendered below, conclude the page already had one, and
+  // unmount it — which re-clears the flag and mounts it again, forever.
+  const pageOwnsHeader = hideHeader
+  // Auto-inject the tenant id so every list query — and the matching mutation
+  // invalidation — is tenant-scoped without each page re-implementing it.
   // Goes through +withStoreScope+ so the slot ordering matches +useResourceKey+
-  // and +useResourceMutation+'s invalidations (storeId at position 1).
+  // and +useResourceMutation+'s invalidations (tenant id at position 1).
   const userPrefix = Array.isArray(queryKey) ? queryKey : [queryKey]
-  const queryKeyPrefix = withStoreScope(userPrefix, storeId)
+  const queryKeyPrefix = withStoreScope(userPrefix, tenantId)
+
+  // Both bulk bars (desktop overlay, mobile bottom bar) reset through here so
+  // they cannot drift apart.
+  const visualViewportOffset = useVisualViewportOffset(bulkActive)
+
+  const clearSelection = useCallback(() => {
+    setSelectedIds(new Set())
+    queryClient.invalidateQueries({ queryKey: queryKeyPrefix })
+  }, [queryClient, queryKeyPrefix])
 
   const { data, isLoading } = useQuery({
     queryKey: [
       ...queryKeyPrefix,
-      { page, limit, sort: sortString, search: deferredSearch, filters },
+      { page, limit, sort: sortString, search: deferredSearch, filters, expand: columnExpand },
     ],
     queryFn: () => {
       const params: Record<string, unknown> = {
@@ -269,12 +384,22 @@ export function ResourceTable<T extends Record<string, any>>({
         params.limit = limit
       }
 
+      if (columnExpand.length) {
+        const base = defaultParams?.expand
+        const baseList = Array.isArray(base)
+          ? base
+          : typeof base === 'string'
+            ? base.split(',')
+            : []
+        params.expand = [...new Set([...baseList, ...columnExpand])]
+      }
+
       if (deferredSearch) {
         const searchParam = table.searchParam ?? 'name_cont'
         params[searchParam] = deferredSearch
       }
 
-      Object.assign(params, filtersToRansack(filters as FilterRule[], table.columns))
+      Object.assign(params, filtersToRansack(filters as FilterRule[], allColumns))
 
       return queryFn(params)
     },
@@ -409,13 +534,57 @@ export function ResourceTable<T extends Record<string, any>>({
           filters: filters as FilterRule[],
           search: deferredSearch,
           searchParam: table.searchParam ?? 'name_cont',
-          columns: table.columns,
+          columns: allColumns,
           totalCount: meta?.count,
         })
       : actions
 
   return (
-    <Card ref={cardRef} className="rounded-xl">
+    // Below `sm` the table spans the full width: the page gutter plus the
+    // card's own border spends ~34px of a 390px screen on chrome, and a table
+    // is the one place that width is worth reclaiming. Negative margins cancel
+    // The frame belongs to the ROWS, not to the screen. The toolbar sits above
+    // it and the pagination below it, both on the sheet itself — so the border
+    // encloses exactly the tabular data, and the controls that act on it read
+    // as chrome rather than as its first and last rows.
+    //
+    // Below `sm` the table loses its frame and spans the gutter the page
+    // container applies, so narrow screens spend no width on a box.
+    //
+    // No shadow at any width: the sheet under it is already a raised surface,
+    // so the table is a region drawn on it rather than a second card floating
+    // above one. Its hairline is `--border`, the same weight as the rules
+    // between its own rows, so the frame and its contents read as one table.
+    <div className="flex flex-col gap-3">
+      {/* The page's own header, not a title bar of the table's own: a list page
+          IS this table, so its title and actions are the page's. Rendering
+          `PageHeader` here rather than a parallel implementation means a list
+          page and a detail page share one heading — the same type, spacing,
+          sticky behaviour and action slot — and the `page.actions` slot a
+          plugin registers into reaches both.
+
+          Skipped via `hideHeader` when the page already mounts its own
+          `PageHeader` (a table embedded as a panel), which would otherwise
+          give the page two. */}
+      {!pageOwnsHeader && (
+        <PageHeader
+          // Not pinned: on a list page the table's own column row is the band
+          // worth keeping on screen, and stacking a sticky title above it
+          // spends a third of a short viewport on chrome.
+          sticky={false}
+          title={title ?? table.title}
+          description={description ?? table.description}
+          docsPath={docsPath ?? table.docsPath}
+          actions={resolvedActions}
+        />
+      )}
+      {/* A page that owns its header still passes `actions` here, and they
+          would otherwise vanish with the suppressed `PageHeader` — taking the
+          orders export and the policies Add button with them. Render them
+          above the toolbar so the control keeps a home either way. */}
+      {pageOwnsHeader && resolvedActions && (
+        <div className="flex flex-wrap items-center justify-end gap-2">{resolvedActions}</div>
+      )}
       <TableToolbar
         columns={displayableColumns}
         visibleColumns={visibleColumnKeys}
@@ -427,12 +596,15 @@ export function ResourceTable<T extends Record<string, any>>({
         onSortChange={handleSortChange}
         filters={filters as FilterRule[]}
         onFiltersChange={handleFiltersChange}
-        allColumns={table.columns}
-        title={title ?? table.title}
-        actions={resolvedActions}
+        allColumns={allColumns}
         hideSort={reorderActive}
       />
-      <CardContent className="p-0">
+      {/* `overflow-x-clip`, never `overflow-hidden`: the rows clip to the
+          rounded frame horizontally, but a `hidden` overflow on either axis
+          makes this a scroll container, and the pinned column row inside
+          would then stick to THIS box rather than to the page — which is to
+          say, scroll away with it. */}
+      <Card className="-mx-4 gap-0 overflow-x-clip rounded-none border-0 bg-transparent py-0 shadow-none sm:mx-0 sm:rounded-xl sm:border">
         {reorderActive ? (
           <DndContext
             sensors={sensors}
@@ -443,13 +615,13 @@ export function ResourceTable<T extends Record<string, any>>({
               items={rows.map((r) => (r as any).id)}
               strategy={verticalListSortingStrategy}
             >
-              <Table>
+              <Table stickyHeader roundedTop roundedBottom>
                 <TableHeader>
-                  <tr>
+                  <TableHeaderRow>
                     <TableHead className="w-8" />
                     {headerColumns.map((col) => (
                       <TableHead key={col.key} className={col.headerClassName}>
-                        {col.label}
+                        <ColumnLabel column={col} />
                       </TableHead>
                     ))}
                     {rowActionsEnabled && (
@@ -457,13 +629,13 @@ export function ResourceTable<T extends Record<string, any>>({
                         <span className="sr-only">{t('admin.row_actions.menu_label')}</span>
                       </TableHead>
                     )}
-                  </tr>
+                  </TableHeaderRow>
                 </TableHeader>
-                <TableBody>
+                <TableBody className="bg-card">
                   {isLoading ? (
-                    <TableEmpty colSpan={visibleColumns.length + 1 + (rowActionsEnabled ? 1 : 0)}>
-                      {t('admin.common.loading')}
-                    </TableEmpty>
+                    <TableSkeletonRows
+                      colSpan={visibleColumns.length + 1 + (rowActionsEnabled ? 1 : 0)}
+                    />
                   ) : rows.length === 0 ? (
                     <TableEmpty colSpan={visibleColumns.length + 1 + (rowActionsEnabled ? 1 : 0)}>
                       <Empty className="border-0 p-0">
@@ -497,112 +669,234 @@ export function ResourceTable<T extends Record<string, any>>({
             </SortableContext>
           </DndContext>
         ) : (
-          <Table>
-            <TableHeader>
-              <tr>
-                {selectionEnabled && (
-                  <TableHead className="w-8">
+          <>
+            {/* The bulk actions overlay the header row but live OUTSIDE the
+                table's horizontal scroller: out there their width is the
+                visible card rather than the table's full scroll width, so the
+                overflow-into-⋯ budget is right and the controls hold still
+                while the columns scroll sideways. A zero-height wrapper with
+                the same sticky offset as the pinned header keeps the two
+                travelling together; the start padding clears the select-all
+                checkbox, which stays visible and interactive underneath. */}
+            {bulkActive && !isMobile && (
+              // `pointer-events-none` on the overlay, re-enabled only on the
+              // bar itself: the start-padding gutter is part of this div and
+              // would otherwise swallow every click aimed at the select-all
+              // checkbox sitting beneath it — checking once, then never
+              // unchecking.
+              <div className="pointer-events-none sticky top-header-height z-30 h-0">
+                <div className="flex h-[2.1875rem] items-center ps-10 pe-4">
+                  <div className="pointer-events-auto min-w-0 flex-1">
+                    <BulkActionBar
+                      selectedIds={Array.from(selectedIds)}
+                      actions={bulkActions!}
+                      onDone={clearSelection}
+                    />
+                  </div>
+                </div>
+              </div>
+            )}
+
+            {/* On a phone the header-row overlay is the wrong home for this: it
+                scrolls sideways with a wide table and sits at the top, far from
+                the thumb. A fixed bottom bar stays put and in reach while the
+                merchant scrolls the list picking rows. */}
+            {bulkActive &&
+              isMobile &&
+              // Portalled to `document.body`: `SidebarInset` is `relative z-0`,
+              // which opens a stacking context, and a `fixed` child of it can
+              // only stack against its siblings there — page content painted
+              // later covered the bar until the merchant scrolled past it.
+              createPortal(
+                <section
+                  className="fixed inset-x-0 z-50 border-t border-border bg-card px-4 py-3 pb-[max(0.75rem,env(safe-area-inset-bottom))] shadow-lg"
+                  // `bottom` anchors to the *layout* viewport. Pinch-zoom (and
+                  // a mobile URL bar) makes the visual viewport a smaller
+                  // window onto it, leaving the bar off-screen until the
+                  // merchant pans down — the offset lifts it back into view.
+                  style={{ bottom: visualViewportOffset }}
+                  aria-label={t('admin.a11y.bulk_actions')}
+                >
+                  <div className="flex items-center gap-3">
                     <Checkbox
                       checked={allPageSelected}
                       indeterminate={somePageSelected}
                       onCheckedChange={togglePage}
                       aria-label={t('admin.a11y.select_all_rows')}
                     />
-                  </TableHead>
-                )}
-                {headerColumns.map((col) => (
-                  <TableHead key={col.key} className={col.headerClassName}>
-                    {col.label}
-                  </TableHead>
-                ))}
-                {rowActionsEnabled && (
-                  <TableHead className="w-12">
-                    <span className="sr-only">{t('admin.row_actions.menu_label')}</span>
-                  </TableHead>
-                )}
-              </tr>
-            </TableHeader>
-            <TableBody>
-              {isLoading ? (
-                <TableEmpty
-                  colSpan={
-                    visibleColumns.length + (selectionEnabled ? 1 : 0) + (rowActionsEnabled ? 1 : 0)
-                  }
-                >
-                  {t('admin.common.loading')}
-                </TableEmpty>
-              ) : rows.length === 0 ? (
-                <TableEmpty
-                  colSpan={
-                    visibleColumns.length + (selectionEnabled ? 1 : 0) + (rowActionsEnabled ? 1 : 0)
-                  }
-                >
-                  <Empty className="border-0 p-0">
-                    <EmptyHeader>
-                      {table.emptyIcon && <EmptyMedia variant="icon">{table.emptyIcon}</EmptyMedia>}
-                      <EmptyTitle>{table.emptyMessage ?? t('admin.common.no_results')}</EmptyTitle>
-                      {(deferredSearch || (filters as FilterRule[]).length > 0) && (
-                        <EmptyDescription>
-                          {t('admin.common.adjust_search_or_filters')}
-                        </EmptyDescription>
+                    <div className="min-w-0 flex-1">
+                      <BulkActionBar
+                        selectedIds={Array.from(selectedIds)}
+                        actions={bulkActions!}
+                        onDone={clearSelection}
+                      />
+                    </div>
+                  </div>
+                </section>,
+                document.body,
+              )}
+            <Table stickyHeader roundedTop roundedBottom>
+              <TableHeader>
+                {/* Column headers stay mounted with rows selected, and the bulk
+                    bar is laid over them. Swapping them for one `colSpan` cell
+                    instead would drop the width constraints they impose on an
+                    auto-layout table, and every column would resize the moment a
+                    row was ticked. `bulkActive` only hides the labels. */}
+                <TableHeaderRow>
+                  {selectionEnabled && (
+                    <TableHead className="w-8">
+                      <Checkbox
+                        checked={allPageSelected}
+                        indeterminate={somePageSelected}
+                        onCheckedChange={togglePage}
+                        aria-label={t('admin.a11y.select_all_rows')}
+                      />
+                    </TableHead>
+                  )}
+                  {headerColumns.map((col) => (
+                    <TableHead
+                      key={col.key}
+                      className={cn(
+                        col.headerClassName,
+                        'transition-colors duration-150 ease-out',
+                        // Hide the text, not the cell: `opacity-0` would erase
+                        // the cell's muted background and bottom rule too,
+                        // leaving rows visible through the band behind the
+                        // bulk actions overlay. Only where that overlay is
+                        // drawn — on a phone the bar is at the foot of the
+                        // screen and the column labels stay readable.
+                        bulkActive && !isMobile && 'text-transparent select-none',
                       )}
-                    </EmptyHeader>
-                  </Empty>
-                </TableEmpty>
-              ) : (
-                rows.map((row, i) => {
-                  const rowId = String((row as any).id ?? i)
-                  const isSelected = selectionEnabled && selectedIds.has(rowId)
-                  return (
-                    <TableRow
-                      key={(row as any).id ?? i}
-                      className={isSelected ? 'bg-muted/40' : undefined}
                     >
-                      {selectionEnabled && (
-                        <TableCell className="w-8">
-                          <Checkbox
-                            checked={isSelected}
-                            onCheckedChange={() => toggleRow(rowId)}
-                            aria-label={t('admin.a11y.select_row')}
-                          />
-                        </TableCell>
-                      )}
-                      {visibleColumns.map((col) => (
-                        <TableCell key={col.key} className={col.className}>
-                          {col.render ? col.render(row) : String((row as any)[col.key] ?? '—')}
-                        </TableCell>
-                      ))}
-                      {rowActionsEnabled && (
-                        <TableCell className="w-12 text-right">{rowActions?.(row)}</TableCell>
-                      )}
-                    </TableRow>
-                  )
-                })
-              )}
-            </TableBody>
-          </Table>
-        )}
-        {meta && (
-          <Pagination
-            meta={meta}
-            onPageChange={(p) => updateSearch({ page: p })}
-            onPageSizeChange={(size) => updateSearch({ limit: size, page: 1 })}
-          />
-        )}
-        {selectionEnabled && (
-          <BulkActionBar
-            selectedIds={Array.from(selectedIds)}
-            actions={bulkActions!}
-            anchorRef={cardRef}
-            onClear={() => setSelectedIds(new Set())}
-            onDone={() => {
-              setSelectedIds(new Set())
-              queryClient.invalidateQueries({ queryKey: queryKeyPrefix })
-            }}
-          />
+                      {/* The hint hides with the label: an info icon floating
+                          over the bulk-actions band would be the only thing
+                          left in the row. */}
+                      <ColumnLabel column={col} hideHint={bulkActive && !isMobile} />
+                    </TableHead>
+                  ))}
+                  {rowActionsEnabled && (
+                    <TableHead className="w-12">
+                      <span className="sr-only">{t('admin.row_actions.menu_label')}</span>
+                    </TableHead>
+                  )}
+                </TableHeaderRow>
+              </TableHeader>
+              <TableBody className="bg-card">
+                {isLoading ? (
+                  <TableSkeletonRows
+                    colSpan={
+                      visibleColumns.length +
+                      (selectionEnabled ? 1 : 0) +
+                      (rowActionsEnabled ? 1 : 0)
+                    }
+                  />
+                ) : rows.length === 0 ? (
+                  <TableEmpty
+                    colSpan={
+                      visibleColumns.length +
+                      (selectionEnabled ? 1 : 0) +
+                      (rowActionsEnabled ? 1 : 0)
+                    }
+                  >
+                    <Empty className="border-0 p-0">
+                      <EmptyHeader>
+                        {table.emptyIcon && (
+                          <EmptyMedia variant="icon">{table.emptyIcon}</EmptyMedia>
+                        )}
+                        <EmptyTitle>
+                          {table.emptyMessage ?? t('admin.common.no_results')}
+                        </EmptyTitle>
+                        {(deferredSearch || (filters as FilterRule[]).length > 0) && (
+                          <EmptyDescription>
+                            {t('admin.common.adjust_search_or_filters')}
+                          </EmptyDescription>
+                        )}
+                      </EmptyHeader>
+                    </Empty>
+                  </TableEmpty>
+                ) : (
+                  rows.map((row, i) => {
+                    const rowId = String((row as any).id ?? i)
+                    const isSelected = selectionEnabled && selectedIds.has(rowId)
+                    return (
+                      <TableRow
+                        key={(row as any).id ?? i}
+                        // Selected rows carry the hover tint so the selection is
+                        // visible at rest; hovering one goes a step deeper so the
+                        // row still answers the pointer.
+                        //
+                        // A row holding an open popover is shaded the same way:
+                        // the panel floats over its neighbours, and without this
+                        // a merchant editing a figure has to count rows to see
+                        // which record they are editing.
+                        className={cn(
+                          'has-data-[popup-open]:bg-accent-strong/40',
+                          isSelected && 'bg-accent-strong/75 hover:bg-accent-strong-hover',
+                        )}
+                      >
+                        {selectionEnabled && (
+                          <TableCell className="w-8">
+                            <Checkbox
+                              checked={isSelected}
+                              onCheckedChange={() => toggleRow(rowId)}
+                              aria-label={t('admin.a11y.select_row')}
+                            />
+                          </TableCell>
+                        )}
+                        {visibleColumns.map((col) => (
+                          <TableCell key={col.key} className={col.className}>
+                            {col.render ? col.render(row) : String((row as any)[col.key] ?? '—')}
+                          </TableCell>
+                        ))}
+                        {rowActionsEnabled && (
+                          <TableCell className="w-12 text-right">{rowActions?.(row)}</TableCell>
+                        )}
+                      </TableRow>
+                    )
+                  })
+                )}
+              </TableBody>
+            </Table>
+          </>
         )}
-      </CardContent>
-    </Card>
+      </Card>
+      {meta && (
+        <Pagination
+          meta={meta}
+          onPageChange={(p) => updateSearch({ page: p })}
+          onPageSizeChange={(size) => updateSearch({ limit: size, page: 1 })}
+        />
+      )}
+      {/* Clears the fixed bottom bar so it can't cover the pagination or the
+          last row while a selection is active. Carries the same safe-area
+          inset the bar pads itself by, or the home indicator's worth of bar
+          still overlaps the last row. Sits after the pagination, which is now
+          the last thing the bar can cover. */}
+      {bulkActive && isMobile && (
+        <div className="h-[calc(4rem+max(0px,env(safe-area-inset-bottom)-0.75rem))]" aria-hidden />
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// TableSkeletonRows — placeholder rows while the first page loads. Rows rather
+// than a "Loading…" line so the table keeps its height and the page doesn't
+// jump when data lands.
+// ============================================================================
+
+function TableSkeletonRows({ colSpan, rows = 8 }: { colSpan: number; rows?: number }) {
+  return (
+    <>
+      {Array.from({ length: rows }, (_, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: fixed-length placeholder list
+        <tr key={i} className="last:*:border-b-0">
+          <TableCell colSpan={colSpan}>
+            <Skeleton className="h-5 w-full" />
+          </TableCell>
+        </tr>
+      ))}
+    </>
   )
 }
 
@@ -634,7 +928,7 @@ function SortableRow<T extends Record<string, any>>({
       ref={setNodeRef}
       style={style}
       className={cn(
-        'group/row hover:bg-muted/60 last:*:border-b-0',
+        'group/row hover:bg-accent-strong/50 last:*:border-b-0',
         isDragging && 'relative z-10 opacity-70',
       )}
     >