Sorting
The sort model is a flat array: SortControl[] — later entries break ties of earlier ones, so the array can express a multi-column sort. A header click sets a single sort (it replaces the array); multi-column sorts are composed in the config dialog. The state contract is the same as for filters: pure mutators, single watcher reaction.
The sort model
interface SortControl {
field: string; // column path (dot-notation)
direction: "asc" | "desc";
}State lives at state.sorters. The renderer translates it into the $sort portion of Uniquery:
// state.sorters
[
{ field: "status", direction: "asc" },
{ field: "createdAt", direction: "desc" },
]
// → controls.$sort
{ status: 1, createdAt: -1 }Order matters. The server applies the directives in the same order, so status is the primary sort and createdAt is the tiebreaker.
How sorters get into the state
Header click
Clicking a <AsTableHeaderCell> replaces state.sorters with a single sort on that column, driven by the column menu's Ascending / Descending items:
- Not sorted (or sorted by another column) → becomes the sole sorter —
asc, ordescif you pick Descending. - Already
asc→ pick Descending to flip it todesc. - Pick the direction it already has → clears the sort entirely.
A header click is a single-sort control: it discards every other sorter, including preset- and v-model-sourced ones. To keep more than one sorter active, build it in the config dialog — that is the only surface that composes a multi-column sort.
The header cell only offers sort when column.sortable === true, which itself derives from meta.fields[path].sortable (the server flag from @db.index.* / @db.column.sortable / @db.table.sortable). For non-sortable columns the header exposes no sort control.
The config dialog
<AsConfigDialog>'s Sorters tab is the heavy-duty editor:
- Reorder sorters by drag.
- Flip direction.
- Remove sorters.
- (Re-)add any sortable column.
All operations write back to state.sorters; nothing else changes until the watcher re-fires the query.
v-model:sorters
<AsTableRoot> accepts an external Ref<SortControl[]> via v-model:sorters. Useful for surfacing sort state in a parent component (URL state, persistence, sync between sibling tables).
Force sorters
<AsTableRoot :force-sorters="..."> (or the underlying useTable({ forceSorters })) pins a list of sorters that always prepend the user's:
<AsTableRoot
url="/db/tables/items"
:force-sorters="[{ field: 'priority', direction: 'desc' }]"
>The merge rule is implemented by mergeSorters in @atscript/ui-table:
import { mergeSorters } from "@atscript/ui-table";
mergeSorters(
[{ field: "priority", direction: "desc" }],
[
{ field: "priority", direction: "asc" },
{ field: "name", direction: "asc" },
],
);
// → [{ field: "priority", direction: "desc" }, { field: "name", direction: "asc" }]If a user sorter targets the same field as a force sorter, the user entry is dropped from the merged result — the force entry wins. The user's array isn't mutated; only the merged result that flows into buildTableQuery is affected.
This is the natural reading of "force": the server always sees the force sorter, and the user can layer additional tie-breakers underneath but cannot override.
Search relevance & sort suppression
When a table has both a search box and a default sort — from a preset, v-model:sorters, or an earlier header click — the two compete on the wire. $search asks the backend to rank matches by relevance; an explicit $sort replaces that ranking with the field order. On a relevance-ranked backend (e.g. Atlas Search) the effect is a search that returns the right set of rows in the wrong order: the closest match can land deep in the list because a default -createdAt sort outranks it. It reads as a broken search, not as a sort problem.
ignoreSortersWhenSearched lets a table opt into preserving relevance while a search is active:
<AsTableRoot url="/api/db/tables/products" ignore-sorters-when-searched />The default is false, so nothing changes unless you opt in. Turn it on only when the search index actually scores matches — for a backend whose search is a plain LIKE filter with no relevance order, suppressing the sort would leave results in an undefined order, which is worse. It's a per-table trade, which is why the table owner holds the switch.
Semantics
The flag is a model, not a static setting — it follows the user's intent across a search session:
- Suppressed while searching. While the flag is
trueandstate.searchTermis non-empty, user sorters are dropped from$sortand the backend ranks by relevance. Suppression is query-time only —state.sortersis never mutated, so nothing is lost and preset-dirty tracking is unaffected. - Sorting during a search is explicit intent. Any write to
state.sorterswhile a search is active flips the flag tofalsefor the rest of that session — a header click, the config dialog, a preset applied mid-search,v-model, or a programmatic write all count. "All matches, newest first" is a legitimate choice, and the header arrows make the trade visible. - A new search resets it. When
searchTermtransitions from empty to non-empty, the flag snaps back to the configured default, so the next search starts at relevance again. Clearing the search resumes emitting whateverstate.sortersholds. forceSortersalways emit. Embed-owner sort (see Force sorters) is never suppressed — it isn't a browse-order default the user can trade away.
Read or drive the runtime value via state.ignoreSortersWhenSearched (a Ref<boolean>), or bind it externally with v-model:ignore-sorters-when-searched:
<AsTableRoot url="/api/db/tables/products" v-model:ignore-sorters-when-searched="relevanceMode" />The runtime value round-trips through the URL as $relevance (see URL State), so a link shared mid-search reproduces exactly the ordering the sharer saw.
Programmatic sorting
For one-off application from the parent component, write directly to the model:
<AsTableRoot ref="root" url="/db/tables/orders" v-slot="{ sorters }">
<button
@click="root!.state.sorters.value = [{ field: 'amount', direction: 'desc' }]"
>
Sort by amount
</button>
<AsTable />
</AsTableRoot>Watchers downstream will re-fire the query automatically — you don't need to call state.query().
What ends up on the wire
buildTableQuery (in @atscript/ui-table) assembles the $sort controls block from the merged sorters:
const sorters = forceSorters?.length ? mergeSorters(forceSorters, userSorters) : userSorters;
const $sort: Record<string, 1 | -1> = {};
for (const s of sorters) {
$sort[s.field] = s.direction === "asc" ? 1 : -1;
}Backends consume the same shape — see atscript-db query syntax for the adapter-specific lowering.
Next steps
- Pagination & Virtualization — how sort changes interact with page reset and block invalidation.
- URL State — bookmarkable sort order.
- Config Dialog — the Sorters tab UX.