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

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();
+  });
 
   // ...
 };

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

@@ -2,7 +2,7 @@
 
 Describes the plural composable that handles search, pagination, and sort for a list blade. Named with the **plural** entity name: `useTeamMembers`, `useCatalogItems`, `useOrders`.
 
-Source: extracted from `apps/vendor-portal/src/modules/team/composables/useTeamMembers/index.ts`.
+Generic worked example for the plural list composable shape.
 
 ---
 
@@ -10,12 +10,7 @@ Source: extracted from `apps/vendor-portal/src/modules/team/composables/useTeamM
 
 ```ts
 import { useApiClient, useAsync, useLoading } from "@vc-shell/framework";
-import {
-  SearchXxxQuery,
-  SearchXxxResult,
-  XxxType,
-  XxxClient,
-} from "../../../../api_client/<module-client-file>";
+import { SearchXxxQuery, SearchXxxResult, XxxType, XxxClient } from "../../../../api_client/<module-client-file>";
 import type { SearchXxxQuery as ISearchXxxQuery } from "../../../../api_client/<module-client-file>";
 import { computed, Ref, ref } from "vue";
 import { useRoute } from "vue-router";
@@ -39,7 +34,7 @@ interface IUseXxxsOptions {
 
 export default (options?: IUseXxxsOptions): IUseXxxs => {
   const { getApiClient } = useApiClient(XxxClient);
-  const route = useRoute();   // for extracting route params (e.g., sellerId, parentId)
+  const route = useRoute(); // for extracting route params (e.g., ownerId, parentId)
 
   const pageSize = options?.pageSize || 20;
 
@@ -90,24 +85,19 @@ export default (options?: IUseXxxsOptions): IUseXxxs => {
 
 ```ts
 import { useApiClient, useAsync, useLoading } from "@vc-shell/framework";
-import {
-  SearchSellerUsersQuery,
-  SearchSellerUsersResult,
-  SellerUser,
-  VcmpSellerSecurityClient,
-} from "../../../../api_client/virtocommerce.marketplacevendor";
-import type { SearchSellerUsersQuery as ISearchSellerUsersQuery } from "../../../../api_client/virtocommerce.marketplacevendor";
+import { SearchUsersQuery, SearchUsersResult, User, UserSecurityClient } from "../../../../api_client/virtocommerce.mymodule";
+import type { SearchUsersQuery as ISearchUsersQuery } from "../../../../api_client/virtocommerce.mymodule";
 import { computed, Ref, ref } from "vue";
 import { useRoute } from "vue-router";
 
 interface IUseTeamMembers {
   readonly loading: Ref<boolean>;
-  readonly membersList: Ref<SellerUser[]>;
+  readonly membersList: Ref<User[]>;
   readonly totalCount: Ref<number>;
   readonly pages: Ref<number>;
   currentPage: Ref<number>;
-  searchQuery: Ref<ISearchSellerUsersQuery>;
-  getTeamMembers: (query?: ISearchSellerUsersQuery) => Promise<void>;
+  searchQuery: Ref<ISearchUsersQuery>;
+  getTeamMembers: (query?: ISearchUsersQuery) => Promise<void>;
 }
 
 interface IUseTeamMembersOptions {
@@ -116,29 +106,29 @@ interface IUseTeamMembersOptions {
 }
 
 export default (options?: IUseTeamMembersOptions): IUseTeamMembers => {
-  const { getApiClient } = useApiClient(VcmpSellerSecurityClient);
+  const { getApiClient } = useApiClient(UserSecurityClient);
   const route = useRoute();
 
   const pageSize = options?.pageSize || 20;
-  const searchQuery = ref<ISearchSellerUsersQuery>({
+  const searchQuery = ref<ISearchUsersQuery>({
     take: pageSize,
     sort: options?.sort,
   });
 
-  const searchResult = ref<SearchSellerUsersResult>();
+  const searchResult = ref<SearchUsersResult>();
 
-  async function GetSellerId(): Promise<string> {
-    const result = route?.params?.sellerId as string;
+  async function GetOwnerId(): Promise<string> {
+    const result = route?.params?.ownerId as string;
     return result;
   }
 
-  const { action: getTeamMembers, loading: getTeamMembersLoading } = useAsync<ISearchSellerUsersQuery>(async (query) => {
+  const { action: getTeamMembers, loading: getTeamMembersLoading } = useAsync<ISearchUsersQuery>(async (query) => {
     const client = await getApiClient();
-    const sellerId = await GetSellerId();
+    const ownerId = await GetOwnerId();
     searchQuery.value = { ...searchQuery.value, ...query };
 
-    const command = { ...searchQuery.value, sellerId } as SearchSellerUsersQuery;
-    searchResult.value = await client.searchSellerUsers(command);
+    const command = { ...searchQuery.value, ownerId } as SearchUsersQuery;
+    searchResult.value = await client.searchUsers(command);
   });
 
   return {
@@ -158,7 +148,9 @@ export default (options?: IUseTeamMembersOptions): IUseTeamMembers => {
 ## Key Rules
 
 ### File location
+
 Each composable lives in its own subdirectory with an `index.ts`:
+
 ```
 composables/
 ├── useXxxs/
@@ -167,39 +159,52 @@ composables/
 ```
 
 ### Default export (not named)
+
 The composable is a **default export** (a factory function). Named exports are the interfaces only. The barrel (`composables/index.ts`) wraps it with a named export:
+
 ```ts
 export { default as useXxxs } from "./useXxxs";
 ```
 
 ### Type aliasing
+
 NSwag generates classes with the same name as their interfaces. Import the class for runtime use, and import the interface type separately with an alias:
+
 ```ts
-import { SearchXxxQuery, XxxClient } from "...";            // class (runtime)
+import { SearchXxxQuery, XxxClient } from "..."; // class (runtime)
 import type { SearchXxxQuery as ISearchXxxQuery } from "..."; // interface (type-only)
 ```
 
 ### `useAsync` signature
+
 `useAsync<TArg>(fn)` — generic `TArg` is the type of the argument passed to the action:
+
 ```ts
 const { action: getXxxs, loading: getXxxsLoading } = useAsync<ISearchXxxQuery>(async (query) => {
   // query is typed as ISearchXxxQuery | undefined
 });
 ```
+
 `action` is the callable — invoke it as `getXxxs(query)`.
 
 ### `useLoading`
+
 Wrap loading refs with `useLoading` for consistent boolean ref behavior:
+
 ```ts
 loading: useLoading(getXxxsLoading),
 ```
+
 If there are multiple async operations (e.g., search + delete), pass all loading refs:
+
 ```ts
 loading: useLoading(getXxxsLoading, deleteXxxLoading),
 ```
 
 ### Route params
-Use `useRoute()` to access route params when the API requires a parent entity ID (e.g., `sellerId`, `orderId`). Access inside the async function, not at module scope:
+
+Use `useRoute()` to access route params when the API requires a parent entity ID (e.g., `ownerId`, `orderId`). Access inside the async function, not at module scope:
+
 ```ts
 const route = useRoute();
 // inside useAsync callback:
@@ -207,15 +212,18 @@ const parentId = route?.params?.parentId as string;
 ```
 
 ### No `useI18n` in composables
+
 i18n belongs in blade components only. Composables must not import or use `useI18n`.
 
 ### `searchQuery` is mutable
+
 The `searchQuery` ref is returned with `Ref<ISearchXxxQuery>` (not `readonly`) because the blade reads it to construct reload/pagination calls:
+
 ```ts
 // In blade:
 const reload = async () => {
   await getXxxs({
-    ...searchQuery.value,          // preserve existing params
+    ...searchQuery.value, // preserve existing params
     skip: (currentPage.value - 1) * (searchQuery.value?.take ?? 20),
     sort: sortExpression.value,
   });
@@ -223,22 +231,26 @@ const reload = async () => {
 ```
 
 ### `currentPage` computation
+
 ```ts
 currentPage: computed(() => Math.floor((searchQuery.value.skip || 0) / pageSize) + 1),
 ```
+
 Derived from `skip` — no separate state needed.
 
 ### `pages` computation
+
 ```ts
 pages: computed(() => Math.ceil((searchResult.value?.totalCount || 0) / pageSize)),
 ```
+
 Total number of pages for pagination component.
 
 ---
 
 ## Composable Without Route Params
 
-When the API doesn't need a parent ID (module is not nested under a seller/store/etc.):
+When the API doesn't need a parent ID (module is not nested under an owner/store/etc.):
 
 ```ts
 const { action: getXxxs, loading: getXxxsLoading } = useAsync<ISearchXxxQuery>(async (query) => {

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

@@ -34,13 +34,13 @@ export * from "./composables";
 
 ```ts
 interface DashboardWidget {
-  id: string;                          // unique across all registered widgets
-  name: string;                        // display name
-  component: Component;                // widget Vue component, wrapped in markRaw()
-  size: { width: number; height: number };  // grid units
+  id: string; // unique across all registered widgets
+  name: string; // display name
+  component: Component; // widget Vue component, wrapped in markRaw()
+  size: { width: number; height: number }; // grid units
   position?: { x: number; y: number }; // optional initial grid position
-  permissions?: string[];              // optional: restrict visibility by permission
-  props?: Record<string, unknown>;     // optional: static props passed to component
+  permissions?: string[]; // optional: restrict visibility by permission
+  props?: Record<string, unknown>; // optional: static props passed to component
 }
 ```
 
@@ -66,28 +66,25 @@ The widget component is a plain Vue SFC placed in `src/modules/xxx/components/`:
 </template>
 
 <script lang="ts" setup>
-import {
-  DashboardWidgetCard,
-  DashboardStatItem,
-} from "@vc-shell/framework";
+import { DashboardWidgetCard, DashboardStatItem } from "@vc-shell/framework";
 import { ref, onMounted } from "vue";
 import useXxxs from "../composables/useXxxs";
 
 const { getXxxs, totalCount, loading } = useXxxs();
 
 onMounted(async () => {
-  await getXxxs({ take: 0 });   // fetch count only
+  await getXxxs({ take: 0 }); // fetch count only
 });
 </script>
 ```
 
 ### Available dashboard sub-components from `@vc-shell/framework`
 
-| Component             | Description                                 |
-|-----------------------|---------------------------------------------|
-| `DashboardWidgetCard` | Card wrapper with title slot                |
-| `DashboardStatItem`   | Single stat row: label + value + loading    |
-| `DashboardBarChart`   | Horizontal bar chart for breakdown stats    |
+| Component             | Description                              |
+| --------------------- | ---------------------------------------- |
+| `DashboardWidgetCard` | Card wrapper with title slot             |
+| `DashboardStatItem`   | Single stat row: label + value + loading |
+| `DashboardBarChart`   | Horizontal bar chart for breakdown stats |
 
 ---
 
@@ -101,6 +98,7 @@ src/modules/xxx/
 ```
 
 `components/index.ts` barrel:
+
 ```ts
 export { default as XxxDashboardCard } from "./XxxDashboardCard.vue";
 ```