refactor(richtext-slate): deprecate slate editor (#14536)

The old Slate-based rich text editor is no longer receiving updates and
will be fully removed in Payload 4.0.

To give developers an early heads-up and encourage migration, this PR
marks richtext-slate as deprecated in preparation for its removal. We
recommend switching to Lexical as the supported rich text editor moving
forward.

Author: AlessioGr

docs/rich-text/overview.mdx

@@ -9,8 +9,8 @@ title: Rich Text Editor
 <Banner type="success">
 
 This documentation is about our new editor, based on Lexical (Meta's rich text editor). The previous default
-editor was based on Slate and is still supported. You can read [its documentation](/docs/rich-text/slate),
-or the optional [migration guide](/docs/rich-text/migration) to migrate from Slate to Lexical (recommended).
+editor, based on Slate, has been deprecated and will be removed in 4.0. You can read [its documentation](/docs/rich-text/slate),
+or the [migration guide](/docs/rich-text/migration) to migrate from Slate to Lexical (recommended).
 
 </Banner>
 

docs/rich-text/slate.mdx

@@ -2,15 +2,13 @@
 title: Slate Editor
 label: Slate (legacy)
 order: 100
-desc: The Slate editor has been supported by Payload since beta. It's very powerful and stores content as JSON, which unlocks a ton of power.
-keywords: slatejs, slate, rich text, editor, headless cms
+desc: The Slate editor is our old rich text editor and will be removed in 4.0.
+keywords: slatejs, slate
 ---
 
 <Banner type="warning">
 
-The [default Payload editor](/docs/rich-text/overview) is currently based on Lexical. This documentation
-is about our old Slate-based editor. You can continue using it because it is still supported, or you can
-see the optional [migration guide](/docs/rich-text/migration) to migrate from Slate to Lexical (recommended).
+The [default Payload editor](/docs/rich-text/overview) is currently based on Lexical. This documentation is about our old Slate-based editor which has been deprecated and will be removed in 4.0. We recommend [migrating to Lexical](/docs/rich-text/migration) instead.
 
 </Banner>
 

packages/richtext-slate/src/cell/rscEntry.tsx

@@ -5,6 +5,9 @@ import { Link } from '@payloadcms/ui'
 import { formatAdminURL } from 'payload/shared'
 import React from 'react'
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export const RscEntrySlateCell: React.FC<
   {
     i18n: I18nClient

packages/richtext-slate/src/field/rscEntry.tsx

@@ -19,6 +19,10 @@ import { elements as elementTypes } from '../field/elements/index.js'
 import { defaultLeaves as leafTypes } from '../field/leaves/index.js'
 import { linkFieldsSchemaPath } from './elements/link/shared.js'
 import { uploadFieldsSchemaPath } from './elements/upload/shared.js'
+
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export const RscEntrySlateField: React.FC<
   {
     args: AdapterArguments

packages/richtext-slate/src/index.tsx

@@ -11,6 +11,9 @@ import { transformExtraFields } from './field/elements/link/utilities.js'
 import { defaultLeaves as leafTypes } from './field/leaves/index.js'
 import { getGenerateSchemaMap } from './generateSchemaMap.js'
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export function slateEditor(
   args: AdapterArguments,
 ): RichTextAdapterProvider<any[], AdapterArguments, any> {

packages/richtext-slate/src/types.ts

@@ -7,31 +7,56 @@ import type {
 } from 'payload'
 import type { Editor } from 'slate'
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type TextNode = { [x: string]: unknown; text: string }
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type ElementNode = { children: (ElementNode | TextNode)[]; type?: string }
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export function nodeIsTextNode(node: ElementNode | TextNode): node is TextNode {
   return 'text' in node
 }
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type RichTextPluginComponent = PayloadComponent
+
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type RichTextPlugin = (editor: Editor) => Editor
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type RichTextCustomElement = {
   Button?: PayloadComponent
   Element: PayloadComponent
   name: string
   plugins?: RichTextPluginComponent[]
 }
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type RichTextCustomLeaf = {
   Button: PayloadComponent
   Leaf: PayloadComponent
   name: string
   plugins?: RichTextPluginComponent[]
 }
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type RichTextElement =
   | 'blockquote'
   | 'h1'
@@ -49,6 +74,10 @@ export type RichTextElement =
   | 'ul'
   | 'upload'
   | RichTextCustomElement
+
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type RichTextLeaf =
   | 'bold'
   | 'code'
@@ -57,6 +86,9 @@ export type RichTextLeaf =
   | 'underline'
   | RichTextCustomLeaf
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type AdapterArguments = {
   admin?: {
     elements?: RichTextElement[]
@@ -77,6 +109,9 @@ export type AdapterArguments = {
   }
 }
 
+/**
+ * @deprecated - slate will be removed in 4.0. Please [migrate our new, lexical-based rich text editor](https://payloadcms.com/docs/rich-text/migration#migrating-from-slate).
+ */
 export type SlateFieldProps = {
   componentMap: {
     [x: string]: ClientField[] | React.ReactNode