@portabletext/editor 7.10.19 → 7.12.0

package/README.md

@@ -17,7 +17,7 @@ In order to set up an editor you'll need to:
 
 - Create a schema that defines the rich text and block content elements.
 - Create a toolbar to toggle and insert these elements.
-- Write render functions to style and display each element type in the editor.
+- Set up rendering for each element type in the editor, including text blocks and inline formatting.
 - Render the editor.
 
 Check out the [Portable Text Playground](../../apps/playground/) for a comprehensive example of the editor in action.
@@ -41,16 +41,14 @@ Next, in your app or the component you're building, import `EditorProvider`, `Po
 ```tsx
 // App.tsx
 import {
+  defineDecorator,
   defineSchema,
+  defineTextBlock,
   EditorProvider,
   PortableTextEditable,
 } from '@portabletext/editor'
-import type {
-  PortableTextBlock,
-  RenderDecoratorFunction,
-  RenderStyleFunction,
-} from '@portabletext/editor'
-import {EventListenerPlugin} from '@portabletext/editor/plugins'
+import type {PortableTextBlock} from '@portabletext/editor'
+import {EventListenerPlugin, NodePlugin} from '@portabletext/editor/plugins'
 ```
 
 ### Define the schema
@@ -103,16 +101,14 @@ Add `useState` from React, then scaffold out a basic application component. For
 ```tsx
 // app.tsx
 import {
+  defineDecorator,
   defineSchema,
+  defineTextBlock,
   EditorProvider,
   PortableTextEditable,
 } from '@portabletext/editor'
-import type {
-  PortableTextBlock,
-  RenderDecoratorFunction,
-  RenderStyleFunction,
-} from '@portabletext/editor'
-import {EventListenerPlugin} from '@portabletext/editor/plugins'
+import type {PortableTextBlock} from '@portabletext/editor'
+import {EventListenerPlugin, NodePlugin} from '@portabletext/editor/plugins'
 import {useState} from 'react'
 
 const schemaDefinition = defineSchema({
@@ -154,77 +150,77 @@ export default App
 
 Include the `App` component in your application and run it. You should see an outlined editor that accepts text, but doesn't do much else.
 
-### Create render functions for schema elements
+### Set up rendering for schema elements
 
-At this point the PTE only has a schema, but it doesn't know how to render anything. Fix that by creating render functions for each property in the schema.
+At this point the editor renders every text block as plain text, whatever its style. Fix that by registering a `defineTextBlock` node for the text blocks and `defineDecorator`/`defineAnnotation` nodes for the marks. If your editor still renders through the deprecated `renderStyle`, `renderBlock`, `renderListItem`, `renderChild`, `renderDecorator`, and `renderAnnotation` props, see the [migration guide](https://www.portabletext.org/editor/guides/migrate-render-props/) to move to node registrations instead.
 
-Start by creating a render function for styles.
+Start by registering the text block render with `defineTextBlock`. The editor dispatches every text block to this callback. Your callback owns the block's wrapper element, so spread `props.attributes` on the outermost element you return, and use the block's `style` to pick the element.
 
 ```tsx
-const renderStyle: RenderStyleFunction = (props) => {
-  if (props.schemaType.value === 'h1') {
-    return <h1>{props.children}</h1>
-  }
-  if (props.schemaType.value === 'h2') {
-    return <h2>{props.children}</h2>
-  }
-  if (props.schemaType.value === 'h3') {
-    return <h3>{props.children}</h3>
-  }
-  if (props.schemaType.value === 'blockquote') {
-    return <blockquote>{props.children}</blockquote>
-  }
-  return <>{props.children}</>
-}
+const textBlock = defineTextBlock({
+  type: 'block',
+  render: (props) => {
+    if (props.node.style === 'h1') {
+      return <h1 {...props.attributes}>{props.children}</h1>
+    }
+    if (props.node.style === 'h2') {
+      return <h2 {...props.attributes}>{props.children}</h2>
+    }
+    if (props.node.style === 'h3') {
+      return <h3 {...props.attributes}>{props.children}</h3>
+    }
+    if (props.node.style === 'blockquote') {
+      return <blockquote {...props.attributes}>{props.children}</blockquote>
+    }
+    return <div {...props.attributes}>{props.children}</div>
+  },
+})
 ```
 
-Render functions all follow the same format.
+Marks (decorators and annotations) join the same `nodes` array. Registrations all follow the same shape.
 
 - They take in props and return JSX elements.
-- They use the schema to make decisions.
-- They return JSX and pass `children` as a fallback.
+- They decide what to render from the registration's `type` and the node itself, not a separate schema-type argument.
+- They return JSX that renders `children` somewhere inside it, the editable content the registration wraps.
 
 With this in mind, continue for the remaining schema types.
 
-Create a render function for decorators.
+Register a decorator with `defineDecorator`, one per decorator name.
 
 ```tsx
-const renderDecorator: RenderDecoratorFunction = (props) => {
-  if (props.value === 'strong') {
-    return <strong>{props.children}</strong>
-  }
-  if (props.value === 'em') {
-    return <em>{props.children}</em>
-  }
-  if (props.value === 'underline') {
-    return <u>{props.children}</u>
-  }
-  return <>{props.children}</>
-}
+const strong = defineDecorator({
+  type: 'strong',
+  render: ({children}) => <strong>{children}</strong>,
+})
+const em = defineDecorator({
+  type: 'em',
+  render: ({children}) => <em>{children}</em>,
+})
+const underline = defineDecorator({
+  type: 'underline',
+  render: ({children}) => <u>{children}</u>,
+})
+
+const nodes = [textBlock, strong, em, underline]
 ```
 
 > [!NOTE]
-> By default, text is rendered as an inline `span` element in the editor. While most render functions return a fragment (`<>`) as the fallback, make sure block level elements return blocks, like `<div>` elements.
-
-Update the `PortableTextEditable` with each corresponding function to attach them to the editor.
+> By default, text is rendered as an inline `span` element in the editor. A decorator's render can pass `children` through unwrapped, but the registered text block render must return a block-level element, like a `<div>`.
 
-You may notice that we skipped a few types from the schema. Declare these inline in the configuration, like in the code below. You can learn more about [customizing the render functions](https://www.portabletext.org/editor/guides/custom-rendering/) in the documentation.
+Mount every registration through one `NodePlugin`, inside the `EditorProvider`. Keep the `nodes` array itself at module scope, as above: a fresh array on every render would make `NodePlugin` unregister and re-register on every keystroke. You can learn more about [customizing the rendering](https://www.portabletext.org/editor/guides/custom-rendering/) in the documentation.
 
 ```tsx
-<PortableTextEditable
-  style={{border: '1px solid black', padding: '0.5em'}}
-  renderStyle={renderStyle}
-  renderDecorator={renderDecorator}
-  renderBlock={(props) => <div>{props.children}</div>}
-  renderListItem={(props) => <>{props.children}</>}
-/>
+<>
+  <NodePlugin nodes={nodes} />
+  <PortableTextEditable style={{border: '1px solid black', padding: '0.5em'}} />
+</>
 ```
 
 Before you can see if anything changed, you need a way to interact with the editor.
 
 ### Create a toolbar
 
-A toolbar is a collection of UI elements for interacting with the editor. The PTE library gives you the necessary hooks to create a toolbar however you like. Learn more about [creating your own toolbar](https://www.portabletext.org/editor/guides/customize-toolbar/) in the documentation.
+A toolbar is a collection of UI elements for interacting with the editor. [`@portabletext/toolbar`](../toolbar/) provides ready-made hooks (`useStyleSelector`, `useDecoratorButton`, and more) for common toolbar UI; see the [toolbar customization guide](https://www.portabletext.org/editor/guides/customize-toolbar/) to use them. What follows here is the lower-level approach: sending events to the editor directly.
 
 1. Create a `Toolbar` component in the same file.
 2. Import the `useEditor` hook, and declare an `editor` constant in the component.
@@ -293,7 +289,7 @@ The `useEditor` hook gives you access to the active editor. `send` lets you send
 
 ### Bring it all together
 
-With render functions created and a toolbar in place, you can fully render the editor. Add the `Toolbar` inside the `EditorProvider`.
+With the registrations created and a toolbar in place, you can fully render the editor. Add the `Toolbar` inside the `EditorProvider`.
 
 ```tsx
 // App.tsx
@@ -319,12 +315,9 @@ function App() {
           }}
         />
         <Toolbar />
+        <NodePlugin nodes={nodes} />
         <PortableTextEditable
           style={{border: '1px solid black', padding: '0.5em'}}
-          renderStyle={renderStyle}
-          renderDecorator={renderDecorator}
-          renderBlock={(props) => <div>{props.children}</div>}
-          renderListItem={(props) => <>{props.children}</>}
         />
       </EditorProvider>
     </>