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

sanity-io · Oct 9, 2023 · 355f3f3 · 355f3f3
1 parent 1a58ed8
commit 355f3f3
Show file tree

Hide file tree

Showing 11 changed files with 472 additions and 74 deletions.
diff --git a/packages/@sanity/types/src/schema/definition/type/block.ts b/packages/@sanity/types/src/schema/definition/type/block.ts
@@ -54,8 +54,11 @@ export interface BlockDecoratorDefinition {
 
 /**
  * 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
  * {
@@ -79,6 +82,29 @@ export interface BlockDecoratorDefinition {
  *   ]
  * }
  * ```
+ * @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

diff --git a/packages/sanity/src/core/components/previews/types.ts b/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

diff --git a/packages/sanity/src/core/form/FormBuilderContext.ts b/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,

diff --git a/packages/sanity/src/core/form/inputs/PortableText/PortableTextInput.tsx b/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 {

diff --git a/packages/sanity/src/core/form/types/_transitional.ts b/packages/sanity/src/core/form/types/_transitional.ts
@@ -14,18 +14,20 @@ import {FieldProps} from './fieldProps'
 import {ItemProps} from './itemProps'
 
 /**
- * Export `PortableTextMarker` so it can be used to build custom Portable Text markers.
+ * Function for rendering custom block markers
  *
- * @beta
+ * @public
  * @hidden
- * @deprecated - use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
+ * @deprecated use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
  */
 export type RenderCustomMarkers = (markers: PortableTextMarker[]) => React.ReactNode
 
 /**
+ * Props for rendering block actions
  *
+ * @public
  * @hidden
- * @beta
+ * @deprecated use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
  */
 export interface RenderBlockActionsProps {
   block: PortableTextBlock
@@ -36,18 +38,20 @@ export interface RenderBlockActionsProps {
 }
 
 /**
+ * Function for rendering custom block actions
  *
+ * @public
  * @hidden
- * @beta
+ * @deprecated use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
  */
 export type RenderBlockActionsCallback = (props: RenderBlockActionsProps) => React.ReactNode
 
 /**
  * A generic marker for attaching metadata to specific nodes of the Portable Text input.
  *
- * @beta
+ * @public
  * @hidden
- * @deprecated - use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
+ * @deprecated use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
  * @param type - a type name for this marker
  * @param data - some data connected to this marker
  * @param path - the path to the Portable Text content connected to this marker
@@ -59,18 +63,11 @@ export interface PortableTextMarker {
 }
 
 /**
+ * Component for rendering custom block markers
  *
+ * @public
  * @hidden
- * @beta
- */
-export type FormBuilderArrayFunctionComponent = React.ComponentType<
-  ArrayInputFunctionsProps<unknown, ArraySchemaType>
->
-
-/**
- *
- * @hidden
- * @beta
+ * @deprecated use `renderBlock`, `renderInlineBlock`, `renderAnnotation` interfaces instead
  */
 export type FormBuilderCustomMarkersComponent = React.ComponentType<{markers: PortableTextMarker[]}>