@portabletext/editor 1.15.1 → 1.15.2

package/lib/behaviors/index.d.ts

@@ -0,0 +1,875 @@
+import type {
+  ArraySchemaType,
+  BlockDecoratorDefinition,
+  BlockListDefinition,
+  BlockStyleDefinition,
+  KeyedSegment,
+  ObjectSchemaType,
+  Path,
+  PortableTextBlock,
+  PortableTextTextBlock,
+} from '@sanity/types'
+import type {TextUnit} from 'slate'
+import type {TextInsertTextOptions} from 'slate/dist/interfaces/transforms/text'
+
+/**
+ * @alpha
+ */
+export declare type Behavior<
+  TBehaviorEventType extends BehaviorEvent['type'] = BehaviorEvent['type'],
+  TGuardResponse = true,
+> = {
+  /**
+   * The internal editor event that triggers this behavior.
+   */
+  on: TBehaviorEventType
+  /**
+   * Predicate function that determines if the behavior should be executed.
+   * Returning a non-nullable value from the guard will pass the value to the
+   * actions and execute them.
+   */
+  guard?: BehaviorGuard<
+    PickFromUnion<BehaviorEvent, 'type', TBehaviorEventType>,
+    TGuardResponse
+  >
+  /**
+   * Array of behavior action sets.
+   */
+  actions: Array<BehaviorActionIntendSet<TBehaviorEventType, TGuardResponse>>
+}
+
+/**
+ * @alpha
+ */
+export declare type BehaviorActionIntend =
+  | SyntheticBehaviorEvent
+  | {
+      type: 'insert.span'
+      text: string
+      annotations?: Array<{
+        name: string
+        value: {
+          [prop: string]: unknown
+        }
+      }>
+      decorators?: Array<string>
+    }
+  | {
+      type: 'insert.text block'
+      placement: 'auto' | 'after' | 'before'
+      textBlock?: {
+        children?: PortableTextTextBlock['children']
+      }
+    }
+  | {
+      type: 'list item.add'
+      listItem: string
+    }
+  | {
+      type: 'list item.remove'
+      listItem: string
+    }
+  | {
+      type: 'move.block'
+      at: [KeyedSegment]
+      to: [KeyedSegment]
+    }
+  | {
+      type: 'move.block down'
+      at: [KeyedSegment]
+    }
+  | {
+      type: 'move.block up'
+      at: [KeyedSegment]
+    }
+  | {
+      type: 'noop'
+    }
+  | {
+      type: 'delete.block'
+      blockPath: [KeyedSegment]
+    }
+  | {
+      type: 'delete.text'
+      anchor: BlockOffset
+      focus: BlockOffset
+    }
+  | {
+      type: 'effect'
+      effect: () => void
+    }
+  | {
+      type: 'select'
+      selection: EditorSelection
+    }
+  | {
+      type: 'select previous block'
+    }
+  | {
+      type: 'select next block'
+    }
+  | {
+      type: 'reselect'
+    }
+  | {
+      type: 'style.add'
+      style: string
+    }
+  | {
+      type: 'style.remove'
+      style: string
+    }
+  | {
+      type: 'text block.set'
+      at: [KeyedSegment]
+      level?: number
+      listItem?: string
+      style?: string
+    }
+  | {
+      type: 'text block.unset'
+      at: [KeyedSegment]
+      props: Array<'level' | 'listItem' | 'style'>
+    }
+
+/**
+ * @alpha
+ */
+export declare type BehaviorActionIntendSet<
+  TBehaviorEventType extends BehaviorEvent['type'] = BehaviorEvent['type'],
+  TGuardResponse = true,
+> = (
+  {
+    context,
+    event,
+  }: {
+    context: EditorContext
+    event: PickFromUnion<BehaviorEvent, 'type', TBehaviorEventType>
+  },
+  guardResponse: TGuardResponse,
+) => Array<BehaviorActionIntend>
+
+/**
+ * @alpha
+ */
+export declare type BehaviorEvent = SyntheticBehaviorEvent | NativeBehaviorEvent
+
+/**
+ * @alpha
+ */
+export declare type BehaviorGuard<
+  TBehaviorEvent extends BehaviorEvent,
+  TGuardResponse,
+> = ({
+  context,
+  event,
+}: {
+  context: EditorContext
+  event: TBehaviorEvent
+}) => TGuardResponse | false
+
+/**
+ * @alpha
+ */
+export declare type BlockOffset = {
+  path: [KeyedSegment]
+  offset: number
+}
+
+/**
+ * @alpha
+ */
+export declare type CodeEditorBehaviorsConfig = {
+  moveBlockUpShortcut: string
+  moveBlockDownShortcut: string
+}
+
+/**
+ * @alpha
+ */
+export declare const coreBehavior: {
+  softReturn: Behavior<
+    | 'annotation.add'
+    | 'annotation.remove'
+    | 'annotation.toggle'
+    | 'blur'
+    | 'decorator.add'
+    | 'decorator.remove'
+    | 'decorator.toggle'
+    | 'delete.backward'
+    | 'delete.forward'
+    | 'focus'
+    | 'insert.block object'
+    | 'insert.inline object'
+    | 'insert.soft break'
+    | 'insert.break'
+    | 'insert.text'
+    | 'list item.toggle'
+    | 'style.toggle'
+    | 'copy'
+    | 'key.down'
+    | 'key.up'
+    | 'paste',
+    true
+  >
+  decorators: {
+    decoratorAdd: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    decoratorRemove: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    decoratorToggle: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+  }
+  blockObjects: {
+    arrowDownOnLonelyBlockObject: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    arrowUpOnLonelyBlockObject: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    breakingBlockObject: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    deletingEmptyTextBlockAfterBlockObject: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    deletingEmptyTextBlockBeforeBlockObject: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+  }
+  lists: {
+    clearListOnBackspace: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    unindentListOnBackspace: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    clearListOnEnter: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    indentListOnTab: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+    unindentListOnShiftTab: Behavior<
+      | 'annotation.add'
+      | 'annotation.remove'
+      | 'annotation.toggle'
+      | 'blur'
+      | 'decorator.add'
+      | 'decorator.remove'
+      | 'decorator.toggle'
+      | 'delete.backward'
+      | 'delete.forward'
+      | 'focus'
+      | 'insert.block object'
+      | 'insert.inline object'
+      | 'insert.soft break'
+      | 'insert.break'
+      | 'insert.text'
+      | 'list item.toggle'
+      | 'style.toggle'
+      | 'copy'
+      | 'key.down'
+      | 'key.up'
+      | 'paste',
+      true
+    >
+  }
+}
+
+/**
+ * @alpha
+ */
+export declare const coreBehaviors: Behavior<
+  | 'annotation.add'
+  | 'annotation.remove'
+  | 'annotation.toggle'
+  | 'blur'
+  | 'decorator.add'
+  | 'decorator.remove'
+  | 'decorator.toggle'
+  | 'delete.backward'
+  | 'delete.forward'
+  | 'focus'
+  | 'insert.block object'
+  | 'insert.inline object'
+  | 'insert.soft break'
+  | 'insert.break'
+  | 'insert.text'
+  | 'list item.toggle'
+  | 'style.toggle'
+  | 'copy'
+  | 'key.down'
+  | 'key.up'
+  | 'paste',
+  true
+>[]
+
+/**
+ * @alpha
+ */
+export declare function createCodeEditorBehaviors(
+  config: CodeEditorBehaviorsConfig,
+): Behavior<
+  | 'annotation.add'
+  | 'annotation.remove'
+  | 'annotation.toggle'
+  | 'blur'
+  | 'decorator.add'
+  | 'decorator.remove'
+  | 'decorator.toggle'
+  | 'delete.backward'
+  | 'delete.forward'
+  | 'focus'
+  | 'insert.block object'
+  | 'insert.inline object'
+  | 'insert.soft break'
+  | 'insert.break'
+  | 'insert.text'
+  | 'list item.toggle'
+  | 'style.toggle'
+  | 'copy'
+  | 'key.down'
+  | 'key.up'
+  | 'paste',
+  true
+>[]
+
+/**
+ * @alpha
+ */
+export declare function createLinkBehaviors(
+  config: LinkBehaviorsConfig,
+): Behavior<
+  | 'annotation.add'
+  | 'annotation.remove'
+  | 'annotation.toggle'
+  | 'blur'
+  | 'decorator.add'
+  | 'decorator.remove'
+  | 'decorator.toggle'
+  | 'delete.backward'
+  | 'delete.forward'
+  | 'focus'
+  | 'insert.block object'
+  | 'insert.inline object'
+  | 'insert.soft break'
+  | 'insert.break'
+  | 'insert.text'
+  | 'list item.toggle'
+  | 'style.toggle'
+  | 'copy'
+  | 'key.down'
+  | 'key.up'
+  | 'paste',
+  true
+>[]
+
+/**
+ * @alpha
+ */
+export declare function createMarkdownBehaviors(
+  config: MarkdownBehaviorsConfig,
+): Behavior<
+  | 'annotation.add'
+  | 'annotation.remove'
+  | 'annotation.toggle'
+  | 'blur'
+  | 'decorator.add'
+  | 'decorator.remove'
+  | 'decorator.toggle'
+  | 'delete.backward'
+  | 'delete.forward'
+  | 'focus'
+  | 'insert.block object'
+  | 'insert.inline object'
+  | 'insert.soft break'
+  | 'insert.break'
+  | 'insert.text'
+  | 'list item.toggle'
+  | 'style.toggle'
+  | 'copy'
+  | 'key.down'
+  | 'key.up'
+  | 'paste',
+  true
+>[]
+
+/**
+ * @alpha
+ */
+export declare function defineBehavior<
+  TAnyBehaviorEventType extends BehaviorEvent['type'],
+  TGuardResponse = true,
+>(behavior: Behavior<TAnyBehaviorEventType, TGuardResponse>): Behavior
+
+/**
+ * @alpha
+ */
+export declare type EditorContext = {
+  keyGenerator: () => string
+  schema: PortableTextMemberSchemaTypes
+  selection: NonNullable<EditorSelection>
+  value: Array<PortableTextBlock>
+}
+
+/** @beta */
+export declare type EditorSelection = {
+  anchor: EditorSelectionPoint
+  focus: EditorSelectionPoint
+  backward?: boolean
+} | null
+
+/** @beta */
+export declare type EditorSelectionPoint = {
+  path: Path
+  offset: number
+}
+
+/**
+ * @alpha
+ */
+export declare type LinkBehaviorsConfig = {
+  linkAnnotation?: (context: {
+    schema: PortableTextMemberSchemaTypes
+    url: string
+  }) =>
+    | {
+        name: string
+        value: {
+          [prop: string]: unknown
+        }
+      }
+    | undefined
+}
+
+/**
+ * @alpha
+ */
+export declare type MarkdownBehaviorsConfig = {
+  horizontalRuleObject?: (context: {schema: PortableTextMemberSchemaTypes}) =>
+    | {
+        name: string
+        value?: {
+          [prop: string]: unknown
+        }
+      }
+    | undefined
+  defaultStyle?: (context: {
+    schema: PortableTextMemberSchemaTypes
+  }) => string | undefined
+  headingStyle?: (context: {
+    schema: PortableTextMemberSchemaTypes
+    level: number
+  }) => string | undefined
+  blockquoteStyle?: (context: {
+    schema: PortableTextMemberSchemaTypes
+  }) => string | undefined
+  unorderedListStyle?: (context: {
+    schema: PortableTextMemberSchemaTypes
+  }) => string | undefined
+  orderedListStyle?: (context: {
+    schema: PortableTextMemberSchemaTypes
+  }) => string | undefined
+}
+
+/**
+ * @alpha
+ */
+export declare type NativeBehaviorEvent =
+  | {
+      type: 'copy'
+      data: DataTransfer
+    }
+  | {
+      type: 'key.down'
+      keyboardEvent: Pick<
+        KeyboardEvent,
+        'key' | 'code' | 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey'
+      >
+    }
+  | {
+      type: 'key.up'
+      keyboardEvent: Pick<
+        KeyboardEvent,
+        'key' | 'code' | 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey'
+      >
+    }
+  | {
+      type: 'paste'
+      data: DataTransfer
+    }
+
+/**
+ * @alpha
+ */
+export declare type PickFromUnion<
+  TUnion,
+  TTagKey extends keyof TUnion,
+  TPickedTags extends TUnion[TTagKey],
+> = TUnion extends Record<TTagKey, TPickedTags> ? TUnion : never
+
+/** @internal */
+export declare type PortableTextMemberSchemaTypes = {
+  annotations: (ObjectSchemaType & {
+    i18nTitleKey?: string
+  })[]
+  block: ObjectSchemaType
+  blockObjects: ObjectSchemaType[]
+  decorators: BlockDecoratorDefinition[]
+  inlineObjects: ObjectSchemaType[]
+  portableText: ArraySchemaType<PortableTextBlock>
+  span: ObjectSchemaType
+  styles: BlockStyleDefinition[]
+  lists: BlockListDefinition[]
+}
+
+/**
+ * @alpha
+ */
+export declare type SyntheticBehaviorEvent =
+  | {
+      type: 'annotation.add'
+      annotation: {
+        name: string
+        value: {
+          [prop: string]: unknown
+        }
+      }
+    }
+  | {
+      type: 'annotation.remove'
+      annotation: {
+        name: string
+      }
+    }
+  | {
+      type: 'annotation.toggle'
+      annotation: {
+        name: string
+        value: {
+          [prop: string]: unknown
+        }
+      }
+    }
+  | {
+      type: 'blur'
+    }
+  | {
+      type: 'decorator.add'
+      decorator: string
+    }
+  | {
+      type: 'decorator.remove'
+      decorator: string
+    }
+  | {
+      type: 'decorator.toggle'
+      decorator: string
+    }
+  | {
+      type: 'delete.backward'
+      unit: TextUnit
+    }
+  | {
+      type: 'delete.forward'
+      unit: TextUnit
+    }
+  | {
+      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: 'insert.soft break'
+    }
+  | {
+      type: 'insert.break'
+    }
+  | {
+      type: 'insert.text'
+      text: string
+      options?: TextInsertTextOptions
+    }
+  | {
+      type: 'list item.toggle'
+      listItem: string
+    }
+  | {
+      type: 'style.toggle'
+      style: string
+    }
+
+export {}