@crombolo/render 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/render",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "TSX server rendering and the published-content model for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.16.0",
+    "@crombolo/core": "0.17.0",
     "@types/react": "^19.3.0"
   }
 }

package/src/context.ts

@@ -16,6 +16,8 @@ import type { SiteSearchPort } from './search.ts'
 
 interface RenderScope {
   page: PageProps | undefined
+  /** An e-mail template is rendering: there is no page to ask for. */
+  email?: boolean
   /** The site search the server scoped to the person asking, when it provides one. */
   search?: SiteSearchPort
   contexts: ReadonlyMap<symbol, unknown>
@@ -37,6 +39,13 @@ export function renderScope<T>(page: PageProps, render: () => T, search?: SiteSe
   return store.run({ page, search, contexts: new Map(), ids: { next: 0 } }, render)
 }
 
+/** Runs an e-mail template's render: ids and context work, and there is no page. */
+export function emailScope<T>(render: () => T): T {
+  return store.run({ page: undefined, email: true, contexts: new Map(), ids: { next: 0 } }, render)
+}
+
+const NO_PAGE_IN_EMAIL = 'an e-mail template has no page; read what it needs from its props.'
+
 function within(caller: string): RenderScope {
   const scope = store.getStore()
   if (!scope)
@@ -53,7 +62,8 @@ function within(caller: string): RenderScope {
  */
 // biome-ignore lint/suspicious/noExplicitAny: an untyped page, as `PageProps` defaults to.
 export function usePage<Properties = any>(): PageProps<Properties> {
-  const { page } = within('usePage()')
+  const { page, email } = within('usePage()')
+  if (email) throw new Error(`usePage() was called while ${NO_PAGE_IN_EMAIL}`)
   if (!page)
     throw new Error('usePage() was called inside a context Provider rendered outside a page.')
   return page as PageProps<Properties>
@@ -62,6 +72,7 @@ export function usePage<Properties = any>(): PageProps<Properties> {
 /** The page and the site search for `search()`, which lives in `search.ts`. */
 export function currentSiteSearch(): { page: PageProps; search: SiteSearchPort | undefined } {
   const scope = within('search()')
+  if (scope.email) throw new Error(`search() was called while ${NO_PAGE_IN_EMAIL}`)
   if (!scope.page)
     throw new Error('search() was called inside a context Provider rendered outside a page.')
   return { page: scope.page, search: scope.search }
@@ -112,7 +123,13 @@ export function createContext<T>(defaultValue: T): Context<T> {
     const contexts = new Map(outer?.contexts)
     contexts.set(key, value)
     return store.run(
-      { page: outer?.page, search: outer?.search, contexts, ids: outer?.ids ?? { next: 0 } },
+      {
+        page: outer?.page,
+        email: outer?.email,
+        search: outer?.search,
+        contexts,
+        ids: outer?.ids ?? { next: 0 },
+      },
       children,
     )
   }

package/src/email.ts

@@ -0,0 +1,52 @@
+/**
+ * What an e-mail template is given: the form, what was sent, and where from.
+ * `docs/forms.md`, "An e-mail template".
+ *
+ * An e-mail is not a page. There is no route, no member and no navigation, so a
+ * template reads everything from these props, and `usePage()` says so.
+ */
+import type { SchemaForm } from '@crombolo/core'
+import type { RawHtml } from './html.ts'
+
+/** One field of the form, in the form's order, as the e-mail may show it. */
+export interface EmailField {
+  alias: string
+  caption: string
+  type: string
+  /** What was entered: a choice's label before its stored value, as `{alias}` shows it. */
+  values: string[]
+  answered: boolean
+  sensitive: boolean
+  /** Sensitive, and the workflow does not send sensitive answers: `values` is empty. */
+  leftOut: boolean
+}
+
+export interface EmailProps {
+  form: SchemaForm
+  fields: EmailField[]
+  /** What was entered for a field, joined as `{alias}` joins it; empty when nothing was. */
+  value(alias: string): string
+  entry: {
+    /** Absent for a form that stores no entries. */
+    id: string | null
+    /** When the workflow was queued: the submission, or the approval for `on = "approve"`. */
+    submittedAt: Date
+  }
+  site: { name: string; url: string }
+  /** The subject line, already substituted. */
+  subject: string
+  /** Aborts when the render has taken too long. */
+  signal: AbortSignal
+}
+
+/** What a layout around an e-mail template is given: the same props, and the template inside. */
+export interface EmailLayoutProps extends EmailProps {
+  children: RawHtml
+}
+
+export type EmailRenderResult =
+  | { status: 'ok'; html: string }
+  /** No component answers to the alias in the views being served. */
+  | { status: 'missing' }
+  /** The message names the template and its line under `components/`, never a snapshot path. */
+  | { status: 'error'; message: string }

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './context.ts'
+export * from './email.ts'
 export * from './excerpt.ts'
 export * from './form-script.ts'
 export * from './forms.ts'

package/src/renderer.ts

@@ -7,10 +7,11 @@
  * declares it too — in the file, not the database.
  */
 import { existsSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { basename, join, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { FormSubmissionState } from '@crombolo/core'
-import { renderScope } from './context.ts'
+import { emailScope, renderScope } from './context.ts'
+import type { EmailProps, EmailRenderResult } from './email.ts'
 import { RawHtml } from './html.ts'
 import { type Child, renderToString } from './jsx-runtime.ts'
 import type { PageProps, PublishedContent, RequestMember } from './model.ts'
@@ -257,16 +258,56 @@ export class Renderer {
     }
   }
 
+  /**
+   * Renders an e-mail template to HTML: resolved in the current views as a
+   * page's template is, under the same time limit, inside its layouts.
+   *
+   * Never throws. A failure comes back as a message a person can act on, naming
+   * the template and the line under `components/` it failed on.
+   */
+  async renderEmail(alias: string, props: Omit<EmailProps, 'signal'>): Promise<EmailRenderResult> {
+    if (!this.componentPath(alias)) return { status: 'missing' }
+    try {
+      const html = await this.#withDeadline(alias, undefined, (signal, rendering) =>
+        emailScope(() => this.#renderLayouts(alias, { ...props, signal }, rendering)),
+      )
+      return html === undefined ? { status: 'missing' } : { status: 'ok', html }
+    } catch (error) {
+      return { status: 'error', message: this.#emailFailure(alias, error) }
+    }
+  }
+
+  /** `The e-mail template 'x' failed at components/x.tsx:12: <what it threw>`. */
+  #emailFailure(alias: string, error: unknown): string {
+    const root = `${this.#componentsDir}${sep}`
+    const shown = `${basename(this.#componentsDir)}/`
+    const readable = (text: string) => this.inSource(text).replaceAll(root, shown)
+    const message = readable(error instanceof Error ? error.message : String(error)).trim()
+    const stack = error instanceof Error ? readable(error.stack ?? '') : ''
+    const escaped = shown.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const frame = new RegExp(`${escaped}[^\\s:()]+\\.[jt]sx?:\\d+`).exec(stack)
+    return `The e-mail template '${alias}' failed${frame ? ` at ${frame[0]}` : ''}: ${message}`
+  }
+
   async #renderContent(
     content: PublishedContent,
     alias: string,
     culture: string | null,
     request: RenderRequest = {},
   ): Promise<string | undefined> {
+    return this.#withDeadline(alias, request.signal, (signal, rendering) =>
+      this.#renderChain(content, alias, culture, request, signal, rendering),
+    )
+  }
+
+  /** Runs a render under the time limit; the signal it hands on aborts when that runs out. */
+  async #withDeadline<T>(
+    alias: string,
+    outer: AbortSignal | undefined,
+    render: (signal: AbortSignal, rendering: { alias: string }) => Promise<T>,
+  ): Promise<T> {
     const deadline = new AbortController()
-    const signal = request.signal
-      ? AbortSignal.any([deadline.signal, request.signal])
-      : deadline.signal
+    const signal = outer ? AbortSignal.any([deadline.signal, outer]) : deadline.signal
     const rendering = { alias }
     const timer =
       this.#renderTimeoutMs > 0
@@ -286,7 +327,7 @@ export class Renderer {
       else signal.addEventListener('abort', fail, { once: true })
     })
     stopped.catch(() => {})
-    const work = this.#renderChain(content, alias, culture, request, signal, rendering)
+    const work = render(signal, rendering)
     // Once the deadline has answered, a late failure has nobody left to tell.
     work.catch(() => {})
     try {
@@ -328,9 +369,10 @@ export class Renderer {
     return renderScope(props, () => this.#renderLayouts(alias, props, rendering), request.search)
   }
 
-  async #renderLayouts(
+  /** Generic over its props: a page's, or an e-mail's. */
+  async #renderLayouts<Props extends object>(
     alias: string,
-    props: PageProps,
+    props: Props,
     rendering: { alias: string },
   ): Promise<string | undefined> {
     let currentAlias: string | undefined = alias
@@ -343,10 +385,8 @@ export class Renderer {
       rendering.alias = currentAlias
       const module = await this.#load(currentAlias)
       if (!module) return depth === 0 || body === undefined ? undefined : withDoctype(body.value)
-      const rendered =
-        body === undefined
-          ? module.default(props)
-          : module.default({ ...props, children: body } as LayoutProps)
+      const render = module.default as unknown as (props: object) => Child | Promise<Child>
+      const rendered = body === undefined ? render(props) : render({ ...props, children: body })
       body = new RawHtml(await renderToString(rendered as Child))
       currentAlias = module.layout
       depth += 1