@vc-shell/vc-app-skill 2.0.3 → 2.0.4-pr228.833ff5f

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

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

@@ -1,3 +1,9 @@
+---
+title: VcPopup
+category: components
+group: feedback
+---
+
 # VcPopup
 
 A modal dialog component built on [HeadlessUI Dialog](https://headlessui.com/vue/dialog). Use it for confirmations, alerts, error messages, and focused form interactions that require the user's immediate attention.
@@ -12,7 +18,10 @@ A modal dialog component built on [HeadlessUI Dialog](https://headlessui.com/vue
 | Side panel for contextual workflows               | VcSidebar   |
 | Stacked detail views (master-detail)              | VcBlade     |
 
-> **Tip:** Prefer blades for CRUD workflows. Reserve popups for brief, interruptive interactions such as confirmations and alerts.
+!!! tip "Prefer blades for CRUD workflows"
+Reserve popups for brief, interruptive interactions such as confirmations and alerts. Use `VcBlade` for CRUD detail views and `VcSidebar` for contextual side panels.
+
+::storybook id="overlay-vcpopup--default"
 
 ---
 
@@ -49,6 +58,8 @@ const showPopup = ref(false);
 
 ### Variants
 
+::storybook id="overlay-vcpopup--variants" height="500"
+
 The `variant` prop adds a semantic icon and color to the popup. Available values: `"default"`, `"info"`, `"success"`, `"warning"`, `"error"`.
 
 ```vue
@@ -248,6 +259,8 @@ Two props control fullscreen behavior:
 
 ### Confirmation Dialog
 
+::storybook id="overlay-vcpopup--with-footer" height="400"
+
 The most common pattern. Uses the `warning` variant and a two-button footer.
 
 ```vue

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

@@ -1,7 +1,18 @@
+---
+title: VcSidebar
+category: components
+group: layout
+---
+
 # VcSidebar
 
 A slide-over panel for contextual workflows, settings, and detail views. Supports left, right, and bottom positions with animated transitions, focus trapping, scroll locking, and swipe-to-dismiss gestures. VcSidebar is built for use cases where a full blade is too heavy but a popup is too small — settings panels, filter drawers, item detail previews, and mobile bottom sheets.
 
+::storybook id="overlay-vcsidebar--elevated-panel"
+
+!!! tip "Sidebar vs Popup vs Blade"
+Use VcSidebar for contextual workflows that need persistent visibility. Use `VcPopup` for brief confirmation dialogs. Use `VcBlade` for primary CRUD content that belongs in the navigation stack.
+
 ## When to Use
 
 - Settings panels, filter drawers, or contextual detail views.
@@ -104,6 +115,8 @@ Override with the `width` or `height` prop for custom dimensions.
 
 ### Bottom Sheet with Swipe-to-Dismiss
 
+::storybook id="overlay-vcsidebar--bottom-sheet" height="500"
+
 ```vue
 <VcSidebar v-model="open" position="bottom" size="md" draggable drag-handle>
   <div class="tw-p-4">Swipe down to close</div>

package/runtime/knowledge/docs/ui/composables/ui-composables.docs.md

@@ -1,3 +1,10 @@
+---
+title: UI Composables
+category: composables
+group: ui-state
+slug: ui-composables-overview
+---
+
 # UI Composables
 
 Shared composables for the VC-Shell UI component library. These provide reusable logic for layout, positioning, form fields, and scroll behavior.

package/runtime/knowledge/docs/ui/composables/useDataTablePagination.docs.md

@@ -1,3 +1,9 @@
+---
+title: useDataTablePagination
+category: composables
+group: data
+---
+
 # useDataTablePagination
 
 Manages page-level pagination state for `VcDataTable`. Derives `pages`, `skip`, `totalCount` from a reactive input, and fires an optional `onPageChange` callback when the page changes. Returns a `reactive()` object — all properties are plain values (no `.value` needed), and the object is directly passable as the VcDataTable `:pagination` prop.
@@ -159,6 +165,6 @@ Blade then simply binds:
 
 ## Related
 
-- [`useDataTableSort`](./useDataTableSort.docs.md) — sort state composable for VcDataTable
-- `VcDataTable` `:pagination` prop — accepts `DataTablePagination` object
-- `DataTablePagination` type — defined in `vc-data-table/types.ts`
+- [`useDataTableSort`](./useDataTableSort.docs.md) -- sort state composable for VcDataTable
+- `VcDataTable` `:pagination` prop -- accepts `DataTablePagination` object
+- `DataTablePagination` -- type exported from `@vc-shell/framework`

package/runtime/knowledge/docs/ui/composables/useDataTableSort.docs.md

@@ -1,3 +1,9 @@
+---
+title: useDataTableSort
+category: composables
+group: data
+---
+
 # useDataTableSort
 
 Manages page-level sort state for `VcDataTable` using numeric sort order conventions (`1` = ASC, `-1` = DESC, `0` = none). Provides `sortField` and `sortOrder` refs for `v-model` binding directly on `VcDataTable`, plus a `sortExpression` computed string for API calls.

package/runtime/knowledge/docs/ui/composables/useTableSelection.docs.md

@@ -1,3 +1,9 @@
+---
+title: useTableSelection
+category: composables
+group: data
+---
+
 # useTableSelection
 
 Manages table row selection state including multi-select, select-all, and programmatic selection. This composable provides a complete external selection API for VcDataTable, enabling bulk operations like delete, export, or status changes on selected rows.

package/runtime/knowledge/docs/ui/composables/useTableSort.docs.md

@@ -1,3 +1,9 @@
+---
+title: useTableSort
+category: composables
+group: data
+---
+
 # useTableSort
 
 Manages table sort state with three-state cycling (ASC, DESC, none) and a formatted sort expression string. This composable externalizes the sort logic from VcDataTable, making it easy to drive server-side sorting, persist sort preferences, or share sort state across multiple components.

package/runtime/knowledge/docs/ui/types/ui-types.docs.md

@@ -1,3 +1,10 @@
+---
+title: UI Types
+category: reference
+group: api
+slug: types-ui
+---
+
 # UI Types
 
 TypeScript interfaces for UI component props shared across all form field components in the framework.

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

@@ -1,28 +0,0 @@
-# usePlatformLocaleSync
-
-One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
-
-Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used.
-
-## When to Use
-
-- Never call directly from feature code. This is a framework-internal sync primitive.
-- It is invoked once per `VcApp` mount from `useShellBootstrap`.
-
-## Behaviour
-
-- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity.
-- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`.
-- On subsequent changes of the platform key, re-applies the value.
-- Skips empty strings (platform clearing the key does not blank the shell locale).
-- Skips values equal to `currentLocale` to avoid redundant re-configuration.
-
-## How It Works
-
-`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`.
-
-The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener.
-
-## Relationship to `VC_LANGUAGE_SETTINGS`
-
-The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side.