feat(packages/mdast-util-hidden): allow visitAndReveal to bail out of…

… `false` is returned

packages/mdast-util-hidden/src/index.ts

@@ -99,19 +99,38 @@ export function reveal<Nodes extends Hidden[]>({
 }
 
 /**
- * Walks the `tree` using unist-util-visit to search for any `Hidden` nodes.
- * Upon encountering a `Hidden` node, `reveal` is called, then `visitor` is
- * called if provided, and finally `[SKIP, index]` is returned _unless `visitor`
- * returns a defined value_.
+ * Walks `tree` using unist-util-visit to search for any `Hidden` nodes. Upon
+ * encountering a `Hidden` node, `visitor` is called if provided.
+ *
+ * If `visitor` is provided but returns `false`, `reveal` is not called and the
+ * hidden is not revealed. Otherwise, `reveal` will always be called.
+ *
+ * If `visitor` is provided and returns a defined value other than `false`, that
+ * value will be passed through to unist-util-visit. If `visitor` is not
+ * provided, or it returns `undefined`, `[SKIP, index]` will be passed through
+ * instead.
  */
 export function visitAndReveal<Tree extends Node<Data>>({
   tree,
   visitor,
   reverse = false
 }: {
+  /**
+   * @see https://github.com/syntax-tree/unist-util-visit#visittree-test-visitor-reverse
+   */
   tree: Tree;
+  /**
+   * If `visitor` is provided but returns `false`, `reveal` is not called and the
+   * hidden is not revealed. Otherwise, `reveal` will always be called.
+   *
+   * If `visitor` is provided and returns a defined value other than `false`, that
+   * value will be passed through to unist-util-visit. If `visitor` is not
+   * provided, or it returns `undefined`, `[SKIP, index]` will be passed through
+   * instead.
+   */
   visitor?: Visitor;
   /**
+   * @see https://github.com/syntax-tree/unist-util-visit#visittree-test-visitor-reverse
    * @default false
    */
   reverse?: boolean;
@@ -122,10 +141,14 @@ export function visitAndReveal<Tree extends Node<Data>>({
     (node, index, parent) => {
       assert(index !== null, 'index is missing');
       assert(parent !== null, 'parent is missing');
-      assert(isHidden(node), 'hidden node is malformed');
+      assert(isHidden(node), 'malformed hidden node');
+
+      const result = visitor?.(node, index, parent);
 
-      reveal({ nodes: [node], index, parent });
-      return visitor?.(node, index, parent) ?? [SKIP, index];
+      if (result !== false) {
+        reveal({ nodes: [node], index, parent });
+        return result ?? [SKIP, index];
+      }
     },
     reverse
   );

packages/mdast-util-hidden/test/unit-index.test.ts

@@ -208,6 +208,40 @@ describe('::visitAndReveal', () => {
     expect(revealSpy).toHaveBeenNthCalledWith(4, { nodes: [node], index, parent });
   });
 
+  it('does not call reveal iff false is returned after invoking visitor', async () => {
+    expect.hasAssertions();
+
+    const revealSpy = jest
+      .spyOn(mdastUtilHidden, 'reveal')
+      .mockImplementation(() => undefined);
+
+    let calledOutsideVisitor = false;
+    let confirmCalled = false;
+
+    jest.spyOn(unistUtilVisit, 'visit').mockImplementation(((
+      _tree,
+      _test,
+      visitor,
+      _reverse
+    ) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect(visitor?.(node as any, index, parent as any)).toBeUndefined();
+      confirmCalled = true;
+    }) as typeof visit);
+
+    visitAndReveal({
+      tree: getInitialAst(),
+      visitor: () => {
+        calledOutsideVisitor = true;
+        return false;
+      }
+    });
+
+    expect(confirmCalled).toBeTrue();
+    expect(calledOutsideVisitor).toBeTrue();
+    expect(revealSpy).not.toBeCalled();
+  });
+
   it('passes through reverse parameter', async () => {
     expect.hasAssertions();
 
@@ -298,7 +332,7 @@ describe('::visitAndReveal', () => {
       visitAndReveal({
         tree: getInitialAst()
       })
-    ).toThrow(/node is malformed/);
+    ).toThrow(/malformed hidden node/);
   });
 });