@vc-shell/vc-app-skill 2.0.0-alpha.33 → 2.0.0-alpha.34

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

@@ -0,0 +1,97 @@
+---
+name: icon-migration
+description: AI transformation rules for migrating non-lucide icons to lucide equivalents.
+---
+
+# Icon Migration: material-/bi-/fa- → lucide-
+
+All icons in the v2 framework must use the `lucide-` prefix. Replace all `material-*`, `bi-*`, and `fa-*` icons with their lucide equivalents.
+
+## RULE 1: Replace Icon Strings
+
+Scan ALL `.vue` and `.ts` files in the affected module for icon strings. For each non-lucide icon, choose the closest semantic match from the lucide icon set (https://lucide.dev/icons).
+
+When choosing a replacement:
+
+- Match by **meaning**, not by visual similarity — e.g., `material-delete` → `lucide-trash-2` (both mean "delete")
+- Use the most specific icon available — e.g., `material-person_add` → `lucide-user-plus` (not just `lucide-user`)
+- When no perfect match exists, pick the closest conceptual equivalent and note it in the report
+
+**BEFORE:**
+
+```typescript
+const bladeToolbar = computed((): IBladeToolbar[] => [
+  {
+    id: "refresh",
+    icon: "material-refresh",
+    title: t("...REFRESH"),
+    clickHandler: reload,
+  },
+  {
+    id: "add",
+    icon: "material-add",
+    title: t("...ADD"),
+    clickHandler: addItem,
+  },
+  {
+    id: "delete",
+    icon: "material-delete",
+    title: t("...DELETE"),
+    clickHandler: deleteItems,
+  },
+]);
+```
+
+**AFTER:**
+
+```typescript
+const bladeToolbar = computed((): IBladeToolbar[] => [
+  {
+    id: "refresh",
+    icon: "lucide-refresh-cw",
+    title: t("...REFRESH"),
+    clickHandler: reload,
+  },
+  {
+    id: "add",
+    icon: "lucide-plus",
+    title: t("...ADD"),
+    clickHandler: addItem,
+  },
+  {
+    id: "delete",
+    icon: "lucide-trash-2",
+    title: t("...DELETE"),
+    clickHandler: deleteItems,
+  },
+]);
+```
+
+## RULE 2: Where Icons Appear
+
+Icons appear in these contexts — check ALL of them:
+
+1. **Toolbar items:** `icon: "material-*"` in `IBladeToolbar[]`
+2. **Menu items in defineBlade:** `icon: "material-*"` in `menuItem` config
+3. **VcIcon components:** `<VcIcon icon="material-*" />`
+4. **Widget declarations:** `icon: "material-*"` in `useBladeWidgets()` config
+5. **Action builders / row actions:** `icon: "material-*"` in action definitions
+6. **Empty state configs:** `icon: "material-*"` in `:empty-state` or `:not-found-state`
+7. **Any other string literal** containing `material-`, `bi-`, or `fa-` prefixes
+
+## RULE 3: Perform Replacements In-Place
+
+This is a **mechanical replacement** — do not restructure code. For each icon string found:
+
+1. Identify the icon name (e.g., `material-edit_square`)
+2. Determine the semantic meaning (e.g., "edit with square indicator")
+3. Find the best lucide match (e.g., `lucide-square-pen`)
+4. Replace the string in-place
+
+## Verification
+
+After migration:
+
+1. Search for remaining non-lucide icons: `grep -rn '"material-\|"bi-\|fa-' src/modules/`
+2. Verify no results (all icons should be `lucide-*`)
+3. Run the app and visually confirm icons render correctly

package/runtime/knowledge/migration-prompts/manual-migration-audit.md

@@ -0,0 +1,117 @@
+---
+name: manual-migration-audit
+description: AI transformation rules for findings emitted by manual-migration-audit transform.
+---
+
+# Manual Migration Audit Fixes
+
+Apply targeted refactors for diagnostics emitted by `manual-migration-audit`.
+
+## RULE 1: `useExternalWidgets` is removed
+
+Replace `useExternalWidgets(...)` with module-level widget composables based on `useBladeWidgets()`.
+
+**BEFORE:**
+
+```typescript
+import { useExternalWidgets } from "@vc-shell/framework";
+
+useExternalWidgets({ bladeId, item });
+```
+
+**AFTER:**
+
+```typescript
+import { useEntityWidgets } from "../widgets";
+
+useEntityWidgets({
+  item,
+  isVisible: computed(() => !!param.value),
+  disabled,
+});
+```
+
+If widget migration is not yet done, perform it first (`widgets-migration` topic).
+
+## RULE 2: Replace `moment` usage with framework date utilities
+
+**BEFORE:**
+
+```typescript
+import moment from "moment";
+
+const formatted = moment(item.value.createdDate).format("L LT");
+```
+
+**AFTER:**
+
+```typescript
+import { formatDateWithPattern } from "@vc-shell/framework";
+
+const formatted = formatDateWithPattern(item.value.createdDate, "L LT", currentLocale.value);
+```
+
+For relative dates, use `formatDateRelative` from `@vc-shell/framework`.
+
+## RULE 3: Replace `useFunctions().debounce` with `useDebounceFn`
+
+**BEFORE:**
+
+```typescript
+import { useFunctions } from "@vc-shell/framework";
+
+const { debounce } = useFunctions();
+const debouncedSearch = debounce(runSearch, 300);
+```
+
+**AFTER:**
+
+```typescript
+import { useDebounceFn } from "@vueuse/core";
+
+const debouncedSearch = useDebounceFn(runSearch, 300);
+```
+
+## RULE 4: Replace `closeBlade()` with `closeSelf()` from `useBlade()`
+
+**BEFORE:**
+
+```typescript
+const { closeBlade } = useBlade();
+await closeBlade();
+```
+
+**AFTER:**
+
+```typescript
+const { closeSelf } = useBlade();
+await closeSelf();
+```
+
+If `closeBlade(index)` was used to close by index, refactor to close current blade only (or use explicit navigation logic) — do not keep index-based close calls.
+
+## RULE 5: Consolidate multiple `useBlade()` calls per file
+
+Use one `useBlade()` destructuring per component/composable unless there is a strong technical reason.
+
+**BEFORE:**
+
+```typescript
+const { openBlade } = useBlade();
+const { closeSelf } = useBlade();
+```
+
+**AFTER:**
+
+```typescript
+const { openBlade, closeSelf, callParent, param } = useBlade();
+```
+
+## Verification
+
+After migration:
+
+1. Search and remove stale APIs: `useExternalWidgets`, `import moment`, `useFunctions(`, `closeBlade(`.
+2. Search for duplicate `useBlade()` calls in the same file and consolidate.
+3. Run `npx vue-tsc --noEmit`.
+4. Run `yarn build`.

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

@@ -146,6 +146,7 @@ export default defineAppModule({
 ```
 
 Toast options:
+
 - `mode`: `"auto"` (show and auto-dismiss), `"progress"` (show with progress bar), `"silent"` (no toast)
 - `severity`: `"info"` (default), `"warning"`, `"error"`, `"critical"`
 
@@ -174,9 +175,13 @@ setNotificationHandler((message) => {
 });
 
 // or watch pattern:
-watch(moduleNotifications, (newVal) => {
-  // manual toast management
-}, { deep: true });
+watch(
+  moduleNotifications,
+  (newVal) => {
+    // manual toast management
+  },
+  { deep: true },
+);
 ```
 
 **AFTER:**

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

@@ -8,6 +8,7 @@ description: AI transformation rules for NSwag class→interface DTO migration.
 You are tasked with fixing TypeScript errors caused by migrating NSwag-generated API clients from class-based to interface-based data models.
 
 **Context:**
+
 - API Client CLASSES (e.g., `*Client` classes) remain unchanged — they still have constructors
 - DATA MODEL types (DTOs, Commands, Queries, etc.) are now INTERFACES instead of classes
 - Interfaces cannot be instantiated with `new` — use object literals with type assertions instead
@@ -120,24 +121,14 @@ When a framework function expects a constructor function (callable with `new`),
 
 ```typescript
 // BEFORE — Framework expects constructor
-const { loadItems } = useFrameworkHook<Type1, Type2>(
-  fetchFunction,
-  ItemClass,
-  OtherClass,
-);
+const { loadItems } = useFrameworkHook<Type1, Type2>(fetchFunction, ItemClass, OtherClass);
 
 // AFTER — Create factory functions
-const createItem = (data?: Partial<ItemType>): ItemType =>
-  ({ ...data } as ItemType);
+const createItem = (data?: Partial<ItemType>): ItemType => ({ ...data }) as ItemType;
 
-const createOther = (data?: Partial<OtherType>): OtherType =>
-  ({ ...data } as OtherType);
+const createOther = (data?: Partial<OtherType>): OtherType => ({ ...data }) as OtherType;
 
-const { loadItems } = useFrameworkHook<Type1, Type2>(
-  fetchFunction,
-  createItem,
-  createOther,
-);
+const { loadItems } = useFrameworkHook<Type1, Type2>(fetchFunction, createItem, createOther);
 ```
 
 ## RULE 4: Image Import Conflict with Global DOM Type
@@ -165,14 +156,14 @@ import { Image as ApiImage, Entity } from "@your-api-package";
 
 ```typescript
 // BEFORE
-items.map((x) => x.id)
-items.filter((item) => item.active)
-data.forEach((d) => process(d))
+items.map((x) => x.id);
+items.filter((item) => item.active);
+data.forEach((d) => process(d));
 
 // AFTER
-items.map((x: ItemType) => x.id)
-items.filter((item: ItemType) => item.active)
-data.forEach((d: DataType) => process(d))
+items.map((x: ItemType) => x.id);
+items.filter((item: ItemType) => item.active);
+data.forEach((d: DataType) => process(d));
 ```
 
 ## RULE 6: Type Mismatch in Function Arguments
@@ -183,25 +174,28 @@ Check if the function signature expects a different type (often an ID instead of
 
 ```typescript
 // BEFORE
-someFunction(asset)  // asset is full object
+someFunction(asset); // asset is full object
 
 // AFTER
-someFunction(asset.id)  // pass the id property
+someFunction(asset.id); // pass the id property
 ```
 
 ## Important Notes
 
 1. **API Client Classes are NOT affected** — Do NOT modify client classes like `*Client`. They remain classes with constructors:
+
    ```typescript
    const { getApiClient } = useApiClient(MyApiClient); // No change needed
    ```
 
 2. **Spread operators work with interfaces:**
+
    ```typescript
    const updated = { ...existingItem, name: "New Name" }; // Works fine
    ```
 
 3. **Required properties must be provided** when using type assertions:
+
    ```typescript
    const details: ItemDetails = {
      sku: item.sku || "",
@@ -210,6 +204,7 @@ someFunction(asset.id)  // pass the id property
    ```
 
 4. **Generic type parameters need updating too:**
+
    ```typescript
    // BEFORE
    const { action } = useAsync<ISearchQuery>(...)
@@ -219,6 +214,7 @@ someFunction(asset.id)  // pass the id property
    ```
 
 5. **Interfaces with all optional properties** can use empty object:
+
    ```typescript
    const query: SearchQuery = {}; // OK if all properties are optional
    ```
@@ -230,13 +226,13 @@ someFunction(asset.id)  // pass the id property
 
 ## Quick Reference Table
 
-| Error Code | Pattern | Fix |
-|------------|---------|-----|
-| TS2724 | `IXxx` not found | Remove "I" prefix from import |
-| TS2693 | Type used as value | Replace `new Type({})` with `{} as Type` |
-| TS2866 | Import conflicts with global | Use `type` import or rename |
-| TS7006 | Implicit any | Add explicit type annotation |
-| TS2345 | Type not assignable | Check if property (like `.id`) should be passed |
+| Error Code | Pattern                      | Fix                                             |
+| ---------- | ---------------------------- | ----------------------------------------------- |
+| TS2724     | `IXxx` not found             | Remove "I" prefix from import                   |
+| TS2693     | Type used as value           | Replace `new Type({})` with `{} as Type`        |
+| TS2866     | Import conflicts with global | Use `type` import or rename                     |
+| TS7006     | Implicit any                 | Add explicit type annotation                    |
+| TS2345     | Type not assignable          | Check if property (like `.id`) should be passed |
 
 ## Verification
 

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.