fix: round-trip object-valued filters in useUrlCollectionState

decodeFilterValue only parsed JSON arrays back, so object-valued filters
(the `between` operator's { min, max } shape) round-tripped to a raw
string on reload and silently broke. Decode objects too; primitives like
"5"/"true" still fall through to strings, preserving string-vs-numeric
filter semantics.

Also harden the write-effect bail-out: compare on a sorted, JSON-encoded
snapshot (stableQueryString) rather than `.toString()`, which is
sensitive to filter key-insertion order and to `&`/`=` inside values.

Folds in fixes already running in the Denim Tears IMS copy of this hook.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 2 people

packages/core/src/hooks/use-url-collection-state.test.ts

@@ -124,6 +124,21 @@ describe("useUrlCollectionState", () => {
       ]);
     });
 
+    it("hydrates object filter values (between {min,max} JSON format)", () => {
+      mockParams = new URLSearchParams(
+        'f.createdAt:between={"min":"2026-01-01","max":"2026-12-31"}',
+      );
+      const control = makeControl();
+      renderHook(() => useUrlCollectionState(control));
+      expect(control.setFilters).toHaveBeenCalledWith([
+        {
+          field: "createdAt",
+          operator: "between",
+          value: { min: "2026-01-01", max: "2026-12-31" },
+        },
+      ]);
+    });
+
     it("skips filters with missing value", () => {
       mockParams = new URLSearchParams("f.status:eq=");
       const control = makeControl();
@@ -204,6 +219,30 @@ describe("useUrlCollectionState", () => {
       }
     });
 
+    it("treats reordered params as unchanged (order-insensitive compare)", () => {
+      // prev URL holds filters in b,a order; control emits the same multiset in
+      // a,b order. The delete-then-set rebuild flips key order, but the param
+      // multiset is identical, so the write must bail out and return prev.
+      // A plain `.toString()` compare would see a difference here and navigate.
+      mockParams = new URLSearchParams("f.b:eq=2&f.a:eq=1&p=20");
+      const filters = [
+        { field: "a", operator: "eq" as never, value: "1" },
+        { field: "b", operator: "eq" as never, value: "2" },
+      ];
+      const { rerender } = renderHook(({ control }) => useUrlCollectionState(control), {
+        initialProps: { control: makeControl({ pageSize: 20, filters }) },
+      });
+      // Re-render with a fresh control (new array refs) to fire the write effect.
+      rerender({ control: makeControl({ pageSize: 20, filters: [...filters] }) });
+      const lastCallIndex = mockSetParams.mock.calls.length - 1;
+      const [updater] = mockSetParams.mock.calls[lastCallIndex];
+      expect(typeof updater).toBe("function");
+      if (typeof updater === "function") {
+        const result = updater(mockParams);
+        expect(result).toBe(mockParams);
+      }
+    });
+
     it("uses replace: true for setParams", () => {
       const { rerender } = renderHook(({ control }) => useUrlCollectionState(control), {
         initialProps: { control: makeControl({ pageSize: 20 }) },
@@ -262,6 +301,22 @@ describe("decodeFilterValue", () => {
     expect(decodeFilterValue('["Smith, John","Doe, Jane"]')).toEqual(["Smith, John", "Doe, Jane"]);
   });
 
+  it("decodes JSON objects (between {min,max} shape)", () => {
+    expect(decodeFilterValue('{"min":1,"max":10}')).toEqual({ min: 1, max: 10 });
+  });
+
+  it("round-trips an object value through encode → decode", () => {
+    const value = { min: "2026-01-01", max: "2026-12-31" };
+    expect(decodeFilterValue(encodeFilterValue(value))).toEqual(value);
+  });
+
+  it("does not coerce numeric- or boolean-looking strings to primitives", () => {
+    // These parse as JSON (number/boolean) but must stay strings so operator
+    // implementations keep their string-vs-numeric semantics.
+    expect(decodeFilterValue("5")).toBe("5");
+    expect(decodeFilterValue("true")).toBe("true");
+  });
+
   it("returns plain string for non-array values", () => {
     expect(decodeFilterValue("hello")).toBe("hello");
   });

packages/core/src/hooks/use-url-collection-state.ts

@@ -118,8 +118,12 @@ export function useUrlCollectionState<
         }
 
         // Bail out if nothing changed — avoids a no-op navigation that could
-        // still trigger re-renders in some react-router versions.
-        if (next.toString() === prev.toString()) return prev;
+        // still trigger re-renders in some react-router versions. Compare on a
+        // sorted snapshot rather than `.toString()`: the filter rebuild above is
+        // delete-then-set, so key order can shift between renders even when the
+        // param multiset is identical (and `.toString()` is additionally
+        // sensitive to `&`/`=` characters inside values).
+        if (stableQueryString(next) === stableQueryString(prev)) return prev;
         return next;
       },
       { replace: true },
@@ -154,14 +158,37 @@ function stringifyPrimitive(value: unknown): string {
 /**
  * Decodes a filter value from URL storage.
  * - JSON arrays are parsed back into arrays.
- * - All other values are returned as plain strings.
+ * - JSON objects are parsed back into objects (e.g. the `between` operator's
+ *   `{ min, max }` shape).
+ * - All other values — including numeric/boolean-looking strings such as `"5"`
+ *   or `"true"` — are returned as plain strings, preserving the string-vs-
+ *   numeric distinction that operator implementations rely on.
  */
 export function decodeFilterValue(raw: string): unknown {
   try {
     const parsed: unknown = JSON.parse(raw);
     if (Array.isArray(parsed)) return parsed;
+    // Objects (e.g. a `between` filter's `{ min, max }`) are JSON-encoded by
+    // encodeFilterValue and must be decoded back here; without this, object-
+    // valued filters round-trip to a raw string on reload and silently break.
+    if (parsed && typeof parsed === "object") return parsed;
   } catch {
     // Not valid JSON — fall through to plain string
   }
   return raw;
 }
+
+/**
+ * Order-insensitive, unambiguous snapshot of a URLSearchParams for equality
+ * checks. Entries are sorted by key then value so a reordered-but-equivalent
+ * param set compares equal, and the pairs are JSON-encoded so a key or value
+ * containing `&`/`=` can't collide with the entry boundary the way a re-joined
+ * query string would (e.g. `[["a","x"],["b","y"]]` vs `[["a","x&b=y"]]`).
+ */
+function stableQueryString(sp: URLSearchParams): string {
+  return JSON.stringify(
+    Array.from(sp.entries()).toSorted(
+      ([ak, av], [bk, bv]) => ak.localeCompare(bk) || av.localeCompare(bv),
+    ),
+  );
+}