@12-apps/notifications 4.8.0 → 4.10.0

package/src/react/live-config.ts

@@ -0,0 +1,79 @@
+/**
+ * The host's half of live activities: where they come from, and what they say.
+ *
+ * Both are the host's because neither can be this package's. It has no idea
+ * what is happening — only the application does — and it has no words, for the
+ * same reason `NotificationMessages` is required rather than defaulted: a
+ * package that ships one product's sentences ships them to every other product
+ * too, and the adopter reached by saying nothing is the one who never notices.
+ */
+import type { ReactNode } from 'react';
+
+import type { LiveActivity } from '../live';
+
+/**
+ * Where the surface gets the activities that are live RIGHT NOW.
+ *
+ * A HOOK rather than a fetcher, and rather than a factory-time `subscribe`,
+ * because the answer almost always lives in React context: the tenant, the
+ * session, the host's query client. `NotificationsSignalHook` exists for
+ * exactly this reason one seam over, and a host in that shape had no way to
+ * pass anything at all.
+ *
+ * `active` is whether the surface currently needs the answer. It is a HINT
+ * about need, never about correctness: a host that ignores it and always
+ * answers is behaving correctly and merely paying for it.
+ *
+ * What it is NOT is the only thing standing between a shut panel and a query.
+ * The panel is fetched lazily and renders nothing until somebody first opens
+ * the bell, and the drawer unmounts its content on close — so a host that
+ * simply reads `active` and ignores it still issues nothing while the panel is
+ * away. `active` is `false` for the frames of the closing transition, which is
+ * where it earns its keep: a query told to stand down there does not fire one
+ * last time on the way out.
+ *
+ * Return whatever is live, newest activity first or in whatever order the host
+ * means; the surface renders them in the order given. An empty array is the
+ * normal answer and renders nothing — no heading, no empty state, no gap.
+ */
+export type LiveActivitiesHook = (options: {
+  active: boolean;
+}) => readonly LiveActivity[];
+
+/** The three sentences the live section says. */
+export interface LiveActivityMessages {
+  /** The heading over the pinned entries, e.g. "Em andamento". */
+  sectionTitle: string;
+  /** The link's accessible name, e.g. `(title) => `Abrir ${title}``. */
+  openActivity: (title: string) => string;
+  /**
+   * The "last moved" line, given an already-relative time.
+   *
+   * Takes the phrase rather than the instant so the relative wording stays in
+   * ONE place — `relativeTime` and the inbox rows' `há 5 min` — and a host
+   * cannot end up with two vocabularies for the same duration in one panel.
+   */
+  updated: (relative: string) => string;
+}
+
+/** Live activities, as a host turns them on. */
+export interface LiveActivitiesConfig {
+  useActivities: LiveActivitiesHook;
+  messages: LiveActivityMessages;
+  /**
+   * The mark on the left of a card — the fastest read, before any words.
+   *
+   * A node rather than a field on {@link LiveActivity} so the contract stays
+   * framework-free: the root entry is shared with the server half, and a
+   * `ReactNode` in it would put React on that import path for a backend that
+   * only ever writes rows. The host switches on `kind`, which is what `kind` is
+   * for. No renderer, no mark, and the card is text — never a placeholder box.
+   *
+   * **Return something PRESENTATIONAL.** The mark is drawn inside the card's
+   * own `<button>` and inside an `aria-hidden` wrapper, so a focusable node
+   * here is a button inside a button — invalid HTML, and the exact defect the
+   * card's structure exists to prevent — as well as a control hidden from the
+   * accessibility tree. An icon or an `<svg>`; not a control.
+   */
+  renderIcon?: (activity: LiveActivity) => ReactNode;
+}

package/src/react/live-section.tsx

@@ -0,0 +1,141 @@
+/**
+ * The pinned block at the top of the panel: everything that is happening NOW,
+ * above everything that has already happened.
+ *
+ * ## Why it is here and not a second surface
+ *
+ * The notification centre is where a person goes to find out what they missed.
+ * Splitting "happening" into its own bell would make them check two places to
+ * answer one question, and the half they would stop checking is the one that
+ * only has something in it occasionally — which is this one. Above the list,
+ * inside the same drawer, it is on the path they already walk.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * - It does not touch `unread`. A live entry is not news; counting it would put
+ *   a number on the bell that no amount of reading can clear.
+ * - It renders nothing at all when there is nothing live — no heading, no empty
+ *   state, no reserved space. A panel with one permanent empty section in it is
+ *   a panel that has taught its reader to skip the top.
+ * - It does not fetch. `useActivities` is the host's, and `active` tells it
+ *   whether anyone is looking.
+ */
+import { useEffect, useId, useState, type JSX } from 'react';
+
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { LiveActivity } from '../live';
+import type { NotificationMessages } from '../messages';
+
+import { LiveActivityCard } from './live-card';
+import type { LiveActivitiesConfig } from './live-config';
+
+/**
+ * How often the section re-reads the clock.
+ *
+ * Every minute, because the timestamps under the cards are in minutes and a
+ * tick that cannot change what is on screen is a wasted render — which is why
+ * it is gated on there being something to tick as well as on the panel being
+ * open. An open panel with nothing live schedules nothing at all; the earlier
+ * gate was `active` alone, and it re-rendered a section that renders `null`
+ * once a minute for as long as somebody left the inbox open.
+ */
+const TICK_MS = 60_000;
+
+/**
+ * The current minute, re-read on a timer while there is something to tick.
+ *
+ * The caller passes `active && there are activities` — see {@link TICK_MS} for
+ * why both halves are in it.
+ */
+function useMinuteTick(active: boolean): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!active) return;
+    // Re-read once on becoming active too: a panel reopened after ten minutes
+    // would otherwise show the minute it was closed at until the first tick.
+    setNow(Date.now());
+    const timer = setInterval(() => setNow(Date.now()), TICK_MS);
+    return () => clearInterval(timer);
+  }, [active]);
+  return now;
+}
+
+export interface LiveSectionProps {
+  config: LiveActivitiesConfig;
+  messages: NotificationMessages;
+  /** Whether the panel is open — passed straight through to the host's hook. */
+  active: boolean;
+  /**
+   * Follow a card's link.
+   *
+   * Optional, and the panel omits it for a host with no router: a card that
+   * cannot go anywhere renders as text rather than as a named control that
+   * does nothing.
+   */
+  onOpen?: (activity: LiveActivity) => void;
+}
+
+
+
+export function LiveSection({
+  config,
+  messages,
+  active,
+  onOpen,
+}: LiveSectionProps): JSX.Element | null {
+  // Unconditional, because it is a hook. `active` is how it is told nobody is
+  // looking — the same arrangement `useSignal` has one seam over.
+  const activities = config.useActivities({ active });
+  const now = useMinuteTick(active && activities.length > 0);
+  // Per MOUNT, not per module: `LiveSection` is exported, and a host with a
+  // desktop and a mobile panel would otherwise emit one id twice and have both
+  // regions resolve their label to whichever came first.
+  const headingId = useId();
+
+  if (activities.length === 0) return null;
+
+  return (
+    // A NAMED region. Without the label a screen-reader user meets a loose run
+    // of controls ahead of the inbox with nothing saying what they are; the
+    // panel's own title is the drawer's heading and cannot describe this block.
+    <Box
+      component="section"
+      aria-labelledby={headingId}
+      data-testid="live-activities"
+      sx={{ pb: 1.5 }}
+    >
+      {/*
+        A SPAN, not a heading. `aria-labelledby` names the region perfectly well
+        from one, and an `<h2>` here would sit under the drawer's own `<h6>`
+        title and ABOVE the inbox's `<h3>` empty state — an outline in which the
+        inbox's states read as part of the live block, which is the opposite of
+        what the two blocks are.
+      */}
+      <Text
+        id={headingId}
+        variant="caption"
+        size="xs"
+        color="secondary"
+        weight="semibold"
+        as="span"
+      >
+        {config.messages.sectionTitle}
+      </Text>
+      <Box sx={{ pt: 0.75 }}>
+        {activities.map((activity) => (
+          <LiveActivityCard
+            key={activity.id}
+            activity={activity}
+            messages={messages}
+            live={config.messages}
+            now={now}
+            {...(onOpen ? { onOpen } : {})}
+            {...(config.renderIcon ? { renderIcon: config.renderIcon } : {})}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}

package/src/react/panel-lazy.tsx

@@ -36,12 +36,15 @@ 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 { 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;
 }
 
 export function lazyNotificationsPanel(

package/src/react/panel.tsx

@@ -17,12 +17,15 @@ 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 { LiveSection } from './live-section';
 import { NotificationRow } from './row';
 
 interface PanelBodyProps {
@@ -105,6 +108,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;
@@ -118,9 +158,11 @@ export function NotificationsPanel({
   onNavigate,
   store,
   messages,
+  live,
 }: NotificationsPanelProps & {
   store: InboxStore;
   messages: NotificationMessages;
+  live?: LiveActivitiesConfig;
 }): 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,16 +172,7 @@ 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);
 
@@ -154,6 +187,20 @@ export function NotificationsPanel({
     >
       <DrawerHeader onClose={onClose}>{messages.panelTitle}</DrawerHeader>
       <DrawerContent>
+        {/*
+          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 } : {})}
+          />
+        ) : null}
         {hasUnread ? (
           <Box sx={{ display: 'flex', justifyContent: 'flex-end', pb: 1 }}>
             <Button

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/email.ts

@@ -5,6 +5,10 @@ import type {
   TransportRecipient,
 } from '../../types';
 
+import { renderEmail } from '../../email/template';
+import type { EmailChromeCopy } from '../../email/template';
+import type { EmailTheme } from '../../email/theme';
+
 import {
   absoluteLink,
   postOrThrow,
@@ -53,6 +57,31 @@ export interface EmailDriverDeclaration extends DriverDeclarationBase {
    * `from` address.
    */
   linkLabel: string;
+  /**
+   * Render through `../../email` — the ONE layout — instead of the three bare
+   * `<p>` tags below.
+   *
+   * OPTIONAL, and its absence is the pre-layout behaviour verbatim. That is
+   * deliberate rather than timid: `brand` and `chrome` are REQUIRED with no
+   * default anywhere in the layout (a package that defaulted them would sign
+   * another company's mail, in a language nobody chose), so a required field
+   * here would break every host that already declares EMAIL — at runtime, on
+   * the first send, which is the worst place to find out.
+   *
+   * So the seam is opt-in and the ad-hoc path is what remains for a host that
+   * has not taken it. `layout.theme` may still be omitted; `../../email/theme`
+   * argues why that one asymmetry is allowed.
+   */
+  layout?: {
+    /** The product name in the header and the footer. */
+    brand: string;
+    /** The layout's own words. `@12-apps/notifications/email/locales` ships packs. */
+    chrome: EmailChromeCopy;
+    /** The recipient's language, for the document's `lang` attribute. */
+    locale: string;
+    /** Defaults to the layout's neutral palette. */
+    theme?: EmailTheme;
+  };
   logger?: NotificationLogger;
 }
 
@@ -108,6 +137,11 @@ export const EMAIL_DRIVERS: Record<
 /**
  * Agnostic content → subject/text/html. The link becomes a trailing CTA, only
  * when an app base URL is configured.
+ *
+ * Two renderings, and which one runs is the host's choice: with `layout`
+ * declared this is the shared document (`../../email`), and without it the
+ * three bare `<p>` tags that predate it. See `EmailDriverDeclaration.layout`
+ * for why the new path could not simply replace the old one.
  */
 export function formatEmail(
   content: NotificationContent,
@@ -115,6 +149,7 @@ export function formatEmail(
 ): EmailMessage {
   const href = absoluteLink(content.link, declaration.appUrl);
   const label = declaration.linkLabel;
+  if (declaration.layout) return layoutEmail(content, declaration.layout, href, label);
   return {
     subject: content.title,
     text: href ? `${content.body}\n\n${href}` : content.body,
@@ -126,6 +161,33 @@ export function formatEmail(
   };
 }
 
+/**
+ * The same notification as a laid-out document.
+ *
+ * The layout escapes and builds the plain-text twin from the SAME object, which
+ * is the pair of defects the branch above still carries by construction: its
+ * text half is assembled separately, and its `href` reaches the anchor through
+ * `escapeHtml` rather than through a scheme check.
+ */
+function layoutEmail(
+  content: NotificationContent,
+  layout: NonNullable<EmailDriverDeclaration['layout']>,
+  href: string | null,
+  label: string,
+): EmailMessage {
+  const rendered = renderEmail({
+    subject: content.title,
+    heading: content.title,
+    paragraphs: [content.body],
+    action: href ? { label, href } : undefined,
+    chrome: layout.chrome,
+    brand: layout.brand,
+    locale: layout.locale,
+    theme: layout.theme,
+  });
+  return { subject: rendered.subject, text: rendered.text, html: rendered.html };
+}
+
 export function emailTransport(
   declaration: EmailDriverDeclaration,
   extraDrivers: Record<string, (d: EmailDriverDeclaration) => EmailDriver> = {},

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>;
 }