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

package/runtime/knowledge/docs/modules/assets/assets-details.docs.md

@@ -0,0 +1,123 @@
+---
+title: Assets Module
+category: reference
+group: modules
+slug: assets
+---
+
+# Assets Details Module
+
+A built-in child blade for editing a single asset's metadata: display name, alt text (images only), and description. Opened by `AssetsManager` when the user clicks a table row, but also usable standalone from any parent blade that needs single-asset editing.
+
+## Overview
+
+The blade reads an `AssetLike` instance from `options.asset`, exposes a form pre-populated from it, and delegates persistence back to the caller through two callbacks (`assetEditHandler`, `assetRemoveHandler`). The blade itself never mutates the original asset and never talks to the network — the caller decides what saving and removing means.
+
+The module is registered as `AssetsDetailsModule` and exposes the `AssetsDetails` blade (registered globally under the name `"AssetsDetails"`).
+
+## Module Registration
+
+```typescript
+import { AssetsDetailsModule } from "@vc-shell/framework";
+
+// Registered automatically when the framework loads
+// Exposes: AssetsDetails blade component
+```
+
+## Options (via `useBlade`)
+
+The blade reads its configuration from `options` via `useBlade<AssetsDetailsOptions>()` (not props):
+
+| Option               | Type                                          | Description                                                                                                                                   |
+| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asset`              | `AssetLike`                                   | The asset to edit. The blade clones it into local state — the source object is never mutated until `assetEditHandler` is called.              |
+| `disabled`           | `boolean?`                                    | When true, every input is read-only and the toolbar Save/Delete buttons are disabled.                                                         |
+| `hiddenFields`       | `string[]?`                                   | Field names to hide. Supported values: `"name"`, `"altText"`, `"description"`. The header (preview, size, created date, URL) is always shown. |
+| `assetEditHandler`   | `(asset: AssetLike) => void \| Promise<void>` | Called by the toolbar Save button with the edited copy. The blade closes itself after the handler resolves.                                   |
+| `assetRemoveHandler` | `(asset: AssetLike) => Promise<void>`         | Called by the toolbar Delete button. The blade closes itself after the handler resolves.                                                      |
+
+## Usage
+
+### Direct invocation
+
+```typescript
+import { useBlade } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
+
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset: selectedAsset,
+    disabled: !canEdit.value,
+    hiddenFields: ["altText"],
+    assetEditHandler: async (edited) => {
+      await api.updateAsset(edited);
+    },
+    assetRemoveHandler: async (asset) => {
+      await api.deleteAsset(asset.id);
+    },
+  },
+});
+```
+
+### Used by AssetsManager
+
+When `AssetsManager` opens this blade on row click, it wires the manager's mutation methods into the handlers automatically:
+
+```typescript
+// inside AssetsManager
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset,
+    disabled: readonly.value,
+    hiddenFields: options.value?.hiddenFields,
+    assetEditHandler: (asset) => manager.updateItem(asset),
+    assetRemoveHandler: (asset) => manager.remove(asset),
+  },
+});
+```
+
+## Header
+
+The header is always rendered above the editable form and is not configurable through `hiddenFields`:
+
+| Element      | Source                                                                                             |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| Preview      | `VcImage` thumbnail for image extensions (png/jpg/jpeg/svg/gif), colored extension badge otherwise |
+| Size         | `readableSize(asset.size)` — formatted as `KB`/`MB`/`GB`                                           |
+| Created date | `asset.createdDate` rendered with `type="date-ago"`                                                |
+| URL          | `asset.url` displayed as a copyable link with `asset.name` as the visible label                    |
+
+## Form fields
+
+All fields are bound to a local clone of `asset`. They can be hidden individually via `hiddenFields`.
+
+| Field         | Visibility                                        | Notes                                                                                                                          |
+| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | Hidden if `hiddenFields` includes `"name"`        | Required. Edits the **base name only** — the original extension is preserved on save (e.g. editing `report.pdf` keeps `.pdf`). |
+| `altText`     | Image assets only; hide via `"altText"`           | Plain string. Shown only when `asset.typeId === "Image"`.                                                                      |
+| `description` | Hidden if `hiddenFields` includes `"description"` | Multiline textarea.                                                                                                            |
+
+## Toolbar
+
+| Button | Disabled condition                                                                                                  | Action                                                      |
+| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Save   | `disabled === true`, the form is invalid, or the form is not dirty (vee-validate `useIsFormValid`/`useIsFormDirty`) | `await assetEditHandler(editedAsset)`, then `closeSelf()`   |
+| Delete | `disabled === true`                                                                                                 | `await assetRemoveHandler(editedAsset)`, then `closeSelf()` |
+
+## Tips
+
+- **Extension is locked.** The `name` input only edits the base name; the original extension is reattached on save. Renaming `photo.png` to `cover` produces `cover.png`.
+- **Required name validation** uses vee-validate's `required` rule. The Save button stays disabled until validation passes.
+- **`assetEditHandler`** is invoked with the edited clone — the original `options.asset` reference is never mutated. Callers should treat the argument as the new state.
+- **`disabled` makes the blade fully read-only:** inputs are disabled and toolbar Save/Delete are disabled regardless of dirtiness.
+- **`hiddenFields` does not enforce required-ness.** Hiding `"name"` skips the validated `<Field>`, so the Save button only depends on form dirtiness.
+
+## Related
+
+- `framework/modules/assets-manager/` -- parent `AssetsManager` blade that opens `AssetsDetails` on row click
+- `framework/core/composables/useAssetsManager/` -- `AssetLike` type definition
+- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
+- `framework/ui/components/molecules/vc-field/` -- `VcField` used by the header for size/date/url

package/runtime/knowledge/docs/modules/assets-manager/assets-manager.docs.md

@@ -1,3 +1,10 @@
+---
+title: Assets Manager
+category: reference
+group: modules
+slug: assets-manager
+---
+
 # Assets Manager Module
 
 A built-in blade module for managing file assets (images, documents, archives). Provides upload, delete, reorder, and preview functionality via a table-based UI.
@@ -32,17 +39,27 @@ The blade reads its configuration from `options` via `useBlade<AssetsManagerOpti
 
 ## Usage
 
-Open the Assets Manager as a child blade:
+The canonical pattern is to bind the manager to a writable `computed` over a field of the parent entity, so that uploads/removes/reorders propagate back into the form. `confirmRemove` is wired to the framework's popup service rather than `window.confirm`.
 
 ```typescript
-import { markRaw } from "vue";
-import { useBlade, useAssetsManager } from "@vc-shell/framework";
+import { computed, markRaw } from "vue";
+import { useBlade, useAssetsManager, usePopup } from "@vc-shell/framework";
 
 const { openBlade } = useBlade();
+const { showConfirmation } = usePopup();
+
+// Two-way binding: the manager mutates `productAssets.value`, which writes
+// straight back to `item.value.productData.assets`.
+const productAssets = computed({
+  get: () => item.value?.productData?.assets ?? [],
+  set: (val) => {
+    if (item.value?.productData) item.value.productData.assets = val;
+  },
+});
 
-const assetsManager = useAssetsManager(product.assets, {
-  uploadPath: () => `/catalog/${product.id}`,
-  confirmRemove: () => confirm("Delete selected assets?"),
+const assetsManager = useAssetsManager(productAssets, {
+  uploadPath: () => `/catalog/${item.value?.id}`,
+  confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"),
 });
 
 openBlade({
@@ -54,7 +71,6 @@ openBlade({
     // manager.items.value and manager.loading.value access.
     manager: markRaw(assetsManager),
     disabled: !canEdit.value,
-    hiddenFields: ["sortOrder"],
   },
 });
 ```
@@ -66,8 +82,8 @@ openBlade({
 - **Delete**: Toolbar delete button (requires selection) and per-row action button.
 - **Reorder**: Drag-and-drop row reordering when not in readonly mode.
 - **Detail view**: Clicking a row opens an `AssetsDetails` child blade for single-asset editing.
-- **Mobile**: Responsive card layout for mobile viewports.
-- **Empty state**: Shows upload prompt when no assets exist (or "No assets" in readonly mode).
+- **Non-image assets**: Files without an image extension render a colored badge with the uppercased extension (`PDF`, `DOCX`, `ZIP`, ...) instead of a thumbnail.
+- **Empty state**: Shows upload prompt when no assets exist; the empty-state action button opens the file picker.
 
 ## Toolbar
 
@@ -81,11 +97,72 @@ openBlade({
 - **Always use `markRaw()` when passing manager through blade options.** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects, so `manager.items` would become a plain array instead of `Ref<AssetLike[]>` — breaking `.value` access. `markRaw()` prevents this by telling Vue not to make the manager reactive.
 - The `manager` object (from `useAssetsManager()`) owns the reactive asset list and all mutation methods. The blade reads `manager.items` and calls `manager.upload()`, `manager.remove()`, `manager.removeMany()`, `manager.reorder()`, and `manager.updateItem()`.
 - The `disabled` prop makes the entire blade readonly: no upload, no delete, no reorder.
-- Asset thumbnails use `isImage()` from shared utilities to determine if an image preview or a file-type icon should be shown.
+- Asset thumbnails use `isImage()` from `@core/utilities/assets` to decide between an image preview (`VcImage`) and a colored extension badge (`getExtensionColor` + `getExtensionLabel`).
 - The module uses `useBlade()` internally to open the detail sub-blade.
+- The `manager` instance can be reused as a `useBladeWidgets` badge source — its `items.value.length` updates reactively as uploads/removes happen inside the blade, so a parent widget showing the asset count refreshes without an extra round-trip.
+
+## Recipes
+
+### Open from a blade widget
+
+Most callers don't open `AssetsManager` directly — they expose it as one of the parent blade's widgets. The widget shows the asset count as a live badge and opens the manager on click. The manager is created once per parent blade and reused across openings.
+
+```typescript
+import { computed, markRaw, type Ref, type ComputedRef } from "vue";
+import { useBlade, useBladeWidgets, useAssetsManager, usePopup } from "@vc-shell/framework";
+
+interface Entity {
+  id?: string;
+  productData?: { assets?: Asset[] };
+}
+
+export function useEntityWidgets(opts: { item: Ref<Entity | undefined>; disabled: ComputedRef<boolean>; isVisible: ComputedRef<boolean> }) {
+  const { item, disabled, isVisible } = opts;
+  const { openBlade } = useBlade();
+  const { showConfirmation } = usePopup();
+
+  const entityAssets = computed({
+    get: () => item.value?.productData?.assets ?? [],
+    set: (val) => {
+      if (item.value?.productData) item.value.productData.assets = val;
+    },
+  });
+
+  const assetsManager = useAssetsManager(entityAssets, {
+    uploadPath: () => `/catalog/${item.value?.id}`,
+    confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"),
+  });
+
+  const assetsCount = computed(() => entityAssets.value.length);
+
+  return useBladeWidgets([
+    {
+      id: "AssetsWidget",
+      icon: "lucide-file",
+      title: "WIDGETS.ASSETS",
+      badge: assetsCount,
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "AssetsManager",
+          options: {
+            manager: markRaw(assetsManager),
+            disabled: disabled.value,
+          },
+        }),
+    },
+  ]);
+}
+```
+
+Key points:
+
+- `useAssetsManager` is invoked once at widget-setup time, not inside `onClick`. Recreating it per click would lose pending state and break optimistic updates.
+- `disabled.value` is unwrapped at click time. Passing the raw `ComputedRef` would work too, but the blade reads `options.value?.disabled` as a plain value.
+- `assetsCount` reads from the source array (not from `assetsManager.items`), but both stay in sync because the manager mutates the same array via the setter.
 
 ## Related
 
 - `framework/core/composables/useAssetsManager/` -- `useAssetsManager`, `AssetLike`, `UseAssetsManagerReturn`
-- `framework/shared/utilities/assets.ts` -- `isImage`, `getFileThumbnail`, `readableSize`
-- `framework/core/utilities/date/` -- `formatDateRelative` for creation dates
+- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
+- `framework/modules/assets/components/assets-details/` -- `AssetsDetails` child blade opened on row click

package/runtime/knowledge/docs/shell/_internal/popup/common/popup-common.docs.md

@@ -1,3 +1,10 @@
+---
+title: PopupCommon
+category: composables
+group: utilities
+internal: true
+---
+
 # Popup Common Components
 
 Pre-configured popup variants for warning, error, and info dialogs. Built on a shared `VcPopupBase` component that wraps the `VcPopup` organism.

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

@@ -1,3 +1,10 @@
+---
+title: ChangePasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ChangePasswordPage
 
 Change password page with current, new, and confirm password fields. Supports a `forced` mode for expired passwords that displays an info banner and is triggered by post-login redirect. This full-page variant is used when the user must change their password before accessing the application (e.g., expired password policy). For voluntary password changes from within the app, the `ChangePasswordButton` in the settings menu opens a popup instead.

package/runtime/knowledge/docs/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: ForgotPasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ForgotPasswordPage
 
 Password recovery page where the user enters their email to receive a reset link. Shows a masked-email confirmation on success. This page is part of the standard authentication flow in vc-shell and handles the first step of password recovery: collecting the user's email address and dispatching a reset email through the platform API.

package/runtime/knowledge/docs/shell/auth/InvitePage/invite-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: InvitePage
+category: composables
+group: utilities
+internal: true
+---
+
 # InvitePage
 
 Invitation acceptance page where an invited user sets their password. Validates the invitation token on mount, displays the pre-filled email, and provides password/confirm fields. On successful acceptance, the user is automatically signed in and redirected to the main application. This page is the final step in the user invitation flow initiated from the VirtoCommerce Platform admin.

package/runtime/knowledge/docs/shell/auth/LoginPage/login-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: LoginPage
+category: composables
+group: utilities
+internal: true
+---
+
 # LoginPage
 
 Full-page login screen with username/password form, SSO external provider support, and forgot-password navigation. Wraps `VcAuthLayout` and uses `useUserManagement` for authentication. This is the primary entry point for user authentication in vc-shell applications, supporting both standard credential-based login and SSO/external provider authentication.

package/runtime/knowledge/docs/shell/auth/ResetPasswordPage/reset-password-page.docs.md

@@ -1,3 +1,10 @@
+---
+title: ResetPasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ResetPasswordPage
 
 Password reset page reached via an email link containing a token. Validates the token on mount, then shows password and confirm-password fields. On success, the user is automatically signed in and redirected to the main application. This page is the second step of the password recovery flow, following the `ForgotPasswordPage` which dispatches the reset email.

package/runtime/knowledge/docs/shell/auth/sign-in/sign-in.docs.md

@@ -1,3 +1,10 @@
+---
+title: SignIn
+category: composables
+group: utilities
+internal: true
+---
+
 # SignIn (External Providers)
 
 Components and composable for SSO / external authentication provider integration. Renders provider buttons on the login page and handles the external sign-in redirect flow. This module supports any OAuth2/OpenID Connect provider configured on the VirtoCommerce Platform (Google, Azure AD, ADFS, Okta, etc.) and provides a clean abstraction over the redirect-based authentication flow.

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

@@ -1,3 +1,10 @@
+---
+title: ChangePassword
+category: composables
+group: utilities
+internal: true
+---
+
 # Change Password Component
 
 A modal dialog for changing the current user's password, with real-time validation and forced-change support.

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

@@ -1,3 +1,10 @@
+---
+title: ChangePasswordButton
+category: composables
+group: utilities
+internal: true
+---
+
 # ChangePasswordButton
 
 Settings menu action that opens the change-password popup through the popup handler system. This component bridges the settings menu and the password change form: it injects `CloseSettingsMenuKey` to dismiss the parent menu before showing the password popup, ensuring a clean transition. The popup itself renders a form with current password, new password, and confirm password fields, with real-time password policy validation.

package/runtime/knowledge/docs/shell/components/error-interceptor/error-interceptor.docs.md

@@ -1,3 +1,10 @@
+---
+title: ErrorInterceptor
+category: composables
+group: utilities
+internal: true
+---
+
 # Error Interceptor
 
 A renderless component that captures Vue `onErrorCaptured` errors and surfaces them to child slots or the blade error banner.

package/runtime/knowledge/docs/shell/components/language-selector/language-selector.docs.md

@@ -1,3 +1,10 @@
+---
+title: LanguageSelector
+category: composables
+group: utilities
+internal: true
+---
+
 # LanguageSelector
 
 Settings menu entry that displays the current UI language and opens a cascading submenu for switching between available locales. Uses the framework `useLanguages` composable and the global vue-i18n locale list. When the user selects a different language, the entire application UI updates immediately without a page reload.

package/runtime/knowledge/docs/shell/components/logout-button/logout-button.docs.md

@@ -1,3 +1,10 @@
+---
+title: LogoutButton
+category: composables
+group: utilities
+internal: true
+---
+
 # LogoutButton
 
 Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeStack()` to close open child blades so the user does not return to stale blade state on next login.

package/runtime/knowledge/docs/shell/components/notification-dropdown/notification-dropdown.docs.md

@@ -1,3 +1,10 @@
+---
+title: NotificationDropdown
+category: composables
+group: utilities
+internal: true
+---
+
 # NotificationDropdown
 
 Dropdown panel that displays the push notification history in reverse chronological order. This component renders a scrollable list of all received push notifications, backed by the `useNotifications()` composable. It automatically marks unread notifications as read when the dropdown is closed (unmounted), updating the unread badge count in the toolbar.

package/runtime/knowledge/docs/shell/components/notification-template/notification-template.docs.md

@@ -1,3 +1,10 @@
+---
+title: NotificationTemplate
+category: composables
+group: utilities
+internal: true
+---
+
 # NotificationTemplate
 
 Base template for rendering a single push notification with title, relative timestamp, optional icon, and a default slot for extra detail content. This component provides the standard layout that all notification types share, while allowing domain-specific content to be injected through the default slot.

package/runtime/knowledge/docs/shell/components/settings-menu/settings-menu.docs.md

@@ -1,3 +1,10 @@
+---
+title: SettingsMenu
+category: composables
+group: utilities
+internal: true
+---
+
 # SettingsMenu
 
 Container component that renders registered settings menu items grouped by category and sorted by order. Items are registered through the `useSettingsMenu` service, not through component props. This decoupled architecture allows any module in the application to contribute settings entries without modifying the menu component itself.

package/runtime/knowledge/docs/shell/components/settings-menu-item/settings-menu-item.docs.md

@@ -1,3 +1,10 @@
+---
+title: SettingsMenuItem
+category: composables
+group: utilities
+internal: true
+---
+
 # SettingsMenuItem
 
 Individual menu row used inside the settings menu. Displays an icon, title, optional current value, and a chevron indicator for sub-menus. Supports click and hover trigger actions.

package/runtime/knowledge/docs/shell/components/sidebar/sidebar.docs.md

@@ -1,3 +1,10 @@
+---
+title: Sidebar
+category: composables
+group: utilities
+internal: true
+---
+
 # Sidebar Component
 
 A responsive sidebar wrapper that conditionally renders content inside a `VcSidebar` panel or inline, based on viewport and expansion state.

package/runtime/knowledge/docs/shell/components/theme-selector/theme-selector.docs.md

@@ -1,3 +1,10 @@
+---
+title: ThemeSelector
+category: composables
+group: utilities
+internal: true
+---
+
 # ThemeSelector
 
 Settings menu entry that shows the current theme and opens a cascading submenu to switch between registered themes. Uses the `useTheme()` composable for theme management and shows a toast notification when the theme changes, confirming the switch to the user.

package/runtime/knowledge/docs/shell/components/user-dropdown-button/user-dropdown-button.docs.md

@@ -1,3 +1,10 @@
+---
+title: UserDropdownButton
+category: composables
+group: utilities
+internal: true
+---
+
 # UserDropdownButton
 
 User account trigger displayed in the shell sidebar footer. Shows the user's avatar, display name, and role. On desktop it opens a floating settings menu dropdown anchored to the button; on mobile it opens a full sidebar panel that slides in from the left. The component automatically adapts its layout based on the sidebar's expanded/collapsed state.

package/runtime/knowledge/docs/shell/dashboard/dashboard-charts/dashboard-charts.docs.md

@@ -1,3 +1,10 @@
+---
+title: DashboardCharts
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardCharts
 
 Suite of dashboard chart components (line, bar, donut) built on Unovis. Each chart accepts a generic data array, a `ChartConfig` for series colors/labels, and supports hover tooltips, legends, and optional range filtering.

package/runtime/knowledge/docs/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md

@@ -1,3 +1,10 @@
+---
+title: DashboardWidgetCard
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardWidgetCard
 
 Modern dashboard widget card with header, optional KPI stats area, action buttons, content body, and footer. Used within the GridStack dashboard layout for displaying metrics, feeds, and charts.

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md

@@ -1,3 +1,10 @@
+---
+title: DashboardWidgetSkeleton
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardWidgetSkeleton
 
 Internal placeholder card used by `GridstackDashboard` while remote modules are still loading. Mimics the shape of `DashboardWidgetCard` (header with icon + title, stats row, content lines) with a shimmer animation. Not exported from `@vc-shell/framework` — consumed only inside the dashboard organism.

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md

@@ -1,3 +1,10 @@
+---
+title: DraggableDashboard
+category: composables
+group: utilities
+internal: true
+---
+
 # DraggableDashboard
 
 Gridstack.js-powered dashboard container that renders registered widgets in a drag-and-drop grid layout. Automatically persists layout changes to localStorage and supports widget resizing. This is the main dashboard component used as the landing page in vc-shell applications, providing a customizable overview with KPI widgets, charts, quick actions, and data summaries.

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

@@ -1,7 +1,15 @@
+---
+title: VcBadge
+category: components
+group: misc
+---
+
 # VcBadge
 
 A small indicator component for displaying counts, status dots, or short text labels. Supports two rendering modes: **positioned overlay** on a slotted element (e.g., notification count on a bell icon), or **standalone inline** badge (e.g., a tag/pill label in a list). Inline badges use a softer color palette with tinted backgrounds, while overlay badges use solid fills for maximum contrast.
 
+::storybook id="data-display-vcbadge--default"
+
 ## When to Use
 
 - Show unread notification counts on icons or buttons
@@ -18,6 +26,8 @@ A small indicator component for displaying counts, status dots, or short text la
 </VcBadge>
 ```
 
+::storybook id="data-display-vcbadge--variants" height="300"
+
 ## Key Props
 
 | Prop             | Type                                                                       | Default     | Description                                               |
@@ -34,6 +44,8 @@ A small indicator component for displaying counts, status dots, or short text la
 | `right`          | `string`                                                                   | --          | Custom right offset (requires `customPosition`)           |
 | `ariaLabel`      | `string`                                                                   | --          | Custom accessible label for the badge                     |
 
+::storybook id="data-display-vcbadge--use-cases" height="350"
+
 ## Common Patterns
 
 ### Notification Count on an Icon
@@ -125,3 +137,15 @@ Fine-tune the badge position relative to its parent:
 - [VcIcon](../vc-icon/) -- commonly used as slotted content inside badges
 - [VcBanner](../vc-banner/) -- for longer contextual messages and alerts
 - [VcStatus](../vc-status/) -- labeled multi-variant status indicator
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcBadge lives in `framework/ui/components/atoms/vc-badge/`.
+- Overlay mode uses `position: absolute` on the badge element; the parent slot wrapper is set to `position: relative` via the `.vc-badge` CSS class.
+- The `inline` prop switches the root element from `<span class="vc-badge">` (overlay) to `<span class="vc-badge--inline">` with no position context.
+- Color palette tokens: overlay uses `--{variant}-500` fills; inline uses `--{variant}-50` background + `--{variant}-700` text, defined in `framework/assets/styles/theme/colors.scss`.
+- Clickable mode integrates `role="button"` and keyboard handlers directly in the component — no separate button wrapper — to preserve the overlay stacking context.
+
+<!-- internal:end -->

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

@@ -1,7 +1,15 @@
+---
+title: VcBanner
+category: components
+group: feedback
+---
+
 # VcBanner
 
 A contextual alert component for displaying important messages, warnings, or status information. VcBanner supports four semantic variants (`info`, `warning`, `danger`, `success`), each with a distinct accent color and left border stripe. Long content is automatically collapsed behind a "Show more" toggle, keeping the blade layout clean while still giving users access to the full message.
 
+::storybook id="action-vcbanner--default"
+
 ## When to Use
 
 - Display validation errors or decline reasons on detail blades
@@ -19,6 +27,8 @@ A contextual alert component for displaying important messages, warnings, or sta
 </VcBanner>
 ```
 
+::storybook id="action-vcbanner--all-variants" height="500"
+
 ## Key Props
 
 | Prop              | Type                                           | Default  | Description                                                   |
@@ -157,3 +167,13 @@ Override the default "Show more" button with a custom trigger:
 - [VcCard](../vc-card/) -- for general-purpose content containers
 - [VcIcon](../vc-icon/) -- used internally for the leading icon
 - [VcBadge](../vc-badge/) -- for inline status pill labels
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- Legacy variants `"light-danger"`, `"info-dark"`, and `"primary"` are mapped in `vc-banner.vue` via a computed `resolvedVariant`. A `console.warn` is emitted in development mode only.
+- The collapse animation is driven by `max-height` CSS transition with a JS-measured `scrollHeight`. The `--vc-banner-collapsed-height` CSS variable is injected inline as a style binding.
+- Source: `framework/ui/components/atoms/vc-banner/vc-banner.vue`
+
+<!-- internal:end -->