@urbicon-ui/sveltekit-utils 6.21.2 → 6.22.0

package/README.md

@@ -5,6 +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
 - **Cron runner** — interval-based background fetcher for scheduled server endpoints
 
 ## Installation
@@ -55,6 +56,56 @@ 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`)
+
+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.
+
+```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';
+
+  const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+</script>
+
+<Table
+  mode="server"
+  {columns}
+  itemsPerPage={25}
+  initialPage={sync.initialQuery.page}
+  initialGroupBy={sync.initialQuery.groupByKey}
+  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 };
+  }}
+/>
+```
+
+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:
+
+```typescript
+// +page.server.ts
+import { searchParamsToTableQuery } from '@urbicon-ui/sveltekit-utils/table-query';
+
+export const load = async ({ url }) => {
+  const query = searchParamsToTableQuery(url.searchParams, { defaults: { itemsPerPage: 25 } });
+  return { initialResult: await fetchUsers(query) };
+};
+```
+
+**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`) 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 limits** — the table currently has no `initialSort` / initial-filter props, so sort/filter state parsed from the URL can seed your fetch but not the table's header indicators. Once those props exist, `initialQuery` covers them too.
+
 ## Cron Runner (`cron`)
 
 Fire HTTP requests against SvelteKit server endpoints on an interval. Pair with a shared-secret header so endpoints can authenticate scheduled calls.
@@ -99,11 +150,12 @@ export const POST = async ({ request }) => {
 
 ## Exports
 
-| Subpath        | Contents                                                                            |
-| -------------- | ----------------------------------------------------------------------------------- |
-| `.`            | Barrel of both modules                                                              |
-| `./url.svelte` | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, types |
-| `./cron`       | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                     |
+| 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`                                                    |
 
 ## Development
 

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './cron';
+export * from './table-query';
 export * from './url.svelte';

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './cron';
+export * from './table-query';
 export * from './url.svelte';

package/dist/table-query.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 passed to `queryFn` / `onQueryChange`
+ * 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.
+ *
+ * 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).
+ */
+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 `queryFn` — 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.
+ *
+ * Works anywhere a `URLSearchParams` exists — including `url.searchParams`
+ * in a server `load`, to run the initial server-mode fetch during SSR.
+ *
+ * @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

@@ -0,0 +1,232 @@
+/**
+ * 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 `queryFn` — 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.
+ *
+ * Works anywhere a `URLSearchParams` exists — including `url.searchParams`
+ * in a server `load`, to run the initial server-mode fetch during SSR.
+ *
+ * @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;
+}

package/dist/url.svelte.d.ts

@@ -1,3 +1,4 @@
+import { type TableQueryParams, type TableQueryUrlOptions } from './table-query';
 export type UrlArrayStrategy = 'repeat' | 'csv';
 export type UrlParamOptions<T> = {
     parse: (sp: URLSearchParams) => T | null | undefined;
@@ -7,7 +8,6 @@ export type UrlParamOptions<T> = {
 };
 export declare function updateUrlSearchParams(next: URLSearchParams | Record<string, string | string[]>, opts?: {
     replaceState?: boolean;
-    keepPath?: boolean;
 }): void;
 export declare function createUrlParam<T>(_key: string, options: UrlParamOptions<T>): {
     readonly get: (sp: URLSearchParams) => T;
@@ -19,3 +19,64 @@ export declare function useUrlArrayParam(key: string, opts: {
     strategy?: UrlArrayStrategy;
     delimiter?: string;
 }): readonly [() => string[], (next: string[]) => void];
+/** Options for {@link createTableQueryUrlSync}. */
+export interface TableQueryUrlSyncOptions extends TableQueryUrlOptions {
+    /**
+     * Replace the current history entry instead of pushing a new one. The
+     * default (`true`) keeps every sort/filter/page interaction from polluting
+     * the back button.
+     * @default true
+     */
+    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.
+ *
+ * Two directions, both explicit:
+ * - **URL → query**: `initialQuery` is parsed once at creation (SSR-safe) —
+ *   seed the table (`initialPage`, `initialGroupBy`, controlled `searchTerm`)
+ *   and run the first fetch from it.
+ * - **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
+ *   `goto` (`replaceState`, `noScroll`, `keepFocus`); unrelated params are
+ *   preserved. Values equal to `options.defaults` are elided, so a table in
+ *   its default state leaves the URL clean.
+ *
+ * Set `options.defaults` to the table's initial props (`itemsPerPage`,
+ * `initialPage`, `initialGroupBy`) so the elision baseline matches the state
+ * the table actually starts in.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Table } from '@urbicon-ui/table';
+ *   import { createTableQueryUrlSync } from '@urbicon-ui/sveltekit-utils/url.svelte';
+ *
+ *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+ * </script>
+ *
+ * <Table
+ *   mode="server"
+ *   columns={columns}
+ *   itemsPerPage={25}
+ *   initialPage={sync.initialQuery.page}
+ *   queryFn={async (query, { signal }) => {
+ *     sync.syncQuery(query);
+ *     const res = await fetch(`/api/users?${new URLSearchParams(...)}`, { signal });
+ *     const data = await res.json();
+ *     return { items: data.results, totalItems: data.total };
+ *   }}
+ * />
+ * ```
+ *
+ * @param options - Elision defaults, key prefix, history behaviour.
+ * @returns `initialQuery` (the URL parsed at creation time) + `syncQuery`
+ *   (write a query back to the URL).
+ */
+export declare function createTableQueryUrlSync(options?: TableQueryUrlSyncOptions): {
+    readonly initialQuery: TableQueryParams;
+    readonly syncQuery: (query: TableQueryParams) => void;
+};

package/dist/url.svelte.js

@@ -1,5 +1,6 @@
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
+import { applyTableQueryToSearchParams, searchParamsToTableQuery } from './table-query';
 // Local imperative use of URLSearchParams — not reactive state — so the
 // SvelteURLSearchParams wrapper is unnecessary here. Likewise for `goto`:
 // we pass constructed relative paths, not resolved route ids; callers of
@@ -25,7 +26,7 @@ export function updateUrlSearchParams(next, opts) {
         }
     }
     const q = base.toString();
-    const path = opts?.keepPath ? page.url.pathname : '/';
+    const path = page.url.pathname;
     goto(q ? `${path}?${q}` : path, {
         replaceState: opts?.replaceState ?? true,
         noScroll: true,
@@ -44,7 +45,7 @@ export function createUrlParam(_key, options) {
         for (const [k, v] of nextSp)
             current.append(k, v);
         const q = current.toString();
-        goto(q ? `?${q}` : '/', {
+        goto(q ? `?${q}` : page.url.pathname, {
             replaceState: options.replaceState ?? true,
             noScroll: true,
             keepFocus: true
@@ -80,3 +81,63 @@ 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.
+ *
+ * Two directions, both explicit:
+ * - **URL → query**: `initialQuery` is parsed once at creation (SSR-safe) —
+ *   seed the table (`initialPage`, `initialGroupBy`, controlled `searchTerm`)
+ *   and run the first fetch from it.
+ * - **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
+ *   `goto` (`replaceState`, `noScroll`, `keepFocus`); unrelated params are
+ *   preserved. Values equal to `options.defaults` are elided, so a table in
+ *   its default state leaves the URL clean.
+ *
+ * Set `options.defaults` to the table's initial props (`itemsPerPage`,
+ * `initialPage`, `initialGroupBy`) so the elision baseline matches the state
+ * the table actually starts in.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Table } from '@urbicon-ui/table';
+ *   import { createTableQueryUrlSync } from '@urbicon-ui/sveltekit-utils/url.svelte';
+ *
+ *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+ * </script>
+ *
+ * <Table
+ *   mode="server"
+ *   columns={columns}
+ *   itemsPerPage={25}
+ *   initialPage={sync.initialQuery.page}
+ *   queryFn={async (query, { signal }) => {
+ *     sync.syncQuery(query);
+ *     const res = await fetch(`/api/users?${new URLSearchParams(...)}`, { signal });
+ *     const data = await res.json();
+ *     return { items: data.results, totalItems: data.total };
+ *   }}
+ * />
+ * ```
+ *
+ * @param options - Elision defaults, key prefix, history behaviour.
+ * @returns `initialQuery` (the URL parsed at creation time) + `syncQuery`
+ *   (write a query back to the URL).
+ */
+export function createTableQueryUrlSync(options = {}) {
+    const initialQuery = searchParamsToTableQuery(page.url.searchParams, options);
+    function syncQuery(query) {
+        const next = applyTableQueryToSearchParams(page.url.searchParams, query, options);
+        const qs = next.toString();
+        goto(`${page.url.pathname}${qs ? `?${qs}` : ''}${page.url.hash}`, {
+            replaceState: options.replaceState ?? true,
+            noScroll: true,
+            keepFocus: true
+        });
+    }
+    return { initialQuery, syncQuery };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "6.21.2",
+  "version": "6.22.0",
   "description": "SvelteKit helper utilities — createCronRunner and URL-state runes",
   "license": "MIT",
   "repository": {
@@ -40,10 +40,17 @@
     "./cron": {
       "types": "./dist/cron.d.ts",
       "import": "./dist/cron.js"
+    },
+    "./table-query": {
+      "types": "./dist/table-query.d.ts",
+      "import": "./dist/table-query.js",
+      "default": "./dist/table-query.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
   ],
   "scripts": {
     "dev": "svelte-package --watch",

package/dist/cron.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cron.test.js

@@ -1,137 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createCronRunner } from './cron';
-describe('createCronRunner', () => {
-    beforeEach(() => {
-        vi.useFakeTimers();
-        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(null, { status: 200 })));
-    });
-    afterEach(() => {
-        vi.useRealTimers();
-        vi.restoreAllMocks();
-    });
-    it('should not be running initially', () => {
-        const runner = createCronRunner({
-            secret: 'test-secret',
-            jobs: [{ path: '/api/test', intervalSeconds: 60 }]
-        });
-        expect(runner.isRunning()).toBe(false);
-    });
-    it('should be running after start()', () => {
-        const runner = createCronRunner({
-            secret: 'test-secret',
-            jobs: [{ path: '/api/test', intervalSeconds: 60 }]
-        });
-        runner.start();
-        expect(runner.isRunning()).toBe(true);
-        runner.stop();
-    });
-    it('should not be running after stop()', () => {
-        const runner = createCronRunner({
-            secret: 'test-secret',
-            jobs: [{ path: '/api/test', intervalSeconds: 60 }]
-        });
-        runner.start();
-        runner.stop();
-        expect(runner.isRunning()).toBe(false);
-    });
-    it('should not start twice', () => {
-        const runner = createCronRunner({
-            secret: 'test-secret',
-            jobs: [{ path: '/api/test', intervalSeconds: 10 }]
-        });
-        runner.start();
-        runner.start();
-        vi.advanceTimersByTime(10_000);
-        expect(fetch).toHaveBeenCalledTimes(1);
-        runner.stop();
-    });
-    it('should call fetch for each job at the correct interval', async () => {
-        const runner = createCronRunner({
-            secret: 'my-secret',
-            baseUrl: 'http://localhost:5000',
-            jobs: [
-                { path: '/api/job-a', intervalSeconds: 10 },
-                { path: '/api/job-b', intervalSeconds: 20, method: 'GET' }
-            ]
-        });
-        runner.start();
-        // At 10s: job-a fires
-        await vi.advanceTimersByTimeAsync(10_000);
-        expect(fetch).toHaveBeenCalledTimes(1);
-        expect(fetch).toHaveBeenCalledWith('http://localhost:5000/api/job-a', {
-            method: 'POST',
-            headers: { 'x-cron-secret': 'my-secret' }
-        });
-        // At 20s: job-a fires again + job-b fires for the first time
-        await vi.advanceTimersByTimeAsync(10_000);
-        expect(fetch).toHaveBeenCalledTimes(3);
-        expect(fetch).toHaveBeenCalledWith('http://localhost:5000/api/job-b', {
-            method: 'GET',
-            headers: { 'x-cron-secret': 'my-secret' }
-        });
-        runner.stop();
-    });
-    it('should use default baseUrl when not provided', async () => {
-        const runner = createCronRunner({
-            secret: 's',
-            jobs: [{ path: '/api/ping', intervalSeconds: 5 }]
-        });
-        runner.start();
-        await vi.advanceTimersByTimeAsync(5_000);
-        expect(fetch).toHaveBeenCalledWith('http://localhost:3000/api/ping', expect.any(Object));
-        runner.stop();
-    });
-    it('should use custom secretHeader', async () => {
-        const runner = createCronRunner({
-            secret: 'abc',
-            secretHeader: 'x-internal-key',
-            jobs: [{ path: '/api/test', intervalSeconds: 5 }]
-        });
-        runner.start();
-        await vi.advanceTimersByTimeAsync(5_000);
-        expect(fetch).toHaveBeenCalledWith(expect.any(String), {
-            method: 'POST',
-            headers: { 'x-internal-key': 'abc' }
-        });
-        runner.stop();
-    });
-    it('should call onError when fetch throws', async () => {
-        const error = new Error('Network error');
-        vi.mocked(fetch).mockRejectedValueOnce(error);
-        const onError = vi.fn();
-        const job = { path: '/api/fail', intervalSeconds: 5 };
-        const runner = createCronRunner({
-            secret: 's',
-            jobs: [job],
-            onError
-        });
-        runner.start();
-        await vi.advanceTimersByTimeAsync(5_000);
-        expect(onError).toHaveBeenCalledWith(job, error);
-        runner.stop();
-    });
-    it('should not call onError when fetch succeeds', async () => {
-        const onError = vi.fn();
-        const runner = createCronRunner({
-            secret: 's',
-            jobs: [{ path: '/api/ok', intervalSeconds: 5 }],
-            onError
-        });
-        runner.start();
-        await vi.advanceTimersByTimeAsync(5_000);
-        expect(onError).not.toHaveBeenCalled();
-        runner.stop();
-    });
-    it('should stop all timers and not fire after stop()', async () => {
-        const runner = createCronRunner({
-            secret: 's',
-            jobs: [{ path: '/api/test', intervalSeconds: 5 }]
-        });
-        runner.start();
-        await vi.advanceTimersByTimeAsync(5_000);
-        expect(fetch).toHaveBeenCalledTimes(1);
-        runner.stop();
-        await vi.advanceTimersByTimeAsync(15_000);
-        expect(fetch).toHaveBeenCalledTimes(1);
-    });
-});