doc(sanity): add TS-doc for block content related types (#4674)

* chore(core/form/inputs): remove outdated workshop case

Remove this non-working workshop left over from v2

* refactor(core/form/inputs): deprecate block marker callbacks and support

* doc(types): add ts doc comments to block schema types

* doc(sanity): add TS-doc for block content related types

packages/@sanity/types/src/schema/definition/type/block.ts

@@ -5,47 +5,238 @@ import {ArrayOfType} from './array'
 import {BaseSchemaDefinition} from './common'
 import {ObjectDefinition} from './object'
 
-/** @public */
+/**
+ * Schema options for a Block schema definition
+ * @public */
 export interface BlockOptions {
+  /**
+   * Turn on or off the builtin browser spellchecking. Default is on.
+   */
   spellCheck?: boolean
 }
 
 /** @public */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface BlockRule extends RuleDef<BlockRule, any[]> {}
 
-/** @public */
+/**
+ * Schema definition for text block decorators.
+ *
+ * @public
+ * @example The default set of decorators
+ * ```ts
+ * {
+ *   name: 'blockContent',
+ *   title: 'Content',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'block',
+ *       marks: {
+ *         decorators: [
+ *           {title: 'Strong', value: 'strong'},
+ *           {title: 'Emphasis', value: 'em'},
+ *           {title: 'Underline', value: 'underline'},
+ *           {title: 'Strike', value: 'strike'},
+ *           {title: 'Code', value: 'code'},
+ *         ]
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
 export interface BlockDecoratorDefinition {
   title: string
   value: string
   icon?: ReactNode | ComponentType
 }
 
-/** @public */
+/**
+ * Schema definition for a text block style.
+ * A text block may have a block style like 'header', 'normal', 'lead'
+ * attached to it, which is stored on the `.style` property for that block.
+ *
+ * @public
+ * @remarks The first defined style will become the default style.´´
+ * @example The default set of styles
+ * ```ts
+ * {
+ *   name: 'blockContent',
+ *   title: 'Content',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'block',
+ *       styles: [
+ *         {title: 'Normal', value: 'normal'},
+ *         {title: 'H1', value: 'h1'},
+ *         {title: 'H2', value: 'h2'},
+ *         {title: 'H3', value: 'h3'},
+ *         {title: 'H4', value: 'h4'},
+ *         {title: 'H5', value: 'h5'},
+ *         {title: 'H6', value: 'h6'},
+ *         {title: 'Quote', value: 'blockquote'}
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ * @example Example of defining a block type with custom styles and render components.
+ * ```ts
+ * defineArrayMember({
+ *   type: 'block',
+ *   styles: [
+ *     {
+ *       title: 'Paragraph',
+ *       value: 'paragraph',
+ *       component: ParagraphStyle,
+ *     },
+ *     {
+ *       title: 'Lead',
+ *       value: 'lead',
+ *       component: LeadStyle,
+ *     },
+ *     {
+ *       title: 'Heading',
+ *       value: 'heading',
+ *       component: HeadingStyle,
+ *     },
+ *   ],
+ * })
+ * ```
+ */
 export interface BlockStyleDefinition {
   title: string
   value: string
 }
 
-/** @public */
+/**
+ * Schema definition for a text block list style.
+ *
+ * @public
+ * @example The defaults lists
+ * ```ts
+ * {
+ *   name: 'blockContent',
+ *   title: 'Content',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'block',
+ *       lists: [
+ *         {title: 'Bullet', value: 'bullet'},
+ *         {title: 'Number', value: 'number'},
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
 export interface BlockListDefinition {
   title: string
   value: string
   icon?: ReactNode | ComponentType
 }
 
-/** @public */
+/**
+ * Schema definition for a text block annotation object.
+ *
+ * @public
+ * @example The default link annotation
+ * ```ts
+ * {
+ *   name: 'blockContent',
+ *   title: 'Content',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'block',
+ *       marks: {
+ *         annotations: [
+ *           {
+ *             type: 'object',
+ *             name: 'link',
+ *             fields: [
+ *               {
+ *                 type: 'string',
+ *                 name: 'href',
+ *               },
+ *             ],
+ *           },
+ *         ]
+ *       },
+ *     }
+ *   ]
+ * }
+ * ```
+ */
 export interface BlockAnnotationDefinition extends ObjectDefinition {
   icon?: ReactNode | ComponentType
 }
 
-/** @public */
+/**
+ * Schema definition for text block marks (decorators and annotations).
+ *
+ * @public */
 export interface BlockMarksDefinition {
   decorators?: BlockDecoratorDefinition[]
   annotations?: ArrayOfType<'object' | 'reference'>[]
 }
 
-/** @public */
+/**
+ * Schema definition for text blocks.
+ *
+ * @public
+ * @example the default block definition
+ * ```ts
+ * {
+ *   name: 'blockContent',
+ *   title: 'Content',
+ *   type: 'array',
+ *   of: [
+ *     {
+ *       type: 'block',
+ *       marks: {
+ *         decorators: [
+ *           {title: 'Strong', value: 'strong'},
+ *           {title: 'Emphasis', value: 'em'},
+ *           {title: 'Underline', value: 'underline'},
+ *           {title: 'Strike', value: 'strike'},
+ *           {title: 'Code', value: 'code'},
+ *         ],
+ *         annotations: [
+ *           {
+ *             type: 'object',
+ *             name: 'link',
+ *             fields: [
+ *               {
+ *                 type: 'string',
+ *                 name: 'href',
+ *               },
+ *             ],
+ *           },
+ *         ]
+ *       },
+ *       styles: [
+ *         {title: 'Normal', value: 'normal'},
+ *         {title: 'H1', value: 'h1'},
+ *         {title: 'H2', value: 'h2'},
+ *         {title: 'H3', value: 'h3'},
+ *         {title: 'H4', value: 'h4'},
+ *         {title: 'H5', value: 'h5'},
+ *         {title: 'H6', value: 'h6'},
+ *         {title: 'Quote', value: 'blockquote'}
+ *       ],
+ *       lists: [
+ *         {title: 'Bullet', value: 'bullet'},
+ *         {title: 'Number', value: 'number'},
+ *       ],
+ *     },
+ *   ]
+ * }
+ * ```
+ */
 export interface BlockDefinition extends BaseSchemaDefinition {
   type: 'block'
   styles?: BlockStyleDefinition[]

packages/sanity/src/core/components/previews/types.ts

@@ -24,7 +24,7 @@ export type PreviewLayoutKey = GeneralPreviewLayoutKey | PortableTextPreviewLayo
 
 /**
  * @hidden
- * @beta
+ * @public
  */
 export interface PreviewMediaDimensions {
   aspect?: number

packages/sanity/src/core/form/FormBuilderContext.ts

@@ -3,7 +3,6 @@ import {createContext} from 'react'
 import {DocumentFieldAction} from '../config'
 import {PatchChannel} from './patch'
 import {
-  FormBuilderArrayFunctionComponent,
   FormBuilderCustomMarkersComponent,
   FormBuilderFilterFieldFn,
   FormBuilderMarkersComponent,

packages/sanity/src/core/form/inputs/PortableText/BlockActions.tsx

@@ -3,7 +3,7 @@ import React, {useMemo} from 'react'
 import styled from 'styled-components'
 import {PortableTextBlock} from '@sanity/types'
 import {PatchEvent} from '../../patch'
-import {RenderBlockActionsCallback, RenderBlockActionsProps} from './types'
+import {RenderBlockActionsCallback, RenderBlockActionsProps} from '../../types/_transitional'
 import {createInsertCallback, createSetCallback, createUnsetCallback} from './callbacks'
 
 interface BlockActionsProps {

packages/sanity/src/core/form/inputs/PortableText/Compositor.tsx

@@ -14,11 +14,11 @@ import {ArrayOfObjectsInputProps, RenderCustomMarkers} from '../../types'
 import {ActivateOnFocus} from '../../components/ActivateOnFocus/ActivateOnFocus'
 import {EMPTY_ARRAY} from '../../../util'
 import {ChangeIndicator} from '../../../changeIndicators'
+import {RenderBlockActionsCallback} from '../../types/_transitional'
 import {Annotation} from './object/Annotation'
 import {BlockObject} from './object/BlockObject'
 import {InlineObject} from './object/InlineObject'
 import {TextBlock} from './text'
-import {RenderBlockActionsCallback} from './types'
 import {Editor} from './Editor'
 import {ExpandedLayer, Root} from './Compositor.styles'
 import {useHotkeys} from './hooks/useHotKeys'

packages/sanity/src/core/form/inputs/PortableText/PortableTextInput.tsx

@@ -45,10 +45,16 @@ export interface PortableTextMemberItem {
 }
 
 /**
- * The root Portable Text Input component
+ * Input component for editing block content
+ * ({@link https://github.com/portabletext/portabletext | Portable Text}) in the Sanity Studio.
  *
- * @hidden
- * @beta
+ * Supports multi-user real-time block content editing on larger documents.
+ *
+ * This component can be configured and customized extensively.
+ * {@link https://www.sanity.io/docs/portable-text-features | Go to the documentation for more details}.
+ *
+ * @public
+ * @param props - {@link PortableTextInputProps} component props.
  */
 export function PortableTextInput(props: PortableTextInputProps) {
   const {

packages/sanity/src/core/form/inputs/PortableText/__workshop__/_common/TestInput.tsx

@@ -2,7 +2,7 @@ import {ArraySchemaType, Path, ValidationMarker, PortableTextBlock} from '@sanit
 import React, {useCallback, useEffect, useMemo, useState} from 'react'
 import {PortableTextMarker, RenderCustomMarkers} from '../../../../types'
 import {applyAll} from '../../../../patch/simplePatch'
-import {RenderBlockActionsCallback} from '../../types'
+import {RenderBlockActionsCallback} from '../../../../types/_transitional'
 import {createPatchChannel} from '../../../../patch/PatchChannel'
 import {useSource} from '../../../../../studio'
 

packages/sanity/src/core/form/inputs/PortableText/__workshop__/customSchema/blockActions.tsx

@@ -3,7 +3,7 @@ import React, {memo, useCallback} from 'react'
 import {CopyIcon} from '@sanity/icons'
 import {keyGenerator} from '@sanity/portable-text-editor'
 import {PortableTextBlock, PortableTextTextBlock} from '@sanity/types'
-import {RenderBlockActionsCallback} from '../../types'
+import {RenderBlockActionsCallback} from '../../../../types/_transitional'
 
 const BlockActions = memo(function BlockActions(props: {
   block: PortableTextBlock