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

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# [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)
 
 

package/package.json

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

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 37522732b on 2026-03-30T14:31:59.196Z
+Synced from framework at commit 2f71da38b on 2026-04-01T16:03:16.012Z

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

@@ -1,6 +1,6 @@
 # useSlowNetworkDetection
 
-Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 5 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
+Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
 
 Like `useConnectionStatus`, this is a module-level singleton — calling it from multiple components shares the same state and listeners.
 
@@ -41,14 +41,14 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 | Property | Type | Description |
 |---|---|---|
 | `isSlowNetwork` | `Readonly<Ref<boolean>>` | `true` when the network is slow (either channel active). Read-only. |
-| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 5 s, it counts as slow. |
+| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 10 s, it counts as slow. |
 | `untrackRequest` | `(id: string) => void` | Stop tracking a request. Cancels the timer or decrements the slow count. |
 
 ### Constants
 
 | Name | Value | Purpose |
 |---|---|---|
-| `SLOW_REQUEST_THRESHOLD_MS` | `5000` | Time before a pending request is considered slow |
+| `SLOW_REQUEST_THRESHOLD_MS` | `10000` | Time before a pending request is considered slow |
 | `DISMISS_DELAY_MS` | `3000` | Delay before hiding the notification after recovery |
 | `SLOW_EFFECTIVE_TYPES` | `["slow-2g", "2g"]` | Connection types flagged as slow |
 
@@ -60,7 +60,7 @@ On first call, the composable checks `navigator.connection.effectiveType` (Netwo
 
 ### Channel 2: Request timers (reactive)
 
-The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 5-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
+The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
 
 ### Notification lifecycle
 

package/runtime/knowledge/docs/ui/components/atoms/vc-image/vc-image.docs.md

@@ -28,6 +28,7 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `clickable` | `boolean` | `false` | Makes the image interactive with cursor and click event |
 | `emptyIcon` | `string` | `"lucide-image"` | Icon shown when `src` is empty |
 | `alt` | `string` | — | Accessible alt text |
+| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
 
 ## Size Reference
 

package/runtime/knowledge/docs/ui/components/molecules/vc-image-tile/vc-image-tile.docs.md

@@ -40,6 +40,7 @@ function deleteImage() { /* remove from list */ }
 | `name` | `string` | — | File name displayed in the tray |
 | `imageFit` | `"contain" \| "cover"` | `"contain"` | How the image fits within the tile |
 | `actions` | `VcImageTileActions` | — | Which built-in action buttons to show |
+| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image |
 
 ## VcImageTileActions Interface
 

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

@@ -62,7 +62,7 @@ A blade has four visual zones, rendered top-to-bottom:
 |--------------------------------------|
 |  [Save] [Delete] [Refresh]  [More >] |  <-- Toolbar
 |--------------------------------------|
-|  ** Unsaved changes banner **        |  <-- Status Banners
+|  ** Status banners (stacked) **      |  <-- Status Banners
 |--------------------------------------|
 |                                      |
 |         Content (default slot)       |  <-- Content Area
@@ -74,7 +74,7 @@ A blade has four visual zones, rendered top-to-bottom:
 
 **Toolbar** -- Action buttons from the `toolbarItems` prop. Overflow items automatically collapse into a "More" dropdown (via `ResizeObserver`).
 
-**Status Banners** -- Yellow banner when `modified` is `true`; red banner when the blade has an error (set via `setError()`).
+**Status Banners** -- Unified, priority-sorted banner area. System banners: yellow when `modified` is `true`, red when the blade has an error (via `setError()`). Custom banners can be added programmatically via `useBlade().addBanner()` — see [useBlade docs](../../../core/composables/useBlade/useBlade.docs.md#banner-management).
 
 **Content Area** -- The `default` slot. Scrolls independently of header and toolbar.
 
@@ -399,6 +399,31 @@ import { useBeforeUnload } from "@vc-shell/framework";
 useBeforeUnload(hasChanges);  // Browser tab close warning
 ```
 
+## Custom Banners
+
+Add informational, warning, or success banners to a blade programmatically. Banners appear between the header and toolbar, sorted by severity.
+
+```vue
+<script setup lang="ts">
+import { useBlade } from "@vc-shell/framework";
+
+const { addBanner, removeBanner, clearBanners } = useBlade();
+
+// Info banner (e.g. read-only mode)
+addBanner({ variant: "info", message: "This record is read-only" });
+
+// Dismissible warning with action
+addBanner({
+  variant: "warning",
+  message: "License expires in 7 days",
+  dismissible: true,
+  action: { label: "Renew", handler: () => openRenewal() },
+});
+</script>
+```
+
+Four variants are available: `danger`, `warning`, `info`, `success`. System banners (error and unsaved changes) are always present and cannot be removed by `clearBanners()`. For the full API reference, see [useBlade — Banner Management](../../../core/composables/useBlade/useBlade.docs.md#banner-management).
+
 ## Blade Width Control
 
 ```vue

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

@@ -13,17 +13,21 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `layout` | `"filmstrip" \| "grid"` | `"filmstrip"` | Layout mode — filmstrip shows a single scrollable row with expand/collapse; grid shows the classic multi-row auto-fill layout. |
+| `label` | `string` | `undefined` | Label text displayed in the gallery header. |
+| `required` | `boolean` | `false` | Shows a required indicator (`*`) on the label. |
 | `images` | `ICommonAsset[]` | `[]` | Array of image assets to display. |
 | `disabled` | `boolean` | `false` | Disables all interactive actions. |
 | `multiple` | `boolean` | `false` | Allow selecting multiple files in upload dialog. |
-| `loading` | `boolean` | `false` | Shows a loading spinner on the upload zone. |
+| `loading` | `boolean` | `false` | Shows a loading overlay with spinner on the gallery. |
 | `itemActions` | `{ preview?: boolean; edit?: boolean; remove?: boolean }` | `{ preview: true, edit: true, remove: true }` | Per-tile action visibility. |
 | `rules` | `IValidationRules` | `undefined` | Validation rules for uploaded files. |
 | `name` | `string` | `"Gallery"` | Field name for validation messages. |
 | `accept` | `string` | `undefined` | Accepted file extensions. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tile size preset. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tile size preset. Sizes are smaller on mobile. |
 | `gap` | `number` | `8` | Gap between tiles in pixels. |
 | `imagefit` | `"contain" \| "cover"` | `"contain"` | How images fit within tiles. |
+| `thumbnailSize` | `ThumbnailSize` | auto from `size` | Thumbnail size for tile images. Auto-mapped: sm→128x128, md→216x216, lg→348x348. Preview thumbnails use 64x64. |
 
 ## Events
 
@@ -44,20 +48,24 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 ## Features
 
-- **Drag-and-drop reorder** -- Drag tiles to reorder. Emits `sort` with the new array. The dragged tile shows a ghost preview during the drag operation.
-- **External file drop** -- Drop files from the OS onto the gallery to upload. The entire gallery acts as a drop target with visual feedback.
-- **Lightbox preview** -- Click a tile to open a full-screen preview carousel. Navigate between images with arrow keys or swipe gestures.
-- **Responsive grid** -- Auto-fill grid adapts to container width using CSS grid with `auto-fill` and `minmax()`.
-- **Per-tile actions** -- Each tile shows preview, edit, and remove buttons on hover. Disable individual actions via the `itemActions` prop.
+- **Filmstrip layout (default)** -- Single-row scrollable strip powered by Swiper. Navigate with arrows, mouse wheel, or swipe. Click "Expand (N)" to show all images in a grid. "Collapse" returns to filmstrip.
+- **Grid layout** -- Classic auto-fill grid that wraps images into multiple rows. Set `layout="grid"` to use this mode.
+- **Drag-and-drop reorder** -- Drag tiles by the grip handle to reorder (powered by SortableJS). Works on both desktop and touch devices. In filmstrip mode, dragging to the edge auto-scrolls the strip. Emits `sort` with the new array.
+- **External file drop** -- Drop files from the OS onto the gallery to upload. The dashed border acts as a visual drop zone indicator (desktop only). A full overlay appears during drag-over.
+- **Fullscreen preview** -- Click the preview button to open a fullscreen carousel. Swipe or use arrow keys to navigate. Thumbnail strip at the bottom syncs with the main image.
+- **Per-tile actions** -- Each tile shows preview, edit, and remove buttons. On desktop: visible on hover. On mobile: visible on tap. Tile name is shown in the top bar alongside the drag handle.
+- **Loading state** -- When `loading` is true, a pulsing border and spinner overlay appear on the gallery. Upload button is disabled. Swiper navigation is frozen.
+- **Mobile responsive** -- Smaller tile sizes, no drag-and-drop hints, no dashed borders, compact action buttons, tap-to-reveal overlays. Uses `useResponsive` throughout.
+- **Lazy loading** -- Images use native `loading="lazy"` for deferred loading.
 
 ## Basic Usage
 
 ```vue
 <VcGallery
+  label="Product Images"
+  required
   :images="product.images"
-  size="md"
   imagefit="cover"
-  :item-actions="{ preview: true, edit: true, remove: true }"
   @upload="handleUpload"
   @sort="handleSort"
   @edit="handleEdit"
@@ -65,6 +73,31 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 />
 ```
 
+## Filmstrip Layout (Default)
+
+```vue
+<VcGallery
+  label="Images"
+  :images="product.images"
+  imagefit="cover"
+  @upload="handleUpload"
+  @sort="handleSort"
+  @remove="handleRemove"
+/>
+```
+
+## Classic Grid Layout
+
+```vue
+<VcGallery
+  layout="grid"
+  label="Attachments"
+  :images="product.images"
+  @upload="handleUpload"
+  @sort="handleSort"
+/>
+```
+
 ## Recipe: Product Image Gallery in a Blade
 
 ```vue
@@ -99,6 +132,8 @@ function handleRemove(image: ICommonAsset) {
 <template>
   <VcBlade title="Product Images">
     <VcGallery
+      label="Product Images"
+      required
       :images="images"
       multiple
       accept=".jpg,.png,.webp"
@@ -152,20 +187,24 @@ function handleRemove(image: ICommonAsset) {
 
 ## Tips
 
-- The `size` prop controls tile dimensions: `"sm"` is good for compact grids (e.g., thumbnails in a sidebar), `"md"` is the standard, and `"lg"` works well for hero image management.
+- The `size` prop controls tile dimensions: `"sm"` is good for compact grids (e.g., thumbnails in a sidebar), `"md"` is the standard, and `"lg"` works well for hero image management. Tiles are automatically smaller on mobile.
 - Use `imagefit="cover"` for photo galleries where cropping is acceptable, and `"contain"` for logos or icons where the full image must be visible.
-- The upload zone tile always appears at the end of the grid when the gallery is not disabled. It accepts both click and drag-and-drop interactions.
+- The filmstrip layout is ideal for blades where vertical space is limited. Users can expand to see all images or scroll horizontally. The classic grid layout is better for dedicated media management pages.
+- Use the `label` prop to display a header label integrated with the upload button. Add `required` to show a required indicator.
 - The `startingSortOrder` parameter in the `upload` event tells you where the new files should be inserted in the sort order. Use it to maintain correct ordering when appending new images.
+- On desktop, reorder by dragging the grip handle icon. In filmstrip mode, dragging to the strip edge auto-scrolls to reveal more tiles.
+- On mobile, tap a tile to reveal action buttons and the image name. Drag-and-drop hints and dashed borders are hidden automatically.
 
 ## Accessibility
 
 - Tiles are keyboard-navigable with Tab and action buttons are focusable
-- Lightbox preview supports keyboard navigation (arrow keys, Escape to close)
-- The upload zone is accessible via keyboard (Enter/Space to open file picker)
-- Drag-and-drop reorder requires mouse/touch; provide an alternative reorder mechanism for keyboard-only users if needed
+- Fullscreen preview supports keyboard navigation (arrow keys, Escape to close) and swipe gestures
+- The upload button in the header is keyboard-accessible
+- On mobile, tile actions are revealed via tap with click-outside to dismiss
 
 ## Related Components
 
 - **VcImageUpload** -- single-image upload component
-- **VcImageTile** -- the internal tile component used for each image
-- **VcLabel** / **VcHint** -- use alongside VcGallery for field labeling
+- **VcImageTile** -- the internal tile component used for each image (topbar with name + drag handle, bottom tray with actions)
+- **VcFileUpload** -- the file upload drop zone used in empty gallery state
+- **VcLabel** -- used internally when `label` prop is set

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

@@ -1,111 +0,0 @@
-# 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/useBladeWidgets.docs.md

@@ -1,305 +0,0 @@
-# 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/useGlobalSearch/useGlobalSearch.docs.md

@@ -1,146 +0,0 @@
-# useGlobalSearch
-
-Provides access to the global search service state: per-blade search visibility, search queries, and methods to toggle/close search. The service maintains a map of blade IDs to search state, allowing each blade in the stack to have its own independent search input. The state is shared through Vue's provide/inject system and automatically cleaned up when the scope is disposed.
-
-Also exports `provideGlobalSearch()` for framework-level initialization.
-
-## When to Use
-
-- In blade toolbars or headers to toggle and read the search input visibility for a specific blade
-- To programmatically set or read the search query for a specific blade (e.g., from a URL parameter or external trigger)
-- To integrate search with the blade toolbar's search icon button
-- When NOT to use: for table-level filtering within a blade, use VcDataTable's built-in search header. Global search is for blade-level search that affects the entire blade's content.
-
-## Quick Start
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { computed, watch } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const { isSearchVisible, searchQuery, toggleSearch, setSearchQuery, closeSearch } = useGlobalSearch();
-
-// Reactive accessors scoped to this blade
-const isVisible = computed(() => isSearchVisible.value[props.bladeId] ?? false);
-const query = computed(() => searchQuery.value[props.bladeId] ?? '');
-
-// React to search query changes
-watch(query, (newQuery) => {
-  if (newQuery.length >= 2) {
-    fetchResults(newQuery);
-  }
-});
-
-function onSearchToggle() {
-  toggleSearch(props.bladeId);
-}
-
-function onSearchClose() {
-  closeSearch(props.bladeId);
-}
-</script>
-
-<template>
-  <div>
-    <VcButton icon="fas fa-search" @click="onSearchToggle" />
-    <VcInput
-      v-if="isVisible"
-      :model-value="query"
-      placeholder="Search..."
-      @update:model-value="(val) => setSearchQuery(bladeId, val)"
-      @keydown.escape="onSearchClose"
-    />
-  </div>
-</template>
-```
-
-## API
-
-### Parameters
-
-None.
-
-### Returns (`GlobalSearchState`)
-
-| Property / Method | Type | Description |
-|-------------------|------|-------------|
-| `isSearchVisible` | `Ref<Record<string, boolean>>` | Map of blade IDs to search visibility state. Access via `isSearchVisible.value[bladeId]`. |
-| `searchQuery` | `Ref<Record<string, string>>` | Map of blade IDs to current search query strings. Access via `searchQuery.value[bladeId]`. |
-| `toggleSearch` | `(bladeId: string) => void` | Toggles search visibility for a blade. If visible, hides it (and clears the query). If hidden, shows it. |
-| `setSearchQuery` | `(bladeId: string, query: string) => void` | Sets the search query for a blade. Does not affect visibility. |
-| `closeSearch` | `(bladeId: string) => void` | Hides the search input for a blade and clears the query. |
-
-### Additional Exports
-
-| Export | Description |
-|--------|-------------|
-| `provideGlobalSearch()` | Creates and provides the global search service. Idempotent -- returns existing service if already provided. Cleans up all state on scope disposal. |
-
-## How It Works
-
-The service is a simple reactive state container with two `Ref<Record<string, ...>>` maps. Each blade ID is a key in these maps. This design means:
-
-1. **Blades are isolated**: Each blade has its own search visibility and query. Opening search in one blade does not affect others in the stack.
-2. **Lazy initialization**: A blade's entry in the map is created on first `toggleSearch` or `setSearchQuery` call. Reading a non-existent key returns `undefined`, which the consumer treats as `false`/empty.
-3. **Cleanup**: When `provideGlobalSearch()` scope is disposed (e.g., app unmount), both maps are cleared.
-
-## Recipe: Toolbar Search Button with Badge Indicator
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { computed } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const { isSearchVisible, searchQuery, toggleSearch } = useGlobalSearch();
-
-const hasActiveSearch = computed(() => {
-  const query = searchQuery.value[props.bladeId];
-  return query != null && query.length > 0;
-});
-</script>
-
-<template>
-  <VcButton
-    :icon="hasActiveSearch ? 'fas fa-search-plus' : 'fas fa-search'"
-    :variant="hasActiveSearch ? 'primary' : 'ghost'"
-    @click="toggleSearch(bladeId)"
-  />
-</template>
-```
-
-## Recipe: Pre-Populating Search from URL Query Parameter
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { useRoute } from 'vue-router';
-import { onMounted } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const route = useRoute();
-const { setSearchQuery, toggleSearch } = useGlobalSearch();
-
-onMounted(() => {
-  const urlQuery = route.query.search as string | undefined;
-  if (urlQuery) {
-    setSearchQuery(props.bladeId, urlQuery);
-    toggleSearch(props.bladeId); // make the search input visible
-  }
-});
-</script>
-```
-
-## Tips
-
-- **`toggleSearch` clears the query when hiding.** This is by design -- when the user closes the search, the query is reset. If you need to preserve the query across toggle cycles, store it separately.
-- **Use blade ID, not component instance ID.** The blade ID comes from the blade descriptor and is stable across re-renders. Using a component's `uid` would break if the component is recreated.
-- **State is not persisted.** Unlike sidebar state, search state is in-memory only. Refreshing the page clears all search queries. Use URL query parameters if you need persistence.
-- **Calling outside VcApp throws.** Like all provide/inject composables in the framework, `useGlobalSearch()` throws an `InjectionError` if the service has not been provided.
-
-## Related
-
-- VcDataTable search header -- table-level filtering built into the data table (different from global search)
-- [useToolbar](../useToolbar/) -- toolbar service for blade action buttons (often includes a search toggle button)
-- `framework/core/services/global-search-service.ts` -- underlying service implementation

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

@@ -1,83 +0,0 @@
-# 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