From 5233f358fccb53a50d0f0f9f1ebfd5920e918ca5 Mon Sep 17 00:00:00 2001
From: Per-Kristian Nordnes <per.kristian.nordnes@gmail.com>
Date: Tue, 24 Oct 2023 16:21:34 +0200
Subject: [PATCH] doc(form): add doc and example for components extention of
 block type (#5059)

---
 .../core/form/types/definitionExtensions.ts   | 30 +++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/packages/sanity/src/core/form/types/definitionExtensions.ts b/packages/sanity/src/core/form/types/definitionExtensions.ts
index 2958f6efaab..24fd59a88b3 100644
--- a/packages/sanity/src/core/form/types/definitionExtensions.ts
+++ b/packages/sanity/src/core/form/types/definitionExtensions.ts
@@ -315,9 +315,35 @@ declare module '@sanity/types' {
 
   export interface BlockDefinition {
     /**
+     * Components for the block schema type
      *
-     * @hidden
-     * @beta
+     * @public
+     * @remarks - This only applies to the block text type, and not block object types (like images).
+     * - Don't render arbitrary text nodes inside regular text blocks, as this will confuse the editor with
+     * what is editable text and not. Make sure to wrap all nodes which are NOT part of the edited text inside a
+     * container with `contentEditable={false}` and with `style={{userSelection: 'none'}}` so that
+     * the editor can distinguish between editable text and non-editable text.
+     * @example Example of custom block component with delete button next to it that removes the block.
+     * ```ts
+     * {
+     *   block: (blockProps) => {
+     *     return (
+     *       <Flex>
+     *         <Box flex={1}>{blockProps.renderDefault(blockProps)}</Box>
+     *         <Box contentEditable={false} style={{userSelect: 'none'}}>
+     *           <Button
+     *             icon={TrashIcon}
+     *             onClick={(event) => {
+     *               event.preventDefault()
+     *               blockProps.onRemove()
+     *              }}
+     *             />
+     *         </Box>
+     *       </Flex>
+     *     )
+     *   },
+     * },
+     * ```
      */
     components?: {
       block?: ComponentType<BlockProps>