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

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# [2.0.0-alpha.30](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.29...v2.0.0-alpha.30) (2026-03-30)
+
+
+### Features
+
+* **docs:** add documentation for usePopup and useResponsive composables ([342a50a](https://github.com/VirtoCommerce/vc-shell/commit/342a50ada1545637782e01f5452a60839aa90fd2))
+# [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.30",
   "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.30

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 37522732b on 2026-03-30T14:31:59.196Z

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

@@ -123,6 +123,14 @@ These are reactive `ComputedRef` values that reflect the current blade's state.
 | `setError`      | `(error: unknown) => void`                   | Display an error banner on the blade                 |
 | `clearError`    | `() => void`                                 | Clear the blade error banner                         |
 
+#### Banner Management (blade context required)
+
+| Method         | Signature                                                    | Description                                                    |
+|----------------|--------------------------------------------------------------|----------------------------------------------------------------|
+| `addBanner`    | `(options: Omit<IBladeBanner, "id" \| "_system">) => string` | Add a custom banner to the blade. Returns the banner's unique ID. |
+| `removeBanner` | `(id: string) => void`                                       | Remove a specific banner by its ID                             |
+| `clearBanners` | `() => void`                                                 | Remove all custom banners (system error/modified banners are preserved) |
+
 #### Lifecycle Hooks (blade context required)
 
 | Method          | Signature                         | Description                                              |
@@ -373,6 +381,74 @@ async function loadData() {
 </script>
 ```
 
+### Banner Management
+
+Add custom banners (info, warning, danger, success) to the top of a blade. Banners appear between the header and toolbar, sorted by severity: danger > warning > info > success.
+
+```vue
+<script setup lang="ts">
+import { h } from "vue";
+import { useBlade } from "@vc-shell/framework";
+
+const { addBanner, removeBanner, clearBanners } = useBlade();
+
+// Simple text banner
+const bannerId = addBanner({
+  variant: "info",
+  message: "This record is in read-only mode",
+});
+
+// Warning with dismiss button
+addBanner({
+  variant: "warning",
+  message: "License expires in 7 days",
+  dismissible: true,
+});
+
+// Banner with an action button
+addBanner({
+  variant: "success",
+  message: "Import completed (42 items)",
+  dismissible: true,
+  action: {
+    label: "View report",
+    handler: () => openReport(),
+  },
+});
+
+// Banner with custom render function
+addBanner({
+  variant: "info",
+  render: () => h("span", [
+    "Data synced from ",
+    h("b", "Warehouse A"),
+    " at 14:32",
+  ]),
+});
+
+// Remove a specific banner
+removeBanner(bannerId);
+
+// Clear all custom banners (system error/modified banners are preserved)
+clearBanners();
+</script>
+```
+
+#### IBladeBanner
+
+The options object passed to `addBanner`:
+
+| Property      | Type                              | Default  | Description                                        |
+|---------------|-----------------------------------|----------|----------------------------------------------------|
+| `variant`     | `"danger" \| "warning" \| "info" \| "success"` | required | Color scheme and default icon              |
+| `message`     | `string`                          | --       | Plain text message                                 |
+| `render`      | `() => VNode`                     | --       | Custom render function (takes priority over message) |
+| `dismissible` | `boolean`                         | `false`  | Show a close button to dismiss the banner          |
+| `icon`        | `string`                          | --       | Override the default variant icon (lucide icon name) |
+| `action`      | `{ label: string; handler: () => void }` | --  | Action button displayed on the right side          |
+
+> **Note:** `addBanner` returns a unique string ID. Use it with `removeBanner(id)` to programmatically remove a specific banner. `clearBanners()` removes all custom banners but preserves system banners (error and unsaved changes).
+
 ---
 
 ## Blade Context: defineBladeContext / injectBladeContext

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/core/composables/usePopup/usePopup.docs.md

@@ -0,0 +1,195 @@
+# usePopup
+
+Programmatic popup management for modal dialogs. Returns methods to open confirmation, error, and info dialogs, as well as fully custom popup components with typed props and emits. Popups are rendered in a dedicated container at the app root level, ensuring they overlay all other content including blades and sidebars.
+
+## When to Use
+
+- Show confirmation dialogs before destructive actions (delete, discard, bulk operations)
+- Display error or info messages in a modal overlay
+- Open custom popup components with typed props and emits
+- When NOT to use: for passive feedback (use `notification()` toast instead), for navigation flows (use blade navigation instead)
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { usePopup } from "@vc-shell/framework";
+
+const { showConfirmation, showError } = usePopup();
+
+async function deleteProduct(id: string) {
+  const confirmed = await showConfirmation(
+    "Are you sure you want to delete this product?"
+  );
+  if (!confirmed) return;
+
+  try {
+    await api.deleteProduct(id);
+  } catch (error) {
+    showError(error.message || "Failed to delete product.");
+  }
+}
+</script>
+
+<template>
+  <VcBlade title="Product">
+    <VcButton variant="danger" @click="deleteProduct(product.id)">
+      Delete
+    </VcButton>
+  </VcBlade>
+</template>
+```
+
+## API
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `options` | `MaybeRef<UsePopupProps<T>>` | No | Configuration for a custom popup component. Omit for built-in dialogs only. |
+
+#### `UsePopupProps<T>`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `component` | `ComponentPublicInstanceConstructor` | Yes | The popup component to render |
+| `props` | `RawProps<T>` | No | Props to pass to the component (typed from the component's `defineProps`) |
+| `emits` | `RawEmits<T>` | No | Event handlers (typed from the component's `defineEmits`) |
+| `slots` | `Record<string, string \| Component \| Slot>` | No | Named slots — strings render as text, components render as VNodes |
+
+### Returns (`IUsePopup`)
+
+| 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 buttons. Resolves `true` on confirm, `false` on cancel or close. |
+| `showError` | `(message: string \| Ref<string>) => void` | Error-styled popup with a close button |
+| `showInfo` | `(message: string \| Ref<string>) => void` | Info-styled popup with a close button |
+
+## How It Works
+
+`usePopup` is backed by the `VcPopupHandler` plugin, which maintains a reactive array of popup instances. When you call `open()` or `showConfirmation()`, a popup descriptor is pushed into this array. The `VcPopupContainer` component (mounted once at the app root) renders all active popups as an overlay stack. Calling `close()` removes the descriptor, and Vue reactivity handles the unmount.
+
+The plugin instance is resolved via `inject(PopupPluginKey)`. If called outside the component tree (e.g., in a utility function), it falls back to the singleton `popupPluginInstance`.
+
+Multiple popups can be open simultaneously — they stack with the most recent on top.
+
+## Recipe: Delete Confirmation with Notification
+
+```vue
+<script setup lang="ts">
+import { usePopup, useBlade } from "@vc-shell/framework";
+import { useNotifications } from "@vc-shell/framework";
+
+const { showConfirmation, showError } = usePopup();
+const { closeSelf } = useBlade();
+
+async function deleteOrder(id: string) {
+  const confirmed = await showConfirmation(
+    "Are you sure you want to delete this order? This action cannot be undone."
+  );
+  if (!confirmed) return;
+
+  try {
+    await api.deleteOrder(id);
+    closeSelf();
+  } catch (error) {
+    showError(error.message || "Failed to delete order.");
+  }
+}
+</script>
+```
+
+## Recipe: Custom Popup with Form
+
+For complex interactions beyond simple confirmation, create a custom popup component:
+
+```ts
+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("prod-1", note);
+      close();
+    },
+    onCancel: () => close(),
+  },
+});
+
+open();
+```
+
+## Recipe: Reactive Options
+
+The `options` parameter accepts `MaybeRef`, so you can pass a computed or ref that updates the popup config dynamically:
+
+```ts
+import { computed } from "vue";
+import { usePopup } from "@vc-shell/framework";
+import ConfirmPopup from "./ConfirmPopup.vue";
+
+const selectedCount = ref(0);
+
+const { open, close } = usePopup(
+  computed(() => ({
+    component: ConfirmPopup,
+    props: { message: `Delete ${selectedCount.value} items?` },
+    emits: { onConfirm: () => { performDelete(); close(); } },
+  }))
+);
+```
+
+## Common Mistakes
+
+**Wrong: not awaiting showConfirmation**
+```ts
+// The delete runs immediately — confirmation is ignored
+showConfirmation("Delete?");
+await api.deleteProduct(id); // runs before user clicks!
+```
+
+**Correct: await the result**
+```ts
+const confirmed = await showConfirmation("Delete?");
+if (!confirmed) return;
+await api.deleteProduct(id);
+```
+
+---
+
+**Wrong: nesting many popups**
+```ts
+// 3+ deep popup stacks confuse users
+const a = await showConfirmation("Step 1?");
+if (a) {
+  const b = await showConfirmation("Step 2?");
+  if (b) {
+    const c = await showConfirmation("Step 3?");
+  }
+}
+```
+
+**Correct: use a blade for multi-step workflows**
+```ts
+// Complex flows belong in blades, not popups
+openBlade({ name: "WizardBlade", options: { step: 1 } });
+```
+
+## Tips
+
+- **Always `await` showConfirmation** before proceeding with the destructive action.
+- **Use `showConfirmation` for yes/no questions**, custom popups for forms or complex interactions.
+- **Calling `usePopup()` without arguments** gives you only the built-in dialogs (`showConfirmation`, `showError`, `showInfo`). Pass `options` only when you need a custom component.
+- **Avoid nesting popups more than 2 levels deep.** Consider blades for complex multi-step workflows.
+- **The message parameter accepts `Ref<string>`** — useful for dynamic messages that update while the popup is open (e.g., progress messages).
+
+## Related
+
+- [VcPopup](../../../ui/components/organisms/vc-popup/vc-popup.docs.md) — the default popup shell component (header, content, actions)
+- [useBlade](../useBlade/useBlade.docs.md) — for panel-based UI; use popups for modal interruptions only
+- `notification()` — for passive, non-blocking feedback (toasts)

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

@@ -0,0 +1,178 @@
+# useResponsive
+
+Reactive breakpoint state for building responsive blade UIs. Returns refs that indicate the current viewport category (phone, tablet, mobile, desktop) and whether the device supports touch input. Replaces the legacy `$isMobile.value` global properties in templates and `inject(IsMobileKey)` in script setup with a single, consistent API.
+
+## When to Use
+
+- Conditionally render desktop vs. mobile layouts in blade pages and components
+- Apply responsive CSS classes based on viewport size
+- Toggle behavior (e.g., disable drag-and-drop on touch devices, switch column visibility)
+- When NOT to use: for CSS-only responsive changes, prefer Tailwind breakpoint prefixes (`md:`, `lg:`) instead of JavaScript-driven conditionals
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+
+const { isMobile, isDesktop } = useResponsive();
+</script>
+
+<template>
+  <VcBlade title="Orders">
+    <!-- Vue auto-unwraps refs from script setup — no .value needed -->
+    <div v-if="isDesktop" class="tw-flex tw-gap-4">
+      <OrdersTable />
+      <OrdersSummary />
+    </div>
+    <OrdersTable v-else />
+  </VcBlade>
+</template>
+```
+
+## API
+
+### Parameters
+
+None. The composable reads breakpoint state from the framework's provide/inject context, which is set up automatically by `VcApp`.
+
+### Returns (`UseResponsiveReturn`)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `isMobile` | `Ref<boolean>` | `false` | `true` when viewport width < 1024px |
+| `isDesktop` | `Ref<boolean>` | `true` | `true` when viewport width >= 1024px |
+| `isPhone` | `Ref<boolean>` | `false` | `true` when viewport width < 480px |
+| `isTablet` | `Ref<boolean>` | `false` | `true` when 480px <= viewport width < 1024px |
+| `isTouch` | `boolean` | `false` | `true` on touch-capable devices (not reactive — set once at app init) |
+
+Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px. These match the framework's `setupBreakpoints()` configuration.
+
+Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold.
+
+## How It Works
+
+Under the hood, `useResponsive()` calls `inject()` for each breakpoint key (`IsMobileKey`, `IsDesktopKey`, etc.) with sensible defaults. The framework's root `VcApp` component provides these refs during app initialization using VueUse's `useBreakpoints`. Because the return values are the same `Ref<boolean>` instances provided at the app level, they are reactive and shared across all components.
+
+The defaults ensure the composable works even outside the VcApp provider tree (e.g., in unit tests or Storybook), defaulting to desktop mode.
+
+## Recipe: Responsive Blade with Mobile Card Layout
+
+```vue
+<script setup lang="ts">
+import { useResponsive, useBlade } from "@vc-shell/framework";
+
+const { isMobile, isDesktop } = useResponsive();
+const { openBlade } = useBlade();
+</script>
+
+<template>
+  <VcBlade title="Products">
+    <VcDataTable
+      :items="products"
+      :total-count="totalCount"
+      @row-click="({ data }) => openBlade({ name: 'ProductDetails', param: data.id })"
+    >
+      <VcColumn
+        id="image"
+        title=""
+        type="image"
+        :width="60"
+        :always-visible="true"
+        mobile-role="image"
+      />
+      <VcColumn
+        id="name"
+        :title="t('NAME')"
+        :sortable="true"
+        :always-visible="true"
+        mobile-role="title"
+      />
+      <!-- Extra columns visible only on desktop -->
+      <VcColumn id="sku" :title="t('SKU')" :sortable="true" />
+      <VcColumn id="price" :title="t('PRICE')" type="money" :sortable="true" />
+      <VcColumn id="createdDate" :title="t('DATE')" type="date-ago" :sortable="true" />
+    </VcDataTable>
+  </VcBlade>
+</template>
+```
+
+## Recipe: Touch-Aware Drag and Drop
+
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+
+const { isTouch } = useResponsive();
+</script>
+
+<template>
+  <VcDataTable
+    :items="items"
+    :reorderable-rows="!isTouch"
+    @reorder="onReorder"
+  >
+    <!-- columns -->
+  </VcDataTable>
+</template>
+```
+
+## Common Mistakes
+
+**Wrong: using `$isMobile.value` in template (deprecated)**
+```vue
+<template>
+  <!-- $isMobile is a global property — requires .value, no auto-unwrap -->
+  <div v-if="$isMobile.value">Mobile</div>
+</template>
+```
+
+**Correct: using `useResponsive()` destructure**
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+const { isMobile } = useResponsive();
+</script>
+<template>
+  <!-- Vue auto-unwraps refs from script setup — clean and type-safe -->
+  <div v-if="isMobile">Mobile</div>
+</template>
+```
+
+---
+
+**Wrong: using `inject(IsMobileKey)` directly**
+```vue
+<script setup lang="ts">
+import { inject, ref } from "vue";
+import { IsMobileKey } from "@vc-shell/framework";
+// Verbose, requires importing both inject and the key
+const isMobile = inject(IsMobileKey, ref(false));
+</script>
+```
+
+**Correct: using `useResponsive()`**
+```vue
+<script setup lang="ts">
+import { useResponsive } from "@vc-shell/framework";
+// One import, one line, all breakpoints available
+const { isMobile } = useResponsive();
+</script>
+```
+
+## Tips
+
+- **Destructure only what you need.** `const { isMobile } = useResponsive()` is fine — unused refs have no overhead since they already exist at the app level.
+- **Prefer CSS breakpoints for styling.** Use `useResponsive()` for structural changes (different component trees), but for spacing/sizing tweaks use Tailwind responsive prefixes (`md:tw-px-4`).
+- **`isTouch` is not reactive.** It's determined once at app startup based on `ontouchstart` / `maxTouchPoints`. It won't change if a user connects a mouse to a tablet mid-session.
+- **Works in tests without providers.** Defaults to desktop mode (`isDesktop: true`, `isMobile: false`), so most component tests don't need to provide breakpoint keys unless testing mobile-specific behavior.
+
+## Migration
+
+See [migration guide #36](../../../../migration/36-use-responsive.md) for automated codemod and manual migration instructions.
+
+## Related
+
+- `VcApp` — provides the breakpoint refs that `useResponsive()` reads
+- `VcBlade` — uses `isMobile` internally for mobile blade layout
+- `VcDataTable` — uses `isMobile` for mobile card rendering and pull-to-refresh

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