feat(lexical-converter): add state transformer and HTML parser (#3569)

packages/app-headless-cms/package.json

@@ -24,6 +24,7 @@
     "@fortawesome/free-regular-svg-icons": "^6.0.0",
     "@fortawesome/free-solid-svg-icons": "^6.0.0",
     "@fortawesome/react-fontawesome": "^0.1.17",
+    "@lexical/utils": "^0.11.3",
     "@material-design-icons/svg": "^0.14.2",
     "@svgr/webpack": "^6.1.1",
     "@types/react": "17.0.39",

packages/app-headless-cms/src/admin/components/LexicalCmsEditor/TypographyDropDown.tsx

@@ -1,22 +1,27 @@
 import React, { useEffect, useState } from "react";
+import { $getNearestNodeOfType } from "@lexical/utils";
 import {
+    $isHeadingNode,
+    $isParagraphNode,
+    $isQuoteNode,
     DropDown,
     DropDownItem,
-    useRichTextEditor,
-    useTypographyAction
+    useCurrentSelection,
+    useCurrentElement,
+    useTypographyAction,
+    $isListNode,
+    ListNode
 } from "@webiny/lexical-editor";
 import { TypographyStyle } from "@webiny/theme/types";
 import { TypographyValue } from "@webiny/lexical-editor/types";
 import { useTheme } from "@webiny/app-admin";
-/*
- * This components support the typography selection for page builder and HCMS.
- * */
+
 export const TypographyDropDown = () => {
     const { value, applyTypography } = useTypographyAction();
     const { theme } = useTheme();
     const [styles, setStyles] = useState<TypographyStyle[]>([]);
-    const { textBlockSelection } = useRichTextEditor();
-    const textType = textBlockSelection?.state?.textType;
+    const { element } = useCurrentElement();
+    const { rangeSelection } = useCurrentSelection();
 
     const getAllTextStyles = (): TypographyStyle[] => {
         if (!theme?.styles.typography) {
@@ -28,8 +33,7 @@ export const TypographyDropDown = () => {
     };
 
     useEffect(() => {
-        // In static toolbar typography styles always need to be visible.
-        // User from the start can select immediately in witch style he wants to start typing.
+        // In static toolbar typography, styles always need to be visible.
         if (theme?.styles) {
             setStyles(getAllTextStyles());
         }
@@ -40,32 +44,46 @@ export const TypographyDropDown = () => {
         if (listStyles.length > 0) {
             return listStyles;
         }
-        // fallback
+
         const fallbackTag = tag === "ul" ? "ol" : "ul";
         return theme?.styles.typography.lists?.filter(x => x.tag === fallbackTag) || [];
     };
 
     useEffect(() => {
-        if (textType) {
-            switch (textType) {
-                case "heading":
-                case "paragraph":
-                    setStyles(getAllTextStyles());
-                    break;
-                case "bullet":
+        if (!element || !rangeSelection) {
+            return;
+        }
+
+        switch (true) {
+            case $isHeadingNode(element):
+            case $isParagraphNode(element):
+                setStyles(getAllTextStyles());
+                break;
+            case $isListNode(element):
+                let type;
+                try {
+                    const anchorNode = rangeSelection.anchor.getNode();
+                    const parentList = $getNearestNodeOfType<ListNode>(anchorNode, ListNode);
+                    if (parentList) {
+                        type = parentList.getListType();
+                    }
+                } catch {
+                    type = element.getListType();
+                }
+
+                if (type === "bullet") {
                     setStyles(getListStyles("ul"));
-                    break;
-                case "number":
+                } else {
                     setStyles(getListStyles("ol"));
-                    break;
-                case "quoteblock":
-                    setStyles(theme?.styles.typography?.quotes || []);
-                    break;
-                default:
-                    setStyles([]);
-            }
+                }
+                break;
+            case $isQuoteNode(element):
+                setStyles(theme?.styles.typography?.quotes || []);
+                break;
+            default:
+                setStyles([]);
         }
-    }, [textType]);
+    }, [element]);
 
     return (
         <>

packages/lexical-converter/.babelrc.js

@@ -0,0 +1 @@
+module.exports = require("@webiny/project-utils").createBabelConfigForNode({ path: __dirname });

packages/lexical-converter/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Webiny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/lexical-converter/README.md

@@ -0,0 +1,106 @@
+# @webiny/lexical-converter
+
+[![](https://img.shields.io/npm/dw/@webiny/lexical-converter.svg)](https://www.npmjs.com/package/@webiny/llexical-lexical-converter)
+[![](https://img.shields.io/npm/v/@webiny/lexical-converter.svg)](https://www.npmjs.com/package/@webiny/lexical-converter)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+## About
+
+This package provides features that will enable you to parse your HTML pages into Lexical editor state object.
+
+Further, this lexical state object can be imported into Webiny's apps like the Page builder and Headless CMS, trough the [Webiny's graphql API](https://www.webiny.com/docs/headless-cms/basics/graphql-api).
+
+> Webiny use the Lexical editor as primary rich text editor across the platform.
+
+Note: This module is built to be used in the `node.js` environment.
+
+## Usage
+
+To parse the HTML to lexical editor state object, you need to import `createHtmlToLexicalParser` factory function,
+to create the parser function (with default or custom configuration) and provide the HTML content as parameter.
+Parser will return Lexical editor state object.
+
+> The parser uses the default configuration with the Webiny's Lexical nodes. DOM elements like headings and
+> paragraph, for example, will be converted to our custom Webiny Lexical nodes.
+
+```tsx
+import { createHtmlToLexicalParser } from "@webiny/lexical-converter";
+
+const htmlString = "<p>My paragraph</p>";
+
+// Create a parser function.
+const myParser = createHtmlToLexicalParser();
+
+// Parse the HTML string to Lexical editor state object.
+const lexicalEditorState = myParser(htmlString);
+```
+
+Here is the result in JSON format. This object structure is a valid Lexical editor state.
+
+```json
+{
+  "root": {
+    "children": [
+      {
+        "children": [
+          {
+            "detail": 0,
+            "format": 0,
+            "mode": "normal",
+            "style": "",
+            "text": "Space",
+            "type": "text",
+            "version": 1
+          }
+        ],
+        "direction": null,
+        "format": "",
+        "indent": 0,
+        "styles": [],
+        "type": "paragraph-element",
+        "version": 1
+      }
+    ],
+    "direction": null,
+    "format": "",
+    "indent": 0,
+    "type": "root",
+    "version": 1
+  }
+}
+```
+
+## Configuration
+
+To configure the parser, you can pass an optional configuration object to the parser factory.
+
+```ts
+import { createHtmlToLexicalParser } from "@webiny/lexical-converter";
+import { myCustomTheme } from "./theme/myCustomTheme";
+import { MyCustomLexicalNode } from "./lexical/nodes/MyCustomLexicalNode";
+
+const addCustomThemeStyleToHeadings = (node: LexicalNode): LexicalNode => {
+  if (node.getType() === "heading-element") {
+    return (node as HeadingNode).setThemeStyles([{ styleId: "my-default-id", type: "typography" }]);
+  }
+  return node;
+};
+
+// Create your parser with custom configuration
+const myParser = createHtmlToLexicalParser({
+  // Lexical editor configuration
+  editorConfig: {
+    // Add custom nodes for parsing
+    nodes: [MyCustomLexicalNode],
+    // Add you custom theme
+    theme: myCustomTheme
+  },
+  nodeMapper: addCustomThemeStyleToHeadings,
+  normalizeTextNodes: false // Default: true
+});
+
+const lexicalEditorState = myParser(htmlString);
+```
+
+To learn more about how to create custom Lexical nodes, please visit [Lexical's documentation web page](https://lexical.dev/docs/intro).