Adds clarification & examples to demystify Transforms. (#4653)

* Adds clarification & examples to demystify Transforms.

* Fleshes out documentation of NodeOptions for Transforms

* Update docs/concepts/04-transforms.md

Co-authored-by: Dylan Schiemann <dylan@dojotoolkit.org>

* Uses 'API' in the title of all API documents

Co-authored-by: Dylan Schiemann <dylan@dojotoolkit.org>

docs/api/locations/README.md

@@ -1,4 +1,4 @@
-# Location Types
+# Location Types APIs
 
 The `Location` interface is a union of the ways to refer to a specific location in a Slate document: paths, points or ranges. Methods will often accept a `Location` instead of requiring only a `Path`, `Point` or `Range`.
 

docs/api/locations/location.md

@@ -1,4 +1,4 @@
-# Location
+# Location API
 
 The Location interface is a union of the ways to refer to a specific location in a Slate document: paths, points or ranges. Methods will often accept a Location instead of requiring only a Path, Point or Range.
 

docs/api/locations/path.md

@@ -1,4 +1,4 @@
-# Path
+# Path API
 
 `Path` arrays are a list of indexes that describe a node's exact position in a Slate node tree. Although they are usually relative to the root `Editor` object, they can be relative to any `Node` object.
 

docs/api/locations/point-entry.md

@@ -1,4 +1,4 @@
-# PointEntry
+# PointEntry API
 
 `PointEntry` objects are returned when iterating over `Point` objects that belong to a range.
 

docs/api/locations/point-ref.md

@@ -1,4 +1,4 @@
-# PointRef
+# PointRef API
 
 `PointRef` objects keep a specific point in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Point` value.
 

docs/api/locations/point.md

@@ -1,6 +1,6 @@
-# Point
+# Point API
 
-`Point` objects refer to a specific location in a text node in a Slate document. Its `path` refers to the location of the node in the tree, and its offset refers to distance into the node's string of text. Points may only refer to `Text` nodes.
+`Point` objects refer to a specific location in a text node in a Slate document. Its `path` refers to the location of the node in the tree, and its `offset` refers to distance into the node's string of text. Points may only refer to `Text` nodes.
 
 ```typescript
 interface Point {

docs/api/locations/range-ref.md

@@ -1,4 +1,4 @@
-# RangeRef
+# RangeRef API
 
 `RangeRef` objects keep a specific range in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Range` value.
 

docs/api/locations/range.md

@@ -1,4 +1,4 @@
-# Range
+# Range API
 
 `Range` objects are a set of points that refer to a specific span of a Slate document. They can define a span inside a single node or they can span across multiple nodes. The editor's `selection` is stored as a range.
 

docs/api/locations/span.md

@@ -1,6 +1,6 @@
-# Span
+# Span API
 
-A `Span` is a low-level way to refer to a range using `Element` as the end points instead of a `Point` which requires the use of leaf text nodes.
+A `Span` is a low-level way to refer to a `Range` using `Element` as the end points instead of a `Point` which requires the use of leaf text nodes.
 
 ```typescript
 type Span = [Path, Path]

docs/api/nodes/README.md

@@ -1,4 +1,4 @@
-# Node Types
+# Node Types APIs
 
 The `Node` union type represents all of the different types of nodes that occur in a Slate document tree.
 

docs/api/nodes/editor.md

@@ -1,6 +1,6 @@
-# Editor
+# Editor API
 
-The `Editor` object stores all the state of a slate editor. It can be extended by plugins to add helpers and implement new behaviors.
+The `Editor` object stores all the state of a Slate editor. It can be extended by [plugins](../../concepts/08-plugins.md) to add helpers and implement new behaviors. It's a type of `Node` and its path is `[]`.
 
 ```typescript
 interface Editor {

docs/api/nodes/element.md

@@ -1,6 +1,6 @@
-# Element
+# Element API
 
-`Element` objects are a type of node in a Slate document that contain other `Element` nodes or `Text` nodes.
+`Element` objects are a type of `Node` in a Slate document that contain other `Element` nodes or `Text` nodes.
 
 ```typescript
 interface Element {

docs/api/nodes/node-entry.md

@@ -1,6 +1,6 @@
-# NodeEntry
+# NodeEntry API
 
-`NodeEntry` objects are returned when iterating over the nodes in a Slate document tree. They consist of the node and its `Path` relative to the root node in the document.
+`NodeEntry` objects are returned when iterating over the nodes in a Slate document tree. They consist of an array with two elements: the `Node` and its `Path` relative to the root node in the document.
 
 They are generics meaning that sometimes they will return a subset of `Node` types like an `Element` or `Text`.
 

docs/api/nodes/node.md

@@ -1,4 +1,4 @@
-# Node
+# Node API
 
 - [Static methods](node.md#static-methods)
   - [Retrieval methods](node.md#retrieval-methods)

docs/api/nodes/text.md

@@ -1,4 +1,4 @@
-# Text
+# Text API
 
 `Text` objects represent the nodes that contain the actual text content of a Slate document along with any formatting properties. They are always leaf nodes in the document tree as they cannot contain any children.
 

docs/api/operation.md

@@ -1,4 +1,4 @@
-# Operation
+# Operation API
 
 `Operation` objects define the low-level instructions that Slate editors use to apply changes to their internal state. Representing all changes as operations is what allows Slate editors to easily implement history, collaboration, and other features.
 

docs/api/transforms.md

@@ -1,4 +1,4 @@
-# Transforms
+# Transforms API
 
 Transforms are helper functions operating on the document. They can be used in defining your own commands.
 
@@ -11,20 +11,24 @@ Transforms are helper functions operating on the document. They can be used in d
 
 ## Node options
 
-All transforms support a parameter `options`. This includes options specific to the transform, and general `NodeOptions` to specify the place in the document that the transform is applied to.
+All transforms support a parameter `options`. This includes options specific to the transform, and general `NodeOptions` to specify which Nodes in the document that the transform is applied to.
 
 ```typescript
 interface NodeOptions {
   at?: Location
-  match?: (node: Node) => boolean
+  match?: (node: Node, path: Location) => boolean
   mode?: 'highest' | 'lowest'
   voids?: boolean
 }
 ```
 
-- The `at` option is versatile and can be used to implement more complex transforms. [Learn more about the `at` option](../concepts/04-transforms.md#the-at-option)
+- The `at` option selects a [Location](../concepts/03-locations.md) in the editor. It defaults to the user's current selection. [Learn more about the `at` option](../concepts/04-transforms.md#the-at-option)
 
-- When combined with `at`, `match` can be powerful. [Learn more about the `match` option](../concepts/04-transforms.md#the-match-option)
+- The `match` option filters the set of Nodes with a custom function. [Learn more about the `match` option](../concepts/04-transforms.md#the-match-option)
+
+- The `mode` option also filters the set of nodes.
+
+- When `voids` is false, [void Elements](./nodes/editor#schema-specific-instance-methods-to-override) are filtered out.
 
 ## Static methods
 

docs/concepts/02-nodes.md

@@ -138,3 +138,4 @@ const text = {
 ```
 
 Text nodes too can contain any custom properties you want, and that's how you implement custom formatting like **bold**, _italic_, `code`, etc.
+These custom properties are sometimes called [marks](../api/nodes/editor#mark-methods).

docs/concepts/03-locations.md

@@ -29,6 +29,9 @@ const editor = {
 
 The leaf text node would have a path of: `[0, 0]`.
 
+The Editor itself has a path of `[]`. For example, to select the whole contents of the editor, call
+`Transforms.select(editor, [])`
+
 ## `Point`
 
 Points are slightly more specific than paths, and contain an `offset` into a specific text node. Their interface is:

docs/concepts/04-transforms.md

@@ -4,6 +4,40 @@ Slate's data structure is immutable, so you can't modify or delete nodes directl
 
 Slate's transform functions are designed to be very flexible, to make it possible to represent all kinds of changes you might need to make to your editor. However, that flexibility can be hard to understand at first.
 
+Typically, you'll apply a single operation to zero or more Nodes. For example, here's how you flatten the syntax tree,
+by applying `unwrapNodes` to every parent of block Elements:
+
+```js
+Transforms.unwrapNodes(editor, {
+  at: [], // Path of Editor
+  match: node =>
+    !Editor.isEditor(node) &&
+    node.children?.every(child => Editor.isBlock(editor, child)),
+  mode: 'all', // also the Editor's children
+})
+```
+
+Non-standard operations (or debugging/tracing which Nodes will be affected by a set of NodeOptions) may require using
+`Editor.nodes` to create a JavaScript Iterator of NodeEntries and a for..of loop to act.
+For example, to replace all image elements with their alt text:
+
+```js
+const imageElmnts = Editor.nodes(editor, {
+  at: [], // Path of Editor
+  match: (node, path) => 'image' === node.type,
+  // mode defaults to "all", so this also searches the Editor's children
+})
+for (const nodeEntry of imageElmnts) {
+  const altText =
+    nodeEntry[0].alt ||
+    nodeEntry[0].title ||
+    /\/([^/]+)$/.exec(nodeEntry[0].url)?.[1] ||
+    '☹︎'
+  Transforms.select(editor, nodeEntry[1])
+  Editor.insertFragment(editor, [{ text: altText }])
+}
+```
+
 > 🤖 Check out the [Transforms](../api/transforms.md) reference for a full list of Slate's transforms.
 
 ## Selection Transforms
@@ -195,3 +229,4 @@ Transform.setNodes(
 ```
 
 When performing transforms, if you're ever looping over nodes and transforming them one at a time, consider seeing if `match` can solve your use case, and offload the complexity of managing loops to Slate instead.
+The `match` function can examine the children of a node, in `node.children`, or use `Node.parent` to examine its parent.