@tinvar/mail 0.0.0-stage → 0.4.1

package/src/components.js

@@ -0,0 +1,803 @@
+// The email kit: components a template is built from, each drawn twice --
+// once as the HTML a mail client lays out, once as the plain-text part --
+// by renderEmail().
+//
+// The HTML is what mail clients read reliably (MER-36.1): inline styles
+// only, layout in presentation tables, no script, no stylesheet, no web
+// font fetched, no image but those the policy allows. The text part is each
+// component's own plain form -- a heading and a blank line, a link as its
+// words and its URL -- so every link the HTML has is written out in the text
+// too (MER-36.2), which PHP checks before it sends (RenderedMail).
+//
+// Every string reaches the markup through React, which escapes it; every
+// href and src through the policy (policy.js). Nothing here holds state
+// between renders.
+
+import { createElement as h, Fragment } from 'react';
+import { ThemeContext, tones, useMailRender, useTheme } from './context.js';
+import {
+  DEFAULT_DARK_THEME,
+  MailPolicyError,
+  safeHref,
+  safeImageSrc,
+  safeTrackerSrc,
+  themeOf,
+} from './policy.js';
+
+/**
+ * Padding after the preview text, so a client's inbox line shows the preview
+ * and nothing of the body after it: zero-width non-joiners and non-breaking
+ * spaces, which clients do not collapse.
+ */
+const PREVIEW_PADDING = '\u200c\u00a0'.repeat(90);
+
+/** A table that is only layout: no borders, no spacing, read as nothing by screen readers. */
+const presentation = { role: 'presentation', width: '100%', cellPadding: 0, cellSpacing: 0, border: 0 };
+
+/** Plain text for this node, when it is plain text -- a string or number -- and null otherwise. */
+function plain(node) {
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number' || typeof node === 'bigint') return String(node);
+  return null;
+}
+
+/** A URL as the text part writes it: a mailto: link as its address alone. */
+function spelled(url) {
+  return url.replace(/^mailto:/i, '');
+}
+
+/**
+ * An <img>. Marked low priority, which mail clients ignore, because React
+ * otherwise writes a <link rel="preload"> for it into the markup -- an
+ * element no email should hold, and which PHP refuses (SafeMailHtml).
+ */
+function img(props) {
+  return h('img', { ...props, fetchPriority: 'low' });
+}
+
+/** A block of the text part: its content, then a blank line. */
+function block(...children) {
+  return h(Fragment, null, ...children, '\n\n');
+}
+
+/**
+ * The whole message: the hidden preview line, a header with the brand, the
+ * body on a card, and a footer saying why the reader got it, how to stop,
+ * and the sender's postal address (MER-36.3).
+ *
+ * `theme` is the tenant's branding, given as props for this message alone;
+ * every component under the layout reads it from the render's context.
+ * `dark` -- true for Meridian's dark palette, or colours over it -- is what
+ * a client that prefers dark draws instead (ADR 0116); without it the
+ * message is light only, as the head's color-scheme then says.
+ *
+ * `unsubscribeLabel` is the words of the footer's link: a transactional
+ * message, which no reader unsubscribes from, links to their preferences
+ * instead, and says so.
+ */
+export function Layout({
+  children,
+  preview,
+  brand,
+  logoUrl,
+  reason,
+  unsubscribeUrl,
+  unsubscribeLabel = 'Unsubscribe from these emails',
+  address,
+  theme,
+  dark,
+  lang = 'en',
+  title,
+}) {
+  const render = useMailRender();
+  const colors = themeOf(theme);
+  if (dark !== undefined && dark !== null && dark !== false) {
+    render.document.dark = themeOf(dark === true ? undefined : dark, DEFAULT_DARK_THEME);
+  }
+  if (typeof unsubscribeLabel !== 'string' || unsubscribeLabel.trim() === '') {
+    throw new MailPolicyError("The footer's unsubscribe link needs words.");
+  }
+  if (typeof brand !== 'string' || brand.trim() === '') {
+    throw new MailPolicyError('An email layout needs the brand it is from.');
+  }
+  if (typeof lang !== 'string' || !/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(lang)) {
+    throw new MailPolicyError(`'${String(lang)}' is not a language tag.`);
+  }
+  render.document.lang = lang;
+  render.document.title = typeof title === 'string' ? title : brand;
+  render.document.background = colors.background;
+
+  const unsubscribe = unsubscribeUrl === undefined || unsubscribeUrl === null ? null : unsubscribeUrl;
+
+  if (render.text) {
+    return h(
+      ThemeContext.Provider,
+      { value: colors },
+      block(brand),
+      children,
+      '\n---\n\n',
+      reason ? block('Why am I getting this? ', reason) : null,
+      unsubscribe === null
+        ? null
+        : block(unsubscribeLabel, ': ', spelled(safeHref(unsubscribe, render.policy))),
+      address ? block(address) : null,
+    );
+  }
+
+  const footerText = { color: colors.muted, fontSize: '12px', lineHeight: '18px', margin: '0 0 8px' };
+
+  return h(
+    ThemeContext.Provider,
+    { value: colors },
+    preview
+      ? h(
+          'div',
+          {
+            style: {
+              display: 'none',
+              overflow: 'hidden',
+              lineHeight: '1px',
+              opacity: 0,
+              maxHeight: 0,
+              maxWidth: 0,
+              msoHide: 'all',
+            },
+          },
+          preview,
+          PREVIEW_PADDING,
+        )
+      : null,
+    h(
+      'table',
+      {
+        ...presentation,
+        className: tones(render, 'bg'),
+        style: { backgroundColor: colors.background, fontFamily: colors.font },
+      },
+      h(
+        'tbody',
+        null,
+        h(
+          'tr',
+          null,
+          h(
+            'td',
+            { align: 'center', style: { padding: '32px 16px' } },
+            h(
+              'table',
+              { ...presentation, style: { maxWidth: '560px', margin: '0 auto' } },
+              h(
+                'tbody',
+                null,
+                h(
+                  'tr',
+                  null,
+                  h(
+                    'td',
+                    {
+                      className: tones(render, 'text'),
+                      style: {
+                        padding: '0 4px 16px',
+                        color: colors.text,
+                        fontSize: '15px',
+                        fontWeight: 600,
+                        letterSpacing: '-0.02em',
+                      },
+                    },
+                    logoUrl
+                      ? img({
+                          src: safeImageSrc(logoUrl, render.policy),
+                          width: 22,
+                          height: 22,
+                          alt: '',
+                          style: {
+                            border: 0,
+                            borderRadius: '6px',
+                            display: 'inline-block',
+                            marginRight: '6px',
+                            verticalAlign: 'middle',
+                          },
+                        })
+                      : null,
+                    brand,
+                  ),
+                ),
+                h(
+                  'tr',
+                  null,
+                  h(
+                    'td',
+                    {
+                      className: tones(render, 'surface'),
+                      style: {
+                        backgroundColor: colors.surface,
+                        border: `1px solid ${colors.border}`,
+                        borderRadius: '12px',
+                        padding: '32px',
+                        fontFamily: colors.font,
+                      },
+                    },
+                    children,
+                  ),
+                ),
+                h(
+                  'tr',
+                  null,
+                  h(
+                    'td',
+                    { style: { padding: '20px 4px 0', fontFamily: colors.font } },
+                    reason
+                      ? h(
+                          'p',
+                          { className: tones(render, 'muted'), style: footerText },
+                          h('b', null, 'Why am I getting this?'),
+                          ' ',
+                          reason,
+                        )
+                      : null,
+                    unsubscribe === null
+                      ? null
+                      : h(
+                          'p',
+                          { className: tones(render, 'muted'), style: footerText },
+                          h(
+                            'a',
+                            {
+                              href: safeHref(unsubscribe, render.policy),
+                              className: tones(render, 'muted'),
+                              style: { color: colors.muted, textDecoration: 'underline' },
+                            },
+                            unsubscribeLabel,
+                          ),
+                        ),
+                    address
+                      ? h('p', { className: tones(render, 'muted'), style: footerText }, address)
+                      : null,
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+const HEADING_SIZES = { 1: ['22px', '28px'], 2: ['18px', '24px'], 3: ['15px', '22px'] };
+
+/** A heading, h1 unless `level` says 2 or 3. The first line says what happened (MER-36.4). */
+export function Heading({ children, level = 1 }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (level !== 1 && level !== 2 && level !== 3) {
+    throw new MailPolicyError(`An email heading is level 1, 2 or 3; got ${String(level)}.`);
+  }
+  if (render.text) return block(children);
+
+  const [fontSize, lineHeight] = HEADING_SIZES[level];
+  return h(
+    `h${level}`,
+    {
+      className: tones(render, 'text'),
+      style: {
+        color: theme.text,
+        fontFamily: theme.font,
+        fontSize,
+        fontWeight: 600,
+        letterSpacing: '-0.02em',
+        lineHeight,
+        margin: '0 0 12px',
+      },
+    },
+    children,
+  );
+}
+
+/** A paragraph; `muted` for the quieter kind, a note under the action. */
+export function Text({ children, muted = false }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (render.text) return block(children);
+
+  return h(
+    'p',
+    {
+      className: tones(render, muted ? 'muted' : 'secondary'),
+      style: muted
+        ? {
+            color: theme.muted,
+            fontFamily: theme.font,
+            fontSize: '13px',
+            lineHeight: '20px',
+            margin: '0 0 12px',
+          }
+        : {
+            color: theme.secondary,
+            fontFamily: theme.font,
+            fontSize: '14px',
+            lineHeight: '22px',
+            margin: '0 0 12px',
+          },
+    },
+    children,
+  );
+}
+
+/**
+ * A link in running text. In the text part, its words and then its URL --
+ * or the URL alone when the words are the URL.
+ */
+export function Link({ href, children }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  const url = safeHref(href, render.policy);
+  const label = children === undefined || children === null ? url : children;
+  if (render.text) {
+    const words = plain(label);
+    return words === url || words === spelled(url)
+      ? spelled(url)
+      : h(Fragment, null, label, ' (', spelled(url), ')');
+  }
+
+  return h(
+    'a',
+    {
+      href: url,
+      className: tones(render, 'accent'),
+      style: { color: theme.accent, textDecoration: 'underline' },
+    },
+    label,
+  );
+}
+
+/**
+ * The message's one action: a button, drawn as a table cell so Outlook
+ * draws it too, and -- unless `fallback` is false -- its URL written out
+ * beneath it, so the email works where buttons are blocked and in plain
+ * text.
+ */
+export function Button({ href, children, fallback = true }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  const url = safeHref(href, render.policy);
+  if (render.text) return block(children, ': ', spelled(url));
+
+  return h(
+    'table',
+    { ...presentation, width: undefined, style: { margin: '24px 0 8px' } },
+    h(
+      'tbody',
+      null,
+      h(
+        'tr',
+        null,
+        h(
+          'td',
+          null,
+          h(
+            'table',
+            { role: 'presentation', cellPadding: 0, cellSpacing: 0, border: 0 },
+            h(
+              'tbody',
+              null,
+              h(
+                'tr',
+                null,
+                h(
+                  'td',
+                  {
+                    bgcolor: theme.button,
+                    className: tones(render, 'button'),
+                    style: { backgroundColor: theme.button, borderRadius: '8px' },
+                  },
+                  h(
+                    'a',
+                    {
+                      href: url,
+                      className: tones(render, 'button-text'),
+                      style: {
+                        color: theme.buttonText,
+                        display: 'inline-block',
+                        fontFamily: theme.font,
+                        fontSize: '14px',
+                        fontWeight: 600,
+                        padding: '11px 18px',
+                        textDecoration: 'none',
+                      },
+                    },
+                    children,
+                  ),
+                ),
+              ),
+            ),
+          ),
+          fallback
+            ? h(
+                'p',
+                {
+                  className: tones(render, 'muted'),
+                  style: {
+                    color: theme.muted,
+                    fontFamily: theme.font,
+                    fontSize: '12px',
+                    lineHeight: '18px',
+                    margin: '12px 0 0',
+                    wordBreak: 'break-all',
+                  },
+                },
+                'Or open: ',
+                h(
+                  'a',
+                  {
+                    href: url,
+                    className: tones(render, 'accent'),
+                    style: { color: theme.accent, textDecoration: 'none' },
+                  },
+                  url,
+                ),
+              )
+            : null,
+        ),
+      ),
+    ),
+  );
+}
+
+/**
+ * Label and value pairs, an order's lines or an invoice's totals: a table,
+ * which Outlook lays out where it would not lay out anything else. In text,
+ * one `label: value` a line.
+ *
+ * @param {{ rows: ReadonlyArray<readonly [import('react').ReactNode, import('react').ReactNode]> }} props
+ */
+export function Rows({ rows }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (!Array.isArray(rows)) throw new MailPolicyError('Rows takes rows: a list of [label, value] pairs.');
+  if (render.text) {
+    return h(
+      Fragment,
+      null,
+      ...rows.map(([label, value], index) => h(Fragment, { key: index }, label, ': ', value, '\n')),
+      '\n',
+    );
+  }
+
+  const cell = {
+    borderBottom: `1px solid ${theme.border}`,
+    fontFamily: theme.font,
+    fontSize: '13px',
+    verticalAlign: 'top',
+  };
+  return h(
+    'table',
+    { ...presentation, style: { borderCollapse: 'collapse', margin: '16px 0' } },
+    h(
+      'tbody',
+      null,
+      ...rows.map(([label, value], index) =>
+        h(
+          'tr',
+          { key: index },
+          h(
+            'td',
+            {
+              className: tones(render, 'border', 'muted'),
+              style: { ...cell, color: theme.muted, padding: '9px 12px 9px 0', width: '38%' },
+            },
+            label,
+          ),
+          h(
+            'td',
+            {
+              className: tones(render, 'border', 'text'),
+              style: { ...cell, color: theme.text, padding: '9px 0' },
+            },
+            value,
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+/**
+ * A table of columns: a header row, if given, then the rows, each cell
+ * aligned as `align` says for its column. In text, each row's cells joined
+ * by ` | `, the header first.
+ *
+ * @param {{
+ *   head?: ReadonlyArray<import('react').ReactNode>,
+ *   rows: ReadonlyArray<ReadonlyArray<import('react').ReactNode>>,
+ *   align?: ReadonlyArray<'left' | 'right' | 'center'>,
+ * }} props
+ */
+export function Table({ head, rows, align = [] }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (!Array.isArray(rows)) throw new MailPolicyError('Table takes rows: a list of lists of cells.');
+  const line = (cells, key) =>
+    h(Fragment, { key }, ...cells.flatMap((cell, index) => (index === 0 ? [cell] : [' | ', cell])), '\n');
+  if (render.text) {
+    return h(
+      Fragment,
+      null,
+      head ? line(head, 'head') : null,
+      ...rows.map((row, index) => line(row, index)),
+      '\n',
+    );
+  }
+
+  const alignOf = (index) => {
+    const value = align[index] ?? 'left';
+    if (value !== 'left' && value !== 'right' && value !== 'center') {
+      throw new MailPolicyError(`A column aligns left, right or center; got '${String(value)}'.`);
+    }
+    return value;
+  };
+  const cell = (tag, color, weight) => (content, index) =>
+    h(
+      tag,
+      {
+        key: index,
+        align: alignOf(index),
+        className: tones(render, 'border', color === theme.muted ? 'muted' : 'text'),
+        style: {
+          borderBottom: `1px solid ${theme.border}`,
+          color,
+          fontFamily: theme.font,
+          fontSize: '13px',
+          fontWeight: weight,
+          padding: '9px 8px',
+          textAlign: alignOf(index),
+          verticalAlign: 'top',
+        },
+      },
+      content,
+    );
+
+  return h(
+    'table',
+    { ...presentation, style: { borderCollapse: 'collapse', margin: '16px 0' } },
+    head ? h('thead', null, h('tr', null, ...head.map(cell('th', theme.muted, 600)))) : null,
+    h(
+      'tbody',
+      null,
+      ...rows.map((row, index) => h('tr', { key: index }, ...row.map(cell('td', theme.text, 400)))),
+    ),
+  );
+}
+
+/**
+ * Preformatted text -- a code, a command, a log line -- on a dark box. In
+ * text, indented four spaces a line.
+ */
+export function Code({ children }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (render.text) {
+    const text = plain(children);
+    return text === null
+      ? block(children)
+      : block(
+          text
+            .split('\n')
+            .map((row) => `    ${row}`)
+            .join('\n'),
+        );
+  }
+
+  return h(
+    'pre',
+    {
+      className: tones(render, 'code'),
+      style: {
+        backgroundColor: theme.code,
+        borderRadius: '8px',
+        color: theme.codeText,
+        fontFamily: theme.mono,
+        fontSize: '12px',
+        lineHeight: '20px',
+        margin: '16px 0',
+        padding: '14px 16px',
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-word',
+      },
+    },
+    children,
+  );
+}
+
+/** A rule between parts of the message, as a table cell's border: Outlook draws an <hr> its own way. */
+export function Divider() {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (render.text) return '---\n\n';
+
+  return h(
+    'table',
+    { ...presentation, style: { margin: '24px 0' } },
+    h(
+      'tbody',
+      null,
+      h(
+        'tr',
+        null,
+        h(
+          'td',
+          {
+            className: tones(render, 'border'),
+            style: { borderTop: `1px solid ${theme.border}`, fontSize: '1px', lineHeight: '1px' },
+          },
+          '\u00a0',
+        ),
+      ),
+    ),
+  );
+}
+
+/** A list of points, bulleted; in text, one `- ` a line. */
+export function List({ items }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  if (!Array.isArray(items)) throw new MailPolicyError('List takes items: a list of what each point says.');
+  if (render.text) {
+    return h(
+      Fragment,
+      null,
+      ...items.map((item, index) => h(Fragment, { key: index }, '- ', item, '\n')),
+      '\n',
+    );
+  }
+
+  return h(
+    'ul',
+    {
+      className: tones(render, 'secondary'),
+      style: {
+        color: theme.secondary,
+        fontFamily: theme.font,
+        fontSize: '14px',
+        lineHeight: '22px',
+        margin: '0 0 12px',
+        paddingLeft: '20px',
+      },
+    },
+    ...items.map((item, index) => h('li', { key: index }, item)),
+  );
+}
+
+/**
+ * An image from the message's own origin or one the application allowed
+ * (policy.js), or one the message carries inline by its content id --
+ * `cid:logo` -- with its size and its words for whoever cannot see it. At
+ * least 8px each way: a smaller image shows nothing a reader needs, and is
+ * the shape of a tracking pixel, which is Tracker's.
+ */
+export function Image({ src, alt, width, height }) {
+  const render = useMailRender();
+  if (typeof alt !== 'string')
+    throw new MailPolicyError('An email image needs alt text, empty if it is decoration.');
+  for (const [name, value] of [
+    ['width', width],
+    ['height', height],
+  ]) {
+    if (!Number.isInteger(value) || value < 8 || value > 1200) {
+      throw new MailPolicyError(`An email image's ${name} is a whole number of pixels from 8 to 1200.`);
+    }
+  }
+  const url = safeImageSrc(src, render.policy);
+  if (render.text) return alt === '' ? null : block(`[${alt}]`);
+
+  return img({
+    src: url,
+    alt,
+    width,
+    height,
+    style: { border: 0, display: 'block', height: 'auto', maxWidth: '100%', outline: 'none' },
+  });
+}
+
+/**
+ * A tracking image (ADR 0116): one pixel, from an origin the Email names in
+ * its tracking origins and nowhere else, its query saying who opened the
+ * message. Not drawn in the text part, which loads nothing. Allowing one
+ * is the application's choice, made where its Email is written; the kit
+ * draws one nowhere on its own.
+ */
+export function Tracker({ src }) {
+  const render = useMailRender();
+  const url = safeTrackerSrc(src, render.policy);
+  if (render.text) return null;
+
+  return img({
+    src: url,
+    alt: '',
+    width: 1,
+    height: 1,
+    style: { border: 0, display: 'block', height: '1px', width: '1px' },
+  });
+}
+
+/** A size as a reader reads it: 840 bytes, 12 KB, 3.4 MB. */
+function size(bytes) {
+  if (bytes < 1024) return `${bytes} bytes`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * What the message carries to be opened, by name and size: what PHP told
+ * the render it attached (ADR 0116), never what a template says it did.
+ * Nothing when it carries none.
+ */
+export function Attachments({ label = 'Attached' }) {
+  const render = useMailRender();
+  const theme = useTheme();
+  const files = render.policy.attachments;
+  if (files.length === 0) return null;
+  if (render.text) {
+    return h(
+      Fragment,
+      null,
+      `${label}:\n`,
+      ...files.map((file, index) =>
+        h(Fragment, { key: index }, '- ', file.name, ' (', size(file.bytes), ')\n'),
+      ),
+      '\n',
+    );
+  }
+
+  const line = {
+    color: theme.muted,
+    fontFamily: theme.font,
+    fontSize: '13px',
+    lineHeight: '20px',
+    margin: 0,
+  };
+  return h(
+    'table',
+    { ...presentation, style: { margin: '16px 0' } },
+    h(
+      'tbody',
+      null,
+      h(
+        'tr',
+        null,
+        h(
+          'td',
+          {
+            className: tones(render, 'border'),
+            style: { borderTop: `1px solid ${theme.border}`, paddingTop: '12px' },
+          },
+          h('p', { className: tones(render, 'muted'), style: { ...line, fontWeight: 600 } }, label),
+          ...files.map((file, index) =>
+            h(
+              'p',
+              { key: index, className: tones(render, 'text'), style: { ...line, color: theme.text } },
+              file.name,
+              h(
+                'span',
+                { className: tones(render, 'muted'), style: { color: theme.muted } },
+                ` · ${size(file.bytes)}`,
+              ),
+            ),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+/** Spacing around a group of components, as a padded cell. */
+export function Section({ children }) {
+  const render = useMailRender();
+  if (render.text) return h(Fragment, null, children);
+
+  return h(
+    'table',
+    { ...presentation, style: { margin: '16px 0' } },
+    h('tbody', null, h('tr', null, h('td', null, children))),
+  );
+}