Generic Value and Editor (#1500)

* fix

* fix

* Create gorgeous-buttons-care.md

* fix

* fix

* fix

* fix

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

* refactor

.changeset/combobox-minor.md

@@ -0,0 +1,10 @@
+---
+"@udecode/plate-combobox": minor
+---
+
+updated deps:
+```bash
+"@udecode/zustood": "^1.1.1",
+"downshift": "^6.1.7",
+"zustand": "^3.7.2"
+```

.changeset/csv-minor.md

@@ -0,0 +1,8 @@
+---
+"@udecode/plate-serializer-csv": patch
+---
+
+updated deps:
+```bash
+"papaparse": "^5.3.2"
+```

.changeset/dnd-minor.md

@@ -0,0 +1,11 @@
+---
+"@udecode/plate-ui-dnd": minor
+---
+
+updated deps:
+```bash
+"@react-hook/merged-ref": "^1.3.2",
+"@tippyjs/react": "^4.2.6",
+"react-dnd": "^15.1.2",
+"react-dnd-html5-backend": "^15.1.3"
+```

.changeset/docx-minor.md

@@ -0,0 +1,8 @@
+---
+"@udecode/plate-serializer-docx": patch
+---
+
+updated deps:
+```bash
+"validator": "^13.7.0"
+```

.changeset/gorgeous-buttons-care.md

@@ -0,0 +1,5 @@
+---
+"@udecode/plate-core": patch
+---
+
+fix: Type alias 'TDescendant' circularly references itself

.changeset/image-minor.md

@@ -0,0 +1,8 @@
+---
+"@udecode/plate-ui-image": patch
+---
+
+updated deps:
+```bash
+"re-resizable": "^6.9.9"
+```

.changeset/juice-minor.md

@@ -0,0 +1,8 @@
+---
+"@udecode/plate-juice": patch
+---
+
+updated deps:
+```bash
+"juice": "^8.0.0"
+```

.changeset/major.md

@@ -0,0 +1,87 @@
+---
+"@udecode/plate-core": major
+---
+
+Thanks @ianstormtaylor for the initial work on https://github.com/ianstormtaylor/slate/pull/4177. 
+
+This release includes major changes to plate and slate types:
+- Changing the `TEditor` type to be `TEditor<V>` where `V` represents the "value" being edited by Slate. In the most generic editor, `V` would be equivalent to `TElement[]` (since that is what is accepted as children of the editor). But in a custom editor, you might have `TEditor<Array<Paragraph | Quote>>`.
+- Other `TEditor`-and-`TNode`-related methods have been also made generic, so for example if you use `getLeafNode(editor, path)` it knows that the return value is a `TText` node. But more specifically, it knows that it is the text node of the type you've defined in your custom elements (with any marks you've defined).
+- This replaces the declaration merging approach, and provides some benefits. One of the drawbacks to declaration merging was that it was impossible to know whether you were dealing with an "unknown" or "known" element, since the underlying type was changed. Similarly, having two editors on the page with different schemas wasn't possible to represent. Hopefully this approach with generics will be able to smoothly replace the declaration merging approach. (While being easy to migrate to, since you can pass those same custom element definitions into `TEditor` still.)
+
+Those Slate types should be replaced by the new types:
+- `Editor` -> `TEditor<V extends Value>`
+- `ReactEditor` -> `TReactEditor<V extends Value>`
+- `HistoryEditor` -> `THistoryEditor<V extends Value>`
+- `EditableProps` -> `TEditableProps<V extends Value>`
+- `Node` -> `TNode`
+- `Element` -> `TElement`
+- `Text` -> `TText`
+
+Those Slate functions should be replaced by the new typed ones:
+- `createEditor` -> `createTEditor`
+- `withReact` -> `withTReact`
+- `withHistory` -> `withTHistory`
+- As the new editor type is not matching the slate ones, all `Transforms`, `Editor`, `Node`, `Element`, `Text`, `HistoryEditor`, `ReactEditor` functions should be replaced.
+  - The whole API has been typed into Plate core. See `https://github.com/udecode/plate/packages/core/src/slate` 
+
+Generic types:
+- `<T = {}>` could be used to extend the editor type. It is now replaced by `<E extends PlateEditor<V> = PlateEditor<V>>` to customize the whole editor type.
+- When the plugin type is customizable, these generics are used: `<P = {}, V extends Value = Value, E extends PlateEditor<V> = PlateEditor<V>>`, where `P` is the plugin options type.
+- `Editor` functions are using `<V extends Value>` generic, where `V` can be a custom editor value type used in `PlateEditor<V>`.
+- `Editor` functions returning a node are using `<N extends ENode<V>, V extends Value = Value>` generics, where `N` can be a custom returned node type.
+- `Editor` callbacks (e.g. a plugin option) are using `<V extends Value, E extends PlateEditor<V> = PlateEditor<V>>` generics, where `E` can be a custom editor type.
+- `Node` functions returning a node are using `<N extends Node, R extends TNode = TNode>` generics.
+- These generics are used by `<V extends Value, K extends keyof EMarks<V>>`: `getMarks`, `isMarkActive`, `removeMark`, `setMarks`, `ToggleMarkPlugin`, `addMark`, `removeEditorMark`
+- `WithOverride` is a special type case as it can return a new editor type:
+```tsx
+// before
+export type WithOverride<T = {}, P = {}> = (
+  editor: PlateEditor<T>,
+  plugin: WithPlatePlugin<T, P>
+) => PlateEditor<T>;
+
+// after - where E is the Editor type (input), and EE is the Extended Editor type (output)
+export type WithOverride<
+  P = {},
+  V extends Value = Value,
+  E extends PlateEditor<V> = PlateEditor<V>,
+  EE extends E = E
+> = (editor: E, plugin: WithPlatePlugin<P, V, E>) => EE;
+```
+
+
+
+Renamed:
+- `getAbove` -> `getAboveNode`
+- `getParent` -> `getParentNode`
+- `getText` -> `getEditorString`
+- `getLastNode` -> `getLastNodeByLevel`
+- `getPointBefore` -> `getPointBeforeLocation`
+- `getNodes` -> `getNodeEntries`
+- `getNodes` -> `getNodeEntries`
+- `isStart` -> `isStartPoint`
+- `isEnd` -> `isEndPoint`
+
+Removing node props types in favor of element types (same props + extends `TElement`). You can use `TNodeProps` to get the node data (props).
+- `LinkNodeData` -> `TLinkElement`
+- `ImageNodeData` -> `TImageElement`
+- `TableNodeData` -> `TTableElement`
+- `MentionNodeData` -> `TMentionElement`
+- `MentionNode` -> `TMentionElement`
+- `MentionInputNodeData` -> `TMentionInputElement`
+- `MentionInputNode` -> `TMentionInputElement`
+- `CodeBlockNodeData` -> `TCodeBlockElement`
+- `MediaEmbedNodeData` -> `TMediaEmbedElement`
+- `TodoListItemNodeData` -> `TTodoListItemElement`
+- `ExcalidrawNodeData` -> `TExcalidrawElement`
+
+Utils:
+- `match` signature change:
+```
+<T extends TNode>(
+  obj: T,
+  path: TPath,
+  predicate?: Predicate<T>
+)
+```

.changeset/md-minor.md

@@ -0,0 +1,9 @@
+---
+"@udecode/plate-serializer-md": minor
+---
+
+updated deps:
+```bash
+"remark-slate": "^1.8.6",
+"unified": "^9.2.1"
+```

.changeset/minor.md

@@ -0,0 +1,48 @@
+---
+"@udecode/plate-core": minor
+---
+
+Transforms:
+- `insertElements`: `insertNodes` where node type is `TElement` 
+- `setElements`: `setNodes` where node type is `TElement`
+
+Types: 
+- General type improvements to all plate packages.
+- `Value = TElement[]`: Default value of an editor.
+- `TNode = TEditor<Value> | TElement | TText`
+- `TElement`: Note that `type: string` is included as it's the standard in Plate.
+- `TText`: it now accepts unknown props.
+- `TDescendant = TElement | TText`
+- `TAncestor = TEditor<Value> | TElement`
+- `ENode<V extends Value>`: Node of an editor value
+- `EElement<V extends Value>`: Element of an editor value
+- `EText<V extends Value>`: Text of an editor value
+- `EDescendant<V extends Value>`: Descendant of an editor value
+- `EAncestor<V extends Value>`: Ancestor of an editor value
+- `NodeOf<N extends TNode>`: A utility type to get all the node types from a root node type.
+- `ElementOf<N extends TNode>`: A utility type to get all the element nodes type from a root node.
+- `TextOf<N extends TNode>`: A utility type to get all the text node types from a root node type.
+- `DescendantOf<N extends TNode>`: A utility type to get all the descendant node types from a root node type.
+- `ChildOf<N extends TNode, I extends number = number>`: A utility type to get the child node types from a root node type.
+- `AncestorOf<N extends TNode>`: A utility type to get all the ancestor node types from a root node type.
+- `ValueOf<E extends TEditor<Value>>`: A helper type for getting the value of an editor.
+- `MarksOf<N extends TNode>`: A utility type to get all the mark types from a root node type.
+- `EMarks<V extends Value>`
+- `TNodeProps<N extends TNode>`: Convenience type for returning the props of a node.
+- `TNodeEntry<N extends TNode = TNode>`
+- `ENodeEntry<V extends Value>`: Node entry from an editor.
+- `TElementEntry<N extends TNode = TNode>`: Element entry from a node.
+- `TTextEntry<N extends TNode = TNode>`: Text node entry from a node.
+- `ETextEntry<V extends Value>`: Text node entry of a value.
+- `TAncestorEntry<N extends TNode = TNode>`: Ancestor entry from a node.
+- `EAncestorEntry<V extends Value>`: Ancestor entry from an editor.
+- `TDescendantEntry<N extends TNode = TNode>`: Descendant entry from a node.
+- `TOperation`: operation types now accept unknown props.
+
+Updated deps:
+```bash
+"@udecode/zustood": "^1.1.1",
+"jotai": "^1.6.6",
+"lodash": "^4.17.21",
+"zustand": "^3.7.2"
+```

.changeset/popover-minor.md

@@ -0,0 +1,8 @@
+---
+"@udecode/plate-ui-popover": patch
+---
+
+updated deps:
+```bash
+"@tippyjs/react": "^4.2.6",
+```

.changeset/popper-minor.md

@@ -0,0 +1,9 @@
+---
+"@udecode/plate-ui-popper": patch
+---
+
+updated deps:
+```bash
+"@popperjs/core": "^2.11.5",
+"react-popper": "^2.3.0"
+```

.changeset/table-minor.md

@@ -0,0 +1,9 @@
+---
+"@udecode/plate-ui-table": minor
+---
+
+updated deps:
+```bash
+"jotai": "^1.6.6",
+"re-resizable": "^6.9.9"
+```

.changeset/toolbar-minor.md

@@ -0,0 +1,10 @@
+---
+"@udecode/plate-ui-toolbar": patch
+---
+
+updated deps:
+```bash
+"@tippyjs/react": "^4.2.6",
+"react-popper": "^2.3.0",
+"react-use": "^17.3.2"
+```

docs/docs/examples/huge-document.mdx

@@ -32,7 +32,7 @@ title: Huge Document
   const WithoutPlate = () => {
     const [value, setValue] = useState(initialValue);
     const renderElement = useCallback((p) => <Element {...p} />, []);
-    const editor = useMemo(() => withReact(createEditor()), []);
+    const editor = useMemo(() => withReact(createTEditor(), []);
 
     return (
       <Slate

docs/docs/getting-started/basic-editor.mdx

@@ -58,6 +58,7 @@ Let's set the initial value of the editor to one block of text.
   // Stored in VALUES.plainText
   const initialValue = [
     {
+      type: 'p',
       children: [
         {
           text:

docs/docs/getting-started/basic-plugins.mdx

@@ -12,7 +12,7 @@ The following undeclared variables and types are imported from `@udecode/plate`.
 This guide will use existing plugins.
 
 If you don't provide any plugins to `Plate` as done in the previous section, 
-`createReactPlugin()`, `createHistoryPlugin()` and other core plugins will be used as default.
+`createTReactPlugin()`, `createTHistoryPlugin()` and other core plugins will be used as default.
 
 ### Plugins
 

docs/docs/guides/Plate.md

@@ -30,7 +30,7 @@ title: Plate
 ### `editor`
 
 - Controlled `editor`.
-- Default is `createEditor()`.
+- Default is `createTEditor()`.
 
 ### `enabled`
 

docs/docs/guides/plugins.mdx

@@ -95,7 +95,7 @@ const createSubscriptPlugin = createPluginFactory<ToggleMarkPlugin>({
 ```ts
 // Example
 const createReactPlugin = {
-  withOverrides: withReact
+  withOverrides: withTReact
 };
 ```
 
@@ -255,7 +255,7 @@ type PlatePluginInsertDataOptions = {
   dataTransfer: DataTransfer;
 };
 
-type PlatePluginInsertData = {
+type PlatePluginInsertData<V extends Value> = {
   /**
    * Format to get data. Example data types are text/plain and text/uri-list.
    */
@@ -271,7 +271,7 @@ type PlatePluginInsertData = {
    */
   getFragment?: (
     options: PlatePluginInsertDataOptions
-  ) => TDescendant[] | undefined;
+  ) => EDescendant<V>[] | undefined;
 
   // injected
 
@@ -282,7 +282,7 @@ type PlatePluginInsertData = {
    * @return if true, the next handlers will be skipped.
    */
   preInsert?: (
-    fragment: TDescendant[],
+    fragment: EDescendant<V>[],
     options: PlatePluginInsertDataOptions
   ) => HandlerReturnType;
 
@@ -298,9 +298,9 @@ type PlatePluginInsertData = {
    * Transform the fragment to insert.
    */
   transformFragment?: (
-    fragment: TDescendant[],
+    fragment: EDescendant<V>[],
     options: PlatePluginInsertDataOptions
-  ) => TDescendant[];
+  ) => EDescendant<V>[];
 }
 ```
 
@@ -349,8 +349,8 @@ This property extends most `textarea` handlers like:
 
 The type of each handler is:
 ```ts
-type Handler<T = {}, P = {}> = (
-  editor: PlateEditor<T>, plugin: WithPlatePlugin<T, P>
+type Handler<P = {}, V extends Value, E extends PlateEditor<V> = PlateEditor<V>> = (
+  editor: E, plugin: WithPlatePlugin<P, V, E>
 ) => (event: Event) => boolean | void;
 ```
 
@@ -402,19 +402,19 @@ type Handler<T = {}, P = {}> = (
    * Transform the className.
    * @default clsx(className, classNames[value])
    */
-  transformClassName?: (options: TransformOptions) => any;
+  transformClassName?: (options: TransformOptions<V>) => any;
 
   /**
    * Transform the node value for the style or className.
    * @default nodeValue
    */
-  transformNodeValue?: (options: TransformOptions) => any;
+  transformNodeValue?: (options: TransformOptions<V>) => any;
 
   /**
    * Transform the style.
    * @default { ...style, [styleKey]: value }
    */
-  transformStyle?: (options: TransformOptions) => CSSProperties;
+  transformStyle?: (options: TransformOptions<V>) => CSSProperties;
 
   /**
    * List of supported node values.
@@ -509,9 +509,9 @@ createIndentPlugin({
 - Type is:
 ```tsx
 (
-  editor: PlateEditor<T>,
-  plugin: WithPlatePlugin<T, P>
-) => Partial<PlatePlugin<T, P>>
+  editor: E,
+  plugin: WithPlatePlugin<P, V, E>
+) => Partial<PlatePlugin<P, V, E>> | void;
 ```
 
 ### `type`