@vc-shell/vc-app-skill 2.0.11 → 2.1.0-pr248.6401a93

package/runtime/knowledge/patterns/list-blade-pattern.md

@@ -20,12 +20,14 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
       class="tw-grow tw-basis-0"
       :loading="loading"
       :items="xxxList"
-      :total-count="totalCount"
-      :pagination="{ currentPage, pages }"
+      :total-count="pagination.totalCount"
+      :pagination="pagination"
       v-model:active-item-id="selectedItemId"
       state-key="xxx_list"
       v-model:sort-field="sortField"
       v-model:sort-order="sortOrder"
+      v-model:search-value="searchValue"
+      :searchable="true"
       :pull-to-refresh="true"
       :empty-state="{
         icon: 'lucide-<icon>',
@@ -34,7 +36,7 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
         actionHandler: onAddItem,
       }"
       @row-click="onItemClick"
-      @pagination-click="onPaginationClick"
+      @pagination-click="pagination.goToPage"
       @pull-refresh="reload"
     >
       <!-- Each VcColumn is declared explicitly in the template (NOT via v-for).
@@ -87,9 +89,11 @@ Generic worked example for a typical list blade (search, sort, pagination, row a
 
 **Key VcDataTable props:**
 
-- `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`).
+- `state-key` — unique string key for persisting column widths/order/visibility to localStorage. Use snake_case module name (e.g., `"team_list"`, `"catalog_list"`). This prop controls column layout only — URL query persistence (sort/search/page) comes from the composables' `stateKey` option.
 - `v-model:active-item-id` — highlights the currently open row. Bind to `selectedItemId` ref.
 - `v-model:sort-field` and `v-model:sort-order` — two-way sort binding from `useDataTableSort`.
+- `v-model:search-value` and `:searchable="true"` — two-way search binding from `useTableSearch`.
+- `:pagination="pagination"` and `@pagination-click="pagination.goToPage"` — pass the reactive object from `useDataTablePagination` directly.
 - `:pull-to-refresh="true"` — enables mobile pull-to-refresh gesture.
 - `:empty-state` — object with `icon`, `title`, `actionLabel`, `actionHandler`.
 
@@ -191,7 +195,8 @@ If the API defines an enum of statuses, populate the map from those values. If s
 ```vue
 <script lang="ts" setup>
 import { ref, computed, watch, onMounted } from "vue";
-import { IBladeToolbar, useBlade, useDataTableSort } from "@vc-shell/framework";
+import { IBladeToolbar, useBlade, useDataTableSort, useDataTablePagination, useTableSearch } from "@vc-shell/framework";
+import { debounce } from "lodash-es";
 import useXxxs from "../composables/useXxxs";
 import { useI18n } from "vue-i18n";
 
@@ -211,19 +216,32 @@ defineBlade({
 // 2. Core composables
 const { openBlade, exposeToChildren, param } = useBlade();
 const { t } = useI18n({ useScope: "global" });
-const { getXxxs, searchQuery, loading, xxxList, currentPage, pages, totalCount } = useXxxs();
+const { getXxxs, loading, xxxList, totalCount } = useXxxs();
 
-// 3. Sort — provides sortField, sortOrder (for VcDataTable v-model), sortExpression (string for API)
+// 3. Sort — stateKey persists sort to blade URL; omit stateKey to opt out
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "xxx_list",
   initialField: "createdDate",
   initialDirection: "DESC",
 });
 
-// 4. UI state
+// 4. Search — stateKey persists keyword to blade URL; omit stateKey to opt out
+const { searchValue } = useTableSearch({ stateKey: "xxx_list" });
+
+// 5. Pagination — stateKey persists current page to blade URL; omit stateKey to opt out
+// Note: state-key on <VcDataTable> is column-layout persistence only (localStorage).
+// URL query persistence (sort/search/page) is controlled by the stateKey option here.
+const pagination = useDataTablePagination({
+  stateKey: "xxx_list",
+  pageSize: 20,
+  totalCount,
+});
+
+// 6. UI state
 const selectedItemId = ref<string | undefined>();
 const title = computed(() => t("XXX.PAGES.LIST.TITLE"));
 
-// 5. Toolbar
+// 7. Toolbar
 const bladeToolbar = ref<IBladeToolbar[]>([
   {
     id: "refresh",
@@ -241,7 +259,7 @@ const bladeToolbar = ref<IBladeToolbar[]>([
   },
 ]);
 
-// 6. Status variant mapping (if status column exists)
+// 8. Status variant mapping (if status column exists)
 const statusVariant = (status: string | undefined): "info" | "warning" | "danger" | "success" | "primary" => {
   const map: Record<string, "info" | "warning" | "danger" | "success" | "primary"> = {
     // TODO: adjust status variants to match your API statuses
@@ -256,12 +274,23 @@ const statusVariant = (status: string | undefined): "info" | "warning" | "danger
   return map[status ?? ""] ?? "info";
 };
 
-// 7. Sort reactivity — reload when sort changes
-watch(sortExpression, async (value) => {
-  await getXxxs({ ...searchQuery.value, sort: value });
-});
+// 9. Load function — explicit; called on mount and by watchers
+const load = async () => {
+  await getXxxs({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: pagination.skip,
+    take: 20,
+  });
+};
 
-// 8. Track selected row when param changes (e.g., navigating directly to URL)
+// 10. Reset to page 1 when search changes, then reload
+watch(searchValue, () => pagination.setPage(1));
+
+// 11. Reload when sort, search, or page changes (debounced to coalesce rapid changes)
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+
+// 12. Track selected row when param changes (e.g., navigating directly to URL)
 watch(
   () => param.value,
   () => {
@@ -270,30 +299,15 @@ watch(
   { immediate: true },
 );
 
-// 9. Load data on mount
-onMounted(async () => {
-  await reload();
-});
+// 13. Load data on mount
+onMounted(() => load());
 
-// 10. Reload — reloads current page with current sort
+// 14. Reload helper — used by toolbar and exposed to child blades
 const reload = async () => {
-  await getXxxs({
-    ...searchQuery.value,
-    skip: (currentPage.value - 1) * (searchQuery.value?.take ?? 20),
-    sort: sortExpression.value,
-  });
-};
-
-// 11. Pagination
-const onPaginationClick = async (page: number) => {
-  await getXxxs({
-    ...searchQuery.value,
-    skip: (page - 1) * (searchQuery.value?.take ?? 20),
-    sort: sortExpression.value,
-  });
+  await load();
 };
 
-// 12. Row click → open details blade
+// 15. Row click → open details blade
 const onItemClick = (event: { data: { id?: string } }) => {
   openBlade({
     name: "XxxDetails",
@@ -310,14 +324,14 @@ const onItemClick = (event: { data: { id?: string } }) => {
   });
 };
 
-// 13. Add new item — open details blade with no param (creates new)
+// 16. Add new item — open details blade with no param (creates new)
 function onAddItem() {
   openBlade({
     name: "XxxDetails",
   });
 }
 
-// 14. Expose reload to child blades so details can trigger list refresh after save/delete
+// 17. Expose reload to child blades so details can trigger list refresh after save/delete
 exposeToChildren({ reload });
 </script>
 ```
@@ -334,6 +348,7 @@ exposeToChildren({ reload });
 
 ```ts
 const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  stateKey: "xxx_list", // optional: persists sort to blade URL
   initialField: "createdDate",
   initialDirection: "DESC",
 });
@@ -342,16 +357,45 @@ const { sortField, sortOrder, sortExpression } = useDataTableSort({
 - `sortField` — reactive ref, two-way bound to `VcDataTable` via `v-model:sort-field`
 - `sortOrder` — reactive ref (`"ASC"` | `"DESC"`), two-way bound via `v-model:sort-order`
 - `sortExpression` — computed string `"field:DIR"` (e.g., `"createdDate:DESC"`), passed to the API
+- `stateKey` — when provided, the composable reads the initial sort from the URL and writes back on change
 
-### Sort watcher pattern
+### `useTableSearch` — search with optional URL persistence
 
 ```ts
-watch(sortExpression, async (value) => {
-  await getXxxs({ ...searchQuery.value, sort: value });
+const { searchValue } = useTableSearch({ stateKey: "xxx_list" });
+```
+
+- Returns `searchValue` ref, two-way bound via `v-model:search-value` on `VcDataTable`.
+- With `stateKey`, restores and persists the keyword to the blade URL.
+- Without `stateKey`, behaves like a plain `ref("")`.
+
+### `useDataTablePagination` — pagination with optional URL persistence
+
+```ts
+const pagination = useDataTablePagination({
+  stateKey: "xxx_list", // optional: persists current page to blade URL
+  pageSize: 20,
+  totalCount,
 });
 ```
 
-Watch `sortExpression` (not `sortField`/`sortOrder` separately) to trigger a reload whenever sort changes.
+- Pass `pagination` directly as `:pagination="pagination"` and `@pagination-click="pagination.goToPage"`.
+- Access `pagination.skip` for API calls, `pagination.setPage(1)` to reset on search change.
+- `stateKey` persists the current page to the blade URL; omit to opt out.
+- The table `state-key` prop is column-layout persistence (localStorage) only and is independent.
+
+### Load + watcher pattern
+
+```ts
+const load = async () => {
+  await getXxxs({ sort: sortExpression.value, keyword: searchValue.value || undefined, skip: pagination.skip, take: 20 });
+};
+watch(searchValue, () => pagination.setPage(1));
+watch([sortExpression, searchValue, () => pagination.skip], debounce(load, 300));
+onMounted(() => load());
+```
+
+Watch `[sortExpression, searchValue, () => pagination.skip]` to reload whenever any query dimension changes. Reset to page 1 when search changes before the reload watcher fires.
 
 ### `exposeToChildren`
 

package/runtime/knowledge/docs/core/blade-navigation/table-query-state/useTableQueryState.docs.md

@@ -1,95 +0,0 @@
----
-title: useTableQueryState
-category: composables
-group: data
----
-
-# useTableQueryState
-
-Reads the table view state (`sort`, `search`, `page`) that `VcDataTable` persists to the URL query for URL-addressable blades. A list page calls `read()` in `setup` to seed its own refs from the restored state before its loader runs, so a reload makes one request.
-
-Read-only: writing the view state to the URL stays inside `VcDataTable`. This composable only exposes the restored values to the page.
-
-## When to Use
-
-- A list blade is URL-addressable (workspace or routable) and uses `VcDataTable` with a `state-key`
-- You want a single, coordinated load on reload (sort + search + page restored together)
-- You are wiring the page's combined loader watcher and need the restored seed values
-
-## When NOT to Use
-
-- The table is standalone or its blade has no URL — there is nothing to restore (`read()` returns `{}`)
-- You only need the live view state — that already lives in your own `sortField`/`searchValue`/`currentPage` refs
-- You want to _write_ to the URL — that is automatic; do not persist manually
-
-## Basic Usage
-
-```ts
-import { ref, watch } from "vue";
-import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
-
-const PAGE_SIZE = 20;
-const { debounce } = useFunctions();
-const { sortField, sortOrder, sortExpression } = useDataTableSort({
-  initialField: "createdDate",
-  initialDirection: "DESC",
-});
-const searchValue = ref<string>();
-const currentPage = ref(1);
-
-// Seed refs from the URL before the loader runs.
-const restored = useTableQueryState("offers_list").read();
-if (restored.sort) {
-  const [field, dir] = restored.sort.split(":");
-  sortField.value = field;
-  sortOrder.value = dir === "DESC" ? -1 : 1;
-}
-if (restored.search) searchValue.value = restored.search;
-if (restored.page) currentPage.value = restored.page;
-
-function load() {
-  return loadItems({
-    sort: sortExpression.value,
-    keyword: searchValue.value || undefined,
-    skip: (currentPage.value - 1) * PAGE_SIZE,
-  });
-}
-
-load();
-watch(searchValue, () => (currentPage.value = 1));
-watch([sortExpression, searchValue, currentPage], debounce(load, 300));
-```
-
-## API
-
-### Parameters
-
-| Parameter  | Type                  | Default     | Description                                                               |
-| ---------- | --------------------- | ----------- | ------------------------------------------------------------------------- |
-| `stateKey` | `string \| undefined` | `undefined` | The same `state-key` passed to `VcDataTable` for this table (namespacing) |
-
-### Returns
-
-| Property | Type                    | Description                                                                                            |
-| -------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
-| `read`   | `() => TableQueryPatch` | Reads the restored `{ sort?, search?, page? }` from the URL. Returns `{}` when no service is available |
-
-`TableQueryPatch`: `{ sort?: string; search?: string; page?: number }` — `sort` is a `"field:ASC"` / `"field:DESC"` expression, `page` is 1-based.
-
-## Details
-
-- **Read in `setup`**: `VcDataTable` does not emit restore events on init; the page reads the state and seeds its refs in `setup`. This avoids a separate load per restored field.
-- **No-op without a service**: When no blade provides the persistence service (standalone table, non-URL blade), `read()` returns `{}`, so you can call it unconditionally.
-- **Write-back is automatic**: View state → URL (debounced `router.replace`) is handled by `VcDataTable` via `useTableQueryPersistence`. Pages do not persist manually.
-
-## Tips
-
-- Call `read()` once, synchronously, before the loader. Seeding after it runs causes an extra load.
-- Use `useDataTablePagination`'s `setPage(n)` to seed the page without firing `onPageChange`.
-- Pass the same `state-key` you give `VcDataTable`, so the URL keys match.
-
-## Related
-
-- [`useDataTableSort`](../../../ui/composables/useDataTableSort.docs.md) — sort state composable for `VcDataTable`
-- [`useDataTablePagination`](../../../ui/composables/useDataTablePagination.docs.md) — pagination state composable (`setPage` for restore seed)
-- `VcDataTable` → _URL query persistence_ — the write-back side of this contract

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

@@ -1,34 +0,0 @@
----
-title: usePlatformLocaleSync
-category: composables
-group: user
----
-
-# usePlatformLocaleSync
-
-One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
-
-Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used.
-
-## When to Use
-
-- Never call directly from feature code. This is a framework-internal sync primitive.
-- It is invoked once per `VcApp` mount from `useShellBootstrap`.
-
-## Behaviour
-
-- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity.
-- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`.
-- On subsequent changes of the platform key, re-applies the value.
-- Skips empty strings (platform clearing the key does not blank the shell locale).
-- Skips values equal to `currentLocale` to avoid redundant re-configuration.
-
-## How It Works
-
-`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`.
-
-The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener.
-
-## Relationship to `VC_LANGUAGE_SETTINGS`
-
-The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side.

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

@@ -1,184 +0,0 @@
----
-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)

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

@@ -1,117 +0,0 @@
----
-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)