ListViewUrlState
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:34
The collection list’s full URL state, decoded from the compact
query-param grammar (Decision 9/48): q, qf (omitted when it’s the
default field), sort=<field>.<asc|desc>, filter=(<field>.<op>.<value>,…)|(…),
size (omitted at the default), view=<config|shared|local>:<id>, peek=<id>,
cols=<field>[:w<width>][:pl|:pr][:h],<field>… (the full column list —
order, width, pin side, and hidden state, one entry per field — omitted
when it matches the active view’s own resolved array — Decision 48).
Lives in @vexcms/core (Decision 40), pure and dependency-free of react
or any UI library — NextAdminPage (Step 14) and useListViewUrlState
(this step’s own react wrapper) both call parseListViewUrlState/
serializeListViewUrlState directly, so the server’s prefetch args and the
client’s query args are built from one implementation, never two that
could drift.
Type Parameters
Section titled “Type Parameters”TFieldSlug
Section titled “TFieldSlug”TFieldSlug extends string = string
The collection’s own field slugs.
Properties
Section titled “Properties”cols:
ColumnEntry<TFieldSlug>[] |undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:79
Full column list (?cols=<field>[:w<width>][:pl|:pr][:h],…, Decision
48) — every entry’s field URI-component-encoded, suffixes (when
present) always in that fixed order: w<width> (pixels), then pl/
pr (pinned left/right — mutually exclusive, at most one), then h
(hidden). undefined falls back to the active view’s own columns,
then collection.admin.view.state.columns (resolveListViewQueryState’s/
completeListViewColumnOrder’s job, not this module’s — a parsed cols here
may be a PARTIAL list, same as an old stored view’s columns;
completion happens downstream). Replaces Step 20’s plain
bare-field-list grammar entirely — a breaking format change, no
back-compat shim (Decision 48, matching Decision 45’s precedent); a
pre-Part-B cols=<field>,<field> URL still parses (every token with
no : suffix is just a bare field), it simply carries no width/pin/
hidden overrides, same as any other bare-slug entry.
filter
Section titled “filter”filter:
VexWhereNode<TFieldSlug> |null|undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:56
The filter (?filter=), decoded into a plain VexWhereNode.
undefined means absent from the URL — inherit the active view’s
own saved where (Decision 9/45/48). null means the user
explicitly cleared it (distinct from absent — developer-reported:
“Clear all” on a view with its own saved filter must NOT silently
re-inherit that saved filter). An object is an explicit filter.
peek:
string|undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:62
The Inspect peek’s open document id (?peek=), or undefined when the peek is closed.
q:
string|undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:43
Raw search text (?q=). undefined means absent from the URL —
inherit the active view’s own saved search (Decision 9/45/48).
"" means the user explicitly cleared it (distinct from absent —
developer-reported: clearing search on a view with its own saved
search must NOT silently re-inherit that saved text). A non-empty
string is an explicit search term.
qf:
TFieldSlug|undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:45
The active search field (?qf=), or undefined to fall back to the active view’s own searchField, then collection.admin.view.state.searchField (Decision 9/45/48).
size:
number|undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:58
Page size (?size=), or undefined to fall back to collection.admin.view.state.pageSize.
sort:
ListViewSort<TFieldSlug> |undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:47
Portable sort (?sort=), or undefined to fall back to collection.admin.view.state.sort. Decision 7: while q !== "", callers must ignore this rather than send it to the server — this hook still parses and returns it (the park is a rendering/query-building concern, not a URL-state one).
view:
string|undefined
Defined in: packages/core/src/collections/listView/listViewUrlState.ts:60
The active saved view, as the raw <source>:<id> string (?view=), or undefined for none. Step 12 splits this into source/id; this module keeps it opaque.