@12-apps/notifications 4.8.0 → 4.10.0

package/src/email/previews/react/message-list.tsx

@@ -0,0 +1,133 @@
+import type { JSX } from 'react';
+
+import { Chip } from '@12-apps/ui/data-display/Chip';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { EmailPreviewRow } from '../catalog';
+
+import type { EmailPreviewScreenCopy } from './copy';
+
+/**
+ * The catalogue, grouped by the PACKAGE that owns each message.
+ *
+ * Grouping by owner rather than by family is the whole answer to "which parts
+ * of this system send mail": the section headers ARE that list, derived from
+ * the rows the surface sent rather than written down anywhere, so a package
+ * that starts sending mail appears the day it does.
+ *
+ * The family stays visible as a chip on each row, because it is the other
+ * question an operator asks — and one owner can span two families.
+ */
+
+interface OwnerGroup {
+  owner: string;
+  rows: EmailPreviewRow[];
+}
+
+/** Group in FIRST-SEEN order, so the list does not reshuffle between renders. */
+function groupByOwner(rows: readonly EmailPreviewRow[]): OwnerGroup[] {
+  const groups = new Map<string, EmailPreviewRow[]>();
+  for (const row of rows) {
+    const bucket = groups.get(row.owner);
+    if (bucket) bucket.push(row);
+    else groups.set(row.owner, [row]);
+  }
+  return [...groups].map(([owner, ownerRows]) => ({ owner, rows: ownerRows }));
+}
+
+/** Does this row match what was typed? Subject, key, owner and family all count. */
+export function matchesFilter(row: EmailPreviewRow, filter: string): boolean {
+  const needle = filter.trim().toLowerCase();
+  if (needle === '') return true;
+  return [row.subject, row.key, row.owner, row.family].some((field) =>
+    field.toLowerCase().includes(needle),
+  );
+}
+
+function MessageRow({
+  row,
+  selected,
+  onSelect,
+}: {
+  row: EmailPreviewRow;
+  selected: boolean;
+  onSelect: (id: string) => void;
+}): JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      data-testid={`email-preview-row-${row.id}`}
+      aria-current={selected}
+      onClick={() => onSelect(row.id)}
+      sx={{
+        appearance: 'none',
+        textAlign: 'left',
+        width: '100%',
+        cursor: 'pointer',
+        border: '1px solid',
+        borderColor: selected ? 'primary.main' : 'divider',
+        background: selected ? 'action.selected' : 'background.paper',
+        borderRadius: 1.5,
+        p: 1.25,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 0.5,
+      }}
+    >
+      <Text as="span" size="sm" weight="medium">
+        {row.subject}
+      </Text>
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+        <Chip label={row.family} size="sm" variant="outlined" color="neutral" />
+        <Text as="span" size="xs" color="secondary">
+          {row.key}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+export function MessageList({
+  rows,
+  selectedId,
+  copy,
+  onSelect,
+}: {
+  rows: readonly EmailPreviewRow[];
+  selectedId: string | null;
+  copy: EmailPreviewScreenCopy;
+  onSelect: (id: string) => void;
+}): JSX.Element {
+  if (rows.length === 0) {
+    return (
+      <Text as="p" size="sm" color="secondary" data-testid="email-preview-no-matches">
+        {copy.noMatches}
+      </Text>
+    );
+  }
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      {groupByOwner(rows).map((group) => (
+        <Box
+          key={group.owner}
+          data-testid={`email-preview-owner-${group.owner}`}
+          sx={{ display: 'flex', flexDirection: 'column', gap: 0.75 }}
+        >
+          <Text as="p" size="xs" weight="medium" color="secondary">
+            {group.owner}
+          </Text>
+          {group.rows.map((row) => (
+            <MessageRow
+              key={row.id}
+              row={row}
+              selected={row.id === selectedId}
+              onSelect={onSelect}
+            />
+          ))}
+        </Box>
+      ))}
+    </Box>
+  );
+}

package/src/email/previews/react/message-view.tsx

@@ -0,0 +1,167 @@
+import type { JSX } from 'react';
+
+import { ToggleGroup } from '@12-apps/ui/form/ToggleGroup';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { EmailPreviewDetail } from '../catalog';
+
+import type { EmailPreviewScreenCopy } from './copy';
+
+/**
+ * One rendered message, in the three ways it is worth looking at.
+ *
+ * - **HTML** — what most people will see, in a sandboxed frame at either of the
+ *   two widths that matter. A phone is not a nice-to-have: more than half of
+ *   transactional mail is opened on one, and the 600px card is exactly the
+ *   thing that either survives that or does not.
+ * - **Text** — the plain-text twin. Worth its own tab because it is what a spam
+ *   filter scores, what a watch shows, and what a screen reader in plain-text
+ *   mode reads — and because it is the half nobody ever looks at, which is how
+ *   it drifts out of step with the HTML.
+ * - **Source** — the markup itself, for the moment somebody is debugging why a
+ *   client rendered it oddly.
+ *
+ * ## Why an iframe, and why sandboxed
+ *
+ * The mail is a whole document with its own `<body>` background, and rendering
+ * that inside the console's DOM would both break the mail (the console's CSS
+ * reaches it) and break the console (the mail's body styles reach the page). A
+ * frame is the only honest preview.
+ *
+ * `sandbox=""` — no scripts, no forms, no top-level navigation. These documents
+ * come from the host's own renderer and carry no script, so this is less a
+ * containment measure than a statement that the preview is INERT: a click on a
+ * CTA inside a previewed mail must never navigate the operator anywhere, least
+ * of all to a sample verification link.
+ */
+
+/** The two widths the HTML view renders at. */
+export type PreviewWidth = 'desktop' | 'mobile';
+
+/** Which of the three views is showing. */
+export type PreviewTab = 'html' | 'text' | 'source';
+
+/** A phone. 390px is a common iPhone CSS width, and among the narrowest. */
+const MOBILE_WIDTH = 390;
+
+function Monospace({ children, testId }: { children: string; testId: string }): JSX.Element {
+  return (
+    <Box
+      component="pre"
+      data-testid={testId}
+      sx={{
+        m: 0,
+        p: 2,
+        borderRadius: 1.5,
+        border: '1px solid',
+        borderColor: 'divider',
+        background: 'background.default',
+        fontSize: 13,
+        lineHeight: 1.6,
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-word',
+        maxHeight: 720,
+        overflow: 'auto',
+      }}
+    >
+      {children}
+    </Box>
+  );
+}
+
+function HtmlFrame({
+  detail,
+  width,
+  title,
+}: {
+  detail: EmailPreviewDetail;
+  width: PreviewWidth;
+  title: string;
+}): JSX.Element {
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        justifyContent: 'center',
+        borderRadius: 1.5,
+        border: '1px solid',
+        borderColor: 'divider',
+        overflow: 'hidden',
+      }}
+    >
+      <Box
+        component="iframe"
+        data-testid="email-preview-frame"
+        title={title}
+        srcDoc={detail.html}
+        sandbox=""
+        sx={{
+          border: 0,
+          width: width === 'mobile' ? MOBILE_WIDTH : '100%',
+          height: 760,
+          background: '#fff',
+        }}
+      />
+    </Box>
+  );
+}
+
+interface MessageViewProps {
+  detail: EmailPreviewDetail;
+  copy: EmailPreviewScreenCopy;
+  tab: PreviewTab;
+  width: PreviewWidth;
+  onTabChange: (tab: PreviewTab) => void;
+  onWidthChange: (width: PreviewWidth) => void;
+}
+
+export function MessageView(props: MessageViewProps): JSX.Element {
+  const { detail, copy, tab, width, onTabChange, onWidthChange } = props;
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1.5 }} data-testid="email-preview-view">
+      <Box>
+        <Text as="p" size="xs" color="secondary">
+          {copy.subjectLabel}
+        </Text>
+        <Text as="p" size="md" weight="medium" data-testid="email-preview-subject">
+          {detail.subject}
+        </Text>
+      </Box>
+      <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 1, alignItems: 'center' }}>
+        <ToggleGroup
+          dataTestId="email-preview-tabs"
+          exclusive
+          value={tab}
+          size="sm"
+          options={[
+            { value: 'html', label: copy.tabHtml },
+            { value: 'text', label: copy.tabText },
+            { value: 'source', label: copy.tabSource },
+          ]}
+          onChange={(_event, value) => {
+            if (value) onTabChange(value as PreviewTab);
+          }}
+        />
+        {tab === 'html' ? (
+          <ToggleGroup
+            dataTestId="email-preview-width"
+            exclusive
+            value={width}
+            size="sm"
+            options={[
+              { value: 'desktop', label: copy.widthDesktop },
+              { value: 'mobile', label: copy.widthMobile },
+            ]}
+            onChange={(_event, value) => {
+              if (value) onWidthChange(value as PreviewWidth);
+            }}
+          />
+        ) : null}
+      </Box>
+      {tab === 'html' ? <HtmlFrame detail={detail} width={width} title={copy.frameTitle} /> : null}
+      {tab === 'text' ? <Monospace testId="email-preview-text">{detail.text}</Monospace> : null}
+      {tab === 'source' ? <Monospace testId="email-preview-source">{detail.html}</Monospace> : null}
+    </Box>
+  );
+}

package/src/email/previews/react/preview-screen.tsx

@@ -0,0 +1,342 @@
+import { useCallback, useMemo, useState, type JSX } from 'react';
+
+import { Alert } from '@12-apps/ui/data-display/Alert';
+import { Input } from '@12-apps/ui/form/Input';
+import { ToggleGroup } from '@12-apps/ui/form/ToggleGroup';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Heading } from '@12-apps/ui/typography/Heading';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { EmailPreviewCoverage, EmailPreviewDetail, EmailPreviewIndex } from '../catalog';
+
+import type { EmailPreviewScreenCopy } from './copy';
+import { Failure, useLoadable } from './loadable';
+import { MessageList, matchesFilter } from './message-list';
+import { MessageView, type PreviewTab, type PreviewWidth } from './message-view';
+import { fetchEmailPreview, fetchEmailPreviewIndex } from './transport';
+
+/**
+ * The operator screen over the `./email/previews` catalogue.
+ *
+ * ## What a host supplies, and what it does not
+ *
+ * `apiBase` — where the routes are mounted — and `copy`, by name. Nothing else:
+ * the owners, the languages, the messages and their subjects all arrive from
+ * the surface, because they are facts about the host's own mail that no prop
+ * could usefully restate.
+ *
+ * ## The selection lives in the URL, without a router
+ *
+ * `?id=` and `?locale=`, read and written through `history.replaceState`. A
+ * link to one mail in one language is the actual workflow this screen serves —
+ * "look at what the reset mail says now" — and local state would make every
+ * such conversation a set of instructions instead of a link.
+ *
+ * Deliberately NOT a router integration: this package cannot know whether a
+ * host runs react-router, TanStack Router or a framework's own, and a screen
+ * that imported one would be unmountable in the other two. `replaceState` is
+ * the one API all of them are built on, and `replace` rather than `push` so
+ * browsing twenty mails is not twenty back-button steps.
+ */
+
+export interface EmailPreviewScreenConfig {
+  /** Where the routes are mounted, e.g. `/api/platform/email-previews`. */
+  readonly apiBase: string;
+  /** The screen's words. REQUIRED — see `./copy`. */
+  readonly copy: EmailPreviewScreenCopy;
+}
+
+/** Read one search param without assuming a router owns the URL. */
+function searchParam(name: string): string | null {
+  if (typeof window === 'undefined') return null;
+  return new URLSearchParams(window.location.search).get(name);
+}
+
+/**
+ * Patch the query string in place, keeping everything else about the URL.
+ *
+ * The HASH is carried over deliberately, and it is not defensive coding: a host
+ * that routes on `location.hash` — the consumer harness does, and so does any
+ * SPA served from a static file — would otherwise be navigated off this screen
+ * by its own locale switch, because rebuilding the URL from `pathname` alone
+ * silently drops the fragment that says which page this is.
+ *
+ * `replaceState` rather than `pushState` for the reason the screen exists:
+ * browsing twenty messages is one place to come back from, not twenty
+ * back-button steps.
+ */
+function patchSearch(patch: Record<string, string>): void {
+  if (typeof window === 'undefined') return;
+  const next = new URLSearchParams(window.location.search);
+  for (const [key, value] of Object.entries(patch)) next.set(key, value);
+  const { pathname, hash } = window.location;
+  window.history.replaceState({}, '', `${pathname}?${next.toString()}${hash}`);
+}
+
+/** The surface's honest report about what it cannot show. */
+function CoverageNotice({
+  coverage,
+  copy,
+}: {
+  coverage: EmailPreviewCoverage;
+  copy: EmailPreviewScreenCopy;
+}): JSX.Element | null {
+  if (coverage.missing.length === 0 && coverage.orphan.length === 0) return null;
+  return (
+    <Alert severity="warning" data-testid="email-preview-coverage">
+      <Text as="p" size="sm" weight="medium">
+        {copy.coverageTitle}
+      </Text>
+      {coverage.missing.length > 0 ? (
+        <Text as="p" size="sm">
+          {copy.missingSamples(coverage.missing.join(', '))}
+        </Text>
+      ) : null}
+      {coverage.orphan.length > 0 ? (
+        <Text as="p" size="sm">
+          {copy.orphanSamples(coverage.orphan.join(', '))}
+        </Text>
+      ) : null}
+    </Alert>
+  );
+}
+
+/** The right-hand pane: the selected message, or an invitation to pick one. */
+function PreviewPane({
+  apiBase,
+  id,
+  locale,
+  copy,
+  tab,
+  width,
+  onTabChange,
+  onWidthChange,
+}: {
+  apiBase: string;
+  id: string | null;
+  locale: string;
+  copy: EmailPreviewScreenCopy;
+  tab: PreviewTab;
+  width: PreviewWidth;
+  onTabChange: (tab: PreviewTab) => void;
+  onWidthChange: (width: PreviewWidth) => void;
+}): JSX.Element {
+  const load = useCallback(
+    () =>
+      id === null
+        ? Promise.resolve(null as EmailPreviewDetail | null)
+        : fetchEmailPreview(apiBase, id, locale),
+    [apiBase, id, locale],
+  );
+  const detail = useLoadable(load);
+
+  if (id === null) {
+    return (
+      <Text as="p" size="sm" color="secondary" data-testid="email-preview-empty">
+        {copy.pickOne}
+      </Text>
+    );
+  }
+  if (detail.error !== null) {
+    return <Failure message={detail.error} copy={copy} onRetry={detail.reload} />;
+  }
+  if (detail.data === null) {
+    return (
+      <Text as="p" size="sm" color="secondary" data-testid="email-preview-detail-loading">
+        {copy.loading}
+      </Text>
+    );
+  }
+  return (
+    <MessageView
+      detail={detail.data}
+      copy={copy}
+      tab={tab}
+      width={width}
+      onTabChange={onTabChange}
+      onWidthChange={onWidthChange}
+    />
+  );
+}
+
+/** The left column: the filter, and the rows under their owners. */
+function CatalogueColumn({
+  index,
+  copy,
+  selectedId,
+  onSelect,
+}: {
+  index: EmailPreviewIndex;
+  copy: EmailPreviewScreenCopy;
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+}): JSX.Element {
+  const [filter, setFilter] = useState('');
+  const visible = useMemo(
+    () => index.items.filter((row) => matchesFilter(row, filter)),
+    [index.items, filter],
+  );
+  return (
+    /*
+      The list owns its OWN scroll rather than growing the page.
+
+      A host's console is typically a fixed-viewport shell whose centre column
+      scrolls, and a twenty-mail catalogue then scrolls the preview frame off
+      the screen — the two things this screen exists to show side by side
+      cannot both be on it. `sticky` keeps the list put while the frame is
+      read; the height is the viewport minus the chrome above it, so the column
+      ends where the window does rather than at an arbitrary pixel count.
+    */
+    <Box
+      sx={{
+        width: 320,
+        flexShrink: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 1.5,
+        position: 'sticky',
+        top: 0,
+        maxHeight: 'calc(100dvh - 220px)',
+        minHeight: 240,
+      }}
+    >
+      <Input
+        label={copy.searchLabel}
+        placeholder={copy.searchPlaceholder}
+        value={filter}
+        data-testid="email-preview-filter"
+        onChange={(event) => setFilter(event.target.value)}
+        fullWidth
+      />
+      {/* Only the ROWS scroll — the filter field stays reachable. */}
+      <Box sx={{ overflowY: 'auto', flex: 1, pr: 0.5 }}>
+        <MessageList rows={visible} selectedId={selectedId} copy={copy} onSelect={onSelect} />
+      </Box>
+    </Box>
+  );
+}
+
+/** The catalogue and the preview, once the index has loaded. */
+function Browser({
+  apiBase,
+  index,
+  copy,
+  locale,
+  selectedId,
+  onPatch,
+}: {
+  apiBase: string;
+  index: EmailPreviewIndex;
+  copy: EmailPreviewScreenCopy;
+  locale: string;
+  selectedId: string | null;
+  onPatch: (patch: Record<string, string>) => void;
+}): JSX.Element {
+  const [tab, setTab] = useState<PreviewTab>('html');
+  const [width, setWidth] = useState<PreviewWidth>('desktop');
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <CoverageNotice coverage={index.coverage} copy={copy} />
+      <ToggleGroup
+        dataTestId="email-preview-locale"
+        exclusive
+        value={locale}
+        size="sm"
+        options={index.locales.map((tag) => ({ value: tag, label: tag }))}
+        onChange={(_event, value) => {
+          if (value) onPatch({ locale: String(value) });
+        }}
+      />
+      <Box sx={{ display: 'flex', gap: 3, alignItems: 'flex-start', flexWrap: 'wrap' }}>
+        <CatalogueColumn
+          index={index}
+          copy={copy}
+          selectedId={selectedId}
+          onSelect={(id) => onPatch({ id })}
+        />
+        <Box sx={{ flex: 1, minWidth: 360 }}>
+          <PreviewPane
+            apiBase={apiBase}
+            id={selectedId}
+            locale={locale}
+            copy={copy}
+            tab={tab}
+            width={width}
+            onTabChange={setTab}
+            onWidthChange={setWidth}
+          />
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * Build the screen. One call, one config object — the shape every factory in
+ * this estate has.
+ */
+export function createEmailPreviewScreen(config: EmailPreviewScreenConfig): {
+  page: () => JSX.Element;
+} {
+  const { apiBase, copy } = config;
+
+  function EmailPreviewsPage(): JSX.Element {
+    // The VALUE is deliberately discarded: nothing reads the counter, and the
+    // only thing it has to do is change, so React re-renders and the URL is
+    // re-read below. It used to be a dependency of the catalogue fetch, which
+    // is what made every row click refetch the list.
+    const [, setUrlNonce] = useState(0);
+    const locale = searchParam('locale') ?? '';
+    const selectedId = searchParam('id');
+    // The catalogue depends on the LANGUAGE and on nothing else. `urlNonce` is
+    // deliberately absent: it counts every URL patch, selection included, and
+    // including it here refetched the whole catalogue on each row click — for a
+    // list whose contents cannot have changed. What the click actually needs is
+    // a re-RENDER, so `selectedId` is re-read, and `setUrlNonce` already does
+    // that on its own.
+    const load = useCallback(
+      () => fetchEmailPreviewIndex(apiBase, locale),
+      [apiBase, locale],
+    );
+    const index = useLoadable(load, { keepPrevious: true });
+
+    const patch = (next: Record<string, string>): void => {
+      patchSearch(next);
+      // `replaceState` does not notify React, so the screen re-reads the URL
+      // through this counter rather than through a router's own subscription.
+      setUrlNonce((n) => n + 1);
+    };
+
+    return (
+      <Box data-testid="page-email-previews" sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+        <Box>
+          <Heading level="h2">{copy.title}</Heading>
+          <Text as="p" size="sm" color="secondary">
+            {copy.description}
+          </Text>
+        </Box>
+        {index.error !== null ? (
+          <Failure message={index.error} copy={copy} onRetry={index.reload} />
+        ) : null}
+        {index.error === null && index.data === null ? (
+          <Text as="p" size="sm" color="secondary" data-testid="email-preview-index-loading">
+            {copy.loading}
+          </Text>
+        ) : null}
+        {index.data !== null ? (
+          <Browser
+            apiBase={apiBase}
+            index={index.data}
+            copy={copy}
+            locale={index.data.locale}
+            selectedId={selectedId}
+            onPatch={patch}
+          />
+        ) : null}
+      </Box>
+    );
+  }
+
+  return { page: EmailPreviewsPage };
+}

package/src/email/previews/react/transport.ts

@@ -0,0 +1,60 @@
+import type { EmailPreviewDetail, EmailPreviewIndex } from '../catalog';
+
+/**
+ * How the screen reaches its own endpoints.
+ *
+ * Plain `fetch` rather than a data library: this package cannot know whether a
+ * host runs react-query, SWR or nothing at all, and a screen that dragged one
+ * in would put a second cache beside whichever the host already has. The two
+ * calls here are a list and a document — neither needs invalidation, retries or
+ * shared state, which is most of what a data library is for.
+ *
+ * Both unwrap the `{ data }` envelope the routes write, and both surface a
+ * non-2xx as a thrown `Error` carrying whatever the surface said, so the screen
+ * can show the operator the real refusal (an unknown locale, a 403 from the
+ * host's own gate) rather than a generic failure.
+ */
+
+/** The envelope every route in this package answers with. */
+interface Envelope<T> {
+  data?: T;
+  error?: string;
+}
+
+async function get<T>(url: string): Promise<T> {
+  const response = await fetch(url, { headers: { Accept: 'application/json' } });
+  let body: Envelope<T> = {};
+  try {
+    body = (await response.json()) as Envelope<T>;
+  } catch {
+    // A gate that refuses before the router runs may answer HTML, not JSON.
+    // Falling through to the status line below is more useful than a parse
+    // error naming a character offset.
+  }
+  if (!response.ok || body.data === undefined) {
+    throw new Error(body.error ?? `The request failed (${response.status}).`);
+  }
+  return body.data;
+}
+
+const withLocale = (base: string, locale: string): string =>
+  `${base}?locale=${encodeURIComponent(locale)}`;
+
+/** The catalogue, with every subject rendered in `locale`. */
+export function fetchEmailPreviewIndex(
+  apiBase: string,
+  locale: string,
+): Promise<EmailPreviewIndex> {
+  return get<EmailPreviewIndex>(withLocale(apiBase, locale));
+}
+
+/** One rendered message. */
+export function fetchEmailPreview(
+  apiBase: string,
+  id: string,
+  locale: string,
+): Promise<EmailPreviewDetail> {
+  return get<EmailPreviewDetail>(
+    withLocale(`${apiBase}/${encodeURIComponent(id)}`, locale),
+  );
+}