@12-apps/notifications 4.9.0 → 4.10.1

package/src/react/panel-lazy.tsx

@@ -36,12 +36,18 @@ import { Suspense, lazy, useEffect, useState, type ComponentType, type JSX } fro
 import type { NotificationMessages } from '../messages';
 
 import type { InboxStore } from './inbox-state';
+import type { LiveActivitiesConfig } from './live-config';
+import type { LiveSeenStore } from './live-seen';
 import type { NotificationsPanelProps } from './panel';
 
 /** What the factory binds into the panel, and the host never passes. */
 interface PanelParts {
   store: InboxStore;
   messages: NotificationMessages;
+  /** Absent unless the host turned live activities on — see `./live-config`. */
+  live?: LiveActivitiesConfig;
+  /** Travels with `live`: where the panel records what the reader has seen. */
+  liveSeen?: LiveSeenStore;
 }
 
 export function lazyNotificationsPanel(

package/src/react/panel.tsx

@@ -17,12 +17,16 @@ import { Box } from '@12-apps/ui/mui/Box';
 import { useMediaQuery } from '@12-apps/ui/mui/useMediaQuery';
 import { useTheme } from '@12-apps/ui/mui/styles';
 
+import type { LiveActivity } from '../live';
 import type { NotificationMessages } from '../messages';
 import type { InboxNotification } from '../wire';
 
 import { BellIcon } from './bell-icon';
 import { useInboxList } from './hooks';
 import type { InboxState, InboxStore } from './inbox-state';
+import type { LiveActivitiesConfig } from './live-config';
+import type { LiveSeenStore } from './live-seen';
+import { LiveSection } from './live-section';
 import { NotificationRow } from './row';
 
 interface PanelBodyProps {
@@ -32,6 +36,14 @@ interface PanelBodyProps {
   onLoadMore: () => void;
   onOpen: (notification: InboxNotification) => void;
   onDelete: (id: string) => void;
+  /**
+   * Whether the live section above has anything in it.
+   *
+   * The empty state is a CLAIM about the whole panel — "nenhuma notificação" —
+   * and a live entry is a notification, so an inbox with no rows under a pinned
+   * pedido is not empty. Without this the panel said both things at once.
+   */
+  hasLive: boolean;
 }
 
 /** The scrollable panel body: loading / error / empty / the list + pager. */
@@ -42,6 +54,7 @@ function PanelBody({
   onLoadMore,
   onOpen,
   onDelete,
+  hasLive,
 }: PanelBodyProps): JSX.Element {
   if (state.status === 'pending' || state.status === 'idle') {
     return (
@@ -65,7 +78,7 @@ function PanelBody({
       />
     );
   }
-  if (state.items.length === 0) {
+  if (state.items.length === 0 && !hasLive) {
     return (
       <EmptyState
         variant="illustrated"
@@ -77,7 +90,12 @@ function PanelBody({
     );
   }
   return (
-    <Box>
+    // A stable anchor for the inbox half, present whether or not it has rows.
+    // The panel's claim is that what is HAPPENING sits above what has already
+    // happened, and until this existed the only thing below the live section to
+    // point at was the empty state — which is exactly what stops rendering when
+    // something is live.
+    <Box data-testid="notifications-inbox">
       {state.items.map((notification) => (
         <NotificationRow
           key={notification.id}
@@ -105,6 +123,43 @@ function PanelBody({
   );
 }
 
+/**
+ * The two open gestures, which are ONE deep-link path with a mark-read in front
+ * of half of it.
+ *
+ * Lifted out of the component because both kinds of entry follow a link the
+ * same way and a host with no router follows neither — one rule, stated once,
+ * rather than the same three lines written twice.
+ */
+function usePanelOpeners(
+  store: InboxStore,
+  onClose: () => void,
+  onNavigate?: (link: string) => void,
+): {
+  openNotification: (notification: InboxNotification) => void;
+  openLive: (activity: LiveActivity) => void;
+} {
+  const follow = useCallback(
+    (link: string | null) => {
+      if (!link || !onNavigate) return;
+      onClose();
+      onNavigate(link);
+    },
+    [onClose, onNavigate],
+  );
+
+  return {
+    openNotification: useCallback(
+      (notification: InboxNotification) => {
+        if (notification.readAt === null) store.markRead([notification.id]);
+        follow(notification.link);
+      },
+      [store, follow],
+    ),
+    openLive: useCallback((activity: LiveActivity) => follow(activity.link), [follow]),
+  };
+}
+
 export interface NotificationsPanelProps {
   open: boolean;
   onClose: () => void;
@@ -112,15 +167,70 @@ export interface NotificationsPanelProps {
   onNavigate?: (link: string) => void;
 }
 
+/**
+ * Everything BELOW the live section: the mark-all control and the list.
+ *
+ * Its own component rather than a block inside the panel because it is rendered
+ * from two places — through `LiveSection`, and directly when the host turned
+ * live activities off — and because the panel is at its line ceiling. "Marcar
+ * todas como lidas" belongs to the INBOX and travels with it: a live entry has
+ * nothing to mark.
+ */
+function PanelInbox({
+  state,
+  messages,
+  store,
+  onOpen,
+  hasLive,
+}: {
+  state: InboxState;
+  messages: NotificationMessages;
+  store: InboxStore;
+  onOpen: (notification: InboxNotification) => void;
+  hasLive: boolean;
+}): JSX.Element {
+  const hasUnread = state.items.some((item) => item.readAt === null);
+  return (
+    <>
+      {hasUnread ? (
+        <Box sx={{ display: 'flex', justifyContent: 'flex-end', pb: 1 }}>
+          <Button
+            variant="ghost"
+            color="primary"
+            size="xs"
+            onClick={() => store.markAllRead()}
+            dataTestId="notifications-mark-all-read"
+          >
+            {messages.markAllRead}
+          </Button>
+        </Box>
+      ) : null}
+      <PanelBody
+        state={state}
+        messages={messages}
+        onRetry={() => store.invalidate()}
+        onLoadMore={() => store.loadMore()}
+        onOpen={onOpen}
+        onDelete={(id) => store.remove(id)}
+        hasLive={hasLive}
+      />
+    </>
+  );
+}
+
 export function NotificationsPanel({
   open,
   onClose,
   onNavigate,
   store,
   messages,
+  live,
+  liveSeen,
 }: NotificationsPanelProps & {
   store: InboxStore;
   messages: NotificationMessages;
+  live?: LiveActivitiesConfig;
+  liveSeen?: LiveSeenStore;
 }): JSX.Element {
   // `useTheme` from @mui/material/styles falls back to the DEFAULT theme when
   // no provider is mounted, where the callback form of `useMediaQuery` would
@@ -130,18 +240,20 @@ export function NotificationsPanel({
   const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
   const state = useInboxList(store, open);
 
-  const openNotification = useCallback(
-    (notification: InboxNotification) => {
-      if (notification.readAt === null) store.markRead([notification.id]);
-      if (notification.link && onNavigate) {
-        onClose();
-        onNavigate(notification.link);
-      }
-    },
-    [store, onClose, onNavigate],
-  );
+  const { openNotification, openLive } = usePanelOpeners(store, onClose, onNavigate);
 
-  const hasUnread = state.items.some((item) => item.readAt === null);
+  // A function rather than an element so the live count can reach it: with a
+  // live section it is called by `LiveSection` — the only place the host's hook
+  // may be called — and without one it is called here with zero.
+  const renderInbox = (liveCount: number): JSX.Element => (
+    <PanelInbox
+      state={state}
+      messages={messages}
+      store={store}
+      onOpen={openNotification}
+      hasLive={liveCount > 0}
+    />
+  );
 
   return (
     <Drawer
@@ -154,27 +266,25 @@ export function NotificationsPanel({
     >
       <DrawerHeader onClose={onClose}>{messages.panelTitle}</DrawerHeader>
       <DrawerContent>
-        {hasUnread ? (
-          <Box sx={{ display: 'flex', justifyContent: 'flex-end', pb: 1 }}>
-            <Button
-              variant="ghost"
-              color="primary"
-              size="xs"
-              onClick={() => store.markAllRead()}
-              dataTestId="notifications-mark-all-read"
-            >
-              {messages.markAllRead}
-            </Button>
-          </Box>
-        ) : null}
-        <PanelBody
-          state={state}
-          messages={messages}
-          onRetry={() => store.invalidate()}
-          onLoadMore={() => store.loadMore()}
-          onOpen={openNotification}
-          onDelete={(id) => store.remove(id)}
-        />
+        {/*
+          Above the mark-all control as well as above the list, deliberately:
+          "marcar todas como lidas" belongs to the INBOX, and a live entry has
+          nothing to mark. A control between the two blocks would read as
+          applying to both.
+        */}
+        {live ? (
+          <LiveSection
+            config={live}
+            messages={messages}
+            active={open}
+            {...(onNavigate ? { onOpen: openLive } : {})}
+            {...(liveSeen ? { seen: liveSeen } : {})}
+          >
+            {renderInbox}
+          </LiveSection>
+        ) : (
+          renderInbox(0)
+        )}
       </DrawerContent>
     </Drawer>
   );

package/src/react/relative-time.ts

@@ -4,9 +4,21 @@ import type { NotificationMessages } from '../messages';
  * "há 5 min"-style relative timestamp, falling back to an absolute date for
  * anything older than a week. Every word comes from the messages table, so a
  * host in another locale changes the copy and the locale together.
+ *
+ * `now` is a parameter rather than a read, and the live section is why. A
+ * relative phrase is only true for the instant it was computed, so something
+ * has to CAUSE the render that recomputes it — and the live entries' own data
+ * cannot: a host backed by react-query gets the previous object back whenever a
+ * poll is deep-equal (`structuralSharing`, on by default), which within one
+ * stage it always is. The section therefore ticks a clock and hands it down.
+ * Defaulted, so every existing caller reads the wall clock exactly as before.
  */
-export function relativeTime(iso: string, messages: NotificationMessages): string {
-  const elapsedMs = Date.now() - new Date(iso).getTime();
+export function relativeTime(
+  iso: string,
+  messages: NotificationMessages,
+  now: number = Date.now(),
+): string {
+  const elapsedMs = now - new Date(iso).getTime();
   const minutes = Math.round(elapsedMs / 60_000);
   if (minutes < 1) return messages.justNow;
   if (minutes < 60) return messages.minutesAgo(minutes);

package/src/server/transports/web-push.ts

@@ -1,3 +1,4 @@
+import { livePushTag } from '../../live';
 import type {
   NotificationContent,
   NotificationLogger,
@@ -52,6 +53,26 @@ export interface WebPushMessage {
   body: string;
   link: string | null;
   data: Record<string, unknown>;
+  /**
+   * The OS tray tag, or `null` for an ordinary event.
+   *
+   * Present for a notification about a LIVE SUBJECT (see `../../live`), and
+   * this is the whole of the live feature's reach onto a locked phone: a tag
+   * makes the next push about the same subject REPLACE the one already in the
+   * tray — silently — instead of stacking under it. Four stages then cost one
+   * entry and one buzz, and the entry that remains is the current one.
+   *
+   * {@link formatWebPush} always sets it, `null` included, so on the WIRE the
+   * key is always there and a service worker reads one shape. A worker that
+   * ignores it keeps today's behaviour exactly, which is what makes this safe
+   * to ship ahead of the workers.
+   *
+   * OPTIONAL in the type, and only in the type: a host that hand-writes its own
+   * `NotificationTransport<WebPushMessage>` — a fixture, a second driver —
+   * would otherwise stop compiling on a field it has no way to know about and
+   * no reason to set.
+   */
+  tag?: string | null;
 }
 
 export interface WebPushDriverDeclaration extends DriverDeclarationBase {
@@ -120,6 +141,7 @@ export function formatWebPush(content: NotificationContent): WebPushMessage {
     body: content.body,
     link: content.link ?? null,
     data: content.data ?? {},
+    tag: livePushTag(content.data),
   };
 }
 

package/src/types.ts

@@ -64,7 +64,16 @@ export interface NotificationContent {
   body: string;
   /** In-app deep link (a same-origin path such as `/orders/123`). */
   link?: string;
-  /** Structured extras for consumers that want more than text. */
+  /**
+   * Structured extras for consumers that want more than text.
+   *
+   * ONE KEY IS RESERVED: `liveSubject` (`LIVE_SUBJECT_KEY` in `./live`) ties
+   * this notification to a live activity, and the WEB_PUSH transport turns it
+   * into the tray `tag` that collapses every push about one subject onto a
+   * single entry. A host already using that name for something else acquires
+   * that behaviour without asking for it — so it is named here, on the field a
+   * generator actually writes, and not only where the feature is documented.
+   */
   data?: Record<string, unknown>;
 }
 

package/dist/chunk-BGI4BQ66.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Core types of the channel-agnostic notification system (12-15).\n *\n * Three decoupled layers, each open for extension without touching the others:\n *   - GENERATORS map a typed domain event to agnostic content (title/body/…).\n *   - The CHANNEL ROUTER always writes the notification-centre inbox record,\n *     then fans out one delivery per enabled channel.\n *   - TRANSPORTS format the agnostic content for one channel and send it.\n *\n * Nothing here knows about a concrete channel's wire format — that lives\n * entirely inside each transport adapter — and nothing here knows about a\n * concrete DOMAIN either: the event `type` set, the preference categories and\n * the channel list are all host config (see {@link NotificationTaxonomy}).\n */\n\n/** Transport channels a notification can fan out to (DB CHECK mirrors this). */\nexport const NOTIFICATION_CHANNELS = ['EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'] as const;\nexport type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];\n\n/**\n * The preference categories are the HOST's, and required.\n *\n * There used to be a `NOTIFICATION_CATEGORIES = ['orders','payments','stock',\n * 'system']` here — one product's set — and `taxonomyOf` fell back to it\n * whenever a host passed none. The docstring argued the case itself: \"it is\n * product vocabulary, not machinery\", and then shipped the vocabulary anyway as\n * the default, which is the only part a forgetful host would ever see.\n *\n * The consequence was quiet rather than loud: the settings screen renders four\n * rows a foreign host never chose, its own categories are absent, and every\n * preference a user sets is filed against a taxonomy nothing else in that\n * system uses. Nothing throws, because `category` is deliberately a free string\n * — the packaged migration puts **no CHECK** on it, precisely because a closed\n * set would be wrong for every host but the first. That freedom is what made\n * the default undetectable.\n *\n * `channel` and `status` are different and keep their CHECKs: those ARE this\n * library's own closed sets.\n */\nexport type NotificationCategory = string;\n\n/**\n * Per-channel delivery lifecycle (DB CHECK mirrors this).\n *\n * `SENDING` is the CLAIM: exactly one dispatcher moves a row out of `QUEUED`,\n * so two dispatchers can never both send the same delivery. A row left\n * `SENDING` is a dispatcher that died mid-send, and the sweep reclaims it once\n * it is older than the cutoff.\n *\n * `DEAD` is terminal: the attempt ceiling was reached (or the recipient no\n * longer exists), and no sweep will pick the row up again. Without it a\n * permanently invalid destination is a billed provider call on every sweep,\n * forever, and the sweep's working set only grows.\n */\nexport type DeliveryStatus = 'QUEUED' | 'SENDING' | 'SENT' | 'FAILED' | 'DEAD';\n\n/**\n * Channel-agnostic content a generator produces. This is what the inbox stores\n * verbatim and what every transport's formatter receives — no channel may leak\n * its wire format into it.\n */\nexport interface NotificationContent {\n  title: string;\n  body: string;\n  /** In-app deep link (a same-origin path such as `/orders/123`). */\n  link?: string;\n  /** Structured extras for consumers that want more than text. */\n  data?: Record<string, unknown>;\n}\n\n/** Who receives a notification. `clientId` scopes it to a tenant when set. */\nexport interface NotificationRecipient {\n  userId: string;\n  clientId?: string;\n}\n\n/**\n * A typed domain event handed to `notify`. `type` selects the registered\n * generator; `payload` is that generator's typed input. Callers never touch\n * channels, formatting, or preferences.\n */\nexport interface NotificationEvent<TPayload = unknown> {\n  type: string;\n  recipient: NotificationRecipient;\n  payload: TPayload;\n}\n\n/**\n * Maps one domain event type to agnostic content. Registered through the\n * server config (or `registerGenerator` for a late arrival); adding a\n * generator never touches existing generators, the router, or any transport\n * (open/closed).\n */\n/**\n * Who the content is being rendered FOR — the reader, at the moment the\n * generator is asked.\n *\n * A notification is stored as rendered TEXT: title and body are columns, so\n * the language is chosen once, when the row is written, and never again. That\n * makes this the only honest place to ask. A generator is registered at BOOT —\n * a host that resolved its words there would pin every future reader to\n * whichever language the process happened to start in, invisibly, because a\n * single-locale host cannot tell the difference.\n *\n * The tag is the RECIPIENT's, never the request's. The person who triggers a\n * notification is routinely not the person who reads it: an invite is sent\n * because an administrator acted and is read by the invitee. Reading\n * `Accept-Language` here would be a bug that only ever surfaces as somebody\n * being told things in a language they do not speak.\n *\n * Absent means \"nobody said\" — a host with one audience, or one that stores no\n * per-user language, populates nothing and every generator answers with its\n * own default exactly as it did before this existed.\n */\nexport interface NotificationGenerateContext {\n  readonly locale?: string | null;\n}\n\nexport interface NotificationGenerator<TPayload = unknown> {\n  /** The event key, dot-namespaced (\"order.paid\"). One generator per type. */\n  type: string;\n  /** The preference category the router gates this type's fan-out on. */\n  category: NotificationCategory;\n  /**\n   * Render this event's content for ONE recipient.\n   *\n   * `context` is OPTIONAL, and that is what keeps every generator written\n   * before it working: a one-parameter `generate` is assignable to this\n   * signature unchanged. A host that passes nothing is stating a fact — it has\n   * no language for this reader — rather than asserting a default.\n   */\n  generate: (payload: TPayload, context?: NotificationGenerateContext) => NotificationContent;\n}\n\n/**\n * The recipient as a transport sees them: resolved destinations only. Built by\n * the router from the host's contact directory + the push subscriptions this\n * package owns; transports use it to answer\n * {@link NotificationTransport.supports}.\n */\nexport interface TransportRecipient {\n  userId: string;\n  email: string | null;\n  /**\n   * The recipient's own language, when the host's contact directory states\n   * one. Absent means \"nobody said\" — see {@link NotificationGenerateContext}.\n   */\n  locale?: string | null;\n  /** Phone as the host stores it (transports normalize per provider rules). */\n  phone: string | null;\n  /** How many active browser push subscriptions the user holds. */\n  pushSubscriptionCount: number;\n}\n\n/**\n * One pluggable channel adapter: a FORMATTER (agnostic content → channel\n * message) plus a SENDER. Adding a channel = registering one of these; the\n * router dispatches through the registry and needs no change.\n *\n * `send` resolves on success and THROWS on failure — the router records the\n * error on the delivery row and isolates it from other channels. Sends must be\n * retry-safe: the router may re-dispatch a QUEUED/FAILED delivery.\n */\nexport interface NotificationTransport<TMessage = unknown> {\n  channel: NotificationChannel;\n  /**\n   * Whether this recipient is addressable on this channel right now — the\n   * destination exists (e-mail / phone / push subscription) AND the provider\n   * is configured. `false` simply skips the channel (no delivery row).\n   */\n  supports(recipient: TransportRecipient): boolean;\n  /** Transform the agnostic content into this channel's message shape. */\n  format(content: NotificationContent): TMessage;\n  /** Deliver the formatted message to the recipient. Throws on failure. */\n  send(message: TMessage, recipient: TransportRecipient): Promise<void>;\n}\n\n/**\n * The host's product vocabulary. Everything below the surface (routing,\n * delivery rows, retries, the wire) is identical for every host; WHICH\n * categories exist and how they are labelled is not.\n */\nexport interface NotificationTaxonomy {\n  /** The preference categories, in the order the settings screen lists them. */\n  categories: readonly NotificationCategory[];\n}\n\n/**\n * The taxonomy in force. `categories` is REQUIRED — see above.\n *\n * The empty check was already here and stays: an empty list and a missing one\n * are the same mistake, and both now fail at assembly rather than rendering an\n * empty settings screen or somebody else's four rows.\n */\nexport function taxonomyOf(config: {\n  categories: readonly NotificationCategory[];\n}): NotificationTaxonomy {\n  const categories = config.categories;\n  if (!categories || categories.length === 0) {\n    throw new Error(\n      '@12-apps/notifications: `categories` is required and must not be empty — ' +\n        'the preference categories are the host\\'s product vocabulary.',\n    );\n  }\n  return { categories: [...categories] };\n}\n\n/** The host's logger. Defaults to the console (the @12-apps/jobs precedent). */\nexport interface NotificationLogger {\n  info(message: string, ...meta: unknown[]): void;\n  error(message: string, ...meta: unknown[]): void;\n}\n"],"mappings":";;;;;AAgBO,IAAM,wBAAwB,CAAC,SAAS,OAAO,YAAY,UAAU;AAkLrE,SAAS,WAAW,QAEF;AACvB,QAAM,aAAa,OAAO;AAC1B,MAAI,CAAC,cAAc,WAAW,WAAW,GAAG;AAC1C,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,SAAO,EAAE,YAAY,CAAC,GAAG,UAAU,EAAE;AACvC;AAXgB;","names":[]}