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

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

@@ -144,3 +144,8 @@ interface RadioGroupOption<V = string | number | boolean> {
 - [VcRadioButton](../vc-radio-button/) — individual radio button component
 - [VcCheckboxGroup](../vc-checkbox-group/) — multiple-selection 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-rating/vc-rating.docs.md

@@ -251,3 +251,8 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 - [VcField](../vc-field/) -- Read-only field display, often used alongside ratings in detail views
 - [VcLabel](../../atoms/vc-label/) -- Label atom used internally for the label and tooltip
 - [VcIcon](../../atoms/vc-icon/) -- Renders the star icons internally
+
+## 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-select/vc-select.docs.md

@@ -682,3 +682,10 @@ Don't forget `:key` with cascading selects, otherwise the second select will ret
 - [VcInput](../vc-input/) — simple text field
 - [VcDatePicker](../vc-date-picker/) — date selection
 - [VcField](../vc-field/) — wrapper with label/error/hint (read-only display)
+
+## 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-slider/vc-slider.docs.md

@@ -113,3 +113,8 @@ const products = [
 ## Related Components
 
 - [VcImage](../../atoms/vc-image/) -- image component often used inside slides
+
+## 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-switch/vc-switch.docs.md

@@ -298,3 +298,8 @@ const isActive = ref(true);
 - [VcCheckbox](../vc-checkbox/) -- for checkboxes and checkbox groups
 - [VcRadioButton](../vc-radio-button/) -- for mutually exclusive choices
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping form controls
+
+## 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-textarea/vc-textarea.docs.md

@@ -305,3 +305,10 @@ const description = ref<string>("");
 - [VcInput](../vc-input/) -- single-line text input
 - [VcEditor](../vc-editor/) -- rich text / Markdown editor
 - [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/organisms/vc-blade/vc-blade.docs.md

@@ -659,3 +659,33 @@ openBlade({ name: "ProductsList" });
 | `useLoading()` | Merges multiple loading refs into a single boolean. |
 | `usePopup()` | Confirmation dialogs and error messages. |
 | `useBladeWidgets()` | Register contextual widgets for the blade widget area. |
+
+## Content Skeleton Mode
+
+When `loading=true`, VcBlade provides `BladeLoadingKey` to all descendant components via Vue's provide/inject. Each framework UI component automatically renders a skeleton placeholder matching its visual footprint.
+
+### How It Works
+
+1. Set `loading` prop on VcBlade (typically bound to your data-fetching composable's loading ref)
+2. All child components (`VcInput`, `VcSelect`, `VcCard`, etc.) detect the loading state and render skeletons
+3. Layout containers (`VcContainer`, `VcRow`, `VcCol`, `VcForm`) are transparent — they preserve layout structure
+4. When loading completes, components switch to their normal rendering
+
+### What Shows During Loading
+
+- **Config-gated fields** (`v-if="config.showName"`) — config is available immediately, so these fields show skeletons
+- **Data-gated fields** (`v-if="item.productData"`) — data not yet loaded, so these fields don't appear in the skeleton
+- **Header and toolbar** — have their own dedicated skeletons (unchanged)
+
+No changes to existing blade pages are required.
+
+### Custom Components
+
+To make custom components skeleton-aware:
+
+```ts
+import { useBladeLoading } from "@vc-shell/framework";
+
+const bladeLoading = useBladeLoading();
+// bladeLoading.value === true when parent VcBlade is loading
+```

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

@@ -619,6 +619,33 @@ Customize expand/collapse icons:
 </VcDataTable>
 ```
 
+### Conditional expansion
+
+Use `isRowExpandable` to control which rows show the expand toggle. Rows that fail the predicate cannot be expanded:
+
+```vue
+<template>
+  <VcDataTable
+    :items="orders"
+    v-model:expanded-rows="expandedRows"
+    :is-row-expandable="(order) => order.lineItems.length > 0"
+  >
+    <VcColumn id="expand" :expander="true" :width="40" />
+    <VcColumn id="orderNumber" field="number" title="Order #" />
+
+    <template #expansion="{ data }">
+      <div class="tw-p-4">
+        <p v-for="item in data.lineItems" :key="item.id">{{ item.name }}</p>
+      </div>
+    </template>
+  </VcDataTable>
+</template>
+
+<script setup lang="ts">
+const expandedRows = ref<Order[]>([]);
+</script>
+```
+
 ---
 
 ## Row Grouping
@@ -1264,6 +1291,7 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 | `expandedRows` | `T[]` | `[]` | Expanded rows. Use with `v-model:expandedRows`. |
 | `expandedRowIcon` | `string` | `"lucide-chevron-down"` | Icon for expanded state. |
 | `collapsedRowIcon` | `string` | `"lucide-chevron-right"` | Icon for collapsed state. |
+| `isRowExpandable` | `(data: T) => boolean` | -- | Per-row predicate to hide the expand toggle. |
 
 ### Row Grouping
 

package/runtime/knowledge/migration-prompts/blade-form-migration.md

@@ -0,0 +1,246 @@
+---
+name: blade-form-migration
+description: AI transformation rules for useForm + onBeforeClose → useBladeForm.
+---
+
+# Blade Form Migration: useForm → useBladeForm
+
+Replace manual wiring of `useForm()` (vee-validate) + `useModificationTracker()` + `useBeforeUnload()` + `onBeforeClose()` with the unified `useBladeForm()` composable.
+
+## RULE 1: Replace useForm + onBeforeClose with useBladeForm
+
+**BEFORE:**
+
+```typescript
+import { useForm } from "vee-validate";
+import { useBeforeUnload, useModificationTracker, useBlade, usePopup } from "@vc-shell/framework";
+
+const { item, loading, load, save } = useMyDetails();
+const { onBeforeClose } = useBlade();
+const { showConfirmation } = usePopup();
+
+const { errorBag, setFieldError, meta: formMeta } = useForm({
+  initialValues: item,
+});
+
+const { currentValue, resetModificationState, isModified } = useModificationTracker(item);
+
+useBeforeUnload(computed(() => isModified.value));
+
+onBeforeClose(async () => {
+  if (isModified.value) {
+    return showConfirmation(t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"));
+  }
+  return true;
+});
+
+const canSave = computed(
+  () => isModified.value && formMeta.value.valid && !loading.value,
+);
+
+async function handleSave() {
+  await save(item.value);
+  resetModificationState();
+}
+
+async function handleCancel() {
+  item.value = JSON.parse(JSON.stringify(currentValue.value));
+  resetModificationState();
+}
+```
+
+**AFTER:**
+
+```typescript
+import { useBladeForm } from "@vc-shell/framework";
+
+const { item, loading, load, save } = useMyDetails();
+
+const { canSave, isModified, setBaseline, revert, setFieldError, errorBag } = useBladeForm({
+  data: item,
+  closeConfirmMessage: () => t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"),
+});
+
+watch(item, () => {
+  if (item.value) setBaseline();
+}, { once: true });
+
+async function handleSave() {
+  await save(item.value);
+  setBaseline();
+}
+```
+
+## RULE 2: Remove onBeforeClose Entirely
+
+`useBladeForm` handles the unsaved-changes guard automatically via `autoBeforeClose` (defaults to `true`).
+
+**BEFORE:**
+
+```typescript
+const { onBeforeClose } = useBlade();
+
+onBeforeClose(async () => {
+  if (formMeta.value.dirty) {
+    return confirm("You have unsaved changes. Discard?");
+  }
+  return true;
+});
+```
+
+**AFTER:**
+
+```typescript
+// Remove entirely. useBladeForm handles this.
+// If you need a custom message, pass closeConfirmMessage option:
+const form = useBladeForm({
+  data: item,
+  closeConfirmMessage: () => t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"),
+});
+```
+
+## RULE 3: Update Toolbar Disabled Logic
+
+**BEFORE:**
+
+```typescript
+const canSave = computed(
+  () => !meta.value.valid || !isModified.value,
+);
+
+// or in toolbar items:
+{
+  id: "save",
+  disabled: computed(() => !formMeta.value.valid || !isModified.value),
+}
+```
+
+**AFTER:**
+
+```typescript
+// canSave is returned directly from useBladeForm:
+const { canSave } = useBladeForm({ data: item });
+
+// In toolbar items:
+{
+  id: "save",
+  disabled: computed(() => !canSave.value),
+}
+```
+
+For additional disabled conditions (e.g., async validation in progress), use `canSaveOverride`:
+
+```typescript
+const { canSave } = useBladeForm({
+  data: item,
+  canSaveOverride: computed(() => !isSkuValidating.value && !loading.value),
+});
+```
+
+## RULE 4: Keep Field from vee-validate
+
+Only remove `useForm` from vee-validate imports. Keep `Field`, `ErrorMessage`, and other template-level components — they still work with `useBladeForm` which uses vee-validate internally.
+
+**BEFORE:**
+
+```typescript
+import { useForm, Field, ErrorMessage } from "vee-validate";
+```
+
+**AFTER:**
+
+```typescript
+import { Field, ErrorMessage } from "vee-validate";
+```
+
+## RULE 5: Remove useBeforeUnload / useModificationTracker
+
+`useBladeForm` handles both browser unload guards and modification tracking internally.
+
+**BEFORE:**
+
+```typescript
+import { useBeforeUnload, useModificationTracker } from "@vc-shell/framework";
+
+const { currentValue, resetModificationState, isModified } = useModificationTracker(item);
+useBeforeUnload(computed(() => isModified.value));
+```
+
+**AFTER:**
+
+```typescript
+// Remove entirely. useBladeForm provides:
+// - isModified (deep comparison against baseline)
+// - setBaseline() (replaces resetModificationState)
+// - revert() (replaces manual JSON.parse(JSON.stringify(currentValue.value)))
+// - Browser unload guard (automatic)
+```
+
+Also remove `useModificationTracker` from data composables if present:
+
+**BEFORE (data composable):**
+
+```typescript
+export function useMyDetails() {
+  const item = ref<MyItem>();
+  const { currentValue, resetModificationState, isModified } = useModificationTracker(item);
+
+  async function load(id: string) {
+    item.value = await api.get(id);
+    resetModificationState();
+  }
+
+  return { item, currentValue, resetModificationState, isModified, load, save };
+}
+```
+
+**AFTER (data composable):**
+
+```typescript
+export function useMyDetails() {
+  const item = ref<MyItem>();
+
+  async function load(id: string) {
+    item.value = await api.get(id);
+  }
+
+  return { item, load, save };
+}
+```
+
+## Template Changes
+
+Remove `:modified` prop from `<VcBlade>` — it is auto-detected via provide/inject.
+
+**BEFORE:**
+
+```vue
+<template>
+  <VcBlade :modified="isModified" :closable="true">
+    <!-- content -->
+  </VcBlade>
+</template>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <VcBlade :closable="true">
+    <!-- content — no :modified prop needed -->
+  </VcBlade>
+</template>
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm the blade shows a modified indicator when data changes
+3. Confirm closing a modified blade shows the confirmation dialog
+4. Confirm the save button is disabled when form is clean or invalid
+5. Confirm `setBaseline()` is called after initial load and after save
+6. Confirm cancel/revert restores data to the last baseline
+7. Confirm `useModificationTracker` is removed from data composables
+8. Confirm no stale imports of `useForm`, `useBeforeUnload`, `useModificationTracker`, or `onBeforeClose`

package/runtime/knowledge/migration-prompts/blade-props-migration.md

@@ -0,0 +1,195 @@
+---
+name: blade-props-migration
+description: AI transformation rules for reusable blade components skipped by CLI migrator.
+---
+
+# Blade Props Migration: Boilerplate Removal
+
+Remove blade prop/emit boilerplate from blade pages. VcBlade is now context-aware — it reads `expanded` and `closable` from the BladeDescriptor automatically via provide/inject. Use `useBlade()` for `param`, `options`, `closeSelf`, and `callParent`.
+
+## RULE 1: Remove Blade Prop Forwarding from Template
+
+Remove `:expanded`, `:closable`, `@close`, `@expand`, `@collapse` from the `<VcBlade>` tag.
+
+**BEFORE:**
+
+```vue
+<template>
+  <VcBlade
+    :title="bladeTitle"
+    :expanded="expanded"
+    :closable="closable"
+    :toolbar-items="bladeToolbar"
+    @close="$emit('close:blade')"
+    @expand="$emit('expand:blade')"
+    @collapse="$emit('collapse:blade')"
+  >
+    <VcDataTable ... />
+  </VcBlade>
+</template>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <VcBlade
+    :title="bladeTitle"
+    :toolbar-items="bladeToolbar"
+  >
+    <VcDataTable ... />
+  </VcBlade>
+</template>
+```
+
+## RULE 2: Remove Props and Emits Interfaces
+
+Remove `expanded`, `closable`, `param`, `options` from Props interface. Remove blade events from Emits. Use `useBlade()` to access `param` and `options`.
+
+**BEFORE:**
+
+```typescript
+export interface Props {
+  expanded?: boolean;
+  closable?: boolean;
+  param?: string;
+  options?: { sellerProduct?: SellerProduct };
+}
+
+export interface Emits {
+  (event: "parent:call", args: IParentCallArgs): void;
+  (event: "close:blade"): void;
+  (event: "collapse:blade"): void;
+  (event: "expand:blade"): void;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  expanded: true,
+  closable: true,
+});
+const emit = defineEmits<Emits>();
+```
+
+**AFTER:**
+
+```typescript
+import { useBlade } from "@vc-shell/framework";
+
+const { param, options, openBlade, closeSelf, callParent } =
+  useBlade<{ sellerProduct?: SellerProduct }>();
+```
+
+If the Props interface has other non-blade props, keep only those:
+
+```typescript
+// Keep non-blade props
+export interface Props {
+  config?: DetailConfig;
+}
+
+const props = defineProps<Props>();
+
+// Blade concerns via composable
+const { param, options, closeSelf, callParent } = useBlade<{ orderId: string }>();
+```
+
+## RULE 3: Replace emit("parent:call") with callParent()
+
+**BEFORE:**
+
+```typescript
+const emit = defineEmits<Emits>();
+
+const reload = async () => {
+  await loadOffers({ ... });
+  emit("parent:call", { method: "reload" });
+};
+
+function onItemSelect(item: Product) {
+  emit("parent:call", { method: "onItemClick", args: { data: item } });
+}
+```
+
+**AFTER:**
+
+```typescript
+const { callParent } = useBlade();
+
+const reload = async () => {
+  await loadOffers({ ... });
+  callParent("reload");
+};
+
+function onItemSelect(item: Product) {
+  callParent("onItemClick", { data: item });
+}
+```
+
+## RULE 4: Replace emit("close:blade") with closeSelf()
+
+**BEFORE:**
+
+```typescript
+const emit = defineEmits<Emits>();
+
+function handleClose() {
+  emit("close:blade");
+}
+
+// or in template:
+// @click="$emit('close:blade')"
+```
+
+**AFTER:**
+
+```typescript
+const { closeSelf } = useBlade();
+
+function handleClose() {
+  closeSelf();
+}
+
+// or in template:
+// @click="closeSelf()"
+```
+
+## Wrapper Components
+
+If a wrapper component forwards blade props to a base component, remove the forwarding. The base component should call `useBlade()` directly.
+
+**BEFORE:**
+
+```vue
+<template>
+  <ProductDetailsBase
+    :expanded="expanded"
+    :closable="closable"
+    :param="param"
+    :options="options"
+    @parent:call="$emit('parent:call', $event)"
+    @close:blade="$emit('close:blade')"
+    @expand:blade="$emit('expand:blade')"
+    @collapse:blade="$emit('collapse:blade')"
+  />
+</template>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <ProductDetailsBase />
+</template>
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm blades open and close correctly
+3. Confirm `param.value` is accessible in script (use `param` without `.value` in templates)
+4. Confirm `options.value` provides typed options from parent
+5. Confirm `callParent()` triggers the parent's exposed method
+6. Confirm no remaining `emit("close:blade")` or `emit("parent:call", ...)` calls
+7. Confirm no remaining `:expanded`, `:closable`, `@close`, `@expand`, `@collapse` on `<VcBlade>`