feat: add normalizeInitialValue prop to Plate

.changeset/thick-years-shop.md

@@ -0,0 +1,5 @@
+---
+"@udecode/plate-core": minor
+---
+
+add `normalizeInitialValue` prop to `Plate`. When `true`, it will normalize the initial value passed to the `editor` once it's created. This is useful when adding normalization rules on already existing content. Default is `false`.

docs/docs/guides/Plate.md

@@ -94,6 +94,12 @@ props if `editor` is defined.
 
 - Initial value of the editor.
 
+### `normalizeInitialValue`
+
+- When `true`, it will normalize the initial value passed to the `editor` once it gets created.
+- This is useful when adding normalization rules on already existing content.
+- Default is `false`.
+
 ### `options`
 
 - Options stored by plugin key.

packages/core/src/components/Plate.spec.tsx

@@ -1,5 +1,8 @@
 import React from 'react';
 import { render } from '@testing-library/react';
+import { isEqual, memoize } from 'lodash';
+import { createEditor, Editor, NodeEntry, Transforms } from 'slate';
+import { PlatePlugin, TEditor } from '../types';
 import { Plate } from './Plate';
 
 describe('Plate', () => {
@@ -9,3 +12,88 @@ describe('Plate', () => {
     expect(1).toBe(1);
   });
 });
+
+describe('Plate', () => {
+  it('should trigger normalize if normalizeInitialValue set', () => {
+    const fn = jest.fn((e: TEditor, [node, path]: NodeEntry) => {
+      if (
+        Editor.isBlock(e, node) &&
+        path?.length &&
+        !isEqual((node as any).path, path)
+      ) {
+        Transforms.setNodes(e, { path } as any, { at: path });
+      }
+    });
+
+    const plugins: PlatePlugin[] = memoize((): PlatePlugin[] => [
+      {
+        withOverrides: (e) => {
+          const { normalizeNode } = e;
+          e.normalizeNode = (n: NodeEntry) => {
+            fn(e, n);
+            normalizeNode(n);
+          };
+          return e;
+        },
+      },
+    ])();
+
+    const editor = createEditor();
+
+    render(
+      <Plate
+        editor={editor as any}
+        plugins={plugins}
+        normalizeInitialValue
+        initialValue={[{ children: [{ text: '' }] }]}
+      />
+    );
+
+    expect(fn).toBeCalled();
+
+    expect(editor.children).toStrictEqual([
+      { children: [{ text: '' }], path: [0] },
+    ]);
+  });
+
+  it('should not trigger normalize if normalizeInitialValue is not set to true', () => {
+    const fn = jest.fn((e: TEditor, [node, path]: NodeEntry) => {
+      if (
+        Editor.isBlock(e, node) &&
+        path?.length &&
+        !isEqual((node as any).path, path)
+      ) {
+        Transforms.setNodes(e, { path } as any, { at: path });
+      }
+    });
+
+    const plugins: PlatePlugin[] = memoize((): PlatePlugin[] => [
+      {
+        withOverrides: (e) => {
+          const { normalizeNode } = e;
+          e.normalizeNode = (n: NodeEntry) => {
+            fn(e, n);
+            normalizeNode(n);
+          };
+          return e;
+        },
+      },
+    ])();
+
+    const editor = createEditor();
+
+    render(
+      <Plate
+        editor={editor as any}
+        plugins={plugins}
+        initialValue={[{ children: [{ text: '' }] }]}
+      />
+    );
+
+    expect(fn).not.toBeCalled();
+
+    expect(editor.children).not.toStrictEqual([
+      { children: [{ text: '' }], path: [0] },
+    ]);
+  });
+});

packages/core/src/hooks/usePlate/usePlate.ts

@@ -18,6 +18,7 @@ export const usePlate = <T extends SPEditor = SPEditor>({
   plugins,
   onChange,
   editableProps,
+  normalizeInitialValue,
 }: UsePlateOptions<T>) => {
   usePlateEffects({
     id,
@@ -27,6 +28,7 @@ export const usePlate = <T extends SPEditor = SPEditor>({
     editor,
     value,
     options,
+    normalizeInitialValue,
   });
 
   return {

packages/core/src/hooks/usePlate/usePlateEffects.ts

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { createEditor } from 'slate';
+import { createEditor, Editor } from 'slate';
 import { createHistoryPlugin } from '../../plugins/createHistoryPlugin';
 import { createReactPlugin } from '../../plugins/createReactPlugin';
 import { usePlateActions } from '../../stores/plate/plate.actions';
@@ -24,6 +24,7 @@ export const usePlateEffects = <T extends SPEditor = SPEditor>({
   components,
   options,
   initialValue,
+  normalizeInitialValue,
   plugins,
 }: UsePlateEffectsOptions<T>) => {
   const {
@@ -114,4 +115,10 @@ export const usePlateEffects = <T extends SPEditor = SPEditor>({
     storePlugins,
     setEditor,
   ]);
+
+  useEffect(() => {
+    if (storeEditor && normalizeInitialValue) {
+      Editor.normalize(storeEditor, { force: true });
+    }
+  }, [storeEditor, normalizeInitialValue]);
 };

packages/core/src/types/UsePlateEffectsOptions.ts

@@ -28,4 +28,11 @@ export interface UsePlateEffectsOptions<T extends SPEditor = SPEditor>
    * @see {@link EditorId}
    */
   components?: Record<string, PlatePluginComponent>;
+
+  /**
+   * When `true`, it will normalize the initial value passed to the `editor` once it gets created.
+   * This is useful when adding normalization rules on already existing content.
+   * @default false
+   */
+  normalizeInitialValue?: boolean;
 }