@vc-shell/vc-app-skill 2.1.0 → 2.2.0-pr260.a8bd3a7

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

@@ -50,25 +50,33 @@ const open = ref(false);
 
 ## Props
 
-| Prop             | Type                                   | Default     | Description                                         |
-| ---------------- | -------------------------------------- | ----------- | --------------------------------------------------- |
-| `modelValue`     | `boolean`                              | _required_  | Open/close state (v-model).                         |
-| `position`       | `"left" \| "right" \| "bottom"`        | `"right"`   | Slide-in direction.                                 |
-| `size`           | `"sm" \| "md" \| "lg" \| "full"`       | `"sm"`      | Panel size preset (300/380/520px or full viewport). |
-| `variant`        | `"default" \| "elevated" \| "minimal"` | `"default"` | Visual style.                                       |
-| `width`          | `number \| string`                     | --          | Custom width override (left/right positions).       |
-| `height`         | `number \| string`                     | --          | Custom height override (bottom position).           |
-| `title`          | `string`                               | `""`        | Header title text.                                  |
-| `subtitle`       | `string`                               | `""`        | Header subtitle text.                               |
-| `showOverlay`    | `boolean`                              | `true`      | Show backdrop overlay.                              |
-| `closeOnOverlay` | `boolean`                              | `true`      | Close when clicking overlay.                        |
-| `closeOnEscape`  | `boolean`                              | `true`      | Close on Escape key.                                |
-| `closeButton`    | `boolean`                              | `true`      | Show close button in header.                        |
-| `trapFocus`      | `boolean`                              | `true`      | Trap keyboard focus inside panel.                   |
-| `lockScroll`     | `boolean`                              | `true`      | Prevent body scroll while open.                     |
-| `inset`          | `boolean`                              | `true`      | Add rounded inset gap from viewport edges.          |
-| `draggable`      | `boolean`                              | `false`     | Enable swipe-to-dismiss (bottom only).              |
-| `dragHandle`     | `boolean`                              | `false`     | Show iOS-style drag handle bar.                     |
+| Prop             | Type                                   | Default           | Description                                                                                 |
+| ---------------- | -------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- |
+| `modelValue`     | `boolean`                              | _required_        | Open/close state (v-model).                                                                 |
+| `position`       | `"left" \| "right" \| "bottom"`        | `"right"`         | Slide-in direction.                                                                         |
+| `size`           | `"sm" \| "md" \| "lg" \| "full"`       | `"sm"`            | Panel size preset. Width (left/right) 300/380/520px/100vw; height (bottom) 40/56/72/100dvh. |
+| `variant`        | `"default" \| "elevated" \| "minimal"` | `"default"`       | Visual style.                                                                               |
+| `width`          | `number \| string`                     | --                | Custom width override (left/right positions).                                               |
+| `height`         | `number \| string`                     | --                | Custom height override (bottom position).                                                   |
+| `title`          | `string`                               | `""`              | Header title text.                                                                          |
+| `subtitle`       | `string`                               | `""`              | Header subtitle text.                                                                       |
+| `showOverlay`    | `boolean`                              | `true`            | Show backdrop overlay.                                                                      |
+| `closeOnOverlay` | `boolean`                              | `true`            | Close when clicking overlay.                                                                |
+| `closeOnEscape`  | `boolean`                              | `true`            | Close on Escape key.                                                                        |
+| `closeButton`    | `boolean`                              | `true`            | Show close button in header.                                                                |
+| `trapFocus`      | `boolean`                              | `true`            | Trap keyboard focus inside panel.                                                           |
+| `lockScroll`     | `boolean`                              | `true`            | Prevent body scroll while open.                                                             |
+| `inset`          | `boolean`                              | `true`            | Add rounded inset gap from viewport edges.                                                  |
+| `returnFocus`    | `boolean`                              | `true`            | Restore focus to the trigger element on close.                                              |
+| `autoFocus`      | `boolean`                              | `true`            | Focus the first focusable element on open.                                                  |
+| `teleport`       | `boolean`                              | `true`            | Teleport the panel to a target (disabled toggles it off).                                   |
+| `teleportTo`     | `string \| HTMLElement`                | --                | Teleport target selector or element.                                                        |
+| `ariaLabel`      | `string`                               | `""`              | Accessible label for the dialog.                                                            |
+| `closeAriaLabel` | `string`                               | `"Close sidebar"` | Accessible label for the close button.                                                      |
+| `zIndex`         | `number`                               | `9200`            | Stacking order of the sidebar container.                                                    |
+| `closeThreshold` | `number`                               | `0.3`             | Swipe fraction of panel height needed to dismiss (bottom).                                  |
+| `draggable`      | `boolean`                              | `false`           | Enable swipe-to-dismiss (bottom only).                                                      |
+| `dragHandle`     | `boolean`                              | `false`           | Show iOS-style drag handle bar.                                                             |
 
 ## Events
 
@@ -86,6 +94,15 @@ const open = ref(false);
 | `actions` | `{ close }` | Extra buttons in the header actions area.     |
 | `footer`  | --          | Sticky footer area.                           |
 
+## Exposed Methods
+
+Accessible via a template ref on the component:
+
+| Method    | Description                                |
+| --------- | ------------------------------------------ |
+| `open()`  | Opens the sidebar (sets model true).       |
+| `close()` | Closes the sidebar with reason `"action"`. |
+
 ## Features
 
 ### Animated Transitions
@@ -102,14 +119,14 @@ When `position="bottom"` and `draggable` is true, users can swipe the panel down
 
 ### Size Presets
 
-| Size   | Width/Height  |
-| ------ | ------------- |
-| `sm`   | 300px         |
-| `md`   | 380px         |
-| `lg`   | 520px         |
-| `full` | Full viewport |
+| Size   | Width (left/right) | Height (bottom) |
+| ------ | ------------------ | --------------- |
+| `sm`   | 300px              | 40dvh           |
+| `md`   | 380px              | 56dvh           |
+| `lg`   | 520px              | 72dvh           |
+| `full` | 100vw              | 100dvh          |
 
-Override with the `width` or `height` prop for custom dimensions.
+Width presets apply to `left`/`right` positions; height presets apply to `position="bottom"`. Override with the `width` or `height` prop for custom dimensions.
 
 ## Common Patterns
 

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

@@ -15,14 +15,20 @@ All composables are exported from `framework/ui/composables/index.ts` and availa
 
 ## Exports
 
-| Composable            | Purpose                                                                            |
-| --------------------- | ---------------------------------------------------------------------------------- |
-| `useAdaptiveItems`    | Measures and distributes items into visible/hidden groups based on container width |
-| `useScrollArrows`     | Tracks scroll overflow state and provides animated scroll-by-arrow controls        |
-| `useFloatingPosition` | Wrapper around `@floating-ui/vue` with sensible defaults for dropdowns/tooltips    |
-| `useTeleportTarget`   | Resolves a consistent teleport target (explicit target, app root, or body)         |
-| `useFormField`        | Shared form field logic: unique IDs, ARIA attributes, InputGroup integration       |
-| `useCollapsible`      | Expand/collapse panel with measured content height and CSS transitions             |
+| Composable               | Purpose                                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| `useAdaptiveItems`       | Measures and distributes items into visible/hidden groups based on container width           |
+| `useScrollArrows`        | Tracks scroll overflow state and provides animated scroll-by-arrow controls                  |
+| `useFloatingPosition`    | Wrapper around `@floating-ui/vue` with sensible defaults for dropdowns/tooltips              |
+| `useTeleportTarget`      | Resolves a consistent teleport target (explicit target, app root, or body)                   |
+| `useFormField`           | Shared form field logic: unique IDs, ARIA attributes, InputGroup integration                 |
+| `useCollapsible`         | Expand/collapse panel with measured content height and CSS transitions                       |
+| `useTableSort`           | Sort state for `VcTable`/`VcDataTable`                                                       |
+| `useTableSelection`      | Row selection state (multi-select, select-all, programmatic) for tables                      |
+| `useDataTableSort`       | URL-persistent sort state for `VcDataTable` ([docs](./useDataTableSort.docs.md))             |
+| `useDataTablePagination` | URL-persistent pagination state for `VcDataTable` ([docs](./useDataTablePagination.docs.md)) |
+| `useTableSearch`         | URL-persistent search keyword for `VcDataTable` ([docs](./useTableSearch.docs.md))           |
+| `useBladeLoading`        | Blade-scoped loading/skeleton state                                                          |
 
 ## API Details
 
@@ -104,4 +110,4 @@ const { isExpanded, toggle, wrapperStyle, contentRef, hasOverflow } = useCollaps
 
 - `framework/ui/components/molecules/vc-dropdown/` -- uses `useFloatingPosition`
 - `framework/ui/components/molecules/vc-input/` -- uses `useFormField`
-- `framework/shared/components/sidebar/` -- uses `useScrollArrows`
+- `framework/ui/components/atoms/vc-scrollable-container/` -- uses `useScrollArrows`

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

@@ -54,12 +54,14 @@ const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({
 
 ### Returns
 
-| Property         | Type                               | Description                                                                            |
-| ---------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
-| `sortField`      | `Ref<string \| undefined>`         | Current sort field; bind with `v-model:sort-field`                                     |
-| `sortOrder`      | `Ref<number>`                      | Numeric sort order: `1` = ASC, `-1` = DESC, `0` = none; bind with `v-model:sort-order` |
-| `sortExpression` | `ComputedRef<string \| undefined>` | Formatted string (e.g., `"name:ASC"`) or `undefined` when no sort is active            |
-| `resetSort`      | `() => void`                       | Reset to the initial field/direction passed to the composable                          |
+| Property         | Type                               | Description                                                                                                          |
+| ---------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `sortField`      | `Ref<string \| undefined>`         | Current sort field; bind with `v-model:sort-field`                                                                   |
+| `sortOrder`      | `Ref<DataTableSortOrder>`          | Sort order (`DataTableSortOrder = 0 \| 1 \| -1`): `1` = ASC, `-1` = DESC, `0` = none; bind with `v-model:sort-order` |
+| `sortExpression` | `ComputedRef<string \| undefined>` | Formatted string (e.g., `"name:ASC"`) or `undefined` when no sort is active                                          |
+| `resetSort`      | `() => void`                       | Reset to the initial field/direction passed to the composable                                                        |
+
+The `DataTableSortOrder` (`0 | 1 | -1`) and `DataTableSortDirection` (`"ASC" | "DESC"`) types are exported alongside the composable.
 
 ## Direction Mapping
 

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

@@ -45,9 +45,9 @@ const { searchValue } = useTableSearch({
 
 ### Returns
 
-| Property      | Type          | Description                                              |
-| ------------- | ------------- | -------------------------------------------------------- |
-| `searchValue` | `Ref<string>` | Current search keyword; bind with `v-model:search-value` |
+| Property      | Type                       | Description                                              |
+| ------------- | -------------------------- | -------------------------------------------------------- |
+| `searchValue` | `Ref<string \| undefined>` | Current search keyword; bind with `v-model:search-value` |
 
 ## Details
 

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

@@ -43,9 +43,9 @@ async function deleteSelected() {
 
 ### Parameters (Options)
 
-| Option    | Type                             | Default | Description                           |
-| --------- | -------------------------------- | ------- | ------------------------------------- |
-| `idField` | `keyof T \| (item: T) => string` | `"id"`  | Field or function to extract item IDs |
+| Option    | Type                                            | Default | Description                           |
+| --------- | ----------------------------------------------- | ------- | ------------------------------------- |
+| `idField` | `keyof T \| ((item: T) => string \| undefined)` | `"id"`  | Field or function to extract item IDs |
 
 ### Returns
 
@@ -159,5 +159,5 @@ const selection2 = useTableSelection<CompositeItem>({
 
 ## Related
 
-- `VcDataTable` -- emits `selection-changed` and `select:all` events
+- `VcTableAdapter` (exported as `VcTable`) -- emits `selection-changed` and `select:all` events
 - `useTableSort` -- often used alongside selection for list blade patterns

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

@@ -139,7 +139,7 @@ watch(sortExpression, () => loadItems(), { immediate: true });
 - **Sort expression format**: The `sortExpression` computed returns `"property:DIRECTION"` when active, or `undefined` when no sort is applied. This format is directly compatible with VirtoCommerce Platform search endpoints.
 - **Writable computed**: `currentSort` is a `WritableComputedRef`, so you can set it programmatically: `currentSort.value = { property: "name", direction: "ASC" }`.
 - **Reset behavior**: `resetSort()` returns to the initial options passed to the composable. If no initial options were provided, it clears the sort entirely.
-- **handleSortChange format**: Accepts either `"fieldName"` (triggers cycling) or `"fieldName:DIR"` (sets explicit direction). VcDataTable's `@header-click` event emits in the latter format when the adapter encodes direction.
+- **handleSortChange format**: Accepts either `"fieldName"` (triggers cycling) or `"fieldName:DIR"` (sets explicit direction). `VcTableAdapter`'s `@header-click` event emits in the latter format when the adapter encodes direction.
 
 ## Tips
 
@@ -149,6 +149,5 @@ watch(sortExpression, () => loadItems(), { immediate: true });
 
 ## Related
 
-- `VcDataTable` -- emits header-click events consumed by `handleSortChange`
-- `VcTableAdapter` -- adapts legacy sort prop format
+- `VcTableAdapter` (exported as `VcTable`) -- emits header-click events consumed by `handleSortChange`; adapts legacy sort prop format
 - `useTableSelection` -- often used alongside sort for list blade patterns

package/runtime/knowledge/migration-prompts/table-url-state-migration.md

@@ -0,0 +1,221 @@
+---
+name: table-url-state-migration
+description: AI transformation rules for opting an existing VcDataTable list into URL-query state persistence (sort, search, page) via the composables' stateKey option.
+---
+
+# Table URL State: persist sort / search / page in the blade URL
+
+This retrofit applies to list blades that **already use `VcDataTable`** with the state
+composables (`useDataTableSort`, `useDataTablePagination`, and search) but do **not** yet
+persist the view to the URL. After it, sort, search keyword, and current page survive a
+reload and travel in a shareable link.
+
+It is independent of the VcTable→VcDataTable swap (`datatable-migration`) and of adopting
+the pagination composable (`use-data-table-pagination-migration`). Run those first if the
+file still uses `<VcTable>` or hand-rolled `pages`/`currentPage`.
+
+## Concept
+
+Each state composable accepts an optional `stateKey`. With it set, the composable reads its
+initial value from the blade URL query on creation and writes changes back:
+
+- `useDataTableSort({ stateKey })` → `<stateKey>_sort` (e.g. `createdDate:DESC`)
+- `useTableSearch({ stateKey })` → `<stateKey>_search`
+- `useDataTablePagination({ stateKey })` → `<stateKey>_page` (page 1 is encoded as absent)
+
+The `state-key` **prop** on `<VcDataTable>` is unrelated — it persists column layout to
+`localStorage`. Leave it as-is. The composable `stateKey` is the URL query store.
+
+## Choosing the key
+
+- One key per table, **the same string** across all three composables on that blade.
+- Use snake_case, conventionally `<module>_list` (e.g. `orders_list`). It may equal the
+  table `state-key` prop — they are separate stores.
+- The key must be unique among tables that can be visible simultaneously (a list plus a
+  child list in the same stack), so their query params do not collide.
+
+## Precondition: the blade must be URL-addressable
+
+`stateKey` only does something when the blade has a `url` in `defineBlade`. For a
+non-routable or nested blade (no `url`) the query service is a no-op — skip that file and
+note it in the report rather than adding dead options.
+
+## RULE 1: Add `stateKey` to `useDataTableSort`
+
+**BEFORE:**
+
+```ts
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+```
+
+**AFTER:**
+
+```ts
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "orders_list",
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+```
+
+## RULE 2: Own the search keyword with `useTableSearch({ stateKey })`
+
+The keyword must live in a ref that `useTableSearch` controls, bound to
+`v-model:search-value`. Three starting shapes:
+
+**2a — bare `ref("")` in the blade:** replace it.
+
+```ts
+// BEFORE
+const searchValue = ref("");
+// AFTER
+const { searchValue } = useTableSearch({ stateKey: "orders_list" });
+```
+
+**2b — event-driven `@search` with no ref:** the table emits `@search` and a handler loads
+directly. Convert to `v-model:search-value` + a watcher.
+
+```vue
+<!-- BEFORE -->
+<VcDataTable :searchable="true" @search="onSearchChange" />
+<!-- AFTER -->
+<VcDataTable :searchable="true" v-model:search-value="searchValue" />
+```
+
+```ts
+// BEFORE
+async function onSearchChange(keyword: string | undefined) {
+  await loadItems({ ...searchQuery.value, keyword, skip: 0 });
+}
+// AFTER — remove onSearchChange; drive load from the watcher (see RULE 5)
+const { searchValue } = useTableSearch({ stateKey: "orders_list" });
+```
+
+**2c — the deprecated `useTableQueryState().read()` preview form:** delete the manual
+restore block entirely (see RULE 6); the three composables now seed themselves.
+
+In all cases add `v-model:search-value="searchValue"` to the `<VcDataTable>` and keep
+`:searchable="true"`.
+
+## RULE 3: Add `stateKey` to `useDataTablePagination`
+
+If pagination is created in the blade, add the option directly:
+
+```ts
+const pagination = useDataTablePagination({
+  stateKey: "orders_list",
+  pageSize: 20,
+  totalCount,
+});
+```
+
+If pagination is created **inside the list composable** (common when `onPageChange` drives
+the load), thread `stateKey` through as a composable option — the blade still owns the key:
+
+```ts
+// composable
+export function useOrdersList(options?: { pageSize?: number; stateKey?: string }) {
+  // ...
+  const pagination = useDataTablePagination({
+    stateKey: options?.stateKey,
+    pageSize: options?.pageSize ?? 20,
+    totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+    onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
+  });
+}
+```
+
+```ts
+// blade
+const { items, pagination, loadItems } = useOrdersList({ stateKey: "orders_list" });
+```
+
+Add the `stateKey?: string` field to the composable's options interface.
+
+## RULE 4: Seed the initial load from the restored values
+
+The first load on mount must read the restored sort, keyword, and page — otherwise the URL
+is restored into the refs but the first fetch ignores them and shows page 1 unfiltered.
+
+```ts
+// BEFORE
+onMounted(() => loadItems({ take: 20, sort: sortExpression.value }));
+// AFTER
+onMounted(() =>
+  loadItems({
+    take: 20,
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: pagination.skip,
+  }),
+);
+```
+
+For a `reload()` helper, use `skip: pagination.skip` (not a recomputed skip).
+
+## RULE 5: Reset to page 1 when the search changes — REQUIRED
+
+This is not optional. If the user is on page 3 and types a query that returns fewer pages,
+leaving `_page=3` in the URL makes the next reload request page 3 of the filtered set:
+`skip` overshoots and the table shows an empty "nothing found" state on reload. Resetting to
+page 1 drops `_page` from the URL and keeps the `(search, page)` pair consistent.
+
+```ts
+watch(searchValue, () => pagination.setPage(1));
+// then the reload watcher (debounced) picks up the change:
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+```
+
+If search loads through a separate handler (event-driven apps), call `pagination.setPage(1)`
+at the top of that handler before loading with `skip: 0`. Apply the same reset when a global
+filter changes.
+
+## RULE 6: Remove the deprecated preview API
+
+Delete any `useTableQueryState().read()` or `useTableQueryPersistence` usage and the manual
+ref-seeding it drove — the `stateKey` option replaces it.
+
+```ts
+// DELETE this whole block:
+const restored = useTableQueryState("orders_list").read();
+if (restored.sort) {
+  /* ... */
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) pagination.setPage(restored.page);
+```
+
+Remove the now-unused `useTableQueryState` / `useTableQueryPersistence` import.
+
+## Advanced: a shared list base with two views
+
+Some apps render two datasets (e.g. flat list vs. category tree) through one
+`VcDataTable`-wrapping base component, each with its own `useDataTablePagination`. Pass the
+same `stateKey` to **both** view paginations (only one view is active at a time, so they
+never write the page param simultaneously) and reset the page on search via the unified
+pagination object the base holds (`props.pagination.setPage(1)`).
+
+## What to add
+
+- `stateKey` on `useDataTableSort`, `useDataTablePagination`, and `useTableSearch` (same key)
+- `useTableSearch({ stateKey })` import + `v-model:search-value="searchValue"` binding
+- `watch(searchValue, () => pagination.setPage(1))`
+- `skip: pagination.skip` and `keyword: searchValue.value || undefined` in the initial load
+- `stateKey?: string` on the list composable's options interface (when pagination is there)
+
+## What to remove
+
+- `useTableQueryState().read()` / `useTableQueryPersistence` calls and their imports
+- Event-driven `@search` handlers that only set a keyword and reload (replaced by RULE 2/5)
+- Any manual `currentPage`/`skip` math used purely to restore a page from the URL
+
+## Verification
+
+1. `npx vue-tsc --noEmit` passes.
+2. Sort a column, search, go to page 2 — the URL gains `<key>_sort`, `<key>_search`,
+   `<key>_page`. Reload: the table restores the same view and shows results.
+3. On page 2, type a search — the URL drops `_page` (reset to page 1) and results show.
+4. No `useTableQueryState` / `useTableQueryPersistence` references remain.

package/runtime/vc-app.md

@@ -1613,6 +1613,7 @@ Map topic headings to migration prompt files and pattern files:
 | Assets API / useAssets / useAssetsManager / use-assets-migration                                                                 | `use-assets-migration`            | `{KNOWLEDGE_BASE}/migration-prompts/use-assets-migration.md`                | `{KNOWLEDGE_BASE}/patterns/assets-management.md`     |
 | Manual Migration Audit / useExternalWidgets / moment / useFunctions / resolveBladeByName / onParentCall / manual-migration-audit | `manual-migration-audit`          | `{KNOWLEDGE_BASE}/migration-prompts/manual-migration-audit.md`              | —                                                    |
 | Pagination / useDataTablePagination / use-data-table-pagination-audit                                                            | `use-data-table-pagination-audit` | `{KNOWLEDGE_BASE}/migration-prompts/use-data-table-pagination-migration.md` | —                                                    |
+| Table URL State / stateKey / useTableQueryState / table-url-state-audit                                                          | `table-url-state-audit`           | `{KNOWLEDGE_BASE}/migration-prompts/table-url-state-migration.md`           | `{KNOWLEDGE_BASE}/patterns/list-blade-pattern.md`    |
 
 Build the `topics` array for the migration-agent using the canonical topic names above.