@templatical/import-html 0.52.1 → 0.54.0

package/dist/index.d.ts

@@ -37,6 +37,10 @@ interface ImportResult {
   content: import("@templatical/types").TemplateContent;
   report: ImportReport;
 }
+interface ConvertHtmlOptions {
+  /** Used when the source declares no default language. */
+  defaultLocale?: string;
+}
 /**
  * Converts an HTML email template to Templatical TemplateContent.
  *
@@ -60,6 +64,6 @@ interface ImportResult {
  * console.log(report.warnings);
  * ```
  */
-export declare function convertHtmlTemplate(html: string): ImportResult;
-export type { ConversionStatus, ImportReport, ImportReportEntry, ImportResult };
+export declare function convertHtmlTemplate(html: string, options?: ConvertHtmlOptions): ImportResult;
+export type { ConversionStatus, ConvertHtmlOptions, ImportReport, ImportReportEntry, ImportResult };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,5 @@
 import { load } from "cheerio";
-import { canonicalFontStack, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createParagraphBlock, createSectionBlock, createSpacerBlock, createTitleBlock } from "@templatical/types";
+import { canonicalFontStack, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createParagraphBlock, createSectionBlock, createSpacerBlock, createTitleBlock, isLocaleTag } from "@templatical/types";
 import { isTag, isText } from "domhandler";
 // src/style-parser.ts
 /**
@@ -155,10 +155,11 @@ function parseLegacyColor(value) {
 	return /^(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(bare) ? parseColor(`#${bare}`) : "";
 }
 /**
-* Parses a CSS `padding` shorthand (1-4 values) into a SpacingValue.
+* Parses a CSS `padding` shorthand (1-4 values) into a SpacingValue. One with
+* a negative side is no padding, since CSS drops the declaration.
 */
 function parsePaddingShorthand(value) {
-	if (!value) return {
+	if (!value || hasNegativeLength(value)) return {
 		top: 0,
 		right: 0,
 		bottom: 0,
@@ -193,16 +194,37 @@ function parsePaddingShorthand(value) {
 	}
 }
 /**
+* A padding longhand's px length as written, `0` included, or `undefined` when
+* it doesn't parse or is negative, which makes CSS drop the declaration.
+* Trimmed first so the pattern has one way to match.
+*/
+function explicitPx(value) {
+	const trimmed = (value ?? "").trim();
+	if (ZERO_LENGTH.test(trimmed)) return 0;
+	const match = /^(-?\d+(?:\.\d+)?)(?:px)?$/i.exec(trimmed);
+	if (!match) return void 0;
+	const px = parseFloat(match[1]);
+	return px < 0 ? void 0 : Math.round(px);
+}
+/**
+* Whether a padding value holds a negative length, judged 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);
+}
+/**
 * Reads CSS padding from a style record, preferring the longhand props
-* (padding-top/right/bottom/left) and falling back to the `padding` shorthand.
+* (padding-top/right/bottom/left), `0` included, and falling back to the
+* `padding` shorthand for a side whose longhand is absent or doesn't parse.
 */
 function readPaddingFromStyles(styles) {
 	const shorthand = parsePaddingShorthand(styles.padding);
 	return {
-		top: parsePxValue(styles["padding-top"]) || shorthand.top,
-		right: parsePxValue(styles["padding-right"]) || shorthand.right,
-		bottom: parsePxValue(styles["padding-bottom"]) || shorthand.bottom,
-		left: parsePxValue(styles["padding-left"]) || shorthand.left
+		top: explicitPx(styles["padding-top"]) ?? shorthand.top,
+		right: explicitPx(styles["padding-right"]) ?? shorthand.right,
+		bottom: explicitPx(styles["padding-bottom"]) ?? shorthand.bottom,
+		left: explicitPx(styles["padding-left"]) ?? shorthand.left
 	};
 }
 /**
@@ -224,46 +246,133 @@ function parseAlignment(value, fallback = "left") {
 	return fallback;
 }
 /**
-* Parses a CSS `border` shorthand (`"1px solid #ccc"`) into width/style/color.
-* Order-tolerant: each token is classified by content.
-*/
-function parseBorderShorthand(value) {
-	const fallback = {
-		width: 0,
-		style: "solid",
-		color: "#000000"
-	};
-	if (!value) return fallback;
-	const styleKeywords = /* @__PURE__ */ new Set([
-		"none",
-		"hidden",
-		"dotted",
-		"dashed",
-		"solid",
-		"double",
-		"groove",
-		"ridge",
-		"inset",
-		"outset"
-	]);
-	let width = 0;
-	let style = "solid";
-	let color = "#000000";
-	for (const token of value.trim().split(/\s+/)) {
+* Whether a CSS colour paints nothing: `transparent`, or an alpha of 0 in a
+* hex (`#rgba`, `#rrggbbaa`) or functional (`rgba()`, `hsl(… / 0%)`) colour.
+* `parseColor` drops the alpha, so ask this before it.
+*/
+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_STYLE_KEYWORDS = /* @__PURE__ */ new Set([
+	"none",
+	"hidden",
+	"dotted",
+	"dashed",
+	"solid",
+	"double",
+	"groove",
+	"ridge",
+	"inset",
+	"outset"
+]);
+const BORDER_WIDTH_TOKEN = /^-?\d+(?:\.\d+)?(?:px)?$/i;
+/**
+* A zero length: `0`, or zero in a CSS length unit, with an optional sign. Run
+* on a trimmed value; each run of zeros has one way to match, so a long run
+* fails in linear time.
+*/
+const ZERO_LENGTH = new RegExp(`^[+-]?(?:0+(?:\\.0+)?|\\.0+)(?:${[
+	"px",
+	"cm",
+	"mm",
+	"q",
+	"in",
+	"pt",
+	"pc",
+	"em",
+	"rem",
+	"ex",
+	"rex",
+	"cap",
+	"rcap",
+	"ch",
+	"rch",
+	"ic",
+	"ric",
+	"lh",
+	"rlh",
+	"vw",
+	"vh",
+	"vi",
+	"vb",
+	"vmin",
+	"vmax",
+	"svw",
+	"svh",
+	"svi",
+	"svb",
+	"svmin",
+	"svmax",
+	"lvw",
+	"lvh",
+	"lvi",
+	"lvb",
+	"lvmin",
+	"lvmax",
+	"dvw",
+	"dvh",
+	"dvi",
+	"dvb",
+	"dvmin",
+	"dvmax",
+	"cqw",
+	"cqh",
+	"cqi",
+	"cqb",
+	"cqmin",
+	"cqmax"
+].join("|")})?$`, "i");
+/**
+* One side of a border: a `border` / `border-top` shorthand (`"1px solid
+* #ccc"`, its parts in any order) with that side's longhands applied over it.
+* `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. Nothing stated reads as
+* drawn.
+*/
+function parseBorderSide(shorthand, longhands = {}) {
+	let widthToken;
+	let styleToken;
+	let colorToken;
+	for (const token of cssTokens((shorthand ?? "").trim())) {
 		const lower = token.toLowerCase();
-		if (styleKeywords.has(lower)) style = lower;
-		else if (/^-?\d+(?:\.\d+)?(?:px)?$/i.test(lower)) width = parsePxValue(lower);
-		else {
-			const c = parseColor(lower);
-			if (c) color = c;
-		}
+		if (BORDER_STYLE_KEYWORDS.has(lower)) styleToken = lower;
+		else if (BORDER_WIDTH_TOKEN.test(lower) || ZERO_LENGTH.test(lower)) widthToken = lower;
+		else if (isTransparentColor(lower) || parseColor(lower)) colorToken = lower;
 	}
+	widthToken = longhands.width?.trim().toLowerCase() ?? widthToken;
+	styleToken = longhands.style?.trim().toLowerCase() ?? styleToken;
+	colorToken = longhands.color?.trim().toLowerCase() ?? colorToken;
+	const style = styleToken ?? "solid";
+	const hidden = style === "none" || style === "hidden";
+	const transparent = isTransparentColor(colorToken);
+	const zeroWidth = widthToken !== void 0 && ZERO_LENGTH.test(widthToken);
 	return {
-		width,
+		width: hidden ? 0 : parsePxValue(widthToken),
 		style,
-		color
+		color: !transparent && parseColor(colorToken) || "#000000",
+		drawn: !zeroWidth && !hidden && !transparent
 	};
 }
+/**
+* The top or bottom value of a 1–4 value box property, such as
+* `border-width: 0 0 1px` (bottom `1px`). `undefined` when it isn't set.
+*/
+function boxSideValue(value, side) {
+	const parts = cssTokens((value ?? "").trim());
+	if (parts.length === 0) return void 0;
+	return side === "top" ? parts[0] : parts[2] ?? parts[0];
+}
 const X_GRID = [
 	"left",
 	"center",
@@ -1532,15 +1641,102 @@ function dividerAlign($el) {
 	return isAuto(left) ? "right" : "left";
 }
 /**
+* One side of an `<hr>`'s border: `border-<side>`, else the `border`
+* shorthand, with `border-<side>-width/-style/-color` and the
+* `border-width/-style/-color` box values applied over it. `declared` is false
+* when nothing sets that side.
+*/
+function hrSide(styles, side) {
+	const shorthand = styles[`border-${side}`] ?? styles.border;
+	const longhands = {
+		width: styles[`border-${side}-width`] ?? boxSideValue(styles["border-width"], side),
+		style: styles[`border-${side}-style`] ?? boxSideValue(styles["border-style"], side),
+		color: styles[`border-${side}-color`] ?? boxSideValue(styles["border-color"], side)
+	};
+	const declared = shorthand !== void 0 || Object.values(longhands).some((value) => value !== void 0);
+	return {
+		...parseBorderSide(shorthand, longhands),
+		declared
+	};
+}
+/**
+* The border that draws an `<hr>`'s line: the top border when it draws, else
+* a drawn bottom border, the common `border: 0; border-bottom: 1px solid #ccc`
+* email `<hr>`. With neither declared, the top reads as the browser's default
+* line.
+*/
+function hrBorder(styles) {
+	const top = hrSide(styles, "top");
+	if (top.declared && top.drawn) return top;
+	const bottom = hrSide(styles, "bottom");
+	return bottom.declared && bottom.drawn ? bottom : top;
+}
+/**
+* The line an `<hr>`'s background draws, the usual email `<hr>`
+* (`border: 0; height: 1px; background: #ccc`): its colour and `height`.
+* `undefined` when the background is unset or transparent, or the height is 0.
+*/
+function hrBackgroundLine(styles) {
+	const raw = styles["background-color"] ?? backgroundShorthandColor(styles.background);
+	if (!raw || isTransparentColor(raw)) return void 0;
+	const color = parseColor(raw);
+	const thickness = parsePxValue(styles.height);
+	return color && thickness > 0 ? {
+		color,
+		thickness
+	} : void 0;
+}
+/** An element's top and bottom margins in px, from the shorthand and longhands. */
+function verticalMargins(styles) {
+	const parts = (styles.margin ?? "").trim().split(/\s+/).filter(Boolean);
+	const top = parts[0] ?? "";
+	const bottom = parts.length >= 3 ? parts[2] : top;
+	return {
+		top: parsePxValue(styles["margin-top"] ?? top),
+		bottom: parsePxValue(styles["margin-bottom"] ?? bottom)
+	};
+}
+/**
+* The room an `<hr>` that draws nothing takes: its vertical margins and
+* padding, its `height` and the widths of transparent top and bottom borders,
+* never below 0 (negative margins pull content up; a spacer can't). CSS drops
+* a negative padding or height, so neither counts. `undefined` when a border
+* or its background draws a line. An `<hr>` with no border styles draws the
+* browser's default line.
+*/
+function undrawnHrHeight($el) {
+	const styles = getStyles$1($el);
+	if (hrBorder(styles).drawn || hrBackgroundLine(styles)) return void 0;
+	const margin = verticalMargins(styles);
+	const padding = readPaddingFromStyles(styles);
+	return Math.max(0, margin.top + padding.top + hrSide(styles, "top").width + Math.max(0, parsePxValue(styles.height)) + hrSide(styles, "bottom").width + padding.bottom + margin.bottom);
+}
+/**
+* The report entry for an element that imports no block, or `undefined` when
+* it converts: an `<hr>` that draws nothing and takes no space.
+*/
+function skippedElementEntry($el, $) {
+	const { $el: $target } = resolveWrappedBlock($el, $);
+	if (tagOf($target[0]) !== "hr" || undrawnHrHeight($target) !== 0) return;
+	return {
+		sourceTag: "hr",
+		templaticalBlockType: null,
+		status: "skipped",
+		note: "The divider draws no line and takes no space."
+	};
+}
+/**
 * <hr> → Divider block, with a note for each thing the block does not keep.
+* The line is the top border, or the background when the border draws nothing.
 *
 * Templatical centres every divider, so a partial one the source places at
 * either side is reported. A full-width line has no placement to lose.
 */
 function convertDivider($el, room) {
 	const styles = getStyles$1($el);
-	const border = parseBorderShorthand(styles["border-top"] ?? styles.border);
-	const lineStyle = border.style === "dashed" || border.style === "dotted" ? border.style : "solid";
+	const border = hrBorder(styles);
+	const background = border.drawn ? void 0 : hrBackgroundLine(styles);
+	const lineStyle = !background && (border.style === "dashed" || border.style === "dotted") ? border.style : "solid";
 	const notes = [];
 	const width = readDividerWidth($el, room, notes);
 	const align = dividerAlign($el);
@@ -1548,8 +1744,8 @@ function convertDivider($el, room) {
 	return {
 		block: createDividerBlock({
 			lineStyle,
-			color: border.color || "#e5e7eb",
-			thickness: border.width || 1,
+			color: background?.color ?? (border.color || "#e5e7eb"),
+			thickness: background?.thickness ?? (border.width || 1),
 			width,
 			styles: { padding: readPaddingFromStyles(styles) }
 		}),
@@ -1704,6 +1900,24 @@ function convertElement($el, $, room) {
 		};
 	}
 	if (tag === "hr") {
+		const height = undrawnHrHeight($target);
+		if (height !== void 0) return {
+			block: createSpacerBlock({
+				height,
+				styles: { padding: {
+					top: 0,
+					right: 0,
+					bottom: 0,
+					left: 0
+				} }
+			}),
+			entry: {
+				sourceTag: tag,
+				templaticalBlockType: "spacer",
+				status: "converted",
+				note: `The divider draws no line; imported as a ${height}px spacer.`
+			}
+		};
 		const { block, notes } = convertDivider($target, room);
 		return {
 			block,
@@ -2522,6 +2736,11 @@ function extractContentBlocks($host, $, entries, warnings, room) {
 			blocks.push(...extractContentBlocks($child, $, entries, warnings, inner));
 			return;
 		}
+		const skipped = skippedElementEntry($child, $);
+		if (skipped) {
+			entries.push(skipped);
+			return;
+		}
 		const r = convertElement($child, $, inner);
 		if (r) {
 			entries.push(r.entry);
@@ -2652,6 +2871,26 @@ function processTable($table, $, entries, warnings, flattenInline = false, enclo
 	return sections;
 }
 // src/converter.ts
+/**
+* The default language: the source's tag, else `defaultLocale`, else
+* `"en"`. A value that isn't a language tag after `_` → `-` is skipped,
+* with a warning naming it.
+*/
+function defaultLanguage(declared, defaultLocale, warnings) {
+	const rejected = [];
+	let locale = "en";
+	for (const [value, name] of [[declared, "the source's default language"], [defaultLocale, "defaultLocale"]]) {
+		if (!value) continue;
+		const tag = value.replaceAll("_", "-");
+		if (isLocaleTag(tag)) {
+			locale = tag;
+			break;
+		}
+		rejected.push(`Ignored ${name} "${value}": unsupported language tag.`);
+	}
+	for (const message of rejected) warnings.push(`${message} Used "${locale}".`);
+	return locale;
+}
 function emptyPadding() {
 	return {
 		top: 0,
@@ -2769,6 +3008,11 @@ function processBody($, entries, warnings, bodyWidth) {
 				walkContainer($inner);
 				return;
 			}
+			const skipped = skippedElementEntry($inner, $);
+			if (skipped) {
+				entries.push(skipped);
+				return;
+			}
 			const r = convertElement($inner, $, bodyWidth);
 			if (r) {
 				entries.push(r.entry);
@@ -2789,6 +3033,11 @@ function processBody($, entries, warnings, bodyWidth) {
 			flushLoose();
 			return;
 		}
+		const skipped = skippedElementEntry($child, $);
+		if (skipped) {
+			entries.push(skipped);
+			return;
+		}
 		const r = convertElement($child, $, bodyWidth);
 		if (r) {
 			entries.push(r.entry);
@@ -2831,7 +3080,7 @@ function pageImageWarning($) {
 * console.log(report.warnings);
 * ```
 */
-function convertHtmlTemplate(html) {
+function convertHtmlTemplate(html, options = {}) {
 	if (typeof html !== "string") throw new Error("Invalid HTML template: expected a string. Pass the raw HTML source as a string.");
 	if (html.trim().length === 0) throw new Error("Invalid HTML template: input is empty. Pass the raw HTML source of an email.");
 	const $ = load(html);
@@ -2841,6 +3090,7 @@ function convertHtmlTemplate(html) {
 	const entries = [];
 	const warnings = [];
 	const settings = extractSettings($, linkUnderline);
+	settings.locale = defaultLanguage($("html").attr("lang")?.trim(), options.defaultLocale, warnings);
 	const pageImage = pageImageWarning($);
 	if (pageImage) warnings.push(pageImage);
 	const blocks = processBody($, entries, warnings, settings.width);