@portabletext/editor 1.21.5 → 1.22.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,
@@ -602,6 +622,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
@@ -7565,6 +7630,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,
@@ -7984,6 +8064,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 +8599,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,

package/lib/index.d.ts

@@ -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,
@@ -602,6 +622,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
@@ -7565,6 +7630,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,
@@ -7984,6 +8064,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 +8599,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,

package/lib/index.js

@@ -24,7 +24,7 @@ import { createGuards } from "./_chunks-es/selector.is-selection-collapsed.js";
 import { blockOffsetToSpanSelectionPoint } from "./_chunks-es/util.is-empty-text-block.js";
 import { coreBehaviors, isCustomBehaviorEvent, isHotkey } from "./_chunks-es/behavior.core.js";
 import getRandomValues from "get-random-values-esm";
-import { htmlToBlocks, normalizeBlock } from "@portabletext/block-tools";
+import { htmlToBlocks } from "@portabletext/block-tools";
 function createEditorSchema(portableTextType) {
   if (!portableTextType)
     throw new Error("Parameter 'portabletextType' missing (required)");
@@ -86,7 +86,7 @@ function compileSchemaDefinition(definition) {
     // Very naive way to work around `SanitySchema.compile` adding default
     // fields to objects with the name `image`
     name: blockObject.name === "image" ? "tmp-image" : blockObject.name,
-    title: blockObject.title,
+    title: blockObject.name === "image" && blockObject.title === void 0 ? "Image" : blockObject.title,
     fields: []
   })) ?? [], inlineObjects = definition?.inlineObjects?.map((inlineObject) => defineType({
     type: "object",
@@ -5580,6 +5580,25 @@ function getActiveDecorators({
     ...Editor.marks(slateEditorInstance) ?? {}
   }.marks ?? []).filter((mark) => decorators.includes(mark));
 }
+function createEditorSnapshot({
+  editor,
+  keyGenerator,
+  schema
+}) {
+  const value = fromSlateValue(editor.children, schema.block.name, KEY_TO_VALUE_ELEMENT.get(editor)), selection = toPortableTextRange(value, editor.selection, schema);
+  return {
+    context: {
+      activeDecorators: getActiveDecorators({
+        schema,
+        slateEditorInstance: editor
+      }),
+      keyGenerator,
+      schema,
+      selection,
+      value
+    }
+  };
+}
 const editorMachine = setup({
   types: {
     context: {},
@@ -5680,26 +5699,21 @@ const editorMachine = setup({
         }), event.editor.onChange();
         return;
       }
-      const value = fromSlateValue(event.editor.children, context.schema.block.name, KEY_TO_VALUE_ELEMENT.get(event.editor)), selection = toPortableTextRange(value, event.editor.selection, context.schema), editorContext = {
-        activeDecorators: getActiveDecorators({
-          schema: context.schema,
-          slateEditorInstance: event.editor
-        }),
+      const editorSnapshot = createEditorSnapshot({
+        editor: event.editor,
         keyGenerator: context.keyGenerator,
-        schema: context.schema,
-        selection,
-        value
-      };
+        schema: context.schema
+      });
       let behaviorOverwritten = !1;
       for (const eventBehavior of eventBehaviors) {
         const shouldRun = eventBehavior.guard === void 0 || eventBehavior.guard({
-          context: editorContext,
+          context: editorSnapshot.context,
           event: event.behaviorEvent
         });
         if (!shouldRun)
           continue;
         const actionIntendSets = eventBehavior.actions.map((actionSet) => actionSet({
-          context: editorContext,
+          context: editorSnapshot.context,
           event: event.behaviorEvent
         }, shouldRun));
         for (const actionIntends of actionIntendSets)
@@ -6618,18 +6632,17 @@ function createWithInsertData(editorActor, schemaTypes) {
         let portableText, fragment, insertedType;
         if (html) {
           if (portableText = htmlToBlocks(html, schemaTypes.portableText, {
-            unstable_whitespaceOnPasteMode: whitespaceOnPasteMode
-          }).map((block) => normalizeBlock(block, {
-            blockTypeName
-          })), fragment = toSlateValue(portableText, {
+            unstable_whitespaceOnPasteMode: whitespaceOnPasteMode,
+            keyGenerator: editorActor.getSnapshot().context.keyGenerator
+          }), fragment = toSlateValue(portableText, {
             schemaTypes
           }), insertedType = "HTML", portableText.length === 0)
             return !1;
         } else {
           const textToHtml = `<html><body>${escapeHtml(text).split(/\n{2,}/).map((line) => line ? `<p>${line.replace(/(?:\r\n|\r|\n)/g, "<br/>")}</p>` : "<p></p>").join("")}</body></html>`;
-          portableText = htmlToBlocks(textToHtml, schemaTypes.portableText).map((block) => normalizeBlock(block, {
-            blockTypeName
-          })), fragment = toSlateValue(portableText, {
+          portableText = htmlToBlocks(textToHtml, schemaTypes.portableText, {
+            keyGenerator: editorActor.getSnapshot().context.keyGenerator
+          }), fragment = toSlateValue(portableText, {
             schemaTypes
           }), insertedType = "text";
         }