From 4da4827bcbcdd1ef163f635d9b29416ff272b0bb Mon Sep 17 00:00:00 2001
From: toasted-nutbread <toasted-nutbread@users.noreply.github.com>
Date: Mon, 27 Nov 2023 12:48:14 -0500
Subject: Add JSDoc type annotations to project (rebased)

---
 ext/js/dom/native-simple-dom-parser.js | 74 +++++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 10 deletions(-)

(limited to 'ext/js/dom/native-simple-dom-parser.js')

diff --git a/ext/js/dom/native-simple-dom-parser.js b/ext/js/dom/native-simple-dom-parser.js
index 882469a0..418a4e3c 100644
--- a/ext/js/dom/native-simple-dom-parser.js
+++ b/ext/js/dom/native-simple-dom-parser.js
@@ -17,35 +17,89 @@
  */
 
 export class NativeSimpleDOMParser {
+    /**
+     * @param {string} content
+     */
     constructor(content) {
+        /** @type {Document} */
         this._document = new DOMParser().parseFromString(content, 'text/html');
     }
 
-    getElementById(id, root=null) {
-        return (root || this._document).querySelector(`[id='${id}']`);
+    /**
+     * @param {string} id
+     * @param {import('simple-dom-parser').Element} [root]
+     * @returns {?import('simple-dom-parser').Element}
+     */
+    getElementById(id, root) {
+        return this._convertElementOrDocument(root).querySelector(`[id='${id}']`);
     }
 
-    getElementByTagName(tagName, root=null) {
-        return (root || this._document).querySelector(tagName);
+    /**
+     * @param {string} tagName
+     * @param {import('simple-dom-parser').Element} [root]
+     * @returns {?import('simple-dom-parser').Element}
+     */
+    getElementByTagName(tagName, root) {
+        return this._convertElementOrDocument(root).querySelector(tagName);
     }
 
-    getElementsByTagName(tagName, root=null) {
-        return [...(root || this._document).querySelectorAll(tagName)];
+    /**
+     * @param {string} tagName
+     * @param {import('simple-dom-parser').Element} [root]
+     * @returns {import('simple-dom-parser').Element[]}
+     */
+    getElementsByTagName(tagName, root) {
+        return [...this._convertElementOrDocument(root).querySelectorAll(tagName)];
     }
 
-    getElementsByClassName(className, root=null) {
-        return [...(root || this._document).querySelectorAll(`.${className}`)];
+    /**
+     * @param {string} className
+     * @param {import('simple-dom-parser').Element} [root]
+     * @returns {import('simple-dom-parser').Element[]}
+     */
+    getElementsByClassName(className, root) {
+        return [...this._convertElementOrDocument(root).querySelectorAll(`.${className}`)];
     }
 
+    /**
+     * @param {import('simple-dom-parser').Element} element
+     * @param {string} attribute
+     * @returns {?string}
+     */
     getAttribute(element, attribute) {
-        return element.hasAttribute(attribute) ? element.getAttribute(attribute) : null;
+        const element2 = this._convertElement(element);
+        return element2.hasAttribute(attribute) ? element2.getAttribute(attribute) : null;
     }
 
+    /**
+     * @param {import('simple-dom-parser').Element} element
+     * @returns {string}
+     */
     getTextContent(element) {
-        return element.textContent;
+        const {textContent} = this._convertElement(element);
+        return typeof textContent === 'string' ? textContent : '';
     }
 
+    /**
+     * @returns {boolean}
+     */
     static isSupported() {
         return typeof DOMParser !== 'undefined';
     }
+
+    /**
+     * @param {import('simple-dom-parser').Element} element
+     * @returns {Element}
+     */
+    _convertElement(element) {
+        return /** @type {Element} */ (element);
+    }
+
+    /**
+     * @param {import('simple-dom-parser').Element|undefined} element
+     * @returns {Element|Document}
+     */
+    _convertElementOrDocument(element) {
+        return typeof element !== 'undefined' ? /** @type {Element} */ (element) : this._document;
+    }
 }
-- 
cgit v1.2.3