@remit/ui 0.0.100 → 0.0.102

package/src/components/rich-text-document.ts

@@ -1,7 +1,21 @@
 import { $generateHtmlFromNodes, $generateNodesFromDOM } from "@lexical/html";
-import { $convertToMarkdownString, TRANSFORMERS } from "@lexical/markdown";
-import type { LexicalEditor, LexicalNode } from "lexical";
+import {
+	$convertFromMarkdownString,
+	$convertToMarkdownString,
+} from "@lexical/markdown";
+import {
+	$getRoot,
+	$insertNodes,
+	$isElementNode,
+	$isTextNode,
+	createEditor,
+	type LexicalEditor,
+	type LexicalNode,
+	type TextFormatType,
+} from "lexical";
 import { sanitizeAdoptedHtml } from "../lib/adopted-html.js";
+import { COMPOSE_TRANSFORMERS } from "./rich-text-markdown.js";
+import { RICH_TEXT_NODES } from "./rich-text-nodes.js";
 import type { RichTextValue } from "./rich-text-value.js";
 
 export const $adoptHtml = (
@@ -15,6 +29,55 @@ export const $adoptHtml = (
 	return $generateNodesFromDOM(editor, document);
 };
 
+/**
+ * What survives a conversion to Markdown unchanged: a run of paragraphs, the
+ * line breaks inside them, and unformatted characters. Anything else is
+ * formatting that becomes visible syntax, or is lost outright.
+ */
+const PLAIN_NODE_TYPES = new Set(["root", "paragraph", "text", "linebreak"]);
+
+const TEXT_FORMATS: readonly TextFormatType[] = [
+	"bold",
+	"italic",
+	"strikethrough",
+	"underline",
+	"code",
+	"subscript",
+	"superscript",
+	"highlight",
+];
+
+/**
+ * Every node type and text format in the document that a plain-text
+ * representation cannot carry, as an inventory rather than a verdict — the
+ * caller decides what to do with a document that holds any.
+ *
+ * A comparison of the Markdown export against the plain text would be the
+ * obvious rule and is the wrong one in both directions. `@lexical/markdown`
+ * ships no underline transformer, so an underlined word exports identical to
+ * its own characters and would be destroyed in silence; a trailing empty
+ * paragraph makes the two strings differ and would raise a warning over
+ * ordinary prose.
+ */
+export const $documentFormatting = (): string[] => {
+	const found = new Set<string>();
+
+	const visit = (node: LexicalNode): void => {
+		const type = node.getType();
+		if (!PLAIN_NODE_TYPES.has(type)) found.add(type);
+		if ($isTextNode(node)) {
+			for (const format of TEXT_FORMATS) {
+				if (node.hasFormat(format)) found.add(format);
+			}
+		}
+		if (!$isElementNode(node)) return;
+		for (const child of node.getChildren()) visit(child);
+	};
+
+	visit($getRoot());
+	return [...found].sort();
+};
+
 /**
  * Lexical's export writes the editor's own theme onto every element — the app's
  * Tailwind class names, a `white-space` span around each text run, computed
@@ -24,5 +87,50 @@ export const $adoptHtml = (
  */
 export const $readRichText = (editor: LexicalEditor): RichTextValue => ({
 	html: sanitizeAdoptedHtml($generateHtmlFromNodes(editor, null)),
-	text: $convertToMarkdownString(TRANSFORMERS),
+	text: $convertToMarkdownString(COMPOSE_TRANSFORMERS),
+	formatting: $documentFormatting(),
 });
+
+/**
+ * A document held only long enough to convert one representation into the
+ * other. It is never attached to the DOM, so it has no theme, no history and
+ * no plugins — only the node types the composer registers, which is what makes
+ * the result the same document the editor would have produced.
+ */
+const scratchEditor = (): LexicalEditor =>
+	createEditor({
+		namespace: "compose-conversion",
+		nodes: [...RICH_TEXT_NODES],
+		onError: (error) => {
+			throw error;
+		},
+	});
+
+/** Adopted HTML as Markdown: a table as pipe rows, a heading as `##`. */
+export const htmlToMarkdown = (html: string): string => {
+	const editor = scratchEditor();
+	editor.update(
+		() => {
+			const root = $getRoot();
+			root.clear();
+			root.select();
+			$insertNodes($adoptHtml(editor, html));
+		},
+		{ discrete: true },
+	);
+	return editor.read(() => $convertToMarkdownString(COMPOSE_TRANSFORMERS));
+};
+
+/** Markdown as the HTML a rich draft stores and sends. */
+export const markdownToHtml = (markdown: string): string => {
+	const editor = scratchEditor();
+	editor.update(
+		() => {
+			$convertFromMarkdownString(markdown, COMPOSE_TRANSFORMERS);
+		},
+		{ discrete: true },
+	);
+	return editor.read(() =>
+		sanitizeAdoptedHtml($generateHtmlFromNodes(editor, null)),
+	);
+};

package/src/components/rich-text-editor.stories.tsx

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { expect, userEvent } from "storybook/test";
 import { sanitizeAdoptedHtml } from "../lib/adopted-html.js";
+import { ComposeLanguageChip } from "./compose-language-chip.js";
+import { ComposeModeToggle } from "./compose-mode-toggle.js";
 import { RichTextEditor } from "./rich-text-editor.js";
 
 /**
@@ -102,3 +104,101 @@ export const ClickBelowTheText: Story = {
 		await expect(editable).toHaveFocus();
 	},
 };
+
+/**
+ * The two pinned controls, in the order compose ships them: the chip first, so
+ * one Shift+Tab out of the body still reaches the mode toggle and two reach the
+ * chip.
+ */
+const pinnedControls = (
+	<>
+		<ComposeLanguageChip
+			language="nl"
+			languages={["nl", "en", "de"]}
+			onSelect={() => undefined}
+		/>
+		<ComposeModeToggle mode="rich" onToggle={() => undefined} />
+	</>
+);
+
+/** The toolbar as compose ships it: the formatting cluster, then the two pinned controls. */
+export const ToolbarInRich: Story = {
+	name: "Toolbar with the language chip and the mode toggle",
+	args: { initialHtml: RICH_DOCUMENT, lang: "nl", trailing: pinnedControls },
+};
+
+/**
+ * At 390 the formatting cluster runs out of room. It scrolls inside its own
+ * strip and both pinned controls stay at the right edge, rather than the
+ * cluster pushing them off the screen — which is what a flex child without
+ * `min-w-0` does. Two letters is what makes room for a second pinned item here.
+ */
+export const NarrowToolbar: Story = {
+	name: "Toolbar at 390",
+	args: { initialHtml: RICH_DOCUMENT, lang: "nl", trailing: pinnedControls },
+	decorators: [
+		(Story) => (
+			<div
+				data-testid="body-area"
+				className="flex h-[420px] w-[390px] flex-col overflow-auto rounded-md border border-line bg-canvas"
+			>
+				<Story />
+			</div>
+		),
+	],
+	play: async ({ canvasElement }) => {
+		const frame = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=body-area]",
+		);
+		const cluster = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=compose-format-cluster]",
+		);
+		const toggle = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=compose-mode-toggle]",
+		);
+		const chip = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=compose-language-chip]",
+		);
+		if (!frame || !cluster || !toggle || !chip)
+			throw new Error("the toolbar is not mounted");
+
+		await expect(cluster.scrollWidth).toBeGreaterThan(cluster.clientWidth);
+		const edge = frame.getBoundingClientRect().right + 1;
+		await expect(toggle.getBoundingClientRect().right).toBeLessThanOrEqual(
+			edge,
+		);
+		await expect(chip.getBoundingClientRect().left).toBeGreaterThanOrEqual(
+			frame.getBoundingClientRect().left,
+		);
+		await expect(chip.getBoundingClientRect().right).toBeLessThanOrEqual(edge);
+	},
+};
+
+/**
+ * The toolbar and the body share one scroller, so twenty lines of typing would
+ * carry the toolbar off the top with them. It stays at the top of the body
+ * while the text moves under it.
+ */
+export const StickyToolbar: Story = {
+	name: "Toolbar over a scrolled body",
+	args: {
+		initialHtml: `${RICH_DOCUMENT}${"<p>Another line of the message.</p>".repeat(30)}`,
+		lang: "nl",
+		trailing: pinnedControls,
+	},
+	play: async ({ canvasElement }) => {
+		const frame = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=body-area]",
+		);
+		const toggle = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=compose-mode-toggle]",
+		);
+		if (!frame || !toggle) throw new Error("the toolbar is not mounted");
+
+		frame.scrollTop = 400;
+		await expect(frame.scrollTop).toBeGreaterThan(0);
+		await expect(
+			toggle.getBoundingClientRect().top - frame.getBoundingClientRect().top,
+		).toBeLessThan(60);
+	},
+};

package/src/components/rich-text-editor.tsx

@@ -36,6 +36,14 @@ export interface RichTextEditorProps {
 	autoFocus?: boolean;
 	placeholder?: string;
 	ariaLabel?: string;
+	/** Pinned to the right of the toolbar strip. The mode toggle rides here. */
+	trailing?: React.ReactNode;
+	/**
+	 * BCP 47 tag of the language the message is being written in. Firefox picks
+	 * a dictionary from it among the ones the user installed; Chrome and Safari
+	 * ignore it. Every screen reader picks a voice from it.
+	 */
+	lang?: string;
 }
 
 /**
@@ -161,6 +169,8 @@ export const RichTextEditor = ({
 	autoFocus = false,
 	placeholder = "Write your message…",
 	ariaLabel = "Message body",
+	trailing,
+	lang,
 }: RichTextEditorProps) => (
 	<LexicalComposer
 		initialConfig={{
@@ -177,11 +187,12 @@ export const RichTextEditor = ({
 		    height of its own text. What is under the last line is the document, so
 		    a click there reaches it instead of an unfocusable parent. */}
 		<div className="flex shrink-0 grow flex-col">
-			<RichTextToolbar />
+			<RichTextToolbar trailing={trailing} />
 			<div className="relative flex shrink-0 grow flex-col">
 				<RichTextPlugin
 					contentEditable={
 						<ContentEditable
+							lang={lang}
 							aria-label={ariaLabel}
 							aria-placeholder={placeholder}
 							data-testid="compose-body"

package/src/components/rich-text-formatting.test.ts

@@ -0,0 +1,153 @@
+/**
+ * The rule that decides whether a message's formatting is destroyed without
+ * asking. It fires on what the document holds, not on a comparison of the
+ * Markdown export against the plain text: `@lexical/markdown` ships no
+ * underline transformer, so an underlined word exports identical to its own
+ * characters and a string comparison would switch in silence over exactly the
+ * document this warning exists for. In the other direction a trailing empty
+ * paragraph makes the two strings differ, and the same comparison would
+ * interrupt the ordinary prose it is meant to leave alone.
+ */
+import assert from "node:assert/strict";
+import { before, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import type { LexicalEditor } from "lexical";
+
+interface Row {
+	what: string;
+	html: string;
+	/** What the switch does: warn first, or switch in silence. */
+	warns: boolean;
+	/** The formatting the document is expected to hold, when it holds any. */
+	holds?: string[];
+}
+
+const ROWS: Row[] = [
+	{ what: "an empty document", html: "", warns: false },
+	{
+		what: "one paragraph of prose",
+		html: "<p>See you at 12:30.</p>",
+		warns: false,
+	},
+	{
+		what: "a double Enter between two paragraphs",
+		html: "<p>First.</p><p></p><p>Second.</p>",
+		warns: false,
+	},
+	{
+		what: "a trailing empty paragraph",
+		html: "<p>Thanks.</p><p></p>",
+		warns: false,
+	},
+	{
+		what: "a line break inside a paragraph",
+		html: "<p>One<br>Two</p>",
+		warns: false,
+	},
+	{
+		what: "a bare URL left as characters",
+		html: "<p>See https://example.com for the report.</p>",
+		warns: false,
+	},
+	{
+		what: "an image, which no registered node can hold",
+		html: '<p>Chart: <img src="https://example.com/chart.png" alt="chart"></p>',
+		warns: false,
+	},
+	{
+		what: "an underlined word",
+		html: "<p>Please <u>read this</u>.</p>",
+		warns: true,
+		holds: ["underline"],
+	},
+	{
+		what: "a bold word",
+		html: "<p>Due <strong>Friday</strong>.</p>",
+		warns: true,
+		holds: ["bold"],
+	},
+	{
+		what: "a URL Lexical turned into a link",
+		html: '<p>See <a href="https://example.com">https://example.com</a>.</p>',
+		warns: true,
+		holds: ["link"],
+	},
+	{
+		what: "a heading",
+		html: "<h2>Quarterly numbers</h2><p>Below.</p>",
+		warns: true,
+		holds: ["heading"],
+	},
+	{
+		what: "a table",
+		html: "<table><tbody><tr><td>EMEA</td><td>412</td></tr></tbody></table>",
+		warns: true,
+	},
+];
+
+let formattingOf: (html: string) => string[];
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	const dom: JSDOM = new JSDOMCtor(
+		"<!doctype html><html><body></body></html>",
+		{
+			url: "http://localhost/",
+		},
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.DOMParser = dom.window.DOMParser;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.Node = dom.window.Node;
+
+	const { $getRoot, $insertNodes, createEditor } = await import("lexical");
+	const { $adoptHtml, $documentFormatting } = await import(
+		"./rich-text-document.js"
+	);
+	const { RICH_TEXT_NODES } = await import("./rich-text-nodes.js");
+
+	formattingOf = (html: string) => {
+		const editor: LexicalEditor = createEditor({
+			namespace: "test",
+			nodes: [...RICH_TEXT_NODES],
+			onError: (error) => {
+				throw error;
+			},
+		});
+		editor.update(
+			() => {
+				const root = $getRoot();
+				root.clear();
+				root.select();
+				if (html !== "") $insertNodes($adoptHtml(editor, html));
+			},
+			{ discrete: true },
+		);
+		return editor.read(() => $documentFormatting());
+	};
+});
+
+describe("what switching to plain text warns about", () => {
+	for (const row of ROWS) {
+		it(`${row.warns ? "warns about" : "says nothing about"} ${row.what}`, () => {
+			const formatting = formattingOf(row.html);
+			assert.equal(
+				formatting.length > 0,
+				row.warns,
+				`formatting was ${JSON.stringify(formatting)}`,
+			);
+			if (row.holds) {
+				for (const held of row.holds) assert.ok(formatting.includes(held));
+			}
+		});
+	}
+
+	it("names what a formatted document holds rather than reducing it to a flag", () => {
+		assert.deepEqual(
+			formattingOf("<p><strong>Due</strong> <em>Friday</em>.</p>"),
+			["bold", "italic"],
+		);
+	});
+});

package/src/components/rich-text-markdown.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `@lexical/markdown` exports `isTableRowDivider` and no table transformer, so
+ * the composer supplies one. Both directions are pinned here: what a recipient
+ * reads in the plain part of a rich send, and what comes back when a plain
+ * draft is switched to rich.
+ *
+ * The same transformer set drives the down-conversion of a paste in plain mode,
+ * so a table pasted there and a table pasted in rich mode and then switched
+ * produce the same characters.
+ */
+import assert from "node:assert/strict";
+import { before, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+
+const TABLE_HTML = [
+	"<table><thead><tr><th>Region</th><th>Total</th></tr></thead>",
+	"<tbody><tr><td>EMEA</td><td>412</td></tr>",
+	"<tr><td>Americas</td><td>388</td></tr></tbody></table>",
+].join("");
+
+const TABLE_MARKDOWN = [
+	"| Region | Total |",
+	"| --- | --- |",
+	"| EMEA | 412 |",
+	"| Americas | 388 |",
+].join("\n");
+
+let htmlToMarkdown: (html: string) => string;
+let markdownToHtml: (markdown: string) => string;
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	const dom: JSDOM = new JSDOMCtor(
+		"<!doctype html><html><body></body></html>",
+		{
+			url: "http://localhost/",
+		},
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.DOMParser = dom.window.DOMParser;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.Node = dom.window.Node;
+
+	({ htmlToMarkdown, markdownToHtml } = await import(
+		"./rich-text-document.js"
+	));
+});
+
+describe("HTML down-converted for the plain surface", () => {
+	it("writes a table as pipe rows under a divider", () => {
+		assert.equal(htmlToMarkdown(TABLE_HTML).trim(), TABLE_MARKDOWN);
+	});
+
+	it("writes headings, lists and emphasis as Markdown", () => {
+		const markdown = htmlToMarkdown(
+			[
+				"<h2>Release checklist</h2>",
+				"<p>Ship <strong>Friday</strong>.</p>",
+				"<ol><li>Cut the tag</li><li>Publish the images</li></ol>",
+			].join(""),
+		);
+
+		assert.match(markdown, /## Release checklist/);
+		assert.match(markdown, /\*\*Friday\*\*/);
+		assert.match(markdown, /1\. Cut the tag/);
+	});
+
+	it("carries no markup through as characters", () => {
+		const markdown = htmlToMarkdown(
+			'<h2 style="color:#c00">Numbers</h2><script>alert(1)</script>',
+		);
+
+		assert.equal(markdown.includes("<h2"), false);
+		assert.equal(markdown.includes("<script"), false);
+		assert.equal(markdown.includes("alert(1)"), false);
+		assert.equal(markdown.includes("color:#c00"), false);
+	});
+
+	it("keeps a cell's own pipe out of the row it sits in", () => {
+		const markdown = htmlToMarkdown(
+			"<table><tbody><tr><td>a|b</td><td>c</td></tr></tbody></table>",
+		);
+		const cells = markdownToHtml(markdown).match(/<t[dh][^>]*>/g) ?? [];
+
+		assert.match(markdown, /a\\\|b/);
+		assert.equal(cells.length, 2);
+	});
+});
+
+describe("Markdown read back into a document", () => {
+	it("renders a pipe table as a table with a header row", () => {
+		const html = markdownToHtml(TABLE_MARKDOWN);
+
+		assert.match(html, /<table/);
+		assert.match(html, /<th[^>]*><p>Region/);
+		assert.match(html, /EMEA/);
+		assert.match(html, /388/);
+	});
+
+	it("renders a heading and emphasis", () => {
+		const html = markdownToHtml("## Numbers\n\nDue **Friday**.");
+
+		assert.match(html, /<h2/);
+		assert.match(html, /<strong/);
+	});
+
+	it("returns a table unchanged over a round trip", () => {
+		assert.equal(
+			htmlToMarkdown(markdownToHtml(TABLE_MARKDOWN)).trim(),
+			TABLE_MARKDOWN,
+		);
+	});
+
+	it("keeps a divider that heads no table as the characters it is", () => {
+		const html = markdownToHtml("| --- | --- |");
+
+		assert.match(html, /\| --- \| --- \|/);
+		assert.equal(html.includes("<table"), false);
+	});
+
+	it("leaves prose that matches no transformer looking the same", () => {
+		const prose = "Thanks — that works.\n\nI'll send the deck tomorrow.";
+		const html = markdownToHtml(prose);
+
+		assert.equal((html.match(/<p>/g) ?? []).length, 2);
+		assert.match(html, /Thanks/);
+		assert.match(html, /send the deck tomorrow/);
+	});
+});