npm - @vc-shell/vc-app-skill - Versions diffs - 2.1.0 → 2.2.0-pr260.a8bd3a7 - Mend

@vc-shell/vc-app-skill 2.1.0 → 2.2.0-pr260.a8bd3a7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

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

@@ -7,6 +7,8 @@ internal: true
 # Sidebar Component
+> **Deprecated.** The `Sidebar` wrapper is deprecated in favor of `VcSidebar` (`framework/ui/components/organisms/vc-sidebar`) and may be removed in a future release. Use this page as legacy/migration guidance only; build new code on `VcSidebar` directly.
 A responsive sidebar wrapper that conditionally renders content inside a `VcSidebar` panel or inline, based on viewport and expansion state.
 ## Overview
@@ -62,7 +64,7 @@ When `render="mobile"` and the viewport is desktop, the content slot renders inl
 ## Behavior
-- **Visibility**: The sidebar is visible when `isExpanded === true` AND the `render` mode matches the current viewport (injected via `IsMobileKey` / `IsDesktopKey`).
+- **Visibility**: The sidebar is visible when `isExpanded === true` AND the `render` mode matches the current viewport (resolved via `useResponsive()` -- `isMobile` / `isDesktop`).
 - **Teleport**: On mobile, the inner `VcSidebar` teleports to the document body for proper overlay stacking.
 - **Close**: Closing the sidebar emits `close` -- the parent must update `isExpanded`.
@@ -70,9 +72,9 @@ When `render="mobile"` and the viewport is desktop, the content slot renders inl
 - Use `render="mobile"` for panels that should be drawers on phones but inline panels on desktop.
 - The `header` slot receives a `close` function so custom headers can include their own close button.
-- The component injects `IsMobileKey` and `IsDesktopKey` from the framework's injection keys.
+- The component resolves the viewport via `useResponsive()` (`isMobile` / `isDesktop`).
 ## Related
 - `framework/ui/components/organisms/vc-sidebar/` -- the underlying `VcSidebar` organism
-- `framework/injection-keys.ts` -- `IsMobileKey`, `IsDesktopKey`
+- `framework/core/composables/useResponsive/` -- `isMobile` / `isDesktop` viewport helper

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

@@ -48,12 +48,12 @@ This component has no props. Themes are managed via the `useTheme()` composable.
 ## Recipe: Registering Custom Themes
-Before the `ThemeSelector` can show themes, they must be registered with the theme service. Themes are defined as objects with a `key` that corresponds to a CSS class or custom property set:
+Before the `ThemeSelector` can show themes, they must be registered with the theme service. Themes are defined as objects with a `key` that corresponds to a `data-theme` attribute value and its custom property set:
 ```ts
 import { useTheme } from "@vc-shell/framework";
-const { register, setTheme, currentTheme } = useTheme();
+const { register, setTheme, currentThemeKey } = useTheme();
 // Register available themes during app initialization
 register([
@@ -66,16 +66,16 @@ register([
 setTheme("light");
 ```
-The theme `key` is applied as a CSS class on the root element, allowing CSS custom properties to cascade:
+The theme `key` is written to the `data-theme` attribute on the root element (`<html data-theme="light">`, via `useColorMode({ attribute: "data-theme" })`), allowing CSS custom properties to cascade:
 ```scss
 // In your theme CSS files
-.light {
+:root[data-theme="light"] {
   --primary-500: #3b82f6;
   --surface-bg: #ffffff;
 }
-.dark {
+:root[data-theme="dark"] {
   --primary-500: #60a5fa;
   --surface-bg: #1e1e2e;
 }
@@ -103,14 +103,14 @@ window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e)
 ## Details
 - **Theme persistence**: The selected theme is persisted to localStorage, so the user's preference survives page reloads and browser restarts.
-- **Toast notification**: When the user switches themes via the selector, a brief toast notification confirms the change (e.g., "Theme changed to Dark").
+- **Toast notification**: When the user switches themes via the selector, a brief toast notification shows the new theme's localized name (e.g., "Dark").
 - **Cascading submenu**: On desktop, selecting the theme entry opens a submenu listing all registered themes. The current theme is highlighted.
 - **CSS custom properties**: Themes work by switching CSS custom properties defined in `framework/assets/styles/theme/colors.scss`. Components reference these variables (e.g., `tw-bg-[var(--primary-500)]`), so theme changes are instant.
 ## Tips
 - If only one theme is registered, the `ThemeSelector` still renders but the submenu will have only one option. Consider hiding it if theming is not a feature of your application.
-- Theme keys should be short, lowercase identifiers. They are used as CSS class names on the root element.
+- Theme keys should be short, lowercase identifiers. They are written to the `data-theme` attribute on the root element.
 - Always pair theme registration with corresponding CSS custom property definitions. A registered theme without CSS variables will result in unstyled or broken visuals.
 - The framework's built-in components use CSS custom properties from the theme system. Custom components should follow the same pattern for consistent theming.

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

@@ -33,12 +33,12 @@ import { UserDropdownButton } from "@vc-shell/framework";
 ## Key Props
-| Prop        | Type      | Default     | Description                   |
-| ----------- | --------- | ----------- | ----------------------------- |
-| `name`      | `string`  | `undefined` | User display name             |
-| `role`      | `string`  | `undefined` | User role label               |
-| `avatarUrl` | `string`  | `undefined` | URL for the user avatar image |
-| `disabled`  | `boolean` | `false`     | Prevents menu from opening    |
+| Prop        | Type      | Default     | Description                                                                                                     |
+| ----------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `name`      | `string`  | `undefined` | User display name                                                                                               |
+| `role`      | `string`  | `undefined` | User role label                                                                                                 |
+| `avatarUrl` | `string`  | `undefined` | URL for the user avatar image                                                                                   |
+| `disabled`  | `boolean` | `false`     | Visual-only: applies the `--auto-width` layout class. Does not suppress clicks or prevent the menu from opening |
 ## Recipe: Wiring to User Management Composable
@@ -50,11 +50,11 @@ import { computed } from "vue";
 import { UserDropdownButton } from "@vc-shell/framework";
 import { useUserManagement } from "@vc-shell/framework";
-const { currentUser } = useUserManagement();
+const { user } = useUserManagement();
-const displayName = computed(() => (currentUser.value ? `${currentUser.value.firstName} ${currentUser.value.lastName}` : ""));
-const role = computed(() => currentUser.value?.roles?.[0]?.name ?? "");
-const avatarUrl = computed(() => currentUser.value?.photoUrl);
+const displayName = computed(() => (user.value ? `${user.value.firstName} ${user.value.lastName}` : ""));
+const role = computed(() => user.value?.roles?.[0]?.name ?? "");
+const avatarUrl = computed(() => user.value?.photoUrl);
 </script>
 <template>
@@ -86,7 +86,7 @@ On mobile viewports (`$isMobile`), clicking the button opens a full-height slide
 ## Tips
 - The component is typically placed in the sidebar footer slot of the app shell. You rarely need to instantiate it manually -- the framework shell handles its placement.
-- If `disabled` is `true`, clicking the button does nothing and the menu does not open. Use this during critical operations where navigation should be prevented.
+- The `disabled` prop is visual-only (it applies the `--auto-width` layout class). It does not block clicks or prevent the menu from opening; the handler always toggles the menu.
 - All menu items are driven by `useSettingsMenu()` registrations. To add custom items to the user menu, register them via the service rather than modifying this component.
 ## Related Components

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

@@ -61,25 +61,36 @@ const config: ChartConfig = {
 ## Key Props (shared across chart types)
-| Prop          | Type          | Default     | Description                          |
-| ------------- | ------------- | ----------- | ------------------------------------ |
-| `data`        | `T[]`         | --          | Array of data points                 |
-| `config`      | `ChartConfig` | --          | Series color and label configuration |
-| `xKey`        | `keyof T`     | --          | Key for x-axis values (line/bar)     |
-| `yKeys`       | `(keyof T)[]` | --          | Keys for y-axis series (line/bar)    |
-| `showTooltip` | `boolean`     | `true`      | Enable hover tooltips                |
-| `showLegend`  | `boolean`     | `true`      | Show color legend below chart        |
-| `rangeStart`  | `number`      | `undefined` | Filter data from this x value        |
-| `rangeEnd`    | `number`      | `undefined` | Filter data up to this x value       |
+| Prop          | Type                                           | Default     | Description                          |
+| ------------- | ---------------------------------------------- | ----------- | ------------------------------------ |
+| `data`        | `T[]`                                          | --          | Array of data points                 |
+| `config`      | `ChartConfig`                                  | --          | Series color and label configuration |
+| `xKey`        | `keyof T`                                      | --          | Key for x-axis values (line/bar)     |
+| `yKeys`       | `(keyof T)[]`                                  | --          | Keys for y-axis series (line/bar)    |
+| `showTooltip` | `boolean`                                      | `true`      | Enable hover tooltips                |
+| `showLegend`  | `boolean`                                      | `true`      | Show color legend below chart        |
+| `rangeStart`  | `ChartRangeValue` (`number \| string \| Date`) | `undefined` | Filter data from this x value        |
+| `rangeEnd`    | `ChartRangeValue` (`number \| string \| Date`) | `undefined` | Filter data up to this x value       |
+| `showXAxis`   | `boolean`                                      | `true`      | Show the x-axis (line/bar)           |
+| `showYAxis`   | `boolean`                                      | `true`      | Show the y-axis (line/bar)           |
+| `showGrid`    | `boolean`                                      | `true`      | Show y-axis grid lines (line/bar)    |
+| `numXTicks`   | `number`                                       | `undefined` | Number of x-axis ticks (line/bar)    |
+| `numYTicks`   | `number`                                       | `5`         | Number of y-axis ticks (line/bar)    |
+| `xTickFormat` | `(value: number \| Date) => string`            | `undefined` | Format x-axis tick labels (line/bar) |
+| `yTickFormat` | `(value: number) => string`                    | `undefined` | Format y-axis tick labels (line/bar) |
+| `height`      | `number`                                       | `undefined` | Fixed chart height in px             |
 ### Donut-specific props
-| Prop              | Type      | Default     | Description                    |
-| ----------------- | --------- | ----------- | ------------------------------ |
-| `valueKey`        | `keyof T` | --          | Key for segment values         |
-| `centralLabel`    | `string`  | `undefined` | Large text in donut center     |
-| `centralSubLabel` | `string`  | `undefined` | Small text below central label |
-| `arcWidth`        | `number`  | `60`        | Donut arc thickness            |
+| Prop              | Type                        | Default     | Description                             |
+| ----------------- | --------------------------- | ----------- | --------------------------------------- |
+| `valueKey`        | `keyof T`                   | --          | Key for segment values                  |
+| `centralLabel`    | `string`                    | `undefined` | Large text in donut center              |
+| `centralSubLabel` | `string`                    | `undefined` | Small text below central label          |
+| `arcWidth`        | `number`                    | `60`        | Donut arc thickness                     |
+| `valueFormat`     | `(value: number) => string` | `undefined` | Formats segment values in tooltip/label |
+| `colorKey`        | `keyof T`                   | `undefined` | Data key holding a per-segment color    |
+| `cornerRadius`    | `number`                    | `4`         | Rounded corner radius of arcs           |
 ## ChartConfig Type
@@ -91,6 +102,7 @@ type ChartConfig = Record<
   {
     label: string; // Display name in legend and tooltip
     color: string; // CSS color value (hex, var(), rgb, etc.)
+    icon?: string; // Optional icon shown alongside the series label
   }
 >;
 ```

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

@@ -67,20 +67,17 @@ import { DashboardWidgetCard } from "@vc-shell/framework";
 ```vue
 <DashboardWidgetCard header="Orders" icon="lucide-shopping-cart">
   <template #stats>
-    <DashboardStatItem :value="48" label="Total" />
-    <DashboardStatItem :value="12" label="Today" variant="info" />
+    <DashboardStatItem :value="48" label="Total" variant="success" />
+    <DashboardStatItem :value="12" label="Today" />
     <DashboardStatItem :value="3" label="Pending" variant="warning" />
-    <DashboardStatItem :value="1" label="Failed" variant="error" />
+    <DashboardStatItem :value="1" label="Failed" variant="danger" />
   </template>
   <template #content>
     <DashboardFeedList>
-      <DashboardFeedRow v-for="order in recentOrders" :key="order.id">
-        <template #icon>
-          <VcIcon :icon="getOrderIcon(order.status)" size="s" />
-        </template>
-        <template #title>{{ order.number }}</template>
-        <template #subtitle>{{ order.customerName }}</template>
-        <template #meta>{{ formatDateRelative(order.createdDate) }}</template>
+      <DashboardFeedRow v-for="order in recentOrders" :key="order.id" @click="openOrder(order)">
+        <VcIcon :icon="getOrderIcon(order.status)" size="s" />
+        <span>{{ order.number }} — {{ order.customerName }}</span>
+        <template #trailing>{{ formatDateRelative(order.createdDate) }}</template>
       </DashboardFeedRow>
     </DashboardFeedList>
   </template>
@@ -167,22 +164,23 @@ import OrdersWidget from "./OrdersWidget.vue";
 const dashboard = useDashboard();
-dashboard.register({
+dashboard.registerWidget({
   id: "orders-overview",
+  name: "Orders overview",
   component: markRaw(OrdersWidget),
+  size: { width: 6, height: 4 },
+  position: { x: 0, y: 0 },
   props: { limit: 10 },
-  order: 1,
-  layout: { w: 6, h: 4, x: 0, y: 0 },
 });
 ```
 ## Companion Components
-| Component           | Description                                                     |
-| ------------------- | --------------------------------------------------------------- |
-| `DashboardStatItem` | Single KPI stat with value, label, and optional color variant   |
-| `DashboardFeedList` | Scrollable list container for feed rows                         |
-| `DashboardFeedRow`  | Individual feed item with icon, title, subtitle, and meta slots |
+| Component           | Description                                                                                                    |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `DashboardStatItem` | Single KPI stat with value, label, and optional color variant                                                  |
+| `DashboardFeedList` | Scrollable list container for feed rows                                                                        |
+| `DashboardFeedRow`  | Individual feed item: default slot for leading content, `#trailing` slot for right-side content, emits `click` |
 ## Tip: Set a Minimum Height
@@ -200,4 +198,4 @@ When the card content is loaded asynchronously, the card may collapse to zero he
 - [DraggableDashboard](../draggable-dashboard/draggable-dashboard.docs.md) -- grid layout container
 - [DashboardCharts](../dashboard-charts/dashboard-charts.docs.md) -- chart components for widget content
-- [useDashboard](../../../core/composables/useDashboard/) -- dashboard widget registration service
+- [useDashboard](../../../core/composables/useDashboard/useDashboard.docs.md) -- dashboard widget registration service

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

@@ -140,6 +140,27 @@ function resetLayout() {
 - The 12-column grid means common widget widths are: 3 (quarter), 4 (third), 6 (half), and 12 (full width).
 - Register widgets during module `install()` before the dashboard component mounts. Late registrations may not be picked up.
+## Advanced / Exports
+Besides the `DraggableDashboard` component, `draggable-dashboard/index.ts` re-exports these symbols through the framework root, for building a custom Gridstack dashboard:
+| Export                    | Kind       | Description                                                 |
+| ------------------------- | ---------- | ----------------------------------------------------------- |
+| `useGridstack`            | composable | Low-level Gridstack integration for a custom dashboard      |
+| `UseGridstackOptions`     | type       | Options for `useGridstack`                                  |
+| `UseGridstackReturn`      | type       | Return shape of `useGridstack`                              |
+| `DashboardWidgetSize`     | type       | Widget size shape: `{ width, height }`                      |
+| `DashboardWidgetPosition` | type       | Widget position shape: `{ x, y }`                           |
+| `DashboardDragEvent`      | type       | Payload emitted on widget drag/reorder                      |
+| `DashboardGridConfig`     | type       | Grid configuration options                                  |
+| `toGridstackWidget`       | function   | Maps an `IDashboardWidget` to a Gridstack widget descriptor |
+| `fromGridstackNode`       | function   | Maps a Gridstack node back to layout data                   |
+| `loadLayoutFromStorage`   | function   | Reads persisted layout from localStorage                    |
+| `saveLayoutToStorage`     | function   | Writes layout to localStorage                               |
+| `mergeLayoutWithWidgets`  | function   | Merges a persisted layout onto the registered widget set    |
+| `clearLayoutStorage`      | function   | Clears the persisted layout                                 |
+| `LAYOUT_STORAGE_KEY`      | constant   | localStorage key used for layout persistence                |
 ## Related Components
 - [DashboardWidgetCard](../dashboard-widget-card/dashboard-widget-card.docs.md) -- card container for widget content

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

@@ -39,6 +39,7 @@ A small indicator component for displaying counts, status dots, or short text la
 | `inline`         | `boolean`                                                                  | `false`     | Renders as an inline element without absolute positioning |
 | `clickable`      | `boolean`                                                                  | `false`     | Makes the badge respond to click events                   |
 | `disabled`       | `boolean`                                                                  | `false`     | Disables interaction on clickable badges                  |
+| `active`         | `boolean`                                                                  | `false`     | Applies the active-state color tokens to the badge        |
 | `customPosition` | `boolean`                                                                  | `false`     | Enables custom `top`/`right` positioning                  |
 | `top`            | `string`                                                                   | --          | Custom top offset (requires `customPosition`)             |
 | `right`          | `string`                                                                   | --          | Custom right offset (requires `customPosition`)           |
@@ -144,7 +145,7 @@ Fine-tune the badge position relative to its parent:
 - 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.
+- The `inline` prop switches the root element from the `<div class="vc-badge">` wrapper (overlay) to a `<div class="vc-badge__badge vc-badge__badge--inline">` rendered directly 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.

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

@@ -172,8 +172,8 @@ Override the default "Show more" button with a custom trigger:
 ## 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.
+- Legacy variants `"light-danger"`, `"info-dark"`, and `"primary"` are mapped in `vc-banner.vue` via a computed `normalizedVariant` (backed by the `normalizeVariant` function). A `console.warn` is emitted in development mode only.
+- The collapse is driven by an inline `max-height` style bound via `wrapperStyle` from `useCollapsible` (max-height set to the measured `collapsedHeight` in px when collapsed), transitioned in CSS. There is no `--vc-banner-collapsed-height` custom property.
 - Source: `framework/ui/components/atoms/vc-banner/vc-banner.vue`
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-button/vc-button.docs.md CHANGED Viewed

@@ -265,19 +265,19 @@ Use the `loading` prop, not `disabled`. A disabled button gives no progress feed
 ## Props
-| Prop        | Type                                                                                                         | Default     | Description                                                     |
-| ----------- | ------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------- |
-| `variant`   | `"primary" \| "secondary" \| "danger" \| "warning" \| "success" \| "info" \| "outline" \| "ghost" \| "link"` | `"primary"` | Visual style variant                                            |
-| `size`      | `"sm" \| "default" \| "lg" \| "icon" \| "icon-sm"`                                                           | `"default"` | Button size                                                     |
-| `icon`      | `string \| Component`                                                                                        | --          | Icon identifier or Vue component                                |
-| `iconClass` | `string`                                                                                                     | --          | Additional CSS class for the icon element                       |
-| `iconSize`  | `IconSize`                                                                                                   | `"s"`       | Size of the icon (`"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`, `"xxl"`) |
-| `loading`   | `boolean`                                                                                                    | `false`     | Shows spinner, disables interaction, sets `aria-busy`           |
-| `disabled`  | `boolean`                                                                                                    | `false`     | Disables the button                                             |
-| `selected`  | `boolean`                                                                                                    | `false`     | Applies selected/active visual state, sets `aria-pressed`       |
-| `text`      | `boolean`                                                                                                    | `false`     | Renders as borderless text in the variant's color               |
-| `type`      | `"button" \| "submit" \| "reset"`                                                                            | `"button"`  | HTML button type                                                |
-| `ariaLabel` | `string`                                                                                                     | --          | Accessible label (required for icon-only buttons)               |
+| Prop        | Type                                                                                                         | Default     | Description                                                               |
+| ----------- | ------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------- |
+| `variant`   | `"primary" \| "secondary" \| "danger" \| "warning" \| "success" \| "info" \| "outline" \| "ghost" \| "link"` | `"primary"` | Visual style variant                                                      |
+| `size`      | `"sm" \| "default" \| "lg" \| "icon" \| "icon-sm"`                                                           | `"default"` | Button size                                                               |
+| `icon`      | `string \| Component`                                                                                        | --          | Icon identifier or Vue component                                          |
+| `iconClass` | `string`                                                                                                     | --          | Additional CSS class for the icon element                                 |
+| `iconSize`  | `IconSize`                                                                                                   | `"s"`       | Size of the icon (`"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`, `"xxl"`, `"xxxl"`) |
+| `loading`   | `boolean`                                                                                                    | `false`     | Shows spinner, disables interaction, sets `aria-busy`                     |
+| `disabled`  | `boolean`                                                                                                    | `false`     | Disables the button                                                       |
+| `selected`  | `boolean`                                                                                                    | `false`     | Applies selected/active visual state, sets `aria-pressed`                 |
+| `text`      | `boolean`                                                                                                    | `false`     | Renders as borderless text in the variant's color                         |
+| `type`      | `"button" \| "submit" \| "reset"`                                                                            | `"button"`  | HTML button type                                                          |
+| `ariaLabel` | `string`                                                                                                     | --          | Accessible label (required for icon-only buttons)                         |
 ## Events
@@ -304,6 +304,7 @@ All visual properties are customizable through CSS custom properties. Each varia
 | `--button-border-radius`                    | `6px`                                     | Corner radius for all buttons |
 | `--button-focus-ring-color`                 | `var(--primary-300)`                      | Focus ring color              |
 | `--button-focus-ring-width`                 | `2px`                                     | Focus ring thickness          |
+| `--button-focus-ring-offset`                | `2px`                                     | Focus ring offset             |
 | `--button-{size}-height`                    | `--button-default-height: 36px`           | Height per size               |
 ## Accessibility
@@ -327,6 +328,6 @@ All visual properties are customizable through CSS custom properties. Each varia
 ## Architecture notes
 - VcButton calls `e.preventDefault()` on click to support `link` variant pattern. Form submit buttons must use `type="submit"` to bypass this.
-- `VcButtonGroup` integration is via provide/inject (`vcButtonGroupSize` injection key in `framework/injection-keys.ts`).
+- `VcButtonGroup` integration is via provide/inject using the `ButtonGroupKey` injection key defined in `framework/ui/components/atoms/vc-button/types.ts`.
 - Size aliases `xs`/`base` are kept for backward compatibility — slated for removal in v3.
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-container/vc-container.docs.md CHANGED Viewed

@@ -57,12 +57,15 @@ The `shadow` prop adds an inset shadow as a scroll cue. Use it for content that
 ## CSS Variables
-| Variable                    | Default       | Description                          |
-| --------------------------- | ------------- | ------------------------------------ |
-| `--container-padding`       | `16px`        | Inner padding of the scrollable area |
-| `--container-bg`            | `transparent` | Background color                     |
-| `--container-border-radius` | `0`           | Border radius                        |
-| `--container-gap`           | `0`           | Gap between child elements           |
+| Variable                     | Default                                                                                | Description                                                     |
+| ---------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `--container-padding`        | `16px`                                                                                 | Inner padding of the scrollable area                            |
+| `--container-bg`             | `transparent`                                                                          | Background color                                                |
+| `--container-border-radius`  | `0`                                                                                    | Border radius                                                   |
+| `--container-gap`            | `0`                                                                                    | Gap between child elements                                      |
+| `--container-shadow-color`   | `var(--additional-950)`                                                                | Scroll-shadow color (RGB channels used by `--container-shadow`) |
+| `--container-shadow-opacity` | `0.1`                                                                                  | Scroll-shadow opacity                                           |
+| `--container-shadow`         | `0 3px 2px rgba(var(--container-shadow-color), var(--container-shadow-opacity)) inset` | Inset shadow applied when the `shadow` prop is set              |
 ## Exposed Methods

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

@@ -0,0 +1,42 @@
+---
+title: VcEnvironmentBanner
+category: components
+group: feedback
+---
+# VcEnvironmentBanner
+Centered badge pinned to the top of the application that labels the current
+environment (Development, QA, Demo, etc.). Mirrors the platform environment
+banner (vc-env-badge). Purely presentational — it renders the colored badge and
+its label, and does not know where the name comes from. Visibility and color are
+decided by the caller (see `useEnvironmentName`).
+## When to Use
+- Inside the app shell to make non-production environments visually obvious
+- When NOT to use: do not place it manually in blades — `VcApp` already mounts it
+## Props
+- `name: string` — environment label to render
+- `color?: string` — badge color (vc-shell theme tokens); recognized values are `primary | secondary | info | success | warning | danger | neutral`, any other value falls back to neutral via CSS, default `neutral`
+## Quick Start
+```vue
+<template>
+  <VcEnvironmentBanner
+    v-if="!isIgnored"
+    :name="environmentName"
+    :color="color"
+  />
+</template>
+<script setup>
+import { VcEnvironmentBanner } from "@vc-shell/framework";
+import { useEnvironmentName } from "@vc-shell/framework";
+const { environmentName, isIgnored, color } = useEnvironmentName();
+</script>
+```

package/runtime/knowledge/docs/ui/components/atoms/vc-hint/vc-hint.docs.md CHANGED Viewed

@@ -145,7 +145,7 @@ Show helper text by default, but swap to an error message when validation fails:
 ## Architecture notes
 - VcHint is a single `<div>` element — no wrapper. `role="alert"` is toggled reactively via `:role` binding when `error` prop changes.
-- CSS variables are scoped with `.vc-hint` selector in `vc-hint.vue` `<style scoped>`.
+- The `--hint-*` CSS variables are declared globally on `:root` (not scoped to `.vc-hint`); the component's `<style lang="scss">` block is not scoped.
 - Source: `framework/ui/components/atoms/vc-hint/vc-hint.vue`
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-icon/vc-icon.docs.md CHANGED Viewed

@@ -25,14 +25,15 @@ A unified icon component that renders icons from multiple libraries. Lucide Icon
 ## Key Props
-| Prop         | Type                                                   | Default           | Description                              |
-| ------------ | ------------------------------------------------------ | ----------------- | ---------------------------------------- |
-| `icon`       | `string \| Component`                                  | `"lucide-square"` | Icon identifier or Vue component         |
-| `size`       | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl" \| "xxxl"` | `"m"`             | Predefined size                          |
-| `variant`    | `"warning" \| "danger" \| "success"`                   | —                 | Semantic color variant                   |
-| `customSize` | `number`                                               | —                 | Custom size in pixels (overrides `size`) |
-| `ariaLabel`  | `string`                                               | —                 | Accessible label for meaningful icons    |
-| `basePath`   | `string`                                               | `"/assets/icons"` | Base path for SVG sprite icons           |
+| Prop           | Type                                                   | Default           | Description                                                                                                                                            |
+| -------------- | ------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `icon`         | `string \| Component`                                  | `"lucide-square"` | Icon identifier or Vue component                                                                                                                       |
+| `size`         | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl" \| "xxxl"` | `"m"`             | Predefined size                                                                                                                                        |
+| `variant`      | `"warning" \| "danger" \| "success"`                   | —                 | Semantic color variant                                                                                                                                 |
+| `customSize`   | `number`                                               | —                 | Custom size in pixels (overrides `size`)                                                                                                               |
+| `ariaLabel`    | `string`                                               | —                 | Accessible label for meaningful icons                                                                                                                  |
+| `basePath`     | `string`                                               | `"/assets/icons"` | Base path for SVG sprite icons                                                                                                                         |
+| `useContainer` | `boolean`                                              | `false`           | Deprecated. Wraps the icon in a fixed-size container; removed in a future version (logs a dev warning). Remove it — icons render correctly without it. |
 ::storybook id="layout-vcicon--all-sizes" height="300"
@@ -127,6 +128,6 @@ import MyCustomIcon from "./MyCustomIcon.vue";
 - Icon resolution is handled by a switch on the string prefix: `lucide-` maps to the Lucide component registry; `fa-` / `fas fa-` / `bi-` / `material-` are legacy paths kept for backward compatibility and will be removed in v3.
 - The `svg:` prefix loads from an SVG sprite at `basePath` (default `/assets/icons`) using a `<use>` element. Sprite must be included in the app's static assets.
 - `customSize` takes a number and sets `width`/`height` inline; it overrides the `size` prop class entirely.
-- Color variants (`warning`, `danger`, `success`) apply CSS custom property overrides (`--icon-color`) rather than inline style to allow theme-level customization.
+- Color variants (`warning`, `danger`, `success`) resolve to the per-variant CSS custom properties `--icon-color-{success|danger|warning}`. Prefix/registry icons pick these up via variant CSS classes; custom Vue-component icons receive the color inline as `color: var(--icon-color-${variant})`.
 <!-- internal:end -->

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

@@ -35,9 +35,15 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `bordered`      | `boolean`                                                       | `false`          | Adds a subtle border                                                                                                                               |
 | `clickable`     | `boolean`                                                       | `false`          | Makes the image interactive with cursor and click event                                                                                            |
 | `emptyIcon`     | `string`                                                        | `"lucide-image"` | Icon shown when `src` is empty                                                                                                                     |
-| `alt`           | `string`                                                        | —                | Accessible alt text                                                                                                                                |
+| `alt`           | `string`                                                        | —                | Accessible alt text. Required to expose `role="img"`; without it the image is decorative                                                           |
 | `thumbnailSize` | `ThumbnailSize`                                                 | —                | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
+## Events
+| Event   | Payload | Description                                                 |
+| ------- | ------- | ----------------------------------------------------------- |
+| `click` | —       | Emitted on click/Enter/Space, only when `clickable` is true |
 ::storybook id="data-display-vcimage--size-variants" height="300"
 ## Size Reference
@@ -53,6 +59,15 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `xxl`  | 145px          |
 | `auto` | 100% of parent |
+## CSS Custom Properties
+| Variable                   | Default               | Description                     |
+| -------------------------- | --------------------- | ------------------------------- |
+| `--image-border-radius`    | `6px`                 | Corner radius when `bordered`   |
+| `--image-border-color`     | `var(--neutrals-200)` | Border color when `bordered`    |
+| `--image-empty-icon-color` | `var(--neutrals-400)` | Placeholder icon color          |
+| `--image-focus-ring-color` | `var(--primary-300)`  | Focus ring color when clickable |
 ## Common Patterns
 ### Product Thumbnail in a List
@@ -87,7 +102,7 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 ## Accessibility
-- When `src` is present and no `clickable`, the container has `role="img"` with `aria-label` from `alt`
+- When `src` **and** `alt` are present and not `clickable`, the container has `role="img"` with `aria-label` from `alt`. Without `alt` the image is treated as decorative (no `role`), since `role="img"` requires an accessible name.
 - Clickable images receive `role="button"`, `tabindex="0"`, and keyboard support (Enter/Space)
 - Empty placeholder icon is marked `aria-hidden="true"`
 - Focus ring appears on `:focus-visible` for clickable images
@@ -107,8 +122,8 @@ When displaying images in lists or grids, pass a `thumbnailSize` (e.g. `"128x128
 - VcImage lives in `framework/ui/components/atoms/vc-image/`.
 - Images are rendered as CSS `background-image` on a `<div>` rather than an `<img>` tag; this enables `background-size: cover/contain` and preserves aspect-ratio without JS.
-- HTTPS enforcement: the `src` watcher rewrites `http://` to `https://` when `window.location.protocol === 'https:'`.
-- `thumbnailSize` appends a query parameter to the URL compatible with Virto Commerce image proxy: `?size=128x128`. This is a platform-specific convention.
+- HTTPS enforcement: the `ensureHttps()` helper (called from the `imageHandler` computed and the thumbnail-probe watcher) upgrades `http://` to `https://` when `window.location.protocol === 'https:'`.
+- `thumbnailSize` inserts a size suffix before the file extension, compatible with the Virto Commerce thumbnail convention: `photo.jpg` becomes `photo_128x128.jpg`. This is a platform-specific convention.
 - Aspect ratios are implemented as Tailwind aspect-ratio utility classes (`tw-aspect-square`, `tw-aspect-video`, etc.).
 - Clickable mode adds `role="button"` and forwards keyboard Enter/Space to the click handler, consistent with other atom-level interactive components.

package/runtime/knowledge/docs/ui/components/atoms/vc-label/vc-label.docs.md CHANGED Viewed

@@ -167,9 +167,9 @@ Use a different icon for the tooltip trigger:
 ## Architecture notes
 - VcLabel lives in `framework/ui/components/atoms/vc-label/`.
-- The element type (`<label>` vs `<div>`) is determined by a computed `tag` that checks whether `htmlFor` is a non-empty string.
+- The root element type (`<label>` vs `<div>`) is chosen inline via `:is="htmlFor ? 'label' : 'div'"` on the root `<component>` (no `tag` computed exists).
 - The tooltip trigger is rendered by `VcTooltip` (internal molecule); the `tooltipIcon` prop simply passes through to an inner `VcIcon` instance.
-- `multilanguage` + `currentLanguage` render a small pill via an inline `<span>` with `.vc-label__lang` class — not a separate component.
+- `multilanguage` + `currentLanguage` render a small pill via an inline `<div>` with `.vc-label__language` class — not a separate component.
 - VcLabel is the canonical label primitive consumed by `VcInput`, `VcSelect`, `VcTextarea`, `VcCheckbox`, and `VcRadioButton` in `framework/ui/components/molecules/`.
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-link/vc-link.docs.md CHANGED Viewed

@@ -35,10 +35,11 @@ function openDetails() {
 ## Key Props
-| Prop       | Type      | Default | Description                                    |
-| ---------- | --------- | ------- | ---------------------------------------------- |
-| `active`   | `boolean` | `false` | Highlights the link as currently selected      |
-| `disabled` | `boolean` | `false` | Prevents interaction and applies muted styling |
+| Prop       | Type         | Default | Description                                                                     |
+| ---------- | ------------ | ------- | ------------------------------------------------------------------------------- |
+| `active`   | `boolean`    | `false` | Highlights the link as currently selected                                       |
+| `disabled` | `boolean`    | `false` | Prevents interaction and applies muted styling                                  |
+| `onClick`  | `() => void` | --      | Declared prop, currently unused by the template (use the `click` event instead) |
 ## Events

package/runtime/knowledge/docs/ui/components/atoms/vc-loading/vc-loading.docs.md CHANGED Viewed

@@ -52,7 +52,8 @@ const isLoading = ref(true);
 | `--loading-overlay-bg` | `rgba(255,255,255,0.6)` | Overlay background color      |
 | `--loading-bar-width`  | `140px`                 | Width of the progress bar     |
 | `--loading-bar-height` | `4px`                   | Height of the progress bar    |
-| `--loading-z-index`    | `9998`                  | Z-index of the overlay layer  |
+> **Note:** The overlay z-index comes from the global `--z-critical-loading` token and is not overridable per-instance.
 ::storybook id="layout-vcloading--interactive"
@@ -117,7 +118,7 @@ Override the bar color to match a specific status or brand theme:
 ## Tips
-- VcLoading is hidden with `display: none` when inactive, so it adds zero layout cost when idle.
+- VcLoading is hidden via the `tw-hidden` class when inactive, so it adds zero layout cost when idle.
 - The sweep animation runs on a 1.5-second infinite loop using CSS `@keyframes` — no JavaScript timers involved.
 - The overlay applies `backdrop-filter: blur(3px)` for a frosted-glass effect. If you need a fully opaque overlay, set `--loading-overlay-bg: rgba(255,255,255,1)`.
 - When using inside a scrollable container, the overlay covers only the visible viewport of that container because it is absolutely positioned.
@@ -138,8 +139,8 @@ Override the bar color to match a specific status or brand theme:
 ## Architecture notes
-- The overlay is a single `<div>` with `v-show` (not `v-if`) so it remains in the DOM and retains animation state. `display: none` from `v-show` removes it from the paint tree when inactive.
-- The sweeping bar is a child `<div>` animated via `@keyframes vc-loading-sweep` (translateX from `-100%` to `100%`).
+- The overlay is a single `<div>` always rendered in the DOM; visibility is toggled via the `vc-loading-overlay--active` class (base state is `tw-hidden`), so it retains animation state when inactive.
+- The sweeping bar is a child `<div>` animated via `@keyframes vc-bar-sweep`, animating the `left` property from `-40%` to `100%`.
 - `backdrop-filter: blur(3px)` is applied to the overlay div directly; older Safari requires `-webkit-backdrop-filter` as a fallback.
 - Source: `framework/ui/components/atoms/vc-loading/vc-loading.vue`