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

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# [2.0.0-alpha.31](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.30...v2.0.0-alpha.31) (2026-04-01)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
+# [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

package/package.json

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

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit d863d7620 on 2026-03-26T14:29:54.970Z
+Synced from framework at commit 2f71da38b on 2026-04-01T16:03:16.012Z

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/useDynamicProperties/useDynamicProperties.docs.md

@@ -1,163 +1,162 @@
 # useDynamicProperties
 
-Generic composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types. This is one of the most complex composables in the framework because it must handle the combinatorial explosion of property configurations: a property can be multilanguage AND multivalue AND dictionary-backed, each combination requiring different get/set logic. The composable handles loading dictionary items from the API, getting/setting property values by locale, unit-of-measure lookups, and color code management.
+Composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types.
 
-The composable is generic over the property, value, dictionary item, and measurement types, allowing it to work with both the standard platform types and custom extensions.
+Internally uses a strategy pattern — each property type (regular, boolean, dictionary, measure, color) has a dedicated handler with `get`/`set` methods.
 
 ## When to Use
 
 - In product, category, or any entity detail blades that display platform dynamic properties
 - When properties are defined at runtime (not compile-time) and may be multilanguage or dictionary-based
 - When you need to render and edit property values that can be text, boolean, number, datetime, dictionary selection, color picker, or measurement with units
-- When NOT to use: for static, compile-time form fields, use standard Vue reactive state. For simple key-value pairs without multilanguage/dictionary support, plain refs are sufficient.
+- When NOT to use: for static, compile-time form fields, use standard Vue reactive state
 
 ## Quick Start
 
 ```typescript
-import { useDynamicProperties } from '@vc-shell/framework';
-import { PropertyValue, PropertyDictionaryItem } from '@core/api/platform';
-
-const { loading, loadDictionaries, getPropertyValue, setPropertyValue, loadMeasurements } =
-  useDynamicProperties(
-    (criteria) => api.searchPropertyDictionaryItems(criteria),
-    PropertyValue,
-    PropertyDictionaryItem,
-    (measureId, locale) => api.searchMeasurements(measureId, locale),
-  );
+import { useDynamicProperties } from "@vc-shell/framework";
+
+const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements, loading } =
+  useDynamicProperties({
+    searchDictionary: (criteria) => api.searchPropertyDictionaryItems(criteria),
+    searchMeasurements: (measureId, locale) => api.searchMeasurements(measureId, locale),
+  });
 ```
 
 ## API
 
-### Parameters
+### Options
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `searchDictionaryItemsFunction` | `(criteria) => Promise<TPropertyDictionaryItem[] \| undefined>` | Yes | API function to search dictionary items by property ID and keyword. Called when the user opens a dictionary dropdown. |
-| `PropertyValueConstructor` | `new (data?) => TPropertyValue` | Yes | Constructor class for creating property value instances. Used when creating new values during `setPropertyValue`. |
-| `PropertyDictionaryItemConstructor` | `new (data?) => TPropertyDictionaryItem` | Yes | Constructor class for creating dictionary item instances. Used when localizing dictionary items. |
-| `searchMeasurementFunction` | `(measureId, locale?) => Promise<TMeasurement[] \| undefined>` | No | API function for loading measurement/unit-of-measure dictionaries. Only needed if you have measure-type properties. |
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `searchDictionary` | `(criteria: IBasePropertyDictionaryItemSearchCriteria) => Promise<IBasePropertyDictionaryItem[] \| undefined>` | Yes | API function to search dictionary items by property ID and keyword |
+| `searchMeasurements` | `(measureId: string, locale?: string) => Promise<IBaseMeasurementDictionaryItem[] \| undefined>` | No | API function for loading measurement units. Only needed for measure-type properties |
 
 ### Returns
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `loading` | `ComputedRef<boolean>` | Whether a dictionary or measurement lookup is in progress. |
-| `loadDictionaries` | `(propertyId, keyword?, locale?) => Promise<TPropertyDictionaryItem[] \| undefined>` | Loads dictionary items for a property. If `locale` is provided, resolves localized values from `localizedValues`. |
-| `getPropertyValue` | `(property, locale) => string \| TPropertyValue[] \| boolean` | Reads the display value for a property in the given locale. Returns string for simple values, array for multivalue, boolean for boolean type. |
-| `setPropertyValue` | `(params: SetPropertyValueParams) => void` | Writes a value to a property. Dispatches to specialized handlers based on property type (measure, color, dictionary, regular). |
-| `loadMeasurements` | `(measureId, keyword?, locale?) => Promise<TMeasurement[] \| undefined>` | Loads measurement units for a measure-type property. No-op if `searchMeasurementFunction` was not provided. |
+| `getPropertyValue` | `(property, locale) => PropertyDisplayValue` | Read display value for a property. Returns string, boolean, or array depending on type. Does NOT mutate the property. |
+| `setPropertyValue` | `(params: SetPropertyValueParams) => void` | Write value to a property. Handles type-specific transformation and empty cleanup. |
+| `loadDictionaries` | `(propertyId, keyword?, locale?) => Promise<...>` | Load dictionary items. If locale is provided, resolves localized values. |
+| `loadMeasurements` | `(measureId, keyword?, locale?) => Promise<...>` | Load measurement units. No-op if `searchMeasurements` was not provided. |
+| `loading` | `ComputedRef<boolean>` | Whether a dictionary lookup is in progress. |
 
 ### SetPropertyValueParams
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `property` | `TProperty` | The property object to update. Modified in place. |
-| `value` | `string \| TPropertyValue[] \| TPropertyDictionaryItem[]` | The new value. Type depends on property configuration. |
-| `dictionary` | `TPropertyDictionaryItem[]?` | Dictionary items for dictionary properties. Required when setting a dictionary value. |
+| `property` | `IBaseProperty` | The property object to update. Modified in place. |
+| `value` | `string \| IBasePropertyValue[] \| (IBasePropertyDictionaryItem & { value: string })[]` | The new value. Type depends on property configuration. |
+| `dictionary` | `IBasePropertyDictionaryItem[]?` | Dictionary items. Required when setting a dictionary value. |
 | `locale` | `string?` | Current locale for multilanguage properties. |
-| `initialProp` | `TProperty?` | Original property state. Used for empty-value detection -- if the original was empty and the new value is empty, a placeholder is preserved; otherwise, the value array is cleared. |
 | `unitOfMeasureId` | `string?` | Unit of measure ID for measure-type properties. |
 | `colorCode` | `string?` | Color hex code for color-type properties. |
 
+### PropertyDisplayValue
+
+```ts
+type PropertyDisplayValue = string | IBasePropertyValue[] | boolean;
+```
+
 ## How It Works
 
-### Value Getting
+### Strategy Resolution
 
-`getPropertyValue` dispatches based on property flags:
+The composable resolves a strategy handler based on property flags:
 
-- **Multilanguage**: Finds the value entry matching the locale. For multivalue, returns all entries for that locale as an array. For dictionary, returns the `valueId`. If no entry exists for the locale, creates a default entry using the first available alias.
-- **Single-language**: Returns the first value entry. For multivalue, returns all entries as an array. For dictionary, returns the `valueId`.
-- **Boolean**: Returns `false` if no value entry exists (instead of empty string).
+| Priority | Condition | Strategy | Handles |
+|----------|-----------|----------|---------|
+| 1 | `valueType === "Measure"` | measureStrategy | Numeric input with unit dropdown |
+| 2 | `valueType === "Color"` && !dictionary | colorStrategy | Color picker, multivalue colors |
+| 3 | `valueType === "Boolean"` | booleanStrategy | Checkbox/switch |
+| 4 | `dictionary === true` | dictionaryStrategy | Select dropdowns with localized options |
+| 5 | (default) | regularStrategy | ShortText, LongText, Number, Integer, DateTime |
 
-### Value Setting
+### Value Getting
 
-`setPropertyValue` checks property type in order:
-1. **Measure** (`valueType === "Measure"`): Creates a single value entry with `unitOfMeasureId`.
-2. **Color** (`valueType === "Color"`, no dictionary): Creates value entry/entries with `colorCode`.
-3. **Dictionary**: Resolves the selected dictionary item(s), expanding `localizedValues` into per-locale value entries for multilanguage dictionaries.
-4. **Regular**: Handles the remaining cases -- simple text, number, boolean, datetime.
+Each strategy's `get()` reads from `property.values` without mutation:
 
-### Dictionary Localization
+- **Multilanguage**: Finds value matching locale, falls back to value without languageCode
+- **Multivalue**: Returns full array (filtered by locale for multilanguage)
+- **Dictionary**: Returns `valueId` instead of `value`
+- **Boolean**: Returns `false` (not `""`) when no value exists
 
-When `loadDictionaries` is called with a locale, each dictionary item's `localizedValues` array is searched for the matching locale. The localized display value replaces the generic `alias` for UI rendering. This is why the function returns `Promise<TPropertyDictionaryItem[]>` -- the items are cloned and enriched.
+### Value Setting
 
-## Recipe: Rendering a Dynamic Property Form
+Each strategy's `set()` writes to `property.values`:
 
-```vue
-<script setup lang="ts">
-import { useDynamicProperties, useLanguages } from '@vc-shell/framework';
-import { ref, watch } from 'vue';
-
-const { currentLocale } = useLanguages();
-const { loading, loadDictionaries, getPropertyValue, setPropertyValue } =
-  useDynamicProperties(searchDictionaryItems, PropertyValue, PropertyDictionaryItem);
-
-const properties = ref<Property[]>([]);
-
-// Display values, keyed by property ID
-function displayValue(property: Property) {
-  return getPropertyValue(property, currentLocale.value);
-}
-
-// Handle value change from a form input
-async function onValueChange(property: Property, newValue: string) {
-  if (property.dictionary) {
-    const dictItems = await loadDictionaries(property.id!, '', currentLocale.value);
-    setPropertyValue({
-      property,
-      value: newValue,
-      dictionary: dictItems ?? [],
-      locale: currentLocale.value,
-    });
-  } else {
-    setPropertyValue({
-      property,
-      value: newValue,
-      locale: currentLocale.value,
-    });
-  }
-}
-</script>
-```
+- **Empty values are cleaned up automatically** via `cleanEmptyValues()`. When user clears a field, scaffolding objects are removed and `property.values` becomes `[]`. This prevents false modification detection in `useBladeForm`.
+- **Multilanguage cleanup**: Only the value for the current locale is removed; other locales are preserved.
+- **Dictionary**: Expands `localizedValues` into per-locale value entries.
 
-## Recipe: Dictionary Property with Search-as-You-Type
+### Empty Value Cleanup (cleanEmptyValues)
 
-```vue
-<script setup lang="ts">
-import { useDynamicProperties } from '@vc-shell/framework';
-import { ref } from 'vue';
+When `setPropertyValue` receives an empty value (`""`, `null`, `undefined`), it cleans up `property.values` instead of leaving scaffolding objects:
 
-const { loadDictionaries } = useDynamicProperties(/* ... */);
+```
+Before: values: [{ value: "", languageCode: "en", propertyId: "abc", ... }]
+After:  values: []
+```
 
-const dictOptions = ref<PropertyDictionaryItem[]>([]);
+This ensures that `useBladeForm`'s deep comparison correctly detects "no change" when user clears a field that was originally empty.
 
-async function onDictionarySearch(property: Property, keyword: string, locale: string) {
-  const items = await loadDictionaries(property.id!, keyword, locale);
-  dictOptions.value = items ?? [];
-}
-</script>
+## Recipe: With VcDynamicProperty
 
+```vue
 <template>
-  <VcSelect
-    :options="dictOptions"
-    option-value="id"
-    option-label="value"
-    @search="(keyword) => onDictionarySearch(property, keyword, currentLocale)"
-    @update:model-value="(val) => onValueChange(property, val)"
+  <VcDynamicProperty
+    v-for="property in properties"
+    :key="property.id"
+    :property="property"
+    :model-value="getPropertyValue(property, currentLocale)"
+    :options-getter="loadDictionaries"
+    :measurements-getter="loadMeasurements"
+    :current-language="currentLocale"
+    :value-type="property.valueType ?? ''"
+    :dictionary="property.dictionary"
+    :multivalue="property.multivalue"
+    :multilanguage="property.multilanguage"
+    @update:model-value="(ev) => setPropertyValue({ property, ...ev })"
   />
 </template>
+
+<script setup lang="ts">
+import { useDynamicProperties } from "@vc-shell/framework";
+
+const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements } =
+  useDynamicProperties({
+    searchDictionary: searchDictionaryItems,
+    searchMeasurements: searchMeasurementItems,
+  });
+</script>
 ```
 
 ## Tips
 
-- **`setPropertyValue` mutates the property in place.** Unlike `useAssets` which returns new arrays, this composable modifies `property.values` directly. This is by design because dynamic properties are typically part of a larger entity object that gets saved as a whole.
-- **Always pass `dictionary` when setting dictionary values.** Without the dictionary items, the composable cannot resolve `valueId` to the correct alias and localized values. Omitting it results in incomplete value entries.
-- **Empty value handling depends on `initialProp`.** When the user clears a field, the behavior differs based on whether the property originally had a value. If it did, clearing sets `values: []` (explicit empty). If it was always empty, a placeholder value entry is preserved. This distinction matters for the platform's diff/save logic.
-- **Boolean properties always have a value entry.** Unlike other types where clearing removes the value, boolean properties always maintain a value entry (with `value: false`). This ensures checkboxes render correctly.
-- **The composable is generic but not abstract.** You must pass concrete constructor classes, not interfaces. The constructors are called with `new` to create value and dictionary item instances.
+- **`setPropertyValue` mutates the property in place.** `property.values` is modified directly. This is by design because dynamic properties are typically part of a larger entity object saved as a whole.
+- **Always pass `dictionary` when setting dictionary values.** Without dictionary items, the composable cannot resolve `valueId` to the correct alias and localized values.
+- **Boolean properties always have a value entry.** Unlike other types where clearing removes the value, boolean properties maintain a value entry (`value: false`). This ensures checkboxes render correctly.
+- **No class constructors needed.** Values are created as plain objects via `createValue()`. No factory classes required.
+
+## File Structure
+
+```
+useDynamicProperties/
+  index.ts              — composable entry point (~60 lines)
+  types.ts              — all interfaces
+  utils.ts              — isEmptyValue, createValue, cleanEmptyValues, type guards
+  strategies/
+    index.ts            — resolveStrategy() registry
+    types.ts            — PropertyValueStrategy interface
+    regular.ts          — ShortText, LongText, Number, Integer, DateTime
+    boolean.ts          — Boolean
+    dictionary.ts       — Dictionary (all multi/single × language/value)
+    measure.ts          — Measure
+    color.ts            — Color
+```
 
 ## Related
 
-- [useLanguages](../useLanguages/useLanguages.docs.md) -- locale management for multilanguage property rendering
-- `IBaseProperty`, `IBasePropertyValue` -- base interfaces defined in the composable file
-- `PropertyValue`, `PropertyDictionaryItem` from `@core/api/platform` -- concrete types for the standard platform
+- [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

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)