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

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

@@ -18,7 +18,7 @@ For each blade that calls `registerWidget()`, create a `widgets/useXxxWidgets.ts
 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";
+import ChildListWidget from "../widgets/ChildListWidget.vue";
 
 const { registerWidget, clearBladeWidgets } = useWidgets();
 const { openBlade } = useBlade();
@@ -26,11 +26,11 @@ const { openBlade } = useBlade();
 onMounted(() => {
   registerWidget(
     {
-      id: "OffersWidget",
-      component: OffersWidget,
+      id: "ChildListWidget",
+      component: ChildListWidget,
       props: {
-        count: offersCount,
-        onClick: () => openBlade({ name: "OffersList", options: { productId: entity.value.id } }),
+        count: childCount,
+        onClick: () => openBlade({ name: "ChildEntityList", options: { entityId: entity.value.id } }),
       },
     },
     bladeContext.id,
@@ -45,35 +45,35 @@ onUnmounted(() => {
 **AFTER:**
 
 ```typescript
-// widgets/useProductWidgets.ts
+// widgets/useEntityWidgets.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>;
+interface UseEntityWidgetsOptions {
+  item: Ref<Entity | undefined>;
   isVisible: Ref<boolean> | boolean;
-  offersCount: Ref<number>;
+  childCount: Ref<number>;
 }
 
-export function useProductWidgets(options: UseProductWidgetsOptions): UseBladeWidgetsReturn {
-  const { item, isVisible, offersCount } = options;
+export function useEntityWidgets(options: UseEntityWidgetsOptions): UseBladeWidgetsReturn {
+  const { item, isVisible, childCount } = options;
   const { openBlade } = useBlade();
 
   return useBladeWidgets([
     {
-      id: "OffersWidget",
+      id: "ChildListWidget",
       icon: "lucide-tag",
-      title: "PRODUCTS.WIDGETS.OFFERS.TITLE",
-      badge: computed(() => offersCount.value),
+      title: "MODULE.WIDGETS.CHILD_LIST.TITLE",
+      badge: computed(() => childCount.value),
       isVisible,
       onClick: () =>
         openBlade({
-          name: "OffersList",
-          options: { productId: item.value?.id },
+          name: "ChildEntityList",
+          options: { entityId: item.value?.id },
         }),
       onRefresh: async () => {
-        // load offers count logic here
+        // load child count logic here
       },
     },
   ]);
@@ -89,14 +89,14 @@ Import the new composable and destructure `{ refreshAll }`.
 ```typescript
 // XxxDetails.vue <script setup>
 import { useWidgets } from "@vc-shell/framework";
-import OffersWidget from "../widgets/OffersWidget.vue";
-import AssociationsWidget from "../widgets/AssociationsWidget.vue";
+import ChildListWidget from "../widgets/ChildListWidget.vue";
+import RelatedItemsWidget from "../widgets/RelatedItemsWidget.vue";
 
 const { registerWidget, clearBladeWidgets } = useWidgets();
 
 onMounted(() => {
-  registerWidget({ id: "OffersWidget", component: OffersWidget, props: { ... } }, bladeId);
-  registerWidget({ id: "AssociationsWidget", component: AssociationsWidget, props: { ... } }, bladeId);
+  registerWidget({ id: "ChildListWidget", component: ChildListWidget, props: { ... } }, bladeId);
+  registerWidget({ id: "RelatedItemsWidget", component: RelatedItemsWidget, props: { ... } }, bladeId);
 });
 
 onUnmounted(() => {
@@ -108,17 +108,29 @@ onUnmounted(() => {
 
 ```typescript
 // XxxDetails.vue <script setup>
-import { useProductWidgets } from "../widgets/useProductWidgets";
+import { useEntityWidgets } from "../widgets/useEntityWidgets";
 
 const isExisting = computed(() => !!param.value);
 
-const { refreshAll } = useProductWidgets({
+const { refreshAll } = useEntityWidgets({
   item: entity,
   isVisible: isExisting,
-  offersCount,
+  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()`.
@@ -126,10 +138,12 @@ Delete widget `.vue` files that only render a standard sidebar item (icon + titl
 **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)
+
+- `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
@@ -142,9 +156,15 @@ 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
+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:
@@ -155,3 +175,4 @@ After migration:
 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
 

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

@@ -1,6 +1,6 @@
 # Blade Widget Pattern
 
-Blade widgets are sidebar items displayed alongside a details blade. They allow navigation to related child blades (e.g., "Offers for this product", "Associated items"). Each widget shows an icon, a title, and an optional reactive badge count.
+Blade widgets are sidebar items displayed alongside a details blade. They allow navigation to related child blades (e.g., "Children of this entity", "Associated items"). Each widget shows an icon, a title, and an optional reactive badge count.
 
 Blade widgets use `useBladeWidgets()` — the headless widget API. No `.vue` component is needed per widget; the framework renders a standard `<VcWidget>` from the config object.
 
@@ -17,18 +17,18 @@ import { useBladeWidgets, useBlade } from "@vc-shell/framework";
 import { computed } from "vue";
 
 const { openBlade } = useBlade();
-const offersCount = ref(0);
+const childCount = ref(0);
 
 useBladeWidgets([
   {
-    id: "OffersWidget",
+    id: "ChildListWidget",
     icon: "lucide-tag",
-    title: "PRODUCTS.WIDGETS.OFFERS.TITLE",
-    badge: computed(() => offersCount.value),
-    isVisible: computed(() => !!param.value),   // hide on "create new"
-    onClick: () => openBlade({ name: "OffersList", options: { productId: entity.value.id } }),
+    title: "MODULE.WIDGETS.CHILD_LIST.TITLE",
+    badge: computed(() => childCount.value),
+    isVisible: computed(() => !!param.value), // hide on "create new"
+    onClick: () => openBlade({ name: "ChildEntityList", options: { entityId: entity.value.id } }),
     onRefresh: async () => {
-      offersCount.value = await loadOffersCount(entity.value.id);
+      childCount.value = await loadChildCount(entity.value.id);
     },
   },
 ]);
@@ -66,10 +66,11 @@ export function useXxxWidgets(options: UseXxxWidgetsOptions): UseBladeWidgetsRet
       title: "XXX.WIDGETS.RELATED_ITEMS.TITLE",
       badge: relatedCount,
       isVisible,
-      onClick: () => openBlade({
-        name: "RelatedItemsList",
-        options: { parentId: item.value?.id },
-      }),
+      onClick: () =>
+        openBlade({
+          name: "RelatedItemsList",
+          options: { parentId: item.value?.id },
+        }),
     },
   ]);
 }
@@ -96,9 +97,9 @@ const { refreshAll } = useXxxWidgets({
 
 ```ts
 interface HeadlessWidgetDeclaration {
-  id: string;                                              // unique within the blade
-  icon: string;                                            // lucide icon name
-  title: string;                                           // i18n key or plain string
+  id: string; // unique within the blade
+  icon: string; // lucide icon name
+  title: string; // i18n key or plain string
   badge?: Ref<number | string> | ComputedRef<number | string>;
   loading?: Ref<boolean> | ComputedRef<boolean>;
   disabled?: Ref<boolean> | ComputedRef<boolean> | boolean;
@@ -112,8 +113,8 @@ interface HeadlessWidgetDeclaration {
 
 ```ts
 interface UseBladeWidgetsReturn {
-  refresh: (widgetId: string) => void;   // trigger onRefresh for one widget
-  refreshAll: () => void;                // trigger onRefresh for all widgets
+  refresh: (widgetId: string) => void; // trigger onRefresh for one widget
+  refreshAll: () => void; // trigger onRefresh for all widgets
 }
 ```
 
@@ -124,6 +125,7 @@ Call `refreshAll()` from `onMounted` or after data loads to populate badge count
 ## Lifecycle
 
 `useBladeWidgets()` automatically:
+
 - Registers all widgets with the `WidgetService` on `onMounted`
 - Unregisters all widgets from the `WidgetService` on `onUnmounted`
 

package/runtime/knowledge/patterns/child-blade-flow.md

@@ -13,10 +13,14 @@ const { openBlade } = useBlade();
 
 openBlade({
   name: "ProductDetails",
-  param: product.id,                    // string — entity ID, appears in URL
-  options: { mode: "edit", origin: "catalog" },  // object — runtime-only, not in URL
-  onOpen() { selectedItemId.value = product.id; },
-  onClose() { selectedItemId.value = undefined; },
+  param: product.id, // string — entity ID, appears in URL
+  options: { mode: "edit", origin: "catalog" }, // object — runtime-only, not in URL
+  onOpen() {
+    selectedItemId.value = product.id;
+  },
+  onClose() {
+    selectedItemId.value = undefined;
+  },
 });
 ```
 
@@ -93,10 +97,12 @@ onBeforeClose(async () => {
 ```
 
 Return value semantics:
+
 - `false` — close is **allowed**
 - `true` — close is **blocked** (user stays on the blade)
 
 The `!(await showConfirmation(...))` idiom:
+
 - User clicks "Confirm" (discard) -> `true` -> `!true` = `false` -> close allowed
 - User clicks "Cancel" (stay) -> `false` -> `!false` = `true` -> close blocked
 
@@ -187,8 +193,12 @@ function onItemClick(event: { data: { id?: string } }) {
   openBlade({
     name: "ProductDetails",
     param: event.data.id,
-    onOpen() { selectedItemId.value = event.data.id; },
-    onClose() { selectedItemId.value = undefined; },
+    onOpen() {
+      selectedItemId.value = event.data.id;
+    },
+    onClose() {
+      selectedItemId.value = undefined;
+    },
   });
 }
 
@@ -250,7 +260,9 @@ A "middle" blade acts as both child (calls its parent) and parent (exposes metho
 const { openBlade, callParent, exposeToChildren, closeSelf } = useBlade();
 
 // As a parent — expose reload for child blades
-async function reload() { await loadOrder(param.value!); }
+async function reload() {
+  await loadOrder(param.value!);
+}
 exposeToChildren({ reload });
 
 // As a child — open sub-details blade

package/runtime/knowledge/patterns/composable-details.md

@@ -1,6 +1,6 @@
 # Details Composable Pattern (`use<Entity>`)
 
-Reference source: `apps/vendor-portal/src/modules/team/composables/useTeamMember/index.ts`
+Generic worked example for the canonical `useTeamMember` / `useEntity` composable shape.
 
 ## Overview
 
@@ -13,19 +13,9 @@ Naming convention: `use<Entity>` (singular) for details, `use<Entity>s` (plural)
 ## Full Code Skeleton
 
 ```ts
-import {
-  useModificationTracker,
-  useApiClient,
-  useAsync,
-  useLoading,
-} from "@vc-shell/framework";
+import { useModificationTracker, useApiClient, useAsync, useLoading } from "@vc-shell/framework";
 import type { AsyncAction } from "@vc-shell/framework";
-import {
-  XxxClient,
-  XxxType,
-  CreateXxxCommand,
-  UpdateXxxCommand,
-} from "../../api_client/xxx-client";
+import { XxxClient, XxxType, CreateXxxCommand, UpdateXxxCommand } from "../../api_client/xxx-client";
 import { computed, ComputedRef, Ref, ref } from "vue";
 
 // NOTE: useI18n is NOT imported here. Translations belong in blade components.
@@ -50,15 +40,11 @@ export default (): IUseXxx => {
   // --- Entity ref and modification tracker ---
   // entityRef is internal; currentValue is exposed as `entity`
   const entityRef = ref({} as XxxType) as Ref<XxxType>;
-  const { currentValue, pristineValue, resetModificationState, isModified } =
-    useModificationTracker(entityRef);
+  const { currentValue, pristineValue, resetModificationState, isModified } = useModificationTracker(entityRef);
 
   // --- CRUD operations (each has its own loading ref) ---
 
-  const { action: getXxx, loading: getXxxLoading } = useAsync<
-    { id: string },
-    void
-  >(async (args) => {
+  const { action: getXxx, loading: getXxxLoading } = useAsync<{ id: string }, void>(async (args) => {
     if (!args?.id) {
       throw new Error("Id is required");
     }
@@ -74,10 +60,7 @@ export default (): IUseXxx => {
     resetModificationState();
   });
 
-  const { action: createXxx, loading: createXxxLoading } = useAsync<
-    XxxType,
-    void
-  >(async (details) => {
+  const { action: createXxx, loading: createXxxLoading } = useAsync<XxxType, void>(async (details) => {
     const client = await getApiClient();
 
     const command = {
@@ -93,10 +76,7 @@ export default (): IUseXxx => {
     resetModificationState();
   });
 
-  const { action: updateXxx, loading: updateXxxLoading } = useAsync<
-    XxxType,
-    void
-  >(async (details) => {
+  const { action: updateXxx, loading: updateXxxLoading } = useAsync<XxxType, void>(async (details) => {
     if (!details?.id) {
       throw new Error("Id is required");
     }
@@ -116,10 +96,7 @@ export default (): IUseXxx => {
     resetModificationState();
   });
 
-  const { action: deleteXxx, loading: deleteXxxLoading } = useAsync<
-    { id: string },
-    void
-  >(async (args) => {
+  const { action: deleteXxx, loading: deleteXxxLoading } = useAsync<{ id: string }, void>(async (args) => {
     if (!args?.id) {
       throw new Error("Id is required");
     }
@@ -138,12 +115,7 @@ export default (): IUseXxx => {
   // --- Return ---
   return {
     // Aggregate all async loading refs into a single computed boolean
-    loading: useLoading(
-      getXxxLoading,
-      createXxxLoading,
-      updateXxxLoading,
-      deleteXxxLoading,
-    ),
+    loading: useLoading(getXxxLoading, createXxxLoading, updateXxxLoading, deleteXxxLoading),
     // currentValue is the reactive entity — alias as `entity` for the blade
     entity: currentValue,
     modified: computed(() => isModified.value),
@@ -263,9 +235,9 @@ export default (): IUseXxx => {
 
 ---
 
-## Route Params (when entity scope requires sellerId / tenantId)
+## Route Params (when entity scope requires a parent ownerId / tenantId)
 
-Some API calls require a scope parameter (e.g., `sellerId`) extracted from the route. Use `useRoute()`:
+Some API calls require a scope parameter (e.g., `ownerId`) extracted from the route. Use `useRoute()`:
 
 ```ts
 import { useRoute } from "vue-router";
@@ -274,20 +246,18 @@ export default (): IUseXxx => {
   const route = useRoute();
   const { getApiClient } = useApiClient(XxxClient);
 
-  async function getSellerId(): Promise<string> {
-    return route?.params?.sellerId as string;
+  async function getOwnerId(): Promise<string> {
+    return route?.params?.ownerId as string;
   }
 
-  const { action: getXxx, loading: getXxxLoading } = useAsync<{ id: string }>(
-    async (args) => {
-      const client = await getApiClient();
-      const sellerId = await getSellerId();
+  const { action: getXxx, loading: getXxxLoading } = useAsync<{ id: string }>(async (args) => {
+    const client = await getApiClient();
+    const ownerId = await getOwnerId();
 
-      const result = await client.getXxx(args.id, sellerId);
-      currentValue.value = result;
-      resetModificationState();
-    },
-  );
+    const result = await client.getXxx(args.id, ownerId);
+    currentValue.value = result;
+    resetModificationState();
+  });
 
   // ...
 };