Add pass option to Editor.nodes (#5843)

Author: 12joan

.changeset/rotten-taxis-battle.md

@@ -0,0 +1,5 @@
+---
+'slate': minor
+---
+
+Add `pass` option to `Editor.nodes`, which is passed through to `Node.nodes`.

docs/api/nodes/editor.md

@@ -141,7 +141,7 @@ Options: `depth?: number, edge?: 'start' | 'end'`
 
 At any given `Location` or `Span` in the editor provided by `at` (default is the current selection), the method returns a Generator of `NodeEntry` objects that represent the nodes that include `at`. At the top of the hierarchy is the `Editor` object itself.
 
-Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean}`
+Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | 'lowest', universal?: boolean, reverse?: boolean, voids?: boolean, pass?: (node: NodeEntry => boolean), ignoreNonSelectable?: boolean}`
 
 `options.match`: Provide a value to the `match?` option to limit the `NodeEntry` objects that are returned.
 
@@ -151,6 +151,8 @@ Options: `{at?: Location | Span, match?: NodeMatch, mode?: 'all' | 'highest' | '
 - `'highest'`: in a hierarchy of nodes, only return the highest level matching nodes
 - `'lowest'`: in a hierarchy of nodes, only return the lowest level matching nodes
 
+`options.pass`: Skip the descendants of certain nodes (but not the nodes themselves).
+
 #### `Editor.parent(editor: Editor, at: Location, options?) => NodeEntry<Ancestor>`
 
 Get the parent node of a location.

packages/slate/src/editor/nodes.ts

@@ -15,6 +15,7 @@ export function* nodes<T extends Node>(
     universal = false,
     reverse = false,
     voids = false,
+    pass,
     ignoreNonSelectable = false,
   } = options
   let { match } = options
@@ -44,7 +45,8 @@ export function* nodes<T extends Node>(
     reverse,
     from,
     to,
-    pass: ([node]) => {
+    pass: ([node, path]) => {
+      if (pass && pass([node, path])) return true
       if (!Element.isElement(node)) return false
       if (
         !voids &&

packages/slate/src/interfaces/editor.ts

@@ -244,6 +244,7 @@ export interface EditorNodesOptions<T extends Node> {
   universal?: boolean
   reverse?: boolean
   voids?: boolean
+  pass?: (entry: NodeEntry) => boolean
   ignoreNonSelectable?: boolean
 }
 

packages/slate/test/interfaces/Editor/nodes/pass/block.tsx

@@ -0,0 +1,35 @@
+/** @jsx jsx */
+import { Editor } from 'slate'
+import { jsx } from '../../../..'
+
+export const input = (
+  <editor>
+    <block pass>
+      <block match>one</block>
+    </block>
+    <block>
+      <block match>two</block>
+      <block pass match>
+        three
+      </block>
+    </block>
+  </editor>
+)
+export const test = editor => {
+  return Array.from(
+    Editor.nodes(editor, {
+      at: [],
+      match: n => !!n.match,
+      pass: ([n]) => !!n.pass,
+    })
+  )
+}
+export const output = [
+  [<block match>two</block>, [1, 0]],
+  [
+    <block pass match>
+      three
+    </block>,
+    [1, 1],
+  ],
+]

packages/slate/test/interfaces/Node/nodes/pass.tsx

@@ -5,27 +5,27 @@ import { jsx } from 'slate-hyperscript'
 export const input = (
   <editor>
     <element>
-      <element>
+      <element pass>
         <text key="a" />
       </element>
     </element>
   </editor>
 )
 export const test = value => {
-  return Array.from(Node.nodes(value, { pass: ([n, p]) => p.length > 1 }))
+  return Array.from(Node.nodes(value, { pass: ([n]) => !!n.pass }))
 }
 export const output = [
   [input, []],
   [
     <element>
-      <element>
+      <element pass>
         <text key="a" />
       </element>
     </element>,
     [0],
   ],
   [
-    <element>
+    <element pass>
       <text key="a" />
     </element>,
     [0, 0],