v2

Author: zbeyens

.changeset/operation-validation-guards.md

@@ -0,0 +1,5 @@
+---
+"slate": minor
+---
+
+Add concrete operation type guards and reject unknown operation replay records.

.changeset/slate-react-example-dx-cleanup.md

@@ -0,0 +1,11 @@
+---
+"slate-react": patch
+---
+
+Rename React annotation and void helper props for clearer v2 authoring.
+
+**Migration:**
+
+- Use `<Slate annotationStore={store}>` instead of `annotationStores={[store]}`.
+- Use `useSlateAnnotations()` and `useSlateAnnotation(id)` inside `Slate` when reading the provider store.
+- Use `renderVoid={({ element, path }) => ...}` instead of `target` for void paths.

docs/api/operations/README.md

@@ -6,6 +6,7 @@
   - [Operation](./operation.md)
 - Operation subtypes
   - [Node Operations](README.md#node-operations)
+  - [Fragment Operations](README.md#fragment-operations)
   - [Text Operations](README.md#text-operations)
   - [Selection Operation](README.md#selection-operation)
   - [Base Operation](README.md#base-operation)
@@ -69,6 +70,29 @@ export type NodeOperation =
   | SplitNodeOperation
 ```
 
+### Fragment Operations
+
+Fragment operations replace a child slice under a path and carry the model
+selection before and after the replacement. Slate uses this shape for bulk
+edits such as paste, where one user action should stay one history and
+collaboration operation.
+
+```typescript
+type ReplaceFragmentOperation = {
+  type: 'replace_fragment'
+  path: Path
+  children: Node[]
+  newChildren: Node[]
+  selection: Range | null
+  newSelection: Range | null
+}
+```
+
+Collaboration adapters can replay this operation directly through
+`tx.operations.replay(...)`. CRDT adapters that cannot represent subtree
+replacement atomically should lower it to their own CRDT edits at the adapter
+boundary.
+
 ### Text Operations
 
 Text operations operate on `Text` objects only.
@@ -125,5 +149,9 @@ export type SelectionOperation = SetSelectionOperation
 The combination of all operation types.
 
 ```typescript
-export type BaseOperation = NodeOperation | SelectionOperation | TextOperation
+export type BaseOperation =
+  | NodeOperation
+  | ReplaceFragmentOperation
+  | SelectionOperation
+  | TextOperation
 ```

docs/concepts/05-operations.md

@@ -35,4 +35,10 @@ editor.update(tx => {
 
 Under the covers Slate converts editor method calls into low-level operations and applies them automatically. You usually think about operations only when implementing collaborative editing, history, or import/export tooling.
 
+Bulk edits can still be one operation. For example, paste can produce a
+`replace_fragment` operation that replaces a child slice and moves the model
+selection to the end of the inserted fragment. Collaboration adapters can replay
+that operation directly, or translate it into their own CRDT representation at
+the adapter boundary.
+
 > 🤖 Slate's editing behaviors being defined as operations is what makes things like collaborative editing possible, because each change is easily define-able, apply-able, compose-able and even undo-able!

docs/general/docs-proof-map.md

@@ -45,7 +45,7 @@ or one-off manual checks.
 Use the focused source and docs gates during docs work.
 
 ```bash
-rg -n "createEditor<|initialValue|renderVoid|useElementSelected|decorationSources|annotationStores|operations\\.replay|editor\\.update|editor\\.read" docs packages
+rg -n "createEditor<|initialValue|renderVoid|useElementSelected|decorationSources|annotationStore|operations\\.replay|editor\\.update|editor\\.read" docs packages
 ```
 
 Use the browser contract registry when a browser-sensitive claim changes.

docs/libraries/slate-react/annotations.md

@@ -70,6 +70,27 @@ const annotationStore = useSlateAnnotationStore(editor, [
 ])
 ```
 
+Pass the store to `Slate` when editor-local annotation UI lives under that
+provider. `useSlateAnnotations()` and `useSlateAnnotation(id)` read that store
+by default.
+
+```tsx
+<Slate annotationStore={annotationStore} editor={editor}>
+  <Editable renderSegment={renderCommentSegment} />
+  <CommentsSidebar />
+</Slate>
+
+function CommentsSidebar() {
+  const snapshot = useSlateAnnotations()
+
+  return snapshot.allIds.map((id) => {
+    const comment = snapshot.byId.get(id)
+
+    return <CommentThread key={id} comment={comment} />
+  })
+}
+```
+
 Release bookmarks when the app removes the annotation.
 
 ```tsx

docs/libraries/slate-react/editable.md

@@ -69,10 +69,10 @@ Always spread `attributes` on the top-level DOM element and render `children`.
 Use `renderVoid` for void elements. A void renderer returns visible content only.
 
 ```tsx
-const renderVoid = ({ element, target }) => {
+const renderVoid = ({ element, path }) => {
   switch (element.type) {
     case 'image':
-      return <ImageElement element={element} target={target} />
+      return <ImageElement element={element} path={path} />
     default:
       return null
   }
@@ -81,11 +81,11 @@ const renderVoid = ({ element, target }) => {
 
 Do not render `children`, hidden text anchors, or shell wrappers in normal void renderers. Slate renders the shell and model anchor for you.
 
-If a void needs selected UI, subscribe by target.
+If a void needs selected UI, subscribe by path.
 
 ```tsx
-const ImageElement = ({ element, target }) => {
-  const selected = useElementSelected(target)
+const ImageElement = ({ element, path }) => {
+  const selected = useElementSelected(path)
 
   return <img data-selected={selected || undefined} src={element.url} />
 }
@@ -137,7 +137,7 @@ const renderText = ({ attributes, children, text }) => {
 />
 ```
 
-Normal apps should pass `decorationSources` and `annotationStores` to `Slate`, then render projected text through `renderSegment`.
+Normal apps should pass `decorationSources` and `annotationStore` to `Slate`, then render projected text through `renderSegment`.
 
 ## `placeholder` And `renderPlaceholder`
 
@@ -181,11 +181,11 @@ Use `onDOMBeforeInput` only when you need the native `InputEvent`. Keep model wr
 
 ## Projection Sources
 
-Put decoration sources and annotation stores on `Slate`, not `Editable`. The provider owns editor-level projection sources so the editor surface, toolbar, and overlay UI read the same committed projection.
+Put decoration sources and the annotation store on `Slate`, not `Editable`. The provider owns editor-level projection sources so the editor surface, toolbar, and overlay UI read the same committed projection.
 
 ```tsx
 <Slate
-  annotationStores={[commentStore]}
+  annotationStore={commentStore}
   decorationSources={[searchSource]}
   editor={editor}
 >

docs/libraries/slate-react/hooks.md

@@ -76,9 +76,9 @@ Get the current element object inside an element renderer.
 Get the current element object, or `null` when the component is not inside an
 element renderer.
 
-#### `useElementSelected(target?: Path): boolean`
+#### `useElementSelected(path?: Path): boolean`
 
-Subscribe to whether a specific element target intersects the current
+Subscribe to whether a specific element path intersects the current
 selection. Use this only when the component actually draws selected UI.
 
 #### `useNodeSelector<T>(selector, equalityFn?, options?): T`

docs/libraries/slate-react/react-editor.md

@@ -103,8 +103,12 @@ Find a Slate range from a DOM range or selection.
 
 #### `editor.dom.clipboard.insertData(data: DataTransfer): void`
 
-Insert data from a `DataTransfer` into the editor. This tries Slate fragment
-data first, then plain text.
+Insert data from a `DataTransfer` into the editor.
+
+Slate runs `dom.clipboard.insertData` capability handlers first. A handler that
+returns `true` stops the default import path. When no handler claims the data,
+Slate tries an internal Slate fragment for the editor's configured
+`clipboardFormatKey`, then plain text.
 
 #### `editor.dom.clipboard.insertFragmentData(data: DataTransfer): boolean`
 
@@ -119,3 +123,8 @@ was inserted.
 #### `editor.dom.clipboard.writeSelection(data: Pick<DataTransfer, 'getData' | 'setData'>): void`
 
 Write the current selection to a `DataTransfer`.
+
+Slate writes plain text, HTML, and an internal Slate fragment payload. The
+fragment payload uses `application/${clipboardFormatKey}` and the HTML fallback
+is tagged with the same key, so differently configured editors do not blindly
+import each other's internal JSON.

docs/libraries/slate-react/slate.md

@@ -13,7 +13,7 @@
 
 ```typescript
 type SlateProps = {
-  annotationStores?: readonly SlateAnnotationStore[] | null
+  annotationStore?: SlateAnnotationStore | null
   children: React.ReactNode
   decorationSources?: readonly SlateDecorationSource[] | null
   editor: ReactEditor
@@ -146,9 +146,9 @@ const searchSource = useMemo(
 
 Prefer provider-owned `decorationSources` so every `Editable` and overlay UI reads from the same projection source.
 
-### `annotationStores`
+### `annotationStore`
 
-Annotation stores publish anchor-backed annotations to text rendering and annotation UI hooks.
+The annotation store publishes anchor-backed annotations to text rendering and annotation UI hooks.
 
 ```tsx
 const annotations = comments.map((comment) => ({
@@ -163,8 +163,8 @@ const annotations = comments.map((comment) => ({
 
 const annotationStore = useSlateAnnotationStore(editor, annotations)
 
-<Slate annotationStores={[annotationStore]} editor={editor}>
+<Slate annotationStore={annotationStore} editor={editor}>
   <Editable renderSegment={renderCommentSegment} />
-  <CommentsSidebar store={annotationStore} />
+  <CommentsSidebar />
 </Slate>
 ```