Add select() and selectAll()

jsor · Nov 1, 2019 · e5d7e98 · e5d7e98
1 parent c6dfb9d
commit e5d7e98
Show file tree

Hide file tree

Showing 6 changed files with 164 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -54,6 +54,8 @@ import {
     find,
     focusable,
     matches,
+    select,
+    selectAll,
     tabbable
 } from 'domestique';
 ```
@@ -90,6 +92,8 @@ API
   * [find()](#find)
   * [focusable()](#focusable)
   * [matches()](#matches)
+  * [select()](#select)
+  * [selectAll()](#selectall)
   * [tabbable()](#tabbable)
 
 ### Dimension
@@ -621,6 +625,40 @@ Returns `true` if the `element` would be selected by the specified `selector`,
 const isParagraph = matches(element, 'p');
 ```
 
+#### select()
+
+```
+select(context: Element, selector: string): array
+```
+
+Returns the descendant of `context` (`document` or `Element`) which matches the 
+specified `selector`.
+
+##### Example
+
+```javascript
+const paragraph = select(document, 'p');
+
+const spanInsideParagraph = select(paragraph, 'span');
+```
+
+#### selectAll()
+
+```
+select(context: Element, selector: string): array
+```
+
+Returns all descendants of `context` (`document` or `Element`) which match the
+specified `selector`.
+
+##### Example
+
+```javascript
+const allParagraphs = selectAll(document, 'p');
+
+const allSpansInsideFirstParagraph = selectAll(paragraph[0], 'span');
+```
+
 #### tabbable()
 
 ```

diff --git a/index.js b/index.js
@@ -24,6 +24,8 @@ import closest from './src/query/closest';
 import find from './src/query/find';
 import focusable from './src/query/focusable';
 import matches from './src/query/matches';
+import select from './src/query/select';
+import selectAll from './src/query/select-all';
 import tabbable from './src/query/tabbable';
 
 export {
@@ -59,5 +61,7 @@ export {
     find,
     focusable,
     matches,
+    select,
+    selectAll,
     tabbable
 };
diff --git a/src/query/select-all.js b/src/query/select-all.js
@@ -0,0 +1,7 @@
+export default function selectAll(context, selector) {
+    if (!context || typeof context.querySelectorAll !== 'function') {
+        return [];
+    }
+
+    return [].slice.call(context.querySelectorAll(selector));
+}
diff --git a/src/query/select.js b/src/query/select.js
@@ -0,0 +1,7 @@
+export default function select(context, selector) {
+    if (!context || typeof context.querySelector !== 'function') {
+        return null;
+    }
+
+    return context.querySelector(selector);
+}
diff --git a/test/query/select-all.test.js b/test/query/select-all.test.js
@@ -0,0 +1,56 @@
+import {selectAll} from '../..';
+import createFixture from '../fixture';
+
+describe('selectAll()', () => {
+    let fixture;
+
+    beforeEach(() => {
+        fixture = createFixture();
+        fixture.append(
+            '<span id="foo" class="bar"><span id="nested" class="baz"></span></span>'
+        );
+    });
+
+    afterEach(() => {
+        fixture.destroy();
+        fixture = null;
+    });
+
+    it('queries against a CSS selector', () => {
+        const span = document.querySelector('#foo');
+        const nested = document.querySelector('#nested');
+
+        assert.equal(selectAll(span, 'span').length, 1);
+        assert.equal(selectAll(span, 'span')[0], nested);
+
+        assert.equal(selectAll(document, '#foo').length, 1);
+        assert.equal(selectAll(document, '#foo')[0], span);
+
+        assert.equal(selectAll(span, '#nested').length, 1);
+        assert.equal(selectAll(span, '#nested')[0], nested);
+
+        assert.equal(selectAll(document, 'body .bar').length, 1);
+        assert.equal(selectAll(document, 'body .bar')[0], span);
+
+        assert.equal(selectAll(span, 'p').length, 0);
+
+        assert.equal(selectAll(span, '#bar').length, 0);
+    });
+
+    it('works for non-nodes', () => {
+        assert.equal(selectAll(undefined, '#foo').length, 0);
+        assert.equal(selectAll('string', '#foo').length, 0);
+        assert.equal(selectAll(true, '#foo').length, 0);
+        assert.equal(selectAll(null, '#foo').length, 0);
+        assert.equal(selectAll(1, '#foo').length, 0);
+        assert.equal(selectAll(1.2, '#foo').length, 0);
+        assert.equal(selectAll({foo: 'bar'}, '#foo').length, 0);
+        assert.equal(selectAll(['bar'], '#foo').length, 0);
+    });
+
+    it('throws syntax error for invalid selector', () => {
+        assert.throws(() => {
+            selectAll(document, '');
+        });
+    });
+});
diff --git a/test/query/select.test.js b/test/query/select.test.js
@@ -0,0 +1,52 @@
+import {select} from '../..';
+import createFixture from '../fixture';
+
+describe('select()', () => {
+    let fixture;
+
+    beforeEach(() => {
+        fixture = createFixture();
+        fixture.append(
+            '<span id="foo" class="bar"><span id="nested" class="baz"></span></span>'
+        );
+    });
+
+    afterEach(() => {
+        fixture.destroy();
+        fixture = null;
+    });
+
+    it('queries against a CSS selector', () => {
+        const span = document.querySelector('#foo');
+        const nested = document.querySelector('#nested');
+
+        assert.equal(select(span, 'span'), nested);
+
+        assert.equal(select(document, '#foo'), span);
+
+        assert.equal(select(span, '#nested'), nested);
+
+        assert.equal(select(document, 'body .bar'), span);
+
+        assert.isNull(select(span, 'p'));
+
+        assert.isNull(select(span, '#bar'));
+    });
+
+    it('works for non-nodes', () => {
+        assert.isNull(select(undefined, '#foo'));
+        assert.isNull(select('string', '#foo'));
+        assert.isNull(select(true, '#foo'));
+        assert.isNull(select(null, '#foo'));
+        assert.isNull(select(1, '#foo'));
+        assert.isNull(select(1.2, '#foo'));
+        assert.isNull(select({foo: 'bar'}, '#foo'));
+        assert.isNull(select(['bar'], '#foo'));
+    });
+
+    it('throws syntax error for invalid selector', () => {
+        assert.throws(() => {
+            select(document, '');
+        });
+    });
+});