Rename <Slate> component value prop to initialValue (#5421)

* Rename `slate-react` Slate component `value` prop to `initialValue`

Fixes #4992

* Update documentation: `value` -> `initialValue`

* Add a changeset record

* Make props order consistent

.changeset/tiny-suns-lick.md

@@ -0,0 +1,5 @@
+---
+'slate-react': minor
+---
+
+Rename `<Slate>` component prop from `value` to `initialValue` to emphasize uncontrolled nature of it

docs/concepts/12-typescript.md

@@ -53,7 +53,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable />
     </Slate>
   )

docs/general/changelog.md

@@ -309,7 +309,7 @@ const [value, setValue] = useState(initialValue)
 const [selection, setSelection] = useState(null)
 
 <Slate
-  value={value}
+  initialValue={initialValue}
   selection={selection}
   onChange={(value, selection) => {
     setValue(value)

docs/walkthroughs/01-installing-slate.md

@@ -81,7 +81,7 @@ const initialValue = [
 const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
   // Render the Slate context.
-  return <Slate editor={editor} value={initialValue} />
+  return <Slate editor={editor} initialValue={initialValue} />
 }
 ```
 
@@ -107,7 +107,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
   return (
     // Add the editable component inside the context.
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable />
     </Slate>
   )

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

@@ -20,7 +20,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable />
     </Slate>
   )
@@ -41,7 +41,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         // Define a new handler which prints the key that was pressed.
         onKeyDown={event => {
@@ -71,7 +71,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         onKeyDown={event => {
           if (event.key === '&') {

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

@@ -18,7 +18,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         onKeyDown={event => {
           if (event.key === '&') {
@@ -88,7 +88,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         // Pass in the `renderElement` function.
         renderElement={renderElement}
@@ -142,7 +142,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         onKeyDown={event => {
@@ -200,7 +200,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         onKeyDown={event => {

docs/walkthroughs/04-applying-custom-formatting.md

@@ -27,7 +27,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         onKeyDown={event => {
@@ -72,7 +72,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         onKeyDown={event => {
@@ -163,7 +163,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         // Pass in the `renderLeaf` function.

docs/walkthroughs/05-executing-commands.md

@@ -35,7 +35,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         renderLeaf={renderLeaf}
@@ -142,7 +142,7 @@ const App = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         renderLeaf={renderLeaf}
@@ -200,7 +200,7 @@ const App = () => {
 
   return (
     // Add a toolbar with buttons that call the same methods.
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <div>
         <button
           onMouseDown={event => {

docs/walkthroughs/06-saving-to-a-database.md

@@ -18,7 +18,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable />
     </Slate>
   )
@@ -45,7 +45,7 @@ const App = () => {
   return (
     <Slate
       editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
       onChange={value => {
         const isAstChange = editor.operations.some(
           op => 'set_selection' !== op.type
@@ -85,7 +85,7 @@ const App = () => {
   return (
     <Slate
       editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
       onChange={value => {
         const isAstChange = editor.operations.some(
           op => 'set_selection' !== op.type
@@ -145,7 +145,7 @@ const App = () => {
   return (
     <Slate
       editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
       onChange={value => {
         const isAstChange = editor.operations.some(
           op => 'set_selection' !== op.type

packages/slate-react/src/components/slate.tsx

@@ -19,18 +19,18 @@ import { EDITOR_TO_ON_CHANGE } from '../utils/weak-maps'
 
 export const Slate = (props: {
   editor: ReactEditor
-  value: Descendant[]
+  initialValue: Descendant[]
   children: React.ReactNode
   onChange?: (value: Descendant[]) => void
 }) => {
-  const { editor, children, onChange, value, ...rest } = props
+  const { editor, children, onChange, initialValue, ...rest } = props
   const unmountRef = useRef(false)
 
   const [context, setContext] = React.useState<SlateContextValue>(() => {
-    if (!Node.isNodeList(value)) {
+    if (!Node.isNodeList(initialValue)) {
       throw new Error(
-        `[Slate] value is invalid! Expected a list of elements but got: ${Scrubber.stringify(
+        `[Slate] initialValue is invalid! Expected a list of elements but got: ${Scrubber.stringify(
-          value
+          initialValue
         )}`
       )
     }
@@ -39,7 +39,7 @@ export const Slate = (props: {
         `[Slate] editor is invalid! You passed: ${Scrubber.stringify(editor)}`
       )
     }
-    editor.children = value
+    editor.children = initialValue
     Object.assign(editor, rest)
     return { v: 0, editor }
   })

packages/slate-react/test/index.spec.tsx

@@ -10,7 +10,9 @@ const createNodeMock = () => ({
 
 class MockResizeObserver {
   observe() {}
+
   unobserve() {}
+
   disconnect() {}
 }
 
@@ -21,14 +23,18 @@ describe('slate-react', () => {
     describe('NODE_TO_KEY logic', () => {
       test('should not unmount the node that gets split on a split_node operation', async () => {
         const editor = withReact(createEditor())
-        const value = [{ type: 'block', children: [{ text: 'test' }] }]
+        const initialValue = [{ type: 'block', children: [{ text: 'test' }] }]
         const mounts = jest.fn()
 
         let el: ReactTestRenderer
 
         act(() => {
           el = create(
-            <Slate editor={editor} value={value} onChange={() => {}}>
+            <Slate
+              editor={editor}
+              initialValue={initialValue}
+              onChange={() => {}}
+            >
               <Editable
                 renderElement={({ children }) => {
                   useEffect(() => mounts(), [])
@@ -52,7 +58,7 @@ describe('slate-react', () => {
 
       test('should not unmount the node that gets merged into on a merge_node operation', async () => {
         const editor = withReact(createEditor())
-        const value = [
+        const initialValue = [
           { type: 'block', children: [{ text: 'te' }] },
           { type: 'block', children: [{ text: 'st' }] },
         ]
@@ -62,7 +68,11 @@ describe('slate-react', () => {
 
         act(() => {
           el = create(
-            <Slate editor={editor} value={value} onChange={() => {}}>
+            <Slate
+              editor={editor}
+              initialValue={initialValue}
+              onChange={() => {}}
+            >
               <Editable
                 renderElement={({ children }) => {
                   useEffect(() => mounts(), [])

site/examples/check-lists.tsx

@@ -73,7 +73,7 @@ const CheckListsExample = () => {
   )
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         placeholder="Get to work…"

site/examples/code-highlighting.tsx

@@ -46,7 +46,7 @@ const CodeHighlightingExample = () => {
   const onKeyDown = useOnKeydown(editor)
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <ExampleToolbar />
       <SetNodeToDecorations />
       <Editable
@@ -324,7 +324,7 @@ const App = () => {
   const [editor] = useState(() => withReact(createEditor()))
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable />
     </Slate>
   )

site/examples/custom-placeholder.tsx

@@ -13,7 +13,7 @@ const initialValue: Descendant[] = [
 const PlainTextExample = () => {
   const editor = useMemo(() => withHistory(withReact(createEditor())), [])
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         placeholder="Type something"
         renderPlaceholder={({ children, attributes }) => (

site/examples/editable-voids.tsx

@@ -15,7 +15,7 @@ const EditableVoidsExample = () => {
   )
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <InsertEditableVoidButton />
       </Toolbar>

site/examples/embeds.tsx

@@ -16,7 +16,7 @@ import {
 const EmbedsExample = () => {
   const editor = useMemo(() => withEmbeds(withReact(createEditor())), [])
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={props => <Element {...props} />}
         placeholder="Enter some text..."

site/examples/forced-layout.tsx

@@ -74,7 +74,7 @@ const ForcedLayoutExample = () => {
     []
   )
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         placeholder="Enter a title…"

site/examples/hovering-toolbar.tsx

@@ -17,7 +17,7 @@ const HoveringMenuExample = () => {
   const editor = useMemo(() => withHistory(withReact(createEditor())), [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <HoveringToolbar />
       <Editable
         renderLeaf={props => <Leaf {...props} />}

site/examples/huge-document.tsx

@@ -25,7 +25,7 @@ const HugeDocumentExample = () => {
   const renderElement = useCallback(props => <Element {...props} />, [])
   const editor = useMemo(() => withReact(createEditor()), [])
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable renderElement={renderElement} spellCheck autoFocus />
     </Slate>
   )

site/examples/iframe.tsx

@@ -25,7 +25,7 @@ const IFrameExample = () => {
   const handleBlur = useCallback(() => ReactEditor.deselect(editor), [editor])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <MarkButton format="bold" icon="format_bold" />
         <MarkButton format="italic" icon="format_italic" />

site/examples/images.tsx

@@ -25,7 +25,7 @@ const ImagesExample = () => {
   )
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <InsertImageButton />
       </Toolbar>

site/examples/inlines.tsx

@@ -98,7 +98,7 @@ const InlinesExample = () => {
   }
 
   return (
-    <SlateReact.Slate editor={editor} value={initialValue}>
+    <SlateReact.Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <AddLinkButton />
         <RemoveLinkButton />

site/examples/markdown-preview.tsx

@@ -48,7 +48,7 @@ const MarkdownPreviewExample = () => {
   }, [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         decorate={decorate}
         renderLeaf={renderLeaf}

site/examples/markdown-shortcuts.tsx

@@ -70,7 +70,7 @@ const MarkdownShortcutsExample = () => {
   )
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         onDOMBeforeInput={handleDOMBeforeInput}
         renderElement={renderElement}

site/examples/mentions.tsx

@@ -73,7 +73,7 @@ const MentionExample = () => {
   return (
     <Slate
       editor={editor}
-      value={initialValue}
+      initialValue={initialValue}
       onChange={() => {
         const { selection } = editor
 

site/examples/paste-html.tsx

@@ -91,7 +91,7 @@ const PasteHtmlExample = () => {
     []
   )
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable
         renderElement={renderElement}
         renderLeaf={renderLeaf}

site/examples/plaintext.tsx

@@ -6,7 +6,7 @@ import { withHistory } from 'slate-history'
 const PlainTextExample = () => {
   const editor = useMemo(() => withHistory(withReact(createEditor())), [])
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable placeholder="Enter some plain text..." />
     </Slate>
   )

site/examples/read-only.tsx

@@ -5,7 +5,7 @@ import { Slate, Editable, withReact } from 'slate-react'
 const ReadOnlyExample = () => {
   const editor = useMemo(() => withReact(createEditor()), [])
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable readOnly placeholder="Enter some plain text..." />
     </Slate>
   )

site/examples/richtext.tsx

@@ -28,7 +28,7 @@ const RichTextExample = () => {
   const editor = useMemo(() => withHistory(withReact(createEditor())), [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <MarkButton format="bold" icon="format_bold" />
         <MarkButton format="italic" icon="format_italic" />

site/examples/scroll-into-view.tsx

@@ -51,7 +51,7 @@ const ScrollIntoViewExample = () => {
 const PlainTextEditor = () => {
   const editor = useMemo(() => withHistory(withReact(createEditor())), [])
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable placeholder="Enter some plain text..." />
     </Slate>
   )

site/examples/search-highlighting.tsx

@@ -37,7 +37,7 @@ const SearchHighlightingExample = () => {
   )
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <div
           className={css`

site/examples/shadow-dom.tsx

@@ -31,7 +31,7 @@ const ShadowEditor = () => {
   const editor = useMemo(() => withHistory(withReact(createEditor())), [])
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable placeholder="Enter some plain text..." />
     </Slate>
   )

site/examples/styling.tsx

@@ -11,7 +11,7 @@ const StylingExample = () => {
     <div style={{ display: 'flex', flexDirection: 'column', gap: '40px' }}>
       <Slate
         editor={editor1}
-        value={[
+        initialValue={[
           {
             type: 'paragraph',
             children: [{ text: 'This editor is styled using the style prop.' }],
@@ -29,7 +29,7 @@ const StylingExample = () => {
 
       <Slate
         editor={editor2}
-        value={[
+        initialValue={[
           {
             type: 'paragraph',
             children: [

site/examples/tables.tsx

@@ -18,7 +18,7 @@ const TablesExample = () => {
     []
   )
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Editable renderElement={renderElement} renderLeaf={renderLeaf} />
     </Slate>
   )