@12-apps/notifications 1.0.0

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

@@ -0,0 +1,127 @@
+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 { useUnreadCount, 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 { httpNotificationsTransport, type NotificationsTransport } from './transport';
+import type { WebPushSetupConfig } from './web-push-setup';
+
+/**
+ * The one thing this package exposes to a FRONTEND host (12-15).
+ *
+ * Everything the notification centre IS — the bell with its live badge, the
+ * slide-over inbox with its optimistic mark-read / delete / mark-all and its
+ * cursor pager, the preferences matrix with its availability hints and the
+ * per-browser push enable step, and every wire call between them — lives inside
+ * this package. The host names where the API is mounted, and that is the whole
+ * wiring.
+ *
+ * `page` is the standalone surface (the preferences screen), which is the one
+ * thing a host routes to. The bell and the panel are a PAIR a host drops into
+ * its own chrome, and they share one store, so a read in the panel moves the
+ * badge in the same tick.
+ */
+
+export interface NotificationsWebConfig {
+  /** The account mount the routes live under, e.g. `/api/account`. */
+  apiBase: string;
+  /** How the surface reaches its data. Default: same-origin fetch. */
+  transport?: NotificationsTransport;
+  /** User-facing copy overrides (pt-BR product copy by default). */
+  messages?: Partial<NotificationMessages>;
+  /**
+   * How the surface learns an inbox changed without asking — the host's message
+   * bus. Without it the badge keeps its 60 s poll, which is the standing
+   * contract rather than a fallback: a dropped event must cost latency, never
+   * correctness.
+   */
+  subscribe?: NotificationsSubscribe;
+  /** The browser push enable step's host seams (SW path, platform hint). */
+  webPush?: WebPushSetupConfig;
+}
+
+export interface WebNotifications {
+  /** The routed surface: the preferences screen. */
+  page: ComponentType<PreferencesScreenProps>;
+  /** The bell, already bound to the shared store. */
+  BellButton: ComponentType<BellButtonProps>;
+  /** The inbox slide-over, sharing that store. */
+  Panel: ComponentType<NotificationsPanelProps>;
+  /**
+   * Bell + panel as ONE element, for a host that just wants the feature in its
+   * header and does not want to own the open/closed state.
+   */
+  BellWithPanel: ComponentType<{
+    enabled?: boolean;
+    onNavigate?: (link: string) => void;
+  }>;
+  /** The badge number, for a host with its own trigger chrome. */
+  useUnreadCount: (options?: { enabled?: boolean }) => number;
+  /** The shared client state, for host glue. */
+  store: InboxStore;
+  /** The bound wire client. */
+  api: NotificationsApiClient;
+  /** The copy in force, so a host's own chrome can reuse a sentence. */
+  messages: NotificationMessages;
+}
+
+export function createWebNotifications(config: NotificationsWebConfig): WebNotifications {
+  const messages = messagesOf(config);
+  const api = createNotificationsApiClient(
+    config.apiBase,
+    config.transport ?? httpNotificationsTransport(messages.operationFailed),
+  );
+  const store = createInboxStore(api);
+  const webPush = config.webPush ?? {};
+  const subscribe = config.subscribe;
+  const subscribeOption = subscribe ? { subscribe } : {};
+
+  const Bell: ComponentType<BellButtonProps> = (props) => (
+    <BellButton {...props} store={store} messages={messages} {...subscribeOption} />
+  );
+  const Panel: ComponentType<NotificationsPanelProps> = (props) => (
+    <NotificationsPanel {...props} store={store} messages={messages} />
+  );
+
+  function useBoundUnreadCount(options: { enabled?: boolean } = {}): number {
+    return useUnreadCount(store, { ...options, ...subscribeOption });
+  }
+
+  function BellWithPanel({
+    enabled = true,
+    onNavigate,
+  }: {
+    enabled?: boolean;
+    onNavigate?: (link: string) => void;
+  }): JSX.Element {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <Bell enabled={enabled} onClick={() => setOpen(true)} />
+        <Panel
+          open={open}
+          onClose={() => setOpen(false)}
+          {...(onNavigate ? { onNavigate } : {})}
+        />
+      </>
+    );
+  }
+
+  return {
+    page: (props) => (
+      <PreferencesScreen {...props} api={api} messages={messages} webPush={webPush} />
+    ),
+    BellButton: Bell,
+    Panel,
+    BellWithPanel,
+    useUnreadCount: useBoundUnreadCount,
+    store,
+    api,
+    messages,
+  };
+}

package/src/react/hooks.ts

@@ -0,0 +1,74 @@
+import { useEffect, useSyncExternalStore } from 'react';
+
+import {
+  BADGE_POLL_MS,
+  BADGE_RECONCILE_MS,
+  type InboxState,
+  type InboxStore,
+} from './inbox-state';
+
+/**
+ * The two hooks the bell and the panel use, and the realtime seam between them.
+ *
+ * A host that has a message bus passes `subscribe`; one that has not passes
+ * nothing and keeps the 60 s poll. The bell ships in this package and mounts in
+ * whatever embeds it, so it must not require the host to have adopted anything.
+ */
+
+/**
+ * How the surface learns an inbox changed without asking.
+ *
+ * Called once per mounted bell with a callback that means only "ask again" — no
+ * payload, so the number on screen is always one the server just gave us.
+ * Returns its own teardown. A host wires this to whatever it already has.
+ */
+export type NotificationsSubscribe = (onHint: () => void) => () => void;
+
+export function useInboxState(store: InboxStore): InboxState {
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}
+
+/**
+ * The bell badge number: pushed while a subscription is live, polled otherwise.
+ *
+ * `enabled` gates the poll AND the subscription. A signed-out header still
+ * mounts the bell, and there is nothing for it to hear.
+ */
+export function useUnreadCount(
+  store: InboxStore,
+  options: { enabled?: boolean; subscribe?: NotificationsSubscribe } = {},
+): number {
+  const enabled = options.enabled ?? true;
+  const subscribe = options.subscribe;
+  const { unread } = useInboxState(store);
+
+  useEffect(() => {
+    if (!enabled) return;
+    store.refreshBadge();
+    const unsubscribe = subscribe?.(() => store.invalidate());
+    // A live subscription relaxes the poll to the reconcile interval; without
+    // one it stays the 60 s poll.
+    const interval = setInterval(
+      () => store.refreshBadge(),
+      subscribe ? BADGE_RECONCILE_MS : BADGE_POLL_MS,
+    );
+    const onFocus = (): void => store.refreshBadge();
+    globalThis.addEventListener?.('focus', onFocus);
+    return () => {
+      clearInterval(interval);
+      globalThis.removeEventListener?.('focus', onFocus);
+      unsubscribe?.();
+    };
+  }, [store, enabled, subscribe]);
+
+  return enabled ? unread : 0;
+}
+
+/** The panel's list — only fetches while the panel is open. */
+export function useInboxList(store: InboxStore, open: boolean): InboxState {
+  const state = useInboxState(store);
+  useEffect(() => {
+    if (open) store.open();
+  }, [store, open]);
+  return state;
+}

package/src/react/inbox-state.ts

@@ -0,0 +1,216 @@
+import type { InboxNotification } from '../wire';
+
+import type { NotificationsApiClient } from './api';
+
+/**
+ * The inbox's client state, as ONE store shared by the bell and the panel.
+ *
+ * They have to share it: marking a row read in the panel must move the badge in
+ * the same tick, and an arrival must add a row to the list AND to the count.
+ * future-pay got that for free from a react-query cache the host had already
+ * mounted; a published package cannot assume one — a query client is a host
+ * decision, and requiring a particular one (or a particular version of one) is
+ * the kind of dependency that keeps a package out of a host that made the other
+ * choice. So the sharing is explicit and dependency-free: one subscribable
+ * store, read through `useSyncExternalStore`.
+ *
+ * Optimistic on every write, with invalidate-on-error: the badge and the list
+ * update instantly, and a failed write refetches the server truth rather than
+ * leaving the screen asserting something the database does not say.
+ */
+
+export const PAGE_SIZE = 20;
+
+/** The badge's poll while nothing is pushing to us. */
+export const BADGE_POLL_MS = 60_000;
+
+/**
+ * The badge's interval while a realtime connection is live.
+ *
+ * Five minutes, not "never": this is the reconcile that catches an event the bus
+ * dropped, and it costs one COUNT per open tab per five minutes. Deliberately
+ * far slower than an operational screen's — a bell badge is ambient, and the
+ * arrival that matters is pushed within milliseconds anyway. The poll does NOT
+ * stop, which is the standing contract: a dropped event must cost latency and
+ * never correctness.
+ */
+export const BADGE_RECONCILE_MS = 300_000;
+
+export type InboxListStatus = 'idle' | 'pending' | 'ready' | 'error';
+
+export interface InboxState {
+  unread: number;
+  items: InboxNotification[];
+  status: InboxListStatus;
+  /** A cursor means there is another page. */
+  nextCursor: string | null;
+  loadingMore: boolean;
+}
+
+export interface InboxStore {
+  getState(): InboxState;
+  subscribe(listener: () => void): () => void;
+  /** Load the first page (idempotent while one is in flight). */
+  open(): void;
+  /** Refetch the badge count. */
+  refreshBadge(): void;
+  /** Refetch both — what a realtime hint or a failed write triggers. */
+  invalidate(): void;
+  loadMore(): void;
+  markRead(ids: readonly string[]): void;
+  markAllRead(): void;
+  remove(id: string): void;
+}
+
+const EMPTY: InboxState = {
+  unread: 0,
+  items: [],
+  status: 'idle',
+  nextCursor: null,
+  loadingMore: false,
+};
+
+/** The mutable cell the functions below share, so each one stays small. */
+interface Cell {
+  state: InboxState;
+  listeners: Set<() => void>;
+  /** Fences a stale reload: a newer one must always win. */
+  request: number;
+}
+
+function patch(cell: Cell, next: Partial<InboxState>): void {
+  cell.state = { ...cell.state, ...next };
+  for (const listener of cell.listeners) listener();
+}
+
+/** Refetch the badge count. The number is always one the server just gave us. */
+function refreshBadge(cell: Cell, api: NotificationsApiClient): void {
+  void api
+    .unreadCount()
+    .then((unread) => patch(cell, { unread }))
+    .catch(() => undefined);
+}
+
+/**
+ * Reload page one, discarding whatever the optimistic path had produced.
+ * `request` fences it: a reload that started before a newer one must not land
+ * after it and reinstate stale rows.
+ */
+function reloadList(cell: Cell, api: NotificationsApiClient): void {
+  const token = (cell.request += 1);
+  patch(cell, { status: cell.state.items.length > 0 ? cell.state.status : 'pending' });
+  void api
+    .listNotifications({ limit: PAGE_SIZE })
+    .then((page) => {
+      if (token !== cell.request) return;
+      patch(cell, { items: page.items, nextCursor: page.nextCursor, status: 'ready' });
+    })
+    .catch(() => {
+      if (token !== cell.request) return;
+      patch(cell, { status: 'error' });
+    });
+}
+
+function invalidate(cell: Cell, api: NotificationsApiClient): void {
+  refreshBadge(cell, api);
+  if (cell.state.status !== 'idle') reloadList(cell, api);
+}
+
+/** Apply an optimistic edit; on failure, take the server's word instead. */
+function write(
+  cell: Cell,
+  api: NotificationsApiClient,
+  apply: () => void,
+  send: () => Promise<{ ok: boolean }>,
+): void {
+  apply();
+  void send()
+    .then((result) => {
+      if (!result.ok) invalidate(cell, api);
+    })
+    .catch(() => invalidate(cell, api));
+}
+
+function bumpUnread(cell: Cell, delta: number): void {
+  patch(cell, { unread: Math.max(0, cell.state.unread + delta) });
+}
+
+function loadMore(cell: Cell, api: NotificationsApiClient): void {
+  const cursor = cell.state.nextCursor;
+  if (!cursor || cell.state.loadingMore) return;
+  patch(cell, { loadingMore: true });
+  void api
+    .listNotifications({ cursor, limit: PAGE_SIZE })
+    .then((page) => {
+      patch(cell, {
+        items: [...cell.state.items, ...page.items],
+        nextCursor: page.nextCursor,
+        loadingMore: false,
+      });
+    })
+    .catch(() => patch(cell, { loadingMore: false }));
+}
+
+function markRead(cell: Cell, api: NotificationsApiClient, ids: readonly string[]): void {
+  const readAt = new Date().toISOString();
+  let flipped = 0;
+  const items = cell.state.items.map((item) => {
+    if (!ids.includes(item.id) || item.readAt !== null) return item;
+    flipped += 1;
+    return { ...item, readAt };
+  });
+  if (flipped === 0) return;
+  write(
+    cell,
+    api,
+    () => {
+      patch(cell, { items });
+      bumpUnread(cell, -flipped);
+    },
+    () => api.markRead(ids),
+  );
+}
+
+function remove(cell: Cell, api: NotificationsApiClient, id: string): void {
+  const target = cell.state.items.find((item) => item.id === id);
+  if (!target) return;
+  const items = cell.state.items.filter((item) => item.id !== id);
+  write(
+    cell,
+    api,
+    () => {
+      patch(cell, { items });
+      if (target.readAt === null) bumpUnread(cell, -1);
+    },
+    () => api.remove([id]),
+  );
+}
+
+export function createInboxStore(api: NotificationsApiClient): InboxStore {
+  const cell: Cell = { state: EMPTY, listeners: new Set(), request: 0 };
+  return {
+    getState: () => cell.state,
+    subscribe(listener) {
+      cell.listeners.add(listener);
+      return () => cell.listeners.delete(listener);
+    },
+    open() {
+      if (cell.state.status === 'idle') reloadList(cell, api);
+    },
+    refreshBadge: () => refreshBadge(cell, api),
+    invalidate: () => invalidate(cell, api),
+    loadMore: () => loadMore(cell, api),
+    markRead: (ids) => markRead(cell, api, ids),
+    markAllRead() {
+      const readAt = new Date().toISOString();
+      const items = cell.state.items.map((item) => ({ ...item, readAt: item.readAt ?? readAt }));
+      write(
+        cell,
+        api,
+        () => patch(cell, { items, unread: 0 }),
+        () => api.markAllRead(),
+      );
+    },
+    remove: (id) => remove(cell, api, id),
+  };
+}

package/src/react/index.ts

@@ -0,0 +1,61 @@
+/**
+ * `@12-apps/notifications/react` — the frontend half (12-15).
+ *
+ * One factory, `createWebNotifications({ apiBase })`, and everything it returns
+ * is already bound to one shared store and one copy table. The individual
+ * pieces are exported too, for a host composing its own chrome — but a host that
+ * only wants the feature needs the factory and nothing else.
+ */
+
+export {
+  createWebNotifications,
+  type NotificationsWebConfig,
+  type WebNotifications,
+} from './create-web-notifications';
+
+export { BellIcon } from './bell-icon';
+export type { BellButtonProps } from './bell-button';
+export type { NotificationsPanelProps } from './panel';
+export type { PreferencesScreenProps } from './preferences-screen';
+export type { WebPushPlatformHint, WebPushSetupConfig } from './web-push-setup';
+
+export {
+  createNotificationsApiClient,
+  type NotificationsApiClient,
+  type PreferencesPayload,
+  type PushRegistrationPayload,
+} from './api';
+
+export {
+  BADGE_POLL_MS,
+  BADGE_RECONCILE_MS,
+  PAGE_SIZE,
+  createInboxStore,
+  type InboxListStatus,
+  type InboxState,
+  type InboxStore,
+} from './inbox-state';
+
+export {
+  useInboxList,
+  useInboxState,
+  useUnreadCount,
+  type NotificationsSubscribe,
+} from './hooks';
+
+export { relativeTime } from './relative-time';
+
+export {
+  NotificationsHttpError,
+  httpNotificationsTransport,
+  type NotificationsResult,
+  type NotificationsTransport,
+} from './transport';
+
+export {
+  disableWebPush,
+  enableWebPush,
+  getExistingPushSubscription,
+  pushSupported,
+  type PushSetupResult,
+} from './web-push-client';

package/src/react/panel.tsx

@@ -0,0 +1,181 @@
+/**
+ * The notification-centre slide-over: newest-first list with unread styling,
+ * per-item open (marks read + deep-links), soft delete, mark-all, empty /
+ * loading / error states and a "load more" cursor pager.
+ *
+ * Rendering is app-agnostic — the host passes `onNavigate` (its router's
+ * navigate) for deep links. Without one a link is simply not followed, which is
+ * what lets the panel mount in a host that has no router at all.
+ */
+import { useCallback, type JSX } from 'react';
+
+import { EmptyState } from '@12-apps/ui/data-display/EmptyState';
+import { LoadingState } from '@12-apps/ui/data-display/LoadingState';
+import { Button } from '@12-apps/ui/form/Button';
+import { Drawer, DrawerContent, DrawerHeader } from '@12-apps/ui/layout/Drawer';
+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 { 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 { NotificationRow } from './row';
+
+interface PanelBodyProps {
+  state: InboxState;
+  messages: NotificationMessages;
+  onRetry: () => void;
+  onLoadMore: () => void;
+  onOpen: (notification: InboxNotification) => void;
+  onDelete: (id: string) => void;
+}
+
+/** The scrollable panel body: loading / error / empty / the list + pager. */
+function PanelBody({
+  state,
+  messages,
+  onRetry,
+  onLoadMore,
+  onOpen,
+  onDelete,
+}: PanelBodyProps): JSX.Element {
+  if (state.status === 'pending' || state.status === 'idle') {
+    return (
+      <LoadingState
+        variant="spinner"
+        message={messages.loading}
+        size="md"
+        dataTestId="notifications-loading"
+      />
+    );
+  }
+  if (state.status === 'error') {
+    return (
+      <EmptyState
+        variant="minimal"
+        title={messages.loadFailedTitle}
+        description={messages.loadFailedBody}
+        onRefresh={onRetry}
+        refreshLabel={messages.retry}
+        dataTestId="notifications-error"
+      />
+    );
+  }
+  if (state.items.length === 0) {
+    return (
+      <EmptyState
+        variant="illustrated"
+        illustration={<BellIcon size={44} dim />}
+        title={messages.emptyTitle}
+        description={messages.emptyBody}
+        dataTestId="notifications-empty"
+      />
+    );
+  }
+  return (
+    <Box>
+      {state.items.map((notification) => (
+        <NotificationRow
+          key={notification.id}
+          notification={notification}
+          messages={messages}
+          onOpen={onOpen}
+          onDelete={onDelete}
+        />
+      ))}
+      {state.nextCursor ? (
+        <Box sx={{ display: 'flex', justifyContent: 'center', py: 1.5 }}>
+          <Button
+            variant="outline"
+            color="neutral"
+            size="sm"
+            disabled={state.loadingMore}
+            onClick={onLoadMore}
+            dataTestId="notifications-load-more"
+          >
+            {state.loadingMore ? messages.loadingMore : messages.loadMore}
+          </Button>
+        </Box>
+      ) : null}
+    </Box>
+  );
+}
+
+export interface NotificationsPanelProps {
+  open: boolean;
+  onClose: () => void;
+  /** Navigate to a notification's in-app link (the host's router). */
+  onNavigate?: (link: string) => void;
+}
+
+export function NotificationsPanel({
+  open,
+  onClose,
+  onNavigate,
+  store,
+  messages,
+}: NotificationsPanelProps & {
+  store: InboxStore;
+  messages: NotificationMessages;
+}): 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
+  // hand the callback a null theme and throw. A published component must render
+  // in a host that has not wrapped it yet.
+  const theme = useTheme();
+  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 hasUnread = state.items.some((item) => item.readAt === null);
+
+  return (
+    <Drawer
+      open={open}
+      onClose={onClose}
+      anchor="right"
+      variant="right"
+      width={isMobile ? '100vw' : 400}
+      dataTestId="notifications-panel"
+    >
+      <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)}
+        />
+      </DrawerContent>
+    </Drawer>
+  );
+}