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
ianstormtaylor · May 26, 2023 · 91e388e · 91e388e
1 parent 0b17990
commit 91e388e
Show file tree

Hide file tree

Showing 34 changed files with 71 additions and 56 deletions.
diff --git a/.changeset/tiny-suns-lick.md b/.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
diff --git a/docs/concepts/12-typescript.md b/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>
   )

diff --git a/docs/general/changelog.md b/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)

diff --git a/docs/walkthroughs/01-installing-slate.md b/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>
   )

diff --git a/docs/walkthroughs/02-adding-event-handlers.md b/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 === '&') {

diff --git a/docs/walkthroughs/03-defining-custom-elements.md b/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 => {

diff --git a/docs/walkthroughs/04-applying-custom-formatting.md b/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.

diff --git a/docs/walkthroughs/05-executing-commands.md b/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 => {

diff --git a/docs/walkthroughs/06-saving-to-a-database.md b/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

diff --git a/packages/slate-react/src/components/slate.tsx b/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(
-          value
+        `[Slate] initialValue is invalid! Expected a list of elements but got: ${Scrubber.stringify(
+          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 }
   })

diff --git a/packages/slate-react/test/index.spec.tsx b/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(), [])

diff --git a/site/examples/check-lists.tsx b/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…"

diff --git a/site/examples/code-highlighting.tsx b/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>
   )

diff --git a/site/examples/custom-placeholder.tsx b/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 }) => (

diff --git a/site/examples/editable-voids.tsx b/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>

diff --git a/site/examples/embeds.tsx b/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..."

diff --git a/site/examples/forced-layout.tsx b/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…"

diff --git a/site/examples/hovering-toolbar.tsx b/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} />}

diff --git a/site/examples/huge-document.tsx b/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>
   )

diff --git a/site/examples/iframe.tsx b/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" />

diff --git a/site/examples/images.tsx b/site/examples/images.tsx
@@ -25,7 +25,7 @@ const ImagesExample = () => {
   )
 
   return (
-    <Slate editor={editor} value={initialValue}>
+    <Slate editor={editor} initialValue={initialValue}>
       <Toolbar>
         <InsertImageButton />
       </Toolbar>

diff --git a/site/examples/inlines.tsx b/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 />

diff --git a/site/examples/markdown-preview.tsx b/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}