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

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";
 ```