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

package/runtime/knowledge/docs/core/composables/useBladeWidgets/index.docs.md

@@ -0,0 +1,305 @@
+# useBladeWidgets / useWidgetTrigger
+
+Two composables for the widget system — one for the **blade side**, one for the **widget side**.
+
+| Composable | Called from | Purpose |
+|---|---|---|
+| `useBladeWidgets` | Blade component | Register headless widgets + get `refresh()` / `refreshAll()` |
+| `useWidgetTrigger` | External widget component | Register trigger callbacks (`onRefresh`, `onClick`) via provide/inject |
+
+Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. External component-based widgets use `useWidgetTrigger` to register their refresh callbacks so the hosting blade can trigger them.
+
+## When to Use
+
+- **`useBladeWidgets`**: Register sidebar widgets (counters, action buttons) for a blade without creating Vue components. Refresh widget data after blade operations (save, delete).
+- **`useWidgetTrigger`**: Inside an external widget component (registered via `registerExternalWidget`) to register `onRefresh` / `onClick` callbacks. The blade can then call `refresh(widgetId)` or `refreshAll()` to trigger them.
+- When NOT to use `useBladeWidgets`: for widgets that need their own template or complex UI (use `registerExternalWidget` + `useWidgetTrigger` instead).
+
+## Basic Usage
+
+```typescript
+import { useBladeWidgets } from '@vc-shell/framework';
+
+const { refreshAll } = useBladeWidgets([
+  {
+    id: 'OffersWidget',
+    icon: 'lucide-tag',
+    title: 'OFFERS.TITLE',
+    badge: offersCount,
+    loading: offersLoading,
+    onClick: () => openBlade({ name: 'OffersList' }),
+    onRefresh: () => reloadOffers(),
+  },
+  {
+    id: 'ReviewsWidget',
+    icon: 'lucide-star',
+    title: 'REVIEWS.TITLE',
+    badge: reviewsCount,
+    isVisible: computed(() => !!item.value?.id),
+    onClick: () => openBlade({ name: 'ReviewsList' }),
+  },
+]);
+
+// After a save, refresh all widget data
+await saveEntity();
+refreshAll();
+```
+
+## API
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `widgets` | `HeadlessWidgetDeclaration[]` | Yes | Array of widget declarations |
+
+### HeadlessWidgetDeclaration
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Unique widget identifier |
+| `icon` | `string` | Yes | Icon name (e.g., `"lucide-tag"`) |
+| `title` | `string` | Yes | i18n key or display title |
+| `badge` | `Ref<number \| string>` | No | Badge counter value |
+| `loading` | `Ref<boolean>` | No | Show loading indicator |
+| `disabled` | `Ref<boolean> \| boolean` | No | Disable the widget |
+| `isVisible` | `ComputedRef<boolean> \| boolean` | No | Toggle visibility |
+| `onClick` | `() => void` | No | Action when widget is clicked |
+| `onRefresh` | `() => void \| Promise<void>` | No | Called by `refresh(id)` or `refreshAll()` |
+
+### Returns
+
+| Property | Type | Description |
+|---|---|---|
+| `refresh` | `(widgetId: string) => void` | Trigger `onRefresh` on a specific widget |
+| `refreshAll` | `() => void` | Trigger `onRefresh` on all widgets that have one |
+
+## useWidgetTrigger
+
+Widget-side composable for external component-based widgets. Registers a trigger contract (`onRefresh`, `onClick`, `badge`) via provide/inject — no props, IDs, or service knowledge required.
+
+### Basic Usage
+
+```typescript
+import { useWidgetTrigger } from '@vc-shell/framework';
+
+// Inside an external widget component:
+useWidgetTrigger({ onRefresh: loadData });
+```
+
+### IWidgetTrigger
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `string` | No | Lucide icon name for dropdown rendering |
+| `title` | `string` | No | Display title (fallback: widget's title) |
+| `badge` | `Ref<number \| string>` | No | Reactive badge value |
+| `onClick` | `() => void` | No | Handler called when widget is clicked in dropdown |
+| `onRefresh` | `() => void \| Promise<void>` | No | Handler called to refresh widget data |
+| `disabled` | `Ref<boolean> \| boolean` | No | Disabled state |
+
+### How It Works
+
+1. `WidgetContainer` wraps each component-based widget in a `WidgetScope` provider
+2. `WidgetScope` provides a `setTrigger` function scoped to the specific widget ID and blade ID
+3. `useWidgetTrigger` injects this scope and calls `setTrigger` — no props or IDs needed
+4. When the blade calls `refresh(widgetId)` or `refreshAll()`, the registered `onRefresh` is invoked
+
+## Recipe: External Widget with Refresh
+
+A complete example of an external widget that shows an unread message count and supports refresh from the blade:
+
+**1. Register the external widget (module index.ts):**
+
+```typescript
+import { createAppModule, registerExternalWidget, BladeDescriptor } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { MessageWidget } from "./components/widgets";
+
+registerExternalWidget({
+  id: "MessageWidget",
+  component: markRaw(MessageWidget),
+  targetBlades: ["ProductDetails", "OrderDetails"],
+  isVisible: (blade?: BladeDescriptor) => !!blade?.param,
+});
+```
+
+**2. Widget component (message-widget.vue):**
+
+```vue
+<template>
+  <VcWidget
+    v-loading:500="loading"
+    :title="$t('MESSENGER.WIDGET.TITLE')"
+    icon="lucide-message-circle"
+    :value="messageCount"
+    @click="openMessageBlade"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted } from "vue";
+import {
+  loading as vLoading,
+  useBlade,
+  injectBladeContext,
+  useWidgetTrigger,
+  VcWidget,
+} from "@vc-shell/framework";
+
+const ctx = injectBladeContext();
+const entityId = computed(() => (ctx.value.item as { id?: string })?.id ?? "");
+
+const messageCount = ref(0);
+const loading = ref(false);
+
+const loadData = async () => {
+  loading.value = true;
+  try {
+    messageCount.value = await api.getUnreadCount(entityId.value);
+  } finally {
+    loading.value = false;
+  }
+};
+
+// Register refresh callback — blade can call refreshAll() after save
+useWidgetTrigger({ onRefresh: loadData });
+
+onMounted(() => {
+  if (entityId.value) loadData();
+});
+</script>
+```
+
+**3. Blade refreshes widgets after save:**
+
+```vue
+<script setup lang="ts">
+import { useBladeWidgets } from "@vc-shell/framework";
+
+// Empty array — blade doesn't register headless widgets,
+// but gets refresh/refreshAll for external widgets
+const { refresh, refreshAll } = useBladeWidgets([]);
+
+async function save() {
+  await api.saveProduct(product.value);
+  refreshAll();           // refresh all widgets (including MessageWidget)
+  // or: refresh("MessageWidget");  // refresh a specific widget by ID
+}
+</script>
+```
+
+## Recipe: Product Detail Blade with Multiple Widgets
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { useBladeWidgets, defineBladeContext } from "@vc-shell/framework";
+
+const product = ref({ id: "prod-1", name: "Widget A" });
+const offersCount = ref(0);
+const reviewsCount = ref(0);
+const offersLoading = ref(false);
+
+// Expose product data to widgets
+defineBladeContext(computed(() => ({ id: product.value?.id })));
+
+async function reloadOffers() {
+  offersLoading.value = true;
+  try {
+    const result = await api.searchOffers({ productId: product.value.id });
+    offersCount.value = result.totalCount;
+  } finally {
+    offersLoading.value = false;
+  }
+}
+
+const { refreshAll } = useBladeWidgets([
+  {
+    id: "OffersWidget",
+    icon: "lucide-tag",
+    title: "PRODUCT.WIDGETS.OFFERS",
+    badge: offersCount,
+    loading: offersLoading,
+    isVisible: computed(() => !!product.value?.id),
+    onClick: () => openBlade({ name: "OffersList" }),
+    onRefresh: reloadOffers,
+  },
+  {
+    id: "ReviewsWidget",
+    icon: "lucide-star",
+    title: "PRODUCT.WIDGETS.REVIEWS",
+    badge: reviewsCount,
+    isVisible: computed(() => !!product.value?.id),
+    onClick: () => openBlade({ name: "ReviewsList" }),
+  },
+]);
+
+async function save() {
+  await api.saveProduct(product.value);
+  // Refresh all widget counts after saving
+  refreshAll();
+}
+</script>
+```
+
+## Prerequisites
+
+**`useBladeWidgets`**:
+- Must be called inside a blade component rendered by `VcBladeSlot` (requires `BladeDescriptorKey` injection).
+- `WidgetService` must be provided in the component tree (automatically available in vc-shell apps).
+- Calling outside a blade context throws an error with a descriptive message.
+
+**`useWidgetTrigger`**:
+- Must be called inside a widget component rendered by `WidgetContainer` (requires `WidgetScopeKey` injection).
+- If called outside a widget scope, logs a warning and does nothing (does not throw).
+
+## Details
+
+- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the WidgetService always reflects the currently visible blades.
+- **Blade ID resolution**: The composable injects `BladeDescriptorKey` to determine which blade the widgets belong to. Each blade has its own isolated widget list.
+- **Trigger pattern**: The `onRefresh` callback is stored as a `trigger` on the registered widget. When `refresh(id)` or `refreshAll()` is called, the trigger is invoked. Widgets without `onRefresh` are silently skipped.
+
+## Tips
+
+- Use `refreshAll()` after any blade operation that might change widget badge counts (save, delete, import).
+- The `badge` field accepts both numbers and strings. Use a string for non-numeric badges like "New" or "!".
+- Keep widget IDs unique within a blade. Duplicate IDs will overwrite previous registrations.
+- Combine with `defineBladeContext` to expose blade entity data that widget components (non-headless) can consume via `injectBladeContext`.
+
+## Common Mistakes
+
+### Calling useWidgetTrigger outside WidgetContainer scope
+
+```typescript
+// Wrong — called in a standalone component, not rendered inside a blade widget slot
+export default defineComponent({
+  setup() {
+    useWidgetTrigger({ onRefresh: loadData }); // ⚠️ Logs warning, trigger not registered
+  },
+});
+```
+
+```typescript
+// Correct — called inside a widget component registered via registerExternalWidget
+// and rendered by WidgetContainer within a blade
+useWidgetTrigger({ onRefresh: loadData }); // ✓ WidgetScope provides context
+```
+
+### Forgetting to pass empty array to useBladeWidgets for refresh-only usage
+
+```typescript
+// Wrong — useBladeWidgets requires an array argument
+const { refreshAll } = useBladeWidgets(); // TS error
+
+// Correct — pass empty array when you only need refresh/refreshAll
+const { refreshAll } = useBladeWidgets([]);
+```
+
+## Related
+
+- `defineBladeContext` / `injectBladeContext` -- expose/consume blade data in external widgets
+- `registerExternalWidget` -- register a component-based widget globally for target blades
+- `WidgetService` in `@core/services/widget-service` -- underlying service
+- `WidgetScope` in `vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
+- `VcBladeSlot` -- the blade wrapper that provides `BladeDescriptorKey`

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

@@ -0,0 +1,83 @@
+# useMenuExpanded
+
+Manages the sidebar menu expanded/collapsed and hover-expanded state with localStorage persistence. This is the low-level composable that powers the sidebar pin/unpin behavior in the vc-shell admin UI. It tracks two independent states: the permanent "pinned" state (persisted across sessions) and the transient "hover-expanded" state (active only while the user hovers over a collapsed sidebar).
+
+## When to Use
+
+- Low-level control over sidebar pin and hover state
+- Building a custom sidebar component that needs expand/collapse persistence
+- When NOT to use: prefer `useSidebarState` which wraps this composable and adds mobile menu support, derived `isExpanded` computed, and responsive breakpoint handling
+
+## Basic Usage
+
+```typescript
+import { useMenuExpanded } from '@vc-shell/framework';
+
+const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
+
+// Toggle pin state (persisted to localStorage)
+toggleExpanded();
+
+// Hover expand with 200ms delay
+toggleHoverExpanded(true);   // opens after delay
+toggleHoverExpanded(false);  // closes immediately
+```
+
+## API
+
+### Returns
+
+| Property | Type | Description |
+|---|---|---|
+| `isExpanded` | `Ref<boolean>` | Pinned state, persisted via `useLocalStorage` |
+| `toggleExpanded` | `() => void` | Toggle the pinned state |
+| `isHoverExpanded` | `Ref<boolean>` | Temporary hover expansion (not persisted) |
+| `toggleHoverExpanded` | `(shouldExpand?: boolean) => void` | Set hover state; opening has a 200ms delay, closing is immediate |
+
+## Recipe: Custom Sidebar with Hover Expand
+
+A common pattern is binding mouse events on the sidebar rail so the menu previews its full width on hover, without permanently pinning it open:
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import { useMenuExpanded } from "@vc-shell/framework";
+
+const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
+
+// The sidebar is visually expanded if pinned OR hover-expanded
+const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.value);
+</script>
+
+<template>
+  <aside
+    :class="{ 'sidebar--expanded': isVisuallyExpanded }"
+    @mouseenter="toggleHoverExpanded(true)"
+    @mouseleave="toggleHoverExpanded(false)"
+  >
+    <nav>
+      <!-- menu items -->
+    </nav>
+    <button @click="toggleExpanded">
+      {{ isExpanded ? 'Unpin' : 'Pin' }}
+    </button>
+  </aside>
+</template>
+```
+
+## Details
+
+- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
+- **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
+- **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
+- **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.
+
+## Tips
+
+- If you call `toggleHoverExpanded(true)` and then `toggleHoverExpanded(false)` within the 200ms window, the expansion is canceled -- the timeout is cleared before it fires.
+- The composable does not handle mobile breakpoints. For responsive behavior, use `useSidebarState` instead, which combines `useMenuExpanded` with mobile detection.
+- Each call to `useMenuExpanded()` creates a new instance with its own timeout tracking, but they share the same localStorage-backed `isExpanded` ref (via `useLocalStorage`). Multiple instances will stay in sync for the pinned state.
+
+## Related
+
+- `useSidebarState` -- higher-level composable that adds mobile menu and derived `isExpanded` computed

package/runtime/knowledge/docs/core/utilities/thumbnail/thumbnail.docs.md

@@ -0,0 +1,116 @@
+# Thumbnail URL Utility
+
+Transforms full-size image URLs into thumbnail variants by appending size suffixes before the file extension. VirtoCommerce backend generates thumbnails automatically with these suffixes.
+
+## When to Use
+
+- Use in any component that displays images at a known size smaller than the original
+- Reduces bandwidth and improves page load time significantly
+- Especially important for image lists (tables, galleries, cards)
+
+## Available Sizes
+
+### Named Presets
+
+| Preset | Use Case |
+|--------|----------|
+| `sm` | Small icons, table cells, avatar thumbnails |
+| `md` | Medium previews, cards |
+| `lg` | Large previews, hero images |
+
+### Pixel Sizes
+
+| Size | Pixels | Use Case |
+|------|--------|----------|
+| `64x64` | 64px | Table cells, tiny thumbnails |
+| `128x128` | 128px | Small tiles, list items |
+| `168x168` | 168px | Medium tiles |
+| `216x216` | 216px | Gallery tiles (md) |
+| `348x348` | 348px | Large gallery tiles |
+
+## API
+
+### `getThumbnailUrl(url, size?)`
+
+Transforms an image URL by inserting a size suffix before the file extension.
+
+```ts
+import { getThumbnailUrl } from "@core/utilities/thumbnail";
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg", "sm")
+// → "https://cdn.example.com/photo_sm.jpg"
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg", "128x128")
+// → "https://cdn.example.com/photo_128x128.jpg"
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg")
+// → "https://cdn.example.com/photo.jpg" (unchanged)
+
+getThumbnailUrl(undefined, "sm")
+// → undefined
+```
+
+**Parameters:**
+- `url` — Original image URL (string or undefined)
+- `size` — Thumbnail size preset or pixel dimensions (optional)
+
+**Returns:** Transformed URL, or original URL if size not specified
+
+### `getBestThumbnailSize(displaySize)`
+
+Maps a CSS pixel display size to the best-fit thumbnail preset. Picks the smallest thumbnail that is >= the display size.
+
+```ts
+import { getBestThumbnailSize } from "@core/utilities/thumbnail";
+
+getBestThumbnailSize(48)   // → "64x64"
+getBestThumbnailSize(96)   // → "128x128"
+getBestThumbnailSize(200)  // → "216x216"
+getBestThumbnailSize(500)  // → "lg"
+```
+
+## Usage in Components
+
+### VcImage
+
+```vue
+<VcImage
+  :src="product.imgSrc"
+  thumbnail-size="sm"
+  size="s"
+/>
+```
+
+### VcGallery
+
+Gallery auto-maps `size` prop to thumbnail size. Override with `thumbnailSize`:
+
+```vue
+<!-- Auto: sm→128x128, md→216x216, lg→348x348 -->
+<VcGallery :images="images" size="md" />
+
+<!-- Explicit override -->
+<VcGallery :images="images" thumbnail-size="128x128" />
+```
+
+Gallery preview uses `64x64` for the thumbnail strip and full-size for the main image automatically.
+
+### VcDataTable (CellImage)
+
+Table image cells use `sm` thumbnail by default — no action needed.
+
+## Types
+
+```ts
+type ThumbnailPreset = "sm" | "md" | "lg";
+type ThumbnailPixelSize = "64x64" | "128x128" | "168x168" | "216x216" | "348x348";
+type ThumbnailSize = ThumbnailPreset | ThumbnailPixelSize;
+```
+
+## Notes
+
+- The utility only transforms the URL — the backend must have generated the thumbnail for the URL to resolve
+- If a thumbnail doesn't exist on the server, the browser will show a broken image. Ensure your asset pipeline generates all required sizes.
+- The suffix is inserted before the file extension: `photo.jpg` → `photo_sm.jpg`
+- URLs without a file extension are returned unchanged
+- Already-suffixed URLs are not double-transformed

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

@@ -91,4 +91,4 @@ export default {
 - [SettingsMenu](../settings-menu/settings-menu.docs.md) -- parent container
 - [SettingsMenuItem](../settings-menu-item/settings-menu-item.docs.md) -- base menu item used internally
 - [LogoutButton](../logout-button/logout-button.docs.md) -- sibling account action
-- [ChangePasswordPage](../../pages/ChangePasswordPage/change-password-page.docs.md) -- full-page variant for expired passwords
+- [ChangePasswordPage](../../auth/ChangePasswordPage/change-password-page.docs.md) -- full-page variant for expired passwords

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

@@ -351,3 +351,7 @@ const validationHeader = computed(() =>
 - [VcContainer](../vc-container/) -- scrollable content wrapper without header or collapsing
 - [VcBanner](../vc-banner/) -- for alert/notification messages rather than content grouping
 - [VcCol](../vc-col/) / [VcRow](../vc-row/) -- for grid-based layout within card bodies
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, VcCard shows a skeleton header (if the `header` prop is set) while its body content renders normally — child components self-skeletonize via their own `BladeLoadingKey` injection.

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

@@ -250,3 +250,7 @@ interface AccordionItem {
 ## Related Components
 
 - [VcAccordionItem](./_internal/vc-accordion-item/) -- individual accordion panel (used internally and available via the default slot)
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.

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

@@ -323,3 +323,8 @@ const selected = ref<string[]>([]);
 - [VcSwitch](../vc-switch/) -- toggle switch for on/off settings
 - [VcRadioButton](../vc-radio-button/) -- mutually exclusive single selection
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping checkboxes or radio buttons
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+

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

@@ -144,3 +144,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 - [VcCheckbox](../vc-checkbox/) — individual checkbox component
 - [VcRadioGroup](../vc-radio-group/) — mutually exclusive option group
 - [VcInputGroup](../vc-input-group/) — generic form field group (used internally)
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+

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

@@ -151,3 +151,8 @@ The native color picker does not support alpha/transparency. If you need RGBA co
 
 - [VcInput](../vc-input/) -- general-purpose input (delegates to VcColorInput for `type="color"`)
 - [VcField](../vc-field/) -- read-only field display (for showing a color value without editing)
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+

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

@@ -359,3 +359,10 @@ Uses the same `--input-*` variables as VcInput for consistent styling across all
 
 - [VcInput](../vc-input/) -- general-purpose input; delegates to VcDatePicker for `type="date"` and `type="datetime-local"`
 - [VcMultivalue](../vc-multivalue/) -- can handle multiple date values with `type="date"`
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -298,3 +298,8 @@ const content = ref("<h1>Title</h1>");
 
 - [VcTextarea](../vc-textarea/) -- plain multi-line text input (no formatting)
 - [VcInput](../vc-input/) -- single-line text input
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+

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

@@ -166,3 +166,8 @@ The `type` prop affects rendering, not validation. Setting `type="email"` does n
 - [VcInput](../vc-input/) -- editable text field (use instead when user input is needed)
 - [VcLabel](../../atoms/vc-label/) -- standalone label atom used internally
 - [VcCol](../../atoms/vc-col/) -- column layout atom used for aspect ratio
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+

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

@@ -322,3 +322,8 @@ async function onUpload(files: FileList) {
 - [VcGallery](../../organisms/vc-gallery/) -- Full image gallery with preview, reorder, drag-and-drop sorting, and upload
 - [VcImageTile](../vc-image-tile/) -- Image display tile used inside galleries
 - [VcHint](../../atoms/vc-hint/) -- Used internally for error message display
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+

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

@@ -786,3 +786,10 @@ VcInput follows WAI-ARIA best practices for form fields:
 - [VcInputGroup](../vc-input-group/) -- Groups multiple inputs with shared label, error state, and disabled state
 - [VcLabel](../../atoms/vc-label/) -- The label atom used internally by VcInput
 - [VcHint](../../atoms/vc-hint/) -- The hint/error atom used internally by VcInput
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -368,3 +368,10 @@ Additionally inherits all `--input-*` CSS variables from VcInput/VcInputDropdown
 - [VcInputDropdown](../vc-input-dropdown/) -- the underlying composite input + dropdown component
 - [VcInput](../vc-input/) -- plain input for non-currency numbers
 - [VcSelect](../vc-select/) -- standalone dropdown selection
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -305,3 +305,10 @@ Replace the default dropdown toggle with a custom element using the `button` slo
 - [VcInputCurrency](../vc-input-currency/) -- Currency-specific variant with built-in locale formatting
 - [VcInput](../vc-input/) -- Standalone text input (used internally)
 - [VcSelect](../vc-select/) -- Standalone dropdown selection (used internally)
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -345,3 +345,10 @@ The component uses `--multivalue-*` variables that fall back to `--select-*` tok
 - [VcSelect](../vc-select/) -- dropdown for single/multi selection without manual entry
 - [VcInput](../vc-input/) -- single-value text input
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping form controls
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -161,3 +161,8 @@ Do not mix `binary` mode with regular `value` comparison in the same group. Bina
 - [VcSwitch](../vc-switch/) -- for on/off toggles
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper with `role="radiogroup"`
 - [VcSelect](../vc-select/) -- dropdown for larger option sets
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+