@vc-shell/vc-app-skill 2.0.11 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.11",
+  "version": "2.1.0",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.0.11
+2.1.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit f2225cc27 on 2026-06-22T15:40:33.524Z
+Synced from framework at commit 3a32dc437 on 2026-06-22T17:27:53.738Z

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/vc-data-table.docs.md

@@ -1032,7 +1032,7 @@ async function loadNextPage() {
 !!! tip "Use unique state keys"
 Every table in your application must have a distinct `state-key`. Two tables sharing the same key will silently overwrite each other's persisted column widths, order, and hidden/shown column lists.
 
-Persist column widths, column order, and column visibility across page reloads. Column layout is stored in `localStorage`/`sessionStorage` (keyed by `state-key`). Sort, search, and the current page are persisted separately — to the **URL query** — automatically when the table is rendered inside a URL-addressable blade (see [URL query persistence](#url-query-persistence) below). Selection, column filters, and other transient state are session-scoped and are deliberately excluded from any persistence:
+Persist column widths, column order, and column visibility across page reloads. Column layout is stored in `localStorage`/`sessionStorage` (keyed by `state-key`). Sort, search, and the current page are NOT persisted by the table itself -- use the state composables with a matching `stateKey` instead (see [URL query persistence](#url-query-persistence) below). Selection, column filters, and other transient state are session-scoped and are deliberately excluded from any persistence:
 
 ```vue
 <VcDataTable :items="products" state-key="product-list">
@@ -1067,58 +1067,78 @@ 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 persisted to the URL query string. Reloading the page or sharing the link restores that view.
+Sort, search, and the current page are owned by the state composables, not by `VcDataTable`. The `state-key` prop on `VcDataTable` controls column-layout persistence (localStorage/sessionStorage) only.
 
-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).
+To persist query state to the blade URL, use `useDataTableSort`, `useTableSearch`, and `useDataTablePagination` with a matching `stateKey`. Each composable restores its slice from the URL on creation and persists changes via `router.replace` (no history entries added).
 
-- **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.
+- **Namespacing:** URL keys are prefixed with the `stateKey` value -- e.g. `?offers_list_sort=name:DESC&offers_list_search=foo&offers_list_page=2`. Use the same string for all three composables on a given page.
+- **Keys:** `<stateKey>_sort` (`field:ASC` / `field:DESC`), `<stateKey>_search`, `<stateKey>_page` (1-based).
+- **Scope:** sort, search, and page only. Column layout still uses localStorage/sessionStorage; column filters and selection are not persisted.
 
-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.
+Canonical list-page pattern:
 
-```ts
-import { ref, watch } from "vue";
-import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+```vue
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from "vue";
+import { useDataTableSort, useDataTablePagination, useTableSearch } from "@vc-shell/framework";
+
+const STATE_KEY = "offers_list";
 
-const PAGE_SIZE = 20;
-const { debounce } = useFunctions();
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: STATE_KEY,
   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;
+const { searchValue } = useTableSearch({ stateKey: STATE_KEY });
+
+const searchResult = ref<{ results: Offer[]; totalCount: number }>();
+const totalCount = computed(() => searchResult.value?.totalCount ?? 0);
 
-function load() {
-  return loadItems({
+const pagination = useDataTablePagination({
+  stateKey: STATE_KEY,
+  pageSize: 20,
+  totalCount,
+});
+
+async function load() {
+  searchResult.value = await api.searchOffers({
     sort: sortExpression.value,
-    keyword: searchValue.value || undefined,
-    skip: (currentPage.value - 1) * PAGE_SIZE,
+    keyword: searchValue.value,
+    skip: pagination.skip,
+    take: pagination.pageSize,
   });
 }
 
-load();
-watch(searchValue, () => (currentPage.value = 1));
-watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+onMounted(() => load());
+watch(sortExpression, () => load());
+</script>
 
-function onPaginationClick(page: number) {
-  currentPage.value = page;
-}
+<template>
+  <VcDataTable
+    :items="searchResult?.results ?? []"
+    :total-count="pagination.totalCount"
+    :pagination="pagination"
+    v-model:sort-field="sortField"
+    v-model:sort-order="sortOrder"
+    v-model:search-value="searchValue"
+    @pagination-click="pagination.goToPage"
+    state-key="offers_list"
+  >
+    <VcColumn
+      id="name"
+      header="Name"
+      sortable
+    />
+    <VcColumn
+      id="createdDate"
+      header="Created"
+      sortable
+    />
+  </VcDataTable>
+</template>
 ```
 
-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.
+The `state-key` on `VcDataTable` here persists column layout to localStorage; the `stateKey` passed to the composables persists query state to the URL. Both use the same string value but serve different purposes.
 
 ---
 

package/runtime/knowledge/docs/ui/composables/useDataTablePagination.docs.md

@@ -29,6 +29,7 @@ import { useDataTablePagination } from "@vc-shell/framework";
 const pagination = useDataTablePagination({
   pageSize: 20,
   totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+  onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
 });
 ```
 
@@ -36,30 +37,29 @@ 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)
 
-| Option         | Type                                              | Default     | Description                                      |
-| -------------- | ------------------------------------------------- | ----------- | ------------------------------------------------ |
-| `totalCount`   | `MaybeRefOrGetter<number>`                        | _required_  | Total item count from API response               |
-| `pageSize`     | `MaybeRefOrGetter<number>`                        | `20`        | Items per page                                   |
-| `onPageChange` | `(state: { page: number; skip: number }) => void` | `undefined` | Event callback fired when `goToPage()` is called |
+| Option         | Type                                              | Default     | Description                                                                            |
+| -------------- | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `stateKey`     | `string \| undefined`                             | `undefined` | When set, restores and persists the current page to the blade URL query under this key |
+| `totalCount`   | `MaybeRefOrGetter<number>`                        | _required_  | Total item count from API response                                                     |
+| `pageSize`     | `MaybeRefOrGetter<number>`                        | `20`        | Items per page                                                                         |
+| `onPageChange` | `(state: { page: number; skip: number }) => void` | `undefined` | Event callback fired when `goToPage()` is called                                       |
 
 ### 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`                                  |
-| `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`                           |
+| 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` | Set the page without firing `onPageChange` (used to seed from a URL restore) |
+| `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.
 
@@ -67,43 +67,38 @@ All properties are auto-unwrapped by `reactive()` — no `.value` access needed
 
 ```vue
 <script setup lang="ts">
-import { ref, computed, watch } from "vue";
-import { useDataTablePagination, useDataTableSort, useTableQueryState } from "@vc-shell/framework";
+import { ref, computed, watch, onMounted } from "vue";
+import { useDataTablePagination, useDataTableSort } from "@vc-shell/framework";
+
+const STATE_KEY = "products_list";
 
 // Data layer
 const searchResult = ref<{ results: Item[]; totalCount: number }>();
 
-async function loadItems(query: { sort?: string; keyword?: string; skip?: number }) {
-  searchResult.value = await api.search({ take: 20, ...query });
+async function loadItems() {
+  searchResult.value = await api.search({
+    sort: sortExpression.value,
+    skip: pagination.skip,
+    take: pagination.pageSize,
+  });
 }
 
-// State only — no self-loading callback.
-const pagination = useDataTablePagination({
-  pageSize: 20,
-  totalCount: computed(() => searchResult.value?.totalCount ?? 0),
-});
+// Sort state
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: STATE_KEY,
   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 },
-);
+
+// Pagination state
+const pagination = useDataTablePagination({
+  stateKey: STATE_KEY,
+  pageSize: 20,
+  totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+});
+
+onMounted(() => loadItems());
+watch(sortExpression, () => loadItems());
 </script>
 
 <template>
@@ -112,12 +107,6 @@ watch(
     :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"
   >
@@ -151,6 +140,7 @@ export function useOffers() {
   const pagination = useDataTablePagination({
     pageSize: 20,
     totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+    onPageChange: ({ skip }) => loadOffers({ ...searchQuery.value, skip }),
   });
 
   return {
@@ -161,7 +151,7 @@ export function useOffers() {
 }
 ```
 
-The blade owns the single loader watch (reading `pagination.skip` with sort/search) and binds:
+Blade then simply binds:
 
 ```vue
 <VcDataTable :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
@@ -170,12 +160,12 @@ The blade owns the single loader watch (reading `pagination.skip` with sort/sear
 ## 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 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.
+- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not know about data fetching -- it just notifies.
 - **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.
+- **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.
 - **Why `reactive()` and not `ref()`**: Pagination is a cohesive group of properties always used together (`pagination.xxx`). `reactive()` is the Vue-idiomatic choice for such objects. `useDataTableSort` returns `ref()`s because its properties are destructured and used with `v-model` individually.
+- **URL state (stateKey)**: When `stateKey` is provided, the composable reads the current page from the blade URL query on creation (via `setPage`, which does not fire `onPageChange`) and persists it on every `goToPage` call. Without `stateKey`, behavior is unchanged.
 
 ## Tips
 

package/runtime/knowledge/docs/ui/composables/useDataTableSort.docs.md

@@ -46,10 +46,11 @@ const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
 
 ### Parameters (Options)
 
-| Option             | Type              | Default     | Description                       |
-| ------------------ | ----------------- | ----------- | --------------------------------- |
-| `initialField`     | `string`          | `undefined` | Column field to sort by initially |
-| `initialDirection` | `"ASC" \| "DESC"` | `undefined` | Initial sort direction            |
+| Option             | Type                  | Default     | Description                                                                |
+| ------------------ | --------------------- | ----------- | -------------------------------------------------------------------------- |
+| `stateKey`         | `string \| undefined` | `undefined` | When set, restores and persists sort to the blade URL query under this key |
+| `initialField`     | `string`              | `undefined` | Column field to sort by initially                                          |
+| `initialDirection` | `"ASC" \| "DESC"`     | `undefined` | Initial sort direction                                                     |
 
 ### Returns
 
@@ -74,26 +75,25 @@ When `sortOrder` is `0`, `sortExpression` returns `undefined` regardless of `sor
 
 ```vue
 <script setup lang="ts">
-import { ref, watch } from "vue";
+import { ref, watch, onMounted } from "vue";
 import { useDataTableSort } from "@vc-shell/framework";
 
 const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
+  stateKey: "products_list",
   initialField: "createdDate",
   initialDirection: "DESC",
 });
 
 const items = ref([]);
 const loading = ref(false);
-const currentPage = ref(1);
-const PAGE_SIZE = 20;
 
-async function loadItems(query: { sort?: string; skip?: number }) {
+async function loadItems() {
   loading.value = true;
   try {
     const response = await api.searchProducts({
-      sort: query.sort, // e.g. "createdDate:DESC" or undefined
-      skip: query.skip ?? 0,
-      take: PAGE_SIZE,
+      sort: sortExpression.value, // e.g. "createdDate:DESC" or undefined
+      skip: 0,
+      take: 20,
     });
     items.value = response.results;
   } finally {
@@ -101,13 +101,8 @@ async function loadItems(query: { sort?: string; skip?: number }) {
   }
 }
 
-// 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 },
-);
+onMounted(() => loadItems());
+watch(sortExpression, () => loadItems());
 </script>
 
 <template>
@@ -141,13 +136,13 @@ watch(
 - **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. 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.
+- **Stateless regarding data**: The composable only manages the sort field and direction. Combine it with your own data-fetching logic using `watch(sortExpression, ...)`.
+- **URL state (stateKey)**: When `stateKey` is provided, the composable reads its slice from the blade URL query on creation and writes back on every change (via `router.replace`). Without `stateKey`, behavior is unchanged -- `sortField` and `sortOrder` are plain refs with no URL interaction.
 
 ## Tips
 
 - Always mark columns as `sortable` in your `<VcColumn>` definitions for the sort indicator icon to appear.
-- 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.
+- Use `{ immediate: true }` on the `watch(sortExpression, ...)` call to trigger the initial data load with the correct sort on mount.
 - Call `resetSort()` alongside any "clear all filters" action to keep sort state consistent with the rest of the filter UI.
 
 ## Related

package/runtime/knowledge/docs/ui/composables/useTableSearch.docs.md

@@ -0,0 +1,130 @@
+---
+title: useTableSearch
+category: composables
+group: data
+---
+
+# useTableSearch
+
+Manages page-level search state for `VcDataTable`. Returns a `searchValue` ref for `v-model:search-value` binding. When `stateKey` is provided, the keyword is restored from the blade URL on creation and persisted to the URL on change.
+
+## When to Use
+
+- You are using `VcDataTable` with `v-model:search-value`
+- You want to share the search keyword with `useDataTableSort` and `useDataTablePagination` under the same `stateKey`
+- You want URL-persistent search without wiring blade query params manually
+
+## When NOT to Use
+
+- The table filters client-side only and you do not need external search state
+- You are using a custom search input unrelated to `VcDataTable`
+
+## Basic Usage
+
+```typescript
+import { useTableSearch } from "@vc-shell/framework";
+
+const { searchValue } = useTableSearch({
+  stateKey: "offers_list",
+  initial: "",
+});
+```
+
+```vue
+<VcDataTable v-model:search-value="searchValue" :items="items" />
+```
+
+## API
+
+### Parameters (Options)
+
+| Option     | Type                  | Default     | Description                                                                              |
+| ---------- | --------------------- | ----------- | ---------------------------------------------------------------------------------------- |
+| `stateKey` | `string \| undefined` | `undefined` | When set, restores and persists the search keyword to the blade URL query under this key |
+| `initial`  | `string \| undefined` | `undefined` | Initial search value used when no URL state is present                                   |
+
+### Returns
+
+| Property      | Type          | Description                                              |
+| ------------- | ------------- | -------------------------------------------------------- |
+| `searchValue` | `Ref<string>` | Current search keyword; bind with `v-model:search-value` |
+
+## Details
+
+- With `stateKey`, the composable reads the current URL query on creation and sets `searchValue` from it. Each write to `searchValue` updates the URL query (using `router.replace`, no history entry added). The URL key used is `<stateKey>_search`.
+- Without `stateKey`, `searchValue` is a plain `ref` with no URL interaction.
+- Use the same `stateKey` value for `useDataTableSort`, `useDataTablePagination`, and `useTableSearch` on the same list page so all three share a consistent URL namespace.
+
+## Tips
+
+- Reset `searchValue` to `""` alongside `pagination.reset()` when clearing filters so the URL stays clean.
+- The composable does not trigger data loads on its own. Watch `searchValue` or combine it in a unified `watch` with `sortExpression` and `pagination.currentPage`.
+
+## Recipe: List Blade with URL State
+
+```vue
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from "vue";
+import { useDataTableSort, useDataTablePagination, useTableSearch } from "@vc-shell/framework";
+
+const STATE_KEY = "offers_list";
+
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: STATE_KEY,
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+
+const { searchValue } = useTableSearch({ stateKey: STATE_KEY });
+
+const searchResult = ref<{ results: Offer[]; totalCount: number }>();
+const totalCount = computed(() => searchResult.value?.totalCount ?? 0);
+
+const pagination = useDataTablePagination({
+  stateKey: STATE_KEY,
+  pageSize: 20,
+  totalCount,
+});
+
+async function load() {
+  searchResult.value = await api.searchOffers({
+    sort: sortExpression.value,
+    keyword: searchValue.value,
+    skip: pagination.skip,
+    take: pagination.pageSize,
+  });
+}
+
+onMounted(() => load());
+watch(sortExpression, () => load());
+</script>
+
+<template>
+  <VcDataTable
+    :items="searchResult?.results ?? []"
+    :total-count="pagination.totalCount"
+    :pagination="pagination"
+    v-model:sort-field="sortField"
+    v-model:sort-order="sortOrder"
+    v-model:search-value="searchValue"
+    @pagination-click="pagination.goToPage"
+  >
+    <VcColumn
+      id="name"
+      header="Name"
+      sortable
+    />
+    <VcColumn
+      id="createdDate"
+      header="Created"
+      sortable
+    />
+  </VcDataTable>
+</template>
+```
+
+## Related
+
+- [`useDataTableSort`](./useDataTableSort.docs.md) -- sort state composable for VcDataTable
+- [`useDataTablePagination`](./useDataTablePagination.docs.md) -- pagination state composable for VcDataTable
+- `VcDataTable` -- table component that accepts `v-model:search-value`

package/runtime/knowledge/migration-prompts/datatable-migration.md

@@ -11,21 +11,21 @@ Replace the imperative `VcTable` component (columns array, manual sort handlers,
 
 Full prop/event mapping:
 
-| VcTable prop/event         | VcDataTable equivalent                           |
-| -------------------------- | ------------------------------------------------ |
-| `:columns="columns"`       | `<VcColumn>` child components (see RULE 2)       |
-| `:selected-item-id="id"`   | `v-model:active-item-id="id"`                    |
-| `:sort="sortExpression"`   | `v-model:sort-field` + `v-model:sort-order`      |
-| `:multiselect="true"`      | `:selection-mode="'multiple'"`                   |
-| `@selection-changed="fn"`  | `v-model:selection="ref"`                        |
-| `:search-value="val"`      | `:searchable="true"` (internal state)            |
-| `@search:change="fn"`      | `@search="fn"`                                   |
-| `@item-click="fn"`         | `@row-click="fn"` (different signature)          |
-| `@header-click="fn"`       | Remove (sort is declarative via v-model)         |
-| `@scroll:ptr="fn"`         | `:pull-to-refresh="true"` + `@pull-refresh="fn"` |
-| `:pages` + `:current-page` | `:pagination="{ currentPage, pages }"`           |
-| `:active-filter-count`     | Remove (managed by global-filters internally)    |
-| `<!--@vue-generic {T}-->`  | Remove (no longer needed)                        |
+| VcTable prop/event         | VcDataTable equivalent                                                  |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `:columns="columns"`       | `<VcColumn>` child components (see RULE 2)                              |
+| `:selected-item-id="id"`   | `v-model:active-item-id="id"`                                           |
+| `:sort="sortExpression"`   | `v-model:sort-field` + `v-model:sort-order`                             |
+| `:multiselect="true"`      | `:selection-mode="'multiple'"`                                          |
+| `@selection-changed="fn"`  | `v-model:selection="ref"`                                               |
+| `:search-value="val"`      | `v-model:search-value` bound to `useTableSearch({ stateKey? })`         |
+| `@search:change="fn"`      | `@search="fn"` (or drop; use watcher on `searchValue`)                  |
+| `@item-click="fn"`         | `@row-click="fn"` (different signature)                                 |
+| `@header-click="fn"`       | Remove (sort is declarative via v-model)                                |
+| `@scroll:ptr="fn"`         | `:pull-to-refresh="true"` + `@pull-refresh="fn"`                        |
+| `:pages` + `:current-page` | `:pagination="pagination"` from `useDataTablePagination({ stateKey? })` |
+| `:active-filter-count`     | Remove (managed by global-filters internally)                           |
+| `<!--@vue-generic {T}-->`  | Remove (no longer needed)                                               |
 
 **BEFORE:**
 
@@ -310,7 +310,7 @@ The Props interface keeps `columns` — the parent still passes column definitio
 
 ## RULE 3: Sort Composable Replacement
 
-Replace `useTableSort` with `useDataTableSort`. The new composable returns `sortField` and `sortOrder` as separate refs that bind directly to `v-model:sort-field` and `v-model:sort-order`. Remove the `onHeaderClick` handler entirely.
+Replace `useTableSort` with `useDataTableSort`. The new composable returns `sortField` and `sortOrder` as separate refs that bind directly to `v-model:sort-field` and `v-model:sort-order`. Remove the `onHeaderClick` handler entirely. Pass `stateKey` to persist sort to the blade URL (opt-in; omit for no URL persistence).
 
 **BEFORE:**
 
@@ -339,6 +339,7 @@ watch(sortExpression, async () => {
 import { useDataTableSort } from "@vc-shell/framework";
 
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "my_list", // optional: persists sort to blade URL
   initialField: "createdDate",
   initialDirection: "DESC",
 });
@@ -684,10 +685,14 @@ Key points:
 - The `@filter` event fires when the user applies filters. The `event.filters` object is keyed by filter `id`, with values matching the selected option values.
 - The active filter count badge is managed internally by VcDataTable — no need for a manual `activeFilterCount` computed.
 
-## RULE 8: Pagination — Manual Calculation → useDataTablePagination
+## RULE 8: Pagination and Search — useDataTablePagination + useTableSearch
 
 Replace manual `pages`/`currentPage` computed properties and `@pagination-click` handlers with the `useDataTablePagination` composable. The composable manages skip/page math internally and returns a reactive pagination object that VcDataTable consumes directly.
 
+Pass `stateKey` to persist the current page to the blade URL (opt-in). The table `state-key` prop is column-layout persistence only and does not control URL query state.
+
+For search, replace a bare `ref("")` with `useTableSearch({ stateKey? })`. The returned `searchValue` ref binds to `v-model:search-value` on VcDataTable. With `stateKey`, the keyword is persisted to the blade URL. Without `stateKey`, it behaves like a plain ref.
+
 **BEFORE (composable):**
 
 ```typescript
@@ -733,6 +738,7 @@ export function useMyList(options?: { pageSize?: number }) {
   });
 
   const pagination = useDataTablePagination({
+    stateKey: "my_list", // optional: persists current page to blade URL
     pageSize,
     totalCount: computed(() => searchResult.value?.totalCount ?? 0),
     onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
@@ -778,12 +784,15 @@ const { items, pagination, loadItems, loading } = useMyList();
 - `totalCount`, `pages`, `currentPage` computed from composable return
 - Manual `onPaginationClick` function in blade pages
 - Manual `skip` calculation `(page - 1) * pageSize`
+- Any `useTableQueryPersistence` or `useTableQueryState().read()` calls — URL query persistence is now handled by `stateKey` on the composables
 
 **What to add:**
 
-- `useDataTablePagination` import in composable
+- `useDataTablePagination` import in composable (with optional `stateKey` for URL persistence)
+- `useTableSearch({ stateKey? })` in the blade to replace a bare `ref("")` for search
 - `pagination` object in composable return
 - `:pagination="pagination"` and `@pagination-click="pagination.goToPage"` in template
+- `v-model:search-value="searchValue"` from `useTableSearch` in template
 
 ## Verification
 

package/runtime/knowledge/patterns/list-blade-pattern.md

@@ -20,12 +20,14 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
       class="tw-grow tw-basis-0"
       :loading="loading"
       :items="xxxList"
-      :total-count="totalCount"
-      :pagination="{ currentPage, pages }"
+      :total-count="pagination.totalCount"
+      :pagination="pagination"
       v-model:active-item-id="selectedItemId"
       state-key="xxx_list"
       v-model:sort-field="sortField"
       v-model:sort-order="sortOrder"
+      v-model:search-value="searchValue"
+      :searchable="true"
       :pull-to-refresh="true"
       :empty-state="{
         icon: 'lucide-<icon>',
@@ -34,7 +36,7 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
         actionHandler: onAddItem,
       }"
       @row-click="onItemClick"
-      @pagination-click="onPaginationClick"
+      @pagination-click="pagination.goToPage"
       @pull-refresh="reload"
     >
       <!-- Each VcColumn is declared explicitly in the template (NOT via v-for).
@@ -87,9 +89,11 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
 
 **Key VcDataTable props:**
 
-- `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`).
+- `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`). This prop controls column layout only — URL query persistence (sort/search/page) comes from the composables' `stateKey` option.
 - `v-model:active-item-id` — highlights the currently open row. Bind to `selectedItemId` ref.
 - `v-model:sort-field` and `v-model:sort-order` — two-way sort binding from `useDataTableSort`.
+- `v-model:search-value` and `:searchable="true"` — two-way search binding from `useTableSearch`.
+- `:pagination="pagination"` and `@pagination-click="pagination.goToPage"` — pass the reactive object from `useDataTablePagination` directly.
 - `:pull-to-refresh="true"` — enables mobile pull-to-refresh gesture.
 - `:empty-state` — object with `icon`, `title`, `actionLabel`, `actionHandler`.
 
@@ -191,7 +195,8 @@ If the API defines an enum of statuses, populate the map from those values. If s
 ```vue
 <script lang="ts" setup>
 import { ref, computed, watch, onMounted } from "vue";
-import { IBladeToolbar, useBlade, useDataTableSort } from "@vc-shell/framework";
+import { IBladeToolbar, useBlade, useDataTableSort, useDataTablePagination, useTableSearch } from "@vc-shell/framework";
+import { debounce } from "lodash-es";
 import useXxxs from "../composables/useXxxs";
 import { useI18n } from "vue-i18n";
 
@@ -211,19 +216,32 @@ defineBlade({
 // 2. Core composables
 const { openBlade, exposeToChildren, param } = useBlade();
 const { t } = useI18n({ useScope: "global" });
-const { getXxxs, searchQuery, loading, xxxList, currentPage, pages, totalCount } = useXxxs();
+const { getXxxs, loading, xxxList, totalCount } = useXxxs();
 
-// 3. Sort — provides sortField, sortOrder (for VcDataTable v-model), sortExpression (string for API)
+// 3. Sort — stateKey persists sort to blade URL; omit stateKey to opt out
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "xxx_list",
   initialField: "createdDate",
   initialDirection: "DESC",
 });
 
-// 4. UI state
+// 4. Search — stateKey persists keyword to blade URL; omit stateKey to opt out
+const { searchValue } = useTableSearch({ stateKey: "xxx_list" });
+
+// 5. Pagination — stateKey persists current page to blade URL; omit stateKey to opt out
+// Note: state-key on <VcDataTable> is column-layout persistence only (localStorage).
+// URL query persistence (sort/search/page) is controlled by the stateKey option here.
+const pagination = useDataTablePagination({
+  stateKey: "xxx_list",
+  pageSize: 20,
+  totalCount,
+});
+
+// 6. UI state
 const selectedItemId = ref<string | undefined>();
 const title = computed(() => t("XXX.PAGES.LIST.TITLE"));
 
-// 5. Toolbar
+// 7. Toolbar
 const bladeToolbar = ref<IBladeToolbar[]>([
   {
     id: "refresh",
@@ -241,7 +259,7 @@ const bladeToolbar = ref<IBladeToolbar[]>([
   },
 ]);
 
-// 6. Status variant mapping (if status column exists)
+// 8. Status variant mapping (if status column exists)
 const statusVariant = (status: string | undefined): "info" | "warning" | "danger" | "success" | "primary" => {
   const map: Record<string, "info" | "warning" | "danger" | "success" | "primary"> = {
     // TODO: adjust status variants to match your API statuses
@@ -256,12 +274,23 @@ const statusVariant = (status: string | undefined): "info" | "warning" | "danger
   return map[status ?? ""] ?? "info";
 };
 
-// 7. Sort reactivity — reload when sort changes
-watch(sortExpression, async (value) => {
-  await getXxxs({ ...searchQuery.value, sort: value });
-});
+// 9. Load function — explicit; called on mount and by watchers
+const load = async () => {
+  await getXxxs({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: pagination.skip,
+    take: 20,
+  });
+};
 
-// 8. Track selected row when param changes (e.g., navigating directly to URL)
+// 10. Reset to page 1 when search changes, then reload
+watch(searchValue, () => pagination.setPage(1));
+
+// 11. Reload when sort, search, or page changes (debounced to coalesce rapid changes)
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+
+// 12. Track selected row when param changes (e.g., navigating directly to URL)
 watch(
   () => param.value,
   () => {
@@ -270,30 +299,15 @@ watch(
   { immediate: true },
 );
 
-// 9. Load data on mount
-onMounted(async () => {
-  await reload();
-});
+// 13. Load data on mount
+onMounted(() => load());
 
-// 10. Reload — reloads current page with current sort
+// 14. Reload helper — used by toolbar and exposed to child blades
 const reload = async () => {
-  await getXxxs({
-    ...searchQuery.value,
-    skip: (currentPage.value - 1) * (searchQuery.value?.take ?? 20),
-    sort: sortExpression.value,
-  });
-};
-
-// 11. Pagination
-const onPaginationClick = async (page: number) => {
-  await getXxxs({
-    ...searchQuery.value,
-    skip: (page - 1) * (searchQuery.value?.take ?? 20),
-    sort: sortExpression.value,
-  });
+  await load();
 };
 
-// 12. Row click → open details blade
+// 15. Row click → open details blade
 const onItemClick = (event: { data: { id?: string } }) => {
   openBlade({
     name: "XxxDetails",
@@ -310,14 +324,14 @@ const onItemClick = (event: { data: { id?: string } }) => {
   });
 };
 
-// 13. Add new item — open details blade with no param (creates new)
+// 16. Add new item — open details blade with no param (creates new)
 function onAddItem() {
   openBlade({
     name: "XxxDetails",
   });
 }
 
-// 14. Expose reload to child blades so details can trigger list refresh after save/delete
+// 17. Expose reload to child blades so details can trigger list refresh after save/delete
 exposeToChildren({ reload });
 </script>
 ```
@@ -334,6 +348,7 @@ exposeToChildren({ reload });
 
 ```ts
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "xxx_list", // optional: persists sort to blade URL
   initialField: "createdDate",
   initialDirection: "DESC",
 });
@@ -342,16 +357,45 @@ const { sortField, sortOrder, sortExpression } = useDataTableSort({
 - `sortField` — reactive ref, two-way bound to `VcDataTable` via `v-model:sort-field`
 - `sortOrder` — reactive ref (`"ASC"` | `"DESC"`), two-way bound via `v-model:sort-order`
 - `sortExpression` — computed string `"field:DIR"` (e.g., `"createdDate:DESC"`), passed to the API
+- `stateKey` — when provided, the composable reads the initial sort from the URL and writes back on change
 
-### Sort watcher pattern
+### `useTableSearch` — search with optional URL persistence
 
 ```ts
-watch(sortExpression, async (value) => {
-  await getXxxs({ ...searchQuery.value, sort: value });
+const { searchValue } = useTableSearch({ stateKey: "xxx_list" });
+```
+
+- Returns `searchValue` ref, two-way bound via `v-model:search-value` on `VcDataTable`.
+- With `stateKey`, restores and persists the keyword to the blade URL.
+- Without `stateKey`, behaves like a plain `ref("")`.
+
+### `useDataTablePagination` — pagination with optional URL persistence
+
+```ts
+const pagination = useDataTablePagination({
+  stateKey: "xxx_list", // optional: persists current page to blade URL
+  pageSize: 20,
+  totalCount,
 });
 ```
 
-Watch `sortExpression` (not `sortField`/`sortOrder` separately) to trigger a reload whenever sort changes.
+- Pass `pagination` directly as `:pagination="pagination"` and `@pagination-click="pagination.goToPage"`.
+- Access `pagination.skip` for API calls, `pagination.setPage(1)` to reset on search change.
+- `stateKey` persists the current page to the blade URL; omit to opt out.
+- The table `state-key` prop is column-layout persistence (localStorage) only and is independent.
+
+### Load + watcher pattern
+
+```ts
+const load = async () => {
+  await getXxxs({ sort: sortExpression.value, keyword: searchValue.value || undefined, skip: pagination.skip, take: 20 });
+};
+watch(searchValue, () => pagination.setPage(1));
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+onMounted(() => load());
+```
+
+Watch `[sortExpression, searchValue, () => pagination.skip]` to reload whenever any query dimension changes. Reset to page 1 when search changes before the reload watcher fires.
 
 ### `exposeToChildren`