From 63c0db5b862137490baf2883d4378efd0b6311de Mon Sep 17 00:00:00 2001
From: Joe Anderson <joe@mousetrapped.co.uk>
Date: Tue, 15 Apr 2025 16:41:31 +0100
Subject: [PATCH] Add `pass` option to `Editor.nodes` (#5843)

---
 .changeset/rotten-taxis-battle.md             |  5 +++
 docs/api/nodes/editor.md                      |  4 ++-
 packages/slate/src/editor/nodes.ts            |  4 ++-
 packages/slate/src/interfaces/editor.ts       |  1 +
 .../interfaces/Editor/nodes/pass/block.tsx    | 35 +++++++++++++++++++
 .../slate/test/interfaces/Node/nodes/pass.tsx |  8 ++---
 6 files changed, 51 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/rotten-taxis-battle.md
 create mode 100644 packages/slate/test/interfaces/Editor/nodes/pass/block.tsx

diff --git a/.changeset/rotten-taxis-battle.md b/.changeset/rotten-taxis-battle.md
new file mode 100644
index 000000000..a2ac091fb
--- /dev/null
+++ b/.changeset/rotten-taxis-battle.md
@@ -0,0 +1,5 @@
+---
+'slate': minor
+---
+
+Add `pass` option to `Editor.nodes`, which is passed through to `Node.nodes`.
diff --git a/docs/api/nodes/editor.md b/docs/api/nodes/editor.md
index 6ee8f4d40..c19f8ca86 100644
--- a/docs/api/nodes/editor.md
+++ b/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.
diff --git a/packages/slate/src/editor/nodes.ts b/packages/slate/src/editor/nodes.ts
index 5c38939f6..a4553942d 100644
--- a/packages/slate/src/editor/nodes.ts
+++ b/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 &&
diff --git a/packages/slate/src/interfaces/editor.ts b/packages/slate/src/interfaces/editor.ts
index 524ce8c7f..c9827e4a8 100644
--- a/packages/slate/src/interfaces/editor.ts
+++ b/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
 }
 
diff --git a/packages/slate/test/interfaces/Editor/nodes/pass/block.tsx b/packages/slate/test/interfaces/Editor/nodes/pass/block.tsx
new file mode 100644
index 000000000..7f9ea2cb4
--- /dev/null
+++ b/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],
+  ],
+]
diff --git a/packages/slate/test/interfaces/Node/nodes/pass.tsx b/packages/slate/test/interfaces/Node/nodes/pass.tsx
index 48bcea964..71f420c3e 100644
--- a/packages/slate/test/interfaces/Node/nodes/pass.tsx
+++ b/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],