@urbicon-ui/sveltekit-utils 7.0.0 → 8.0.0

package/README.md

@@ -5,7 +5,7 @@ Small, focused SvelteKit helpers that Urbicon apps share. Zero runtime dependenc
 Currently shipping:
 
 - **URL-state runes** — reactive `useUrlParam` / `useUrlArrayParam` that keep component state in sync with `?query=` parameters
-- **Table-query URL sync** — opt-in `?q=…&sort=…&page=…` mirroring for `@urbicon-ui/table` server mode, plus the pure serializers behind it
+- **Table view ↔ URL** — `bindViewToUrl`, the URL home for a `@urbicon-ui/table` view object (`?q=…&sort=…&page=…`), plus the pure serializers for the load path
 - **Cron runner** — interval-based background fetcher for scheduled server endpoints
 - **SSE stream reader** — `streamSse`, a spec-correct async-generator client for one-shot POST `text/event-stream` endpoints (LLM relays)
 
@@ -57,60 +57,60 @@ updateUrlSearchParams({ page: '1', tag: ['a', 'b'] }, { replaceState: true });
 - URL updates use `goto()` with `replaceState: true`, `noScroll: true`, `keepFocus: true` — suited for filter/pagination UIs, not full page transitions.
 - `useUrlParam` returns getters (not Svelte stores) so consumers can read the value lazily inside `$derived`/`$effect`.
 
-## Table Query ↔ URL (`table-query` + `url.svelte`)
+## Table View ↔ URL (`url.svelte` + `table-query`)
 
-Opt-in URL sync for `@urbicon-ui/table`, in client mode as well as `mode="server"`: the `TableQuery` the table emits (search, sort, page, page size, filters, grouping) is mirrored onto query parameters (`?q=…&sort=…&page=…`), so the view state survives reloads, can be shared as a link, and — unlike `localStorage` — is visible to the server.
+`bindViewToUrl` gives the view object of `@urbicon-ui/table` — search, sort, page, page size, filters, grouping — the URL as its home: the axes are mirrored onto query parameters (`?q=…&sort=…&page=…`), so the view survives a reload, can be shared as a link, and — unlike `localStorage` — is visible to the server.
 
 ```svelte
 <script lang="ts">
-  import { Table } from '@urbicon-ui/table';
-  import { tableQueryToSearchParams } from '@urbicon-ui/sveltekit-utils/table-query';
-  import { createTableQueryUrlSync } from '@urbicon-ui/sveltekit-utils/url.svelte';
+  import { Table, createTableView } from '@urbicon-ui/table';
+  import { bindViewToUrl } from '@urbicon-ui/sveltekit-utils/url.svelte';
 
-  const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+  const view = createTableView({ defaults: { pageSize: 25 } });
+  bindViewToUrl(view);
 </script>
 
-<Table
-  mode="server"
-  {columns}
-  itemsPerPage={25}
-  query={sync.viewState}
-  queryFn={async (query, { signal }) => {
-    sync.syncQuery(query); // mirror the query onto the URL (replaceState)
-    const res = await fetch(`/api/users?${tableQueryToSearchParams(query)}`, { signal });
-    const data = await res.json();
-    return { items: data.results, totalItems: data.total };
-  }}
-/>
+<Table {items} {columns} {view} />
 ```
 
-`viewState` carries **only the axes the URL actually names**, and the table's `query` prop reads it by field presence: a present field controls that axis, an absent one leaves persistence and the `initial*` seeds alone. That is why this is not `initialQuery` — that one describes every axis, including the ones it filled in from the defaults, so a table wired to it ignores `persistenceConfig`, `initialSort`, `initialFilters` and `initialGroupBy` on every URL. `initialQuery` stays what its name says: a complete snapshot, parsed once, to seed a fetch with.
+Both calls belong in the component's initialisation. The init half runs synchronously — a `?sort=…` link renders sorted server HTML — and the runtime halves are effects: URL navigations apply to the view, the reader's changes reach the URL debounced.
 
-Because `viewState` re-reads the URL rather than capturing it, the browser's back button works: navigating back to a URL without `?sort` returns the table to its unsorted view.
+The second argument is optional; every option has a default:
 
-A controlled axis is not written to `localStorage` by default, so a visit that arrives without query params starts clean. For a business table where "my filters are still there tomorrow" is expected, pair the sync with `persistenceConfig={{ tableId: '…', persistControlled: true }}` — the table then stores what the reader themselves changed (never what a shared link brought), and hands it back on a bare visit. Reading order is unaffected: the URL still wins.
+| Option            | Default | Effect                                                                                                                                                                                                            |
+| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `axes`            | all six | Which axes this binding manages. An unbound axis never reaches the URL, whatever the view holds.                                                                                                                  |
+| `debounceMs`      | `300`   | Delay before a view change is written to the URL.                                                                                                                                                                 |
+| `replaceState`    | `true`  | Replace the current history entry instead of pushing one, so rapid sort/filter/page edits do not flood the back button.                                                                                           |
+| `prefix`          | `''`    | Key namespace (`prefix: 't_'` → `?t_q=…&t_page=…`) for a second bound table on the same page.                                                                                                                     |
+| `reflectExternal` | `false` | Mirror an externally applied value (a storage seed) into the URL immediately. Off by default: the address bar does not change without reader interaction, and the seed reaches the URL with the first one anyway. |
 
-With manual control (`onQueryChange` instead of `queryFn`), pass `sync.syncQuery` directly — note that `onQueryChange` does not fire when `queryFn` is set, which is why the managed variant calls it inside `queryFn`.
+Because the binding re-reads the URL rather than capturing it, the browser's back button works: navigating back to a URL that no longer names `?sort` returns the table to its default sort.
 
-The pure serializers live under `@urbicon-ui/sveltekit-utils/table-query` and work without SvelteKit — e.g. to parse the initial query in a server `load` and fetch the first page during SSR:
+The pure serializers work without SvelteKit — e.g. to parse the incoming query in a server `load` and fetch the first page during SSR. Use `searchParamsToViewQuery` from `./table-view`: it takes the *same* defaults object the component hands `createTableView`, so the server cannot resolve an absent param differently from the client.
 
 ```typescript
+// view-defaults.ts — imported by both the component and the load function
+export const userView = { pageSize: 25, sort: { column: 'joined', direction: 'desc' } };
+
 // +page.server.ts
-import { searchParamsToTableQuery } from '@urbicon-ui/sveltekit-utils/table-query';
+import { searchParamsToViewQuery } from '@urbicon-ui/sveltekit-utils/table-view';
+import { userView } from './view-defaults';
 
-export const load = async ({ url }) => {
-  const query = searchParamsToTableQuery(url.searchParams, { defaults: { itemsPerPage: 25 } });
-  return { initialResult: await fetchUsers(query) };
-};
+export const load = async ({ url }) => ({
+  initialResult: await fetchUsers(searchParamsToViewQuery(url.searchParams, userView))
+});
 ```
 
+`searchParamsToTableQuery` in `./table-query` does the same job with a baseline in the wire vocabulary (`itemsPerPage`, `sortColumn`/`sortDirection`, `groupByKey`). It has no field for a default filter set, which is why the view-vocabulary function exists.
+
 **Design notes**
 
-- **Default elision** — values equal to `defaults` are not written; a table in its default state leaves the URL clean. Set `defaults` to the table's initial props (`itemsPerPage`, `initialPage`, `initialGroupBy`, and `sortColumn`/`sortDirection` when the table ships a baked-in `initialSort`) so the elision baseline matches the state the table starts in.
-- **Read tolerant, write strict** — unparsable params fall back to the defaults and malformed `filter` entries are skipped; serializing a structurally invalid query (non-positive page, unknown operator) throws instead of writing corrupt state.
-- **Namespacing** — `prefix: 't_'` scopes all keys (`?t_q=…`) for multiple synced tables on one page; unrelated params are always preserved.
-- **Types** — `TableQueryParams` is a structural mirror of the table's `TableQuery` (no dependency on `@urbicon-ui/table`; a parity test in the table package guards against drift).
-- **Seeding** — every axis the URL carries can seed the table: `initialPage`, `initialGroupBy`, `initialSort`, `initialFilters` (plus controlled `searchTerm` with an `onSearchTermChange` write-back). The seeds land before the table's first query emission, so a shared URL's sort/filter params survive it — the header indicator and filter chips show the URL state instead of the first emission wiping it. One precedence caveat: the `initial*` props seed only an axis `persistenceConfig` has nothing stored for — when both are active, a persisted sort/filter/group wins over the URL, and that includes a persisted _empty_ value (the user cleared that axis once, so it stays cleared). Scope or disable persistence for URL-driven tables if the link should be the source of truth.
+- **Default elision** — an axis whose value equals its default is not written; a table in its default state leaves the URL clean. The baseline *is* `view.defaults`, read off the object the binding decorates, so there is no second copy of the defaults to keep in step with the table's own.
+- **Read tolerant, write strict** — an unparsable value on a param the URL actually carries falls back to that axis' default, and malformed `filter` entries are skipped individually; the `table-query` serializer throws on a structurally invalid query (non-positive page, unknown operator) instead of writing corrupt state.
+- **Namespacing** — `prefix: 't_'` scopes all keys (`?t_q=…`) for multiple bound tables on one page; unrelated params are always preserved. Two prefixless bindings would manage the same keys, so that throws at registration instead of producing a link that loads the wrong table.
+- **One writer per page** — every binding submits into one coalescing URL writer, so two tables land in a single navigation, each replacing only its own keys. A landing URL the writer itself sent is not applied back onto the view: an edit made while that navigation was in flight survives instead of being overwritten by the URL it raced.
+- **Types** — `TableQueryParams` mirrors the table's `TableQuery`, and `TableViewLike` / `TableViewSnapshot` (from `./table-view`) mirror its view object structurally — so this package carries no dependency on `@urbicon-ui/table`. A parity test in the table package (`tableQuery.parity.test.ts`) pins both mirrors: the snapshot shapes must stay mutually assignable, and the real `TableView` must satisfy `TableViewLike`, which is the entire mechanism by which this binding decorates a view it never imports.
 
 ## Cron Runner (`cron`)
 
@@ -207,13 +207,16 @@ export const POST = async ({ request }) => {
 
 ## Exports
 
-| Subpath         | Contents                                                                                                           |
-| --------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `.`             | Barrel of all modules                                                                                              |
-| `./url.svelte`  | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `createTableQueryUrlSync`, types     |
-| `./table-query` | `tableQueryToSearchParams`, `searchParamsToTableQuery`, `applyTableQueryToSearchParams`, `TableQueryParams`, types |
-| `./cron`        | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                                                    |
-| `./sse`         | `streamSse`, `SseEvent`, `StreamSseOptions`, `SseRequestError`                                                     |
+| Subpath         | Contents                                                                                                                                           |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`             | Barrel of all modules                                                                                                                              |
+| `./url.svelte`  | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, types                                               |
+| `./table-view`  | `searchParamsToViewQuery`, `searchParamsToViewSnapshot`, `viewSnapshotToTableQuery`, `searchParamsToViewPartial`, `viewSnapshotToSearchParams`, `viewAxesNamedBy`, `viewAxisKeys`, `TABLE_VIEW_AXES`, `TableViewLike`, types |
+| `./table-query` | `tableQueryToSearchParams`, `searchParamsToTableQuery`, `applyTableQueryToSearchParams`, `TABLE_QUERY_FILTER_OPERATORS`, `TableQueryParams`, types |
+| `./cron`        | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                                                                                    |
+| `./sse`         | `streamSse`, `SseEvent`, `StreamSseOptions`, `SseRequestError`                                                                                     |
+
+`bindViewToUrl` lives in its own module (`view-binding.svelte.ts`) and is re-exported from `./url.svelte`, which is its documented import path — it has no subpath of its own. `./table-view` and `./table-query` are SvelteKit-free (they touch no `$app/*`), which is what lets a `load` function and a plain test use them; `./url.svelte` is the half that needs the router.
 
 ## Development
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './cron.js';
 export * from './sse.js';
 export * from './table-query.js';
+export * from './table-view.js';
 export * from './url.svelte.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './cron.js';
 export * from './sse.js';
 export * from './table-query.js';
+export * from './table-view.js';
 export * from './url.svelte.js';

package/dist/table-query.d.ts

@@ -40,8 +40,8 @@ export interface TableQueryFilter {
 }
 /**
  * Query state of a table in server mode. Structural mirror of `TableQuery`
- * from `@urbicon-ui/table` — the object passed to `queryFn` / `onQueryChange`
- * is directly assignable.
+ * from `@urbicon-ui/table` — the object a managed `source.query` receives
+ * (or `viewToQuery` projects) is directly assignable.
  */
 export interface TableQueryParams {
     /** Current page (1-based). */
@@ -59,39 +59,17 @@ export interface TableQueryParams {
     /** Column ID for grouping, or null if ungrouped. */
     groupByKey: string | null;
 }
-/**
- * The partial half of {@link TableQueryParams} — structural mirror of
- * `TableViewState` from `@urbicon-ui/table`, the type its `query` prop takes.
- *
- * Every field optional, and that is the whole contract: **presence means
- * controlled**. A consumer may hand over the sort and leave paging to the
- * table, so "absent" has to stay distinguishable from "set to its default
- * value" — which is exactly what {@link TableQueryParams} cannot express.
- */
-export interface TableQueryViewState {
-    /** Current page (1-based). */
-    page?: number;
-    /** Number of items per page. */
-    itemsPerPage?: number;
-    /** Column ID to sort by, or empty string for no sort. */
-    sortColumn?: string;
-    /** Sort direction. */
-    sortDirection?: TableQuerySortDirection;
-    /** Full-text search term. */
-    searchTerm?: string;
-    /** Active column filters. */
-    activeFilters?: TableQueryFilter[];
-    /** Column ID for grouping, or null for ungrouped. */
-    groupByKey?: string | null;
-}
 /**
  * Baseline used for default elision: query values equal to these defaults are
  * omitted from the URL, and missing params parse back to them.
  *
- * Set the defaults to the table's **initial, uncontrolled state** — i.e. the
- * values you pass as props (`itemsPerPage`, `initialPage`, `initialGroupBy`).
- * Unset fields fall back to the table's own defaults (page 1, 10 items per
- * page, no sort, empty search, ungrouped).
+ * A **wire-codec** baseline in the query shape — when your defaults live on a
+ * view object (`createTableView({ defaults })`), skip the manual projection
+ * and use `searchParamsToViewQuery` from `./table-view`, which takes the view
+ * itself. Unset fields fall back to the table's own defaults (page 1, 10
+ * items per page, no sort, empty search, ungrouped). Filters have no default
+ * field: active filters are always written, an absent `filter` param parses
+ * to none.
  */
 export interface TableQueryDefaults {
     /** Default page. @default 1 */
@@ -136,8 +114,8 @@ export interface TableQueryUrlOptions {
  * When `sortColumn` is empty the sort direction is meaningless and is
  * normalized away (it parses back as `'asc'`).
  *
- * Also handy for building the backend request inside `queryFn` — the same
- * scheme works as an API query string.
+ * Also handy for building the backend request inside a managed
+ * `source.query` — the same scheme works as an API query string.
  *
  * @param query - Query emitted by the table (`TableQuery` is assignable).
  * @param options - Elision defaults + key prefix.
@@ -153,41 +131,17 @@ export declare function tableQueryToSearchParams(query: TableQueryParams, option
  * unknown `dir` becomes `'asc'`, and malformed `filter` entries (wrong shape,
  * unknown operator, broken percent-encoding) are skipped individually.
  *
- * Works anywhere a `URLSearchParams` exists — including `url.searchParams`
- * in a server `load`, to run the initial server-mode fetch during SSR.
+ * The wire-level codec, for consumers who hold their defaults in the query
+ * shape. For the SSR load path of a v8 view — running the initial fetch in a
+ * server `load` from `url.searchParams` — prefer `searchParamsToViewQuery`
+ * from `./table-view`: same keys, but it reads the defaults off the view
+ * object instead of a hand-projected baseline.
  *
  * @param params - Search params to read (not mutated).
  * @param options - Fallback defaults + key prefix.
  * @returns Complete query object (assignable to `TableQuery`).
  */
 export declare function searchParamsToTableQuery(params: URLSearchParams, options?: TableQueryUrlOptions): TableQueryParams;
-/**
- * Parse `URLSearchParams` into the **partial** view state a table's `query`
- * prop takes — a key per axis the URL actually carries, and nothing else.
- *
- * This is the deliberate opposite of {@link searchParamsToTableQuery}, and the
- * distinction is load-bearing rather than cosmetic. The table reads `query` by
- * **field presence**: a present field means "this axis is controlled — outrank
- * persistence and the `initial*` seed"; an absent one means "the URL has no
- * opinion, carry on". A complete object therefore claims every axis, so
- * handing `searchParamsToTableQuery`'s output to `query` silently switches off
- * `persistenceConfig`, `initialSort`, `initialFilters` and `initialGroupBy` —
- * even on a URL with no params at all, where its every field is a default it
- * invented. That is not a hypothetical: it was the shipped wiring, and this
- * function exists because of it.
- *
- * `sortColumn` and `sortDirection` are emitted as a pair or not at all, so the
- * half-controlled sort (a direction with no column) cannot be produced here.
- *
- * Same tolerance as the full parser: an unparsable `page`/`size` falls back to
- * the resolved default *for that key* — the key was present, so the axis stays
- * controlled — and malformed filters are skipped individually.
- *
- * @param params - Search params to read (not mutated).
- * @param options - Fallback defaults + key prefix.
- * @returns Only the axes present in `params`.
- */
-export declare function searchParamsToTableViewState(params: URLSearchParams, options?: TableQueryUrlOptions): TableQueryViewState;
 /**
  * Merge a table query into existing search params: all managed keys (`q`,
  * `page`, `size`, `sort`, `dir`, `group`, `filter` — with the configured

package/dist/table-query.js

@@ -128,8 +128,8 @@ function parseFilterParam(raw) {
  * When `sortColumn` is empty the sort direction is meaningless and is
  * normalized away (it parses back as `'asc'`).
  *
- * Also handy for building the backend request inside `queryFn` — the same
- * scheme works as an API query string.
+ * Also handy for building the backend request inside a managed
+ * `source.query` — the same scheme works as an API query string.
  *
  * @param query - Query emitted by the table (`TableQuery` is assignable).
  * @param options - Elision defaults + key prefix.
@@ -172,8 +172,11 @@ export function tableQueryToSearchParams(query, options = {}) {
  * unknown `dir` becomes `'asc'`, and malformed `filter` entries (wrong shape,
  * unknown operator, broken percent-encoding) are skipped individually.
  *
- * Works anywhere a `URLSearchParams` exists — including `url.searchParams`
- * in a server `load`, to run the initial server-mode fetch during SSR.
+ * The wire-level codec, for consumers who hold their defaults in the query
+ * shape. For the SSR load path of a v8 view — running the initial fetch in a
+ * server `load` from `url.searchParams` — prefer `searchParamsToViewQuery`
+ * from `./table-view`: same keys, but it reads the defaults off the view
+ * object instead of a hand-projected baseline.
  *
  * @param params - Search params to read (not mutated).
  * @param options - Fallback defaults + key prefix.
@@ -206,65 +209,6 @@ export function searchParamsToTableQuery(params, options = {}) {
         groupByKey: rawGroup !== null ? (rawGroup === '' ? null : rawGroup) : d.groupByKey
     };
 }
-/**
- * Parse `URLSearchParams` into the **partial** view state a table's `query`
- * prop takes — a key per axis the URL actually carries, and nothing else.
- *
- * This is the deliberate opposite of {@link searchParamsToTableQuery}, and the
- * distinction is load-bearing rather than cosmetic. The table reads `query` by
- * **field presence**: a present field means "this axis is controlled — outrank
- * persistence and the `initial*` seed"; an absent one means "the URL has no
- * opinion, carry on". A complete object therefore claims every axis, so
- * handing `searchParamsToTableQuery`'s output to `query` silently switches off
- * `persistenceConfig`, `initialSort`, `initialFilters` and `initialGroupBy` —
- * even on a URL with no params at all, where its every field is a default it
- * invented. That is not a hypothetical: it was the shipped wiring, and this
- * function exists because of it.
- *
- * `sortColumn` and `sortDirection` are emitted as a pair or not at all, so the
- * half-controlled sort (a direction with no column) cannot be produced here.
- *
- * Same tolerance as the full parser: an unparsable `page`/`size` falls back to
- * the resolved default *for that key* — the key was present, so the axis stays
- * controlled — and malformed filters are skipped individually.
- *
- * @param params - Search params to read (not mutated).
- * @param options - Fallback defaults + key prefix.
- * @returns Only the axes present in `params`.
- */
-export function searchParamsToTableViewState(params, options = {}) {
-    const d = resolveDefaults(options.defaults);
-    const k = paramKeys(options.prefix ?? '');
-    const view = {};
-    const rawPage = params.get(k.page);
-    if (rawPage !== null)
-        view.page = parsePositiveInt(rawPage) ?? d.page;
-    const rawSize = params.get(k.size);
-    if (rawSize !== null)
-        view.itemsPerPage = parsePositiveInt(rawSize) ?? d.itemsPerPage;
-    const rawSort = params.get(k.sort);
-    if (rawSort !== null) {
-        view.sortColumn = rawSort;
-        view.sortDirection = rawSort !== '' && params.get(k.dir) === 'desc' ? 'desc' : 'asc';
-    }
-    const rawSearch = params.get(k.q);
-    if (rawSearch !== null)
-        view.searchTerm = rawSearch;
-    const rawFilters = params.getAll(k.filter);
-    if (rawFilters.length > 0) {
-        const activeFilters = [];
-        for (const raw of rawFilters) {
-            const filter = parseFilterParam(raw);
-            if (filter)
-                activeFilters.push(filter);
-        }
-        view.activeFilters = activeFilters;
-    }
-    const rawGroup = params.get(k.group);
-    if (rawGroup !== null)
-        view.groupByKey = rawGroup === '' ? null : rawGroup;
-    return view;
-}
 /**
  * Merge a table query into existing search params: all managed keys (`q`,
  * `page`, `size`, `sort`, `dir`, `group`, `filter` — with the configured

package/dist/table-view.d.ts

@@ -0,0 +1,123 @@
+/**
+ * URL (de)serialization for the v8 table view vocabulary (`TableView` from
+ * `@urbicon-ui/table`: search, sort, page, pageSize, filters, groupBy).
+ *
+ * The types in this module are a **structural mirror** of the table package's
+ * view types — deliberately not imported, so this package carries no
+ * dependency on `@urbicon-ui/table`. A type-parity test over there guards the
+ * shapes against drift; `bindViewToUrl` accepts any object shaped like
+ * {@link TableViewLike}, which the real `TableView` is.
+ *
+ * The key scheme is the shipped one (`q`, `page`, `size`, `sort`, `dir`,
+ * `group`, `filter`) — deep links written for v7 keep parsing. The write
+ * side adds one compatible extension: an empty `filter=` marker, analogous
+ * to `sort=`, so a cleared filter set elides like every other axis (the
+ * shipped read side already tolerated it).
+ */
+import { type TableQueryFilter, type TableQueryParams } from './table-query.js';
+/** One of the six view axes. Mirrors `ViewAxis` from `@urbicon-ui/table`. */
+export type TableViewAxis = 'search' | 'sort' | 'page' | 'pageSize' | 'filters' | 'groupBy';
+/** All six view axes, in vocabulary order. */
+export declare const TABLE_VIEW_AXES: readonly TableViewAxis[];
+/** Sort state of a view. Mirrors `ViewSort` from `@urbicon-ui/table`. */
+export interface TableViewSort {
+    /** Column ID to sort by. */
+    column: string;
+    /** Sort direction. */
+    direction: 'asc' | 'desc';
+}
+/**
+ * A fully resolved view state — never `undefined` anywhere. Mirrors
+ * `TableViewSnapshot` from `@urbicon-ui/table`.
+ */
+export interface TableViewSnapshot {
+    search: string;
+    sort: TableViewSort | null;
+    page: number;
+    pageSize: number;
+    filters: TableQueryFilter[];
+    groupBy: string | null;
+}
+/**
+ * The surface {@link bindViewToUrl} needs from a view object — a structural
+ * mirror of the table package's `TableView` class. Field reads are reactive,
+ * field writes count as the reader's own change; `applyExternal` is the
+ * binding write surface, `claimAxes`/`releaseAxes` the fail-loud composition
+ * registry, and `originOf` the per-axis (revision, origin) bookkeeping the
+ * bindings decide by.
+ */
+export interface TableViewLike {
+    readonly defaults: TableViewSnapshot;
+    search: string;
+    sort: TableViewSort | null;
+    page: number;
+    pageSize: number;
+    filters: TableQueryFilter[];
+    groupBy: string | null;
+    applyExternal(partial: Partial<TableViewSnapshot>, origin: 'external' | 'system'): void;
+    claimAxes(kind: 'url' | 'storage', axes: readonly TableViewAxis[]): void;
+    releaseAxes(kind: 'url' | 'storage', axes: readonly TableViewAxis[]): void;
+    markInitApplied(axes: readonly TableViewAxis[]): void;
+    wasInitApplied(axis: TableViewAxis): boolean;
+    originOf(axis: TableViewAxis): {
+        revision: number;
+        origin: 'user' | 'external' | 'system' | 'init';
+    };
+    snapshot(): TableViewSnapshot;
+}
+/** The URL keys a set of axes owns, with the configured prefix applied. */
+export declare function viewAxisKeys(axes: readonly TableViewAxis[], prefix?: string): string[];
+/** The axes a URL names — presence only for params it actually carries. */
+export declare function viewAxesNamedBy(sp: URLSearchParams, prefix?: string): TableViewAxis[];
+/**
+ * Parse search params into a **partial** view snapshot — a key per axis the
+ * URL actually carries, and nothing else. Read tolerant per key: an
+ * unparsable value on a *present* key falls back to the configured default
+ * for that axis (the key was present, so the axis stays claimed), and
+ * malformed filter entries are skipped individually.
+ */
+export declare function searchParamsToViewPartial(sp: URLSearchParams, defaults: Pick<TableViewSnapshot, 'page' | 'pageSize'>, prefix?: string): Partial<TableViewSnapshot>;
+/**
+ * Resolve a full view snapshot from search params: every axis the URL names
+ * comes from the URL, every other one from `defaults` — the same resolution
+ * the URL binding performs at init, for code that has no view (a server
+ * `load`).
+ */
+export declare function searchParamsToViewSnapshot(sp: URLSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableViewSnapshot;
+/**
+ * Project a view snapshot into the wire shape a backend speaks — the same
+ * mapping the table applies before calling a managed `source.query`, so a
+ * server `load` and the table's own fetches send identical field names.
+ */
+export declare function viewSnapshotToTableQuery(snapshot: TableViewSnapshot): TableQueryParams;
+/**
+ * The load-path counterpart of the URL binding: parse search params against
+ * the **view's own defaults** and hand back the query a fetch needs.
+ *
+ * The point is the defaults argument. `searchParamsToTableQuery` takes its
+ * baseline in the wire vocabulary (`itemsPerPage`, `sortColumn`/`sortDirection`,
+ * `groupByKey`) and has no field for filters at all, so a `load` had to keep a
+ * second, differently-spelled copy of what `createTableView({ defaults })`
+ * already says — and could not express a default filter set no matter how it
+ * was written (#157 finding 2). This one takes the very object the view takes:
+ * one spelling, all six axes, so the server cannot resolve an absent param
+ * differently from the client.
+ *
+ * @example
+ * ```ts
+ * // shared with the component that calls createTableView({ defaults })
+ * export const invoiceView = { pageSize: 25, sort: { column: 'date', direction: 'desc' } };
+ *
+ * export const load = async ({ url }) => ({
+ *   initialResult: await fetchInvoices(searchParamsToViewQuery(url.searchParams, invoiceView))
+ * });
+ * ```
+ */
+export declare function searchParamsToViewQuery(sp: URLSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableQueryParams;
+/**
+ * Serialize a snapshot, eliding every axis that equals the defaults — the
+ * elision baseline *is* the view's defaults, structurally. `axes` restricts
+ * the output to a binding's own axes: an unbound axis never reaches the URL,
+ * no matter what the view holds.
+ */
+export declare function viewSnapshotToSearchParams(snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;