@portabletext/editor 1.27.0 → 1.28.0

package/lib/index.d.cts

@@ -19509,11 +19509,46 @@ export declare class PortableTextEditor extends Component<
   componentDidUpdate(prevProps: PortableTextEditorProps): void
   setEditable: (editable: EditableAPI) => void
   render(): JSX.Element
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.getActiveAnnotations)
+   * ```
+   */
   static activeAnnotations: (editor: PortableTextEditor) => PortableTextObject[]
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveAnnotation(...))
+   * ```
+   */
   static isAnnotationActive: (
     editor: PortableTextEditor,
     annotationType: PortableTextObject['_type'],
   ) => boolean
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'annotation.add',
+   *  annotation: {
+   *    name: '...',
+   *    value: {...},
+   *  }
+   * })
+   * ```
+   */
   static addAnnotation: <
     TSchemaType extends {
       name: string
@@ -19525,6 +19560,17 @@ export declare class PortableTextEditor extends Component<
       [prop: string]: unknown
     },
   ) => AddedAnnotationPaths | undefined
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'blur',
+   * })
+   * ```
+   */
   static blur: (editor: PortableTextEditor) => void
   static delete: (
     editor: PortableTextEditor,
@@ -19547,28 +19593,150 @@ export declare class PortableTextEditor extends Component<
     ),
     Path | undefined,
   ]
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'focus',
+   * })
+   * ```
+   */
   static focus: (editor: PortableTextEditor) => void
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const focusBlock = useEditorSelector(editor, selectors.getFocusBlock)
+   * ```
+   */
   static focusBlock: (
     editor: PortableTextEditor,
   ) => PortableTextBlock | undefined
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const focusChild = useEditorSelector(editor, selectors.getFocusChild)
+   * ```
+   */
   static focusChild: (
     editor: PortableTextEditor,
   ) => PortableTextChild | undefined
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const selection = useEditorSelector(editor, selectors.getSelection)
+   * ```
+   */
   static getSelection: (editor: PortableTextEditor) => EditorSelection
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const value = useEditorSelector(editor, selectors.getValue)
+   * ```
+   */
   static getValue: (
     editor: PortableTextEditor,
   ) => PortableTextBlock[] | undefined
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveStyle(...))
+   * ```
+   */
   static hasBlockStyle: (
     editor: PortableTextEditor,
     blockStyle: string,
   ) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveListItem(...))
+   * ```
+   */
   static hasListStyle: (
     editor: PortableTextEditor,
     listStyle: string,
   ) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isSelectionCollapsed = useEditorSelector(editor, selectors.isSelectionCollapsed)
+   * ```
+   */
   static isCollapsedSelection: (editor: PortableTextEditor) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isSelectionExpanded = useEditorSelector(editor, selectors.isSelectionExpanded)
+   * ```
+   */
   static isExpandedSelection: (editor: PortableTextEditor) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveDecorator(...))
+   * ```
+   */
   static isMarkActive: (editor: PortableTextEditor, mark: string) => boolean
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.span',
+   *  text: '...',
+   *  annotations: [{name: '...', value: {...}}],
+   *  decorators: ['...'],
+   * })
+   * editor.send({
+   *  type: 'insert.inline object',
+   *  inlineObject: {
+   *    name: '...',
+   *    value: {...},
+   *  },
+   * })
+   * ```
+   */
   static insertChild: <
     TSchemaType extends {
       name: string
@@ -19580,6 +19748,22 @@ export declare class PortableTextEditor extends Component<
       [prop: string]: unknown
     },
   ) => Path | undefined
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.block object',
+   *  blockObject: {
+   *    name: '...',
+   *    value: {...},
+   *  },
+   *  placement: 'auto' | 'after' | 'before',
+   * })
+   * ```
+   */
   static insertBlock: <
     TSchemaType extends {
       name: string
@@ -19591,6 +19775,17 @@ export declare class PortableTextEditor extends Component<
       [prop: string]: unknown
     },
   ) => Path | undefined
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.break',
+   * })
+   * ```
+   */
   static insertBreak: (editor: PortableTextEditor) => void
   static isVoid: (
     editor: PortableTextEditor,
@@ -19598,10 +19793,36 @@ export declare class PortableTextEditor extends Component<
   ) => boolean
   static isObjectPath: (_editor: PortableTextEditor, path: Path) => boolean
   static marks: (editor: PortableTextEditor) => string[]
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'select',
+   *  selection: {...},
+   * })
+   * ```
+   */
   static select: (
     editor: PortableTextEditor,
     selection: EditorSelection | null,
   ) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'annotation.remove',
+   *  annotation: {
+   *    name: '...',
+   *  },
+   * })
+   * ```
+   */
   static removeAnnotation: <
     TSchemaType extends {
       name: string
@@ -19610,11 +19831,47 @@ export declare class PortableTextEditor extends Component<
     editor: PortableTextEditor,
     type: TSchemaType,
   ) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'style.toggle',
+   *  style: '...',
+   * })
+   * ```
+   */
   static toggleBlockStyle: (
     editor: PortableTextEditor,
     blockStyle: string,
   ) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'list item.toggle',
+   *  listItem: '...',
+   * })
+   * ```
+   */
   static toggleList: (editor: PortableTextEditor, listStyle: string) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'decorator.toggle',
+   *  decorator: '...',
+   * })
+   * ```
+   */
   static toggleMark: (editor: PortableTextEditor, mark: string) => void
   static getFragment: (
     editor: PortableTextEditor,

package/lib/index.d.ts

@@ -19509,11 +19509,46 @@ export declare class PortableTextEditor extends Component<
   componentDidUpdate(prevProps: PortableTextEditorProps): void
   setEditable: (editable: EditableAPI) => void
   render(): JSX.Element
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.getActiveAnnotations)
+   * ```
+   */
   static activeAnnotations: (editor: PortableTextEditor) => PortableTextObject[]
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveAnnotation(...))
+   * ```
+   */
   static isAnnotationActive: (
     editor: PortableTextEditor,
     annotationType: PortableTextObject['_type'],
   ) => boolean
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'annotation.add',
+   *  annotation: {
+   *    name: '...',
+   *    value: {...},
+   *  }
+   * })
+   * ```
+   */
   static addAnnotation: <
     TSchemaType extends {
       name: string
@@ -19525,6 +19560,17 @@ export declare class PortableTextEditor extends Component<
       [prop: string]: unknown
     },
   ) => AddedAnnotationPaths | undefined
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'blur',
+   * })
+   * ```
+   */
   static blur: (editor: PortableTextEditor) => void
   static delete: (
     editor: PortableTextEditor,
@@ -19547,28 +19593,150 @@ export declare class PortableTextEditor extends Component<
     ),
     Path | undefined,
   ]
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'focus',
+   * })
+   * ```
+   */
   static focus: (editor: PortableTextEditor) => void
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const focusBlock = useEditorSelector(editor, selectors.getFocusBlock)
+   * ```
+   */
   static focusBlock: (
     editor: PortableTextEditor,
   ) => PortableTextBlock | undefined
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const focusChild = useEditorSelector(editor, selectors.getFocusChild)
+   * ```
+   */
   static focusChild: (
     editor: PortableTextEditor,
   ) => PortableTextChild | undefined
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const selection = useEditorSelector(editor, selectors.getSelection)
+   * ```
+   */
   static getSelection: (editor: PortableTextEditor) => EditorSelection
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const value = useEditorSelector(editor, selectors.getValue)
+   * ```
+   */
   static getValue: (
     editor: PortableTextEditor,
   ) => PortableTextBlock[] | undefined
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveStyle(...))
+   * ```
+   */
   static hasBlockStyle: (
     editor: PortableTextEditor,
     blockStyle: string,
   ) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveListItem(...))
+   * ```
+   */
   static hasListStyle: (
     editor: PortableTextEditor,
     listStyle: string,
   ) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isSelectionCollapsed = useEditorSelector(editor, selectors.isSelectionCollapsed)
+   * ```
+   */
   static isCollapsedSelection: (editor: PortableTextEditor) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isSelectionExpanded = useEditorSelector(editor, selectors.isSelectionExpanded)
+   * ```
+   */
   static isExpandedSelection: (editor: PortableTextEditor) => boolean
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveDecorator(...))
+   * ```
+   */
   static isMarkActive: (editor: PortableTextEditor, mark: string) => boolean
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.span',
+   *  text: '...',
+   *  annotations: [{name: '...', value: {...}}],
+   *  decorators: ['...'],
+   * })
+   * editor.send({
+   *  type: 'insert.inline object',
+   *  inlineObject: {
+   *    name: '...',
+   *    value: {...},
+   *  },
+   * })
+   * ```
+   */
   static insertChild: <
     TSchemaType extends {
       name: string
@@ -19580,6 +19748,22 @@ export declare class PortableTextEditor extends Component<
       [prop: string]: unknown
     },
   ) => Path | undefined
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.block object',
+   *  blockObject: {
+   *    name: '...',
+   *    value: {...},
+   *  },
+   *  placement: 'auto' | 'after' | 'before',
+   * })
+   * ```
+   */
   static insertBlock: <
     TSchemaType extends {
       name: string
@@ -19591,6 +19775,17 @@ export declare class PortableTextEditor extends Component<
       [prop: string]: unknown
     },
   ) => Path | undefined
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.break',
+   * })
+   * ```
+   */
   static insertBreak: (editor: PortableTextEditor) => void
   static isVoid: (
     editor: PortableTextEditor,
@@ -19598,10 +19793,36 @@ export declare class PortableTextEditor extends Component<
   ) => boolean
   static isObjectPath: (_editor: PortableTextEditor, path: Path) => boolean
   static marks: (editor: PortableTextEditor) => string[]
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'select',
+   *  selection: {...},
+   * })
+   * ```
+   */
   static select: (
     editor: PortableTextEditor,
     selection: EditorSelection | null,
   ) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'annotation.remove',
+   *  annotation: {
+   *    name: '...',
+   *  },
+   * })
+   * ```
+   */
   static removeAnnotation: <
     TSchemaType extends {
       name: string
@@ -19610,11 +19831,47 @@ export declare class PortableTextEditor extends Component<
     editor: PortableTextEditor,
     type: TSchemaType,
   ) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'style.toggle',
+   *  style: '...',
+   * })
+   * ```
+   */
   static toggleBlockStyle: (
     editor: PortableTextEditor,
     blockStyle: string,
   ) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'list item.toggle',
+   *  listItem: '...',
+   * })
+   * ```
+   */
   static toggleList: (editor: PortableTextEditor, listStyle: string) => void
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'decorator.toggle',
+   *  decorator: '...',
+   * })
+   * ```
+   */
   static toggleMark: (editor: PortableTextEditor, mark: string) => void
   static getFragment: (
     editor: PortableTextEditor,