feat: add URL state persistence of CollectionControl

.changeset/witty-mice-drum.md

@@ -0,0 +1,16 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add `useURLCollectionVariables` for wiring collection state (filters, sort, page size) to the URL query string in a single call. It seeds initial state from the current router search params and writes changes back as the user filters, sorts, or pages.
+
+```tsx
+const { variables, control } = useURLCollectionVariables({
+  tableMetadata,
+  params: { pageSize: 20 },
+});
+```
+
+For cases that need URL persistence without react-router's `useSearchParams` (e.g. a custom binding), the pure `withURLCollectionState(options, [searchParams, setSearchParams])` decorator is also exported and can be composed with `useCollectionVariables` directly.
+
+`useCollectionVariables` now reports state updates through `onParamsChange` using the same `params` shape it accepts.

examples/nextjs-app/src/modules/pages/data-table-demo.tsx

@@ -2,7 +2,7 @@ import {
   defineResource,
   DataTable,
   useDataTable,
-  useCollectionVariables,
+  useURLCollectionVariables,
   createColumnHelper,
   Layout,
   type RowAction,
@@ -140,7 +140,7 @@ const productRowActions: RowAction<Product>[] = [
 // ---------------------------------------------------------------------------
 
 const DataTableDemoPage = () => {
-  const { variables, control } = useCollectionVariables({
+  const { variables, control } = useURLCollectionVariables({
     params: { pageSize: 5 },
     tableMetadata: productMetadata,
   });

examples/vite-app/src/App.tsx

@@ -33,6 +33,7 @@ const App = () => {
             <SidebarGroup title={labels.t("navMain")}>
               <SidebarItem to="/dashboard" activeMatch="exact" />
               <SidebarItem to="/dashboard/orders" />
+              <SidebarItem to="/dashboard/products" />
             </SidebarGroup>
             <SidebarItem to="/settings" />
           </DefaultSidebar>