textbrowser 0.50.0 → 0.51.0

package/resources/utils/Params.js

@@ -1,19 +1,58 @@
 // Todo: Reimplement this with `formSerialize.deserialize` as possible
+
+// @ts-expect-error Todo: Add types
 import {serialize as formSerialize} from 'form-serialization';
 
+/**
+ * @param {URLSearchParams} paramsCopy
+ */
 export const replaceHash = (paramsCopy) => {
   return location.href.replace(/#.*$/, '') + '#' + paramsCopy.toString();
 };
 
-export const getSerializeParamsAsURL = function (...args) {
-  const setter = getParamsSetter(...args);
-  return function (...innerArgs) {
-    const paramsCopy = setter(...innerArgs);
+/**
+ * @param {{
+*   l: import('intl-dom').I18NCallback,
+*   lParam: (key: string) => string,
+*   $p: import('./IntlURLSearchParams.js').default
+* }} args
+*/
+export const getSerializeParamsAsURL = function (args) {
+  const setter = getParamsSetter(args);
+  /**
+   * @param {{
+   *   form: HTMLFormElement,
+   *   random: {checked: boolean},
+   *   checkboxes: HTMLInputElement[],
+   *   type: string,
+   *   fieldAliasOrNames?: string[],
+   *   workName?: string
+   * }} innerArg
+   */
+  return function (innerArg) {
+    const paramsCopy = setter(innerArg);
     return replaceHash(paramsCopy);
   };
 };
 
+/**
+ * @param {{
+ *   l: import('intl-dom').I18NCallback,
+ *   lParam: (key: string) => string,
+ *   $p: import('./IntlURLSearchParams.js').default
+ * }} cfg
+ */
 export const getParamsSetter = function ({l, lParam, $p}) {
+  /**
+   * @param {{
+   *   form: HTMLFormElement,
+   *   random: {checked: boolean},
+   *   checkboxes: HTMLInputElement[],
+   *   type: string,
+   *   fieldAliasOrNames?: string[],
+   *   workName?: string
+   * }} cfg
+   */
   return function ({form, random = {
     checked: false
   }, checkboxes, type, fieldAliasOrNames = [], workName}) {
@@ -26,7 +65,11 @@ export const getParamsSetter = function ({l, lParam, $p}) {
 
     // Follow the same style (and order) for checkboxes
     paramsCopy.delete(lParam('rand'));
-    paramsCopy.set(lParam('rand'), random.checked ? l('yes') : l('no'));
+    paramsCopy.set(
+      lParam('rand'), /** @type {string} */ (
+        random.checked ? l('yes') : l('no')
+      )
+    );
 
     // We want checkboxes to typically show by default, so we cannot use the
     //    standard serialization
@@ -34,7 +77,11 @@ export const getParamsSetter = function ({l, lParam, $p}) {
       // Let's ensure the checked items are all together (at the end)
       paramsCopy.delete(checkbox.name);
       if (checkbox.name) { // We don't want, e.g., preference controls added to URL
-        paramsCopy.set(checkbox.name, checkbox.checked ? l('yes') : l('no'));
+        paramsCopy.set(
+          checkbox.name,
+          /** @type {string} */
+          (checkbox.checked ? l('yes') : l('no'))
+        );
       }
     });
 
@@ -45,11 +92,11 @@ export const getParamsSetter = function ({l, lParam, $p}) {
     function removeStartsEndsAndAnchors () {
       let num = 1;
       let num2 = 1;
-      while (paramsCopy.has(`${workName}-start${num}-${num2}`, true)) {
-        while (paramsCopy.has(`${workName}-start${num}-${num2}`, true)) {
-          paramsCopy.delete(`${workName}-start${num}-${num2}`, true);
-          paramsCopy.delete(`${workName}-end${num}-${num2}`, true);
-          paramsCopy.delete(`${workName}-anchor${num}-${num2}`, true);
+      while (paramsCopy.has(`${workName}-start${num}-${num2}`)) {
+        while (paramsCopy.has(`${workName}-start${num}-${num2}`)) {
+          paramsCopy.delete(`${workName}-start${num}-${num2}`);
+          paramsCopy.delete(`${workName}-end${num}-${num2}`);
+          paramsCopy.delete(`${workName}-anchor${num}-${num2}`);
           num2++;
         }
         num2 = 1;
@@ -67,29 +114,29 @@ export const getParamsSetter = function ({l, lParam, $p}) {
     case 'shortcutResult': {
       paramsCopy.delete(lParam('rand'));
       let num = 1;
-      while (paramsCopy.has(`anchorfield${num}`, true)) {
-        paramsCopy.delete(`anchorfield${num}`, true);
+      while (paramsCopy.has(`anchorfield${num}`)) {
+        paramsCopy.delete(`anchorfield${num}`);
         num++;
       }
       removeStartsEndsAndAnchors();
 
       num = 1;
       // Delete field-specific so we can add our own
-      while (paramsCopy.has(`field${num}`, true)) {
-        paramsCopy.delete(`field${num}`, true);
-        paramsCopy.delete(`checked${num}`, true);
-        paramsCopy.delete(`interlin${num}`, true);
-        paramsCopy.delete(`css${num}`, true);
+      while (paramsCopy.has(`field${num}`)) {
+        paramsCopy.delete(`field${num}`);
+        paramsCopy.delete(`checked${num}`);
+        paramsCopy.delete(`interlin${num}`);
+        paramsCopy.delete(`css${num}`);
         num++;
       }
       fieldAliasOrNames.forEach((fieldAliasOrName, i) => {
-        paramsCopy.set(`field${i + 1}`, fieldAliasOrName, true);
+        paramsCopy.set(`field${i + 1}`, fieldAliasOrName);
         // Todo: Restrict by content locale?
-        paramsCopy.set(`checked${i + 1}`, l('yes'), true);
+        paramsCopy.set(`checked${i + 1}`, /** @type {string} */ (l('yes')));
         paramsCopy.set(`interlin${i + 1}`, '');
         paramsCopy.set(`css${i + 1}`, '');
       });
-      paramsCopy.delete('work', true);
+      paramsCopy.delete('work');
     }
     // Fallthrough
     case 'startEndResult':
@@ -102,9 +149,9 @@ export const getParamsSetter = function ({l, lParam, $p}) {
       //    let's put random again toward the end.
       if (type === 'randomResult' || random.checked) {
         paramsCopy.delete(lParam('rand'));
-        paramsCopy.set(lParam('rand'), l('yes'));
+        paramsCopy.set(lParam('rand'), /** @type {string} */ (l('yes')));
       }
-      paramsCopy.set(lParam('result'), l('yes'));
+      paramsCopy.set(lParam('result'), /** @type {string} */ (l('yes')));
       break;
     }
     default: {

package/resources/utils/Plugin.js

@@ -1,8 +1,18 @@
+/**
+ * @typedef {number} Integer
+ */
+
+/**
+ * @param {string} pluginName
+ */
 export const escapePluginComponent = (pluginName) => {
   return pluginName.replaceAll('^', '^^'). // Escape our escape
     replaceAll('-', '^0');
 };
 
+/**
+ * @param {string|undefined} pluginName
+ */
 export const unescapePluginComponent = (pluginName) => {
   if (!pluginName) {
     return pluginName;
@@ -17,18 +27,120 @@ export const unescapePluginComponent = (pluginName) => {
   ).replaceAll('^^', '^');
 };
 
+/**
+ * @param {{
+ *   pluginName: string,
+ *   applicableField: string,
+ *   targetLanguage: string
+ * }} cfg
+ */
 export const escapePlugin = ({pluginName, applicableField, targetLanguage}) => {
   return escapePluginComponent(pluginName) +
         (applicableField ? '-' + escapePluginComponent(applicableField) : '-') +
         (targetLanguage ? '-' + escapePluginComponent(targetLanguage) : '');
 };
 
+/**
+ * @todo Complete
+ * @typedef {{
+ *   path: string,
+ *   onByDefault?: boolean,
+ *   lang?: string,
+ *   meta?: {[key: string]: string}
+ *   getCellData?: (info: {
+ *     tr: (string|Integer)[],
+ *     tableData: (string|Integer)[][],
+ *     i: number,
+ *     j: number,
+ *     applicableField?: string,
+ *     fieldInfo: import('../resultsDisplay.js').FieldInfo,
+ *     applicableFieldIdx: number,
+ *     applicableFieldText: string|Integer,
+ *     fieldLang: string,
+ *     getLangDir: (locale: string) => string,
+ *     meta: {
+ *       [key: string]: string
+ *     }|undefined,
+ *     metaApplicableField?: {
+ *       [key: string]: string
+ *     },
+ *     $p: import('./IntlURLSearchParams.js').default,
+ *     thisObj: import('../index.js').default|import('../../server/main.js').ResultsDisplayServerContext
+ *   }) => void,
+ *   done: (info: {
+ *     $p: import('./IntlURLSearchParams.js').default,
+ *     applicableField: string|undefined,
+ *     meta?: {[key: string]: string}
+ *     thisObj: import('../index.js').default
+ *     j?: number
+ *   }) => void,
+ *   getTargetLanguage: (info: {
+ *     applicableField: string,
+ *     targetLanguage?: string,
+ *     pluginLang: string,
+ *     applicableFieldLang?: string
+ *   }) => string,
+ *   escapeColumn?: boolean,
+ *   getFieldAliasOrName: (info: {
+ *     locales: string[],
+ *     workI18n: import('intl-dom').I18NCallback,
+ *     targetLanguage: string,
+ *     applicableField: string,
+ *     applicableFieldI18N: string|string[]|import("../../server/main.js").LocalizationStrings,
+ *     meta: any,
+ *     metaApplicableField: {
+ *       [key: string]: string
+ *     },
+ *     targetLanguageI18N: string
+ *   }) => string
+ * }} PluginObject
+ */
+
+/**
+ * @typedef {{
+ *   path: string,
+ *   lang: string,
+ *   meta: any,
+ *   onByDefault: boolean
+ * }} PluginInfo
+ */
+
+/**
+ * @typedef {{
+ *   placement: "end"|number,
+ *   'applicable-fields': {
+ *     [field: string]: {
+ *       targetLanguage: string|string[],
+ *       onByDefault: boolean,
+ *       meta: {
+ *         [key: string]: string
+ *       },
+ *       [args: string]: {}
+ *     }
+ *   },
+ *   [fieldArgs: string]: {
+ *   }
+ * }} PluginFieldMappingForWork
+ */
+
 export class PluginsForWork {
+  /**
+   * @param {{
+   *   pluginsInWork: [string, PluginInfo][],
+   *   pluginFieldMappings: PluginFieldMappingForWork[],
+   *   pluginObjects: PluginObject[]
+   * }} cfg
+   */
   constructor ({pluginsInWork, pluginFieldMappings, pluginObjects}) {
     this.pluginsInWork = pluginsInWork;
     this.pluginFieldMappings = pluginFieldMappings;
     this.pluginObjects = pluginObjects;
   }
+
+  /**
+   * @param {string} pluginName
+   * @returns {PluginObject}
+   */
   getPluginObject (pluginName) {
     const idx = this.pluginsInWork.findIndex(([name]) => {
       return name === pluginName;
@@ -36,6 +148,25 @@ export class PluginsForWork {
     const plugin = this.pluginObjects[idx];
     return plugin;
   }
+
+  /**
+   * @param {(cfg: {
+   *   plugin: PluginObject,
+   *   placement: "end"|number,
+   *   applicableFields: {
+   *     [applicableField: string]: {
+   *       targetLanguage: string|string[],
+   *       onByDefault: boolean,
+   *       meta: any
+   *     }
+   *   },
+   *   pluginName: string,
+   *   pluginLang: string,
+   *   onByDefaultDefault: boolean,
+   *   meta: {}
+   * }) => void} cb
+   * @returns {void}
+   */
   iterateMappings (cb) {
     this.pluginFieldMappings.forEach(({
       placement,
@@ -62,6 +193,25 @@ export class PluginsForWork {
       });
     });
   }
+
+  /**
+   * @param {{
+   *   [applicableField: string]: {
+   *     targetLanguage: string|string[],
+   *     onByDefault: boolean,
+   *     meta: any
+   *   }
+   * }} applicableFields
+   * @param {(cfg: {
+   *   applicableField: string,
+   *   targetLanguage: string,
+   *   onByDefault: boolean,
+   *   metaApplicableField: {
+   *     [key: string]: string
+   *   }
+   * }) => void} cb
+   * @returns {boolean}
+   */
   processTargetLanguages (applicableFields, cb) {
     if (!applicableFields) {
       return false;
@@ -79,9 +229,25 @@ export class PluginsForWork {
     });
     return true;
   }
+
+  /**
+   * @param {{
+   *   namespace: string,
+   *   field: string
+   * }} cfg
+   * @returns {boolean}
+   */
   isPluginField ({namespace, field}) {
     return field.startsWith(`${namespace}-plugin-`);
   }
+
+  /**
+   * @param {{
+   *   namespace: string,
+   *   field: string
+   * }} cfg
+   * @returns {[string, string|undefined, string|undefined]}
+   */
   getPluginFieldParts ({namespace, field}) {
     field = field.replace(`${namespace}-plugin-`, '');
     let pluginName, applicableField, targetLanguage;
@@ -90,6 +256,8 @@ export class PluginsForWork {
     } else {
       pluginName = field;
     }
-    return [pluginName, applicableField, targetLanguage].map(unescapePluginComponent);
+    return /** @type {[string, string|undefined, string|undefined]} */ (
+      [pluginName, applicableField, targetLanguage].map(unescapePluginComponent)
+    );
   }
 }

package/resources/utils/ServiceWorker.js

@@ -2,16 +2,21 @@
 import {dialogs} from './dialogs.js';
 
 /**
- * Note that this function be kept as a polyglot client-server file.
- * @param {PlainObject} target
- * @param {PlainObject} source
- * @returns {{
+ * @typedef {{
  *   userJSON: string,
  *   languages: string,
  *   serviceWorkerPath: string,
  *   files: string,
- *   namespace: string
- * }}
+ *   namespace: string,
+ *   stylesheets?: string[]
+ * }} ServiceWorkerConfig
+ */
+
+/**
+ * Note that this function be kept as a polyglot client-server file.
+ * @param {Partial<ServiceWorkerConfig>} target
+ * @param {Partial<ServiceWorkerConfig>} source
+ * @returns {ServiceWorkerConfig}
  */
 export const setServiceWorkerDefaults = (target, source) => {
   target.userJSON = source.userJSON || 'resources/user.json';
@@ -27,13 +32,18 @@ export const setServiceWorkerDefaults = (target, source) => {
         }`;
   target.files = source.files || 'files.json';
   target.namespace = source.namespace || 'textbrowser';
-  return target;
+  return /** @type {ServiceWorkerConfig} */ (target);
 };
 
 // (Unless skipped in code, will wait between install
 //    of new and activation of new or existing if still
 //    some tabs open)
 
+/**
+ * @param {{
+ *   r: ServiceWorkerRegistration
+ * }} cfg
+ */
 export const listenForWorkerUpdate = ({
   r
   // logger
@@ -43,7 +53,7 @@ export const listenForWorkerUpdate = ({
     // r.installing now available (though r.active is also,
     //    apparently due to prior activation; but not r.waiting)
     console.log('update found', e);
-    const newWorker = r.installing;
+    const newWorker = /** @type {ServiceWorker} */ (r.installing);
 
     // statechange won't catch this installing event as already installing
 
@@ -97,6 +107,18 @@ for offline installation.
   });
 };
 
+/**
+ * @typedef {{
+ *   addLogEntry: (entry: {text: string}) => void,
+ * }} Logger
+ */
+
+/**
+ * @param {{
+ *   r: ServiceWorkerRegistration,
+ *   logger: Logger
+ * }} cfg
+ */
 export const respondToState = async ({
   r, logger
 }) => {
@@ -157,20 +179,20 @@ export const respondToState = async ({
           }; trying again...`
         });
         /*
-                if (errorType === 'dbError') {
-                    logger.dbError({
-                        type: name || errorType,
-                        escapedErrorMessage: escapeHTML(message)
-                    });
-                }
-                */
+          if (errorType === 'dbError') {
+              logger.dbError({
+                  type: name || errorType,
+                  escapedErrorMessage: escapeHTML(message)
+              });
+          }
+          */
         // Todo: auto-close any dbError dialog if retrying
         // No longer rejecting as should auto-retry
         /*
-                const err = new Error(message);
-                err.type = type;
-                reject(err);
-                */
+          const err = new Error(message);
+          err.type = type;
+          reject(err);
+          */
         break;
       default:
         console.error('Unexpected type', type);
@@ -219,6 +241,13 @@ any indication it is installing.
 
 // Keep in this file as may wish to avoid using for server (while still
 //   doing other service worker work)
+
+/**
+ * @param {{
+ *   serviceWorkerPath: string,
+ *   logger: Logger
+ * }} cfg
+ */
 export const registerServiceWorker = async ({
   serviceWorkerPath,
   logger