@vc-shell/vc-app-skill 2.0.11-pr247.0f1e741 → 2.0.11-pr247.8c6c87f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.11-pr247.0f1e741",
+  "version": "2.0.11-pr247.8c6c87f",
   "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/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`