Customizing the Portable Text editor not working in V3

[shanejones]

https://www.sanity.io/docs/customization

From following the guide lower down the page it seems that you cannot add blockEditor with icon or render as children to decorators anymore.

I inspected the type declaration for this and that shows

export declare interface SpanSchemaType extends Omit<ObjectSchemaType, 'fields'> {
  annotations: (ObjectSchemaType & {
    blockEditor?: {
      icon?: string | ComponentType
      render?: ComponentType
    }
  })[]
  decorators: TitledListValue<string>[]
  fields: [MarksObjectField, TextObjectField]
}

decorators seem to only accept a TitledListValue

export declare interface TitledListValue<V = unknown> {
  _key?: string
  title: string
  value?: V
}

I think this should be the same as the annotations for this to be able to work.

I think we might also need to convert the specific file to .tsx now that we have JSX code being added.

[MarioGiancini]

Overview

@shanejones I've also come across issues in adding Block editor customizations.

The example from the above v2 customization documentation shows adding a custom "highlight" decorator like this:

// RichTextEditor.js
import React from 'react'

const highlightIcon = () => (
  <span style={{ fontWeight: 'bold' }}>H</span>
)
const highlightRender = props => (
  <span style={{ backgroundColor: 'yellow' }}>{props.children}</span>
)

export default {
  name: 'content',
  title: 'Content',
  type: 'array',
  of: [
    {
      type: 'block',
      marks: {
        decorators: [
          { title: 'Strong', value: 'strong' },
          { title: 'Emphasis', value: 'em' },
          { title: 'Code', value: 'code' },
          {
            title: 'Highlight',
            value: 'highlight',
            blockEditor: {
              icon: highlightIcon,
              render: highlightRender
            }
          }
        ]
      }
    }
  ]
}

In this example the custom decorator being:

{
  title: 'Highlight',
  value: 'highlight',
  blockEditor: {
    icon: highlightIcon,
    render: highlightRender
  }
}

Issue 1

Since the new v3 instances are using typescript files (like schemas/post.ts) for schema definitions, the highlightIcon and highlightRender components will produce errors since the typescript file isn't expecting components. So you would either need to change the file type to .tsx (as @shanejones suggested) or import the components from a separate file (perhaps /components/highlight-text.tsx) like:

import { HighlightIcon, HighlightRender } from '../components/highlight-text'

Issue 2

The structure for the DecoratorDefinition is different than the old v2 documentation. Following the type interface declared for marks, decorators should be an optional array of DecoratorDefinition types:

/** @public */
export declare interface MarksDefinition {
  decorators?: DecoratorDefinition[]
  annotations?: (SchemaTypeDefinition | TypeReference)[]
}

And a DecoratorDefinition is:

/** @public */
export declare interface DecoratorDefinition {
  title: string
  value: string
  icon?: ReactNode | ComponentType
  portableText?: {
    icon?: ReactNode | ComponentType
    render?: ComponentType
  }
}

Which is different from the v2 version, since blockEditor has been replaced by portableText.

Issue 3

Even when I place the custom "highlight" icon and render components in a separate .tsx file, import them, and use the DecoratorDefinition interface, I get an error in Studio Desk:

Server Error
Error: SchemaError

Example schema file based off the new v3-ready vercel blog (note: I'm also using Internal Link annotations, which do work):

import { ComposeIcon } from '@sanity/icons'
import { defineType } from 'sanity'

import { HighlightIcon, HighlightRender } from '../components/highlight-text'

export default defineType({
  name: 'post',
  title: 'Post',
  icon: ComposeIcon,
  type: 'document',
  fields: [
    {
      name: 'title',
      title: 'Title',
      type: 'string',
      validation: (Rule) => Rule.required(),
    },
    {
      name: 'slug',
      title: 'Slug',
      type: 'slug',
      options: {
        source: 'title',
        maxLength: 96,
      },
      validation: (Rule) => Rule.required(),
    },
    {
      name: 'content',
      title: 'Content',
      type: 'array',
      of: [
        { 
          type: 'block',
          marks: {
            annotations: [
              {
                name: 'internalLink',
                type: 'object',
                title: 'Internal link',
                icon: ComposeIcon,
                fields: [
                  {
                    name: 'reference',
                    type: 'reference',
                    to: [
                      { type: 'post' },
                      // other types you may want to link to
                    ]
                  }
                ]
              }
            ],
            decorators: [
              // Include normal decorators
              { title: 'Strong', value: 'strong' },
              { title: 'Emphasis', value: 'em' },
              { title: 'Code', value: 'code' },
              { title: 'Underline', value: 'underline' },
              { title: 'Strike', value: 'strike-through' },
              // This doesn't seem to work in v3
              // @see https://www.sanity.io/docs/customization#e6401a8fe843
              {
                title: 'Highlight',
                value: 'highlight',
                icon: HighlightIcon,
                portableText: {
                  icon: HighlightIcon,
                  render: HighlightRender,
                }
              }
            ]
          },
        },
        {
          type: 'image',
          options: {hotspot: true},
          fields: [
            {
              name: 'alt',
              type: 'string',
              title: 'Alt Text',
              options: {
                isHighlighted: true
              }
            },
          ]
        },
        {
          type: 'code',
        },
      ],
      validation: (Rule) => Rule.required(),
    },
    {
      name: 'excerpt',
      title: 'Excerpt',
      type: 'text',
    },
    {
      name: 'coverImage',
      title: 'Cover Image',
      type: 'image',
      options: {
        hotspot: true,
      },
    },
    {
      name: 'publishedAt',
      title: 'Published At',
      type: 'datetime',
    },
    {
      name: 'author',
      title: 'Author',
      type: 'reference',
      to: [{ type: authorType.name }],
    },
  ],
  preview: {
    select: {
      title: 'title',
      author: 'author.name',
      media: 'coverImage',
    },
    prepare(selection) {
      const { author } = selection
      return { ...selection, subtitle: author && `by ${author}` }
    },
  },
})