@vc-shell/vc-app-skill 2.0.5 → 2.0.6

package/runtime/knowledge/docs/core/composables/useToolbar/useToolbar.docs.md

@@ -5,84 +5,88 @@ group: services
 ---
 
 !!! tip "Long page"
-Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Updating Button State Dynamically](#updating-button-state-dynamically), [Visibility and Permissions](#visibility-and-permissions), or [API Reference](#api-reference).
+Use the section headings to jump directly to what you need: [Primary pattern: array + toolbar-items](#primary-pattern-array--toolbar-items), [When to reach for useToolbar](#when-to-reach-for-usetoolbar), [Quick Start](#quick-start), or [API Reference](#api-reference).
 
 # useToolbar
 
-Manages toolbar buttons for blades. Each blade in the application has its own toolbar area at the top of the blade header. `useToolbar` provides a scoped API to register, update, and remove buttons within that toolbar. It automatically resolves the current blade context and cleans up registered items when the component unmounts.
+`useToolbar` is the framework's **advanced** API for blade toolbar registration. The everyday way to give a blade a toolbar is the `:toolbar-items` prop on `VcBlade` with a plain `IBladeToolbar[]` array — there is no need to call `useToolbar` in the typical case. Reach for `useToolbar` when toolbar items must appear after mount, when a blade needs to mutate another blade's toolbar, or when toolbar composition is driven from a non-blade owner.
 
-## When to Use
+## Primary pattern: array + toolbar-items
 
-- Add action buttons (Save, Delete, Refresh, Export) to a blade's toolbar header
-- Dynamically update button state (disabled, visible, icon) in response to loading or form changes
-- When NOT to use: for global app-bar actions -- use `useAppBarWidget`; for navigation links -- use `useMenuService`
+In a regular blade, declare the toolbar as `ref<IBladeToolbar[]>([...])` and bind it. Reactive fields (`isVisible`, `disabled`, computed `title`) drive visibility and state without any `watch` plumbing. The framework filters items by `permissions` and `isVisible` before render.
 
-## Quick Start
-
-```typescript
+```vue title="orders-details.vue"
 <script setup lang="ts">
-import { useToolbar } from "@vc-shell/framework";
+import { computed, ref } from "vue";
+import { useAsync, usePermissions, VcBlade, type IBladeToolbar } from "@vc-shell/framework";
 
-const { registerToolbarItem } = useToolbar();
-
-registerToolbarItem({
-  id: "save",
-  title: "Save",
-  icon: "fas fa-save",
-  clickHandler: () => saveData(),
+const { hasAccess } = usePermissions();
+const { loading: saving, action: save } = useAsync(async () => {
+  await saveOrder(order.value);
 });
+
+const bladeToolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "lucide-save",
+    disabled: computed(() => saving.value),
+    isVisible: computed(() => isDirty.value && hasAccess("order:update")),
+    clickHandler: () => save(),
+  },
+  {
+    id: "delete",
+    title: "Delete",
+    icon: "lucide-trash",
+    isVisible: computed(() => hasAccess(["order:delete", "order:manage"])),
+    clickHandler: () => confirmDelete(),
+  },
+]);
 </script>
+
+<template>
+  <VcBlade :toolbar-items="bladeToolbar" />
+</template>
 ```
 
-The button appears in the current blade's toolbar immediately. When the component unmounts, the button is automatically removed.
+Use this pattern for every blade unless you have a concrete reason to register imperatively. `IBladeToolbar` is exported from `@vc-shell/framework`; see [Core types](../../types/) for the full shape. Permission gating goes through `isVisible: computed(() => hasAccess(...))` so it stays reactive when the user's permission set changes.
 
-## Registering Toolbar Buttons
+## When to reach for useToolbar
 
-Every toolbar button requires a unique `id`. The remaining properties control appearance, behavior, and ordering.
+`useToolbar` becomes the right tool only in these cases:
 
-```typescript
-<script setup lang="ts">
+- **Dynamic registration after mount.** A toolbar item is decided after the blade is already on screen — for example, a button that appears after a long-running operation completes and never has a representation in the initial array.
+- **Cross-blade toolbar mutation.** Code in blade A needs to add or change a button on blade B. Pass `targetBladeId` to the imperative methods.
+- **Non-blade owner.** A composable or service that doesn't live inside a blade `<script setup>` but still needs to contribute toolbar items.
+- **Wildcard / global items.** Toolbar items that appear on every blade through the `*` wildcard bladeId.
+
+In all other cases, declare the array and bind `:toolbar-items`. The imperative API exists to cover edge cases, not to replace the array.
+
+## Quick Start
+
+Imperative registration from inside a blade, scoped to the current blade context:
+
+```typescript title="<script setup>"
 import { useToolbar } from "@vc-shell/framework";
 
 const { registerToolbarItem } = useToolbar();
 
-// Primary action — highest priority, appears first
 registerToolbarItem({
   id: "save",
   title: "Save",
   icon: "fas fa-save",
-  clickHandler: () => save(),
-  priority: 100,
-});
-
-// Secondary action — lower priority, appears after Save
-registerToolbarItem({
-  id: "refresh",
-  title: "Refresh",
-  icon: "fas fa-sync",
-  clickHandler: () => refresh(),
-  priority: 50,
-});
-
-// Destructive action with permission gate
-registerToolbarItem({
-  id: "delete",
-  title: "Delete",
-  icon: "fas fa-trash",
-  clickHandler: () => confirmDelete(),
-  priority: 10,
-  permissions: "order:delete",
+  clickHandler: () => saveData(),
 });
-</script>
 ```
 
-> **Note:** The `priority` field controls display order. Higher values appear first (leftmost). The default is `0`.
+The button appears in the current blade's toolbar immediately. When the component unmounts, the button is automatically removed (controlled by `autoCleanup`).
 
-## Updating Button State Dynamically
+## Updating button state dynamically
 
-Use `updateToolbarItem` to change any property of a registered button without re-registering it. This is the recommended pattern for toggling disabled state during async operations.
+Use `updateToolbarItem` to change any property of a registered button without re-registering it. This is the imperative analogue of binding a reactive `disabled` value in the array pattern.
 
 ```typescript
+// pseudo-code: replace OrderClient with your generated API client
 <script setup lang="ts">
 import { watch } from "vue";
 import { useToolbar, useAsync } from "@vc-shell/framework";
@@ -109,6 +113,8 @@ watch(loading, (isLoading) => {
 </script>
 ```
 
+In the array pattern, the same outcome reads as `disabled: computed(() => loading.value)` on the entry — no `watch` needed. Use `updateToolbarItem` only when the item has been registered imperatively and there is no array reference to mutate.
+
 You can update any subset of `IToolbarItem` properties:
 
 ```typescript
@@ -119,14 +125,12 @@ updateToolbarItem("toggle-publish", {
 });
 ```
 
-## Visibility and Permissions
+## Visibility and permissions
 
-Toolbar items support both reactive visibility and permission-based access control.
+Both reactive visibility and permission gating work the same way whether the item lives in an array or is registered imperatively — the framework filters by `isVisible` and `permissions` before render in either path.
 
 ### Reactive visibility with `isVisible`
 
-The `isVisible` property accepts a boolean, a `Ref<boolean>`, a `ComputedRef<boolean>`, or a function:
-
 ```typescript
 import { computed } from "vue";
 
@@ -143,25 +147,7 @@ registerToolbarItem({
 
 ### Permission-based registration
 
-Use `usePermissions` alongside `useToolbar` to conditionally register buttons:
-
-```typescript
-import { useToolbar, usePermissions } from "@vc-shell/framework";
-
-const { registerToolbarItem } = useToolbar();
-const { hasAccess } = usePermissions();
-
-if (hasAccess("order:delete")) {
-  registerToolbarItem({
-    id: "delete",
-    title: "Delete",
-    icon: "fas fa-trash",
-    clickHandler: () => deleteOrder(),
-  });
-}
-```
-
-Alternatively, set the `permissions` property on the item itself. The toolbar renderer checks this before displaying the button:
+Set `permissions` on the item; the renderer hides it when the user lacks the listed permission(s) (OR logic on arrays):
 
 ```typescript
 registerToolbarItem({
@@ -169,13 +155,15 @@ registerToolbarItem({
   title: "Delete",
   icon: "fas fa-trash",
   clickHandler: () => deleteOrder(),
-  permissions: ["order:delete"],
+  permissions: ["order:delete", "order:manage"],
 });
 ```
 
-## Cross-Blade Toolbar Management
+Avoid wrapping `registerToolbarItem` in an `if (hasAccess(...))` check unless you specifically want to skip side effects of the registration; the `permissions` field already gates rendering.
+
+## Cross-blade toolbar management
 
-By default, all methods operate on the current blade. Pass an explicit `targetBladeId` to manage another blade's toolbar:
+All methods accept an optional `targetBladeId` second argument. Pass it to register, update, or clear toolbar items on a blade other than the current one:
 
 ```typescript
 // Register a button on a specific child blade
@@ -185,14 +173,15 @@ registerToolbarItem({ id: "child-action", title: "Action", clickHandler: () => {
 clearBladeToolbarItems("ChildBlade");
 ```
 
-## Auto-Cleanup Control
+Pass `"*"` as the bladeId to register a global item that appears on every blade.
+
+## Auto-cleanup control
 
-By default, all toolbar items registered by a component are removed when that component unmounts (`autoCleanup: true`). Disable this for shared toolbar items that should persist:
+By default, items registered through `useToolbar()` inside a component setup are cleared when that component unmounts (`autoCleanup: true`). Disable this for items that should persist beyond the registering component:
 
 ```typescript
 const { registerToolbarItem } = useToolbar({ autoCleanup: false });
 
-// These items survive the component's unmount cycle
 registerToolbarItem({
   id: "global-help",
   title: "Help",
@@ -201,68 +190,38 @@ registerToolbarItem({
 });
 ```
 
-## Recipes
-
-### Complete Blade with Save / Delete / Refresh
+Use `autoCleanup: false` for shared toolbar items registered outside a blade lifecycle (for example, from a module's bootstrap).
 
-```typescript
-<script setup lang="ts">
-import { watch } from "vue";
-import { useToolbar, useAsync, usePermissions, useApiClient } from "@vc-shell/framework";
-import { OrderClient } from "@api/orders";
+## Recipes
 
-const { registerToolbarItem, updateToolbarItem } = useToolbar();
-const { hasAccess } = usePermissions();
-const { getApiClient } = useApiClient(OrderClient);
+### Dynamic registration after a non-blade action
 
-const { loading: saving, action: save } = useAsync(async () => {
-  const client = await getApiClient();
-  await client.updateOrder(order.value);
-});
+`useToolbar` shines when a button is decided by a non-blade flow — for example, after a long-running export completes, expose a "Download result" button on the originating blade:
 
-const { loading: refreshing, action: refresh } = useAsync(async () => {
-  const client = await getApiClient();
-  order.value = await client.getOrderById(props.param);
-});
+```ts
+// pseudo-code: replace ExportClient with your generated API client
+import { useToolbar, useBlade } from "@vc-shell/framework";
 
-registerToolbarItem({
-  id: "save",
-  title: "Save",
-  icon: "fas fa-save",
-  clickHandler: () => save(),
-  priority: 100,
-});
+const { registerToolbarItem, unregisterToolbarItem } = useToolbar();
+const { id: bladeId } = useBlade();
 
-registerToolbarItem({
-  id: "refresh",
-  title: "Refresh",
-  icon: "fas fa-sync",
-  clickHandler: () => refresh(),
-  priority: 50,
-});
+async function startExport() {
+  const job = await startServerExport();
+  await waitForCompletion(job.id);
 
-if (hasAccess("order:delete")) {
-  registerToolbarItem({
-    id: "delete",
-    title: "Delete",
-    icon: "fas fa-trash",
-    clickHandler: () => confirmDelete(),
-    priority: 10,
-  });
+  registerToolbarItem(
+    {
+      id: `download-${job.id}`,
+      title: "Download CSV",
+      icon: "lucide-download",
+      clickHandler: () => downloadResult(job.id),
+    },
+    bladeId.value,
+  );
 }
-
-// Disable all buttons while any operation is running
-watch([saving, refreshing], ([s, r]) => {
-  const busy = s || r;
-  updateToolbarItem("save", { disabled: busy });
-  updateToolbarItem("refresh", { disabled: busy });
-});
-</script>
 ```
 
-### Visual Separator Between Button Groups
-
-Use the `separator` property to add a vertical divider:
+### Visual separator between button groups
 
 ```typescript
 registerToolbarItem({
@@ -275,7 +234,21 @@ registerToolbarItem({
 });
 ```
 
-## Common Mistakes
+## Common mistakes
+
+### Reaching for `useToolbar` before considering the array pattern
+
+```typescript
+// Avoid in everyday blades — preferred pattern is the array + :toolbar-items
+const { registerToolbarItem } = useToolbar();
+registerToolbarItem({ id: "save", ... });
+
+// Preferred: declarative array bound to VcBlade
+const bladeToolbar = ref<IBladeToolbar[]>([{ id: "save", ... }]);
+// <VcBlade :toolbar-items="bladeToolbar" />
+```
+
+The array form is shorter, reactive without `watch`/`updateToolbarItem` plumbing, and easier to test.
 
 ### Forgetting the `id` property
 
@@ -299,7 +272,7 @@ registerToolbarItem({
 ### Re-registering instead of updating
 
 ```typescript
-// Wrong -- creates duplicate entries on each loading state change
+// Wrong -- duplicates the entry on each loading state change
 watch(loading, (isLoading) => {
   registerToolbarItem({
     id: "save",
@@ -315,7 +288,7 @@ watch(loading, (isLoading) => {
 });
 ```
 
-### Using useToolbar outside a component setup
+### Using `useToolbar` outside a component setup
 
 ```typescript
 // Wrong -- no component instance, autoCleanup will not work
@@ -324,7 +297,7 @@ function helperFunction() {
   registerToolbarItem({ id: "test", title: "Test" });
 }
 
-// Correct -- call in <script setup> or within setup()
+// Correct -- call in <script setup> or within setup(), or pass autoCleanup: false
 ```
 
 ## API Reference
@@ -368,8 +341,11 @@ function helperFunction() {
 | `permissions`  | `string \| string[]`                                                       | No       | Required permission(s) to display the button                   |
 | `bladeId`      | `string`                                                                   | No       | Target blade ID (auto-resolved from context)                   |
 
+`IToolbarItem` is the shape consumed by `ToolbarService`. The blade-level array binding uses `IBladeToolbar` (see [Core types](../../types/)), a near-identical shape that the framework normalizes into `IToolbarItem` before render.
+
 ## Related
 
 - [useBlade](../useBlade/) -- blade context that toolbar items are scoped to
 - [usePermissions](../usePermissions/) -- conditionally register toolbar items based on permissions
 - [useAsync](../useAsync/) -- wraps async operations with loading state for disabling buttons
+- `IBladeToolbar` in [Core types](../../types/) — the shape used by the `:toolbar-items` array binding

package/runtime/knowledge/docs/core/composables/useWidgets/useWidgets.docs.md

@@ -153,6 +153,5 @@ const allWidgets = computed(() => [...bladeWidgets.value, ...externalWidgets.val
 
 ## Related
 
-- [useWidget](../useWidget/useWidget.docs.md) -- widget-side composable for registering trigger contracts (badge, refresh)
-- [useBladeWidgets](../useBladeWidgets/) -- lifecycle-managed widget registration for blades (preferred API)
+- [useBladeWidgets](../useBladeWidgets/index.docs.md) -- lifecycle-managed widget registration for blades (preferred API)
 - `framework/core/services/widget-service.ts` -- underlying service implementation

package/runtime/knowledge/docs/core/notifications/composables/useBladeNotifications.docs.md

@@ -0,0 +1,184 @@
+---
+title: useBladeNotifications
+category: composables
+group: notifications
+---
+
+# useBladeNotifications
+
+Subscribes a blade to one or more push-notification types from the platform's SignalR stream. The composable returns a reactive list of matching unread messages, an unread count, and a `markAsRead` action. The subscription is bound to the current effect scope, so it disappears the moment the blade closes — no manual unsubscribe.
+
+This is the **Level 2** entry point in the notification system. Level 1 — `defineAppModule({ notifications })` — registers types globally with their toast configuration and is the always-on path. Level 2 layers blade-specific behavior on top of that: refresh a list, update a progress UI, mark a job complete.
+
+## When to use
+
+- A list blade needs to refresh when an entity is created, updated, or deleted elsewhere.
+- A long-running operation has a dedicated blade and the blade should update as `processedCount` / `errorCount` flow in.
+- A blade wants to surface an inline "N new" badge for messages of a specific type.
+- When NOT to use: app-wide toasts already come from the Level 1 module config — the blade does not need to subscribe just to show a toast. Reach for the blade subscription only when you also need to _react_ to the event in code.
+
+## Quick Start
+
+```ts
+import { useBladeNotifications } from "@vc-shell/framework";
+
+useBladeNotifications({
+  types: ["OfferDeletedDomainEvent"],
+  onMessage: () => reload(),
+});
+```
+
+That is the full recipe for "refresh this list when an offer is deleted somewhere in the app." The handler runs once per matching message; the framework cleans up the subscription when the blade unmounts.
+
+## API
+
+### Parameters
+
+```typescript
+interface BladeNotificationOptions<T extends PushNotification = PushNotification> {
+  types: string[];
+  filter?: (msg: T) => boolean;
+  onMessage?: (msg: T) => void;
+}
+```
+
+| Field       | Type                  | Required | Description                                                                                             |
+| ----------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `types`     | `string[]`            | Yes      | Notification types to subscribe to. Must match the `notifyType` field on incoming messages.             |
+| `filter`    | `(msg: T) => boolean` | No       | Narrow the subscription further (for example, only events for the entity this blade is editing).        |
+| `onMessage` | `(msg: T) => void`    | No       | Callback fired once per matching message. Use it to refresh data, mark progress, or update local state. |
+
+### Returns
+
+```typescript
+interface BladeNotificationReturn<T extends PushNotification = PushNotification> {
+  messages: ComputedRef<T[]>;
+  unreadCount: ComputedRef<number>;
+  markAsRead: (msg: T) => void;
+}
+```
+
+| Property      | Type                  | Description                                                                                                             |
+| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `messages`    | `ComputedRef<T[]>`    | Realtime messages matching `types` and `filter` that are still unread. Updates reactively as new messages arrive.       |
+| `unreadCount` | `ComputedRef<number>` | `messages.value.length`. Bind to a badge.                                                                               |
+| `markAsRead`  | `(msg: T) => void`    | Mark a specific message as read. Removes it from `messages` (and reduces the global unread badge in the bell dropdown). |
+
+## Typed payloads
+
+Notification payloads often extend `PushNotification` with domain fields. Pass the type parameter so `onMessage` and `messages` are typed:
+
+```ts
+import type { PushNotification } from "@vc-shell/framework";
+
+interface ImportPushNotification extends PushNotification {
+  jobId: string;
+  profileId: string;
+  profileName?: string;
+  processedCount: number;
+  errorCount: number;
+  finished: boolean;
+}
+
+const { messages, markAsRead } = useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    if (message.finished) {
+      reload();
+      markAsRead(message);
+    }
+  },
+});
+```
+
+## Common patterns
+
+### Refresh a list on any matching event
+
+```ts
+useBladeNotifications({
+  types: ["OfferDeletedDomainEvent"],
+  onMessage: () => reload(),
+});
+```
+
+Drop-in for a list blade that needs to stay in sync with deletions happening anywhere in the app.
+
+### Filter to the entity this blade owns
+
+```ts
+useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    if (message.profileId !== param.value) return; // not our job
+    if (!message.finished) updateProgress(message);
+    else finalizeImport(message);
+  },
+});
+```
+
+Two open import blades will both receive the stream; each one filters by its own `profileId` so they do not step on each other.
+
+### Drive a manual progress toast
+
+When the platform sends progress updates for a long-running job, you may want to render one persistent toast that you update as messages arrive — instead of letting Level 1 spawn a new toast per event.
+
+Set the Level 1 type to `silent` and drive the toast yourself:
+
+```ts title="src/modules/import/index.ts"
+defineAppModule({
+  notifications: {
+    ImportPushNotification: { toast: { mode: "silent" } },
+  },
+  // ...
+});
+```
+
+```ts title="pages/import-process.vue"
+import { useBladeNotifications, notification } from "@vc-shell/framework";
+
+let toastId: string | undefined;
+
+useBladeNotifications<ImportPushNotification>({
+  types: ["ImportPushNotification"],
+  onMessage: (message) => {
+    const content = message.profileName ? `${message.profileName}: ${message.title}` : message.title;
+
+    if (!toastId) {
+      toastId = notification(content, { timeout: false });
+    } else if (!message.finished) {
+      notification.update(toastId, { content });
+    } else {
+      notification.update(toastId, {
+        content,
+        timeout: 5000,
+        type: message.errorCount ? "error" : "success",
+        onClose: () => (toastId = undefined),
+      });
+    }
+  },
+});
+```
+
+The `notification()` helper returns the toast id; `notification.update` mutates it in place. The bell-dropdown history still grows — `silent` only suppresses the auto-toast.
+
+## Lifecycle
+
+`useBladeNotifications` calls `useNotificationStore().subscribe(...)` and registers `onScopeDispose(unsub)` against the current effect scope. Inside a Vue `setup()` (component or `<script setup>`) the scope is the component's; the subscription dies with the component.
+
+If you call the composable from a manually managed `effectScope()`, the cleanup runs when that scope is stopped. Calling it outside any scope is a bug — the subscription would never be released.
+
+## Tips
+
+- **Listen, do not declare.** `useBladeNotifications` does not register the notification type with the framework. Types must already be declared by some module via `defineAppModule({ notifications })`, otherwise nothing reaches `onMessage`.
+- **`messages` shows only unread.** `markAsRead(msg)` removes a message from `messages` (and from the global unread count). The notification stays in history.
+- **One subscription per call.** Calling `useBladeNotifications` multiple times in the same blade creates independent subscriptions. Combine handlers if you only need one.
+- **Type strings are case-sensitive.** The string in `types` must exactly equal the `notifyType` field on incoming messages.
+
+## Related
+
+- [useNotificationStore](./useNotificationStore.md) — direct store access for app-shell features (dropdown, badge).
+- [useNotificationContext](./useNotificationContext.md) — read the current notification inside a custom template.
+- [useBroadcastFilter](./useBroadcastFilter.md) — control which `SendSystemEvents` broadcasts reach the store.
+- [Notifications concept page.](../../concepts/notifications.md)
+- [Notifications plugin reference.](../../plugins/notifications.md)