From bfb451ef7174067ae167b5a3d6517f74c4627366 Mon Sep 17 00:00:00 2001
From: Maksim <maxim.zinchuk@gmail.com>
Date: Thu, 18 Jun 2026 16:19:40 +0300
Subject: [PATCH] feat(vc-data-table): single-load restore for list views

Restoring sort/search/page from the URL used to trigger several loads at once,
so the data could disagree with the indicators after a reload. Move restore from
push to pull:

- useTableQueryPersistence no longer emits restore events on init; it keeps the
  URL write-back and only seeds the table's search box for display.
- Add useTableQueryState(stateKey).read() so a page seeds its own sort/search/page
  refs in setup and loads once.
- Add useDataTablePagination.setPage(n): set the page without firing onPageChange.

Update the create-vc-app list templates and the table docs to the single-loader
pattern. Unit tests cover read(), setPage, and the removed restore push.
---
 .../module/composables/useList.ts.ejs         | 85 ++++++++---------
 .../src/templates/module/pages/list.vue.ejs   | 84 +++++++++++-----
 .../templates/sample-module/pages/list.vue    | 80 +++++++---------
 framework/core/blade-navigation/index.ts      |  5 +
 .../table-query-state/index.ts                |  1 +
 .../useTableQueryState.docs.md                | 95 +++++++++++++++++++
 .../useTableQueryState.test.ts                | 37 ++++++++
 .../table-query-state/useTableQueryState.ts   | 28 ++++++
 .../organisms/vc-data-table/VcDataTable.vue   |  1 -
 .../useTableQueryPersistence.test.ts          | 30 +++---
 .../composables/useTableQueryPersistence.ts   | 41 +++-----
 .../vc-data-table/vc-data-table.docs.md       | 46 ++++++++-
 .../useDataTablePagination.docs.md            | 67 ++++++++-----
 .../useDataTablePagination.test.ts            | 18 ++++
 .../ui/composables/useDataTablePagination.ts  | 11 ++-
 .../ui/composables/useDataTableSort.docs.md   | 24 +++--
 16 files changed, 462 insertions(+), 191 deletions(-)
 create mode 100644 framework/core/blade-navigation/table-query-state/useTableQueryState.docs.md
 create mode 100644 framework/core/blade-navigation/table-query-state/useTableQueryState.test.ts
 create mode 100644 framework/core/blade-navigation/table-query-state/useTableQueryState.ts

diff --git a/cli/create-vc-app/src/templates/module/composables/useList.ts.ejs b/cli/create-vc-app/src/templates/module/composables/useList.ts.ejs
index 6997695db..4bd296abf 100644
--- a/cli/create-vc-app/src/templates/module/composables/useList.ts.ejs
+++ b/cli/create-vc-app/src/templates/module/composables/useList.ts.ejs
@@ -1,43 +1,42 @@
-import { ref, type Ref } from "vue";
-import { useAsync, useLoading } from "@vc-shell/framework";
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function use<%- ModuleNamePascalCase %>List() {
-  const data: Ref<Record<string, any>[]> = ref([]);
-  const totalCount = ref(0);
-  const currentPage = ref(1);
-  const searchQuery = ref("");
-
-  const { loading: itemsLoading, action: fetchItems } = useAsync(async () => {
-    // TODO: Replace with real API call
-    // const result = await apiClient.search({
-    //   keyword: searchQuery.value,
-    //   skip: (currentPage.value - 1) * 20,
-    //   take: 20,
-    // });
-    // data.value = result.results ?? [];
-    // totalCount.value = result.totalCount ?? 0;
-  });
-
-  const { loading: deleteLoading, action: removeItems } = useAsync(async (ids?: string[]) => {
-    // TODO: Replace with real API call
-    // await Promise.all((ids ?? []).map((id) => apiClient.delete(id)));
-    // await fetchItems();
-  });
-
-  const loading = useLoading(itemsLoading, deleteLoading);
-
-  async function getItems() {
-    await fetchItems();
-  }
-
-  return {
-    data,
-    loading,
-    totalCount,
-    currentPage,
-    searchQuery,
-    getItems,
-    removeItems,
-  };
-}
+import { ref, type Ref } from "vue";
+import { useAsync, useLoading } from "@vc-shell/framework";
+
+export interface <%- ModuleNamePascalCase %>ListQuery {
+  keyword?: string;
+  sort?: string;
+  skip?: number;
+  take?: number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function use<%- ModuleNamePascalCase %>List() {
+  const data: Ref<Record<string, any>[]> = ref([]);
+  const totalCount = ref(0);
+
+  const { loading: itemsLoading, action: getItems } = useAsync<<%- ModuleNamePascalCase %>ListQuery>(async (query) => {
+    // TODO: Replace with real API call
+    // const result = await apiClient.search({
+    //   keyword: query?.keyword,
+    //   sort: query?.sort,
+    //   skip: query?.skip ?? 0,
+    //   take: query?.take ?? 20,
+    // });
+    // data.value = result.results ?? [];
+    // totalCount.value = result.totalCount ?? 0;
+  });
+
+  const { loading: deleteLoading, action: removeItems } = useAsync(async (ids?: string[]) => {
+    // TODO: Replace with real API call
+    // await Promise.all((ids ?? []).map((id) => apiClient.delete(id)));
+  });
+
+  const loading = useLoading(itemsLoading, deleteLoading);
+
+  return {
+    data,
+    loading,
+    totalCount,
+    getItems,
+    removeItems,
+  };
+}
diff --git a/cli/create-vc-app/src/templates/module/pages/list.vue.ejs b/cli/create-vc-app/src/templates/module/pages/list.vue.ejs
index 882d2737a..23fedd93a 100644
--- a/cli/create-vc-app/src/templates/module/pages/list.vue.ejs
+++ b/cli/create-vc-app/src/templates/module/pages/list.vue.ejs
@@ -6,26 +6,28 @@
     width="50%"
   >
     <VcDataTable
+      v-model:search-value="searchValue"
+      v-model:sort-field="sortField"
+      v-model:sort-order="sortOrder"
       :items="data"
       :total-count="totalCount"
-      :current-page="currentPage"
-      :search-value="searchQuery"
+      :pagination="{ currentPage, pages }"
+      :searchable="true"
       :state-key="'<%- ModuleNameScreamingSnake %>'"
-      @search:change="(val: string) => { searchQuery = val; getItems(); }"
-      @item-click="openDetails"
-      @pagination-click="(page: number) => { currentPage = page; getItems(); }"
+      @row-click="onRowClick"
+      @pagination-click="onPaginationClick"
     >
       <!-- Add your columns here -->
-      <VcColumn id="name" :header="$t('<%- ModuleNameScreamingSnake %>.PAGES.LIST.COLUMNS.NAME')" sortable />
-      <VcColumn id="createdDate" :header="$t('<%- ModuleNameScreamingSnake %>.PAGES.LIST.COLUMNS.CREATED_DATE')" type="datetime" sortable />
+      <VcColumn id="name" :title="$t('<%- ModuleNameScreamingSnake %>.PAGES.LIST.COLUMNS.NAME')" sortable />
+      <VcColumn id="createdDate" :title="$t('<%- ModuleNameScreamingSnake %>.PAGES.LIST.COLUMNS.CREATED_DATE')" type="datetime" sortable />
     </VcDataTable>
   </VcBlade>
 </template>
 
 <script setup lang="ts">
-import { useBlade, type IBladeToolbar } from "@vc-shell/framework";
+import { useBlade, useDataTableSort, useTableQueryState, useFunctions, type IBladeToolbar } from "@vc-shell/framework";
 import { VcBlade, VcDataTable, VcColumn } from "@vc-shell/framework/ui";
-import { ref, onMounted } from "vue";
+import { computed, ref, watch } from "vue";
 import use<%- ModuleNamePascalCase %>List from "../composables/useList";
 import { useI18n } from "vue-i18n";
 
@@ -42,22 +44,57 @@ defineBlade({
 
 const { t } = useI18n({ useScope: "global" });
 const { openBlade, exposeToChildren } = useBlade();
+const { debounce } = useFunctions();
 
-const {
-  data,
-  loading,
-  totalCount,
-  currentPage,
-  searchQuery,
-  getItems,
-} = use<%- ModuleNamePascalCase %>List();
+const PAGE_SIZE = 20;
+
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+
+const { data, loading, totalCount, getItems } = use<%- ModuleNamePascalCase %>List();
+
+const searchValue = ref<string>();
+const currentPage = ref(1);
+const pages = computed(() => Math.ceil(totalCount.value / PAGE_SIZE) || 0);
+
+// Restore sort/search/page from the URL, then load once below.
+const restored = useTableQueryState("<%- ModuleNameScreamingSnake %>").read();
+if (restored.sort) {
+  const [field, direction] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = direction === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
+function load() {
+  return getItems({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
+    take: PAGE_SIZE,
+  });
+}
+
+// One loader for sort/search/page. Debounced so typing doesn't fetch per keystroke.
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+
+const onPaginationClick = (page: number) => {
+  currentPage.value = page;
+};
+
+const reload = () => load();
 
 const bladeToolbar = ref<IBladeToolbar[]>([
   {
     id: "refresh",
     title: t("<%- ModuleNameScreamingSnake %>.PAGES.LIST.TOOLBAR.REFRESH"),
     icon: "lucide-refresh-cw",
-    clickHandler: () => getItems(),
+    clickHandler: () => reload(),
   },
   {
     id: "add",
@@ -72,15 +109,14 @@ function openDetails(item?: { id?: string }) {
     name: "<%- ModuleNamePascalCase %>Details",
     param: item?.id,
     async onClose() {
-      await getItems();
+      await reload();
     },
   });
 }
 
-onMounted(async () => {
-  await getItems();
-})
-
+function onRowClick(event: { data: { id?: string } }) {
+  openDetails(event.data);
+}
 
-exposeToChildren({ reload: getItems });
+exposeToChildren({ reload });
 </script>
diff --git a/cli/create-vc-app/src/templates/sample-module/pages/list.vue b/cli/create-vc-app/src/templates/sample-module/pages/list.vue
index a00f878ca..8516fb2a0 100644
--- a/cli/create-vc-app/src/templates/sample-module/pages/list.vue
+++ b/cli/create-vc-app/src/templates/sample-module/pages/list.vue
@@ -7,6 +7,8 @@
     <!-- Blade contents -->
     <VcDataTable
       v-model:search-value="searchValue"
+      v-model:sort-field="sortField"
+      v-model:sort-order="sortOrder"
       v-model:active-item-id="selectedItemId"
       v-model:selection="selectedItems"
       :loading="loading"
@@ -32,7 +34,6 @@
       :total-label="$t('SAMPLE_APP.PAGES.LIST.TABLE.TOTALS')"
       :total-count="totalCount"
       state-key="SAMPLE_APP"
-      @search="onSearchList"
       @row-click="onItemClick"
       @pagination-click="onPaginationClick"
     >
@@ -73,8 +74,8 @@
 </template>
 
 <script lang="ts" setup>
-import { computed, ref, onMounted, watch } from "vue";
-import { IBladeToolbar, useBlade, usePopup, useTableSort, useFunctions } from "@vc-shell/framework";
+import { computed, ref, watch } from "vue";
+import { IBladeToolbar, useBlade, usePopup, useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
 import type { TableAction } from "@vc-shell/framework";
 import { VcColumn, VcDataTable, VcBlade } from "@vc-shell/framework/ui";
 import { useI18n } from "vue-i18n";
@@ -97,22 +98,35 @@ const { param, openBlade, exposeToChildren } = useBlade();
 const { showConfirmation } = usePopup();
 const { debounce } = useFunctions();
 
-const { sortExpression } = useTableSort({
-  initialProperty: "createdDate",
+const PAGE_SIZE = 20;
+
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
   initialDirection: "DESC",
 });
 
-const { getItems, removeItems, data, loading, totalCount, pages, currentPage, searchQuery } = useList({
+const { getItems, removeItems, data, loading, totalCount, pages } = useList({
   sort: sortExpression.value,
-  pageSize: 20,
+  pageSize: PAGE_SIZE,
 });
 
-const searchValue = ref();
+const searchValue = ref<string>();
+const currentPage = ref(1);
 const selectedItemId = ref<string>();
 const selectedItems = ref<MockedItem[]>([]);
 
 const selectedIds = computed(() => selectedItems.value.map((item) => item.id).filter(Boolean) as string[]);
 
+// Restore sort/search/page from the URL, then load once below.
+const restored = useTableQueryState("SAMPLE_APP").read();
+if (restored.sort) {
+  const [field, direction] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = direction === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
 watch(
   param,
   (newVal) => {
@@ -121,47 +135,29 @@ watch(
   { immediate: true },
 );
 
-onMounted(async () => {
-  await getItems({
-    ...searchQuery.value,
+function load() {
+  return getItems({
     sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
   });
-});
-
-watch(sortExpression, async (value) => {
-  await getItems({
-    ...searchQuery.value,
-    sort: value,
-  });
-});
+}
 
-const onSearchList = debounce(async (keyword: string) => {
-  searchValue.value = keyword;
-  await getItems({
-    ...searchQuery.value,
-    keyword,
-  });
-}, 1000);
+// One loader for sort/search/page. Debounced so typing doesn't fetch per keystroke.
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
 
-const clearSearch = async () => {
+const clearSearch = () => {
   searchValue.value = "";
-  await getItems({
-    ...searchQuery.value,
-    keyword: "",
-  });
 };
 
 const addItem = () => {
-  openBlade({
-    name: "SampleDetails",
-  });
+  openBlade({ name: "SampleDetails" });
 };
 
-const onPaginationClick = async (page: number) => {
-  await getItems({
-    ...searchQuery.value,
-    skip: (page - 1) * (searchQuery.value.take ?? 20),
-  });
+const onPaginationClick = (page: number) => {
+  currentPage.value = page;
 };
 
 const bladeToolbar = ref<IBladeToolbar[]>([
@@ -188,11 +184,7 @@ const title = computed(() => t("SAMPLE_APP.PAGES.LIST.TITLE"));
 
 const reload = async () => {
   selectedItems.value = [];
-  await getItems({
-    ...searchQuery.value,
-    skip: (currentPage.value - 1) * (searchQuery.value.take ?? 10),
-    sort: sortExpression.value,
-  });
+  await load();
 };
 
 const onItemClick = (event: { data: MockedItem; index: number; originalEvent: Event }) => {
diff --git a/framework/core/blade-navigation/index.ts b/framework/core/blade-navigation/index.ts
index ad1716a0b..323bed4c7 100644
--- a/framework/core/blade-navigation/index.ts
+++ b/framework/core/blade-navigation/index.ts
@@ -3,3 +3,8 @@ export { useBladeStack } from "@core/blade-navigation/useBladeStack";
 export { useBladeMessaging } from "@core/blade-navigation/useBladeMessaging";
 export * from "@core/blade-navigation/types";
 export { __registerBladeConfig, getBladeConfig, getAllBladeConfigs } from "@core/blade-navigation/bladeConfigRegistry";
+// Table query-state: page-facing pull-accessor only. The TableQueryStateKey service
+// and createBladeQueryState factory stay internal (consumed directly by VcDataTable
+// and the blade rendering layer).
+export { useTableQueryState } from "@core/blade-navigation/table-query-state";
+export type { UseTableQueryStateReturn, TableQueryPatch } from "@core/blade-navigation/table-query-state";
diff --git a/framework/core/blade-navigation/table-query-state/index.ts b/framework/core/blade-navigation/table-query-state/index.ts
index 4ad04cc41..45fd829e9 100644
--- a/framework/core/blade-navigation/table-query-state/index.ts
+++ b/framework/core/blade-navigation/table-query-state/index.ts
@@ -1,3 +1,4 @@
 export * from "./types";
 export * from "./serialization";
 export * from "./createBladeQueryState";
+export * from "./useTableQueryState";
diff --git a/framework/core/blade-navigation/table-query-state/useTableQueryState.docs.md b/framework/core/blade-navigation/table-query-state/useTableQueryState.docs.md
new file mode 100644
index 000000000..e6c87dda5
--- /dev/null
+++ b/framework/core/blade-navigation/table-query-state/useTableQueryState.docs.md
@@ -0,0 +1,95 @@
+---
+title: useTableQueryState
+category: composables
+group: data
+---
+
+# useTableQueryState
+
+Reads the table view state (`sort`, `search`, `page`) that `VcDataTable` persists to the URL query for URL-addressable blades. A list page calls `read()` in `setup` to seed its own refs from the restored state before its loader runs, so a reload makes one request.
+
+Read-only: writing the view state to the URL stays inside `VcDataTable`. This composable only exposes the restored values to the page.
+
+## When to Use
+
+- A list blade is URL-addressable (workspace or routable) and uses `VcDataTable` with a `state-key`
+- You want a single, coordinated load on reload (sort + search + page restored together)
+- You are wiring the page's combined loader watcher and need the restored seed values
+
+## When NOT to Use
+
+- The table is standalone or its blade has no URL — there is nothing to restore (`read()` returns `{}`)
+- You only need the live view state — that already lives in your own `sortField`/`searchValue`/`currentPage` refs
+- You want to _write_ to the URL — that is automatic; do not persist manually
+
+## Basic Usage
+
+```ts
+import { ref, watch } from "vue";
+import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+
+const PAGE_SIZE = 20;
+const { debounce } = useFunctions();
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+const searchValue = ref<string>();
+const currentPage = ref(1);
+
+// Seed refs from the URL before the loader runs.
+const restored = useTableQueryState("offers_list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
+function load() {
+  return loadItems({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
+  });
+}
+
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+```
+
+## API
+
+### Parameters
+
+| Parameter  | Type                  | Default     | Description                                                               |
+| ---------- | --------------------- | ----------- | ------------------------------------------------------------------------- |
+| `stateKey` | `string \| undefined` | `undefined` | The same `state-key` passed to `VcDataTable` for this table (namespacing) |
+
+### Returns
+
+| Property | Type                    | Description                                                                                            |
+| -------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `read`   | `() => TableQueryPatch` | Reads the restored `{ sort?, search?, page? }` from the URL. Returns `{}` when no service is available |
+
+`TableQueryPatch`: `{ sort?: string; search?: string; page?: number }` — `sort` is a `"field:ASC"` / `"field:DESC"` expression, `page` is 1-based.
+
+## Details
+
+- **Read in `setup`**: `VcDataTable` does not emit restore events on init; the page reads the state and seeds its refs in `setup`. This avoids a separate load per restored field.
+- **No-op without a service**: When no blade provides the persistence service (standalone table, non-URL blade), `read()` returns `{}`, so you can call it unconditionally.
+- **Write-back is automatic**: View state → URL (debounced `router.replace`) is handled by `VcDataTable` via `useTableQueryPersistence`. Pages do not persist manually.
+
+## Tips
+
+- Call `read()` once, synchronously, before the loader. Seeding after it runs causes an extra load.
+- Use `useDataTablePagination`'s `setPage(n)` to seed the page without firing `onPageChange`.
+- Pass the same `state-key` you give `VcDataTable`, so the URL keys match.
+
+## Related
+
+- [`useDataTableSort`](../../../ui/composables/useDataTableSort.docs.md) — sort state composable for `VcDataTable`
+- [`useDataTablePagination`](../../../ui/composables/useDataTablePagination.docs.md) — pagination state composable (`setPage` for restore seed)
+- `VcDataTable` → _URL query persistence_ — the write-back side of this contract
diff --git a/framework/core/blade-navigation/table-query-state/useTableQueryState.test.ts b/framework/core/blade-navigation/table-query-state/useTableQueryState.test.ts
new file mode 100644
index 000000000..56ffcf644
--- /dev/null
+++ b/framework/core/blade-navigation/table-query-state/useTableQueryState.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from "vitest";
+import { defineComponent, h } from "vue";
+import { mount } from "@vue/test-utils";
+import { TableQueryStateKey } from "./types";
+import type { ITableQueryStateService, TableQueryPatch } from "./types";
+import { useTableQueryState } from "./useTableQueryState";
+
+function harness(service: ITableQueryStateService | undefined, stateKey?: string) {
+  let patch: TableQueryPatch | undefined;
+  const Comp = defineComponent({
+    setup() {
+      patch = useTableQueryState(stateKey).read();
+      return () => h("div");
+    },
+  });
+  mount(Comp, { global: { provide: { [TableQueryStateKey as symbol]: service } } });
+  return patch!;
+}
+
+describe("useTableQueryState", () => {
+  it("returns the restored patch from the injected service", () => {
+    const read = vi.fn(() => ({ sort: "name:DESC", search: "foo", page: 3 }));
+    const patch = harness({ read, write: vi.fn() });
+    expect(patch).toEqual({ sort: "name:DESC", search: "foo", page: 3 });
+  });
+
+  it("forwards the stateKey to the service", () => {
+    const read = vi.fn(() => ({}));
+    harness({ read, write: vi.fn() }, "offers_list");
+    expect(read).toHaveBeenCalledWith("offers_list");
+  });
+
+  it("returns an empty patch when no service is provided", () => {
+    const patch = harness(undefined);
+    expect(patch).toEqual({});
+  });
+});
diff --git a/framework/core/blade-navigation/table-query-state/useTableQueryState.ts b/framework/core/blade-navigation/table-query-state/useTableQueryState.ts
new file mode 100644
index 000000000..fcb8594de
--- /dev/null
+++ b/framework/core/blade-navigation/table-query-state/useTableQueryState.ts
@@ -0,0 +1,28 @@
+import { inject } from "vue";
+import { TableQueryStateKey, type TableQueryPatch } from "./types";
+
+export interface UseTableQueryStateReturn {
+  /**
+   * Read the table view state (sort/search/page) restored from the URL for this
+   * table. Returns an empty patch when no persistence service is provided (a
+   * standalone table or a non-URL blade), so callers can use it unconditionally.
+   */
+  read(): TableQueryPatch;
+}
+
+/**
+ * Reads the table view state (sort/search/page) restored from the URL.
+ *
+ * A list page calls this in `setup`, reads `{ sort, search, page }`, and seeds its
+ * own refs before its loader runs, so a reload makes one request. Read-only: the
+ * write-back (view state → URL) stays inside VcDataTable via useTableQueryPersistence.
+ *
+ * @param stateKey  The same `state-key` passed to VcDataTable for this table.
+ */
+export function useTableQueryState(stateKey?: string): UseTableQueryStateReturn {
+  const service = inject(TableQueryStateKey, undefined);
+
+  return {
+    read: () => (service ? service.read(stateKey) : {}),
+  };
+}
diff --git a/framework/ui/components/organisms/vc-data-table/VcDataTable.vue b/framework/ui/components/organisms/vc-data-table/VcDataTable.vue
index a4cd424f6..019268f75 100644
--- a/framework/ui/components/organisms/vc-data-table/VcDataTable.vue
+++ b/framework/ui/components/organisms/vc-data-table/VcDataTable.vue
@@ -1018,7 +1018,6 @@ watch(
 // No-op unless a blade provides ITableQueryStateService (URL-addressable blade).
 useTableQueryPersistence<T>({
   props,
-  emit: emit as unknown as (event: string, value?: unknown) => void,
   internalSearchValue,
 });
 
diff --git a/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.test.ts b/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.test.ts
index 278ae5709..cb617755a 100644
--- a/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.test.ts
+++ b/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.test.ts
@@ -6,7 +6,6 @@ import type { ITableQueryStateService } from "@core/blade-navigation/table-query
 import { useTableQueryPersistence } from "./useTableQueryPersistence";
 
 function harness(service: ITableQueryStateService | undefined, initialProps: Record<string, unknown> = {}) {
-  const emitted: Array<[string, unknown]> = [];
   const internalSearchValue = ref("");
 
   const Comp = defineComponent({
@@ -14,7 +13,6 @@ function harness(service: ITableQueryStateService | undefined, initialProps: Rec
     setup(props) {
       useTableQueryPersistence({
         props: props as never,
-        emit: ((event: string, value: unknown) => emitted.push([event, value])) as never,
         internalSearchValue,
       });
       return () => h("div");
@@ -33,30 +31,30 @@ function harness(service: ITableQueryStateService | undefined, initialProps: Rec
     global: { provide: { [TableQueryStateKey as symbol]: service } },
   });
 
-  return { wrapper, emitted, internalSearchValue };
+  return { wrapper, internalSearchValue };
 }
 
 describe("useTableQueryPersistence", () => {
   it("does nothing when no service is provided", async () => {
-    const { emitted } = harness(undefined, { pagination: { currentPage: 1, pages: 5 } });
+    const { internalSearchValue } = harness(undefined, { pagination: { currentPage: 1, pages: 5 } });
     await nextTick();
-    expect(emitted).toEqual([]);
+    expect(internalSearchValue.value).toBe("");
   });
 
-  it("seeds sort/search/page from the service on init", async () => {
+  // The composable does not push restore events to the page (the page reads state
+  // via useTableQueryState). The only restore effect here is seeding the search box.
+  it("seeds only the search box on init and does not write back", async () => {
+    const write = vi.fn();
     const service: ITableQueryStateService = {
       read: () => ({ sort: "name:DESC", search: "foo", page: 3 }),
-      write: vi.fn(),
+      write,
     };
-    const { emitted, internalSearchValue } = harness(service);
-
-    expect(emitted).toContainEqual(["update:sortField", "name"]);
-    expect(emitted).toContainEqual(["update:sortOrder", -1]);
-    expect(emitted).toContainEqual(["sort", { sortField: "name", sortOrder: -1 }]);
-    expect(emitted).toContainEqual(["update:searchValue", "foo"]);
-    expect(emitted).toContainEqual(["search", "foo"]);
-    expect(emitted).toContainEqual(["pagination-click", 3]);
+    const { internalSearchValue } = harness(service);
+    await nextTick();
+
     expect(internalSearchValue.value).toBe("foo");
+    // Restoring must not bounce the just-read values back into the URL.
+    expect(write).not.toHaveBeenCalled();
   });
 
   it("does NOT write back the value it just restored (echo dedup)", async () => {
@@ -64,7 +62,7 @@ describe("useTableQueryPersistence", () => {
     const service: ITableQueryStateService = { read: () => ({ page: 2 }), write };
     const { wrapper } = harness(service, { pagination: { currentPage: 1, pages: 5 } });
 
-    // Parent applies the restored page (echo) after the pagination-click emit.
+    // Parent applies the restored page (echo) after seeding its own refs.
     await wrapper.setProps({ pagination: { currentPage: 2, pages: 5 } });
     await nextTick();
 
diff --git a/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.ts b/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.ts
index 4b0255ab2..48fef6660 100644
--- a/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.ts
+++ b/framework/ui/components/organisms/vc-data-table/composables/useTableQueryPersistence.ts
@@ -5,8 +5,6 @@ import type { VcDataTableExtendedProps } from "@ui/components/organisms/vc-data-
 export interface UseTableQueryPersistenceOptions<T extends Record<string, unknown>> {
   /** VcDataTable props (read sortField/sortOrder/searchValue/pagination/stateKey). */
   props: VcDataTableExtendedProps<T>;
-  /** VcDataTable emit. */
-  emit: (event: string, value?: unknown) => void;
   /** Live search UI state owned by VcDataTable. */
   internalSearchValue: Ref<string>;
 }
@@ -16,11 +14,14 @@ export interface UseTableQueryPersistenceOptions<T extends Record<string, unknow
  * optional per-blade ITableQueryStateService. No-op when no service is provided
  * (standalone table or non-URL blade).
  *
- * On init it seeds the parent (v-models + search/pagination events) from the
- * restored URL state, then watches for changes and writes them back (the service
- * debounces). To avoid writing back the just-restored values (the parent echoes
- * them as prop changes on a later tick), each field tracks its last-applied value
- * and skips writes that match it — timing-independent, unlike a transient flag.
+ * This handles the write side: it watches sort/search/page and writes them to the
+ * URL (the service debounces). To avoid writing back values the page just restored
+ * (the parent echoes them as prop changes a tick later), each field remembers its
+ * last-applied value and skips writes that match it.
+ *
+ * It does not push restored state to the page — the page reads it via
+ * useTableQueryState. The only restore-side effect here is seeding the table's own
+ * search box for display, which does not load.
  */
 export function useTableQueryPersistence<T extends Record<string, unknown>>(
   options: UseTableQueryPersistenceOptions<T>,
@@ -28,38 +29,22 @@ export function useTableQueryPersistence<T extends Record<string, unknown>>(
   const service = inject(TableQueryStateKey, undefined);
   if (!service) return;
 
-  const { props, emit, internalSearchValue } = options;
+  const { props, internalSearchValue } = options;
 
-  // ── Restore (synchronous, during setup, before the parent's mounted load) ──
   const restored = service.read(props.stateKey);
 
-  // Seed-and-dedup state: remember what we last pushed/applied per field, so the
-  // parent's prop echo of the restored values does not bounce back into a write.
+  // Last value written per field, so the page's prop echo of the restored values
+  // is not written back.
   let lastSort: string | undefined = restored.sort;
   let lastSearch = restored.search ?? "";
   let lastPage: number | undefined = restored.page;
 
-  if (restored.sort) {
-    const [field, dir] = restored.sort.split(":");
-    if (field) {
-      const order = dir === "DESC" ? -1 : 1;
-      emit("update:sortField", field);
-      emit("update:sortOrder", order);
-      // Mirror a genuine sort so adapter-based tables (which react only to
-      // `@sort`, not the sort-field/sort-order v-models) also restore sort.
-      emit("sort", { sortField: field, sortOrder: order });
-    }
-  }
+  // Show the restored keyword in the table's own search box (display only, no load).
   if (restored.search !== undefined) {
     internalSearchValue.value = restored.search;
-    emit("update:searchValue", restored.search);
-    emit("search", restored.search);
-  }
-  if (restored.page !== undefined) {
-    emit("pagination-click", restored.page);
   }
 
-  // ── Write (push genuine view-state changes back to the URL) ────────────────
+  // Write view-state changes back to the URL.
   function currentSortExpression(): string | undefined {
     const field = props.sortField;
     const order = props.sortOrder;
diff --git a/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md b/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md
index 0fd87be28..82927868c 100644
--- a/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md
+++ b/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md
@@ -1065,16 +1065,56 @@ Listen to state events:
 
 ### URL query persistence
 
-When a table is rendered inside a **URL-addressable blade** (a workspace or routable blade whose address appears in the address bar), its **sort**, **search**, and **current page** are automatically persisted to the URL query string. Reloading the page — or sharing the link — restores that view.
+When a table is rendered inside a URL-addressable blade (a workspace or routable blade whose address appears in the address bar), its sort, search, and current page are persisted to the URL query string. Reloading the page or sharing the link restores that view.
 
-This works out of the box; you do not wire it up. The behavior is provided through the blade context: tables outside a blade (or in a blade with no URL) simply do not persist (no-op).
+Writing the view state to the URL is automatic — you do not wire it up. Tables outside a blade (or in a blade with no URL) do not persist (no-op). Reading it back on reload is done by the page (see below).
 
 - **Namespacing:** query keys are prefixed with the table's `state-key` if set, otherwise with the blade's URL segment — e.g. `?offers_sort=name:DESC&offers_search=foo&offers_page=2`. Give each table a unique `state-key` when several tables can be visible at once (the same rule as column-layout persistence).
 - **Keys:** `<ns>_sort` (`field:ASC` / `field:DESC`), `<ns>_search`, `<ns>_page` (1-based).
 - **History:** changes use `router.replace`, so they do not add browser-history entries.
 - **Scope:** only sort, search, and page. Column layout still uses `localStorage`/`sessionStorage` (above); column filters and selection are not persisted.
 
-On reload the restored values are applied through the table's normal `v-model:sort-field` / `v-model:sort-order` / `v-model:search-value` and `pagination-click` channels, so the owning blade loads data with the restored parameters without any extra code.
+The page reads the persisted values with `useTableQueryState(stateKey)`, seeds its sort/search/page refs in `setup`, and loads once. The table does not push the restored values back into the page, so a reload runs a single request rather than one per restored field.
+
+```ts
+import { ref, watch } from "vue";
+import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+
+const PAGE_SIZE = 20;
+const { debounce } = useFunctions();
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+const searchValue = ref<string>();
+const currentPage = ref(1);
+
+// Restore from the URL, then load once.
+const restored = useTableQueryState("offers_list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
+function load() {
+  return loadItems({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
+  });
+}
+
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+
+function onPaginationClick(page: number) {
+  currentPage.value = page;
+}
+```
 
 If a blade cannot be reopened on reload (e.g. a non-routable blade, or an intermediate blade that is not on the restored URL path), its table query params have no owner — they are automatically dropped from the URL once the restored blades have mounted, so the address bar never accumulates stale query keys.
 
diff --git a/framework/ui/composables/useDataTablePagination.docs.md b/framework/ui/composables/useDataTablePagination.docs.md
index 5df1a597c..762dd1dd2 100644
--- a/framework/ui/composables/useDataTablePagination.docs.md
+++ b/framework/ui/composables/useDataTablePagination.docs.md
@@ -29,7 +29,6 @@ import { useDataTablePagination } from "@vc-shell/framework";
 const pagination = useDataTablePagination({
   pageSize: 20,
   totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-  onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
 });
 ```
 
@@ -37,6 +36,8 @@ const pagination = useDataTablePagination({
 <VcDataTable :items="items" :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
 ```
 
+> **Note:** Let `@pagination-click` only update the page (`goToPage`) and load from one watcher that reads `pagination.skip` together with sort and search — see the recipe below. `onPageChange` (load on each page change) still works for simple tables, but do not combine it with that watcher or the page loads twice.
+
 ## API
 
 ### Parameters (Options)
@@ -49,15 +50,16 @@ const pagination = useDataTablePagination({
 
 ### Returns (`reactive()` object)
 
-| Property      | Type                     | Description                                   |
-| ------------- | ------------------------ | --------------------------------------------- |
-| `currentPage` | `number`                 | Current 1-based page number (writable)        |
-| `pages`       | `number` (readonly)      | Total number of pages                         |
-| `skip`        | `number` (readonly)      | Current skip offset for API calls             |
-| `pageSize`    | `number` (readonly)      | Resolved page size                            |
-| `totalCount`  | `number` (readonly)      | Resolved total item count                     |
-| `goToPage`    | `(page: number) => void` | Navigate to page; fires `onPageChange`        |
-| `reset`       | `() => void`             | Reset to page 1; does NOT fire `onPageChange` |
+| Property      | Type                     | Description                                                             |
+| ------------- | ------------------------ | ----------------------------------------------------------------------- |
+| `currentPage` | `number`                 | Current 1-based page number (writable)                                  |
+| `pages`       | `number` (readonly)      | Total number of pages                                                   |
+| `skip`        | `number` (readonly)      | Current skip offset for API calls                                       |
+| `pageSize`    | `number` (readonly)      | Resolved page size                                                      |
+| `totalCount`  | `number` (readonly)      | Resolved total item count                                               |
+| `goToPage`    | `(page: number) => void` | Navigate to page; fires `onPageChange`                                  |
+| `setPage`     | `(page: number) => void` | Seed the page WITHOUT firing `onPageChange` — use for pull-restore seed |
+| `reset`       | `() => void`             | Reset to page 1; does NOT fire `onPageChange`                           |
 
 All properties are auto-unwrapped by `reactive()` — no `.value` access needed in script or template.
 
@@ -65,30 +67,43 @@ All properties are auto-unwrapped by `reactive()` — no `.value` access needed
 
 ```vue
 <script setup lang="ts">
-import { ref, computed } from "vue";
-import { useDataTablePagination, useDataTableSort } from "@vc-shell/framework";
+import { ref, computed, watch } from "vue";
+import { useDataTablePagination, useDataTableSort, useTableQueryState } from "@vc-shell/framework";
 
 // Data layer
 const searchResult = ref<{ results: Item[]; totalCount: number }>();
-const searchQuery = ref({ take: 20, skip: 0 });
 
-async function loadItems(query?: Partial<typeof searchQuery.value>) {
-  searchQuery.value = { ...searchQuery.value, ...query };
-  searchResult.value = await api.search(searchQuery.value);
+async function loadItems(query: { sort?: string; keyword?: string; skip?: number }) {
+  searchResult.value = await api.search({ take: 20, ...query });
 }
 
-// Pagination state
+// State only — no self-loading callback.
 const pagination = useDataTablePagination({
   pageSize: 20,
   totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-  onPageChange: ({ skip }) => loadItems({ skip }),
 });
-
-// Sort state
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
   initialField: "createdDate",
   initialDirection: "DESC",
 });
+const searchValue = ref<string>();
+
+// Restore from the URL, then load once. setPage seeds the page without loading.
+const restored = useTableQueryState("product-list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) pagination.setPage(restored.page);
+
+// One loader reading sort + search + page.
+watch(
+  () => ({ sort: sortExpression.value, keyword: searchValue.value || undefined, skip: pagination.skip }),
+  (query) => loadItems(query),
+  { immediate: true },
+);
 </script>
 
 <template>
@@ -97,6 +112,12 @@ const { sortField, sortOrder, sortExpression } = useDataTableSort({
     :total-count="pagination.totalCount"
     :pagination="pagination"
     @pagination-click="pagination.goToPage"
+    @search="
+      (kw) => {
+        searchValue = kw;
+        pagination.setPage(1);
+      }
+    "
     v-model:sort-field="sortField"
     v-model:sort-order="sortOrder"
   >
@@ -130,7 +151,6 @@ export function useOffers() {
   const pagination = useDataTablePagination({
     pageSize: 20,
     totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-    onPageChange: ({ skip }) => loadOffers({ ...searchQuery.value, skip }),
   });
 
   return {
@@ -141,7 +161,7 @@ export function useOffers() {
 }
 ```
 
-Blade then simply binds:
+The blade owns the single loader watch (reading `pagination.skip` with sort/search) and binds:
 
 ```vue
 <VcDataTable :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
@@ -150,7 +170,8 @@ Blade then simply binds:
 ## Details
 
 - **`reactive()` return**: The composable wraps its return in `reactive()`, so all `Ref`/`ComputedRef` properties are auto-unwrapped. Access with `pagination.pages` (not `pagination.pages.value`). This allows the object to be passed directly as `:pagination` prop to VcDataTable without intermediate conversion.
-- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not know about data fetching — it just notifies.
+- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not fetch data. With a single loader watcher you usually omit it and read `pagination.skip` from the watcher instead.
+- **`setPage` vs `goToPage`**: `goToPage(n)` updates the page and fires `onPageChange`; `setPage(n)` updates it without the callback. Use `setPage` to seed the page from a URL restore so the seed itself does not load.
 - **No auto-clamp**: When `totalCount` decreases (e.g. after deletion), `currentPage` is NOT automatically clamped. Call `reset()` or `goToPage(1)` explicitly after mutations.
 - **reset() is silent**: `reset()` sets `currentPage = 1` but does NOT fire `onPageChange`. This prevents accidental double-fetches when the consumer resets pagination during a reload.
 - **Pure without callback**: Omit `onPageChange` and the composable works as pure state — useful for unit tests or when the consumer prefers to watch properties reactively.
diff --git a/framework/ui/composables/useDataTablePagination.test.ts b/framework/ui/composables/useDataTablePagination.test.ts
index 44604486b..b3d8b5804 100644
--- a/framework/ui/composables/useDataTablePagination.test.ts
+++ b/framework/ui/composables/useDataTablePagination.test.ts
@@ -58,6 +58,24 @@ describe("useDataTablePagination", () => {
     });
   });
 
+  describe("setPage", () => {
+    it("updates currentPage and skip", () => {
+      const { result } = mountWithSetup(() => useDataTablePagination({ totalCount: ref(100), pageSize: 20 }));
+      result.setPage(3);
+      expect(result.currentPage).toBe(3);
+      expect(result.skip).toBe(40); // (3-1)*20
+    });
+
+    it("does NOT fire onPageChange (pull-restore seed)", () => {
+      const onPageChange = vi.fn();
+      const { result } = mountWithSetup(() =>
+        useDataTablePagination({ totalCount: ref(100), pageSize: 20, onPageChange }),
+      );
+      result.setPage(4);
+      expect(onPageChange).not.toHaveBeenCalled();
+    });
+  });
+
   describe("reset", () => {
     it("resets currentPage to 1", () => {
       const { result } = mountWithSetup(() => useDataTablePagination({ totalCount: ref(100), pageSize: 20 }));
diff --git a/framework/ui/composables/useDataTablePagination.ts b/framework/ui/composables/useDataTablePagination.ts
index 901ac6ae3..c834f768c 100644
--- a/framework/ui/composables/useDataTablePagination.ts
+++ b/framework/ui/composables/useDataTablePagination.ts
@@ -22,6 +22,11 @@ export interface UseDataTablePaginationReturn {
   readonly totalCount: number;
   /** Navigate to a specific page. Fires onPageChange if provided. */
   goToPage: (page: number) => void;
+  /**
+   * Set the current page without firing onPageChange. Use to seed the page from a
+   * URL restore in setup, so the seed itself does not trigger a load.
+   */
+  setPage: (page: number) => void;
   /** Reset to page 1. Does NOT fire onPageChange. */
   reset: () => void;
 }
@@ -38,9 +43,13 @@ export function useDataTablePagination(options: UseDataTablePaginationOptions):
     options.onPageChange?.({ page, skip: skip.value });
   }
 
+  function setPage(page: number) {
+    currentPage.value = page;
+  }
+
   function reset() {
     currentPage.value = 1;
   }
 
-  return reactive({ currentPage, pages, skip, pageSize, totalCount, goToPage, reset });
+  return reactive({ currentPage, pages, skip, pageSize, totalCount, goToPage, setPage, reset });
 }
diff --git a/framework/ui/composables/useDataTableSort.docs.md b/framework/ui/composables/useDataTableSort.docs.md
index 7f1baed63..33b06b2c6 100644
--- a/framework/ui/composables/useDataTableSort.docs.md
+++ b/framework/ui/composables/useDataTableSort.docs.md
@@ -84,14 +84,16 @@ const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
 
 const items = ref([]);
 const loading = ref(false);
+const currentPage = ref(1);
+const PAGE_SIZE = 20;
 
-async function loadItems() {
+async function loadItems(query: { sort?: string; skip?: number }) {
   loading.value = true;
   try {
     const response = await api.searchProducts({
-      sort: sortExpression.value, // e.g. "createdDate:DESC" or undefined
-      skip: 0,
-      take: 20,
+      sort: query.sort, // e.g. "createdDate:DESC" or undefined
+      skip: query.skip ?? 0,
+      take: PAGE_SIZE,
     });
     items.value = response.results;
   } finally {
@@ -99,8 +101,13 @@ async function loadItems() {
   }
 }
 
-// Reload whenever sort changes; { immediate: true } loads data on mount
-watch(sortExpression, () => loadItems(), { immediate: true });
+// Load from one watcher that reads sort together with search and page, so changing
+// several at once is a single request. { immediate: true } also does the first load.
+watch(
+  () => ({ sort: sortExpression.value, skip: (currentPage.value - 1) * PAGE_SIZE }),
+  (query) => loadItems(query),
+  { immediate: true },
+);
 </script>
 
 <template>
@@ -134,12 +141,13 @@ watch(sortExpression, () => loadItems(), { immediate: true });
 - **Sort expression format**: `sortExpression` returns `"field:DIRECTION"` when both `sortField` and a non-zero `sortOrder` are set, otherwise `undefined`. This format is directly compatible with VirtoCommerce Platform search endpoints.
 - **Reset behavior**: `resetSort()` restores `sortField` and `sortOrder` to the values passed at construction time. If no initial options were provided, both are cleared.
 - **Numeric order convention**: `VcDataTable` uses PrimeVue's numeric sort order convention (`1`/`-1`/`0`). This composable encapsulates the mapping so call sites never need to handle the numeric values directly.
-- **Stateless regarding data**: The composable only manages the sort field and direction. Combine it with your own data-fetching logic using `watch(sortExpression, ...)`.
+- **Stateless regarding data**: The composable only manages the sort field and direction. Read `sortExpression` from the same loader watcher that reads search and page, instead of giving sort its own `watch(sortExpression, load)`. See VcDataTable → URL query persistence.
 
 ## Tips
 
 - Always mark columns as `sortable` in your `<VcColumn>` definitions for the sort indicator icon to appear.
-- Use `{ immediate: true }` on the `watch(sortExpression, ...)` call to trigger the initial data load with the correct sort on mount.
+- Use `{ immediate: true }` on the combined loader watcher to trigger the initial (or URL-restored) data load with the correct sort on mount.
+- On reload, seed `sortField`/`sortOrder` from `useTableQueryState(stateKey).read().sort` (`"field:DIR"`) before the loader watcher, so restore costs a single request.
 - Call `resetSort()` alongside any "clear all filters" action to keep sort state consistent with the rest of the filter UI.
 
 ## Related