@templatical/renderer 0.44.3 → 0.46.0

package/dist/index.d.ts

@@ -84,9 +84,13 @@ export declare class RenderContext {
    */
   withContainerWidth(width: number): RenderContext;
   /**
-   * Resolve a font family name to include custom font fallbacks.
-   * If the font matches a custom font, returns `'FontName', fallback`.
-   * Otherwise returns the original font family string.
+   * The stack to emit for a block's or the template's `fontFamily`. A stack is
+   * the author's own fallback chain and is emitted as written, as is anything
+   * that doesn't parse as a font. A lone family gets a fallback: a custom
+   * font's own `fallback` (or `defaultFallbackFont`), a built-in's fixed stack,
+   * or, for any other family, `defaultFallbackFont`, so a client without the
+   * face falls back to it rather than to its own default (Times New Roman in
+   * Outlook on Windows). A generic family needs nothing appended.
    */
   resolveFontFamily(fontFamily: string): string;
 }
@@ -170,6 +174,16 @@ export declare function richTextGapClass(gap: number): string;
  */
 export declare function resolveParagraphGap(spacing: number | undefined): number;
 //#endregion
+//#region src/renderers/button.d.ts
+/**
+ * Marks the `mj-button` of a full-width button. MJML gives the button's `<a>`
+ * a width only for a px `width`; for `100%` it widens the `<table>` and leaves
+ * the `<a>` at `display:inline-block`, so only the label is clickable.
+ * `renderToMjml` scopes the head rule that makes the `<a>` fill the button to
+ * this class.
+ */
+export declare const BUTTON_FULL_WIDTH_CSS_CLASS = "tpl-button-full";
+//#endregion
 //#region src/columns.d.ts
 /**
  * Get width percentages for each column in a layout.

package/dist/index.js

@@ -1,17 +1,7 @@
-import { HEADING_LEVEL_FONT_SIZE, RICH_TEXT_SPACING, applyLayout, assertNoSlotInContent, assertNoWrapperInContent, findOpenTagEnd, getTagAttrValue, isButton, isCustomBlock, isDivider, isHtml, isImage, isMenu, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, isWrapper, resolveContentDirection, toBorderDeclarations, toBorderRadiusCss } from "@templatical/types";
+import { BUILT_IN_FONT_STACKS, HEADING_LEVEL_FONT_SIZE, RICH_TEXT_SPACING, applyLayout, assertNoSlotInContent, assertNoWrapperInContent, findOpenTagEnd, getTagAttrValue, isButton, isCustomBlock, isDivider, isGenericFontFamily, isHtml, isImage, isMenu, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, isWrapper, parseFontFamilies, quoteFontFamily, resolveContentDirection, socialIconAssetDir, toBorderDeclarations, toBorderRadiusCss } from "@templatical/types";
 //#endregion
 //#region src/render-context.ts
-const DEFAULT_SOCIAL_ICONS_BASE_URL = `https://cdn.jsdelivr.net/npm/@templatical/renderer@0.44.3/assets/social`;
-const BUILT_IN_FONT_FALLBACKS = {
-	arial: "Arial, sans-serif",
-	helvetica: "Helvetica, sans-serif",
-	georgia: "Georgia, serif",
-	"times new roman": "'Times New Roman', serif",
-	verdana: "Verdana, sans-serif",
-	"trebuchet ms": "'Trebuchet MS', sans-serif",
-	"courier new": "'Courier New', monospace",
-	tahoma: "Tahoma, sans-serif"
-};
+const DEFAULT_SOCIAL_ICONS_BASE_URL = `https://cdn.jsdelivr.net/npm/@templatical/renderer@0.46.0/assets/social`;
 /**
 * Immutable context passed through the block rendering chain.
 */
@@ -42,18 +32,27 @@ var RenderContext = class RenderContext {
 		return new RenderContext(width, this.customFonts, this.defaultFallbackFont, this.allowHtmlBlocks, this.customBlockHtml, this.socialIconsBaseUrl, this.blockRenderers, this.contentDirection);
 	}
 	/**
-	* Resolve a font family name to include custom font fallbacks.
-	* If the font matches a custom font, returns `'FontName', fallback`.
-	* Otherwise returns the original font family string.
+	* The stack to emit for a block's or the template's `fontFamily`. A stack is
+	* the author's own fallback chain and is emitted as written, as is anything
+	* that doesn't parse as a font. A lone family gets a fallback: a custom
+	* font's own `fallback` (or `defaultFallbackFont`), a built-in's fixed stack,
+	* or, for any other family, `defaultFallbackFont`, so a client without the
+	* face falls back to it rather than to its own default (Times New Roman in
+	* Outlook on Windows). A generic family needs nothing appended.
 	*/
 	resolveFontFamily(fontFamily) {
-		for (const customFont of this.customFonts) if (customFont.name.toLowerCase() === fontFamily.toLowerCase()) {
+		const families = parseFontFamilies(fontFamily);
+		if (families.length !== 1) return fontFamily;
+		const [family] = families;
+		const key = family.name.toLowerCase();
+		for (const customFont of this.customFonts) if (customFont.name.toLowerCase() === key) {
 			const fallback = customFont.fallback ?? this.defaultFallbackFont;
 			return `'${customFont.name}', ${fallback}`;
 		}
-		const builtIn = BUILT_IN_FONT_FALLBACKS[fontFamily.toLowerCase()];
+		const builtIn = BUILT_IN_FONT_STACKS[key];
 		if (builtIn) return builtIn;
-		return fontFamily;
+		if (isGenericFontFamily(family)) return fontFamily;
+		return `${quoteFontFamily(family.name)}, ${this.defaultFallbackFont}`;
 	}
 };
 //#endregion
@@ -177,6 +176,18 @@ function escapeCssValue(text) {
 	if (text === "") return "";
 	return escapeAttr(text).replace(/[;{}\r\n]/g, "");
 }
+const FONT_FAMILY_ENTITY_REGEX = /[&<>"]/g;
+/**
+* Escape a font stack for a double-quoted `font-family="…"` MJML attribute.
+* A `"`-quoted family (`"Helvetica Neue", Arial`) must not end the attribute,
+* or the compiler reads it as empty. Unlike `escapeAttr`, single quotes are
+* left alone: they can't end a double-quoted attribute, and they're how the
+* renderer quotes families itself (`'Times New Roman', serif`), so every
+* stack without `&<>"` is emitted byte-for-byte.
+*/
+function escapeFontFamily(text) {
+	return text.replace(FONT_FAMILY_ENTITY_REGEX, (char) => HTML_ENTITIES[char] ?? char);
+}
 /**
 * Replace merge tag span elements with their data attribute values.
 * Converts `<span data-merge-tag="{{name}}">Label</span>` to `{{name}}`.
@@ -442,7 +453,7 @@ function unwrapParagraph(html) {
 }
 function renderFontFamilyAttr$3(fontFamily, context) {
 	if (!fontFamily) return "";
-	return ` font-family="${context.resolveFontFamily(fontFamily)}"`;
+	return ` font-family="${escapeFontFamily(context.resolveFontFamily(fontFamily))}"`;
 }
 //#endregion
 //#region src/renderers/paragraph.ts
@@ -495,6 +506,14 @@ function renderImage(block, context) {
 //#endregion
 //#region src/renderers/button.ts
 /**
+* Marks the `mj-button` of a full-width button. MJML gives the button's `<a>`
+* a width only for a px `width`; for `100%` it widens the `<table>` and leaves
+* the `<a>` at `display:inline-block`, so only the label is clickable.
+* `renderToMjml` scopes the head rule that makes the `<a>` fill the button to
+* this class.
+*/
+const BUTTON_FULL_WIDTH_CSS_CLASS = "tpl-button-full";
+/**
 * Render a button block to MJML markup.
 */
 function renderButton(block, context) {
@@ -512,7 +531,7 @@ function renderButton(block, context) {
 	const targetAttr = block.openInNewTab ? " target=\"_blank\" rel=\"noopener\"" : "";
 	const fontFamilyAttr = renderFontFamilyAttr$2(block.fontFamily, context);
 	const widthAttr = renderWidthAttr(block.width);
-	const visibilityAttr = getCssClassAttr(block);
+	const cssClassAttr = getCssClassAttr(block, block.width === "full" ? [BUTTON_FULL_WIDTH_CSS_CLASS] : []);
 	return `<mj-button${hrefAttr}${targetAttr}
   background-color="${backgroundColor}"
   color="${textColor}"
@@ -521,7 +540,7 @@ function renderButton(block, context) {
   border-radius="${borderRadius}"${borderAttr(block.border)}
   inner-padding="${buttonPadding}"
   align="${block.align ?? "center"}"
-  padding="${padding}"${bgColor}${fontFamilyAttr}${widthAttr}${visibilityAttr}
+  padding="${padding}"${bgColor}${fontFamilyAttr}${widthAttr}${cssClassAttr}
 >${text}</mj-button>`;
 }
 /**
@@ -534,7 +553,7 @@ function buttonBackgroundAttr(color) {
 }
 function renderFontFamilyAttr$2(fontFamily, context) {
 	if (!fontFamily) return "";
-	return ` font-family="${context.resolveFontFamily(fontFamily)}"`;
+	return ` font-family="${escapeFontFamily(context.resolveFontFamily(fontFamily))}"`;
 }
 /**
 * The button has always emitted its radius, `0px` included, so a plain number
@@ -603,13 +622,14 @@ ${content}
 /**
 * Render a social icons block to MJML markup.
 *
-* Icons are emitted as `<img src="…/{style}/{platform}.png">` rather than
+* Icons are emitted as `<img src="…/{dir}/{platform}.png">` rather than
 * inline SVG or base64 data URIs. Outlook desktop (Word rendering engine)
 * does not support SVG and rejects base64 in `<img src>`, so hosted PNGs are
 * the only format that renders across every mainstream client. The base URL
 * is read from `context.socialIconsBaseUrl` (configurable via
 * `RenderOptions.socialIconsBaseUrl`; default is the version-pinned jsDelivr
-* mirror of this package).
+* mirror of this package). `{dir}` is the style, plus `-{tone}` for a
+* one-color tone (`socialIconAssetDir`).
 */
 function renderSocialIcons(block, context) {
 	if (isHiddenOnAll(block)) return "";
@@ -621,6 +641,7 @@ function renderSocialIcons(block, context) {
 	const align = block.align;
 	const iconSize = block.iconSize;
 	const iconStyle = block.iconStyle;
+	const assetDir = socialIconAssetDir(iconStyle, block.iconTone);
 	const spacing = block.spacing;
 	let iconSizePx;
 	switch (iconSize) {
@@ -655,7 +676,7 @@ function renderSocialIcons(block, context) {
 ${icons.map((icon, index) => {
 		const platform = icon.platform;
 		const url = escapeAttr(icon.url);
-		const iconSrc = `${context.socialIconsBaseUrl}/${iconStyle}/${platform}.png`;
+		const iconSrc = `${context.socialIconsBaseUrl}/${assetDir}/${platform}.png`;
 		const rightPad = index === iconCount - 1 ? 0 : spacing;
 		return `<mj-social-element src="${iconSrc}" href="${url}" icon-size="${iconSizePx}px" padding="0 ${rightPad}px 0 0" border-radius="${borderRadius}" background-color="transparent"></mj-social-element>`;
 	}).join("\n")}
@@ -709,7 +730,7 @@ function renderMenuItem(item, linkColor) {
 }
 function renderFontFamilyAttr$1(fontFamily, context) {
 	if (!fontFamily) return "";
-	return ` font-family="${context.resolveFontFamily(fontFamily)}"`;
+	return ` font-family="${escapeFontFamily(context.resolveFontFamily(fontFamily))}"`;
 }
 //#endregion
 //#region src/renderers/table.ts
@@ -762,7 +783,7 @@ function renderCell(cell, block, isHeader, borderColor, borderWidth) {
 }
 function renderFontFamilyAttr(fontFamily, context) {
 	if (!fontFamily) return "";
-	return ` font-family="${context.resolveFontFamily(fontFamily)}"`;
+	return ` font-family="${escapeFontFamily(context.resolveFontFamily(fontFamily))}"`;
 }
 //#endregion
 //#region src/renderers/custom.ts
@@ -960,6 +981,19 @@ function renderBlock(block, context) {
 //#endregion
 //#region src/index.ts
 /**
+* Makes a full-width button's whole fill clickable. MJML sizes a button's `<a>`
+* only for a px width, so without this rule the link of a `100%` button stays
+* the size of its label.
+*
+* It sits in the inline `<mj-style>` so `mjml`'s juice pass writes it onto the
+* `<a>`; MRML's default build emits that block as a plain `<style>` instead.
+* `!important` lets it beat MJML's inline `display:inline-block` either way.
+* Every template carries it, so nothing has to walk the tree for full-width
+* buttons: juice drops a rule that matches nothing, so with `mjml` it costs
+* nothing in the compiled HTML.
+*/
+const BUTTON_FULL_WIDTH_RULE = `.${BUTTON_FULL_WIDTH_CSS_CLASS} a { display: block !important; }`;
+/**
 * Render template content to an MJML string.
 *
 * The function is async because resolving custom blocks may require
@@ -990,7 +1024,7 @@ async function renderToMjml(content, options) {
 	return `<mjml lang="${escapeAttr(toRender.settings.locale)}" dir="${escapeAttr(contentDirection)}">
   <mj-head>${previewTag}
     <mj-attributes>
-      <mj-all font-family="${fontFamily}" />
+      <mj-all font-family="${escapeFontFamily(fontFamily)}" />
       <mj-text font-size="14px"${textColorAttr} />
       <mj-section padding="0" />
       <mj-column padding="0" />
@@ -998,6 +1032,7 @@ async function renderToMjml(content, options) {
     </mj-attributes>${fontDeclarations}
     <mj-style inline="inline">
       ${richTextStylesheet(collectParagraphGaps(blocks), contentDirection)}
+      ${BUTTON_FULL_WIDTH_RULE}
     </mj-style>
     <mj-style>
       a { color: ${linkColor}; text-decoration: ${linkDecoration}; }
@@ -1139,6 +1174,6 @@ function renderCustomBlockStylesheets(stylesheets) {
 	return stylesheets.map((css) => `\n    <mj-style>\n${css}\n    </mj-style>`).join("");
 }
 //#endregion
-export { DEFAULT_SOCIAL_ICONS_BASE_URL, RICH_TEXT_CSS_CLASS, RenderContext, UNRENDERABLE_MARKER_PREFIX, convertMergeTagsToValues, escapeAttr, escapeHtml, getCssClassAttr, getCssClasses, getWidthPercentages, getWidthPixels, isHiddenOnAll, renderBlock, renderToMjml, renderUnrenderableBlock, resolveParagraphGap, richTextGapClass, toPaddingString };
+export { BUTTON_FULL_WIDTH_CSS_CLASS, DEFAULT_SOCIAL_ICONS_BASE_URL, RICH_TEXT_CSS_CLASS, RenderContext, UNRENDERABLE_MARKER_PREFIX, convertMergeTagsToValues, escapeAttr, escapeHtml, getCssClassAttr, getCssClasses, getWidthPercentages, getWidthPixels, isHiddenOnAll, renderBlock, renderToMjml, renderUnrenderableBlock, resolveParagraphGap, richTextGapClass, toPaddingString };
 
 //# sourceMappingURL=index.js.map