@urbicon-ui/sveltekit-utils 8.0.0 → 8.2.0

package/README.md

@@ -57,7 +57,7 @@ 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 View ↔ URL (`url.svelte` + `table-query`)
+## Table View ↔ URL (`url.svelte` + `table-view`)
 
 `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.
 
@@ -87,30 +87,30 @@ The second argument is optional; every option has a default:
 
 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 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.
+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 `searchParamsToViewSnapshot` 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, and it hands back the very shape a managed `source.query` receives.
 
 ```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 { searchParamsToViewQuery } from '@urbicon-ui/sveltekit-utils/table-view';
+import { searchParamsToViewSnapshot } from '@urbicon-ui/sveltekit-utils/table-view';
 import { userView } from './view-defaults';
 
 export const load = async ({ url }) => ({
-  initialResult: await fetchUsers(searchParamsToViewQuery(url.searchParams, userView))
+  initialResult: await fetchUsers(searchParamsToViewSnapshot(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.
+The `./table-query` subpath that used to hold a second copy of this codec — same URL scheme, wire-vocabulary spellings, no field for a default filter set — retired with the vocabulary split it served (#162).
 
 **Design notes**
 
 - **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.
+- **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. `assertValidViewSnapshot` is the strict half: it throws on a structurally invalid view (non-positive page, unknown operator) instead of writing corrupt state, and `applyViewToSearchParams` calls it. `viewSnapshotToSearchParams` deliberately does not — it runs inside the binding on every view change, where a throw would cost the page rather than the URL.
 - **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.
+- **Types** — `TableViewLike`, `TableViewSnapshot` and `TableViewFilter` mirror the table's view object structurally, so this package carries no dependency on `@urbicon-ui/table`. A parity test in the table package (`viewMirror.parity.test.ts`) pins the mirror: the 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`)
 
@@ -211,12 +211,11 @@ export const POST = async ({ request }) => {
 | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.`             | 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 |
+| `./table-view`  | `searchParamsToViewSnapshot`, `searchParamsToViewPartial`, `viewSnapshotToSearchParams`, `applyViewToSearchParams`, `assertValidViewSnapshot`, `viewAxesNamedBy`, `viewAxisKeys`, `TABLE_VIEW_AXES`, `TABLE_VIEW_FILTER_OPERATORS`, `TableViewLike`, 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.
+`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` is SvelteKit-free (it touches no `$app/*`), which is what lets a `load` function and a plain test use it; `./url.svelte` is the half that needs the router.
 
 ## Development
 

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 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,5 +1,4 @@
 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-view.d.ts

@@ -14,7 +14,23 @@
  * 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';
+/**
+ * Filter operators supported by the table. Mirrors `FilterOperator` from
+ * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
+ * params from the URL.
+ */
+export declare const TABLE_VIEW_FILTER_OPERATORS: readonly ["contains", "equals", "startsWith", "endsWith", "greaterThan", "lessThan"];
+/** Filter operator of a view filter. Mirrors `@urbicon-ui/table`. */
+export type TableViewFilterOperator = (typeof TABLE_VIEW_FILTER_OPERATORS)[number];
+/** Single column filter on the `filters` axis. Mirrors `Filter` from `@urbicon-ui/table`. */
+export interface TableViewFilter {
+    /** Column ID the filter applies to. */
+    column: string;
+    /** Filter operator. */
+    operator: TableViewFilterOperator;
+    /** Filter value (always a string, numeric operators convert internally). */
+    value: string;
+}
 /** 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. */
@@ -35,7 +51,7 @@ export interface TableViewSnapshot {
     sort: TableViewSort | null;
     page: number;
     pageSize: number;
-    filters: TableQueryFilter[];
+    filters: TableViewFilter[];
     groupBy: string | null;
 }
 /**
@@ -52,7 +68,7 @@ export interface TableViewLike {
     sort: TableViewSort | null;
     page: number;
     pageSize: number;
-    filters: TableQueryFilter[];
+    filters: TableViewFilter[];
     groupBy: string | null;
     applyExternal(partial: Partial<TableViewSnapshot>, origin: 'external' | 'system'): void;
     claimAxes(kind: 'url' | 'storage', axes: readonly TableViewAxis[]): void;
@@ -82,26 +98,19 @@ export declare function searchParamsToViewPartial(sp: URLSearchParams, defaults:
  * 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.
+ * This is also what a server `load` hands its fetch. Since v9 the view and
+ * the query speak one vocabulary (#162), so there is nothing to project on
+ * the way out: the object below is the same shape a managed `source.query`
+ * receives. The `searchParamsToViewQuery` / `viewSnapshotToTableQuery` pair
+ * that used to do the projecting were identity functions once the names
+ * agreed, and are gone.
+ *
+ * The `defaults` argument is the point: it takes the very object
+ * `createTableView({ defaults })` takes, so the server cannot resolve an
+ * absent param differently from the client — and a default filter set is
+ * expressible, which the old wire-vocabulary baseline could not manage no
+ * matter how it was written (#157 finding 2).
  *
  * @example
  * ```ts
@@ -109,11 +118,11 @@ export declare function viewSnapshotToTableQuery(snapshot: TableViewSnapshot): T
  * export const invoiceView = { pageSize: 25, sort: { column: 'date', direction: 'desc' } };
  *
  * export const load = async ({ url }) => ({
- *   initialResult: await fetchInvoices(searchParamsToViewQuery(url.searchParams, invoiceView))
+ *   initialResult: await fetchInvoices(searchParamsToViewSnapshot(url.searchParams, invoiceView))
  * });
  * ```
  */
-export declare function searchParamsToViewQuery(sp: URLSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableQueryParams;
+export declare function searchParamsToViewSnapshot(sp: URLSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableViewSnapshot;
 /**
  * Serialize a snapshot, eliding every axis that equals the defaults — the
  * elision baseline *is* the view's defaults, structurally. `axes` restricts
@@ -121,3 +130,34 @@ export declare function searchParamsToViewQuery(sp: URLSearchParams, defaults?:
  * no matter what the view holds.
  */
 export declare function viewSnapshotToSearchParams(snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;
+/**
+ * Write-side validation: never serialize structurally invalid state.
+ *
+ * The strict half of the module's read-tolerant / write-strict contract, and
+ * deliberately NOT called by {@link viewSnapshotToSearchParams}: that one runs
+ * inside the URL binding on every view change, where a throw would take the
+ * whole table down over a `view.page = 0` a consumer wrote. Serializing a bad
+ * page there costs a wrong URL; throwing there costs the page.
+ *
+ * @throws TypeError when an axis holds a value the URL scheme cannot mean.
+ */
+export declare function assertValidViewSnapshot(snapshot: TableViewSnapshot): void;
+/**
+ * Merge a view into existing search params: every key the given axes own is
+ * replaced by the serialized snapshot, and every other param is preserved
+ * untouched. Keys whose axis returned to its default are removed (the same
+ * elision {@link viewSnapshotToSearchParams} applies).
+ *
+ * This is the one thing the axis-scoped serializer cannot do on its own —
+ * everything else the retired `./table-query` module offered was the same
+ * codec under wire-vocabulary names (#162).
+ *
+ * @param existing - Current search params (not mutated — a copy is returned).
+ * @param snapshot - The view state to write.
+ * @param defaults - Elision baseline, structurally the view's own defaults.
+ * @param axes - Axes to write; every other axis is left alone in `existing`.
+ * @param prefix - Key prefix, to namespace multiple synced tables on a page.
+ * @returns New `URLSearchParams` with the view applied.
+ * @throws TypeError when the snapshot is structurally invalid (write strict).
+ */
+export declare function applyViewToSearchParams(existing: URLSearchParams, snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;

package/dist/table-view.js

@@ -14,7 +14,19 @@
  * to `sort=`, so a cleared filter set elides like every other axis (the
  * shipped read side already tolerated it).
  */
-import { TABLE_QUERY_FILTER_OPERATORS } from './table-query.js';
+/**
+ * Filter operators supported by the table. Mirrors `FilterOperator` from
+ * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
+ * params from the URL.
+ */
+export const TABLE_VIEW_FILTER_OPERATORS = [
+    'contains',
+    'equals',
+    'startsWith',
+    'endsWith',
+    'greaterThan',
+    'lessThan'
+];
 /** All six view axes, in vocabulary order. */
 export const TABLE_VIEW_AXES = [
     'search',
@@ -38,9 +50,9 @@ export function viewAxisKeys(axes, prefix = '') {
     return axes.flatMap((axis) => AXIS_KEYS[axis].map((key) => `${prefix}${key}`));
 }
 function isFilterOperator(value) {
-    return TABLE_QUERY_FILTER_OPERATORS.includes(value);
+    return TABLE_VIEW_FILTER_OPERATORS.includes(value);
 }
-/** Same per-entry tolerance as the table-query parser: malformed → null → skipped. */
+/** Per-entry tolerance: a malformed entry becomes null and the caller skips it. */
 function parseFilterParam(raw) {
     const parts = raw.split(':');
     if (parts.length !== 3)
@@ -126,64 +138,55 @@ export function searchParamsToViewPartial(sp, defaults, prefix = '') {
  * 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`).
+ *
+ * This is also what a server `load` hands its fetch. Since v9 the view and
+ * the query speak one vocabulary (#162), so there is nothing to project on
+ * the way out: the object below is the same shape a managed `source.query`
+ * receives. The `searchParamsToViewQuery` / `viewSnapshotToTableQuery` pair
+ * that used to do the projecting were identity functions once the names
+ * agreed, and are gone.
+ *
+ * The `defaults` argument is the point: it takes the very object
+ * `createTableView({ defaults })` takes, so the server cannot resolve an
+ * absent param differently from the client — and a default filter set is
+ * expressible, which the old wire-vocabulary baseline could not manage no
+ * matter how it was written (#157 finding 2).
+ *
+ * @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(searchParamsToViewSnapshot(url.searchParams, invoiceView))
+ * });
+ * ```
  */
 export function searchParamsToViewSnapshot(sp, defaults = {}, prefix = '') {
     const resolved = resolveViewDefaults(defaults);
     return { ...resolved, ...searchParamsToViewPartial(sp, resolved, prefix) };
 }
-/** Fill an unset axis with the table's own default — never `undefined` anywhere. */
+/**
+ * Fill an unset axis with the table's own default — never `undefined`
+ * anywhere.
+ *
+ * The two composite axes are copied for the same reason `TableView`'s
+ * constructor copies them: the documented `load` pattern shares ONE defaults
+ * object between the server and the component (a module-scope
+ * `export const invoiceView = …`). Handing a caller's array straight back out
+ * means a `load` that sorts or normalises the snapshot in place poisons that
+ * shared constant for every later request on the same server process.
+ */
 function resolveViewDefaults(defaults) {
     return {
         search: defaults.search ?? '',
-        sort: defaults.sort ?? null,
+        sort: defaults.sort ? { ...defaults.sort } : null,
         page: defaults.page ?? 1,
         pageSize: defaults.pageSize ?? 10,
-        filters: defaults.filters ?? [],
+        filters: defaults.filters ? [...defaults.filters] : [],
         groupBy: defaults.groupBy || null
     };
 }
-/**
- * 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 function viewSnapshotToTableQuery(snapshot) {
-    return {
-        page: snapshot.page,
-        itemsPerPage: snapshot.pageSize,
-        sortColumn: snapshot.sort?.column ?? '',
-        sortDirection: snapshot.sort?.direction ?? 'asc',
-        searchTerm: snapshot.search,
-        activeFilters: [...snapshot.filters],
-        groupByKey: snapshot.groupBy
-    };
-}
-/**
- * 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 function searchParamsToViewQuery(sp, defaults = {}, prefix = '') {
-    return viewSnapshotToTableQuery(searchParamsToViewSnapshot(sp, defaults, prefix));
-}
 /**
  * Serialize a snapshot, eliding every axis that equals the defaults — the
  * elision baseline *is* the view's defaults, structurally. `axes` restricts
@@ -239,3 +242,71 @@ export function viewSnapshotToSearchParams(snapshot, defaults, axes = TABLE_VIEW
     }
     return sp;
 }
+/**
+ * Write-side validation: never serialize structurally invalid state.
+ *
+ * The strict half of the module's read-tolerant / write-strict contract, and
+ * deliberately NOT called by {@link viewSnapshotToSearchParams}: that one runs
+ * inside the URL binding on every view change, where a throw would take the
+ * whole table down over a `view.page = 0` a consumer wrote. Serializing a bad
+ * page there costs a wrong URL; throwing there costs the page.
+ *
+ * @throws TypeError when an axis holds a value the URL scheme cannot mean.
+ */
+export function assertValidViewSnapshot(snapshot) {
+    if (!Number.isSafeInteger(snapshot.page) || snapshot.page < 1) {
+        throw new TypeError(`[table-view] page must be a positive integer, got ${snapshot.page}`);
+    }
+    if (!Number.isSafeInteger(snapshot.pageSize) || snapshot.pageSize < 1) {
+        throw new TypeError(`[table-view] pageSize must be a positive integer, got ${snapshot.pageSize}`);
+    }
+    if (snapshot.sort !== null) {
+        if (!snapshot.sort.column) {
+            throw new TypeError('[table-view] sort.column must be a non-empty string, or sort must be null');
+        }
+        if (snapshot.sort.direction !== 'asc' && snapshot.sort.direction !== 'desc') {
+            throw new TypeError(`[table-view] sort.direction must be 'asc' or 'desc', got ${String(snapshot.sort.direction)}`);
+        }
+    }
+    if (snapshot.groupBy === '') {
+        throw new TypeError("[table-view] groupBy must be a non-empty string or null, got ''");
+    }
+    for (const filter of snapshot.filters) {
+        if (!filter.column) {
+            throw new TypeError('[table-view] filter.column must be a non-empty string');
+        }
+        if (!isFilterOperator(filter.operator)) {
+            throw new TypeError(`[table-view] unknown filter operator '${String(filter.operator)}' on column '${filter.column}'`);
+        }
+    }
+}
+/**
+ * Merge a view into existing search params: every key the given axes own is
+ * replaced by the serialized snapshot, and every other param is preserved
+ * untouched. Keys whose axis returned to its default are removed (the same
+ * elision {@link viewSnapshotToSearchParams} applies).
+ *
+ * This is the one thing the axis-scoped serializer cannot do on its own —
+ * everything else the retired `./table-query` module offered was the same
+ * codec under wire-vocabulary names (#162).
+ *
+ * @param existing - Current search params (not mutated — a copy is returned).
+ * @param snapshot - The view state to write.
+ * @param defaults - Elision baseline, structurally the view's own defaults.
+ * @param axes - Axes to write; every other axis is left alone in `existing`.
+ * @param prefix - Key prefix, to namespace multiple synced tables on a page.
+ * @returns New `URLSearchParams` with the view applied.
+ * @throws TypeError when the snapshot is structurally invalid (write strict).
+ */
+export function applyViewToSearchParams(existing, snapshot, defaults, axes = TABLE_VIEW_AXES, prefix = '') {
+    assertValidViewSnapshot(snapshot);
+    const serialized = viewSnapshotToSearchParams(snapshot, defaults, axes, prefix);
+    const next = new URLSearchParams(existing);
+    for (const key of viewAxisKeys(axes, prefix)) {
+        next.delete(key);
+    }
+    for (const [key, value] of serialized) {
+        next.append(key, value);
+    }
+    return next;
+}

package/dist/url.svelte.js

@@ -8,7 +8,7 @@ import { page } from '$app/state';
 // root's star exports ambiguous and silently drop them. The v7
 // `createTableQueryUrlSync` factory is gone with the table's `query` prop —
 // the URL home of a table view is `bindViewToUrl`; the load-path serializers
-// (`searchParamsToTableQuery` & friends) live on in `table-query`.
+// (`searchParamsToViewSnapshot` & friends) live in `table-view`.
 export { bindViewToUrl } from './view-binding.svelte.js';
 /**
  * Low-level escape hatch to update several params at once via `goto` (without a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "8.0.0",
+  "version": "8.2.0",
   "description": "SvelteKit helper utilities — createCronRunner, streamSse, and URL-state runes",
   "license": "MIT",
   "repository": {
@@ -47,11 +47,6 @@
       "import": "./dist/sse.js",
       "default": "./dist/sse.js"
     },
-    "./table-query": {
-      "types": "./dist/table-query.d.ts",
-      "import": "./dist/table-query.js",
-      "default": "./dist/table-query.js"
-    },
     "./table-view": {
       "types": "./dist/table-view.d.ts",
       "import": "./dist/table-view.js",
@@ -83,14 +78,14 @@
   "devDependencies": {
     "@sveltejs/kit": "^2.70.2",
     "@sveltejs/package": "^2.5.8",
-    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "prettier": "^3.9.6",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "svelte": "^5.56.8",
-    "svelte-check": "^4.7.4",
+    "svelte-check": "^4.7.5",
     "typescript": "^6.0.3",
-    "vite": "^8.2.0",
+    "vite": "^8.2.1",
     "vitest": "^4.1.9"
   }
 }

package/dist/table-query.d.ts

@@ -1,158 +0,0 @@
-/**
- * URL (de)serialization for the query state a data table emits in server mode
- * (`TableQuery` from `@urbicon-ui/table`: page, page size, sort, search term,
- * column filters, grouping).
- *
- * The types in this module are a **structural mirror** of `TableQuery` — they
- * are deliberately not imported from `@urbicon-ui/table`, so this package
- * carries no dependency on the table package. Any object shaped like
- * `TableQuery` is accepted; a type-parity test in `@urbicon-ui/table` guards
- * the two shapes against drift.
- *
- * Serialization contract:
- * - **Deterministic** — fixed key order (`q`, `page`, `size`, `sort`, `dir`,
- *   `group`, `filter`), stable filter order.
- * - **Default elision** — values equal to the resolved defaults are not
- *   written; a table in its default state produces an empty query string.
- * - **Read tolerant** — unparsable params fall back to the defaults, and
- *   malformed filter entries are skipped.
- * - **Write strict** — a structurally invalid query (non-positive page,
- *   unknown filter operator, …) throws instead of writing corrupt state.
- */
-/** Sort direction of a table query. Mirrors `@urbicon-ui/table`. */
-export type TableQuerySortDirection = 'asc' | 'desc';
-/**
- * Filter operators supported by the table. Mirrors `FilterOperator` from
- * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
- * params from the URL.
- */
-export declare const TABLE_QUERY_FILTER_OPERATORS: readonly ["contains", "equals", "startsWith", "endsWith", "greaterThan", "lessThan"];
-/** Filter operator of a table query filter. Mirrors `@urbicon-ui/table`. */
-export type TableQueryFilterOperator = (typeof TABLE_QUERY_FILTER_OPERATORS)[number];
-/** Single column filter of a table query. Mirrors `Filter` from `@urbicon-ui/table`. */
-export interface TableQueryFilter {
-    /** Column ID the filter applies to. */
-    column: string;
-    /** Filter operator. */
-    operator: TableQueryFilterOperator;
-    /** Filter value (always a string, numeric operators convert internally). */
-    value: string;
-}
-/**
- * Query state of a table in server mode. Structural mirror of `TableQuery`
- * from `@urbicon-ui/table` — the object a managed `source.query` receives
- * (or `viewToQuery` projects) is directly assignable.
- */
-export interface TableQueryParams {
-    /** Current page (1-based). */
-    page: number;
-    /** Number of items per page. */
-    itemsPerPage: number;
-    /** Column ID to sort by, or empty string if no sort is active. */
-    sortColumn: string;
-    /** Sort direction. */
-    sortDirection: TableQuerySortDirection;
-    /** Full-text search term. */
-    searchTerm: string;
-    /** Active column filters. */
-    activeFilters: TableQueryFilter[];
-    /** Column ID for grouping, or null if 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.
- *
- * 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 */
-    page?: number;
-    /** Default page size. @default 10 */
-    itemsPerPage?: number;
-    /** Default sort column ('' = unsorted). @default '' */
-    sortColumn?: string;
-    /** Default sort direction. @default 'asc' */
-    sortDirection?: TableQuerySortDirection;
-    /** Default search term. @default '' */
-    searchTerm?: string;
-    /** Default group key (null = ungrouped). @default null */
-    groupByKey?: string | null;
-}
-/** Options shared by the table-query (de)serializers. */
-export interface TableQueryUrlOptions {
-    /** Elision baseline — see {@link TableQueryDefaults}. */
-    defaults?: TableQueryDefaults;
-    /**
-     * Prefix for every param key (`prefix: 't_'` → `?t_q=…&t_page=…`). Use it
-     * to namespace multiple synced tables on the same page.
-     * @default ''
-     */
-    prefix?: string;
-}
-/**
- * Serialize a table query into `URLSearchParams`, eliding every value that
- * equals the resolved defaults (see {@link TableQueryDefaults}).
- *
- * Key scheme (each key optionally prefixed via `options.prefix`):
- * - `q` — search term
- * - `page` — 1-based page
- * - `size` — items per page
- * - `sort` — sort column; an **empty** `sort=` marks "explicitly unsorted"
- *   and is only written when the defaults specify a sort column
- * - `dir` — `desc` (ascending is implied when absent)
- * - `group` — group key; an empty `group=` marks "explicitly ungrouped"
- * - `filter` — repeated, `<column>:<operator>:<value>` with column and value
- *   URI-component-encoded so the `:` separators stay unambiguous
- *
- * 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 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.
- * @returns Fresh `URLSearchParams` containing only non-default values.
- * @throws TypeError when the query is structurally invalid (write strict).
- */
-export declare function tableQueryToSearchParams(query: TableQueryParams, options?: TableQueryUrlOptions): URLSearchParams;
-/**
- * Parse `URLSearchParams` back into a full table query, filling every missing
- * param from the resolved defaults (see {@link TableQueryDefaults}).
- *
- * Read tolerant: non-numeric `page`/`size` fall back to the defaults, an
- * unknown `dir` becomes `'asc'`, and malformed `filter` entries (wrong shape,
- * unknown operator, broken percent-encoding) are skipped individually.
- *
- * 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;
-/**
- * Merge a table query into existing search params: all managed keys (`q`,
- * `page`, `size`, `sort`, `dir`, `group`, `filter` — with the configured
- * prefix) are replaced by the serialized query, every other param is
- * preserved untouched. Managed keys whose value returned to the default are
- * removed (default elision).
- *
- * @param existing - Current search params (not mutated — a copy is returned).
- * @param query - Query emitted by the table.
- * @param options - Elision defaults + key prefix.
- * @returns New `URLSearchParams` with the query applied.
- * @throws TypeError when the query is structurally invalid (write strict).
- */
-export declare function applyTableQueryToSearchParams(existing: URLSearchParams, query: TableQueryParams, options?: TableQueryUrlOptions): URLSearchParams;

package/dist/table-query.js

@@ -1,235 +0,0 @@
-/**
- * URL (de)serialization for the query state a data table emits in server mode
- * (`TableQuery` from `@urbicon-ui/table`: page, page size, sort, search term,
- * column filters, grouping).
- *
- * The types in this module are a **structural mirror** of `TableQuery` — they
- * are deliberately not imported from `@urbicon-ui/table`, so this package
- * carries no dependency on the table package. Any object shaped like
- * `TableQuery` is accepted; a type-parity test in `@urbicon-ui/table` guards
- * the two shapes against drift.
- *
- * Serialization contract:
- * - **Deterministic** — fixed key order (`q`, `page`, `size`, `sort`, `dir`,
- *   `group`, `filter`), stable filter order.
- * - **Default elision** — values equal to the resolved defaults are not
- *   written; a table in its default state produces an empty query string.
- * - **Read tolerant** — unparsable params fall back to the defaults, and
- *   malformed filter entries are skipped.
- * - **Write strict** — a structurally invalid query (non-positive page,
- *   unknown filter operator, …) throws instead of writing corrupt state.
- */
-/**
- * Filter operators supported by the table. Mirrors `FilterOperator` from
- * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
- * params from the URL.
- */
-export const TABLE_QUERY_FILTER_OPERATORS = [
-    'contains',
-    'equals',
-    'startsWith',
-    'endsWith',
-    'greaterThan',
-    'lessThan'
-];
-/** Resolved param key names for one prefix. */
-function paramKeys(prefix) {
-    return {
-        q: `${prefix}q`,
-        page: `${prefix}page`,
-        size: `${prefix}size`,
-        sort: `${prefix}sort`,
-        dir: `${prefix}dir`,
-        group: `${prefix}group`,
-        filter: `${prefix}filter`
-    };
-}
-function resolveDefaults(defaults) {
-    return {
-        page: defaults?.page ?? 1,
-        itemsPerPage: defaults?.itemsPerPage ?? 10,
-        sortColumn: defaults?.sortColumn ?? '',
-        sortDirection: defaults?.sortDirection ?? 'asc',
-        searchTerm: defaults?.searchTerm ?? '',
-        groupByKey: defaults?.groupByKey ?? null
-    };
-}
-function isFilterOperator(value) {
-    return TABLE_QUERY_FILTER_OPERATORS.includes(value);
-}
-/** Write-side validation: never serialize structurally invalid state. */
-function assertValidQuery(query) {
-    if (!Number.isSafeInteger(query.page) || query.page < 1) {
-        throw new TypeError(`[table-query] page must be a positive integer, got ${query.page}`);
-    }
-    if (!Number.isSafeInteger(query.itemsPerPage) || query.itemsPerPage < 1) {
-        throw new TypeError(`[table-query] itemsPerPage must be a positive integer, got ${query.itemsPerPage}`);
-    }
-    if (query.sortDirection !== 'asc' && query.sortDirection !== 'desc') {
-        throw new TypeError(`[table-query] sortDirection must be 'asc' or 'desc', got ${String(query.sortDirection)}`);
-    }
-    if (query.groupByKey === '') {
-        throw new TypeError("[table-query] groupByKey must be a non-empty string or null, got ''");
-    }
-    for (const filter of query.activeFilters) {
-        if (!filter.column) {
-            throw new TypeError('[table-query] filter.column must be a non-empty string');
-        }
-        if (!isFilterOperator(filter.operator)) {
-            throw new TypeError(`[table-query] unknown filter operator '${String(filter.operator)}' on column '${filter.column}'`);
-        }
-    }
-}
-/** Read-side tolerant integer parsing: anything non-numeric → null. */
-function parsePositiveInt(raw) {
-    if (raw === null || !/^\d+$/.test(raw))
-        return null;
-    const value = Number(raw);
-    return Number.isSafeInteger(value) && value >= 1 ? value : null;
-}
-/**
- * Parse one `filter` param value (`<column>:<operator>:<value>`, column and
- * value URI-component-encoded). Returns null for malformed entries — the
- * caller skips them (read tolerant).
- */
-function parseFilterParam(raw) {
-    const parts = raw.split(':');
-    if (parts.length !== 3)
-        return null;
-    const [encodedColumn, operator, encodedValue] = parts;
-    if (!isFilterOperator(operator))
-        return null;
-    try {
-        const column = decodeURIComponent(encodedColumn);
-        if (!column)
-            return null;
-        return { column, operator, value: decodeURIComponent(encodedValue) };
-    }
-    catch {
-        // Malformed percent-encoding (URIError) — skip the entry.
-        return null;
-    }
-}
-/**
- * Serialize a table query into `URLSearchParams`, eliding every value that
- * equals the resolved defaults (see {@link TableQueryDefaults}).
- *
- * Key scheme (each key optionally prefixed via `options.prefix`):
- * - `q` — search term
- * - `page` — 1-based page
- * - `size` — items per page
- * - `sort` — sort column; an **empty** `sort=` marks "explicitly unsorted"
- *   and is only written when the defaults specify a sort column
- * - `dir` — `desc` (ascending is implied when absent)
- * - `group` — group key; an empty `group=` marks "explicitly ungrouped"
- * - `filter` — repeated, `<column>:<operator>:<value>` with column and value
- *   URI-component-encoded so the `:` separators stay unambiguous
- *
- * 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 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.
- * @returns Fresh `URLSearchParams` containing only non-default values.
- * @throws TypeError when the query is structurally invalid (write strict).
- */
-export function tableQueryToSearchParams(query, options = {}) {
-    assertValidQuery(query);
-    const d = resolveDefaults(options.defaults);
-    const k = paramKeys(options.prefix ?? '');
-    const sp = new URLSearchParams();
-    if (query.searchTerm !== d.searchTerm)
-        sp.set(k.q, query.searchTerm);
-    if (query.page !== d.page)
-        sp.set(k.page, String(query.page));
-    if (query.itemsPerPage !== d.itemsPerPage)
-        sp.set(k.size, String(query.itemsPerPage));
-    if (query.sortColumn === '') {
-        // Unsorted: only mark explicitly when the defaults would re-introduce a sort.
-        if (d.sortColumn !== '')
-            sp.set(k.sort, '');
-    }
-    else if (query.sortColumn !== d.sortColumn || query.sortDirection !== d.sortDirection) {
-        sp.set(k.sort, query.sortColumn);
-        if (query.sortDirection === 'desc')
-            sp.set(k.dir, 'desc');
-    }
-    if (query.groupByKey !== d.groupByKey)
-        sp.set(k.group, query.groupByKey ?? '');
-    for (const filter of query.activeFilters) {
-        sp.append(k.filter, `${encodeURIComponent(filter.column)}:${filter.operator}:${encodeURIComponent(filter.value)}`);
-    }
-    return sp;
-}
-/**
- * Parse `URLSearchParams` back into a full table query, filling every missing
- * param from the resolved defaults (see {@link TableQueryDefaults}).
- *
- * Read tolerant: non-numeric `page`/`size` fall back to the defaults, an
- * unknown `dir` becomes `'asc'`, and malformed `filter` entries (wrong shape,
- * unknown operator, broken percent-encoding) are skipped individually.
- *
- * 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 function searchParamsToTableQuery(params, options = {}) {
-    const d = resolveDefaults(options.defaults);
-    const k = paramKeys(options.prefix ?? '');
-    let sortColumn = d.sortColumn;
-    let sortDirection = d.sortDirection;
-    const rawSort = params.get(k.sort);
-    if (rawSort !== null) {
-        sortColumn = rawSort;
-        sortDirection = rawSort !== '' && params.get(k.dir) === 'desc' ? 'desc' : 'asc';
-    }
-    const rawGroup = params.get(k.group);
-    const activeFilters = [];
-    for (const raw of params.getAll(k.filter)) {
-        const filter = parseFilterParam(raw);
-        if (filter)
-            activeFilters.push(filter);
-    }
-    return {
-        page: parsePositiveInt(params.get(k.page)) ?? d.page,
-        itemsPerPage: parsePositiveInt(params.get(k.size)) ?? d.itemsPerPage,
-        sortColumn,
-        sortDirection,
-        searchTerm: params.get(k.q) ?? d.searchTerm,
-        activeFilters,
-        groupByKey: rawGroup !== null ? (rawGroup === '' ? null : rawGroup) : d.groupByKey
-    };
-}
-/**
- * Merge a table query into existing search params: all managed keys (`q`,
- * `page`, `size`, `sort`, `dir`, `group`, `filter` — with the configured
- * prefix) are replaced by the serialized query, every other param is
- * preserved untouched. Managed keys whose value returned to the default are
- * removed (default elision).
- *
- * @param existing - Current search params (not mutated — a copy is returned).
- * @param query - Query emitted by the table.
- * @param options - Elision defaults + key prefix.
- * @returns New `URLSearchParams` with the query applied.
- * @throws TypeError when the query is structurally invalid (write strict).
- */
-export function applyTableQueryToSearchParams(existing, query, options = {}) {
-    const serialized = tableQueryToSearchParams(query, options);
-    const next = new URLSearchParams(existing);
-    for (const key of Object.values(paramKeys(options.prefix ?? ''))) {
-        next.delete(key);
-    }
-    for (const [key, value] of serialized) {
-        next.append(key, value);
-    }
-    return next;
-}