@vc-shell/vc-app-skill 2.0.0-alpha.24 → 2.0.0-alpha.25

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# [2.0.0-alpha.25](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.24...v2.0.0-alpha.25) (2026-03-25)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
 # [2.0.0-alpha.24](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.23...v2.0.0-alpha.24) (2026-03-25)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.24",
+  "version": "2.0.0-alpha.25",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.0.0-alpha.24
+2.0.0-alpha.25

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit c001cdf1a on 2026-03-25T10:46:45.153Z
+Synced from framework at commit 99a2f022b on 2026-03-25T11:57:14.169Z

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

@@ -1,15 +1,19 @@
-# useBladeWidgets
+# useBladeWidgets / useWidgetTrigger
 
-Declarative headless widget registration for blades. Widgets are automatically registered with the WidgetService on mount and cleaned up on unmount, following the Vue component lifecycle. This composable is the recommended way to add sidebar counter widgets, action buttons, and status indicators to a blade without creating separate Vue component files for each widget.
+Two composables for the widget system — one for the **blade side**, one for the **widget side**.
 
-Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. The WidgetService renders them in the blade sidebar.
+| Composable | Called from | Purpose |
+|---|---|---|
+| `useBladeWidgets` | Blade component | Register headless widgets + get `refresh()` / `refreshAll()` |
+| `useWidgetTrigger` | External widget component | Register trigger callbacks (`onRefresh`, `onClick`) via provide/inject |
+
+Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. External component-based widgets use `useWidgetTrigger` to register their refresh callbacks so the hosting blade can trigger them.
 
 ## When to Use
 
-- Register sidebar widgets (counters, action buttons) for a blade without creating Vue components
-- Refresh widget data programmatically after blade operations (save, delete, status change)
-- Show/hide widgets conditionally based on blade state (e.g., only show after entity is saved)
-- When NOT to use: for widgets that need their own template or complex UI (use a full widget component instead)
+- **`useBladeWidgets`**: Register sidebar widgets (counters, action buttons) for a blade without creating Vue components. Refresh widget data after blade operations (save, delete).
+- **`useWidgetTrigger`**: Inside an external widget component (registered via `registerExternalWidget`) to register `onRefresh` / `onClick` callbacks. The blade can then call `refresh(widgetId)` or `refreshAll()` to trigger them.
+- When NOT to use `useBladeWidgets`: for widgets that need their own template or complex UI (use `registerExternalWidget` + `useWidgetTrigger` instead).
 
 ## Basic Usage
 
@@ -70,6 +74,121 @@ refreshAll();
 | `refresh` | `(widgetId: string) => void` | Trigger `onRefresh` on a specific widget |
 | `refreshAll` | `() => void` | Trigger `onRefresh` on all widgets that have one |
 
+## useWidgetTrigger
+
+Widget-side composable for external component-based widgets. Registers a trigger contract (`onRefresh`, `onClick`, `badge`) via provide/inject — no props, IDs, or service knowledge required.
+
+### Basic Usage
+
+```typescript
+import { useWidgetTrigger } from '@vc-shell/framework';
+
+// Inside an external widget component:
+useWidgetTrigger({ onRefresh: loadData });
+```
+
+### IWidgetTrigger
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `string` | No | Lucide icon name for dropdown rendering |
+| `title` | `string` | No | Display title (fallback: widget's title) |
+| `badge` | `Ref<number \| string>` | No | Reactive badge value |
+| `onClick` | `() => void` | No | Handler called when widget is clicked in dropdown |
+| `onRefresh` | `() => void \| Promise<void>` | No | Handler called to refresh widget data |
+| `disabled` | `Ref<boolean> \| boolean` | No | Disabled state |
+
+### How It Works
+
+1. `WidgetContainer` wraps each component-based widget in a `WidgetScope` provider
+2. `WidgetScope` provides a `setTrigger` function scoped to the specific widget ID and blade ID
+3. `useWidgetTrigger` injects this scope and calls `setTrigger` — no props or IDs needed
+4. When the blade calls `refresh(widgetId)` or `refreshAll()`, the registered `onRefresh` is invoked
+
+## Recipe: External Widget with Refresh
+
+A complete example of an external widget that shows an unread message count and supports refresh from the blade:
+
+**1. Register the external widget (module index.ts):**
+
+```typescript
+import { createAppModule, registerExternalWidget, IBladeInstance } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { MessageWidget } from "./components/widgets";
+
+registerExternalWidget({
+  id: "MessageWidget",
+  component: markRaw(MessageWidget),
+  targetBlades: ["ProductDetails", "OrderDetails"],
+  isVisible: (blade?: IBladeInstance) => !!blade?.param,
+});
+```
+
+**2. Widget component (message-widget.vue):**
+
+```vue
+<template>
+  <VcWidget
+    v-loading:500="loading"
+    :title="$t('MESSENGER.WIDGET.TITLE')"
+    icon="lucide-message-circle"
+    :value="messageCount"
+    @click="openMessageBlade"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted } from "vue";
+import {
+  loading as vLoading,
+  useBlade,
+  injectBladeContext,
+  useWidgetTrigger,
+  VcWidget,
+} from "@vc-shell/framework";
+
+const ctx = injectBladeContext();
+const entityId = computed(() => (ctx.value.item as { id?: string })?.id ?? "");
+
+const messageCount = ref(0);
+const loading = ref(false);
+
+const loadData = async () => {
+  loading.value = true;
+  try {
+    messageCount.value = await api.getUnreadCount(entityId.value);
+  } finally {
+    loading.value = false;
+  }
+};
+
+// Register refresh callback — blade can call refreshAll() after save
+useWidgetTrigger({ onRefresh: loadData });
+
+onMounted(() => {
+  if (entityId.value) loadData();
+});
+</script>
+```
+
+**3. Blade refreshes widgets after save:**
+
+```vue
+<script setup lang="ts">
+import { useBladeWidgets } from "@vc-shell/framework";
+
+// Empty array — blade doesn't register headless widgets,
+// but gets refresh/refreshAll for external widgets
+const { refresh, refreshAll } = useBladeWidgets([]);
+
+async function save() {
+  await api.saveProduct(product.value);
+  refreshAll();           // refresh all widgets (including MessageWidget)
+  // or: refresh("MessageWidget");  // refresh a specific widget by ID
+}
+</script>
+```
+
 ## Recipe: Product Detail Blade with Multiple Widgets
 
 ```vue
@@ -126,10 +245,15 @@ async function save() {
 
 ## Prerequisites
 
+**`useBladeWidgets`**:
 - Must be called inside a blade component rendered by `VcBladeSlot` (requires `BladeDescriptorKey` injection).
 - `WidgetService` must be provided in the component tree (automatically available in vc-shell apps).
 - Calling outside a blade context throws an error with a descriptive message.
 
+**`useWidgetTrigger`**:
+- Must be called inside a widget component rendered by `WidgetContainer` (requires `WidgetScopeKey` injection).
+- If called outside a widget scope, logs a warning and does nothing (does not throw).
+
 ## Details
 
 - **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the WidgetService always reflects the currently visible blades.
@@ -143,8 +267,39 @@ async function save() {
 - Keep widget IDs unique within a blade. Duplicate IDs will overwrite previous registrations.
 - Combine with `defineBladeContext` to expose blade entity data that widget components (non-headless) can consume via `injectBladeContext`.
 
+## Common Mistakes
+
+### Calling useWidgetTrigger outside WidgetContainer scope
+
+```typescript
+// Wrong — called in a standalone component, not rendered inside a blade widget slot
+export default defineComponent({
+  setup() {
+    useWidgetTrigger({ onRefresh: loadData }); // ⚠️ Logs warning, trigger not registered
+  },
+});
+```
+
+```typescript
+// Correct — called inside a widget component registered via registerExternalWidget
+// and rendered by WidgetContainer within a blade
+useWidgetTrigger({ onRefresh: loadData }); // ✓ WidgetScope provides context
+```
+
+### Forgetting to pass empty array to useBladeWidgets for refresh-only usage
+
+```typescript
+// Wrong — useBladeWidgets requires an array argument
+const { refreshAll } = useBladeWidgets(); // TS error
+
+// Correct — pass empty array when you only need refresh/refreshAll
+const { refreshAll } = useBladeWidgets([]);
+```
+
 ## Related
 
-- `defineBladeContext` -- expose blade data to widgets
-- `WidgetService` in `@core/services/widget-service`
+- `defineBladeContext` / `injectBladeContext` -- expose/consume blade data in external widgets
+- `registerExternalWidget` -- register a component-based widget globally for target blades
+- `WidgetService` in `@core/services/widget-service` -- underlying service
+- `WidgetScope` in `vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
 - `VcBladeSlot` -- the blade wrapper that provides `BladeDescriptorKey`

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

@@ -9,7 +9,7 @@ Also exports `provideWidgetService()` for framework-level initialization and `re
 - When you need low-level access to the widget service (register, unregister, query widgets)
 - When building framework infrastructure that manages widget lifecycles
 - When pre-registering widgets from a module's `install()` function before the component tree exists
-- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use `useWidget()`.
+- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use headless widgets.
 
 ## Quick Start
 
@@ -46,7 +46,7 @@ None.
 | `setActiveWidget` | `(args) => void` | Sets a widget as active with its exposed instance. |
 | `updateActiveWidget` | `() => void` | Triggers the active widget's update function. Deprecated -- use headless widgets instead. |
 | `isWidgetRegistered` | `(id: string) => boolean` | Checks if a widget ID exists in any blade's registry. |
-| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). Used by `useWidget().setTrigger()`. |
+| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). |
 | `resolveWidgetProps` | `(widget, bladeData) => Record<string, unknown>` | Resolves widget props from blade data. Deprecated. |
 | `getExternalWidgetsForBlade` | `(bladeId: string) => IExternalWidgetRegistration[]` | Gets external widgets that target a specific blade (registered by other modules). |
 | `getAllExternalWidgets` | `() => IExternalWidgetRegistration[]` | Gets all registered external widgets across all modules. |

package/runtime/knowledge/docs/injection-keys.docs.md

@@ -62,7 +62,7 @@ This centralized approach has several advantages:
 
 | Key | Type | Description |
 |-----|------|-------------|
-| `WidgetIdKey` | `string` | Widget identity (provided by WidgetProvider) |
+| `WidgetScopeKey` | `IWidgetScope` | Widget scope (provided by WidgetContainer for component-based widgets via `WidgetScope.vue`) |
 | `AppRootElementKey` | `Ref<HTMLElement \| undefined>` | App root element for scoped Teleport |
 | `EmbeddedModeKey` | `boolean` | Whether the app runs in embedded mode |
 | `ShellIndicatorsKey` | `ComputedRef<boolean>` | Unread indicator state for sidebar |

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

@@ -1,159 +0,0 @@
-# useWidget
-
-Widget-side composable that auto-discovers widget identity from `WidgetProvider` and provides a `setTrigger()` method to register refresh/badge contracts with the widget service. This composable is the counterpart to the blade-side `useWidgets()` / `useBladeWidgets()` -- while those manage widget registration from the blade's perspective, `useWidget()` is called from inside the widget component itself to communicate its state (badge count, icon, refresh callback) back to the widget system.
-
-**Deprecated**: Prefer headless widgets via `useBladeWidgets()` instead. This composable is only needed for legacy SFC widgets that register trigger contracts manually.
-
-## When to Use
-
-- Inside a widget component wrapped by `WidgetProvider` to register badge counts, refresh callbacks, or click handlers
-- When building a custom blade widget that needs to communicate its state back to the parent blade's widget panel
-- When NOT to use: outside a `WidgetProvider` context (will throw). For managing widgets from the blade side, use `useWidgets()` or `useBladeWidgets()` instead. For new widgets, prefer the headless widget pattern.
-
-## Quick Start
-
-```vue
-<script setup lang="ts">
-import { useWidget } from '@vc-shell/framework';
-import { ref, computed, onMounted } from 'vue';
-
-const { widgetId, setTrigger } = useWidget();
-
-const items = ref<unknown[]>([]);
-const unreadCount = computed(() => items.value.filter((i) => !i.isRead).length);
-
-async function fetchData() {
-  items.value = await api.getWidgetItems();
-}
-
-// Register the trigger contract: badge + refresh callback
-setTrigger({
-  badge: unreadCount,
-  icon: 'fas fa-inbox',
-  title: 'Messages',
-});
-
-onMounted(fetchData);
-</script>
-
-<template>
-  <div class="tw-p-4">
-    <p class="tw-text-sm tw-text-gray-500">Widget ID: {{ widgetId }}</p>
-    <ul>
-      <li v-for="item in items" :key="item.id">{{ item.title }}</li>
-    </ul>
-  </div>
-</template>
-```
-
-## API
-
-### Parameters
-
-None. Identity is auto-discovered from the `WidgetProvider` injection context. The composable injects `WidgetIdKey` for the widget ID, `WidgetServiceKey` for the service, and `BladeDescriptorKey` for the parent blade context.
-
-### Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `widgetId` | `string` | The widget's unique ID, injected by `WidgetProvider`. |
-| `setTrigger` | `(trigger: IWidgetTrigger) => void` | Registers a trigger contract (badge, icon, title, callbacks) for this widget. Can be called multiple times to update the trigger. |
-
-### IWidgetTrigger
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `icon` | `string?` | Lucide or FontAwesome icon name for the widget's display in the dropdown/panel. |
-| `title` | `string?` | Display title for the widget. Falls back to `IWidget.title` if not set. |
-| `badge` | `Ref<number \| string> \| ComputedRef<number \| string>?` | Reactive badge value displayed on the widget button/tab. Pass a computed ref for automatic updates. |
-
-## How It Works
-
-1. **Identity discovery**: On creation, the composable injects `WidgetIdKey` (provided by `WidgetProvider`) and `WidgetServiceKey` (provided by `provideWidgetService()`). It also injects `BladeDescriptorKey` to know which blade this widget belongs to.
-
-2. **Trigger registration**: When you call `setTrigger(trigger)`, the composable calls `widgetService.updateWidget({ id: widgetId, bladeId, widget: { trigger } })`. This stores the trigger contract in the widget service, where the blade's widget panel can read it.
-
-3. **Reactive badges**: Because `badge` accepts a `Ref` or `ComputedRef`, the widget panel automatically updates whenever the badge value changes. There is no need to call `setTrigger` again after the initial registration.
-
-## Recipe: Widget with Live Badge Count
-
-```vue
-<script setup lang="ts">
-import { useWidget } from '@vc-shell/framework';
-import { ref, computed, onMounted } from 'vue';
-
-const { setTrigger } = useWidget();
-const pendingOrders = ref<Order[]>([]);
-
-async function loadPendingOrders() {
-  pendingOrders.value = await orderApi.getPending();
-}
-
-// Badge shows the count of pending orders
-setTrigger({
-  badge: computed(() => pendingOrders.value.length),
-  icon: 'fas fa-clock',
-  title: 'Pending Orders',
-});
-
-onMounted(loadPendingOrders);
-
-// Optionally refresh periodically
-const interval = setInterval(loadPendingOrders, 30_000);
-onUnmounted(() => clearInterval(interval));
-</script>
-
-<template>
-  <div class="tw-space-y-2">
-    <div v-for="order in pendingOrders" :key="order.id" class="tw-p-2 tw-border tw-rounded">
-      <p class="tw-font-medium">{{ order.number }}</p>
-      <p class="tw-text-sm tw-text-gray-500">{{ order.status }}</p>
-    </div>
-    <p v-if="!pendingOrders.length" class="tw-text-gray-400">No pending orders</p>
-  </div>
-</template>
-```
-
-## Recipe: Widget That Updates on Blade Data Change
-
-```vue
-<script setup lang="ts">
-import { useWidget } from '@vc-shell/framework';
-import { inject, watch, ref, computed } from 'vue';
-
-const { setTrigger } = useWidget();
-
-// Inject blade data from parent
-const bladeData = inject('bladeData') as Ref<{ orderId: string }>;
-const comments = ref<Comment[]>([]);
-
-async function loadComments(orderId: string) {
-  comments.value = await commentApi.getByOrder(orderId);
-}
-
-// Reload when blade data changes
-watch(() => bladeData.value.orderId, (id) => {
-  if (id) loadComments(id);
-}, { immediate: true });
-
-setTrigger({
-  badge: computed(() => comments.value.length),
-  icon: 'fas fa-comments',
-  title: 'Comments',
-});
-</script>
-```
-
-## Tips
-
-- **Must be inside `WidgetProvider`.** This composable relies on `WidgetIdKey` being injected by `WidgetProvider`. If called outside that context, it throws an `InjectionError`. The `WidgetProvider` component is automatically rendered by the blade widget system.
-- **`setTrigger` can be called multiple times.** Each call replaces the previous trigger contract. However, since `badge` is reactive, you typically only need to call `setTrigger` once during setup.
-- **Badge accepts both numbers and strings.** You can use `computed(() => 3)` for a numeric badge or `computed(() => '!')` for a text indicator.
-- **Prefer headless widgets for new code.** The `useBladeWidgets()` composable supports a headless pattern where widgets are defined declaratively without a separate SFC. This is simpler and avoids the WidgetProvider ceremony.
-
-## Related
-
-- [useWidgets](../useWidgets/useWidgets.docs.md) -- blade-level widget service access
-- [useBladeWidgets](../useBladeWidgets/) -- lifecycle-managed widget registration for blades (preferred API for new code)
-- `WidgetProvider` -- the component that provides the `WidgetIdKey` injection
-- `framework/injection-keys.ts` -- defines `WidgetIdKey` and `WidgetServiceKey`