LexicalBlockNormalizer

.flowconfig

@@ -39,6 +39,7 @@ module.name_mapper='^@lexical/plain-text$' -> '<PROJECT_ROOT>/packages/lexical-p
 module.name_mapper='^@lexical/react/LexicalAutoEmbedPlugin$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalAutoEmbedPlugin.js.flow'
 module.name_mapper='^@lexical/react/LexicalAutoFocusPlugin$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalAutoFocusPlugin.js.flow'
 module.name_mapper='^@lexical/react/LexicalAutoLinkPlugin$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalAutoLinkPlugin.js.flow'
+module.name_mapper='^@lexical/react/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.js.flow'
 module.name_mapper='^@lexical/react/LexicalBlockWithAlignableContents$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalBlockWithAlignableContents.js.flow'
 module.name_mapper='^@lexical/react/LexicalCharacterLimitPlugin$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalCharacterLimitPlugin.js.flow'
 module.name_mapper='^@lexical/react/LexicalCheckListPlugin$' -> '<PROJECT_ROOT>/packages/lexical-react/flow/LexicalCheckListPlugin.js.flow'

packages/lexical-devtools/tsconfig.json

@@ -35,6 +35,9 @@
       "@lexical/react/LexicalAutoLinkPlugin": [
         "../lexical-react/src/LexicalAutoLinkPlugin.ts"
       ],
+      "@lexical/react/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL": [
+        "../lexical-react/src/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.tsx"
+      ],
       "@lexical/react/LexicalBlockWithAlignableContents": [
         "../lexical-react/src/LexicalBlockWithAlignableContents.tsx"
       ],

packages/lexical-playground/src/App.tsx

@@ -19,14 +19,15 @@ import {SharedAutocompleteContext} from './context/SharedAutocompleteContext';
 import {SharedHistoryContext} from './context/SharedHistoryContext';
 import Editor from './Editor';
 import logo from './images/logo.svg';
-import PlaygroundNodes from './nodes/PlaygroundNodes';
+import {NODES} from './nodes/PlaygroundNodes';
 import DocsPlugin from './plugins/DocsPlugin';
 import PasteLogPlugin from './plugins/PasteLogPlugin';
 import {TableContext} from './plugins/TablePlugin';
 import TestRecorderPlugin from './plugins/TestRecorderPlugin';
 import TypingPerfPlugin from './plugins/TypingPerfPlugin';
 import Settings from './Settings';
 import PlaygroundEditorTheme from './themes/PlaygroundEditorTheme';
+import onError from './utils/onError';
 
 console.warn(
   'If you are profiling the playground app, please ensure you turn off the debug view. You can disable it by pressing on the settings control in the bottom-left of your screen and toggling the debug view setting.',
@@ -124,10 +125,8 @@ function App(): JSX.Element {
       ? undefined
       : prepopulatedRichText,
     namespace: 'Playground',
-    nodes: [...PlaygroundNodes],
-    onError: (error: Error) => {
-      throw error;
-    },
+    nodes: [...NODES],
+    onError,
     theme: PlaygroundEditorTheme,
   };
 
@@ -148,7 +147,6 @@ function App(): JSX.Element {
             {isDevPlayground ? <DocsPlugin /> : null}
             {isDevPlayground ? <PasteLogPlugin /> : null}
             {isDevPlayground ? <TestRecorderPlugin /> : null}
-
             {measureTypingPerf ? <TypingPerfPlugin /> : null}
           </SharedAutocompleteContext>
         </TableContext>

packages/lexical-playground/src/Editor.tsx

@@ -7,6 +7,10 @@
  */
 
 import {AutoFocusPlugin} from '@lexical/react/LexicalAutoFocusPlugin';
+import {
+  BlockNode,
+  LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL,
+} from '@lexical/react/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL';
 import {CharacterLimitPlugin} from '@lexical/react/LexicalCharacterLimitPlugin';
 import {CheckListPlugin} from '@lexical/react/LexicalCheckListPlugin';
 import {ClearEditorPlugin} from '@lexical/react/LexicalClearEditorPlugin';
@@ -22,13 +26,15 @@ import {RichTextPlugin} from '@lexical/react/LexicalRichTextPlugin';
 import {TabIndentationPlugin} from '@lexical/react/LexicalTabIndentationPlugin';
 import {TablePlugin} from '@lexical/react/LexicalTablePlugin';
 import useLexicalEditable from '@lexical/react/useLexicalEditable';
+import {ElementNode} from 'lexical';
 import * as React from 'react';
-import {useEffect, useState} from 'react';
+import {useCallback, useEffect, useState} from 'react';
 import {CAN_USE_DOM} from 'shared/canUseDOM';
 
 import {createWebsocketProvider} from './collaboration';
 import {useSettings} from './context/SettingsContext';
 import {useSharedHistoryContext} from './context/SharedHistoryContext';
+import {BLOCK_NODES} from './nodes/PlaygroundNodes';
 import ActionsPlugin from './plugins/ActionsPlugin';
 import AutocompletePlugin from './plugins/AutocompletePlugin';
 import AutoEmbedPlugin from './plugins/AutoEmbedPlugin';
@@ -70,6 +76,7 @@ import TwitterPlugin from './plugins/TwitterPlugin';
 import YouTubePlugin from './plugins/YouTubePlugin';
 import ContentEditable from './ui/ContentEditable';
 import Placeholder from './ui/Placeholder';
+import onWarn from './utils/onWarn';
 
 const skipCollaborationInit =
   // @ts-expect-error
@@ -142,7 +149,6 @@ export default function Editor(): JSX.Element {
         <ComponentPickerPlugin />
         <EmojiPickerPlugin />
         <AutoEmbedPlugin />
-
         <MentionsPlugin />
         <EmojisPlugin />
         <HashtagPlugin />
@@ -152,6 +158,25 @@ export default function Editor(): JSX.Element {
         <CommentPlugin
           providerFactory={isCollab ? createWebsocketProvider : undefined}
         />
+        <LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL
+          blockNodes={BLOCK_NODES}
+          $onNormalize={useCallback(
+            (
+              node: BlockNode<JSX.Element>,
+              parent: ElementNode,
+              event?: 'paste',
+            ) => {
+              onWarn(
+                `Found top level node ${node.getKey()} ${
+                  node.constructor.name
+                } inside ${parent.getKey()} ${parent.constructor.name}${
+                  event != null ? ` (${event})` : ''
+                }`,
+              );
+            },
+            [],
+          )}
+        />
         {isRichText ? (
           <>
             {isCollab ? (

packages/lexical-playground/src/nodes/PlaygroundNodes.ts

@@ -14,9 +14,11 @@ import {AutoLinkNode, LinkNode} from '@lexical/link';
 import {ListItemNode, ListNode} from '@lexical/list';
 import {MarkNode} from '@lexical/mark';
 import {OverflowNode} from '@lexical/overflow';
+import {BlockNodeKlass} from '@lexical/react/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL';
 import {HorizontalRuleNode} from '@lexical/react/LexicalHorizontalRuleNode';
 import {HeadingNode, QuoteNode} from '@lexical/rich-text';
 import {TableCellNode, TableNode, TableRowNode} from '@lexical/table';
+import {DecoratorNode, ElementNode} from 'lexical';
 
 import {CollapsibleContainerNode} from '../plugins/CollapsiblePlugin/CollapsibleContainerNode';
 import {CollapsibleContentNode} from '../plugins/CollapsiblePlugin/CollapsibleContentNode';
@@ -38,7 +40,7 @@ import {StickyNode} from './StickyNode';
 import {TweetNode} from './TweetNode';
 import {YouTubeNode} from './YouTubeNode';
 
-const PlaygroundNodes: Array<Klass<LexicalNode>> = [
+export const NODES: Array<Klass<LexicalNode>> = [
   HeadingNode,
   ListNode,
   ListItemNode,
@@ -75,4 +77,17 @@ const PlaygroundNodes: Array<Klass<LexicalNode>> = [
   LayoutItemNode,
 ];
 
-export default PlaygroundNodes;
+export const BLOCK_NODES: Array<BlockNodeKlass<JSX.Element>> = [];
+// The below snippet assumes that for every node, node.isInline() is hardcoded to either true or
+// false, Lexical's recommendation.
+for (const Node of NODES) {
+  if (
+    (Node === ElementNode ||
+      Node.prototype instanceof ElementNode ||
+      Node === DecoratorNode ||
+      Node.prototype instanceof DecoratorNode) &&
+    !Node.prototype.isInline()
+  ) {
+    BLOCK_NODES.push(Node as BlockNodeKlass<JSX.Element>);
+  }
+}

packages/lexical-playground/src/utils/onError.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ */
+
+export default function onError(error: Error | string) {
+  if (typeof error === 'string') {
+    throw new Error(error);
+  }
+  throw error;
+}

packages/lexical-playground/src/utils/onWarn.ts

@@ -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.
+ *
+ */
+
+export default function onWarn(message: string) {
+  console.warn(message);
+}

packages/lexical-react/flow/LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.js.flow

@@ -0,0 +1,31 @@
+/**
+ * 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 {ElementNode, DecoratorNode} from 'lexical';
+import {LexicalEditor} from 'lexical';
+import * as React from 'react';
+
+export type BlockNode<T> = ElementNode | DecoratorNode<T>;
+export type BlockNodeKlass<T> = Class<BlockNode<T>>;
+export type OnNormalizeFn<T> = (
+  node: BlockNode<T>,
+  previousParent: ElementNode,
+  event?: 'paste',
+) => void;
+
+declare export function LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL(props: {
+  blockNodes: Array<Class<React.Node>>;
+  $onNormalize?: OnNormalizeFn<React.Node>;
+}): React$Node;
+
+declare export function registerBlockNodeNormalizerPlugin__EXPERIMENTAL<T>(
+  editor: LexicalEditor,
+  nodes: Array<Class<T>>,
+  $onNormalize?: OnNormalizeFn<React.Node>
+): () => void;

packages/lexical-react/package.json

@@ -131,6 +131,36 @@
         "default": "./LexicalAutoLinkPlugin.js"
       }
     },
+    "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL": {
+      "import": {
+        "types": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.d.ts",
+        "development": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.dev.mjs",
+        "production": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.prod.mjs",
+        "node": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.node.mjs",
+        "default": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.mjs"
+      },
+      "require": {
+        "types": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.d.ts",
+        "development": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.dev.js",
+        "production": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.prod.js",
+        "default": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.js"
+      }
+    },
+    "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.js": {
+      "import": {
+        "types": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.d.ts",
+        "development": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.dev.mjs",
+        "production": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.prod.mjs",
+        "node": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.node.mjs",
+        "default": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.mjs"
+      },
+      "require": {
+        "types": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.d.ts",
+        "development": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.dev.js",
+        "production": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.prod.js",
+        "default": "./LexicalBlockNodeNormalizerPlugin__EXPERIMENTAL.js"
+      }
+    },
     "./LexicalBlockWithAlignableContents": {
       "import": {
         "types": "./LexicalBlockWithAlignableContents.d.ts",