@templatical/import-mjml 0.46.0 → 0.48.0

package/dist/index.d.ts

@@ -14,7 +14,7 @@ type ConversionStatus = "converted" | "approximated" | "html-fallback" | "skippe
  * A single entry in the import report.
  */
 interface ImportReportEntry {
-  /** The source MJML tag name (e.g. "mj-section", "mj-image", "mj-hero"). */
+  /** The source MJML tag name (e.g. "mj-section", "mj-image", "mj-carousel"). */
   sourceTag: string;
   /** The Templatical block type produced, or null if skipped. */
   templaticalBlockType: string | null;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { load } from "cheerio";
-import { BORDER_SIDES, DEFAULT_TEMPLATE_DEFAULTS, RICH_TEXT_SPACING, SOCIAL_ICON_STYLES, SOCIAL_ICON_TONES, SYNTAX_PRESETS, canonicalFontStack, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, generateId, resolveContentDirection } from "@templatical/types";
+import { BORDER_SIDES, DEFAULT_TEMPLATE_DEFAULTS, RICH_TEXT_SPACING, SOCIAL_ICON_STYLES, SOCIAL_ICON_TONES, SYNTAX_PRESETS, canonicalFontStack, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, generateId, resolveContentDirection, resolveHero } from "@templatical/types";
 import { isTag, isText } from "domhandler";
 //#region src/attribute-resolver.ts
 /**
@@ -470,6 +470,280 @@ function parseBorderStyle(value) {
 	if (v === "dashed" || v === "dotted") return v;
 	return "solid";
 }
+const X_GRID = [
+	"left",
+	"center",
+	"right"
+];
+const Y_GRID = [
+	"top",
+	"center",
+	"bottom"
+];
+const PERCENT = /^(-?(?:\d+(?:\.\d+)?|\.\d+))%$/;
+const LENGTH = /^-?(?:\d+(?:\.\d+)?|\.\d+)[a-z]*$/;
+/** What MJML paints for a `background-*` attribute an `mj-section` / `mj-wrapper` leaves out. */
+const MJML_BACKGROUND_DEFAULTS = {
+	size: "auto",
+	x: "center",
+	y: "top",
+	repeat: true
+};
+/**
+* `background-size` as a keyword. A size with a side at 100%, or a px width
+* spanning the box, fills it as `cover` does; any other length or percentage
+* draws the image at a size of its own, which `auto` is closest to.
+*/
+function backgroundSizeKeyword(raw, boxWidth) {
+	const parts = raw.toLowerCase().split(/\s+/);
+	const [first] = parts;
+	if (parts.length === 1 && (first === "cover" || first === "contain")) return {
+		size: first,
+		exact: true
+	};
+	if (parts.every((part) => part === "auto")) return {
+		size: "auto",
+		exact: true
+	};
+	const px = /^(\d+(?:\.\d+)?|\.\d+)px$/.exec(first);
+	return {
+		size: parts.includes("100%") || px !== null && boxWidth !== void 0 && Number(px[1]) >= boxWidth ? "cover" : "auto",
+		exact: false
+	};
+}
+/**
+* `background-position` split into x and y the way MJML and CSS read it: a
+* lone `top` / `bottom` names y and centres x, any other lone value is x
+* with y centred, and a pair is x then y unless it leads with `top` /
+* `bottom` (or with `center` before `left` / `right`). Three- and four-value
+* edge offsets keep their edge keywords only.
+*/
+function splitBackgroundPosition(raw) {
+	const parts = raw.toLowerCase().split(/\s+/);
+	if (parts.length === 1) {
+		const [only] = parts;
+		return only === "top" || only === "bottom" ? {
+			x: "center",
+			y: only,
+			exact: true
+		} : {
+			x: only,
+			y: "center",
+			exact: true
+		};
+	}
+	if (parts.length === 2) {
+		const [a, b] = parts;
+		return a === "top" || a === "bottom" || a === "center" && (b === "left" || b === "right") ? {
+			x: b,
+			y: a,
+			exact: true
+		} : {
+			x: a,
+			y: b,
+			exact: true
+		};
+	}
+	return {
+		x: parts.find((part) => part === "left" || part === "right") ?? "center",
+		y: parts.find((part) => part === "top" || part === "bottom") ?? "center",
+		exact: false
+	};
+}
+/**
+* One axis as a grid point: its keyword; the point nearest a percentage,
+* ties going to the centre; or the start edge for a length, which is an
+* offset from it. `null` when the token is unreadable.
+*/
+function backgroundAxisPoint(token, grid) {
+	const keyword = grid.find((point) => point === token);
+	if (keyword) return {
+		point: keyword,
+		exact: true
+	};
+	const percent = PERCENT.exec(token);
+	if (percent) {
+		const n = Number(percent[1]);
+		return {
+			point: n < 25 ? grid[0] : n > 75 ? grid[2] : grid[1],
+			exact: n === 0 || n === 50 || n === 100
+		};
+	}
+	if (LENGTH.test(token)) return {
+		point: grid[0],
+		exact: parseFloat(token) === 0
+	};
+	return null;
+}
+/**
+* `background-repeat`: unrepeated only when every axis is `no-repeat`.
+* Anything but plain `repeat` tiles too, inexactly.
+*/
+function backgroundRepeatFlag(raw) {
+	const parts = raw.toLowerCase().split(/\s+/);
+	if (parts.every((part) => part === "no-repeat")) return {
+		repeat: false,
+		exact: true
+	};
+	return {
+		repeat: true,
+		exact: parts.every((part) => part === "repeat")
+	};
+}
+/**
+* An `mj-section` / `mj-wrapper` background image, `null` when
+* `background-url` is absent or blank. `read` returns an attribute's
+* resolved value. Unset attributes take MJML's own defaults, so the import
+* paints what MJML painted; a value with no exact keyword takes the nearest
+* one and adds a note naming it. `label` names the element in each note, and
+* a px `background-size` is measured against `boxWidth`.
+*/
+function readMjmlBackgroundImage(read, label, boxWidth) {
+	const url = (read("background-url") ?? "").trim();
+	if (!url) return null;
+	const notes = [];
+	const lossy = (name, raw, shown) => {
+		notes.push(`${label} ${name} "${raw}" has no exact Templatical equivalent; imported as "${shown}".`);
+	};
+	let size = MJML_BACKGROUND_DEFAULTS.size;
+	const rawSize = read("background-size")?.trim();
+	if (rawSize) {
+		const parsed = backgroundSizeKeyword(rawSize, boxWidth);
+		size = parsed.size;
+		if (!parsed.exact) lossy("background-size", rawSize, size);
+	}
+	let x = MJML_BACKGROUND_DEFAULTS.x;
+	let y = MJML_BACKGROUND_DEFAULTS.y;
+	let lossyX = false;
+	let lossyY = false;
+	const rawPosition = read("background-position")?.trim();
+	if (rawPosition) {
+		const split = splitBackgroundPosition(rawPosition);
+		const readX = backgroundAxisPoint(split.x, X_GRID);
+		const readY = backgroundAxisPoint(split.y, Y_GRID);
+		x = readX?.point ?? x;
+		y = readY?.point ?? y;
+		lossyX = !split.exact || !readX?.exact;
+		lossyY = !split.exact || !readY?.exact;
+	}
+	const rawX = read("background-position-x")?.trim();
+	const overrideX = rawX ? backgroundAxisPoint(rawX.toLowerCase(), X_GRID) : null;
+	if (overrideX) {
+		x = overrideX.point;
+		lossyX = false;
+	}
+	const rawY = read("background-position-y")?.trim();
+	const overrideY = rawY ? backgroundAxisPoint(rawY.toLowerCase(), Y_GRID) : null;
+	if (overrideY) {
+		y = overrideY.point;
+		lossyY = false;
+	}
+	if (rawPosition && (lossyX || lossyY)) lossy("background-position", rawPosition, `${x} ${y}`);
+	if (rawX && !overrideX?.exact) lossy("background-position-x", rawX, x);
+	if (rawY && !overrideY?.exact) lossy("background-position-y", rawY, y);
+	let repeat = MJML_BACKGROUND_DEFAULTS.repeat;
+	const rawRepeat = read("background-repeat")?.trim();
+	if (rawRepeat) {
+		const parsed = backgroundRepeatFlag(rawRepeat);
+		repeat = parsed.repeat;
+		if (!parsed.exact) lossy("background-repeat", rawRepeat, repeat ? "repeat" : "no-repeat");
+	}
+	return {
+		image: {
+			url,
+			size,
+			position: {
+				x,
+				y
+			},
+			repeat
+		},
+		notes
+	};
+}
+const HERO_ALIGNS = [
+	"top",
+	"middle",
+	"bottom"
+];
+const HERO_DROPPED_ATTRIBUTES = [
+	"inner-padding",
+	"inner-padding-top",
+	"inner-padding-right",
+	"inner-padding-bottom",
+	"inner-padding-left",
+	"inner-background-color"
+];
+/**
+* An `mj-hero`'s mode, height and background, taking MJML's defaults for what
+* it leaves out (`fixed-height`, `0px`, `center center`, `vertical-align:
+* top`). mj-hero always paints its image `cover` and unrepeated and has no
+* position longhands, so those are fixed rather than read.
+* `background-width` / `background-height` are stored as the image's
+* `naturalWidth` / `naturalHeight`, though they are often the hero box's size
+* (Templatical's renderer writes them so) rather than the file's: only their
+* ratio is used. A `fixed-height` hero without a positive `height` is as
+* tall as its content — exactly what a regular section with the same
+* background paints — so it comes back without `hero`.
+*
+* Templatical's renderer writes "match image" as `fixed-height`: the image
+* drawn across the hero box (`background-width` = `boxWidth`) and the box at
+* the image's own height, or at the hero's `verticalPadding` where the image
+* is shorter. That exact shape comes back as `height: "image"`, which
+* re-renders identically.
+*/
+function readMjmlHero(read, label, boxWidth, verticalPadding) {
+	const notes = [];
+	const background = readMjmlBackgroundImage((name) => {
+		if (name === "background-size") return "cover";
+		if (name === "background-repeat") return "no-repeat";
+		if (name === "background-position") return read(name) ?? "center center";
+		if (name === "background-position-x" || name === "background-position-y") return;
+		return read(name);
+	}, label, boxWidth);
+	if (background) notes.push(...background.notes);
+	const width = parseDefinitePx(read("background-width"));
+	const height = parseDefinitePx(read("background-height"));
+	const sized = width !== null && height !== null && width > 0 && height > 0;
+	const image = background ? {
+		...background.image,
+		...sized ? {
+			naturalWidth: width,
+			naturalHeight: height
+		} : {}
+	} : null;
+	const rawAlign = read("vertical-align")?.trim();
+	const verticalAlign = HERO_ALIGNS.find((align) => align === rawAlign?.toLowerCase()) ?? "top";
+	if (rawAlign && verticalAlign !== rawAlign.toLowerCase()) notes.push(`${label} vertical-align "${rawAlign}" has no Templatical equivalent; imported as "top".`);
+	const rawMode = read("mode")?.trim();
+	const mode = rawMode ? rawMode.toLowerCase() : "fixed-height";
+	let hero = null;
+	if (mode === "fluid-height") {
+		hero = {
+			height: "image",
+			verticalAlign
+		};
+		if (!sized) notes.push(`${label} fluid-height has no background-width / background-height, so its image size is unknown; it renders as a regular section until it has a size or a fixed height.`);
+	} else {
+		if (mode !== "fixed-height") notes.push(`${label} mode "${rawMode}" has no Templatical equivalent; imported as "fixed-height".`);
+		const fixed = parseDefinitePx(read("height"));
+		if (fixed !== null && fixed > 0) hero = {
+			height: sized && width === boxWidth && fixed === Math.max(height, verticalPadding) ? "image" : Math.round(fixed),
+			verticalAlign
+		};
+	}
+	if (hero && !image) notes.push(`${label} has no background-url, so it renders as a regular section until it has a background image.`);
+	for (const name of HERO_DROPPED_ATTRIBUTES) {
+		const raw = read(name);
+		if (raw === void 0) continue;
+		notes.push(`${label} ${name} "${raw.trim()}" has no Templatical equivalent; dropped.`);
+	}
+	return {
+		hero,
+		image,
+		notes
+	};
+}
 //#endregion
 //#region src/block-base.ts
 /**
@@ -501,6 +775,63 @@ function baseFields(attrs, placement = "container") {
 	};
 }
 /**
+* The width side padding and side borders take from a box, read from the
+* element's own attributes exactly as MJML reads them when it sizes the box
+* (`getBoxWidths`): `padding-left` / `-right` over the `padding` shorthand and
+* `border-left` / `-right` over `border`, each as a whole pixel (`parseInt`).
+* Read from the source rather than the converted block, whose padding and
+* border widths are rounded, so a room matches MJML's to the pixel.
+*/
+function mjmlHorizontalInset(attrs) {
+	const border = (side) => {
+		const raw = attrs[`border-${side}`] || attrs.border || "0";
+		const width = /(?:^| )(\d+)/.exec(raw);
+		return width ? parseInt(width[1], 10) : 0;
+	};
+	return mjmlPaddingSide(attrs, "left") + mjmlPaddingSide(attrs, "right") + border("left") + border("right");
+}
+/**
+* Top plus bottom padding, read from the element's own attributes exactly as
+* MJML reads them when it sizes a fixed-height hero's cell: `padding-top` /
+* `-bottom` over the `padding` shorthand, each as a whole pixel.
+*/
+function mjmlVerticalPadding(attrs) {
+	return mjmlPaddingSide(attrs, "top") + mjmlPaddingSide(attrs, "bottom");
+}
+/** One side's padding as MJML's `getShorthandAttrValue` reads it. */
+function mjmlPaddingSide(attrs, side) {
+	const own = attrs[`padding-${side}`];
+	if (own) return parseInt(own, 10) || 0;
+	return attrs.padding ? shorthandSide(attrs.padding, side) : 0;
+}
+/** Which value of a 2-, 3- or 4-value shorthand each side takes. */
+const SHORTHAND_INDEX = {
+	2: {
+		top: 0,
+		right: 1,
+		bottom: 0,
+		left: 1
+	},
+	3: {
+		top: 0,
+		right: 1,
+		bottom: 2,
+		left: 1
+	},
+	4: {
+		top: 0,
+		right: 1,
+		bottom: 2,
+		left: 3
+	}
+};
+/** One side of a CSS padding shorthand, as MJML's `shorthandParser` reads it. */
+function shorthandSide(value, side) {
+	const parts = value.trim().replace(/\s+/g, " ").split(" ", 4);
+	const index = SHORTHAND_INDEX[parts.length]?.[side];
+	return parseInt(index === void 0 ? value : parts[index], 10) || 0;
+}
+/**
 * `border-radius` as a `BorderRadiusValue`, `undefined` when the attribute is
 * absent. A value with no px reading is square corners, `0`, and pushes a
 * note: `label` names the element in it.
@@ -1134,11 +1465,7 @@ const STRUCTURAL_TAGS = /* @__PURE__ */ new Set([
 	"mj-navbar-link"
 ]);
 /** Tags with no Templatical equivalent that keep their markup verbatim. */
-const NO_EQUIVALENT_TAGS = /* @__PURE__ */ new Set([
-	"mj-hero",
-	"mj-carousel",
-	"mj-accordion"
-]);
+const NO_EQUIVALENT_TAGS = /* @__PURE__ */ new Set(["mj-carousel", "mj-accordion"]);
 function convertImage($el, attrs, ctx) {
 	const src = (attrs.src ?? "").trim();
 	if (!src) return null;
@@ -1149,11 +1476,15 @@ function convertImage($el, attrs, ctx) {
 	const notes = [];
 	const borderRadius = readBorderRadius(attrs, "Image", notes);
 	const border = readBorder(attrs, "Image", notes);
+	const base = baseFields(attrs);
+	const room = Math.floor(ctx.contentWidth) - mjmlHorizontalInset(attrs);
+	const width = !pxWidth || pxWidth >= room ? "full" : pxWidth;
+	if ((attrs["fluid-on-mobile"] ?? "").trim().toLowerCase() === "true" && width !== "full") notes.push(`fluid-on-mobile on a ${width}px image narrower than its column has no Templatical equivalent: the image keeps its width on phones instead of filling the column.`);
 	return {
 		block: createImageBlock({
 			src,
 			alt: decorative ? "" : attrs.alt ?? "",
-			width: pxWidth === ctx.containerWidth ? "full" : pxWidth || "full",
+			width,
 			align: parseAlignment(attrs.align, "center"),
 			...height > 0 ? { height } : {},
 			...borderRadius ? { borderRadius } : {},
@@ -1161,7 +1492,7 @@ function convertImage($el, attrs, ctx) {
 			...href ? { linkUrl: href } : {},
 			...href && isNewTab(attrs) ? { linkOpenInNewTab: true } : {},
 			...decorative ? { decorative: true } : {},
-			...baseFields(attrs)
+			...base
 		}),
 		entry: {
 			sourceTag: "mj-image",
@@ -1630,6 +1961,22 @@ const COLUMN_COUNT = {
 	"2-1": 2,
 	"1-2": 2
 };
+/**
+* Column percentages per layout, exactly as `getWidthPercentages` in
+* `renderer/src/columns.ts` emits them. MJML sizes a column from the emitted
+* string, so 33.33% of 600 is 199, not a third.
+*/
+const COLUMN_PERCENTS = {
+	"1": [100],
+	"2": [50, 50],
+	"3": [
+		33.33,
+		33.33,
+		33.34
+	],
+	"1-2": [33.33, 66.67],
+	"2-1": [66.67, 33.33]
+};
 /** Column pixel widths per layout, mirroring `renderer/src/columns.ts`. */
 function columnPixels(layout, containerWidth) {
 	switch (layout) {
@@ -1683,12 +2030,12 @@ function convertColumnChildren($column, ctx, entries) {
 	const blocks = [];
 	for (const unit of planSiblings(childElements($column, ctx.$))) {
 		const tag = tagOf(unit.$el[0]);
-		if (tag === "mj-section" || tag === "mj-wrapper") {
+		if (tag === "mj-section" || tag === "mj-wrapper" || tag === "mj-hero") {
 			const attrs = resolveAttributes(unit.$el, ctx.cascade);
 			const fallback = convertHtmlFallback(unit.$el, ctx, attrs);
 			if (unit.displayCondition) fallback.displayCondition = unit.displayCondition;
 			blocks.push(fallback);
-			const noun = tag === "mj-section" ? "section" : "wrapper";
+			const noun = tag === "mj-section" ? "section" : tag === "mj-hero" ? "hero" : "wrapper";
 			entries.push({
 				sourceTag: tag,
 				templaticalBlockType: "html",
@@ -1738,6 +2085,10 @@ function buildSection($el, ctx, entries, wrapper) {
 	const notes = exact ? [] : [`Column widths ${shown} have no exact Templatical layout; resolved to "${layout}".`];
 	const borderRadius = readBorderRadius(attrs, "Section", notes);
 	const border = readBorder(attrs, "Section", notes);
+	const background = readMjmlBackgroundImage((name) => attrs[name], "Section", ctx.containerWidth);
+	if (background) notes.push(...background.notes);
+	const sectionFields = baseFields(attrs, "native");
+	const sectionBox = Math.floor(ctx.contentWidth) - mjmlHorizontalInset(attrs);
 	entries.push({
 		sourceTag: "mj-section",
 		templaticalBlockType: "section",
@@ -1751,6 +2102,7 @@ function buildSection($el, ctx, entries, wrapper) {
 		const columnCtx = {
 			...ctx,
 			containerWidth: Math.round(pixels[slot] ?? ctx.containerWidth),
+			contentWidth: Math.floor(sectionBox * COLUMN_PERCENTS[layout][slot] / 100),
 			columnPadding: left + right
 		};
 		children[slot].push(...convertColumnChildren($column, columnCtx, entries));
@@ -1761,8 +2113,53 @@ function buildSection($el, ctx, entries, wrapper) {
 		...grouped ? { stackOnMobile: false } : {},
 		...borderRadius ? { borderRadius } : {},
 		...border ? { border } : {},
+		...background ? { backgroundImage: background.image } : {},
+		...wrapper ? { wrapper } : {},
+		...sectionFields
+	})];
+}
+/**
+* Build a one-column `SectionBlock` from an `mj-hero`, whose content elements
+* sit directly under it (no `mj-column`). Its mode, height and background map
+* onto `hero` and `backgroundImage` (`readMjmlHero`). mj-hero paints white
+* where its source sets no `background-color`, so an absent colour imports as
+* `#ffffff`; an explicit `transparent` stays unset.
+*/
+function buildHero($el, ctx, entries, wrapper) {
+	const attrs = resolveAttributes($el, ctx.cascade);
+	const notes = [];
+	const heroBox = Math.floor(ctx.contentWidth);
+	const read = readMjmlHero((name) => attrs[name], "Hero", heroBox, mjmlVerticalPadding(attrs));
+	notes.push(...read.notes);
+	const borderRadius = readBorderRadius(attrs, "Hero", notes);
+	entries.push({
+		sourceTag: "mj-hero",
+		templaticalBlockType: "section",
+		status: notes.length > 0 ? "approximated" : "converted",
+		...notes.length > 0 ? { note: notes.join(" ") } : {}
+	});
+	const fields = baseFields(attrs, "native");
+	const heroPadding = mjmlHorizontalInset(attrs);
+	const applied = resolveHero({
+		columns: "1",
+		hero: read.hero ?? void 0,
+		backgroundImage: read.image ?? void 0
+	})?.applied;
+	const children = convertColumnChildren($el, {
+		...ctx,
+		containerWidth: applied ? heroBox : ctx.containerWidth,
+		contentWidth: heroBox - heroPadding,
+		columnPadding: heroPadding
+	}, entries);
+	if (attrs["background-color"] === void 0) fields.styles.backgroundColor = "#ffffff";
+	return [createSectionBlock({
+		columns: "1",
+		children: [children],
+		...borderRadius ? { borderRadius } : {},
+		...read.image ? { backgroundImage: read.image } : {},
+		...read.hero ? { hero: read.hero } : {},
 		...wrapper ? { wrapper } : {},
-		...baseFields(attrs, "native")
+		...fields
 	})];
 }
 const WRAPPER_BORDER_ATTRIBUTES = [
@@ -1776,19 +2173,37 @@ const WRAPPER_BORDER_ATTRIBUTES = [
 * `SectionWrapper` has no border, so each `border` or `border-<side>` the
 * wrapper sets pushes a note instead.
 */
-function readWrapper(attrs, notes) {
+function readWrapper(attrs, notes, boxWidth) {
 	const backgroundColor = parseColor(attrs["background-color"]);
 	const padding = parsePaddingShorthand(attrs.padding);
 	const borderRadius = readBorderRadius(attrs, "Wrapper", notes);
+	const background = readMjmlBackgroundImage((name) => attrs[name], "Wrapper", boxWidth);
 	for (const name of WRAPPER_BORDER_ATTRIBUTES) {
 		const raw = attrs[name];
 		if (raw === void 0) continue;
 		notes.push(`Wrapper ${name} "${raw.trim()}" has no Templatical equivalent; dropped.`);
 	}
+	if (background) notes.push(...background.notes);
 	return {
 		...backgroundColor ? { backgroundColor } : {},
 		padding,
-		...borderRadius ? { borderRadius } : {}
+		...borderRadius ? { borderRadius } : {},
+		...background ? { backgroundImage: background.image } : {}
+	};
+}
+/**
+* Each section gets its own band object and band image, so editing one
+* section's image leaves the others alone. `padding` and `borderRadius` stay
+* shared, as in the other importers.
+*/
+function copyWrapper(wrapper) {
+	const image = wrapper.backgroundImage;
+	return {
+		...wrapper,
+		...image ? { backgroundImage: {
+			...image,
+			position: { ...image.position }
+		} } : {}
 	};
 }
 /**
@@ -1801,14 +2216,17 @@ function readWrapper(attrs, notes) {
 function buildWrapper($el, ctx, entries) {
 	const attrs = resolveAttributes($el, ctx.cascade);
 	const notes = [];
-	const wrapper = readWrapper(attrs, notes);
-	const sections = childElements($el, ctx.$).filter(($k) => tagOf($k[0]) === "mj-section");
+	const wrapper = readWrapper(attrs, notes, ctx.containerWidth);
+	const sections = childElements($el, ctx.$).filter(($k) => {
+		const tag = tagOf($k[0]);
+		return tag === "mj-section" || tag === "mj-hero";
+	});
 	if (sections.length === 0) {
 		entries.push({
 			sourceTag: "mj-wrapper",
 			templaticalBlockType: null,
 			status: "skipped",
-			note: "An <mj-wrapper> with no <mj-section> children produces nothing."
+			note: "An <mj-wrapper> with no <mj-section> or <mj-hero> children produces nothing."
 		});
 		return [];
 	}
@@ -1819,7 +2237,11 @@ function buildWrapper($el, ctx, entries) {
 		status: "approximated",
 		note: notes.join(" ")
 	});
-	return sections.flatMap(($section) => buildSection($section, ctx, entries, wrapper));
+	const bandCtx = {
+		...ctx,
+		contentWidth: Math.floor(ctx.contentWidth) - mjmlHorizontalInset(attrs)
+	};
+	return sections.flatMap(($section) => tagOf($section[0]) === "mj-hero" ? buildHero($section, bandCtx, entries, copyWrapper(wrapper)) : buildSection($section, bandCtx, entries, copyWrapper(wrapper)));
 }
 //#endregion
 //#region src/converter.ts
@@ -1854,9 +2276,9 @@ function walkBody($body, ctx, entries) {
 	};
 	for (const unit of planSiblings(childElements($body, ctx.$))) {
 		const tag = tagOf(unit.$el[0]);
-		if (tag === "mj-wrapper" || tag === "mj-section") {
+		if (tag === "mj-wrapper" || tag === "mj-section" || tag === "mj-hero") {
 			flushLoose();
-			const produced = tag === "mj-wrapper" ? buildWrapper(unit.$el, ctx, entries) : buildSection(unit.$el, ctx, entries);
+			const produced = tag === "mj-wrapper" ? buildWrapper(unit.$el, ctx, entries) : tag === "mj-hero" ? buildHero(unit.$el, ctx, entries) : buildSection(unit.$el, ctx, entries);
 			for (const block of produced) {
 				if (unit.displayCondition) block.displayCondition = unit.displayCondition;
 				blocks.push(block);
@@ -1907,6 +2329,7 @@ function convertMjmlTemplate(mjml) {
 		$,
 		cascade,
 		containerWidth: settings.width,
+		contentWidth: settings.width,
 		columnPadding: 0,
 		direction: resolveContentDirection(settings),
 		warnings