@vc-shell/vc-app-skill 2.0.0-alpha.23 → 2.0.0-alpha.25

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

@@ -2,6 +2,17 @@
 
 A bordered container with an optional header, icon, action buttons, and collapsible body. VcCard groups related content into visually distinct sections on blades and detail views. It supports three color variants for semantic meaning and smooth animated collapse/expand.
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Grouping form fields or content with a header | **VcCard** |
+| Scrollable content wrapper without a header | [VcContainer](../vc-container/) |
+| Collapsible section with rich toggle behavior | [VcAccordion](../../molecules/vc-accordion/) (for multiple exclusive panels) |
+| Alert or notification banner | [VcBanner](../vc-banner/) |
+
+Use VcCard to visually separate content sections on a blade -- especially when you need a titled header, action buttons, or collapsible body. **Do not use** VcCard for dismissible alerts or status messages (use `VcBanner`), and avoid nesting VcCard when a simple `VcContainer` with padding would suffice.
+
 ## Quick Start
 
 ```vue

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

@@ -25,6 +25,17 @@ Traditional admin panels use page-based routing: click a link, the entire viewpo
 | Layout | Full viewport | Side-by-side panels |
 | Depth | Flat (1 level) | Unlimited nesting |
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Stacked panel with toolbar, header, and lifecycle | **VcBlade** |
+| One-off confirmation or input dialog | [VcPopup](../../molecules/vc-popup/) |
+| Full-page route without blade stack | Vue Router view |
+| Scrollable content section inside a blade | [VcContainer](../../molecules/vc-container/) |
+
+Use VcBlade for every screen in a vc-shell application -- it is the standard container that integrates with the navigation system, toolbar, breadcrumbs, and unsaved-changes guards. **Do not use** VcBlade for transient dialogs (use `VcPopup` / `usePopup()`) or for content areas that do not need their own header and close button.
+
 ## Quick Start
 
 ```vue

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

@@ -18,6 +18,17 @@ Columns are defined as `<VcColumn>` child components -- no configuration objects
 - State persistence (column widths, order, sort, filters) to localStorage/sessionStorage
 - Full TypeScript generics -- `VcDataTable<Product>` propagates types to events and slots
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Tabular data with sorting, selection, pagination | **VcDataTable** |
+| Simple short list without table features | `v-for` with custom markup |
+| Image/card grid layout | [VcGallery](../vc-gallery/) |
+| Key-value detail display | [VcField](../../molecules/vc-field/) or [VcCard](../../atoms/vc-card/) |
+
+Use VcDataTable whenever you need structured rows and columns with any combination of sorting, filtering, inline editing, or column management. **Do not use** VcDataTable for simple lists of 5-10 items that need no table features -- a plain `v-for` loop is lighter. For thumbnail/card grids, prefer VcGallery.
+
 ---
 
 ## Table of Contents
@@ -1329,6 +1340,7 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 
 | Event | Payload | Description |
 |-------|---------|-------------|
+| `update:editingRows` | `T[]` | v-model update for currently editing rows. |
 | `cell-edit-init` | `{ data: T, field: string, index: number }` | Cell entered edit mode. |
 | `cell-edit-complete` | `{ data: T, field: string, newValue: unknown, index: number }` | Cell edit committed. |
 | `cell-edit-cancel` | `{ data: T, field: string, index: number }` | Cell edit cancelled. |

package/runtime/knowledge/index.md

@@ -29,9 +29,23 @@ Notable location: `useDataTableSort.docs.md` is under `ui/composables/`, not `co
 - `knowledge/patterns/blade-navigation.md`
 
 ### Framework docs to read (basename glob):
+
+**Core table components (always read):**
 - `**/vc-blade.docs.md`
 - `**/vc-data-table.docs.md`
 - `**/vc-pagination.docs.md`
+
+**Cell renderer components (read for custom #body slots in VcColumn):**
+- `**/vc-status.docs.md` — for status/state columns (variant-colored badge)
+- `**/vc-status-icon.docs.md` — for boolean columns (check/cross icon)
+- `**/vc-badge.docs.md` — for count/tag columns (numeric badge, category tag)
+- `**/vc-image.docs.md` — for image/avatar/thumbnail columns
+- `**/vc-link.docs.md` — for clickable URL/email columns
+- `**/vc-progress.docs.md` — for percentage/progress columns
+- `**/vc-rating.docs.md` — for rating columns (read-only stars)
+- `**/vc-tooltip.docs.md` — for columns with truncated text that need hover detail
+
+**Composable docs (always read):**
 - `**/useBlade.docs.md`
 - `**/useAsync.docs.md`
 - `**/useLoading.docs.md`
@@ -50,17 +64,63 @@ Notable location: `useDataTableSort.docs.md` is under `ui/composables/`, not `co
 - `knowledge/patterns/blade-navigation.md`
 
 ### Framework docs to read (basename glob):
+
+**Core form components (always read):**
 - `**/vc-blade.docs.md`
 - `**/vc-form.docs.md`
 - `**/vc-input.docs.md`
 - `**/vc-select.docs.md`
 - `**/vc-switch.docs.md`
+
+**Extended form components (read based on field types — see Field Type → Component Mapping in details-blade-pattern.md):**
+- `**/vc-textarea.docs.md` — for `text` / `rich-text` fields
+- `**/vc-editor.docs.md` — for `rich-text` fields (WYSIWYG HTML editor)
+- `**/vc-date-picker.docs.md` — for `date-time` fields (calendar widget, preferred over VcInput type="datetime-local")
+- `**/vc-checkbox.docs.md` — for `boolean` fields (alternative to VcSwitch for "agree/accept" semantics)
+- `**/vc-checkbox-group.docs.md` — for `multi-select` fields with few static options
+- `**/vc-radio-group.docs.md` — for `enum` fields with 2-5 options
+- `**/vc-input-currency.docs.md` — for `currency` fields (formatted monetary input)
+- `**/vc-multivalue.docs.md` — for `multi-select` / `tags` fields (tag-style multi-picker)
+- `**/vc-rating.docs.md` — for `rating` fields (star rating)
+- `**/vc-slider.docs.md` — for `range` fields (numeric slider)
+- `**/vc-color-input.docs.md` — for `color` fields
+- `**/vc-file-upload.docs.md` — for `file` fields (file attachment upload)
+- `**/vc-input-group.docs.md` — for grouped inputs (prefix/suffix patterns like URL, phone)
+
+**Read-only display components (read when blade has view-only fields):**
+- `**/vc-field.docs.md` — for read-only key-value display (horizontal label:value, copyable, tooltip). Use instead of VcInput for non-editable data.
+
+**Layout & display components (read when the form has sections or read-only data):**
+- `**/vc-card.docs.md` — for grouping form sections visually (ALWAYS use for 3+ field groups)
+- `**/vc-accordion.docs.md` — for collapsible form sections
+- `**/vc-badge.docs.md` — for status indicators in form headers
+- `**/vc-banner.docs.md` — for contextual alerts at top of form (error, info, warning states)
+- `**/vc-hint.docs.md` — for field-level help text or secondary descriptions
+- `**/vc-status.docs.md` — for status display in read-only areas
+- `**/vc-button.docs.md` — for inline action buttons (e.g., inside banners)
+
+**Media components (read when entity has images/gallery/video):**
+- `**/vc-image-upload.docs.md` — for `image` fields (single image upload with preview)
+- `**/vc-gallery.docs.md` — for `gallery` / `images` fields (multi-image management)
+- `**/vc-image.docs.md` — for read-only image display
+
+**Composable docs (always read):**
 - `**/useBlade.docs.md`
 - `**/useAsync.docs.md`
 - `**/useModificationTracker.docs.md`
 - `**/useLoading.docs.md`
 - `**/validation.docs.md`
 
+**Composable docs (read when entity has related sub-entities):**
+- `**/useBladeWidgets.docs.md` — for blade sidebar widgets (icon buttons with badge counts that open child blades)
+
+### Advanced patterns to read (based on design intent):
+
+Read `knowledge/patterns/` files when the design requires these patterns:
+- `knowledge/patterns/blade-widget.md` — when entity has related sub-entities that need sidebar widget navigation
+- `knowledge/patterns/dashboard-widget.md` — when module should contribute a dashboard card
+- `knowledge/patterns/notification-template.md` — when module needs push notification rendering
+
 ---
 
 ## Module Assembler

package/runtime/knowledge/patterns/assets-management.md

@@ -0,0 +1,213 @@
+# Assets Management Pattern
+
+Integrating file/image assets into a details blade. Covers two scenarios: inline gallery on the blade and an AssetsWidget opening the AssetsManager as a child blade.
+
+Both scenarios use `useAssetsManager` — a composable that wraps `useAssets` with higher-level operations (upload with deduplication, remove with confirmation, reorder). The manager operates on a **writable computed** bound to the parent entity's asset array.
+
+---
+
+## Core Setup — Writable Computed + useAssetsManager
+
+The key is creating a two-way binding between the entity's asset array and the manager:
+
+```ts
+import { computed, markRaw } from "vue";
+import { useAssetsManager, usePopup } from "@vc-shell/framework";
+import type { Asset } from "../api_client/...";
+
+// `item` is a Ref to the parent entity (e.g., product, category, order)
+const entityAssets = computed({
+  get: () => (item.value?.assets ?? []) as Asset[],
+  set: (val) => {
+    if (item.value) item.value.assets = val;
+  },
+});
+
+const { showConfirmation } = usePopup();
+
+const assetsManager = useAssetsManager(entityAssets, {
+  // Dynamic upload path — resolved at upload time
+  uploadPath: () => `/catalog/${item.value?.id}`,
+  // Optional: confirmation dialog before remove
+  confirmRemove: () => showConfirmation("Delete selected assets?"),
+});
+```
+
+**Why writable computed?** `useAssetsManager` reads and writes the asset array reactively. A writable computed bridges the gap between the manager and the nested entity field (`item.value.assets`). When the manager sets a new array after upload/remove/reorder, Vue's reactivity propagates the change to the entity — making it trackable by `useModificationTracker`.
+
+---
+
+## Scenario 1 — Inline Gallery (VcGallery on the blade)
+
+Use when images are a primary field of the entity (e.g., product images shown directly on the details blade).
+
+```vue
+<template>
+  <VcCard header="Images">
+    <div class="tw-p-2">
+      <VcGallery
+        :images="item.images"
+        :multiple="!disabled"
+        :disabled="disabled"
+        :loading="assets.loading.value"
+        @upload="assets.upload"
+        @remove="assets.remove"
+        @sort="assets.reorder"
+        @edit="onEditAsset"
+      />
+    </div>
+  </VcCard>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import { useBlade, useAssetsManager, usePopup } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
+const { showConfirmation } = usePopup();
+
+const images = computed({
+  get: () => item.value?.images ?? [],
+  set: (val) => { if (item.value) item.value.images = val; },
+});
+
+const assets = useAssetsManager(images, {
+  uploadPath: () => `/catalog/${item.value?.id}`,
+  confirmRemove: () => showConfirmation("Delete selected images?"),
+});
+
+// Open AssetsDetails blade for editing a single asset (alt text, crop, etc.)
+function onEditAsset(asset: Asset) {
+  openBlade({
+    name: "AssetsDetails",
+    options: {
+      asset,
+      assetEditHandler: (updated: Asset) => assets.updateItem(updated),
+      assetRemoveHandler: (toRemove: Asset) => assets.remove(toRemove),
+    },
+  });
+}
+</script>
+```
+
+---
+
+## Scenario 2 — AssetsWidget (child blade)
+
+Use when assets are a secondary concern shown as a widget badge. Clicking the widget opens the built-in `AssetsManager` blade.
+
+### Widget composable
+
+```ts
+// widgets/useEntityWidgets.ts
+import { computed, markRaw, type Ref, type ComputedRef } from "vue";
+import {
+  useBlade,
+  useBladeWidgets,
+  useAssetsManager,
+  usePopup,
+  type UseBladeWidgetsReturn,
+} from "@vc-shell/framework";
+
+interface Options {
+  item: Ref<Entity | undefined>;
+  disabled: ComputedRef<boolean>;
+  isVisible: ComputedRef<boolean>;
+}
+
+export function useEntityWidgets({ item, disabled, isVisible }: Options): UseBladeWidgetsReturn {
+  const { openBlade } = useBlade();
+  const { showConfirmation } = usePopup();
+
+  // Assets manager for the widget
+  const entityAssets = computed({
+    get: () => (item.value?.assets ?? []) as Asset[],
+    set: (val) => {
+      if (item.value) item.value.assets = val;
+    },
+  });
+
+  const assetsManager = useAssetsManager(entityAssets, {
+    uploadPath: () => `/files/${item.value?.id}`,
+    confirmRemove: () => showConfirmation("Delete selected assets?"),
+  });
+
+  const assetsCount = computed(() => item.value?.assets?.length ?? 0);
+
+  return useBladeWidgets([
+    {
+      id: "AssetsWidget",
+      icon: "lucide-file",
+      title: "MODULE.WIDGETS.ASSETS",
+      badge: assetsCount,
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "AssetsManager",
+          options: {
+            manager: markRaw(assetsManager),  // markRaw prevents Vue from making it reactive
+            disabled: disabled.value,
+          },
+        }),
+    },
+    // ... other widgets
+  ]);
+}
+```
+
+### Usage in the details blade
+
+```vue
+<script setup lang="ts">
+import { useEntityWidgets } from "../widgets";
+
+const { item, loading } = useEntityDetails();
+
+useEntityWidgets({
+  item,
+  disabled: computed(() => !!param.value && !item.value?.canBeModified),
+  isVisible: computed(() => !!param.value), // hide widgets on "create new"
+});
+</script>
+```
+
+---
+
+## Combining Both Scenarios
+
+A blade can use **both** an inline gallery and an assets widget. The product details blade demonstrates this:
+
+- **Inline gallery** — `useAssetsManager` for product images, bound to `item.productData.images`, rendered via `VcGallery`
+- **Assets widget** — a separate `useAssetsManager` for product file assets, bound to `item.productData.assets`, opened via `AssetsManager` blade
+
+Each manager operates on a different writable computed pointing to a different array on the entity. They are fully independent.
+
+```ts
+// Gallery assets (images)
+const productImages = computed({
+  get: () => item.value.productData?.images ?? [],
+  set: (val) => { if (item.value.productData) item.value.productData.images = val; },
+});
+const imageAssets = useAssetsManager(productImages, { uploadPath: () => `/catalog/${item.value.id}` });
+
+// Widget assets (files)
+const productFiles = computed({
+  get: () => (item.value?.productData?.assets ?? []) as Asset[],
+  set: (val) => { if (item.value?.productData) item.value.productData.assets = val; },
+});
+const fileAssets = useAssetsManager(productFiles, { uploadPath: () => `/catalog/${item.value.id}` });
+```
+
+---
+
+## Key Points
+
+| Concern | Approach |
+|---|---|
+| Binding to entity | Writable `computed` — getter reads nested array, setter writes it back |
+| Upload path | Callback `() => string` — resolved at upload time, so entity ID is available |
+| Remove confirmation | Pass `confirmRemove` returning `Promise<boolean>` via `usePopup().showConfirmation` |
+| Passing to AssetsManager blade | Wrap with `markRaw()` — prevents Vue from making the manager deeply reactive |
+| Multiple asset types | Create separate `useAssetsManager` instances per array (images vs files) |
+| Gallery edit | Open `AssetsDetails` blade, pass `assetEditHandler` and `assetRemoveHandler` callbacks |
+| Widget visibility | Use `isVisible: computed(() => !!param.value)` to hide on "create new" mode |

package/runtime/knowledge/patterns/child-blade-flow.md

@@ -0,0 +1,277 @@
+# Child Blade Flow Pattern
+
+Parent-child blade communication and nested blade workflows. Covers opening child blades, cross-blade method calls, close guards, and the picker blade pattern.
+
+---
+
+## Opening a Child Blade with `param` and `options`
+
+```ts
+import { useBlade } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
+
+openBlade({
+  name: "ProductDetails",
+  param: product.id,                    // string — entity ID, appears in URL
+  options: { mode: "edit", origin: "catalog" },  // object — runtime-only, not in URL
+  onOpen() { selectedItemId.value = product.id; },
+  onClose() { selectedItemId.value = undefined; },
+});
+```
+
+- `param` is always a **string** (entity ID). When `undefined`, the child blade is in "create new" mode.
+- `options` carries structured data that does not belong in the URL. Type it via the generic: `useBlade<{ mode: string }>()`.
+- `onOpen` / `onClose` callbacks run when the child blade opens or closes — use them to sync selection state in the parent.
+
+---
+
+## `exposeToChildren()` — Parent Exposes Methods
+
+The parent blade declares which methods child blades may invoke. Call once at the bottom of `<script setup>`.
+
+```ts
+const { exposeToChildren } = useBlade();
+
+async function reload() {
+  await searchProducts(searchQuery.value);
+}
+
+function markProductDirty() {
+  isModified.value = true;
+}
+
+// Expose at end of setup — method names must match callParent("methodName")
+exposeToChildren({ reload, markProductDirty, closeChildren });
+```
+
+- Pass a plain object of functions.
+- Calling `exposeToChildren` multiple times **overwrites** the previous context — call it once.
+- Method names must match exactly what children pass to `callParent()`.
+
+---
+
+## `callParent()` — Child Calls Parent Methods
+
+```ts
+const { callParent, closeSelf } = useBlade();
+
+async function onSave() {
+  await updateProduct(product.value);
+
+  // Tell parent list to refresh its data
+  await callParent("reload");
+
+  // Close the child blade
+  await closeSelf();
+}
+```
+
+- `callParent("methodName", args?)` invokes the function the parent exposed via `exposeToChildren`.
+- If the parent did not expose that method, the call is a **silent no-op** — no error thrown.
+- `callParent` is generic for typed return values: `const count = await callParent<number>("getCount");`
+
+---
+
+## `onBeforeClose` Guard — Confirmation Before Closing
+
+Prevents accidental data loss when the user closes a blade with unsaved changes.
+
+```ts
+import { useBlade, usePopup } from "@vc-shell/framework";
+
+const { onBeforeClose } = useBlade();
+const { showConfirmation } = usePopup();
+
+onBeforeClose(async () => {
+  if (!disabled.value && isModified.value) {
+    // showConfirmation returns true if user confirms, false if cancelled
+    return !(await showConfirmation(t("MODULE.PAGES.ALERTS.CLOSE_CONFIRMATION")));
+  }
+  return false; // no unsaved changes — allow close
+});
+```
+
+Return value semantics:
+- `false` — close is **allowed**
+- `true` — close is **blocked** (user stays on the blade)
+
+The `!(await showConfirmation(...))` idiom:
+- User clicks "Confirm" (discard) -> `true` -> `!true` = `false` -> close allowed
+- User clicks "Cancel" (stay) -> `false` -> `!false` = `true` -> close blocked
+
+---
+
+## Picker Blade Pattern
+
+A child blade opened to select an item and return the result to the parent via `callParent`.
+
+**Parent — opens picker and exposes a handler:**
+
+```ts
+const { openBlade, exposeToChildren } = useBlade();
+
+function onPickerResult(selectedItem: Category) {
+  product.value.categoryId = selectedItem.id;
+  product.value.categoryName = selectedItem.name;
+  isModified.value = true;
+}
+
+exposeToChildren({ onPickerResult });
+
+function openCategoryPicker() {
+  openBlade({
+    name: "CategoryPicker",
+    options: { currentCategoryId: product.value.categoryId },
+  });
+}
+```
+
+**Child (picker) — selects item and returns to parent:**
+
+```ts
+const { callParent, closeSelf, options } = useBlade<{ currentCategoryId?: string }>();
+
+async function onSelect(category: Category) {
+  await callParent("onPickerResult", category);
+  await closeSelf();
+}
+```
+
+The picker blade calls the parent's exposed method with the selection, then closes itself.
+
+---
+
+## Data Refresh Flow: Child Saves -> Parent Reloads
+
+The standard lifecycle when a child blade modifies data and the parent list needs to update:
+
+```
+Parent (List blade)
+  exposeToChildren({ reload })
+  openBlade({ name: "Details", param: item.id, onClose: clearSelection })
+      |
+      v
+Child (Details blade)
+  1. User edits data
+  2. onBeforeClose guard checks isModified.value
+  3. Save button handler:
+      await saveEntity(entity.value)
+      await callParent("reload")    <-- parent refetches list data
+      await closeSelf()             <-- triggers onClose callback
+          |
+          v
+Parent receives:
+  - reload() executes -> list data refreshed
+  - onClose() fires -> selectedItemId cleared
+```
+
+### Complete Example
+
+**Parent list blade:**
+
+```vue
+<script setup lang="ts">
+import { useBlade } from "@vc-shell/framework";
+
+defineOptions({ name: "ProductsList", url: "/products", isWorkspace: true });
+
+const { openBlade, exposeToChildren } = useBlade();
+const selectedItemId = ref<string>();
+
+async function reload() {
+  await searchProducts(searchQuery.value);
+}
+
+function onItemClick(event: { data: { id?: string } }) {
+  openBlade({
+    name: "ProductDetails",
+    param: event.data.id,
+    onOpen() { selectedItemId.value = event.data.id; },
+    onClose() { selectedItemId.value = undefined; },
+  });
+}
+
+exposeToChildren({ reload });
+</script>
+```
+
+**Child details blade:**
+
+```vue
+<script setup lang="ts">
+import { useBlade, usePopup, defineBladeContext } from "@vc-shell/framework";
+
+defineOptions({ name: "ProductDetails", url: "/product-details" });
+
+const { param, callParent, closeSelf, exposeToChildren, onBeforeClose } = useBlade();
+const { showConfirmation } = usePopup();
+
+const item = ref<Product>();
+const isModified = ref(false);
+
+defineBladeContext({ item });
+
+onMounted(async () => {
+  if (param.value) {
+    await loadProduct({ id: param.value });
+  }
+});
+
+async function onSave() {
+  await saveProduct(item.value);
+  await callParent("reload");
+  await closeSelf();
+}
+
+function reload() {
+  if (param.value) loadProduct({ id: param.value });
+}
+
+onBeforeClose(async () => {
+  if (isModified.value) {
+    return !(await showConfirmation("Discard unsaved changes?"));
+  }
+  return false;
+});
+
+// This blade is also a parent — expose reload to its own children
+exposeToChildren({ reload });
+</script>
+```
+
+---
+
+## Multi-Level Chain: List -> Details -> Sub-Details
+
+A "middle" blade acts as both child (calls its parent) and parent (exposes methods to its own children):
+
+```ts
+const { openBlade, callParent, exposeToChildren, closeSelf } = useBlade();
+
+// As a parent — expose reload for child blades
+async function reload() { await loadOrder(param.value!); }
+exposeToChildren({ reload });
+
+// As a child — open sub-details blade
+function openShipment(id: string) {
+  openBlade({ name: "ShipmentDetails", param: id });
+}
+
+// As a child — propagate delete up to grandparent
+async function onDelete() {
+  await deleteOrder(param.value!);
+  await callParent("reload"); // grandparent list refreshes
+  await closeSelf();
+}
+```
+
+---
+
+## Key Rules
+
+1. **`exposeToChildren` must be called once** at the end of setup — calling it again overwrites the exposed context.
+2. **`callParent` is always safe** — no-ops silently if the parent did not expose the method.
+3. **`onBeforeClose` return value is inverted** — `true` blocks close, `false` allows it.
+4. **Always `await callParent("reload")` before `closeSelf()`** — ensures parent data is refreshed before the child blade is destroyed.
+5. **Use `defineBladeContext` for widget data sharing**, `exposeToChildren` / `callParent` for cross-blade communication — they serve different purposes.