@vc-shell/vc-app-skill 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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.9.0
+2.10.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit fd1e671ba on 2026-11-02T09:58:34.572Z
+Synced from framework at commit 413c13a36 on 2026-11-02T10:54:29.692Z

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

@@ -101,13 +101,13 @@ defineBladeContext(
 
 ## Recipe: Consumers Registered from Another Module
 
-Toolbar buttons and headless widgets registered by blade name from another module are plain objects, so `injectBladeContext()` has no component to run in. The framework hands them the context instead:
+Toolbar buttons and headless widgets registered by blade name from another module are plain objects, so `injectBladeContext()` has no component to run in. The framework calls their function forms with two arguments instead: `(blade, ctx)`, the descriptor of the blade the button or widget sits on and its context. The blade comes first because `isVisible: (blade) => …` has worked that way since 1.1.37.
 
-| Registration                                          | Receives the context                                                              |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `registerExternalToolbarItem` / `registerToolbarItem` | `clickHandler(ctx)`, `disabled: (ctx) => …`, `isVisible: (blade, ctx) => …`       |
-| `registerExternalWidget` / `registerWidget`           | `isVisible: (blade, ctx) => …`; the component itself calls `injectBladeContext()` |
-| `registerWidget` with `headless`                      | `headless.onClick(ctx)`, `headless.disabled: (ctx) => …`                          |
+| Registration                                          | Called with `(blade, ctx)`                                     |
+| ----------------------------------------------------- | -------------------------------------------------------------- |
+| `registerExternalToolbarItem` / `registerToolbarItem` | `clickHandler`, `disabled`, `isVisible`                        |
+| `registerExternalWidget` / `registerWidget`           | `isVisible`; the component itself calls `injectBladeContext()` |
+| `registerWidget` with `headless`                      | `headless.onClick`, `headless.disabled`                        |
 
 ```typescript
 // In the blade
@@ -118,13 +118,24 @@ registerExternalToolbarItem({
   id: "bulk-export",
   title: "Export selected",
   targetBlades: ["Products"],
-  disabled: (ctx) => !(ctx.selectedItems as Product[] | undefined)?.length,
-  clickHandler: (ctx) => exportProducts(ctx?.selectedItems as Product[]),
+  disabled: (_blade, ctx) => !(ctx.selectedItems as Product[] | undefined)?.length,
+  clickHandler: (_blade, ctx) => exportProducts(ctx.selectedItems as Product[]),
 });
 ```
 
 The values are the same unwrapped snapshot `injectBladeContext()` returns, and the state is reactive: `disabled` and `isVisible` follow the blade's refs. A blade without `defineBladeContext` gives these handlers `{}`, not an error.
 
+`ctx` does not say which blade it came from. When one registration targets several blades, tell them apart by `blade.name`:
+
+```typescript
+registerExternalToolbarItem({
+  id: "bulk-export",
+  targetBlades: ["Products", "Offers"],
+  disabled: (_blade, ctx) => !(ctx.selectedItems as unknown[] | undefined)?.length,
+  clickHandler: (blade, ctx) => (blade?.name === "Offers" ? exportOffers(ctx.selectedItems as Offer[]) : exportProducts(ctx.selectedItems as Product[])),
+});
+```
+
 ## Details
 
 - **Automatic ref unwrapping**: `defineBladeContext` shallow-unwraps all ref/computed values in the provided object. Consumers get plain values directly (`ctx.value.item` instead of `ctx.value.item.value`). This works reactively — when the source ref changes, the context updates automatically.

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

@@ -199,7 +199,7 @@ The name match is case-insensitive. If the blade registers its own item with the
 
 ### Reading the blade's data
 
-A button registered from outside cannot call `injectBladeContext()`: its handlers run outside the blade's component tree. The framework passes them the data the blade exposed with [`defineBladeContext`](../bladeContext/) instead. `clickHandler` receives it, and so do the function forms of `disabled` and `isVisible`:
+A button registered from outside cannot call `injectBladeContext()`: its handlers run outside the blade's component tree. The framework calls `clickHandler` and the function forms of `disabled` and `isVisible` with `(blade, ctx)`: the descriptor of the blade the button sits on, and the data it exposed with [`defineBladeContext`](../bladeContext/).
 
 ```typescript
 // In the target blade
@@ -211,12 +211,22 @@ registerExternalToolbarItem({
   title: "Export selected",
   icon: "lucide-download",
   targetBlades: ["Products"],
-  disabled: (ctx) => !(ctx.selectedItems as Product[] | undefined)?.length,
-  clickHandler: (ctx) => exportProducts(ctx?.selectedItems as Product[]),
+  disabled: (_blade, ctx) => !(ctx.selectedItems as Product[] | undefined)?.length,
+  clickHandler: (_blade, ctx) => exportProducts(ctx.selectedItems as Product[]),
 });
 ```
 
-Refs are already unwrapped, and the state follows the blade: the button enables as soon as the user selects a row. A keyboard `shortcut` on the item gets the same context. When the blade defines no context, the handlers get `{}`.
+Refs are already unwrapped, and the state follows the blade: the button enables as soon as the user selects a row. A keyboard `shortcut` on the item gets the same arguments. When the blade defines no context, `ctx` is `{}`.
+
+`ctx` does not say which blade it came from. With several `targetBlades`, branch on `blade.name`:
+
+```typescript
+registerExternalToolbarItem({
+  id: "bulk-export",
+  targetBlades: ["Products", "Offers"],
+  clickHandler: (blade, ctx) => (blade?.name === "Offers" ? exportOffers(ctx.selectedItems as Offer[]) : exportProducts(ctx.selectedItems as Product[])),
+});
+```
 
 ## Auto-cleanup control
 
@@ -404,9 +414,9 @@ function helperFunction() {
 | `id`           | `string`                                                                                                                  | Yes      | Unique identifier for the button                                                                                            |
 | `title`        | `string \| Ref<string> \| ComputedRef<string>`                                                                            | No       | Button label (supports reactive values)                                                                                     |
 | `icon`         | `string \| (() => string)`                                                                                                | No       | Icon class (e.g., `"fas fa-save"`) or a function returning one                                                              |
-| `clickHandler` | `(context?: BladeContext) => void`                                                                                        | No       | Click callback; receives the blade context                                                                                  |
-| `disabled`     | `boolean \| ComputedRef<boolean \| undefined> \| ((context: BladeContext) => boolean \| undefined)`                       | No       | Whether the button is disabled; a function receives the blade context                                                       |
-| `isVisible`    | `boolean \| Ref<boolean \| undefined> \| ComputedRef<boolean \| undefined> \| ((blade, context) => boolean \| undefined)` | No       | Controls button visibility; a function receives the blade descriptor and the blade context                                  |
+| `clickHandler` | `(blade, context) => void`                                                                                                | No       | Click callback; receives the blade and its context                                                                          |
+| `disabled`     | `boolean \| ComputedRef<boolean \| undefined> \| ((blade, context) => boolean \| undefined)`                              | No       | Whether the button is disabled; a function receives the blade and its context                                               |
+| `isVisible`    | `boolean \| Ref<boolean \| undefined> \| ComputedRef<boolean \| undefined> \| ((blade, context) => boolean \| undefined)` | No       | Controls button visibility; a function receives the blade and its context                                                   |
 | `priority`     | `number`                                                                                                                  | No       | Sort order (higher = displayed first, default `0`)                                                                          |
 | `separator`    | `"left" \| "right" \| "both"`                                                                                             | No       | Adds a visual divider next to the button                                                                                    |
 | `permissions`  | `string \| string[]`                                                                                                      | No       | Required permission(s) to display the button                                                                                |

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

@@ -118,7 +118,7 @@ export default {
 };
 ```
 
-The widget component reads the blade's data with [`injectBladeContext()`](../bladeContext/), since it renders inside the blade. `isVisible` runs before the component exists, so a function form receives the blade context as its second argument:
+The widget component reads the blade's data with [`injectBladeContext()`](../bladeContext/), since it renders inside the blade. `isVisible` runs before the component exists, so a function form receives `(blade, ctx)`: the blade descriptor and the blade context.
 
 ```typescript
 registerExternalWidget({
@@ -126,11 +126,11 @@ registerExternalWidget({
   targetBlades: ["OrderDetails"],
   component: markRaw(ShippingTracker),
   // the blade calls defineBladeContext({ item })
-  isVisible: (blade, ctx) => (ctx.item as Order | undefined)?.status === "Shipped",
+  isVisible: (_blade, ctx) => (ctx.item as Order | undefined)?.status === "Shipped",
 });
 ```
 
-A headless widget registered by blade name has no component to inject from, so its `onClick` and a function `disabled` receive the context too:
+A headless widget registered by blade name has no component to inject from, so its `onClick` and a function `disabled` receive `(blade, ctx)` too:
 
 ```typescript
 registerWidget(
@@ -139,8 +139,8 @@ registerWidget(
     title: "Invoice",
     headless: {
       icon: "lucide-receipt",
-      disabled: (ctx) => !ctx.item,
-      onClick: (ctx) => openInvoice((ctx?.item as Order).id),
+      disabled: (_blade, ctx) => !ctx.item,
+      onClick: (_blade, ctx) => openInvoice((ctx.item as Order).id),
     },
   },
   "OrderDetails",

package/runtime/knowledge/docs/ui/components/organisms/vc-blade/vc-blade.docs.md

@@ -359,9 +359,10 @@ interface IBladeToolbar {
   id?: string;
   title?: string | Ref<string> | ComputedRef<string>;
   icon?: string | (() => string);
-  clickHandler?(app?: Record<string, any> | null): void;
-  disabled?: boolean | ComputedRef<boolean | undefined>;
-  isVisible?: boolean | Ref<boolean | undefined> | ComputedRef<boolean | undefined> | ((blade?: BladeDescriptor) => boolean | undefined);
+  // function forms get (blade, context): the blade descriptor and the blade context
+  clickHandler?(blade: BladeDescriptor | undefined, context: BladeContext): void;
+  disabled?: boolean | ComputedRef<boolean | undefined> | ((blade: BladeDescriptor | undefined, context: BladeContext) => boolean | undefined);
+  isVisible?: boolean | Ref<boolean | undefined> | ComputedRef<boolean | undefined> | ((blade: BladeDescriptor | undefined, context: BladeContext) => boolean | undefined);
   separator?: "left" | "right" | "both";
   permissions?: string | string[];
 }