textbrowser 0.50.0 → 0.51.0

package/resources/templates/index.js

@@ -16,7 +16,7 @@ const Templates = {
     // We empty rather than `replaceWith` as our Jamilih `body`
     //   aliases expect the old instance
     while (body.hasChildNodes()) {
-      body.firstChild.remove();
+      body.firstChild?.remove();
     }
     return jml('div', {
       id: 'main', role: 'main'
@@ -24,19 +24,25 @@ const Templates = {
   },
   permissions: {
     versionChange () {
-      $('#versionChange').showModal();
+      /** @type {HTMLDialogElement} */
+      ($('#versionChange'))?.showModal();
     },
+
+    /**
+     * @param {{text: string}} cfg
+     */
     addLogEntry ({text}) {
       const installationDialog = $('#installationLogContainer');
       try {
-        installationDialog.showModal();
-        const container = $('#dialogContainer');
+        /** @type {HTMLDialogElement} */
+        (installationDialog).showModal();
+        const container = /** @type {HTMLElement} */ ($('#dialogContainer'));
         container.hidden = false;
       // eslint-disable-next-line no-unused-vars -- Ok
       } catch (err) {
         // May already be open
       }
-      $('#installationLog').append(text + '\n');
+      /** @type {HTMLElement} */ ($('#installationLog')).append(text + '\n');
     },
     exitDialogs () {
       const container = $('#dialogContainer');
@@ -44,6 +50,12 @@ const Templates = {
         container.hidden = true;
       }
     },
+    /**
+     * @param {{
+     *   type: string,
+     *   escapedErrorMessage: string
+     * }} cfg
+     */
     dbError ({type, escapedErrorMessage}) {
       if (type) {
         jml('span', [
@@ -51,26 +63,33 @@ const Templates = {
           escapedErrorMessage
         ], $('#dbError'));
       }
-      $('#dbError').showModal();
+      /** @type {HTMLDialogElement} */
+      ($('#dbError')).showModal();
     },
+
+    /**
+     * @param {string} escapedErrorMessage
+     */
     errorRegistering (escapedErrorMessage) {
       if (escapedErrorMessage) {
         jml('span', [escapedErrorMessage], $('#errorRegistering'));
       }
-      $('#errorRegistering').showModal();
+      /** @type {HTMLDialogElement} */
+      ($('#errorRegistering')).showModal();
     },
     browserNotGrantingPersistence () {
-      $('#browserNotGrantingPersistence').showModal();
+      /** @type {HTMLDialogElement} */
+      ($('#browserNotGrantingPersistence')).showModal();
     },
     /**
-     * @param {PlainObject} cfg
-     * @param {I18NCallback} cfg.siteI18n
-     * @param {() => Promise<void>} cfg.ok
-     * @param {() => void} cfg.refuse
-     * @param {() => Promise<void>} cfg.close
-     * @param {() => void} cfg.closeBrowserNotGranting
+     * @param {object} cfg
+     * @param {import('intl-dom').I18NCallback} cfg.siteI18n
+     * @param {() => Promise<void>} [cfg.ok]
+     * @param {() => void} [cfg.refuse]
+     * @param {() => Promise<void>} [cfg.close]
+     * @param {() => void} [cfg.closeBrowserNotGranting]
      * @returns {[
-     *   HTMLDialogElement, HTMLDialogElement, HTMLDialogElement,
+     *   HTMLDialogElement, HTMLDialogElement|"", HTMLDialogElement|"",
      *   HTMLDialogElement, HTMLDialogElement, HTMLDialogElement
      * ]}
      */
@@ -89,8 +108,10 @@ const Templates = {
         ]]
         // ['textarea', {readonly: true, style: 'width: 80%; height: 80%;'}]
       ]);
+
+      /** @type {""|HTMLDialogElement} */
       let requestPermissionsDialog = '';
-      if (ok) {
+      if (ok && refuse && close) {
         requestPermissionsDialog = jml(
           'dialog', {
             id: 'willRequestStoragePermissions',
@@ -121,6 +142,8 @@ const Templates = {
           ]]
         ]
       );
+
+      /** @type {""|HTMLDialogElement} */
       let browserNotGrantingPersistenceAlert = '';
       if (closeBrowserNotGranting) {
         browserNotGrantingPersistenceAlert = jml(

package/resources/templates/languageSelect.js

@@ -1,7 +1,17 @@
 import {jml, $} from 'jamilih';
+
+// @ts-expect-error Missing TS types
 import {deserialize as formDeserialize} from 'form-serialization';
 
 export default {
+  /**
+   * @param {{
+   *   langs: import('../../server/main.js').LanguageInfo[]
+   *   languages: import('../utils/Languages.js').Languages
+   *   followParams: (formSelector: string, cb: () => void) => void
+   *   $p: import('../utils/IntlURLSearchParams.js').default
+   * }} cfg
+   */
   main ({langs, languages, followParams, $p}) {
     jml('form', {class: 'focus', id: 'languageSelectionContainer', $on: {
       submit (e) {
@@ -12,7 +22,10 @@ export default {
         name: 'lang',
         size: langs.length,
         $on: {
-          click ({target: {parentNode: {selectedOptions}}}) {
+          click ({target: {parentNode: {
+            // @ts-expect-error Ok
+            selectedOptions
+          }}}) {
             followParams('#languageSelectionContainer', () => {
               $p.set('lang', selectedOptions[0].value, true);
             });

package/resources/templates/resultsDisplayClient.js

@@ -3,9 +3,20 @@ import Templates from './index.js';
 import {dialogs} from '../utils/dialogs.js';
 
 export default {
+  /**
+   * @param {{
+   *   anchorRowCol: string
+   * }} cfg
+   */
   anchorRowCol ({anchorRowCol}) {
     return $('#' + anchorRowCol);
   },
+  /**
+   * @param {{
+   *   escapedRow: string
+   *   escapedCol: string|undefined
+   * }} cfg
+   */
   anchors ({escapedRow, escapedCol}) {
     const sel = 'tr[data-row="' + escapedRow + '"]' +
             (escapedCol
@@ -13,16 +24,24 @@ export default {
               : '');
     return $(sel);
   },
-  main (...args) {
+
+  /**
+   * @param {import('./resultsDisplayServerOrClient.js').ResultsDisplayServerOrClientArgs} args
+   */
+  main (args) {
     let html;
     try {
-      html = Templates.resultsDisplayServerOrClient.main(...args);
-    } catch (err) {
+      html = /** @type {import('jamilih').JamilihArray} */ (
+        Templates.resultsDisplayServerOrClient.main(args)
+      );
+    } catch (error) {
+      const err = /** @type {Error} */ (error);
       if (err.message === 'JSON support is currently not available') {
         dialogs.alert(err.message);
       } else {
         console.error(err);
       }
+      return;
     }
     jml(...html, $('#main'));
   }

package/resources/templates/resultsDisplayServerOrClient.js

@@ -1,26 +1,96 @@
 import Templates from './index.js';
 
+/**
+ * @typedef {number} Integer
+ */
+/**
+ * @typedef {{
+ *   interlinearSeparator?: string,
+ *   showEmptyInterlinear?: boolean,
+ *   showTitleOnSingleInterlinear?: boolean,
+ *   tableData: (string|Integer)[][],
+ *   $p: import('../utils/IntlURLSearchParams.js').default,
+ *   $pRaw: (key: string, avoidLog?: boolean) => string,
+ *   $pRawEsc: (str: string) => string,
+ *   $pEscArbitrary: (str: string) => string,
+ *   escapeQuotedCSS: (str: string) => string,
+ *   escapeCSS: (str: string) => string,
+ *   escapeHTML: (str: string) => string,
+ *   l: import('intl-dom').I18NCallback,
+ *   localizedFieldNames: (string|string[]|import('../../server/main.js').LocalizationStrings)[],
+ *   fieldLangs: (string|null)[],
+ *   fieldDirs: (string | null)[],
+ *   caption?: string,
+ *   hasCaption: boolean,
+ *   showInterlinTitles: boolean,
+ *   determineEnd: import('../resultsDisplay.js').DetermineEnd,
+ *   getCanonicalID: import('../resultsDisplay.js').GetCanonicalID,
+ *   canonicalBrowseFieldSetName: string,
+ *   getCellValue: import('../resultsDisplay.js').GetCellValue,
+ *   checkedAndInterlinearFieldInfo: [string[], number[], ("" | number[] | null)[]]
+ * }} ResultsDisplayServerOrClientArgs
+ */
+
 export default {
+  /**
+   * @param {{
+   *   heading: string,
+   *   ranges: string
+   * }} cfg
+   */
   caption ({heading, ranges}) {
     return heading + ' ' + ranges;
   },
+  /**
+   * @param {{
+   *   l: import('intl-dom').I18NCallback
+   * }} cfg
+   * @returns {string}
+   */
   startSeparator ({l}) {
-    return l('colon');
+    return /** @type {string} */ (l('colon'));
   },
+
+  /**
+   * @param {{
+   *   l: import('intl-dom').I18NCallback
+   * }} cfg
+   */
   innerBrowseFieldSeparator ({l}) {
-    return l('comma-space');
+    return /** @type {string} */ (l('comma-space'));
   },
+  /**
+   * @param {{
+  *   l: import('intl-dom').I18NCallback,
+  *   startRange: string,
+  *   endVals: string[],
+  *   rangeNames: string
+  * }} cfg
+  */
   ranges ({l, startRange, endVals, rangeNames}) {
     return startRange +
-            // l('to').toLowerCase() + ' ' +
-            '-' +
-            endVals.join(
-              Templates.resultsDisplayServerOrClient.startSeparator({l})
-            ) + ' (' + rangeNames + ')';
+      // l('to').toLowerCase() + ' ' +
+      '-' +
+      endVals.join(
+        Templates.resultsDisplayServerOrClient.startSeparator({l})
+      ) + ' (' + rangeNames + ')';
   },
+  /**
+   * @param {{
+   *   key: string,
+   *   value: string|number
+   * }} cfg
+   */
   fieldValueAlias ({key, value}) {
     return value + ' (' + key + ')';
   },
+  /**
+   * @param {{
+   *   lang?: string|null,
+   *   dir?: string|null,
+   *   html: string
+   * }} cfg
+   */
   interlinearSegment ({lang, dir, html}) {
     return `<span${
       lang ? ` lang="${lang}"` : ''
@@ -28,10 +98,30 @@ export default {
       dir ? ` dir="${dir}"` : ''
     }>${html}</span>`;
   },
+
+  /**
+   * @param {{
+  *   l: import('intl-dom').I18NCallback,
+  *   val: string
+  * }} cfg
+  */
   interlinearTitle ({l, val}) {
     const colonSpace = l('colon-space');
     return `<span class="interlintitle">${val}</span>${colonSpace}`;
   },
+  /**
+   * @param {{
+   *   $p: import('../utils/IntlURLSearchParams.js').default,
+   *   $pRaw: (key: string, avoidLog?: boolean) => string,
+   *   $pRawEsc: (str: string) => string,
+   *   $pEscArbitrary: (str: string) => string,
+   *   escapeCSS: (str: string) => string,
+   *   tableWithFixedHeaderAndFooter: boolean,
+   *   checkedFieldIndexes: number[],
+   *   hasCaption: boolean
+   * }} cfg
+   * @returns {import('jamilih').JamilihArray}
+   */
   styles ({
     $p, $pRaw, $pRawEsc, $pEscArbitrary, // escapeQuotedCSS,
     escapeCSS,
@@ -176,16 +266,32 @@ body {
               : '')
     ]];
   },
+
+  /**
+   * @param {ResultsDisplayServerOrClientArgs} args
+   * @returns {import('jamilih').JamilihArray}
+   */
   main ({
     tableData, $p, $pRaw, $pRawEsc, $pEscArbitrary,
     // Todo: escaping should be done in business logic!
-    escapeQuotedCSS, escapeCSS, escapeHTML,
+    // escapeQuotedCSS,
+    escapeCSS, escapeHTML,
     l, localizedFieldNames, fieldLangs, fieldDirs,
     caption, hasCaption, showInterlinTitles,
     determineEnd, getCanonicalID, canonicalBrowseFieldSetName,
     getCellValue, checkedAndInterlinearFieldInfo,
+    showEmptyInterlinear,
+    showTitleOnSingleInterlinear,
     interlinearSeparator = '<br /><br />'
   }) {
+    /**
+     * @type {{
+     *   table: [string, (import('jamilih').JamilihAttributes | undefined)?][],
+     *   div: [string, (import('jamilih').JamilihAttributes | undefined)?][],
+     *   "json-array": "json",
+     *   "json-object": "json"
+     * }}
+     */
     const tableOptions = {
       table: [
         ['table', {class: 'table', border: $pRaw('border') || '0'}],
@@ -214,7 +320,7 @@ body {
       'json-array': 'json',
       'json-object': 'json'
     };
-    const outputmode = $p.get('outputmode', true); // Why not $pRaw?
+    const outputmode = /** @type {"json-object"|"json-array"|"table"|"div"} */ ($p.get('outputmode', true)); // Why not $pRaw?
 
     switch (outputmode) {
     case 'json-object': // Can later fall through if supporting
@@ -227,7 +333,7 @@ body {
     }
 
     const tableElems = tableOptions[
-      Object.prototype.hasOwnProperty.call(tableOptions, outputmode)
+      Object.hasOwn(tableOptions, outputmode) && outputmode
         ? outputmode
         : 'table' // Default
     ];
@@ -236,9 +342,13 @@ body {
     ] = tableElems; // colgroupElem, colElem
 
     const [checkedFields, checkedFieldIndexes, allInterlinearColIndexes] =
-            checkedAndInterlinearFieldInfo;
+      checkedAndInterlinearFieldInfo;
 
     const tableWithFixedHeaderAndFooter = $pRaw('headerfooterfixed') === 'yes';
+
+    /**
+     * @param {import('jamilih').JamilihChildren} children
+     */
     const tableWrap = (children) => {
       return tableWithFixedHeaderAndFooter
         ? ['div', {class: 'table-responsive anchor-table-header zupa'}, [
@@ -247,30 +357,44 @@ body {
         : ['div', {class: 'table-responsive'}, children];
     };
 
+    /**
+     * @param {import('jamilih').JamilihArray} el
+     * @param {import('jamilih').JamilihChildren} children
+     */
     const addChildren = (el, children) => {
       // eslint-disable-next-line unicorn/prefer-structured-clone -- Need JSON
       el = JSON.parse(JSON.stringify(el));
       el.push(children);
       return el;
     };
+
+    /**
+     * @param {[string, import('jamilih').JamilihAttributes?]} elAtts
+     * @param {import('jamilih').JamilihAttributes} newAtts
+     * @returns {import('jamilih').JamilihArray}
+     */
     const addAtts = ([el, atts], newAtts) => [el, {...atts, ...newAtts}];
 
     const foundState = {
       start: false,
       end: false
     };
-    const outArr = [];
 
-    const {showEmptyInterlinear, showTitleOnSingleInterlinear} = this;
+    /** @type {import('jamilih').JamilihArray[]} */
+    const outArr = [];
 
+    /**
+     * @param {string} tdVal
+     * @param {boolean} [htmlEscaped]
+     */
     const checkEmpty = (tdVal, htmlEscaped) => {
       if (!showEmptyInterlinear) {
         if (!htmlEscaped) {
-          tdVal = new DOMParser().parseFromString(tdVal, 'text/html').body;
-          [...tdVal.querySelectorAll('br')].forEach((br) => {
+          const tdValElem = new DOMParser().parseFromString(tdVal, 'text/html').body;
+          [...tdValElem.querySelectorAll('br')].forEach((br) => {
             br.remove();
           });
-          tdVal = tdVal.innerHTML;
+          tdVal = tdValElem.innerHTML;
         }
         if (!tdVal.trim()) {
           return true;
@@ -302,7 +426,11 @@ body {
             // Need to get a new one
             const {tdVal, htmlEscaped} = getCellValue({tr, idx});
             console.log('showEmptyInterlinear', showEmptyInterlinear, htmlEscaped);
-            const isEmpty = checkEmpty(tdVal, htmlEscaped);
+            const isEmpty = checkEmpty(
+              /** @type {string} */
+              (tdVal),
+              htmlEscaped
+            );
             if (isEmpty) {
               return '';
             }
@@ -313,7 +441,7 @@ body {
                 dir: fieldDirs[idx],
                 html: (showInterlinTitles
                   ? Templates.resultsDisplayServerOrClient.interlinearTitle({
-                    l, val: localizedFieldNames[idx]
+                    l, val: /** @type {string} */ (localizedFieldNames[idx])
                   })
                   : '') + tdVal
               })
@@ -327,36 +455,41 @@ body {
             lang: fieldLangs[idx],
             dir: fieldDirs[idx],
             dataset: {
-              col: localizedFieldNames[idx]
+              col: /** @type {string} */ (localizedFieldNames[idx])
             },
             innerHTML:
-                            (showInterlins && !checkEmpty(tdVal, htmlEscaped) &&
-                                (showTitleOnSingleInterlinear || interlins.length)
-                              ? Templates.resultsDisplayServerOrClient.interlinearSegment({
-                                lang: fieldLangs[idx],
-                                html: (showInterlinTitles
-                                  ? Templates.resultsDisplayServerOrClient.interlinearTitle({
-                                    l, val: localizedFieldNames[idx]
-                                  })
-                                  : '') + tdVal
-                              })
-                              : tdVal
-                            ) +
-                            (interlinearColIndexes && interlins.length
-                              ? interlinearSeparator +
-                                    interlins.join(interlinearSeparator)
-                              : ''
-                            )
+              (showInterlins && !checkEmpty(
+                /** @type {string} */
+                (tdVal),
+                htmlEscaped
+              ) &&
+                  (showTitleOnSingleInterlinear || interlins?.length)
+                ? Templates.resultsDisplayServerOrClient.interlinearSegment({
+                  lang: fieldLangs[idx],
+                  html: (showInterlinTitles
+                    ? Templates.resultsDisplayServerOrClient.interlinearTitle({
+                      l, val: /** @type {string} */ (localizedFieldNames[idx])
+                    })
+                    : '') + tdVal
+                })
+                : tdVal
+              ) +
+              (interlinearColIndexes && interlins && interlins.length
+                ? interlinearSeparator +
+                      interlins.join(interlinearSeparator)
+                : ''
+              )
           });
         })
       ));
       return false;
     });
 
-    return ['div', [
+    return /** @type {import('jamilih').JamilihArray} */ (['div', [
       Templates.resultsDisplayServerOrClient.styles({
         $p, $pRaw, $pRawEsc, $pEscArbitrary,
-        escapeQuotedCSS, escapeCSS, tableWithFixedHeaderAndFooter,
+        // escapeQuotedCSS,
+        escapeCSS, tableWithFixedHeaderAndFooter,
         checkedFieldIndexes, hasCaption
       }),
       tableWrap([
@@ -374,14 +507,14 @@ body {
             ])
             : ''),
           /*
-                    // Works but quirky, e.g., `color` doesn't work (as also
-                    //  confirmed per https://quirksmode.org/css/css2/columns.html)
-                    addChildren(colgroupElem,
-                        checkedFieldIndexes.map((idx, i) =>
-                            addAtts(colElem, {style: $pRaw('css' + (idx + 1))})
-                        )
-                    ),
-                    */
+            // Works but quirky, e.g., `color` doesn't work (as also
+            //  confirmed per https://quirksmode.org/css/css2/columns.html)
+            addChildren(colgroupElem,
+                checkedFieldIndexes.map((idx, i) =>
+                    addAtts(colElem, {style: $pRaw('css' + (idx + 1))})
+                )
+            ),
+          */
           ($pRaw('header') !== '0'
             ? addChildren(theadElem, [
               addChildren(
@@ -391,7 +524,10 @@ body {
                   cf = escapeHTML(cf) + (interlinearColIndexes
                     ? l('comma-space') + interlinearColIndexes.map((idx) => {
                       return localizedFieldNames[idx];
-                    }).join(l('comma-space'))
+                    }).join(
+                      /** @type {string} */
+                      (l('comma-space'))
+                    )
                     : ''
                   );
                   return addChildren(thElem, [
@@ -418,7 +554,10 @@ body {
                   cf = escapeHTML(cf) + (interlinearColIndexes
                     ? l('comma-space') + interlinearColIndexes.map((idx) => {
                       return localizedFieldNames[idx];
-                    }).join(l('comma-space'))
+                    }).join(
+                      /** @type {string} */
+                      (l('comma-space'))
+                    )
                     : ''
                   );
                   return addChildren(thElem, [
@@ -439,6 +578,6 @@ body {
           addChildren(tbodyElem, outArr)
         ])
       ])
-    ]];
+    ]]);
   }
 };

package/resources/templates/utils/dom.js

@@ -1,10 +1,21 @@
 const nbsp = '\u00A0';
+
+/**
+ * @param {string} sel
+ */
 const $ = (sel) => document.querySelector(sel);
+/**
+ * @param {string} sel
+ */
 const $$ = (sel) => [...document.querySelectorAll(sel)];
 
+/**
+ * @param {string|HTMLElement} el
+ * @param {string} descendentsSel
+ */
 const $e = (el, descendentsSel) => {
-  el = typeof el === 'string' ? $(el) : el;
-  return el.querySelector(descendentsSel);
+  const elem = typeof el === 'string' ? $(el) : el;
+  return elem?.querySelector(descendentsSel);
 };
 
 export {nbsp, $, $$, $e};