From e21a591483c52bc23577c14602485570dc01bd8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Hamburger=20Gr=C3=B8ngaard?= Date: Thu, 30 Jan 2025 16:16:55 +0100 Subject: [PATCH] fix: add deprecation messages to `PortableTextEditor` methods --- .../editor/src/editor/PortableTextEditor.tsx | 289 +++++++++++++++++- 1 file changed, 288 insertions(+), 1 deletion(-) diff --git a/packages/editor/src/editor/PortableTextEditor.tsx b/packages/editor/src/editor/PortableTextEditor.tsx index 61fa80cb6..26addb06f 100644 --- a/packages/editor/src/editor/PortableTextEditor.tsx +++ b/packages/editor/src/editor/PortableTextEditor.tsx @@ -261,12 +261,32 @@ export class PortableTextEditor extends Component< ) } - // Static API methods + /** + * @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[] => { return editor && editor.editable ? editor.editable.activeAnnotations() : [] } + + /** + * @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'], @@ -275,60 +295,224 @@ export class PortableTextEditor extends Component< ? editor.editable.isAnnotationActive(annotationType) : false } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'annotation.add', + * annotation: { + * name: '...', + * value: {...}, + * } + * }) + * ``` + */ static addAnnotation = ( editor: PortableTextEditor, type: TSchemaType, value?: {[prop: string]: unknown}, ): AddedAnnotationPaths | undefined => editor.editable?.addAnnotation(type, value) + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'blur', + * }) + * ``` + */ static blur = (editor: PortableTextEditor): void => { debug('Host blurred') editor.editable?.blur() } + static delete = ( editor: PortableTextEditor, selection: EditorSelection, options?: EditableAPIDeleteOptions, ) => editor.editable?.delete(selection, options) + static findDOMNode = ( editor: PortableTextEditor, element: PortableTextBlock | PortableTextChild, ) => { return editor.editable?.findDOMNode(element) } + static findByPath = (editor: PortableTextEditor, path: Path) => { return editor.editable?.findByPath(path) || [] } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'focus', + * }) + * ``` + */ static focus = (editor: PortableTextEditor): void => { debug('Host requesting focus') editor.editable?.focus() } + + /** + * @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) => { return editor.editable?.focusBlock() } + + /** + * @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 => { return editor.editable?.focusChild() } + + /** + * @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) => { return editor.editable ? editor.editable.getSelection() : null } + + /** + * @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) => { return editor.editable?.getValue() } + + /** + * @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) => { return editor.editable?.hasBlockStyle(blockStyle) } + + /** + * @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) => { return editor.editable?.hasListStyle(listStyle) } + + /** + * @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) => editor.editable?.isCollapsedSelection() + + /** + * @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) => editor.editable?.isExpandedSelection() + + /** + * @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) => editor.editable?.isMarkActive(mark) + + /** + * @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 = ( editor: PortableTextEditor, type: TSchemaType, @@ -337,6 +521,23 @@ export class PortableTextEditor extends Component< debug(`Host inserting child`) return editor.editable?.insertChild(type, value) } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'insert.block object', + * blockObject: { + * name: '...', + * value: {...}, + * }, + * placement: 'auto' | 'after' | 'before', + * }) + * ``` + */ static insertBlock = ( editor: PortableTextEditor, type: TSchemaType, @@ -344,24 +545,52 @@ export class PortableTextEditor extends Component< ): Path | undefined => { return editor.editable?.insertBlock(type, value) } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'insert.break', + * }) + * ``` + */ static insertBreak = (editor: PortableTextEditor): void => { return editor.editable?.insertBreak() } + static isVoid = ( editor: PortableTextEditor, element: PortableTextBlock | PortableTextChild, ) => { return editor.editable?.isVoid(element) } + static isObjectPath = (_editor: PortableTextEditor, path: Path): boolean => { if (!path || !Array.isArray(path)) return false const isChildObjectEditPath = path.length > 3 && path[1] === 'children' const isBlockObjectEditPath = path.length > 1 && path[1] !== 'children' return isBlockObjectEditPath || isChildObjectEditPath } + static marks = (editor: PortableTextEditor) => { return editor.editable?.marks() } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'select', + * selection: {...}, + * }) + * ``` + */ static select = ( editor: PortableTextEditor, selection: EditorSelection | null, @@ -369,10 +598,38 @@ export class PortableTextEditor extends Component< debug(`Host setting selection`, selection) editor.editable?.select(selection) } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'annotation.remove', + * annotation: { + * name: '...', + * }, + * }) + * ``` + */ static removeAnnotation = ( editor: PortableTextEditor, type: TSchemaType, ) => editor.editable?.removeAnnotation(type) + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'style.toggle', + * style: '...', + * }) + * ``` + */ static toggleBlockStyle = ( editor: PortableTextEditor, blockStyle: string, @@ -380,27 +637,57 @@ export class PortableTextEditor extends Component< debug(`Host is toggling block style`) return editor.editable?.toggleBlockStyle(blockStyle) } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'list item.toggle', + * listItem: '...', + * }) + * ``` + */ static toggleList = (editor: PortableTextEditor, listStyle: string): void => { return editor.editable?.toggleList(listStyle) } + + /** + * @deprecated + * Use `editor.send(...)` instead + * + * ``` + * const editor = useEditor() + * editor.send({ + * type: 'decorator.toggle', + * decorator: '...', + * }) + * ``` + */ static toggleMark = (editor: PortableTextEditor, mark: string): void => { debug(`Host toggling mark`, mark) editor.editable?.toggleMark(mark) } + static getFragment = ( editor: PortableTextEditor, ): PortableTextBlock[] | undefined => { debug(`Host getting fragment`) return editor.editable?.getFragment() } + static undo = (editor: PortableTextEditor): void => { debug('Host undoing') editor.editable?.undo() } + static redo = (editor: PortableTextEditor): void => { debug('Host redoing') editor.editable?.redo() } + static isSelectionsOverlapping = ( editor: PortableTextEditor, selectionA: EditorSelection,