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

package/runtime/knowledge/migration-prompts/blade-form-migration.md

@@ -0,0 +1,246 @@
+---
+name: blade-form-migration
+description: AI transformation rules for useForm + onBeforeClose → useBladeForm.
+---
+
+# Blade Form Migration: useForm → useBladeForm
+
+Replace manual wiring of `useForm()` (vee-validate) + `useModificationTracker()` + `useBeforeUnload()` + `onBeforeClose()` with the unified `useBladeForm()` composable.
+
+## RULE 1: Replace useForm + onBeforeClose with useBladeForm
+
+**BEFORE:**
+
+```typescript
+import { useForm } from "vee-validate";
+import { useBeforeUnload, useModificationTracker, useBlade, usePopup } from "@vc-shell/framework";
+
+const { item, loading, load, save } = useMyDetails();
+const { onBeforeClose } = useBlade();
+const { showConfirmation } = usePopup();
+
+const { errorBag, setFieldError, meta: formMeta } = useForm({
+  initialValues: item,
+});
+
+const { currentValue, resetModificationState, isModified } = useModificationTracker(item);
+
+useBeforeUnload(computed(() => isModified.value));
+
+onBeforeClose(async () => {
+  if (isModified.value) {
+    return showConfirmation(t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"));
+  }
+  return true;
+});
+
+const canSave = computed(
+  () => isModified.value && formMeta.value.valid && !loading.value,
+);
+
+async function handleSave() {
+  await save(item.value);
+  resetModificationState();
+}
+
+async function handleCancel() {
+  item.value = JSON.parse(JSON.stringify(currentValue.value));
+  resetModificationState();
+}
+```
+
+**AFTER:**
+
+```typescript
+import { useBladeForm } from "@vc-shell/framework";
+
+const { item, loading, load, save } = useMyDetails();
+
+const { canSave, isModified, setBaseline, revert, setFieldError, errorBag } = useBladeForm({
+  data: item,
+  closeConfirmMessage: () => t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"),
+});
+
+watch(item, () => {
+  if (item.value) setBaseline();
+}, { once: true });
+
+async function handleSave() {
+  await save(item.value);
+  setBaseline();
+}
+```
+
+## RULE 2: Remove onBeforeClose Entirely
+
+`useBladeForm` handles the unsaved-changes guard automatically via `autoBeforeClose` (defaults to `true`).
+
+**BEFORE:**
+
+```typescript
+const { onBeforeClose } = useBlade();
+
+onBeforeClose(async () => {
+  if (formMeta.value.dirty) {
+    return confirm("You have unsaved changes. Discard?");
+  }
+  return true;
+});
+```
+
+**AFTER:**
+
+```typescript
+// Remove entirely. useBladeForm handles this.
+// If you need a custom message, pass closeConfirmMessage option:
+const form = useBladeForm({
+  data: item,
+  closeConfirmMessage: () => t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"),
+});
+```
+
+## RULE 3: Update Toolbar Disabled Logic
+
+**BEFORE:**
+
+```typescript
+const canSave = computed(
+  () => !meta.value.valid || !isModified.value,
+);
+
+// or in toolbar items:
+{
+  id: "save",
+  disabled: computed(() => !formMeta.value.valid || !isModified.value),
+}
+```
+
+**AFTER:**
+
+```typescript
+// canSave is returned directly from useBladeForm:
+const { canSave } = useBladeForm({ data: item });
+
+// In toolbar items:
+{
+  id: "save",
+  disabled: computed(() => !canSave.value),
+}
+```
+
+For additional disabled conditions (e.g., async validation in progress), use `canSaveOverride`:
+
+```typescript
+const { canSave } = useBladeForm({
+  data: item,
+  canSaveOverride: computed(() => !isSkuValidating.value && !loading.value),
+});
+```
+
+## RULE 4: Keep Field from vee-validate
+
+Only remove `useForm` from vee-validate imports. Keep `Field`, `ErrorMessage`, and other template-level components — they still work with `useBladeForm` which uses vee-validate internally.
+
+**BEFORE:**
+
+```typescript
+import { useForm, Field, ErrorMessage } from "vee-validate";
+```
+
+**AFTER:**
+
+```typescript
+import { Field, ErrorMessage } from "vee-validate";
+```
+
+## RULE 5: Remove useBeforeUnload / useModificationTracker
+
+`useBladeForm` handles both browser unload guards and modification tracking internally.
+
+**BEFORE:**
+
+```typescript
+import { useBeforeUnload, useModificationTracker } from "@vc-shell/framework";
+
+const { currentValue, resetModificationState, isModified } = useModificationTracker(item);
+useBeforeUnload(computed(() => isModified.value));
+```
+
+**AFTER:**
+
+```typescript
+// Remove entirely. useBladeForm provides:
+// - isModified (deep comparison against baseline)
+// - setBaseline() (replaces resetModificationState)
+// - revert() (replaces manual JSON.parse(JSON.stringify(currentValue.value)))
+// - Browser unload guard (automatic)
+```
+
+Also remove `useModificationTracker` from data composables if present:
+
+**BEFORE (data composable):**
+
+```typescript
+export function useMyDetails() {
+  const item = ref<MyItem>();
+  const { currentValue, resetModificationState, isModified } = useModificationTracker(item);
+
+  async function load(id: string) {
+    item.value = await api.get(id);
+    resetModificationState();
+  }
+
+  return { item, currentValue, resetModificationState, isModified, load, save };
+}
+```
+
+**AFTER (data composable):**
+
+```typescript
+export function useMyDetails() {
+  const item = ref<MyItem>();
+
+  async function load(id: string) {
+    item.value = await api.get(id);
+  }
+
+  return { item, load, save };
+}
+```
+
+## Template Changes
+
+Remove `:modified` prop from `<VcBlade>` — it is auto-detected via provide/inject.
+
+**BEFORE:**
+
+```vue
+<template>
+  <VcBlade :modified="isModified" :closable="true">
+    <!-- content -->
+  </VcBlade>
+</template>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <VcBlade :closable="true">
+    <!-- content — no :modified prop needed -->
+  </VcBlade>
+</template>
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm the blade shows a modified indicator when data changes
+3. Confirm closing a modified blade shows the confirmation dialog
+4. Confirm the save button is disabled when form is clean or invalid
+5. Confirm `setBaseline()` is called after initial load and after save
+6. Confirm cancel/revert restores data to the last baseline
+7. Confirm `useModificationTracker` is removed from data composables
+8. Confirm no stale imports of `useForm`, `useBeforeUnload`, `useModificationTracker`, or `onBeforeClose`

package/runtime/knowledge/migration-prompts/blade-props-migration.md

@@ -0,0 +1,195 @@
+---
+name: blade-props-migration
+description: AI transformation rules for reusable blade components skipped by CLI migrator.
+---
+
+# Blade Props Migration: Boilerplate Removal
+
+Remove blade prop/emit boilerplate from blade pages. VcBlade is now context-aware — it reads `expanded` and `closable` from the BladeDescriptor automatically via provide/inject. Use `useBlade()` for `param`, `options`, `closeSelf`, and `callParent`.
+
+## RULE 1: Remove Blade Prop Forwarding from Template
+
+Remove `:expanded`, `:closable`, `@close`, `@expand`, `@collapse` from the `<VcBlade>` tag.
+
+**BEFORE:**
+
+```vue
+<template>
+  <VcBlade
+    :title="bladeTitle"
+    :expanded="expanded"
+    :closable="closable"
+    :toolbar-items="bladeToolbar"
+    @close="$emit('close:blade')"
+    @expand="$emit('expand:blade')"
+    @collapse="$emit('collapse:blade')"
+  >
+    <VcDataTable ... />
+  </VcBlade>
+</template>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <VcBlade
+    :title="bladeTitle"
+    :toolbar-items="bladeToolbar"
+  >
+    <VcDataTable ... />
+  </VcBlade>
+</template>
+```
+
+## RULE 2: Remove Props and Emits Interfaces
+
+Remove `expanded`, `closable`, `param`, `options` from Props interface. Remove blade events from Emits. Use `useBlade()` to access `param` and `options`.
+
+**BEFORE:**
+
+```typescript
+export interface Props {
+  expanded?: boolean;
+  closable?: boolean;
+  param?: string;
+  options?: { sellerProduct?: SellerProduct };
+}
+
+export interface Emits {
+  (event: "parent:call", args: IParentCallArgs): void;
+  (event: "close:blade"): void;
+  (event: "collapse:blade"): void;
+  (event: "expand:blade"): void;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  expanded: true,
+  closable: true,
+});
+const emit = defineEmits<Emits>();
+```
+
+**AFTER:**
+
+```typescript
+import { useBlade } from "@vc-shell/framework";
+
+const { param, options, openBlade, closeSelf, callParent } =
+  useBlade<{ sellerProduct?: SellerProduct }>();
+```
+
+If the Props interface has other non-blade props, keep only those:
+
+```typescript
+// Keep non-blade props
+export interface Props {
+  config?: DetailConfig;
+}
+
+const props = defineProps<Props>();
+
+// Blade concerns via composable
+const { param, options, closeSelf, callParent } = useBlade<{ orderId: string }>();
+```
+
+## RULE 3: Replace emit("parent:call") with callParent()
+
+**BEFORE:**
+
+```typescript
+const emit = defineEmits<Emits>();
+
+const reload = async () => {
+  await loadOffers({ ... });
+  emit("parent:call", { method: "reload" });
+};
+
+function onItemSelect(item: Product) {
+  emit("parent:call", { method: "onItemClick", args: { data: item } });
+}
+```
+
+**AFTER:**
+
+```typescript
+const { callParent } = useBlade();
+
+const reload = async () => {
+  await loadOffers({ ... });
+  callParent("reload");
+};
+
+function onItemSelect(item: Product) {
+  callParent("onItemClick", { data: item });
+}
+```
+
+## RULE 4: Replace emit("close:blade") with closeSelf()
+
+**BEFORE:**
+
+```typescript
+const emit = defineEmits<Emits>();
+
+function handleClose() {
+  emit("close:blade");
+}
+
+// or in template:
+// @click="$emit('close:blade')"
+```
+
+**AFTER:**
+
+```typescript
+const { closeSelf } = useBlade();
+
+function handleClose() {
+  closeSelf();
+}
+
+// or in template:
+// @click="closeSelf()"
+```
+
+## Wrapper Components
+
+If a wrapper component forwards blade props to a base component, remove the forwarding. The base component should call `useBlade()` directly.
+
+**BEFORE:**
+
+```vue
+<template>
+  <ProductDetailsBase
+    :expanded="expanded"
+    :closable="closable"
+    :param="param"
+    :options="options"
+    @parent:call="$emit('parent:call', $event)"
+    @close:blade="$emit('close:blade')"
+    @expand:blade="$emit('expand:blade')"
+    @collapse:blade="$emit('collapse:blade')"
+  />
+</template>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <ProductDetailsBase />
+</template>
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm blades open and close correctly
+3. Confirm `param.value` is accessible in script (use `param` without `.value` in templates)
+4. Confirm `options.value` provides typed options from parent
+5. Confirm `callParent()` triggers the parent's exposed method
+6. Confirm no remaining `emit("close:blade")` or `emit("parent:call", ...)` calls
+7. Confirm no remaining `:expanded`, `:closable`, `@close`, `@expand`, `@collapse` on `<VcBlade>`

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