@portabletext/editor 1.23.0 → 1.24.0

package/lib/index.d.ts

@@ -98,7 +98,11 @@ export declare type BaseDefinition = {
 export declare type Behavior<
   TBehaviorEventType extends BehaviorEvent['type'] = BehaviorEvent['type'],
   TGuardResponse = true,
-  TBehaviorEvent extends BehaviorEvent = BehaviorEvent,
+  TBehaviorEvent extends BehaviorEvent = PickFromUnion<
+    BehaviorEvent,
+    'type',
+    TBehaviorEventType
+  >,
 > = {
   /**
    * The internal editor event that triggers this behavior.
@@ -364,6 +368,43 @@ export declare type ConnectionChange = {
   value: 'online' | 'offline'
 }
 
+declare type Converter<TMIMEType extends MIMEType = MIMEType> = {
+  mimeType: TMIMEType
+  serialize: Serializer<TMIMEType>
+  deserialize: Deserializer<TMIMEType>
+}
+
+declare type ConverterEvent<TMIMEType extends MIMEType = MIMEType> =
+  | {
+      type: 'serialize'
+      originEvent: 'copy' | 'cut' | 'unknown'
+    }
+  | {
+      type: 'serialization.failure'
+      mimeType: TMIMEType
+      reason: string
+    }
+  | {
+      type: 'serialization.success'
+      data: string
+      mimeType: TMIMEType
+      originEvent: 'copy' | 'cut' | 'unknown'
+    }
+  | {
+      type: 'deserialize'
+      data: string
+    }
+  | {
+      type: 'deserialization.failure'
+      mimeType: TMIMEType
+      reason: string
+    }
+  | {
+      type: 'deserialization.success'
+      data: Array<PortableTextBlock>
+      mimeType: TMIMEType
+    }
+
 /**
  * @beta
  */
@@ -402,6 +443,18 @@ export declare function defineSchema<
   const TSchemaDefinition extends SchemaDefinition,
 >(definition: TSchemaDefinition): TSchemaDefinition
 
+declare type Deserializer<TMIMEType extends MIMEType> = ({
+  context,
+  event,
+}: {
+  context: EditorContext
+  event: PickFromUnion<ConverterEvent<TMIMEType>, 'type', 'deserialize'>
+}) => PickFromUnion<
+  ConverterEvent<TMIMEType>,
+  'type',
+  'deserialization.success' | 'deserialization.failure'
+>
+
 /** @beta */
 export declare interface EditableAPI {
   activeAnnotations: () => PortableTextObject[]
@@ -569,6 +622,7 @@ export declare type EditorConfig = {
  */
 export declare type EditorContext = {
   activeDecorators: Array<string>
+  converters: Array<Converter>
   keyGenerator: () => string
   schema: EditorSchema
   selection: EditorSelection
@@ -679,6 +733,7 @@ export declare function EditorEventListener(props: {
 export declare const editorMachine: StateMachine<
   {
     behaviors: Set<Behavior>
+    converters: Set<Converter>
     keyGenerator: () => string
     pendingEvents: Array<PatchEvent | MutationEvent>
     schema: EditorSchema
@@ -920,6 +975,7 @@ export declare const editorMachine: StateMachine<
   string,
   {
     behaviors?: Array<Behavior>
+    converters?: Array<Converter>
     keyGenerator: () => string
     maxBlocks?: number
     readOnly?: boolean
@@ -1066,6 +1122,7 @@ export declare const editorMachine: StateMachine<
       }
       input: {
         behaviors?: Array<Behavior>
+        converters?: Array<Converter>
         keyGenerator: () => string
         maxBlocks?: number
         readOnly?: boolean
@@ -1076,6 +1133,7 @@ export declare const editorMachine: StateMachine<
         MachineSnapshot<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -1413,6 +1471,7 @@ export declare const editorMachine: StateMachine<
       >
     }) => {
       behaviors: Set<Behavior>
+      converters: Set<Converter>
       keyGenerator: () => string
       pendingEvents: never[]
       schema: PortableTextMemberSchemaTypes_2
@@ -1432,6 +1491,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -1723,6 +1783,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -2014,6 +2075,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -2306,6 +2368,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -2600,6 +2663,7 @@ export declare const editorMachine: StateMachine<
           ActionFunction<
             {
               behaviors: Set<Behavior>
+              converters: Set<Converter>
               keyGenerator: () => string
               pendingEvents: Array<PatchEvent | MutationEvent>
               schema: EditorSchema
@@ -2781,6 +2845,7 @@ export declare const editorMachine: StateMachine<
           ActionFunction<
             {
               behaviors: Set<Behavior>
+              converters: Set<Converter>
               keyGenerator: () => string
               pendingEvents: Array<PatchEvent | MutationEvent>
               schema: EditorSchema
@@ -3073,6 +3138,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -3364,6 +3430,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -3655,6 +3722,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -3945,6 +4013,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -4233,6 +4302,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -4526,6 +4596,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -4712,6 +4783,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -4895,6 +4967,7 @@ export declare const editorMachine: StateMachine<
         readonly actions: ActionFunction<
           {
             behaviors: Set<Behavior>
+            converters: Set<Converter>
             keyGenerator: () => string
             pendingEvents: Array<PatchEvent | MutationEvent>
             schema: EditorSchema
@@ -5093,6 +5166,7 @@ export declare const editorMachine: StateMachine<
                       }: GuardArgs<
                         {
                           behaviors: Set<Behavior>
+                          converters: Set<Converter>
                           keyGenerator: () => string
                           pendingEvents: Array<PatchEvent | MutationEvent>
                           schema: EditorSchema
@@ -5114,12 +5188,42 @@ export declare const editorMachine: StateMachine<
               }
               readonly 'read only': {
                 readonly on: {
+                  readonly 'behavior event': {
+                    readonly actions: 'handle behavior event'
+                    readonly guard: ({
+                      event,
+                    }: GuardArgs<
+                      {
+                        behaviors: Set<Behavior>
+                        converters: Set<Converter>
+                        keyGenerator: () => string
+                        pendingEvents: Array<PatchEvent | MutationEvent>
+                        schema: EditorSchema
+                        initialReadOnly: boolean
+                        maxBlocks: number | undefined
+                        selection: EditorSelection
+                        value: Array<PortableTextBlock> | undefined
+                      },
+                      {
+                        type: 'behavior event'
+                        behaviorEvent:
+                          | SyntheticBehaviorEvent
+                          | NativeBehaviorEvent
+                        editor: PortableTextSlateEditor
+                        defaultActionCallback?: () => void
+                        nativeEvent?: {
+                          preventDefault: () => void
+                        }
+                      }
+                    >) => boolean
+                  }
                   readonly 'update readOnly': {
                     readonly guard: ({
                       event,
                     }: GuardArgs<
                       {
                         behaviors: Set<Behavior>
+                        converters: Set<Converter>
                         keyGenerator: () => string
                         pendingEvents: Array<PatchEvent | MutationEvent>
                         schema: EditorSchema
@@ -5148,6 +5252,7 @@ export declare const editorMachine: StateMachine<
                 }: GuardArgs<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -5174,6 +5279,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -5478,6 +5584,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -5770,6 +5877,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -6064,6 +6172,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -6357,6 +6466,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -6649,6 +6759,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -6957,6 +7068,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -7250,6 +7362,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -7543,6 +7656,7 @@ export declare const editorMachine: StateMachine<
                 readonly actions: ActionFunction<
                   {
                     behaviors: Set<Behavior>
+                    converters: Set<Converter>
                     keyGenerator: () => string
                     pendingEvents: Array<PatchEvent | MutationEvent>
                     schema: EditorSchema
@@ -8207,6 +8321,8 @@ export declare type LoadingChange = {
   isLoading: boolean
 }
 
+declare type MIMEType = `${string}/${string}`
+
 /**
  * The editor has mutated it's content.
  * @beta */
@@ -8237,6 +8353,10 @@ export declare type NativeBehaviorEvent =
       type: 'copy'
       data: DataTransfer
     }
+  | {
+      type: 'deserialize'
+      dataTransfer: DataTransfer
+    }
   | {
       type: 'key.down'
       keyboardEvent: Pick<
@@ -8255,6 +8375,11 @@ export declare type NativeBehaviorEvent =
       type: 'paste'
       data: DataTransfer
     }
+  | {
+      type: 'serialize'
+      originEvent: 'copy' | 'cut' | 'unknown'
+      dataTransfer: DataTransfer
+    }
 
 /**
  * @alpha
@@ -8782,6 +8907,18 @@ export declare type SelectionChange = {
   selection: EditorSelection
 }
 
+declare type Serializer<TMIMEType extends MIMEType> = ({
+  context,
+  event,
+}: {
+  context: EditorContext
+  event: PickFromUnion<ConverterEvent<TMIMEType>, 'type', 'serialize'>
+}) => PickFromUnion<
+  ConverterEvent<TMIMEType>,
+  'type',
+  'serialization.success' | 'serialization.failure'
+>
+
 /**
  * @internal
  */
@@ -8812,6 +8949,12 @@ export declare type SyntheticBehaviorEvent =
   | {
       type: 'blur'
     }
+  | {
+      type: 'data transfer.set'
+      data: string
+      dataTransfer: DataTransfer
+      mimeType: MIMEType
+    }
   | {
       type: 'decorator.toggle'
       decorator: string
@@ -8827,6 +8970,10 @@ export declare type SyntheticBehaviorEvent =
   | {
       type: 'focus'
     }
+  | {
+      type: 'insert.blocks'
+      blocks: Array<PortableTextBlock>
+    }
   | {
       type: 'insert.block object'
       placement: 'auto' | 'after' | 'before'
@@ -8869,6 +9016,16 @@ export declare type SyntheticBehaviorEvent =
       type: 'style.toggle'
       style: string
     }
+  | (PickFromUnion<
+      ConverterEvent,
+      'type',
+      | 'deserialization.failure'
+      | 'deserialization.success'
+      | 'serialization.failure'
+      | 'serialization.success'
+    > & {
+      dataTransfer: DataTransfer
+    })
 
 /**
  * The editor performed a undo history step