v2

Author: zbeyens

docs/api/locations/point.md

@@ -11,10 +11,9 @@ interface Point {
 ```
 
 When `root` is omitted, Slate resolves the point against the current editor or
-view root. The base editor and pure helpers fall back to `main`; root-bound
-views fall back to their own root. Points may also carry `root: 'main'`
-explicitly. Points in header, footer, content-root, or other named roots carry
-that root key.
+view root. The base editor and pure helpers fall back to the primary document;
+root-bound views fall back to their own root. Points in header, footer,
+content-root, or other extra roots carry that root key.
 
 - [Static methods](point.md#static-methods)
   - [Retrieval methods](point.md#retrieval-methods)

docs/api/locations/range.md

@@ -9,8 +9,8 @@ interface Range {
 }
 ```
 
-Both points must resolve inside the same root. The `main` root is implicit; named
-roots are stored on each point with `root`.
+Both points must resolve inside the same root. The primary document is
+implicit; extra roots are stored on each point with `root`.
 
 - [Static methods](range.md#static-methods)
   - [Retrieval methods](range.md#retrieval-methods)

docs/api/nodes/editor.md

@@ -134,28 +134,30 @@ editor.update((tx, { afterCommit }) => {
 
 ## Document roots
 
-The default document root is `main`. A plain block array initializes `main`.
-Pass `initialValue.roots` when one editor owns multiple roots.
+A plain block array initializes the primary document. Pass
+`initialValue.children` plus `initialValue.roots` when one editor owns extra
+roots.
 
 ```javascript
 const editor = createEditor({
   initialValue: {
+    children: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
     roots: {
       header: [{ type: 'paragraph', children: [{ text: 'Draft' }] }],
-      main: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
       footer: [{ type: 'paragraph', children: [{ text: 'Internal' }] }],
     },
   },
 })
 ```
 
-Read roots from `state.value.get().roots`.
+Read the primary document with `state.value.root()`. Read an extra root by key.
 
 ```javascript
-const footer = editor.read((state) => state.value.get().roots.footer)
+const body = editor.read((state) => state.value.root())
+const footer = editor.read((state) => state.value.root('footer'))
 ```
 
-Create, replace, or delete non-main roots with `tx.roots`.
+Create, replace, or delete extra roots with `tx.roots`.
 
 ```javascript
 editor.update((tx) => {
@@ -165,7 +167,7 @@ editor.update((tx) => {
 })
 ```
 
-Use normal node and text transforms for the `main` root. See
+Use normal node and text transforms for the primary document. See
 [Roots](../../concepts/13-roots.md) for React rendering, root chrome, and
 content roots.
 
@@ -175,13 +177,14 @@ content roots.
 
 ```ts
 type EditorDocumentValue = {
-  roots: Record<string, Descendant[]>
+  children: Descendant[]
+  roots?: Record<string, Descendant[]>
   state?: Record<string, unknown>
 }
 ```
 
-Use it for database persistence because it includes named roots and persistent
-state fields.
+Use it for database persistence because it includes the primary document, extra
+roots, and persistent state fields.
 
 ```javascript
 const documentValue = editor.read((state) => state.value.get())

docs/api/operations/operation.md

@@ -4,14 +4,14 @@
 
 Node, text, selection, fragment, and `replace_children` operations may include
 `root`. When `root` is omitted, Slate resolves the operation against the
-active operation/view root, then falls back to `main` for the base editor.
-Serialized non-main operations should preserve `root`.
+active operation/view root, then falls back to the primary document for the
+base editor. Serialized extra-root operations should preserve `root`.
 
 Root lifecycle updates from `tx.roots.create`, `tx.roots.replace`, and
 `tx.roots.delete` are represented as `replace_children` operations at `path:
 []`. Those operations carry `root`, `rootWasPresent`, and `rootIsPresent` so
 history and collaboration replay can create, replace, or delete the named root
-instead of applying the change to `main`.
+instead of applying the change to the primary document.
 
 - [Static methods](operation.md#static-methods)
   - [Manipulation methods](operation.md#manipulation-methods)

docs/api/transforms.md

@@ -324,7 +324,7 @@ Replace an existing named root.
 
 #### `tx.roots.delete(root: RootKey)`
 
-Delete a named root. The main root is not deleted through `tx.roots`.
+Delete an extra root. The primary document is not deleted through `tx.roots`.
 
 ## State field methods
 

docs/concepts/02-nodes.md

@@ -7,27 +7,25 @@ two node types:
 - `Text` nodes hold string content and mark properties.
 
 The editor runtime can also act as the root ancestor for node APIs, but the
-persisted document value is roots plus optional state fields. Save
-`state.value.get()` when you need the whole document.
+persisted document value is primary children, optional extra roots, and optional
+state fields. Save `state.value.get()` when you need the whole document.
 
 ```ts
 const documentValue = {
-  roots: {
-    main: [
-      {
-        type: 'paragraph',
-        children: [{ text: 'A line of text!' }],
-      },
-    ],
-  },
+  children: [
+    {
+      type: 'paragraph',
+      children: [{ text: 'A line of text!' }],
+    },
+  ],
   state: {
     'document.title': 'Draft',
   },
 }
 ```
 
 The short editor value is still an array of block elements. Slate treats that
-array as the `main` root.
+array as the primary document.
 
 ```ts
 const initialValue = [
@@ -39,7 +37,7 @@ const initialValue = [
 ```
 
 See [Document State](14-document-state.md) for persistence and
-[Roots](13-roots.md) for named roots, content roots, and multi-root rendering.
+[Roots](13-roots.md) for extra roots, content roots, and multi-root rendering.
 
 ## Element
 

docs/concepts/03-locations.md

@@ -1,11 +1,11 @@
 # Locations
 
-Locations tell Slate where to read or write inside an editor root. The main
+Locations tell Slate where to read or write inside an editor root. The core
 location types are `Path`, `Point`, and `Range`.
 
 Rootless locations resolve against the current editor or view root. The base
-editor uses `main`; root-bound views use their own root. Locations in named
-roots carry the root key on their points.
+editor uses the primary document; root-bound views use their own root.
+Locations in extra roots carry the root key on their points.
 
 ## Path
 
@@ -19,7 +19,7 @@ In this root value, the paragraph has path `[0]` and the text node has path
 `[0, 0]`.
 
 ```ts
-const main = [
+const children = [
   {
     type: 'paragraph',
     children: [{ text: 'A line of text!' }],

docs/concepts/10-serializing.md

@@ -8,11 +8,11 @@ Read the full persisted document through `state.value.get()`.
 
 ```ts
 const documentValue = editor.read((state) => state.value.get())
-const main = documentValue.roots.main
+const children = documentValue.children
 ```
 
 For single-root editors, `<Slate onChange>` gives the current provider root
-value. Use `state.value.get()` when you need named roots or persistent state
+value. Use `state.value.get()` when you need extra roots or persistent state
 fields. See [Document State](14-document-state.md).
 
 ## Plain Text
@@ -72,7 +72,7 @@ const serializeHtml = (node: Descendant): string => {
 }
 
 const html = editor
-  .read((state) => state.value.get().roots.main)
+  .read((state) => state.value.root())
   .map(serializeHtml)
   .join('')
 ```

docs/concepts/13-roots.md

@@ -1,8 +1,8 @@
 # Roots
 
-Slate stores document content in named roots. The default root is `main`; extra
-roots let one editor own headers, footers, synced blocks, captions, side panels,
-and other editable regions without creating separate editor instances.
+Slate stores the primary document as a normal block array. Extra roots let one
+editor own headers, footers, synced blocks, captions, side panels, and other
+editable regions without creating separate editor instances.
 
 Use roots when the content should share editor state, history, collaboration,
 schema, and commands. Use separate editors when the documents should be fully
@@ -11,45 +11,46 @@ independent.
 ## Value Shape
 
 The shortest editor value is still an array of blocks. Slate treats it as the
-`main` root.
+primary document.
 
 ```tsx
 const editor = createEditor({
   initialValue: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
 })
 ```
 
-Pass `initialValue.roots` when the editor owns more than one root.
+Pass `initialValue.children` plus `initialValue.roots` when the editor owns
+extra roots.
 
 ```tsx
 const editor = createEditor({
   initialValue: {
+    children: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
     roots: {
       header: [{ type: 'paragraph', children: [{ text: 'Draft' }] }],
-      main: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
       footer: [{ type: 'paragraph', children: [{ text: 'Internal' }] }],
     },
   },
 })
 ```
 
 Each root is a normal Slate block array. Rootless operations, points, and
-selections resolve against the current editor or view root. The base editor's
-current root defaults to `main`; a root-bound view resolves rootless locations
-against its own root.
+selections resolve against the current editor or view root. A root-bound view
+resolves rootless locations against its own root.
 
 Persist roots through the full [Document State](14-document-state.md) value
-instead of saving only the main root.
+instead of saving only the provider root.
 
 ## Reading And Writing Roots
 
-Read all roots from `state.value.get().roots`.
+Read the primary document with `state.value.root()`. Read an extra root by key.
 
 ```tsx
-const header = editor.read((state) => state.value.get().roots.header)
+const body = editor.read((state) => state.value.root())
+const header = editor.read((state) => state.value.root('header'))
 ```
 
-Create, replace, or delete non-main roots inside `editor.update`.
+Create, replace, or delete extra roots inside `editor.update`.
 
 ```tsx
 editor.update((tx) => {
@@ -59,8 +60,8 @@ editor.update((tx) => {
 })
 ```
 
-`main` is the stable document root. Mutate its children with normal node and
-text transforms instead of `tx.roots`.
+Mutate the primary document with normal node and text transforms instead of
+`tx.roots`.
 
 ## Rendering Roots
 
@@ -96,7 +97,7 @@ that must run against a specific root.
 Content roots attach an editable child root to an element in another root. The
 element keeps an empty text child as its model anchor. `element.childRoots[slot]`
 stores the root key, and the editable content lives in
-`state.value.get().roots[rootKey]`.
+`state.value.root(rootKey)`.
 
 ```tsx
 const syncedBlocks = defineEditorExtension({

docs/concepts/14-document-state.md

@@ -1,8 +1,9 @@
 # Document State
 
-Slate persists a document as roots plus optional state fields. Use roots for
-editable content and state fields for document metadata, settings, and other
-small model state that should share the editor runtime.
+Slate persists a document as primary children, optional extra roots, and
+optional state fields. Use roots for editable content outside the primary
+document and state fields for document metadata, settings, and other small model
+state that should share the editor runtime.
 
 Use external stores for comment bodies, permissions, and audit events; Slate can
 render their anchors through annotations.
@@ -13,12 +14,13 @@ The full persisted value is `EditorDocumentValue`.
 
 ```ts
 type EditorDocumentValue = {
-  roots: Record<string, Descendant[]>
+  children: Descendant[]
+  roots?: Record<string, Descendant[]>
   state?: Record<string, unknown>
 }
 ```
 
-`roots.main` is the default editable body. Named roots store headers, footers,
+`children` is the primary editable body. Extra roots store headers, footers,
 content roots, synced blocks, captions, and other editable regions owned by the
 same editor.
 
@@ -36,8 +38,8 @@ await saveDocument(JSON.stringify(documentValue))
 ```
 
 The first argument passed to `<Slate onChange>` is the provider root's block
-array. For `<Slate editor={editor}>`, that is `main`. That is enough for a
-simple single-root editor, but it drops named roots and persistent state fields.
+array. That is enough for a simple single-root editor, but it drops extra roots
+and persistent state fields.
 Use `editor.subscribe(...)` for full document persistence so state-field-only
 commits and edits in other roots are observed.
 
@@ -66,9 +68,7 @@ const saved = localStorage.getItem('slate.document')
 const initialValue = saved
   ? JSON.parse(saved)
   : {
-      roots: {
-        main: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
-      },
+      children: [{ type: 'paragraph', children: [{ text: 'Body' }] }],
     }
 
 const editor = useSlateEditor({