feat(browse): guide an empty table to importing or seeding data

[dawsontoth]

Summary

Follow-up to #1703, from the conversation at the end of it: with Import Data moving into
the "..." menu, the empty table itself becomes the place to offer it — and, per that
thread, Import or Seed, because they are two different ideas.

So an empty table now gets two separate invitations rather than one button:

card	opens the Import Data modal on
Import your data	file (or url when that is the only source the role has)
Seed some data	sample

with a quieter "Or write one yourself: Add New Record(s)" underneath.

Both still land in the one modal — ShowImportData just carries the method the card
asked for, and ImportDataModal prefers it over its own tableName ? 'file' : 'sample'
default. That is the entire change to the modal.

Only a table that can be filled is invited to fill itself

The interesting half of this PR is everything the empty state deliberately does not
say. Each of these was a way to tell the user something untrue:

• A page past the end → "No records on this page". Checked first, because on page 3
  of a filtered set "nothing matched" is wrong too.
• Filters matched nothing → "No records match these filters" + Clear Filters. The
  table may be full; the filters are the way out.
• An empty page against a non-zero count → "No records came back", and a pointer at
  Refresh / Only If Cached. search_by_value answers a 404 with { data: [] }
  (getSearchByValue.ts), and Only If Cached — on by default — can produce one on a
  cache miss. Claiming "no records yet" there invites a duplicating import.
• Seed with nothing to seed. methods.sample and methods.file share one path
  (IMPORT_METHOD_PATHS), so a bare insert grant makes both true. An insert-only
  role on a fresh primary-key-only table would get a Seed card whose dataset dropdown is
  empty and whose submit dead-ends on datasetId validation. Each card is now gated on
  the source it would actually use: bundled datasets need csv-data, random records need
  json-records plus columns to model values on.
• Seed promising the wrong table. Picking a bundled dataset retargets the form to the
  dataset's own table (dog/book/animal), so the card says "load a ready-made sample
  dataset into a table of its own"; only the random-records path claims it fills the
  table on screen.
• Copy outrunning the role. "Two ways to get some in" renders only when both cards
  do, and the Import card describes only the sources this role can reach — a URL-only
  role no longer reads file-upload copy.

Why the panel is outside the table

It renders as a sibling of the scroll container, not in a colSpan cell. The grid is
table-fixed and can be far wider than the viewport, so a centred message inside it sits
off past the last column, reachable only by scrolling right.

The empty panel appears on data === undefined, not on isFetching: neither list query
keeps the previous page's rows, so an empty array is always this result set's own settled
answer — and gating on isFetching swapped a settled empty panel back to the spinner cell
on every manual Refresh.

dark:text-violet-300 on the accents is not decoration: --primary is #403b8a, which
is invisible against the table's near-black in dark mode. It is the pairing ClusterHome
already uses.

Tests

• EmptyResultSet.test.tsx — the two invitations are separate and call their own handler;
  each card is dropped when its source is closed; the copy tracks the role; and none of
  the three "not actually an empty table" cases offers to import.
• DatabaseTableView.test.tsx — the wiring, not just the component: each card through to
  the ShowImportData launch it fires and the method it carries, the url fallback, and
  Seed withheld on a primary-key-only table with no csv-data grant.
• TableView.test.tsx — the panel renders outside <table>; the plain "No results." cell
  survives when no empty state is passed; nothing claims a table is empty before rows
  arrive; and a settled empty panel stays put through a refetch.

Every guard was mutation-checked — delete it, confirm exactly one test goes red.

Verification

• tsc -b, oxlint, dprint check — clean (exit codes captured directly, not through a pipe).
• vitest run — 343 files, 3060 passed / 11 skipped.
• Rendered against the real CSS cascade, light and dark, at every permission combination
  and all three withheld-invitation cases.

Review

Four rounds of cross-model review (codex + gemini + cursor-grok + Harper domain
adjudication, independent=true). Round 2 converged; rounds 2 and 3 were spent fixing
defects the review found in my own fixes:

round	found	now
1	Seed offered to a role with nothing to seed; Seed promising the wrong table; copy outrunning the role; refresh flash; untested wiring	fixed in 852d11ed
2	unknown count read as "empty"; seed gate and modal reading different schema sources; unmemoized scan; initialMethod untested	fixed in 6bfafab3
3	the unknown-count heading still asserting the table was empty	fixed in 436494b1

Writing round 2's initialMethod test found a real gap the same way: nothing had
exercised the modal consuming it, so a dropped ?? would have shipped silently.

Two findings were left alone, deliberately:

• Delete-to-empty from page ≥ 1 shows "No records on this page" until you page back.
  Adjudicated to a nit across two rounds — the message is accurate and recovery is one
  click. Resetting pageIndex on an empty page is a behaviour change beyond this diff.
• A useCallback dependency finding was dropped as factually wrong:
  useInstanceImportCapabilities returns a useMemo'd object keyed on permission, so
  its identity is stable.

Coverage caveat on the last round: the gemini leg failed on a headless permission denial
(0 bytes), and the cursor/domain legs were auto-pruned as a narrow low-risk delta, so
round 3 is codex-only. Rounds 1 and 2 carried the full four-lens set with adjudication.

Note on the base

Branched from stage, not from #1703 — the empty state stands on its own and the two
diffs touch different parts of DatabaseTableView.tsx.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a new EmptyResultSet component to handle empty states in the database table view, offering distinct actions for importing data, seeding data, or adding records manually based on user permissions. It also updates TableView to render this custom empty state outside the scrollable table area, and updates ImportDataModal to support preselecting a specific import method. Feedback was provided to make the guidance text in EmptyResultSet dynamic so that it correctly reflects whether one or both of the import/seed options are available to the user.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	62.4%	8643 / 13849
🔵	Statements	62.76%	9242 / 14724
🔵	Functions	55.11%	2176 / 3948
🔵	Branches	55.99%	6229 / 11125

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/instance/databases/components/DatabaseActionModals.tsx	0%	0%	0%	0%	29-112
src/features/instance/databases/components/DatabaseTableView.tsx	58.66%	45.55%	34.14%	58.29%	217-230, 234-236, 261, 266-269, 273, 331-334, 441-442, 453-455, 460-473, 483-489, 503-519, 523-531, 540-548, 554-565, 574-579, 583-598, 605-609, 612-639, 643-644, 647-650, 655, 659, 677, 696-697, 816-826
src/features/instance/databases/components/EmptyResultSet.tsx	95.45%	94.44%	100%	95.45%	144
src/features/instance/databases/components/TableView.tsx	72%	57.14%	84.61%	71.42%	139, 144-157, 285-293, 301, 328-334
src/features/instance/databases/modals/ImportDataModal.tsx	37.28%	32.72%	52%	36.84%	69-89, 204-230, 234-238, 243, 247-316, 326-327, 427-440

Generated in workflow #1892 for commit 436494b by the Vitest Coverage Report Action

[cb1kenobi]

Reviewed the empty-table guidance change at 7dfbd5d against the PR bundle. The state precedence, per-permission gating of the Import and Seed cards, modal method preselection, and the loading-race guard all hold up, and the non-empty table rendering is unchanged. CI is green on this commit and Gemini's copy comment is already on file. No blocking issues found.

—
Reviewed 7dfbd5d

[cb1kenobi]

I was a little on the fence about the seed data thing, but it's AWESOME. Super clean UI. Nice work!

[cb1kenobi]

Re-reviewed the two new commits against the full diff at 6bfafab. The recordCount guards distinguish zero, unknown, and non-zero correctly, the seed gate now reads the same attribute map the modal reads so it fails toward withholding a card rather than opening an empty dropdown, and the modal's method preselection still refuses a method the role cannot run. Gemini's copy comment was already addressed and CI is green; no blocking issues found.

—
Reviewed 6bfafab

[cb1kenobi]

The empty-table invitations stay behind the page, filter, and non-zero-count guards, and Seed is withheld unless a real sample or random source exists. The latest commit only stops the unknown-count heading from claiming the table is empty. Existing discussion already covered the two-ways copy, which is now gated on both cards. No blocking defects on the changed lines.

—
Reviewed 436494b

[cb1kenobi]

No blocking defects on the changed lines at 436494b. The empty-state precedence (page, then filters, then non-zero count) is correct, both cards are gated on the import source they would actually use rather than the shared method path, and the modal still refuses a preselected method the role cannot run. Two things could not be verified from the bundle alone: whether an open-but-empty filter row sets isFiltered, and what the modal's sample page defaults to for a json-records-only role.

—
Reviewed 436494b

[dawsontoth]

Answering the two items @cb1kenobi couldn't verify from the bundle — both check out, no change needed.

An open-but-empty filter row does not set isFiltered. The flag is useFilteredList = filtersToggled && !!appliedSearchConditions (DatabaseTableView.tsx:343), and applyFilters stores null, not [], when nothing was typed: translateFilterValues skips blank values (if (value?.length), line 220) and the result is conditions.length ? conditions : null (line 235). So showing the filter row — or typing and clearing it — leaves an empty table on the invitations rather than on "No records match these filters". Typing without applying does the same, which is consistent: the grid is still running the unfiltered query.

A json-records-only role gets a sample page with exactly one option: Random Data. The bundled-dataset group is gated on allowsSource('csv-data') and the Random Data item on canGenerateRandom && allowsSource('json-records') (ImportDataModal.tsx, the method === 'sample' block). datasetId defaults to '', so the select opens on its "Select a dataset..." placeholder and the user picks the one item present. The Seed card's gate is deliberately the same predicate — allowsSource('json-records') plus a non-empty randomizableAttributes — so the card cannot appear over an empty dropdown. On a primary-key-only table that role gets no Seed card at all, which is the regression test withholds Seed when no dataset and no random records are available.

Worth noting the dropdown does not preselect Random Data even when it is the only choice — pre-existing modal behavior, and a small follow-up if we want Seed to be one click for that role.

🤖 Addressed by Claude Code

[cb1kenobi]

The empty-state guards still withhold Import and Seed on later pages, filters, and a non-zero table count, and each card is still gated on the source it would open. The latest heading change only stops an unknown count from claiming the table is empty. The author's follow-up matches the code: an empty filter row does not count as filtered, and a json-records-only Seed card cannot open an empty dropdown. No blocking defects on the changed lines.

—
Reviewed 436494b