@tinvar/mail 0.0.0-stage → 0.4.1

package/src/preview.js

@@ -0,0 +1,171 @@
+// A preview of an app's emails, in dev and in dev alone (ADR 0086).
+//
+// A Vite plugin: its pages are served by Vite's dev server -- the one
+// `tinvar serve --dev` starts, behind PHP's server under /_vite/ -- and by
+// nothing else. It has no part in a build (`apply: 'serve'`), refuses to
+// start anywhere that says production, as the dev server itself does, and
+// answers only a request naming this machine. What it draws is each
+// template from the sample props the app writes for it: never a database's
+// rows, a reader's address or a real link's token.
+
+/** The variables any of which, saying `production`, rule the preview out. Mirrors Tinvar\Support\DevMode. */
+const PRODUCTION_MARKERS = ['NODE_ENV', 'TINVAR_ENV', 'APP_ENV'];
+
+/** Hosts a request may name: this machine's. */
+const LOOPBACK_HOST = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::[1-9]\d{0,4})?$/i;
+
+/** A template's name, as PHP's Email allows one. */
+const TEMPLATE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Refuses, loudly, anywhere that says production. */
+export function assertDevelopment(env = process.env) {
+  for (const name of PRODUCTION_MARKERS) {
+    if (
+      String(env[name] ?? '')
+        .trim()
+        .toLowerCase() === 'production'
+    ) {
+      throw new Error(
+        `The email preview is refused: ${name}=production. It draws templates over HTTP for whoever asks, ` +
+          'so it runs under the dev server alone.',
+      );
+    }
+  }
+}
+
+/** @param {string} value */
+function escapeHtml(value) {
+  return value.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;' })[c],
+  );
+}
+
+/**
+ * The plugin. `templates` is the module whose `renderMail(frame)` draws the
+ * app's emails (createMailRenderer()), `previews` one whose default export
+ * is a function of the origin the preview is served on, answering sample
+ * props for each template by name.
+ *
+ * @param {{ templates: string, previews: string, environment?: string, path?: string }} options
+ * @returns {import('vite').Plugin}
+ */
+export function mailPreview({ templates, previews, environment = 'ssr', path = '__mail' }) {
+  return {
+    name: 'tinvar:mail-preview',
+    apply: 'serve',
+    configureServer(server) {
+      assertDevelopment();
+      const prefix = `${server.config.base.replace(/\/?$/, '/')}${path}`;
+
+      server.middlewares.use(async (req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://preview.invalid');
+        if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) return next();
+
+        const send = (status, type, body, policy) => {
+          res.statusCode = status;
+          res.setHeader('content-type', `${type}; charset=utf-8`);
+          res.setHeader('cache-control', 'no-store');
+          res.setHeader('x-content-type-options', 'nosniff');
+          res.setHeader('referrer-policy', 'no-referrer');
+          res.setHeader('content-security-policy', policy);
+          res.end(body);
+        };
+        const page =
+          "default-src 'none'; style-src 'unsafe-inline'; frame-src 'self'; frame-ancestors 'self'";
+
+        // This machine, asked by this machine: a dev server reached through
+        // a name that rebinds to it is not asked by its developer.
+        const host = req.headers.host ?? '';
+        const peer = req.socket.remoteAddress ?? '';
+        if (!LOOPBACK_HOST.test(host) || !/^(?:127\.|::1$|::ffff:127\.)/.test(peer)) {
+          return send(404, 'text/plain', 'Not found', "default-src 'none'");
+        }
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          return send(405, 'text/plain', 'Method not allowed', "default-src 'none'");
+        }
+
+        try {
+          const env = server.environments[environment];
+          if (!env?.runner) throw new Error(`The dev server has no runnable '${environment}' environment.`);
+          const load = async (source) => {
+            const resolved = await env.pluginContainer.resolveId(source, undefined);
+            if (!resolved) throw new Error(`${source} does not resolve in the '${environment}' environment.`);
+            return env.runner.import(resolved.id);
+          };
+          const [mail, samples] = await Promise.all([load(templates), load(previews)]);
+          const origin = `http://${host}`;
+          const props = typeof samples.default === 'function' ? samples.default(origin) : null;
+          if (props === null || typeof props !== 'object') {
+            throw new Error(
+              `${previews} must export a default function of the origin, answering props by template.`,
+            );
+          }
+          const names = Object.keys(props)
+            .filter((name) => TEMPLATE.test(name))
+            .sort();
+          const rest = url.pathname.slice(prefix.length).replace(/^\//, '');
+
+          if (rest === '') {
+            const items = names
+              .map((name) => `<li><a href="${escapeHtml(`${prefix}/${name}`)}">${escapeHtml(name)}</a></li>`)
+              .join('');
+            return send(200, 'text/html', shell('Emails', `<h1>Emails</h1><ul>${items}</ul>`), page);
+          }
+
+          const [name, part] = rest.split('/');
+          if (!name || !names.includes(name) || (part !== undefined && part !== 'html')) {
+            return send(404, 'text/plain', 'No such email', "default-src 'none'");
+          }
+          const rendered = await mail.renderMail({
+            template: name,
+            props: props[name],
+            links: { origin, images: [] },
+          });
+          if (part === 'html') {
+            // Drawn in a sandbox of its own: no script, no form, an origin
+            // of nobody's, and nothing loaded but its images from here.
+            return send(
+              200,
+              'text/html',
+              rendered.html,
+              `sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src ${origin}; frame-ancestors 'self'`,
+            );
+          }
+
+          const frame = escapeHtml(`${prefix}/${name}/html`);
+          return send(
+            200,
+            'text/html',
+            shell(
+              name,
+              `<p><a href="${escapeHtml(prefix)}">Emails</a></p><h1>${escapeHtml(name)}</h1>` +
+                `<iframe src="${frame}" sandbox title="${escapeHtml(name)} as HTML"></iframe>` +
+                `<h2>Plain text</h2><pre>${escapeHtml(rendered.text)}</pre>`,
+            ),
+            page,
+          );
+        } catch (error) {
+          const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+          return send(
+            500,
+            'text/html',
+            shell('Email preview failed', `<h1>Failed</h1><pre>${escapeHtml(message)}</pre>`),
+            page,
+          );
+        }
+      });
+    },
+  };
+}
+
+/** @param {string} title @param {string} body */
+function shell(title, body) {
+  return (
+    `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)} · email preview</title>` +
+    '<style>body{font:14px/1.5 system-ui,sans-serif;margin:24px;color:#111110;background:#F7F7F5}' +
+    'iframe{width:100%;height:640px;border:1px solid #E6E5E1;background:#fff}' +
+    'pre{white-space:pre-wrap;background:#fff;border:1px solid #E6E5E1;padding:12px}</style>' +
+    `</head><body>${body}</body></html>`
+  );
+}

package/src/render.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentType, ReactElement } from 'react';
+
+export interface RenderedEmail {
+  html: string;
+  text: string;
+}
+
+/** The `mail` frame's fields a renderMail() entry reads. */
+export interface MailFrame {
+  template: string;
+  props: Record<string, unknown>;
+  links?: unknown;
+}
+
+/** Draws `element` into an HTML part and a plain-text part, its links held to `links`. */
+export declare function renderEmail(element: ReactElement, links?: unknown): RenderedEmail;
+
+/** The app's renderMail(), over a registry of the templates PHP may name. */
+export declare function createMailRenderer(
+  templates: Record<string, ComponentType<any>>,
+): (frame: MailFrame) => Promise<RenderedEmail>;

package/src/render.js

@@ -0,0 +1,163 @@
+// Draws an email: the HTML part and the plain-text part, from one tree.
+//
+// In the renderer's ssr environment -- the react-server condition has no
+// react-dom/server -- where the app's renderMail() entry is called with the
+// `mail` frame PHP sent (ADR 0032, ADR 0086).
+
+import { createElement as h } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { RenderContext } from './context.js';
+import { DEFAULT_THEME, policyOf } from './policy.js';
+
+/**
+ * The dark palette's rule: each class a kit component marks an element with,
+ * recoloured where the client prefers dark -- and in Outlook.com, which says
+ * so by `[data-ogsc]` rather than the media query. `!important`, since the
+ * light colours are inline. Every value is a hex colour themeOf() checked.
+ *
+ * @param {typeof DEFAULT_THEME} dark
+ */
+function darkStyle(dark) {
+  const rules = [
+    ['bg', `background-color:${dark.background}`],
+    ['surface', `background-color:${dark.surface};border-color:${dark.border}`],
+    ['border', `border-color:${dark.border}`],
+    ['text', `color:${dark.text}`],
+    ['secondary', `color:${dark.secondary}`],
+    ['muted', `color:${dark.muted}`],
+    ['accent', `color:${dark.accent}`],
+    ['button', `background-color:${dark.button}`],
+    ['button-text', `color:${dark.buttonText}`],
+    ['code', `background-color:${dark.code};color:${dark.codeText}`],
+  ];
+  const body = (prefix) =>
+    rules
+      .map(
+        ([tone, declarations]) =>
+          `${prefix}.tm-${tone}{${declarations
+            .split(';')
+            .map((declaration) => `${declaration} !important`)
+            .join(';')}}`,
+      )
+      .join('');
+
+  return (
+    ':root{color-scheme:light dark;supported-color-schemes:light dark}' +
+    `@media (prefers-color-scheme: dark){${body('')}}` +
+    body('[data-ogsc] ')
+  );
+}
+
+/** The characters React escapes in text, and what each stands for. */
+const ENTITIES = { '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#x27;': "'", '&amp;': '&' };
+
+/** The closing tag of a block element: in the text part, the end of a line. */
+const BLOCK_END =
+  /<\/(?:address|article|aside|blockquote|center|dd|div|dl|dt|figcaption|figure|footer|h[1-6]|header|li|main|nav|ol|p|pre|section|table|tbody|tfoot|thead|tr|ul)\s*>/gi;
+
+/** Escapes text for the shell's <title>, as React escapes the body's. */
+function escapeHtml(value) {
+  return value.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;' })[c],
+  );
+}
+
+/**
+ * One email from `element`, under `links` -- the message's origin and the
+ * origins its images may come from, as PHP's LinkPolicy sent them.
+ *
+ * Two passes over the same tree, each with a context of its own: the HTML
+ * pass, whose body is put inside a document this function writes -- so no
+ * <link rel="preload"> React would put in a <head> it drew, and nothing the
+ * template did not ask for, and no <meta>: PHP writes the head's own, the
+ * charset first, and refuses any other (SafeMailHtml) -- and the text
+ * pass, where each kit component
+ * draws its plain form. Synchronous: a template is handed everything it
+ * shows, and has nothing to wait for.
+ *
+ * @param {import('react').ReactElement} element
+ * @param {unknown} [links]
+ * @returns {{ html: string, text: string }}
+ */
+export function renderEmail(element, links) {
+  const policy = policyOf(links);
+
+  const document = { lang: 'en', title: '', background: DEFAULT_THEME.background, dark: null };
+  const body = renderToStaticMarkup(
+    h(RenderContext.Provider, { value: { text: false, policy, document } }, element),
+  );
+  const textMarkup = renderToStaticMarkup(
+    h(RenderContext.Provider, { value: { text: true, policy, document: { ...document } } }, element),
+  );
+
+  const html =
+    '<!DOCTYPE html>' +
+    `<html lang="${escapeHtml(document.lang)}" dir="ltr">` +
+    '<head>' +
+    `<title>${escapeHtml(document.title)}</title>` +
+    (document.dark === null ? '' : `<style>${darkStyle(document.dark)}</style>`) +
+    '</head>' +
+    `<body${document.dark === null ? '' : ' class="tm-bg"'} style="margin:0;padding:0;background-color:${document.background}">` +
+    body +
+    '</body></html>';
+
+  return { html, text: plainText(textMarkup) };
+}
+
+/**
+ * The text pass's markup as text: any element a template drew itself (a
+ * <b>, a <span>) taken out -- its words kept -- and React's escapes undone.
+ * Text React wrote has no `<` of its own, only `&lt;`, so every tag found is
+ * one an element made.
+ *
+ * A block element a template drew (a <div>, a <p>, a row) ends a line where
+ * it closes, or blocks ran together ("Order shippedTrack it soon"); blank
+ * lines past one, from blocks nested in blocks, are collapsed below. The
+ * components draw nothing in the text pass but text, so these are only ever
+ * a template's own.
+ *
+ * @param {string} markup
+ */
+function plainText(markup) {
+  const text = markup
+    .replace(/<(?:br|hr)\s*\/?>/gi, '\n')
+    .replace(BLOCK_END, '\n')
+    .replace(/<[^>]*>/g, '')
+    .replace(
+      /&(?:lt|gt|quot|#x27|amp);/g,
+      (entity) => ENTITIES[/** @type {keyof typeof ENTITIES} */ (entity)],
+    );
+
+  return `${text
+    .split('\n')
+    .map((line) => line.replace(/[ \t\u00a0]+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()}\n`;
+}
+
+/**
+ * The app's renderMail(): the templates PHP may name, by the name its
+ * Mailable gives, in a registry -- as the deferred components are -- so a
+ * name from PHP is never a module path, and never a key the registry
+ * inherited (`constructor`, `toString`).
+ *
+ * @template {Record<string, import('react').ComponentType<any>>} T
+ * @param {T} templates
+ * @returns {(frame: { template: string, props: Record<string, unknown>, links?: unknown }) => Promise<{ html: string, text: string }>}
+ */
+export function createMailRenderer(templates) {
+  const registry = new Map(Object.entries(templates));
+
+  return async function renderMail(frame) {
+    const { template, props, links } = frame ?? {};
+    const Template = typeof template === 'string' ? registry.get(template) : undefined;
+    if (Template === undefined) throw new Error(`Unknown email template '${String(template)}'.`);
+    if (typeof props !== 'object' || props === null || Array.isArray(props)) {
+      throw new TypeError(`The props of '${template}' must be an object, as PHP encodes a Data object.`);
+    }
+
+    return renderEmail(h(Template, props), links);
+  };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.