@12-apps/notifications 4.7.1 → 4.9.0

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),
+  );
+}

package/src/email/previews/routes.ts

@@ -0,0 +1,111 @@
+import {
+  createEmailPreviews,
+  type ApiEmailPreviews,
+  type EmailPreviewsConfig,
+} from './catalog';
+
+/**
+ * The two endpoints over the catalogue, as descriptors.
+ *
+ * `GET /` answers the list — one row per message, a subject each, no rendered
+ * bytes — and `GET /:id` answers one whole document. Two calls rather than one
+ * because a rendered mail is 6-10 KB and a catalogue of twenty would be twenty
+ * times that on a screen where the operator reads one.
+ *
+ * ## Nothing here can send anything
+ *
+ * The surface holds no driver, no transport and no address. `render` is pure by
+ * the contract `EmailPreviewMessage` states, so the one mistake a preview
+ * surface must be incapable of — putting a sample in somebody's inbox — is not
+ * reachable from this code at all rather than merely not done.
+ *
+ * ## The gate is the HOST's — but the POSTURE is declared here
+ *
+ * Every route carries `kind: 'authenticated'`, the wiring contract's own word
+ * for "behind the host's session resolution and its RBAC". A package cannot
+ * know WHICH gate a host uses, and this one does not try: it names no
+ * permission id, because the ids belong to whichever host mounts it.
+ *
+ * What it must not do is stay silent. `public` is the contract's word for
+ * anonymous-by-design, and the contract's DEFAULT is `authenticated` — so a
+ * descriptor that declared nothing would still read as authenticated to a
+ * host's gates, while saying nothing to the person adopting it. This surface
+ * publishes a host's whole transactional-mail inventory and the exact wording
+ * and link shape of its verification and password-reset mails, which is the
+ * reference somebody writing a convincing phishing mail would want. That is
+ * worth one word in the descriptor rather than a sentence in a document.
+ *
+ * `ADOPTING.md` states the obligation in prose as well, because a host still
+ * has to supply the gate this word only asks for.
+ *
+ * An unknown LOCALE is a 400 rather than a silent fall back to the default.
+ * This is a diagnostic surface: quietly answering the default language to
+ * `?locale=es-AR` looks exactly like a product with no Spanish, which is the
+ * question the operator was asking.
+ */
+
+/** Twin of the wiring contract's request; no import, so this package stays liftable. */
+export interface EmailPreviewRequest {
+  /** The path segment after the mount, when the caller asked for one message. */
+  params?: Readonly<Record<string, string | undefined>>;
+  query?: Readonly<Record<string, string | undefined>>;
+}
+
+export interface EmailPreviewResponse {
+  status: number;
+  body: unknown;
+}
+
+export interface EmailPreviewRoute {
+  method: 'GET';
+  path: string;
+  /**
+   * The wiring contract's `WireRouteKind`, restated. Always `authenticated`
+   * here: the host supplies the gate, and this is the descriptor asking for
+   * one — see the docblock above for why silence was not an option.
+   */
+  kind: 'authenticated';
+  handle(request: EmailPreviewRequest): Promise<EmailPreviewResponse>;
+}
+
+const ok = (body: unknown): EmailPreviewResponse => ({ status: 200, body: { data: body } });
+const fail = (status: number, error: string): EmailPreviewResponse => ({ status, body: { error } });
+
+/** `undefined` passes through as "not asked"; anything unknown is refused. */
+function readLocale(
+  previews: ApiEmailPreviews,
+  request: EmailPreviewRequest,
+): { ok: true; locale?: string } | { ok: false; tag: string } {
+  const tag = request.query?.locale;
+  if (tag === undefined || tag === '') return { ok: true };
+  return previews.supportsLocale(tag) ? { ok: true, locale: tag } : { ok: false, tag };
+}
+
+export function emailPreviewRoutes(config: EmailPreviewsConfig): EmailPreviewRoute[] {
+  const previews = createEmailPreviews(config);
+
+  return [
+    {
+      method: 'GET',
+      path: '/',
+      kind: 'authenticated',
+      handle: (request) => {
+        const locale = readLocale(previews, request);
+        if (!locale.ok) return Promise.resolve(fail(400, `Unknown locale "${locale.tag}".`));
+        return Promise.resolve(ok(previews.index(locale.locale)));
+      },
+    },
+    {
+      method: 'GET',
+      path: '/:id',
+      kind: 'authenticated',
+      handle: (request) => {
+        const locale = readLocale(previews, request);
+        if (!locale.ok) return Promise.resolve(fail(400, `Unknown locale "${locale.tag}".`));
+        const id = request.params?.id ?? '';
+        const detail = previews.render(id, locale.locale);
+        return Promise.resolve(detail ? ok(detail) : fail(404, `No e-mail preview named "${id}".`));
+      },
+    },
+  ];
+}