Skip to content

Specify the one table every surface uses - #1128

Draft
Yaraslaut wants to merge 3 commits into
masterfrom
feat/table-pending-cells
Draft

Yaraslaut wants to merge 3 commits into
masterfrom
feat/table-pending-cells

Conversation

@Yaraslaut

Copy link
Copy Markdown
Member

Design only: no code. Adds docs/spec/table/table.md, the spec for one generic, optimized table that every surface reuses. Refs #1085; this PR does not close it.

What the spec covers

  • A table is a description. Any C++ model can offer zero, one or many tables (BRIDGE_REGISTER_TABLE). Columns can depend on the session, and generic pages go on the wire. Typed rows are a convenience layer on top.
  • One pipeline for document table nodes over rows, model-backed tables, forms collections and server pages, with the fate of each existing path.
  • Unloaded cells and data levels. The issue's core:
    • three-valued filters with undecided rows;
    • unloaded cells sort last;
    • a query loads only the levels its shown, sorted and filtered columns need;
    • partial pages and keyed refetches;
    • arrival is pushed through RemoteServer::announce, with no polling.
  • Caching layers:
    • a framework-owned server LevelCache (load once, deduplicated, explicit invalidation tied to effects, leases and backoff);
    • query-cache rules for partial pages;
    • PageWindow under changes;
    • a server-side view cache.
  • Where sort and filter run, with a single-threaded browser client (Qt WASM) treated as first-class.
  • Configuration:
    • column reorder, hide, resize and pin;
    • chained sort;
    • Excel-like header filters with distinct values and oneOf;
    • column groups with any/all/at-least/exactly/together quantifiers;
    • values with mixed units (Measure with a unit registry filled at run time);
    • copy, a status line, saved views.
  • Persisted state through an injected table::ITableStateStore, loaded before the first query.
  • Performance: a benchmark fixture (bench::WideTableModel, in memory, no database) and budgets at 100,000 × 300 for the server, wire, caches, the frontend at 60 fps (including column virtualization) and the browser.
  • The rest: invariants, API surface, tests, failure modes, alternatives, open questions, and a delivery order (steps 0–10).

engine.md, database_pages.md and the spec index link to it. Sections owed in neighbouring specs are listed with the step each lands in.

Review status

  • Proposed and revised by a design agent, then given one adversarial review (Fable) against the code on master.
  • Every review finding was checked against the code and applied; the table of review items is in the session.
  • Not reviewed since that revision.
  • All budgets are derived from the measurements in engine.md or marked provisional until step 0 records baselines.
  • Nothing was built or measured for this PR.

Open questions

  • Grouping text in a store by the collator's fold.
  • Level-cache invalidation in local mode.
  • Stable offscreen frame timing on the CI image.
  • The level cache's shard count.
  • Concurrent views saves without a conditional write in IPreferencesStore.

🤖 Generated with Claude Code

https://claude.ai/code/session_01No1NzmrVC1p6J5NnZm43g2

Adds docs/spec/table/table.md: a table as a run-time description that any
C++ model can offer (one or many per model), a single pipeline for document
tables, model-backed tables, collections and server pages, unloaded cells and
data levels with partial pages and keyed refetches, the server level cache and
client cache rules, where sort and filter run for a browser client, table
configuration (column order/hide/resize/pin, chained sort, Excel-like filters,
column groups with quantifiers, values with units), persisted table state
through an injected store, and benchmarks with budgets at 100,000 x 300 on an
in-memory C++ model. engine.md, database_pages.md and the spec index point at it.

Refs #1085

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01No1NzmrVC1p6J5NnZm43g2
@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Yaraslaut and others added 2 commits November 17, 2026 10:11
table.md: how a column shows its cells (places, rounding, empty text, units,
labels), tone, tooltip and lock from companion columns, and acting on rows: a
selection of the whole view resolved on the server against its membership,
the application's menu entries, rows an action changed kept in view, key
changes, busy, failed and locked rows, a disabled header, shared views and a
sort bound up to 32. Paging in a database leaves the design: a model's rows in
a database are a DataSource the server sorts and filters with apply.

editing.md (new): grids of a form's ObjectArray on the forms field model,
derived values through evaluate and a derive action, cells of a model's table
edited through CellEdit and RowEdit actions, the walk, cell selection, paste
and fill, header bands, spans, summary rows and fixed grids.

docs/superpowers/plans/2026-11-17-one-table.md: one implementation plan for
both specs, task by task in their delivery order, including the removal of
paging in a database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The index (2026-11-17-one-table.md) gains the parts table and 29
cross-part decisions that every part follows. Parts A to G plan
table.md steps 0 to 9c and editing.md steps 1 to 6 with exact
signatures, tests and commands. Every part has had one review round;
the handover file lists the findings still open for parts C, D, E and
G and the spec questions for the author.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant