feat(form/inputs): control PortableTextEditor instance via ref (#5793)

* feat(form/inputs): PortableTextInput can now use a editor ref

This will allow us to control the PortableTextEditor from the outside.

* feat(portable-text-editor): support setting editorRef through props

This allows for setting the editorRef from the outside.
If not provided, a internal one will be used as before.

* test(playwright-ct): add test for new editorRef prop for PortableTextInput

Author: skogsmaskin

packages/@sanity/portable-text-editor/src/editor/PortableTextEditor.tsx

@@ -9,7 +9,7 @@ import {
   type PortableTextObject,
   type SpanSchemaType,
 } from '@sanity/types'
-import {Component, type PropsWithChildren} from 'react'
+import {Component, type MutableRefObject, type PropsWithChildren} from 'react'
 import {Subject} from 'rxjs'
 
 import {
@@ -80,6 +80,11 @@ export type PortableTextEditorProps = PropsWithChildren<{
    * Backward compatibility (renamed to patches$).
    */
   incomingPatches$?: PatchObservable
+
+  /**
+   * A ref to the editor instance
+   */
+  editorRef?: MutableRefObject<PortableTextEditor | null>
 }>
 
 /**
@@ -129,6 +134,9 @@ export class PortableTextEditor extends Component<PortableTextEditorProps> {
           : compileType(this.props.schemaType),
       )
     }
+    if (this.props.editorRef !== prevProps.editorRef && this.props.editorRef) {
+      this.props.editorRef.current = this
+    }
   }
 
   public setEditable = (editable: EditableAPI) => {

packages/sanity/playwright-ct/tests/formBuilder/inputs/PortableText/Input.spec.tsx

@@ -1,7 +1,9 @@
 import {expect, test} from '@playwright/experimental-ct-react'
+import {type PortableTextEditor} from '@sanity/portable-text-editor'
+import {type RefObject} from 'react'
 
 import {testHelpers} from '../../../utils/testHelpers'
-import InputStory from './InputStory'
+import {InputStory} from './InputStory'
 
 test.describe('Portable Text Input', () => {
   test.describe('Activation', () => {
@@ -41,4 +43,21 @@ test.describe('Portable Text Input', () => {
       await expect($placeholder).not.toBeVisible()
     })
   })
+
+  test.describe('Editor Ref', () => {
+    test(`Editor can be controlled from outside the Input using the editorRef prop`, async ({
+      mount,
+      page,
+    }) => {
+      let ref: undefined | RefObject<PortableTextEditor | null>
+      const getRef = (editorRef: RefObject<PortableTextEditor | null>) => {
+        ref = editorRef
+      }
+      await mount(<InputStory getRef={getRef} />)
+      const $editor = page.getByTestId('pt-input-with-editor-ref')
+      await expect($editor).toBeVisible()
+      // If the ref has .schemaTypes.block, it means the editorRef was set correctly
+      expect(ref?.current?.schemaTypes.block).toBeDefined()
+    })
+  })
 })

packages/sanity/playwright-ct/tests/formBuilder/inputs/PortableText/InputStory.tsx

@@ -1,33 +1,62 @@
+import {type PortableTextEditor} from '@sanity/portable-text-editor'
 import {defineArrayMember, defineField, defineType} from '@sanity/types'
+import {createRef, type RefObject, useMemo, useState} from 'react'
+import {type InputProps, type PortableTextInputProps} from 'sanity'
 
 import {TestForm} from '../../utils/TestForm'
 import {TestWrapper} from '../../utils/TestWrapper'
 
-const SCHEMA_TYPES = [
-  defineType({
-    type: 'document',
-    name: 'test',
-    title: 'Test',
-    fields: [
-      defineField({
-        type: 'array',
-        name: 'body',
-        of: [
-          defineArrayMember({
-            type: 'block',
+export function InputStory(props: {
+  getRef?: (editorRef: RefObject<PortableTextEditor | null>) => void
+}) {
+  // Use a state as ref here to be make sure we are able to call the ref callback when
+  // the ref is ready
+  const [editorRef, setEditorRef] = useState<RefObject<PortableTextEditor | null>>({current: null})
+  if (props.getRef && editorRef.current) {
+    props.getRef(editorRef)
+  }
+
+  const schemaTypes = useMemo(
+    () => [
+      defineType({
+        type: 'document',
+        name: 'test',
+        title: 'Test',
+        fields: [
+          defineField({
+            type: 'array',
+            name: 'body',
+            of: [
+              defineArrayMember({
+                type: 'block',
+              }),
+            ],
+            components: {
+              input: (inputProps: InputProps) => {
+                const editorProps = {
+                  ...inputProps,
+                  editorRef: createRef(),
+                } as PortableTextInputProps
+                if (editorProps.editorRef) {
+                  setEditorRef(editorProps.editorRef)
+                }
+                return (
+                  <div data-testid="pt-input-with-editor-ref">
+                    {inputProps.renderDefault(editorProps)}
+                  </div>
+                )
+              },
+            },
           }),
         ],
       }),
     ],
-  }),
-]
+    [],
+  )
 
-export function InputStory() {
   return (
-    <TestWrapper schemaTypes={SCHEMA_TYPES}>
+    <TestWrapper schemaTypes={schemaTypes}>
       <TestForm />
     </TestWrapper>
   )
 }
-
-export default InputStory

packages/sanity/src/core/form/inputs/PortableText/PortableTextInput.tsx

@@ -60,6 +60,7 @@ export interface PortableTextMemberItem {
  */
 export function PortableTextInput(props: PortableTextInputProps) {
   const {
+    editorRef: editorRefProp,
     elementProps,
     hotkeys,
     markers = EMPTY_ARRAY,
@@ -78,8 +79,12 @@ export function PortableTextInput(props: PortableTextInputProps) {
   } = props
 
   const {onBlur} = elementProps
+  const defaultEditorRef = useRef<PortableTextEditor | null>(null)
+  const editorRef = editorRefProp || defaultEditorRef
 
-  // Make the PTE focusable from the outside
+  // This handle will allow for natively calling .focus
+  // on the returned component and have the PortableTextEditor focused,
+  // simulating a native input element (like with an string input)
   useImperativeHandle(elementProps.ref, () => ({
     focus() {
       if (editorRef.current) {
@@ -89,7 +94,6 @@ export function PortableTextInput(props: PortableTextInputProps) {
   }))
 
   const {subscribe} = usePatches({path})
-  const editorRef = useRef<PortableTextEditor | null>(null)
   const [ignoreValidationError, setIgnoreValidationError] = useState(false)
   const [invalidValue, setInvalidValue] = useState<InvalidValue | null>(null)
   const [isFullscreen, setIsFullscreen] = useState(false)
@@ -110,17 +114,15 @@ export function PortableTextInput(props: PortableTextInputProps) {
   const innerElementRef = useRef<HTMLDivElement | null>(null)
 
   const handleToggleFullscreen = useCallback(() => {
-    if (editorRef.current) {
-      setIsFullscreen((v) => {
-        const next = !v
-        if (next) {
-          telemetry.log(PortableTextInputExpanded)
-        } else {
-          telemetry.log(PortableTextInputCollapsed)
-        }
-        return next
-      })
-    }
+    setIsFullscreen((v) => {
+      const next = !v
+      if (next) {
+        telemetry.log(PortableTextInputExpanded)
+      } else {
+        telemetry.log(PortableTextInputCollapsed)
+      }
+      return next
+    })
   }, [telemetry])
 
   // Reset invalidValue if new value is coming in from props
@@ -253,7 +255,7 @@ export function PortableTextInput(props: PortableTextInputProps) {
         PortableTextEditor.focus(editorRef.current)
       }
     }
-  }, [isActive])
+  }, [editorRef, isActive])
 
   return (
     <Box ref={innerElementRef}>
@@ -262,10 +264,10 @@ export function PortableTextInput(props: PortableTextInputProps) {
         <PortableTextMarkersProvider markers={markers}>
           <PortableTextMemberItemsProvider memberItems={portableTextMemberItems}>
             <PortableTextEditor
-              ref={editorRef}
               patches$={patches$}
               onChange={handleEditorChange}
               maxBlocks={undefined} // TODO: from schema?
+              ref={editorRef}
               readOnly={isOffline || readOnly}
               schemaType={schemaType}
               value={value}

packages/sanity/src/core/form/types/inputProps.ts

@@ -1,4 +1,9 @@
-import {type HotkeyOptions, type OnCopyFn, type OnPasteFn} from '@sanity/portable-text-editor'
+import {
+  type HotkeyOptions,
+  type OnCopyFn,
+  type OnPasteFn,
+  type PortableTextEditor,
+} from '@sanity/portable-text-editor'
 import {
   type ArraySchemaType,
   type BooleanSchemaType,
@@ -488,6 +493,10 @@ export type PrimitiveInputProps = StringInputProps | BooleanInputProps | NumberI
  * */
 export interface PortableTextInputProps
   extends ArrayOfObjectsInputProps<PortableTextBlock, ArraySchemaType<PortableTextBlock>> {
+  /**
+   * A React Ref that can reference the underlying editor instance
+   */
+  editorRef?: React.MutableRefObject<PortableTextEditor | null>
   /**
    * Assign hotkeys that can be attached to custom editing functions
    */