feat: add function to select a single element

sometimes you need to accept only a single element, selectOne allows you to do that

Author: TimoBechtel

README.md

@@ -19,7 +19,7 @@
   ·
 </p>
 
-You are writing a JavaScript library and need to accept one or more HTML elements? But you want to leave your users a broad choice, how to select them? Then this is for you.
+You are writing a JavaScript library and need to receive one or more HTML elements? But you want to leave your users a broad choice, on how to select them? Then this might be for you.
 
 ## Table of Contents
 
@@ -35,7 +35,7 @@ You are writing a JavaScript library and need to accept one or more HTML element
 
 Universal Element Accept (uea) allows you to accept a range of different inputs as HTML elements.
 
-It accepts, query selector strings, arrays, NodeLists and more (check out [usage](#usage)) and always returns an array with HTMLElements.
+It accepts query selector strings, arrays, NodeLists and more (check out [usage](#usage)) and always returns either an array with HTMLElements or a single element, depending on the function you use.
 
 ## Install
 
@@ -56,14 +56,20 @@ npm install @compactjs/uea
 ### As module:
 
 ```javascript
-import { accept } from '@compactjs/uea';
+import { select, selectOne } from '@compactjs/uea';
 ```
 
 ### Example:
 
 ```javascript
-accept('.my-classes');
-accept(document.getElementById('my-id'));
+// select multiple elements
+select('.my-classes');
+select(document.getElementById('my-id'));
+select(document.forms);
+
+// or only select a single element
+selectOne('.my-classes');
+selectOne(document.getElementById('my-id'));
 ```
 
 Check out the [demo](https://compactjs.github.io/uea/)
@@ -73,11 +79,18 @@ and the [examples file](https://github.com/CompactJS/uea/blob/main/example/index
 
 ```typescript
 /**
- * Allow a range of different ways to select HTML Elements
+ * Use a range of different ways to select HTML elements.
+ * Always returns an array of elements.
  */
-function accept(
+export function select(
   input: string | HTMLElement | HTMLElement[] | HTMLCollection | NodeList
 ): HTMLElement[];
+
+/**
+ * Use a range of different ways to select an HTMLElement.
+ * Always returns a single HTMLElement.
+ */
+export function selectOne(selector: string | HTMLElement): HTMLElement | null;
 ```
 
 ## Run tests

package.json

@@ -16,7 +16,8 @@
     "test": "jest"
   },
   "files": [
-    "dist"
+    "dist",
+    "package.json"
   ],
   "repository": {
     "type": "git",

src/index.ts

@@ -5,20 +5,42 @@ export type UniversalElementSelector =
   | HTMLCollection
   | NodeList;
 
-export const accept = (input: UniversalElementSelector): HTMLElement[] => {
+export type SingleElementSelector = string | HTMLElement;
+
+/**
+ * Allow a range of different ways to select HTML Elements.
+ * Always returns a single element.
+ */
+export function selectOne(selector: SingleElementSelector): HTMLElement | null {
+  if (typeof selector === 'string') {
+    return document.querySelector<HTMLElement>(selector);
+  } else if (selector instanceof HTMLElement) {
+    return selector;
+  }
+  return null;
+}
+
+/**
+ * alias for backwards compatibility
+ * @deprecated use select() instead
+ */
+export const accept = select;
+
+/**
+ * Allow a range of different ways to select HTML Elements.
+ * Always returns an array of HTMLElements.
+ */
+export function select(input: UniversalElementSelector): HTMLElement[] {
   if (typeof input === 'string')
     return Array.from(document.querySelectorAll(input));
   if (Array.isArray(input)) return input;
   if ('length' in input)
     return Array.from(input).reduce(nodeToElementArray, []);
   return [input];
-};
+}
 
 // typeguard
-const nodeToElementArray = (
-  array: HTMLElement[],
-  node: Node
-): HTMLElement[] => {
+function nodeToElementArray(array: HTMLElement[], node: Node): HTMLElement[] {
   if (node.nodeType === Node.ELEMENT_NODE) array.push(node as HTMLElement);
   return array;
-};
+}

test/accept.test.ts

@@ -1,6 +1,6 @@
-import { accept } from '../src/index';
+import { accept, selectOne } from '../src/index';
 
-describe('accept', () => {
+describe('accepts multiple', () => {
   it('returns a HTMLElement list for strings', () => {
     document.body.innerHTML = `
 				<h1></h1>
@@ -40,3 +40,23 @@ describe('accept', () => {
     expect(acceptedElements[0]).toBeInstanceOf(HTMLFormElement);
   });
 });
+
+describe('accepts single', () => {
+  it('returns a HTMLElement for a string input', () => {
+    document.body.innerHTML = `
+				<h1></h1>
+				<div class="a-class"></div>
+				<span id="empty">empty</span>
+			`;
+    const element: HTMLElement = selectOne('h1');
+    expect(element).toBeInstanceOf(HTMLHeadingElement);
+
+    const element2: HTMLElement = selectOne('.a-class');
+    expect(element2).toBeInstanceOf(HTMLDivElement);
+  });
+  it('returns an HTMLElement with a HTMLElement as input', () => {
+    const element = document.createElement('div');
+    const acceptedElement = selectOne(element);
+    expect(acceptedElement).toBeInstanceOf(HTMLDivElement);
+  });
+});