onchain-lexical-markdown 0.0.1

package/OnchainLexicalMarkdown.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+
+module.exports = require('./dist/OnchainLexicalMarkdown.js');

package/README.md

@@ -0,0 +1,96 @@
+# `@lexical/markdown`
+
+[![See API Documentation](https://lexical.dev/img/see-api-documentation.svg)](https://lexical.dev/docs/api/modules/lexical_markdown)
+
+This package contains markdown helpers for Lexical: import, export and shortcuts.
+
+## Import and export
+```js
+import {
+  $convertFromMarkdownString,
+  $convertToMarkdownString,
+  TRANSFORMERS,
+} from '@lexical/markdown';
+
+editor.update(() => {
+  const markdown = $convertToMarkdownString(TRANSFORMERS);
+  ...
+});
+
+editor.update(() => {
+  $convertFromMarkdownString(markdown, TRANSFORMERS);
+});
+```
+
+It can also be used for initializing editor's state from markdown string. Here's an example with react `<RichTextPlugin>`
+```jsx
+<LexicalComposer initialConfig={{
+  editorState: () => $convertFromMarkdownString(markdown, TRANSFORMERS)
+}}>
+  <RichTextPlugin />
+</LexicalComposer>
+```
+
+## Shortcuts
+Can use `<MarkdownShortcutPlugin>` if using React
+```jsx
+import { TRANSFORMERS } from '@lexical/markdown';
+import {MarkdownShortcutPlugin} from '@lexical/react/LexicalMarkdownShortcutPlugin';
+
+<LexicalComposer>
+  <MarkdownShortcutPlugin transformers={TRANSFORMERS} />
+</LexicalComposer>
+```
+
+Or `registerMarkdownShortcuts` to register it manually:
+```js
+import {
+  registerMarkdownShortcuts,
+  TRANSFORMERS,
+} from '@lexical/markdown';
+
+const editor = createEditor(...);
+registerMarkdownShortcuts(editor, TRANSFORMERS);
+```
+
+## Transformers
+Markdown functionality relies on transformers configuration. It's an array of objects that define how certain text or nodes
+are processed during import, export or while typing. `@lexical/markdown` package provides set of built-in transformers:
+```js
+// Element transformers
+UNORDERED_LIST
+CODE
+HEADING
+ORDERED_LIST
+QUOTE
+
+// Text format transformers
+BOLD_ITALIC_STAR
+BOLD_ITALIC_UNDERSCORE
+BOLD_STAR
+BOLD_UNDERSCORE
+INLINE_CODE
+ITALIC_STAR
+ITALIC_UNDERSCORE
+STRIKETHROUGH
+
+// Text match transformers
+LINK
+```
+
+And bundles of commonly used transformers:
+- `TRANSFORMERS` - all built-in transformers
+- `ELEMENT_TRANSFORMERS` - all built-in element transformers
+- `MULTILINE_ELEMENT_TRANSFORMERS` - all built-in multiline element transformers
+- `TEXT_FORMAT_TRANSFORMERS` - all built-in text format transformers
+- `TEXT_MATCH_TRANSFORMERS` - all built-in text match transformers
+
+Transformers are explicitly passed to markdown API allowing application-specific subset of markdown or custom transformers.
+
+There're three types of transformers:
+
+- **Element transformer** handles top level elements (lists, headings, quotes, tables or code blocks)
+- **Text format transformer** applies text range formats defined in `TextFormatType` (bold, italic, underline, strikethrough, code, subscript and superscript)
+- **Text match transformer** relies on matching leaf text node content
+
+See `MarkdownTransformers.js` for transformer implementation examples

package/flow/OnchainLexicalMarkdown.js.flow

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import type {
+  LexicalEditor,
+  LexicalNode,
+  ElementNode,
+  TextFormatType,
+  TextNode,
+} from 'lexical';
+
+export type Transformer =
+  | ElementTransformer
+  | MultilineElementTransformer
+  | TextFormatTransformer
+  | TextMatchTransformer;
+
+export type ElementTransformer = {
+  dependencies: Array<Class<LexicalNode>>,
+  export: (
+    node: LexicalNode,
+    traverseChildren: (node: ElementNode) => string,
+  ) => string | null,
+  regExp: RegExp,
+  replace: (
+    parentNode: ElementNode,
+    children: Array<LexicalNode>,
+    match: Array<string>,
+    isImport: boolean,
+  ) => boolean | void,
+  type: 'element',
+};
+
+export type MultilineElementTransformer = {
+  dependencies: Array<Class<LexicalNode>>;
+  export?: (
+    node: LexicalNode,
+    traverseChildren: (node: ElementNode) => string,
+  ) => string | null;
+  regExpStart: RegExp;
+  regExpEnd?:
+    | RegExp
+    | {
+        optional?: true;
+        regExp: RegExp;
+      };
+  replace: (
+    rootNode: ElementNode,
+    children: Array<LexicalNode> | null,
+    startMatch: Array<string>,
+    endMatch: Array<string> | null,
+    linesInBetween: Array<string> | null,
+    isImport: boolean,
+  ) => boolean | void;
+  type: 'multiline-element';
+};
+
+export type TextFormatTransformer = $ReadOnly<{
+  format: $ReadOnlyArray<TextFormatType>,
+  tag: string,
+  intraword?: boolean,
+  type: 'text-format',
+}>;
+
+export type TextMatchTransformer = $ReadOnly<{
+  dependencies: Array<Class<LexicalNode>>,
+  export: (
+    node: LexicalNode,
+    exportChildren: (node: ElementNode) => string,
+    exportFormat: (node: TextNode, textContent: string) => string,
+  ) => string | null,
+  importRegExp: RegExp,
+  regExp: RegExp,
+  replace: (node: TextNode, match: RegExp$matchResult) => void,
+  trigger: string,
+  type: 'text-match',
+}>;
+// TODO:
+// transformers should be required argument, breaking change
+declare export function registerMarkdownShortcuts(
+  editor: LexicalEditor,
+  transformers?: Array<Transformer>,
+): () => void;
+
+// TODO:
+// transformers should be required argument, breaking change
+declare export function $convertFromMarkdownString(
+  markdown: string,
+  transformers?: Array<Transformer>,
+  node?: ElementNode,
+  shouldPreserveNewLines?: boolean,
+  shouldMergeAdjacentLines?: boolean,
+): void;
+
+// TODO:
+// transformers should be required argument, breaking change
+declare export function $convertToMarkdownString(
+  transformers?: Array<Transformer>,
+  node?: ElementNode,
+  shouldPreserveNewLines?: boolean,
+): string;
+
+declare export var BOLD_ITALIC_STAR: TextFormatTransformer;
+declare export var BOLD_ITALIC_UNDERSCORE: TextFormatTransformer;
+declare export var BOLD_STAR: TextFormatTransformer;
+declare export var BOLD_UNDERSCORE: TextFormatTransformer;
+declare export var INLINE_CODE: TextFormatTransformer;
+declare export var ITALIC_STAR: TextFormatTransformer;
+declare export var ITALIC_UNDERSCORE: TextFormatTransformer;
+declare export var STRIKETHROUGH: TextFormatTransformer;
+
+declare export var UNORDERED_LIST: ElementTransformer;
+declare export var CODE: MultilineElementTransformer;
+declare export var HEADING: ElementTransformer;
+declare export var ORDERED_LIST: ElementTransformer;
+declare export var QUOTE: ElementTransformer;
+declare export var CHECK_LIST: ElementTransformer;
+
+declare export var LINK: TextMatchTransformer;
+
+declare export var TRANSFORMERS: Array<Transformer>;
+declare export var ELEMENT_TRANSFORMERS: Array<ElementTransformer>;
+declare export var TEXT_FORMAT_TRANSFORMERS: Array<TextFormatTransformer>;
+declare export var TEXT_MATCH_TRANSFORMERS: Array<TextFormatTransformer>;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "onchain-lexical-markdown",
+  "description": "This package contains Markdown helpers and functionality for Lexical.",
+  "keywords": [
+    "lexical",
+    "editor",
+    "rich-text",
+    "markdown"
+  ],
+  "license": "MIT",
+  "version": "0.0.1",
+  "main": "OnchainLexicalMarkdown.js",
+  "types": "index.d.ts",
+  "dependencies": {
+    "@lexical/code": "0.30.0",
+    "@lexical/link": "0.30.0",
+    "@lexical/list": "0.30.0",
+    "@lexical/react": "^0.30.0",
+    "@lexical/rich-text": "0.30.0",
+    "@lexical/table": "^0.30.0",
+    "@lexical/text": "0.30.0",
+    "@lexical/utils": "0.30.0",
+    "lexical": "0.30.0",
+    "onchain-lexical-instance": "^0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/lexical",
+    "directory": "packages/lexical-markdown"
+  },
+  "module": "OnchainLexicalMarkdown.mjs",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./dist/OnchainLexicalMarkdown.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./dist/OnchainLexicalMarkdown.js"
+      }
+    }
+  }
+}

package/src/MarkdownExport.ts

@@ -0,0 +1,362 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {ElementNode, LexicalNode, TextFormatType, TextNode} from 'lexical';
+
+import {
+  $getRoot,
+  $isDecoratorNode,
+  $isElementNode,
+  $isLineBreakNode,
+  $isTextNode,
+} from 'lexical';
+import {
+  $isBarDecoratorNode,
+  $isNumberDecoratorNode,
+} from 'onchain-lexical-instance';
+
+import {
+  ElementTransformer,
+  MultilineElementTransformer,
+  TextFormatTransformer,
+  TextMatchTransformer,
+  Transformer,
+} from './MarkdownTransformers';
+import {isEmptyParagraph, transformersByType} from './utils';
+
+/**
+ * Renders string from markdown. The selection is moved to the start after the operation.
+ */
+export function createMarkdownExport(
+  transformers: Array<Transformer>,
+  shouldPreserveNewLines: boolean = false,
+): (node?: ElementNode) => string {
+  const byType = transformersByType(transformers);
+  const elementTransformers = [...byType.multilineElement, ...byType.element];
+  const isNewlineDelimited = !shouldPreserveNewLines;
+
+  // Export only uses text formats that are responsible for single format
+  // e.g. it will filter out *** (bold, italic) and instead use separate ** and *
+  const textFormatTransformers = byType.textFormat
+    .filter((transformer) => transformer.format.length === 1)
+    // Make sure all text transformers that contain 'code' in their format are at the end of the array. Otherwise, formatted code like
+    // <strong><code>code</code></strong> will be exported as `**Bold Code**`, as the code format will be applied first, and the bold format
+    // will be applied second and thus skipped entirely, as the code format will prevent any further formatting.
+    .sort((a, b) => {
+      return (
+        Number(a.format.includes('code')) - Number(b.format.includes('code'))
+      );
+    });
+
+  return (node) => {
+    const output = [];
+    const children = (node || $getRoot()).getChildren();
+
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      const result = exportTopLevelElements(
+        child,
+        elementTransformers,
+        textFormatTransformers,
+        byType.textMatch,
+      );
+      if (result != null) {
+        if (
+          [$isBarDecoratorNode, $isNumberDecoratorNode].every(
+            (fn) => !fn(child),
+          )
+        ) {
+          output.push(
+            // separate consecutive group of texts with a line break: eg. ["hello", "world"] -> ["hello", "/nworld"]
+            isNewlineDelimited &&
+              i > 0 &&
+              !isEmptyParagraph(child) &&
+              !isEmptyParagraph(children[i - 1])
+              ? '\n'.concat(result)
+              : result,
+          );
+        }
+      }
+    }
+    // Ensure consecutive groups of texts are at least \n\n apart while each empty paragraph render as a newline.
+    // Eg. ["hello", "", "", "hi", "\nworld"] -> "hello\n\n\nhi\n\nworld"
+    return output.join('\n');
+  };
+}
+
+function exportTopLevelElements(
+  node: LexicalNode,
+  elementTransformers: Array<ElementTransformer | MultilineElementTransformer>,
+  textTransformersIndex: Array<TextFormatTransformer>,
+  textMatchTransformers: Array<TextMatchTransformer>,
+): string | null {
+  for (const transformer of elementTransformers) {
+    if (!transformer.export) {
+      continue;
+    }
+    const result = transformer.export(node, (_node) =>
+      exportChildren(_node, textTransformersIndex, textMatchTransformers),
+    );
+
+    if (result != null) {
+      return result;
+    }
+  }
+
+  if ($isElementNode(node)) {
+    return exportChildren(node, textTransformersIndex, textMatchTransformers);
+  } else if ($isDecoratorNode(node)) {
+    return node.getTextContent();
+  } else {
+    return null;
+  }
+}
+
+function exportChildren(
+  node: ElementNode,
+  textTransformersIndex: Array<TextFormatTransformer>,
+  textMatchTransformers: Array<TextMatchTransformer>,
+  unclosedTags?: Array<{format: TextFormatType; tag: string}>,
+  unclosableTags?: Array<{format: TextFormatType; tag: string}>,
+): string {
+  const output = [];
+  const children = node.getChildren();
+  // keep track of unclosed tags from the very beginning
+  if (!unclosedTags) {
+    unclosedTags = [];
+  }
+  if (!unclosableTags) {
+    unclosableTags = [];
+  }
+
+  mainLoop: for (const child of children) {
+    for (const transformer of textMatchTransformers) {
+      if (!transformer.export) {
+        continue;
+      }
+
+      const result = transformer.export(
+        child,
+        (parentNode) =>
+          exportChildren(
+            parentNode,
+            textTransformersIndex,
+            textMatchTransformers,
+            unclosedTags,
+            // Add current unclosed tags to the list of unclosable tags - we don't want nested tags from
+            // textmatch transformers to close the outer ones, as that may result in invalid markdown.
+            // E.g. **text [text**](https://lexical.io)
+            // is invalid markdown, as the closing ** is inside the link.
+            //
+            [...unclosableTags, ...unclosedTags],
+          ),
+        (textNode, textContent) =>
+          exportTextFormat(
+            textNode,
+            textContent,
+            textTransformersIndex,
+            unclosedTags,
+            unclosableTags,
+          ),
+      );
+
+      if (result != null) {
+        output.push(result);
+        continue mainLoop;
+      }
+    }
+
+    if ($isLineBreakNode(child)) {
+      output.push('\n');
+    } else if ($isTextNode(child)) {
+      output.push(
+        exportTextFormat(
+          child,
+          child.getTextContent(),
+          textTransformersIndex,
+          unclosedTags,
+          unclosableTags,
+        ),
+      );
+    } else if ($isElementNode(child)) {
+      // empty paragraph returns ""
+      output.push(
+        exportChildren(
+          child,
+          textTransformersIndex,
+          textMatchTransformers,
+          unclosedTags,
+          unclosableTags,
+        ),
+      );
+    } else if ($isDecoratorNode(child)) {
+      output.push(child.getTextContent());
+    }
+  }
+
+  return output.join('');
+}
+
+function exportTextFormat(
+  node: TextNode,
+  textContent: string,
+  textTransformers: Array<TextFormatTransformer>,
+  // unclosed tags include the markdown tags that haven't been closed yet, and their associated formats
+  unclosedTags: Array<{format: TextFormatType; tag: string}>,
+  unclosableTags?: Array<{format: TextFormatType; tag: string}>,
+): string {
+  // This function handles the case of a string looking like this: "   foo   "
+  // Where it would be invalid markdown to generate: "**   foo   **"
+  // If the node has no format, we use the original text.
+  // Otherwise, we escape leading and trailing whitespaces to their corresponding code points,
+  // ensuring the returned string maintains its original formatting, e.g., "**&#32;&#32;&#32;foo&#32;&#32;&#32;**".
+  let output =
+    node.getFormat() === 0
+      ? textContent
+      : escapeLeadingAndTrailingWhitespaces(textContent);
+
+  if (!node.hasFormat('code')) {
+    // Escape any markdown characters in the text content
+    output = output.replace(/([*_`~\\])/g, '\\$1');
+  }
+
+  // the opening tags to be added to the result
+  let openingTags = '';
+  // the closing tags to be added to the result
+  let closingTagsBefore = '';
+  let closingTagsAfter = '';
+
+  const prevNode = getTextSibling(node, true);
+  const nextNode = getTextSibling(node, false);
+
+  const applied = new Set();
+
+  for (const transformer of textTransformers) {
+    const format = transformer.format[0];
+    const tag = transformer.tag;
+
+    // dedup applied formats
+    if (hasFormat(node, format) && !applied.has(format)) {
+      // Multiple tags might be used for the same format (*, _)
+      applied.add(format);
+
+      // append the tag to openingTags, if it's not applied to the previous nodes,
+      // or the nodes before that (which would result in an unclosed tag)
+      if (
+        !hasFormat(prevNode, format) ||
+        !unclosedTags.find((element) => element.tag === tag)
+      ) {
+        unclosedTags.push({format, tag});
+        openingTags += tag;
+      }
+    }
+  }
+
+  // close any tags in the same order they were applied, if necessary
+  for (let i = 0; i < unclosedTags.length; i++) {
+    const nodeHasFormat = hasFormat(node, unclosedTags[i].format);
+    const nextNodeHasFormat = hasFormat(nextNode, unclosedTags[i].format);
+
+    // prevent adding closing tag if next sibling will do it
+    if (nodeHasFormat && nextNodeHasFormat) {
+      continue;
+    }
+
+    const unhandledUnclosedTags = [...unclosedTags]; // Shallow copy to avoid modifying the original array
+
+    while (unhandledUnclosedTags.length > i) {
+      const unclosedTag = unhandledUnclosedTags.pop();
+
+      // If tag is unclosable, don't close it and leave it in the original array,
+      // So that it can be closed when it's no longer unclosable
+      if (
+        unclosableTags &&
+        unclosedTag &&
+        unclosableTags.find((element) => element.tag === unclosedTag.tag)
+      ) {
+        continue;
+      }
+
+      if (unclosedTag && typeof unclosedTag.tag === 'string') {
+        if (!nodeHasFormat) {
+          // Handles cases where the tag has not been closed before, e.g. if the previous node
+          // was a text match transformer that did not account for closing tags of the next node (e.g. a link)
+          closingTagsBefore += unclosedTag.tag;
+        } else if (!nextNodeHasFormat) {
+          closingTagsAfter += unclosedTag.tag;
+        }
+      }
+      // Mutate the original array to remove the closed tag
+      unclosedTags.pop();
+    }
+    break;
+  }
+
+  output = openingTags + output + closingTagsAfter;
+  // Replace trimmed version of textContent ensuring surrounding whitespace is not modified
+  return closingTagsBefore + output;
+}
+
+// Get next or previous text sibling a text node, including cases
+// when it's a child of inline element (e.g. link)
+function getTextSibling(node: TextNode, backward: boolean): TextNode | null {
+  let sibling = backward ? node.getPreviousSibling() : node.getNextSibling();
+
+  if (!sibling) {
+    const parent = node.getParentOrThrow();
+
+    if (parent.isInline()) {
+      sibling = backward
+        ? parent.getPreviousSibling()
+        : parent.getNextSibling();
+    }
+  }
+
+  while (sibling) {
+    if ($isElementNode(sibling)) {
+      if (!sibling.isInline()) {
+        break;
+      }
+
+      const descendant = backward
+        ? sibling.getLastDescendant()
+        : sibling.getFirstDescendant();
+
+      if ($isTextNode(descendant)) {
+        return descendant;
+      } else {
+        sibling = backward
+          ? sibling.getPreviousSibling()
+          : sibling.getNextSibling();
+      }
+    }
+
+    if ($isTextNode(sibling)) {
+      return sibling;
+    }
+
+    if (!$isElementNode(sibling)) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+function hasFormat(
+  node: LexicalNode | null | undefined,
+  format: TextFormatType,
+): boolean {
+  return $isTextNode(node) && node.hasFormat(format);
+}
+
+function escapeLeadingAndTrailingWhitespaces(textContent: string) {
+  return textContent.replace(/^\s+|\s+$/g, (match) => {
+    return [...match].map((char) => '&#' + char.codePointAt(0) + ';').join('');
+  });
+}