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

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.