From 30c1546a3901f9536daf7cebcf315bcc6d9ccb52 Mon Sep 17 00:00:00 2001 From: zbeyens Date: Sun, 17 Sep 2023 23:27:50 +0200 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .changeset/core-major.md | 3 +- apps/www/content/docs/accessing-editor.mdx | 4 +- apps/www/content/docs/api/core.mdx | 67 ++++--- apps/www/content/docs/api/core/plate.mdx | 208 +++++++++------------ apps/www/content/docs/api/core/store.mdx | 12 +- apps/www/content/docs/getting-started.mdx | 10 +- 6 files changed, 135 insertions(+), 169 deletions(-) diff --git a/.changeset/core-major.md b/.changeset/core-major.md index 8a4c1eb866..9f06cacc8a 100644 --- a/.changeset/core-major.md +++ b/.changeset/core-major.md @@ -26,7 +26,6 @@ - [**Breaking**] Remove `firstChildren` prop from `PlateContent`. Render instead these components before `PlateContent`. - [**Breaking**] Remove `editableRef` prop from `PlateContent`. Use `ref` instead. - [**Breaking**] Remove `withPlateProvider`. -- [**Breaking**] Rename `usePlate` to `usePlateActions`. - [**Breaking**] Rename `usePlateEditorRef` to `useEditorRef`. - [**Breaking**] Rename `usePlateEditorState` to `useEditorState`. - [**Breaking**] Rename `usePlateReadOnly` to `useEditorReadOnly`. This hook can be used below `Plate` while `useReadOnly` can only be used in node components. @@ -37,4 +36,4 @@ - Add `useEditorVersion` hook. Version incremented on each editor change. - Add `useSelectionVersion` hook. Version incremented on each selection change. - Fix `editor.reset` should now reset the editor without mutating the ref so it does not remount `PlateContent`. Default is using `resetEditor`. If you need to replace the editor ref, use `useReplaceEditor`. -- [Type] Remove generic from `TEditableProps`, `RenderElementFn` +- [Type] Remove generic from `TEditableProps`, `RenderElementFn`, `RenderAfterEditable` diff --git a/apps/www/content/docs/accessing-editor.mdx b/apps/www/content/docs/accessing-editor.mdx index 0105d9a927..bdf1112aa5 100644 --- a/apps/www/content/docs/accessing-editor.mdx +++ b/apps/www/content/docs/accessing-editor.mdx @@ -102,9 +102,9 @@ const CustomEffect = () => { export default () => ( - - + + ); ``` diff --git a/apps/www/content/docs/api/core.mdx b/apps/www/content/docs/api/core.mdx index 7ee8262071..802c66b0ac 100644 --- a/apps/www/content/docs/api/core.mdx +++ b/apps/www/content/docs/api/core.mdx @@ -315,7 +315,7 @@ Hook to get the element from a node component. The plugin key. -- **Default:** `SCOPE_ELEMENT`. +- **Default:** the closest element key. @@ -327,44 +327,15 @@ The value of the element as a TElement. ### useEditorRef -Get the Slate editor reference. +Get the Slate editor reference without re-rendering. - Does not re-render on editor change. -- Does not support nested editors. -- Should be used inside `Plate`. - - - -A `PlateEditor` object, which is the Slate editor. - - - -### useEditorState - -Get the Slate editor reference. - -- Re-renders on editor change. -- Does not support nested editors. -- Should be used inside `Plate`. - - - -A `PlateEditor` object, which is the Slate editor. - - - -### useEditorRef - -Get the Slate editor reference. - -- Does not re-render on editor change. -- Supports nested editors. - Should be used inside `Plate`. - Note the reference does not change when the editor changes. - The ID of the plate editor. Useful only when nesting editors. + The ID of the plate editor. Useful only when nesting editors. Default is using the closest editor id. @@ -375,7 +346,7 @@ A `PlateEditor` object, which is the Slate editor. ### useEditorState -Get the Slate editor reference which . +Get the Slate editor reference with re-rendering. - Re-renders on editor change. - Supports nested editors. @@ -384,7 +355,7 @@ Get the Slate editor reference which . - The ID of the plate editor. + The ID of the plate editor. Default is using the closest editor id. @@ -410,7 +381,7 @@ The `readOnly` state of the editor. ### useEditorSelection -Get the editor's selection which is updated on each editor change. +Get the editor's selection. Memoized so it does not re-render if the range is the same. @@ -419,6 +390,28 @@ Get the editor's selection which is updated on each editor change. The current selection in the editor. +### useEditorVersion + +Get the version of the editor value. That version is incremented on each editor change. + + + + The ID of the plate editor. + + +The current version of the editor value. + +### useSelectionVersion + +Get the version of the editor selection. That version is incremented on each selection change (the range being different). + + + + The ID of the plate editor. + + +The current version of the editor selection. + ## Core plugins ### createDeserializeAstPlugin @@ -449,6 +442,10 @@ Creates a plugin that merges and registers all the inline types and void types f Creates a plugin that overrides the default `insertData` function in the editor, which is called when data is being pasted or dragged into the editor. +### createLengthPlugin + +Creates a plugin that enforces a maximum length for the editor. + ### createNodeFactoryPlugin Creates a plugin that overrides the default `blockFactory` and `childrenFactory` functions in the editor. These functions are used to generate the default blocks and children for the editor. diff --git a/apps/www/content/docs/api/core/plate.mdx b/apps/www/content/docs/api/core/plate.mdx index f961433d62..26adfdcdf5 100644 --- a/apps/www/content/docs/api/core/plate.mdx +++ b/apps/www/content/docs/api/core/plate.mdx @@ -3,9 +3,9 @@ title: Plate description: API reference for Plate component. --- -`Plate` is the core component rendering the editor. It takes care of computing and passing `Slate` and `Editable` props from the `plugins`. +`Plate` is the root component loading the editor state into a store provider. -`PlateProvider` is the component loading the Plate store. Any component rendered below has access to the Plate store. If `Plate` does not find any parent `PlateProvider`, it will take care of creating one (provider-less mode). +`PlateContent` is the component that renders the editor. ## Plate Props @@ -13,17 +13,17 @@ description: API reference for Plate component. A unique ID to store the editor state by ID. This is mandatory when nesting **`Plate`** instances but optional otherwise. -- **Default:** `'main'`. +- **Default:** `'plate'`. -The last component rendered inside **`Slate`**, after **`Editable`**. Use **`firstChildren`** to render the first children. +Children components have access to the plate store. -See [decorate](#decorate). +See [decorations](https://docs.slatejs.org/concepts/09-rendering#decorations). @@ -38,189 +38,153 @@ Can be **`true`** to disable all core plugins, an object to selectively disable + - + + +A controlled **`editor`**. + +- **Default:** **`createPlateEditor({ id, plugins, disableCorePlugins })`** + + + + +An uncontrolled **`editor`** ref. + +- **Default:** **`createPlateEditor({ id, plugins, disableCorePlugins })`** + + + + +Initial editor value. -Props for the **`Editable`** component. Extends `TextareaHTMLAttributes`. See [Editable](https://docs.slatejs.org/libraries/slate-react/editable) docs. +- **Default:** **`editor.childrenFactory()`** + + + + +Specifies the maximum number of characters allowed in the editor. - + + + +If **`true`**, normalizes the initial **`editor`** value upon creation. This is useful for applying normalization rules on existing content. + +- **Default:** **`false`** + + + + +Controlled callback called when the editor state changes. - + + +Plate plugins. See [Plugin](/docs/plugin) guide. + + + + +Alias to **`initialValue`**. Stored in the store on each change (**`Editable.onChange`**). To update **`value`** with history support, use **[Slate transforms](https://docs.slatejs.org/concepts/04-transforms)**. To reset **`value`**, use `resetEditor`. + +- **Default:** **`editor.childrenFactory()`** + + + + +## PlateContent Props + +Props for the [Editable](https://docs.slatejs.org/libraries/slate-react/editable) component. Extends `TextareaHTMLAttributes`. + + + + +Custom **`Editable`** node. + +- **Default:** **``** + + + - - - - - - - - - - - - + - - - - - - - -Ref to the **`Editable`** component. [Not yet supported by Slate React](https://github.com/ianstormtaylor/slate/issues/4082). - - - - -A controlled **`editor`**. - -- **Default:** **`createPlateEditor({ id, plugins, disableCorePlugins })`** - - - - -The first children rendered inside **`Slate`**, before **`Editable`**. Use **`children`** instead if you need resolved Slate DOM on the first render. - - - - -Initial editor value. - -- **Default:** **`editor.childrenFactory()`** - - - - -If **`true`**, normalizes the initial **`editor`** value upon creation. This is useful for applying normalization rules on existing content. - -- **Default:** **`false`** - - - - -Controlled callback called when the editor state changes. - - - - -Plate plugins. See [Plugin](/docs/plugin) guide. - - - - -Custom **`Editable`** node. - -- **Default:** **``** - - - - -See [renderElement](#renderelement). - - - - -See [renderLeaf](#renderleaf). - - - - -Alias to **`initialValue`**. Stored in the store on each change (**`Editable.onChange`**). To update **`value`** with history support, use **[Slate transforms](https://docs.slatejs.org/concepts/04-transforms)**. To reset **`value`**, use `useResetPlateEditor`, which will also reset the editor. - -- **Default:** **`editor.childrenFactory()`** - - - - -## PlateProvider Props - -A react component that provides the context for the Plate editor. - -Same props than [PlateProps](#plate-props) excluding: - -- `editableProps` -- `editableRef` -- `firstChildren` -- `renderEditable` - -If used, only the listed props should be set on `Plate`. + ## How Plate Works **`Plate`** computes the **`Slate`** props: **`key`**, **`editor`**, **`onChange`**. -In addition to **`editableProps`**, **`Plate`** computes **`Editable`** props if **`editor`** is defined: +**`Plate`** also computes **`Editable`** props if **`editor`** is defined: ### decorate -This prop integrates **`decorate`** plugins. If a **`decorate`** prop is defined, it will be added. Similarly, if **`editableProps.decorate`** is defined, it will be included as well. +This prop integrates **`decorate`** plugins. If a **`decorate`** prop is defined, it will be added. ### renderElement @@ -230,7 +194,7 @@ When a plugin's **`isElement`** is **`true`** and its **`type`** matches **`prop - **`component`** is used to render the element itself. - **`inject.aboveComponent`** and **`inject.belowComponent`** can inject components above and below **`component`**, respectively. -If no suitable plugin is found for a node type, **`editableProps.renderElement`** is used (if defined). In the absence of this prop, **`DefaultElement`** (a plain **`div`**) is used. +If no suitable plugin is found for a node type, **`renderElement`** prop is used (if defined). In the absence of this prop, **`DefaultElement`** (a plain **`div`**) is used. ### renderLeaf @@ -239,7 +203,7 @@ If a plugin's **`isLeaf`** is **`true`** and its **`type`** matches **`props.lea - **`inject.props`** are used to inject rendering props. - **`component`** is used to render the leaf. -If no plugin is found for a node type, **`editableProps.renderLeaf`** is used (if defined). If this is also not defined, **`DefaultLeaf`** (a plain **`span`**) is used. +If no plugin is found for a node type, **`renderLeaf`** prop is used (if defined). If this is also not defined, **`DefaultLeaf`** (a plain **`span`**) is used. ### Handlers diff --git a/apps/www/content/docs/api/core/store.mdx b/apps/www/content/docs/api/core/store.mdx index 595bef8d15..94181cb543 100644 --- a/apps/www/content/docs/api/core/store.mdx +++ b/apps/www/content/docs/api/core/store.mdx @@ -34,6 +34,12 @@ Slate editor reference. + + +Whether the `PlateContent` is mounted. + + + Whether the editor is read-only. @@ -60,19 +66,19 @@ Value of the `editor`. - + Version incremented on each `editor` change. - + Version incremented on each `editor.selection` change. - + Version incremented when calling `redecorate`. This is a dependency of the `decorate` function. diff --git a/apps/www/content/docs/getting-started.mdx b/apps/www/content/docs/getting-started.mdx index 2d4c48fcf8..0a2e8454a6 100644 --- a/apps/www/content/docs/getting-started.mdx +++ b/apps/www/content/docs/getting-started.mdx @@ -37,9 +37,9 @@ npm install @udecode/plate slate slate-react slate-history slate-hyperscript rea ### Basic Editor -Let's start with a minimal editor setup leveraging **`Plate`** and **`PlateContent`**. +Let's start with a minimal editor setup using **`Plate`** and **`PlateContent`**. -```tsx showLineNumbers {1,3-5,9} +```tsx showLineNumbers {1,5-7} import { Plate } from '@udecode/plate-common'; export default function BasicEditor() { @@ -64,7 +64,7 @@ Simple and straightforward. Try it out: Let's specify the initial content of the editor: a single paragraph. -```tsx showLineNumbers {3-12,18} +```tsx showLineNumbers {3-12,16-18} // ... const initialValue = [ @@ -98,7 +98,7 @@ export default function BasicEditor() { At this stage, it's crucial to monitor editor modifications in order to store the values appropriately. The **`onChange`** prop will serve this purpose. -```tsx showLineNumbers {8-10} +```tsx showLineNumbers {7-9} // ... export default function BasicEditor() { @@ -198,6 +198,6 @@ export default function BasicEditor() { ### That's it! -You can now play around with the Playground and start building your own rich-text editor. +You can now play around with the Playground and start building your own editor.