Add general purpose notification API for embed

CHANGELOG.md

@@ -11,6 +11,8 @@
 - Added `Model#legacyPrepare` readonly property to indicate whether the legacy `prepare` method is used or the new `setup()` method
 - Updated `struct` view to define the `setStructViewAnnotations` action when using the new `setup()` method, allowing custom annotations to be specified across all `struct` views
 - Updated `embed` option of `App` to accept a config
+- Added `EmbedApp#publicApi.notify(name, details)` method for sending notifications
+- Introduced `onNotify(name, details)` option in the embed extension to define a callback for handling `notification` messages from the embed host
 - Added `EmbedApp#publicApi.setLocationSync()` method to simplify sync between the embed app and the host location, preventing potential pitfalls
 - Added `ViewModel#enforceScheduledRenders()` to immediately execute scheduled renders
 - Changed `ViewModel#scheduleRender()` to use `setTimeout()` instead of `Promise.resolve()` to ensure proper processing of event loop tasks, eliminating unnecessary renders

src/extensions/embed-client.ts

@@ -10,6 +10,7 @@ import { loadDataFromPush, loadDataFromStream } from '../core/utils/load-data.js
 export type EmbedClientOptions = {
     hostId: string;
     postponeMessages: EmbedHostToClientPostponeMessage[];
+    onNotify: (name: string, details: any) => void;
 };
 
 export type LoadDataChunkedStatus = LoadDataFromPush & {
@@ -44,6 +45,9 @@ function createNavItemConfig(rawConfig: unknown, sendMessage: SendMessage, rawCo
 function setup(options?: Partial<EmbedClientOptions>) {
     const hostId = options?.hostId || randomId();
     const postponeMessages = options?.postponeMessages;
+    const onNotify = typeof options?.onNotify === 'function'
+        ? options.onNotify
+        : () => {};
 
     return function(host: ViewModel) {
         let loadChunkedDataStatus: LoadDataChunkedStatus | null = null;
@@ -87,6 +91,14 @@ function setup(options?: Partial<EmbedClientOptions>) {
 
             if (id === hostId) {
                 switch (type) {
+                    case 'notification': {
+                        const { name, details } = payload;
+
+                        onNotify(name, details);
+
+                        break;
+                    }
+
                     case 'defineAction': {
                         const name = payload;
                         host.action.define(name, (...args) =>

src/extensions/embed-host.ts

@@ -163,6 +163,10 @@ class EmbedApp extends BaseApp<EmbedHostToClientMessage, EmbedAppEvents> {
 
             nav: Object.assign(nav.secondary, nav),
 
+            notify(name: string, details: any) {
+                app.sendMessage('notification', { name, details });
+            },
+
             defineAction(name: string, fn: (...args: unknown[]) => unknown) {
                 app.actions.set(name, fn);
                 app.sendMessage('defineAction', name);

src/extensions/embed-message.types.ts

@@ -42,6 +42,7 @@ export type EmbedHostToClientPostponeMessage = Extract<EmbedHostToPreinitMessage
 
 export type EmbedHostToClientMessage = CreateMessageType<{
     defineAction: string;
+    notification: { name: string; details: any; };
     setPageHash: { hash: string; replace?: boolean; };
     setPage: Omit<PageState, 'hash'> & { replace?: boolean; };
     setPageRef: { ref: PageRef; replace?: boolean; };