@vc-shell/vc-app-skill 2.0.0-alpha.32 → 2.0.0-alpha.33-pr220.455e322

package/runtime/knowledge/migration-prompts/use-assets-migration.md

@@ -0,0 +1,164 @@
+---
+name: use-assets-migration
+description: AI transformation rules for useAssets()/AssetsHandler migration to useAssetsManager().
+---
+
+# Assets Migration: useAssets -> useAssetsManager
+
+Migrate legacy assets handling (`useAssets`, `AssetsHandler`, ad-hoc upload/remove/edit callbacks) to `useAssetsManager`.
+
+## RULE 1: Replace `useAssets()` with `useAssetsManager()`
+
+**BEFORE:**
+
+```typescript
+import { useAssets } from "@vc-shell/framework";
+
+const { upload, remove, edit, loading } = useAssets(imagesRef, uploadPath);
+```
+
+**AFTER:**
+
+```typescript
+import { useAssetsManager } from "@vc-shell/framework";
+
+const assetsManager = useAssetsManager(imagesRef, {
+  uploadPath: () => uploadPath.value,
+  confirmRemove: () => showConfirmation(t("MY_MODULE.ALERTS.DELETE_CONFIRMATION")),
+});
+
+// assetsManager.items, assetsManager.upload, assetsManager.remove,
+// assetsManager.removeMany, assetsManager.reorder, assetsManager.updateItem, assetsManager.loading
+```
+
+Notes:
+
+- `uploadPath` must be a function (`() => string`), not a static string.
+- If no confirmation is needed, omit `confirmRemove`.
+
+## RULE 2: Replace `ICommonAsset` with `AssetLike`
+
+**BEFORE:**
+
+```typescript
+import type { ICommonAsset } from "@vc-shell/framework";
+```
+
+**AFTER:**
+
+```typescript
+import type { AssetLike } from "@vc-shell/framework";
+```
+
+Also update all type annotations in the file.
+
+## RULE 3: Single-image fields must be wrapped in writable computed array
+
+For fields like `iconUrl`, `logo`, `photo`, convert single value <-> array bridge.
+
+**BEFORE:**
+
+```typescript
+const { upload, remove } = useAssets(photoRef, () => `users/${item.value?.id}`);
+```
+
+**AFTER:**
+
+```typescript
+const photoAssets = computed({
+  get: () => (item.value?.iconUrl ? [{ url: item.value.iconUrl }] : []),
+  set: (val) => {
+    if (item.value) item.value.iconUrl = val[0]?.url;
+  },
+});
+
+const photoManager = useAssetsManager(photoAssets, {
+  uploadPath: () => `users/${item.value?.id ?? "new"}`,
+});
+```
+
+## RULE 4: `AssetsHandler` and raw handler props -> manager object
+
+If the component receives or creates handler bundles (`assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`, `AssetsHandler<T>`), replace with a manager instance.
+
+**BEFORE:**
+
+```typescript
+interface Props {
+  imageHandlers?: AssetsHandler<MyImage>;
+}
+
+const defaultHandlers = { upload, remove, edit, loading };
+const handlers = props.imageHandlers ?? defaultHandlers;
+```
+
+**AFTER:**
+
+```typescript
+interface Props {
+  manager?: ReturnType<typeof useAssetsManager>;
+}
+
+const defaultManager = useAssetsManager(imagesRef, {
+  uploadPath: () => `products/${item.value?.id}`,
+});
+
+const manager = computed(() => props.manager ?? defaultManager);
+```
+
+## RULE 5: `openBlade("AssetsManager")` must pass `manager: markRaw(...)`
+
+**BEFORE:**
+
+```typescript
+openBlade({
+  name: "AssetsManager",
+  options: {
+    assets: item.value?.assets,
+    assetsUploadHandler: upload,
+    assetsEditHandler: edit,
+    assetsRemoveHandler: remove,
+    loading,
+  },
+});
+```
+
+**AFTER:**
+
+```typescript
+import { markRaw } from "vue";
+
+openBlade({
+  name: "AssetsManager",
+  options: {
+    manager: markRaw(assetsManager),
+    disabled: disabled.value,
+  },
+});
+```
+
+If `manager` is already passed but not wrapped, add `markRaw()`.
+
+## RULE 6: Keep `AssetsDetails` callbacks wired to manager methods
+
+If opening `AssetsDetails`, connect handlers to manager methods (`updateItem`, `remove`) and keep asset type as `AssetLike`.
+
+```typescript
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset,
+    assetEditHandler: (updated: AssetLike) => assetsManager.updateItem(updated),
+    assetRemoveHandler: (toRemove: AssetLike) => assetsManager.remove(toRemove),
+  },
+});
+```
+
+## Verification
+
+After migration:
+
+1. Search for stale API: `useAssets(`, `AssetsHandler`, `ICommonAsset`, `assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`.
+2. Confirm `AssetsManager` blade calls pass `manager: markRaw(...)`.
+3. Run `npx vue-tsc --noEmit`.
+4. Validate runtime flow: upload, remove, reorder, edit metadata.

package/runtime/knowledge/migration-prompts/use-data-table-pagination-migration.md

@@ -0,0 +1,176 @@
+# useDataTablePagination Migration
+
+Replace the manual `totalCount` / `pages` / `currentPage` computed triple plus hand-written `onPaginationClick` handler with a single `useDataTablePagination()` call.
+
+## Rule 1: Update the data composable
+
+For each list composable file:
+
+### 1a. Add import
+
+Add to the `@vc-shell/framework` import (merge, don't duplicate):
+
+```ts
+import { useDataTablePagination, type UseDataTablePaginationReturn } from "@vc-shell/framework";
+```
+
+### 1b. Create `pagination` before the return
+
+Declare, before the return block:
+
+```ts
+const pagination = useDataTablePagination({
+  pageSize,
+  totalCount: computed(() => searchResult.value?.totalCount ?? 0),
+  onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }),
+});
+```
+
+- Use the same `pageSize` the composable already accepts as option (default 20).
+- Pass `totalCount` as a computed (not a plain number).
+- Use the composable's own loader name for `onPageChange` (`loadItems`, `loadMessages`, `searchXxx` — whatever already exists).
+
+### 1c. Replace the three computed in the return
+
+**Before:**
+
+```ts
+return {
+  totalCount: computed(() => searchResult.value?.totalCount || 0),
+  pages: computed(() => Math.ceil((searchResult.value?.totalCount || 1) / pageSize)),
+  currentPage: computed(() => Math.ceil((searchQuery.value?.skip || 0) / pageSize + 1)),
+  // ...other returns
+};
+```
+
+**After:**
+
+```ts
+return {
+  pagination,
+  // ...other returns (unchanged)
+};
+```
+
+### 1d. Update the return type interface (if present)
+
+**Before:**
+
+```ts
+export interface IUseList {
+  totalCount: ComputedRef<number>;
+  pages: ComputedRef<number>;
+  currentPage: ComputedRef<number>;
+  // ...
+}
+```
+
+**After:**
+
+```ts
+export interface IUseList {
+  pagination: UseDataTablePaginationReturn;
+  // ...
+}
+```
+
+## Rule 2: Update the blade page template
+
+### 2a. Replace VcDataTable pagination bindings
+
+**Before:**
+
+```vue
+<VcDataTable :total-count="totalCount" :pagination="{ currentPage, pages }" @pagination-click="onPaginationClick" />
+```
+
+**After:**
+
+```vue
+<VcDataTable :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" />
+```
+
+### 2b. Update the composable destructure
+
+**Before:**
+
+```ts
+const { items, totalCount, pages, currentPage, searchQuery, loadItems } = useList();
+```
+
+**After:**
+
+```ts
+const { items, pagination, searchQuery, loadItems } = useList();
+```
+
+### 2c. Delete the manual `onPaginationClick` handler
+
+Remove the entire function — it's redundant; `pagination.goToPage` fires the composable's `onPageChange`.
+
+**Delete:**
+
+```ts
+async function onPaginationClick(page: number) {
+  await loadItems({
+    ...searchQuery.value,
+    skip: (page - 1) * (searchQuery.value.take ?? 20),
+  });
+}
+```
+
+### 2d. Rewrite `reload()` helper (if present)
+
+If the blade has a `reload()` helper that recomputes skip from currentPage, use `pagination.skip`:
+
+**Before:**
+
+```ts
+const reload = async () => {
+  await loadItems({
+    ...searchQuery.value,
+    skip: (currentPage.value - 1) * (searchQuery.value.take ?? 10),
+    sort: sortExpression.value,
+  });
+};
+```
+
+**After:**
+
+```ts
+const reload = async () => {
+  await loadItems({
+    ...searchQuery.value,
+    skip: pagination.skip,
+    sort: sortExpression.value,
+  });
+};
+```
+
+## Rule 3: VcTable / VcTableAdapter — skip that file (not the whole topic)
+
+Per-file check. If a specific blade page still uses `<VcTable>` (legacy adapter, with `:pages` + `:current-page` scalar props), SKIP that file — migrating pagination against a different table API would break the bindings. But:
+
+- **Still migrate the composable** if other callers (pages with `<VcDataTable>`) exist — the composable change is independent of any single consumer.
+- **Still migrate other pages** in the same `affectedFiles` list that DO use `<VcDataTable>`.
+- In your report, mark the skipped file(s) as `needs vctable-audit first` so the user knows why.
+
+Do not skip the entire topic just because one file is out of scope.
+
+## Rule 4: Infinite-scroll tables — skip that file
+
+If a specific VcDataTable uses `:infinite-scroll="true"`, pagination is not used — skip that file. Same per-file rule as Rule 3.
+
+## Behavioral notes
+
+- `pagination` is a `reactive()` object — access properties directly (`pagination.totalCount`), never `.value`.
+- Do NOT destructure `pagination` — destructuring loses reactivity.
+- `pagination.reset()` sets currentPage to 1 silently (no onPageChange fire). Use when resetting filters.
+
+## Self-check after migration
+
+- [ ] `totalCount`, `pages`, `currentPage` no longer appear in the composable's return.
+- [ ] `onPaginationClick` function is deleted from the blade page.
+- [ ] Template uses `pagination.goToPage` not a handwritten callback.
+- [ ] No `.value` access on `pagination.*` properties.
+- [ ] `useDataTablePagination` import is present in the composable.

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

@@ -0,0 +1,178 @@
+---
+name: widgets-migration
+description: AI transformation rules for useWidgets→useBladeWidgets migration.
+---
+
+# Widget Migration: useWidgets → useBladeWidgets
+
+Migrate blade widgets from the imperative `useWidgets()` + `registerWidget()` API to the declarative `useBladeWidgets()` composable. The new API eliminates manual registration/cleanup and removes the need for per-widget `.vue` components when they only render a standard sidebar item.
+
+## RULE 1: Create Widget Composable
+
+For each blade that calls `registerWidget()`, create a `widgets/useXxxWidgets.ts` composable.
+
+**BEFORE:**
+
+```typescript
+// In XxxDetails.vue <script setup>
+import { useWidgets, useBlade } from "@vc-shell/framework";
+import type { BladeInstance } from "@vc-shell/framework";
+import { onMounted, onUnmounted } from "vue";
+import ChildListWidget from "../widgets/ChildListWidget.vue";
+
+const { registerWidget, clearBladeWidgets } = useWidgets();
+const { openBlade } = useBlade();
+
+onMounted(() => {
+  registerWidget(
+    {
+      id: "ChildListWidget",
+      component: ChildListWidget,
+      props: {
+        count: childCount,
+        onClick: () => openBlade({ name: "ChildEntityList", options: { entityId: entity.value.id } }),
+      },
+    },
+    bladeContext.id,
+  );
+});
+
+onUnmounted(() => {
+  clearBladeWidgets(bladeContext.id);
+});
+```
+
+**AFTER:**
+
+```typescript
+// widgets/useEntityWidgets.ts
+import { useBladeWidgets, useBlade } from "@vc-shell/framework";
+import type { UseBladeWidgetsReturn } from "@vc-shell/framework";
+import { computed, type Ref } from "vue";
+
+interface UseEntityWidgetsOptions {
+  item: Ref<Entity | undefined>;
+  isVisible: Ref<boolean> | boolean;
+  childCount: Ref<number>;
+}
+
+export function useEntityWidgets(options: UseEntityWidgetsOptions): UseBladeWidgetsReturn {
+  const { item, isVisible, childCount } = options;
+  const { openBlade } = useBlade();
+
+  return useBladeWidgets([
+    {
+      id: "ChildListWidget",
+      icon: "lucide-tag",
+      title: "MODULE.WIDGETS.CHILD_LIST.TITLE",
+      badge: computed(() => childCount.value),
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "ChildEntityList",
+          options: { entityId: item.value?.id },
+        }),
+      onRefresh: async () => {
+        // load child count logic here
+      },
+    },
+  ]);
+}
+```
+
+## RULE 2: Replace Usage in Blade Page
+
+Import the new composable and destructure `{ refreshAll }`.
+
+**BEFORE:**
+
+```typescript
+// XxxDetails.vue <script setup>
+import { useWidgets } from "@vc-shell/framework";
+import ChildListWidget from "../widgets/ChildListWidget.vue";
+import RelatedItemsWidget from "../widgets/RelatedItemsWidget.vue";
+
+const { registerWidget, clearBladeWidgets } = useWidgets();
+
+onMounted(() => {
+  registerWidget({ id: "ChildListWidget", component: ChildListWidget, props: { ... } }, bladeId);
+  registerWidget({ id: "RelatedItemsWidget", component: RelatedItemsWidget, props: { ... } }, bladeId);
+});
+
+onUnmounted(() => {
+  clearBladeWidgets(bladeId);
+});
+```
+
+**AFTER:**
+
+```typescript
+// XxxDetails.vue <script setup>
+import { useEntityWidgets } from "../widgets/useEntityWidgets";
+
+const isExisting = computed(() => !!param.value);
+
+const { refreshAll } = useEntityWidgets({
+  item: entity,
+  isVisible: isExisting,
+  childCount,
+});
+```
+
+If the old code used `updateActiveWidget()`, replace it with `refreshAll()` from the widget composable return:
+
+```typescript
+// BEFORE
+const { updateActiveWidget } = useWidgets();
+updateActiveWidget();
+
+// AFTER
+const { refreshAll } = useEntityWidgets({ item: entity, isVisible: isExisting, childCount });
+refreshAll();
+```
+
+## RULE 3: Remove Widget .vue Components
+
+Delete widget `.vue` files that only render a standard sidebar item (icon + title + badge + click handler). These are replaced by the declarative config in `useBladeWidgets()`.
+
+**Keep** the `.vue` component only if it has custom rendering beyond the standard widget layout.
+
+**Delete:**
+
+- `widgets/ChildListWidget.vue` (if it only shows icon, title, badge, click)
+- `widgets/RelatedItemsWidget.vue` (same)
+
+**Keep:**
+
+- `widgets/CustomChartWidget.vue` (has custom chart rendering)
+
+## RULE 4: Remove Old Imports
+
+Remove these imports that are no longer needed:
+
+```typescript
+// REMOVE all of these:
+import { useWidgets } from "@vc-shell/framework";
+import type { BladeInstance } from "@vc-shell/framework"; // if only used for widgets
+import { registerWidget, unregisterWidget, clearBladeWidgets } from "...";
+import { onUnmounted } from "vue"; // if only used for widget cleanup
+import ChildListWidget from "../widgets/ChildListWidget.vue"; // deleted component
+```
+
+## RULE 5: `defineBladeContext` only for external widgets
+
+Do not add `defineBladeContext()` by default in this migration.
+
+Add it only if the blade hosts external widget components that use `injectBladeContext()`.
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm widgets appear in the blade sidebar
+3. Confirm badge counts update reactively
+4. Confirm clicking a widget opens the correct child blade
+5. Confirm widgets are hidden when `isVisible` is false (e.g., on "create new" blades)
+6. Confirm no console errors about widget registration/cleanup on blade close
+7. Confirm `updateActiveWidget()` calls are removed and replaced with `refreshAll()` from `useEntityWidgets` return

package/runtime/knowledge/patterns/assets-management.md

@@ -68,7 +68,9 @@ const { showConfirmation } = usePopup();
 
 const images = computed({
   get: () => item.value?.images ?? [],
-  set: (val) => { if (item.value) item.value.images = val; },
+  set: (val) => {
+    if (item.value) item.value.images = val;
+  },
 });
 
 const assets = useAssetsManager(images, {
@@ -101,13 +103,7 @@ Use when assets are a secondary concern shown as a widget badge. Clicking the wi
 ```ts
 // widgets/useEntityWidgets.ts
 import { computed, markRaw, type Ref, type ComputedRef } from "vue";
-import {
-  useBlade,
-  useBladeWidgets,
-  useAssetsManager,
-  usePopup,
-  type UseBladeWidgetsReturn,
-} from "@vc-shell/framework";
+import { useBlade, useBladeWidgets, useAssetsManager, usePopup, type UseBladeWidgetsReturn } from "@vc-shell/framework";
 
 interface Options {
   item: Ref<Entity | undefined>;
@@ -145,7 +141,7 @@ export function useEntityWidgets({ item, disabled, isVisible }: Options): UseBla
         openBlade({
           name: "AssetsManager",
           options: {
-            manager: markRaw(assetsManager),  // markRaw prevents Vue from making it reactive
+            manager: markRaw(assetsManager), // markRaw prevents Vue from making it reactive
             disabled: disabled.value,
           },
         }),
@@ -186,14 +182,18 @@ Each manager operates on a different writable computed pointing to a different a
 // Gallery assets (images)
 const productImages = computed({
   get: () => item.value.productData?.images ?? [],
-  set: (val) => { if (item.value.productData) item.value.productData.images = val; },
+  set: (val) => {
+    if (item.value.productData) item.value.productData.images = val;
+  },
 });
 const imageAssets = useAssetsManager(productImages, { uploadPath: () => `/catalog/${item.value.id}` });
 
 // Widget assets (files)
 const productFiles = computed({
   get: () => (item.value?.productData?.assets ?? []) as Asset[],
-  set: (val) => { if (item.value?.productData) item.value.productData.assets = val; },
+  set: (val) => {
+    if (item.value?.productData) item.value.productData.assets = val;
+  },
 });
 const fileAssets = useAssetsManager(productFiles, { uploadPath: () => `/catalog/${item.value.id}` });
 ```
@@ -202,12 +202,12 @@ const fileAssets = useAssetsManager(productFiles, { uploadPath: () => `/catalog/
 
 ## Key Points
 
-| Concern | Approach |
-|---|---|
-| Binding to entity | Writable `computed` — getter reads nested array, setter writes it back |
-| Upload path | Callback `() => string` — resolved at upload time, so entity ID is available |
-| Remove confirmation | Pass `confirmRemove` returning `Promise<boolean>` via `usePopup().showConfirmation` |
-| Passing to AssetsManager blade | Wrap with `markRaw()` — prevents Vue from making the manager deeply reactive |
-| Multiple asset types | Create separate `useAssetsManager` instances per array (images vs files) |
-| Gallery edit | Open `AssetsDetails` blade, pass `assetEditHandler` and `assetRemoveHandler` callbacks |
-| Widget visibility | Use `isVisible: computed(() => !!param.value)` to hide on "create new" mode |
+| Concern                        | Approach                                                                               |
+| ------------------------------ | -------------------------------------------------------------------------------------- |
+| Binding to entity              | Writable `computed` — getter reads nested array, setter writes it back                 |
+| Upload path                    | Callback `() => string` — resolved at upload time, so entity ID is available           |
+| Remove confirmation            | Pass `confirmRemove` returning `Promise<boolean>` via `usePopup().showConfirmation`    |
+| Passing to AssetsManager blade | Wrap with `markRaw()` — prevents Vue from making the manager deeply reactive           |
+| Multiple asset types           | Create separate `useAssetsManager` instances per array (images vs files)               |
+| Gallery edit                   | Open `AssetsDetails` blade, pass `assetEditHandler` and `assetRemoveHandler` callbacks |
+| Widget visibility              | Use `isVisible: computed(() => !!param.value)` to hide on "create new" mode            |

package/runtime/knowledge/patterns/blade-navigation.md

@@ -9,15 +9,7 @@ Blades are stacked panels rendered by `VcBladeNavigation`. Navigation between bl
 ```ts
 import { useBlade } from "@vc-shell/framework";
 
-const {
-  openBlade,
-  closeSelf,
-  callParent,
-  exposeToChildren,
-  onBeforeClose,
-  param,
-  options,
-} = useBlade<OptionsType>();
+const { openBlade, closeSelf, callParent, exposeToChildren, onBeforeClose, param, options } = useBlade<OptionsType>();
 ```
 
 `useBlade()` must be called inside `<script setup>` of a blade component. It uses provide/inject to wire the blade hierarchy.
@@ -58,6 +50,7 @@ entity.value.name = options.value?.prefilledName ?? "";
 ## `openBlade()` — Open a child blade
 
 Full signature:
+
 ```ts
 openBlade({
   name: string,           // defineBlade name of the target blade
@@ -133,7 +126,7 @@ const { callParent } = useBlade();
 
 // In details blade after save:
 await updateXxx(entity.value);
-callParent("reload");   // calls parent's reload() function
+callParent("reload"); // calls parent's reload() function
 closeSelf();
 ```
 
@@ -170,19 +163,19 @@ const { showConfirmation } = usePopup();
 onBeforeClose(async () => {
   if (modified.value) {
     // returns true to BLOCK close, false to ALLOW close
-    return !(await showConfirmation(
-      unref(computed(() => t("MODULE.PAGES.ALERTS.CLOSE_CONFIRMATION"))),
-    ));
+    return !(await showConfirmation(unref(computed(() => t("MODULE.PAGES.ALERTS.CLOSE_CONFIRMATION")))));
   }
-  return false;   // no unsaved changes — allow close
+  return false; // no unsaved changes — allow close
 });
 ```
 
 Return value semantics:
+
 - `false` → close is allowed
 - `true` → close is blocked (user stays on the blade)
 
 The pattern `!(await showConfirmation(...))` works as:
+
 - User clicks "Confirm" → `showConfirmation` returns `true` → `!true` = `false` → close allowed
 - User clicks "Cancel" → `showConfirmation` returns `false` → `!false` = `true` → close blocked