One

README.md

@@ -276,6 +276,26 @@ Returns the owner window for the specified *node*. If *node* is a node, returns
 
 Returns the value of the style property with the specified *name* for the specified *node*. If the *node* has an inline style with the specified *name*, its value is returned; otherwise, the [computed property value](https://developer.mozilla.org/en-US/docs/Web/CSS/computed_value) is returned. See also [*selection*.style](#selection_style).
 
+<a name="one" href="#one">#</a> d3.<b>one</b>(<i>selection</i>, <i>name</i>[, <i>class</i>]) · [Source](https://github.com/d3/d3-selection/blob/master/src/selection/one.js)
+
+A convenience utility for managing a single element of the given <i>name</i> within the given <i>selection</i>. Optionally a <i>class</i> can be specified to disambiguate between siblings of the same name.
+
+For example, consider the following logic for managing an axis container:
+
+```js
+const xAxisG = selection
+  .selectAll(`g.x-axis`)
+  .data([null])
+  .join('g')
+  .attr('class', 'x-axis');
+```
+
+The above logic can be expressed more concisely as:
+
+```js
+const xAxisG = one(selection, 'g', 'x-axis');
+```
+
 ### Modifying Elements
 
 After selecting elements, use the selection’s transformation methods to affect document content. For example, to set the name attribute and color style of an anchor element:

src/index.js

@@ -4,6 +4,7 @@ export {default as local} from "./local.js";
 export {default as matcher} from "./matcher.js";
 export {default as namespace} from "./namespace.js";
 export {default as namespaces} from "./namespaces.js";
+export {default as one} from "./one.js";
 export {default as pointer} from "./pointer.js";
 export {default as pointers} from "./pointers.js";
 export {default as select} from "./select.js";

src/one.js

@@ -0,0 +1,12 @@
+export default (selection, name, className) =>
+  className
+    ? selection
+      .selectAll(`${name}.${className}`)
+      .data([null])
+      .join(name)
+      .attr('class', className)
+    : selection
+      .selectAll(name)
+      .data([null])
+      .join(name);
+

test/selection/one-test.js

@@ -0,0 +1,22 @@
+import assert from "assert";
+import {select, one} from "../../src/index.js";
+import it from "../jsdom.js";
+
+it("selection.one(name) manages a single element", "<div id='container'></div>", () => {
+  const container = document.querySelector("#container");
+  const s = select(container);
+  const div = one(s, "div");
+  assert.strictEqual(div._groups[0][0].tagName, "DIV");
+});
+
+it("selection.one(name, class) elements by class", "<div id='container'></div>", () => {
+  const container = document.querySelector("#container");
+  const s = select(container);
+  const a = one(s, "div", "a");
+  const b = one(s, "div", "b");
+  assert.strictEqual(a._groups[0][0].tagName, "DIV");
+  assert.strictEqual(a._groups[0][0].className, "a");
+  assert.strictEqual(b._groups[0][0].tagName, "DIV");
+  assert.strictEqual(b._groups[0][0].className, "b");
+});
+