feat: Add an option to provide serialized initial state (#378)

Author: 11bit

core/README.md

@@ -277,6 +277,46 @@ export default function App() {
 }
 ```
 
+## Use `initialState` to restore state from JSON-serialized representation
+
+CodeMirror allows to serialize editor state to JSON representation with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function for persistency or other needs. This JSON representation can be later used to recreate ReactCodeMirror component with the same internal state.
+
+For example, this is how undo history can be saved in the local storage, so that it remains after the page reloads
+
+```
+import CodeMirror from '@uiw/react-codemirror'
+import { historyField } from '@codemirror/commands'
+
+// When custom fields should be serialized, you can pass them in as an object mapping property names to fields.
+// See [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) documentation for more details
+const stateFields = { history: historyField }
+
+export function EditorWithInitialState() {
+  const serializedState = localStorage.getItem('myEditorState')
+  const value = localStorage.getItem('myValue') || ''
+
+  return (
+    <CodeMirror
+      value={value}
+      initialState={
+        serializedState
+          ? {
+              json: JSON.parse(serializedState || ''),
+              fields: stateFields,
+            }
+          : undefined
+      }
+      onChange={(value, viewUpdate) => {
+        localStorage.setItem('myValue', value)
+
+        const state = viewUpdate.state.toJSON(stateFields)
+        localStorage.setItem('myEditorState', JSON.stringify(state))
+      }}
+    />
+  )
+}
+```
+
 ## Props
 
 <!--rehype:style=background-color: #ffe564; display: inline-block; border-bottom: 0; padding: 3px 12px;-->
@@ -364,6 +404,13 @@ export interface ReactCodeMirrorProps
    * Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root)
    */
   root?: ShadowRoot | Document;
+  /**
+   * Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function
+   */
+  initialState?: {
+    json: any;
+    fields?: Record<'string', StateField<any>>;
+  };
 }
 export interface ReactCodeMirrorRef {
   editor?: HTMLDivElement | null;

core/src/index.tsx

@@ -1,5 +1,5 @@
 import React, { useRef, forwardRef, useImperativeHandle } from 'react';
-import { EditorState, EditorStateConfig, Extension } from '@codemirror/state';
+import { EditorState, EditorStateConfig, Extension, StateField } from '@codemirror/state';
 import { EditorView, ViewUpdate } from '@codemirror/view';
 import { BasicSetupOptions } from '@uiw/codemirror-extensions-basic-setup';
 import { useCodeMirror } from './useCodeMirror';
@@ -69,6 +69,13 @@ export interface ReactCodeMirrorProps
    * Originally from the [config of EditorView](https://codemirror.net/6/docs/ref/#view.EditorView.constructor%5Econfig.root)
    */
   root?: ShadowRoot | Document;
+  /**
+   * Create a state from its JSON representation serialized with [toJSON](https://codemirror.net/docs/ref/#state.EditorState.toJSON) function
+   */
+  initialState?: {
+    json: any;
+    fields?: Record<'string', StateField<any>>;
+  };
 }
 
 export interface ReactCodeMirrorRef {
@@ -101,6 +108,7 @@ const ReactCodeMirror = forwardRef<ReactCodeMirrorRef, ReactCodeMirrorProps>((pr
     editable,
     readOnly,
     root,
+    initialState,
     ...other
   } = props;
   const editor = useRef<HTMLDivElement>(null);
@@ -127,6 +135,7 @@ const ReactCodeMirror = forwardRef<ReactCodeMirrorRef, ReactCodeMirrorProps>((pr
     onCreateEditor,
     onUpdate,
     extensions,
+    initialState,
   });
 
   useImperativeHandle(ref, () => ({ editor: editor.current, state: state, view: view }), [

core/src/useCodeMirror.ts

@@ -34,6 +34,7 @@ export function useCodeMirror(props: UseCodeMirror) {
     indentWithTab: defaultIndentWithTab = true,
     basicSetup: defaultBasicSetup = true,
     root,
+    initialState,
   } = props;
   const [container, setContainer] = useState<HTMLDivElement>();
   const [view, setView] = useState<EditorView>();
@@ -109,11 +110,14 @@ export function useCodeMirror(props: UseCodeMirror) {
 
   useEffect(() => {
     if (container && !state) {
-      const stateCurrent = EditorState.create({
+      const config = {
         doc: value,
         selection,
         extensions: getExtensions,
-      });
+      };
+      const stateCurrent = initialState
+        ? EditorState.fromJSON(initialState.json, config, initialState.fields)
+        : EditorState.create(config);
       setState(stateCurrent);
       if (!view) {
         const viewCurrent = new EditorView({