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

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

@@ -0,0 +1,117 @@
+---
+title: useBroadcastFilter
+category: composables
+group: notifications
+---
+
+# useBroadcastFilter
+
+Controls which **broadcast** push notifications reach the store. The platform SignalR hub delivers messages through two channels: `Send` (targeted to a specific user) and `SendSystemEvents` (broadcast to everyone connected). Broadcasts run through the filter installed here; targeted messages are always accepted.
+
+This is the standard mechanism for scoping a multi-tenant app — show a seller only the broadcasts that mention them, hide events from other tenants. Without a filter every broadcast lands in every user's history.
+
+## When to use
+
+- Multi-tenant apps where the same broadcast topic carries events for different tenants (sellers, organizations, departments) and each user should only see their slice.
+- Apps that want to drop noisy `IndexProgressPushNotification` or similar maintenance events for non-admin roles.
+- When NOT to use: filtering targeted notifications. The platform already delivers `Send` messages only to the addressed user; `useBroadcastFilter` does not see them.
+
+## Quick Start
+
+```ts
+import { useBroadcastFilter, useUser } from "@vc-shell/framework";
+import { onMounted } from "vue";
+
+const { user } = useUser();
+const { setBroadcastFilter } = useBroadcastFilter();
+
+onMounted(() => {
+  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
+});
+```
+
+Install the filter once at app bootstrap (or whenever the active user changes). Every incoming broadcast is run through it; messages that return `false` are dropped before they touch history, toasts, or subscribers.
+
+## API
+
+### Returns
+
+```typescript
+interface UseBroadcastFilterReturn {
+  setBroadcastFilter(fn: (msg: PushNotification) => boolean): void;
+  clearBroadcastFilter(): void;
+}
+```
+
+| Method                 | Type                                           | Description                                                                               |
+| ---------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `setBroadcastFilter`   | `((msg: PushNotification) => boolean) => void` | Install the filter. Replaces any previous filter — there is at most one active at a time. |
+| `clearBroadcastFilter` | `() => void`                                   | Remove the filter. All subsequent broadcasts are accepted.                                |
+
+The filter returns `true` to **accept** a message, `false` to **drop** it.
+
+## Common patterns
+
+### Scope by current user
+
+```ts
+onMounted(() => {
+  setBroadcastFilter((msg) => msg.creator === user.value?.userName);
+});
+```
+
+`creator` is the user that originated the event on the platform side. This is the canonical "show me my own broadcasts" filter in multi-tenant back-office apps.
+
+### Scope by tenant id
+
+```ts
+onMounted(() => {
+  setBroadcastFilter((msg) => (msg as TenantPush).sellerId === currentSellerId.value);
+});
+```
+
+When your broadcast payloads carry a tenant id, gate on it instead of `creator`. The cast clarifies typing without expanding `PushNotification` for every caller.
+
+### Re-install on user switch
+
+```ts
+import { watch } from "vue";
+
+watch(
+  () => user.value?.userName,
+  (name) => {
+    if (!name) clearBroadcastFilter();
+    else setBroadcastFilter((msg) => msg.creator === name);
+  },
+  { immediate: true },
+);
+```
+
+If the app supports user switching without a full reload (impersonation, multi-account), re-install the filter on every change. There is only one slot — installing again replaces the previous filter.
+
+### Drop a noisy type entirely
+
+```ts
+setBroadcastFilter((msg) => msg.notifyType !== "IndexProgressPushNotification");
+```
+
+Broadcast-only suppression. To suppress targeted messages too, set `toast: false` or `toast: { mode: "silent" }` on the type's `defineAppModule({ notifications })` config — that controls the toast surface; the history still records the event.
+
+## Behavior
+
+- The filter applies only to messages ingested with the `broadcast: true` flag (the SignalR `SendSystemEvents` channel).
+- Targeted messages (`Send`) bypass the filter entirely.
+- Installing a filter mid-session does not retroactively prune `history` or `realtime`. Past broadcasts stay; only future ones are filtered.
+- The filter is a single function. To compose multiple predicates, `&&` them inside one callback.
+
+## Tips
+
+- **Install once, early.** Setting the filter in `App.vue` `onMounted` (after authentication) is the canonical placement, so messages arriving before the first blade mounts are already scoped.
+- **Filter exceptions go straight to the console.** If your predicate throws, the message is dropped. Wrap the logic if you are reading off potentially missing fields.
+- **Do not query the store from inside the filter.** The store is `useBroadcastFilter`'s parent — calling back into it during ingestion causes re-entrancy.
+
+## Related
+
+- [useNotificationStore](./useNotificationStore.md) — exposes the same set/clear methods plus the rest of the store API.
+- [useBladeNotifications](./useBladeNotifications.md) — blade-scoped subscription that sees broadcasts after filtering.
+- [Notifications concept page — broadcasts.](../../concepts/notifications.md#broadcast-vs-targeted)

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

@@ -0,0 +1,150 @@
+---
+title: useNotificationContext
+category: composables
+group: notifications
+---
+
+# useNotificationContext
+
+Reads the current `PushNotification` payload inside a custom notification template. The framework provides the message via Vue's `inject()` from the dropdown or toast surface that hosts the template — the composable returns a reactive `ComputedRef` over it.
+
+This is the one piece you write when a notification type registered with `defineAppModule({ notifications: { Type: { template } } })` needs a richer rendering than the default `NotificationTemplate` chrome — for example, formatting a domain-specific status, deriving a colored accent, or wiring a click handler that opens the relevant blade.
+
+## When to use
+
+- Implementing the `template` component for a notification type registered through `defineAppModule({ notifications })`.
+- Reading typed payload fields (status, entity name, job id) to drive the template's layout, color, or actions.
+- When NOT to use: anywhere outside a notification template. The composable throws if the inject context is not present.
+
+## Quick Start
+
+```vue
+<script lang="ts" setup>
+import { PushNotification, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
+import { computed } from "vue";
+
+interface IOrderPushNotification extends PushNotification {
+  orderId: string;
+  total: number;
+}
+
+const notificationRef = useNotificationContext<IOrderPushNotification>();
+const notification = computed(() => notificationRef.value);
+</script>
+
+<template>
+  <NotificationTemplate
+    :title="notification.title ?? ''"
+    :notification="notification"
+  >
+    <p>Order {{ notification.orderId }} — ${{ notification.total }}</p>
+  </NotificationTemplate>
+</template>
+```
+
+## API
+
+### Parameters
+
+None. The composable is always called without arguments. Generic type parameter narrows the payload shape:
+
+```typescript
+function useNotificationContext<T extends PushNotification = PushNotification>(): ComputedRef<T>;
+```
+
+### Returns
+
+`ComputedRef<T>` — reactive reference to the current `PushNotification` (or your extended subtype via the generic). Update reactively if the same template instance is reused for a refreshed payload (for example, when a progress message is updated through `notification.update`).
+
+## Common patterns
+
+### Compute display strings from payload fields
+
+```vue
+<script lang="ts" setup>
+import { PushNotification, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
+import { computed } from "vue";
+import { useI18n } from "vue-i18n";
+
+interface IProductPush extends PushNotification {
+  productName?: string;
+  newStatus?: string;
+}
+
+const ctx = useNotificationContext<IProductPush>();
+const notification = computed(() => ctx.value);
+const { t } = useI18n({ useScope: "global" });
+
+const title = computed(() => (notification.value.productName ? `${t("PRODUCTS.PUSH.PRODUCT")} "${notification.value.productName}" ${t("PRODUCTS.PUSH.UPDATE")}` : (notification.value.title ?? "")));
+</script>
+```
+
+### Open a blade on click
+
+```vue
+<script lang="ts" setup>
+import { useBlade, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
+import { computed } from "vue";
+
+const { openBlade } = useBlade();
+const ctx = useNotificationContext<IOrderPush>();
+const notification = computed(() => ctx.value);
+
+function onClick() {
+  if (!notification.value.orderId) return;
+  openBlade({ name: "OrderDetails", param: notification.value.orderId });
+}
+</script>
+
+<template>
+  <NotificationTemplate
+    :title="notification.title ?? ''"
+    :notification="notification"
+    @click="onClick"
+  >
+    <p>{{ notification.description }}</p>
+  </NotificationTemplate>
+</template>
+```
+
+`NotificationTemplate` re-emits the click event so the host (dropdown row, toast) can close itself before your handler runs.
+
+### Color the template by status
+
+```ts
+const notificationStyle = computed(() => {
+  switch (notification.value.newStatus) {
+    case "Approved":
+      return { color: "var(--success-400)", icon: "lucide-check-circle" };
+    case "RequestChanges":
+      return { color: "var(--danger-400)", icon: "lucide-alert-circle" };
+    case "WaitForApproval":
+      return { color: "var(--warning-600)", icon: "lucide-clock" };
+    default:
+      return { color: "var(--primary-400)", icon: "lucide-bell" };
+  }
+});
+```
+
+`NotificationTemplate` accepts `:color` and `:icon` props that line up with these computeds — the dropdown row and the toast use the same template, so the styling stays consistent across surfaces.
+
+## Where the template runs
+
+Notification templates render in two places:
+
+- **In the bell dropdown**, as one row in the history list.
+- **As a toast**, when the type's `toast.mode` is `"auto"` or `"progress"` (set the mode to `"silent"` to render only in the dropdown).
+
+The template component must be **the same** in both — register it once on `defineAppModule({ notifications })` and the framework reuses it everywhere.
+
+## Tips
+
+- **Always type the generic.** `useNotificationContext<MyPushType>()` enables autocompletion on payload fields. Without it everything degrades to `PushNotification`.
+- **`computed(() => ctx.value)` is idiomatic** in the example apps because consumers want a regular `Ref` shape to pass into child components and template bindings. Direct access via `ctx.value` is fine too.
+- **Do not subscribe inside a template.** The template renders one message; if you need to react to other notifications, do that in a blade with `useBladeNotifications`.
+
+## Related
+
+- [useBladeNotifications](./useBladeNotifications.md) — subscribe to types inside a blade.
+- [useNotificationStore](./useNotificationStore.md) — access the underlying store.
+- [Notifications concept page.](../../concepts/notifications.md)

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

@@ -0,0 +1,113 @@
+---
+title: useNotificationStore
+category: composables
+group: notifications
+---
+
+# useNotificationStore
+
+!!! warning "Advanced — most apps do not need this"
+Reach for [useBladeNotifications](./useBladeNotifications.md), [useBroadcastFilter](./useBroadcastFilter.md), and the `notifications` option on `defineAppModule` first. The bell dropdown, unread badge, and toast pipeline are already wired by the shell. This composable is an **escape hatch** for the small set of cases where those facades do not fit.
+
+Returns the singleton store that backs the framework's notification system. Direct access exposes the full reactive state plus low-level actions: subscribing, ingesting synthetic messages, controlling the broadcast filter, paging history.
+
+## When to use
+
+There are only two cases where this composable belongs in app code:
+
+- **A test or scripted harness** that needs to push synthetic messages through the same pipeline SignalR uses, via `ingest`. Real-time production code never calls `ingest` directly.
+- **A custom shell** that replaces the framework's bell dropdown entirely — typically a module-federation host with its own chrome — and therefore needs to bind to `history`, `unreadCount`, and `markAllAsRead` outside the default surface. Apps that use the standard `VcApp` shell do not need this; the dropdown is already there.
+
+For everything else — reacting in a blade, gating broadcasts, registering types, displaying a toast — use the facades. Direct store mutations can bypass invariants the facades enforce (broadcast filter, scope-aware cleanup, type validation).
+
+## Quick Start
+
+```ts
+import { useNotificationStore } from "@vc-shell/framework";
+
+const store = useNotificationStore();
+
+await store.loadHistory(50);
+```
+
+## API
+
+The store exposes the full reactive state plus actions. The shape is summarized below; the underlying types live in `core/notifications/store.ts` and `core/notifications/types.ts`.
+
+| Member                   | Type                                                   | Description                                                                                                                                                                |
+| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registry`               | `Map<string, NotificationTypeConfig>`                  | Notification types registered through `defineAppModule({ notifications })`.                                                                                                |
+| `history`                | `Ref<PushNotification[]>`                              | Full history (server-loaded plus ingested), newest first.                                                                                                                  |
+| `realtime`               | `Ref<PushNotification[]>`                              | Session-only realtime queue from the SignalR hub. Drives `messages` in `useBladeNotifications`.                                                                            |
+| `unreadCount`            | `ComputedRef<number>`                                  | Count of unread items in `history`. Drives the bell badge.                                                                                                                 |
+| `hasUnread`              | `ComputedRef<boolean>`                                 | Convenience boolean over `unreadCount`.                                                                                                                                    |
+| `registerType(t, cfg)`   | `(string, NotificationTypeConfig) => void`             | Register a type. Called by the framework when `defineAppModule({ notifications })` runs — rarely needed manually.                                                          |
+| `ingest(msg, opts?)`     | `(PushNotification, { broadcast?: boolean }?) => void` | Push a message through the same pipeline SignalR uses. Broadcasts pass through the active broadcast filter.                                                                |
+| `setBroadcastFilter(fn)` | `((PushNotification) => boolean) => void`              | Install a filter for broadcast messages. Prefer [useBroadcastFilter](./useBroadcastFilter.md) — same method.                                                               |
+| `clearBroadcastFilter()` | `() => void`                                           | Remove the broadcast filter.                                                                                                                                               |
+| `markAsRead(msg)`        | `(PushNotification) => void`                           | Mark one message as read. Mirrors to the server.                                                                                                                           |
+| `markAllAsRead()`        | `() => Promise<void>`                                  | Optimistic mark-all with rollback on failure.                                                                                                                              |
+| `loadHistory(take?)`     | `(number?) => Promise<void>`                           | Fetch history from the platform. Default page size is 10. The shell already calls this at bootstrap.                                                                       |
+| `subscribe(opts)`        | `({ types, filter?, handler? }) => () => void`         | Low-level pub/sub. Returns an `unsub` function. Inside blades use [useBladeNotifications](./useBladeNotifications.md) — it wraps this and registers cleanup automatically. |
+| `getByType(type)`        | `(string) => PushNotification[]`                       | Filter `history` by `notifyType`.                                                                                                                                          |
+
+## Escape-hatch patterns
+
+### Manually ingest a message (tests, scripted replay)
+
+```ts
+const store = useNotificationStore();
+
+store.ingest({
+  id: "test-1",
+  notifyType: "OrderCreatedDomainEvent",
+  title: "Test order",
+  isNew: true,
+  created: new Date().toISOString(),
+} as PushNotification);
+```
+
+The ingest pipeline runs the configured toast logic and notifies subscribers exactly like a real SignalR message would, so you can verify the end-to-end behavior of `defineAppModule({ notifications })` + `useBladeNotifications` without a live hub.
+
+`ingest` with `{ broadcast: true }` simulates `SendSystemEvents` and runs the broadcast filter; without it the message is treated as targeted and bypasses the filter.
+
+### Custom shell surface (replace the bell dropdown)
+
+When you are building a shell variant that omits the framework's bell dropdown — for example, a module-federation host that renders its own header — bind to the store directly:
+
+```ts
+import { useNotificationStore } from "@vc-shell/framework";
+import { onMounted } from "vue";
+
+const store = useNotificationStore();
+
+onMounted(() => store.loadHistory(100));
+// Use store.history, store.unreadCount, store.markAllAsRead in your own components.
+```
+
+If you are using `VcApp` (the default shell), do **not** do this — the dropdown is already mounted and binding to the same store, so a second surface duplicates what is already on screen.
+
+## Resolution
+
+`useNotificationStore()` resolves in this order:
+
+1. If called inside a Vue component's `setup` (or `app.runWithContext()`), it uses `inject(NotificationStoreKey)`.
+2. Otherwise it returns a module-level singleton created on first call.
+
+The fallback exists so module-federation remotes and standalone scripts see the same store the host app uses.
+
+## Tips
+
+- **Prefer facades.** Every time you find yourself writing `store.subscribe(...)` inside a blade, you want `useBladeNotifications`. Every time you write `store.setBroadcastFilter(...)`, you want `useBroadcastFilter`. The facades exist to keep cleanup, typing, and invariants in one place.
+- **Do not iterate `realtime` for unread counts inside a blade.** That is what `useBladeNotifications` does correctly. Touching `realtime` directly couples your component to shell internals.
+- **`loadHistory` replaces, then merges.** Calling it again pages in more entries and merges them with the existing history.
+- **`markAllAsRead` is optimistic.** The local state flips immediately; if the server call fails the change is rolled back and an error toast surfaces.
+- **Direct store mutations can bypass invariants.** The broadcast filter only runs through `ingest({ broadcast: true })`. Pushing arrays around `history.value` directly is not supported.
+
+## Related
+
+- [useBladeNotifications](./useBladeNotifications.md) — recommended scope-aware subscription. **Start here.**
+- [useBroadcastFilter](./useBroadcastFilter.md) — broadcast acceptance gate.
+- [useNotificationContext](./useNotificationContext.md) — payload access inside templates.
+- [Notifications concept page.](../../concepts/notifications.md)
+- [Notifications plugin reference.](../../plugins/notifications.md)

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

@@ -24,21 +24,18 @@ The notification system receives `PushNotification` messages from the platform S
 
 ## Architecture
 
-```
-PushNotification (SignalR)
-        |
-  ┌─────┴─────┐
-  Send     SendSystemEvents
-  |            |
-  |     broadcastFilter?
-  |            |
-  v            v
-  NotificationStore.ingest()
-        |
-        +---> history[]  (persistent, loaded from API)
-        +---> realtime[] (session-only, from SignalR)
-        +---> ToastController.handle()   [Level 1: always-on]
-        +---> subscriber callbacks        [Level 2: blade-scoped]
+```mermaid
+flowchart TD
+    H["PushNotification (SignalR hub)"] --> S["Send<br/>(targeted)"]
+    H --> B["SendSystemEvents<br/>(broadcast)"]
+    B --> F{"broadcastFilter?"}
+    F -->|accept| I["NotificationStore.ingest()"]
+    F -->|reject| X["dropped"]
+    S --> I
+    I --> Hist["history[]<br/>(persistent, loaded from API)"]
+    I --> RT["realtime[]<br/>(session-only)"]
+    I --> Toast["ToastController.handle()<br/>Level 1: always-on"]
+    I --> Sub["subscriber callbacks<br/>Level 2: blade-scoped"]
 ```
 
 ## API

package/runtime/knowledge/docs/core/plugins/extension-points/extension-points.docs.md

@@ -684,4 +684,4 @@ These are used internally by `defineExtensionPoint` and `useExtensionPoint`. You
 | Extension Point Store          | `core/plugins/extension-points/store.ts`           | Reactive registry implementation              |
 | ExtensionPoint Component       | `core/plugins/extension-points/ExtensionPoint.vue` | Declarative render component                  |
 | Types                          | `core/plugins/extension-points/types.ts`           | `ExtensionComponent`, `ExtensionPointOptions` |
-| Seller Details (usage example) | `apps/vendor-portal/src/modules/seller-details/`   | Real-world extension point host               |
+| Seller Details (usage example) | Generated seller details module                    | Extension point host                          |