From 91e3baa95aa9a2a81e651b355e6ea017c76c6f2c Mon Sep 17 00:00:00 2001
From: "Grok (via xAI)" <grok@llazyemail.github.io>
Date: Thu, 15 Oct 2026 04:29:12 +0000
Subject: [PATCH] feat: template-level shell defaults and structured attributes

- htmlAttributes / bodyAttributes accept a raw string or a structured map.
- openTag / serializeAttributes handle both shapes (raw interpolation).
- EmailTemplate.shell holds default DocumentShellOptions; per-render
  props override them.
- composeEmail merges the two and forwards the result to document().

A Postmark-style or styled-body template can declare its shape once.
---
 README.md                          |  2 +-
 llms-full.txt                      |  4 ++--
 src/index.ts                       |  2 ++
 src/templates/body/body.ts         | 10 +++++----
 src/templates/document/document.ts | 28 ++++++++++++++---------
 src/templates/email/email.ts       |  2 +-
 src/templates/email/shell.ts       | 36 ++++++++++++++++++++----------
 src/templates/email/types.ts       |  4 ++++
 src/utils/openTag.ts               | 30 ++++++++++++++++++++++---
 test/email.test.ts                 | 18 +++++++++++++++
 test/index.test.ts                 | 11 +++++++++
 11 files changed, 113 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index caf61f1..711fce0 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ The email preset calls these. They stay public so a part, or a caller, can use t
 | `footer({ companyName?, unsubscribeUrl? })`                                                          | `<footer>` with the company name and an optional unsubscribe link                                                         |
 | `body({ preheaderHtml?, mainHtml?, footerHtml?, attributes? })`                                      | `<body>` around an optional preheader, main, and footer. Optional raw attributes.                                         |
 | `content({ content? })`                                                                              | A `<div>` around raw HTML. The email shell does not call it                                                               |
-| `document({ headHtml?, mainHtml?, footerHtml?, doctype?, lang?, htmlAttributes?, bodyAttributes? })` | Doctype, `<html>`, head, and body. Defaults to HTML5 + `lang="en"`. Supports XHTML, omitting `lang`, and body attributes. |
+| `document({ headHtml?, mainHtml?, footerHtml?, doctype?, lang?, htmlAttributes?, bodyAttributes? })` | Doctype, `<html>`, head, and body. Defaults to HTML5 + `lang="en"`. Attributes accept a raw string or a structured map. |
 
 Omitted strings render empty. The button is present only when both `ctaLabel` and `ctaUrl` are set. The unsubscribe link is present only when `unsubscribeUrl` is set.
 
diff --git a/llms-full.txt b/llms-full.txt
index 30c8b9a..d082019 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -109,8 +109,8 @@ document({
 |---|---|
 | `doctype` | `<!DOCTYPE html>` |
 | `lang` | `"en"`. Pass `false` or `null` to omit the attribute |
-| `htmlAttributes` | raw extra attributes on `<html>` (e.g. `xmlns="..."`) |
-| `bodyAttributes` | raw extra attributes on `<body>` (e.g. `style="margin:0"`) |
+| `htmlAttributes` | raw string or structured map (e.g. `{ xmlns: '...' }`) |
+| `bodyAttributes` | raw string or structured map (e.g. `{ style: 'margin:0' }`) |
 | `headHtml` | empty |
 | (BodyProps) | passed through to `body` |
 
diff --git a/src/index.ts b/src/index.ts
index b699856..f0bd0f5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -44,3 +44,5 @@ export type { ContentProps } from './templates/content/content';
 
 export { document } from './templates/document/document';
 export type { DocumentProps, DocumentShellOptions } from './templates/document/document';
+export { openTag, serializeAttributes } from './utils/openTag';
+export type { TagAttributes } from './utils/openTag';
diff --git a/src/templates/body/body.ts b/src/templates/body/body.ts
index a9cde79..6e48048 100644
--- a/src/templates/body/body.ts
+++ b/src/templates/body/body.ts
@@ -1,4 +1,5 @@
 import { openTag } from '../../utils/openTag';
+import type { TagAttributes } from '../../utils/openTag';
 
 export interface BodyProps {
   /** Raw HTML for the top of `<body>` (e.g. hidden preheader). */
@@ -8,18 +9,19 @@ export interface BodyProps {
   /** `<footer>` fragment. */
   footerHtml?: string;
   /**
-   * Raw attributes for the opening `<body>` tag
-   * (for example `style="background-color:#fff;margin:0"`).
+   * Attributes for the opening `<body>` tag.
+   * Accepts a raw string or a structured map
+   * (for example `{ style: 'background-color:#fff;margin:0' }`).
    * Callers own escaping. Empty when omitted.
    */
-  attributes?: string;
+  attributes?: TagAttributes;
 }
 
 export function body({
   preheaderHtml = '',
   mainHtml = '',
   footerHtml = '',
-  attributes = '',
+  attributes,
 }: BodyProps = {}): string {
   const open = openTag('body', attributes);
   return `${open}
diff --git a/src/templates/document/document.ts b/src/templates/document/document.ts
index 79159c8..c918a54 100644
--- a/src/templates/document/document.ts
+++ b/src/templates/document/document.ts
@@ -1,6 +1,7 @@
 import { body } from '../body/body';
 import type { BodyProps } from '../body/body';
-import { openTag } from '../../utils/openTag';
+import { openTag, serializeAttributes } from '../../utils/openTag';
+import type { TagAttributes } from '../../utils/openTag';
 
 /**
  * Options that control the outer document shell.
@@ -19,17 +20,19 @@ export interface DocumentShellOptions {
    */
   lang?: string | false | null;
   /**
-   * Additional raw attributes for the `<html>` element
-   * (for example `xmlns="http://www.w3.org/1999/xhtml"`).
+   * Additional attributes for the `<html>` element.
+   * Accepts a raw string or a structured map
+   * (for example `{ xmlns: 'http://www.w3.org/1999/xhtml' }`).
    * Placed after `lang` when both are present. Callers own escaping.
    */
-  htmlAttributes?: string;
+  htmlAttributes?: TagAttributes;
   /**
-   * Additional raw attributes for the `<body>` element
-   * (for example `style="margin:0;padding:0"` or `class="email"`).
+   * Additional attributes for the `<body>` element.
+   * Accepts a raw string or a structured map
+   * (for example `{ style: 'margin:0;padding:0' }`).
    * Callers own escaping.
    */
-  bodyAttributes?: string;
+  bodyAttributes?: TagAttributes;
 }
 
 export interface DocumentProps extends BodyProps, DocumentShellOptions {
@@ -50,17 +53,20 @@ export function document({
   headHtml = '',
   doctype = '<!DOCTYPE html>',
   lang = 'en',
-  htmlAttributes = '',
-  bodyAttributes = '',
+  htmlAttributes,
+  bodyAttributes,
   ...rest
 }: DocumentProps = {}): string {
   const langPart = lang === false || lang === null || lang === '' ? '' : `lang="${lang}"`;
 
-  const htmlAttrParts = [langPart, htmlAttributes.trim()].filter(Boolean);
+  const htmlAttrParts = [langPart, serializeAttributes(htmlAttributes)].filter(Boolean);
   const htmlAttrs = htmlAttrParts.join(' ');
 
   const htmlOpen = openTag('html', htmlAttrs);
-  const bodyHtml = body({ ...rest, attributes: bodyAttributes });
+  const bodyHtml = body({
+    ...rest,
+    ...(bodyAttributes !== undefined ? { attributes: bodyAttributes } : {}),
+  });
 
   return `${doctype}
 ${htmlOpen}
diff --git a/src/templates/email/email.ts b/src/templates/email/email.ts
index a91f47f..f838859 100644
--- a/src/templates/email/email.ts
+++ b/src/templates/email/email.ts
@@ -39,7 +39,7 @@ export function defineEmailTemplate(input: EmailTemplate): Template<EmailProps>
         ),
       ),
     ],
-    compose: (parts, ctx) => composeEmail(parts, ctx.props),
+    compose: (parts, ctx) => composeEmail(parts, ctx.props, input.shell),
   });
 }
 
diff --git a/src/templates/email/shell.ts b/src/templates/email/shell.ts
index 5995cc5..fbb76a9 100644
--- a/src/templates/email/shell.ts
+++ b/src/templates/email/shell.ts
@@ -1,9 +1,9 @@
 import { displayErrors } from '../../runtime/errors';
 import { document } from '../document/document';
+import type { DocumentShellOptions } from '../document/document';
 import { hasSlot, slot } from '../../runtime/render';
 import type { RenderContext, TemplatePart } from '../../runtime/types';
 import type { EmailProps } from './types';
-import { pickDefined } from '../../utils/pickDefined';
 
 const SHELL_PARTS = new Set(['head', 'main', 'footer']);
 
@@ -26,10 +26,27 @@ export function shellPart(
   };
 }
 
+/**
+ * Merge template-level shell defaults with per-render props.
+ * Props win when both supply a value.
+ */
+export function mergeShell(
+  defaults: DocumentShellOptions | undefined,
+  props: EmailProps,
+): DocumentShellOptions {
+  const merged: DocumentShellOptions = { ...defaults };
+  if (props.doctype !== undefined) merged.doctype = props.doctype;
+  if (props.lang !== undefined) merged.lang = props.lang;
+  if (props.htmlAttributes !== undefined) merged.htmlAttributes = props.htmlAttributes;
+  if (props.bodyAttributes !== undefined) merged.bodyAttributes = props.bodyAttributes;
+  return merged;
+}
+
 /** Place custom part HTML inside `<body>`, after `main` and before `footer`. */
 export function composeEmail(
   parts: Readonly<Record<string, string>>,
   props: EmailProps = {},
+  shellDefaults?: DocumentShellOptions,
 ): string {
   // Read the shell before custom ids. Key order is the part list.
   const headHtml = readPart(parts, 'head');
@@ -39,20 +56,15 @@ export function composeEmail(
   const footerHtml = readPart(parts, 'footer');
   const mainHtml = extraIds.length > 0 ? `${mainPiece}\n${extraHtml}` : mainPiece;
 
-  const { doctype, lang, htmlAttributes, bodyAttributes } = props;
-
-  const shell = pickDefined({
-    doctype,
-    htmlAttributes,
-    bodyAttributes,
-    ...(typeof lang === 'string' ? { lang } : {}),
-  });
+  const shell = mergeShell(shellDefaults, props);
 
   return document({
     headHtml,
     mainHtml,
     footerHtml,
-    ...shell,
-    ...(lang === false || lang === null ? { lang } : {}),
+    ...(shell.doctype !== undefined ? { doctype: shell.doctype } : {}),
+    ...(shell.lang !== undefined ? { lang: shell.lang } : {}),
+    ...(shell.htmlAttributes !== undefined ? { htmlAttributes: shell.htmlAttributes } : {}),
+    ...(shell.bodyAttributes !== undefined ? { bodyAttributes: shell.bodyAttributes } : {}),
   });
-}
\ No newline at end of file
+}
diff --git a/src/templates/email/types.ts b/src/templates/email/types.ts
index 2400d0c..2d3320f 100644
--- a/src/templates/email/types.ts
+++ b/src/templates/email/types.ts
@@ -17,8 +17,12 @@ export interface EmailProps extends DocumentShellOptions {
  * An email-shaped template. `parts` are custom steps inserted inside `<body>`
  * after `main` and before `footer`. Built-in `head`, `main`, and `footer`
  * stay in place. A slot with the same id replaces that built-in part.
+ *
+ * `shell` holds default document options for this template. Per-render
+ * `EmailProps` override them.
  */
 export interface EmailTemplate {
   id: string;
   parts?: readonly TemplatePart<EmailProps>[];
+  shell?: DocumentShellOptions;
 }
diff --git a/src/utils/openTag.ts b/src/utils/openTag.ts
index 8cf98fc..497e997 100644
--- a/src/utils/openTag.ts
+++ b/src/utils/openTag.ts
@@ -1,8 +1,32 @@
 /**
- * Build an opening tag with optional raw attributes.
+ * Raw attribute string or a structured attribute map.
+ * Values are interpolated raw (callers own escaping), matching package policy.
+ * Boolean `true` emits the bare attribute name; `false`/`null`/`undefined` are omitted.
+ */
+export type TagAttributes = string | Record<string, string | number | boolean | null | undefined>;
+
+/**
+ * Build an opening tag with optional attributes.
  * Attributes are interpolated raw (callers own escaping), matching package policy.
  */
-export function openTag(name: string, attributes?: string): string {
-  const attr = attributes?.trim();
+export function openTag(name: string, attributes?: TagAttributes): string {
+  const attr = serializeAttributes(attributes);
   return attr ? `<${name} ${attr}>` : `<${name}>`;
 }
+
+/** Turn a raw string or attribute map into a single attribute string. */
+export function serializeAttributes(attributes?: TagAttributes): string {
+  if (!attributes) return '';
+  if (typeof attributes === 'string') return attributes.trim();
+
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined || value === null || value === false) continue;
+    if (value === true) {
+      parts.push(key);
+    } else {
+      parts.push(`${key}="${String(value)}"`);
+    }
+  }
+  return parts.join(' ');
+}
diff --git a/test/email.test.ts b/test/email.test.ts
index 83a28b4..5ca472d 100644
--- a/test/email.test.ts
+++ b/test/email.test.ts
@@ -138,6 +138,24 @@ describe('renderEmail', () => {
     expect(html.startsWith('<!DOCTYPE html>')).toBe(true);
   });
 
+  it('applies template-level shell defaults, with props winning', () => {
+    const template = defineEmailTemplate({
+      id: 'postmark-like',
+      shell: {
+        doctype:
+          '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+        lang: false,
+        htmlAttributes: { xmlns: 'http://www.w3.org/1999/xhtml' },
+        bodyAttributes: 'style="margin:0"',
+      },
+    });
+    const html = renderEmail(template, { title: 'Hi', bodyAttributes: 'style="padding:0"' }).html;
+    expect(html).toMatch(/^<!DOCTYPE html PUBLIC/);
+    expect(html).toContain('<html xmlns="http://www.w3.org/1999/xhtml">');
+    expect(html).not.toContain('lang=');
+    expect(html).toContain('<body style="padding:0">');
+  });
+
   it('forwards document shell options from EmailProps', () => {
     const html = renderEmail(
       { id: 'styled' },
diff --git a/test/index.test.ts b/test/index.test.ts
index 841dbc5..218147f 100644
--- a/test/index.test.ts
+++ b/test/index.test.ts
@@ -94,6 +94,17 @@ describe('document', () => {
     expect(html).toContain('<title>Postmark</title>');
   });
 
+  it('accepts structured attributes on html and body', () => {
+    const html = document({
+      lang: false,
+      htmlAttributes: { xmlns: 'http://www.w3.org/1999/xhtml', class: 'email' },
+      bodyAttributes: { style: 'margin:0', 'data-theme': 'light' },
+      mainHtml: '<p>Hi</p>',
+    });
+    expect(html).toContain('<html xmlns="http://www.w3.org/1999/xhtml" class="email">');
+    expect(html).toContain('<body style="margin:0" data-theme="light">');
+  });
+
   it('supports body attributes and omitting lang (good-news style)', () => {
     const html = document({
       lang: null,