From d9e5ce085f416c931479bade14fda2623aa2798a Mon Sep 17 00:00:00 2001
From: Sam Bleckley <sam@mutuallyhuman.com>
Date: Sun, 1 Jan 2017 16:16:46 -0500
Subject: [PATCH] d3-selection: Mark before param of insert() as optional
 (#13090)

Selection<etc>.insert functions perfectly well without a `before` selector -- it does so in many d3 official examples.

This corrects the type signature to mark it as optional.
---
 d3-selection/d3-selection-tests.ts | 77 ++++++++++++------------------
 d3-selection/index.d.ts            |  4 +-
 2 files changed, 32 insertions(+), 49 deletions(-)

diff --git a/d3-selection/d3-selection-tests.ts b/d3-selection/d3-selection-tests.ts
index b1f776c442..042fba622a 100644
--- a/d3-selection/d3-selection-tests.ts
+++ b/d3-selection/d3-selection-tests.ts
@@ -846,60 +846,43 @@ newDiv2 = body.append(function (d, i, g) {
 // without insert<...> typing returned selection has group element of type BaseType
 let newParagraph: d3Selection.Selection<d3Selection.BaseType, BodyDatum, HTMLElement, any>;
 newParagraph = body.insert('p', 'p.second-paragraph');
+newParagraph = body.insert('p');
+
+// Two arguments; the first can be string, selection , or a
+
+const typeValueFunction = function (
+  this: HTMLBodyElement,
+  d: BodyDatum,
+  i: number,
+  g: HTMLBodyElement[] | d3Selection.ArrayLike<HTMLBodyElement>
+) {
+    return this.ownerDocument.createElement('p'); // this-type HTMLParagraphElement
+}
+
+const beforeValueFunction = function (
+  this: HTMLBodyElement,
+  d: BodyDatum,
+  i: number,
+  g: HTMLBodyElement[] | d3Selection.ArrayLike<HTMLBodyElement>
+) {
+    return this.children[0]; 
+}
 
 let newParagraph2: d3Selection.Selection<HTMLParagraphElement, BodyDatum, HTMLElement, any>;
+
+// 2 args, with 3 possibilities each, makes 9 possible combinations:
 newParagraph2 = body.insert<HTMLParagraphElement>('p', 'p.second-paragraph');
+newParagraph2 = body.insert<HTMLParagraphElement>('p', beforeValueFunction);
+newParagraph2 = body.insert<HTMLParagraphElement>('p');
 
 newParagraph2 = body.insert(d3Selection.creator<HTMLParagraphElement>('p'), 'p.second-paragraph');
-newParagraph2 = body.insert(function (d, i, g) {
-    let that: HTMLBodyElement = this;
-    // let that2: SVGElement  = this; // fails, type mismatch
-    let datum: BodyDatum = d;
-    let index: number = i;
-    let group: HTMLBodyElement[] | d3Selection.ArrayLike<HTMLBodyElement> = g;
-    console.log('Body element foo property: ', d.foo); // data of type BodyDatum
-    return this.ownerDocument.createElement('p'); // this-type HTMLParagraphElement
-}, 'p.second-paragraph');
+newParagraph2 = body.insert(d3Selection.creator<HTMLParagraphElement>('p'), beforeValueFunction);
+newParagraph2 = body.insert(d3Selection.creator<HTMLParagraphElement>('p'));
 
-// newParagraph2 = body.insert<HTMLParagraphElement>(function(d) {
-//     return this.ownerDocument.createElement('a'); // fails, HTMLParagraphElement expected by type parameter, HTMLAnchorElement returned
-// }, 'p.second-paragraph');
+newParagraph2 = body.insert(typeValueFunction, 'p.second-paragraph');
+newParagraph2 = body.insert(typeValueFunction, beforeValueFunction);
+newParagraph2 = body.insert(typeValueFunction);
 
-// newParagraph2 = body.insert(function(d) {
-//     return this.ownerDocument.createElement('a'); // fails, HTMLParagraphElement expected by type inference, HTMLAnchorElement returned
-// }, 'p.second-paragraph');
-
-newParagraph2 = body.insert(d3Selection.creator<HTMLParagraphElement>('p'), function (d, i, g) {
-    let that: HTMLBodyElement = this;
-    // let that2: SVGElement  = this; // fails, type mismatch
-    let datum: BodyDatum = d;
-    let index: number = i;
-    let group: HTMLBodyElement[] | d3Selection.ArrayLike<HTMLBodyElement> = g;
-    console.log('Body element foo property: ', d.foo); // data of type BodyDatum
-    return this.children[0]; // this type HTMLBodyElement
-});
-
-newParagraph2 = body.insert(
-    // type
-    function (d, i, g) {
-        let that: HTMLBodyElement = this;
-        // let that2: SVGElement  = this; // fails, type mismatch
-        let datum: BodyDatum = d;
-        let index: number = i;
-        let group: HTMLBodyElement[] | d3Selection.ArrayLike<HTMLBodyElement> = g;
-        console.log('Body element foo property: ', d.foo); // data of type BodyDatum
-        return this.ownerDocument.createElement('p'); // this-type HTMLParagraphElement
-    },
-    // before
-    function (d, i, g) {
-        let that: HTMLBodyElement = this;
-        // let that2: SVGElement  = this; // fails, type mismatch
-        let datum: BodyDatum = d;
-        let index: number = i;
-        let group: HTMLBodyElement[] | d3Selection.ArrayLike<HTMLBodyElement> = g;
-        console.log('Body element foo property: ', d.foo); // data of type BodyDatum
-        return this.children[0]; // this type HTMLBodyElement
-    });
 
 // sort(...) -----------------------------------------------------------------------------
 
diff --git a/d3-selection/index.d.ts b/d3-selection/index.d.ts
index 0380e10c9d..029a986024 100644
--- a/d3-selection/index.d.ts
+++ b/d3-selection/index.d.ts
@@ -509,7 +509,7 @@ interface Selection<GElement extends BaseType, Datum, PElement extends BaseType,
      * (for example, svg implies svg:svg)
      * @param before A CSS selector string for the element before which the insertion should occur.
      */
-    insert<ChildElement extends BaseType>(type: string, before: string): Selection<ChildElement, Datum, PElement, PDatum>;
+    insert<ChildElement extends BaseType>(type: string, before?: string): Selection<ChildElement, Datum, PElement, PDatum>;
     /**
      * Inserts a new element of the type provided by the element creator function before the element matching the specified "before"
      * selector string for each selected element.
@@ -524,7 +524,7 @@ interface Selection<GElement extends BaseType, Datum, PElement extends BaseType,
      * an element to be inserted. (The function typically creates a new element, but it may instead return an existing element.)
      * @param before A CSS selector string for the element before which the insertion should occur.
      */
-    insert<ChildElement extends BaseType>(type: ValueFn<GElement, Datum, ChildElement>, before: string): Selection<ChildElement, Datum, PElement, PDatum>;
+    insert<ChildElement extends BaseType>(type: ValueFn<GElement, Datum, ChildElement>, before?: string): Selection<ChildElement, Datum, PElement, PDatum>;
     /**
      * Inserts a new element of the specified type (tag name) before the element returned by the "before" child selector function
      * for each selected element.