@urbicon-ui/sveltekit-utils 6.51.0 → 7.0.1

package/README.md

@@ -59,7 +59,7 @@ updateUrlSearchParams({ page: '1', tag: ['a', 'b'] }, { replaceState: true });
 
 ## Table Query ↔ URL (`table-query` + `url.svelte`)
 
-Opt-in URL sync for `@urbicon-ui/table` in `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 and can be shared as a link.
+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.
 
 ```svelte
 <script lang="ts">
@@ -74,12 +74,7 @@ Opt-in URL sync for `@urbicon-ui/table` in `mode="server"`: the `TableQuery` the
   mode="server"
   {columns}
   itemsPerPage={25}
-  initialPage={sync.initialQuery.page}
-  initialGroupBy={sync.initialQuery.groupByKey}
-  initialSort={sync.initialQuery.sortColumn
-    ? { column: sync.initialQuery.sortColumn, direction: sync.initialQuery.sortDirection }
-    : undefined}
-  initialFilters={sync.initialQuery.activeFilters}
+  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 });
@@ -89,6 +84,12 @@ Opt-in URL sync for `@urbicon-ui/table` in `mode="server"`: the `TableQuery` the
 />
 ```
 
+`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.
+
+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.
+
+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.
+
 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`.
 
 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:
@@ -109,7 +110,7 @@ export const load = async ({ url }) => {
 - **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.
+- **Seeding, the variant without `query`** — every axis the URL carries can also be handed to the table as a seed: `initialPage`, `initialGroupBy`, `initialSort`, `initialFilters` (plus a 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. Its precedence is the **inverse** of `query`'s, and that is the reason to prefer `query`: an `initial*` prop seeds only an axis `persistenceConfig` has nothing stored for, so with both active a persisted sort/filter/group beats the link — including a persisted _empty_ value (the user cleared that axis once, so it stays cleared). The seeds do reach the server-rendered HTML — they are applied during construction, which runs under SSR too (measured: `initialSort`, `initialFilters`, `initialGroupBy` and `initialPage` all land in the server markup; only a controlled `searchTerm`, applied in an effect, does not). What they lack is the per-axis precedence above and any reaction to the back button, since a seed is read once. Use them only where the axis must not be controlled; otherwise `query={sync.viewState}` (+ `persistControlled` when the reader's own state should outlive the link).
 
 ## Cron Runner (`cron`)
 

package/dist/table-query.d.ts

@@ -59,6 +59,31 @@ 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.
@@ -136,6 +161,33 @@ export declare function tableQueryToSearchParams(query: TableQueryParams, option
  * @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

@@ -206,6 +206,65 @@ 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/url.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type TableQueryParams, type TableQueryUrlOptions } from './table-query.js';
+import { type TableQueryParams, type TableQueryUrlOptions, type TableQueryViewState } from './table-query.js';
 /**
  * How {@link useUrlArrayParam} maps an array onto the URL:
  * - `repeat` — one entry per key: `?tag=a&tag=b`
@@ -145,17 +145,20 @@ export interface TableQueryUrlSyncOptions extends TableQueryUrlOptions {
     replaceState?: boolean;
 }
 /**
- * Opt-in URL sync for a table in server mode: mirrors the `TableQuery` the
- * table emits onto `?q=…&sort=…&page=…` query params, so the view state
- * survives reloads and can be shared as a link.
+ * Opt-in URL sync for a table: mirrors the `TableQuery` the table emits onto
+ * `?q=…&sort=…&page=…` query params, so the view state survives reloads, can
+ * be shared as a link, and — unlike `localStorage` — is visible to the server.
+ * Works in client mode as well as server mode; the table emits its query in
+ * both.
  *
  * Two directions, both explicit:
- * - **URL → query**: `initialQuery` is parsed once at creation (SSR-safe) —
- *   seed the table (`initialPage`, `initialGroupBy`, `initialSort`,
- *   `initialFilters`, controlled `searchTerm`) and run the first fetch from
- *   it. The seeds land before the table's first query emission, so URL sort/
- *   filter params survive it; note that a value restored via the table's
- *   `persistenceConfig` wins over an `initial*` seed for its axis.
+ * - **URL → query**: `viewState` carries the axes the URL actually names, and
+ *   re-reads the URL on every navigation. Hand it to the table's `query` prop,
+ *   which controls exactly those axes — per field, and ahead of both
+ *   `persistenceConfig` and the `initial*` seeds. Because a controlled axis is
+ *   a derived rather than a write, it resolves during server rendering too,
+ *   which is the point: the server renders the view the link asked for instead
+ *   of a default one the client swaps out on hydration.
  * - **query → URL**: pass `syncQuery` the query from `onQueryChange`, or call
  *   it inside `queryFn` (when `queryFn` is set, `onQueryChange` does not
  *   fire). It rewrites only its own — optionally prefixed — params via
@@ -167,7 +170,7 @@ export interface TableQueryUrlSyncOptions extends TableQueryUrlOptions {
  * `initialPage`, `initialGroupBy`) so the elision baseline matches the state
  * the table actually starts in.
  *
- * @example
+ * @example Client mode — the whole wiring is two props
  * ```svelte
  * <script lang="ts">
  *   import { Table } from '@urbicon-ui/table';
@@ -176,11 +179,32 @@ export interface TableQueryUrlSyncOptions extends TableQueryUrlOptions {
  *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
  * </script>
  *
+ * <Table {items} {columns} query={sync.viewState} onQueryChange={sync.syncQuery} />
+ * ```
+ *
+ * `query` is a *controlled* prop, which is what makes this work on the server:
+ * the URL is parsed during SSR and the table renders the linked view rather
+ * than an unfiltered one the client then replaces. It also outranks
+ * `persistenceConfig` per axis, so there is no longer a caveat about a stored
+ * value beating the link.
+ *
+ * Pass `viewState`, never `initialQuery`. `initialQuery` describes **every**
+ * axis, so as a `query` value it claims every axis — including the ones the URL
+ * says nothing about, whose values it filled in from the defaults. A table
+ * wired that way ignores `persistenceConfig`, `initialSort`, `initialFilters`
+ * and `initialGroupBy` entirely, on any URL, and says nothing about it.
+ *
+ * @example Server mode — the same two directions, with the fetch in between
+ * ```svelte
+ * <script lang="ts">
+ *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+ * </script>
+ *
  * <Table
  *   mode="server"
- *   columns={columns}
+ *   {columns}
  *   itemsPerPage={25}
- *   initialPage={sync.initialQuery.page}
+ *   query={sync.viewState}
  *   queryFn={async (query, { signal }) => {
  *     sync.syncQuery(query);
  *     const res = await fetch(`/api/users?${new URLSearchParams(...)}`, { signal });
@@ -191,10 +215,22 @@ export interface TableQueryUrlSyncOptions extends TableQueryUrlOptions {
  * ```
  *
  * @param options - Elision defaults, key prefix, history behaviour.
- * @returns `initialQuery` (the URL parsed at creation time) + `syncQuery`
- *   (write a query back to the URL).
+ * @returns `viewState` (the controlled axes, re-read on every navigation),
+ *   `initialQuery` (a complete snapshot for a fetch) + `syncQuery` (write a
+ *   query back to the URL).
  */
 export declare function createTableQueryUrlSync(options?: TableQueryUrlSyncOptions): {
+    /**
+     * The axes the URL names, re-read on every navigation.
+     *
+     * A getter, not a captured value: `createTableQueryUrlSync` runs once per
+     * page component, and SvelteKit does not remount that component when only
+     * the query string changes. A snapshot would therefore never see the back
+     * button — the table would stay sorted after the user navigated back to a
+     * URL with no sort param. Reading `page.url` here makes every consumer of
+     * this getter a reader of SvelteKit's own reactive page state.
+     */
+    readonly viewState: TableQueryViewState;
     readonly initialQuery: TableQueryParams;
     readonly syncQuery: (query: TableQueryParams) => void;
 };

package/dist/url.svelte.js

@@ -1,7 +1,7 @@
 import { building } from '$app/environment';
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
-import { applyTableQueryToSearchParams, searchParamsToTableQuery } from './table-query.js';
+import { applyTableQueryToSearchParams, searchParamsToTableQuery, searchParamsToTableViewState } from './table-query.js';
 /**
  * Low-level escape hatch to update several params at once via `goto` (without a
  * full navigation). Starts from the current URL, applies `next`, and keeps
@@ -176,17 +176,20 @@ export function useUrlArrayParam(key, opts) {
     return useUrlParam(key, { parse, serialize, initial: opts.initial });
 }
 /**
- * Opt-in URL sync for a table in server mode: mirrors the `TableQuery` the
- * table emits onto `?q=…&sort=…&page=…` query params, so the view state
- * survives reloads and can be shared as a link.
+ * Opt-in URL sync for a table: mirrors the `TableQuery` the table emits onto
+ * `?q=…&sort=…&page=…` query params, so the view state survives reloads, can
+ * be shared as a link, and — unlike `localStorage` — is visible to the server.
+ * Works in client mode as well as server mode; the table emits its query in
+ * both.
  *
  * Two directions, both explicit:
- * - **URL → query**: `initialQuery` is parsed once at creation (SSR-safe) —
- *   seed the table (`initialPage`, `initialGroupBy`, `initialSort`,
- *   `initialFilters`, controlled `searchTerm`) and run the first fetch from
- *   it. The seeds land before the table's first query emission, so URL sort/
- *   filter params survive it; note that a value restored via the table's
- *   `persistenceConfig` wins over an `initial*` seed for its axis.
+ * - **URL → query**: `viewState` carries the axes the URL actually names, and
+ *   re-reads the URL on every navigation. Hand it to the table's `query` prop,
+ *   which controls exactly those axes — per field, and ahead of both
+ *   `persistenceConfig` and the `initial*` seeds. Because a controlled axis is
+ *   a derived rather than a write, it resolves during server rendering too,
+ *   which is the point: the server renders the view the link asked for instead
+ *   of a default one the client swaps out on hydration.
  * - **query → URL**: pass `syncQuery` the query from `onQueryChange`, or call
  *   it inside `queryFn` (when `queryFn` is set, `onQueryChange` does not
  *   fire). It rewrites only its own — optionally prefixed — params via
@@ -198,7 +201,7 @@ export function useUrlArrayParam(key, opts) {
  * `initialPage`, `initialGroupBy`) so the elision baseline matches the state
  * the table actually starts in.
  *
- * @example
+ * @example Client mode — the whole wiring is two props
  * ```svelte
  * <script lang="ts">
  *   import { Table } from '@urbicon-ui/table';
@@ -207,11 +210,32 @@ export function useUrlArrayParam(key, opts) {
  *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
  * </script>
  *
+ * <Table {items} {columns} query={sync.viewState} onQueryChange={sync.syncQuery} />
+ * ```
+ *
+ * `query` is a *controlled* prop, which is what makes this work on the server:
+ * the URL is parsed during SSR and the table renders the linked view rather
+ * than an unfiltered one the client then replaces. It also outranks
+ * `persistenceConfig` per axis, so there is no longer a caveat about a stored
+ * value beating the link.
+ *
+ * Pass `viewState`, never `initialQuery`. `initialQuery` describes **every**
+ * axis, so as a `query` value it claims every axis — including the ones the URL
+ * says nothing about, whose values it filled in from the defaults. A table
+ * wired that way ignores `persistenceConfig`, `initialSort`, `initialFilters`
+ * and `initialGroupBy` entirely, on any URL, and says nothing about it.
+ *
+ * @example Server mode — the same two directions, with the fetch in between
+ * ```svelte
+ * <script lang="ts">
+ *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+ * </script>
+ *
  * <Table
  *   mode="server"
- *   columns={columns}
+ *   {columns}
  *   itemsPerPage={25}
- *   initialPage={sync.initialQuery.page}
+ *   query={sync.viewState}
  *   queryFn={async (query, { signal }) => {
  *     sync.syncQuery(query);
  *     const res = await fetch(`/api/users?${new URLSearchParams(...)}`, { signal });
@@ -222,13 +246,17 @@ export function useUrlArrayParam(key, opts) {
  * ```
  *
  * @param options - Elision defaults, key prefix, history behaviour.
- * @returns `initialQuery` (the URL parsed at creation time) + `syncQuery`
- *   (write a query back to the URL).
+ * @returns `viewState` (the controlled axes, re-read on every navigation),
+ *   `initialQuery` (a complete snapshot for a fetch) + `syncQuery` (write a
+ *   query back to the URL).
  */
 export function createTableQueryUrlSync(options = {}) {
     // Same prerender rule as `useUrlParam`: no query string exists while
-    // building, so the seed parses from empty params instead of throwing.
-    const initialQuery = searchParamsToTableQuery(building ? new URLSearchParams() : page.url.searchParams, options);
+    // building, so both readers parse from empty params instead of throwing.
+    const currentParams = () => (building ? new URLSearchParams() : page.url.searchParams);
+    // Parsed once, on purpose — a snapshot to seed a fetch with, not a source of
+    // truth. `viewState` below is the one the table binds to.
+    const initialQuery = searchParamsToTableQuery(currentParams(), options);
     function syncQuery(query) {
         const next = applyTableQueryToSearchParams(page.url.searchParams, query, options);
         const qs = next.toString();
@@ -238,5 +266,21 @@ export function createTableQueryUrlSync(options = {}) {
             keepFocus: true
         });
     }
-    return { initialQuery, syncQuery };
+    return {
+        /**
+         * The axes the URL names, re-read on every navigation.
+         *
+         * A getter, not a captured value: `createTableQueryUrlSync` runs once per
+         * page component, and SvelteKit does not remount that component when only
+         * the query string changes. A snapshot would therefore never see the back
+         * button — the table would stay sorted after the user navigated back to a
+         * URL with no sort param. Reading `page.url` here makes every consumer of
+         * this getter a reader of SvelteKit's own reactive page state.
+         */
+        get viewState() {
+            return searchParamsToTableViewState(currentParams(), options);
+        },
+        initialQuery,
+        syncQuery
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "6.51.0",
+  "version": "7.0.1",
   "description": "SvelteKit helper utilities — createCronRunner, streamSse, and URL-state runes",
   "license": "MIT",
   "repository": {