adds dom/insertAt

docs/dom.md

@@ -100,6 +100,39 @@ var f = fragment(element);
 ```
 
 
+## insertAt(parent, nodes, index)
+
+Inserts a node or an array of nodes into the parents list of children at given index. Any
+index smaller than 1 will lead into prepending the nodes and any index larger than the
+amount of children in the parent node will result in appending the nodes.
+
+```html
+<ul id="list">
+    <li>One</li>
+    <li>Two</li>
+    <li>Four</li>
+    <li>Five</li>
+</ul>
+```
+```js
+var three = document.createElement("li");
+three.innerText = "Three";
+
+var ul = document.getElementById("list");
+
+insertAt(ul, three, 2);
+```
+This results in:
+```html
+<ul id="list">
+    <li>One</li>
+    <li>Two</li>
+    <li>Three</li>
+    <li>Four</li>
+    <li>Five</li>
+</ul>
+```
+
 ## matches(selector, items...)
 
 Returns true if all items match the CSS selector.

source/dom/insertAt.js

@@ -0,0 +1,24 @@
+define([
+    "mout/math/clamp",
+    "./append",
+    "../utils/allNodes"
+], function(clamp, append, allNodes) {
+
+    function insertAt(parent, nodes, index) {
+
+        index = Math.max(index, 0);
+
+        if (index >= parent.children.length) {
+            append(parent, nodes);
+        } else {
+            var sibling;
+            allNodes(nodes, function(node) {
+                sibling = parent.children[ index ];
+                parent.insertBefore(node, sibling);
+                index++;
+            });
+        }
+    }
+
+    return insertAt;
+});

tests/dom/spec-insertAt.js

@@ -0,0 +1,73 @@
+define(["cane/dom/insertAt"], function(insertAt) {
+
+    describe("dom/insertAt", function() {
+
+        it("should insert node at index", function() {
+            var parent = document.createElement("div"),
+                first = document.createElement("span"),
+                second = document.createElement("span"),
+                third = document.createElement("span"),
+                div = document.createElement("div");
+
+            parent.appendChild(first);
+            parent.appendChild(second);
+            parent.appendChild(third);
+
+            insertAt(parent, div, 1);
+
+            expect(parent.children[1]).to.be(div);
+        });
+
+        it("should append if index is higher then children", function() {
+            var parent = document.createElement("div"),
+                first = document.createElement("span"),
+                second = document.createElement("span"),
+                third = document.createElement("span"),
+                div = document.createElement("div");
+
+            parent.appendChild(first);
+            parent.appendChild(second);
+            parent.appendChild(third);
+
+            insertAt(parent, div, 10);
+
+            expect(parent.children[3]).to.be(div);
+        });
+
+        it("should prepend node if index small than 1", function() {
+            var parent = document.createElement("div"),
+                first = document.createElement("span"),
+                second = document.createElement("span"),
+                third = document.createElement("span"),
+                div = document.createElement("div");
+
+            parent.appendChild(first);
+            parent.appendChild(second);
+            parent.appendChild(third);
+
+            insertAt(parent, div, -25);
+
+            expect(parent.children[0]).to.be(div);
+        });
+
+        it("should insert multiple nodes", function() {
+            var parent = document.createElement("div"),
+                first = document.createElement("span"),
+                second = document.createElement("span"),
+                third = document.createElement("span"),
+                foo = document.createElement("div"),
+                bar = document.createElement("div");
+
+            parent.appendChild(first);
+            parent.appendChild(second);
+            parent.appendChild(third);
+
+            insertAt(parent, [foo, bar], 1);
+
+            expect(parent.children[1]).to.be(foo);
+            expect(parent.children[2]).to.be(bar);
+        });
+
+    });
+
+});