@vc-shell/vc-app-skill 2.0.0-alpha.28 → 2.0.0-alpha.29

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.28",
+  "version": "2.0.0-alpha.29",
   "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.28
+2.0.0-alpha.29

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 8bc5a83cc on 2026-03-26T07:20:52.461Z
+Synced from framework at commit d863d7620 on 2026-03-26T14:29:54.970Z

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

@@ -17,7 +17,7 @@ The pattern follows a "define once, inject anywhere" approach: the blade compone
 // In a blade's <script setup>
 import { defineBladeContext, injectBladeContext } from '@vc-shell/framework';
 
-// Provide context (blade component)
+// Provide context — refs/computeds are auto-unwrapped for consumers
 defineBladeContext({ item, disabled, loading });
 
 // Or with a computed for selective exposure
@@ -29,7 +29,9 @@ defineBladeContext(computed(() => ({ id: item.value?.id })));
 import { injectBladeContext } from '@vc-shell/framework';
 
 const ctx = injectBladeContext();
+// Refs are already unwrapped — access values directly, no .value needed
 const entityId = computed(() => ctx.value.id as string);
+const item = computed(() => ctx.value.item as { id: string; name: string });
 ```
 
 ## API
@@ -90,6 +92,7 @@ defineBladeContext(computed(() => ({
 
 ## 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.
 - **Reactivity**: The provided context is always wrapped in a `computed`, so consumers receive a `ComputedRef` regardless of whether the provider passed a plain object, a ref, or a getter. Changes propagate automatically.
 - **Injection key**: Uses `BladeContextKey` from `framework/injection-keys.ts`. This is a framework-level Symbol, so there is no risk of key collision with application code.
 - **Error handling**: `injectBladeContext` throws an `InjectionError` with a descriptive message if called outside a blade component tree. This fails fast during development rather than silently returning `undefined`.

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

@@ -112,7 +112,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, IBladeInstance } from "@vc-shell/framework";
+import { createAppModule, registerExternalWidget, BladeDescriptor } from "@vc-shell/framework";
 import { markRaw } from "vue";
 import { MessageWidget } from "./components/widgets";
 
@@ -120,7 +120,7 @@ registerExternalWidget({
   id: "MessageWidget",
   component: markRaw(MessageWidget),
   targetBlades: ["ProductDetails", "OrderDetails"],
-  isVisible: (blade?: IBladeInstance) => !!blade?.param,
+  isVisible: (blade?: BladeDescriptor) => !!blade?.param,
 });
 ```
 

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

@@ -21,7 +21,7 @@ This centralized approach has several advantages:
 | Key | Type | Description |
 |-----|------|-------------|
 | `NavigationViewLocationKey` | `BladeVNode` | Current blade VNode location in navigation |
-| `BladeInstanceKey` | `ComputedRef<IBladeInstance>` | Current blade instance metadata |
+| `BladeDescriptorKey` | `ComputedRef<BladeDescriptor>` | Current blade descriptor metadata |
 | `BladeBackButtonKey` | `Component \| undefined` | Custom back button component for a blade |
 | `BladeDataKey` | *(from blade-navigation types)* | Data passed between parent/child blades |
 | `BladeContextKey` | `ComputedRef<Record<string, unknown>>` | Blade-exposed context for widgets/extensions |
@@ -83,7 +83,7 @@ This centralized approach has several advantages:
 | Deprecated | Use Instead |
 |------------|-------------|
 | `navigationViewLocation` | `NavigationViewLocationKey` |
-| `BladeInstance` | `BladeInstanceKey` |
+| `BladeDescriptor` | `BladeDescriptorKey` |
 | `NotificationTemplatesSymbol` | `NotificationTemplatesKey` |
 | `BLADE_BACK_BUTTON` | `BladeBackButtonKey` |
 | `TOOLBAR_SERVICE` | `ToolbarServiceKey` |

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

@@ -355,7 +355,7 @@ interface IBladeToolbar {
   clickHandler?(): void;
   disabled?: boolean | ComputedRef<boolean>;
   isVisible?: boolean | Ref<boolean> | ComputedRef<boolean>
-             | ((blade?: IBladeInstance) => boolean);
+             | ((blade?: BladeDescriptor) => boolean);
   separator?: "left" | "right" | "both";
 }
 ```

package/runtime/knowledge/docs/shell/_internal/popup/popup-handler.docs.md

@@ -1,135 +0,0 @@
-# PopupHandler
-
-A global popup management system that renders modal dialogs on demand. Installed as a Vue plugin (`VcPopupHandler`), it provides the `usePopup` composable for programmatic popup control. Popups are rendered in a dedicated container at the app root level, ensuring they overlay all other content including blades and sidebars.
-
-The system supports both built-in dialog types (confirmation, error, info) and fully custom popup components with typed props and emits.
-
-## When to Use
-
-- To show confirmation dialogs before destructive actions (delete, discard, bulk operations)
-- To display error or info messages in a modal overlay
-- To open custom popup components with typed props and emits
-- Do NOT use for passive feedback (use `notification()` toast instead)
-- Do NOT use for navigation (use blade navigation instead)
-
-## Basic Usage
-
-```ts
-import { usePopup } from "@vc-shell/framework";
-
-const { showConfirmation, showError, showInfo } = usePopup();
-
-// Confirmation dialog (returns Promise<boolean>)
-const confirmed = await showConfirmation("Delete this item?");
-
-// Error popup
-showError("Something went wrong.");
-
-// Info popup
-showInfo("Operation completed successfully.");
-```
-
-### Custom Popup Component
-
-```ts
-import { usePopup } from "@vc-shell/framework";
-import MyDialog from "./MyDialog.vue";
-
-const { open, close } = usePopup({
-  component: MyDialog,
-  props: { title: "Custom Dialog" },
-  emits: { onConfirm: () => close() },
-});
-
-open();
-```
-
-## API (`usePopup`)
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `open` | `() => void` | Push the popup onto the stack and render it |
-| `close` | `() => void` | Remove the popup from the stack |
-| `showConfirmation` | `(message: string \| Ref<string>) => Promise<boolean>` | Warning dialog with confirm/cancel |
-| `showError` | `(message: string \| Ref<string>) => void` | Error-styled popup |
-| `showInfo` | `(message: string \| Ref<string>) => void` | Info-styled popup |
-
-## Recipe: Delete Confirmation Before API Call
-
-The most common popup pattern is asking for confirmation before a destructive action:
-
-```vue
-<script setup lang="ts">
-import { usePopup, notification } from "@vc-shell/framework";
-
-const { showConfirmation } = usePopup();
-
-async function deleteProduct(id: string) {
-  const confirmed = await showConfirmation(
-    "Are you sure you want to delete this product? This action cannot be undone."
-  );
-
-  if (!confirmed) return;
-
-  try {
-    await api.deleteProduct(id);
-    notification("Product deleted.", { type: "success" });
-    closeSelf();
-  } catch (error) {
-    showError(error.message || "Failed to delete product.");
-  }
-}
-</script>
-```
-
-## Recipe: Custom Popup with Form
-
-Create a custom popup component for complex interactions:
-
-```ts
-// Using a custom popup component
-import { usePopup } from "@vc-shell/framework";
-import AddNotePopup from "./AddNotePopup.vue";
-
-const { open, close } = usePopup({
-  component: AddNotePopup,
-  props: { entityId: "prod-1" },
-  emits: {
-    onConfirm: async (note: string) => {
-      await api.addNote(entityId, note);
-      close();
-      notification("Note added.", { type: "success" });
-    },
-    onCancel: () => close(),
-  },
-});
-
-open();
-```
-
-## Key Parts
-
-| Export | Description |
-|--------|-------------|
-| `VcPopupHandler` | Vue plugin that installs the popup registry |
-| `VcPopupContainer` | Renders all active popups (placed once in the app root) |
-| `usePopup` | Composable for opening/closing popups |
-
-## Details
-
-- **Popup stack**: Multiple popups can be open simultaneously, stacking with the most recent on top.
-- **Promise-based confirmation**: `showConfirmation` returns a `Promise<boolean>` that resolves to `true` on confirm, `false` on cancel.
-- **Plugin requirement**: `VcPopupHandler` must be installed as a Vue plugin, and `VcPopupContainer` must be mounted in the component tree. Both are automatically set up in the standard vc-shell app shell.
-
-## Tips
-
-- Always `await` the result of `showConfirmation` before proceeding with the destructive action.
-- For simple yes/no questions, use `showConfirmation`. For forms or complex interactions, create a custom popup component.
-- The `usePopup` composable can be called without arguments (for built-in dialogs) or with a component config (for custom popups).
-- Avoid nesting popups more than 2 levels deep. Consider blades for complex multi-step workflows.
-
-## Related Components
-
-- **VcPopup** - The default popup shell component (header, content, actions)
-- **VcBlade** - For panel-based UI; use popups for modal interruptions
-- **notification()** - For passive, non-blocking feedback