Repository navigation
feat(sheets)!: a model-driven grid that works with any tenant schema - #63
Conversation
- Resolve a `TableModel` from `_meta` and targeted introspection: keys, column kinds, write rules, relations (belongs-to, has-one, has-many, many-to-many), filter operators, order-by values and label fields. Nothing guesses a GraphQL name. - Build list, find-one, create, update and delete documents from the model, with a write codec that encodes values by the column's input type. - Update and delete documents report whether a row changed (`applied`), so a write a row rule hides is not mistaken for a save. - `isAuthenticationError` counts HTTP 401 and the codes in the exported `AUTHENTICATION_ERROR_CODES` only, never message text.
…tton press - Menu, select and list highlights move at once; toggle groups and the code input keep their slide through an opt-in `travel` prop. - Menu and select items use a 5px radius, nested inside the 10px popup. - Button press animates only its scale (0.97, 150ms) and stays still with reduced motion; the Sheet close button's hover is instant.
- Build every read and write from the table model: all scalar kinds, files (image, upload, attachment), every relation kind, composite keys, views and read-only columns, each degraded with a visible reason instead of a guess. - Editors for every kind, a shared editor frame, link editor and picker, file editor, record panel, CSV import and export (opt-in formula protection), saved views, filters, sort, search, fill-width columns and a host `readOnly` prop. - One save status in a bottom bar for every write; a write a row rule refuses shows "Not saved" and puts the value back. - Split `sheets.tsx` and `use-sheets.ts` into focused render and assembly modules. - Remove the stale tracked `dist-vendor/` output and the unused `inflekt` dependency.
|
Review complete. 🟠 1 high · 🟡 1 medium 💬 Inline comments (2)
🧹 Nitpicks (2) — 🟢 2 low
This PR ships a major rewrite of the sheets package onto a shared table-model layer in
Several verified defects remain around batch-commit rollback, filter application reporting, import error-report formula injection, and dropped Reviewed commit: 6f435d1 |
The registry installs Sheets as source, and the smoke test compiles it with `strictNullChecks` off. Without it, `!result.ok` does not narrow a result union and `null` initializers widen to `any`, so results now compare `ok === false` and those values carry explicit types. Behavior is unchanged.
…l uses The smoke install looked for `.w-[52px]`, which only the old toolbar's page-size inputs used. It now looks for `.min-w-[320px]`, the small editor width preset.
There was a problem hiding this comment.
Rewrites @constructive-io/sheets as a table-model-driven CRUD grid with a new table-model subsystem in @constructive-io/data, plus cell-type, upload, import/export, and record-panel rework.
Key findings
- 🟠 Failed batch commit reverts rows the server already saved — use-batch-commit.ts:263
- 🟡 Filter conditions dropped from the where still count as applied — build-view-query.ts:56
A paste or fill saves one row at a time and stops at the first row the server refuses. The rows saved before it used to go back to their old values on screen while the server kept the new ones. Now only the refused row and the rows not sent yet go back; the saved rows keep their values, stay undoable, and the status says "N changes saved, M not saved".
When the table's filter input has no `and` field, two conditions on one field (or a condition on the field the search uses) cannot be combined, and the query left them out while the filter count still called them applied. Those conditions now show why they are not applied, the count leaves them out, and the search still applies.
The error report repeats column names from the imported file and values that reasons quote. Text that a spreadsheet app would run as a formula now gets a leading apostrophe. The report is never imported back, so this changes no data.
…orm builder The type mapping now gives `bigint` and `bitstring` cell types, which the deprecated `buildScalarFormSpec` did not know, so those fields dropped out of its forms. They map to the `integer` and `bit` kinds they had before.
In infinite mode no page query exists until the table model resolves, so the grid was not "loading" yet and drew its toolbar over an empty grid before the loading placeholder. Loading now covers the model step too.
Profiled on a 100,000-row table: a click, an arrow key or a save took 300 ms to 1.5 s because every interaction rebuilt and re-rendered far more than it changed. - The TanStack table holds columns only. It built a row object for every row whenever the row array changed; the viewport now draws rows by index. - The infinite-scroll hooks keep their values until a page's data changes, read pages by a hash computed once per page, and normalize each row once. - Each body row is memoized on its own share of the active cell, range and in-place editor, so a cursor move renders the two rows it touches. - The cell resolver caches by row object and reads the rows at call time, so a save renders only the saved row; its options and the table options no longer change identity on every render. - The row marker changes only with the selected rows.
- The view on the left: the saved view, then Fields, Filters and Sort, quiet until they change the view and then tinted with a count, then search. - The actions on the right: Import and Export view as quiet tools, New record, and Add row, the one filled button. - Selected rows get their own group (count, Export, Delete, Clear) in place of the tools; Add row stays put. Delete no longer shows without a selection. - Labels fold into their icons on a narrow toolbar (container queries) and keep their accessible names, so the toolbar stays on one line from about 740 px. - The view and action groups are memoized, so a cursor move renders neither.
…only tables
- `integerBounds` on integer columns: the range of the Postgres type (a smallint
holds -32768..32767 though GraphQL types it `Int`), so a value out of range is
refused before it is sent.
- A Postgres `money` column has the `currency` semantic, like the `currency` domain.
- A table without a primary key that is a view says so ("This is a view of other
tables, so its records cannot be changed here."), in the table issue and the
update and delete reasons.
- The no-primary-key reason says what cannot happen: records cannot be changed or
deleted.
Links
- Undo covers saved link changes: each save is one step that runs the inverse
writes (key values put back, a moved record returned to its old owner, a removed
link row added again, an added one removed). A refused step stays to retry.
- The link editor fits the space above or below its cell, and its body scrolls.
- The open icon sits at the cell's right edge (on hover in a list), and a press
inside a portalled surface no longer counts as a press outside the grid.
- Records with the same label show what tells them apart (email, else key).
- Link columns read short ("Assignee", "Tasks"); the long name is kept only where
two fields would read the same, and for a list of the table's own records.
- A copied link cell holds the record labels, not JSON.
Editing
- Inline editors: Enter saves and moves down, Tab and Shift+Tab save and move
across.
- The date editor takes a typed date (year first, or in the locale's day/month
order) and Enter saves it.
- Money fields read "$1,234.56"; integer fields check their Postgres range;
clearing a required text field of a saved record is refused.
- Refused writes read in plain words (unique, not null, check, foreign key, a
delete blocked by linked records).
Rows
- Add row puts the cursor on the first cell the row still needs; Save names the
missing fields and goes back there.
- Delete row acts on the selected rows, else the cursor's; a new row is
discarded ("Discard new row?"), also where saved rows cannot be deleted.
- A failed rows request keeps the toolbar and shows the error over the grid,
with Clear and Try again.
- The grid reads its rows and model again when the page comes back after 30 s.
Other
- The new-record form marks a required link and shows "Set automatically when
created" for a field the table fills in.
- The search box never names a full-text or vector column.
- Export headers use the grid labels; the import result lists the top reasons
rows were refused.
- On a narrow grid a frozen column takes at most 40% of the width.
- Column headers carry aria-colindex.
- `tableRolesFromCatalog(platformTables)` reads each table's `category` from the
platform API (`tables { name category schema { schemaName } }`): `APP` is the
owner's, any other category a platform module's. Keys are the physical schema plus
the SQL table name, the same in the catalog and in `_meta`.
- `isSystemTable(metaTable, roles?)`: a table the catalog files as a module's, or one
`_meta` marks (storage files and buckets, scope `database`). The catalog only adds:
generated search tables are filed as APP but stay system tables.
- `_meta` selects `tableName` when the server has it (optional capability).
…able - `SheetsTableSelector` items take `system: true`. System tables are hidden behind a "Show system tables (N)" switch, off by default and remembered per browser; while on, they show in their own section. The open table always stays listed. `useShowSystemTables()` shares the setting with any other picker on the page. - The table list scrolls, so a long list or the second section is never cut off, and the search, switch and list sit on an even rhythm. - An empty table keeps the toolbar, headers and status bar; "No rows yet" covers the body with Add row and Import. A host's `slots.empty` still replaces the grid.
Related: constructive-io/constructive#1996 (the
_metafields this grid reads), constructive-io/dashboard#324 (the Dashboard copy; draft until@constructive-io/datais published) and constructive-io/constructive-desktop#283 (the Desktop Sheets tab).What changed
@constructive-io/data,table-model/). Each table is built once from_meta(contract2026-07) plus targeted__typelookups. The model holds the keys, column kinds, write rules, relations, filter operators, order-by values, label fields and storage role. Every list, find, create, update and delete document is built from it, with no name guessing.ColumnModel/RelationModel. Anything the model cannot prove is read-only with a reason the user can see. A field or table that cannot be resolved degrades on its own and never breaks the database view.YYYY-MM-DD HH:mm:ss, zoned values in the viewer's zone, the exact text kept for copy and writes)._meta:uploadHeaderssent unchanged, deduplication, and one renewal of an expired URL;uploadToFilesTablefor uploads outside a cell.unfinishedUploadOf(error)names it.applied, and the adapter turns an empty answer into an error: the value comes back, the status says "Not saved", and the card says "This record was not changed. You may not be allowed to change it, or it no longer exists."personByAssigneeEmail, "Tasks", "Projects"). The long form ("People by manager", "Projects via project members") is kept for a list of the table's own records and where two fields of the table would read the same.SheetsTableSelectoritems takesystem: true, and the list hides those behind "Show system tables (N)", off by default and remembered per browser; while on they show in their own section, and the open table always stays listed.isSystemTableandtableRolesFromCatalog(@constructive-io/data) decide from the platform catalog's tablecategory(anything butAPPis a module's) plus the_metafacts (storage, scopedatabase), since the catalog files generated search tables asAPP._metaselectstableNamewhere the server has it. The table list scrolls instead of cutting off a long list.slots.emptystill replaces the grid.aria-colindex.commands,keymap,interceptors,onCommand);gridcelland carriesaria-selectedand the read-only reason;EditorHeader/EditorFooter).docs/FEATURES.md,docs/HOST_INTEGRATION.md,docs/EMBEDDING.md,docs/OVERLAY_EDITORS.md, and the registry docs string.csvExport={{ protectFormulas: true }}, every CSV export (Export view, Export selected,exportCsv) writes text that starts with=,+,-,@, a tab or a carriage return with a leading apostrophe. Numbers and the header are never changed.exportCsv({ protectFormulas })overrides it per call. The import error report always protects its text, because it is read, never imported back.readOnlyprop (trueor a reason). Every cell, paste, fill, link, New record, Import, Delete and record panel field refuses with the reason. Add row is hidden and the toolbar shows "Read-only". Viewing, sorting, filtering, search and export stay. HeadlessuseSheetshosts useSheetsReadOnlyProvider.UNAUTHENTICATEDorBAD_TOKEN_DEFINITION(AUTHENTICATION_ERROR_CODES), never message text.isAuthenticationError(@constructive-io/data) and Sheets' executor share the list.packages/sheets/dist-vendor/build output is deleted and now gitignored (pnpm build:vendorstill works locally), and the unusedinflektdependency is dropped from@constructive-io/sheets.SheetsConfig.map).tilesis{ url, attribution, subdomains? }or'off', and'off'edits shapes as GeoJSON text.placeSearchis{ url }or'off', and'off'removes the search box. The default is unchanged: OpenStreetMap and Nominatim. An unusable setting turns that part off with a logged warning and never falls back to the public services.packages/uipolish:travelprop keeps the spring for the toggle group and the one-time-code input.The table model
The save status
Overlapping writes settle once, to one outcome: one write keeps its own message ("Saved", "Row created", "3 rows deleted"); several read "All changes saved", "Some changes were not saved" or "Changes were not saved".
Host API at a glance
Upgrading
This is a breaking release. The full table is in the README, under "Upgrading". The headlines:
SheetsBackendAdaptergainsfetchTableModel.AdapterTableContextis now{ model, tableName }, andAdapterListQuerychanges shape.SheetsFilterGroup, …), andSheetsViewStatemoves to version 2 (columnsis required). Version 1 is still read.executeFieldUploadtakes aTableModel.useSheetsFieldUploadis deprecated.SheetsConfig.uploadis nowSheetsUploadConfig.SaveStatusin its status bar instead ofFloatingStatus, which is still exported. "Image saved" and "Update failed" are no longer toasts.UNAUTHENTICATEDorBAD_TOKEN_DEFINITION.onErrorreceives failed uploads withsource: 'upload'.callUploadOp,discoverUploadCapability,fetchDownloadUrl,presignedPutandsha256HexFromBuffer. Tests pin their earlier behavior.SheetsHandle.exportCsvandExportViewControltake an optionalprotectFormulas.isAuthenticationErrorno longer reads message text. A host that relied on a message to sign users out now needs a 401 or one of the codes inAUTHENTICATION_ERROR_CODES.SheetsaddsreadOnly, and the package exportsSheetsReadOnlyProviderandDEFAULT_READ_ONLY_REASON.SheetsConfig.mapis new and optional, and the default is unchanged. A site with a Content-Security-Policy needsimg-srcfor the tile host andconnect-srcfor the search endpoint.packages/ui: the list highlight no longer slides between items unless a component passestravel.@constructive-io/data:ColumnValueModel.integerBoundsis new (null for non-integer columns), and a Postgresmoneycolumn hassemantic: 'currency'.SheetsDraftBindingsaddsdeleteRows(rows).isSystemTable,tableRolesFromCatalogand theTableRolestypes (@constructive-io/data);useShowSystemTables,visibleTablesandTableWithCategory.system(@constructive-io/sheets).slots.emptyto keep a full replacement.SheetsControls: Delete and Export selected show only while rows are selected, in their own group.ImportRecordsControlandExportViewControlrender quiet ghost buttons whose labels fold inside a narrow Sheets toolbar (anywhere else they keep their labels).Screenshots
Live on a local stack with a seeded tenant database (dark theme). These surfaces are new, so there is no earlier screen to compare.
Task table with 20,005 rows: choice chips, priorities, the bottom bar with the row count and "Saved" after an edit
Link editor on a required link: the current link, a searchable picker over 303 projects, and why it cannot be removed
Record panel (Shift+Space): fields with their own editors, linked records with Change link and Clear link
Image cells from real uploads, and relation columns named "People by manager" and "Projects via project members"
An edit a row rule refuses: the value comes back, the bar says "Not saved", and the card says why
Gallery cells with thumbnails, and the file editor on a multi-file column
Relation and stress pass
From a pass over every relation shape and a 20,000-row table on the local stack.
Same-name records told apart in the link picker
Mod+Z undoes a saved link change ("Link change undone")
Save on an incomplete new row names the missing fields and marks them
A search the server refuses keeps the toolbar, with Clear search and Try again
Follow-ups
@constructive-io/data, then@constructive-io/sheetsand@constructive-io/ui; then the Dashboard bump and re-sync, and the Desktop bump._metatable kind and foreign-key delete rules, nulls-last sort values, codes for length and RESTRICT errors, row versions, per-row permissions) need backend work; Sheets reads each one once the server sends it.🤖 Generated with Claude Code
https://claude.ai/code/session_017WbsG7zuvxWWo3jB12oYkA