LibWeb: Add basic support for DOM's NodeIterator and NodeFilter

This patch adds NodeIterator (created via Document.createNodeIterator())
which allows you to iterate through all the nodes in a subtree while
filtering with a provided NodeFilter callback along the way.

This first cut implements the full API, but does not yet handle nodes
being removed from the document while referenced by the iterator. That
will be done in a subsequent patch.

8 files changed, 338 insertions, 1 deletions

diff --git a/Userland/Libraries/LibWeb/DOM/Document.cpp b/Userland/Libraries/LibWeb/DOM/Document.cpp
index af4be273d3..a1d8df1fad 100644
--- a/Userland/Libraries/LibWeb/DOM/Document.cpp
+++ b/Userland/Libraries/LibWeb/DOM/Document.cpp
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018-2021, Andreas Kling <kling@serenityos.org>
+ * Copyright (c) 2018-2022, Andreas Kling <kling@serenityos.org>
  * Copyright (c) 2021, Linus Groh <linusg@serenityos.org>
  * Copyright (c) 2021, Luke Wilde <lukew@serenityos.org>
  * Copyright (c) 2021, Sam Atkins <atkinssj@serenityos.org>
@@ -31,6 +31,7 @@
 #include <LibWeb/DOM/Event.h>
 #include <LibWeb/DOM/ExceptionOr.h>
 #include <LibWeb/DOM/HTMLCollection.h>
+#include <LibWeb/DOM/NodeIterator.h>
 #include <LibWeb/DOM/Range.h>
 #include <LibWeb/DOM/ShadowRoot.h>
 #include <LibWeb/DOM/Text.h>
@@ -1460,4 +1461,10 @@ ExceptionOr<Document::PrefixAndTagName> Document::validate_qualified_name(String
     };
 }
 
+// https://dom.spec.whatwg.org/#dom-document-createnodeiterator
+NonnullRefPtr<NodeIterator> Document::create_node_iterator(Node& root, unsigned what_to_show, RefPtr<NodeFilter> filter)
+{
+    return NodeIterator::create(root, what_to_show, move(filter));
+}
+
 }
diff --git a/Userland/Libraries/LibWeb/DOM/Document.h b/Userland/Libraries/LibWeb/DOM/Document.h
index 6da28d8a62..299ce9d4b1 100644
--- a/Userland/Libraries/LibWeb/DOM/Document.h
+++ b/Userland/Libraries/LibWeb/DOM/Document.h
@@ -324,6 +324,8 @@ public:
     };
     static ExceptionOr<PrefixAndTagName> validate_qualified_name(String const& qualified_name);
 
+    NonnullRefPtr<NodeIterator> create_node_iterator(Node& root, unsigned what_to_show, RefPtr<NodeFilter>);
+
 private:
     explicit Document(const AK::URL&);
 
diff --git a/Userland/Libraries/LibWeb/DOM/Document.idl b/Userland/Libraries/LibWeb/DOM/Document.idl
index 50b1baceef..e7b9401e85 100644
--- a/Userland/Libraries/LibWeb/DOM/Document.idl
+++ b/Userland/Libraries/LibWeb/DOM/Document.idl
@@ -7,6 +7,8 @@
 #import <DOM/Event.idl>
 #import <DOM/HTMLCollection.idl>
 #import <DOM/Node.idl>
+#import <DOM/NodeFilter.idl>
+#import <DOM/NodeIterator.idl>
 #import <DOM/NodeList.idl>
 #import <DOM/Range.idl>
 #import <DOM/Text.idl>
@@ -173,4 +175,6 @@ interface Document : Node {
     readonly boolean hidden;
     readonly DOMString visibilityState;
 
+    [NewObject] NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
+
 };
diff --git a/Userland/Libraries/LibWeb/DOM/NodeFilter.h b/Userland/Libraries/LibWeb/DOM/NodeFilter.h
new file mode 100644
index 0000000000..47f530e99e
--- /dev/null
+++ b/Userland/Libraries/LibWeb/DOM/NodeFilter.h
@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2022, Andreas Kling <kling@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/RefCounted.h>
+#include <LibJS/Heap/Handle.h>
+#include <LibWeb/Bindings/CallbackType.h>
+#include <LibWeb/Bindings/Wrappable.h>
+
+namespace Web::DOM {
+
+class NodeFilter
+    : public RefCounted<NodeFilter>
+    , public Bindings::Wrappable {
+public:
+    using WrapperType = Bindings::NodeFilterWrapper;
+
+    explicit NodeFilter(Bindings::CallbackType callback)
+        : m_callback(move(callback))
+    {
+    }
+
+    virtual ~NodeFilter() = default;
+
+    Bindings::CallbackType& callback() { return m_callback; }
+
+    enum Result {
+        FILTER_ACCEPT = 1,
+        FILTER_REJECT = 2,
+        FILTER_SKIP = 3,
+    };
+
+private:
+    Bindings::CallbackType m_callback;
+};
+
+inline JS::Object* wrap(JS::GlobalObject&, Web::DOM::NodeFilter& filter)
+{
+    return filter.callback().callback.cell();
+}
+
+}
diff --git a/Userland/Libraries/LibWeb/DOM/NodeFilter.idl b/Userland/Libraries/LibWeb/DOM/NodeFilter.idl
new file mode 100644
index 0000000000..94215112f9
--- /dev/null
+++ b/Userland/Libraries/LibWeb/DOM/NodeFilter.idl
@@ -0,0 +1,30 @@
+#import <DOM/Node.idl>
+
+[Exposed=Window]
+interface NodeFilter {
+
+    // FIXME: This should be a callback interface.
+
+    // Constants for acceptNode()
+    const unsigned short FILTER_ACCEPT = 1;
+    const unsigned short FILTER_REJECT = 2;
+    const unsigned short FILTER_SKIP = 3;
+
+    // Constants for whatToShow
+    const unsigned long SHOW_ALL = 0xFFFFFFFF;
+    const unsigned long SHOW_ELEMENT = 0x1;
+    const unsigned long SHOW_ATTRIBUTE = 0x2;
+    const unsigned long SHOW_TEXT = 0x4;
+    const unsigned long SHOW_CDATA_SECTION = 0x8;
+    const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // legacy
+    const unsigned long SHOW_ENTITY = 0x20; // legacy
+    const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40;
+    const unsigned long SHOW_COMMENT = 0x80;
+    const unsigned long SHOW_DOCUMENT = 0x100;
+    const unsigned long SHOW_DOCUMENT_TYPE = 0x200;
+    const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400;
+    const unsigned long SHOW_NOTATION = 0x800; // legacy
+
+    unsigned short acceptNode(Node node);
+
+};
diff --git a/Userland/Libraries/LibWeb/DOM/NodeIterator.cpp b/Userland/Libraries/LibWeb/DOM/NodeIterator.cpp
new file mode 100644
index 0000000000..0abba71695
--- /dev/null
+++ b/Userland/Libraries/LibWeb/DOM/NodeIterator.cpp
@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) 2022, Andreas Kling <kling@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <LibWeb/Bindings/DOMExceptionWrapper.h>
+#include <LibWeb/Bindings/IDLAbstractOperations.h>
+#include <LibWeb/Bindings/NodeWrapper.h>
+#include <LibWeb/Bindings/NodeWrapperFactory.h>
+#include <LibWeb/DOM/Node.h>
+#include <LibWeb/DOM/NodeIterator.h>
+
+namespace Web::DOM {
+
+NodeIterator::NodeIterator(Node& root)
+    : m_root(root)
+    , m_reference(root)
+{
+}
+
+// https://dom.spec.whatwg.org/#dom-document-createnodeiterator
+NonnullRefPtr<NodeIterator> NodeIterator::create(Node& root, unsigned what_to_show, RefPtr<NodeFilter> filter)
+{
+    // 1. Let iterator be a new NodeIterator object.
+    // 2. Set iterator’s root and iterator’s reference to root.
+    auto iterator = adopt_ref(*new NodeIterator(root));
+
+    // 3. Set iterator’s pointer before reference to true.
+    iterator->m_pointer_before_reference = true;
+
+    // 4. Set iterator’s whatToShow to whatToShow.
+    iterator->m_what_to_show = what_to_show;
+
+    // 5. Set iterator’s filter to filter.
+    iterator->m_filter = move(filter);
+
+    // 6. Return iterator.
+    return iterator;
+}
+
+// https://dom.spec.whatwg.org/#dom-nodeiterator-detach
+void NodeIterator::detach()
+{
+    // The detach() method steps are to do nothing.
+    // Its functionality (disabling a NodeIterator object) was removed, but the method itself is preserved for compatibility.
+}
+
+// https://dom.spec.whatwg.org/#concept-nodeiterator-traverse
+JS::ThrowCompletionOr<RefPtr<Node>> NodeIterator::traverse(Direction direction)
+{
+    // 1. Let node be iterator’s reference.
+    auto node = m_reference;
+
+    // 2. Let beforeNode be iterator’s pointer before reference.
+    auto before_node = m_pointer_before_reference;
+
+    // 3. While true:
+    while (true) {
+        // 4. Branch on direction:
+        if (direction == Direction::Next) {
+            // next
+            // If beforeNode is false, then set node to the first node following node in iterator’s iterator collection.
+            // If there is no such node, then return null.
+            if (!before_node) {
+                auto* next_node = node->next_in_pre_order(m_root.ptr());
+                if (!next_node)
+                    return RefPtr<Node> {};
+                node = *next_node;
+            } else {
+                // If beforeNode is true, then set it to false.
+                before_node = false;
+            }
+        } else {
+            // previous
+            // If beforeNode is true, then set node to the first node preceding node in iterator’s iterator collection.
+            // If there is no such node, then return null.
+            if (before_node) {
+                if (node == m_root.ptr())
+                    return nullptr;
+                auto* previous_node = node->previous_in_pre_order();
+                if (!previous_node)
+                    return RefPtr<Node> {};
+                node = *previous_node;
+            } else {
+                // If beforeNode is false, then set it to true.
+                before_node = true;
+            }
+        }
+
+        // 2. Let result be the result of filtering node within iterator.
+        auto result = filter(*node);
+        if (result.is_throw_completion())
+            return result.release_error();
+
+        // 3. If result is FILTER_ACCEPT, then break.
+        if (result.value() == NodeFilter::FILTER_ACCEPT)
+            break;
+    }
+
+    // 4. Set iterator’s reference to node.
+    m_reference = node;
+
+    // 5. Set iterator’s pointer before reference to beforeNode.
+    m_pointer_before_reference = before_node;
+
+    // 6. Return node.
+    return RefPtr<Node> { node };
+}
+
+// https://dom.spec.whatwg.org/#concept-node-filter
+JS::ThrowCompletionOr<NodeFilter::Result> NodeIterator::filter(Node& node)
+{
+    VERIFY(wrapper());
+    auto& global_object = wrapper()->global_object();
+
+    // 1. If traverser’s active flag is set, then throw an "InvalidStateError" DOMException.
+    if (m_active)
+        return JS::throw_completion(wrap(global_object, InvalidStateError::create("NodeIterator is already active")));
+
+    // 2. Let n be node’s nodeType attribute value − 1.
+    auto n = node.node_type() - 1;
+
+    // 3. If the nth bit (where 0 is the least significant bit) of traverser’s whatToShow is not set, then return FILTER_SKIP.
+    if (!(m_what_to_show & (1u << n)))
+        return NodeFilter::FILTER_SKIP;
+
+    // 4. If traverser’s filter is null, then return FILTER_ACCEPT.
+    if (!m_filter)
+        return NodeFilter::FILTER_ACCEPT;
+
+    // 5. Set traverser’s active flag.
+    m_active = true;
+
+    // 6. Let result be the return value of call a user object’s operation with traverser’s filter, "acceptNode", and « node ».
+    //    If this throws an exception, then unset traverser’s active flag and rethrow the exception.
+    auto result = Bindings::IDL::call_user_object_operation(m_filter->callback(), "acceptNode", {}, wrap(global_object, node));
+    if (result.is_abrupt()) {
+        m_active = false;
+        return result;
+    }
+
+    // 7. Unset traverser’s active flag.
+    m_active = false;
+
+    // 8. Return result.
+    auto result_value = TRY(result.value()->to_i32(global_object));
+    return static_cast<NodeFilter::Result>(result_value);
+}
+
+// https://dom.spec.whatwg.org/#dom-nodeiterator-nextnode
+JS::ThrowCompletionOr<RefPtr<Node>> NodeIterator::next_node()
+{
+    return traverse(Direction::Next);
+}
+
+// https://dom.spec.whatwg.org/#dom-nodeiterator-previousnode
+JS::ThrowCompletionOr<RefPtr<Node>> NodeIterator::previous_node()
+{
+    return traverse(Direction::Previous);
+}
+
+}
diff --git a/Userland/Libraries/LibWeb/DOM/NodeIterator.h b/Userland/Libraries/LibWeb/DOM/NodeIterator.h
new file mode 100644
index 0000000000..4df146617c
--- /dev/null
+++ b/Userland/Libraries/LibWeb/DOM/NodeIterator.h
@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2022, Andreas Kling <kling@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/RefCounted.h>
+#include <LibWeb/Bindings/Wrappable.h>
+#include <LibWeb/DOM/NodeFilter.h>
+
+namespace Web::DOM {
+
+// https://dom.spec.whatwg.org/#nodeiterator
+class NodeIterator
+    : public RefCounted<NodeIterator>
+    , public Bindings::Wrappable {
+public:
+    using WrapperType = Bindings::NodeIteratorWrapper;
+
+    static NonnullRefPtr<NodeIterator> create(Node& root, unsigned what_to_show, RefPtr<NodeFilter>);
+
+    NonnullRefPtr<Node> root() { return m_root; }
+    NonnullRefPtr<Node> reference_node() { return m_reference; }
+    bool pointer_before_reference_node() const { return m_pointer_before_reference; }
+    unsigned what_to_show() const { return m_what_to_show; }
+
+    NodeFilter* filter() { return m_filter; }
+
+    JS::ThrowCompletionOr<RefPtr<Node>> next_node();
+    JS::ThrowCompletionOr<RefPtr<Node>> previous_node();
+
+    void detach();
+
+private:
+    NodeIterator(Node& root);
+
+    enum class Direction {
+        Next,
+        Previous,
+    };
+
+    JS::ThrowCompletionOr<RefPtr<Node>> traverse(Direction);
+
+    JS::ThrowCompletionOr<NodeFilter::Result> filter(Node&);
+
+    // https://dom.spec.whatwg.org/#concept-traversal-root
+    NonnullRefPtr<DOM::Node> m_root;
+
+    // https://dom.spec.whatwg.org/#nodeiterator-reference
+    NonnullRefPtr<DOM::Node> m_reference;
+
+    // https://dom.spec.whatwg.org/#nodeiterator-pointer-before-reference
+    bool m_pointer_before_reference { true };
+
+    // https://dom.spec.whatwg.org/#concept-traversal-whattoshow
+    unsigned m_what_to_show { 0 };
+
+    // https://dom.spec.whatwg.org/#concept-traversal-filter
+    RefPtr<DOM::NodeFilter> m_filter;
+
+    // https://dom.spec.whatwg.org/#concept-traversal-active
+    bool m_active { false };
+};
+
+}
diff --git a/Userland/Libraries/LibWeb/DOM/NodeIterator.idl b/Userland/Libraries/LibWeb/DOM/NodeIterator.idl
new file mode 100644
index 0000000000..b46a41ff45
--- /dev/null
+++ b/Userland/Libraries/LibWeb/DOM/NodeIterator.idl
@@ -0,0 +1,18 @@
+#import <DOM/Node.idl>
+#import <DOM/NodeFilter.idl>
+
+[Exposed=Window]
+interface NodeIterator {
+
+    [SameObject] readonly attribute Node root;
+    readonly attribute Node referenceNode;
+    readonly attribute boolean pointerBeforeReferenceNode;
+    readonly attribute unsigned long whatToShow;
+    readonly attribute NodeFilter? filter;
+
+    Node? nextNode();
+    Node? previousNode();
+
+    undefined detach();
+
+};