@12-apps/notifications 4.9.0 → 4.10.1

package/src/live.ts

@@ -0,0 +1,179 @@
+/**
+ * LIVE ACTIVITIES — the notification centre's second kind of entry.
+ *
+ * An inbox notification is an EVENT: it happened, it is stamped, it is read or
+ * unread, and it is still there tomorrow saying the same thing. A live activity
+ * is ONGOING STATE: it is pinned above the list, it has no read/unread, nobody
+ * deletes it, it updates itself, and it is GONE the moment the thing it tracks
+ * finishes.
+ *
+ * The distinction is not cosmetic. A row that says "your order is on its way",
+ * read an hour later, is a claim about the past presented as news — and the
+ * more reliable the inbox is, the more of those a person accumulates. Somewhere
+ * in that list is the one question they actually have, which is *where is it
+ * now*. A live activity answers that question and then removes itself, which is
+ * the property no amount of better event copy can buy.
+ *
+ * ## This file is domain-free, and that is the whole design
+ *
+ * Nothing here knows what is being tracked. A host publishes activities through
+ * `LiveActivitiesConfig.useActivities` (see `./react/live-config`) and this
+ * package owns the contract, the placement, the rendering and the OS-level
+ * collapse. The package that raises an alert has never been this package's
+ * business — see the `generators` seam — and the thing an alert is ABOUT is not
+ * either.
+ *
+ * ## The lane
+ *
+ * `steps` + `activeStepId` describe a progress lane, because "how far along is
+ * this" is the shape almost every ongoing subject has. Both are optional in
+ * effect: an activity with no lane (`steps: []`, `activeStepId: null`) is a
+ * perfectly good live entry — a heading, a sentence and a timestamp that keeps
+ * moving.
+ */
+
+/** One stop on a live activity's lane. */
+export interface LiveActivityStep {
+  /** Stable across updates — the id is what `activeStepId` names. */
+  id: string;
+  /** What the reader sees under the dot. The HOST's word, in the reader's language. */
+  label: string;
+}
+
+/** One thing that is happening right now, as the notification centre shows it. */
+export interface LiveActivity {
+  /**
+   * Stable for the whole life of the subject.
+   *
+   * The SAME id on every update, because it is the identity of the thing being
+   * tracked and not of the message: the panel keys on it so a stage change
+   * re-renders one card rather than swapping two, and it is what
+   * {@link livePushTag} collapses an OS notification onto.
+   *
+   * **Unique among the activities live at one moment**, for the same reason:
+   * it is the React key and the card's test id. Two activities sharing one
+   * gives a duplicate-key warning and a card that silently shows the wrong
+   * subject.
+   */
+  id: string;
+  /**
+   * Which host concern this belongs to, e.g. `order`, `delivery`, `import`.
+   *
+   * Free-form and never rendered — it exists so a host publishing from two
+   * sources can tell its own activities apart in a test or a log without
+   * parsing `id`.
+   */
+  kind: string;
+  /** The heading — what is happening. */
+  title: string;
+  /** The line under it: the detail that makes the heading actionable, or none. */
+  body: string | null;
+  /** Where tapping the card goes, as a same-origin path. `null` renders no link. */
+  link: string | null;
+  /** The lane, in the order it is walked. Empty when this subject has no lane. */
+  steps: readonly LiveActivityStep[];
+  /**
+   * The stop the subject is AT — one of `steps`, or `null` for a laneless entry.
+   *
+   * An id that names no step is neither, and it is handled rather than trusted:
+   * see {@link liveActivityLane}.
+   */
+  activeStepId: string | null;
+  /**
+   * ISO-8601 — when the subject last MOVED, not when it was last polled.
+   *
+   * A timestamp that advances on every read would render "just now" forever,
+   * which is the one thing a live entry must not say when nothing is happening.
+   */
+  updatedAt: string;
+}
+
+/** A live activity's lane, resolved for rendering. */
+export interface LiveActivityLane {
+  steps: readonly LiveActivityStep[];
+  activeStepId: string;
+  /** Every stop BEFORE the active one — never the active one itself. */
+  completed: ReadonlySet<string>;
+}
+
+/**
+ * The lane to draw, or `null` when this activity has none to draw.
+ *
+ * Three cases collapse to `null`, and the third is the one worth writing down:
+ * no steps, no active step, and **an active step the lane does not contain**.
+ * That last one is not a theoretical defect — it is what a host produces the
+ * first time a subject reaches a stage the lane was filtered to exclude, and
+ * the symptom is a row of dots with NONE of them lit, which reads as a process
+ * that has stopped. A card with no lane still says what is happening and when
+ * it last moved; a dead lane says the tracking is broken.
+ *
+ * `completed` deliberately stops short of the active stop: a completed step
+ * draws a tick, and ticking the stop the subject is sitting in claims it has
+ * already left.
+ */
+export function liveActivityLane(activity: LiveActivity): LiveActivityLane | null {
+  const activeStepId = activity.activeStepId;
+  if (activeStepId === null || activity.steps.length === 0) return null;
+  const reached = activity.steps.findIndex((step) => step.id === activeStepId);
+  if (reached < 0) return null;
+  return {
+    steps: activity.steps,
+    activeStepId,
+    completed: new Set(activity.steps.slice(0, reached).map((step) => step.id)),
+  };
+}
+
+/**
+ * The reserved `data` key that ties a NOTIFICATION to a live subject.
+ *
+ * A notification and a live activity are different objects with different
+ * lifetimes, and this is the only thing that joins them: a generator whose
+ * event is about something also tracked live puts the activity's id here, and
+ * every channel that can collapse gets to.
+ *
+ *     data: { [LIVE_SUBJECT_KEY]: `order:${orderId}` }
+ *
+ * A plain string on purpose. An object here would grow a second wire contract
+ * inside a column this package stores verbatim.
+ */
+export const LIVE_SUBJECT_KEY = 'liveSubject';
+
+/**
+ * Namespaces the tray tag, so a live tag does not collide with the ones a host
+ * already uses.
+ *
+ * A convention rather than an enforcement — nothing stops a host emitting its
+ * own `live:`-prefixed tags — but it means the two id spaces have to be made to
+ * meet rather than meeting by accident.
+ */
+export const LIVE_PUSH_TAG_PREFIX = 'live:';
+
+/**
+ * The OS notification tag for a push about a live subject, or `null` for an
+ * ordinary event.
+ *
+ * ## What the tag buys, and why it is the PWA half of this feature
+ *
+ * A `tag` makes a new notification REPLACE the one already in the tray instead
+ * of stacking under it, and — unless the sender asks otherwise — replace it
+ * *silently*. So a subject that moves through four stages costs one tray entry
+ * and one buzz, and the entry that remains is the CURRENT one. Without it a
+ * phone accumulates one alert per stage, all of them still asserting a stage
+ * the subject has since left; the freshest is at the top and the reader has to
+ * work out that the three below it are history.
+ *
+ * That is as close as the web platform gets to an ongoing/live notification,
+ * and it is the half that reaches a person who does not have the app open —
+ * which is most of the time a live activity is live.
+ *
+ * The id is passed through unchanged: it is the host's, it is already unique
+ * per subject, and a hash would make the tray impossible to reason about from a
+ * log line.
+ */
+export function livePushTag(
+  data: Readonly<Record<string, unknown>> | null | undefined,
+): string | null {
+  const subject = data?.[LIVE_SUBJECT_KEY];
+  if (typeof subject !== 'string' || subject === '') return null;
+  return `${LIVE_PUSH_TAG_PREFIX}${subject}`;
+}

package/src/react/bell-button.tsx

@@ -3,7 +3,7 @@
  * have a styled icon-button slot. A host with its own trigger chrome uses
  * `useUnreadCount` + `Panel` directly.
  */
-import type { JSX } from 'react';
+import { useSyncExternalStore, type JSX } from 'react';
 
 import { Badge } from '@12-apps/ui/data-display/Badge';
 import { Box } from '@12-apps/ui/mui/Box';
@@ -12,6 +12,8 @@ import type { NotificationMessages } from '../messages';
 
 import { BellIcon } from './bell-icon';
 import { useUnreadCount, type NotificationsSignalHook, type NotificationsSubscribe } from './hooks';
+import type { LiveActivitiesConfig } from './live-config';
+import { hasUnseenActivity, type LiveSeenStore } from './live-seen';
 import type { InboxStore } from './inbox-state';
 
 const triggerSx = {
@@ -40,42 +42,136 @@ export interface BellButtonProps {
   enabled?: boolean;
 }
 
-export function BellButton({
+/**
+ * The trigger itself, given a count and whether any of it is NEW.
+ *
+ * Presentational, and shared by both bells below, so the two can never drift on
+ * what the badge looks like — only on where the number comes from.
+ *
+ * ## The two tones
+ *
+ * `primary` says *something happened*; `neutral` says *something is present*. A
+ * live activity is the reason that distinction has to exist: it stays on the
+ * panel for as long as the thing is happening, so a bell that painted every
+ * live entry as new would be permanently red for a pedido the reader already
+ * looked at, and a bell that ignored them would say nothing at all while one
+ * was running. Grey keeps the count honest without spending attention twice.
+ */
+function BellTrigger({
   onClick,
-  enabled = true,
-  store,
+  count,
+  hasNew,
   messages,
-  subscribe,
-  useSignal,
-}: BellButtonProps & {
-  store: InboxStore;
+}: {
+  onClick: () => void;
+  count: number;
+  hasNew: boolean;
   messages: NotificationMessages;
-  subscribe?: NotificationsSubscribe;
-  useSignal?: NotificationsSignalHook;
 }): JSX.Element {
-  const count = useUnreadCount(store, {
-    enabled,
-    ...(subscribe ? { subscribe } : {}),
-    ...(useSignal ? { useSignal } : {}),
-  });
   return (
     <Box
       component="button"
       type="button"
       onClick={onClick}
+      // `openBellWithUnread` rather than a new message, and not for want of
+      // precision: `NotificationMessages` is REQUIRED of every host, so adding
+      // a field is a breaking change to a package several apps already mount.
+      // The sentence a host wrote for "you have N" is the sentence this wants.
       aria-label={count > 0 ? messages.openBellWithUnread(count) : messages.openBell}
       data-testid="notifications-bell"
       sx={triggerSx}
     >
       <Badge
         content={count > 0 ? count : undefined}
-        color="primary"
+        color={hasNew ? 'primary' : 'neutral'}
         variant="count"
         max={99}
         data-testid="notifications-badge"
+        // The tone is carried by a colour, and a colour is not something a
+        // test can read — nor, on its own, a signal every reader can. This is
+        // what the tests assert on.
+        data-tone={hasNew ? 'new' : 'seen'}
       >
         <BellIcon size={28} />
       </Badge>
     </Box>
   );
 }
+
+export function BellButton({
+  onClick,
+  enabled = true,
+  store,
+  messages,
+  subscribe,
+  useSignal,
+}: BellButtonProps & {
+  store: InboxStore;
+  messages: NotificationMessages;
+  subscribe?: NotificationsSubscribe;
+  useSignal?: NotificationsSignalHook;
+}): JSX.Element {
+  const count = useUnreadCount(store, {
+    enabled,
+    ...(subscribe ? { subscribe } : {}),
+    ...(useSignal ? { useSignal } : {}),
+  });
+  // No live config on this host: unread IS the whole count, and an unread row
+  // is by definition something the reader has not seen.
+  return <BellTrigger onClick={onClick} count={count} hasNew={count > 0} messages={messages} />;
+}
+
+/**
+ * The bell for a host that configured live activities.
+ *
+ * A SECOND component rather than a flag on the one above, because the host's
+ * `useActivities` is a hook: reading an optional config inside one component
+ * would mean calling it conditionally, which React reports as a crash in some
+ * unrelated component rather than here. The factory knows statically which host
+ * it is building for and picks one.
+ *
+ * ## What it costs the host, stated plainly
+ *
+ * The bell is mounted for as long as the app is, so unlike the panel's copy of
+ * this hook there is no "nobody is looking" state to stand down in — `active`
+ * is simply `enabled`. A host that answers by polling therefore polls for every
+ * signed-in reader whether or not they ever open the centre. That is the price
+ * of a badge that knows about live activities at all, and the reason to answer
+ * this hook from a pushed cache rather than from an interval.
+ */
+export function LiveBellButton({
+  onClick,
+  enabled = true,
+  store,
+  messages,
+  subscribe,
+  useSignal,
+  live,
+  seen,
+}: BellButtonProps & {
+  store: InboxStore;
+  messages: NotificationMessages;
+  subscribe?: NotificationsSubscribe;
+  useSignal?: NotificationsSignalHook;
+  live: LiveActivitiesConfig;
+  seen: LiveSeenStore;
+}): JSX.Element {
+  const unread = useUnreadCount(store, {
+    enabled,
+    ...(subscribe ? { subscribe } : {}),
+    ...(useSignal ? { useSignal } : {}),
+  });
+  const activities = live.useActivities({ active: enabled });
+  const seenIso = useSyncExternalStore(seen.subscribe, seen.read, seen.read);
+  const liveCount = enabled ? activities.length : 0;
+  return (
+    <BellTrigger
+      onClick={onClick}
+      // A live entry counts. It is a notification — it is the one the reader
+      // most wants to know about — and the panel it opens lists it.
+      count={unread + liveCount}
+      hasNew={unread > 0 || (enabled && hasUnseenActivity(activities, seenIso))}
+      messages={messages}
+    />
+  );
+}

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

@@ -3,13 +3,15 @@ import { useState, type ComponentType, type JSX } from 'react';
 import { messagesOf, type NotificationMessages } from '../messages';
 
 import { createNotificationsApiClient, type NotificationsApiClient } from './api';
-import { BellButton, type BellButtonProps } from './bell-button';
+import { BellButton, LiveBellButton, type BellButtonProps } from './bell-button';
 import {
   useUnreadCount,
   type NotificationsSignalHook,
   type NotificationsSubscribe,
 } from './hooks';
 import { createInboxStore, type InboxStore } from './inbox-state';
+import type { LiveActivitiesConfig } from './live-config';
+import { createLiveSeenStore } from './live-seen';
 import { lazyNotificationsPanel } from './panel-lazy';
 import type { NotificationsPanelProps } from './panel';
 import { lazyPreferencesPage } from './page-lazy';
@@ -55,6 +57,15 @@ export interface NotificationsWebConfig {
   useSignal?: NotificationsSignalHook;
   /** The browser push enable step's host seams (SW path, platform hint). */
   webPush?: WebPushSetupConfig;
+  /**
+   * LIVE ACTIVITIES — the ongoing-state entries pinned above the inbox list.
+   *
+   * Opt-in, and absent means absent: a host that passes nothing gets the panel
+   * it had, with no section, no heading and no reserved space. See
+   * `./live-config` for the two things a host has to supply (where they come
+   * from, and what the section says) and `../live` for what one IS.
+   */
+  liveActivities?: LiveActivitiesConfig;
 }
 
 export interface WebNotifications {
@@ -107,10 +118,34 @@ export function createWebNotifications(config: NotificationsWebConfig): WebNotif
     ...(config.useSignal ? { useSignal: config.useSignal } : {}),
   };
 
-  const Bell: ComponentType<BellButtonProps> = (props) => (
-    <BellButton {...props} store={store} messages={messages} {...subscribeOption} />
-  );
-  const Panel = lazyNotificationsPanel({ store, messages });
+  // One store per factory, shared by the bell that READS it and the panel that
+  // WRITES it — the same arrangement as the inbox store above, and for the same
+  // reason: two independent copies would disagree about what the reader saw.
+  const liveSeen = createLiveSeenStore();
+
+  // Chosen ONCE, here, because `useActivities` is a hook and the choice must
+  // not be made per render: a bell that read an optional config inside itself
+  // would be calling a hook conditionally.
+  const live = config.liveActivities;
+  const Bell: ComponentType<BellButtonProps> = live
+    ? (props) => (
+        <LiveBellButton
+          {...props}
+          store={store}
+          messages={messages}
+          live={live}
+          seen={liveSeen}
+          {...subscribeOption}
+        />
+      )
+    : (props) => (
+        <BellButton {...props} store={store} messages={messages} {...subscribeOption} />
+      );
+  const Panel = lazyNotificationsPanel({
+    store,
+    messages,
+    ...(live ? { live, liveSeen } : {}),
+  });
 
   function useBoundUnreadCount(options: { enabled?: boolean } = {}): number {
     return useUnreadCount(store, { ...options, ...subscribeOption });

package/src/react/index.ts

@@ -44,6 +44,35 @@ export {
   type NotificationsSubscribe,
 } from './hooks';
 
+// `LiveActivityCard` is deliberately NOT exported. It takes the clock as a
+// prop, and the minute tick that produces one lives in `LiveSection` — so an
+// external composer would either reimplement the tick or pass `Date.now()` once
+// and get the frozen timestamp `relative-time.ts` was changed to prevent.
+// `LiveSection` is the composable unit and carries its own clock.
+export {
+  type LiveActivitiesConfig,
+  type LiveActivitiesHook,
+  type LiveActivityMessages,
+} from './live-config';
+
+/**
+ * The contract itself, re-exported from the entry a host WIRES through.
+ *
+ * It lives in the root, because both halves need it and neither owns it — but a
+ * host writing `useActivities` imports the seam from `./react` and then has to
+ * reach into a second entry for the one type that seam returns. Measured on the
+ * first adopter: a `LiveActivity` imported from here failed to compile with
+ * "declares 'LiveActivity' locally, but it is not exported", which is a
+ * confusing way to say "you wanted the other subpath".
+ */
+export {
+  liveActivityLane,
+  type LiveActivity,
+  type LiveActivityLane,
+  type LiveActivityStep,
+} from '../live';
+export { LiveSection, type LiveSectionProps } from './live-section';
+
 export { relativeTime } from './relative-time';
 
 export {