Merge pull request #339 from toasted-nutbread/type-annotations

Type annotations

3 files changed, 63 insertions, 15 deletions

diff --git a/ext/js/accessibility/accessibility-controller.js b/ext/js/accessibility/accessibility-controller.js
index e9a24880..8250b369 100644
--- a/ext/js/accessibility/accessibility-controller.js
+++ b/ext/js/accessibility/accessibility-controller.js
@@ -16,7 +16,6 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import {ScriptManager} from '../background/script-manager.js';
 import {log} from '../core.js';
 
 /**
@@ -25,18 +24,22 @@ import {log} from '../core.js';
 export class AccessibilityController {
     /**
      * Creates a new instance.
-     * @param {ScriptManager} scriptManager An instance of the `ScriptManager` class.
+     * @param {import('../background/script-manager.js').ScriptManager} scriptManager An instance of the `ScriptManager` class.
      */
     constructor(scriptManager) {
+        /** @type {import('../background/script-manager.js').ScriptManager} */
         this._scriptManager = scriptManager;
+        /** @type {?import('core').TokenObject} */
         this._updateGoogleDocsAccessibilityToken = null;
+        /** @type {?Promise<void>} */
         this._updateGoogleDocsAccessibilityPromise = null;
+        /** @type {boolean} */
         this._forceGoogleDocsHtmlRenderingAny = false;
     }
 
     /**
      * Updates the accessibility handlers.
-     * @param {object} fullOptions The full options object from the `Backend` instance.
+     * @param {import('settings').Options} fullOptions The full options object from the `Backend` instance.
      *   The value is treated as read-only and is not modified.
      */
     async update(fullOptions) {
@@ -53,8 +56,12 @@ export class AccessibilityController {
 
     // Private
 
+    /**
+     * @param {boolean} forceGoogleDocsHtmlRenderingAny
+     */
     async _updateGoogleDocsAccessibility(forceGoogleDocsHtmlRenderingAny) {
         // Reentrant token
+        /** @type {?import('core').TokenObject} */
         const token = {};
         this._updateGoogleDocsAccessibilityToken = token;
 
@@ -72,6 +79,9 @@ export class AccessibilityController {
         this._updateGoogleDocsAccessibilityPromise = null;
     }
 
+    /**
+     * @param {boolean} forceGoogleDocsHtmlRenderingAny
+     */
     async _updateGoogleDocsAccessibilityInner(forceGoogleDocsHtmlRenderingAny) {
         if (this._forceGoogleDocsHtmlRenderingAny === forceGoogleDocsHtmlRenderingAny) { return; }
 
@@ -81,6 +91,7 @@ export class AccessibilityController {
         try {
             if (forceGoogleDocsHtmlRenderingAny) {
                 if (await this._scriptManager.isContentScriptRegistered(id)) { return; }
+                /** @type {import('script-manager').RegistrationDetails} */
                 const details = {
                     allFrames: true,
                     matchAboutBlank: true,
diff --git a/ext/js/accessibility/google-docs-util.js b/ext/js/accessibility/google-docs-util.js
index e170f334..4321f082 100644
--- a/ext/js/accessibility/google-docs-util.js
+++ b/ext/js/accessibility/google-docs-util.js
@@ -17,7 +17,6 @@
  */
 
 import {DocumentUtil} from '../dom/document-util.js';
-import {TextSourceElement} from '../dom/text-source-element.js';
 import {TextSourceRange} from '../dom/text-source-range.js';
 
 /**
@@ -29,8 +28,8 @@ export class GoogleDocsUtil {
      * Coordinates are provided in [client space](https://developer.mozilla.org/en-US/docs/Web/CSS/CSSOM_View/Coordinate_systems).
      * @param {number} x The x coordinate to search at.
      * @param {number} y The y coordinate to search at.
-     * @param {GetRangeFromPointOptions} options Options to configure how element detection is performed.
-     * @returns {?TextSourceRange|TextSourceElement} A range for the hovered text or element, or `null` if no applicable content was found.
+     * @param {import('document-util').GetRangeFromPointOptions} options Options to configure how element detection is performed.
+     * @returns {?TextSourceRange} A range for the hovered text or element, or `null` if no applicable content was found.
      */
     static getRangeFromPoint(x, y, {normalizeCssZoom}) {
         const styleNode = this._getStyleNode();
@@ -46,10 +45,13 @@ export class GoogleDocsUtil {
         return null;
     }
 
+    /**
+     * @returns {HTMLStyleElement}
+     */
     static _getStyleNode() {
         // This <style> node is necessary to force the SVG <rect> elements to have a fill,
         // which allows them to be included in document.elementsFromPoint's return value.
-        if (this._styleNode === null) {
+        if (typeof this._styleNode === 'undefined') {
             const style = document.createElement('style');
             style.textContent = [
                 '.kix-canvas-tile-content{pointer-events:none!important;}',
@@ -64,21 +66,34 @@ export class GoogleDocsUtil {
         return this._styleNode;
     }
 
+    /**
+     * @param {Element} element
+     * @param {string} text
+     * @param {number} x
+     * @param {number} y
+     * @param {boolean} normalizeCssZoom
+     * @returns {TextSourceRange}
+     */
     static _createRange(element, text, x, y, normalizeCssZoom) {
         // Create imposter
         const content = document.createTextNode(text);
         const svgText = document.createElementNS('http://www.w3.org/2000/svg', 'text');
         const transform = element.getAttribute('transform') || '';
         const font = element.getAttribute('data-font-css') || '';
-        svgText.setAttribute('x', element.getAttribute('x'));
-        svgText.setAttribute('y', element.getAttribute('y'));
+        const elementX = element.getAttribute('x');
+        const elementY = element.getAttribute('y');
+        if (typeof elementX === 'string') { svgText.setAttribute('x', elementX); }
+        if (typeof elementY === 'string') { svgText.setAttribute('y', elementY); }
         svgText.appendChild(content);
         const textStyle = svgText.style;
         this._setImportantStyle(textStyle, 'all', 'initial');
         this._setImportantStyle(textStyle, 'transform', transform);
         this._setImportantStyle(textStyle, 'font', font);
         this._setImportantStyle(textStyle, 'text-anchor', 'start');
-        element.parentNode.appendChild(svgText);
+        const {parentNode} = element;
+        if (parentNode !== null) {
+            parentNode.appendChild(svgText);
+        }
 
         // Adjust offset
         const elementRect = element.getBoundingClientRect();
@@ -93,6 +108,13 @@ export class GoogleDocsUtil {
         return TextSourceRange.createFromImposter(range, svgText, element);
     }
 
+    /**
+     * @param {Text} textNode
+     * @param {number} x
+     * @param {number} y
+     * @param {boolean} normalizeCssZoom
+     * @returns {Range}
+     */
     static _getRangeWithPoint(textNode, x, y, normalizeCssZoom) {
         if (normalizeCssZoom) {
             const scale = DocumentUtil.computeZoomScale(textNode);
@@ -101,7 +123,7 @@ export class GoogleDocsUtil {
         }
         const range = document.createRange();
         let start = 0;
-        let end = textNode.nodeValue.length;
+        let end = /** @type {string} */ (textNode.nodeValue).length;
         while (end - start > 1) {
             const mid = Math.floor((start + end) / 2);
             range.setStart(textNode, mid);
@@ -117,9 +139,16 @@ export class GoogleDocsUtil {
         return range;
     }
 
+    /**
+     * @param {CSSStyleDeclaration} style
+     * @param {string} propertyName
+     * @param {string} value
+     */
     static _setImportantStyle(style, propertyName, value) {
         style.setProperty(propertyName, value, 'important');
     }
 }
+
+/** @type {HTMLStyleElement|undefined} */
 // eslint-disable-next-line no-underscore-dangle
-GoogleDocsUtil._styleNode = null;
+GoogleDocsUtil._styleNode = void 0;
diff --git a/ext/js/accessibility/google-docs.js b/ext/js/accessibility/google-docs.js
index f9290078..27841b6d 100644
--- a/ext/js/accessibility/google-docs.js
+++ b/ext/js/accessibility/google-docs.js
@@ -18,9 +18,17 @@
 
 (async () => {
     // Reentrant check
+    // @ts-expect-error - Checking a property to the global object
     if (self.googleDocsAccessibilitySetup) { return; }
+    // @ts-expect-error - Adding a property to the global object
     self.googleDocsAccessibilitySetup = true;
 
+    /**
+     * @template [TReturn=unknown]
+     * @param {string} action
+     * @param {import('core').SerializableObject} params
+     * @returns {Promise<TReturn>}
+     */
     const invokeApi = (action, params) => {
         return new Promise((resolve, reject) => {
             chrome.runtime.sendMessage({action, params}, (response) => {
@@ -37,6 +45,7 @@
     };
 
     const optionsContext = {depth: 0, url: location.href};
+    /** @type {import('api').OptionsGetResult} */
     let options;
     try {
         options = await invokeApi('optionsGet', {optionsContext});
@@ -48,9 +57,8 @@
 
     // The extension ID below is on an allow-list that is used on the Google Docs webpage.
     /* eslint-disable */
-    const inject = () => {
-        window._docs_annotate_canvas_by_ext = 'ogmnaimimemjmbakcfefmnahgdfhfami';
-    };
+    // @ts-expect-error : Adding a property to the global object
+    const inject = () => { window._docs_annotate_canvas_by_ext = 'ogmnaimimemjmbakcfefmnahgdfhfami'; };
     /* eslint-enable */
 
     let parent = document.head;