@remit/ui 0.0.121 → 0.0.123

package/src/components/slide-panel.tsx

@@ -54,7 +54,7 @@ export function SlidePanel({
 
 			<div
 				className={cn(
-					"safe-area-frame fixed top-0 right-0 z-50 h-full w-full border-l border-line bg-canvas shadow-xl sm:w-[400px] sm:max-w-[90vw]",
+					"safe-area-frame fixed top-0 right-0 z-50 flex h-full w-full flex-col border-l border-line bg-canvas shadow-xl sm:w-[400px] sm:max-w-[90vw]",
 					"transform transition-transform duration-200 ease-out",
 					isOpen ? "translate-x-0" : "pointer-events-none translate-x-full",
 				)}
@@ -64,7 +64,7 @@ export function SlidePanel({
 				inert={!isOpen}
 				aria-labelledby="slide-panel-title"
 			>
-				<div className="flex h-14 items-center justify-between border-b border-line px-4">
+				<div className="flex h-14 shrink-0 items-center justify-between border-b border-line px-4">
 					<h2 id="slide-panel-title" className="font-semibold">
 						{title}
 					</h2>
@@ -78,7 +78,11 @@ export function SlidePanel({
 					</button>
 				</div>
 
-				<div className="flex h-[calc(100%-3.5rem)] flex-col">
+				{/* The body takes what the header leaves, from the layout rather than
+				    from arithmetic over the header's height: a computed height puts
+				    the box on a fractional pixel and drifts the moment the header
+				    does. */}
+				<div className="flex min-h-0 flex-1 flex-col">
 					<div className="flex-1 overflow-auto p-4">{children}</div>
 					{footer && (
 						<div className="flex justify-end gap-3 border-t border-line bg-canvas p-4">

package/src/index.ts

@@ -179,6 +179,7 @@ export {
 	ComposeFormShell,
 	type ComposeFormShellProps,
 	type ComposeMode,
+	type ComposeShellLayout,
 	composeModeLabels,
 } from "./components/compose-form-shell.js";
 export {
@@ -218,7 +219,10 @@ export {
 	DialogBackdrop,
 	type DialogBackdropProps,
 } from "./components/dialog-backdrop.js";
-export type { EmailFrameVariant } from "./components/email-frame-css.js";
+export type {
+	AuthorDeclarations,
+	EmailFrameVariant,
+} from "./components/email-frame-css.js";
 export {
 	EventDetail,
 	type EventDetailProps,
@@ -408,6 +412,7 @@ export {
 } from "./components/mail-header.js";
 export {
 	type EmailRenderCategory,
+	MessageBodyRegion,
 	MessageBodyView,
 	type MessageBodyViewProps,
 } from "./components/message-body-view.js";
@@ -569,6 +574,7 @@ export {
 	ResizableHandle,
 	ResizablePanel,
 	ResizablePanelGroup,
+	WholePixelWidth,
 } from "./components/resizable.js";
 export {
 	EMPTY_RICH_TEXT,
@@ -819,6 +825,7 @@ export {
 export {
 	createEmailSanitizer,
 	detectAuthorBackground,
+	detectAuthorSpacing,
 	type SanitizedEmail,
 	type SanitizeOptions,
 	sanitizeInlineStyle,

package/src/lib/compose-language.test.ts

@@ -13,6 +13,9 @@ import {
 	wrapWithLanguage,
 } from "./compose-language.js";
 
+/** The dictionaries the published image stages, per `REMIT_SPELLCHECK_LANGUAGES`. */
+const BUILT = ["en", "en-GB", "nl"];
+
 before(() => {
 	const dom = new JSDOM("");
 	globalThis.DOMParser = dom.window.DOMParser;
@@ -66,6 +69,20 @@ describe("defaultComposeLanguages", () => {
 	it("falls back to English when the browser offers nothing usable", () => {
 		assert.deepEqual(defaultComposeLanguages([]), ["en"]);
 	});
+
+	it("offers what the build can spellcheck, not the browser alone", () => {
+		assert.deepEqual(defaultComposeLanguages(["en-US", "en"], BUILT), [
+			"en",
+			"nl",
+		]);
+	});
+
+	it("keeps the browser's own language first, so it stays the default", () => {
+		assert.deepEqual(defaultComposeLanguages(["nl-NL", "nl"], BUILT), [
+			"nl",
+			"en",
+		]);
+	});
 });
 
 describe("browserSpellcheckHelp", () => {

package/src/lib/compose-language.ts

@@ -10,6 +10,8 @@
  * message the recipient's client can read the language off. See issue #686.
  */
 
+import { spellcheckLanguages } from "../components/rich-text-spellcheck-languages.js";
+
 /**
  * A language the composer offers, and the ISO 639-3 code `franc-min` knows it
  * by. The two are separate alphabets: the tag is what goes on the document and
@@ -111,16 +113,25 @@ export const languageLabel = (tag: string): string => {
 };
 
 /**
- * The languages an account writes in when it has not said. The browser already
- * holds an ordered answer; `en` follows it, so a browser set to one language
- * nothing can detect still leaves the chip something to show.
+ * The languages an account writes in when it has not said: the browser's own
+ * ordered answer first, then the dictionaries this build carries, then `en`.
+ *
+ * The dictionaries are in there because the browser routinely names one
+ * language and the writer uses another — Dutch mail written on an English
+ * browser is the ordinary case, not the exception. A candidate set of one turns
+ * detection off, since there is nothing to choose between, and every message
+ * then keeps the default tag and is checked against the wrong dictionary. What
+ * the deployment staged is the other statement about which languages are
+ * written here, and it is a short list, which is what keeps detection accurate.
  */
 export const defaultComposeLanguages = (
 	locales: readonly string[],
+	built: readonly string[] = spellcheckLanguages(),
 ): string[] => {
-	const known = locales.filter((locale) => detectionCodeFor(locale) !== null);
-	const tags = known.map(primaryLanguageSubtag);
-	const unique = [...new Set(tags)];
+	const known = [...locales, ...built].filter(
+		(locale) => detectionCodeFor(locale) !== null,
+	);
+	const unique = [...new Set(known.map(primaryLanguageSubtag))];
 	if (!unique.includes("en")) unique.push("en");
 	return unique;
 };

package/src/lib/detect-compose-language.test.ts

@@ -5,6 +5,7 @@
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
+import { defaultComposeLanguages } from "./compose-language.js";
 import { detectComposeLanguage } from "./detect-compose-language.js";
 
 const DUTCH =
@@ -45,6 +46,23 @@ describe("detectComposeLanguage", () => {
 		assert.equal(detectComposeLanguage(DUTCH, ["nl", "ja", "en"]), "nl");
 	});
 
+	it("reads a Dutch line written on an English browser", () => {
+		// The account has never been to the language setting, and the browser it is
+		// read on says English and nothing else. A candidate set built from that
+		// alone has nothing to choose between, and every Dutch message goes out
+		// tagged `en` with the English dictionary underlining all of it.
+		const candidates = defaultComposeLanguages(
+			["en-US", "en"],
+			["en", "en-GB", "nl"],
+		);
+		assert.equal(
+			detectComposeLanguage("OK nou dank je wel hoor flapsigaar", candidates),
+			"nl",
+		);
+		assert.equal(detectComposeLanguage(DUTCH, candidates), "nl");
+		assert.equal(detectComposeLanguage(ENGLISH, candidates), "en");
+	});
+
 	it("resolves a regional tag through its language", () => {
 		assert.equal(detectComposeLanguage(ENGLISH, ["nl", "en-GB"]), "en-GB");
 	});

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

@@ -54,6 +54,22 @@ 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 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

@@ -104,17 +104,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" },