@templatical/import-beefree 0.52.1 → 0.54.0

package/dist/index.js

@@ -1,4 +1,56 @@
-import { canonicalFontStack, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, generateId } from "@templatical/types";
+import { canonicalFontStack, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, generateId, isLocaleTag, isSafeHtmlUrl, sourceHash } from "@templatical/types";
+// src/localization.ts
+function warn(warnings, message) {
+	if (!warnings.includes(message)) warnings.push(message);
+}
+function localeTag(value, warnings) {
+	const locale = value.replaceAll("_", "-");
+	if (isLocaleTag(locale)) return locale;
+	warn(warnings, `Dropped language "${value}": unsupported language tag.`);
+	return null;
+}
+/** The `defaultLocale` option as a tag; `null`, with a warning, when it isn't one. */
+function defaultLocaleOption(value, warnings) {
+	if (!value) return null;
+	const locale = value.replaceAll("_", "-");
+	if (isLocaleTag(locale)) return locale;
+	warn(warnings, `Ignored defaultLocale "${value}": unsupported language tag. Used "en".`);
+	return null;
+}
+function text(target, locale, path, base, value) {
+	if (base === void 0) {
+		set(target, locale, path, value);
+		return;
+	}
+	const layer = (target.l10n ??= {})[locale] ??= {};
+	(layer.text ??= {})[path] = {
+		value,
+		sourceHash: sourceHash(base)
+	};
+}
+function set(target, locale, path, value) {
+	const layer = (target.l10n ??= {})[locale] ??= {};
+	(layer.set ??= {})[path] = value;
+}
+/** Register only non-default versions, leaving single-language imports unchanged. */
+function registerLocales(content) {
+	const locales = /* @__PURE__ */ new Set();
+	const visit = (target) => {
+		if (!target.l10n) return;
+		delete target.l10n[content.settings.locale];
+		for (const locale of Object.keys(target.l10n)) locales.add(locale);
+		if (Object.keys(target.l10n).length === 0) delete target.l10n;
+	};
+	visit(content.settings);
+	const walk = (blocks) => {
+		for (const block of blocks) {
+			visit(block);
+			if (block.type === "section") block.children.forEach(walk);
+		}
+	};
+	walk(content.blocks);
+	if (locales.size) content.settings.locales = [...locales];
+}
 // src/style-parser.ts
 /**
 * Parses CSS-like style values from BeeFree descriptors.
@@ -69,17 +121,88 @@ function parseColor(value) {
 	}
 	return trimmed;
 }
+/**
+* Whether a CSS colour paints nothing: `transparent`, or an alpha of 0 in a
+* hex (`#rgba`, `#rrggbbaa`) or functional (`rgba()`, `hsl(… / 0%)`) colour.
+*/
+function isTransparentColor(value) {
+	if (!value) return false;
+	const color = value.trim().toLowerCase();
+	if (color === "transparent") return true;
+	const hex = color.match(/^#(?:[0-9a-f]{3}([0-9a-f])|[0-9a-f]{6}([0-9a-f]{2}))$/);
+	if (hex) return /^0+$/.test(hex[1] ?? hex[2]);
+	const fn = color.match(/^(?:rgb|hsl)a?\((.*)\)$/);
+	if (!fn) return false;
+	const alpha = fn[1].includes("/") ? fn[1].split("/")[1] : fn[1].split(",")[3];
+	if (alpha === void 0) return false;
+	const opacity = parseFloat(alpha);
+	return Number.isFinite(opacity) && opacity <= 0;
+}
+const BORDER_STYLES = /* @__PURE__ */ new Set([
+	"none",
+	"hidden",
+	"dotted",
+	"dashed",
+	"solid",
+	"double",
+	"groove",
+	"ridge",
+	"inset",
+	"outset"
+]);
+const BORDER_WIDTH_KEYWORDS = {
+	thin: 1,
+	medium: 3,
+	thick: 5
+};
+/** Split on whitespace outside parentheses, so `rgba(0, 0, 0, 0)` is one part. */
+function splitShorthand(value) {
+	const parts = [];
+	let depth = 0;
+	let current = "";
+	for (const ch of value.trim()) {
+		if (ch === "(") depth++;
+		if (ch === ")") depth = Math.max(0, depth - 1);
+		if (depth === 0 && /\s/.test(ch)) {
+			if (current) parts.push(current);
+			current = "";
+			continue;
+		}
+		current += ch;
+	}
+	if (current) parts.push(current);
+	return parts;
+}
+/**
+* A `border-top` shorthand, its parts in any order. `width` is the room the
+* border takes, so a `none` or `hidden` border has none. `drawn` is false when
+* the border paints nothing: a stated 0 width, a `none` or `hidden` style, or a
+* transparent colour. A shorthand without a width reads as 0 wide but drawn.
+*/
 function parseBorderTop(value) {
 	if (!value) return {
 		width: 0,
 		style: "solid",
-		color: "#000000"
+		color: "#000000",
+		drawn: true
 	};
-	const parts = value.trim().split(/\s+/);
+	let width;
+	let style;
+	let colorPart;
+	for (const part of splitShorthand(value)) {
+		const lower = part.toLowerCase();
+		const length = lower.match(/^(\d+(?:\.\d+)?|\.\d+)(px)?$/);
+		if (width === void 0 && length && (length[2] || Number(length[1]) === 0)) width = Number(length[1]);
+		else if (width === void 0 && Object.hasOwn(BORDER_WIDTH_KEYWORDS, lower)) width = BORDER_WIDTH_KEYWORDS[lower];
+		else if (style === void 0 && BORDER_STYLES.has(lower)) style = lower;
+		else colorPart ??= part;
+	}
+	const hidden = style === "none" || style === "hidden";
 	return {
-		width: parsePxValue(parts[0]),
-		style: parts[1] || "solid",
-		color: parseColor(parts[2]) || "#000000"
+		width: hidden || width === void 0 ? 0 : Math.round(width),
+		style: style ?? "solid",
+		color: parseColor(colorPart) || "#000000",
+		drawn: width !== 0 && !hidden && !isTransparentColor(colorPart)
 	};
 }
 function extractPadding(style) {
@@ -89,14 +212,24 @@ function extractPadding(style) {
 		bottom: 0,
 		left: 0
 	};
-	if (style.padding) return parseShorthandPadding(style.padding);
+	if (style.padding && !hasNegativeLength(style.padding)) return parseShorthandPadding(style.padding);
 	return {
-		top: parsePxValue(style["padding-top"]),
-		right: parsePxValue(style["padding-right"]),
-		bottom: parsePxValue(style["padding-bottom"]),
-		left: parsePxValue(style["padding-left"])
+		top: paddingLonghand(style["padding-top"]),
+		right: paddingLonghand(style["padding-right"]),
+		bottom: paddingLonghand(style["padding-bottom"]),
+		left: paddingLonghand(style["padding-left"])
 	};
 }
+function paddingLonghand(value) {
+	return Math.max(0, parsePxValue(value));
+}
+/**
+* Whether a padding value holds a negative length, read before rounding:
+* `-0.4px` rounds to `-0`, which would pass as valid. A literal `-0` is 0.
+*/
+function hasNegativeLength(value) {
+	return value.trim().split(/\s+/).some((part) => parseFloat(part) < 0);
+}
 function parseShorthandPadding(value) {
 	const values = value.trim().split(/\s+/).map((p) => parsePxValue(p));
 	switch (values.length) {
@@ -350,8 +483,32 @@ const MODULE_TYPE_MAP = {
 	"mailup-bee-newsletter-modules-social": "social",
 	"mailup-bee-newsletter-modules-video": "video",
 	"mailup-bee-newsletter-modules-menu": "menu",
-	"mailup-bee-newsletter-modules-table": "table"
+	"mailup-bee-newsletter-modules-table": "table",
+	"mailup-bee-newsletter-modules-icons": "icons"
 };
+const ADDON_MODULE = "mailup-bee-newsletter-modules-addon";
+const EMPTY_MODULE = "mailup-bee-newsletter-modules-empty";
+/**
+* An addon keeps the payload of the module it stands in for, so the payload it
+* carries names the converter. Checked in this order.
+*/
+const ADDON_PAYLOADS = [
+	["image", "image"],
+	["html", "html"],
+	["heading", "title"],
+	["paragraph", "paragraph"],
+	["text", "paragraph"],
+	["list", "list"],
+	["button", "button"],
+	["divider", "divider"],
+	["menu", "menu"],
+	["iconsList", "icons"]
+];
+/** The converter a module goes to, or `undefined` when there is none. */
+function moduleKind(module) {
+	if (module.type !== ADDON_MODULE) return MODULE_TYPE_MAP[module.type];
+	return ADDON_PAYLOADS.find(([key]) => module.descriptor[key] !== void 0)?.[1];
+}
 const SOCIAL_PLATFORM_MAP = {
 	facebook: "facebook",
 	twitter: "twitter",
@@ -514,32 +671,65 @@ function convertHeading(descriptor, textColor) {
 }
 /**
 * The classes BeeFree records in `computedStyle.class` for an image: its
-* alignment and `autowidth` / `fixedwidth`.
+* alignment, `autowidth` / `fixedwidth`, and in older exports `fullwidth`.
 */
 function computedClasses(descriptor) {
 	const value = descriptor.computedStyle?.class;
 	return typeof value === "string" ? value.trim().split(/\s+/) : [];
 }
 /**
-* The width BeeFree shows an image at, as `ImageBlock.width`. `image.width` and
-* `image.height` are the file's own size: an `autowidth` image fills its
-* column, and a `fixedwidth` one is shown at `computedStyle.width`. An export
-* without `computedStyle` falls back to `image.width`. No width, or one that
+* A px length BeeFree computed: `"172.5px"`, or a bare number in older
+* exports. 0 when it isn't one.
+*/
+function computedPx(value) {
+	if (typeof value === "number") return Number.isFinite(value) && value > 0 ? Math.round(value) : 0;
+	return typeof value === "string" ? parsePxValue(value) : 0;
+}
+/**
+* The width BeeFree shows an image at, as `ImageBlock.width`. BeeFree records
+* it in `computedStyle.width` for both classes: a `fixedwidth` image at the
+* width the author set, an `autowidth` one at its file's width capped at the
+* column. `image.width` and `image.height` are the file's own size, the
+* fallback for an export without `computedStyle`. No width, or one that
 * reaches `room` (the column less the image's side padding), is `"full"`.
+* Older exports class an image that fills its column `fullwidth`, and its
+* computed width leaves out the column padding the import drops, so the class
+* decides. A computed percentage under 100% becomes px of `room`, with a note:
+* px keeps its size on a phone, where the percentage would shrink.
 */
 function resolveImageWidth(descriptor, room) {
-	if (computedClasses(descriptor).includes("autowidth")) return "full";
-	const computed = descriptor.computedStyle?.width;
-	const shown = parsePxValue(typeof computed === "string" ? computed : void 0) || parsePxValue(descriptor.image?.width);
+	if (computedClasses(descriptor).includes("fullwidth")) return { width: "full" };
+	const percent = computedPercent(descriptor.computedStyle?.width);
+	if (percent !== void 0) {
+		if (percent >= 100) return { width: "full" };
+		const width = room === void 0 ? "full" : shownWidth(Math.round(room * percent / 100), room);
+		return {
+			width,
+			note: `Image width ${percent}% was converted to ${width === "full" ? "full width" : `${width}px`}.`
+		};
+	}
+	return { width: shownWidth(computedPx(descriptor.computedStyle?.width) || parsePxValue(descriptor.image?.width), room) };
+}
+/** A percentage BeeFree computed (`"50%"`), or `undefined` when it isn't one. */
+function computedPercent(value) {
+	if (typeof value !== "string") return void 0;
+	const match = /^(\d+(?:\.\d+)?|\.\d+)%$/.exec(value.trim());
+	return match ? parseFloat(match[1]) : void 0;
+}
+/** A shown px width as `ImageBlock.width`: `"full"` when unknown or at `room`. */
+function shownWidth(shown, room) {
 	if (shown <= 0) return "full";
 	return room !== void 0 && shown >= room ? "full" : shown;
 }
 function convertImage(descriptor, columnWidth) {
 	const image = descriptor.image;
 	const styles = makeStyles(descriptor);
-	if (!image) return createImageBlock({ styles });
+	if (!image) return {
+		block: createImageBlock({ styles }),
+		notes: []
+	};
 	const room = columnWidth === void 0 ? void 0 : columnWidth - styles.padding.left - styles.padding.right;
-	const width = resolveImageWidth(descriptor, room);
+	const { width, note } = resolveImageWidth(descriptor, room);
 	const fileWidth = parsePxValue(image.width);
 	const fileHeight = parsePxValue(image.height);
 	const shownWidth = width === "full" ? room : width;
@@ -551,19 +741,22 @@ function convertImage(descriptor, columnWidth) {
 		"center",
 		"right"
 	].find((side) => classes.includes(side));
-	return createImageBlock({
-		src: image.src || "",
-		alt: image.alt || "",
-		width,
-		...fileWidth > 0 && fileHeight > 0 ? {
-			naturalWidth: fileWidth,
-			naturalHeight: fileHeight
-		} : {},
-		borderRadius: parseImageBorderRadius(image.style?.["border-radius"], stated ? shownWidth : void 0, shownHeight),
-		align: toAlign(image.style?.["text-align"] ?? classAlign, "center"),
-		linkUrl: image.href || void 0,
-		styles
-	});
+	return {
+		block: createImageBlock({
+			src: image.src || "",
+			alt: image.alt || "",
+			width,
+			...fileWidth > 0 && fileHeight > 0 ? {
+				naturalWidth: fileWidth,
+				naturalHeight: fileHeight
+			} : {},
+			borderRadius: parseImageBorderRadius(image.style?.["border-radius"], stated ? shownWidth : void 0, shownHeight),
+			align: toAlign(image.style?.["text-align"] ?? classAlign, "center"),
+			linkUrl: image.href || void 0,
+			styles
+		}),
+		notes: note ? [note] : []
+	};
 }
 function convertButton(descriptor) {
 	const button = descriptor.button;
@@ -639,6 +832,35 @@ function dividerAlign(descriptor) {
 	const computed = descriptor.computedStyle?.align;
 	return typeof computed === "string" ? computed : descriptor.style?.["text-align"];
 }
+/**
+* The room a divider that draws no line takes: its top and bottom padding plus
+* the width of a transparent border. `undefined` when the line is drawn.
+* BeeFree templates space content this way.
+*/
+function undrawnDividerHeight(descriptor) {
+	const border = parseBorderTop(descriptor.divider?.style?.["border-top"]);
+	if (border.drawn) return void 0;
+	const padding = extractPadding(descriptor.style);
+	return padding.top + border.width + padding.bottom;
+}
+/**
+* A divider that draws no line, as a spacer of the same height. A spacer
+* renders no padding, so the divider's padding goes into the height.
+*/
+function convertUndrawnDivider(descriptor, height) {
+	return createSpacerBlock({
+		height,
+		styles: {
+			...makeStyles(descriptor),
+			padding: {
+				top: 0,
+				right: 0,
+				bottom: 0,
+				left: 0
+			}
+		}
+	});
+}
 function convertSpacer(descriptor) {
 	const spacer = descriptor.spacer;
 	const height = parsePxValue(spacer?.style?.height) || 24;
@@ -676,13 +898,170 @@ function convertSocial(descriptor, warnings) {
 		styles: makeStyles(descriptor)
 	});
 }
+/** Escape `& < > "` for text content and attribute values. */
+function escapeHtml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+function stringField(value) {
+	return typeof value === "string" ? value : "";
+}
+function iconItems(descriptor) {
+	const icons = descriptor.iconsList?.icons;
+	return Array.isArray(icons) ? icons : [];
+}
+/** The padding BeeFree keeps around each icon, `computedStyle.iconSpacing`. */
+function iconSpacing(descriptor) {
+	const value = descriptor.computedStyle?.iconSpacing;
+	if (typeof value !== "object" || value === null) return extractPadding({});
+	return extractPadding(Object.fromEntries(Object.entries(value).filter(([, side]) => typeof side === "string")));
+}
+/**
+* The height BeeFree draws every icon at, and an icon's width at that height,
+* from its file's size. The width is `undefined` when the size isn't stated.
+*/
+function iconSize(descriptor, item) {
+	const height = computedPx(descriptor.computedStyle?.iconHeight) || 32;
+	const fileWidth = parsePxValue(stringField(item.width));
+	const fileHeight = parsePxValue(stringField(item.height));
+	return {
+		height,
+		width: fileWidth > 0 && fileHeight > 0 ? Math.round(height * fileWidth / fileHeight) : void 0
+	};
+}
+/**
+* A lone icon without text, as an image block at the icon height. `undefined`
+* when the module holds anything else, or the icon's file size is unknown.
+*/
+function convertSingleIcon(descriptor, columnWidth) {
+	const items = iconItems(descriptor);
+	if (items.length !== 1) return void 0;
+	const [item] = items;
+	const src = stringField(item.image);
+	const { width } = iconSize(descriptor, item);
+	if (!src || stringField(item.text) || width === void 0) return void 0;
+	const styles = makeStyles(descriptor);
+	const spacing = iconSpacing(descriptor);
+	const padding = {
+		top: styles.padding.top + spacing.top,
+		right: styles.padding.right + spacing.right,
+		bottom: styles.padding.bottom + spacing.bottom,
+		left: styles.padding.left + spacing.left
+	};
+	const room = columnWidth === void 0 ? void 0 : columnWidth - padding.left - padding.right;
+	return createImageBlock({
+		src,
+		alt: stringField(item.alt),
+		width: shownWidth(width, room),
+		naturalWidth: parsePxValue(stringField(item.width)),
+		naturalHeight: parsePxValue(stringField(item.height)),
+		align: toAlign(descriptor.style?.["text-align"]),
+		linkUrl: stringField(item.href) || void 0,
+		styles: {
+			...styles,
+			padding
+		}
+	});
+}
+/** The module's text style as CSS declarations, for the icons' text cells. */
+function iconTextStyle(style) {
+	const color = parseColor(style.color);
+	const fontFamily = canonicalFontStack(style["font-family"]);
+	const fontSize = parsePxValue(style["font-size"]);
+	const fontWeight = style["font-weight"];
+	return [
+		color ? `color: ${color};` : "",
+		fontFamily ? `font-family: ${fontFamily};` : "",
+		fontSize ? `font-size: ${fontSize}px;` : "",
+		fontWeight ? `font-weight: ${fontWeight};` : ""
+	].filter(Boolean).join(" ");
+}
+/**
+* The Icons module as the table BeeFree draws: the icons side by side, each at
+* the icon height inside its `iconSpacing`, with its text on the side
+* `textPosition` names, in the module's text style.
+*/
+function iconsHtml(descriptor) {
+	const style = descriptor.style ?? {};
+	const computed = descriptor.computedStyle ?? {};
+	const align = toAlign(style["text-align"]);
+	const color = parseColor(style.color);
+	const textStyle = iconTextStyle(style);
+	const gap = computedPx(computed.itemsSpacing) || computedPx(computed.itemSpacing);
+	const spacing = iconSpacing(descriptor);
+	const iconPadding = spacing.top || spacing.right || spacing.bottom || spacing.left ? `padding: ${spacing.top}px ${spacing.right}px ${spacing.bottom}px ${spacing.left}px; ` : "";
+	const items = iconItems(descriptor).map((item, index) => {
+		const position = stringField(item.textPosition);
+		const stacked = position === "top" || position === "bottom";
+		const cellAlign = stacked ? " align=\"center\"" : "";
+		const href = stringField(item.href);
+		const target = stringField(item.target);
+		const link = (inner, linkStyle) => href ? `<a href="${escapeHtml(href)}"${target ? ` target="${escapeHtml(target)}"` : ""} style="${escapeHtml(linkStyle)}">${inner}</a>` : inner;
+		const src = stringField(item.image);
+		const { height, width } = iconSize(descriptor, item);
+		const title = stringField(item.title);
+		const imgStyle = [
+			"display: block;",
+			stacked ? "margin: 0 auto;" : "",
+			width === void 0 ? "" : `width: ${width}px;`,
+			`height: ${height}px;`,
+			"border: 0;"
+		].filter(Boolean).join(" ");
+		const img = `<img src="${escapeHtml(src)}" alt="${escapeHtml(stringField(item.alt))}"${title ? ` title="${escapeHtml(title)}"` : ""}${width === void 0 ? "" : ` width="${width}"`} height="${height}" style="${imgStyle}">`;
+		const iconCell = src ? `<td${cellAlign} style="${iconPadding}vertical-align: middle;">${link(img, "text-decoration: none;")}</td>` : "";
+		const text = stringField(item.text);
+		const textCell = text ? `<td${cellAlign} style="vertical-align: middle;${textStyle ? ` ${escapeHtml(textStyle)}` : ""}">${link(escapeHtml(text), `${color ? `color: ${color}; ` : ""}text-decoration: none;`)}</td>` : "";
+		const body = (position === "top" ? [textCell, iconCell] : position === "bottom" ? [iconCell, textCell] : [position === "left" ? textCell + iconCell : iconCell + textCell]).filter(Boolean).map((row) => `<tr>${row}</tr>`).join("");
+		return `<td style="${index > 0 && gap ? `padding-left: ${gap}px; ` : ""}vertical-align: middle;"><table role="presentation" border="0" cellpadding="0" cellspacing="0" style="border-collapse: collapse;">${body}</table></td>`;
+	});
+	return `<table role="presentation" border="0" cellpadding="0" cellspacing="0"${align === "left" ? "" : ` align="${align}"`} style="border-collapse: collapse;"><tr>${items.join("")}</tr></table>`;
+}
+/**
+* The Icons module's items without the link and image URLs the editor's HTML
+* policy rejects (`javascript:`, `vbscript:`, a non-image `data:`), each named
+* in `warnings`. Both outputs carry these URLs into markup, and an HTML block
+* renders unsanitized.
+*/
+function safeIconItems(descriptor, warnings) {
+	return iconItems(descriptor).map((item) => {
+		const safe = { ...item };
+		const image = stringField(item.image);
+		if (image && !isSafeHtmlUrl(image, "src")) {
+			warnings.push(`Dropped the unsafe image "${image}" on an Icons item.`);
+			safe.image = "";
+		}
+		const href = stringField(item.href);
+		if (href && !isSafeHtmlUrl(href, "href")) {
+			warnings.push(`Dropped the unsafe link "${href}" on an Icons item.`);
+			safe.href = "";
+		}
+		return safe;
+	});
+}
+function convertIcons(descriptor, columnWidth, warnings) {
+	const safe = {
+		...descriptor,
+		iconsList: { icons: safeIconItems(descriptor, warnings) }
+	};
+	const single = convertSingleIcon(safe, columnWidth);
+	if (single) return {
+		block: single,
+		rebuilt: false
+	};
+	return {
+		block: createHtmlBlock({
+			content: iconsHtml(safe),
+			styles: makeStyles(descriptor)
+		}),
+		rebuilt: true
+	};
+}
 function convertVideo(descriptor) {
 	const video = descriptor.video;
 	if (!video) return createVideoBlock({ styles: makeStyles(descriptor) });
 	return createVideoBlock({
 		url: video.src || "",
 		thumbnailUrl: video.thumbnail || "",
-		alt: video.alt || "",
+		alt: video.thumbAlt ?? video.alt ?? "",
 		width: parsePxValue(video.style?.width) || 600,
 		height: parsePxValue(video.style?.height) || void 0,
 		align: toAlign(video.style?.["text-align"], "center"),
@@ -764,8 +1143,8 @@ function convertHtmlFallback(module) {
 * Converts a single BeeFree module to a Templatical block.
 * Returns the block and a report entry.
 */
-function convertModule(module, warnings, context = {}) {
-	const mappedType = MODULE_TYPE_MAP[module.type];
+function convertModuleBase(module, warnings, context = {}) {
+	const mappedType = moduleKind(module);
 	const descriptor = module.descriptor;
 	const textColor = context.textColor ?? "#1a1a1a";
 	if (!mappedType) return {
@@ -774,7 +1153,7 @@ function convertModule(module, warnings, context = {}) {
 			beeFreeModuleType: module.type,
 			templaticalBlockType: "html",
 			status: "html-fallback",
-			note: `Unknown module type "${module.type}" converted to HTML block.`
+			note: module.type === ADDON_MODULE ? "The addon carries no content Templatical reads; converted to an HTML block." : `Unknown module type "${module.type}" converted to HTML block.`
 		}
 	};
 	let block;
@@ -788,13 +1167,23 @@ function convertModule(module, warnings, context = {}) {
 		case "title":
 			block = convertHeading(descriptor, textColor);
 			break;
-		case "image":
-			block = convertImage(descriptor, context.columnWidth);
+		case "image": {
+			const result = convertImage(descriptor, context.columnWidth);
+			block = result.block;
+			notes = result.notes;
+			isApproximation = notes.length > 0;
 			break;
+		}
 		case "button":
 			block = convertButton(descriptor);
 			break;
 		case "divider": {
+			const height = undrawnDividerHeight(descriptor);
+			if (height !== void 0) {
+				block = convertUndrawnDivider(descriptor, height);
+				notes = [`The divider draws no line; imported as a ${height}px spacer.`];
+				break;
+			}
 			const result = convertDivider(descriptor, context.columnWidth);
 			block = result.block;
 			notes = result.notes;
@@ -804,6 +1193,20 @@ function convertModule(module, warnings, context = {}) {
 		case "spacer":
 			block = convertSpacer(descriptor);
 			break;
+		case "icons": {
+			const result = convertIcons(descriptor, context.columnWidth, warnings);
+			if (result.rebuilt) return {
+				block: result.block,
+				entry: {
+					beeFreeModuleType: module.type,
+					templaticalBlockType: "html",
+					status: "html-fallback",
+					note: "Icons module rebuilt as an HTML table."
+				}
+			};
+			block = result.block;
+			break;
+		}
 		case "html":
 			block = convertHtml(descriptor);
 			break;
@@ -847,6 +1250,79 @@ function convertModule(module, warnings, context = {}) {
 		}
 	};
 }
+/**
+* The report entry for a module that imports no block, or `undefined` when it
+* converts: an empty module, an Icons module with no icons, and a divider that
+* draws no line and takes no space.
+*/
+function skippedModuleEntry(module) {
+	const skip = (note) => ({
+		beeFreeModuleType: module.type,
+		templaticalBlockType: null,
+		status: "skipped",
+		note
+	});
+	if (module.type === EMPTY_MODULE) return skip("The module is empty.");
+	switch (moduleKind(module)) {
+		case "icons": return iconItems(module.descriptor).length === 0 ? skip("The Icons module has no icons.") : void 0;
+		case "divider": return undrawnDividerHeight(module.descriptor) === 0 ? skip("The divider draws no line and takes no space.") : void 0;
+		default: return;
+	}
+}
+function convertModule(module, warnings, context = {}) {
+	const result = convertModuleBase(module, warnings, context);
+	const { block } = result;
+	const descriptor = module.descriptor;
+	const payloads = [
+		["heading", descriptor.heading],
+		["text", descriptor.text],
+		["paragraph", descriptor.paragraph],
+		["list", descriptor.list],
+		["button", descriptor.button],
+		["image", descriptor.image],
+		["video", descriptor.video],
+		["menu", descriptor.menu]
+	];
+	const active = payloads.find(([, payload]) => payload !== void 0);
+	const sources = [module.translations, ...payloads.map(([, payload]) => payload?.translations)];
+	for (const translations of sources) for (const [code, values] of Object.entries(translations ?? {})) {
+		const locale = localeTag(code, warnings);
+		if (!locale) continue;
+		if (result.entry.status === "html-fallback" || block.type === "html") {
+			warn(warnings, `Dropped language "${locale}" on module "${module.type}": target converted to HTML fallback.`);
+			continue;
+		}
+		const key = active?.[0];
+		const field = block.type === "title" ? "text" : block.type === "paragraph" ? "html" : block.type === "button" ? "label" : block.type === "image" ? "alt" : block.type === "video" ? "thumbAlt" : block.type === "menu" ? "items" : void 0;
+		for (const unknown of Object.keys(values).filter((name) => name !== field)) warn(warnings, `Dropped language "${locale}" key "${unknown}": no language mapping for this format.`);
+		if (!field || values[field] === void 0) continue;
+		if (block.type === "menu" && Array.isArray(values.items)) {
+			if (values.items.length !== block.items.length) {
+				warn(warnings, `Dropped language "${locale}" menu translation: item count differs from the source.`);
+				continue;
+			}
+			values.items.forEach((item, index) => {
+				for (const key of Object.keys(item ?? {}).filter((key) => key !== "text")) warn(warnings, `Dropped language "${locale}" key "${key}": no language mapping for this format.`);
+				if (typeof item?.text === "string") text(block, locale, `items.${block.items[index].id}.text`, block.items[index].text, item.text);
+			});
+		} else if (key && typeof values[field] === "string") {
+			const translated = convertModuleBase({
+				...module,
+				descriptor: {
+					...descriptor,
+					[key]: {
+						...descriptor[key],
+						[field]: values[field]
+					}
+				}
+			}, [], context).block;
+			if ((block.type === "title" || block.type === "paragraph") && (translated.type === "title" || translated.type === "paragraph")) text(block, locale, "content", block.content, translated.content);
+			if (block.type === "button" && translated.type === "button") text(block, locale, "text", block.text, translated.text);
+			if ((block.type === "image" || block.type === "video") && (translated.type === "image" || translated.type === "video")) text(block, locale, "alt", block.alt, translated.alt ?? "");
+		}
+	}
+	return result;
+}
 // src/converter.ts
 /**
 * Determines the Templatical ColumnLayout from BeeFree column grid values.
@@ -890,6 +1366,11 @@ function columnPixels(layout, bodyWidth) {
 function convertColumnModules(column, context, entries, warnings) {
 	const blocks = [];
 	for (const module of column.modules) {
+		const skipped = skippedModuleEntry(module);
+		if (skipped) {
+			entries.push(skipped);
+			continue;
+		}
 		const { block, entry } = convertModule(module, warnings, context);
 		blocks.push(block);
 		entries.push(entry);
@@ -1017,7 +1498,7 @@ function extractSettings(template) {
 * console.log(report.warnings);
 * ```
 */
-function convertBeeFreeTemplate(template) {
+function convertBeeFreeTemplate(template, options = {}) {
 	if (!template?.page?.rows) throw new Error("Invalid BeeFree template: missing page.rows. Ensure you are passing a valid BeeFree JSON export.");
 	const entries = [];
 	const warnings = [];
@@ -1025,16 +1506,32 @@ function convertBeeFreeTemplate(template) {
 	const webFonts = template.page.body?.webFonts;
 	if (webFonts && webFonts.length > 1) warnings.push(`Template uses ${webFonts.length} web fonts. Only the primary font is preserved; additional fonts may need to be configured via the fonts option.`);
 	const settings = extractSettings(template);
+	const declared = template.page.body?.language?.value ?? template.page.language?.value ?? template.language?.value;
+	settings.locale = (declared ? localeTag(declared, warnings) : null) ?? defaultLocaleOption(options.defaultLocale, warnings) ?? "en";
+	const meta = template.head?.meta;
+	if (typeof meta?.preheader === "string") settings.preheaderText = meta.preheader;
+	for (const [code, values] of Object.entries(meta?.translations ?? {})) {
+		const locale = localeTag(code, warnings);
+		if (!locale) continue;
+		for (const key of Object.keys(values)) if (key === "preheader" && typeof values.preheader === "string") text(settings, locale, "preheaderText", settings.preheaderText, values.preheader);
+		else warn(warnings, `Dropped language "${locale}" metadata "${key}": ${[
+			"subject",
+			"title",
+			"description"
+		].includes(key) ? "the host owns this field" : "no language mapping for this format"}.`);
+	}
 	for (const row of template.page.rows) {
 		if (row.empty) continue;
 		blocks.push(...processRow(row, settings, entries, warnings));
 	}
+	const content = {
+		...createDefaultTemplateContent(),
+		blocks,
+		settings
+	};
+	registerLocales(content);
 	return {
-		content: {
-			...createDefaultTemplateContent(),
-			blocks,
-			settings
-		},
+		content,
 		report: {
 			entries,
 			warnings,