@remit/ui 0.0.122 → 0.0.124

package/src/lib/email-layout-clamp.test.ts

@@ -89,6 +89,36 @@ describe("generateLayoutClampCSS (#374 / #727)", () => {
 		);
 	});
 
+	test("overrides an author nowrap so flowing text can never be clipped", () => {
+		// The frame is the pane's width, so a pinned paragraph is read by dragging
+		// the whole email sideways; inside an author `overflow:hidden` it is cut
+		// mid-character with nothing to scroll at all.
+		assert.ok(
+			/\[nowrap\][^{]*\{[^}]*white-space:\s*normal\s*!important/.test(css),
+			"a nowrap attribute must not pin a line wider than the frame",
+		);
+		assert.ok(
+			/\[style\*="nowrap" i\][^{]*\{[^}]*white-space:\s*normal\s*!important/.test(
+				css,
+			),
+			"an inline white-space:nowrap must not pin a line wider than the frame",
+		);
+		assert.ok(
+			/\[style\*="nowrap" i\]/.test(css),
+			"Outlook emits WHITE-SPACE: NOWRAP — the attribute match must ignore case",
+		);
+		assert.ok(
+			/\[nowrap\]:not\(pre, code, pre \*, code \*\)/.test(css),
+			"pre/code AND their descendants keep their own whitespace handling",
+		);
+		assert.ok(
+			/:is\(pre, code, pre \*, code \*\):is\(\[nowrap\], \[style\*="nowrap" i\]\)[^{]*\{[^}]*white-space:\s*pre-wrap\s*!important/.test(
+				css,
+			),
+			"a nowrap inside a pre wraps rather than collapsing the block's spacing",
+		);
+	});
+
 	test("wraps long unbroken lines in pre/code blocks", () => {
 		assert.ok(/\bpre\b/.test(css));
 		assert.ok(/\bcode\b/.test(css));

package/src/lib/email-layout-clamp.ts

@@ -55,10 +55,27 @@ td, th {
 * {
   min-width: 0;
 }
+/* An author \`nowrap\` assumes a viewport as wide as the line. The frame is the
+   pane's width whatever the mail is, so a pinned paragraph turns reading one
+   sentence into a sideways drag — and inside an author \`overflow:hidden\` it is
+   cut mid-character with nothing left to scroll at all. Flowing text wraps. The
+   \`i\` flag is load-bearing: Outlook and older generators emit \`WHITE-SPACE:
+   NOWRAP\`, and an attribute value match is case-sensitive without it. */
+[nowrap]:not(pre, code, pre *, code *),
+[style*="nowrap" i]:not(pre, code, pre *, code *) {
+  white-space: normal !important;
+}
 /* Long unbroken strings (URLs, tokens) wrap instead of forcing a wide line. */
 pre, code {
   white-space: pre-wrap;
   overflow-wrap: anywhere;
   word-break: break-word;
 }
+/* Preformatted text keeps its spacing even where a nowrap is declared — on the
+   block or on a span inside it. \`normal\` would collapse the runs of spaces that
+   are the entire content of a \`pre\`, and the un-important rule above cannot
+   defend an inline style, so this wraps to \`pre-wrap\` instead of unwrapping. */
+:is(pre, code, pre *, code *):is([nowrap], [style*="nowrap" i]) {
+  white-space: pre-wrap !important;
+}
 `;

package/src/lib/email-sanitizer.test.ts

@@ -3,6 +3,7 @@ import { describe, test } from "node:test";
 import { buildCidResolver } from "./cid-resolver.js";
 import {
 	detectAuthorBackground,
+	detectAuthorSpacing,
 	sanitizeInlineStyle,
 	sanitizeStyleElementCss,
 } from "./email-sanitizer.js";
@@ -360,3 +361,155 @@ describe("detectAuthorBackground — <style> block over-match hardening (#483)",
 		assert.equal(detectAuthorBackground(html), false);
 	});
 });
+
+describe("detectAuthorSpacing — does the mail lay out its own breathing room?", () => {
+	test("a bare message declares none", () => {
+		assert.equal(
+			detectAuthorSpacing("<div><p>Hi there,</p><p>See you at 3.</p></div>"),
+			false,
+		);
+	});
+
+	test("a reset is not breathing room", () => {
+		assert.equal(
+			detectAuthorSpacing(
+				'<table style="margin:0;padding:0"><tr></tr></table>',
+			),
+			false,
+		);
+		assert.equal(
+			detectAuthorSpacing("<style>body{margin:0 auto;padding:0px}</style>"),
+			false,
+		);
+	});
+
+	test("a reset that shouts is still a reset", () => {
+		assert.equal(
+			detectAuthorSpacing('<div style="padding:0 !important">x</div>'),
+			false,
+		);
+	});
+
+	test("an inline padding on a container counts", () => {
+		assert.equal(
+			detectAuthorSpacing('<td style="padding:24px;color:#111">x</td>'),
+			true,
+		);
+	});
+
+	test("a horizontal margin in a <style> block counts", () => {
+		assert.equal(
+			detectAuthorSpacing("<style>.wrap{margin:0 24px}</style><p>x</p>"),
+			true,
+		);
+	});
+
+	test("the tables newsletters are still built from count via cellpadding", () => {
+		assert.equal(detectAuthorSpacing('<table cellpadding="8"></table>'), true);
+		assert.equal(detectAuthorSpacing('<table cellpadding="0"></table>'), false);
+	});
+
+	test("the word margin in prose is not a declaration", () => {
+		assert.equal(
+			detectAuthorSpacing("<p>The margin was thin this quarter.</p>"),
+			false,
+		);
+	});
+
+	test("a mail about CSS quotes a declaration without making one", () => {
+		assert.equal(
+			detectAuthorSpacing(
+				'<p>Set style="padding:9px" on the cell and it lines up.</p>',
+			),
+			false,
+		);
+	});
+
+	test("a commented-out declaration is not a declaration", () => {
+		assert.equal(
+			detectAuthorSpacing("<style>.wrap{/* padding: 20px */}</style><p>x</p>"),
+			false,
+		);
+		assert.equal(
+			detectAuthorSpacing(
+				'<!--[if mso]><td style="padding:20px"><![endif]--><p>x</p>',
+			),
+			false,
+		);
+	});
+
+	test("CSS hidden from prehistoric clients still counts", () => {
+		assert.equal(
+			detectAuthorSpacing(
+				"<style><!-- .wrap{padding:24px} --></style><p>x</p>",
+			),
+			true,
+		);
+	});
+
+	test("a property that merely ends in padding is not padding", () => {
+		assert.equal(
+			detectAuthorSpacing('<div style="scroll-padding:40px">x</div>'),
+			false,
+		);
+		assert.equal(
+			detectAuthorSpacing("<style>td{mso-padding-alt:0cm 5.4pt}</style>"),
+			false,
+		);
+	});
+
+	test("a negative margin pulls content out, it does not space it", () => {
+		assert.equal(
+			detectAuthorSpacing('<div style="margin-left:-12px">x</div>'),
+			false,
+		);
+	});
+});
+
+/**
+ * The commonest mail in an inbox is a personal reply, and a personal reply
+ * carries a quote. Every client indents that quote and spaces its paragraphs,
+ * so counting either as "the mail lays out its own container" left exactly the
+ * mail the inset exists for flush against a phone's screen edge.
+ */
+describe("detectAuthorSpacing — the mail the inset exists for", () => {
+	test("an Apple Mail reply with a quoted original declares none", () => {
+		const html = [
+			"<div>Ja hoor, tot donderdag.</div><br>",
+			'<blockquote type="cite" style="margin:0 0 0 40px;border:none;padding:0px">',
+			"<div>Kun je donderdag?</div>",
+			"</blockquote>",
+		].join("");
+		assert.equal(detectAuthorSpacing(html), false);
+	});
+
+	test("a Gmail reply with a quoted original declares none", () => {
+		const html = [
+			'<div dir="ltr">Works for me.</div>',
+			'<div class="gmail_quote">',
+			'<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;',
+			'border-left:1px solid rgb(204,204,204);padding-left:1ex">',
+			"<div>Thursday still good?</div>",
+			"</blockquote></div>",
+		].join("");
+		assert.equal(detectAuthorSpacing(html), false);
+	});
+
+	test("Outlook paragraph spacing is not a container", () => {
+		const html = [
+			"<style>p.MsoNormal{margin:0cm;margin-bottom:.0001pt}</style>",
+			"<p class=MsoNormal style='margin-bottom:12.0pt'>Beste Matthijs,</p>",
+			"<p class=MsoNormal style='margin-bottom:12.0pt'>Met vriendelijke groet,</p>",
+		].join("");
+		assert.equal(detectAuthorSpacing(html), false);
+	});
+
+	test("a newsletter that lays out its own container still counts", () => {
+		const html = [
+			'<table width="600" style="margin:0 auto">',
+			'<tr><td style="width:600px;padding:24px;background:#83cd29">',
+			"<h1>Node Weekly</h1></td></tr></table>",
+		].join("");
+		assert.equal(detectAuthorSpacing(html), true);
+	});
+});

package/src/lib/email-sanitizer.ts

@@ -27,10 +27,18 @@ export interface SanitizeOptions {
  * so author colors survive (newsletter / designed mail). When false, the
  * subtree inherits the app theme so plain mail blends with dark chrome
  * instead of becoming a bright slab (#375).
+ *
+ * `hasAuthorSpacing` is the same question for layout: does the mail hold its own
+ * content off its container's left and right edges? A newsletter that already
+ * spaces its container must not be given a second helping; everything else —
+ * including a personal reply whose only declarations are a quote's indent and
+ * the gaps between paragraphs — gets breathing room injected inside its own
+ * background.
  */
 export interface SanitizedEmail {
 	html: string;
 	hasAuthorBackground: boolean;
+	hasAuthorSpacing: boolean;
 }
 
 /**
@@ -112,6 +120,161 @@ export const detectAuthorBackground = (html: string): boolean => {
 	return false;
 };
 
+/**
+ * CSS keywords that space nothing: a `margin: 0` reset is not the mail laying
+ * out its own breathing room, and neither is `margin: auto` centring a table.
+ */
+const NO_SPACING_KEYWORDS = new Set([
+	"auto",
+	"none",
+	"initial",
+	"inherit",
+	"unset",
+	"revert",
+	"revert-layer",
+]);
+
+/**
+ * `padding` / `margin` declarations, and only those. The lookbehind keeps the
+ * properties that merely end in the same word out of the scan — `scroll-padding`
+ * on a scroll container and Outlook's `mso-padding-alt` are not the mail
+ * spacing its container.
+ */
+const SPACING_DECL_RE =
+	/(?<![-\w])(?:padding|margin)(?:-(top|right|bottom|left|block|inline)(?:-(?:start|end))?)?\s*:\s*([^;}"']+)/gi;
+
+const VERTICAL_SIDES = new Set(["top", "bottom", "block"]);
+
+/** CSS comments hold no declarations, in a `<style>` block or in a `style=`. */
+const stripCssComments = (css: string): string =>
+	css.replace(/\/\*[\s\S]*?\*\//g, "");
+
+/**
+ * Whether one length token pushes content off the container edge. Zero, a
+ * keyword and a negative all fail — a negative margin pulls content out rather
+ * than spacing it in. Anything unrecognised (`calc()`, `var()`) counts, on the
+ * conservative side of leaving a self-spacing mail alone.
+ */
+const isSpacingLength = (token: string): boolean => {
+	const value = token.toLowerCase();
+	if (!value || NO_SPACING_KEYWORDS.has(value)) return false;
+	if (value.startsWith("-")) return false;
+	const numeric = /^\+?(\d*\.?\d+)[a-z%]*$/.exec(value);
+	if (numeric) return Number.parseFloat(numeric[1]) !== 0;
+	return true;
+};
+
+/** The left/right components of a `padding`/`margin` shorthand value. */
+const horizontalComponents = (value: string): string[] => {
+	const parts = value.split(/\s+/).filter(Boolean);
+	if (parts.length < 2) return parts;
+	if (parts.length < 4) return [parts[1]];
+	return [parts[1], parts[3]];
+};
+
+/**
+ * Whether one declaration spaces the container horizontally. Only the
+ * horizontal axis answers the question the inset asks: a `margin-bottom` between
+ * two Outlook paragraphs is the mail spacing its own paragraphs, not laying out
+ * a container, and a mail with nothing but that still runs into a phone's screen
+ * edge without the inset.
+ */
+const spacesHorizontally = (side: string | undefined, raw: string): boolean => {
+	if (side && VERTICAL_SIDES.has(side)) return false;
+	const value = raw.replace(/!\s*important/gi, "").trim();
+	if (!value) return false;
+	if (side) return value.split(/\s+/).some(isSpacingLength);
+	return horizontalComponents(value).some(isSpacingLength);
+};
+
+/** Whether CSS text lays out horizontal container spacing. */
+const declaresContainerSpacing = (css: string): boolean => {
+	for (const match of stripCssComments(css).matchAll(SPACING_DECL_RE)) {
+		if (spacesHorizontally(match[1], match[2])) return true;
+	}
+	return false;
+};
+
+/**
+ * Elements whose spacing is a convention rather than a container. Every mail
+ * client on earth indents a quote with a left margin on the `<blockquote>`, and
+ * a reply carrying a quote is exactly the mail the injected inset exists for.
+ */
+const SPACING_EXEMPT_TAGS = new Set(["blockquote"]);
+
+/** HTML comments hold no markup — including the `<!--[if mso]>` conditionals
+ *  Outlook mail is padded with, which no other client ever renders. */
+const stripHtmlComments = (html: string): string =>
+	html.replace(/<!--[\s\S]*?-->/g, "");
+
+/**
+ * Every inline `style="…"` / `style='…'` value in the raw markup, with the tag
+ * carrying it. Scanning tags rather than the whole string is what keeps a
+ * literal `style="padding:9px"` written out in the text of a mail ABOUT CSS
+ * from reading as layout.
+ */
+const extractStyledTags = (html: string): { tag: string; style: string }[] => {
+	const found: { tag: string; style: string }[] = [];
+	const tags = /<([a-zA-Z][\w:-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+	const styles = /\bstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+	for (const [, tag, attrs] of html.matchAll(tags)) {
+		for (const match of attrs.matchAll(styles)) {
+			found.push({ tag: tag.toLowerCase(), style: match[1] ?? match[2] ?? "" });
+		}
+	}
+	return found;
+};
+
+/** `selector { … }` pairs; a nested at-rule yields its inner rules. */
+const extractCssRules = (css: string): { selector: string; body: string }[] =>
+	[...stripCssComments(css).matchAll(/([^{}]*)\{([^{}]*)\}/g)].map((match) => ({
+		selector: match[1].trim(),
+		body: match[2],
+	}));
+
+/** The element a selector actually styles — the tag of its last compound. */
+const selectorSubjectTag = (selector: string): string => {
+	const last =
+		selector
+			.trim()
+			.split(/[\s>+~]+/)
+			.pop() ?? "";
+	return (/^[a-zA-Z][\w-]*/.exec(last)?.[0] ?? "").toLowerCase();
+};
+
+const stylesOnlyQuotes = (selector: string): boolean =>
+	selector
+		.split(",")
+		.every((one) => SPACING_EXEMPT_TAGS.has(selectorSubjectTag(one)));
+
+/**
+ * Detect whether the mail lays out horizontal spacing of its own — in an inline
+ * style, in a `<style>` block, or through a non-zero `cellpadding` on the tables
+ * newsletters are still built from. Same shape and same limits as
+ * `detectAuthorBackground`: a declaration scan over the raw markup, deliberately
+ * conservative, because the cost of a false positive (no injected inset) is a
+ * message that runs into the screen edge, while a false negative doubles a
+ * newsletter's own padding.
+ */
+export const detectAuthorSpacing = (html: string): boolean => {
+	// Style blocks come off the raw string: old mail wraps its CSS in an HTML
+	// comment to hide it from clients that never shipped `<style>`.
+	const blocks = extractStyleBlocks(html);
+	const markup = stripHtmlComments(html);
+	if (/\bcellpadding\s*=\s*["']?(?!0["'\s>])\d/i.test(markup)) return true;
+	for (const { tag, style } of extractStyledTags(markup)) {
+		if (SPACING_EXEMPT_TAGS.has(tag)) continue;
+		if (declaresContainerSpacing(style)) return true;
+	}
+	for (const block of blocks) {
+		for (const rule of extractCssRules(block)) {
+			if (stylesOnlyQuotes(rule.selector)) continue;
+			if (declaresContainerSpacing(rule.body)) return true;
+		}
+	}
+	return false;
+};
+
 const FORBIDDEN_TAGS = [
 	"script",
 	"iframe",
@@ -282,6 +445,7 @@ export const createEmailSanitizer = (options: SanitizeOptions = {}) => {
 		// #375), but running the detector on the raw input is simpler and
 		// not sensitive to any future hook rewrites.
 		const hasAuthorBackground = detectAuthorBackground(html);
+		const hasAuthorSpacing = detectAuthorSpacing(html);
 
 		const sanitized = purify.sanitize(html, config);
 
@@ -293,6 +457,7 @@ export const createEmailSanitizer = (options: SanitizeOptions = {}) => {
 		return {
 			html: `<style>${layoutCss}</style>${sanitized}`,
 			hasAuthorBackground,
+			hasAuthorSpacing,
 		};
 	};
 };

package/src/lib/keymap.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import {
+	ALL_TRIAGE_ACTIONS,
 	KEY_HINT_GROUPS,
 	keysForAction,
 	shortcutHintForAction,
@@ -54,6 +55,28 @@ describe("keymap module", () => {
 		assert.strictEqual(tooltipForAction(unbound), "");
 	});
 
+	test("the navigation hints name a direction on screen, not a place in time", () => {
+		const navigation = KEY_HINT_GROUPS.find((g) => g.title === "Navigation");
+		assert.ok(navigation, "the Navigation group is declared");
+
+		const describes = (key: string): string | undefined =>
+			navigation.hints.find((hint) => hint.keys.join("") === key)?.description;
+
+		// Both surfaces the keys serve read downward, and a conversation reads
+		// newest first — so down is back in time there. A description saying
+		// "next message" is read as the newer one, which is the opposite.
+		assert.strictEqual(describes("j"), "Focus the message below");
+		assert.strictEqual(describes("↓"), "Focus the message below");
+		assert.strictEqual(describes("k"), "Focus the message above");
+		assert.strictEqual(describes("↑"), "Focus the message above");
+	});
+
+	test("every action the app can produce has a displayed binding", () => {
+		for (const action of ALL_TRIAGE_ACTIONS) {
+			assert.ok(keysForAction(action), `${action} has keys`);
+		}
+	});
+
 	test("every hint's action is a non-empty key list", () => {
 		for (const group of KEY_HINT_GROUPS) {
 			for (const hint of group.hints) {

package/src/lib/keymap.ts

@@ -48,6 +48,51 @@ export type TriageAction =
 	| "goFlagged"
 	| "goSettings";
 
+/**
+ * Presence table for {@link TriageAction}. `Record<TriageAction, true>` is what
+ * makes it exhaustive: adding a member to the union without adding it here is a
+ * type error, so anything that must reason about *every* action — the shortcut
+ * tree's completeness tests, the help overlay's audit — has a runtime list that
+ * cannot silently fall behind the type.
+ */
+const TRIAGE_ACTION_PRESENCE: Record<TriageAction, true> = {
+	focusNext: true,
+	focusPrevious: true,
+	focusFirst: true,
+	focusLast: true,
+	openFocused: true,
+	back: true,
+	toggleSelect: true,
+	extendSelectDown: true,
+	extendSelectUp: true,
+	selectAll: true,
+	reply: true,
+	replyAll: true,
+	forward: true,
+	delete: true,
+	toggleStar: true,
+	toggleRead: true,
+	muteSender: true,
+	blockSender: true,
+	vipSender: true,
+	markJunk: true,
+	toggleIntelligence: true,
+	toggleDensity: true,
+	focusSearch: true,
+	compose: true,
+	help: true,
+	goBrief: true,
+	goInbox: true,
+	goSent: true,
+	goFlagged: true,
+	goSettings: true,
+};
+
+/** Every action the app can produce, in declaration order. */
+export const ALL_TRIAGE_ACTIONS: readonly TriageAction[] = Object.keys(
+	TRIAGE_ACTION_PRESENCE,
+) as TriageAction[];
+
 /** Map of action → handler. Omitted actions are inert (no-op). */
 export type TriageHandlers = Partial<Record<TriageAction, () => void>>;
 
@@ -104,17 +149,29 @@ export const KEY_HINT_GROUPS: KeyHintGroup[] = [
 	{
 		title: "Navigation",
 		hints: [
-			{ action: "focusNext", keys: ["j"], description: "Focus next message" },
+			// The keys move through what is on screen, so the description is a
+			// direction rather than a position in time. A conversation reads newest
+			// first, where the message below is the older one — "next message" read
+			// as the newer one there and named the opposite of what j does.
+			{
+				action: "focusNext",
+				keys: ["j"],
+				description: "Focus the message below",
+			},
 			{
 				action: "focusPrevious",
 				keys: ["k"],
-				description: "Focus previous message",
+				description: "Focus the message above",
+			},
+			{
+				action: "focusNext",
+				keys: ["↓"],
+				description: "Focus the message below",
 			},
-			{ action: "focusNext", keys: ["↓"], description: "Focus next message" },
 			{
 				action: "focusPrevious",
 				keys: ["↑"],
-				description: "Focus previous message",
+				description: "Focus the message above",
 			},
 			{ action: "focusFirst", keys: ["Home"], description: "Focus first" },
 			{ action: "focusLast", keys: ["End"], description: "Focus last" },