Table Layout

Table Layout #

Classification: Restricted (describes source code structure).

Status: available to every organisation, no feature flag (ENG-9536). Never run against a real bonsapi or a real accounting system; see What has never been verified.

What it is #

The Table is a second way to draw an entity’s review list, beside the List: every document as the List’s own row in one spreadsheet (ui-v2 SheetGrid), with each document’s lines folded under it in the line columns and its pages in a docked panel beside the rows. Its next step (Mark ready, Publish or Export, Retry publish) runs from Mod+Enter, the row menu and the selection’s toolbar; see Columns. In code, stores and stored data the layout is also called table (extraction-table, layout: 'table'). It is another presentation of the same review list, not a second app: it reuses the List’s query and live updates, held rows, review sessions, save transports, conflict merge, validation and commands. The one new read is GET /api/v2/extractions?view=table, which returns up to 50 documents' full rows (or too_large past 200 lines) in the shape each type’s detail endpoint returns. A document over 200 lines is a row with no lines to unfold, edited on its review page; a document the read does not return (an expense claim, an untyped one, one with no revision yet, a type the role cannot read) is a row from the list header only. Every row’s menu has “Open the review page”.

The Table is a layout of a saved view (layout: 'table' in the view’s definition, beside its filter, grouping, sort and columns; see Saved views). A definition without a layout is a list, so every view saved before is one. A view may also hold a table block, the Table’s line items: columnGrouping (side, the default: the Debit and Credit bands; field: bands Account, Tags, Tax rate, Tax amount and Amount, each holding its Debit and Credit column; none) and lineColumns, the line columns shown in order (absent: all thirteen in the default order, the Debit and Credit columns, then transactionDate, transactionContact and description; at least one, each once). Both validators (utils’ isValidSavedView, bonsapi’s validate.rs) check it against the same fixtures, and the API spec lists the keys. Views are shared: an organisation view reaches every entity, an entity view everyone on that entity.

The review list (review-list.container.tsx) draws the Table only where all of these hold (reviewPaneOf in domain/extraction-table/view.ts):

  • the window is wide (TABLE_WIDE_QUERY, 48rem) and the list is the main pane (no document or other page beside it). Elsewhere a table view draws as a list;
  • the active view’s layout is table: the reader’s unsaved choice if they made one, else the view’s saved layout (activeLayoutOf in domain/extraction-views.ts).

With room for the Table, the pane stays empty (busy) while a named ?view resolves, so a table view never shows the List first; All and a screen without room draw at once.

Where the choice is made. Display > Layout (List / Table), shown only where the Table can be drawn (layoutOffered in the list store, set by the review list), or set_list_layout. It is an unsaved choice on the view on screen, exactly like a grouping change: main’s view-changed notice names it (Layout) and offers Reset and Save / Save as new by who may write the view. New view and Rename (from the list’s tab menu, Entity Settings > Views, Organization Settings > Views) have a Layout field for every organisation (forms cannot see the screen width). Rename starts on the view’s saved layout and saves layout only when it changes, keeping the rest of the definition as stored; a name-only edit sends no definition. A reader’s unsaved layout choice on screen stays theirs, and the view-changed notice compares it with the new saved layout. An existing view’s layout also changes by opening it, choosing Display > Layout and saving.

Permissions. Main’s view permissions, nothing new: an organisation view is saved by organisation-wide access (owners, admins), an entity view by entity:extraction_view:write (Managers), never while staff impersonate. Anyone who can read the list can switch the layout for themself; the notice then offers them Save as new where they may create an entity view, else nothing to save.

Per device. The document panel (open, width) and column widths stay in extraction-table-layout.store.ts, per organisation on this device; nothing about the layout or the groupings is kept there. A width kept for a column that no longer exists is ignored.

The Table follows the view. Its rows are the view’s list: filter (chips and the Filter menu), search, sort and grouping, as the List asks bonsapi for them. Every grouping level (Display > Group by and Then by) has a group row, the List’s own header: ui-v2 GroupedListHeaderRow (the body GroupedList draws under its pinning) with what extractionGroupHeader says, the same label, glyph, count, totals and fold as the List, hosted over a SheetGrid band through band.content (table-group-row.tsx renders it through a context, so a busy action or a selection never rebuilds the grid). A top-level group is a band, a sub-group a line, as on the List; the rows are plain (nothing pins). The fold is the Table’s own (foldedBands in the table store, by group key; folding a group hides its sub-groups too); its chevron, Enter or Space on it, and ArrowLeft / ArrowRight on the row fold and unfold, and ArrowUp / ArrowDown stop on it. A status group’s hover actions (Mark ready, Review later, More) show while the group row itself is hovered or holds the keys. They are the List’s (useListGroupActions, shared with the List): each loads the rest of the group up to the bulk limit, then runs through useListActions’ one dispatcher, so the Table’s takeOver (its own Mark ready, Review later, Publish and Export steps) and withhold (documents with unsaved Table edits) apply exactly as for the selection; More selects the group’s documents (unfolding it) and opens the selection’s menu. A type group’s Upload is not offered in the Table. The toolbar is the List’s: the view bar with More and each view’s menu, Filter, Display, the missing-view and view-changed notices; the Table has no sort control of its own, Display’s Sort orders it as it orders the List. Unsaved Table edits hold every change that would swap the list (view tab, search, sort, filter, grouping, layout, Reset, and a view write that changes or leaves the view on screen: saving another definition over it, a new layout from Rename, restoring, hiding or deleting it), in the UI and at command level.

Columns and the document panel #

Display › Columns in the Table has two parts. Document: the List’s own Columns chips, the same per-view setting, which the document rows draw. Line items: Grouping (Debit / Credit, By field, No grouping), then a chip per line column to show or hide it, with Move earlier / Move later buttons for the shown ones (the last shown column stays). The choice is the view’s like the others (ListViewChoices.table in the list store, the table part of the view-changed notice, Reset, Save) and the assistant sets it with set_list_line_columns. The grid builds its columns with tableLineColumns (columns.ts): the shown columns in the view’s order, gathered under their bands; a band sits where its first column is and keeps its columns in the view’s order, and a column in no band (Date, Contact, Description) keeps its own place.

The grid’s columns are the line columns only (domain/extraction-table/columns.ts): the Debit band (account, tags, tax rate, tax amount, amount), the Credit band (the same), a bank transaction’s own Date and Contact (labelled as the review page labels them) and Description, in the order and grouping the view chooses, starting at the grid’s first column. Date and Contact are a bank statement’s only (types on the column, columnApplies): they are drawn only while the list holds a bank statement document (tableColumnsFor over the types of every document in the list, not the unfolded ones, so unfolding never adds a column; their chips stay in Display either way), and on another type’s line their cell is the grid’s inapplicable dash, locked with no reason, which paste skips. A transaction’s date edits in the grid as a date (its review cell date, the same session, tint, Undo and Save as any line cell); its contact (the extracted contact_name) is read only, as it was before the redesign: the review page matches or accepts it. There are no document columns and nothing is pinned: a document is its row, the List’s own (ExtractionRow, the view’s Document columns), hosted over a SheetGrid band through band.content (table-document-row.tsx renders it through a context) with its fold chevron before it when it has lines (a document with one line unfolds like any other). Group and document rows span the visible width and stay put while the line columns scroll sideways. The header’s titles show only while some document is unfolded; with everything folded the header keeps its height, blank. A line row has no number of its own: it sits under its document’s row, its first cell indented (a split part one step further), and its cell buttons and errors name it by its place among the line rows (rowNames: 'all').

A document row is selected the List’s way: its hover checkbox, X on the row, Space, or Shift and a click for a range; a selected row is the List’s checked row.

Selection and bulk actions follow the document list (ENG-9420, PR #6452). The Table’s selection is the list’s own: the view’s checked documents in extraction-list.store.ts, the same in either layout, at most 1,000 (LIST_SELECTION_MAX, every path: checkboxes, ranges, select all, the set_table_ticks tool). With documents selected, the list’s toolbar (BulkBar: count, Actions, clear) floats over the rows’ foot, and Actions (Shift+M) opens the list’s palette, its actions offered by the list’s one status policy (useListActions, shared with the list container). Four actions run the Table’s own steps, which keep its guards: Mark ready (and Mark ready and publish) saves a document’s unsaved edits first, Review later and Publish refuse one with unsaved edits, Export opens the Table’s export of one type (several types are refused, as before). Every other list action (Done, Revert, Re-extract, Delete, Change type, Edit pages, publish to the bank feed) runs the list’s own command, and a document with unsaved Table edits is left out of it with the reason on its row. The rule is the commands’ own, so it holds from every entry point (the assistant’s tool call, a key, the palette, either layout): tableHeldIds in extraction-list.ts names the documents whose Table edits are unsaved; actOnSelection (Delete, Revert, Revert finalized, Re-extract, Change type, Publish to the accounting software, Restore, Undo revert) refuses each with TABLE_HELD_REASON and never reaches its write or the discard of its draft, and the rest go on; refuseAllTableHeld refuses the whole call before any confirmation when every document is held, so no dialog offers to delete them and lose the edits; Edit pages works on whole files and is refused while any selected document is held. The assistant’s result lists each document left out with that reason. Done goes through set_extractions_status, which already refuses any document with unsaved review edits. A document whose edits were made on its review page (no Table edit) keeps main’s rules. Refused documents stay selected. A group’s own actions go through the same dispatcher, so the same holds for them.

Which side a line’s cells sit on (documents.ts): on a double-entry AP bill, AR invoice or direct expense (the document’s own flag, as the review form reads it, so a line with no account yet still offers both sides to pick) the line’s own debit and credit cells (the invoice and direct-expense specs read the document’s own side from the line’s own account and tax wires, else the side’s wires extraction v2 writes, and the contra from the other side’s); otherwise bookedSide (AP bill and AR credit note debit, AR invoice and AP credit note credit, a direct expense by money spent or received), the other side blank; a bank transaction by transactionSides (money out: its account debit, the contra account or the bank’s credit). The line has one amount, shown on each side it books: both sides of a double-entry line and of a bank transaction, the booked side of a single-entry line. Either side’s amount cell edits that one amount (amount; on a double-entry line, as in webapp, the typed amount becomes the unit price at quantity 1, and a double-entry invoice line shows quantity times unit price, or no amount where it has no quantity or unit price, as webapp; a bank transaction’s own debit or credit cell). On a single-entry line, where the review calculates the amount (quantity times unit price), the cell is read only, as on the review page.

Contact, date and total edit on the document row (decision D-A). The row’s Contact, Date and Total values (the List’s contact, documentDate and amount fields, drawn through ExtractionRow’s renderField) are buttons where the document can change: a press, or Enter on one (Tab walks to them from the row), opens the review kit’s own control in a popover beside it (TableRowFieldEditor, drawn beside the row menu, outside the grid, so the grid and the Table’s keys never see its keys): FieldWithLens through the review page’s ReviewFieldContainer, the contact as the review’s contact picker (Match existing: any contact in the books) with CounterpartyStatus under it (Accept for a new contact, Undo for an accepted one), the date as the review’s date field, the total as its money field. Enter on what was typed, or a pick, writes it and closes the editor; pressing elsewhere keeps what was typed; Escape drops it. Each change is an unsaved edit like a typed cell’s (edit_table_cells, the same session, 20-document limit, Mod+Z, Save and Discard): the value is tinted as the grid tints an unsaved cell and drawn from the edited copy in the List’s own format (tableEditedRowOf), with “Saved as …” and its Undo in the editor. Which value edits, and why one does not, is row-fields.ts (tableRowFieldStateOf): the document’s lines lock first (too large, not read, still loading), then its review’s gate (ready, final, not editable, the role), with the grid’s lock reasons on hover; a bank statement edits its account’s name and start date only when it has one account, and has no total. The contact is TableEditMap.contact (external_contact_id, matched from the books), never a grid cell. Accept is the review page’s accept_review_counterparty: nothing is written then; the document’s next save or Mark ready creates the contact. An accept alone is not an unsaved Table edit, so the toolbar’s Save does not save a document that holds nothing else. A value the List row hides at a narrow width has no editor there either: the control sits in the List’s own column.

Everything else (number, due date, currency, payment and spend type, paid from, tax ID, reference, title, description, a statement’s balances and totals, “More from the document”) has no line column and does not edit here: the document row shows what the List row shows for it, and the row menu’s Open the review page edits it there. A line’s item, quantity and unit price are reached the same way. Its tax amounts show read only in each band (documents.ts reads them from the review form’s model: a double-entry line’s own side as calculated or overridden and its contra side as derived, a single-entry line’s on its booked side, a bank transaction’s as it holds them for each side; a column the review form hides stays blank).

Issues are read from the rows. A document’s issues (issues.ts) show as the row’s markers, with the List’s tooltips, and as red cells with their message on hover. A step refused by a check (Mark ready stopped by validation, from Mod+Enter or the assistant) says so in a toast (“Mark ready is blocked: …”) and moves the cursor to the first place to fix (jumpToBlocker in table.container.tsx): the line cell it names, unfolding its document, or the cell’s line row when the line has no column for it; a field with no line column, or a document with nothing placed, takes the cursor to the document’s row (scrolled to first when it is far off).

The panel is the page (table-document-panel.tsx): the header (document name, status, the hide button) and the pages, nothing else. It follows the cursor: the document row in focus, or the document of the line the cursor is on, loading the one it rests on. Escape in the panel (its buttons, the pages’ toolbar) takes the keyboard back to the grid’s cell.

The panel’s pages are drawn as the review page’s document pane draws them (ui-v2 ReviewDocumentPanel with focusMode='lens' and the lens from useReviewLens, shared with the review page): the cursor cell’s box is framed and magnified in the zoom lens with the review page’s label and its value, and a line cell with no box of its own shows its whole line. The panel keeps its own page, zoom, rotation and highlights toggle.

Where it lives #

Layer Path What
domain apps/tofu-web/src/domain/extraction-table/ Pure rules: columns, documents and lines (documents.ts, load.ts), rows and row ids (rows.ts, line-keys.ts), fold and the row budget (fold.ts), the lines window and Load more (window.ts), group sections (grouping.ts), editing (editing.ts, edits.ts, the document row’s own values in row-fields.ts), issues (issues.ts), actions and roles (actions.ts), bulk steps (bulk.ts), layout, the view switch (view.ts), telemetry properties (telemetry.ts).
features apps/tofu-web/src/features/extraction-table/ queries/table.ts (the view=table read), containers/ (table.container.tsx, review-list.container.tsx the switch, the lines, list, edits, issues and owner hooks), components/ (presenters), commands/ (layout, view, edits, actions, bulk, telemetry), surface.ts.
state apps/tofu-web/src/state/extraction-table.store.ts, extraction-table-layout.store.ts (+ .persist.ts); extraction-list.store.ts Fold state, edited documents, undo, bulk outcomes, created contacts, who the state belongs to; panel open and width and column widths per organisation on this device. The layout choice and the selection are the list store’s view choices.
ui-v2 libs/typescript/ui-v2/src/components/sheet-grid/ The grid APIs below.
bonsapi GET /api/v2/extractions?view=table; optional expected_data_id on each type’s data save The read, and the version check behind conflict merge.

SheetGrid APIs added for the Table (all off by default; other grids unchanged unless noted): onViewportRowsChange, onEditingChange and canChangeRows (edit guard), rowAnchor with focusCell / revealCell (the cursor keeps its row across rebuilds), parentId + indent (rows indented per ancestor), band rows (band: { label, detail, fold, content }; content is the host’s own row drawn over the band, the Table’s group and document rows), rowNumbers ('top-level' / 'none') and rowNames (with no gutter, buttons and errors still name a line by its document’s number), the statusGlyph decoration, description on a column or column group (header help), cell actions with an accessible name, an onSelect(anchor) for a menu and the more icon, headerToggles (on any column), onPasteResult, and the exports commitSheetGridEditor and sheetGridIsTyping. Changed for every grid: the redraw-flash hold, action buttons only near the screen, the header as one tab stop, Enter on a focused cell button runs it.

Rules that are easy to break #

Row budget and Load more. About 2,000 rows can be edited at a time (TABLE_ROW_BUDGET, document rows included); Expand all stops there. The list pages itself (200 headers a page) only up to 2,000 loaded documents (TABLE_AUTO_LOAD_LIMIT); then a Load more control asks for one page per press. Lines are fetched for a window of 50 documents around the screen (TABLE_WINDOW), debounced; every row-set change is a full sheet rebuild, so changes are batched and never made while the cell editor is open.

Row ids. band:<list group key>, doc:<extractionId>, line:<extractionId>:<key> (the key is the line’s id when it first reached this Table; session.renamed maps it to the current id), load:<extractionId>. Never key anything by position.

At most 20 documents with unsaved edits (TABLE_DIRTY_LIMIT). An edit or paste that would make a 21st is refused whole (“Save first”). Save (Mod+S) saves the dirty documents through each type’s own save transport, five at a time; Discard drops them, after a question.

Version check and conflicts. Each save sends expected_data_id, the revision its edits were made on. bonsapi answers 409 stale_data when someone or something (publish, import, a review page save) wrote a newer revision; the Table then merges the newer revision into the document’s review session with the session’s own merge (snapshot + resolve), saves again when nothing clashes, and otherwise shows Keep mine / Use theirs. A save racing a review page save in the same instant is an accepted edge case (decision 15).

Hold while dirty. While any document holds unsaved edits, its view=table copy is not refetched (an “Updates available” pill applies it), and view tab, search, sort, filter, grouping, layout, Reset and the view writes that change or leave the view on screen are refused at command level. A dirty document under a folded band stays wanted.

The stale-row rule. A step is refused once when the row shows an older revision than bonsapi holds: a clean document’s row is read again; an edited one has the newer revision merged in first, clashes marked, and the step has to be asked for again. In bulk, per document.

Every step opens the review page’s review on a fresh read. The review page’s checks (validate_review, assertReviewReady) run only on an open review session. Each Table step, single or bulk, reads the document fresh and opens the review page’s review on it before running the review page’s own command, and refuses a document that left the step’s starting status. A missing issue marker in the Table is never taken as “clear”.

A new contact is created once per name (createdContacts, by entity and trimmed lower-case name). Several documents naming the same new contact: the first save or Mark ready creates it, the others pick it. Bulk Mark ready refuses a document that still names a new contact (bonsapi’s batch call creates none).

Undo names Table commands. Mark ready’s Undo is return_table_document_to_draft with ifReady (never reopens a document published since); bulk Mark ready and Review later undo through restore_table_document_statuses; Mod+Z undoes the last grid edit (undo_table_edit). Publish and Export offer none.

The command-level hold. One step at a time; a step waits while a Save is under way (refuseWhileSaving), and Publish and Export refuse a document with unsaved edits. Mark ready saves the document’s edits first.

Bulk Mark ready auto-publishes; single never does. The bulk step uses bonsapi’s batch status call, which publishes at once where the entity publishes that type automatically once ready; a person is asked first when it might, and those documents get no Undo. A single Mark ready only moves the document to READY. (Open product question; do not change without Estu.)

Reasons are person text only. A refusal shown on a row or in a toast is a check’s display text or the accounting software’s validation text through the backend error translation, else the generic message. Never a request’s internals or the words written for the assistant.

Telemetry: counts and words, once per step. Events are in ANALYTICS_EVENTS (observability/events.ts), sent through observability’s track (Amplitude, behind consent, no development builds); their properties are built only in domain/extraction-table/telemetry.ts:

Event When Properties
review_view_shown The review list is drawn; once per entity, pane, layout, width and canvas, after a named view is read view (table, list: the pane drawn, the Table or the List), layout (list, table: the active view’s, the unsaved choice included), wide, canvas
table_layout_changed Panel toggle or set_table_layout panel_open (when given), panel_resized, columns_resized (a count)
table_cells_edited Each grid edit or paste documents, cells, outcome (applied, refused_limit, refused_role)
table_edits_saved Each save of Table edits via (save, mark_ready, bulk_mark_ready), documents, saved, conflicts, locked, failed
table_edits_discarded Discard, all or one document, when something was dropped documents, scope (all, document)
table_step_run Each Table step whose body ran step (mark_ready, review_later, publish, retry_publish, export, return_to_draft, restore_statuses), scope (single, bulk: by command, so Review later from the row menu is bulk with 1 document), caller (human, palette, form, agent), documents, done, refused, published, exported, failure (a result code, or none)
table_review_opened open_table_document_in_review succeeded reason (too_large, list_only, chosen)

No issue text, refusal text, contact name, amount, number or id goes in; the telemetry test checks every value is a count, a boolean or a listed word. The no-double-count rule: a Table step sends one table_step_run at its top level; the review page’s and the List’s commands it runs inside report themselves only as the runner’s command_executed, which now carries parent_command (the Table command’s name) on a nested run. So the review page’s and the List’s own use is command_executed without a Table parent_command, and the Table’s is the table_* events; never add the two. Publishes are counted by outcome (published: documents sent to the accounting software, including bulk Mark ready’s automatic publishes), never from a command’s declared reversibility (the Table’s single Publish, Export and return commands are declared reversible around irreversible review page commands). A step the runner refuses before its body runs (role, staleness across a confirmation, the assistant asking for an irreversible step) has command_executed only.

Permissions: the review page’s helpers, the server decides. Every Table command that writes declares the review page’s predicates as its permission: mayUpdateDocuments to set aside, restore statuses or return to Draft; mayVerifyAndUpdateDocuments (mayUpdateDocuments and mayVerifyDocuments) to edit, save, mark ready, publish or export. Each step then checks the document’s own type with tableAccessOf / tableRoleAllows (mayOnDocument on the type’s resource, as the List does) before any read, save or write, and refuses forbidden; a bulk step leaves such a document with that reason. A role without verification sees read-only cells (the review page’s Save refuses it with no_permission). The cells, row fields and row menu read the same grants, with the caller’s organisation grants as the review page reads them (an organisation-wide admin, org:access:all, may do everything whatever their entity role, as bonsapi allows); the selection’s toolbar is the list’s, its actions gated as the list gates them. bonsapi re-checks everything.

Role Shown Editable Runnable from the assistant
Uploader, Viewer (read only) Rows, Status, document panel; no steps; row menu: Open the review page; selection, its toolbar offering what the role may do Nothing (cells locked, “Your role cannot edit…”) Every write refused forbidden
Update without verification Review later (row menu, selection toolbar); Return to Draft of a READY document; no Mark ready, Publish or Export Nothing (the review page could not save it) Review later, Return to Draft of a READY document; the rest forbidden
Update on some types only, with verification Steps on those types only Those types only Those types; others forbidden (bulk: left with the reason)
Update and verification, or organisation-wide access Everything Everything Everything (Publish and Export still ask the person)

Whose state it is. The Table’s store records the person and organisation it belongs to (tableStateFor, applied by useTableOwner in the app layout). Another organisation of the same person starts the Table afresh, each entity’s unsaved documents staying with that entity (as the review page’s sessions stay with their documents); a sign-out or another person drops all of it and closes the review sessions of the documents edited in the Table, without a question. The beforeunload prompt (decision 23) asks on reload or tab close while any Table document holds unsaved edits, and only then.

Keyboard #

Keys Does
Mod+S Save every document with unsaved edits
Mod+Z Undo the last grid edit (a cell editor or text box keeps its own)
Mod+Enter The cursor row’s next step; with documents selected, the selection’s Actions palette
Mod+Shift+D Show or hide the document panel (same key on JIS and US layouts; Mod+D is fill down)
Escape In the document panel, back to the grid’s cell
→ / ← On a document’s row, show or hide its lines
Space, X On a document’s row, select or deselect its document
Shift+Space From any cell, select or deselect the cursor’s document
Shift+↑ / Shift+↓ On a document’s row, run the selection to the document above or below, as the list’s do
Mod+A On a document’s row or the selection’s toolbar, select every loaded document (at most 1,000)
Escape On a document’s row or the toolbar, clear the selection
Shift+M, Shift+R, Shift+L, … On a document’s row or the toolbar, the list’s selection keys (LIST_BULK_KEYS); in a cell they type

What has never been verified #

Everything above was verified with unit tests, happy-dom containers and headless Chromium driving the real grid, containers and command runner over a mocked bonsapi. Never verified:

  • against a real bonsapi (the view=table read, expected_data_id and its 409, the batch calls);
  • against a real accounting system (publish, its errors, automatic publishing on ready);
  • in real browsers other than headless Chromium, with an IME (Japanese input in a cell), or with a screen reader (the canvas grid exposes no per-cell names);
  • a production build’s performance (edit cost was measured in development Storybook only);
  • the advisory lock behind expected_data_id in production (to confirm before release);
  • the telemetry reaching Amplitude (only the track calls were recorded);
  • sign-out and organisation switch with the real Clerk (the reset is unit-tested only).

References #

Linear ENG-9536 (plan v2 and decisions 1–23). Review kit: Review Kit.