@12-apps/notifications 4.7.1 → 4.9.0

package/src/email/previews/react/loadable.tsx

@@ -0,0 +1,83 @@
+import type { JSX } from 'react';
+import { useEffect, useState } from 'react';
+
+import { Alert } from '@12-apps/ui/data-display/Alert';
+import { Button } from '@12-apps/ui/form/Button';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { EmailPreviewScreenCopy } from './copy';
+
+/**
+ * The screen's async plumbing: one hook, and the state it cannot render itself.
+ *
+ * Its own module because it is the half with no opinion about e-mail. What is
+ * left in `preview-screen.tsx` is composition — which columns, which panes,
+ * what the URL says — and this is the machinery underneath all of it.
+ *
+ * `keepPrevious` is the load-bearing option and its docblock says why: a
+ * consumer that renders children only while `data` is non-null gets those
+ * children UNMOUNTED by a blanking reload, which silently discards whatever
+ * state they held.
+ */
+
+/** A load that can fail, in the two states a screen has to render. */
+interface Loadable<T> {
+  data: T | null;
+  error: string | null;
+}
+
+export function useLoadable<T>(
+  load: () => Promise<T>,
+  options: { keepPrevious?: boolean } = {},
+): Loadable<T> & { reload: () => void } {
+  const [state, setState] = useState<Loadable<T>>({ data: null, error: null });
+  const [nonce, setNonce] = useState(0);
+  const { keepPrevious = false } = options;
+  useEffect(() => {
+    let live = true;
+    // `keepPrevious` holds the last good answer on screen while the next one is
+    // in flight, and it is not a nicety. The consumer of this hook renders its
+    // children only while `data` is non-null, so blanking here UNMOUNTS them —
+    // taking the filter text, the open tab and the chosen width with it. On a
+    // fast connection the refetch lands before anyone notices; on a slow one
+    // the operator watches what they just typed disappear.
+    setState((previous) => (keepPrevious ? { ...previous, error: null } : { data: null, error: null }));
+    load()
+      .then((data) => live && setState({ data, error: null }))
+      .catch(
+        (error: unknown) =>
+          live &&
+          setState({ data: null, error: error instanceof Error ? error.message : String(error) }),
+      );
+    return () => {
+      // A language switched twice in a second must not let the FIRST answer
+      // land last — the screen would show a document the operator did not ask
+      // for, with the toggle disagreeing.
+      live = false;
+    };
+  }, [load, nonce]);
+  return { ...state, reload: () => setNonce((n) => n + 1) };
+}
+
+export function Failure({
+  message,
+  copy,
+  onRetry,
+}: {
+  message: string;
+  copy: EmailPreviewScreenCopy;
+  onRetry: () => void;
+}): JSX.Element {
+  return (
+    <Box data-testid="email-preview-error" sx={{ display: 'flex', flexDirection: 'column', gap: 1, alignItems: 'flex-start' }}>
+      <Alert severity="error">
+        <Text as="p" size="sm">{copy.loadError}</Text>
+        <Text as="p" size="sm">{message}</Text>
+      </Alert>
+      <Button size="sm" variant="outline" onClick={onRetry}>
+        {copy.retry}
+      </Button>
+    </Box>
+  );
+}

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