@12-apps/notifications 4.7.0 → 4.8.0

package/src/react/create-web-notifications.tsx

@@ -10,8 +10,10 @@ import {
   type NotificationsSubscribe,
 } from './hooks';
 import { createInboxStore, type InboxStore } from './inbox-state';
-import { NotificationsPanel, type NotificationsPanelProps } from './panel';
-import { PreferencesScreen, type PreferencesScreenProps } from './preferences-screen';
+import { lazyNotificationsPanel } from './panel-lazy';
+import type { NotificationsPanelProps } from './panel';
+import { lazyPreferencesPage } from './page-lazy';
+import type { PreferencesScreenProps } from './preferences-screen';
 import { httpNotificationsTransport, type NotificationsTransport } from './transport';
 import type { WebPushSetupConfig } from './web-push-setup';
 
@@ -56,11 +58,22 @@ export interface NotificationsWebConfig {
 }
 
 export interface WebNotifications {
-  /** The routed surface: the preferences screen. */
+  /**
+   * The routed surface: the preferences screen.
+   *
+   * Loaded on demand — see `page-lazy.tsx`. A host that mounts only the bell and
+   * the panel never downloads it, and a host that routes to it fetches it while
+   * entering that route.
+   */
   page: ComponentType<PreferencesScreenProps>;
   /** The bell, already bound to the shared store. */
   BellButton: ComponentType<BellButtonProps>;
-  /** The inbox slide-over, sharing that store. */
+  /**
+   * The inbox slide-over, sharing that store.
+   *
+   * Loaded the first time it is opened — see `panel-lazy.tsx`. Until then a
+   * host's chrome carries the bell and nothing else.
+   */
   Panel: ComponentType<NotificationsPanelProps>;
   /**
    * Bell + panel as ONE element, for a host that just wants the feature in its
@@ -97,9 +110,7 @@ export function createWebNotifications(config: NotificationsWebConfig): WebNotif
   const Bell: ComponentType<BellButtonProps> = (props) => (
     <BellButton {...props} store={store} messages={messages} {...subscribeOption} />
   );
-  const Panel: ComponentType<NotificationsPanelProps> = (props) => (
-    <NotificationsPanel {...props} store={store} messages={messages} />
-  );
+  const Panel = lazyNotificationsPanel({ store, messages });
 
   function useBoundUnreadCount(options: { enabled?: boolean } = {}): number {
     return useUnreadCount(store, { ...options, ...subscribeOption });
@@ -126,9 +137,7 @@ export function createWebNotifications(config: NotificationsWebConfig): WebNotif
   }
 
   return {
-    page: (props) => (
-      <PreferencesScreen {...props} api={api} messages={messages} webPush={webPush} />
-    ),
+    page: lazyPreferencesPage({ api, messages, webPush }),
     BellButton: Bell,
     Panel,
     BellWithPanel,

package/src/react/page-lazy.tsx

@@ -0,0 +1,73 @@
+/**
+ * The routed preferences screen, fetched when a host actually routes to it.
+ *
+ * `createWebNotifications` returns two different KINDS of thing, and its own
+ * docstring says so: `page` is "the standalone surface … the one thing a host
+ * routes to", while the bell and the panel "are a PAIR a host drops into its own
+ * chrome". Chrome is on screen from the first paint; a routed surface is not.
+ *
+ * A static import made that distinction invisible to a bundler. Every host that
+ * put the bell in its header also shipped the preferences matrix — its channel
+ * toggles, the per-browser push enable step, and the design-system `Switch`
+ * behind them — in the same chunk as the header. A storefront paid for a
+ * settings screen a shopper never opens, before its first screen could render;
+ * a host that renders its OWN preferences page paid for this one twice.
+ *
+ * So `page` now loads on demand. Nothing else moves: the bell, the panel and
+ * `BellWithPanel` stay exactly as eager as the chrome they belong to, because
+ * that is what they are.
+ *
+ * NO PREFETCH, deliberately, and this is the opposite call from a surface a
+ * host opens from chrome it already has. A routed surface is reached by
+ * NAVIGATION, and every host here already code-splits its routes — so the
+ * fetch happens while the route is being entered, which is the moment a
+ * prefetch would have been trying to anticipate. Warming it at factory time
+ * would put the screen back on the boot path of every app, which is the whole
+ * cost this removes.
+ */
+import { Suspense, lazy, type ComponentType, type JSX } from 'react';
+
+import type { NotificationMessages } from '../messages';
+
+import type { NotificationsApiClient } from './api';
+import type { PreferencesScreenProps } from './preferences-screen';
+import type { WebPushSetupConfig } from './web-push-setup';
+
+/** What the factory binds into the screen, and the host never passes. */
+interface PreferencesPageParts {
+  api: NotificationsApiClient;
+  messages: NotificationMessages;
+  webPush: WebPushSetupConfig;
+}
+
+/**
+ * The routed screen, bound and loaded on first render.
+ *
+ * `lazy` memoises its factory, so the binding below happens once however many
+ * times a host mounts the page — the same guarantee the direct call gave.
+ *
+ * The fallback is `null` because a host routes to this: whatever it renders
+ * around the route is already on screen, and a second spinner inside it would
+ * be one more thing appearing and disappearing during a navigation the host is
+ * already indicating.
+ */
+export function lazyPreferencesPage(
+  parts: PreferencesPageParts,
+): ComponentType<PreferencesScreenProps> {
+  const Bound = lazy(async () => {
+    const { PreferencesScreen } = await import('./preferences-screen');
+    return {
+      default: (props: PreferencesScreenProps): JSX.Element => (
+        <PreferencesScreen {...props} {...parts} />
+      ),
+    };
+  });
+
+  return function NotificationsPreferencesPage(props: PreferencesScreenProps): JSX.Element {
+    return (
+      <Suspense fallback={null}>
+        <Bound {...props} />
+      </Suspense>
+    );
+  };
+}

package/src/react/panel-lazy.tsx

@@ -0,0 +1,74 @@
+/**
+ * The inbox slide-over, fetched the first time somebody opens it.
+ *
+ * The bell and the panel are a PAIR a host drops into its chrome, and that is
+ * still true — but only the BELL is on screen when a page paints. The panel is
+ * behind a tap, and a static import made every host pay for it up front: the
+ * design-system `Drawer` and, through it, MUI's `SwipeableDrawer`, `Modal`,
+ * `Slide` and the focus trap, plus the row, the empty state and the pager. On a
+ * storefront that is a slide-over most visits never open, parsed before the
+ * first screen can render.
+ *
+ * ## Why the gate is "ever opened" rather than `open`
+ *
+ * `lazy` fetches when a component first RENDERS, so a boundary that still
+ * rendered the panel while closed would fetch immediately and buy nothing. This
+ * renders `null` until the panel has been open once, which is what actually
+ * defers the download to the tap.
+ *
+ * And once opened it STAYS mounted. Unmounting on close would throw away the
+ * drawer's transition state, so the panel would vanish instead of sliding out,
+ * and the entrance animation would re-run on every reopen — which someone
+ * working through an inbox does repeatedly. The fetch happens once.
+ *
+ * The initial state reads `open` rather than starting at `false`, so a host that
+ * mounts the panel already open renders it in the same commit instead of a frame
+ * later.
+ *
+ * ## Why `null` for the fallback
+ *
+ * The only frame this can show anything is the one right after the tap, where a
+ * spinner reads as a stall rather than as progress. The chunk is small and
+ * same-origin.
+ */
+import { Suspense, lazy, useEffect, useState, type ComponentType, type JSX } from 'react';
+
+import type { NotificationMessages } from '../messages';
+
+import type { InboxStore } from './inbox-state';
+import type { NotificationsPanelProps } from './panel';
+
+/** What the factory binds into the panel, and the host never passes. */
+interface PanelParts {
+  store: InboxStore;
+  messages: NotificationMessages;
+}
+
+export function lazyNotificationsPanel(
+  parts: PanelParts,
+): ComponentType<NotificationsPanelProps> {
+  const Bound = lazy(async () => {
+    const { NotificationsPanel } = await import('./panel');
+    return {
+      default: (props: NotificationsPanelProps): JSX.Element => (
+        <NotificationsPanel {...props} {...parts} />
+      ),
+    };
+  });
+
+  return function NotificationsPanelSlot(props: NotificationsPanelProps): JSX.Element | null {
+    const [everOpened, setEverOpened] = useState(props.open);
+
+    useEffect(() => {
+      if (props.open) setEverOpened(true);
+    }, [props.open]);
+
+    if (!everOpened) return null;
+
+    return (
+      <Suspense fallback={null}>
+        <Bound {...props} />
+      </Suspense>
+    );
+  };
+}

package/src/server/db.ts

@@ -246,7 +246,18 @@ export type NotificationsDbProvider = () => Promise<NotificationsDb>;
  * Returning `null` for a user id means "no such recipient", which `notify`
  * treats as a caller bug and throws on — a notification addressed to nobody is
  * never silently dropped.
+ *
+ * `locale` is the recipient's own language, and it is here rather than on the
+ * event because it is a fact about the PERSON, not about what happened
+ * The host owns it for the same reason it owns the address: this
+ * package has no user table to read it from. Absent — the field omitted, or
+ * `null` for a host that stores no language yet — means "nobody said", and
+ * every generator answers with its default exactly as before.
  */
 export interface NotificationContactDirectory {
-  getContact(userId: string): Promise<{ email: string | null; phone: string | null } | null>;
+  getContact(userId: string): Promise<{
+    email: string | null;
+    phone: string | null;
+    locale?: string | null;
+  } | null>;
 }

package/src/server/dispatch.ts

@@ -99,6 +99,10 @@ export async function loadRecipient(
     userId,
     email: contact.email,
     phone: contact.phone,
+    // Carried through UNRESOLVED and only where the host supplied one: the
+    // absent case has to stay distinguishable from a stated language, because
+    // that is what lets a generator apply its own default in one place.
+    ...(contact.locale === undefined ? {} : { locale: contact.locale }),
     pushSubscriptionCount: await deps.pushSubscriptions.count(userId),
   };
 }

package/src/server/router.ts

@@ -235,11 +235,27 @@ export function createNotificationRouter(deps: NotificationRouterDeps): Notifica
 
     async notify(event, options = {}) {
       const generator = deps.generators.resolve(event.type);
-      const content = generator.generate(event.payload as never);
 
+      /*
+        The recipient is loaded BEFORE the content is rendered, and the order is
+        the whole of the fix.
+
+        `notify` is already per-person — `event.recipient.userId` is one user,
+        and a permission fan-out resolves its audience and calls this once each
+        — so the reader was knowable here all along. Rendering first simply
+        threw that away: the row was written in whatever language the generator
+        had been bound to at boot, for everyone.
+
+        Loading first also means a notification addressed to nobody now throws
+        before any content is built, which is the cheaper order anyway.
+      */
       const recipient = await loadRecipient(deps, event.recipient.userId);
       if (!recipient) throw new UnknownNotificationRecipientError(event.recipient.userId);
 
+      // Forwarded exactly as the directory stated it, `undefined` included: the
+      // generator owns the fallback, in one place a reader can find.
+      const content = generator.generate(event.payload as never, { locale: recipient.locale });
+
       const channels = await resolveChannels(deps, event, generator.category, recipient);
       const notification = await commit(deps, event, generator.category, content, channels);
 

package/src/types.ts

@@ -91,12 +91,45 @@ export interface NotificationEvent<TPayload = unknown> {
  * generator never touches existing generators, the router, or any transport
  * (open/closed).
  */
+/**
+ * Who the content is being rendered FOR — the reader, at the moment the
+ * generator is asked.
+ *
+ * A notification is stored as rendered TEXT: title and body are columns, so
+ * the language is chosen once, when the row is written, and never again. That
+ * makes this the only honest place to ask. A generator is registered at BOOT —
+ * a host that resolved its words there would pin every future reader to
+ * whichever language the process happened to start in, invisibly, because a
+ * single-locale host cannot tell the difference.
+ *
+ * The tag is the RECIPIENT's, never the request's. The person who triggers a
+ * notification is routinely not the person who reads it: an invite is sent
+ * because an administrator acted and is read by the invitee. Reading
+ * `Accept-Language` here would be a bug that only ever surfaces as somebody
+ * being told things in a language they do not speak.
+ *
+ * Absent means "nobody said" — a host with one audience, or one that stores no
+ * per-user language, populates nothing and every generator answers with its
+ * own default exactly as it did before this existed.
+ */
+export interface NotificationGenerateContext {
+  readonly locale?: string | null;
+}
+
 export interface NotificationGenerator<TPayload = unknown> {
   /** The event key, dot-namespaced ("order.paid"). One generator per type. */
   type: string;
   /** The preference category the router gates this type's fan-out on. */
   category: NotificationCategory;
-  generate: (payload: TPayload) => NotificationContent;
+  /**
+   * Render this event's content for ONE recipient.
+   *
+   * `context` is OPTIONAL, and that is what keeps every generator written
+   * before it working: a one-parameter `generate` is assignable to this
+   * signature unchanged. A host that passes nothing is stating a fact — it has
+   * no language for this reader — rather than asserting a default.
+   */
+  generate: (payload: TPayload, context?: NotificationGenerateContext) => NotificationContent;
 }
 
 /**
@@ -108,6 +141,11 @@ export interface NotificationGenerator<TPayload = unknown> {
 export interface TransportRecipient {
   userId: string;
   email: string | null;
+  /**
+   * The recipient's own language, when the host's contact directory states
+   * one. Absent means "nobody said" — see {@link NotificationGenerateContext}.
+   */
+  locale?: string | null;
   /** Phone as the host stores it (transports normalize per provider rules). */
   phone: string | null;
   /** How many active browser push subscriptions the user holds. */