@unlayer/react-elements 0.1.16 → 0.1.17

package/README.md

@@ -47,6 +47,16 @@ function WelcomeEmail() {
 }
 ```
 
+## Using with AI agents (Claude, Cursor, etc.)
+
+Assembling these templates in code is something AI coding agents do well. The official **`unlayer-elements`** skill teaches them the strict structure, the canonical prop shapes, the image-sizing model, and the patterns that make generated emails actually look good:
+
+```bash
+npx skills add unlayer/unlayer-skills
+```
+
+This installs the `unlayer-elements` skill (alongside the other Unlayer skills). Your agent then knows how to build emails, pages, and documents with these components and render them via `renderToHtml` / `renderToJson`. See [unlayer/unlayer-skills](https://github.com/unlayer/unlayer-skills).
+
 ## Critical Rules
 
 These props have non-obvious shapes that **must** be followed exactly:
@@ -293,7 +303,7 @@ Each wrapper threads the correct mode to all children automatically.
 
 ## renderToHtml
 
-Render any element tree to a clean HTML string — no React hydration markers, perfect for email sending and PDF generation:
+Render any element tree to a complete, ready-to-use HTML document — from `<!DOCTYPE ...>` to `</html>` — with no React hydration markers. Perfect for email sending and PDF generation:
 
 ```tsx
 import { renderToHtml, Email, Row, Column, ColumnLayouts, Paragraph, Button } from '@unlayer/react-elements';
@@ -311,10 +321,18 @@ const html = renderToHtml(
         </Button>
       </Column>
     </Row>
-  </Email>
+  </Email>,
+  { title: "Welcome" }
 );
 ```
 
+The document shell matches the mode: `<Email>` gets the XHTML transitional doctype plus the MSO conditional comments Outlook needs, `<Page>` gets a standard HTML5 shell, and `<Document>` gets a print/PDF-friendly XHTML shell. Options accept config overrides plus:
+
+- `title` — document `<title>`
+- `fonts` — web-font stylesheet URLs to load via `<link>` tags, e.g. `[{ url: "https://fonts.googleapis.com/css2?family=Inter" }]`
+
+If your app owns the document shell (an existing page template, an ESP template, an iframe `srcdoc`), use `renderToHtmlParts` instead — it returns `{ head, body }` chunks for you to place yourself.
+
 ## UnlayerProvider
 
 Configure global settings like CDN base URL, merge tags, text direction, and rendering mode:

package/dist/index.cjs

@@ -198,6 +198,50 @@ function textNodeToHtml(node) {
   }
   return html;
 }
+var NUMERIC_ALIGN = {
+  1: "left",
+  2: "center",
+  3: "right",
+  4: "justify"
+};
+function dirAttribute(direction) {
+  return direction === "ltr" || direction === "rtl" ? ` dir="${direction}"` : "";
+}
+function paragraphAlign(format) {
+  if (typeof format === "string") {
+    return ["left", "center", "right", "justify"].includes(format) ? format : void 0;
+  }
+  if (typeof format === "number") {
+    return NUMERIC_ALIGN[format];
+  }
+  return void 0;
+}
+function paragraphNodeToHtml(node, childrenHtml) {
+  const isInlineTool = !!node.isInlineTool;
+  const tag = isInlineTool ? "span" : "p";
+  const dir = dirAttribute(node.direction);
+  const styleParts = [];
+  if (node.style) {
+    styleParts.push(String(node.style).replace(/;+\s*$/, ""));
+  }
+  if (!isInlineTool) {
+    styleParts.push(
+      "margin: 0px",
+      "margin-block-start: 0px",
+      "margin-block-end: 0px"
+    );
+  }
+  const indent = Number(node.indent) || 0;
+  if (indent > 0) {
+    styleParts.push(`padding-inline-start: ${indent * 40}px`);
+  }
+  const align = paragraphAlign(node.format);
+  if (align) {
+    styleParts.push(`text-align: ${align}`);
+  }
+  const style = styleParts.length > 0 ? ` style="${escapeHtml(styleParts.join("; ") + ";")}"` : "";
+  return `<${tag}${dir}${style}>${childrenHtml || "<br>"}</${tag}>`;
+}
 function nodeToHtml(node) {
   if (!node || typeof node !== "object") return "";
   const type = node.type;
@@ -212,14 +256,11 @@ function nodeToHtml(node) {
     case "root":
       return childrenHtml;
     case "paragraph":
-    case "extended-paragraph": {
-      if (!childrenHtml) return "<p><br></p>";
-      const dir = node.direction ? ` dir="${node.direction}"` : "";
-      return `<p${dir}>${childrenHtml}</p>`;
-    }
+    case "extended-paragraph":
+      return paragraphNodeToHtml(node, childrenHtml);
     case "heading": {
-      const tag = node.tag || "h1";
-      const dir = node.direction ? ` dir="${node.direction}"` : "";
+      const tag = /^h[1-6]$/.test(node.tag) ? node.tag : "h1";
+      const dir = dirAttribute(node.direction);
       return `<${tag}${dir}>${childrenHtml}</${tag}>`;
     }
     case "link": {
@@ -1122,7 +1163,7 @@ function getWidthPercentages(cells) {
     return { value, className };
   });
 }
-function generateGridCSS(cells, mode, contentWidth = 600, mobileBreakpoint = 620) {
+function generateGridCSS(cells, mode, contentWidth = 600, mobileBreakpoint = 480) {
   const widths = getWidthPercentages(cells);
   if (mode === "email") {
     const minQuery = `@media only screen and (min-width: ${contentWidth + 20}px)`;
@@ -1159,21 +1200,14 @@ ${widths.map(({ value, className }) => `  .no-stack .u-col-${className} { width:
   const columnCSS = widths.map(
     ({ value, className }) => `.u-row .u-col.u-col-${className} { flex: 0 0 ${value}%; max-width: ${value}%; }`
   ).join("\n");
-  const responsiveCSS = `
-@media only screen and (max-width: ${mobileBreakpoint}px) {
-  .u-row { width: 100% !important; }
-  .u-row .u-col {
-    display: block !important;
-    width: 100% !important;
-    min-width: 320px !important;
+  const responsiveCSS = mode === "document" ? "" : `
+@media (max-width: ${mobileBreakpoint}px) {
+  .u_row .container { max-width: 100% !important; }
+  .u-row:not(.no-stack) { flex-wrap: wrap; }
+  .u-row:not(.no-stack) .u-col {
+    flex: 0 0 100% !important;
     max-width: 100% !important;
   }
-  .u-row .u-col > div { margin: 0 auto; }
-  .no-stack .u-col {
-    min-width: 0 !important;
-    display: table-cell !important;
-  }
-${widths.map(({ value, className }) => `  .no-stack .u-col-${className} { width: ${value}% !important; }`).join("\n")}
 }`;
   return baseCSS + "\n" + columnCSS + "\n" + responsiveCSS;
 }
@@ -1674,8 +1708,81 @@ function extractHeadFromTree(element, options) {
   };
 }
 
+// src/utils/document-layouts.ts
+function emailLayout(args) {
+  const { dir, titleTag, tagLines, styleTag, scriptTag, fontLinks, body } = args;
+  const head = [
+    titleTag,
+    tagLines,
+    styleTag,
+    scriptTag,
+    fontLinks && `<!--[if !mso]><!-->${fontLinks}<!--<![endif]-->`
+  ].filter(Boolean).join("\n  ");
+  return `<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html${dir} xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<head>
+<!--[if gte mso 9]>
+<xml>
+  <o:OfficeDocumentSettings>
+    <o:AllowPNG/>
+    <o:PixelsPerInch>96</o:PixelsPerInch>
+  </o:OfficeDocumentSettings>
+</xml>
+<![endif]-->
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="x-apple-disable-message-reformatting">
+  <!--[if !mso]><!--><meta http-equiv="X-UA-Compatible" content="IE=edge"><!--<![endif]-->
+  ${head}
+</head>
+${body}
+</html>
+`;
+}
+function documentLayout(args) {
+  const { dir, titleTag, tagLines, styleTag, scriptTag, fontLinks, body } = args;
+  const head = [titleTag, tagLines, styleTag, scriptTag, fontLinks].filter(Boolean).join("\n  ");
+  return `<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html${dir} xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  ${head}
+</head>
+${body}
+</html>
+`;
+}
+function webLayout(args) {
+  const { dir, titleTag, tagLines, styleTag, scriptTag, fontLinks, body } = args;
+  const head = [titleTag, fontLinks, tagLines, styleTag, scriptTag].filter(Boolean).join("\n    ");
+  return `<!doctype html>
+<html${dir}>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="x-ua-compatible" content="ie=edge">
+    <meta name="description" content="">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    ${head}
+  </head>
+  <body>
+${body}
+  </body>
+</html>
+`;
+}
+
 // src/utils/render-to-html.tsx
-function renderToHtml(element, config) {
+var MODE_BY_WRAPPER = {
+  Email: "email",
+  Page: "web",
+  Document: "document"
+};
+function resolveDisplayMode(element, mergedConfig) {
+  const displayName = element.type?.displayName;
+  const wrapperMode = displayName ? MODE_BY_WRAPPER[displayName] : void 0;
+  return wrapperMode ?? element.props.mode ?? mergedConfig.mode ?? "web";
+}
+function renderBody(element, config) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   try {
     const enriched = React__default.default.cloneElement(element, { config: mergedConfig });
@@ -1688,14 +1795,52 @@ Tip: Ensure your tree uses Body > Row > Column > Item structure.`
     );
   }
 }
+function stripOuterDiv(html) {
+  const match = html.match(/^\s*<div[^>]*>([\s\S]*)<\/div>\s*$/);
+  return match ? match[1] : html;
+}
+function escapeForHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderToHtml(element, options) {
+  const { title, fonts = [], ...config } = options ?? {};
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  const displayMode = resolveDisplayMode(element, mergedConfig);
+  const wrapperName = element.type?.displayName;
+  const isUnlayerWrapper = wrapperName === "Body" || (wrapperName ? wrapperName in MODE_BY_WRAPPER : false);
+  const rawBody = renderBody(element, config);
+  const body = isUnlayerWrapper ? stripOuterDiv(rawBody) : rawBody;
+  const { css, js, tags } = extractHeadFromTree(element, {
+    displayMode,
+    headConfig: mergedConfig.headConfig
+  });
+  const layoutArgs = {
+    dir: mergedConfig.textDirection ? ` dir="${escapeForHtml(String(mergedConfig.textDirection))}"` : "",
+    titleTag: title ? `<title>${escapeForHtml(title.trim())}</title>` : "",
+    styleTag: css ? `<style type="text/css">
+${css}
+</style>` : "",
+    scriptTag: js ? `<script type="application/javascript">
+${js}
+</script>` : "",
+    tagLines: tags.join("\n"),
+    fontLinks: fonts.filter((font) => font?.url).map(
+      (font) => `<link href="${escapeForHtml(font.url)}" rel="stylesheet" type="text/css">`
+    ).join(""),
+    body
+  };
+  if (displayMode === "email") return emailLayout(layoutArgs);
+  if (displayMode === "document") return documentLayout(layoutArgs);
+  return webLayout(layoutArgs);
+}
 function renderToPlainText(element, config) {
-  const html = renderToHtml(element, config);
+  const html = renderBody(element, config);
   return htmlToPlainText(html);
 }
 function renderToHtmlParts(element, config) {
-  const body = renderToHtml(element, config);
+  const body = renderBody(element, config);
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
-  const displayMode = element.props.mode ?? mergedConfig.mode ?? "web";
+  const displayMode = resolveDisplayMode(element, mergedConfig);
   const { css, js, tags } = extractHeadFromTree(element, {
     displayMode,
     headConfig: mergedConfig.headConfig