refactor(portable-text-editor): improve typings

packages/@sanity/portable-text-editor/src/editor/PortableTextEditor.tsx

@@ -46,24 +46,63 @@ function bufferUntil<T>(emitWhen: (currentBuffer: T[]) => boolean): OperatorFunc
     })
 }
 
-export type PortableTextEditorProps = {
-  keyGenerator?: () => string
-  maxBlocks?: number | string
+/**
+ * Props for the PortableTextEditor component
+ *
+ * @public
+ */
+export interface PortableTextEditorProps {
+  /**
+   * Function that gets called when the editor changes the value
+   */
   onChange: (change: EditorChange) => void
-  incomingPatches$?: PatchObservable
-  readOnly?: boolean
+
+  /**
+   * (Compiled) schema type for the portable text field
+   */
   type: ArraySchemaType<PortableTextBlock>
+
+  /**
+   * Maximum number of blocks to allow within the editor
+   */
+  maxBlocks?: number | string
+
+  /**
+   * Whether or not the editor should be in read-only mode
+   */
+  readOnly?: boolean
+
+  /**
+   * The current value of the portable text field
+   */
   value?: PortableTextBlock[]
+
+  /**
+   * Function used to generate keys for array items (`_key`)
+   */
+  keyGenerator?: () => string
+
+  /**
+   * Observable of incoming patches - used for undo/redo operations,
+   * adjusting editor selections on concurrent editing and similar
+   */
+  incomingPatches$?: PatchObservable
 }
 
-type State = {
+/**
+ * @internal
+ */
+export interface PortableTextEditorState {
   invalidValueResolution: InvalidValueResolution | null
   selection: EditorSelection // This state is only used to force the selection context to update.
   hasPendingPatches: boolean
 }
 
 // The PT editor's public API
-export class PortableTextEditor extends React.Component<PortableTextEditorProps, State> {
+export class PortableTextEditor extends React.Component<
+  PortableTextEditorProps,
+  PortableTextEditorState
+> {
   static activeAnnotations = (editor: PortableTextEditor): PortableTextBlock[] => {
     return editor && editor.editable ? editor.editable.activeAnnotations() : []
   }
@@ -204,7 +243,7 @@ export class PortableTextEditor extends React.Component<PortableTextEditorProps,
     this.keyGenerator = props.keyGenerator || defaultKeyGenerator
 
     // Validate the Portable Text value
-    let state: State = {
+    let state: PortableTextEditorState = {
       invalidValueResolution: null,
       selection: null,
       hasPendingPatches: false,
@@ -247,7 +286,7 @@ export class PortableTextEditor extends React.Component<PortableTextEditorProps,
     this.changeSubscription.unsubscribe()
   }
 
-  componentDidUpdate(prevProps: PortableTextEditorProps, prevState: State) {
+  componentDidUpdate(prevProps: PortableTextEditorProps, prevState: PortableTextEditorState) {
     if (this.props.readOnly !== prevProps.readOnly) {
       this.readOnly = this.props.readOnly || false
       this.slateInstance.readOnly = this.readOnly

packages/@sanity/portable-text-editor/src/index.ts

@@ -1,5 +1,5 @@
 export {PortableTextEditor, defaultKeyGenerator as keyGenerator} from './editor/PortableTextEditor'
-export type {PortableTextEditorProps} from './editor/PortableTextEditor'
+export type {PortableTextEditorProps, PortableTextEditorState} from './editor/PortableTextEditor'
 export * from './types/editor'
 export * from './types/portableText'
 export * from './types/patch'

packages/@sanity/portable-text-editor/src/types/editor.ts

@@ -84,87 +84,96 @@ export interface PortableTextSlateEditor extends ReactEditor {
   maxBlocks: number | undefined
 
   /**
-   * Increments selected list items levels, or decrements them if @reverse is true.
+   * Increments selected list items levels, or decrements them if `reverse` is true.
    *
-   * @param {boolean} reverse
-   * @returns {boolean} True if anything was incremented in the selection
+   * @param reverse - if true, decrement instead of incrementing
+   * @returns True if anything was incremented in the selection
    */
   pteIncrementBlockLevels: (reverse?: boolean) => boolean
+
   /**
    * Toggle selected blocks as listItem
    *
-   * @param {string} listStyle
+   * @param listStyle - Style of list item to toggle on/off
    */
   pteToggleListItem: (listStyle: string) => void
+
   /**
    * Set selected block as listItem
    *
-   * @param {string} listStyle
+   * @param listStyle - Style of list item to set
    */
   pteSetListItem: (listStyle: string) => void
+
   /**
    * Unset selected block as listItem
    *
-   * @param {string} listStyle
+   * @param listStyle - Style of list item to unset
    */
   pteUnsetListItem: (listStyle: string) => void
+
   /**
    * Ends a list
    *
-   * @returns {boolean} True if a list was ended in the selection
+   * @returns True if a list was ended in the selection
    */
   pteEndList: () => boolean
+
   /**
    * Toggle marks in the selection
    *
-   * @param {string} mark
+   * @param mark - Mark to toggle on/off
    */
   pteToggleMark: (mark: string) => void
+
   /**
-   * Teset if a mark is active in the current selection
+   * Test if a mark is active in the current selection
    *
-   * @param {string} mark
+   * @param mark - Mark to check whether or not is active
    */
   pteIsMarkActive: (mark: string) => boolean
+
   /**
    * Toggle the selected block style
    *
-   * @param {string} style The style name
+   * @param style - The style name
    *
    */
   pteToggleBlockStyle: (style: string) => void
+
   /**
    * Test if the current selection has a certain block style
    *
-   * @param {string} style The style name
+   * @param style - The style name
    *
    */
   pteHasBlockStyle: (style: string) => boolean
+
   /**
    * Test if the current selection has a certain list style
    *
-   * @param {string} listStyle The liststyle name
+   * @param listStyle - Style name to check whether or not the selection has
    *
    */
   pteHasListStyle: (style: string) => boolean
+
   /**
    * Try to expand the current selection to a word
-   *
    */
   pteExpandToWord: () => void
+
   /**
    * Use hotkeys
-   *
    */
   pteWithHotKeys: (event: React.KeyboardEvent<HTMLDivElement>) => void
+
   /**
    * Undo
-   *
    */
   undo: () => void
+
   /**
    * Redo
-   *
    */
   redo: () => void
 }