@portabletext/editor 1.21.6 → 1.23.0

package/lib/index.d.cts

@@ -377,6 +377,26 @@ declare type CustomBehaviorEvent<
 
 /**
  * @public
+ * A helper wrapper that adds editor support, such as autocomplete and type checking, for a schema definition.
+ * @example
+ * ```ts
+ * import { defineSchema } from '@portabletext/editor'
+ *
+ * const schemaDefinition = defineSchema({
+ *  decorators: [{name: 'strong'}, {name: 'em'}, {name: 'underline'}],
+ *  annotations: [{name: 'link'}],
+ *  styles: [
+ *    {name: 'normal'},
+ *    {name: 'h1'},
+ *    {name: 'h2'},
+ *    {name: 'h3'},
+ *    {name: 'blockquote'},
+ *  ],
+ *  lists: [],
+ *  inlineObjects: [],
+ *  blockObjects: [],
+ * }
+ * ```
  */
 export declare function defineSchema<
   const TSchemaDefinition extends SchemaDefinition,
@@ -595,6 +615,7 @@ export declare type EditorEvent =
       | 'style.toggle'
       | 'patches'
       | 'update behaviors'
+      | 'update key generator'
       | 'update readOnly'
       | 'update value'
     >
@@ -602,6 +623,51 @@ export declare type EditorEvent =
 
 /**
  * @public
+ * Listen for events emitted by the editor. Must be used inside `EditorProvider`. Events available include:
+ *  - 'blurred'
+ *  - 'done loading'
+ *  - 'editable'
+ *  - 'error'
+ *  - 'focused'
+ *  - 'invalid value'
+ *  - 'loading'
+ *  - 'mutation'
+ *  - 'patch'
+ *  - 'read only'
+ *  - 'ready'
+ *  - 'selection'
+ *  - 'value changed'
+ *
+ * @example
+ * Listen and log events.
+ * ```tsx
+ * import {EditorEventListener, EditorProvider} from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  return (
+ *  <EditorProvider>
+ *   <EditorEventListener
+ *    on={(event) => {
+ *     console.log(event)
+ *    }
+ *   } />
+ *   { ... }
+ * </EditorProvider>
+ *  )
+ * }
+ * ```
+ * @example
+ * Handle events when there is a mutation.
+ * ```tsx
+ * <EditorEventListener
+ *  on={(event) => {
+ *    if (event.type === 'mutation') {
+ *      console.log('Value changed:', event.snapshot)
+ *    }
+ *  }}
+ * />
+ * ```
+ * @group Components
  */
 export declare function EditorEventListener(props: {
   on: (event: EditorEmittedEvent) => void
@@ -722,6 +788,10 @@ export declare const editorMachine: StateMachine<
       type: 'update behaviors'
       behaviors: Array<Behavior>
     }
+  | {
+      type: 'update key generator'
+      keyGenerator: () => string
+    }
   | {
       type: 'update value'
       value: Array<PortableTextBlock> | undefined
@@ -1115,6 +1185,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -1277,6 +1351,10 @@ export declare const editorMachine: StateMachine<
             type: 'update behaviors'
             behaviors: Array<Behavior>
           }
+        | {
+            type: 'update key generator'
+            keyGenerator: () => string
+          }
         | {
             type: 'update value'
             value: Array<PortableTextBlock> | undefined
@@ -1467,6 +1545,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -1754,6 +1836,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -2042,6 +2128,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -2331,6 +2421,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -2619,6 +2713,10 @@ export declare const editorMachine: StateMachine<
                 type: 'update behaviors'
                 behaviors: Array<Behavior>
               }
+            | {
+                type: 'update key generator'
+                keyGenerator: () => string
+              }
             | {
                 type: 'update value'
                 value: Array<PortableTextBlock> | undefined
@@ -2796,6 +2894,10 @@ export declare const editorMachine: StateMachine<
                 type: 'update behaviors'
                 behaviors: Array<Behavior>
               }
+            | {
+                type: 'update key generator'
+                keyGenerator: () => string
+              }
             | {
                 type: 'update value'
                 value: Array<PortableTextBlock> | undefined
@@ -3084,6 +3186,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -3371,6 +3477,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -3657,6 +3767,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -3941,6 +4055,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -4227,6 +4345,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -4400,6 +4522,189 @@ export declare const editorMachine: StateMachine<
       readonly 'update behaviors': {
         readonly actions: 'assign behaviors'
       }
+      readonly 'update key generator': {
+        readonly actions: ActionFunction<
+          {
+            behaviors: Set<Behavior>
+            keyGenerator: () => string
+            pendingEvents: Array<PatchEvent | MutationEvent>
+            schema: EditorSchema
+            initialReadOnly: boolean
+            maxBlocks: number | undefined
+            selection: EditorSelection
+            value: Array<PortableTextBlock> | undefined
+          },
+          {
+            type: 'update key generator'
+            keyGenerator: () => string
+          },
+          | {
+              type: 'annotation.add'
+              annotation: {
+                name: string
+                value: {
+                  [prop: string]: unknown
+                }
+              }
+            }
+          | {
+              type: 'annotation.remove'
+              annotation: {
+                name: string
+              }
+            }
+          | {
+              type: 'blur'
+            }
+          | {
+              type: 'decorator.toggle'
+              decorator: string
+            }
+          | {
+              type: 'focus'
+            }
+          | {
+              type: 'insert.block object'
+              placement: 'auto' | 'after' | 'before'
+              blockObject: {
+                name: string
+                value?: {
+                  [prop: string]: unknown
+                }
+              }
+            }
+          | {
+              type: 'insert.inline object'
+              inlineObject: {
+                name: string
+                value?: {
+                  [prop: string]: unknown
+                }
+              }
+            }
+          | {
+              type: 'list item.toggle'
+              listItem: string
+            }
+          | {
+              type: 'style.toggle'
+              style: string
+            }
+          | PatchEvent
+          | MutationEvent
+          | {
+              type: 'normalizing'
+            }
+          | {
+              type: 'done normalizing'
+            }
+          | {
+              type: 'done syncing initial value'
+            }
+          | {
+              type: 'behavior event'
+              behaviorEvent: SyntheticBehaviorEvent | NativeBehaviorEvent
+              editor: PortableTextSlateEditor
+              defaultActionCallback?: () => void
+              nativeEvent?: {
+                preventDefault: () => void
+              }
+            }
+          | {
+              type: 'custom behavior event'
+              behaviorEvent: CustomBehaviorEvent
+              editor: PortableTextSlateEditor
+              nativeEvent?: {
+                preventDefault: () => void
+              }
+            }
+          | CustomBehaviorEvent
+          | {
+              type: 'add behavior'
+              behavior: Behavior
+            }
+          | {
+              type: 'remove behavior'
+              behavior: Behavior
+            }
+          | {
+              type: 'update readOnly'
+              readOnly: boolean
+            }
+          | {
+              type: 'update schema'
+              schema: EditorSchema
+            }
+          | {
+              type: 'update behaviors'
+              behaviors: Array<Behavior>
+            }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
+          | {
+              type: 'update value'
+              value: Array<PortableTextBlock> | undefined
+            }
+          | {
+              type: 'update maxBlocks'
+              maxBlocks: number | undefined
+            }
+          | PatchesEvent
+          | {
+              type: 'unset'
+              previousValue: Array<PortableTextBlock>
+            }
+          | {
+              type: 'value changed'
+              value: Array<PortableTextBlock> | undefined
+            }
+          | {
+              type: 'invalid value'
+              resolution: InvalidValueResolution | null
+              value: Array<PortableTextBlock> | undefined
+            }
+          | {
+              type: 'error'
+              name: string
+              description: string
+              data: unknown
+            }
+          | {
+              type: 'select'
+              selection: EditorSelection
+            }
+          | {
+              type: 'selection'
+              selection: EditorSelection
+            }
+          | {
+              type: 'blurred'
+              event: FocusEvent_2<HTMLDivElement, Element>
+            }
+          | {
+              type: 'focused'
+              event: FocusEvent_2<HTMLDivElement, Element>
+            }
+          | {
+              type: 'loading'
+            }
+          | {
+              type: 'done loading'
+            }
+          | {
+              type: 'custom.*'
+              event: CustomBehaviorEvent
+            },
+          undefined,
+          never,
+          never,
+          never,
+          never,
+          never
+        >
+      }
       readonly 'update schema': {
         readonly actions: 'assign schema'
       }
@@ -4520,6 +4825,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -4699,6 +5008,10 @@ export declare const editorMachine: StateMachine<
               type: 'update behaviors'
               behaviors: Array<Behavior>
             }
+          | {
+              type: 'update key generator'
+              keyGenerator: () => string
+            }
           | {
               type: 'update value'
               value: Array<PortableTextBlock> | undefined
@@ -4987,6 +5300,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -5275,6 +5592,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -5565,6 +5886,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -5854,6 +6179,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -6142,6 +6471,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -6446,6 +6779,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -6735,6 +7072,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -7024,6 +7365,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -7313,6 +7658,10 @@ export declare const editorMachine: StateMachine<
                       type: 'update behaviors'
                       behaviors: Array<Behavior>
                     }
+                  | {
+                      type: 'update key generator'
+                      keyGenerator: () => string
+                    }
                   | {
                       type: 'update value'
                       value: Array<PortableTextBlock> | undefined
@@ -7565,6 +7914,21 @@ export declare type EditorNode = Node_2 & {
 
 /**
  * @public
+ * The EditorProvider component is used to set up the editor context and configure the Portable Text Editor.
+ * @example
+ * ```tsx
+ * import {EditorProvider} from '@portabletext/editor'
+ *
+ * function App() {
+ *  return (
+ *    <EditorProvider initialConfig={{ ... }} >
+ *      ...
+ *    </EditorProvider>
+ *  )
+ * }
+ *
+ * ```
+ * @group Components
  */
 export declare function EditorProvider(
   props: EditorProviderProps,
@@ -7779,6 +8143,10 @@ export declare type InternalEditorEvent =
       type: 'update behaviors'
       behaviors: Array<Behavior>
     }
+  | {
+      type: 'update key generator'
+      keyGenerator: () => string
+    }
   | {
       type: 'update value'
       value: Array<PortableTextBlock> | undefined
@@ -7984,6 +8352,23 @@ export {PortableTextChild}
 
 /**
  * @public
+ *
+ *
+ * The core component that renders the editor. Must be placed within the {@link EventProvider} component.
+ *
+ * @example
+ * ```tsx
+ * import { PortableTextEditable, EditorProvider } from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  return (
+ *   <EditorProvider>
+ *    <PortableTextEditable />
+ *  </EditorProvider>
+ *  )
+ * }
+ * ```
+ * @group Components
  */
 export declare const PortableTextEditable: ForwardRefExoticComponent<
   Omit<PortableTextEditableProps, 'ref'> &
@@ -8502,11 +8887,44 @@ export declare type UnsetChange = {
 
 /**
  * @public
+ * Get the current editor context from the `EditorProvider`.
+ * Must be used inside the `EditorProvider` component.
+ * @returns The current editor object.
+ * @example
+ * ```tsx
+ * import { useEditor } from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  const editor = useEditor()
+ * }
+ * ```
+ * @group Hooks
  */
 export declare function useEditor(): Editor
 
 /**
  * @public
+ * Hook to select a value from the editor state.
+ * @example
+ * Pass a selector as the second argument
+ * ```tsx
+ * import { useEditorSelector } from '@portabletext/editor'
+ *
+ * function MyComponent(editor) {
+ *  const value = useEditorSelector(editor, selector)
+ * }
+ * ```
+ * @example
+ * Pass an inline selector as the second argument.
+ * In this case, use the editor context to obtain the schema.
+ * ```tsx
+ * import { useEditorSelector } from '@portabletext/editor'
+ *
+ * function MyComponent(editor) {
+ *  const schema = useEditorSelector(editor, (snapshot) => snapshot.context.schema)
+ * }
+ * ```
+ * @group Hooks
  */
 export declare function useEditorSelector<TSelected>(
   editor: Editor,