feat: add URL state persistence of CollectionControl

[IzumiSy]

Overview

A feature to persist CollectionControl state (filters, sort, page size) to URL query parameters.

This enables:

• Bookmarkable page state — Users can share or save URLs with applied filters and sort
• Browser back/forward support — State is restored through URL history
• Entity-agnostic design — Uses short key names and automatic encoding derived from the Filter shape, making it usable with any resource

Cursor/pagination direction state is intentionally not persisted — a page refresh resets to page 1.

[interacsean]

Heads-up from the downstream side 👋 — we've been running this hook in the Denim Tears IMS app (apps/ims/frontend/src/hooks/use-url-collection-state.ts), and this PR looks like it was derived from a mid-May snapshot of it (same doc comment, p/s/f. keys). We landed a few fixes on our copy on June 2, after this PR opened (May 27), that are worth folding in here — one is a real bug.

1. between (object-valued) filters don't round-trip 🐛

encodeFilterValue writes objects as JSON, but decodeFilterValue only parses arrays back — objects fall through to the raw string:

const parsed = JSON.parse(raw);
if (Array.isArray(parsed)) return parsed;   // objects dropped → returned as a string
return raw;

The Filter type here defines between → { min, max } (OperatorValueType), so any between filter (date ranges, numeric ranges) gets written to the URL as {"min":…,"max":…} and comes back as a string on reload — the filter silently breaks. One-line fix:

const parsed = JSON.parse(raw);
if (Array.isArray(parsed)) return parsed;
if (parsed && typeof parsed === "object") return parsed;  // round-trip between/{min,max}
return raw;

(Primitives like "5"/"true" parse but aren't objects, so they still return as strings — string-vs-numeric filter semantics preserved.)

2. Equality check is order- / &=-sensitive (robustness, lower priority)

next.toString() === prev.toString() is sensitive to key-insertion order and to &/= inside values. We switched to a sorted, JSON-encoded snapshot of the entries so reordered or edge-char params compare equal. Your functional-updater approach (omitting params from the deps) already sidesteps the churn loop this originally guarded against, so it's more of a latent sharp edge than a live bug — flagging in case it's cheap to fold in.

3. Multi-value encoding — heads-up, not a request

We independently fixed the same comma-splitting bug ("Apparel, LLC" → ["Apparel"," LLC"]), but chose repeated params (f.status:in=a&f.status:in=b) where you chose a JSON array (f.status:in=["a","b"]). Both are valid. Yours actually keeps single-element arrays as arrays (ours round-trips them to scalars and re-wraps downstream), so no change requested — just flagging that whichever format ships becomes the URL contract consumers bookmark against.

Nice to see the test coverage — our copy has none, so we'll likely adopt this hook and retire ours once it lands. Only #1 is a must-fix from our experience.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/tailor-platform/app-shell/@tailor-platform/app-shell@293

npm i https://pkg.pr.new/tailor-platform/app-shell/@tailor-platform/app-shell-sdk-plugin@293

npm i https://pkg.pr.new/tailor-platform/app-shell/@tailor-platform/app-shell-vite-plugin@293

commit: 82856e6