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.mjsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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 updiff --git a/packages/richtext/src/markdownTable.ts b/packages/richtext/src/markdownTable.tsindex 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,];