@freighttech/ui 0.13.18

package/src/backend/dynamic-table/__tests__/DynamicTable.density.test.tsx

@@ -0,0 +1,299 @@
+/**
+ * @jest-environment jsdom
+ *
+ * DENSITY + COLUMN-VIRTUALIZATION WIRING, asserted on the real grid.
+ *
+ * Two capabilities were built in an earlier wave and reached no render path.
+ * The unit tests for both are green and prove nothing about whether a user can
+ * see them, which is the only question that matters here.
+ *
+ * The load-bearing assertions:
+ *
+ *  • DEFAULT IS A NO-OP. The product owner has repeatedly flagged FMS tables as
+ *    "fonts too small", so a density feature that quietly shrinks anything for
+ *    somebody who never opened the picker is a regression, not a feature.
+ *    `comfortable` must render at exactly today's row height.
+ *
+ *  • DENSITY IS PER USER. Workshop item A3 is a recorded incident of one person
+ *    changing a shared default for a whole organisation by accident. The switch
+ *    must never travel through a perspective or any server-held object.
+ *
+ *  • THE DENSITY GUARDRAIL CANNOT INVERT. `data-dt-columns` declares how many
+ *    columns EXIST. Without it the perf harness counts mounted `<th>`s, so a
+ *    successful virtualization reads as "the change lost 36 columns" — the one
+ *    outcome the product owner explicitly forbade.
+ */
+
+import * as React from 'react'
+import { render, fireEvent, act } from '@testing-library/react'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import DynamicTable from '../DynamicTable'
+import {
+  DENSITY_ATTRIBUTE,
+  DENSITY_METRICS,
+  DENSITY_STORAGE_PREFIX,
+} from '../index'
+import { resetDensityPreferenceStore } from '../hooks/useDensityPreference'
+import { apiCall } from '@freighttech/ui/backend/utils/apiCall'
+import type { ColumnDef } from '../types/index'
+
+jest.mock('@freighttech/ui/backend/utils/apiCall', () => ({
+  apiCall: jest.fn(),
+}))
+const mockApiCall = apiCall as unknown as jest.Mock
+
+const columns: ColumnDef[] = Array.from({ length: 12 }, (_, i) => ({
+  data: `c${i}`,
+  title: `Col ${i}`,
+  width: 120,
+}))
+
+const makeRows = () =>
+  Array.from({ length: 5 }, (_, r) => {
+    const row: Record<string, unknown> = { id: `r${r}` }
+    for (let c = 0; c < 12; c++) row[`c${c}`] = `v${r}-${c}`
+    return row
+  })
+
+function Harness(props: Record<string, unknown>) {
+  const tableRef = React.useRef<HTMLDivElement | null>(null)
+  const [data] = React.useState(makeRows)
+  return React.createElement(
+    I18nProvider as any,
+    { locale: 'en', dict: {} },
+    React.createElement(DynamicTable as any, {
+      data,
+      columns,
+      tableRef,
+      height: 400,
+      ...props,
+    }),
+  )
+}
+const harness = (props: Record<string, unknown> = {}) => React.createElement(Harness, props)
+
+// jsdom gives every box a 0×0 rect, so the ROW virtualiser mounts nothing.
+// Same stub the other mount tests use.
+beforeAll(() => {
+  const rect = {
+    width: 1200, height: 600, top: 0, left: 0, right: 1200, bottom: 600, x: 0, y: 0,
+    toJSON() {},
+  }
+  Object.defineProperty(HTMLElement.prototype, 'getBoundingClientRect', {
+    configurable: true,
+    value: () => rect,
+  })
+  for (const [prop, value] of [
+    ['clientHeight', 600],
+    ['offsetHeight', 600],
+    ['clientWidth', 1200],
+    ['offsetWidth', 1200],
+  ] as const) {
+    Object.defineProperty(HTMLElement.prototype, prop, { configurable: true, get: () => value })
+  }
+})
+
+beforeEach(() => {
+  window.localStorage.clear()
+  resetDensityPreferenceStore()
+  mockApiCall.mockReset()
+  mockApiCall.mockResolvedValue({ ok: false })
+})
+
+const container = () => document.querySelector('.hot-container') as HTMLElement
+const scroller = () => document.querySelector('.hot-virtual-container') as HTMLElement
+const firstRowHeight = () => {
+  const tr = document.querySelector('tbody tr[data-row]') as HTMLElement
+  return tr?.style.height
+}
+
+describe('density — mounted in the grid', () => {
+  it('carries the density attribute on the grid container, so ONE switch restyles everything', () => {
+    render(harness())
+    expect(container().getAttribute(DENSITY_ATTRIBUTE)).toBe('comfortable')
+  })
+
+  it('defaults to comfortable and renders at TODAY\'S row height — opting out is a no-op', () => {
+    render(harness())
+    expect(firstRowHeight()).toBe(`${DENSITY_METRICS.comfortable.rowHeight}px`)
+    expect(firstRowHeight()).toBe('32px')
+  })
+
+
+/**
+ * Density now lives inside the toolbar's overflow menu, as a SEGMENTED control
+ * rather than a listbox trigger: Export, row height and fullscreen are
+ * secondary controls that no longer each spend permanent toolbar width (see
+ * `ToolbarOverflow`).
+ *
+ * These tests assert the same behaviour as before — the level applies, the
+ * grid re-measures, the choice persists under a user-scoped key. Only the
+ * route to the control changed, so they open the overflow rather than dropping
+ * an assertion.
+ */
+function openDensityControls(): void {
+  const overflow = document.querySelector('[data-toolbar-overflow]') as HTMLElement | null
+  if (overflow && !document.querySelector('[data-toolbar-overflow-menu]')) {
+    act(() => { fireEvent.click(overflow) })
+  }
+}
+
+function densityOption(level: 'comfortable' | 'compact' | 'dense'): HTMLElement {
+  openDensityControls()
+  return document.querySelector(`[data-density-option="${level}"]`) as HTMLElement
+}
+
+  it('shows the density picker in the toolbar, naming the current level for screen readers', () => {
+    render(harness())
+    // The segmented control marks the current level with `aria-pressed`, which
+    // is what a screen reader announces now that there is no collapsed trigger
+    // carrying the level in its label.
+    const current = densityOption('comfortable')
+    expect(current).not.toBeNull()
+    expect(current.getAttribute('aria-pressed')).toBe('true')
+    expect(densityOption('dense').getAttribute('aria-pressed')).toBe('false')
+  })
+
+  it('lets the user pick a tighter level, and the whole grid restyles + re-measures', () => {
+    render(harness())
+    const dense = densityOption('dense')
+    expect(dense).not.toBeNull()
+    act(() => { fireEvent.click(dense) })
+
+    expect(container().getAttribute(DENSITY_ATTRIBUTE)).toBe('dense')
+    // Row height is the ONE number CSS cannot own — rows are absolutely
+    // positioned by the virtualiser, so JS has to know it.
+    expect(firstRowHeight()).toBe(`${DENSITY_METRICS.dense.rowHeight}px`)
+  })
+
+  it('persists the choice under a USER-scoped key and never through a perspective', () => {
+    render(harness())
+    const compact = densityOption('compact')
+    act(() => { fireEvent.click(compact) })
+
+    const keys = Object.keys(window.localStorage)
+    expect(keys.some((k) => k.startsWith(DENSITY_STORAGE_PREFIX))).toBe(true)
+    // The A3 guarantee: nothing organisation-shaped in the key, and no request
+    // was made to persist it anywhere a second user could read.
+    expect(mockApiCall).not.toHaveBeenCalledWith(
+      expect.stringContaining('/api/perspectives'),
+      expect.anything(),
+    )
+  })
+
+  it('honours a developer override without persisting it as the user\'s setting', () => {
+    render(harness({ uiConfig: { densityLevel: 'compact' } }))
+    expect(container().getAttribute(DENSITY_ATTRIBUTE)).toBe('compact')
+    expect(firstRowHeight()).toBe(`${DENSITY_METRICS.compact.rowHeight}px`)
+    expect(
+      Object.keys(window.localStorage).some((k) => k.startsWith(DENSITY_STORAGE_PREFIX)),
+    ).toBe(false)
+  })
+
+  it('can be hidden per table without pinning the level', () => {
+    render(harness({ uiConfig: { hideDensityControl: true } }))
+    expect(
+      document.querySelector('button[aria-haspopup="listbox"][aria-label*="density"]'),
+    ).toBeNull()
+    expect(container().getAttribute(DENSITY_ATTRIBUTE)).toBe('comfortable')
+  })
+
+  it('leaves the LEGACY developer density prop alone — the two attributes are different axes', () => {
+    render(harness({ density: 'md' }))
+    // `data-density` is what DynamicTable.v2.css keys `:not([data-density])` on;
+    // reusing it for the user preference would silently switch those rules off.
+    expect(container().getAttribute('data-density')).toBe('md')
+    expect(container().getAttribute(DENSITY_ATTRIBUTE)).toBe('comfortable')
+    expect(firstRowHeight()).toBe('44px')
+  })
+})
+
+describe('column virtualization — the guardrail and the default', () => {
+  it('declares how many columns EXIST, so a virtualization win cannot read as a column loss', () => {
+    render(harness())
+    expect(scroller().getAttribute('data-dt-columns')).toBe('12')
+    expect(scroller().getAttribute('data-dt-rows')).toBe('5')
+  })
+
+  it('reports the full column count to assistive tech, never the mounted subset', () => {
+    render(harness())
+    // 12 data columns; no row header, no actions column on this table.
+    expect(Number(scroller().getAttribute('aria-colcount'))).toBe(12)
+  })
+
+  it('counts the row-header gutter in aria-colcount when there is one', () => {
+    render(harness({ rowHeaders: true }))
+    expect(Number(scroller().getAttribute('aria-colcount'))).toBe(13)
+  })
+
+  it('is OFF by default — every column is mounted, exactly as before', () => {
+    render(harness())
+    const cells = document.querySelectorAll(
+      'tbody tr[data-row]:first-child td.hot-cell[data-col]:not(.hot-actions-cell)',
+    )
+    expect(cells).toHaveLength(12)
+    expect(document.querySelectorAll('.hot-cell-spacer')).toHaveLength(0)
+    expect(scroller().getAttribute('data-column-virtualized')).toBeNull()
+  })
+
+  it('with the flag ON but nothing measured, FAILS OPEN — never an empty grid', () => {
+    // jsdom has no layout and a stubbed ResizeObserver, so the virtualizer
+    // cannot measure. Correct-but-slow is the only acceptable failure
+    // direction: the alternative paints a table with no cells in it.
+    render(harness({ uiConfig: { enableColumnVirtualization: true } }))
+    const cells = document.querySelectorAll(
+      'tbody tr[data-row]:first-child td.hot-cell[data-col]:not(.hot-actions-cell)',
+    )
+    expect(cells).toHaveLength(12)
+    expect(document.querySelectorAll('.hot-cell-spacer')).toHaveLength(0)
+    expect(scroller().getAttribute('data-dt-columns')).toBe('12')
+  })
+
+  it('publishes the mounted window so a test can ask the MODEL, not the DOM', () => {
+    render(harness({ uiConfig: { enableColumnVirtualization: true } }))
+    expect(scroller().getAttribute('data-column-window')).toBe('0:11')
+  })
+})
+
+describe('scroll-into-view — rule 9 of the range-operation contract', () => {
+  let scrollTo: jest.SpyInstance
+
+  beforeEach(() => {
+    scrollTo = jest.spyOn(Element.prototype, 'scrollTo').mockImplementation(() => {})
+  })
+  afterEach(() => {
+    scrollTo.mockRestore()
+  })
+
+  // 12 columns × 120px = 1440px of columns in a 1200px viewport, so the last
+  // column genuinely does not fit and moving onto it MUST scroll.
+  const selectColumn = (colIndex: number) => {
+    const cell = document.querySelector(
+      `tbody tr[data-row="0"] td.hot-cell[data-col="${colIndex}"]`,
+    ) as HTMLElement
+    expect(cell).not.toBeNull()
+    act(() => { fireEvent.mouseDown(cell) })
+  }
+
+  it('scrolls a column that does not fit into view when the caret lands on it', () => {
+    render(harness({ uiConfig: { enableColumnVirtualization: true } }))
+    selectColumn(11)
+    expect(scrollTo).toHaveBeenCalled()
+    const arg = scrollTo.mock.calls.at(-1)![0] as { left: number }
+    expect(arg.left).toBeGreaterThan(0)
+  })
+
+  it('does NOT scroll for a column that is already fully visible', () => {
+    render(harness({ uiConfig: { enableColumnVirtualization: true } }))
+    scrollTo.mockClear()
+    selectColumn(0)
+    expect(scrollTo).not.toHaveBeenCalled()
+  })
+
+  it('leaves scrolling behaviour completely untouched when the flag is off', () => {
+    render(harness())
+    scrollTo.mockClear()
+    selectColumn(11)
+    expect(scrollTo).not.toHaveBeenCalled()
+  })
+})

package/src/backend/dynamic-table/__tests__/DynamicTable.exportTruncation.test.tsx

@@ -0,0 +1,145 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import DynamicTable from '../DynamicTable'
+import { downloadBlob } from '../utils/exportTable'
+import { flash } from '../../FlashMessages'
+import type { ColumnDef, ExportAllResult } from '../types/index'
+
+/**
+ * HEDGE-123 — the half of the fix the hook cannot enforce: NO FILE IS WRITTEN.
+ *
+ * `exportAllRows` rejecting is only useful if the caller refuses to hand over a
+ * download. These tests assert the thing the user actually experiences — an
+ * error instead of a file — by watching `downloadBlob`, which is the single
+ * point where a file reaches the browser.
+ *
+ * The distinction matters because a short CSV is worse than a failed one. A
+ * failure is visible and can be retried; a file that opens, has headers and has
+ * rows looks like an answer and goes into a reconciliation unquestioned.
+ */
+
+jest.mock('../utils/exportTable', () => {
+  const actual = jest.requireActual('../utils/exportTable')
+  return { ...actual, downloadBlob: jest.fn() }
+})
+jest.mock('../../FlashMessages', () => ({ flash: jest.fn() }))
+
+const columns: ColumnDef[] = [
+  { data: 'invoiceNumber', title: 'Invoice' },
+  { data: 'grossAmount', title: 'Gross' },
+]
+
+const rows = [
+  { id: '1', invoiceNumber: 'FV/2026/001', grossAmount: '1230.00' },
+  { id: '2', invoiceNumber: 'FV/2026/002', grossAmount: '984.00' },
+]
+
+function renderTable(onExportAll: (() => Promise<any[] | ExportAllResult>) | undefined) {
+  function Harness() {
+    const tableRef = React.useRef<HTMLDivElement | null>(null)
+    return React.createElement(
+      I18nProvider as any,
+      { locale: 'en', dict: {} },
+      React.createElement(DynamicTable as any, {
+        data: rows,
+        columns,
+        tableRef,
+        tableName: 'Invoices',
+        height: 400,
+        onExportAll,
+      }),
+    )
+  }
+  return render(React.createElement(Harness))
+}
+
+/**
+ * Drive the export the way a user does. jsdom reports every box as 0x0, so the
+ * toolbar always collapses its actions into the "More" overflow — the same menu
+ * a narrow real window produces. Open that, then pick CSV.
+ */
+async function clickExportCsv() {
+  fireEvent.click(await screen.findByRole('button', { name: /more table actions/i }))
+  fireEvent.click(document.querySelector('[data-toolbar-export]') as HTMLElement)
+  fireEvent.click(document.querySelector('[data-toolbar-export-format="csv"]') as HTMLElement)
+}
+
+function flashCalls(): string[] {
+  return (flash as jest.Mock).mock.calls.map((c) => String(c[0]))
+}
+
+describe('DynamicTable export — a failed walk yields an error, not a file (HEDGE-123)', () => {
+  beforeEach(() => jest.clearAllMocks())
+
+  it('writes NO file when the export fetch rejects', async () => {
+    renderTable(async () => {
+      throw new Error('Export failed on page 3 (HTTP 500) after 200 row(s)')
+    })
+    await clickExportCsv()
+
+    await waitFor(() => expect(flash as jest.Mock).toHaveBeenCalled())
+    // The assertion that matters: nothing reached the browser.
+    expect(downloadBlob as jest.Mock).not.toHaveBeenCalled()
+  })
+
+  it('surfaces WHY it failed, not a bare "Could not export"', async () => {
+    renderTable(async () => {
+      throw new Error('Export failed on page 3 (HTTP 500) after 200 row(s)')
+    })
+    await clickExportCsv()
+
+    await waitFor(() => expect(flash as jest.Mock).toHaveBeenCalled())
+    // A user could not previously tell a filter problem from a server problem.
+    expect(flashCalls().join(' ')).toMatch(/page 3/)
+    expect((flash as jest.Mock).mock.calls.some((c) => c[1] === 'error')).toBe(true)
+  })
+
+  it('writes NO file when the walk could not be proven complete', async () => {
+    renderTable(async () => ({
+      rows: [{ id: '1', invoiceNumber: 'FV/2026/001', grossAmount: '1230.00' }],
+      expected: 500,
+      complete: false,
+      reason: 'fetched 300 of 500 row(s)',
+    }))
+    await clickExportCsv()
+
+    await waitFor(() => expect(flash as jest.Mock).toHaveBeenCalled())
+    expect(downloadBlob as jest.Mock).not.toHaveBeenCalled()
+  })
+
+  it('tells the user BOTH counts when it refuses an incomplete export', async () => {
+    renderTable(async () => ({
+      rows: [{ id: '1', invoiceNumber: 'FV/2026/001', grossAmount: '1230.00' }],
+      expected: 500,
+      complete: false,
+      reason: 'fetched 300 of 500 row(s)',
+    }))
+    await clickExportCsv()
+
+    await waitFor(() => expect(flash as jest.Mock).toHaveBeenCalled())
+    const said = flashCalls().join(' ')
+    expect(said).toMatch(/300 of 500/)
+    // And it must say the file was not saved, so nobody goes looking for one.
+    expect(said).toMatch(/not saved|NOT saved/i)
+  })
+
+  it('DOES write the file when the walk completed — the honest path still works', async () => {
+    renderTable(async () => ({ rows, expected: rows.length, complete: true }))
+    await clickExportCsv()
+
+    await waitFor(() => expect(downloadBlob as jest.Mock).toHaveBeenCalled())
+  })
+
+  it('still accepts a bare array as complete, for hosts predating the counts', async () => {
+    // Backwards compatibility is load-bearing: `onExportAll` is a public prop.
+    renderTable(async () => rows)
+    await clickExportCsv()
+
+    await waitFor(() => expect(downloadBlob as jest.Mock).toHaveBeenCalled())
+  })
+})

package/src/backend/dynamic-table/__tests__/DynamicTable.loadError.test.tsx

@@ -0,0 +1,173 @@
+import * as React from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import DynamicTable from '../DynamicTable'
+import type { ColumnDef } from '../types/index'
+
+/**
+ * HEDGE-119 — the WIRING, which is where the defect actually lived.
+ *
+ * `LoadErrorState` existing is not the fix; the fix is that the zero-row branch
+ * consults something other than the row count. Both situations arrive at that
+ * branch as `data: []`:
+ *
+ *   - the server said "zero rows"      → EmptyState, correctly
+ *   - the request failed               → LoadErrorState
+ *
+ * Before this, `rowCount === 0` was the ONLY condition and the second case got
+ * the first case's UI — an Inbox icon and "Nothing here yet" — which is how a
+ * 500 on `/api/invoicing/invoices` reached an accountant as "no invoices".
+ *
+ * So the pair of tests below is the point: same empty `data`, two different
+ * screens, decided by `loadError`.
+ */
+
+const columns: ColumnDef[] = [
+  { data: 'invoiceNumber', title: 'Invoice' },
+  { data: 'grossAmount', title: 'Gross', type: 'numeric' },
+]
+
+function renderTable(props: Record<string, unknown> = {}) {
+  function Harness() {
+    const tableRef = React.useRef<HTMLDivElement | null>(null)
+    return React.createElement(
+      I18nProvider as any,
+      { locale: 'en', dict: {} },
+      React.createElement(DynamicTable as any, {
+        data: [],
+        columns,
+        tableRef,
+        tableName: 'Invoices',
+        height: 400,
+        ...props,
+      }),
+    )
+  }
+  return render(React.createElement(Harness))
+}
+
+describe('DynamicTable — failed load vs empty table (HEDGE-119)', () => {
+  it('renders the EMPTY state when the server truthfully returned zero rows', () => {
+    renderTable({ loadError: false })
+    expect(screen.getByRole('status')).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+    expect(screen.queryByText(/could not load/i)).not.toBeInTheDocument()
+  })
+
+  it('renders the ERROR state when the list request failed, on identical empty data', () => {
+    renderTable({ loadError: true })
+    expect(screen.getByRole('alert')).toBeInTheDocument()
+    expect(screen.getByText(/could not load/i)).toBeInTheDocument()
+    // The regression, stated literally: this must not say the table is empty.
+    expect(screen.queryByText(/nothing here yet/i)).not.toBeInTheDocument()
+  })
+
+  it('names the failing table so the user knows WHAT did not load', () => {
+    renderTable({ loadError: true, tableName: 'Invoices' })
+    // Scoped to the alert: "Invoices" also appears in the toolbar heading.
+    expect(screen.getByText(/Could not load Invoices/i)).toBeInTheDocument()
+  })
+
+  it('does not blame the search box for a server failure', () => {
+    // A search is live AND the request failed. Attributing the empty grid to
+    // the search would send the user to clear a filter that is not the cause.
+    renderTable({ loadError: true, searchQuery: 'FV/2026' })
+    expect(screen.getByRole('alert')).toBeInTheDocument()
+    expect(screen.queryByText(/Nothing matches/i)).not.toBeInTheDocument()
+  })
+
+  it('still shows the search diagnosis when the request SUCCEEDED and matched nothing', () => {
+    // The counterpart: fixing the error case must not break the case that
+    // EmptyState already got right.
+    renderTable({ loadError: false, searchQuery: 'FV/2026' })
+    expect(screen.getByText(/Nothing matches/i)).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('defaults to the empty state when a host passes no error flag at all', () => {
+    // All 24 existing `useDynamicTablePage` hosts pass nothing; none may change
+    // behaviour because this prop was added.
+    renderTable()
+    expect(screen.getByRole('status')).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+})
+
+/**
+ * HEDGE-165 — the half HEDGE-119 left open: a failed load that STILL HAS ROWS.
+ *
+ * Every case above renders `data: []`, which is exactly why the gap survived
+ * review: `LoadErrorState` is gated on `rowCount === 0`, so `loadError === true`
+ * with rows on screen rendered nothing at all and no test noticed.
+ *
+ * That is the durable case, not the rare one. `placeholderData` in
+ * `useDynamicTablePage` deliberately keeps the previous response's rows, and
+ * TanStack keeps `data` when a query that already holds data transitions to
+ * `error` — so a failed post-save invalidation, a failed refetch-on-focus, or a
+ * failed search inside its retry window all land here: correct-looking rows
+ * answering a request that never succeeded.
+ *
+ * The rows must stay. Only the signal is asserted below.
+ */
+const rows = [
+  { invoiceNumber: 'FV/2026/01', grossAmount: 1230 },
+  { invoiceNumber: 'FV/2026/02', grossAmount: 4560 },
+]
+
+/**
+ * How many rows the grid is HOLDING, not how many cells jsdom painted.
+ *
+ * The row virtualiser measures a scroller that has no layout in jsdom, so it
+ * mounts a window of zero and the tbody comes out empty however many rows were
+ * passed. `data-dt-rows` is the density guardrail the perf harness reads — it
+ * is `data.length` by construction and never the mounted subset — which makes
+ * it the only honest way to assert "the rows are still there" in this
+ * environment. Asserting on cell text here would fail for reasons that have
+ * nothing to do with this defect.
+ */
+function heldRowCount(): string | null {
+  return document.querySelector('[data-dt-rows]')?.getAttribute('data-dt-rows') ?? null
+}
+
+describe('DynamicTable — failed load with rows still on screen (HEDGE-165)', () => {
+  it('warns that the visible rows are the PREVIOUS result when a refetch failed', () => {
+    renderTable({ loadError: true, data: rows })
+    const bar = document.querySelector('[data-stale-data]')
+    expect(bar).not.toBeNull()
+    expect(bar).toHaveTextContent(/previous result/i)
+    // The rows are the point of keeping them — the bar must not replace them.
+    expect(heldRowCount()).toBe('2')
+    // Neither zero-row state applies: there are rows.
+    expect(screen.queryByText(/could not load/i)).not.toBeInTheDocument()
+    expect(screen.queryByText(/nothing here yet/i)).not.toBeInTheDocument()
+  })
+
+  it('names the table so the user knows WHICH list is stale', () => {
+    renderTable({ loadError: true, data: rows, tableName: 'Invoices' })
+    expect(document.querySelector('[data-stale-data]')).toHaveTextContent(/Could not refresh Invoices/i)
+  })
+
+  it('retry on the bar re-runs the list request', () => {
+    const onRetryLoad = jest.fn()
+    renderTable({ loadError: true, data: rows, onRetryLoad })
+    const retry = document.querySelector('[data-stale-data-retry]') as HTMLElement | null
+    expect(retry).not.toBeNull()
+    fireEvent.click(retry!)
+    expect(onRetryLoad).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows nothing extra when the load SUCCEEDED and returned rows', () => {
+    // The healthy path is every list in the app; it must not gain a band.
+    renderTable({ loadError: false, data: rows })
+    expect(document.querySelector('[data-stale-data]')).toBeNull()
+    expect(heldRowCount()).toBe('2')
+  })
+
+  it('leaves the zero-row error state alone — the bar is not a replacement for it', () => {
+    // HEDGE-119's branch stays exactly as it was: with no rows to caveat, the
+    // full-height explanation is the right screen, not a one-line band.
+    renderTable({ loadError: true, data: [] })
+    expect(document.querySelector('[data-stale-data]')).toBeNull()
+    expect(screen.getByRole('alert')).toBeInTheDocument()
+  })
+})