@remit/ui 0.0.100 → 0.0.101

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,7 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { expect, userEvent } from "storybook/test";
 import { sanitizeAdoptedHtml } from "../lib/adopted-html.js";
+import { ComposeModeToggle } from "./compose-mode-toggle.js";
 import { RichTextEditor } from "./rich-text-editor.js";
 
 /**
@@ -102,3 +103,78 @@ export const ClickBelowTheText: Story = {
 		await expect(editable).toHaveFocus();
 	},
 };
+
+const modeToggle = <ComposeModeToggle mode="rich" onToggle={() => undefined} />;
+
+/** The toolbar as compose ships it: the formatting cluster, then the mode. */
+export const ToolbarInRich: Story = {
+	name: "Toolbar with the mode toggle",
+	args: { initialHtml: RICH_DOCUMENT, trailing: modeToggle },
+};
+
+/**
+ * At 390 the formatting cluster runs out of room. It scrolls inside its own
+ * strip and the toggle stays pinned at the right edge, rather than the cluster
+ * pushing the toggle off the screen — which is what a flex child without
+ * `min-w-0` does.
+ */
+export const NarrowToolbar: Story = {
+	name: "Toolbar at 390",
+	args: { initialHtml: RICH_DOCUMENT, trailing: modeToggle },
+	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]",
+		);
+		if (!frame || !cluster || !toggle)
+			throw new Error("the toolbar is not mounted");
+
+		await expect(cluster.scrollWidth).toBeGreaterThan(cluster.clientWidth);
+		await expect(toggle.getBoundingClientRect().right).toBeLessThanOrEqual(
+			frame.getBoundingClientRect().right + 1,
+		);
+	},
+};
+
+/**
+ * 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)}`,
+		trailing: modeToggle,
+	},
+	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,8 @@ 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;
 }
 
 /**
@@ -161,6 +163,7 @@ export const RichTextEditor = ({
 	autoFocus = false,
 	placeholder = "Write your message…",
 	ariaLabel = "Message body",
+	trailing,
 }: RichTextEditorProps) => (
 	<LexicalComposer
 		initialConfig={{
@@ -177,7 +180,7 @@ 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={

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/);
+	});
+});

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

@@ -0,0 +1,155 @@
+import {
+	$convertFromMarkdownString,
+	$convertToMarkdownString,
+	type ElementTransformer,
+	isTableRowDivider,
+	TRANSFORMERS,
+	type Transformer,
+} from "@lexical/markdown";
+import {
+	$createTableCellNode,
+	$createTableNode,
+	$createTableRowNode,
+	$isTableCellNode,
+	$isTableNode,
+	$isTableRowNode,
+	TableCellHeaderStates,
+	TableCellNode,
+	TableNode,
+	TableRowNode,
+} from "@lexical/table";
+import { $isTextNode, type ElementNode, type LexicalNode } from "lexical";
+
+const TABLE_ROW = /^\|(.+)\|\s*$/;
+
+/**
+ * A cell is a document of its own, so its content goes through the same
+ * transformers. A newline or a bare pipe inside one would end the row early,
+ * which is the difference between a table and a wall of broken syntax.
+ */
+const exportCell = (cell: TableCellNode): string =>
+	$convertToMarkdownString(COMPOSE_TRANSFORMERS, cell)
+		.replace(/\n+/g, " ")
+		.replace(/\|/g, "\\|")
+		.trim();
+
+const splitRow = (line: string): string[] => {
+	const inner = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+	const cells: string[] = [];
+	let current = "";
+	for (let index = 0; index < inner.length; index++) {
+		const character = inner[index];
+		if (character === "\\" && inner[index + 1] === "|") {
+			current += "|";
+			index++;
+			continue;
+		}
+		if (character === "|") {
+			cells.push(current);
+			current = "";
+			continue;
+		}
+		current += character;
+	}
+	cells.push(current);
+	return cells;
+};
+
+const $createCell = (text: string): TableCellNode => {
+	const cell = $createTableCellNode(TableCellHeaderStates.NO_STATUS);
+	$convertFromMarkdownString(text.trim(), COMPOSE_TRANSFORMERS, cell);
+	return cell;
+};
+
+const $createRow = (texts: string[], columns: number): TableRowNode => {
+	const row = $createTableRowNode();
+	for (let index = 0; index < columns; index++) {
+		row.append($createCell(texts[index] ?? ""));
+	}
+	return row;
+};
+
+const columnsOf = (table: TableNode): number => {
+	const first = table.getFirstChild();
+	return $isTableRowNode(first) ? first.getChildrenSize() : 0;
+};
+
+const $markFirstRowAsHeader = (table: TableNode): void => {
+	const first = table.getFirstChild();
+	if (!$isTableRowNode(first)) return;
+	for (const cell of first.getChildren()) {
+		if (!$isTableCellNode(cell)) continue;
+		cell.setHeaderStyles(TableCellHeaderStates.ROW, TableCellHeaderStates.ROW);
+	}
+};
+
+/**
+ * `@lexical/markdown` 0.49 exports `isTableRowDivider` but no table
+ * transformer, so the composer supplies one over `@lexical/table` nodes. One
+ * list drives Markdown export, Markdown import and the cell round trip, which
+ * is what keeps a table that left as pipes coming back as a table.
+ *
+ * Import runs a line at a time, each line arriving as a paragraph. A row
+ * appended to the table its predecessor left behind is how the rows join up.
+ * A divider carries no content of its own: it says the row above is a header.
+ */
+export const TABLE: ElementTransformer = {
+	dependencies: [TableNode, TableRowNode, TableCellNode],
+	export: (node: LexicalNode): string | null => {
+		if (!$isTableNode(node)) return null;
+		const lines: string[] = [];
+		for (const row of node.getChildren()) {
+			if (!$isTableRowNode(row)) continue;
+			const cells = row.getChildren().filter($isTableCellNode);
+			if (cells.length === 0) continue;
+			lines.push(`| ${cells.map(exportCell).join(" | ")} |`);
+			// GFM only reads a block of pipe rows as a table when a divider follows
+			// the first one, so it is written whether or not that row was a header.
+			// Without it a recipient sees the pipes and no table.
+			if (lines.length === 1) {
+				lines.push(`| ${cells.map(() => "---").join(" | ")} |`);
+			}
+		}
+		return lines.length === 0 ? null : lines.join("\n");
+	},
+	regExp: TABLE_ROW,
+	replace: (parentNode: ElementNode, children, match): void => {
+		const line = match[0].trimEnd();
+		const previous = parentNode.getPreviousSibling();
+
+		if (isTableRowDivider(line)) {
+			if ($isTableNode(previous)) {
+				$markFirstRowAsHeader(previous);
+				parentNode.remove();
+				return;
+			}
+			// A divider with no rows above it is not a table. The import emptied
+			// this line's text node before calling here, so declining the match
+			// would drop the characters rather than leave them alone.
+			const first = children[0];
+			if ($isTextNode(first)) first.setTextContent(line);
+			return;
+		}
+
+		const texts = splitRow(line);
+		if ($isTableNode(previous)) {
+			previous.append($createRow(texts, columnsOf(previous)));
+			parentNode.remove();
+			return;
+		}
+
+		const table = $createTableNode();
+		table.append($createRow(texts, texts.length));
+		parentNode.replace(table);
+	},
+	type: "element",
+};
+
+/**
+ * The composer's own transformer set. Everything that reads or writes Markdown
+ * in compose uses this one list — the plain alternative on a rich send, the
+ * body of a plain send, the down-conversion of a paste, and both directions of
+ * the mode switch — so the conversions are inverses rather than four
+ * independent best efforts.
+ */
+export const COMPOSE_TRANSFORMERS: Transformer[] = [TABLE, ...TRANSFORMERS];