@remit/ui 0.0.106 → 0.0.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.106",
+  "version": "0.0.107",
   "type": "module",
   "files": [
     "src"

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

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
-import { expect, userEvent } from "storybook/test";
+import { expect, userEvent, waitFor } from "storybook/test";
 import { sanitizeAdoptedHtml } from "../lib/adopted-html.js";
 import { ComposeLanguageChip } from "./compose-language-chip.js";
 import {
@@ -8,6 +8,16 @@ import {
 	ComposeModeToggle,
 } from "./compose-mode-toggle.js";
 import { RichTextEditor } from "./rich-text-editor.js";
+import type {
+	CheckRequest,
+	Finding,
+	SpellcheckOptions,
+} from "./rich-text-spellcheck.js";
+import {
+	dictionaryFor,
+	findMisspellings,
+} from "./rich-text-spellcheck-words.js";
+import { openSpellcheckWorker } from "./rich-text-spellcheck-worker-provider.js";
 
 /**
  * The frame is the compose body region at its real geometry — a column with a
@@ -189,6 +199,159 @@ export const NarrowToolbar: Story = {
 	},
 };
 
+const MISSPELT = "Ths report is redy today, and the notes are attachd.";
+
+/**
+ * A real module worker does the checking, over the same messages an engine
+ * would answer: the component is handed a provider and never learns where the
+ * words came from. What the worker holds instead of a dictionary is a short
+ * list of English words.
+ */
+const workerSpellcheck: SpellcheckOptions = { provider: openSpellcheckWorker };
+
+/**
+ * The same findings, answered against the revision before the one asked for —
+ * what a slow engine looks like when the text has already moved on.
+ */
+const staleAnswers: string[] = [];
+
+const staleSpellcheck: SpellcheckOptions = {
+	provider: async () => ({
+		language: "en",
+		onStatus: (listener) => {
+			listener({ state: "ready", language: "en" });
+			return () => {};
+		},
+		check: (request: CheckRequest) => {
+			staleAnswers.push(request.requestId);
+			const words = dictionaryFor(request.language) ?? new Set<string>();
+			return Promise.resolve({
+				requestId: request.requestId,
+				revision: request.revision - 1,
+				findings: request.spans.flatMap((span) =>
+					findMisspellings(span.text, words).map(
+						(range): Finding => ({
+							spanId: span.spanId,
+							start: range.start,
+							end: range.end,
+							kind: "spelling",
+							suggestions: [],
+						}),
+					),
+				),
+			});
+		},
+		close: () => {},
+	}),
+};
+
+/**
+ * Every editor on the page shares the one registry entry, so a story reads back
+ * the marks that fall inside its own writing surface — on a docs page the
+ * neighbouring stories are drawing into it at the same time.
+ */
+const spellMarks = (editable: HTMLElement): AbstractRange[] => {
+	const ranges: AbstractRange[] = [];
+	CSS.highlights.forEach((highlight, name) => {
+		if (name !== "spell-error") return;
+		highlight.forEach((range) => {
+			if (editable.contains(range.startContainer)) ranges.push(range);
+		});
+	});
+	return ranges;
+};
+
+const spellMarkOffsets = (editable: HTMLElement): [number, number][] =>
+	spellMarks(editable).map((range) => [range.startOffset, range.endOffset]);
+
+const writingSurface = (canvasElement: HTMLElement): HTMLElement => {
+	const editable = canvasElement.querySelector<HTMLElement>(
+		"[data-testid=compose-body]",
+	);
+	if (!editable) throw new Error("the editor is not mounted");
+	return editable;
+};
+
+/**
+ * The marks a provider produced, drawn through the CSS Custom Highlight
+ * registry: two misspelt words carry a squiggle, the browser's own checking is
+ * off while ours is on, and the document holds nothing that was not typed.
+ */
+export const SpellcheckMarks: Story = {
+	name: "Spellcheck marks (worker provider)",
+	args: {
+		initialHtml: `<p>${MISSPELT}</p>`,
+		lang: "en",
+		spellcheck: workerSpellcheck,
+	},
+	play: async ({ canvasElement }) => {
+		const editable = writingSurface(canvasElement);
+
+		await waitFor(
+			() =>
+				expect(spellMarkOffsets(editable)).toEqual([
+					[0, 3],
+					[14, 18],
+					[44, 51],
+				]),
+			{ timeout: 5000 },
+		);
+		await expect(editable.getAttribute("spellcheck")).toBe("false");
+		await expect(editable.textContent).toBe(MISSPELT);
+		await expect(editable.querySelectorAll("[data-lexical-text]")).toHaveLength(
+			1,
+		);
+
+		// The word the caret sits in is left alone until the writer moves on.
+		await userEvent.click(editable);
+		const line = editable.querySelector<HTMLElement>("[data-lexical-text]");
+		const characters = line?.firstChild ?? null;
+		canvasElement.ownerDocument.getSelection()?.setPosition(characters, 17);
+
+		await waitFor(
+			() =>
+				expect(spellMarkOffsets(editable)).toEqual([
+					[0, 3],
+					[44, 51],
+				]),
+			{ timeout: 5000 },
+		);
+	},
+};
+
+/** A language the build carries no dictionary for: the browser keeps checking. */
+export const SpellcheckWithoutDictionary: Story = {
+	name: "Spellcheck with no dictionary for the language",
+	args: {
+		initialHtml: `<p>Vielen Dank für den Bericht.</p>`,
+		lang: "de",
+		spellcheck: workerSpellcheck,
+	},
+	play: async ({ canvasElement }) => {
+		const editable = writingSurface(canvasElement);
+		await expect(editable.getAttribute("spellcheck")).toBe("true");
+		await expect(spellMarks(editable)).toHaveLength(0);
+	},
+};
+
+/** An answer against a revision the document has moved past paints nothing. */
+export const SpellcheckStaleAnswer: Story = {
+	name: "Spellcheck drops a stale answer",
+	args: {
+		initialHtml: `<p>${MISSPELT}</p>`,
+		lang: "en",
+		spellcheck: staleSpellcheck,
+	},
+	play: async ({ canvasElement }) => {
+		const editable = writingSurface(canvasElement);
+		await waitFor(() => expect(staleAnswers.length).toBeGreaterThan(0), {
+			timeout: 5000,
+		});
+		await expect(spellMarks(editable)).toHaveLength(0);
+		await expect(editable.textContent).toBe(MISSPELT);
+	},
+};
+
 /**
  * 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

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

@@ -9,19 +9,28 @@ import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";
 import { TablePlugin } from "@lexical/react/LexicalTablePlugin";
 import { mergeRegister } from "@lexical/utils";
 import {
+	$getNodeByKey,
 	$getRoot,
 	$getSelection,
 	$insertNodes,
 	$isRangeSelection,
+	$isTextNode,
 	COMMAND_PRIORITY_CRITICAL,
 	COMMAND_PRIORITY_LOW,
 	KEY_DOWN_COMMAND,
 	type LexicalEditor,
 	PASTE_COMMAND,
 } from "lexical";
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { $adoptHtml, $readRichText } from "./rich-text-document.js";
 import { RICH_TEXT_NODES, richTextTheme } from "./rich-text-nodes.js";
+import type {
+	CheckSpan,
+	Finding,
+	ProviderStatus,
+	SpellcheckOptions,
+	SpellProvider,
+} from "./rich-text-spellcheck.js";
 import { RichTextToolbar } from "./rich-text-toolbar.js";
 import type { RichTextValue } from "./rich-text-value.js";
 
@@ -44,6 +53,13 @@ export interface RichTextEditorProps {
 	 * ignore it. Every screen reader picks a voice from it.
 	 */
 	lang?: string;
+	/**
+	 * Where checking comes from. Left out, the browser does its own and the
+	 * editor behaves as it does today. The engine is injected: this component
+	 * never imports one, and a `provider` resolving null means no dictionary for
+	 * `lang`, which is also when the browser keeps checking.
+	 */
+	spellcheck?: SpellcheckOptions;
 }
 
 /**
@@ -141,6 +157,282 @@ const ChangePlugin = ({
 	return null;
 };
 
+const SPELLCHECK_IDLE_MS = 250;
+const SPELLCHECK_HIGHLIGHT = "spell-error";
+
+interface SpellMarks {
+	add(range: Range): void;
+}
+
+interface MarkRegistry {
+	set(name: string, marks: SpellMarks): void;
+	delete(name: string): void;
+}
+
+/**
+ * The registry is read off the global rather than through the DOM typings,
+ * which describe `Highlight` without the members that put a range in it. Where
+ * a browser has neither, nothing is drawn and the provider is never opened.
+ */
+interface MarkHost {
+	CSS?: { highlights?: MarkRegistry };
+	Highlight?: new () => SpellMarks;
+}
+
+const markHost = (): MarkHost => globalThis as unknown as MarkHost;
+
+const marksSupported = (): boolean => {
+	const host = markHost();
+	return Boolean(host.CSS?.highlights) && typeof host.Highlight === "function";
+};
+
+/**
+ * One registry entry carries the marks of every editor on the page, because a
+ * highlight name is a page-wide thing and `::highlight(spell-error)` names it
+ * statically. Each editor owns its own ranges here and hands over the whole set
+ * each pass, so a second composer neither overwrites the first nor takes its
+ * marks down when it closes.
+ */
+const painters = new Map<symbol, readonly Range[]>();
+
+const paintMarks = (painter: symbol, ranges: readonly Range[]): void => {
+	const host = markHost();
+	const registry = host.CSS?.highlights;
+	const Marks = host.Highlight;
+	if (!registry || !Marks) return;
+	if (ranges.length === 0) painters.delete(painter);
+	else painters.set(painter, ranges);
+
+	const marks = new Marks();
+	let drawn = 0;
+	for (const owned of painters.values())
+		for (const range of owned) {
+			marks.add(range);
+			drawn += 1;
+		}
+	if (drawn === 0) {
+		registry.delete(SPELLCHECK_HIGHLIGHT);
+		return;
+	}
+	registry.set(SPELLCHECK_HIGHLIGHT, marks);
+};
+
+/**
+ * The characters of a leaf. A format Lexical renders with a tag of its own —
+ * code, subscript, superscript — puts the text one level further down, so the
+ * element the node key resolves to is not always the text itself.
+ */
+const leafCharacters = (node: Node): Node | null => {
+	if (node.nodeType === Node.TEXT_NODE) return node;
+	for (let child = node.firstChild; child; child = child.nextSibling) {
+		const characters = leafCharacters(child);
+		if (characters) return characters;
+	}
+	return null;
+};
+
+/**
+ * Marks, and nothing else. Only the leaves an edit touched are sent, a quarter
+ * of a second after the typing stops, so a word is not called wrong while it is
+ * still being written — and the word the caret sits in is never marked at all.
+ * An answer carrying a revision the document has moved past is dropped.
+ *
+ * The marks live in the highlight registry, keyed by node key and rebuilt after
+ * every reconciliation. Nothing enters the document, so history, the outgoing
+ * HTML and the Markdown never see one.
+ */
+const SpellcheckPlugin = ({
+	language,
+	options,
+	onReady,
+}: {
+	language: string;
+	options: SpellcheckOptions;
+	onReady: (ready: boolean) => void;
+}) => {
+	const [editor] = useLexicalComposerContext();
+	const settings = useRef(options);
+	const report = useRef(onReady);
+
+	useEffect(() => {
+		settings.current = options;
+		report.current = onReady;
+	}, [options, onReady]);
+
+	useEffect(() => {
+		if (!marksSupported()) return;
+		const painter = Symbol(SPELLCHECK_HIGHLIGHT);
+		const found = new Map<string, readonly Finding[]>();
+		const touched = new Set<string>();
+		let provider: SpellProvider | null = null;
+		let unsubscribe: (() => void) | undefined;
+		let idle: ReturnType<typeof setTimeout> | undefined;
+		let live = true;
+		let state: ProviderStatus["state"] = "opening";
+		let revision = 0;
+		let asked = 0;
+
+		const repaint = (): void => {
+			const ranges: Range[] = [];
+			editor.read(() => {
+				const selection = $getSelection();
+				const caret =
+					$isRangeSelection(selection) && selection.isCollapsed()
+						? selection.anchor
+						: null;
+				for (const [key, findings] of found) {
+					const node = $getNodeByKey(key);
+					if (!$isTextNode(node)) {
+						found.delete(key);
+						continue;
+					}
+					const element = editor.getElementByKey(key);
+					const text = element ? leafCharacters(element) : null;
+					if (!text) continue;
+					const length = text.textContent?.length ?? 0;
+					for (const finding of findings) {
+						if (finding.end > length) continue;
+						if (
+							caret?.key === key &&
+							caret.offset > finding.start &&
+							caret.offset <= finding.end
+						)
+							continue;
+						const range = text.ownerDocument?.createRange();
+						if (!range) continue;
+						range.setStart(text, finding.start);
+						range.setEnd(text, finding.end);
+						ranges.push(range);
+					}
+				}
+			});
+			paintMarks(painter, ranges);
+		};
+
+		const check = (): void => {
+			// Anything queued while the provider is not answering stays queued: the
+			// next status that says ready sends it.
+			if (!provider || state !== "ready") return;
+			const keys = [...touched];
+			touched.clear();
+			const spans: CheckSpan[] = [];
+			editor.read(() => {
+				for (const key of keys) {
+					const node = $getNodeByKey(key);
+					if (!$isTextNode(node)) {
+						found.delete(key);
+						continue;
+					}
+					spans.push({ spanId: key, text: node.getTextContent() });
+				}
+			});
+			if (spans.length === 0) {
+				repaint();
+				return;
+			}
+			asked += 1;
+			const sent = revision;
+			provider
+				.check({ requestId: `${asked}`, language, revision: sent, spans })
+				.then((response) => {
+					if (!live) return;
+					// The text moved while this was in flight, so the offsets are
+					// answers to a document that no longer exists. The leaves go back
+					// on the queue: dropping them here would leave them unchecked
+					// until the writer happened to touch them again.
+					if (response.revision !== revision) {
+						for (const span of spans) touched.add(span.spanId);
+						schedule();
+						return;
+					}
+					const grouped = new Map<string, Finding[]>();
+					for (const finding of response.findings) {
+						const list = grouped.get(finding.spanId);
+						if (list) {
+							list.push(finding);
+							continue;
+						}
+						grouped.set(finding.spanId, [finding]);
+					}
+					for (const span of spans) found.delete(span.spanId);
+					for (const [key, findings] of grouped) found.set(key, findings);
+					repaint();
+				});
+		};
+
+		const schedule = (): void => {
+			clearTimeout(idle);
+			idle = setTimeout(check, SPELLCHECK_IDLE_MS);
+		};
+
+		const unregister = editor.registerUpdateListener(({ dirtyLeaves }) => {
+			if (dirtyLeaves.size === 0) {
+				repaint();
+				return;
+			}
+			revision += 1;
+			// Characters moved under the findings this leaf carries, so they are
+			// answers about text that is no longer there. They go now rather than
+			// sitting over the wrong letters until the next answer arrives.
+			for (const key of dirtyLeaves) {
+				found.delete(key);
+				touched.add(key);
+			}
+			repaint();
+			schedule();
+		});
+
+		settings.current.provider(language).then((opened) => {
+			if (!live) {
+				opened?.close();
+				return;
+			}
+			provider = opened;
+			if (!opened) {
+				settings.current.onStatus?.({ state: "unavailable", language });
+				report.current(false);
+				return;
+			}
+			unsubscribe = opened.onStatus((status) => {
+				state = status.state;
+				settings.current.onStatus?.(status);
+				const ready = status.state === "ready";
+				report.current(ready);
+				if (ready) {
+					schedule();
+					return;
+				}
+				// Checking stopped, so the browser's own is back. Its squiggles are
+				// the only ones on screen from here.
+				found.clear();
+				touched.clear();
+				repaint();
+			});
+			// The document the editor opened on was reconciled before this
+			// listener existed, so its leaves are checked here rather than waiting
+			// for an edit that may never come.
+			editor.read(() => {
+				for (const node of $getRoot().getAllTextNodes())
+					touched.add(node.getKey());
+			});
+			schedule();
+		});
+
+		return () => {
+			live = false;
+			clearTimeout(idle);
+			unregister();
+			unsubscribe?.();
+			provider?.close();
+			provider = null;
+			report.current(false);
+			paintMarks(painter, []);
+		};
+	}, [editor, language]);
+
+	return null;
+};
+
 const AutoFocus = ({ enabled }: { enabled: boolean }) => {
 	const [editor] = useLexicalComposerContext();
 
@@ -171,56 +463,75 @@ export const RichTextEditor = ({
 	ariaLabel = "Message body",
 	trailing,
 	lang,
-}: RichTextEditorProps) => (
-	<LexicalComposer
-		initialConfig={{
-			namespace: "compose",
-			nodes: RICH_TEXT_NODES,
-			theme: richTextTheme,
-			editorState: initialHtml ? seedDocument(initialHtml) : undefined,
-			onError: (error) => {
-				throw error;
-			},
-		}}
-	>
-		{/* The editable claims the height its container offers rather than only the
-		    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 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"
-							className="min-h-[120px] w-full shrink-0 grow bg-canvas px-3 py-2 text-sm text-fg outline-none"
-							placeholder={
-								<div className="pointer-events-none absolute inset-x-0 top-0 px-3 py-2 text-sm text-fg-subtle">
-									{placeholder}
-								</div>
-							}
-							onKeyDown={(event) => {
-								if (!onSubmit) return;
-								if (!(event.metaKey || event.ctrlKey) || event.key !== "Enter")
-									return;
-								event.preventDefault();
-								onSubmit();
-							}}
-						/>
-					}
-					ErrorBoundary={LexicalErrorBoundary}
-				/>
+	spellcheck,
+}: RichTextEditorProps) => {
+	const [checkedHere, setCheckedHere] = useState(false);
+
+	return (
+		<LexicalComposer
+			initialConfig={{
+				namespace: "compose",
+				nodes: RICH_TEXT_NODES,
+				theme: richTextTheme,
+				editorState: initialHtml ? seedDocument(initialHtml) : undefined,
+				onError: (error) => {
+					throw error;
+				},
+			}}
+		>
+			{/* The editable claims the height its container offers rather than only the
+			    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 trailing={trailing} />
+				<div className="relative flex shrink-0 grow flex-col">
+					<RichTextPlugin
+						contentEditable={
+							<ContentEditable
+								lang={lang}
+								/* Two sets of squiggles never coexist: the browser stops
+								   checking exactly while a provider of ours is ready, and
+								   checks again the moment one is not. */
+								spellCheck={spellcheck ? !checkedHere : undefined}
+								aria-label={ariaLabel}
+								aria-placeholder={placeholder}
+								data-testid="compose-body"
+								className="min-h-[120px] w-full shrink-0 grow bg-canvas px-3 py-2 text-sm text-fg outline-none"
+								placeholder={
+									<div className="pointer-events-none absolute inset-x-0 top-0 px-3 py-2 text-sm text-fg-subtle">
+										{placeholder}
+									</div>
+								}
+								onKeyDown={(event) => {
+									if (!onSubmit) return;
+									if (
+										!(event.metaKey || event.ctrlKey) ||
+										event.key !== "Enter"
+									)
+										return;
+									event.preventDefault();
+									onSubmit();
+								}}
+							/>
+						}
+						ErrorBoundary={LexicalErrorBoundary}
+					/>
+				</div>
 			</div>
-		</div>
-		<HistoryPlugin />
-		<ListPlugin />
-		<LinkPlugin />
-		<TablePlugin />
-		<PastePlugin />
-		<AutoFocus enabled={autoFocus} />
-		{onChange && <ChangePlugin onChange={onChange} />}
-	</LexicalComposer>
-);
+			<HistoryPlugin />
+			<ListPlugin />
+			<LinkPlugin />
+			<TablePlugin />
+			<PastePlugin />
+			<AutoFocus enabled={autoFocus} />
+			{onChange && <ChangePlugin onChange={onChange} />}
+			{spellcheck && lang ? (
+				<SpellcheckPlugin
+					language={lang}
+					options={spellcheck}
+					onReady={setCheckedHere}
+				/>
+			) : null}
+		</LexicalComposer>
+	);
+};