@urbicon-ui/sveltekit-utils 8.19.0 → 8.20.0

package/README.md

@@ -4,7 +4,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
+- **URL-state runes** — reactive `useUrlParam` / `useUrlArrayParam` that keep component state in sync with `?query=` parameters, and `withSearchParams` for the links that change them
 - **Table view ↔ URL** — `bindViewToUrl`, the URL home for a `@urbicon-ui/table` view object (`?q=…&sort=…&page=…`), plus the pure serializers for the load path
 - **Cron runner** — interval-based background fetcher for scheduled server endpoints
 - **SSE stream reader** — `streamSse`, a spec-correct async-generator client for one-shot POST `text/event-stream` endpoints (LLM relays)
@@ -53,9 +53,57 @@ import { updateUrlSearchParams } from '@urbicon-ui/sveltekit-utils/url.svelte';
 updateUrlSearchParams({ page: '1', tag: ['a', 'b'] }, { replaceState: true });
 ```
 
+A link needs an address, not a setter. `withSearchParams(url, patch)` is the pure core that `updateUrlSearchParams` and `createUrlParam`'s setter navigate to: the address `url` has after `patch` — a scalar `set`s its key, an array `append`s each element, `null` removes the key, every other param stays as it is. An empty string is a value and keeps its key (`?a=`); an empty array appends nothing and so removes it. It reads nothing from the page and navigates nowhere, so the same call builds a link's `href` and a redirect's location.
+
+<!-- typecheck -->
+```typescript
+import { withSearchParams } from '@urbicon-ui/sveltekit-utils/search-params';
+
+const url = new URL('https://films.test/archive?sort=title&page=3');
+
+withSearchParams(url, { sort: 'year' }); // '/archive?page=3&sort=year'
+withSearchParams(url, { tag: ['noir', 'silent'] }); // '/archive?sort=title&page=3&tag=noir&tag=silent'
+withSearchParams(url, { sort: null, page: null }); // '/archive'
+```
+
+`./search-params` is the import path that reaches no `$app/*` module, so a `load`, a form action or a plain test can use it; importing `withSearchParams` from `./url.svelte` (or from the package root) is the same function, but pulls SvelteKit's client runtime along:
+
+<!-- typecheck -->
+```typescript
+// src/routes/archive/+page.server.ts
+import { withSearchParams } from '@urbicon-ui/sveltekit-utils/search-params';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = ({ url }) => {
+  const current = Number(url.searchParams.get('page') ?? '1');
+  return {
+    // Page 1 is the default, so its link carries no `page` at all.
+    prevHref: withSearchParams(url, { page: current > 2 ? String(current - 1) : null }),
+    nextHref: withSearchParams(url, { page: String(current + 1) })
+  };
+};
+```
+
+In a component the URL to start from is `page.url`, and the result is the `href`:
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/state';
+  import { withSearchParams } from '@urbicon-ui/sveltekit-utils/url.svelte';
+</script>
+
+<a href={withSearchParams(page.url, { sort: 'year', page: null })}>Sort by year</a>
+```
+
+Not on a prerendered page: SvelteKit makes `url.searchParams` throw there — the emitted HTML must not depend on a query string that will not exist at request time — and `withSearchParams` reads it. `useUrlParam` guards that case for you by yielding its `initial` while `building`; a link on such a page has to be built after hydration, or from a `URL` you construct rather than the page's.
+
+Link or binding: an `href` from `withSearchParams` where the reader picks a destination — a sort header, a pagination step, a filter chip — and the address should exist before the click, so it can be hovered, middle-clicked and crawled; `useUrlParam` where a control owns a value that keeps changing — a search box, a slider — and the URL follows it.
+
 **Design notes**
 
 - URL updates use `goto()` with `replaceState: true`, `noScroll: true`, `keepFocus: true` — suited for filter/pagination UIs, not full page transitions.
+- `updateUrlSearchParams` and `createUrlParam`'s setter hand `goto` the pathname-qualified address `withSearchParams` returns, never a bare `?query`. `goto` resolves a relative target against `document.baseURI`, which equals the page's own URL only while the document carries no `<base href>` — with one, `?page=2` keeps the base's path, not the page's.
+- `bindViewToUrl` is a third URL writer and does **not** go through `withSearchParams`: it merges the view axes itself and carries the URL hash across, where `withSearchParams` drops it. Do not read one policy off the other.
 - `useUrlParam` returns getters (not Svelte stores) so consumers can read the value lazily inside `$derived`/`$effect`.
 
 ## Table View ↔ URL (`url.svelte` + `table-view`)
@@ -228,15 +276,16 @@ export const POST: RequestHandler = async ({ request }) => {
 
 ## Exports
 
-| Subpath         | Contents                                                                                                                                           |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`             | Barrel of all modules                                                                                                                              |
-| `./url.svelte`  | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, 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`                                                                                     |
+| Subpath           | Contents                                                                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`               | Barrel of all modules                                                                                                                            |
+| `./url.svelte`    | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, types (re-exports `withSearchParams`)             |
+| `./search-params` | `withSearchParams`, `SearchParamsPatch` — no `$app/*` import                                                                                     |
+| `./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` 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.
+`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. `./search-params` and `./table-view` 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 — importing it from server code pulls SvelteKit's client runtime in, which is why `withSearchParams` has a subpath of its own as well as the re-export.
 
 ## Development
 

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/search-params.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What {@link withSearchParams} applies to a URL: a plain record, or a
+ * `URLSearchParams` whose repeated keys survive the merge.
+ */
+export type SearchParamsPatch = URLSearchParams | Record<string, string | string[] | null | undefined>;
+/**
+ * The address `url` has after `patch` — the pure core that
+ * `updateUrlSearchParams` and `createUrlParam`'s setter navigate to. Returns
+ * `pathname?query`, or the pathname alone once no param is left, so the result
+ * serves as a link's `href`, a redirect's location, or the argument of `goto`.
+ * Reads nothing from the page, mutates neither argument, navigates nowhere.
+ *
+ * Merge semantics per key in `patch`: the key is first cleared, then
+ * re-applied — a record value `set`s a scalar, `append`s each array element,
+ * and **removes** the key entirely for `null`/`undefined`; a `URLSearchParams`
+ * re-appends all of its entries, so repeated keys survive. An empty string is a
+ * value and keeps its key (`?a=`); an empty array appends nothing and therefore
+ * removes it. A param the patch does not name keeps its value and its position;
+ * a patched key moves behind them. The hash is not carried.
+ *
+ * A `url.pathname` that itself begins with `//` comes back origin-qualified
+ * (`https://host//films?page=2`): left relative, `//films` is a
+ * protocol-relative URL naming `films` as the host.
+ *
+ * @param url - The URL to start from — `page.url` in a component, `url` in a
+ *   `load`. SvelteKit makes `url.searchParams` throw while prerendering
+ *   (`@sveltejs/kit/src/utils/url.js` `disable_search`: the emitted HTML must
+ *   not depend on a query string), and this reads it.
+ * @param patch - Params to apply. A record value of `null`/`undefined` deletes
+ *   that key.
+ * @returns Pathname plus the merged query: `/films?sort=year`.
+ * @example
+ * ```typescript
+ * withSearchParams(new URL('https://x.test/films?sort=title&page=3'), {
+ *   sort: 'year',
+ *   page: null
+ * });
+ * // '/films?sort=year'
+ * ```
+ */
+export declare function withSearchParams(url: URL, patch: SearchParamsPatch): string;

package/dist/search-params.js

@@ -0,0 +1,62 @@
+/**
+ * The address `url` has after `patch` — the pure core that
+ * `updateUrlSearchParams` and `createUrlParam`'s setter navigate to. Returns
+ * `pathname?query`, or the pathname alone once no param is left, so the result
+ * serves as a link's `href`, a redirect's location, or the argument of `goto`.
+ * Reads nothing from the page, mutates neither argument, navigates nowhere.
+ *
+ * Merge semantics per key in `patch`: the key is first cleared, then
+ * re-applied — a record value `set`s a scalar, `append`s each array element,
+ * and **removes** the key entirely for `null`/`undefined`; a `URLSearchParams`
+ * re-appends all of its entries, so repeated keys survive. An empty string is a
+ * value and keeps its key (`?a=`); an empty array appends nothing and therefore
+ * removes it. A param the patch does not name keeps its value and its position;
+ * a patched key moves behind them. The hash is not carried.
+ *
+ * A `url.pathname` that itself begins with `//` comes back origin-qualified
+ * (`https://host//films?page=2`): left relative, `//films` is a
+ * protocol-relative URL naming `films` as the host.
+ *
+ * @param url - The URL to start from — `page.url` in a component, `url` in a
+ *   `load`. SvelteKit makes `url.searchParams` throw while prerendering
+ *   (`@sveltejs/kit/src/utils/url.js` `disable_search`: the emitted HTML must
+ *   not depend on a query string), and this reads it.
+ * @param patch - Params to apply. A record value of `null`/`undefined` deletes
+ *   that key.
+ * @returns Pathname plus the merged query: `/films?sort=year`.
+ * @example
+ * ```typescript
+ * withSearchParams(new URL('https://x.test/films?sort=title&page=3'), {
+ *   sort: 'year',
+ *   page: null
+ * });
+ * // '/films?sort=year'
+ * ```
+ */
+export function withSearchParams(url, patch) {
+    const next = new URLSearchParams(url.searchParams);
+    if (patch instanceof URLSearchParams) {
+        for (const [key] of patch)
+            next.delete(key);
+        for (const [key, value] of patch)
+            next.append(key, value);
+    }
+    else {
+        for (const [key, value] of Object.entries(patch)) {
+            next.delete(key);
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    next.append(key, v);
+            }
+            else if (value != null) {
+                next.set(key, value);
+            }
+        }
+    }
+    const query = next.toString();
+    const address = query ? `${url.pathname}?${query}` : url.pathname;
+    // A leading `//` makes the address protocol-relative: as an `href` or a
+    // `goto` target `//films` names `films` as the host, not a path on this one.
+    // The origin is what disambiguates it; every other pathname stays relative.
+    return url.pathname.startsWith('//') ? `${url.origin}${address}` : address;
+}

package/dist/url.svelte.d.ts

@@ -1,3 +1,5 @@
+import { type SearchParamsPatch } from './search-params.js';
+export { type SearchParamsPatch, withSearchParams } from './search-params.js';
 export { bindViewToUrl, type UrlViewBindingOptions } from './view-binding.svelte.js';
 /**
  * How {@link useUrlArrayParam} maps an array onto the URL:
@@ -30,24 +32,21 @@ export type UrlParamOptions<T> = {
 };
 /**
  * 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
- * every unrelated param.
- *
- * Merge semantics per key in `next`: the key is first cleared, then re-applied
- * — a `URLSearchParams` re-appends all of its entries (repeated keys survive),
- * a record `set`s a scalar, `append`s each array element, and **removes** the
- * key entirely for a `null`/`undefined` value.
+ * full navigation). Navigates to the address {@link withSearchParams} builds
+ * from the current URL and `next`, so every unrelated param is kept; the merge
+ * semantics per key are documented there.
  *
  * @param next - Params to apply, as `URLSearchParams` or a plain record. A
  *   record value of `null`/`undefined` deletes that key.
  * @param opts - `replaceState` (default `true`) — replace vs. push history.
  * @example
  * ```typescript
+ * // on /films?filter=old
  * updateUrlSearchParams({ page: '1', tag: ['a', 'b'], filter: null });
- * // ?page=1&tag=a&tag=b   (any prior `filter` param is dropped)
+ * // navigates to /films?page=1&tag=a&tag=b   (the prior `filter` param is dropped)
  * ```
  */
-export declare function updateUrlSearchParams(next: URLSearchParams | Record<string, string | string[]>, opts?: {
+export declare function updateUrlSearchParams(next: SearchParamsPatch, opts?: {
     replaceState?: boolean;
 }): void;
 /**
@@ -58,8 +57,8 @@ export declare function updateUrlSearchParams(next: URLSearchParams | Record<str
  * page URL (tests, a server `load`).
  *
  * `set` rewrites only the keys that `options.serialize` produces (clear +
- * re-append) and preserves the rest, then navigates with `goto`
- * (`replaceState`, `noScroll`, `keepFocus`).
+ * re-append) and preserves the rest, then navigates with `goto` to the address
+ * {@link withSearchParams} builds (`replaceState`, `noScroll`, `keepFocus`).
  *
  * @param _key - Ignored — `options.parse`/`options.serialize` already close
  *   over the key (see {@link useUrlArrayParam}); kept only for signature parity

package/dist/url.svelte.js

@@ -1,6 +1,12 @@
 import { building } from '$app/environment';
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
+import { withSearchParams } from './search-params.js';
+// The pure core of the two writers below, re-exported so this import path
+// carries it next to them. Its own module — and its own `./search-params`
+// subpath — because it must stay free of `$app`: importing this one pulls
+// SvelteKit's client runtime, which a `load` or a form action must not.
+export { withSearchParams } from './search-params.js';
 // The v8 view-object binding lives in its own module; re-exported here so the
 // documented import path (`@urbicon-ui/sveltekit-utils/url.svelte`) carries it.
 // The mirror types (TableViewLike, TableViewSnapshot, …) are exported from the
@@ -12,50 +18,31 @@ import { page } from '$app/state';
 export { bindViewToUrl } from './view-binding.svelte.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
- * every unrelated param.
- *
- * Merge semantics per key in `next`: the key is first cleared, then re-applied
- * — a `URLSearchParams` re-appends all of its entries (repeated keys survive),
- * a record `set`s a scalar, `append`s each array element, and **removes** the
- * key entirely for a `null`/`undefined` value.
+ * full navigation). Navigates to the address {@link withSearchParams} builds
+ * from the current URL and `next`, so every unrelated param is kept; the merge
+ * semantics per key are documented there.
  *
  * @param next - Params to apply, as `URLSearchParams` or a plain record. A
  *   record value of `null`/`undefined` deletes that key.
  * @param opts - `replaceState` (default `true`) — replace vs. push history.
  * @example
  * ```typescript
+ * // on /films?filter=old
  * updateUrlSearchParams({ page: '1', tag: ['a', 'b'], filter: null });
- * // ?page=1&tag=a&tag=b   (any prior `filter` param is dropped)
+ * // navigates to /films?page=1&tag=a&tag=b   (the prior `filter` param is dropped)
  * ```
  */
-// 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
-// this helper are free to call `resolve()` at their composition point.
+// This writer and `createUrlParam`'s setter hand `goto` the pathname-qualified
+// address, never a bare `?query`: `goto` resolves a relative target against
+// `document.baseURI` (`@sveltejs/kit/src/runtime/client/utils.js` `resolve_url`,
+// which falls back to the first `<base>` tag), so with a `<base href>` in the
+// document `?page=2` keeps the base's path, not the page's. No harness can
+// separate the two spellings by outcome — both resolve against `page.url` there
+// — so `url.test.ts` pins the string `goto` was handed instead.
+// The address is not a route id either, so no `resolve()` here; callers are
+// free to call it at their composition point.
 export function updateUrlSearchParams(next, opts) {
-    const base = new URLSearchParams(page.url.searchParams);
-    if (next instanceof URLSearchParams) {
-        for (const [k] of next)
-            base.delete(k);
-        for (const [k, v] of next)
-            base.append(k, v);
-    }
-    else {
-        for (const [key, val] of Object.entries(next)) {
-            base.delete(key);
-            if (Array.isArray(val)) {
-                for (const v of val)
-                    base.append(key, v);
-            }
-            else if (val != null) {
-                base.set(key, String(val));
-            }
-        }
-    }
-    const q = base.toString();
-    const path = page.url.pathname;
-    goto(q ? `${path}?${q}` : path, {
+    goto(withSearchParams(page.url, next), {
         replaceState: opts?.replaceState ?? true,
         noScroll: true,
         keepFocus: true
@@ -69,8 +56,8 @@ export function updateUrlSearchParams(next, opts) {
  * page URL (tests, a server `load`).
  *
  * `set` rewrites only the keys that `options.serialize` produces (clear +
- * re-append) and preserves the rest, then navigates with `goto`
- * (`replaceState`, `noScroll`, `keepFocus`).
+ * re-append) and preserves the rest, then navigates with `goto` to the address
+ * {@link withSearchParams} builds (`replaceState`, `noScroll`, `keepFocus`).
  *
  * @param _key - Ignored — `options.parse`/`options.serialize` already close
  *   over the key (see {@link useUrlArrayParam}); kept only for signature parity
@@ -84,14 +71,7 @@ export function updateUrlSearchParams(next, opts) {
 export function createUrlParam(_key, options) {
     const get = (sp) => options.parse(sp) ?? options.initial;
     function setValue(next) {
-        const current = new URLSearchParams(page.url.searchParams);
-        const nextSp = options.serialize(next);
-        for (const [k] of nextSp)
-            current.delete(k);
-        for (const [k, v] of nextSp)
-            current.append(k, v);
-        const q = current.toString();
-        goto(q ? `?${q}` : page.url.pathname, {
+        goto(withSearchParams(page.url, options.serialize(next)), {
             replaceState: options.replaceState ?? true,
             noScroll: true,
             keepFocus: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "8.19.0",
+  "version": "8.20.0",
   "description": "SvelteKit helper utilities — createCronRunner, streamSse, and URL-state runes",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,11 @@
       "import": "./dist/url.svelte.js",
       "default": "./dist/url.svelte.js"
     },
+    "./search-params": {
+      "types": "./dist/search-params.d.ts",
+      "import": "./dist/search-params.js",
+      "default": "./dist/search-params.js"
+    },
     "./cron": {
       "types": "./dist/cron.d.ts",
       "import": "./dist/cron.js"