Allow void elements to receive marks (#5135)

Some void elements are effectively stand-ins for text, such as with the mentions example,
where the mention element renders the character's name. Users might want to format Void
elements like this with bold, or set their font and size, so `editor.markableVoid` tells
Slate whether or not to apply Marks to the text children of void elements.

- Adds `markableVoid()` as a schema-specific overrideable test.
- Changes `addMark` and `removeMark` so marks can apply to voids. Also changes behavior
of collapsed selection so that if a markable Void is selected, the mark will be applied /
removed.
- Shows how `markableVoid()` can work in the mentions example

docs/api/nodes/editor.md

@@ -12,6 +12,7 @@ interface Editor {
   // Schema-specific node behaviors.
   isInline: (element: Element) => boolean
   isVoid: (element: Element) => boolean
+  markableVoid: (element: Element) => boolean
   normalizeNode: (entry: NodeEntry) => void
   onChange: () => void
 
@@ -221,7 +222,7 @@ Options: `{at?: Location, mode?: 'highest' | 'lowest', voids?: boolean}`
 
 #### `Editor.addMark(editor: Editor, key: string, value: any) => void`
 
-Add a custom property to the leaf text nodes in the current selection.
+Add a custom property to the leaf text nodes and any nodes that `editor.markableVoid()` allows in the current selection.
 
 If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.
 
@@ -265,7 +266,7 @@ If the selection is currently expanded, it will be deleted first.
 
 #### `Editor.removeMark(editor: Editor, key: string) => void`
 
-Remove a custom property from all of the leaf text nodes in the current selection.
+Remove a custom property from all of the leaf text nodes within non-void nodes or void nodes that `editor.markableVoid()` allows in the current selection.
 
 If the selection is currently collapsed, the removal will be stored on `editor.marks` and applied to the text inserted next.
 
@@ -423,13 +424,17 @@ Called when there is a change in the editor.
 
 ### Mark methods
 
+#### `markableVoid: (element: Element) => boolean`
+
+Tells which void nodes accept Marks. Slate's default implementation returns `false`, but if some void elements support formatting, override this function to include them.
+
 #### `addMark(key: string, value: any) => void`
 
-Add a custom property to the leaf text nodes in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.
+Add a custom property to the leaf text nodes within non-void nodes or void nodes that `editor.markableVoid()` allows in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.
 
 #### `removeMark(key: string) => void`
 
-Remove a custom property from the leaf text nodes in the current selection.
+Remove a custom property from the leaf text nodes within non-void nodes or void nodes that `editor.markableVoid()` allows in the current selection.
 
 ### getFragment method
 

docs/api/nodes/element.md

@@ -31,6 +31,10 @@ A "block" element can only be siblings with other "block" elements. An "inline"
 
 In a not "void" element, Slate handles the rendering of its `children` (e.g. in a paragraph where the `Text` and `Inline` children are rendered by Slate). In a "void" element, the `children` are rendered by the `Element`'s render code.
 
+#### Voids That Support Marks
+
+Some void elements are effectively stand-ins for text, such as with the [Mentions](https://www.slatejs.org/examples/mentions) example, where the mention element renders the character's name. Users might want to format Void elements like this with bold, or set their font and size, so `editor.markableVoid` tells Slate whether or not to apply Marks to the text children of void elements.
+
 #### Rendering Void Elements
 
 Void Elements must
@@ -50,6 +54,42 @@ return (
 )
 ```
 
+For a "markable" void such as a `mention` element, marks on the empty child element can be used to determine how the void element is rendered (Slate Marks are applied only to Text leaves):
+
+```javascript
+const Mention = ({ attributes, children, element }) => {
+  const selected = useSelected()
+  const focused = useFocused()
+  const style: React.CSSProperties = {
+    padding: '3px 3px 2px',
+    margin: '0 1px',
+    verticalAlign: 'baseline',
+    display: 'inline-block',
+    borderRadius: '4px',
+    backgroundColor: '#eee',
+    fontSize: '0.9em',
+    boxShadow: selected && focused ? '0 0 0 2px #B4D5FF' : 'none',
+  }
+  // See if our empty text child has any styling marks applied and apply those
+  if (element.children[0].bold) {
+    style.fontWeight = 'bold'
+  }
+  if (element.children[0].italic) {
+    style.fontStyle = 'italic'
+  }
+  return (
+    <span
+      {...attributes}
+      contentEditable={false}
+      data-cy={`mention-${element.character.replace(' ', '-')}`}
+      style={style}
+    >
+      {children}@{element.character}
+    </span>
+  )
+}
+```
+
 ## Static methods
 
 ### Retrieval methods