@vc-shell/vc-app-skill 2.0.3 → 2.0.4

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

@@ -1,9 +1,20 @@
+---
+title: VcSelect
+category: components
+group: form
+---
+
 # VcSelect
 
 A dropdown list component for selecting one or multiple values. Supports synchronous and asynchronous data sources, search with debounce, infinite scrolling, custom option templates, and full integration with the framework's validation system.
 
 VcSelect is one of the most widely used components in vc-shell. It covers most selection scenarios: from a simple dropdown with a static list to searching via a server API with pagination.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Data Sources](#data-sources), [Multiple Selection](#multiple-selection), [Slots](#slots), [Props](#props).
+
+::storybook id="form-vcselect--basic"
+
 ## When to Use
 
 | Scenario                                | Component                                |
@@ -82,6 +93,8 @@ In this case `optionValue` and `optionLabel` are not needed — the component us
 
 ### Async Function (Server API)
 
+::storybook id="form-vcselect--async-options" height="450"
+
 To load data from a server, pass a function instead of an array. This is the most powerful mode — it automatically provides:
 
 - Search with debounce (500ms by default)
@@ -142,6 +155,8 @@ const loadProducts = async (keyword?: string, skip?: number, ids?: string[]) =>
 
 ## Multiple Selection
 
+::storybook id="form-vcselect--multiple-selection"
+
 Add `multiple` to enable selecting several values. The model becomes an array:
 
 ```vue
@@ -178,6 +193,8 @@ Selected values are displayed as chips with a remove button. The `clearable` but
 
 ## Search and Filtering
 
+::storybook id="form-vcselect--searchable"
+
 Enable `searchable` to add a search field to the dropdown:
 
 ```vue
@@ -192,6 +209,8 @@ Enable `searchable` to add a search field to the dropdown:
 
 ## Custom Option Rendering
 
+::storybook id="form-vcselect--custom-option-slot" height="450"
+
 Use the `#option` slot for full control over how each option is rendered:
 
 ```vue
@@ -678,3 +697,16 @@ Don't forget `:key` with cascading selects, otherwise the second select will ret
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSelect is split into three layers: `vc-select.vue` (orchestrator), `SelectTrigger.vue` (trigger button + chips), `SelectDropdown.vue` (popup list).
+- Composable split: `useSelectDataSource` (options loading, infinite scroll, search), `useSelectSelection` (model-to-option mapping, toggle, remove), `useSelectValueMapping` (optionValue/optionLabel getters), `useSelectDropdown` (Floating UI positioning), `useSelectVisibility` (IntersectionObserver for lazy open).
+- `emitValue: true` (default) means `modelValue` is always a primitive (string/number/boolean). `emitValue: false` means full option object. The `mapOptions` flag controls whether resolved objects are stored in the cache for label resolution.
+- Infinite scroll is driven by `useIntersectionObserver` on a 1px sentinel element inside the dropdown viewport.
+- Keyboard navigation is managed by `useKeyboardNavigation` (`core/composables/`) — arrow keys, Enter, Escape. The composable attaches/detaches listeners when the dropdown opens/closes.
+- Source files: `framework/ui/components/molecules/vc-select/`
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcSlider
+category: components
+group: form
+---
+
 # VcSlider
 
 A content carousel component built on Swiper.js for displaying slides with optional navigation buttons. Renders any content via the default slot.
 
+::storybook id="form-vcslider--default"
+
 ## When to Use
 
 - Image carousels (product galleries, banners)
@@ -65,6 +73,8 @@ const products = [
 
 ### Custom Navigation Buttons
 
+::storybook id="form-vcslider--custom-navigation"
+
 ```vue
 <VcSlider :slides="items" navigation>
   <template #default="{ slide }">
@@ -123,3 +133,15 @@ const products = [
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSlider wraps the `swiper/vue` `<Swiper>` / `<SwiperSlide>` components with the `Navigation` module. Navigation buttons are custom DOM elements (`.vc-slider__prev` / `.vc-slider__next`) referenced by Swiper's `navigation.prevEl` / `nextEl` selectors.
+- `overflow` prop toggles `overflow: visible` on the swiper container, allowing slides to bleed outside bounds — useful for "peek" effects.
+- `slidesPerView="auto"` (default) lets each slide size itself from content. Pass a number for fixed-count layouts.
+- The `slides` prop accepts any array. Each item is exposed as `{ slide }` in the default scoped slot.
+- Source file: `framework/ui/components/molecules/vc-slider/vc-slider.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,18 @@
+---
+title: VcSwitch
+category: components
+group: form
+---
+
 # VcSwitch
 
 A toggle switch component for binary on/off choices. Renders as a sliding track with a thumb indicator and supports labels, hints, validation, and value inversion.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables).
+
+::storybook id="form-vcswitch--default"
+
 ## When to Use
 
 - Toggling a feature or setting on/off (e.g., "Enable notifications", "Publish product")
@@ -46,6 +57,8 @@ The `label` prop renders text above the switch. Use `hint` for helper text below
 
 ### Value Inversion with trueValue / falseValue
 
+::storybook id="form-vcswitch--variants"
+
 By default, `v-model` maps `true` to the checked (on) state and `false` to unchecked (off). The `trueValue` and `falseValue` props let you invert the mapping when your data model uses opposite semantics.
 
 ```vue
@@ -294,3 +307,15 @@ const isActive = ref(true);
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSwitch renders a hidden `<input type="checkbox">` with `role="switch"`. Visual state is driven by CSS (`:checked + .vc-switch__slider`). No JavaScript DOM manipulation needed for toggling.
+- `invertValue` handles the `trueValue`/`falseValue` mapping — both on read (for rendering) and on write (for emitting). When `trueValue` is `false`, the display is inverted.
+- The `tooltip` prop is kept for backward compatibility (legacy vc-shell code used it as hint text). A dev-mode `console.warn` nudges maintainers to migrate. The prop is mapped to `hintText` computed.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-switch/vc-switch.vue`
+
+<!-- internal:end -->

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

@@ -1,7 +1,18 @@
+---
+title: VcTextarea
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcTextarea
 
 A multi-line text input field for entering and editing large blocks of text. Provides label, placeholder, hint text, validation error display, character limits, and multilanguage support out of the box.
 
+::storybook id="form-vctextarea--default"
+
 ## When to Use
 
 - Multi-line free-form text: descriptions, comments, notes, addresses, bios
@@ -99,6 +110,8 @@ const form = reactive({
 
 ### States
 
+::storybook id="form-vctextarea--with-error"
+
 ```vue
 <!-- Required field -->
 <VcTextarea v-model="value" label="Address" required />
@@ -112,6 +125,8 @@ const form = reactive({
 
 ## Recipes
 
+::storybook id="form-vctextarea--with-max-length"
+
 ### Product Description in a Blade Form
 
 A typical product-editing blade with a description textarea and character limit:
@@ -293,3 +308,15 @@ const description = ref<string>("");
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- The native `<textarea>` element is exposed via `defineExpose({ focus })` so parent components can call `focus()` programmatically.
+- The `invalid` computed is `props.error || !!props.errorMessage` — either flag alone triggers error styling.
+- There is no debounce on the textarea; all `input` events fire `update:modelValue` immediately.
+- The `disabled` state is inherited from the nearest `VcInputGroup` ancestor via provide/inject (when used inside a group).
+- Source file: `framework/ui/components/molecules/vc-textarea/vc-textarea.vue`
+
+<!-- internal:end -->

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

@@ -1,3 +1,12 @@
+---
+title: VcToast
+category: components
+group: feedback
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props-component) · [Events](#events) · [Notification Service Methods](#notification-service-methods) · [CSS Variables](#css-variables)
+
 # VcToast
 
 Toast notification component with type-based styling, auto-dismiss timer, swipe-to-dismiss on touch devices, and Sonner-style stacking animations. Most applications interact with toasts through the `notification` service rather than mounting the component directly.
@@ -17,6 +26,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="overlay-vctoast--notification-service"
+
 The recommended approach is the `notification` service, not direct component usage:
 
 ```ts
@@ -98,6 +109,8 @@ Available positions: `"top-center"`, `"top-right"`, `"top-left"`, `"bottom-cente
 
 ### Notification Types
 
+::storybook id="overlay-vctoast--success"
+
 Each type displays a distinct icon and colored left accent border.
 
 | Type      | Icon           | Accent Color             | Use Case                     |
@@ -129,6 +142,8 @@ notification(OrderNotification, { timeout: 10000, pauseOnHover: true });
 
 ### Stacking, Swipe, and Auto-dismiss
 
+::storybook id="overlay-vctoast--multiple-notifications"
+
 Toasts use Sonner-style stacking: the newest toast is in front, older toasts scale down behind it, and hovering expands the full stack. Only 3 toasts are visible by default in the collapsed state.
 
 On touch devices, horizontal swipe dismisses toasts (threshold: 45px or velocity > 0.11px/ms).
@@ -298,3 +313,16 @@ These props are used internally by the notification system. You rarely need to s
 
 - [VcHint](../../atoms/vc-hint/) -- inline hint/error text for form fields
 - [VcIcon](../../atoms/vc-icon/) -- used internally for type-specific icons
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `VcToast` is managed by the notification system's container component (in `framework/shell/_internal/notifications/`). Direct mounting is unusual and bypasses the stacking/positioning logic.
+- Stacking CSS uses data attributes (`data-mounted`, `data-removed`, `data-expanded`, `data-front`, `data-y-position`, `data-visible`, `data-swiping`, `data-swiped-out`) rather than class bindings for animation state — this matches the Sonner pattern and avoids Vue transition conflicts.
+- `TIME_BEFORE_UNMOUNT = 200ms` — the toast sets `data-removed="true"` to trigger CSS exit animation, then emits `close` after 200ms to remove it from the reactive list.
+- The `Timer` helper (defined inline) is a pauseable/resumeable setTimeout — `pause()` records remaining time, `resume()` restarts from remaining. Used for `pauseOnHover`.
+- Height reporting via `ResizeObserver` + `onReportHeight` callback allows the container to compute accurate stack offsets using `getBoundingClientRect()` on an `height: auto` snapshot.
+- Swipe detection uses pointer capture (`setPointerCapture`) to track moves even when the pointer leaves the element. Threshold: 45px displacement or velocity > 0.11 px/ms.
+
+<!-- internal:end -->

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

@@ -1,7 +1,18 @@
+---
+title: VcApp
+category: components
+group: layout
+---
+
 # VcApp
 
 The root application shell that bootstraps the VirtoCommerce admin UI. It provides the desktop sidebar / mobile top bar layout, blade navigation workspace, popup container, module loading, and service registration. Every VirtoCommerce admin application must render exactly one `VcApp` at the root of its authenticated route tree.
 
+::storybook id="layout-vcapp--desktop-expanded"
+
+!!! note "One VcApp per application"
+Every VirtoCommerce admin application must render exactly one `VcApp` at the root of its authenticated route tree. Multiple instances cause service registration conflicts.
+
 ## When to Use
 
 - Every VirtoCommerce admin application must have exactly one `VcApp` at the root.
@@ -59,6 +70,8 @@ const user = reactive({ name: "John", role: "Admin" });
 | `workspace`      | `{ isAuthenticated }`                                                       | Override the blade navigation workspace.                                                                              |
 | `app-hub`        | `{ appsList, switchApp }`                                                   | Custom content for the Applications section of the App Hub.                                                           |
 
+<!-- internal:start -->
+
 ## Architecture
 
 VcApp orchestrates several internal systems:
@@ -68,6 +81,8 @@ VcApp orchestrates several internal systems:
 3. **Module Loading** -- consumes `DynamicModulesKey` for runtime module registration; shows error notifications on failure. Modules declare routes, menu items, and services.
 4. **Services** -- bootstraps shell services (Menu, Toolbar, Settings, Dashboard, GlobalSearch, etc.) via `useShellBootstrap`. These services are available to all child components through provide/inject.
 
+<!-- internal:end -->
+
 ## Features
 
 ### Responsive Layout Switching
@@ -76,6 +91,8 @@ On desktop viewports, VcApp renders a collapsible sidebar on the left with navig
 
 ### Sidebar Menu Search
 
+::storybook id="layout-vcapp--with-sidebar-search" height="500"
+
 When `showSearch` is `true`, a search input appears at the top of the sidebar (desktop) or mobile navigation panel. It filters menu items in real time (300ms debounce) by matching the search query against translated item titles:
 
 - **Standalone items** — shown if their title contains the query.
@@ -134,6 +151,8 @@ The App Hub is a popover panel (desktop) or a swipeable tab (mobile) that combin
 
 On desktop, the App Hub opens from the sidebar header menu button (`AppHubPopover`). On mobile, it appears as a second tab ("Hub") in the slide-out navigation panel — users can swipe between Menu and Hub tabs.
 
+::storybook id="layout-vcapp--mobile" height="500"
+
 ## Recipe: Minimal App Setup
 
 ```vue

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

@@ -1,7 +1,18 @@
+---
+title: VcAuthLayout
+category: components
+group: layout
+---
+
 # VcAuthLayout
 
 A full-page centered authentication layout for login, registration, password reset, and other auth-related screens. VcAuthLayout renders a vertically and horizontally centered card on top of an optional background image, with a logo, title, subtitle, form content area, and a footer slot for legal links. It is the standard layout for all pre-authentication pages in VirtoCommerce admin applications.
 
+::storybook id="layout-vcauthlayout--default"
+
+!!! warning "Use outside VcApp"
+VcAuthLayout is a full-page layout meant to replace `VcApp`, not nest inside it. Your router should switch between VcAuthLayout (for auth routes) and VcApp (for authenticated routes) at the top level.
+
 ## When to Use
 
 - Use for any authentication page: sign-in, sign-up, password reset, email verification
@@ -132,6 +143,8 @@ The layout uses a `<main>` element as the page landmark and an `<h2>` for the ca
 </template>
 ```
 
+::storybook id="layout-vcauthlayout--with-sso-providers" height="500"
+
 ## Recipe: Password Reset Page
 
 ```vue

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

@@ -1,3 +1,9 @@
+---
+title: VcBlade
+category: components
+group: layout
+---
+
 # VcBlade
 
 The foundational container component of the VirtoCommerce admin shell. Blades are stacked panels -- inspired by the Azure Portal -- that form the primary navigation paradigm. Every screen in a vc-shell application is a blade.
@@ -34,6 +40,8 @@ Traditional admin panels use page-based routing: click a link, the entire viewpo
 | Full-page route without blade stack               | Vue Router view                              |
 | Scrollable content section inside a blade         | [VcContainer](../../molecules/vc-container/) |
 
+::storybook id="navigation-vcblade--default"
+
 Use VcBlade for every screen in a vc-shell application -- it is the standard container that integrates with the navigation system, toolbar, breadcrumbs, and unsaved-changes guards. **Do not use** VcBlade for transient dialogs (use `VcPopup` / `usePopup()`) or for content areas that do not need their own header and close button.
 
 ## Quick Start
@@ -54,7 +62,8 @@ defineOptions({ name: "MyFirstBlade", url: "/my-first-blade" });
 </script>
 ```
 
-> **Tip:** Every blade needs a `name` in `defineOptions`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment.
+!!! tip "Every blade needs a name"
+Every blade must define a `name` in `defineOptions`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment.
 
 ## Blade Anatomy
 
@@ -374,6 +383,8 @@ interface IBladeToolbar {
 
 ## Loading State and Skeleton
 
+::storybook id="navigation-vcblade--loading" height="500"
+
 `loading` shows skeleton placeholders for header, toolbar, and content:
 
 ```vue
@@ -384,6 +395,10 @@ interface IBladeToolbar {
 
 > **Tip:** Content is hidden (not unmounted) while loading, so `onMounted` hooks still fire.
 
+> **Note:** During `loading=true`, the header keeps its **close/expand controls operational** — only the icon, title, and subtitle are replaced with skeleton placeholders. Users can always close or maximize a loading blade. The `actions` slot, breadcrumbs, and modified-status dot are hidden until loading finishes.
+
+> **Note:** The toolbar zone uses an in-place skeleton: `BladeToolbar` itself renders skeleton buttons/widgets when its `loading` prop is true (no separate skeleton component is mounted). On mobile, the toolbar is omitted entirely while loading.
+
 Merge multiple loading sources with `useLoading`:
 
 ```ts
@@ -409,6 +424,8 @@ useBeforeUnload(hasChanges); // Browser tab close warning
 
 ## Custom Banners
 
+::storybook id="navigation-vcblade--custom-banners" height="500"
+
 Add informational, warning, or success banners to a blade programmatically. Banners appear between the header and toolbar, sorted by severity.
 
 ```vue
@@ -675,6 +692,8 @@ openBlade({ name: "ProductsList" });
 | `usePopup()`                                    | Confirmation dialogs and error messages.                                           |
 | `useBladeWidgets()`                             | Register contextual widgets for the blade widget area.                             |
 
+<!-- internal:start -->
+
 ## Content Skeleton Mode
 
 When `loading=true`, VcBlade provides `BladeLoadingKey` to all descendant components via Vue's provide/inject. Each framework UI component automatically renders a skeleton placeholder matching its visual footprint.
@@ -704,3 +723,5 @@ import { useBladeLoading } from "@vc-shell/framework";
 const bladeLoading = useBladeLoading();
 // bladeLoading.value === true when parent VcBlade is loading
 ```
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/composables/table-composables.docs.md

@@ -1,3 +1,10 @@
+---
+title: Table Composables
+category: composables
+group: data
+slug: table-composables
+---
+
 # VcTable Composables
 
 Composables that power VcDataTable's functionality. Each handles a single concern and is wired together by the table component. Module developers rarely use these directly -- they are consumed internally by `VcDataTable.vue`.
@@ -144,14 +151,32 @@ register({
 
 - `useTableColumns` never removes entries from `columnState` — hidden columns preserve their weight and order for when they reappear. Use `engineOutput` (not `columnState` directly) to read computed pixel widths for rendering.
 - Call `recompute()` (returned by `useTableColumns`) whenever the container width changes to force the engine to redistribute widths without altering weights.
-- `useDataTableState` stores the v2 schema (weights, order, hidden/shown IDs). It automatically migrates v1 state (pixel-based) on the first restore. Guard against save-during-restore loops with the `isRestoring` flag.
+- `useDataTableState` stores the v2 schema (weights, order, hidden/shown IDs). It auto-migrates v1 state (pixel-based) on the first restore.
 - `useColumnWidthEngine` functions are pure — pass immutable copies of `specs` when testing or previewing layouts without committing to state.
+- `useVirtualScroll` requires a fixed `itemSize` (row height in pixels) for accurate positioning.
+
+<!-- internal:start -->
+
+### Contributor notes
+
+- `useDataTableState`: Guard against save-during-restore loops with the `isRestoring` flag.
 - `useTableRowReorder`: `event.preventDefault()` in `dragover` MUST be called on every event or `drop` never fires.
 - `useTableColumnsResize` applies DOM-level px changes during drag for 60fps performance, then commits final weights to `columnState` on mouseup. No `ResizeObserver` scaling is involved.
-- `useVirtualScroll` requires a fixed `itemSize` (row height in pixels) for accurate positioning.
+
+<!-- internal:end -->
 
 ## Related
 
-- `framework/ui/components/organisms/vc-table/VcDataTable.vue` -- main consumer
-- `framework/ui/components/organisms/vc-table/VcTableAdapter.vue` -- legacy API adapter
-- `framework/ui/components/organisms/vc-table/components/` -- sub-components (TableHead, TableRow, cells)
+- [VcDataTable](../../vc-data-table) -- the main consumer of these composables
+- [VcColumn](../../vc-data-table) -- declarative column definitions
+
+<!-- internal:start -->
+
+## Source references
+
+- `framework/ui/components/organisms/vc-data-table/VcDataTable.vue` -- main consumer
+- `framework/ui/components/organisms/vc-data-table/VcTableAdapter.vue` -- legacy API adapter
+- `framework/ui/components/organisms/vc-data-table/components/` -- sub-components (TableHead, TableRow, cells)
+- `framework/ui/components/organisms/vc-data-table/composables/` -- full composable list
+
+<!-- internal:end -->

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

@@ -1,3 +1,9 @@
+---
+title: VcDataTable
+category: components
+group: data-display
+---
+
 # VcDataTable
 
 The flagship data table component for VirtoCommerce admin shell. VcDataTable provides a fully declarative, template-driven API for building interactive tables with sorting, selection, inline editing, filtering, pagination, column management, row reordering, and more.
@@ -107,6 +113,8 @@ const products = ref([
 
 > **Note:** Each item must have a unique identifier field. The default is `id` -- override with the `data-key` prop if your field is named differently (e.g., `data-key="sku"`).
 
+::storybook id="data-display-vcdatatable--basic"
+
 ---
 
 ## Column Types
@@ -207,6 +215,8 @@ For any rendering not covered by built-in types, use the `#body` slot:
 
 ## Sorting
 
+::storybook id="data-display-vcdatatable--with-sorting" height="500"
+
 ### Single Column Sort
 
 Mark columns as sortable and bind the sort state:
@@ -293,6 +303,8 @@ When the backend sort field differs from the column id:
 
 ## Selection
 
+::storybook id="data-display-vcdatatable--with-selection" height="450"
+
 ### Multiple Selection (checkboxes)
 
 ```vue
@@ -1015,6 +1027,9 @@ async function loadNextPage() {
 
 ## State Persistence
 
+!!! tip "Use unique state keys"
+Every table in your application must have a distinct `state-key`. Two tables sharing the same key will silently overwrite each other's persisted column widths, order, and sort state.
+
 Persist column widths, column order, hidden columns, sort, and filters across page reloads:
 
 ```vue
@@ -1862,6 +1877,9 @@ function onRowRemove(event: { data: PriceEntry; cancel: () => void }) {
 
 ## Common Mistakes
 
+!!! warning "Performance: avoid mutating the items array in-place"
+Always replace `items` with a new array reference instead of using `splice` or `push` directly on the reactive array. Vue cannot track in-place mutations reliably in all scenarios, and VcDataTable's row reorder logic depends on receiving a fresh array to reset the pending-reorder state.
+
 ### 1. Missing `dataKey` with non-`id` identifiers
 
 ```vue

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

@@ -1,7 +1,15 @@
+---
+title: VcDynamicProperty
+category: components
+group: form
+---
+
 # VcDynamicProperty
 
 Renders a VirtoCommerce platform dynamic property as the appropriate form control, automatically selecting the input component based on value type, dictionary, and multivalue flags. VcDynamicProperty eliminates the need for manual `v-if` chains when rendering properties whose type is determined at runtime — it maps each combination of `valueType`, `dictionary`, and `multivalue` to the correct input molecule and passes through all relevant props.
 
+::storybook id="data-display-vcdynamicproperty--default"
+
 ## When to Use
 
 - Use to render dynamic properties from the VirtoCommerce platform (catalog properties, member properties, store properties, etc.)
@@ -44,6 +52,8 @@ Renders a VirtoCommerce platform dynamic property as the appropriate form contro
 | `measurementsGetter` | `Function` | -       | Async loader for measurement units                                            |
 | `rules`              | `object`   | -       | Validation rules: `{ min, max, regex }`                                       |
 
+::storybook id="data-display-vcdynamicproperty--property-form" height="500"
+
 ## Value Type to Component Mapping
 
 | valueType | dictionary | multivalue | Component                    |
@@ -109,6 +119,8 @@ function handlePropertyUpdate(property: any, newValue: any) {
 </template>
 ```
 
+::storybook id="data-display-vcdynamicproperty--required-with-validation" height="300"
+
 ## Recipe: Dynamic Property with Validation
 
 ```vue

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

@@ -1,7 +1,15 @@
+---
+title: VcGallery
+category: components
+group: data-display
+---
+
 # VcGallery
 
 A responsive multi-image gallery with drag-and-drop reorder, file upload, lightbox preview, and per-image actions. VcGallery renders images in a CSS grid that auto-fills based on the container width, with a built-in upload zone tile at the end of the grid. It is the standard component for managing collections of images such as product photos, media libraries, and document attachments.
 
+::storybook id="data-display-vcgallery--default"
+
 ## When to Use
 
 - Use **VcGallery** for multi-image fields (product images, media libraries, banner collections).
@@ -64,12 +72,16 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 <VcGallery label="Product Images" required :images="product.images" imagefit="cover" @upload="handleUpload" @sort="handleSort" @edit="handleEdit" @remove="handleRemove" />
 ```
 
+::storybook id="data-display-vcgallery--filmstrip-default" height="400"
+
 ## Filmstrip Layout (Default)
 
 ```vue
 <VcGallery label="Images" :images="product.images" imagefit="cover" @upload="handleUpload" @sort="handleSort" @remove="handleRemove" />
 ```
 
+::storybook id="data-display-vcgallery--grid-layout" height="400"
+
 ## Classic Grid Layout
 
 ```vue
@@ -128,6 +140,8 @@ function handleRemove(image: ICommonAsset) {
 </template>
 ```
 
+::storybook id="data-display-vcgallery--disabled" height="300"
+
 ## Recipe: Read-Only Gallery (Disabled)
 
 ```vue

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

@@ -1,7 +1,15 @@
+---
+title: VcImageUpload
+category: components
+group: media
+---
+
 # VcImageUpload
 
 A single-image upload organism that displays either a drag-and-drop upload zone or an image tile with preview and remove actions. VcImageUpload manages three visual states automatically: an interactive dropzone when no image is set, an image tile with action overlays when an image is provided, and a disabled empty state with a hint message. It integrates with vee-validate for file validation (size, format) and supports lightbox preview via the built-in VcImageTile component.
 
+::storybook id="data-display-vcimageupload--empty"
+
 ## When to Use
 
 - Use **VcImageUpload** for single-image fields (avatar, logo, thumbnail, hero image).
@@ -31,6 +39,8 @@ A single-image upload organism that displays either a drag-and-drop upload zone
 | `upload` | `FileList`     | Emitted when files are selected or dropped. |
 | `remove` | `ICommonAsset` | Emitted when the remove button is clicked.  |
 
+::storybook id="data-display-vcimageupload--with-image" height="300"
+
 ## Visual States
 
 The component has three visual states:
@@ -83,6 +93,8 @@ function handleRemove() {
 </template>
 ```
 
+::storybook id="data-display-vcimageupload--loading" height="250"
+
 ## Recipe: Conditional Upload with Loading State
 
 ```vue