Skip to content

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

TypeScript

feat(richtext): adopt Markdown plugins in import and export, with a server-safe markdown entry (#7039)

Cindy Zhang1f63a932c12f
diff --git a/apps/storybook/stories/RichTextEditor.markdownPluginsImportExport.tsx b/apps/storybook/stories/RichTextEditor.markdownPluginsImportExport.tsx
new file mode 100644
index 0000000000..67fe255797
--- /dev/null
+++ b/apps/storybook/stories/RichTextEditor.markdownPluginsImportExport.tsx
@@ -0,0 +1,333 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RichTextEditor.markdownPluginsImportExport.tsx
+ * @input Uses core's Markdown plugin protocol and the RichText serializers,
+ * editor, and plugin adapter.
+ * @output Exports MarkdownPluginsImportExport: Markdown with plugin syntax in,
+ * the plugin nodes RichText recognized, and the Markdown it exports beside
+ * the input, byte for byte; an editor to change the text around the nodes;
+ * and a refused plugin's error.
+ * @position Lab story for spec:AST-064's import and export. How plugin nodes
+ * look in the editor and the view is the "Markdown plugins" story.
+ */
+
+import {useMemo, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Button} from '@astryxdesign/core/Button';
+import {Text} from '@astryxdesign/core/Text';
+import {
+ colorVars,
+ radiusVars,
+ spacingVars,
+ typographyVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import {
+ createMarkdownPlugin,
+ type MarkdownExtensionNode,
+} from '@astryxdesign/core/Markdown/plugins';
+import {
+ createRichTextExtension,
+ editorStateJSONToMarkdown,
+ markdownToEditorStateJSON,
+ RichTextEditor,
+ type RichTextEditorRef,
+} from '@astryxdesign/richtext';
+
+type MentionNode = MarkdownExtensionNode<
+ 'story-mentions',
+ 'mention',
+ {readonly handle: string},
+ 'inline'
+>;
+type NoteNode = MarkdownExtensionNode<
+ 'story-notes',
+ 'note',
+ {readonly body: string},
+ 'block'
+>;
+
+const mentions = createMarkdownPlugin<'story-mentions', MentionNode>({
+ name: 'story-mentions',
+ apiVersion: 1,
+ parseKey: 'v1',
+ syntax: {
+ inline: [
+ {
+ startsWith: ['@{'],
+ maxSpan: 64,
+ tokenize({source, offset, end}) {
+ const close = source.indexOf('}', offset + 2);
+ if (close < 0 || close >= end) {
+ return {status: 'no-match'};
+ }
+ return {
+ status: 'match',
+ end: close + 1,
+ node: {
+ type: 'extension',
+ plugin: 'story-mentions',
+ name: 'mention',
+ display: 'inline',
+ data: {handle: source.slice(offset + 2, close)},
+ },
+ };
+ },
+ },
+ ],
+ },
+ renderers: {
+ mention: {
+ render: ({node}) => (
+ <a href={`#people/${node.data.handle}`}>@{node.data.handle}</a>
+ ),
+ toText: node => `@${node.data.handle}`,
+ },
+ },
+});
+
+const notes = createMarkdownPlugin<'story-notes', NoteNode>({
+ name: 'story-notes',
+ apiVersion: 1,
+ parseKey: 'v1',
+ syntax: {
+ block: [
+ {
+ startsWith: [':::note'],
+ maxSpan: 400,
+ tokenize({source, offset, end}) {
+ const close = source.indexOf('\n:::', offset);
+ if (close < 0 || close + 4 > end) {
+ return {status: 'no-match'};
+ }
+ return {
+ status: 'match',
+ end: close + 4,
+ node: {
+ type: 'extension',
+ plugin: 'story-notes',
+ name: 'note',
+ display: 'block',
+ data: {body: source.slice(offset + 8, close)},
+ },
+ };
+ },
+ },
+ ],
+ },
+ renderers: {
+ note: {
+ render: ({node}) => <aside aria-label="Note">{node.data.body}</aside>,
+ toText: node => node.data.body,
+ },
+ },
+});
+
+/** A plugin RichText refuses: it declares an immutable transform. */
+const shouting = createMarkdownPlugin({
+ name: 'story-shouting',
+ apiVersion: 1,
+ transform: root => root,
+});
+
+const EXTENSIONS = [
+ createRichTextExtension(mentions),
+ createRichTextExtension(notes),
+];
+
+const SAMPLE = [
+ 'Ping @{ada} about the review.',
+ '',
+ 'Marks stay around nodes: *see @{grace} here*, **ask @{linus}**, and ~~not @{old}~~.',
+ 'Inside link text a mention stays text, as in Markdown: [ask @{ada}](https://example.com).',
+ 'Code is never a node: `@{ada}` stays code.',
+ 'This line ends a paragraph',
+ ':::note',
+ 'and this note starts on the next line.',
+ ':::',
+ '',
+].join('\n');
+
+const FORMATS: ReadonlyArray<readonly [number, string]> = [
+ [1, 'bold'],
+ [2, 'italic'],
+ [4, 'strikethrough'],
+];
+
+interface Recognized {
+ readonly plugin: string;
+ readonly display: string;
+ readonly source: string;
+ readonly marks: string;
+}
+
+function recognized(json: string): Array<Recognized> {
+ const found: Array<Recognized> = [];
+ const visit = (node: Record<string, unknown>) => {
+ if (node.type === 'astryx-markdown-extension') {
+ const format = (node.format as number | undefined) ?? 0;
+ found.push({
+ plugin: node.plugin as string,
+ display: node.display as string,
+ source: node.source as string,
+ marks:
+ FORMATS.filter(([bit]) => (format & bit) !== 0)
+ .map(([, name]) => name)
+ .join(', ') || 'none',
+ });
+ }
+ (node.children as Array<Record<string, unknown>> | undefined)?.forEach(
+ visit,
+ );
+ };
+ visit((JSON.parse(json) as {root: Record<string, unknown>}).root);
+ return found;
+}
+
+// Theme tokens, so every box reads in light and dark mode.
+const styles = stylex.create({
+ page: {
+ display: 'grid',
+ gap: spacingVars['--spacing-6'],
+ maxWidth: 1100,
+ color: colorVars['--color-text-primary'],
+ },
+ columns: {
+ display: 'grid',
+ gap: spacingVars['--spacing-4'],
+ gridTemplateColumns: 'repeat(2, minmax(0, 1fr))',
+ },
+ stack: {
+ display: 'grid',
+ gap: spacingVars['--spacing-2'],
+ alignContent: 'start',
+ },
+ box: {
+ margin: 0,
+ padding: spacingVars['--spacing-3'],
+ borderWidth: 1,
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: colorVars['--color-background-muted'],
+ color: colorVars['--color-text-primary'],
+ fontFamily: typographyVars['--font-family-code'],
+ fontSize: 13,
+ whiteSpace: 'pre-wrap',
+ overflowWrap: 'anywhere',
+ },
+ table: {
+ borderCollapse: 'collapse',
+ color: colorVars['--color-text-primary'],
+ },
+ cell: {
+ textAlign: 'start',
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInlineEnd: spacingVars['--spacing-4'],
+ borderBlockEndWidth: 1,
+ borderBlockEndStyle: 'solid',
+ borderBlockEndColor: colorVars['--color-border'],
+ },
+});
+
+export function MarkdownPluginsImportExport() {
+ const [markdown, setMarkdown] = useState(SAMPLE);
+ const json = useMemo(
+ () => markdownToEditorStateJSON(markdown, {extensions: EXTENSIONS}),
+ [markdown],
+ );
+ const exported = useMemo(() => editorStateJSONToMarkdown(json), [json]);
+ const nodes = useMemo(() => recognized(json), [json]);
+ const editor = useRef<RichTextEditorRef>(null);
+ const [edited, setEdited] = useState('');
+ const refusal = useMemo(() => {
+ try {
+ createRichTextExtension(shouting);
+ return 'adopted';
+ } catch (error) {
+ return error instanceof Error ? `${error.name}: ${error.message}` : '';
+ }
+ }, []);
+ return (
+ <div {...stylex.props(styles.page)}>
+ <section {...stylex.props(styles.columns)}>
+ <label {...stylex.props(styles.stack)}>
+ <Text type="label">Markdown in</Text>
+ <textarea
+ data-plugins-input=""
+ rows={12}
+ value={markdown}
+ onChange={event => setMarkdown(event.target.value)}
+ {...stylex.props(styles.box)}
+ />
+ </label>
+ <div {...stylex.props(styles.stack)}>
+ <Text type="label">
+ Markdown out{' '}
+ <strong data-plugins-identical="">
+ {exported === markdown
+ ? '— identical, byte for byte'
+ : '— differs from the input'}
+ </strong>
+ </Text>
+ <pre data-plugins-output="" {...stylex.props(styles.box)}>
+ {exported}
+ </pre>
+ </div>
+ </section>
+ <section {...stylex.props(styles.stack)}>
+ <Text type="label">Plugin nodes RichText recognized</Text>
+ <table data-plugins-nodes="" {...stylex.props(styles.table)}>
+ <thead>
+ <tr>
+ <th {...stylex.props(styles.cell)}>Plugin</th>
+ <th {...stylex.props(styles.cell)}>Display</th>
+ <th {...stylex.props(styles.cell)}>Source</th>
+ <th {...stylex.props(styles.cell)}>Marks around it</th>
+ </tr>
+ </thead>
+ <tbody>
+ {nodes.map((node, index) => (
+ <tr key={index}>
+ <td {...stylex.props(styles.cell)}>{node.plugin}</td>
+ <td {...stylex.props(styles.cell)}>{node.display}</td>
+ <td {...stylex.props(styles.cell)}>
+ <code>{node.source}</code>
+ </td>
+ <td {...stylex.props(styles.cell)}>{node.marks}</td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </section>
+ <section {...stylex.props(styles.stack)}>
+ <Text type="label">
+ Edit the text around the nodes, then export. Here a node shows its
+ source; the &quot;Markdown plugins&quot; story shows it rendered.
+ </Text>
+ <RichTextEditor
+ key={json}
+ label="Editor"
+ ref={editor}
+ defaultValue={json}
+ />
+ <div>
+ <Button
+ label="Export"
+ variant="secondary"
+ onClick={() => setEdited(editor.current?.getMarkdown() ?? '')}
+ />
+ </div>
+ <pre data-plugins-edited="" {...stylex.props(styles.box)}>
+ {edited}
+ </pre>
+ </section>
+ <section {...stylex.props(styles.stack)}>
+ <Text type="label">A plugin with a transform is refused</Text>
+ <pre data-plugins-refusal="" {...stylex.props(styles.box)}>
+ {refusal}
+ </pre>
+ </section>
+ </div>
+ );
+}
diff --git a/apps/storybook/stories/RichTextEditor.stories.tsx b/apps/storybook/stories/RichTextEditor.stories.tsx
index 90a2476a5d..cbedc35590 100644
--- a/apps/storybook/stories/RichTextEditor.stories.tsx
+++ b/apps/storybook/stories/RichTextEditor.stories.tsx
@@ -19,6 +19,7 @@ import {
MarkdownParitySandbox,
type MarkdownParitySandboxProps,
} from './RichTextEditor.markdownParity';
+import {MarkdownPluginsImportExport as MarkdownPluginsImportExportStory} from './RichTextEditor.markdownPluginsImportExport';
const meta: Meta<typeof RichTextEditor> = {
title: 'Lab/RichTextEditor',
@@ -377,6 +378,20 @@ Supports **bold**, _italic_, and lists:
* 4. Round-trip it back to Markdown with `editorStateJSONToMarkdown`
* so you can eyeball that Markdown -> JSON -> Markdown is stable.
*/
+/**
+ * Markdown with plugin syntax in, and out again (spec:AST-064). A mention
+ * plugin and a note-block plugin, adopted with createRichTextExtension, are
+ * recognized as RichText imports the Markdown; the exported Markdown sits
+ * beside the input, byte for byte. Nodes inside emphasis, strong, and
+ * strikethrough stay inside them, a note that starts on the line after a
+ * paragraph line becomes its own block, and a plugin with a transform is
+ * refused. Edit the text around the nodes and export to see them kept.
+ */
+export const MarkdownPluginsImportExport = {
+ name: 'Markdown plugins: import and export',
+ render: () => <MarkdownPluginsImportExportStory />,
+};
+
export const MarkdownSerializers = {
render: () => {
const [markdown, setMarkdown] = useState<string>(SAMPLE_MARKDOWN);
diff --git a/packages/richtext/package.json b/packages/richtext/package.json
index 08e3566064..1a32ad1520 100644
--- a/packages/richtext/package.json
+++ b/packages/richtext/package.json
@@ -45,6 +45,11 @@
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
+ "./markdown": {
+ "source": "./src/markdown.ts",
+ "types": "./dist/markdown.d.ts",
+ "default": "./dist/markdown.js"
+ },
"./richtext.css": {
"default": "./dist/richtext.css"
}
diff --git a/packages/richtext/src/RichTextEditor.doc.mjs b/packages/richtext/src/RichTextEditor.doc.mjs
index afc959b8f9..9b4d6a2bc9 100644
--- a/packages/richtext/src/RichTextEditor.doc.mjs
+++ b/packages/richtext/src/RichTextEditor.doc.mjs
@@ -207,7 +207,12 @@ export const docs = {
{
guidance: true,
description:
- 'To produce a defaultValue from Markdown without mounting an editor (e.g. on the server), use markdownToEditorStateJSON(markdown). Convert the other way with editorStateJSONToMarkdown(json). Both run headless via @lexical/headless and accept the same transformers/nodes options as the editor. The round trip keeps the Markdown as written: exporting unchanged content returns the input exactly, including indentation, escapes, character references, fence metadata, and constructs the editor shows as plain text, and an edit regenerates only the blocks it changed.',
+ 'To produce a defaultValue from Markdown without mounting an editor (e.g. on the server), use markdownToEditorStateJSON(markdown). Convert the other way with editorStateJSONToMarkdown(json). Both run headless via @lexical/headless and accept the same transformers/nodes options as the editor. The round trip keeps the Markdown as written: exporting unchanged content returns the input exactly, including indentation, escapes, character references, fence metadata, and constructs the editor shows as plain text, and an edit regenerates only the blocks it changed. On the server or in Node, import them from @astryxdesign/richtext/markdown, which loads no React or client code.',
+ },
+ {
+ guidance: true,
+ description:
+ "To recognize a Markdown plugin made with createMarkdownPlugin, adopt it with createRichTextExtension(plugin) and pass the result in the extensions option of markdownToEditorStateJSON. Core's parser finds the plugin's syntax, and each node keeps its exact source, which is what it exports; base Markdown inside plugin source stays part of the node. A plugin that declares a transform is refused with a RichTextExtensionError, and so is a configuration that adopts one plugin twice. Without the extension, plugin syntax stays text. createRichTextExtension and the serializers are also exported from @astryxdesign/richtext/markdown for server code.",
},
{
guidance: true,
diff --git a/packages/richtext/src/__tests__/MarkdownPluginsImportExport.a11y.chromium.spec.ts b/packages/richtext/src/__tests__/MarkdownPluginsImportExport.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..4f6b56c371
--- /dev/null
+++ b/packages/richtext/src/__tests__/MarkdownPluginsImportExport.a11y.chromium.spec.ts
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MarkdownPluginsImportExport.a11y.chromium.spec.ts
+ * @input The built Storybook's "Markdown plugins: import and export" story.
+ * @output Real-browser proof for spec:AST-064 FR4, FR5, and FR10: plugin
+ * syntax is recognized as core recognizes it, nodes keep the marks around
+ * them, a block after a paragraph line becomes its own block, the export is
+ * byte for byte, edits keep every node's source, and a transform plugin is
+ * refused.
+ *
+ * Run after building Storybook:
+ * pnpm storybook:build
+ * pnpm exec playwright test packages/richtext --project chromium
+ */
+
+import AxeBuilder from '@axe-core/playwright';
+import {expect, test, type Page} from '@playwright/test';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const STORYBOOK_DIR = process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR;
+const STORY = 'lab-richtexteditor--markdown-plugins-import-export';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(STORYBOOK_DIR);
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+async function openStory(
+ page: Page,
+ colorMode: 'light' | 'dark' = 'light',
+): Promise<string[]> {
+ const errors: string[] = [];
+ page.on('pageerror', error => errors.push(String(error)));
+ page.on('console', message => {
+ if (message.type() === 'error' && !message.text().includes('404')) {
+ errors.push(message.text());
+ }
+ });
+ await page.setViewportSize({width: 1440, height: 900});
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=${STORY}&viewMode=story&globals=astryxTheme:neutral;colorMode:${colorMode};direction:ltr`,
+ {waitUntil: 'load'},
+ );
+ await expect(page.locator('[data-plugins-identical]')).toBeVisible();
+ return errors;
+}
+
+test('the story imports plugin syntax, keeps marks, and exports byte for byte', async ({
+ page,
+}) => {
+ const errors = await openStory(page);
+ await expect(page.locator('[data-plugins-identical]')).toHaveText(
+ '— identical, byte for byte',
+ );
+ const input = await page.locator('[data-plugins-input]').inputValue();
+ await expect(page.locator('[data-plugins-output]')).toHaveText(input);
+ const rows = page.locator('[data-plugins-nodes] tbody tr');
+ await expect(rows).toHaveText([
+ /story-mentions\s*inline\s*@\{ada\}\s*none/,
+ /story-mentions\s*inline\s*@\{grace\}\s*italic/,
+ /story-mentions\s*inline\s*@\{linus\}\s*bold/,
+ /story-mentions\s*inline\s*@\{old\}\s*strikethrough/,
+ /story-notes\s*block\s*:::note[\s\S]*:::\s*none/,
+ ]);
+ await expect(page.locator('[data-plugins-refusal]')).toContainText(
+ 'RichTextExtensionError: RichText cannot adopt Markdown plugin "story-shouting"',
+ );
+ expect(errors).toEqual([]);
+});
+
+test('editing the text beside the nodes keeps every node and its marks', async ({
+ page,
+}) => {
+ const errors = await openStory(page);
+ const editor = page.locator('[contenteditable="true"]');
+ await editor.getByText('Ping', {exact: false}).first().click();
+ await page.keyboard.press('Home');
+ await page.keyboard.type('Please ');
+ await page.getByRole('button', {name: 'Export'}).click();
+ const edited =
+ (await page.locator('[data-plugins-edited]').textContent()) ?? '';
+ expect(edited).toContain('Please Ping @{ada} about the review.');
+ expect(edited).toContain('*see @{grace} here*');
+ expect(edited).toContain('**ask @{linus}**');
+ expect(edited).toContain('~~not @{old}~~');
+ expect(edited).toContain(
+ ':::note\nand this note starts on the next line.\n:::',
+ );
+ expect(errors).toEqual([]);
+});
+
+for (const colorMode of ['light', 'dark'] as const) {
+ test(`the story meets text contrast in ${colorMode} mode`, async ({page}) => {
+ const errors = await openStory(page, colorMode);
+ await page.getByRole('button', {name: 'Export'}).click();
+ const results = await new AxeBuilder({page})
+ .include('#storybook-root')
+ .withRules(['color-contrast'])
+ .analyze();
+ expect(
+ results.violations.flatMap(violation =>
+ violation.nodes.map(node => node.target.join(' ')),
+ ),
+ ).toEqual([]);
+ expect(errors).toEqual([]);
+ });
+}
diff --git a/packages/richtext/src/editorNodes.ts b/packages/richtext/src/editorNodes.ts
index 5b05550e4e..218309f0f4 100644
--- a/packages/richtext/src/editorNodes.ts
+++ b/packages/richtext/src/editorNodes.ts
@@ -18,6 +18,7 @@ import {CodeNode, CodeHighlightNode} from '@lexical/code';
import {TableNode, TableRowNode, TableCellNode} from '@lexical/table';
import {HorizontalRuleNode} from '@lexical/extension';
import type {Klass, LexicalNode} from 'lexical';
+import {RichTextExtensionNode} from './markdownExtensionNode';
/**
* The default OSS node set registered with the editor: headings, quotes,
@@ -37,4 +38,7 @@ export const DEFAULT_NODES: ReadonlyArray<Klass<LexicalNode>> = [
TableRowNode,
TableCellNode,
HorizontalRuleNode,
+ // Markdown plugin nodes (spec:AST-064): registered everywhere so stored
+ // state that holds them always loads.
+ RichTextExtensionNode,
];
diff --git a/packages/richtext/src/index.ts b/packages/richtext/src/index.ts
index c1be519089..97cc156868 100644
--- a/packages/richtext/src/index.ts
+++ b/packages/richtext/src/index.ts
@@ -34,6 +34,11 @@ export {
editorStateJSONToMarkdown,
} from './markdownSerializers';
export type {MarkdownSerializerOptions} from './markdownSerializers';
+export {
+ createRichTextExtension,
+ RichTextExtensionError,
+} from './markdownExtensions';
+export type {RichTextMarkdownExtension} from './markdownExtensions';
export {
RichTextEditorToolbar,
diff --git a/packages/richtext/src/markdown.ts b/packages/richtext/src/markdown.ts
new file mode 100644
index 0000000000..850c9eb8fb
--- /dev/null
+++ b/packages/richtext/src/markdown.ts
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdown.ts
+ * @output Server-safe entry `@astryxdesign/richtext/markdown`: the Markdown
+ * serializers, createRichTextExtension, RichTextExtensionError, and their
+ * types.
+ * @position Imports no React, DOM, or client-only module, so server and Node
+ * code converts Markdown and adopts plugins here (spec:AST-064 FR3, FR12).
+ * The package's main entry is a client module and re-exports all of this
+ * for client code. An extension holds its plugin's functions, so it is not
+ * serializable: create the extensions a page passes to the surfaces in a
+ * client module, and create your own for headless use.
+ */
+
+export {
+ markdownToEditorStateJSON,
+ editorStateJSONToMarkdown,
+} from './markdownSerializers';
+export type {MarkdownSerializerOptions} from './markdownSerializers';
+export {
+ createRichTextExtension,
+ RichTextExtensionError,
+} from './markdownExtensions';
+export type {RichTextMarkdownExtension} from './markdownExtensions';
diff --git a/packages/richtext/src/markdownExtensionNode.ts b/packages/richtext/src/markdownExtensionNode.ts
new file mode 100644
index 0000000000..6d24c6423b
--- /dev/null
+++ b/packages/richtext/src/markdownExtensionNode.ts
@@ -0,0 +1,171 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownExtensionNode.ts
+ * @input Uses lexical (DecoratorNode, node serialization, text formats).
+ * @output Exports RichTextExtensionNode, the editor node for one Markdown
+ * plugin node, with $createRichTextExtensionNode and
+ * $isRichTextExtensionNode.
+ * @position Registered with every RichText surface and serializer
+ * (editorNodes.ts), so stored state holding plugin nodes always loads. A
+ * node is atomic — the editor cannot type into it — and keeps the exact
+ * source it was read from, which is what it exports (spec:AST-064 FR7,
+ * FR10). Stored state keeps that source, the plugin's name and protocol
+ * version, the data the plugin derived for rendering (FR11), and the text
+ * formats the node sits inside, so a node inside emphasis, strong, or
+ * strikethrough stays inside it. Imports no React.
+ */
+
+import {
+ DecoratorNode,
+ TEXT_TYPE_TO_FORMAT,
+ type EditorConfig,
+ type LexicalNode,
+ type NodeKey,
+ type SerializedLexicalNode,
+ type Spread,
+ type TextFormatType,
+} from 'lexical';
+import type {MarkdownPluginData} from '@astryxdesign/core/Markdown/plugins';
+
+/** What one plugin node is: the parsed node's identity, data, and source. */
+export interface RichTextExtensionNodeFacts {
+ readonly plugin: string;
+ readonly apiVersion: number;
+ readonly name: string;
+ readonly display: 'inline' | 'block';
+ readonly data: MarkdownPluginData;
+ readonly source: string;
+}
+
+export type SerializedRichTextExtensionNode = Spread<
+ RichTextExtensionNodeFacts & {
+ /** The text formats the node sits inside, as a text node's format bits. */
+ readonly format: number;
+ },
+ SerializedLexicalNode
+>;
+
+/** Reads stored facts defensively: a missing field becomes an empty value. */
+export function factsFrom(
+ value: Record<string, unknown>,
+): RichTextExtensionNodeFacts {
+ const {plugin, apiVersion, name, display, data, source} = value;
+ return {
+ plugin: typeof plugin === 'string' ? plugin : '',
+ apiVersion: typeof apiVersion === 'number' ? apiVersion : 0,
+ name: typeof name === 'string' ? name : '',
+ display: display === 'block' ? 'block' : 'inline',
+ data: (data ?? null) as MarkdownPluginData,
+ source: typeof source === 'string' ? source : '',
+ };
+}
+
+export class RichTextExtensionNode extends DecoratorNode<unknown> {
+ __facts: RichTextExtensionNodeFacts;
+ /**
+ * The text formats the node sits inside, as a text node's format bits. Only
+ * inline nodes carry any.
+ */
+ __format: number;
+
+ static getType(): string {
+ return 'astryx-markdown-extension';
+ }
+
+ static clone(node: RichTextExtensionNode): RichTextExtensionNode {
+ return new RichTextExtensionNode(node.__facts, node.__format, node.__key);
+ }
+
+ static importJSON(
+ serialized: SerializedLexicalNode & Record<string, unknown>,
+ ): RichTextExtensionNode {
+ // Stored state is read defensively, so a damaged node still loads.
+ const {format} = serialized;
+ return $createRichTextExtensionNode(
+ factsFrom(serialized),
+ typeof format === 'number' ? format : 0,
+ ).updateFromJSON(serialized);
+ }
+
+ constructor(facts: RichTextExtensionNodeFacts, format = 0, key?: NodeKey) {
+ super(key);
+ this.__facts = facts;
+ this.__format = facts.display === 'inline' ? format : 0;
+ }
+
+ exportJSON(): SerializedRichTextExtensionNode {
+ const latest = this.getLatest();
+ return {
+ ...super.exportJSON(),
+ ...latest.__facts,
+ format: latest.__format,
+ };
+ }
+
+ /** The node's identity, data, and source. */
+ getFacts(): RichTextExtensionNodeFacts {
+ return this.getLatest().__facts;
+ }
+
+ /** The exact Markdown the node was read from. */
+ getSource(): string {
+ return this.getLatest().__facts.source;
+ }
+
+ /** The text formats the node sits inside, as a text node's format bits. */
+ getFormat(): number {
+ return this.getLatest().__format;
+ }
+
+ hasFormat(type: TextFormatType): boolean {
+ return (this.getFormat() & TEXT_TYPE_TO_FORMAT[type]) !== 0;
+ }
+
+ /** Puts the node inside, or takes it out of, one text format. */
+ setFormatFlag(type: TextFormatType, isOn: boolean): this {
+ const writable = this.getWritable();
+ const flag = TEXT_TYPE_TO_FORMAT[type];
+ writable.__format = isOn
+ ? writable.__format | flag
+ : writable.__format & ~flag;
+ return writable;
+ }
+
+ createDOM(_config: EditorConfig): HTMLElement {
+ return document.createElement(
+ this.__facts.display === 'block' ? 'div' : 'span',
+ );
+ }
+
+ updateDOM(): false {
+ return false;
+ }
+
+ isInline(): boolean {
+ return this.__facts.display === 'inline';
+ }
+
+ /** The node's text is its source, so plain-text copies and search see it. */
+ getTextContent(): string {
+ return this.getLatest().__facts.source;
+ }
+
+ /** Until a surface draws plugin nodes, a node shows its source. */
+ decorate(): unknown {
+ return this.__facts.source;
+ }
+}
+
+export function $createRichTextExtensionNode(
+ facts: RichTextExtensionNodeFacts,
+ format = 0,
+): RichTextExtensionNode {
+ return new RichTextExtensionNode(facts, format);
+}
+
+export function $isRichTextExtensionNode(
+ node: LexicalNode | null | undefined,
+): node is RichTextExtensionNode {
+ return node instanceof RichTextExtensionNode;
+}
diff --git a/packages/richtext/src/markdownExtensions.test.ts b/packages/richtext/src/markdownExtensions.test.ts
new file mode 100644
index 0000000000..36edc5234f
--- /dev/null
+++ b/packages/richtext/src/markdownExtensions.test.ts
@@ -0,0 +1,670 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {readFileSync} from 'node:fs';
+import {dirname, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+import {createHeadlessEditor} from '@lexical/headless';
+import {$getRoot, $isTextNode} from 'lexical';
+import {
+ createMarkdownPlugin,
+ type MarkdownExtensionNode,
+ type MarkdownPluginEntry,
+} from '@astryxdesign/core/Markdown/plugins';
+import {parseMarkdownAst} from '@astryxdesign/core/Markdown/parser';
+import {
+ createRichTextExtension,
+ editorStateJSONToMarkdown,
+ markdownToEditorStateJSON,
+ RichTextExtensionError,
+} from './markdown';
+import {DEFAULT_NODES} from './editorNodes';
+import {RichTextExtensionNode} from './markdownExtensionNode';
+import {
+ $exportMarkdownKeepingSource,
+ importMarkdownKeepingSource,
+} from './markdownSource';
+import {DEFAULT_TRANSFORMERS} from './markdownTable';
+
+type MentionNode = MarkdownExtensionNode<
+ 'mentions',
+ 'mention',
+ {readonly label: string},
+ 'inline'
+>;
+type NoteNode = MarkdownExtensionNode<
+ 'notes',
+ 'note',
+ {readonly body: string},
+ 'block'
+>;
+type AsideNode = MarkdownExtensionNode<
+ 'asides',
+ 'aside',
+ {readonly text: string},
+ 'inline'
+>;
+
+const mentions = createMarkdownPlugin<'mentions', MentionNode>({
+ name: 'mentions',
+ apiVersion: 1,
+ parseKey: 'v1',
+ syntax: {
+ inline: [
+ {
+ startsWith: ['@{'],
+ maxSpan: 80,
+ tokenize({source, offset, end}) {
+ const close = source.indexOf('}', offset + 2);
+ if (close < 0 || close >= end) {
+ return {status: 'no-match'};
+ }
+ return {
+ status: 'match',
+ end: close + 1,
+ node: {
+ type: 'extension',
+ plugin: 'mentions',
+ name: 'mention',
+ display: 'inline',
+ data: {label: source.slice(offset + 2, close)},
+ },
+ };
+ },
+ },
+ ],
+ },
+ renderers: {
+ mention: {
+ render: () => null,
+ toText: node => `@${node.data.label}`,
+ },
+ },
+});
+
+const notes = createMarkdownPlugin<'notes', NoteNode>({
+ name: 'notes',
+ apiVersion: 1,
+ parseKey: 'v1',
+ syntax: {
+ block: [
+ {
+ startsWith: [':::note'],
+ maxSpan: 500,
+ tokenize({source, offset, end}) {
+ const close = source.indexOf('\n:::', offset);
+ if (close < 0 || close + 4 > end) {
+ return {status: 'no-match'};
+ }
+ return {
+ status: 'match',
+ end: close + 4,
+ node: {
+ type: 'extension',
+ plugin: 'notes',
+ name: 'note',
+ display: 'block',
+ data: {body: source.slice(offset + 8, close)},
+ },
+ };
+ },
+ },
+ ],
+ },
+ renderers: {
+ note: {render: () => null, toText: node => node.data.body},
+ },
+});
+
+// Plugin source that holds base Markdown: emphasis, a link, a list marker.
+const asides = createMarkdownPlugin<'asides', AsideNode>({
+ name: 'asides',
+ apiVersion: 1,
+ parseKey: 'v1',
+ syntax: {
+ inline: [
+ {
+ startsWith: ['{{'],
+ maxSpan: 200,
+ tokenize({source, offset, end}) {
+ const close = source.indexOf('}}', offset + 2);
+ if (close < 0 || close + 2 > end) {
+ return {status: 'no-match'};
+ }
+ return {
+ status: 'match',
+ end: close + 2,
+ node: {
+ type: 'extension',
+ plugin: 'asides',
+ name: 'aside',
+ display: 'inline',
+ data: {text: source.slice(offset + 2, close)},
+ },
+ };
+ },
+ },
+ ],
+ },
+ renderers: {
+ aside: {render: () => null, toText: node => node.data.text},
+ },
+});
+
+const PLUGINS: ReadonlyArray<MarkdownPluginEntry> = [mentions, notes, asides];
+const EXTENSIONS = PLUGINS.map(createRichTextExtension);
+
+interface Recognized {
+ readonly plugin: string;
+ readonly name: string;
+ readonly display: string;
+ readonly data: unknown;
+ readonly source: string | undefined;
+}
+
+/** The nodes core recognizes, inline anywhere and block at the top level. */
+function coreNodes(markdown: string): Array<Recognized> {
+ const found: Array<Recognized> = [];
+ const visit = (node: unknown, isTopLevel: boolean) => {
+ const candidate = node as {type?: string; children?: Array<unknown>};
+ if (candidate.type === 'extension') {
+ const extension = node as MarkdownExtensionNode;
+ if (extension.display === 'inline' || isTopLevel) {
+ found.push({
+ plugin: extension.plugin,
+ name: extension.name,
+ display: extension.display,
+ data: extension.data,
+ source: extension.source,
+ });
+ }
+ return;
+ }
+ candidate.children?.forEach(child => visit(child, false));
+ };
+ parseMarkdownAst(markdown, {plugins: [...PLUGINS]}).children.forEach(block =>
+ visit(block, true),
+ );
+ return found;
+}
+
+/** The extension nodes in stored RichText state, in document order. */
+function richTextNodes(json: string): Array<Recognized> {
+ const found: Array<Recognized> = [];
+ const visit = (node: Record<string, unknown>) => {
+ if (node.type === 'astryx-markdown-extension') {
+ found.push({
+ plugin: node.plugin as string,
+ name: node.name as string,
+ display: node.display as string,
+ data: node.data,
+ source: node.source as string,
+ });
+ }
+ (node.children as Array<Record<string, unknown>> | undefined)?.forEach(
+ visit,
+ );
+ };
+ visit((JSON.parse(json) as {root: Record<string, unknown>}).root);
+ return found;
+}
+
+/** Every node type in stored RichText state. */
+function nodeTypes(json: string): Set<string> {
+ const types = new Set<string>();
+ const visit = (node: Record<string, unknown>) => {
+ types.add(node.type as string);
+ if (typeof node.format === 'number' && node.format !== 0) {
+ types.add(`format:${node.format}`);
+ }
+ (node.children as Array<Record<string, unknown>> | undefined)?.forEach(
+ visit,
+ );
+ };
+ visit((JSON.parse(json) as {root: Record<string, unknown>}).root);
+ return types;
+}
+
+const CORPUS: ReadonlyArray<string> = [
+ 'Hi @{ada} and @{grace}.\n',
+ '`@{code}` then @{real} and `@{code}` again @{real}.\n',
+ '\\@{escaped} and @{real}\n',
+ 'Adjacent @{a}@{b} nodes.\n',
+ '- item @{list}\n- other\n',
+ '> quote @{quoted}\n',
+ '| a | b |\n| --- | --- |\n| @{cell} | x |\n',
+ '[link @{inside}](https://example.com) after\n',
+ '*emphasis @{inside}* and **strong**\n',
+ ':::note\nBody with **bold**\n:::\n\nAfter @{x}\n',
+ '{{see **this**, [that](https://example.com), and - this}} stays one node.\n',
+ '```\n@{fenced}\n```\n',
+ 'Two paragraphs @{one}\n\nand @{two}\n',
+ // A block node that leads its group keeps the group's authored bytes,
+ // three blank lines included, through stored state.
+ ':::note\nBody\n:::\n\n\n\nAfter @{x}\n',
+ // A block that starts on the line after a paragraph line.
+ 'Intro line @{a}\n:::note\nBody\n:::\nAfter line @{b}\n',
+ // The same source as a decoy before the real node: in code, escaped, and in
+ // a link destination. Placing the node at the first occurrence fails these.
+ '`@{ada}` then @{ada}.\n',
+ '\\@{ada} then @{ada}.\n',
+ '[x](https://example.com/@{ada}) then @{ada}.\n',
+ 'Many @{a} @{a} `@{a}` @{a}\n',
+ // Nodes inside marks.
+ '*emphasis @{inside} here* and **strong @{s}**, ~~struck @{d}~~, ***both @{b}***.\n',
+];
+
+describe('createRichTextExtension (spec:AST-064 FR1, FR4)', () => {
+ it('adopts a syntax plugin as it is', () => {
+ expect(createRichTextExtension(mentions).name).toBe('mentions');
+ });
+
+ it('refuses a plugin that declares a transform, naming the plugin and the capability', () => {
+ const transforming = createMarkdownPlugin({
+ name: 'transforming',
+ apiVersion: 1,
+ transform: root => root,
+ });
+ let refusal: unknown;
+ try {
+ createRichTextExtension(transforming);
+ } catch (error) {
+ refusal = error;
+ }
+ expect(refusal).toBeInstanceOf(RichTextExtensionError);
+ expect(refusal).toMatchObject({
+ name: 'RichTextExtensionError',
+ plugin: 'transforming',
+ capability: 'transform',
+ claimant: null,
+ });
+ expect(String(refusal)).toContain('"transforming"');
+ });
+
+ it('refuses an entry that did not come from createMarkdownPlugin', () => {
+ expect(() =>
+ createRichTextExtension({
+ name: 'forged',
+ apiVersion: 1,
+ } as unknown as MarkdownPluginEntry),
+ ).toThrow('createMarkdownPlugin()');
+ });
+});
+
+describe('configuration conflicts (spec:AST-064 FR6)', () => {
+ it('refuses two extensions for one plugin, and a transformer that owns plugin nodes', () => {
+ expect(() =>
+ markdownToEditorStateJSON('x', {
+ extensions: [
+ createRichTextExtension(mentions),
+ createRichTextExtension(mentions),
+ ],
+ }),
+ ).toThrow(RichTextExtensionError);
+ const owning = {
+ dependencies: [RichTextExtensionNode],
+ export: () => null,
+ regExp: /(?!)/,
+ replace: () => false,
+ type: 'element',
+ } as unknown as (typeof DEFAULT_TRANSFORMERS)[number];
+ expect(() =>
+ markdownToEditorStateJSON('x', {
+ extensions: EXTENSIONS,
+ transformers: [...DEFAULT_TRANSFORMERS, owning],
+ }),
+ ).toThrow(/claim its nodes/);
+ });
+
+ it('opens a document whose plugin source holds base syntax with the default transformers', () => {
+ const json = markdownToEditorStateJSON(CORPUS[10] ?? '', {
+ extensions: EXTENSIONS,
+ });
+ const types = nodeTypes(json);
+ // The aside is one node; its emphasis, link, and list marker are not read.
+ expect(types.has('link')).toBe(false);
+ expect(types.has('list')).toBe(false);
+ expect([...types].some(type => type.startsWith('format:'))).toBe(false);
+ expect(richTextNodes(json)).toEqual([
+ {
+ plugin: 'asides',
+ name: 'aside',
+ display: 'inline',
+ data: {text: 'see **this**, [that](https://example.com), and - this'},
+ source: '{{see **this**, [that](https://example.com), and - this}}',
+ },
+ ]);
+ });
+});
+
+describe('recognition (spec:AST-064 FR5)', () => {
+ it.each(CORPUS.map(markdown => [JSON.stringify(markdown), markdown]))(
+ 'recognizes what core recognizes in %s',
+ (_, markdown) => {
+ const json = markdownToEditorStateJSON(markdown, {
+ extensions: EXTENSIONS,
+ });
+ expect(richTextNodes(json)).toEqual(coreNodes(markdown));
+ },
+ );
+
+ it('keeps block syntax nested in a list item as text', () => {
+ const markdown = '- item\n\n :::note\n nested\n :::\n';
+ const json = markdownToEditorStateJSON(markdown, {extensions: EXTENSIONS});
+ expect(richTextNodes(json)).toEqual([]);
+ expect(editorStateJSONToMarkdown(json)).toBe(markdown);
+ });
+
+ it('keeps plugin syntax as text without the extension', () => {
+ const markdown = CORPUS[0] ?? '';
+ const json = markdownToEditorStateJSON(markdown);
+ expect(richTextNodes(json)).toEqual([]);
+ expect(editorStateJSONToMarkdown(json)).toBe(markdown);
+ });
+});
+
+describe('source authority (spec:AST-064 FR10, FR11)', () => {
+ it.each(CORPUS.map(markdown => [JSON.stringify(markdown), markdown]))(
+ 'round-trips %s byte for byte',
+ (_, markdown) => {
+ const json = markdownToEditorStateJSON(markdown, {
+ extensions: EXTENSIONS,
+ });
+ expect(editorStateJSONToMarkdown(json)).toBe(markdown);
+ // Export needs no plugin: the nodes carry their source.
+ expect(
+ editorStateJSONToMarkdown(json, {transformers: DEFAULT_TRANSFORMERS}),
+ ).toBe(markdown);
+ },
+ );
+
+ it("stores each node's source, plugin name, protocol version, and data", () => {
+ const json = markdownToEditorStateJSON('Hi @{ada}.\n', {
+ extensions: EXTENSIONS,
+ });
+ const paragraph = (
+ JSON.parse(json) as {
+ root: {children: Array<{children: Array<Record<string, unknown>>}>};
+ }
+ ).root.children[0];
+ const node = paragraph?.children.find(
+ child => child.type === 'astryx-markdown-extension',
+ );
+ expect(node).toMatchObject({
+ plugin: 'mentions',
+ apiVersion: 1,
+ name: 'mention',
+ display: 'inline',
+ data: {label: 'ada'},
+ source: '@{ada}',
+ });
+ expect(node).not.toHaveProperty('parseKey');
+ });
+
+ it('rewrites nothing in a node when the text beside it changes, and moves its bytes with it', () => {
+ const editor = createHeadlessEditor({
+ nodes: [...DEFAULT_NODES],
+ onError(error) {
+ throw error;
+ },
+ });
+ importMarkdownKeepingSource(
+ editor,
+ 'Hi @{ada} and *more*.\n\n{{keep **this** exactly}}\n',
+ [...DEFAULT_TRANSFORMERS],
+ PLUGINS,
+ );
+ editor.update(
+ () => {
+ const first = $getRoot().getAllTextNodes()[0];
+ if ($isTextNode(first)) {
+ first.setTextContent('Hello ');
+ }
+ },
+ {discrete: true},
+ );
+ const exported = editor
+ .getEditorState()
+ .read(() => $exportMarkdownKeepingSource([...DEFAULT_TRANSFORMERS]));
+ expect(exported).toContain('Hello @{ada}');
+ expect(exported).toContain('{{keep **this** exactly}}');
+ });
+});
+
+/** Edits the first text node whose text includes `find`, then exports. */
+function editAndExport(
+ markdown: string,
+ find: string,
+ replace: string,
+): string {
+ const editor = createHeadlessEditor({
+ nodes: [...DEFAULT_NODES],
+ onError(error) {
+ throw error;
+ },
+ });
+ importMarkdownKeepingSource(
+ editor,
+ markdown,
+ [...DEFAULT_TRANSFORMERS],
+ PLUGINS,
+ );
+ editor.update(
+ () => {
+ const target = $getRoot()
+ .getAllTextNodes()
+ .find(node => node.getTextContent().includes(find));
+ if (!$isTextNode(target)) {
+ throw new Error(`No text holds ${find}`);
+ }
+ target.setTextContent(target.getTextContent().replace(find, replace));
+ },
+ {discrete: true},
+ );
+ return editor
+ .getEditorState()
+ .read(() => $exportMarkdownKeepingSource([...DEFAULT_TRANSFORMERS]));
+}
+
+/** Each inline plugin node's source and the formats around it. */
+function formatsOf(json: string): Array<[string, number]> {
+ const found: Array<[string, number]> = [];
+ const visit = (node: Record<string, unknown>) => {
+ if (node.type === 'astryx-markdown-extension') {
+ found.push([node.source as string, node.format as number]);
+ }
+ (node.children as Array<Record<string, unknown>> | undefined)?.forEach(
+ visit,
+ );
+ };
+ visit((JSON.parse(json) as {root: Record<string, unknown>}).root);
+ return found;
+}
+
+/** A paragraph's inline content, with code in backticks and nodes marked. */
+function coreLine(markdown: string): string {
+ const flat = (node: Record<string, unknown>): string => {
+ switch (node.type) {
+ case 'text':
+ return node.value as string;
+ case 'inlineCode':
+ return `\`${node.value as string}\``;
+ case 'extension':
+ return `[[${node.source as string}]]`;
+ default:
+ return ((node.children as Array<Record<string, unknown>>) ?? [])
+ .map(flat)
+ .join('');
+ }
+ };
+ const [paragraph] = parseMarkdownAst(markdown, {plugins: [...PLUGINS]})
+ .children as unknown as Array<Record<string, unknown>>;
+ return paragraph == null ? '' : flat(paragraph);
+}
+
+function richTextLine(json: string): string {
+ const flat = (node: Record<string, unknown>): string => {
+ if (node.type === 'astryx-markdown-extension') {
+ return `[[${node.source as string}]]`;
+ }
+ if (node.type === 'text') {
+ const text = node.text as string;
+ // Format bit 16 is inline code.
+ return ((node.format as number) & 16) !== 0 ? `\`${text}\`` : text;
+ }
+ return ((node.children as Array<Record<string, unknown>>) ?? [])
+ .map(flat)
+ .join('');
+ };
+ const [paragraph] = (
+ JSON.parse(json) as {root: {children: Array<Record<string, unknown>>}}
+ ).root.children;
+ return paragraph == null ? '' : flat(paragraph);
+}
+
+describe('placement among same-source decoys (spec:AST-064 FR5)', () => {
+ it.each([
+ '`@{ada}` then @{ada}.\n',
+ '\\@{ada} then @{ada}.\n',
+ '[x](https://example.com/@{ada}) then @{ada}.\n',
+ 'Many @{a} @{a} `@{a}` @{a}\n',
+ ])('puts the node where core reads it in %j', markdown => {
+ const json = markdownToEditorStateJSON(markdown, {extensions: EXTENSIONS});
+ expect(richTextLine(json)).toBe(coreLine(markdown));
+ });
+});
+
+describe('nodes inside marks (spec:AST-064 FR5, FR10)', () => {
+ const MARKED =
+ '*emphasis @{inside} here* and **strong @{s}**, ~~struck @{d}~~, ***both @{b}***, [link @{l}](https://example.com).\n';
+
+ it('keep the formats around them', () => {
+ const json = markdownToEditorStateJSON(MARKED, {extensions: EXTENSIONS});
+ // italic 2, bold 1, strikethrough 4, bold + italic 3. Core reads link
+ // text as text, so the mention in the link stays text on both.
+ expect(formatsOf(json)).toEqual([
+ ['@{inside}', 2],
+ ['@{s}', 1],
+ ['@{d}', 4],
+ ['@{b}', 3],
+ ]);
+ expect(richTextNodes(json)).toEqual(coreNodes(MARKED));
+ });
+
+ it('stay inside their marks when text beside them is edited, and read back the same', () => {
+ const exported = editAndExport(MARKED, ' and ', ' or ');
+ expect(exported).toBe(MARKED.replace(' and ', ' or '));
+ const again = markdownToEditorStateJSON(exported, {extensions: EXTENSIONS});
+ expect(formatsOf(again)).toEqual(
+ formatsOf(markdownToEditorStateJSON(MARKED, {extensions: EXTENSIONS})),
+ );
+ // An edit inside the emphasis keeps the node inside it too.
+ expect(editAndExport(MARKED, ' here', ' there')).toBe(
+ MARKED.replace(' here', ' there'),
+ );
+ });
+});
+
+describe('a block after a paragraph line (spec:AST-064 FR5)', () => {
+ it('splits the paragraph around the block node, as core reads it', () => {
+ const markdown = 'Intro line\n:::note\nBody\n:::\nAfter line\n';
+ const json = markdownToEditorStateJSON(markdown, {extensions: EXTENSIONS});
+ const root = (
+ JSON.parse(json) as {root: {children: Array<Record<string, unknown>>}}
+ ).root;
+ expect(root.children.map(node => node.type)).toEqual([
+ 'paragraph',
+ 'astryx-markdown-extension',
+ 'paragraph',
+ ]);
+ expect(editorStateJSONToMarkdown(json)).toBe(markdown);
+ // An edit regenerates the chunk the block shares with its paragraphs, in
+ // canonical form (spec:AST-062 DEC-2): blank lines between the blocks,
+ // the same structure, and the node's exact source.
+ const edited = editAndExport(markdown, 'Intro', 'Opening');
+ expect(edited).toBe('Opening line\n\n:::note\nBody\n:::\n\nAfter line\n');
+ const again = (
+ JSON.parse(
+ markdownToEditorStateJSON(edited, {extensions: EXTENSIONS}),
+ ) as {
+ root: {children: Array<Record<string, unknown>>};
+ }
+ ).root;
+ expect(again.children.map(node => node.type)).toEqual([
+ 'paragraph',
+ 'astryx-markdown-extension',
+ 'paragraph',
+ ]);
+ });
+});
+
+describe('placement cost', () => {
+ it('places 200 list items and 500 identical nodes in a paragraph without a parse per node', () => {
+ const list = Array.from({length: 200}, (_, index) => `- item @{n${index}}`)
+ .join('\n')
+ .concat('\n');
+ const paragraph = `${Array.from({length: 500}, () => '@{same}').join(' ')}\n`;
+ const started = performance.now();
+ const listJson = markdownToEditorStateJSON(list, {extensions: EXTENSIONS});
+ const paragraphJson = markdownToEditorStateJSON(paragraph, {
+ extensions: EXTENSIONS,
+ });
+ const elapsed = performance.now() - started;
+ expect(richTextNodes(listJson)).toHaveLength(200);
+ expect(richTextNodes(paragraphJson)).toHaveLength(500);
+ expect(editorStateJSONToMarkdown(paragraphJson)).toBe(paragraph);
+ // Every occurrence is a node, so no occurrence needs core to confirm it.
+ expect(elapsed).toBeLessThan(5000);
+ });
+});
+
+describe('@astryxdesign/richtext/markdown (spec:AST-064 FR3, FR12)', () => {
+ it('imports no React, DOM, or client module', () => {
+ const here = dirname(fileURLToPath(import.meta.url));
+ const seen = new Set<string>();
+ const bare = new Set<string>();
+ const visit = (file: string) => {
+ if (seen.has(file)) {
+ return;
+ }
+ seen.add(file);
+ const source = readFileSync(file, 'utf8');
+ expect(source, file).not.toMatch(/^\s*['"]use client['"]/m);
+ for (const [, specifier] of source.matchAll(
+ /^(?:import|export)[^'"]*from\s+['"]([^'"]+)['"]/gm,
+ )) {
+ if (specifier == null) {
+ continue;
+ }
+ if (specifier.startsWith('.')) {
+ const base = resolve(dirname(file), specifier);
+ const candidates = [
+ `${base}.ts`,
+ `${base}.tsx`,
+ join(base, 'index.ts'),
+ ];
+ const next = candidates.find(path => {
+ try {
+ readFileSync(path);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ if (next != null) {
+ visit(next);
+ }
+ } else {
+ bare.add(specifier);
+ }
+ }
+ };
+ visit(join(here, 'markdown.ts'));
+ for (const specifier of bare) {
+ expect(specifier).not.toMatch(
+ /^(react|react-dom|@lexical\/react)(\/|$)|plugin-renderer/,
+ );
+ }
+ expect(bare).toContain('@astryxdesign/core/Markdown/plugins');
+ });
+});
diff --git a/packages/richtext/src/markdownExtensions.ts b/packages/richtext/src/markdownExtensions.ts
new file mode 100644
index 0000000000..646440ff2f
--- /dev/null
+++ b/packages/richtext/src/markdownExtensions.ts
@@ -0,0 +1,496 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file markdownExtensions.ts
+ * @input Uses core's server-safe plugin protocol (getMarkdownPluginCapabilities)
+ * and parser (parseMarkdownAst), lexical, and RichTextExtensionNode.
+ * @output Exports createRichTextExtension, RichTextExtensionError, and the
+ * RichTextMarkdownExtension type; and, for RichText's own Markdown import and
+ * export, the configuration check, the source shielding and restoring that
+ * puts core-recognized plugin nodes into the editor, and the transformers
+ * that export them.
+ * @position Implements spec:AST-064 FR1–FR6 and FR10 for RichText's Markdown
+ * import and export. Server-safe: imports no React, DOM, or client module.
+ *
+ * A plugin is the entry core's createMarkdownPlugin returns; RichText adopts it
+ * as it is (FR1), refusing a plugin that declares a transform (FR4, DEC-3).
+ * Before Lexical imports a chunk of Markdown, core's parser finds the adopted
+ * plugins' nodes in it, and each node's exact source becomes a private-use
+ * stand-in that Lexical's transformers read as plain text (FR5, DEC-4). Core
+ * reports where a top-level block node sits but not an inline one, so each
+ * node is placed at the occurrence of its source that core itself recognizes:
+ * replacing that occurrence, and only that one, removes exactly that node from
+ * core's parse. After the import, each stand-in becomes an atomic
+ * RichTextExtensionNode holding the node's source and data.
+ */
+
+import type {Transformer} from '@lexical/markdown';
+import {
+ $createParagraphNode,
+ $createTextNode,
+ $isLineBreakNode,
+ $isParagraphNode,
+ TextNode,
+ type ElementNode,
+ type LexicalNode,
+ type ParagraphNode,
+} from 'lexical';
+import {
+ getMarkdownPluginCapabilities,
+ type MarkdownExtensionNode,
+ type MarkdownPluginEntry,
+} from '@astryxdesign/core/Markdown/plugins';
+import {parseMarkdownAst} from '@astryxdesign/core/Markdown/parser';
+import {
+ $createRichTextExtensionNode,
+ $isRichTextExtensionNode,
+ RichTextExtensionNode,
+} from './markdownExtensionNode';
+
+const extensionPlugin = Symbol('RichTextMarkdownExtension.plugin');
+
+/**
+ * One Markdown plugin adopted by RichText. Opaque: create it with
+ * `createRichTextExtension`, and pass it to the surfaces and serializers that
+ * should recognize the plugin's syntax.
+ */
+export interface RichTextMarkdownExtension {
+ /** The adopted plugin's name. */
+ readonly name: string;
+ readonly [extensionPlugin]: MarkdownPluginEntry;
+}
+
+/** Why RichText refused a plugin or a configuration (spec:AST-064 FR4, FR6). */
+export class RichTextExtensionError extends Error {
+ /** The plugin RichText refused, or that a configuration claims twice. */
+ readonly plugin: string;
+ /** What RichText cannot honor: `transform`, or what was claimed twice. */
+ readonly capability: string;
+ /** The transformer or second extension that claims the same thing. */
+ readonly claimant: string | null;
+
+ constructor(plugin: string, capability: string, claimant: string | null) {
+ super(
+ claimant == null
+ ? `RichText cannot adopt Markdown plugin "${plugin}": RichText does not run its ${capability}.`
+ : `RichText cannot use Markdown plugin "${plugin}" with ${claimant}: both claim its ${capability}.`,
+ );
+ this.name = 'RichTextExtensionError';
+ this.plugin = plugin;
+ this.capability = capability;
+ this.claimant = claimant;
+ }
+}
+
+/**
+ * Adopts a Markdown plugin for RichText (spec:AST-064 FR1, FR4). RichText
+ * recognizes the plugin's syntax with core's parser and keeps each node's
+ * source; it never runs the plugin's immutable transform, so a plugin that
+ * declares one is refused with a `RichTextExtensionError` here, before any
+ * surface uses it.
+ *
+ * @example
+ * ```
+ * const mentions = createRichTextExtension(mentionsPlugin);
+ * markdownToEditorStateJSON(markdown, {extensions: [mentions]});
+ * ```
+ */
+export function createRichTextExtension(
+ plugin: MarkdownPluginEntry,
+): RichTextMarkdownExtension {
+ const capabilities = getMarkdownPluginCapabilities(plugin);
+ if (capabilities.transform) {
+ throw new RichTextExtensionError(plugin.name, 'transform', null);
+ }
+ return Object.freeze({name: plugin.name, [extensionPlugin]: plugin});
+}
+
+/**
+ * The plugins behind `extensions`, after checking that the configuration is
+ * one RichText can honor (spec:AST-064 FR6): no plugin adopted twice, and no
+ * transformer that imports or exports plugin nodes.
+ */
+export function pluginsOf(
+ extensions: ReadonlyArray<RichTextMarkdownExtension>,
+ transformers: ReadonlyArray<Transformer>,
+): ReadonlyArray<MarkdownPluginEntry> {
+ const seen = new Set<string>();
+ for (const extension of extensions) {
+ if (seen.has(extension.name)) {
+ throw new RichTextExtensionError(
+ extension.name,
+ 'syntax',
+ `a second extension for "${extension.name}"`,
+ );
+ }
+ seen.add(extension.name);
+ }
+ const [first] = extensions;
+ if (first != null) {
+ transformers.forEach((transformer, index) => {
+ if (
+ 'dependencies' in transformer &&
+ transformer.dependencies.includes(RichTextExtensionNode)
+ ) {
+ throw new RichTextExtensionError(
+ first.name,
+ 'nodes',
+ `transformer ${index} (${transformer.type})`,
+ );
+ }
+ });
+ }
+ return extensions.map(extension => extension[extensionPlugin]);
+}
+
+// ---------------------------------------------------------------------------
+// Shielding plugin source from Lexical's import
+// ---------------------------------------------------------------------------
+
+/** A plugin node core recognized, and the stand-in that holds its place. */
+export interface ShieldedNode {
+ readonly node: MarkdownExtensionNode;
+ readonly apiVersion: number;
+}
+
+export interface ShieldedMarkdown {
+ /** The Markdown with a stand-in in place of each recognized node. */
+ readonly markdown: string;
+ /** What each stand-in holds the place of. */
+ readonly standIns: ReadonlyMap<string, ShieldedNode>;
+}
+
+const PRIVATE_USE_RANGES: ReadonlyArray<readonly [number, number]> = [
+ [0xe000, 0xf8ff],
+ [0xf0000, 0xffffd],
+ [0x100000, 0x10fffd],
+];
+
+/** Private-use characters that do not occur in `text`, in order. */
+export function* absentCharacters(text: string): Generator<string> {
+ const present = new Set(text);
+ for (const [first, last] of PRIVATE_USE_RANGES) {
+ for (let codePoint = first; codePoint <= last; codePoint++) {
+ const character = String.fromCodePoint(codePoint);
+ if (!present.has(character)) {
+ yield character;
+ }
+ }
+ }
+}
+
+/**
+ * The extension nodes core recognizes in `markdown`, in document order: inline
+ * nodes anywhere, and block nodes at the top level only (block syntax nested
+ * in a list item, quote, or table cell stays text in RichText).
+ */
+function recognizedNodes(
+ markdown: string,
+ plugins: ReadonlyArray<MarkdownPluginEntry>,
+): {
+ readonly adoptable: Array<MarkdownExtensionNode>;
+ readonly total: number;
+} {
+ const adoptable: Array<MarkdownExtensionNode> = [];
+ let total = 0;
+ const visit = (node: unknown, isTopLevel: boolean) => {
+ if (node == null || typeof node !== 'object') {
+ return;
+ }
+ const candidate = node as {
+ readonly type?: unknown;
+ readonly children?: unknown;
+ };
+ if (candidate.type === 'extension') {
+ total++;
+ const extension = node as MarkdownExtensionNode;
+ if (
+ typeof extension.source === 'string' &&
+ (extension.display === 'inline' || isTopLevel)
+ ) {
+ adoptable.push(extension);
+ }
+ return;
+ }
+ if (Array.isArray(candidate.children)) {
+ for (const child of candidate.children) {
+ visit(child, false);
+ }
+ }
+ };
+ const root = parseMarkdownAst(markdown, {plugins: [...plugins]});
+ for (const block of root.children) {
+ visit(block, true);
+ }
+ return {adoptable, total};
+}
+
+/**
+ * Replaces the source of every plugin node core recognizes in `markdown` with
+ * a stand-in, so Lexical's transformers never read plugin source as base
+ * Markdown (spec:AST-064 FR5). A node whose source core does not recognize at
+ * any one occurrence — a span split across a container's line markers — stays
+ * text.
+ */
+export function shieldExtensionSources(
+ markdown: string,
+ plugins: ReadonlyArray<MarkdownPluginEntry>,
+): ShieldedMarkdown {
+ const standIns = new Map<string, ShieldedNode>();
+ if (plugins.length === 0) {
+ return {markdown, standIns};
+ }
+ const {adoptable, total} = recognizedNodes(markdown, plugins);
+ if (adoptable.length === 0) {
+ return {markdown, standIns};
+ }
+ const versions = new Map(
+ plugins.map(plugin => [plugin.name, plugin.apiVersion]),
+ );
+ const tokens = absentCharacters(markdown);
+ // How many recognized nodes with each source are still to be placed.
+ const remaining = new Map<string, number>();
+ for (const node of adoptable) {
+ const source = node.source ?? '';
+ remaining.set(source, (remaining.get(source) ?? 0) + 1);
+ }
+ let text = markdown;
+ let shielded = 0;
+ let searchFrom = 0;
+ for (const node of adoptable) {
+ const source = node.source ?? '';
+ const token = tokens.next().value;
+ if (token == null || source === '') {
+ break;
+ }
+ const first = text.indexOf(source, searchFrom);
+ // When every remaining occurrence of the source is a node core
+ // recognized, the first occurrence is this node: no need to ask core.
+ const isEveryOccurrence =
+ occurrences(text, source, searchFrom) === (remaining.get(source) ?? 0);
+ remaining.set(source, (remaining.get(source) ?? 1) - 1);
+ for (let at = first; at !== -1; at = text.indexOf(source, at + 1)) {
+ const candidate =
+ text.slice(0, at) + token + text.slice(at + source.length);
+ // The right occurrence is the one whose replacement removes exactly
+ // this node from core's parse and leaves every other node in place.
+ if (
+ isEveryOccurrence ||
+ recognizedNodes(candidate, plugins).total === total - shielded - 1
+ ) {
+ text = candidate;
+ shielded++;
+ searchFrom = at + token.length;
+ standIns.set(token, {
+ node,
+ apiVersion: versions.get(node.plugin) ?? 1,
+ });
+ break;
+ }
+ }
+ }
+ return {markdown: text, standIns};
+}
+
+/** How many times `source` occurs in `text` from `from`, overlaps included. */
+function occurrences(text: string, source: string, from: number): number {
+ let count = 0;
+ for (
+ let at = text.indexOf(source, from);
+ at !== -1;
+ at = text.indexOf(source, at + 1)
+ ) {
+ count++;
+ }
+ return count;
+}
+
+function $nodeFor(
+ {node, apiVersion}: ShieldedNode,
+ format = 0,
+): RichTextExtensionNode {
+ return $createRichTextExtensionNode(
+ {
+ plugin: node.plugin,
+ apiVersion,
+ name: node.name,
+ display: node.display,
+ data: node.data,
+ source: node.source ?? '',
+ },
+ format,
+ );
+}
+
+/**
+ * Puts a RichTextExtensionNode in place of every stand-in Lexical imported
+ * into `holder`: inline nodes where their stand-in is, and a block node in
+ * place of the paragraph that holds only its stand-in.
+ */
+export function $restoreExtensionSources(
+ holder: ElementNode,
+ standIns: ReadonlyMap<string, ShieldedNode>,
+): void {
+ if (standIns.size === 0) {
+ return;
+ }
+ for (const textNode of holder.getAllTextNodes()) {
+ $restoreInText(textNode, holder, standIns);
+ }
+}
+
+function $restoreInText(
+ textNode: TextNode,
+ holder: ElementNode,
+ standIns: ReadonlyMap<string, ShieldedNode>,
+): void {
+ const text = textNode.getTextContent();
+ const offsets = new Set<number>();
+ let offset = 0;
+ for (const character of text) {
+ if (standIns.has(character)) {
+ offsets.add(offset);
+ offsets.add(offset + character.length);
+ }
+ offset += character.length;
+ }
+ offsets.delete(0);
+ offsets.delete(text.length);
+ if (offsets.size === 0 && !standIns.has(text)) {
+ return;
+ }
+ const pieces =
+ offsets.size === 0
+ ? [textNode]
+ : textNode.splitText(...[...offsets].sort((a, b) => a - b));
+ for (const piece of pieces) {
+ const shielded = standIns.get(piece.getTextContent());
+ if (shielded == null) {
+ continue;
+ }
+ if (shielded.node.display === 'inline') {
+ // The node keeps the text formats its stand-in had: a node inside
+ // emphasis, strong, or strikethrough stays inside it.
+ piece.replace($nodeFor(shielded, piece.getFormat()));
+ continue;
+ }
+ const paragraph = piece.getParent();
+ if (
+ $isParagraphNode(paragraph) &&
+ paragraph.getParent()?.is(holder) === true
+ ) {
+ $placeBlockNode(paragraph, piece, $nodeFor(shielded));
+ } else {
+ // A block stand-in that did not land in a top-level paragraph keeps
+ // the node's source as text.
+ piece.replace($createTextNode(shielded.node.source ?? ''));
+ }
+ }
+}
+
+/**
+ * Puts a block node where its stand-in sits in `paragraph`, splitting the
+ * paragraph around it: lines before the stand-in stay a paragraph, the node
+ * follows as its own top-level block, and lines after it become a new
+ * paragraph — as core reads a block that starts on the line after a paragraph
+ * line.
+ */
+function $placeBlockNode(
+ paragraph: ParagraphNode,
+ standIn: TextNode,
+ block: RichTextExtensionNode,
+): void {
+ const after = standIn.getNextSiblings();
+ const before = standIn.getPreviousSiblings();
+ // The line breaks around the stand-in end and start the neighbouring lines.
+ if ($isLineBreakNode(before[before.length - 1])) {
+ before[before.length - 1]?.remove();
+ }
+ if ($isLineBreakNode(after[0])) {
+ after[0]?.remove();
+ after.shift();
+ }
+ standIn.remove();
+ if (after.length > 0) {
+ const rest = $createParagraphNode();
+ rest.append(...after);
+ paragraph.insertAfter(rest);
+ }
+ paragraph.insertAfter(block);
+ if (paragraph.getChildrenSize() === 0) {
+ paragraph.remove();
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+const NEVER = /(?!)/;
+
+/**
+ * Exports every plugin node as its exact source (spec:AST-064 FR10). Always
+ * part of RichText's export, whatever transformers the caller passes, so no
+ * transformer set can drop a plugin node's source.
+ */
+export const EXTENSION_EXPORT_TRANSFORMERS: ReadonlyArray<Transformer> = [
+ {
+ dependencies: [RichTextExtensionNode],
+ export: (node: LexicalNode) =>
+ $isRichTextExtensionNode(node) && !node.isInline()
+ ? node.getSource()
+ : null,
+ regExp: NEVER,
+ replace: () => false,
+ type: 'element',
+ },
+ {
+ dependencies: [RichTextExtensionNode],
+ export: (node: LexicalNode) =>
+ $isRichTextExtensionNode(node) && node.isInline()
+ ? node.getSource()
+ : null,
+ importRegExp: NEVER,
+ regExp: NEVER,
+ replace: () => {},
+ type: 'text-match',
+ },
+];
+
+/**
+ * A text view of an inline plugin node for Lexical's exporter: it reads as
+ * text holding `placeholder`, with the node's formats, so emphasis, strong, or
+ * strikethrough around the node wraps it instead of closing before it. The
+ * caller writes the node's source in place of the placeholder.
+ */
+export function extensionTextView(
+ node: RichTextExtensionNode,
+ placeholder: string,
+): TextNode {
+ const view = Object.create(TextNode.prototype) as TextNode;
+ // Reads of the view's format go to the node itself through its key.
+ Object.assign(view, {__key: node.getKey()});
+ view.getTextContent = () => placeholder;
+ view.getParent = <T extends ElementNode>() => node.getParent<T>();
+ return view;
+}
+
+const withExport = new WeakMap<
+ ReadonlyArray<Transformer>,
+ Array<Transformer>
+>();
+
+/**
+ * `transformers` with the plugin node export first, the same array for the
+ * same transformers so callers that cache by transformer list keep hitting.
+ */
+export function withExtensionExport(
+ transformers: ReadonlyArray<Transformer>,
+): Array<Transformer> {
+ let combined = withExport.get(transformers);
+ if (combined == null) {
+ combined = [...EXTENSION_EXPORT_TRANSFORMERS, ...transformers];
+ withExport.set(transformers, combined);
+ }
+ return combined;
+}
diff --git a/packages/richtext/src/markdownSerializers.ts b/packages/richtext/src/markdownSerializers.ts
index 9ad8e32496..9bfc1752ed 100644
--- a/packages/richtext/src/markdownSerializers.ts
+++ b/packages/richtext/src/markdownSerializers.ts
@@ -7,8 +7,8 @@
* and the source-preserving import and export in markdownSource.ts.
* @output Standalone Markdown <-> serialized EditorState helpers:
* markdownToEditorStateJSON, editorStateJSONToMarkdown.
- * @position Re-exported from RichTextEditor/index.ts and the @astryxdesign/richtext
- * barrel. Complements the ref's getMarkdown() by working WITHOUT a mounted
+ * @position Exported from the server-safe `@astryxdesign/richtext/markdown`
+ * entry and re-exported from the @astryxdesign/richtext barrel. Complements the ref's getMarkdown() by working WITHOUT a mounted
* editor (e.g. to produce a `defaultValue` from Markdown on the server).
*
* SYNC: When modified, update:
@@ -30,6 +30,7 @@ import {
importMarkdownKeepingSource,
} from './markdownSource';
import {DEFAULT_TRANSFORMERS} from './markdownTable';
+import {pluginsOf, type RichTextMarkdownExtension} from './markdownExtensions';
import type {Klass, LexicalNode} from 'lexical';
/** Options shared by the Markdown serializer helpers. */
@@ -46,6 +47,13 @@ export interface MarkdownSerializerOptions {
* editor's `nodes` prop. Required for custom node types to serialize.
*/
nodes?: ReadonlyArray<Klass<LexicalNode>>;
+ /**
+ * Markdown plugins to recognize, each adopted with `createRichTextExtension`
+ * (spec:AST-064). Their syntax becomes extension nodes holding its exact
+ * source; without them, plugin syntax stays text. Pass the same extensions
+ * the surfaces that show the document use.
+ */
+ extensions?: ReadonlyArray<RichTextMarkdownExtension>;
}
function createSerializerEditor(nodes?: ReadonlyArray<Klass<LexicalNode>>) {
@@ -73,9 +81,10 @@ export function markdownToEditorStateJSON(
markdown: string,
options: MarkdownSerializerOptions = {},
): string {
- const {transformers = DEFAULT_TRANSFORMERS, nodes} = options;
+ const {transformers = DEFAULT_TRANSFORMERS, nodes, extensions = []} = options;
+ const plugins = pluginsOf(extensions, transformers);
const editor = createSerializerEditor(nodes);
- importMarkdownKeepingSource(editor, markdown, [...transformers]);
+ importMarkdownKeepingSource(editor, markdown, [...transformers], plugins);
return JSON.stringify(editor.getEditorState().toJSON());
}
diff --git a/packages/richtext/src/markdownSource.ts b/packages/richtext/src/markdownSource.ts
index 2964f59111..f6d285556e 100644
--- a/packages/richtext/src/markdownSource.ts
+++ b/packages/richtext/src/markdownSource.ts
@@ -3,7 +3,8 @@
/**
* @file markdownSource.ts
* @input Uses lexical (node state, root, node classes), @lexical/markdown
- * ($convertFromMarkdownString / $convertToMarkdownString), and @lexical/code.
+ * ($convertFromMarkdownString / $convertToMarkdownString), @lexical/code,
+ * and the plugin node shielding and export in markdownExtensions.ts.
* @output Exports importMarkdownKeepingSource and $exportMarkdownKeepingSource,
* the source-preserving Markdown import and export behind
* markdownToEditorStateJSON, editorStateJSONToMarkdown, and getMarkdown().
@@ -46,6 +47,7 @@ import {
type ElementNode,
type LexicalEditor,
type LexicalNode,
+ type NodeKey,
} from 'lexical';
import {isMarkedHardLineBreak} from './markdownHardLineBreak';
import {normalizeListIndentation} from './markdownListIndentation';
@@ -53,6 +55,15 @@ import {
$restoreCharacterReferences,
protectCharacterReferences,
} from './markdownCharacterReferences';
+import {
+ $restoreExtensionSources,
+ absentCharacters,
+ extensionTextView,
+ shieldExtensionSources,
+ withExtensionExport,
+} from './markdownExtensions';
+import {$isRichTextExtensionNode} from './markdownExtensionNode';
+import type {MarkdownPluginEntry} from '@astryxdesign/core/Markdown/plugins';
/** The whitespace and content one chunk of Markdown source was split into. */
export interface MarkdownChunk {
@@ -327,6 +338,7 @@ export function importMarkdownKeepingSource(
editor: LexicalEditor,
markdown: string,
transformers: Array<Transformer>,
+ plugins: ReadonlyArray<MarkdownPluginEntry> = [],
): void {
const importId = nextImportId();
const byteOrderMark = markdown.startsWith('\uFEFF');
@@ -349,12 +361,19 @@ export function importMarkdownKeepingSource(
const holder = $createParagraphNode();
root.append(holder);
// Lexical imports LF lines; the record keeps the authored endings.
- // Character references go through as stand-ins and come back decoded.
- const {markdown: chunkMarkdown, standIns} = protectCharacterReferences(
+ // Adopted plugins' nodes, and then character references, go through
+ // as stand-ins: plugin nodes come back as extension nodes holding
+ // their source, references come back decoded.
+ const shielded = shieldExtensionSources(
withoutCarriageReturns(importChunks[index]?.content ?? chunk.content),
+ plugins,
+ );
+ const {markdown: chunkMarkdown, standIns} = protectCharacterReferences(
+ shielded.markdown,
);
$convertFromMarkdownString(chunkMarkdown, transformers, holder);
$restoreCharacterReferences(holder, standIns);
+ $restoreExtensionSources(holder, shielded.standIns);
$joinSoftLineBreaks(holder);
for (const node of holder.getChildren()) {
$setState(node, groupState, {group: `${importId}:${index}`});
@@ -580,7 +599,10 @@ function $canonicalMarkdown(
) {
return cached;
}
- const markdown = $convertToMarkdownString(transformers, childrenOf(nodes));
+ const markdown = $convertToMarkdownString(
+ withExtensionExport(transformers),
+ childrenOf(nodes),
+ );
const entry = {descendants, transformers, markdown, hash: hashOf(markdown)};
canonicalCache.set(nodes[0], entry);
return entry;
@@ -644,7 +666,15 @@ export function absentToken(text: string): string {
* with `token`. Views delegate everything else to the node they wrap, so
* Lexical's exporter reads them like the real tree without changing it.
*/
-function markedView(node: LexicalNode, token: string): LexicalNode {
+function markedView(
+ node: LexicalNode,
+ token: string,
+ placeholders: ReadonlyMap<NodeKey, string>,
+): LexicalNode {
+ const placeholder = placeholders.get(node.getKey());
+ if (placeholder != null && $isRichTextExtensionNode(node)) {
+ return extensionTextView(node, placeholder);
+ }
if ($isTextNode(node)) {
if (node.hasFormat('code') || $isCodeNode(node.getParent())) {
return node;
@@ -666,7 +696,19 @@ function markedView(node: LexicalNode, token: string): LexicalNode {
return view;
}
if ($isElementNode(node) && !$isCodeNode(node)) {
- const children = node.getChildren().map(child => markedView(child, token));
+ const children = node
+ .getChildren()
+ .map(child => markedView(child, token, placeholders));
+ // Each view's siblings are the views beside it, so a text view sees a
+ // plugin node's text view as text with formats, not as a gap.
+ children.forEach((child, index) => {
+ if (child !== node.getChildren()[index]) {
+ child.getPreviousSibling = <T extends LexicalNode>() =>
+ (children[index - 1] ?? null) as T | null;
+ child.getNextSibling = <T extends LexicalNode>() =>
+ (children[index + 1] ?? null) as T | null;
+ }
+ });
const view = Object.create(node) as typeof node;
view.getChildren = <T extends LexicalNode>() => children as Array<T>;
return view;
@@ -685,14 +727,34 @@ function $regeneratedMarkdown(
): string {
// The token is absent from the plain export and from every text the views
// mark, so each token in the marked export is one of the marks.
- const token = absentToken(
- canonical + nodes.map(node => node.getTextContent()).join(''),
- );
- const marked = $convertToMarkdownString(
- transformers,
- childrenOf(nodes.map(node => markedView(node, token))),
- );
- return marked.split(token).join('\\');
+ const text = canonical + nodes.map(node => node.getTextContent()).join('');
+ const token = absentToken(text);
+ // Inline plugin nodes export as placeholders inside the text around them,
+ // so the marks around a node wrap it; each placeholder becomes the node's
+ // exact source afterwards.
+ const placeholders = new Map<NodeKey, string>();
+ const sources = new Map<string, string>();
+ const free = absentCharacters(text + token);
+ for (const node of descendantsOf(nodes)) {
+ if ($isRichTextExtensionNode(node) && node.isInline()) {
+ const placeholder = free.next().value;
+ if (placeholder == null) {
+ break;
+ }
+ placeholders.set(node.getKey(), placeholder);
+ sources.set(placeholder, node.getSource());
+ }
+ }
+ let marked = $convertToMarkdownString(
+ withExtensionExport(transformers),
+ childrenOf(nodes.map(node => markedView(node, token, placeholders))),
+ )
+ .split(token)
+ .join('\\');
+ for (const [placeholder, source] of sources) {
+ marked = marked.split(placeholder).join(source);
+ }
+ return marked;
}
interface ExportPiece {