Custom TypeScript Types (#3835)

This PR adds better TypeScript types into Slate and is based on the proposal here: #3725

* Extend Slate's types like Element and Text

* Supports type discrimination (ie. if an element has type === "table" then we get a reduced set of properties)

* added custom types

* files

* more extensions

* files

* changed fixtures

* changes eslint file

* changed element.children to descendant

* updated types

* more type changes

* changed a lot of typing, still getting building errors

* extended text type in slate-react

* removed type assertions

* Clean up of custom types and a couple uneeded comments.

* Rename headingElement-true.tsx.tsx to headingElement-true.tsx

* moved basetext and baselement

* Update packages/slate/src/interfaces/text.ts

Co-authored-by: Brent Farese <25846953+BrentFarese@users.noreply.github.com>

* Fix some type issues with core functions.

* Clean up text and element files.

* Convert other types to extended types.

* Change the type of editor.marks to the appropriate type.

* Add version 100.0.0 to package.json

* Revert "Add version 100.0.0 to package.json"

This reverts commit 329e44e.

* added custom types

* files

* more extensions

* files

* changed fixtures

* changes eslint file

* changed element.children to descendant

* updated types

* more type changes

* changed a lot of typing, still getting building errors

* extended text type in slate-react

* removed type assertions

* Clean up of custom types and a couple uneeded comments.

* Rename headingElement-true.tsx.tsx to headingElement-true.tsx

* moved basetext and baselement

* Update packages/slate/src/interfaces/text.ts

Co-authored-by: Brent Farese <25846953+BrentFarese@users.noreply.github.com>

* Fix some type issues with core functions.

* Clean up text and element files.

* Convert other types to extended types.

* Change the type of editor.marks to the appropriate type.

* Run linter.

* Remove key:string uknown from the base types.

* Clean up types after removing key:string unknown.

* Lint and prettier fixes.

* Implement custom-types

Co-authored-by: mdmjg <mdj308@nyu.edu>

* added custom types to examples

* reset yarn lock

* added ts to fixtures

* examples custom types

* Working fix

* ts-thesunny-try

* Extract interface types.

* Fix minor return type in create-editor.

* Fix the typing issue with Location having compile time CustomTypes

* Extract types for Transforms.

* Update README.

* Fix dependency on slate-history in slate-react

Co-authored-by: mdmjg <mdj308@nyu.edu>
Co-authored-by: Brent Farese <brentfarese@gmail.com>
Co-authored-by: Brent Farese <25846953+BrentFarese@users.noreply.github.com>
Co-authored-by: Tim Buckley <timothypbuckley@gmail.com>

.eslintrc

@@ -5,7 +5,12 @@
     "prettier/@typescript-eslint",
     "prettier/react"
   ],
-  "plugins": ["@typescript-eslint", "import", "react", "prettier"],
+  "plugins": [
+    "@typescript-eslint",
+    "import",
+    "react",
+    "prettier"
+  ],
   "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "sourceType": "module",
@@ -16,7 +21,12 @@
   },
   "ignorePatterns": ["**/next-env.d.ts"],
   "settings": {
-    "import/extensions": [".js", ".ts", ".jsx", ".tsx"],
+    "import/extensions": [
+      ".js",
+      ".ts",
+      ".jsx",
+      ".tsx"
+    ],
     "react": {
       "version": "detect"
     }
@@ -29,8 +39,16 @@
   },
   "rules": {
     "constructor-super": "error",
-    "dot-notation": ["error", { "allowKeywords": true }],
-    "eqeqeq": ["error", "smart"],
+    "dot-notation": [
+      "error",
+      {
+        "allowKeywords": true
+      }
+    ],
+    "eqeqeq": [
+      "error",
+      "smart"
+    ],
     "import/default": "error",
     "import/export": "error",
     "import/first": "error",
@@ -40,7 +58,9 @@
     "import/no-deprecated": "error",
     "import/no-extraneous-dependencies": [
       "error",
-      { "peerDependencies": true }
+      {
+        "peerDependencies": true
+      }
     ],
     "import/no-mutable-exports": "error",
     "import/no-named-as-default": "error",
@@ -86,18 +106,27 @@
     "no-var": "error",
     "no-void": "error",
     "no-with": "error",
-    "object-shorthand": ["error", "always"],
+    "object-shorthand": [
+      "error",
+      "always"
+    ],
     "prefer-arrow-callback": "error",
     "prefer-const": [
       "error",
-      { "destructuring": "all", "ignoreReadBeforeAssign": true }
+      {
+        "destructuring": "all",
+        "ignoreReadBeforeAssign": true
+      }
     ],
     "prefer-rest-params": "error",
     "prefer-spread": "error",
     "prefer-template": "error",
     "prettier/prettier": "error",
     "radix": "error",
-    "react/jsx-boolean-value": ["error", "never"],
+    "react/jsx-boolean-value": [
+      "error",
+      "never"
+    ],
     "react/jsx-no-duplicate-props": "error",
     "react/jsx-no-target-blank": "error",
     "react/jsx-no-undef": "error",
@@ -112,15 +141,34 @@
     "react/react-in-jsx-scope": "error",
     "react/self-closing-comp": "error",
     "react/sort-prop-types": "error",
-    "spaced-comment": ["error", "always", { "exceptions": ["-"] }],
+    "spaced-comment": [
+      "error",
+      "always",
+      {
+        "exceptions": [
+          "-"
+        ]
+      }
+    ],
     "use-isnan": "error",
     "valid-jsdoc": [
       "error",
-      { "prefer": { "return": "returns" }, "requireReturn": false }
+      {
+        "prefer": {
+          "return": "returns"
+        },
+        "requireReturn": false
+      }
     ],
     "valid-typeof": "error",
-    "yield-star-spacing": ["error", "after"],
-    "yoda": ["error", "never"]
+    "yield-star-spacing": [
+      "error",
+      "after"
+    ],
+    "yoda": [
+      "error",
+      "never"
+    ]
   },
   "overrides": [
     {
@@ -131,4 +179,4 @@
       }
     }
   ]
-}
+}

docs/api/locations.md

@@ -1,6 +1,6 @@
 # Location
 
-The `Location` interface is a union of the ways to refer to a specific location in a Slate document: paths, points or ranges. Methods will often accept a `Location` instead of requiring only a `Path`, `Point` or `Range`. 
+The `Location` interface is a union of the ways to refer to a specific location in a Slate document: paths, points or ranges. Methods will often accept a `Location` instead of requiring only a `Path`, `Point` or `Range`.
 
 ```typescript
 type Location = Path | Point | Range
@@ -26,9 +26,9 @@ type Path = number[]
 
 ```typescript
 interface Point {
-    path: Path
-    offset: number  
-    [key: string]: unknown
+  path: Path
+  offset: number
+  [key: string]: unknown
 }
 ```
 
@@ -66,9 +66,9 @@ Options: `{affinity?: 'forward' | 'backward' | null}`
 
 ```typescript
 interface Range {
-    anchor: Point
-    focus: Point
-    [key: string]: unknown
+  anchor: Point
+  focus: Point
+  [key: string]: unknown
 }
 ```
 
@@ -96,7 +96,7 @@ Get the intersection of one `range` with `another`.
 
 ###### `Range.isBackward(range: Range): boolean`
 
-Check if a `range` is backward, meaning that its anchor point appears *after* its focus point in the document.
+Check if a `range` is backward, meaning that its anchor point appears _after_ its focus point in the document.
 
 ###### `Range.isCollapsed(range: Range): boolean`
 
@@ -126,5 +126,4 @@ Get the start point of a `range`
 
 Transform a `range` by an `op`.
 
-Options: `{affinity: 'forward' | 'backward' | 
-'outward' | 'inward' | null}`
+Options: `{affinity: 'forward' | 'backward' | 'outward' | 'inward' | null}`

docs/api/nodes.md

@@ -1,6 +1,6 @@
 # Node
 
-The `Node` union type represents all of the different types of nodes that occur in a Slate document tree. 
+The `Node` union type represents all of the different types of nodes that occur in a Slate document tree.
 
 ```typescript
 type Node = Editor | Element | Text
@@ -57,7 +57,7 @@ Get the first node entry in a root node from a `path`.
 
 ###### `Node.fragment(root: Node, range: Range): Descendant[]`
 
-Get the sliced fragment represented by the  `range`.
+Get the sliced fragment represented by the `range`.
 
 ###### `Node.get(root: Node, path: Path): Node`
 
@@ -85,7 +85,7 @@ Get the node at a specific `path`, ensuring it's a leaf text node. If the node i
 
 ###### `Node.levels(root: Node, path: Path, options?): Generator<NodeEntry>`
 
-Return a generator of the nodes in a branch of the tree, from a specific `path`.  By default, the order is top-down, from the lowest to the highest node in the tree, but you can pass the `reverse: true` option to go bottom-up.
+Return a generator of the nodes in a branch of the tree, from a specific `path`. By default, the order is top-down, from the lowest to the highest node in the tree, but you can pass the `reverse: true` option to go bottom-up.
 
 Options: `{reverse?: boolean}`
 
@@ -236,8 +236,8 @@ Check if an element matches a set of `props`. Note: This checks custom propertie
 
 ```typescript
 interface Text {
-    text: string,
-    [key: string]: unknown
+  text: string
+  [key: string]: unknown
 }
 ```
 

docs/api/refs.md

@@ -8,9 +8,9 @@
 
 ```typescript
 interface PointRef {
-    current: Point | null
-    affinity: 'forward' | 'backward' | null
-    unref(): Point | null
+  current: Point | null
+  affinity: 'forward' | 'backward' | null
+  unref(): Point | null
 }
 ```
 
@@ -26,9 +26,9 @@ Transform the point refs current value by an `op`.
 
 ```typescript
 interface RangeRef {
-    current: Range | null
-    affinity: 'forward' | 'backward' | 'outward' | 'inward' | null
-    unref(): Range | null
+  current: Range | null
+  affinity: 'forward' | 'backward' | 'outward' | 'inward' | null
+  unref(): Range | null
 }
 ```
 

docs/api/transforms.md

@@ -8,28 +8,28 @@ Transforms that operate on nodes.
 
 ###### NodeOptions
 
-All transforms listed below support a parameter `options`. This includes options specific to the transform, and general `NodeOptions` to specify the place in the document that the transform is applied to. 
+All transforms listed below support a parameter `options`. This includes options specific to the transform, and general `NodeOptions` to specify the place in the document that the transform is applied to.
 
 ```typescript
 interface NodeOptions {
-    at?: Location
-    match?: (node: Node) => boolean
-    mode?: 'highest' | 'lowest'
-    voids?: boolean
+  at?: Location
+  match?: (node: Node) => boolean
+  mode?: 'highest' | 'lowest'
+  voids?: boolean
 }
 ```
 
 ###### `Transforms.insertNodes(editor: Editor, nodes: Node | Node[], options?)`
 
-Insert `nodes` at the specified location in the document.  If no location is specified, insert at the current selection. If there is no selection, insert at the end of the document.
+Insert `nodes` at the specified location in the document. If no location is specified, insert at the current selection. If there is no selection, insert at the end of the document.
 
-Options supported: `NodeOptions & {hanging?: boolean, select?: boolean}`. 
+Options supported: `NodeOptions & {hanging?: boolean, select?: boolean}`.
 
 ###### `Transforms.removeNodes(editor: Editor, options?)`
 
-Remove nodes at the specified location in the document. If no location is specified, remove the nodes in the selection. 
+Remove nodes at the specified location in the document. If no location is specified, remove the nodes in the selection.
 
-Options supported: `NodeOptions & {hanging?: boolean}` 
+Options supported: `NodeOptions & {hanging?: boolean}`
 
 ###### `Transforms.mergeNodes(editor: Editor, options?)`
 
@@ -41,7 +41,7 @@ Options supported: `NodeOptions & {hanging?: boolean}`
 
 Split nodes at the specified location. If no location is specified, split the selection.
 
-Options supported: `NodeOptions & {height?: number, always?: boolean}` 
+Options supported: `NodeOptions & {height?: number, always?: boolean}`
 
 ###### `Transforms.wrapNodes(editor: Editor, element: Element, options?)`
 
@@ -75,7 +75,7 @@ Options supported: `NodeOptions`. For `options.mode`, `'all'` is also supported.
 
 ###### `Transforms.moveNodes(editor: Editor, options)`
 
-Move the nodes from an origin to a destination. A destination must be specified in the `options`.  If no origin is specified, move the selection.
+Move the nodes from an origin to a destination. A destination must be specified in the `options`. If no origin is specified, move the selection.
 
 Options supported: `NodeOptions & {to: Path}`. For `options.mode`, `'all'` is also supported.
 
@@ -87,7 +87,7 @@ Transforms that operate on the document's selection.
 
 Collapse the selection to a single point.
 
-Options:  `{edge?: 'anchor' | 'focus' | 'start' | 'end'}`
+Options: `{edge?: 'anchor' | 'focus' | 'start' | 'end'}`
 
 ###### `Transforms.select(editor: Editor, target: Location)`
 

docs/libraries/slate-hyperscript.md

@@ -1,3 +1,3 @@
 # Slate Hyperscript
 
-This package contains a hyperscript helper for creating Slate documents with JSX!
+This package contains a hyperscript helper for creating Slate documents with JSX!

docs/walkthroughs/01-installing-slate.md

@@ -16,10 +16,9 @@ _Note, if you'd rather use a pre-bundled version of Slate, you can `yarn add sla
 
 Once you've installed Slate, you'll need to import it.
 
-
 ```jsx
 // Import React dependencies.
-import React, { useEffect, useMemo, useState } from "react";
+import React, { useEffect, useMemo, useState } from 'react'
 // Import the Slate editor factory.
 import { createEditor } from 'slate'
 
@@ -70,7 +69,11 @@ const App = () => {
   const [value, setValue] = useState([])
   // Render the Slate context.
   return (
-    <Slate editor={editor} value={value} onChange={newValue => setValue(newValue)} />
+    <Slate
+      editor={editor}
+      value={value}
+      onChange={newValue => setValue(newValue)}
+    />
   )
 }
 ```
@@ -89,7 +92,11 @@ const App = () => {
   const [value, setValue] = useState([])
   return (
     // Add the editable component inside the context.
-    <Slate editor={editor} value={value} onChange={newValue => setValue(newValue)}>
+    <Slate
+      editor={editor}
+      value={value}
+      onChange={newValue => setValue(newValue)}
+    >
       <Editable />
     </Slate>
   )
@@ -114,7 +121,11 @@ const App = () => {
   ])
 
   return (
-    <Slate editor={editor} value={value} onChange={newValue => setValue(newValue)}>
+    <Slate
+      editor={editor}
+      value={value}
+      onChange={newValue => setValue(newValue)}
+    >
       <Editable />
     </Slate>
   )

docs/walkthroughs/02-adding-event-handlers.md

@@ -75,7 +75,7 @@ const App = () => {
             // Prevent the ampersand character from being inserted.
             event.preventDefault()
             // Execute the `insertText` method when the event occurs.
-            editor.insertText("and")
+            editor.insertText('and')
           }
         }}
       />

docs/walkthroughs/03-defining-custom-elements.md

@@ -22,7 +22,7 @@ const App = () => {
         onKeyDown={event => {
           if (event.key === '&') {
             event.preventDefault()
-            editor.insertText("and")
+            editor.insertText('and')
           }
         }}
       />
@@ -93,7 +93,7 @@ const App = () => {
         onKeyDown={event => {
           if (event.key === '&') {
             event.preventDefault()
-            editor.insertText("and")
+            editor.insertText('and')
           }
         }}
       />