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

package/CHANGELOG.md

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

package/package.json

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

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 2f71da38b on 2026-04-01T16:03:16.012Z
+Synced from framework at commit fc29b1e1b on 2026-04-02T05:22:47.427Z

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

@@ -0,0 +1,111 @@
+# useBladeContext (defineBladeContext / injectBladeContext)
+
+Exposes blade-level data to descendant widgets, extensions, and nested components via Vue's provide/inject mechanism. This pair of functions eliminates the need for prop drilling when child widgets or extension points need access to the parent blade's entity data, loading flags, or other shared state.
+
+The pattern follows a "define once, inject anywhere" approach: the blade component calls `defineBladeContext` during setup, and any descendant (no matter how deeply nested) can call `injectBladeContext` to read that data reactively.
+
+## When to Use
+
+- Share blade state (current entity, loading flags, disabled state) with child widgets without prop drilling
+- Access parent blade data from an extension or widget component
+- Expose selective fields to widgets (e.g., only the entity ID) via a computed getter
+- When NOT to use: for cross-blade communication between sibling blades (use `useBlade` / blade messaging instead)
+
+## Basic Usage
+
+```typescript
+// In a blade's <script setup>
+import { defineBladeContext, injectBladeContext } from '@vc-shell/framework';
+
+// Provide context — refs/computeds are auto-unwrapped for consumers
+defineBladeContext({ item, disabled, loading });
+
+// Or with a computed for selective exposure
+defineBladeContext(computed(() => ({ id: item.value?.id })));
+```
+
+```typescript
+// In a widget or nested component
+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
+
+### defineBladeContext
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `data` | `MaybeRefOrGetter<Record<string, unknown>>` | Yes | Plain object, ref, or getter to expose |
+
+Returns `void`. Must be called in the blade's `<script setup>`.
+
+### injectBladeContext
+
+Takes no parameters. Returns `ComputedRef<Record<string, unknown>>`.
+
+Throws `InjectionError` if no ancestor blade has called `defineBladeContext`.
+
+## Recipe: Widget Consuming Blade Context
+
+A typical pattern is a sidebar widget that needs to load related data based on the current blade entity. The widget does not receive any props from the blade -- it reads the entity ID from the blade context:
+
+```vue
+<script setup lang="ts">
+// widgets/RelatedOrdersWidget.vue
+import { computed, watch } from "vue";
+import { injectBladeContext } from "@vc-shell/framework";
+
+const ctx = injectBladeContext();
+const customerId = computed(() => ctx.value.id as string | undefined);
+
+// Reload orders whenever the customer changes
+watch(customerId, async (id) => {
+  if (id) {
+    await loadOrders(id);
+  }
+});
+</script>
+```
+
+```vue
+<script setup lang="ts">
+// blades/CustomerDetailBlade.vue
+import { ref, computed } from "vue";
+import { defineBladeContext } from "@vc-shell/framework";
+
+const customer = ref({ id: "cust-1", name: "Acme Corp" });
+const loading = ref(false);
+
+// Expose the customer data to all descendant widgets
+defineBladeContext(computed(() => ({
+  id: customer.value?.id,
+  name: customer.value?.name,
+  loading: loading.value,
+})));
+</script>
+```
+
+## 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`.
+- **Scope**: The context is scoped to the Vue component subtree. Each blade in the stack has its own context, so nested blades do not leak data upward or sideways.
+
+## Tips
+
+- Prefer exposing a computed getter rather than the full reactive object when only a subset of fields is needed. This minimizes unnecessary re-renders in consuming widgets.
+- The context value is untyped (`Record<string, unknown>`). Use type assertions or a typed wrapper in your module if you need type safety (e.g., `ctx.value.id as string`).
+- If a blade does not call `defineBladeContext`, any descendant calling `injectBladeContext` will throw. Make sure all blades that host widgets define their context.
+
+## Related
+
+- `BladeContextKey` in `framework/injection-keys.ts`
+- `useBladeWidgets` -- widgets that consume blade context
+- `useBladeStack` -- manages the blade navigation stack

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

@@ -0,0 +1,113 @@
+# useBladeForm
+
+Unified form state management for blades. Replaces manual combination of `useForm` + `useModificationTracker` + `useBeforeUnload` + `onBeforeClose` with a single composable.
+
+## Import
+
+```ts
+import { useBladeForm } from "@vc-shell/framework";
+```
+
+## Basic Usage
+
+```ts
+const { item, loadItem, saveItem } = useItemData();
+
+const form = useBladeForm({ data: item });
+
+onMounted(async () => {
+  await loadItem({ id: param.value });
+  form.setBaseline(); // snapshot current data as pristine
+});
+
+// Toolbar
+const toolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "lucide-save",
+    disabled: computed(() => !form.canSave.value),
+    async clickHandler() {
+      await saveItem(item.value);
+      form.setBaseline(); // snapshot after save
+      callParent("reload");
+    },
+  },
+]);
+```
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `data` | `Ref<T>` | required | Reactive data object for the form |
+| `canSaveOverride` | `ComputedRef<boolean>` | — | Additional condition for canSave |
+| `autoBeforeClose` | `boolean \| ComputedRef<boolean>` | `true` | Close guard behavior |
+| `autoBeforeUnload` | `boolean` | `true` | Browser tab close guard |
+| `closeConfirmMessage` | `MaybeRefOrGetter<string>` | — | Custom unsaved changes message |
+| `onRevert` | `() => void \| Promise<void>` | — | Custom revert handler |
+
+### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `setBaseline()` | `() => void` | Snapshot current data as pristine. Call after load and after save |
+| `revert()` | `() => void \| Promise<void>` | Revert data to pristine (or call onRevert) |
+| `canSave` | `ComputedRef<boolean>` | `isReady && valid && modified && canSaveOverride` |
+| `isModified` | `ComputedRef<boolean>` | Data differs from pristine (false until setBaseline) |
+| `isReady` | `ComputedRef<boolean>` | setBaseline() called at least once |
+| `formMeta` | vee-validate meta | Form validation state |
+| `setFieldError` | function | Set field error programmatically |
+| `errorBag` | Ref | All field errors |
+
+## Lifecycle
+
+```
+Mount → Load data → setBaseline() → User edits → Save → setBaseline()
+                                                 └→ Cancel → revert()
+```
+
+## VcBlade Integration
+
+`useBladeForm` auto-provides form state to `VcBlade` via inject. No need to pass `:modified` prop:
+
+```vue
+<!-- Before -->
+<VcBlade :modified="isModified" :toolbar-items="toolbar">
+
+<!-- After -->
+<VcBlade :toolbar-items="toolbar">
+```
+
+## Advanced: Readonly Blade
+
+```ts
+const disabled = computed(() => !!param.value && !item.value?.canBeModified);
+
+const form = useBladeForm({
+  data: item,
+  canSaveOverride: computed(() => !disabled.value),
+  autoBeforeClose: computed(() => !disabled.value), // no prompt when readonly
+});
+```
+
+## Advanced: Custom Revert
+
+```ts
+const form = useBladeForm({
+  data: item,
+  onRevert: () => loadItem({ id: param.value }), // reload from server
+});
+```
+
+## Constraints
+
+- **Must be called from component `setup()`** (or `<script setup>`). Do NOT call from shared data-composables.
+- Validation rules stay in template (`<Field rules="...">`).
+- `setBaseline()` must be called after data is loaded — before that, `canSave` and `isModified` are `false`.
+
+## Migration
+
+See `MIGRATION_GUIDE.md` for step-by-step instructions on migrating existing modules.

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

@@ -0,0 +1,305 @@
+# useBladeWidgets / useWidgetTrigger
+
+Two composables for the widget system — one for the **blade side**, one for the **widget side**.
+
+| 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
+
+- **`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
+
+```typescript
+import { useBladeWidgets } from '@vc-shell/framework';
+
+const { refreshAll } = useBladeWidgets([
+  {
+    id: 'OffersWidget',
+    icon: 'lucide-tag',
+    title: 'OFFERS.TITLE',
+    badge: offersCount,
+    loading: offersLoading,
+    onClick: () => openBlade({ name: 'OffersList' }),
+    onRefresh: () => reloadOffers(),
+  },
+  {
+    id: 'ReviewsWidget',
+    icon: 'lucide-star',
+    title: 'REVIEWS.TITLE',
+    badge: reviewsCount,
+    isVisible: computed(() => !!item.value?.id),
+    onClick: () => openBlade({ name: 'ReviewsList' }),
+  },
+]);
+
+// After a save, refresh all widget data
+await saveEntity();
+refreshAll();
+```
+
+## API
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `widgets` | `HeadlessWidgetDeclaration[]` | Yes | Array of widget declarations |
+
+### HeadlessWidgetDeclaration
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Unique widget identifier |
+| `icon` | `string` | Yes | Icon name (e.g., `"lucide-tag"`) |
+| `title` | `string` | Yes | i18n key or display title |
+| `badge` | `Ref<number \| string>` | No | Badge counter value |
+| `loading` | `Ref<boolean>` | No | Show loading indicator |
+| `disabled` | `Ref<boolean> \| boolean` | No | Disable the widget |
+| `isVisible` | `ComputedRef<boolean> \| boolean` | No | Toggle visibility |
+| `onClick` | `() => void` | No | Action when widget is clicked |
+| `onRefresh` | `() => void \| Promise<void>` | No | Called by `refresh(id)` or `refreshAll()` |
+
+### Returns
+
+| Property | Type | Description |
+|---|---|---|
+| `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, BladeDescriptor } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { MessageWidget } from "./components/widgets";
+
+registerExternalWidget({
+  id: "MessageWidget",
+  component: markRaw(MessageWidget),
+  targetBlades: ["ProductDetails", "OrderDetails"],
+  isVisible: (blade?: BladeDescriptor) => !!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
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { useBladeWidgets, defineBladeContext } from "@vc-shell/framework";
+
+const product = ref({ id: "prod-1", name: "Widget A" });
+const offersCount = ref(0);
+const reviewsCount = ref(0);
+const offersLoading = ref(false);
+
+// Expose product data to widgets
+defineBladeContext(computed(() => ({ id: product.value?.id })));
+
+async function reloadOffers() {
+  offersLoading.value = true;
+  try {
+    const result = await api.searchOffers({ productId: product.value.id });
+    offersCount.value = result.totalCount;
+  } finally {
+    offersLoading.value = false;
+  }
+}
+
+const { refreshAll } = useBladeWidgets([
+  {
+    id: "OffersWidget",
+    icon: "lucide-tag",
+    title: "PRODUCT.WIDGETS.OFFERS",
+    badge: offersCount,
+    loading: offersLoading,
+    isVisible: computed(() => !!product.value?.id),
+    onClick: () => openBlade({ name: "OffersList" }),
+    onRefresh: reloadOffers,
+  },
+  {
+    id: "ReviewsWidget",
+    icon: "lucide-star",
+    title: "PRODUCT.WIDGETS.REVIEWS",
+    badge: reviewsCount,
+    isVisible: computed(() => !!product.value?.id),
+    onClick: () => openBlade({ name: "ReviewsList" }),
+  },
+]);
+
+async function save() {
+  await api.saveProduct(product.value);
+  // Refresh all widget counts after saving
+  refreshAll();
+}
+</script>
+```
+
+## 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.
+- **Blade ID resolution**: The composable injects `BladeDescriptorKey` to determine which blade the widgets belong to. Each blade has its own isolated widget list.
+- **Trigger pattern**: The `onRefresh` callback is stored as a `trigger` on the registered widget. When `refresh(id)` or `refreshAll()` is called, the trigger is invoked. Widgets without `onRefresh` are silently skipped.
+
+## Tips
+
+- Use `refreshAll()` after any blade operation that might change widget badge counts (save, delete, import).
+- The `badge` field accepts both numbers and strings. Use a string for non-numeric badges like "New" or "!".
+- 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` / `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/useMenuExpanded/index.docs.md

@@ -0,0 +1,83 @@
+# useMenuExpanded
+
+Manages the sidebar menu expanded/collapsed and hover-expanded state with localStorage persistence. This is the low-level composable that powers the sidebar pin/unpin behavior in the vc-shell admin UI. It tracks two independent states: the permanent "pinned" state (persisted across sessions) and the transient "hover-expanded" state (active only while the user hovers over a collapsed sidebar).
+
+## When to Use
+
+- Low-level control over sidebar pin and hover state
+- Building a custom sidebar component that needs expand/collapse persistence
+- When NOT to use: prefer `useSidebarState` which wraps this composable and adds mobile menu support, derived `isExpanded` computed, and responsive breakpoint handling
+
+## Basic Usage
+
+```typescript
+import { useMenuExpanded } from '@vc-shell/framework';
+
+const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
+
+// Toggle pin state (persisted to localStorage)
+toggleExpanded();
+
+// Hover expand with 200ms delay
+toggleHoverExpanded(true);   // opens after delay
+toggleHoverExpanded(false);  // closes immediately
+```
+
+## API
+
+### Returns
+
+| Property | Type | Description |
+|---|---|---|
+| `isExpanded` | `Ref<boolean>` | Pinned state, persisted via `useLocalStorage` |
+| `toggleExpanded` | `() => void` | Toggle the pinned state |
+| `isHoverExpanded` | `Ref<boolean>` | Temporary hover expansion (not persisted) |
+| `toggleHoverExpanded` | `(shouldExpand?: boolean) => void` | Set hover state; opening has a 200ms delay, closing is immediate |
+
+## Recipe: Custom Sidebar with Hover Expand
+
+A common pattern is binding mouse events on the sidebar rail so the menu previews its full width on hover, without permanently pinning it open:
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import { useMenuExpanded } from "@vc-shell/framework";
+
+const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
+
+// The sidebar is visually expanded if pinned OR hover-expanded
+const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.value);
+</script>
+
+<template>
+  <aside
+    :class="{ 'sidebar--expanded': isVisuallyExpanded }"
+    @mouseenter="toggleHoverExpanded(true)"
+    @mouseleave="toggleHoverExpanded(false)"
+  >
+    <nav>
+      <!-- menu items -->
+    </nav>
+    <button @click="toggleExpanded">
+      {{ isExpanded ? 'Unpin' : 'Pin' }}
+    </button>
+  </aside>
+</template>
+```
+
+## Details
+
+- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
+- **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
+- **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
+- **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.
+
+## Tips
+
+- If you call `toggleHoverExpanded(true)` and then `toggleHoverExpanded(false)` within the 200ms window, the expansion is canceled -- the timeout is cleared before it fires.
+- The composable does not handle mobile breakpoints. For responsive behavior, use `useSidebarState` instead, which combines `useMenuExpanded` with mobile detection.
+- Each call to `useMenuExpanded()` creates a new instance with its own timeout tracking, but they share the same localStorage-backed `isExpanded` ref (via `useLocalStorage`). Multiple instances will stay in sync for the pinned state.
+
+## Related
+
+- `useSidebarState` -- higher-level composable that adds mobile menu and derived `isExpanded` computed

package/runtime/knowledge/docs/core/utilities/thumbnail/thumbnail.docs.md

@@ -0,0 +1,116 @@
+# Thumbnail URL Utility
+
+Transforms full-size image URLs into thumbnail variants by appending size suffixes before the file extension. VirtoCommerce backend generates thumbnails automatically with these suffixes.
+
+## When to Use
+
+- Use in any component that displays images at a known size smaller than the original
+- Reduces bandwidth and improves page load time significantly
+- Especially important for image lists (tables, galleries, cards)
+
+## Available Sizes
+
+### Named Presets
+
+| Preset | Use Case |
+|--------|----------|
+| `sm` | Small icons, table cells, avatar thumbnails |
+| `md` | Medium previews, cards |
+| `lg` | Large previews, hero images |
+
+### Pixel Sizes
+
+| Size | Pixels | Use Case |
+|------|--------|----------|
+| `64x64` | 64px | Table cells, tiny thumbnails |
+| `128x128` | 128px | Small tiles, list items |
+| `168x168` | 168px | Medium tiles |
+| `216x216` | 216px | Gallery tiles (md) |
+| `348x348` | 348px | Large gallery tiles |
+
+## API
+
+### `getThumbnailUrl(url, size?)`
+
+Transforms an image URL by inserting a size suffix before the file extension.
+
+```ts
+import { getThumbnailUrl } from "@core/utilities/thumbnail";
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg", "sm")
+// → "https://cdn.example.com/photo_sm.jpg"
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg", "128x128")
+// → "https://cdn.example.com/photo_128x128.jpg"
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg")
+// → "https://cdn.example.com/photo.jpg" (unchanged)
+
+getThumbnailUrl(undefined, "sm")
+// → undefined
+```
+
+**Parameters:**
+- `url` — Original image URL (string or undefined)
+- `size` — Thumbnail size preset or pixel dimensions (optional)
+
+**Returns:** Transformed URL, or original URL if size not specified
+
+### `getBestThumbnailSize(displaySize)`
+
+Maps a CSS pixel display size to the best-fit thumbnail preset. Picks the smallest thumbnail that is >= the display size.
+
+```ts
+import { getBestThumbnailSize } from "@core/utilities/thumbnail";
+
+getBestThumbnailSize(48)   // → "64x64"
+getBestThumbnailSize(96)   // → "128x128"
+getBestThumbnailSize(200)  // → "216x216"
+getBestThumbnailSize(500)  // → "lg"
+```
+
+## Usage in Components
+
+### VcImage
+
+```vue
+<VcImage
+  :src="product.imgSrc"
+  thumbnail-size="sm"
+  size="s"
+/>
+```
+
+### VcGallery
+
+Gallery auto-maps `size` prop to thumbnail size. Override with `thumbnailSize`:
+
+```vue
+<!-- Auto: sm→128x128, md→216x216, lg→348x348 -->
+<VcGallery :images="images" size="md" />
+
+<!-- Explicit override -->
+<VcGallery :images="images" thumbnail-size="128x128" />
+```
+
+Gallery preview uses `64x64` for the thumbnail strip and full-size for the main image automatically.
+
+### VcDataTable (CellImage)
+
+Table image cells use `sm` thumbnail by default — no action needed.
+
+## Types
+
+```ts
+type ThumbnailPreset = "sm" | "md" | "lg";
+type ThumbnailPixelSize = "64x64" | "128x128" | "168x168" | "216x216" | "348x348";
+type ThumbnailSize = ThumbnailPreset | ThumbnailPixelSize;
+```
+
+## Notes
+
+- The utility only transforms the URL — the backend must have generated the thumbnail for the URL to resolve
+- If a thumbnail doesn't exist on the server, the browser will show a broken image. Ensure your asset pipeline generates all required sizes.
+- The suffix is inserted before the file extension: `photo.jpg` → `photo_sm.jpg`
+- URLs without a file extension are returned unchanged
+- Already-suffixed URLs are not double-transformed

package/runtime/knowledge/docs/shell/components/change-password-button/change-password-button.docs.md

@@ -91,4 +91,4 @@ export default {
 - [SettingsMenu](../settings-menu/settings-menu.docs.md) -- parent container
 - [SettingsMenuItem](../settings-menu-item/settings-menu-item.docs.md) -- base menu item used internally
 - [LogoutButton](../logout-button/logout-button.docs.md) -- sibling account action
-- [ChangePasswordPage](../../pages/ChangePasswordPage/change-password-page.docs.md) -- full-page variant for expired passwords
+- [ChangePasswordPage](../../auth/ChangePasswordPage/change-password-page.docs.md) -- full-page variant for expired passwords

package/runtime/knowledge/docs/shell/pages/ChangePasswordPage/change-password-page.docs.md

@@ -1,102 +0,0 @@
-# ChangePasswordPage
-
-Change password page with current, new, and confirm password fields. Supports a `forced` mode for expired passwords that displays an info banner and is triggered by post-login redirect. This full-page variant is used when the user must change their password before accessing the application (e.g., expired password policy). For voluntary password changes from within the app, the `ChangePasswordButton` in the settings menu opens a popup instead.
-
-## When to Use
-
-- When a signed-in user wants to change their password (full-page flow)
-- In `forced` mode after login when the user's password has expired
-- The standard vc-shell routing maps `/change-password` to this page
-
-## Basic Usage
-
-```vue
-<template>
-  <ChangePassword />
-</template>
-
-<!-- Forced mode (expired password) -->
-<template>
-  <ChangePassword forced />
-</template>
-```
-
-With custom branding:
-
-```vue
-<template>
-  <ChangePassword
-    forced
-    logo="/assets/my-company-logo.svg"
-    background="/assets/custom-background.jpg"
-  />
-</template>
-```
-
-## Key Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `forced` | `boolean` | `false` | Show expired-password info banner and adjusted title |
-| `logo` | `string` | - | Override logo image URL |
-| `background` | `string` | - | Custom background image URL |
-
-## Recipe: Router Configuration with Forced Mode
-
-Set up the route so the login page can redirect here when the password is expired:
-
-```ts
-import ChangePassword from "@vc-shell/framework/shared/pages/ChangePasswordPage";
-
-const routes = [
-  {
-    path: "/change-password",
-    name: "ChangePassword",
-    component: ChangePassword,
-    props: (route) => ({
-      forced: route.query.forced === "true",
-    }),
-  },
-];
-```
-
-In the login flow, redirect when the user's password has expired:
-
-```ts
-async function handleLogin() {
-  const result = await signIn(username.value, password.value);
-  if (result.passwordExpired) {
-    router.push({ name: "ChangePassword", query: { forced: "true" } });
-  } else {
-    router.push("/");
-  }
-}
-```
-
-## Features
-
-- **Real-time password policy validation**: Uses `useUserManagement().validatePassword` to check the new password against the platform's policy as the user types (minimum length, required uppercase, lowercase, digits, special characters)
-- **Equal password detection**: Shows a specific "Equal-passwords" error when the new password matches the current password, without making an API call
-- **Confirm-password mismatch detection**: Validates that the new password and confirm password fields match
-- **Forced mode banner**: When `forced` is `true`, displays an info banner explaining that the password has expired and must be changed
-- **Cancel behavior**: Cancel button signs out the user and redirects to `/login`
-- **Success redirect**: On successful password change, redirects to `/` (main application)
-
-## Details
-
-- **Auth layout**: Renders inside `VcAuthLayout`, providing the centered card design with logo and background.
-- **Password policy**: The validation rules are fetched from the platform API and include configurable requirements (minimum length, character classes, etc.). The component displays these rules as a checklist.
-- **Forced vs voluntary**: In forced mode (`forced=true`), the page title changes to reflect the expired password scenario, and an info banner explains why the change is required. The form fields and behavior are otherwise identical.
-- **Sign-out on cancel**: If the user cancels during a forced password change, they are signed out. This prevents access to the application with an expired password.
-
-## Tips
-
-- The `forced` prop is typically set via a route query parameter, not hardcoded. The login page detects expired passwords and redirects with the appropriate flag.
-- Password policy validation runs on keyup, providing immediate feedback. The submit button is disabled until all policy requirements are met and the passwords match.
-- This page is distinct from the `ChangePasswordButton` popup. The page is for full-screen flow (forced changes), while the popup is for voluntary in-app password changes.
-
-## Related Components
-
-- **VcAuthLayout** - The underlying centered card layout
-- **LoginPage** - Redirects here when `user.passwordExpired` is true
-- **ChangePasswordButton** - Settings menu popup variant for voluntary password changes