Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(richtext): continue a block across soft line breaks, as Markdown reads it (#7000)

Cindy Zhang8701623a13ef
diff --git a/packages/richtext/src/RichTextEditor.doc.mjs b/packages/richtext/src/RichTextEditor.doc.mjs
index 3d24a5c244..a10f5877d8 100644
--- a/packages/richtext/src/RichTextEditor.doc.mjs
+++ b/packages/richtext/src/RichTextEditor.doc.mjs
@@ -109,14 +109,14 @@ export const docs = {
name: 'hasMarkdownShortcuts',
type: 'boolean',
description:
- 'Enable Markdown shortcut typing (e.g. "# " for a heading). Uses the transformers prop (defaults to the standard @lexical/markdown transformers plus GFM tables).',
+ 'Enable Markdown shortcut typing (e.g. "# " for a heading). Uses the transformers prop (defaults to the standard @lexical/markdown transformers, hard line breaks, and GFM tables).',
default: 'true',
},
{
name: 'transformers',
type: 'ReadonlyArray<Transformer>',
description:
- 'Markdown transformers: the single source of truth for markdown behaviour. Defaults to the standard @lexical/markdown TRANSFORMERS plus GFM tables; a custom array replaces the default, tables included. In Lexical the same array drives all three markdown operations (shortcut typing, markdown->state import, state->markdown export); this prop wires shortcut typing today and is the intended input for the serialization APIs added in later phases. Pass a custom array to support additional node types (e.g. transformers layered in via the nodes extension point) consistently across all three. Shortcut typing is only applied when hasMarkdownShortcuts is true.',
+ 'Markdown transformers: the single source of truth for markdown behaviour. Defaults to the standard @lexical/markdown TRANSFORMERS, hard line breaks (a line break typed with Shift+Enter exports as a backslash before the line ending, so it reads back as a line break), and GFM tables; a custom array replaces the default, tables included. In Lexical the same array drives all three markdown operations (shortcut typing, markdown->state import, state->markdown export); this prop wires shortcut typing today and is the intended input for the serialization APIs added in later phases. Pass a custom array to support additional node types (e.g. transformers layered in via the nodes extension point) consistently across all three. Shortcut typing is only applied when hasMarkdownShortcuts is true.',
default: 'TRANSFORMERS',
},
{
diff --git a/packages/richtext/src/markdownHardLineBreak.ts b/packages/richtext/src/markdownHardLineBreak.ts
new file mode 100644
index 0000000000..787abb0381
--- /dev/null
+++ b/packages/richtext/src/markdownHardLineBreak.ts
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownHardLineBreak.ts
+ * @input Uses lexical (LineBreakNode) and @lexical/markdown
+ * (TextMatchTransformer).
+ * @output Exports HARD_LINE_BREAK, the transformer that writes a line break
+ * added in the editor (Shift+Enter) as a Markdown hard break, `\` and a
+ * line ending.
+ * @position Part of DEFAULT_TRANSFORMERS (markdownTable.ts). Import joins
+ * soft line breaks into their block (markdownSource.ts), so every line
+ * break left in a paragraph, list item, or quote is a hard one. Lexical
+ * writes the breaks it imported as hard with their own marker (two spaces
+ * or a backslash); a break typed in the editor has none and would be
+ * written as a plain line ending, which reads back as a soft break and
+ * loses the line (spec:AST-062 FR3). Headings are one line in Markdown, so
+ * a break typed in one keeps Lexical's plain line ending.
+ */
+
+import type {TextMatchTransformer} from '@lexical/markdown';
+import {$isHeadingNode} from '@lexical/rich-text';
+import {$findMatchingParent} from '@lexical/utils';
+import {$isLineBreakNode, LineBreakNode} from 'lexical';
+
+/** Whether Lexical's Markdown import marked this line break as a hard one. */
+export function isMarkedHardLineBreak(node: LineBreakNode): boolean {
+ const serialized = node.exportJSON() as {$?: {mdHardLineBreak?: unknown}};
+ return (
+ typeof serialized.$?.mdHardLineBreak === 'string' &&
+ serialized.$.mdHardLineBreak !== ''
+ );
+}
+
+export const HARD_LINE_BREAK: TextMatchTransformer = {
+ dependencies: [LineBreakNode],
+ export: node =>
+ $isLineBreakNode(node) &&
+ !isMarkedHardLineBreak(node) &&
+ // A heading is one line in Markdown; a break inside one has no hard-break
+ // form, so it keeps Lexical's plain line ending.
+ $findMatchingParent(node, $isHeadingNode) == null
+ ? '\\\n'
+ : null,
+ // Export only: Lexical's own import recognizes hard breaks.
+ regExp: /(?!)/,
+ type: 'text-match',
+};
diff --git a/packages/richtext/src/markdownSource.test.tsx b/packages/richtext/src/markdownSource.test.tsx
index 814f4e7d48..4a2cedc345 100644
--- a/packages/richtext/src/markdownSource.test.tsx
+++ b/packages/richtext/src/markdownSource.test.tsx
@@ -17,6 +17,7 @@ import {
$getRoot,
$isElementNode,
$parseSerializedNode,
+ INSERT_LINE_BREAK_COMMAND,
REDO_COMMAND,
UNDO_COMMAND,
type SerializedLexicalNode,
@@ -27,7 +28,11 @@ import {
editorStateJSONToMarkdown,
markdownToEditorStateJSON,
} from './markdownSerializers';
-import {absentToken, splitMarkdownChunks} from './markdownSource';
+import {
+ $joinSoftLineBreaks,
+ absentToken,
+ splitMarkdownChunks,
+} from './markdownSource';
import {RichTextEditor, type RichTextEditorRef} from './RichTextEditor';
import {RichTextEditorAutoLinkPlugin} from './RichTextEditorAutoLinkPlugin';
@@ -35,6 +40,12 @@ import {RichTextEditorAutoLinkPlugin} from './RichTextEditorAutoLinkPlugin';
* The conformance corpus for spec:AST-062. Each document must come back byte
* for byte from a no-op round trip, whatever RichText makes of it.
*/
+interface SerializedShapeNode {
+ readonly type: string;
+ readonly text?: string;
+ readonly children?: ReadonlyArray<SerializedShapeNode>;
+}
+
const CORPUS: Record<string, string> = {
empty: '',
whitespaceOnly: ' \n\n\t\n',
@@ -277,7 +288,7 @@ describe('Markdown source preservation (spec:AST-062)', () => {
// group writes two paragraphs, in the group's CRLF style.
expect(
editAndExport(crlf, () => $appendToBlockContaining('First', ' one')),
- ).toBe('\uFEFF\r\n# Title\r\n\r\nFirst one\r\nsecond line\r\n\r\nLast\r\n');
+ ).toBe('\uFEFF\r\n# Title\r\n\r\nFirst second line one\r\n\r\nLast\r\n');
expect(
editAndExport(crlf, () => {
const paragraph = $createParagraphNode();
@@ -324,7 +335,8 @@ describe('Markdown source preservation (spec:AST-062)', () => {
it('imports the same structure as importing the whole document at once', () => {
// Node state aside, chunked import must build exactly the tree Lexical's
- // own import builds: soft breaks, lazy continuation lines, loose lists.
+ // own import builds, soft breaks joined: lazy continuation lines, loose
+ // lists, and line breaks all land in the same blocks.
const structureOf = (json: string): unknown =>
JSON.parse(json, (key, value: unknown) =>
key === '$' ? undefined : value,
@@ -343,6 +355,7 @@ describe('Markdown source preservation (spec:AST-062)', () => {
markdown.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n'),
[...DEFAULT_TRANSFORMERS],
);
+ $joinSoftLineBreaks($getRoot());
},
{discrete: true},
);
@@ -355,6 +368,138 @@ describe('Markdown source preservation (spec:AST-062)', () => {
}
});
+ it('continues a block across soft line breaks and keeps hard breaks', () => {
+ const shape = (markdown: string): string => {
+ const {root} = JSON.parse(markdownToEditorStateJSON(markdown)) as {
+ root: SerializedShapeNode;
+ };
+ const describe = (node: SerializedShapeNode): string =>
+ node.children != null
+ ? `${node.type}[${node.children.map(describe).join(',')}]`
+ : node.type === 'text'
+ ? JSON.stringify(node.text)
+ : node.type;
+ return root.children?.map(describe).join(' ') ?? '';
+ };
+ expect(shape('One line\nsame paragraph\nstill same\n')).toBe(
+ 'paragraph["One line same paragraph still same"]',
+ );
+ expect(shape('Two spaces \nand a backslash\\\nend\n')).toBe(
+ 'paragraph["Two spaces",linebreak,"and a backslash",linebreak,"end"]',
+ );
+ expect(shape('- An item\n that continues\n')).toBe(
+ 'list[listitem["An item that continues"]]',
+ );
+ expect(shape('> A quote\n> on two lines\n')).toBe(
+ 'quote["A quote on two lines"]',
+ );
+ expect(shape('**Bold**\nthen plain\n')).toBe(
+ 'paragraph["Bold"," then plain"]',
+ );
+ // Code keeps its line endings.
+ expect(shape('```\nline one\nline two\n```\n')).toBe(
+ 'code["line one\\nline two"]',
+ );
+ // An edited paragraph is written again on one line.
+ expect(
+ editAndExport('One line\nsame paragraph\n\nNext\n', () =>
+ $appendToTextContaining('One line', ' edited'),
+ ),
+ ).toBe('One line same paragraph edited\n\nNext\n');
+ });
+
+ it('writes a line break typed in the editor as a hard break that survives a reload (FR3)', async () => {
+ const markdown =
+ 'Ada Lovelace\n\n- item one\n\n> quoted text\n\nTwo spaces \nkept\n\n```\ncode line\n```\n';
+ const ref = createRef<RichTextEditorRef>();
+ render(
+ <RichTextEditor
+ label="Notes"
+ ref={ref}
+ defaultValue={markdownToEditorStateJSON(markdown)}
+ />,
+ );
+ // Edit only once the document has loaded.
+ await waitFor(() => expect(ref.current?.getMarkdown()).toBe(markdown));
+ const editor = ref.current?.getEditor();
+ // Shift+Enter after the first word of the paragraph, the list item, the
+ // quote, and the code line.
+ for (const text of [
+ 'Ada Lovelace',
+ 'item one',
+ 'quoted text',
+ 'code line',
+ ]) {
+ editor?.update(
+ () => {
+ const node = $getRoot()
+ .getAllTextNodes()
+ .find(candidate => candidate.getTextContent().startsWith(text));
+ node?.select(text.indexOf(' '), text.indexOf(' '));
+ },
+ {discrete: true},
+ );
+ editor?.dispatchCommand(INSERT_LINE_BREAK_COMMAND, false);
+ }
+ const edited =
+ 'Ada\\\n Lovelace\n\n- item\\\n one\n\n> quoted\\\n> text\n\nTwo spaces \nkept\n\n```\ncode\n line\n```\n';
+ await waitFor(() => expect(ref.current?.getMarkdown()).toBe(edited));
+ // A reload keeps every typed break as a line break.
+ const reloaded = JSON.parse(markdownToEditorStateJSON(edited)) as {
+ root: SerializedShapeNode;
+ };
+ const lineBreaks = (node: SerializedShapeNode): number =>
+ (node.type === 'linebreak' ? 1 : 0) +
+ (node.children ?? []).reduce(
+ (count, child) => count + lineBreaks(child),
+ 0,
+ );
+ // Paragraph, list item, quote, and the imported two-space break; the
+ // code line break is part of the code text.
+ expect(lineBreaks(reloaded.root)).toBe(4);
+ expect(editorStateJSONToMarkdown(markdownToEditorStateJSON(edited))).toBe(
+ edited,
+ );
+ editor?.dispatchCommand(UNDO_COMMAND, undefined);
+ await waitFor(() => expect(ref.current?.getMarkdown()).not.toBe(edited));
+ editor?.dispatchCommand(REDO_COMMAND, undefined);
+ await waitFor(() => expect(ref.current?.getMarkdown()).toBe(edited));
+ });
+
+ it('leaves a line break typed in a heading as Lexical writes it', async () => {
+ const ref = createRef<RichTextEditorRef>();
+ render(
+ <RichTextEditor
+ label="Notes"
+ ref={ref}
+ defaultValue={markdownToEditorStateJSON('## Release title\n\nBody\n')}
+ />,
+ );
+ // Edit only once the document has loaded.
+ await waitFor(() =>
+ expect(ref.current?.getMarkdown()).toBe('## Release title\n\nBody\n'),
+ );
+ const editor = ref.current?.getEditor();
+ editor?.update(
+ () => {
+ const node = $getRoot()
+ .getAllTextNodes()
+ .find(candidate => candidate.getTextContent() === 'Release title');
+ node?.select(7, 7);
+ },
+ {discrete: true},
+ );
+ editor?.dispatchCommand(INSERT_LINE_BREAK_COMMAND, false);
+ // No backslash: a heading has no hard-break form.
+ const markdown = '## Release\n title\n\nBody\n';
+ await waitFor(() => expect(ref.current?.getMarkdown()).toBe(markdown));
+ const {root} = JSON.parse(markdownToEditorStateJSON(markdown)) as {
+ root: SerializedShapeNode;
+ };
+ expect(root.children?.[0]?.type).toBe('heading');
+ expect(JSON.stringify(root)).not.toContain('\\\\');
+ });
+
it('keeps document facts at the document when blocks move, repeat, or go (FR4)', () => {
const source = '\uFEFF\n\nAlpha\n\n\\# Beta\n\nGamma\n\n';
// Moving the first block to the end keeps the envelope at the edges.
diff --git a/packages/richtext/src/markdownSource.ts b/packages/richtext/src/markdownSource.ts
index 041828d3b7..d8ccc53d47 100644
--- a/packages/richtext/src/markdownSource.ts
+++ b/packages/richtext/src/markdownSource.ts
@@ -34,6 +34,7 @@ import {
import {$isCodeNode} from '@lexical/code';
import {
$createParagraphNode,
+ $createTextNode,
$getRoot,
$getState,
$isElementNode,
@@ -45,6 +46,7 @@ import {
type LexicalEditor,
type LexicalNode,
} from 'lexical';
+import {isMarkedHardLineBreak} from './markdownHardLineBreak';
/** The whitespace and content one chunk of Markdown source was split into. */
export interface MarkdownChunk {
@@ -306,6 +308,7 @@ export function importMarkdownKeepingSource(
transformers,
holder,
);
+ $joinSoftLineBreaks(holder);
for (const node of holder.getChildren()) {
$setState(node, groupState, {group: `${importId}:${index}`});
}
@@ -342,6 +345,36 @@ export function importMarkdownKeepingSource(
);
}
+/**
+ * Joins the lines of a paragraph, list item, or block quote across soft line
+ * breaks: a line ending without two trailing spaces or a backslash continues
+ * the block, as one space (CommonMark, soft line breaks; spec:AST-061 FR5).
+ * Lexical imports every line ending as a line break and marks the hard ones,
+ * so the unmarked ones outside code are the soft breaks.
+ */
+export function $joinSoftLineBreaks(element: ElementNode): void {
+ for (const child of element.getChildren()) {
+ if ($isElementNode(child) && !$isCodeNode(child)) {
+ $joinSoftLineBreaks(child);
+ }
+ }
+ for (const child of element.getChildren()) {
+ if (!$isLineBreakNode(child) || isMarkedHardLineBreak(child)) {
+ continue;
+ }
+ // The spaces around a soft break are part of it.
+ const previous = child.getPreviousSibling();
+ if ($isTextNode(previous) && !previous.hasFormat('code')) {
+ previous.setTextContent(previous.getTextContent().replace(/[ \t]+$/, ''));
+ }
+ const next = child.getNextSibling();
+ if ($isTextNode(next) && !next.hasFormat('code')) {
+ next.setTextContent(next.getTextContent().replace(/^[ \t]+/, ''));
+ }
+ child.replace($createTextNode(' '));
+ }
+}
+
/**
* Turns the first pass's chunk stamps into groups. Consecutive nodes stamped
* with one chunk form a group, and the group also covers every later chunk up
diff --git a/packages/richtext/src/markdownTable.ts b/packages/richtext/src/markdownTable.ts
index 983a22d6d8..c19842a3a4 100644
--- a/packages/richtext/src/markdownTable.ts
+++ b/packages/richtext/src/markdownTable.ts
@@ -37,6 +37,7 @@ import {
TableRowNode,
} from '@lexical/table';
import type {ElementFormatType} from 'lexical';
+import {HARD_LINE_BREAK} from './markdownHardLineBreak';
/**
* Cells hold inline Markdown only, so they are imported and exported with the
@@ -234,10 +235,11 @@ export const TABLE: MultilineElementTransformer = {
};
/**
- * The editor's default Markdown transformers: Lexical's standard set plus GFM
- * tables.
+ * The editor's default Markdown transformers: Lexical's standard set, hard
+ * line breaks for breaks typed in the editor, and GFM tables.
*/
export const DEFAULT_TRANSFORMERS: ReadonlyArray<Transformer> = [
...TRANSFORMERS,
+ HARD_LINE_BREAK,
TABLE,
];