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

[IzumiSy]

After comparing this with the old useEffect-based approach, I think the current API is the better direction for AppShell.

The old design hydrated internal collection state after mount and synchronized it back to the URL through effects. While functional, that approach leans on post-render state synchronization in a way that is less aligned with the React style we should aim for.

The current API is closer to the React way:

• parse URL state up front
• treat params as initial values
• initialize internal state from them
• report later changes via onParamsChange

This gives clearer initialization semantics and avoids effect-based external-to-internal state synchronization after mount.

I also think this matters from a maintenance and tooling perspective. If we keep introducing patterns like the old one, they are more likely to be repeated by AI-assisted development as well. I’d rather have the codebase teach and reinforce the React-idiomatic pattern wherever we can.