@portabletext/editor 0.0.0

package/src/editor/components/Synchronizer.tsx

@@ -0,0 +1,190 @@
+import {type PortableTextBlock} from '@sanity/types'
+import {throttle} from 'lodash'
+import {
+  type PropsWithChildren,
+  startTransition,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import {Editor} from 'slate'
+import {useSlate} from 'slate-react'
+
+import {type EditorChange, type EditorChanges, type EditorSelection} from '../../types/editor'
+import {type Patch} from '../../types/patch'
+import {debugWithName} from '../../utils/debug'
+import {IS_PROCESSING_LOCAL_CHANGES} from '../../utils/weakMaps'
+import {PortableTextEditorContext} from '../hooks/usePortableTextEditor'
+import {PortableTextEditorKeyGeneratorContext} from '../hooks/usePortableTextEditorKeyGenerator'
+import {PortableTextEditorSelectionContext} from '../hooks/usePortableTextEditorSelection'
+import {PortableTextEditorValueContext} from '../hooks/usePortableTextEditorValue'
+import {PortableTextEditorReadOnlyContext} from '../hooks/usePortableTextReadOnly'
+import {useSyncValue} from '../hooks/useSyncValue'
+import {PortableTextEditor} from '../PortableTextEditor'
+
+const debug = debugWithName('component:PortableTextEditor:Synchronizer')
+const debugVerbose = debug.enabled && false
+
+// The editor will commit changes in a throttled fashion in order
+// not to overload the network and degrade performance while typing.
+const FLUSH_PATCHES_THROTTLED_MS = process.env.NODE_ENV === 'test' ? 500 : 1000
+
+/**
+ * @internal
+ */
+export interface SynchronizerProps extends PropsWithChildren {
+  change$: EditorChanges
+  portableTextEditor: PortableTextEditor
+  keyGenerator: () => string
+  onChange: (change: EditorChange) => void
+  readOnly: boolean
+  value: PortableTextBlock[] | undefined
+}
+
+/**
+ * Synchronizes the server value with the editor, and provides various contexts for the editor state.
+ * @internal
+ */
+export function Synchronizer(props: SynchronizerProps) {
+  const {change$, portableTextEditor, onChange, keyGenerator, readOnly, value} = props
+  const [selection, setSelection] = useState<EditorSelection>(null)
+  const pendingPatches = useRef<Patch[]>([])
+
+  const syncValue = useSyncValue({
+    keyGenerator,
+    onChange,
+    portableTextEditor,
+    readOnly,
+  })
+
+  const slateEditor = useSlate()
+
+  useEffect(() => {
+    IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, false)
+  }, [slateEditor])
+
+  const onFlushPendingPatches = useCallback(() => {
+    if (pendingPatches.current.length > 0) {
+      debug('Flushing pending patches')
+      if (debugVerbose) {
+        debug(`Patches:\n${JSON.stringify(pendingPatches.current, null, 2)}`)
+      }
+      const snapshot = PortableTextEditor.getValue(portableTextEditor)
+      change$.next({type: 'mutation', patches: pendingPatches.current, snapshot})
+      pendingPatches.current = []
+    }
+    IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, false)
+  }, [slateEditor, portableTextEditor, change$])
+
+  const onFlushPendingPatchesThrottled = useMemo(() => {
+    return throttle(
+      () => {
+        // If the editor is normalizing (each operation) it means that it's not in the middle of a bigger transform,
+        // and we can flush these changes immediately.
+        if (Editor.isNormalizing(slateEditor)) {
+          onFlushPendingPatches()
+          return
+        }
+        // If it's in the middle of something, try again.
+        onFlushPendingPatchesThrottled()
+      },
+      FLUSH_PATCHES_THROTTLED_MS,
+      {
+        leading: false,
+        trailing: true,
+      },
+    )
+  }, [onFlushPendingPatches, slateEditor])
+
+  // Flush pending patches immediately on unmount
+  useEffect(() => {
+    return () => {
+      onFlushPendingPatches()
+    }
+  }, [onFlushPendingPatches])
+
+  // Subscribe to, and handle changes from the editor
+  useEffect(() => {
+    debug('Subscribing to editor changes$')
+    const sub = change$.subscribe((next: EditorChange): void => {
+      switch (next.type) {
+        case 'patch':
+          IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, true)
+          pendingPatches.current.push(next.patch)
+          onFlushPendingPatchesThrottled()
+          onChange(next)
+          break
+        case 'selection':
+          // Set the selection state in a transition, we don't need the state immediately.
+          startTransition(() => {
+            if (debugVerbose) debug('Setting selection')
+            setSelection(next.selection)
+          })
+          onChange(next) // Keep this out of the startTransition!
+          break
+        default:
+          onChange(next)
+      }
+    })
+    return () => {
+      debug('Unsubscribing to changes$')
+      sub.unsubscribe()
+    }
+  }, [change$, onChange, onFlushPendingPatchesThrottled, slateEditor])
+
+  // Sync the value when going online
+  const handleOnline = useCallback(() => {
+    debug('Editor is online, syncing from props.value')
+    change$.next({type: 'connection', value: 'online'})
+    syncValue(value)
+  }, [change$, syncValue, value])
+
+  const handleOffline = useCallback(() => {
+    debug('Editor is offline')
+    change$.next({type: 'connection', value: 'offline'})
+  }, [change$])
+
+  // Notify about window online and offline status changes
+  useEffect(() => {
+    if (portableTextEditor.props.patches$) {
+      window.addEventListener('online', handleOnline)
+      window.addEventListener('offline', handleOffline)
+    }
+    return () => {
+      if (portableTextEditor.props.patches$) {
+        window.removeEventListener('online', handleOnline)
+        window.removeEventListener('offline', handleOffline)
+      }
+    }
+  })
+
+  // This hook must be set up after setting up the subscription above, or it will not pick up validation errors from the useSyncValue hook.
+  // This will cause the editor to not be able to signal a validation error and offer invalid value resolution of the initial value.
+  const isInitialValueFromProps = useRef(true)
+  useEffect(() => {
+    debug('Value from props changed, syncing new value')
+    syncValue(value)
+    // Signal that we have our first value, and are ready to roll.
+    if (isInitialValueFromProps.current) {
+      change$.next({type: 'loading', isLoading: false})
+      change$.next({type: 'ready'})
+      isInitialValueFromProps.current = false
+    }
+  }, [change$, syncValue, value])
+
+  return (
+    <PortableTextEditorKeyGeneratorContext.Provider value={keyGenerator}>
+      <PortableTextEditorContext.Provider value={portableTextEditor}>
+        <PortableTextEditorValueContext.Provider value={value}>
+          <PortableTextEditorReadOnlyContext.Provider value={readOnly}>
+            <PortableTextEditorSelectionContext.Provider value={selection}>
+              {props.children}
+            </PortableTextEditorSelectionContext.Provider>
+          </PortableTextEditorReadOnlyContext.Provider>
+        </PortableTextEditorValueContext.Provider>
+      </PortableTextEditorContext.Provider>
+    </PortableTextEditorKeyGeneratorContext.Provider>
+  )
+}

package/src/editor/hooks/usePortableTextEditor.ts

@@ -0,0 +1,23 @@
+import {createContext, useContext} from 'react'
+
+import {type PortableTextEditor} from '../PortableTextEditor'
+
+/**
+ * A React context for sharing the editor object.
+ */
+export const PortableTextEditorContext = createContext<PortableTextEditor | null>(null)
+
+/**
+ * Get the current editor object from the React context.
+ */
+export const usePortableTextEditor = (): PortableTextEditor => {
+  const editor = useContext(PortableTextEditorContext)
+
+  if (!editor) {
+    throw new Error(
+      `The \`usePortableTextEditor\` hook must be used inside the <PortableTextEditor> component's context.`,
+    )
+  }
+
+  return editor
+}

package/src/editor/hooks/usePortableTextEditorKeyGenerator.ts

@@ -0,0 +1,24 @@
+import {randomKey} from '@sanity/util/content'
+import {createContext, useContext} from 'react'
+
+export const defaultKeyGenerator = (): string => randomKey(12)
+
+/**
+ * A React context for sharing the editor's keyGenerator.
+ */
+export const PortableTextEditorKeyGeneratorContext =
+  createContext<() => string>(defaultKeyGenerator)
+
+/**
+ * Get the current editor selection from the React context.
+ */
+export const usePortableTextEditorKeyGenerator = (): (() => string) => {
+  const keyGenerator = useContext(PortableTextEditorKeyGeneratorContext)
+
+  if (keyGenerator === undefined) {
+    throw new Error(
+      `The \`usePortableTextEditorKeyGenerator\` hook must be used inside the <PortableTextEditor> component's context.`,
+    )
+  }
+  return keyGenerator
+}

package/src/editor/hooks/usePortableTextEditorSelection.ts

@@ -0,0 +1,22 @@
+import {createContext, useContext} from 'react'
+
+import {type EditorSelection} from '../../types/editor'
+
+/**
+ * A React context for sharing the editor selection.
+ */
+export const PortableTextEditorSelectionContext = createContext<EditorSelection | null>(null)
+
+/**
+ * Get the current editor selection from the React context.
+ */
+export const usePortableTextEditorSelection = (): EditorSelection => {
+  const selection = useContext(PortableTextEditorSelectionContext)
+
+  if (selection === undefined) {
+    throw new Error(
+      `The \`usePortableTextEditorSelection\` hook must be used inside the <PortableTextEditor> component's context.`,
+    )
+  }
+  return selection
+}

package/src/editor/hooks/usePortableTextEditorValue.ts

@@ -0,0 +1,16 @@
+import {type PortableTextBlock} from '@sanity/types'
+import {createContext, useContext} from 'react'
+
+/**
+ * A React context for sharing the editor value.
+ */
+export const PortableTextEditorValueContext = createContext<PortableTextBlock[] | undefined>(
+  undefined,
+)
+
+/**
+ * Get the current editor value from the React context.
+ */
+export const usePortableTextEditorValue = () => {
+  return useContext(PortableTextEditorValueContext)
+}

package/src/editor/hooks/usePortableTextReadOnly.ts

@@ -0,0 +1,20 @@
+import {createContext, useContext} from 'react'
+
+/**
+ * A React context for sharing the editor's readOnly status.
+ */
+export const PortableTextEditorReadOnlyContext = createContext<boolean>(false)
+
+/**
+ * Get the current editor selection from the React context.
+ */
+export const usePortableTextEditorReadOnlyStatus = (): boolean => {
+  const readOnly = useContext(PortableTextEditorReadOnlyContext)
+
+  if (readOnly === undefined) {
+    throw new Error(
+      `The \`usePortableTextEditorReadOnly\` hook must be used inside the <PortableTextEditor> component's context.`,
+    )
+  }
+  return readOnly
+}

package/src/editor/hooks/useSyncValue.test.tsx

@@ -0,0 +1,125 @@
+import {describe, expect, it, jest} from '@jest/globals'
+import {render, waitFor} from '@testing-library/react'
+import {createRef, type RefObject} from 'react'
+
+import {PortableTextEditorTester, schemaType} from '../__tests__/PortableTextEditorTester'
+import {PortableTextEditor} from '../PortableTextEditor'
+
+const initialValue = [
+  {
+    _key: '77071c3af231',
+    _type: 'myTestBlockType',
+    children: [
+      {
+        _key: 'c001f0e92c1f0',
+        _type: 'span',
+        marks: [],
+        text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ',
+      },
+    ],
+    markDefs: [],
+    style: 'normal',
+  },
+]
+
+describe('useSyncValue', () => {
+  it('updates span text', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const onChange = jest.fn()
+    const syncedValue = [
+      {
+        _key: '77071c3af231',
+        _type: 'myTestBlockType',
+        children: [
+          {
+            _key: 'c001f0e92c1f0',
+            _type: 'span',
+            marks: [],
+            text: 'Lorem my ipsum!',
+          },
+        ],
+        markDefs: [],
+        style: 'normal',
+      },
+    ]
+    const {rerender} = render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    rerender(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        schemaType={schemaType}
+        value={syncedValue}
+      />,
+    )
+    await waitFor(() => {
+      if (editorRef.current) {
+        expect(PortableTextEditor.getValue(editorRef.current)).toEqual(syncedValue)
+      }
+    })
+  })
+  it('replaces span nodes with different keys inside the same children array', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const onChange = jest.fn()
+    const syncedValue = [
+      {
+        _key: '77071c3af231',
+        _type: 'myTestBlockType',
+        children: [
+          {
+            _key: 'c001f0e92c1f0__NEW_KEY_YA!',
+            _type: 'span',
+            marks: [],
+            text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ',
+          },
+        ],
+        markDefs: [],
+        style: 'normal',
+      },
+    ]
+    const {rerender} = render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    rerender(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        schemaType={schemaType}
+        value={syncedValue}
+      />,
+    )
+    await waitFor(() => {
+      if (editorRef.current) {
+        expect(PortableTextEditor.getValue(editorRef.current)).toMatchInlineSnapshot(`
+          Array [
+            Object {
+              "_key": "77071c3af231",
+              "_type": "myTestBlockType",
+              "children": Array [
+                Object {
+                  "_key": "c001f0e92c1f0__NEW_KEY_YA!",
+                  "_type": "span",
+                  "marks": Array [],
+                  "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. ",
+                },
+              ],
+              "markDefs": Array [],
+              "style": "normal",
+            },
+          ]
+        `)
+      }
+    })
+  })
+})