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

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

@@ -0,0 +1,218 @@
+---
+name: notifications-migration
+description: AI transformation rules for notification template migration to new defineAppModule config.
+---
+
+# Notifications Migration: useNotifications → useBladeNotifications
+
+Migrate from `createAppModule(pages, locales, notificationTemplates)` to `defineAppModule({ notifications })`, and from `useNotifications()` to `useBladeNotifications()`.
+
+## RULE 1: Move Notification Directory
+
+Move `components/notifications/` to `notifications/` at the module root. Remove the barrel `index.ts` that re-exports all templates.
+
+**BEFORE:**
+
+```
+my-module/
+  components/
+    notifications/
+      index.ts           ← barrel: export { default as MyEvent } from "./MyEvent.vue"
+      MyEvent.vue
+  pages/
+  index.ts
+```
+
+**AFTER:**
+
+```
+my-module/
+  notifications/
+    MyEvent.vue          ← no barrel index.ts needed
+  pages/
+  index.ts
+```
+
+## RULE 2: Update Notification Template
+
+Remove `defineProps`, remove `defineOptions({ inheritAttrs: false })`, and use `useNotificationContext()` composable instead of props.
+
+**BEFORE:**
+
+```vue
+<template>
+  <NotificationTemplate
+    :color="color"
+    :title="notification.title"
+    :icon="icon"
+    :notification="notification"
+    @click="onClick"
+  >
+    <VcHint>{{ notification.description }}</VcHint>
+  </NotificationTemplate>
+</template>
+
+<script lang="ts" setup>
+import { PushNotification, NotificationTemplate } from "@vc-shell/framework";
+
+export interface Props {
+  notification: PushNotification;
+}
+
+defineProps<Props>();
+defineOptions({ inheritAttrs: false });
+
+const color = computed(() => "var(--primary-500)");
+const icon = "lucide-bell";
+
+function onClick() {
+  // handle click
+}
+</script>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <NotificationTemplate
+    :color="color"
+    :title="notification.title"
+    :icon="icon"
+    :notification="notification"
+    @click="onClick"
+  >
+    <VcHint>{{ notification.description }}</VcHint>
+  </NotificationTemplate>
+</template>
+
+<script lang="ts" setup>
+import { PushNotification, useBlade, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
+import { computed } from "vue";
+
+interface IMyNotification extends PushNotification {
+  customField?: string;
+}
+
+const notificationRef = useNotificationContext<IMyNotification>();
+const notification = computed(() => notificationRef.value);
+
+const color = computed(() => "var(--primary-500)");
+const icon = "lucide-bell";
+
+function onClick() {
+  // handle click
+}
+</script>
+```
+
+## RULE 3: Update Module index.ts
+
+Replace `createAppModule(pages, locales, notificationTemplates)` with `defineAppModule({ notifications })`. Import each notification template individually instead of using a barrel `import *`.
+
+**BEFORE:**
+
+```typescript
+import * as pages from "./pages";
+import * as locales from "./locales";
+import * as notificationTemplates from "./components/notifications";
+
+export default createAppModule(pages, locales, notificationTemplates);
+```
+
+**AFTER:**
+
+```typescript
+import * as pages from "./pages";
+import * as locales from "./locales";
+import MyCreatedEvent from "./notifications/MyCreatedEvent.vue";
+import MyDeletedEvent from "./notifications/MyDeletedEvent.vue";
+import { defineAppModule } from "@vc-shell/framework";
+
+export default defineAppModule({
+  blades: pages,
+  locales,
+  notifications: {
+    MyCreatedDomainEvent: {
+      template: MyCreatedEvent,
+      toast: { mode: "auto" },
+    },
+    MyDeletedDomainEvent: {
+      template: MyDeletedEvent,
+      toast: { mode: "auto", severity: "warning" },
+    },
+  },
+});
+```
+
+Toast options:
+- `mode`: `"auto"` (show and auto-dismiss), `"progress"` (show with progress bar), `"silent"` (no toast)
+- `severity`: `"info"` (default), `"warning"`, `"error"`, `"critical"`
+
+## RULE 4: Replace useNotifications in Blades
+
+Replace `useNotifications()` with `useBladeNotifications()`. Remove `setNotificationHandler`, `moduleNotifications` watch, and `notifyType` from `defineOptions`.
+
+**BEFORE:**
+
+```typescript
+defineOptions({
+  name: "MyBlade",
+  notifyType: "MyDomainEvent",
+});
+
+const { markAsRead, setNotificationHandler, moduleNotifications } = useNotifications("MyDomainEvent");
+
+setNotificationHandler((message) => {
+  if (message.title) {
+    notification.success(message.title, {
+      onClose() {
+        markAsRead(message);
+      },
+    });
+  }
+});
+
+// or watch pattern:
+watch(moduleNotifications, (newVal) => {
+  // manual toast management
+}, { deep: true });
+```
+
+**AFTER:**
+
+```typescript
+defineOptions({
+  name: "MyBlade",
+  // notifyType removed
+});
+
+const { messages } = useBladeNotifications({
+  types: ["MyDomainEvent"],
+  onMessage: () => reloadData(),
+});
+```
+
+For progress notifications:
+
+```typescript
+// Module config: notifications: { MyProgressEvent: { toast: { mode: "progress" } } }
+useBladeNotifications({
+  types: ["MyProgressEvent"],
+  filter: (msg) => msg.entityId === param.value,
+  onMessage: (msg) => refreshData(msg),
+});
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm notification templates render correctly in the notification panel
+3. Confirm toast notifications appear for configured event types
+4. Confirm `useBladeNotifications` triggers `onMessage` callback when events arrive
+5. Confirm `notifyType` is removed from all `defineOptions` calls
+6. Confirm `components/notifications/` directory is removed and `notifications/` exists at module root
+7. Confirm no remaining imports of `useNotifications`, `setNotificationHandler`, or `moduleNotifications`
+8. Confirm no remaining `defineProps` or `defineOptions({ inheritAttrs: false })` in notification templates

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

@@ -0,0 +1,248 @@
+---
+name: nswag-migration
+description: AI transformation rules for NSwag class→interface DTO migration.
+---
+
+# NSwag API Client Migration: Class to Interface
+
+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
+
+## RULE 1: Import Name Changes (Remove "I" Prefix)
+
+**Error:** `error TS2724: has no exported member named 'IXxx'. Did you mean 'Xxx'?`
+
+**Fix:** Remove the "I" prefix from all data model interface imports.
+
+```typescript
+// BEFORE
+import { IOffer, ISeller, ISearchQuery } from "@your-api-package";
+
+// AFTER
+import { Offer, Seller, SearchQuery } from "@your-api-package";
+```
+
+Also update all type annotations in the file:
+
+```typescript
+// BEFORE
+const item = ref<IOffer>(...);
+function process(data: IOffer): IOffer { ... }
+
+// AFTER
+const item = ref<Offer>(...);
+function process(data: Offer): Offer { ... }
+```
+
+## RULE 2: Class Instantiation → Object Literals
+
+**Error:** `error TS2693: 'Xxx' only refers to a type, but is being used as a value here`
+
+**Fix:** Replace `new TypeName({...})` with `{...} as TypeName` or typed variable declaration.
+
+**Pattern A — Command/Query objects:**
+
+```typescript
+// BEFORE
+const command = new CreateCommand({
+  id: "123",
+  name: "Test",
+  details: new Details({ value: 100 }),
+});
+
+// AFTER
+const command: CreateCommand = {
+  id: "123",
+  name: "Test",
+  details: { value: 100 } as Details,
+};
+```
+
+**Pattern B — Search/Query criteria:**
+
+```typescript
+// BEFORE
+const criteria = new SearchQuery({
+  take: 20,
+  skip: 0,
+  sort: "name:asc",
+});
+
+// AFTER
+const criteria: SearchQuery = {
+  take: 20,
+  skip: 0,
+  sort: "name:asc",
+};
+```
+
+**Pattern C — Empty/default objects:**
+
+```typescript
+// BEFORE
+const item = ref<IEntity>(new Entity());
+
+// AFTER
+const item = ref<Entity>({} as Entity);
+```
+
+**Pattern D — Nested objects:**
+
+```typescript
+// BEFORE
+const data = ref(new Parent({ child: new Child() }));
+
+// AFTER
+const data = ref<Parent>({
+  child: {} as Child,
+} as Parent);
+```
+
+**Pattern E — With Vue reactive():**
+
+```typescript
+// BEFORE
+const item = ref<Order>(reactive(new Order()));
+
+// AFTER
+const item = ref<Order>(reactive({} as Order));
+```
+
+## RULE 3: Factory Functions for Framework Callbacks
+
+**Error:** `error TS2693: 'PropertyValue' only refers to a type, but is being used as a value here`
+
+When a framework function expects a constructor function (callable with `new`), create factory functions:
+
+```typescript
+// BEFORE — Framework expects constructor
+const { loadItems } = useFrameworkHook<Type1, Type2>(
+  fetchFunction,
+  ItemClass,
+  OtherClass,
+);
+
+// AFTER — Create factory functions
+const createItem = (data?: Partial<ItemType>): ItemType =>
+  ({ ...data } as ItemType);
+
+const createOther = (data?: Partial<OtherType>): OtherType =>
+  ({ ...data } as OtherType);
+
+const { loadItems } = useFrameworkHook<Type1, Type2>(
+  fetchFunction,
+  createItem,
+  createOther,
+);
+```
+
+## RULE 4: Image Import Conflict with Global DOM Type
+
+**Error:** `error TS2866: Import 'Image' conflicts with global value used in this file`
+
+**Fix:** Use type-only import or rename:
+
+```typescript
+// BEFORE
+import { Image, Entity } from "@your-api-package";
+
+// AFTER — Option 1: Type-only import
+import { type Image, Entity } from "@your-api-package";
+
+// AFTER — Option 2: Rename import
+import { Image as ApiImage, Entity } from "@your-api-package";
+```
+
+## RULE 5: Implicit Any Types
+
+**Error:** `error TS7006: Parameter 'x' implicitly has an 'any' type`
+
+**Fix:** Add explicit type annotations to callback parameters:
+
+```typescript
+// BEFORE
+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))
+```
+
+## RULE 6: Type Mismatch in Function Arguments
+
+**Error:** `error TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'`
+
+Check if the function signature expects a different type (often an ID instead of a full object):
+
+```typescript
+// BEFORE
+someFunction(asset)  // asset is full object
+
+// AFTER
+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 || "",
+     ...otherProps,
+   };
+   ```
+
+4. **Generic type parameters need updating too:**
+   ```typescript
+   // BEFORE
+   const { action } = useAsync<ISearchQuery>(...)
+
+   // AFTER
+   const { action } = useAsync<SearchQuery>(...)
+   ```
+
+5. **Interfaces with all optional properties** can use empty object:
+   ```typescript
+   const query: SearchQuery = {}; // OK if all properties are optional
+   ```
+
+6. **Interfaces with required properties** need those properties:
+   ```typescript
+   const item: Item = { id: "default" }; // Must provide 'id'
+   ```
+
+## 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 |
+
+## Verification
+
+After making changes:
+
+1. Run TypeScript compiler: `npx tsc --noEmit` or `npx vue-tsc --noEmit`
+2. Verify no new errors were introduced
+3. Build the project to ensure everything compiles
+4. Test affected functionality if possible

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

@@ -0,0 +1,157 @@
+---
+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 OffersWidget from "../widgets/OffersWidget.vue";
+
+const { registerWidget, clearBladeWidgets } = useWidgets();
+const { openBlade } = useBlade();
+
+onMounted(() => {
+  registerWidget(
+    {
+      id: "OffersWidget",
+      component: OffersWidget,
+      props: {
+        count: offersCount,
+        onClick: () => openBlade({ name: "OffersList", options: { productId: entity.value.id } }),
+      },
+    },
+    bladeContext.id,
+  );
+});
+
+onUnmounted(() => {
+  clearBladeWidgets(bladeContext.id);
+});
+```
+
+**AFTER:**
+
+```typescript
+// widgets/useProductWidgets.ts
+import { useBladeWidgets, useBlade } from "@vc-shell/framework";
+import type { UseBladeWidgetsReturn } from "@vc-shell/framework";
+import { computed, type Ref } from "vue";
+
+interface UseProductWidgetsOptions {
+  item: Ref<Product | undefined>;
+  isVisible: Ref<boolean> | boolean;
+  offersCount: Ref<number>;
+}
+
+export function useProductWidgets(options: UseProductWidgetsOptions): UseBladeWidgetsReturn {
+  const { item, isVisible, offersCount } = options;
+  const { openBlade } = useBlade();
+
+  return useBladeWidgets([
+    {
+      id: "OffersWidget",
+      icon: "lucide-tag",
+      title: "PRODUCTS.WIDGETS.OFFERS.TITLE",
+      badge: computed(() => offersCount.value),
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "OffersList",
+          options: { productId: item.value?.id },
+        }),
+      onRefresh: async () => {
+        // load offers 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 OffersWidget from "../widgets/OffersWidget.vue";
+import AssociationsWidget from "../widgets/AssociationsWidget.vue";
+
+const { registerWidget, clearBladeWidgets } = useWidgets();
+
+onMounted(() => {
+  registerWidget({ id: "OffersWidget", component: OffersWidget, props: { ... } }, bladeId);
+  registerWidget({ id: "AssociationsWidget", component: AssociationsWidget, props: { ... } }, bladeId);
+});
+
+onUnmounted(() => {
+  clearBladeWidgets(bladeId);
+});
+```
+
+**AFTER:**
+
+```typescript
+// XxxDetails.vue <script setup>
+import { useProductWidgets } from "../widgets/useProductWidgets";
+
+const isExisting = computed(() => !!param.value);
+
+const { refreshAll } = useProductWidgets({
+  item: entity,
+  isVisible: isExisting,
+  offersCount,
+});
+```
+
+## 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/OffersWidget.vue` (if it only shows icon, title, badge, click)
+- `widgets/AssociationsWidget.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 OffersWidget from "../widgets/OffersWidget.vue"; // deleted component
+```
+
+## 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