@portabletext/editor 1.16.2 → 1.16.4

package/README.md

@@ -9,20 +9,8 @@
 
 > The official editor for editing [Portable Text](https://github.com/portabletext/portabletext) – the JSON based rich text specification for modern content editing platforms.
 
-> [!NOTE]
-> We are currently working hard on the general release of this component. Better docs and refined APIs are coming.
-
-## End-User Experience
-
-In order to provide a robust and consistent end-user experience, the editor is backed by an elaborate E2E test suite generated from a [human-readable Gherkin spec](/packages/editor/gherkin-spec/).
-
 ## Build Your Own Portable Text Editor
 
-> [!WARNING]
-> The `@portabletext/editor` is currently on the path to deprecate legacy APIs and introduce new ones. The end goals are to make the editor easier to use outside of `Sanity` (and without `@sanity/*` libraries) as well as providing a brand new API to configure the behavior of the editor.
->
-> This means that the `defineSchema` and `EditorProvider` APIs showcased here are still experimental APIs tagged with `@alpha` and cannot be considered stable yet. At the same time, the examples below showcase usages of legacy static methods on the `PortableTextEditor` (for example, `PortableTextEditor.isMarkActive(...)` and `PortableTextEditor.toggleMark(...)`) that will soon be discouraged and deprecrated.
-
 Check [/examples/basic/src/App.tsx](/examples/basic/src/App.tsx) for a basic example of how to set up the edior. Most of the source code from this example app can also be found in the instructions below.
 
 ### Define the Schema
@@ -219,153 +207,177 @@ function isStockTicker(
 
 ### Render the Toolbar
 
-Your toolbar needs to be rendered within `EditorProvider` because it requires a reference to the `editorInstance` that it produces. To toggle marks and styles and to insert objects, you'll have to use this `editorInstance` together with static methods on the `PortableTextEditor` class.
+Your toolbar needs to be rendered within `EditorProvider` because it requires a reference to the `editor` that it produces. To toggle marks and styles and to insert objects, you'll have to use the `.send` method on this `editor` instance.
 
 ```tsx
 function Toolbar() {
   // Obtain the editor instance
-  const editorInstance = usePortableTextEditor()
-  // Rerender the toolbar whenever the selection changes
-  usePortableTextEditorSelection()
+  const editor = useEditor()
 
-  const decoratorButtons = schemaDefinition.decorators.map((decorator) => {
-    return (
-      <button
-        key={decorator.name}
-        style={{
-          textDecoration: PortableTextEditor.isMarkActive(
-            editorInstance,
-            decorator.name,
-          )
-            ? 'underline'
-            : 'unset',
-        }}
-        onClick={() => {
-          // Toggle the decorator by name
-          PortableTextEditor.toggleMark(editorInstance, decorator.name)
-          // Pressing this button steals focus so let's focus the editor again
-          PortableTextEditor.focus(editorInstance)
-        }}
-      >
-        {decorator.name}
-      </button>
-    )
-  })
+  const decoratorButtons = schemaDefinition.decorators.map((decorator) => (
+    <DecoratorButton key={decorator.name} decorator={decorator.name} />
+  ))
+
+  const annotationButtons = schemaDefinition.annotations.map((annotation) => (
+    <AnnotationButton key={annotation.name} annotation={annotation} />
+  ))
+
+  const styleButtons = schemaDefinition.styles.map((style) => (
+    <StyleButton key={style.name} style={style.name} />
+  ))
 
-  const linkButton = (
+  const listButtons = schemaDefinition.lists.map((list) => (
+    <ListButton key={list.name} list={list.name} />
+  ))
+
+  const imageButton = (
     <button
-      style={{
-        textDecoration: PortableTextEditor.isAnnotationActive(
-          editorInstance,
-          schemaDefinition.annotations[0].name,
-        )
-          ? 'underline'
-          : 'unset',
-      }}
       onClick={() => {
-        if (
-          PortableTextEditor.isAnnotationActive(
-            editorInstance,
-            schemaDefinition.annotations[0].name,
-          )
-        ) {
-          PortableTextEditor.removeAnnotation(
-            editorInstance,
-            schemaDefinition.annotations[0],
-          )
-        } else {
-          PortableTextEditor.addAnnotation(
-            editorInstance,
-            schemaDefinition.annotations[0],
-            {href: 'https://example.com'},
-          )
-        }
-        PortableTextEditor.focus(editorInstance)
+        editor.send({
+          type: 'insert.block object',
+          blockObject: {
+            name: 'image',
+            value: {src: 'https://example.com/image.jpg'},
+          },
+          placement: 'auto',
+        })
+        editor.send({type: 'focus'})
       }}
     >
-      link
+      {schemaDefinition.blockObjects[0].name}
     </button>
   )
 
-  const styleButtons = schemaDefinition.styles.map((style) => (
+  const stockTickerButton = (
     <button
-      key={style.name}
-      style={{
-        textDecoration: PortableTextEditor.hasBlockStyle(
-          editorInstance,
-          style.name,
-        )
-          ? 'underline'
-          : 'unset',
-      }}
       onClick={() => {
-        PortableTextEditor.toggleBlockStyle(editorInstance, style.name)
-        PortableTextEditor.focus(editorInstance)
+        editor.send({
+          type: 'insert.inline object',
+          inlineObject: {
+            name: 'stock-ticker',
+            value: {symbol: 'AAPL'},
+          },
+        })
+        editor.send({type: 'focus'})
       }}
     >
-      {style.name}
+      {schemaDefinition.inlineObjects[0].name}
     </button>
-  ))
+  )
 
-  const listButtons = schemaDefinition.lists.map((list) => (
+  return (
+    <>
+      <div>{decoratorButtons}</div>
+      <div>{annotationButtons}</div>
+      <div>{styleButtons}</div>
+      <div>{listButtons}</div>
+      <div>{imageButton}</div>
+      <div>{stockTickerButton}</div>
+    </>
+  )
+}
+
+function DecoratorButton(props: {decorator: string}) {
+  // Obtain the editor instance
+  const editor = useEditor()
+  // Check if the decorator is active using a selector
+  const active = useEditorSelector(
+    editor,
+    selectors.isActiveDecorator(props.decorator),
+  )
+
+  return (
     <button
-      key={list.name}
       style={{
-        textDecoration: PortableTextEditor.hasListStyle(
-          editorInstance,
-          list.name,
-        )
-          ? 'underline'
-          : 'unset',
+        textDecoration: active ? 'underline' : 'unset',
       }}
       onClick={() => {
-        PortableTextEditor.toggleList(editorInstance, list.name)
-        PortableTextEditor.focus(editorInstance)
+        // Toggle the decorator
+        editor.send({
+          type: 'decorator.toggle',
+          decorator: props.decorator,
+        })
+        // Pressing this button steals focus so let's focus the editor again
+        editor.send({type: 'focus'})
       }}
     >
-      {list.name}
+      {props.decorator}
     </button>
-  ))
+  )
+}
 
-  const imageButton = (
+function AnnotationButton(props: {annotation: {name: string}}) {
+  const editor = useEditor()
+  const active = useEditorSelector(
+    editor,
+    selectors.isActiveAnnotation(props.annotation.name),
+  )
+
+  return (
     <button
+      style={{
+        textDecoration: active ? 'underline' : 'unset',
+      }}
       onClick={() => {
-        PortableTextEditor.insertBlock(
-          editorInstance,
-          schemaDefinition.blockObjects[0],
-          {src: 'https://example.com/image.jpg'},
-        )
-        PortableTextEditor.focus(editorInstance)
+        editor.send({
+          type: 'annotation.toggle',
+          annotation: {
+            name: props.annotation.name,
+            value:
+              props.annotation.name === 'link'
+                ? {href: 'https://example.com'}
+                : {},
+          },
+        })
+        editor.send({type: 'focus'})
       }}
     >
-      {schemaDefinition.blockObjects[0].name}
+      {props.annotation.name}
     </button>
   )
+}
 
-  const stockTickerButton = (
+function StyleButton(props: {style: string}) {
+  const editor = useEditor()
+  const active = useEditorSelector(editor, selectors.isActiveStyle(props.style))
+
+  return (
     <button
+      style={{
+        textDecoration: active ? 'underline' : 'unset',
+      }}
       onClick={() => {
-        PortableTextEditor.insertChild(
-          editorInstance,
-          schemaDefinition.inlineObjects[0],
-          {symbol: 'AAPL'},
-        )
-        PortableTextEditor.focus(editorInstance)
+        editor.send({type: 'style.toggle', style: props.style})
+        editor.send({type: 'focus'})
       }}
     >
-      {schemaDefinition.inlineObjects[0].name}
+      {props.style}
     </button>
   )
+}
+
+function ListButton(props: {list: string}) {
+  const editor = useEditor()
+  const active = useEditorSelector(
+    editor,
+    selectors.isActiveListItem(props.list),
+  )
 
   return (
-    <>
-      <div>{decoratorButtons}</div>
-      <div>{linkButton}</div>
-      <div>{styleButtons}</div>
-      <div>{listButtons}</div>
-      <div>{imageButton}</div>
-      <div>{stockTickerButton}</div>
-    </>
+    <button
+      style={{
+        textDecoration: active ? 'underline' : 'unset',
+      }}
+      onClick={() => {
+        editor.send({
+          type: 'list item.toggle',
+          listItem: props.list,
+        })
+        editor.send({type: 'focus'})
+      }}
+    >
+      {props.list}
+    </button>
   )
 }
 ```
@@ -379,6 +391,10 @@ The Behavior API is a new way of interfacing with the Portable Text Editor. It a
 3. Deriving editor **state** using **pure functions**.
 4. Subscribe to **emitted** editor **events** using `editor.on(…)`.
 
+## End-User Experience
+
+In order to provide a robust and consistent end-user experience, the editor is backed by an elaborate E2E test suite generated from a [human-readable Gherkin spec](/packages/editor/gherkin-spec/).
+
 ## Development
 
 ### Develop Together with Sanity Studio

package/lib/index.cjs

@@ -11,11 +11,11 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
   return a;
 };
 Object.defineProperty(exports, "__esModule", { value: !0 });
-var schema = require("@sanity/schema"), types = require("@sanity/types"), startCase = require("lodash.startcase"), jsxRuntime = require("react/jsx-runtime"), react = require("@xstate/react"), isEqual = require("lodash/isEqual.js"), noop = require("lodash/noop.js"), React = require("react"), slate = require("slate"), slateReact = require("slate-react"), debug$m = require("debug"), reactCompilerRuntime = require("react-compiler-runtime"), styledComponents = require("styled-components"), uniq = require("lodash/uniq.js"), rxjs = require("rxjs"), useEffectEvent = require("use-effect-event"), xstate = require("xstate"), patches = require("@portabletext/patches"), flatten = require("lodash/flatten.js"), isPlainObject = require("lodash/isPlainObject.js"), get = require("lodash/get.js"), isUndefined = require("lodash/isUndefined.js"), omitBy = require("lodash/omitBy.js"), selector_isSelectionCollapsed = require("./_chunks-cjs/selector.is-selection-collapsed.cjs"), behavior_core = require("./_chunks-cjs/behavior.core.cjs"), getRandomValues = require("get-random-values-esm"), blockTools = require("@sanity/block-tools");
+var schema = require("@sanity/schema"), types = require("@sanity/types"), startCase = require("lodash.startcase"), jsxRuntime = require("react/jsx-runtime"), react = require("@xstate/react"), isEqual = require("lodash/isEqual.js"), noop = require("lodash/noop.js"), React = require("react"), slate = require("slate"), slateReact = require("slate-react"), debug$l = require("debug"), reactCompilerRuntime = require("react-compiler-runtime"), styledComponents = require("styled-components"), uniq = require("lodash/uniq.js"), rxjs = require("rxjs"), useEffectEvent = require("use-effect-event"), xstate = require("xstate"), patches = require("@portabletext/patches"), flatten = require("lodash/flatten.js"), isPlainObject = require("lodash/isPlainObject.js"), get = require("lodash/get.js"), isUndefined = require("lodash/isUndefined.js"), omitBy = require("lodash/omitBy.js"), selector_isSelectionCollapsed = require("./_chunks-cjs/selector.is-selection-collapsed.cjs"), behavior_core = require("./_chunks-cjs/behavior.core.cjs"), getRandomValues = require("get-random-values-esm"), blockTools = require("@sanity/block-tools");
 function _interopDefaultCompat(e) {
   return e && typeof e == "object" && "default" in e ? e : { default: e };
 }
-var startCase__default = /* @__PURE__ */ _interopDefaultCompat(startCase), isEqual__default = /* @__PURE__ */ _interopDefaultCompat(isEqual), noop__default = /* @__PURE__ */ _interopDefaultCompat(noop), React__default = /* @__PURE__ */ _interopDefaultCompat(React), debug__default = /* @__PURE__ */ _interopDefaultCompat(debug$m), uniq__default = /* @__PURE__ */ _interopDefaultCompat(uniq), flatten__default = /* @__PURE__ */ _interopDefaultCompat(flatten), isPlainObject__default = /* @__PURE__ */ _interopDefaultCompat(isPlainObject), get__default = /* @__PURE__ */ _interopDefaultCompat(get), isUndefined__default = /* @__PURE__ */ _interopDefaultCompat(isUndefined), omitBy__default = /* @__PURE__ */ _interopDefaultCompat(omitBy), getRandomValues__default = /* @__PURE__ */ _interopDefaultCompat(getRandomValues);
+var startCase__default = /* @__PURE__ */ _interopDefaultCompat(startCase), isEqual__default = /* @__PURE__ */ _interopDefaultCompat(isEqual), noop__default = /* @__PURE__ */ _interopDefaultCompat(noop), React__default = /* @__PURE__ */ _interopDefaultCompat(React), debug__default = /* @__PURE__ */ _interopDefaultCompat(debug$l), uniq__default = /* @__PURE__ */ _interopDefaultCompat(uniq), flatten__default = /* @__PURE__ */ _interopDefaultCompat(flatten), isPlainObject__default = /* @__PURE__ */ _interopDefaultCompat(isPlainObject), get__default = /* @__PURE__ */ _interopDefaultCompat(get), isUndefined__default = /* @__PURE__ */ _interopDefaultCompat(isUndefined), omitBy__default = /* @__PURE__ */ _interopDefaultCompat(omitBy), getRandomValues__default = /* @__PURE__ */ _interopDefaultCompat(getRandomValues);
 function createEditorSchema(portableTextType) {
   var _a, _b, _c;
   if (!portableTextType)
@@ -155,7 +155,7 @@ function compileSchemaDefinition(definition) {
   });
 }
 const rootName = "sanity-pte:";
-var debug$l = debug__default.default(rootName);
+debug__default.default(rootName);
 function debugWithName(name) {
   const namespace = `${rootName}${name}`;
   return debug__default.default && debug__default.default.enabled(namespace) ? debug__default.default(namespace) : debug__default.default(rootName);
@@ -2315,24 +2315,20 @@ const syncValueCallback = ({
         event
       }) => (xstate.assertEvent(event, "done syncing"), event.value)
     }),
-    "emit done syncing": xstate.emit(({
-      event
-    }) => (xstate.assertEvent(event, "done syncing"), event))
+    "emit done syncing initial value": xstate.emit({
+      type: "done syncing initial value"
+    })
   },
   guards: {
-    "is readOnly": ({
+    "initial value synced": ({
       context
-    }) => context.readOnly,
-    "is processing local changes": ({
-      context
-    }) => context.isProcessingLocalChanges,
-    "is processing remote changes": ({
+    }) => context.initialValueSynced,
+    "is busy": ({
       context
     }) => {
       var _a;
-      return (_a = isChangingRemotely(context.slateEditor)) != null ? _a : !1;
+      return !context.readOnly && (context.isProcessingLocalChanges || ((_a = isChangingRemotely(context.slateEditor)) != null ? _a : !1));
     },
-    "is busy": xstate.and([xstate.not("is readOnly"), xstate.or(["is processing local changes", "is processing remote changes"])]),
     "value changed while syncing": ({
       context,
       event
@@ -2358,7 +2354,6 @@ const syncValueCallback = ({
     pendingValue: void 0,
     previousValue: void 0
   }),
-  initial: "idle",
   on: {
     "has pending patches": {
       actions: xstate.assign({
@@ -2374,94 +2369,105 @@ const syncValueCallback = ({
       actions: ["assign readOnly"]
     }
   },
+  type: "parallel",
   states: {
-    idle: {
-      on: {
-        "update value": [{
-          guard: "is busy",
-          target: "busy",
-          actions: ["assign pending value"]
-        }, {
-          target: "syncing",
-          actions: ["assign pending value"]
-        }]
-      }
-    },
-    busy: {
-      after: {
-        1e3: {
-          target: "syncing"
+    "setting up": {
+      initial: "syncing initial value",
+      states: {
+        "syncing initial value": {
+          always: {
+            guard: "initial value synced",
+            target: "done syncing initial value"
+          }
+        },
+        "done syncing initial value": {
+          entry: ["emit done syncing initial value"],
+          type: "final"
         }
-      },
-      on: {
-        "update value": [{
-          guard: "is busy",
-          actions: ["assign pending value"],
-          reenter: !0
-        }, {
-          target: "syncing",
-          actions: ["assign pending value"]
-        }]
       }
     },
     syncing: {
-      invoke: {
-        src: "sync value",
-        id: "sync value",
-        input: ({
-          context
-        }) => {
-          var _a;
-          return {
-            context: {
-              keyGenerator: context.keyGenerator,
-              previousValue: context.previousValue,
-              readOnly: context.readOnly,
-              schema: context.schema
-            },
-            slateEditor: context.slateEditor,
-            streamBlocks: !context.initialValueSynced,
-            value: (_a = context.pendingValue) != null ? _a : void 0
-          };
-        }
-      },
-      always: {
-        guard: "pending value equals previous value",
-        actions: [xstate.emit(({
-          context
-        }) => ({
-          type: "done syncing",
-          value: context.previousValue
-        }))],
-        target: "idle"
-      },
-      on: {
-        "update value": {
-          actions: ["assign pending value"]
-        },
-        patch: {
-          actions: [xstate.emit(({
-            event
-          }) => event)]
-        },
-        "invalid value": {
-          actions: [xstate.emit(({
-            event
-          }) => event)]
+      initial: "idle",
+      states: {
+        idle: {
+          on: {
+            "update value": [{
+              guard: "is busy",
+              target: "busy",
+              actions: ["assign pending value"]
+            }, {
+              target: "syncing",
+              actions: ["assign pending value"]
+            }]
+          }
         },
-        "value changed": {
-          actions: [xstate.emit(({
-            event
-          }) => event)]
+        busy: {
+          after: {
+            1e3: [{
+              guard: "is busy",
+              reenter: !0
+            }, {
+              target: "syncing"
+            }]
+          },
+          on: {
+            "update value": [{
+              actions: ["assign pending value"]
+            }]
+          }
         },
-        "done syncing": [{
-          guard: "value changed while syncing",
-          actions: ["assign previous value", "emit done syncing", "assign initial value synced"],
-          reenter: !0
-        }, {
-          target: "idle",
-          actions: ["clear pending value", "assign previous value", "emit done syncing", "assign initial value synced"]
-        }]
+        syncing: {
+          always: {
+            guard: "pending value equals previous value",
+            target: "idle",
+            actions: ["clear pending value", "assign initial value synced"]
+          },
+          invoke: {
+            src: "sync value",
+            id: "sync value",
+            input: ({
+              context
+            }) => ({
+              context: {
+                keyGenerator: context.keyGenerator,
+                previousValue: context.previousValue,
+                readOnly: context.readOnly,
+                schema: context.schema
+              },
+              slateEditor: context.slateEditor,
+              streamBlocks: !context.initialValueSynced,
+              value: context.pendingValue
+            })
+          },
+          on: {
+            "update value": {
+              actions: ["assign pending value"]
+            },
+            patch: {
+              actions: [xstate.emit(({
+                event
+              }) => event)]
+            },
+            "invalid value": {
+              actions: [xstate.emit(({
+                event
+              }) => event)]
+            },
+            "value changed": {
+              actions: [xstate.emit(({
+                event
+              }) => event)]
+            },
+            "done syncing": [{
+              guard: "value changed while syncing",
+              actions: ["assign previous value", "assign initial value synced"],
+              reenter: !0
+            }, {
+              target: "idle",
+              actions: ["clear pending value", "assign previous value", "assign initial value synced"]
+            }]
+          }
+        }
       }
     }
   }
@@ -5704,7 +5710,7 @@ function performAction({
   context,
   action
 }) {
-  switch (debug$l("Behavior action", action), action.type) {
+  switch (action.type) {
     case "delete.block": {
       behaviorActionImplementations["delete.block"]({
         context,
@@ -6043,7 +6049,7 @@ const editorMachine = xstate.setup({
       enqueue
     }) => {
       var _a;
-      xstate.assertEvent(event, ["behavior event"]), debug$l("Behavior event", event);
+      xstate.assertEvent(event, ["behavior event"]);
       const defaultAction = event.behaviorEvent.type === "copy" || event.behaviorEvent.type === "key.down" || event.behaviorEvent.type === "key.up" || event.behaviorEvent.type === "paste" ? void 0 : __spreadProps$4(__spreadValues$4({}, event.behaviorEvent), {
         editor: event.editor
       }), eventBehaviors = context.behaviors.filter((behavior) => behavior.on === event.behaviorEvent.type);
@@ -6231,7 +6237,7 @@ const editorMachine = xstate.setup({
           states: {
             "determine initial edit mode": {
               on: {
-                "done syncing": [{
+                "done syncing initial value": [{
                   target: "#editor.edit mode.read only.read only",
                   guard: ({
                     context
@@ -6327,7 +6333,7 @@ const editorMachine = xstate.setup({
             mutation: {
               actions: "defer event"
             },
-            "done syncing": {
+            "done syncing initial value": {
               target: "pristine"
             }
           }