Refine URL collection state: single useURLCollectionVariables hook + typed filter coercion

[interacsean]

Proposed refinements on top of improve-use-url-collection-state (#293), in two parts: a hook-interface change and a bugfix to the URL-state code on that branch. Scoped to the library + the one consumer update the interface change forces — no unrelated demo/scaffolding.

1. Interface — collapse the common path into one hook

The base branch exposes URL persistence as a decorator returned by a hook, used like:

const withURLCollectionState = useURLCollectionState();
const { variables, control } = useCollectionVariables(
  withURLCollectionState({ tableMetadata, params: { pageSize: 20 } }),
);

useURLCollectionState() only ever wraps react-router's useSearchParams, so it provides no flexibility a single fused hook wouldn't — while forcing every call site through a two-hook dance and an awkward name collision (const withURLCollectionState = useURLCollectionState() shadows the exported withURLCollectionState).

This collapses the 99% path to one call:

const { variables, control } = useURLCollectionVariables({
  tableMetadata,
  params: { pageSize: 20 },
});

Public surface becomes three exports, each with a distinct job:

• useCollectionVariables — router-free primitive (unchanged)
• useURLCollectionVariables (new) — URL persistence in one call
• withURLCollectionState(options, binding) — pure decorator, kept as the escape hatch for a non-react-router binding / composition

Removed useURLCollectionState (redundant with the fused hook; unreleased, so no external consumers).

2. Bugfix — typed filter values lost their type on URL round-trip

decodeFilterValue intentionally returns numeric/boolean values as strings (on its own it can't know the intended type). But parseCollectionSearchParams — the metadata-aware overload — never restored the type, so a deep-linked f.price:gt=130 came back as the string "130". That contradicts TypedCollectionVariables (which declares query.price.gt as number) and silently breaks any type-aware filtering — a real typed GraphQL Float/Int input would also reject a string.

Fix: when table metadata is present, coerce decoded filter values to the field's declared type (number/boolean), descending into in/nin arrays and between { min, max } bounds. The untyped overload (no metadata) is unchanged — values stay strings.

Tests

• coerces number/boolean filter values (incl. in arrays) using metadata
• round-trips a numeric gt filter through write → parse as a number
• leaves numeric-looking values as strings when no metadata is provided
• updated the hook test to the new useURLCollectionVariables shape

Verification

• packages/core: lint clean, format clean, 27 tests pass, tsc clean.
• nextjs example: tsc clean.
• Verified live (vite example) against an f.price:gt=130 deep-link: rows hydrate correctly, filtered + sorted, no console errors.

Notes

• examples/nextjs-app/.../data-table-demo.tsx is updated to the new hook — required by the export change, not optional.
• The existing changeset is updated to document the single-hook API; no separate changeset for the bugfix since it's internal to the unreleased feature.

🤖 Generated with Claude Code

[IzumiSy]

I originally preferred the useCollectionVariables(withURLCollectionState(...)) shape because it kept useCollectionVariables as the main API and treated URL state as a small layer around it, rather than introducing a separate entry point. I was also a little concerned that having multiple hooks with the same general surface for different persistence targets could become confusing over time.

That said, after thinking about it more, I agree that useURLCollectionVariables(...) is the better default API for now.

The key point for me is that the important abstraction is still useCollectionVariables itself. As long as that remains the storage-agnostic primitive, adding a URL-specific convenience hook on top does not really reduce extensibility. withURLCollectionState(...) still gives us a way to compose URL state manually when needed.

I also don’t think keeping useURLCollectionState() as a separate hook gives us much extra future-proofing. Synchronous persistence targets can still be built on top of useCollectionVariables, and asynchronous persistence would require additional reset/controlled behavior there anyway.

So I’m 👍 on useURLCollectionVariables(...) as the default API.