@emabuild/email-renderer 0.3.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -5
- package/dist/index.d.ts +19 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1371 -109
- package/dist/index.js.map +1 -1
- package/dist/layout/document-shell.d.ts +23 -1
- package/dist/layout/document-shell.d.ts.map +1 -1
- package/dist/layout/fluid-hybrid.d.ts +23 -2
- package/dist/layout/fluid-hybrid.d.ts.map +1 -1
- package/dist/layout/web-layout.d.ts +51 -0
- package/dist/layout/web-layout.d.ts.map +1 -0
- package/dist/render.d.ts +101 -1
- package/dist/render.d.ts.map +1 -1
- package/dist/utils/border.d.ts +7 -0
- package/dist/utils/border.d.ts.map +1 -0
- package/dist/utils/css-inliner.d.ts +58 -0
- package/dist/utils/css-inliner.d.ts.map +1 -0
- package/dist/utils/css.d.ts +67 -0
- package/dist/utils/css.d.ts.map +1 -0
- package/dist/utils/dark-mode.d.ts +12 -0
- package/dist/utils/dark-mode.d.ts.map +1 -0
- package/dist/utils/display-condition.d.ts +11 -0
- package/dist/utils/display-condition.d.ts.map +1 -0
- package/dist/utils/html-cleanup.d.ts +20 -0
- package/dist/utils/html-cleanup.d.ts.map +1 -0
- package/dist/utils/html-minifier.d.ts +20 -0
- package/dist/utils/html-minifier.d.ts.map +1 -0
- package/dist/utils/html-sanitizer.d.ts.map +1 -1
- package/dist/utils/html-tokenizer.d.ts +89 -0
- package/dist/utils/html-tokenizer.d.ts.map +1 -0
- package/dist/utils/plain-text.d.ts +52 -0
- package/dist/utils/plain-text.d.ts.map +1 -0
- package/dist/utils/responsive-css.d.ts +16 -0
- package/dist/utils/responsive-css.d.ts.map +1 -1
- package/dist/utils/responsive-overrides.d.ts +61 -0
- package/dist/utils/responsive-overrides.d.ts.map +1 -0
- package/package.json +22 -12
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Standalone email HTML renderer for the [@emabuild](https://www.npmjs.com/package/@emabuild/core) email editor. Converts design JSON into cross-client email HTML.
|
|
4
4
|
|
|
5
|
-
Works in
|
|
5
|
+
Works in browsers, Node.js and Web Workers (no DOM usage) — use it server-side to generate email HTML without the editor UI.
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
@@ -40,15 +40,97 @@ console.log(result.chunks); // { body, css, fonts[], js }
|
|
|
40
40
|
|
|
41
41
|
```typescript
|
|
42
42
|
renderDesignToHtml(design, toolRenderers, {
|
|
43
|
-
minify: true, //
|
|
44
|
-
inlineStyles: true, // Inline
|
|
45
|
-
cleanup: true, // Remove
|
|
43
|
+
minify: true, // Collapse whitespace, strip comments (MSO conditionals kept), minify CSS
|
|
44
|
+
inlineStyles: true, // Inline <style> rules into style attributes (@media, :hover, !important stay)
|
|
45
|
+
cleanup: true, // Remove empty class/style/id and editor-only attributes
|
|
46
46
|
mergeTags: { // Replace {{tag}} with values
|
|
47
47
|
first_name: 'John',
|
|
48
48
|
},
|
|
49
|
+
designTags: { company: 'Acme' }, // Replace design tags ({{company}})
|
|
50
|
+
designTagsDelimiter: ['{{', '}}'], // Design tag delimiters (default)
|
|
51
|
+
title: 'Spring sale', // Document <title> (escaped; default empty)
|
|
52
|
+
displayMode: 'web', // Responsive web page instead of email HTML (default: email)
|
|
49
53
|
});
|
|
50
54
|
```
|
|
51
55
|
|
|
56
|
+
Processing order: render (headers → rows → footers, with `displayCondition` `before`/`after` wrapping) → content `<style>` blocks hoisted into `<head>` → mobile override CSS → web font `<link>`s added → merge tags → design tags (`designTags`, `designTagsDelimiter`, default `['{{','}}']`) → inline styles → cleanup → minify.
|
|
57
|
+
|
|
58
|
+
## Render Cache (fast re-exports)
|
|
59
|
+
|
|
60
|
+
Pass a cache to reuse the HTML of rows that did not change. Rows are keyed by **object identity** (`WeakMap`), so it pays off with immutable, structurally shared designs — like the editor store, where an edit replaces only the touched row/column/content objects.
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
import { renderDesignToHtml, createRenderCache } from '@emabuild/email-renderer';
|
|
64
|
+
|
|
65
|
+
const cache = createRenderCache();
|
|
66
|
+
const renderers = buildToolRenderers(); // keep the SAME Map instance across calls
|
|
67
|
+
|
|
68
|
+
renderDesignToHtml(design, renderers, options, { cache }); // renders every row
|
|
69
|
+
renderDesignToHtml(nextDesign, renderers, options, { cache }); // re-renders only replaced rows
|
|
70
|
+
cache.stats; // { hits, misses }
|
|
71
|
+
cache.clear(); // drop everything
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- 4th argument `{ cache }` (or `options.cache`). Also accepted by `renderDesignToPlainText(design, renderers, options, { cache })`.
|
|
75
|
+
- A cached row is reused only when everything outside it that affects its markup is unchanged: body values handed to the tools (`contentWidth`, `fontFamily`, `textColor`, `linkStyle`, … — `preheaderText` excepted), `displayMode` and the identity of the renderer `Map`.
|
|
76
|
+
- Each row's hoisted `<style>` blocks, fonts and `_override.mobile` rules are cached with it; merge/design tags, inlining, cleanup and minification still run on every call.
|
|
77
|
+
- Contract: don't mutate a row in place after rendering it with a cache (replace the object, or call `cache.clear()`).
|
|
78
|
+
- With a cache, `result.design` is a lazy deep copy (taken on first access).
|
|
79
|
+
|
|
80
|
+
Benchmark (test suite, 200 rows × 3 columns × 3 contents, Apple Silicon): first render ≈ 55–155 ms, re-render after editing one content ≈ 5 ms (4–8 %).
|
|
81
|
+
|
|
82
|
+
## Web Display Mode
|
|
83
|
+
|
|
84
|
+
`displayMode: 'web'` renders a responsive **web page** instead of email tables:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
const { html } = renderDesignToHtml(design, renderers, { displayMode: 'web' });
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- HTML5 document with `<meta charset>` and `<meta name="viewport">`, no MSO conditionals, VML, ghost tables or preheader (Outlook conditional comments emitted by tools are stripped too: hidden blocks dropped, `<!--[if !mso]><!-->` content kept).
|
|
91
|
+
- Rows are `<div class="u_row">` blocks; their `.u_row_inner` is a flex container centred with `max-width: contentWidth`. Columns are flex items sized by the row's `cells` ratio (`flex: <cells> 1 0%`) and stack below `max-width: contentWidth + 20px` (`noStackMobile` rows stay side by side).
|
|
92
|
+
- Plain stylesheet in `<head>`: body background colour/image, text colour, font family, `linkStyle` (`.u_body a`, `a:hover`), `hideDesktop` / `hideMobile` classes, and the same `_override.mobile` rules as the email export (same ids and `v-*` hook classes).
|
|
93
|
+
- Tool renderers receive `ctx.displayMode === 'web'`; their markup (tables are fine) is kept, and email-only CSS sanitizing is skipped (flex, grid, gap… survive).
|
|
94
|
+
- Building blocks: `renderWebRow()`, `wrapInWebShell()`, `getWebCss()`, `stripMsoConditionals()`.
|
|
95
|
+
|
|
96
|
+
## Plain-Text Export
|
|
97
|
+
|
|
98
|
+
Generate the `text/plain` alternative of an email — DOM-free, so it works in Node.js and Web Workers:
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
import { renderPlainText, renderDesignToPlainText } from '@emabuild/email-renderer';
|
|
102
|
+
|
|
103
|
+
const text = renderPlainText(html, {
|
|
104
|
+
wordwrap: 78, // wrap at 78 columns (default: false = no wrapping)
|
|
105
|
+
linkStyle: 'footnote', // 'inline' (default): "Shop now (https://…)"; 'footnote': "Shop now [1]" + URL list
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
// Or straight from the design (accepts ExportOptions such as mergeTags too)
|
|
109
|
+
const text2 = renderDesignToPlainText(design, toolRenderers, { mergeTags: { first_name: 'John' } });
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Rules: `<head>`, `<style>`, `<script>`, comments (MSO-only content) and hidden elements (`display:none`, `mso-hide:all`, `max-height:0` — e.g. the preheader) are dropped; headings become UPPERCASE with blank lines around; paragraphs and content tables are separated by a blank line, `div`/`tr`/`br` by a line break; `<li>` → `- item` (`1. item` in `<ol>`); links and buttons → `text (url)` unless the URL equals the text; images → `[alt]`; entities decoded; whitespace collapsed; at most 2 consecutive blank lines.
|
|
113
|
+
|
|
114
|
+
## Per-Device Overrides (`_override.mobile`)
|
|
115
|
+
|
|
116
|
+
Values stored in `values._override.mobile` of a row or content are exported as `!important` rules inside the mobile media query (`max-width: contentWidth + 20px`), in a single `<style>` block in `<head>` (preserved by inlining and minification). `buildResponsiveOverridesCss(design)` returns that CSS on its own.
|
|
117
|
+
|
|
118
|
+
Markup convention for tool renderers:
|
|
119
|
+
|
|
120
|
+
- The content wrapper carries `id = values.anchor || values._meta.htmlID` (sanitized to `[A-Za-z0-9_:.-]`; `contentElementId()`). If the tool output lacks it, the renderer wraps the content in `<div id="…">` (only when the content has mobile overrides).
|
|
121
|
+
- The element whose CSS comes from value key `<key>` carries class `v-<kebab-key>` (`fontSize` → `v-font-size`, `textAlign` → `v-text-align`, `lineHeight` → `v-line-height`, `color` → `v-color`, `padding` → `v-padding`, `width` → `v-width`; `containerPadding` → `v-container-padding` on the container cell).
|
|
122
|
+
- Generated rule: `#<id> .v-<kebab>, #<id>.v-<kebab> { <prop>: <value> !important; }` where `<prop>` is the kebab-case key (`containerPadding` → `padding`). Numbers get `px` for length keys (`fontSize`, `letterSpacing`, `width`, …).
|
|
123
|
+
- Objects are skipped except `border` (each `borderTopWidth`… side prop on `.v-border`) and `buttonColors` (`backgroundColor` / `color` on `.v-button-colors`).
|
|
124
|
+
- Rows: the `u_row` div gets `id = anchor || _meta.htmlID || u_row_<row.id>` and `v-padding` / `v-background-color` classes; columns without their own background get `v-columns-background-color`. Row rules are `#<rowId>.v-padding`, `#<rowId>.v-background-color`, `#<rowId> .v-columns-background-color` (they never reach the row's contents).
|
|
125
|
+
|
|
126
|
+
## Rows That Don't Stack (`noStackMobile`)
|
|
127
|
+
|
|
128
|
+
Rows with `values.noStackMobile: true` (and more than one column) get class `no-stack`; each column is wrapped in a `.u_column_ns` inline-block with a percentage width, so columns stay side by side on mobile while Outlook keeps the px ghost table.
|
|
129
|
+
|
|
130
|
+
## Body Background Image
|
|
131
|
+
|
|
132
|
+
`body.values.backgroundImage` (`{ url, repeat, center, cover, fullWidth }`) is applied to the `#u_body` wrapper table (`background` attribute + inline `background-image/repeat/position/size`) and to Outlook via a `v:background` VML fill.
|
|
133
|
+
|
|
52
134
|
## Email Client Support
|
|
53
135
|
|
|
54
136
|
The generated HTML uses fluid hybrid design with MSO conditional comments:
|
|
@@ -62,15 +144,30 @@ The generated HTML uses fluid hybrid design with MSO conditional comments:
|
|
|
62
144
|
|
|
63
145
|
| Function | Description |
|
|
64
146
|
|----------|-------------|
|
|
65
|
-
| `renderDesignToHtml()` | Main export: design JSON → full HTML document |
|
|
147
|
+
| `renderDesignToHtml()` | Main export: design JSON → full HTML document (email, or web page with `displayMode: 'web'`) |
|
|
148
|
+
| `createRenderCache()` | Per-row render cache for fast re-exports |
|
|
149
|
+
| `renderWebRow()` / `wrapInWebShell()` / `getWebCss()` | Web display mode building blocks |
|
|
150
|
+
| `stripMsoConditionals()` | Remove Outlook conditional comments from HTML |
|
|
151
|
+
| `renderPlainText()` | Email HTML → plain text (DOM-free) |
|
|
152
|
+
| `renderDesignToPlainText()` | Design JSON → plain text |
|
|
153
|
+
| `buildResponsiveOverridesCss()` | Mobile override CSS for a design's `_override.mobile` values |
|
|
154
|
+
| `overrideDeclarations()` / `contentElementId()` / `rowElementId()` / `kebabKey()` | Building blocks of the override convention |
|
|
155
|
+
| `mobileMediaQuery()` | The mobile media query for a content width |
|
|
66
156
|
| `wrapInDocumentShell()` | Wrap body HTML in email-safe DOCTYPE/head/body |
|
|
67
157
|
| `renderRow()` | Render a single row with fluid hybrid columns |
|
|
68
158
|
| `getResponsiveCss()` | Generate responsive CSS media queries |
|
|
159
|
+
| `inlineCss()` | Inline `<style>` rules into `style` attributes (browser + Node, no deps) |
|
|
160
|
+
| `minifyHtml()` / `minifyCss()` | Email-safe HTML / CSS minification |
|
|
161
|
+
| `cleanupHtml()` | Remove empty and editor-only attributes |
|
|
162
|
+
| `collectFontUrls()` | Distinct web font URLs used by a design |
|
|
163
|
+
| `replaceDesignTags()` | Replace design tags with a custom delimiter |
|
|
164
|
+
| `wrapWithDisplayCondition()` | Wrap HTML with a display condition's `before` / `after` |
|
|
69
165
|
|
|
70
166
|
## Related Packages
|
|
71
167
|
|
|
72
168
|
- [`@emabuild/core`](https://www.npmjs.com/package/@emabuild/core) — Full drag & drop editor Web Component
|
|
73
169
|
- [`@emabuild/types`](https://www.npmjs.com/package/@emabuild/types) — TypeScript type definitions
|
|
170
|
+
- [`@emabuild/export`](https://www.npmjs.com/package/@emabuild/export) — Server-side PNG/JPEG, PDF and ZIP export
|
|
74
171
|
|
|
75
172
|
## License
|
|
76
173
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,24 @@
|
|
|
1
|
-
export { renderDesignToHtml } from './render.js';
|
|
1
|
+
export { renderDesignToHtml, renderDesignToPlainText, createRenderCache } from './render.js';
|
|
2
|
+
export type { RenderOptions, RenderContext, RenderCache, RenderCacheStats } from './render.js';
|
|
3
|
+
export { renderWebRow, wrapInWebShell, getWebCss, stripMsoConditionals } from './layout/web-layout.js';
|
|
4
|
+
export type { WebShellExtras } from './layout/web-layout.js';
|
|
5
|
+
export { renderPlainText, decodeEntities, wrapText } from './utils/plain-text.js';
|
|
6
|
+
export type { PlainTextOptions } from './utils/plain-text.js';
|
|
7
|
+
export { buildResponsiveOverridesCss, overrideDeclarations, overrideClass, kebabKey, contentElementId, rowElementId, getMobileOverrides, } from './utils/responsive-overrides.js';
|
|
8
|
+
export type { OverrideDeclaration } from './utils/responsive-overrides.js';
|
|
2
9
|
export { wrapInDocumentShell } from './layout/document-shell.js';
|
|
10
|
+
export { buildDarkModeCss, hasDarkMode, getDarkOverrides } from './utils/dark-mode.js';
|
|
3
11
|
export { renderRow } from './layout/fluid-hybrid.js';
|
|
4
|
-
export { getResponsiveCss } from './utils/responsive-css.js';
|
|
12
|
+
export { getResponsiveCss, mobileMediaQuery } from './utils/responsive-css.js';
|
|
5
13
|
export { validateEmailHtml } from './utils/html-validator.js';
|
|
6
14
|
export type { ValidationResult, ValidationIssue } from './utils/html-validator.js';
|
|
15
|
+
export { inlineCss } from './utils/css-inliner.js';
|
|
16
|
+
export type { InlineCssOptions } from './utils/css-inliner.js';
|
|
17
|
+
export { minifyHtml } from './utils/html-minifier.js';
|
|
18
|
+
export { minifyCss } from './utils/css.js';
|
|
19
|
+
export { cleanupHtml } from './utils/html-cleanup.js';
|
|
20
|
+
export { wrapWithDisplayCondition } from './utils/display-condition.js';
|
|
21
|
+
export { replaceDesignTags, collectFontUrls } from './render.js';
|
|
22
|
+
export type { DocumentShellExtras } from './layout/document-shell.js';
|
|
23
|
+
export { allRows, documentTitle, documentLanguage, bodyFontWeight, isLanguageCode, cleanCssValue, isSafeCssValue } from '@emabuild/shared';
|
|
7
24
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC7F,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACvG,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAClF,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,2BAA2B,EAC3B,oBAAoB,EACpB,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
|