@vc-shell/vc-app-skill 2.0.4 → 2.0.6

package/runtime/knowledge/docs/core/composables/useBlade/useBlade.docs.md

@@ -23,14 +23,22 @@ Unified composable for blade navigation, identity, communication, guards, and er
 <script setup lang="ts">
 import { useBlade } from "@vc-shell/framework";
 
-// Inside a blade -- full API is available
-const { openBlade, closeSelf, param, onBeforeClose } = useBlade();
+// List blade -- typical destructure: open children, expose parent methods, read param
+interface BladeOptions {
+  item?: Order;
+}
+const { openBlade, exposeToChildren, param, options, callParent } = useBlade<BladeOptions>();
 
-// Open a child blade
-await openBlade({ name: "OrderDetails", param: "order-123" });
+// Expose a reload method so child details blades can refresh the list after save
+async function reload() {
+  /* refetch items */
+}
+exposeToChildren({ reload });
 
-// Read the parameter passed when this blade was opened
-console.log(param.value); // "order-123"
+// Open a child details blade
+function onRowClick(order: Order) {
+  openBlade({ name: "OrderDetails", param: order.id, options: { item: order } });
+}
 </script>
 ```
 
@@ -41,7 +49,7 @@ import { useBlade } from "@vc-shell/framework";
 // Outside a blade (e.g. dashboard widget) -- only navigation works
 const { openBlade } = useBlade();
 
-openBlade({ name: "OrderDetails", param: "order-123" });
+openBlade({ name: "OrdersList", isWorkspace: true });
 </script>
 ```
 
@@ -49,13 +57,14 @@ openBlade({ name: "OrderDetails", param: "order-123" });
 <script setup lang="ts">
 import { useBlade } from "@vc-shell/framework";
 
-// Typed options — no manual casting needed
-interface BladeOptions {
-  sellerProduct?: SellerProduct;
-}
-const { param, options, callParent } = useBlade<BladeOptions>();
+// Details blade -- call back into the parent after save
+const { param, options, callParent, closeSelf } = useBlade<{ item?: Order }>();
 
-console.log(options.value?.sellerProduct); // typed as SellerProduct | undefined
+async function onSave() {
+  await saveOrder();
+  await callParent("reload");
+  await closeSelf();
+}
 </script>
 ```
 
@@ -518,7 +527,7 @@ The most common pattern: a list workspace that opens a details blade on row clic
 <script setup lang="ts">
 import { useBlade } from "@vc-shell/framework";
 
-defineOptions({ name: "ProductsList", url: "/products", isWorkspace: true });
+defineBlade({ name: "ProductsList", url: "/products", isWorkspace: true });
 
 const { openBlade } = useBlade();
 const selectedItemId = ref<string>();
@@ -552,7 +561,7 @@ defineExpose({ reload, title: "Products" });
 <script setup lang="ts">
 import { useBlade, usePopup } from "@vc-shell/framework";
 
-defineOptions({ name: "ProductDetails", url: "/product-details" });
+defineBlade({ name: "ProductDetails", url: "/product-details" });
 
 const { param, onBeforeClose, closeSelf, callParent } = useBlade();
 const { showConfirmation } = usePopup();
@@ -764,11 +773,10 @@ if (param.value) {
 
 ## Related
 
-| Resource                                                                  | Description                                                  |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| [`defineBladeContext` / `injectBladeContext`](../useBladeContext.docs.md) | Share reactive blade data with descendant widgets            |
-| [`useBladeRegistry`](../useBladeRegistry/)                                | Look up registered blade components by name                  |
-| [`VcBlade`](../../../ui/components/organisms/vc-blade/)                   | The blade UI shell component (header, toolbar, content area) |
-| [`VcBladeNavigation`](../../../shared/components/blade-navigation/)       | The container component that renders the blade stack         |
-| [`useToolbar`](../../../shared/composables/useToolbar/)                   | Dynamic toolbar management for blades                        |
-| [`usePopup`](../../../shared/composables/usePopup/)                       | Confirmation dialogs, commonly used in close guards          |
+| Resource                                                                     | Description                                                  |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| [`defineBladeContext` / `injectBladeContext`](../bladeContext/index.docs.md) | Share reactive blade data with descendant widgets            |
+| [`useBladeRegistry`](../useBladeRegistry/)                                   | Look up registered blade components by name                  |
+| [`VcBlade`](../../../ui/components/organisms/vc-blade/vc-blade.docs.md)      | The blade UI shell component (header, toolbar, content area) |
+| [`useToolbar`](../useToolbar/useToolbar.docs.md)                             | Dynamic toolbar management for blades                        |
+| [`usePopup`](../usePopup/usePopup.docs.md)                                   | Confirmation dialogs, commonly used in close guards          |

package/runtime/knowledge/docs/core/composables/useBladeWidgets/index.docs.md

@@ -24,34 +24,54 @@ Headless widgets are defined as plain configuration objects with reactive refs f
 
 ## Basic Usage
 
-```typescript
-import { useBladeWidgets } from "@vc-shell/framework";
+In production apps, the widget array is almost never declared inline in the blade's `<script setup>`. The recommended pattern is to extract widget setup into a sibling composable (`useXxxWidgets.ts`) so the blade stays clean, the widgets are testable in isolation, and they can be reused across blades that share a domain.
 
-const { refreshAll } = useBladeWidgets([
-  {
-    id: "OffersWidget",
-    icon: "lucide-tag",
-    title: "OFFERS.TITLE",
-    badge: offersCount,
-    loading: offersLoading,
-    onClick: () => openBlade({ name: "OffersList" }),
-    onRefresh: () => reloadOffers(),
-  },
-  {
-    id: "ReviewsWidget",
-    icon: "lucide-star",
-    title: "REVIEWS.TITLE",
-    badge: reviewsCount,
-    isVisible: computed(() => !!item.value?.id),
-    onClick: () => openBlade({ name: "ReviewsList" }),
-  },
-]);
+```typescript title="modules/products/widgets/useProductWidgets.ts"
+import { useBlade, useBladeWidgets, type UseBladeWidgetsReturn } from "@vc-shell/framework";
+import type { Ref, ComputedRef } from "vue";
+import { useOfferCount } from "./useOfferCount";
+
+interface Options {
+  item: Ref<Product | undefined>;
+  isVisible: ComputedRef<boolean>;
+}
+
+export function useProductWidgets({ item, isVisible }: Options): UseBladeWidgetsReturn {
+  const { openBlade } = useBlade();
+  const { count: offersCount, loading, refresh } = useOfferCount(item);
+
+  return useBladeWidgets([
+    {
+      id: "OffersWidget",
+      icon: "lucide-tag",
+      title: "OFFERS.TITLE",
+      badge: offersCount,
+      loading,
+      isVisible,
+      onClick: () => openBlade({ name: "OffersList", options: { productId: item.value?.id } }),
+      onRefresh: refresh,
+    },
+  ]);
+}
+```
 
-// After a save, refresh all widget data
-await saveEntity();
-refreshAll();
+```vue title="modules/products/pages/product-details.vue"
+<script setup lang="ts">
+import { useProductWidgets } from "../widgets/useProductWidgets";
+
+const { item } = useProductDetails();
+const isVisible = computed(() => !!item.value?.id);
+const { refreshAll } = useProductWidgets({ item, isVisible });
+
+async function onSave() {
+  await saveProduct();
+  refreshAll();
+}
+</script>
 ```
 
+Inline `useBladeWidgets([...])` is fine for one-off widgets, but extracting becomes essential when widget data comes from API calls (which need their own composables anyway).
+
 ## API
 
 ### Parameters
@@ -119,7 +139,7 @@ A complete example of an external widget that shows an unread message count and
 **1. Register the external widget (module index.ts):**
 
 ```typescript
-import { createAppModule, registerExternalWidget, BladeDescriptor } from "@vc-shell/framework";
+import { registerExternalWidget, BladeDescriptor } from "@vc-shell/framework";
 import { markRaw } from "vue";
 import { MessageWidget } from "./components/widgets";
 
@@ -304,7 +324,7 @@ const { refreshAll } = useBladeWidgets([]);
 
 ## Related
 
-- [`defineBladeContext` / `injectBladeContext`](../bladeContext/) -- expose/consume blade data in external widgets
+- [`defineBladeContext` / `injectBladeContext`](../bladeContext/index.docs.md) -- expose/consume blade data in external widgets
 - `registerExternalWidget` -- register a component-based widget globally for target blades
 
 <!-- internal:start -->

package/runtime/knowledge/docs/core/composables/useDashboard/useDashboard.docs.md

@@ -270,6 +270,7 @@ export function registerAnalyticsDashboard() {
 ### Widget Component Template
 
 ```typescript
+// pseudo-code: replace OrderClient with your generated API client
 <!-- widgets/OrdersSummary.vue -->
 <script setup lang="ts">
 import { ref, onMounted } from "vue";

package/runtime/knowledge/docs/core/composables/useDynamicProperties/useDynamicProperties.docs.md

@@ -163,4 +163,4 @@ useDynamicProperties/
 ## Related
 
 - [useBladeForm](../useBladeForm/useBladeForm.docs.md) — form state management that uses `semanticEqual` for modification detection. `cleanEmptyValues` ensures compatibility.
-- [VcDynamicProperty](../../../../ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md) — UI component that renders dynamic properties
+- [VcDynamicProperty](../../../ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md) — UI component that renders dynamic properties

package/runtime/knowledge/docs/core/composables/useMenuExpanded/index.docs.md

@@ -76,7 +76,7 @@ const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.va
 
 ## Details
 
-- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
+- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/operations/`, the key is `VC_APP_MENU_EXPANDED_operations`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
 - **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
 - **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
 - **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.

package/runtime/knowledge/docs/core/composables/useMenuService/useMenuService.docs.md

@@ -193,6 +193,7 @@ removeRegisteredMenuItem({ routeId: "ReturnsList" } as MenuItem);
 ### Dynamic Badge Based on API Data
 
 ```typescript
+// pseudo-code: replace OrderClient with your generated API client
 <script setup lang="ts">
 import { onMounted, ref } from "vue";
 import { setMenuBadge, useApiClient } from "@vc-shell/framework";

package/runtime/knowledge/docs/core/composables/useNotifications/useNotifications.docs.md

@@ -18,22 +18,36 @@ Provides access to the push-notification system: reading notification history, f
 
 ## Quick Start
 
+In new code, prefer `useBladeNotifications` — it integrates with the blade effect scope and auto-cleans on unmount.
+
+```typescript
+import { useBladeNotifications } from "@vc-shell/framework";
+
+// Blade-scoped subscription with automatic cleanup
+const { messages, unreadCount, markAsRead } = useBladeNotifications({
+  types: ["OrderStatusChanged"],
+  filter: (msg) => msg.orderId === currentOrderId.value,
+  onMessage: () => refreshOrderList(),
+});
+```
+
+Use `useNotifications` (this composable) only in legacy code or when you need to subscribe outside a blade scope:
+
 ```typescript
 import { useNotifications } from "@vc-shell/framework";
 
-// Subscribe to specific notification types
-const { notifications, moduleNotifications, loadFromHistory, markAsRead, markAllAsRead, setNotificationHandler } = useNotifications("OrderStatusChanged");
+// Legacy: type-filtered subscription with manual lifecycle
+const { notifications, setNotificationHandler, loadFromHistory } = useNotifications("OrderStatusChanged");
 
-// Register a handler for real-time notifications
 setNotificationHandler((notification) => {
-  console.log("Order status changed:", notification);
   refreshOrderList();
 });
 
-// Load historical notifications on mount
 onMounted(() => loadFromHistory(50));
 ```
 
+For the canonical blade-side example and the registration of notification types at module load, see the [Notifications system reference](../../notifications/notifications.docs.md).
+
 ## API
 
 ### Parameters
@@ -155,6 +169,6 @@ onMounted(refreshInventory);
 
 ## Related
 
-- [useBladeNotifications](../useBladeNotifications/) -- preferred replacement with blade lifecycle integration
+- [Notification system reference](../../notifications/notifications.docs.md) -- includes the recommended `useBladeNotifications` composable with blade lifecycle integration
 - `useNotificationStore()` -- direct Pinia-based store access for full control
 - `MIGRATION_GUIDE.md#notifications` -- migration guide from useNotifications to useBladeNotifications

package/runtime/knowledge/docs/core/composables/usePermissions/usePermissions.docs.md

@@ -38,6 +38,7 @@ The `hasAccess` function evaluates permissions from the current user object (loa
 | Input                            | Result                                                              |
 | -------------------------------- | ------------------------------------------------------------------- |
 | `undefined`                      | `true` -- no permission required, everyone has access               |
+| `[]` (empty array)               | `true` -- empty array means no restriction, same as `undefined`     |
 | `"order:read"`                   | `true` if the user has this exact permission string                 |
 | `["order:read", "order:update"]` | `true` if the user has **any** of the listed permissions (OR logic) |
 | Any value, administrator user    | Always `true` -- administrators bypass all checks                   |
@@ -279,7 +280,7 @@ if (hasAccess("order:delete")) {
 - Permissions are read from `useUserManagement().user.value.permissions` at composable initialization.
 - If `user.value.isAdministrator` is `true`, `hasAccess` always returns `true` regardless of the input.
 - An array input uses OR logic: the user needs at least one of the listed permissions.
-- Passing `undefined` returns `true`, allowing unrestricted access by default.
+- Passing `undefined` or an empty array (`[]`) returns `true`, allowing unrestricted access by default.
 
 ## Related
 

package/runtime/knowledge/docs/core/composables/useSettings/useSettings.docs.md

@@ -94,8 +94,8 @@ const { applySettings } = useSettings();
 
 // Override default platform settings with module-specific branding
 applySettings({
-  logo: "/modules/vendor-portal/logo.svg",
-  title: "Vendor Portal",
+  logo: "/modules/operations-console/logo.svg",
+  title: "Operations Console",
 });
 </script>
 ```