@vuu-ui/vuu-notifications 4.2.4 → 4.2.6

package/README.md

@@ -1 +1,157 @@
 # Notifications
+
+`@vuu-ui/vuu-notifications` shows toast and workspace notifications.
+
+Wrap the app in a `NotificationsProvider` and raise notifications with `useNotifications`:
+
+```tsx
+import {
+  NotificationsProvider,
+  useNotifications,
+} from "@vuu-ui/vuu-notifications";
+
+const SaveButton = () => {
+  const { showNotification } = useNotifications();
+  return (
+    <button
+      onClick={() =>
+        showNotification({
+          header: "Layout saved",
+          status: "success",
+          type: "toast",
+        })
+      }
+    >
+      Save
+    </button>
+  );
+};
+
+export const App = () => (
+  <NotificationsProvider>
+    <SaveButton />
+  </NotificationsProvider>
+);
+```
+
+`showNotification` returns an ID that can be passed to `hideNotification`. A toast is dismissed automatically after a delay unless `dismissal` is `"manual"`.
+
+## What's new in this version
+
+These changes let an app host other apps (for example, modules loaded with module federation in a portal) and still show every notification once, in one place, knowing where each came from.
+
+### Notification origins
+
+`NotificationOriginProvider` tags every notification raised beneath it with an `origin`:
+
+```tsx
+<NotificationOriginProvider connectionId="simul" moduleId="basket-trading">
+  <BasketTrading />
+</NotificationOriginProvider>
+```
+
+| Field            | Meaning                                                                         |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `moduleId`       | The module that raised the notification.                                        |
+| `connectionId`   | The Vuu server the module uses.                                                 |
+| `parentModuleId` | For nested origins, the `moduleId` of the enclosing origin; set automatically. |
+
+- **Explicit origins win:** a notification that already has an `origin` keeps it.
+- **No provider, no origin:** outside any `NotificationOriginProvider`, notifications have no `origin`.
+- **Reading it:** `useNotificationOrigin()` returns the current origin.
+
+### Interceptor
+
+`NotificationsProvider` takes an optional `interceptor`. It sees every notification raised beneath the provider before it is shown, and returns `"present"` to show it or `"suppress"` to drop it. A host can use it to keep a history of notifications, or to drop those from a module the user has muted.
+
+```tsx
+<NotificationsProvider
+  interceptor={(notification) => {
+    history.add(notification);
+    return notification.origin?.moduleId === mutedModule
+      ? "suppress"
+      : "present";
+  }}
+>
+```
+
+Only the outermost provider's interceptor is used.
+
+### One outermost provider
+
+A `NotificationsProvider` inside another now renders only its children. Notifications raised anywhere beneath the outermost provider, including inside nested providers, are shown once, by that provider. A hosted app can therefore keep its own `NotificationsProvider`: it works standalone and defers to the host when embedded.
+
+### Shared across copies of the package
+
+The provider contexts are kept on the global object under `Symbol.for` keys, not in module scope. A module federation remote that loads its own copy of `@vuu-ui/vuu-notifications` still finds the host's provider.
+
+### Other additions
+
+- **`record`:** an optional flag on a notification, telling a host that keeps a notification history whether to record it. The host chooses the default.
+- **New exports:**
+  - the types `ToastNotificationDescriptor`, `WorkspaceNotificationDescriptor`, `NotificationOrigin`, `NotificationInterceptor` and `NotificationsProviderProps`
+  - the type guards `isToastNotification` and `isWorkspaceNotification`
+- **`children` is optional:** `NotificationsProvider` now accepts any `ReactNode`, not only elements.
+
+## Compatibility
+
+The changes are backward compatible: existing code needs no changes.
+
+- **API:** every change is an addition or a widening.
+  - Exports are only added.
+  - The new notification fields (`origin`, `record`) are optional.
+  - `NotificationsProvider`'s `children` accepts more than before.
+- **Single provider:** an app with one `NotificationsProvider` behaves as before.
+- **Callers outside a provider:** their notifications are still shown by the most recently mounted provider. vuu-shell's `WorkspaceProvider`, for example, sits above the shell's `NotificationsProvider`. If no provider is mounted anywhere, `showNotification` logs a warning and returns `undefined`, as before.
+- **`useNotifications` identity:** without an origin, it returns the same stable functions as before.
+
+Two cases now behave differently. Neither occurs in this repository outside showcase examples.
+
+- **Nested providers:** before, all providers shared one notification centre and the last one to mount, usually the innermost, showed every notification. Now the outermost provider shows them.
+- **Sibling providers:** two providers side by side now each show the notifications raised beneath them. Before, the last one to mount showed both sets.
+
+## Vuu server support
+
+The new attributes are filled in on the client, so they work with today's Vuu server. A portal gets more out of them if the server can also say who a notification concerns and how it should be treated. This section describes what the server sends today and what it would need to add.
+
+### What the server sends today
+
+The Vuu server notifies the client in two ways:
+
+- **RPC responses:** a response can carry a `SHOW_NOTIFICATION_ACTION` with `notificationType` (`Error`, `Warning` or `Info`), `title` and `message`. The client shows it as a toast.
+- **The `NOTIFICATIONS` module:** its `notifications` table has the columns `id`, `type`, `expiryTime`, `title`, `message`, `level` and `audience`, plus any columns the application adds. Rows are pushed to subscribers like any other table, so the server can notify users without a request.
+
+### What each attribute is for, and what the server would need
+
+| Attribute | What it's for in a portal | What the server would need |
+| --- | --- | --- |
+| `origin.moduleId` | Says which application a notification belongs to. The portal can then badge that application in its navigation, filter the notification history by application, and let the user mute an application. | **RPC responses:** nothing. The response returns to the application that made the request, and that application's `NotificationOriginProvider` sets the origin. (Today this holds for context-menu RPCs only; see below.)<br>**`notifications` table:** a standard column naming the application, such as `module`, holding the application's client identifier. Without it, a notification can only be attributed to every application using that server. |
+| `origin.connectionId` | Says which Vuu server a notification came from, when a portal uses several. | Nothing: the client knows which connection a message arrived on. |
+| `origin.parentModuleId` | Attributes notifications from an application embedded in another to the outer application too. | Nothing: it comes from the nesting of origin providers on the client. |
+| Topic, for routing | Lets applications declare the kinds of notification they care about (for example `orders`), so the server doesn't need to know application names. | A standard `topic` column on the `notifications` table. |
+| `record` | Tells the portal whether to keep a notification in its history. A confirmation such as "Saved" needn't be kept; a rejected order should be. | An optional `record` field on `SHOW_NOTIFICATION_ACTION`. Rows in the `notifications` table are already a record, so they need nothing. |
+| `status` (level) | Sets the toast's colour and icon. The worst unread level can also badge the portal's notification bell. | A `Success` value in `NotificationType`, which has only `Error`, `Warning` and `Info`. The `level` column should use the same four values. |
+| `dismissal` | `"manual"` keeps a toast on screen until the user closes it. An error that needs acknowledging shouldn't disappear after a few seconds. | An optional `dismissal` field on `SHOW_NOTIFICATION_ACTION`, for example defaulting to manual for errors. |
+
+The interceptor needs nothing from the server: it runs on the client and sees server and client notifications alike.
+
+### Client changes to go with them
+
+The client shows the notifications on both kinds of RPC response at the server's level: `Error`, `Warning` and `Info` are shown with those statuses, and an action without a `notificationType` as a success. Without a `title`, the header names the status. The mapping is `getServerNotificationStatus` in `@vuu-ui/vuu-utils`.
+
+- **Context-menu RPCs:** the menu action handler shows the notification.
+- **Other RPCs:** the caller gets only the response's `result`, so `ConnectionManager` emits the notification as a `server-notification` event. `useServerNotifications(ConnectionManager)` shows these. The hook takes the event source as an argument, so this package doesn't depend on `@vuu-ui/vuu-data-remote`. vuu-shell calls it; an application that doesn't use the shell calls it once itself. A caller that also reports the `ERROR_RESULT`, such as the session editing form, shows the error twice: inline and as a toast.
+
+Two client changes remain:
+
+- **Origin of other RPC notifications:** the event isn't tied to the request that caused it, so these notifications get the origin of wherever `useServerNotifications` is called, not of the application that made the request. Passing the notification back to the caller would fix this.
+- **New fields:** once the server sends `record` and `dismissal`, both handlers should pass them to `showNotification` as well.
+
+## Examples and tests
+
+- **Examples:** the showcase has examples under `Notifications/Toast`, `Notifications/NotificationOrigins` and `Notifications/ServerNotifications`.
+- **Component tests:** in `src/__tests__/__component__`, run with:
+
+  ```sh
+  npx playwright test --config=playwright.config.ts --project=components-chromium packages/vuu-notifications
+  ```

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.2.4",
+  "version": "4.2.6",
   "description": "VUU notifications - Toast, WorkspaceNotification etc",
   "main": "./src/index.js",
   "author": "heswell",
@@ -8,12 +8,15 @@
     "build": "node ../../scripts/run-build-rslib.ts",
     "type-defs": "node ../../scripts/build-type-defs.mjs"
   },
+  "devDependencies": {
+    "@vuu-ui/vuu-protocol-types": "4.2.6"
+  },
   "dependencies": {
     "@salt-ds/core": "1.74.0",
     "@salt-ds/styles": "0.4.2",
     "@salt-ds/window": "0.1.2",
-    "@vuu-ui/vuu-ui-controls": "4.2.4",
-    "@vuu-ui/vuu-utils": "4.2.4"
+    "@vuu-ui/vuu-ui-controls": "4.2.6",
+    "@vuu-ui/vuu-utils": "4.2.6"
   },
   "peerDependencies": {
     "clsx": "^2.0.0",

package/src/NotificationsProvider.js

@@ -1,26 +1,64 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import react, { useContext, useMemo } from "react";
-import { NotificationsCenter } from "./NotificationsCenter.js";
 import { getLocalEntity } from "@vuu-ui/vuu-utils";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import { NotificationsCenter } from "./NotificationsCenter.js";
+const globalContext = (name, defaultValue)=>{
+    const key = Symbol.for(name);
+    const contexts = globalThis;
+    let context = contexts[key];
+    if (void 0 === context) {
+        context = /*#__PURE__*/ createContext(defaultValue);
+        contexts[key] = context;
+    }
+    return context;
+};
 class NotificationsContextObject {
     #showNotification = ()=>{
         console.log("have you forgotten to provide a NotificationsCenter?");
     };
     #hideNotification = ()=>console.log("have you forgotten to provide a NotificationsCenter?");
-    showNotification = (notification)=>this.#showNotification(notification);
+    interceptor = void 0;
+    showNotification = (notification)=>this.interceptor?.(notification) === "suppress" ? void 0 : this.#showNotification(notification);
     hideNotification = (id)=>this.#hideNotification(id);
     setNotify = (showNotificationDispatcher, hideNotificationDispatcher)=>{
         this.#showNotification = showNotificationDispatcher;
         this.#hideNotification = hideNotificationDispatcher;
     };
 }
-const NotificationsContext = /*#__PURE__*/ react.createContext(new NotificationsContextObject());
-const NotificationsProvider = (props)=>{
-    const context = useContext(NotificationsContext);
+const NotificationsContext = globalContext("vuu.notifications.context", null);
+const NotificationOriginContext = globalContext("vuu.notifications.origin", void 0);
+const globalProviders = globalThis;
+const providersKey = Symbol.for("vuu.notifications.providers");
+globalProviders[providersKey] ??= [];
+const mountedProviders = globalProviders[providersKey];
+const noProvider = new NotificationsContextObject();
+noProvider.setNotify((notification)=>{
+    const provider = mountedProviders.at(-1);
+    if (provider) return provider.showNotification(notification);
+    console.log("have you forgotten to provide a NotificationsProvider?");
+}, (id)=>mountedProviders.at(-1)?.hideNotification(id));
+const NotificationsProvider = ({ children, interceptor })=>{
+    const outerContext = useContext(NotificationsContext);
+    return outerContext ? children : /*#__PURE__*/ jsx(OutermostNotificationsProvider, {
+        interceptor: interceptor,
+        children: children
+    });
+};
+const OutermostNotificationsProvider = ({ children, interceptor })=>{
+    const [context] = useState(()=>new NotificationsContextObject());
+    context.interceptor = interceptor;
+    useEffect(()=>{
+        mountedProviders.push(context);
+        return ()=>{
+            mountedProviders.splice(mountedProviders.indexOf(context), 1);
+        };
+    }, [
+        context
+    ]);
     const startupToastNotification = useMemo(()=>{
         const toast = getLocalEntity("startup-notification", true);
         if (toast && toast.expires >= +Date.now()) {
-            const { expires, ...toastDescriptor } = toast;
+            const { expires: _expires, ...toastDescriptor } = toast;
             return toastDescriptor;
         }
     }, []);
@@ -31,15 +69,41 @@ const NotificationsProvider = (props)=>{
                 startupToastNotification: startupToastNotification,
                 notificationsContext: context
             }),
-            props.children
+            children
         ]
     });
 };
+const NotificationOriginProvider = ({ children, connectionId, moduleId })=>{
+    const outerOrigin = useContext(NotificationOriginContext);
+    const outerModuleId = outerOrigin?.moduleId ?? outerOrigin?.parentModuleId;
+    const parentModuleId = outerModuleId !== moduleId ? outerModuleId : outerOrigin?.parentModuleId;
+    const origin = useMemo(()=>({
+            connectionId,
+            moduleId,
+            parentModuleId
+        }), [
+        connectionId,
+        moduleId,
+        parentModuleId
+    ]);
+    return /*#__PURE__*/ jsx(NotificationOriginContext.Provider, {
+        value: origin,
+        children: children
+    });
+};
+const useNotificationOrigin = ()=>useContext(NotificationOriginContext);
 const useNotifications = ()=>{
-    const { hideNotification, showNotification } = useContext(NotificationsContext);
-    return {
-        hideNotification,
-        showNotification
-    };
+    const context = useContext(NotificationsContext) ?? noProvider;
+    const origin = useContext(NotificationOriginContext);
+    return useMemo(()=>({
+            hideNotification: context.hideNotification,
+            showNotification: origin ? (notification)=>context.showNotification(notification.origin ? notification : {
+                    ...notification,
+                    origin
+                }) : context.showNotification
+        }), [
+        context,
+        origin
+    ]);
 };
-export { NotificationsProvider, useNotifications };
+export { NotificationOriginProvider, NotificationsProvider, useNotificationOrigin, useNotifications };

package/src/index.js

@@ -1,3 +1,4 @@
-export { NotificationType } from "./NotificationsContext.js";
-export { NotificationsProvider, useNotifications } from "./NotificationsProvider.js";
+export { NotificationType, isToastNotification, isWorkspaceNotification } from "./NotificationsContext.js";
+export { NotificationOriginProvider, NotificationsProvider, useNotificationOrigin, useNotifications } from "./NotificationsProvider.js";
 export { ToastNotification } from "./ToastNotification.js";
+export { useServerNotifications } from "./useServerNotifications.js";

package/src/useServerNotifications.js

@@ -0,0 +1,24 @@
+import { getServerNotificationStatus } from "@vuu-ui/vuu-utils";
+import { useEffect } from "react";
+import { NotificationType } from "./NotificationsContext.js";
+import { useNotifications } from "./NotificationsProvider.js";
+const useServerNotifications = (source)=>{
+    const { showNotification } = useNotifications();
+    useEffect(()=>{
+        const handleServerNotification = (action)=>{
+            showNotification({
+                ...getServerNotificationStatus(action),
+                content: action.message,
+                type: NotificationType.Toast
+            });
+        };
+        source.on("server-notification", handleServerNotification);
+        return ()=>{
+            source.removeListener("server-notification", handleServerNotification);
+        };
+    }, [
+        showNotification,
+        source
+    ]);
+};
+export { useServerNotifications };

package/types/NotificationsCenter.d.ts

@@ -1,4 +1,4 @@
-import { NotificationsContextProps, ToastNotificationDescriptor } from "./NotificationsContext";
+import { type NotificationsContextProps, type ToastNotificationDescriptor } from "./NotificationsContext";
 export interface NotificationsCenterProps {
     notificationsContext: NotificationsContextProps;
     startupToastNotification?: ToastNotificationDescriptor;

package/types/NotificationsContext.d.ts

@@ -10,6 +10,18 @@ export declare const NotificationType: {
 export type NotificationType = ValueOf<typeof NotificationType>;
 export type DismissalStyle = "automatic" | "manual";
 export type NotificationAnimationType = "slide-in" | "slide-out" | "slide-in,slide-out";
+/**
+ * Where a notification was raised. Filled in by `useNotifications` from the
+ * nearest `NotificationOriginProvider`, e.g. the portal module rendering the
+ * caller.
+ */
+export interface NotificationOrigin {
+    moduleId?: string | number;
+    /** The Vuu server the module uses. */
+    connectionId?: string;
+    /** The module hosting the origin's module, for nested modules. */
+    parentModuleId?: string | number;
+}
 interface NotificationDescriptorBase<T extends NotificationType> {
     animationType?: NotificationAnimationType;
     /**
@@ -23,6 +35,13 @@ interface NotificationDescriptorBase<T extends NotificationType> {
      * Default icons will be rendered for the different status values.
      */
     icon?: string | false;
+    /** Set automatically by `useNotifications`, when a provider gives one. */
+    origin?: NotificationOrigin;
+    /**
+     * Whether a host that keeps a notification history (e.g. a portal) should
+     * record this notification. Hosts choose the default.
+     */
+    record?: boolean;
     renderPostRefresh?: boolean;
     showCloseButton?: boolean;
     status: ValidationStatus;
@@ -39,6 +58,12 @@ export interface WorkspaceNotificationDescriptor extends NotificationDescriptorB
 export type Notification = ToastNotificationDescriptor | WorkspaceNotificationDescriptor;
 export declare const isToastNotification: (n: Notification) => n is ToastNotificationDescriptor;
 export declare const isWorkspaceNotification: (n: Notification) => n is WorkspaceNotificationDescriptor;
+/**
+ * Decides whether a notification is shown. Given to the outermost
+ * `NotificationsProvider`, it sees every notification raised beneath it,
+ * including those raised inside nested providers.
+ */
+export type NotificationInterceptor = (notification: Notification) => "present" | "suppress";
 export type NotificationsContextProps = {
     hideNotification: DispatchHideNotification;
     showNotification: DispatchShowNotification;

package/types/NotificationsProvider.d.ts

@@ -1,8 +1,29 @@
-import React, { type ReactElement } from "react";
-import type { DispatchHideNotification, DispatchShowNotification } from "./NotificationsContext";
-export declare const NotificationsProvider: (props: {
-    children: ReactElement | ReactElement[];
-}) => React.JSX.Element;
+import { type ReactNode } from "react";
+import type { DispatchHideNotification, DispatchShowNotification, NotificationInterceptor, NotificationOrigin } from "./NotificationsContext";
+export interface NotificationsProviderProps {
+    children?: ReactNode;
+    /**
+     * Sees every notification raised beneath the provider before it is shown.
+     * Only used by the outermost provider.
+     */
+    interceptor?: NotificationInterceptor;
+}
+/**
+ * Shows the notifications raised beneath it. Inside another
+ * `NotificationsProvider` it renders only its children, so notifications
+ * from nested applications are shown, once, by the outermost provider.
+ */
+export declare const NotificationsProvider: ({ children, interceptor, }: NotificationsProviderProps) => string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+/**
+ * Tags notifications raised beneath it with their origin. A nested provider
+ * records the enclosing origin's module as its `parentModuleId`.
+ */
+export declare const NotificationOriginProvider: ({ children, connectionId, moduleId, }: {
+    children?: ReactNode;
+    connectionId?: string;
+    moduleId?: string | number;
+}) => import("react").JSX.Element;
+export declare const useNotificationOrigin: () => NotificationOrigin | undefined;
 export declare const useNotifications: () => {
     hideNotification: DispatchHideNotification;
     showNotification: DispatchShowNotification;

package/types/index.d.ts

@@ -1,3 +1,4 @@
-export { NotificationType, type Notification, type NotificationAnimationType, } from "./NotificationsContext";
-export { NotificationsProvider, useNotifications, } from "./NotificationsProvider";
+export { NotificationType, type Notification, type NotificationAnimationType, type NotificationInterceptor, type NotificationOrigin, type ToastNotificationDescriptor, type WorkspaceNotificationDescriptor, isToastNotification, isWorkspaceNotification, } from "./NotificationsContext";
+export { NotificationOriginProvider, NotificationsProvider, type NotificationsProviderProps, useNotificationOrigin, useNotifications, } from "./NotificationsProvider";
 export { ToastNotification, type ToastNotificationProps, } from "./ToastNotification";
+export { type ServerNotificationSource, useServerNotifications, } from "./useServerNotifications";

package/types/useServerNotifications.d.ts

@@ -0,0 +1,16 @@
+import type { ShowNotificationAction } from "@vuu-ui/vuu-protocol-types";
+type ServerNotificationListener = (action: ShowNotificationAction) => void;
+/**
+ * Emits the notifications the server attaches to RPC responses. The Vuu
+ * ConnectionManager is one.
+ */
+export interface ServerNotificationSource {
+    on(event: "server-notification", listener: ServerNotificationListener): void;
+    removeListener(event: "server-notification", listener: ServerNotificationListener): void;
+}
+/**
+ * Shows, as toasts, the notifications the server attaches to RPC responses,
+ * such as its report that a request failed. Use it once per application.
+ */
+export declare const useServerNotifications: (source: ServerNotificationSource) => void;
+export {};