HTMLElement#moveBefore() implemented

rbri · rbri · commit 6cca44f70ba2 · 2025-11-24T19:50:09.000+01:00
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -7,6 +7,16 @@
     </properties>
 
     <body>
+        <release version="4.20.0" date="December xx, 2025" description="Bugfixes">
+            <action type="add" dev="rbri" issue="#1053">
+                HTMLElement#moveBefore() implemented.
+            </action>
+            <action type="update" dev="rbri">
+                neko: code cleanup and warning fixes.
+            </action>
+        </release>
+
+
         <release version="4.19.0" date="November 23, 2025" description="Chrome/Edge 142, Firefox 145, support spread in arrays, neko improvements, Bugfixes">
             <action type="update" dev="rbri">
                 neko: code quality and minor performance improvements.
diff --git a/src/main/java/org/htmlunit/html/DomNode.java b/src/main/java/org/htmlunit/html/DomNode.java
@@ -1318,6 +1318,52 @@ protected void onAddedToDocumentFragment() {
         }
     }
 
+    /**
+     * Add a DOM node as a child to this node before the referenced node.
+     * If the referenced node is null, append to the end.
+     * @param movedDomNode the node to move
+     * @param referenceDomNode the node to move before
+     * @throws DOMException in case of problems
+     */
+    public void moveBefore(final DomNode movedDomNode, final DomNode referenceDomNode) {
+        if (movedDomNode == referenceDomNode) {
+            return;
+        }
+
+        // If moving to the same position (node is already right before referenceNode), no operation needed
+        if (movedDomNode.getNextSibling() == referenceDomNode) {
+            return;
+        }
+
+        if (movedDomNode.isAncestorOf(this)) {
+            throw new DOMException(DOMException.HIERARCHY_REQUEST_ERR,
+                    "The new child element contains the parent.");
+        }
+
+        if (referenceDomNode != null && !this.isAncestorOf(referenceDomNode)) {
+            throw new DOMException(DOMException.NOT_FOUND_ERR,
+                    "The node before which the new node is to be inserted is not a child of this node.");
+        }
+
+        if (referenceDomNode != null && referenceDomNode.isAttachedToPage() && !movedDomNode.isAttachedToPage()) {
+            throw new DOMException(DOMException.HIERARCHY_REQUEST_ERR,
+                    "State-preserving atomic move cannot be performed on nodes participating in an invalid hierarchy.");
+        }
+
+        // Remove the node from its current position
+        movedDomNode.basicRemove();
+
+        // Insert at the new position
+        if (referenceDomNode == null) {
+            // Move to the end
+            basicAppend(movedDomNode);
+        }
+        else {
+            // Insert before the reference node
+            referenceDomNode.basicInsertBefore(movedDomNode);
+        }
+    }
+
     /**
      * @return an {@link Iterable} over the children of this node
      */
diff --git a/src/main/java/org/htmlunit/javascript/host/Element.java b/src/main/java/org/htmlunit/javascript/host/Element.java
@@ -826,6 +826,61 @@ public void insertAdjacentHTML(final String position, final String text) {
         parseHtmlSnippet(proxyDomNode, text);
     }
 
+    /**
+     * Moves a given Node inside the invoking node as a direct child, before a given reference node.
+     *
+     * @param context the JavaScript context
+     * @param scope the scope
+     * @param thisObj the scriptable
+     * @param args the arguments passed into the method
+     * @param function the function
+     */
+    @JsxFunction({CHROME, EDGE, FF})
+    public static void moveBefore(final Context context, final Scriptable scope,
+            final Scriptable thisObj, final Object[] args, final Function function) {
+        ((HTMLElement) thisObj).moveBeforeImpl(args);
+    }
+
+    /**
+     * Add a DOM node as a child to this node before the referenced node.
+     * If the referenced node is null, append to the end.
+     * @param args the arguments
+     * @throws DOMException in case of problems
+     */
+    protected void moveBeforeImpl(final Object[] args) throws org.w3c.dom.DOMException {
+        if (args.length < 2) {
+            throw JavaScriptEngine.typeError(
+                    "Failed to execute 'moveBefore' on 'Element': 2 arguments required, but only 0 present.");
+        }
+
+        final Object movedNodeObject = args[0];
+        if (!(movedNodeObject instanceof Node)) {
+            throw JavaScriptEngine.typeError(
+                    "Failed to execute 'moveBefore' on 'Element': parameter 1 is not of type 'Node'.");
+        }
+        final Object referenceNodeObject = args[1];
+        if (referenceNodeObject != null && !(referenceNodeObject instanceof Node)) {
+            throw JavaScriptEngine.typeError(
+                    "Failed to execute 'moveBefore' on 'Element': parameter 2 is not of type 'Node'.");
+        }
+
+        try {
+            if (referenceNodeObject == null) {
+                getDomNodeOrDie().moveBefore(((Node) movedNodeObject).getDomNodeOrDie(), null);
+                return;
+            }
+
+            getDomNodeOrDie().moveBefore(
+                    ((Node) movedNodeObject).getDomNodeOrDie(), ((Node) referenceNodeObject).getDomNodeOrDie());
+        }
+        catch (final org.w3c.dom.DOMException e) {
+            throw JavaScriptEngine.asJavaScriptException(
+                    getWindow(),
+                    "Failed to execute 'moveChild' on '" + this + ": " + e.getMessage(),
+                    e.code);
+        }
+    }
+
     /**
      * Parses the specified HTML source code, appending the resulting content at the specified target location.
      * @param target the node indicating the position at which the parsed content should be placed
@@ -1687,6 +1742,7 @@ public boolean toggleAttribute(final String name, final Object force) {
     /**
      * Inserts a set of Node objects or string objects after the last child of the Element.
      * String objects are inserted as equivalent Text nodes.
+     *
      * @param context the context
      * @param scope the scope
      * @param thisObj this object
@@ -1706,6 +1762,7 @@ public static void append(final Context context, final Scriptable scope,
     /**
      * Inserts a set of Node objects or string objects before the first child of the Element.
      * String objects are inserted as equivalent Text nodes.
+     *
      * @param context the context
      * @param scope the scope
      * @param thisObj this object
@@ -1725,6 +1782,7 @@ public static void prepend(final Context context, final Scriptable scope,
     /**
      * Replaces the existing children of a Node with a specified new set of children.
      * These can be string or Node objects.
+     *
      * @param context the context
      * @param scope the scope
      * @param thisObj this object
diff --git a/src/test/java/org/htmlunit/javascript/host/html/HTMLElementTest.java b/src/test/java/org/htmlunit/javascript/host/html/HTMLElementTest.java
