Server mode for query-bound tables: complete-result filtering and sorting before paging

[woksin]

Problem

Components 4 deliberately applies table search, column filtering, and sorting only to the currently loaded page. Arc's paginator totals still describe the complete server result. A consumer can otherwise mistake a convenient loaded-page interaction for complete-result behavior and miss matches on unloaded pages.

The deprecated clientFiltering compatibility prop does not toggle this behavior; loaded-page filtering is always available. Issue #159 tracks that old silent-no-op contract and is resolved by the explicit v4 semantics. This issue owns the distinct complete-result capability.

Direction

Complete-result filtering and sorting belong in explicit Arc query arguments and server query logic, applied before paging. Components may provide typed UI state and callbacks that a consumer maps to generated query arguments, but it must not infer backend field names, operators, or authorization policy and must not silently mix loaded-page and complete-result modes.

Coordinate with #109 if consumer proof shows a reusable Arc React state seam. Do not block a server-capable consumer on a new Components table abstraction.

Acceptance criteria

• Documentation names loaded-page and complete-result behavior distinctly.
• A representative generated query accepts explicit sort/filter arguments and applies them before paging.
• Table state changes reset or validate the current page and cannot show stale totals/results during races.
• Snapshot and observable query paths have specs for argument changes, paging, empty results, and server failures.
• The UI indicates which behavior is active and does not claim complete-result search/filter/sort when only the loaded page is affected.
• Public contracts remain renderer-neutral where they represent Arc query state and Cratis-owned where they represent table UI.

[cratis-direct]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.

[woksin]

Decision: start with a time-boxed spike that connects the table's filter and sort state to Arc query arguments, using Arc's paging and sorting hooks. It must also show that results stay correct when arguments change (see #354, fixed in 4.19.1). Then add the smallest opt-in state/event contract: the caller maps table fields and operators to generated query arguments, and the server filters and sorts before paging. Filtering and sorting of the loaded page stay the default. Without a reusable seam, this becomes a documented application-owned example instead.

[woksin]

Spike result and plan. Correction to my earlier comment: #354 is not fixed. The table workaround was withdrawn from 4.19.1, and the root cause is tracked in Cratis/Arc#2872.

What Arc offers today

• Arc already sorts and pages the complete result on the server when the query returns an IQueryable or uses MongoDB Observe, and PagingInfo.totalItems is the filtered total.
• Sorting is native, on a single field: sortBy and sortDirection, with the field name converted to PascalCase.
• Filtering has no Arc primitive, so filters must be query arguments that the query method applies.
• IEnumerable results silently ignore sorting and paging.

What blocks it

• Query hooks show and cache results for arguments that are no longer current Arc#2872: changing an optional argument, such as a filter, never refetches, and a late response can show and cache under the wrong arguments.
• useObservableQuery never resubscribes when the page or page size changes Arc#2869: observable sorting and paging never reach the server.

Plan

1. Now, in 4.21.0: make DataTableCore's sort, column filter and global filter state controllable (sort and onSortChange, filters and onFilter, globalFilter and onGlobalFilterChange). Add an option to render rows as given when the server has already filtered and sorted them. The default behavior is unchanged.
2. After the Arc fixes, in the same Arc upgrade batch as Bound tables show the previous query's status after their arguments change #354 and Support typed Guid fields in AutoCommandForm #314: add an opt-in serverQuery on both bound tables. It maps the table's sort to Arc Sorting through an optional field mapping, maps filter state to query arguments through a caller-supplied function, resets to the first page on changes, and debounces global search. The docs will say the query must return an IQueryable or use Mongo Observe and apply the filter arguments itself.

[github-actions]

Closed by release v4.21.0.

[woksin]

Step 1 shipped in 4.21.0 (#368): DataTableCore now accepts controlled sort/onSortChange, filters (reported through onFilter), globalFilter/onGlobalFilterChange, and rowProcessing (DataTableRowProcessing.None renders rows as given). DataTableSort, DataTableSortDirection and DataTableRowProcessing are exported from @cratis/components/DataTables.

Step 2, server mode for the query-bound tables, is waiting on Cratis/Arc#2872 and Cratis/Arc#2869, which are both still open.

[woksin]

Reopening: the 4.21.0 release workflow closed this automatically, but only step 1 shipped. Step 2 (server mode for the query-bound tables) is still to do and is waiting on Cratis/Arc#2872 and #2869.