From 03eed53cf1f38bb517f08fbea3c057e379483324 Mon Sep 17 00:00:00 2001
From: Coury Ditch <cmditch@users.noreply.github.com>
Date: Thu, 8 Jul 2021 22:50:13 -0400
Subject: [PATCH] Fix typescript docs (#4303)

* Add docs on annotations for useState and initial editor value

* Typescript docs: Use initialValue
---
 docs/concepts/12-typescript.md           | 39 +++++++++++++++++++++---
 docs/walkthroughs/01-installing-slate.md | 12 ++++++--
 2 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/docs/concepts/12-typescript.md b/docs/concepts/12-typescript.md
index 8634e5a36..4b3c8b5bd 100644
--- a/docs/concepts/12-typescript.md
+++ b/docs/concepts/12-typescript.md
@@ -2,7 +2,7 @@
 
 Slate supports typing of one Slate document model \(ie. one set of custom `Editor`, `Element` and `Text` types\). If you need to support more than one document model, see the section Multiple Document Models.
 
-**Warning:** You must define `CustomTypes` when using TypeScript or Slate will display typing errors.
+**Warning:** You must define `CustomTypes`, annotate `useState`, and annotate the editor's initial state when using TypeScript or Slate will display typing errors.
 
 ## Migrating from 0.47.x
 
@@ -21,17 +21,48 @@ import { BaseEditor } from 'slate'
 import { ReactEditor } from 'slate-react'
 import { HistoryEditor } from 'slate-history'
 
-type CustomText = { text: string; bold: boolean; italic: boolean }
+type CustomElement = { type: 'paragraph'; children: CustomText[] }
+type CustomText = { text: string; bold?: boolean; italic?: boolean }
 
 declare module 'slate' {
   interface CustomTypes {
     Editor: BaseEditor & ReactEditor & HistoryEditor
-    Element: { type: 'paragraph'; children: CustomText[] }
+    Element: CustomElement
     Text: CustomText
   }
 }
 ```
 
+## Annotations in the Editor
+
+To avoid typing errors annotate `useState` w/ `<Descendant[]>` and the editor's initial value w/ your custom Element type.
+
+```typescript jsx
+import React, { useMemo, useState } from 'react'
+import { createEditor, Descendant } from 'slate'
+import { Slate, Editable, withReact } from 'slate-react'
+
+const App = () => {
+  const initialValue: CustomElement[] = [
+    {
+      type: 'paragraph',
+      children: [{ text: 'A line of text in a paragraph.' }],
+    },
+  ];
+  const editor = useMemo(() => withReact(createEditor()), [])
+  const [value, setValue] = useState<Descendant[]>(initialValue)
+  return (
+    <Slate
+      editor={editor}
+      value={value}
+      onChange={setValue}
+    >
+      <Editable />
+    </Slate>
+  )
+}
+```
+
 ## Best Practices for `Element` and `Text` Types
 
 While you can define types directly in the `CustomTypes` interface, best practice is to define and export each type separately so that you can reference individual types like a `ParagraphElement`.
@@ -59,7 +90,7 @@ export type HeadingElement = {
 
 export type CustomElement = ParagraphElement | HeadingElement
 
-export type FormattedText = { text: string; bold: boolean; italic: boolean }
+export type FormattedText = { text: string; bold?: boolean; italic?: boolean }
 
 export type CustomText = FormattedText
 
diff --git a/docs/walkthroughs/01-installing-slate.md b/docs/walkthroughs/01-installing-slate.md
index cab19b244..2c8c98438 100644
--- a/docs/walkthroughs/01-installing-slate.md
+++ b/docs/walkthroughs/01-installing-slate.md
@@ -47,10 +47,10 @@ const App = () => {
 
 Of course we haven't rendered anything, so you won't see any changes.
 
-> If you are using TypeScript, you will also need to extend the `Editor` with `ReactEditor` as per the documentation on [TypeScript](../concepts/12-typescript.md). The example below also includes the custom types required for the rest of this example.
+> If you are using TypeScript, you will also need to extend the `Editor` with `ReactEditor` and add annotations as per the documentation on [TypeScript](../concepts/12-typescript.md). The example below also includes the custom types required for the rest of this example.
 
 ```typescript
-// TypeScript Users only add this code
+// TypeScript users only add this code
 import { BaseEditor } from 'slate'
 import { ReactEditor } from 'slate-react'
 
@@ -65,6 +65,14 @@ declare module 'slate' {
   }
 }
 ```
+```typescript jsx
+// Also you must annotate `useState<Descendant[]>` and the editor's initial value.
+const App = () => {
+  const initialValue : CustomElement = [];
+  const [value, setValue] = useState<Descendant[]>(initialValue)
+  return <Slate value={value} onChange={setValue}>...</Slate>
+}
+```
 
 Next we want to create state for `value`: