textbrowser 0.50.0 → 0.52.0

package/resources/templates/workSelect.js

@@ -1,6 +1,17 @@
 import {jml, $} from 'jamilih';
+
+// @ts-expect-error -- Missing TS
 import {deserialize as formDeserialize} from 'form-serialization';
 
+/**
+ * @param {{
+ *   groups: import('../utils/WorkInfo.js').FileGroup[]
+ *   workI18n: import('intl-dom').I18NCallback
+ *   getNextAlias: () => string|string[]|import('../../server/main.js').LocalizationStrings
+ *   $p: import('../utils/IntlURLSearchParams.js').default
+ *   followParams: (formSelector: string, cb: () => void) => void
+ * }} cfg
+ */
 const workSelect = function ({groups, workI18n, getNextAlias, $p, followParams}) {
   const form = jml(
     'form',
@@ -10,7 +21,7 @@ const workSelect = function ({groups, workI18n, getNextAlias, $p, followParams})
       }
     }},
     groups.map((group, i) => {
-      return ['div', [
+      return /** @type {import('jamilih').JamilihArray} */ (['div', [
         i > 0 ? ['br', 'br', 'br'] : '',
         ['div', [
           workI18n(group.directions.localeKey)
@@ -23,7 +34,9 @@ const workSelect = function ({groups, workI18n, getNextAlias, $p, followParams})
             name: group.name.localeKey
           },
           $on: {
-            change ({target: {value}}) {
+            change (e) {
+              // eslint-disable-next-line prefer-destructuring -- TS
+              const value = /** @type {HTMLSelectElement} */ (e.target).value;
               /*
                             // If using click, but click doesn't always fire
                             if (e.target.nodeName.toLowerCase() === 'select') {
@@ -45,7 +58,7 @@ const workSelect = function ({groups, workI18n, getNextAlias, $p, followParams})
         ]]
         // Todo: Add in Go button (with 'submitgo' localization string) to
         //    avoid need for pull-down if using first selection?
-      ]];
+      ]]);
     }),
     $('#main')
   );

package/resources/user-sample.js

@@ -1,3 +1,4 @@
+// eslint-disable-next-line sonarjs/no-internal-api-use -- Demo
 import TextBrowser from '../node_modules/textbrowser/dist/index-es.js';
 
 const tb = new TextBrowser({

package/resources/utils/IntlURLSearchParams.js

@@ -2,10 +2,10 @@
  * @file Note that this should be kept as a polyglot client-server file.
  */
 /**
- *
- * @param {string} param
- * @param {boolean} skip
  * @this {IntlURLSearchParams}
+ * @param {string} param
+ * @param {boolean} [skip]
+ * @throws {Error}
  * @returns {string}
  */
 function _prepareParam (param, skip) {
@@ -16,39 +16,81 @@ function _prepareParam (param, skip) {
   // start, end, toggle
   const endNums = /\d+(-\d+)?$/;
   const indexed = param.match(endNums);
+  if (!this.l10n) {
+    throw new Error('l10n is not defined');
+  }
   if (indexed) {
     // Todo: We could i18nize numbers as well
     return this.l10n(['params', 'indexed', param.replace(endNums, '')]) + indexed[0];
   }
-  return this.l10n(['params', param]);
+  return /** @type {string} */ (this.l10n(['params', param]));
 }
 
 class IntlURLSearchParams {
+  /**
+   * @param {object} [options]
+   * @param {import('intl-dom').I18NCallback} [options.l10n]
+   * @param {URLSearchParams|string} [options.params]
+   */
   constructor ({l10n, params} = {}) {
     this.l10n = l10n;
+    this.localizeParamNames = false;
     if (!params) {
       params = location.hash.slice(1);
     }
     if (typeof params === 'string') {
       params = new URLSearchParams(params);
     }
+    /** @type {URLSearchParams} */
     this.params = params;
   }
+  /**
+   * @param {string} param
+   * @param {boolean} [skip]
+   * @returns {string|null}
+   */
   get (param, skip) {
     return this.params.get(_prepareParam.call(this, param, skip));
   }
+  /**
+   * @param {string} param
+   * @param {boolean} skip
+   * @returns {string[]}
+   */
   getAll (param, skip) {
     return this.params.getAll(_prepareParam.call(this, param, skip));
   }
+  /**
+   * @param {string} param
+   * @param {boolean} [skip]
+   * @returns {boolean}
+   */
   has (param, skip) {
     return this.params.has(_prepareParam.call(this, param, skip));
   }
+  /**
+   * @param {string} param
+   * @param {boolean} skip
+   * @returns {void}
+   */
   delete (param, skip) {
     return this.params.delete(_prepareParam.call(this, param, skip));
   }
+  /**
+   * @param {string} param
+   * @param {string} value
+   * @param {boolean} [skip]
+   * @returns {void}
+   */
   set (param, value, skip) {
     return this.params.set(_prepareParam.call(this, param, skip), value);
   }
+  /**
+   * @param {string} param
+   * @param {string} value
+   * @param {boolean} skip
+   * @returns {void}
+   */
   append (param, value, skip) {
     return this.params.append(_prepareParam.call(this, param, skip), value);
   }

package/resources/utils/Languages.js

@@ -1,10 +1,21 @@
 // Todo: remember this locales choice by cookie?
+
+/**
+ * @param {{
+ *   namespace: string,
+ *   preferredLocale: string
+ * }} cfg
+ */
 export const getPreferredLanguages = ({namespace, preferredLocale}) => {
   // Todo: Add to this optionally with one-off tag input box
   // Todo: Switch to fallbackLanguages so can default to
   //    navigator.languages?
   const langCodes = localStorage.getItem(namespace + '-langCodes');
-  const lngs = (langCodes && JSON.parse(langCodes)) || [preferredLocale];
+  const lngs = /** @type {string[]} */ (
+    (langCodes && JSON.parse(langCodes)) || [preferredLocale]
+  );
+
+  /** @type {string[]} */
   const langArr = [];
   lngs.forEach((lng) => {
     // Todo: Check for multiple separate hyphenated
@@ -23,23 +34,66 @@ export const getPreferredLanguages = ({namespace, preferredLocale}) => {
  * @classdesc Note that this should be kept as a polyglot client-server class.
  */
 export class Languages {
+  /**
+   * @param {{
+   *   langData: import('../../server/main.js').LanguagesData
+   * }} cfg
+   */
   constructor ({langData}) {
     this.langData = langData;
   }
+  /**
+   * @param {string} langCode
+   * @returns {{
+   *   languages: {
+   *     [key: string]: string
+   *   }
+   * }}
+   */
   localeFromLangData (langCode) {
-    return this.langData['localization-strings'][langCode];
+    return (
+      /**
+       * @type {{
+       *   languages: {
+       *     [key: string]: string
+       *   }
+       * }}
+       */ (
+        this.langData['localization-strings'][langCode]
+      )
+    );
   }
+  /**
+   * @param {string} code
+   * @returns {string}
+   */
   getLanguageFromCode (code) {
     return this.localeFromLangData(code).languages[code];
     // Could add something like this in place or as fallback, though need to pass in locale
     // || new Intl.DisplayNames([locale], {type: 'language'}).of(code);
   }
+
+  /**
+   * @param {{
+   *   pluginName: string,
+   *   workI18n: import('intl-dom').I18NCallback,
+   *   targetLanguage: string,
+   *   applicableFieldI18N: string|string[],
+   *   meta: {
+   *     [key: string]: string
+   *   },
+   *   metaApplicableField: {
+   *     [key: string]: string
+   *   },
+   * }} cfg
+   * @returns {string}
+   */
   getFieldNameFromPluginNameAndLocales ({
     pluginName,
     // locales,
     workI18n, targetLanguage, applicableFieldI18N, meta, metaApplicableField
   }) {
-    return workI18n(['plugins', pluginName, 'fieldname'], {
+    return /** @type {string} */ (workI18n(['plugins', pluginName, 'fieldname'], {
       ...meta,
       ...metaApplicableField,
       applicableField: applicableFieldI18N,
@@ -49,10 +103,23 @@ export class Languages {
     }, {
       // We provide more than may be desired by the plugin
       throwOnExtraSuppliedFormatters: false
-    });
+    }));
   }
+
+  /**
+   * @param {{$p: import('./IntlURLSearchParams.js').default}} cfg
+   * @returns {{
+   *   lang: string[],
+   *   langs: import('../../server/main.js').LanguageInfo[],
+   *   languageParam: string|null,
+   *   fallbackLanguages: string[]
+   * }}
+   */
   getLanguageInfo ({$p}) {
     const langs = this.langData.languages;
+    /**
+     * @param {string} lcl
+     */
     const localePass = (lcl) => {
       return langs.some(({code}) => code === lcl) ? lcl : false;
     };

package/resources/utils/Metadata.js

@@ -3,17 +3,56 @@ import {getPreferredLanguages} from './Languages.js';
 import JsonRefs from 'json-refs'; // // eslint-disable-line import/order
 
 const getCurrDir = () => {
-  return window.location.href.replace(/(index\.html)?#.*$/, '');
+  return globalThis.location.href.replace(/(index\.html)?#.*$/, '');
 };
 
+/**
+ * @typedef {{
+ *   [key: string]: string|Integer|(string|Integer)[]|{
+ *     [key: string]: string|Integer
+ *   }
+ * }} FieldValueAliases
+ */
+
+/**
+ * @typedef {{
+ *   "localization-strings": import('../../server/main.js').LocalizationStrings
+ *   table: {browse_fields: (string|{
+ *     name?: string,
+ *     set: string[],
+ *     presort?: boolean
+ *   })[]}
+ *   fields: {
+ *     [key: string]: {
+ *       prefer_alias: boolean|string,
+ *       name: string|{localeKey: string},
+ *       alias: string|{localeKey: string},
+ *       lang: string,
+ *       'fieldvalue-aliases': FieldValueAliases
+ *     }
+ *   }
+* }} MetadataObj
+ */
+
+/**
+ * @param {string[]} lang
+ * @param {MetadataObj} metadataObj
+ * @param {string|string[]} properties
+ * @param {boolean} [allowObjects]
+ * @returns {string|string[]|import('../../server/main.js').LocalizationStrings}
+ */
 export const getMetaProp = function getMetaProp (lang, metadataObj, properties, allowObjects) {
   let prop;
   properties = typeof properties === 'string' ? [properties] : properties;
-  lang.some((lan) => {
+  for (const lan of lang) {
     const p = [...properties];
-    let strings = metadataObj['localization-strings'][lan];
+    let strings = /** @type {string|string[]|import('../../server/main.js').LocalizationStrings} */ (
+      metadataObj['localization-strings'][lan]
+    );
     while (strings && p.length) {
-      strings = strings[p.shift()];
+      strings = /** @type {import('../../server/main.js').LocalizationStrings} */ (
+        strings
+      )[/** @type {string} */ (p.shift())];
     }
     // Todo: Fix this allowance for allowObjects (as it does not properly
     //        fallback if an object is returned from a language because
@@ -22,9 +61,13 @@ export const getMetaProp = function getMetaProp (lang, metadataObj, properties,
     prop = (allowObjects || typeof strings === 'string')
       ? strings
       : undefined;
-    return prop;
-  });
-  return prop;
+    if (prop) {
+      break;
+    }
+  }
+  return /** @type {string|string[]|import('../../server/main.js').LocalizationStrings} */ (
+    prop
+  );
 };
 
 // Use the following to dynamically add specific file schema in place of
@@ -32,18 +75,46 @@ export const getMetaProp = function getMetaProp (lang, metadataObj, properties,
 //  filesSchema.properties.groups.items.properties.files.items.properties.
 //      file.anyOf.splice(1, 1, {$ref: schemaFile});
 // Todo: Allow use of dbs and fileGroup together in base directories?
+
+/**
+ * @typedef {{
+ *   items: {
+ *     items: {
+ *       title: string,
+ *       type: string
+ *       format?: string
+ *     }[]
+ *   }
+ * }} SchemaObj
+ */
+
+/**
+ * @param {string} file
+ * @param {string} property
+ * @param {string} [basePath]
+ * @returns {Promise<MetadataObj|SchemaObj>}
+ */
 export const getMetadata = async (file, property, basePath) => {
   const url = new URL(basePath || getCurrDir());
   url.search = ''; // Clear out query string, e.g., `?fbclid` from Facebook
   url.pathname = file;
   url.hash = property ? '#/' + property : '';
 
-  return (await JsonRefs.
+  return /** @type {MetadataObj} */ ((await JsonRefs.
     resolveRefsAt(
       url.toString(),
       {
         loaderOptions: {
+          /* eslint-disable jsdoc/reject-any-type -- How to resolve? */
+          /**
+           * @param {{
+           *   text: string,
+           *   body: any
+           * }} res
+           * @param {(err?: Error, cbValue: any) => void} callback
+           */
           processContent (res, callback) {
+            /* eslint-enable jsdoc/reject-any-type -- How to resolve? */
             callback(undefined, JSON.parse(
               res.text ||
                             // `.metadata` not a recognized extension, so
@@ -53,9 +124,39 @@ export const getMetadata = async (file, property, basePath) => {
           }
         }
       }
-    )).resolved;
+    )).resolved);
 };
 
+/**
+ * @typedef {{
+ *   field: string,
+ *   schemaItems: {
+ *     title: string,
+ *     type: string,
+ *     enum?: string[]
+ *   }[],
+ *   metadataObj: MetadataObj,
+ *   getFieldAliasOrName: (field: string) => string|string[]|import('../../server/main.js').LocalizationStrings,
+ *   lang: string[]
+ * }} GetFieldNameAndValueAliasesOptions
+ */
+
+/**
+ * @param {GetFieldNameAndValueAliasesOptions} cfg
+ * @returns {{
+ *   aliases: string[]|null,
+ *   fieldValueAliasMap: FieldValueAliases|null,
+ *   rawFieldValueAliasMap: FieldValueAliases|null,
+ *   fieldName: string,
+ *   fieldSchema: {
+ *     title: string,
+ *     type: string
+ *   },
+ *   fieldSchemaIndex: number,
+ *   preferAlias: boolean|string,
+ *   lang: string
+ * }}
+ */
 export const getFieldNameAndValueAliases = function ({
   field, schemaItems, metadataObj, getFieldAliasOrName, lang
 }) {
@@ -66,27 +167,46 @@ export const getFieldNameAndValueAliases = function ({
 
   const fieldInfo = metadataObj.fields[field];
 
+  /**
+   * @type {{
+   *   aliases: string[]|null,
+   *   fieldValueAliasMap: FieldValueAliases|null,
+   *   rawFieldValueAliasMap: FieldValueAliases|null,
+   *   fieldName: string,
+   *   fieldSchema: {
+   *     title: string,
+   *     type: string
+   *   },
+   *   fieldSchemaIndex: number,
+   *   preferAlias: boolean|string,
+   *   lang: string
+   * }}
+   */
   const ret = {
     // field,
     aliases: null,
     fieldValueAliasMap: null,
     rawFieldValueAliasMap: null,
-    fieldName: getFieldAliasOrName(field),
+    fieldName: /** @type {string} */ (getFieldAliasOrName(field)),
     fieldSchema,
     fieldSchemaIndex,
     preferAlias: fieldInfo.prefer_alias,
     lang: fieldInfo.lang
   };
 
+  /** @type {FieldValueAliases} */
   let fieldValueAliasMap = fieldInfo && fieldInfo['fieldvalue-aliases'];
 
   if (fieldValueAliasMap) {
     if (fieldValueAliasMap.localeKey) {
-      fieldValueAliasMap = getMetaProp(
-        lang,
-        metadataObj,
-        fieldValueAliasMap.localeKey.split('/'),
-        true
+      fieldValueAliasMap = /** @type {FieldValueAliases} */ (
+        getMetaProp(
+          lang,
+          metadataObj,
+          /** @type {string} */
+          (fieldValueAliasMap.localeKey).split('/'),
+          true
+        )
       );
     }
     // eslint-disable-next-line unicorn/prefer-structured-clone -- Expecting JSON
@@ -96,14 +216,18 @@ export const getFieldNameAndValueAliases = function ({
     //    needed cases
     if (fieldSchema.enum && fieldSchema.enum.length) {
       fieldSchema.enum.forEach((enm) => {
-        ret.aliases.push(
-          getMetaProp(lang, metadataObj, ['fieldvalue', field, enm], true)
+        /** @type {string[]} */
+        (ret.aliases).push(
+          /** @type {string} */ (
+            getMetaProp(lang, metadataObj, ['fieldvalue', field, enm], true)
+          )
         );
         if (enm in fieldValueAliasMap &&
                     // Todo: We could allow numbers here too, but crowds
                     //         pull-down
                     typeof fieldValueAliasMap[enm] === 'string') {
-          ret.aliases.push(...fieldValueAliasMap[enm]);
+          /** @type {string[]} */
+          (ret.aliases).push(...fieldValueAliasMap[enm]);
         }
       });
     } else {
@@ -114,15 +238,24 @@ export const getFieldNameAndValueAliases = function ({
         // We'll preserve the numbers since probably more useful if
         //   stored with data (as opposed to enums)
         if (!Array.isArray(aliases)) {
-          aliases = Object.values(aliases);
+          aliases = /** @type {string[]} */ (
+            Object.values(/** @type {import('../../server/main.js').LocalizationStrings} */ (
+              aliases
+            ))
+          );
         }
         // We'll assume the longest version is best for auto-complete
-        ret.aliases.push(
+        /** @type {string[]} */
+        (ret.aliases).push(
           ...(
             aliases.filter((v) => {
               return aliases.every((x) => {
                 return x === v || !(
-                  x.toLowerCase().startsWith(v.toLowerCase())
+                  /** @type {string} */
+                  (x).toLowerCase().startsWith(
+                    /** @type {string} */
+                    (v).toLowerCase()
+                  )
                 );
               });
             }).map((v) => v + ' (' + key + ')') // Todo: i18nize
@@ -131,12 +264,55 @@ export const getFieldNameAndValueAliases = function ({
       });
     }
     // eslint-disable-next-line unicorn/prefer-structured-clone -- Expecting JSON
-    ret.fieldValueAliasMap = JSON.parse(JSON.stringify(fieldValueAliasMap));
+    ret.fieldValueAliasMap = /** @type {FieldValueAliases} */ (JSON.parse(JSON.stringify(fieldValueAliasMap)));
     // ret.aliases.sort();
   }
   return ret;
 };
 
+/**
+ * @typedef {number} Integer
+ */
+
+/**
+ * @typedef {{
+ *   aliases: string[]|null,
+ *   fieldValueAliasMap: FieldValueAliases|null,
+ *   rawFieldValueAliasMap: FieldValueAliases|null,
+ *   fieldName: string,
+ *   fieldSchema: {
+ *     title: string,
+ *     type: string,
+ *     minimum?: Integer,
+ *     maximum?: Integer
+ *   },
+ *   fieldSchemaIndex: number,
+ *   preferAlias: boolean|string,
+ *   lang: string
+ * }[]} BrowseFields
+ */
+
+/**
+ * @typedef {{
+ *   metadataObj: MetadataObj,
+ *   schemaItems: {
+ *     title: string,
+ *     type: string
+ *   }[],
+ *   getFieldAliasOrName: (field: string) => string|string[]|import('../../server/main.js').LocalizationStrings,
+ *   lang: string[],
+ *   callback: (cfg: {
+ *     setName: string,
+ *     browseFields: BrowseFields,
+ *     i: number,
+ *     presort: boolean|undefined
+ *   }) => void
+ * }} GetBrowseFieldDataOptions
+ */
+
+/**
+ * @param {GetBrowseFieldDataOptions} cfg
+ */
 export const getBrowseFieldData = function ({
   metadataObj, schemaItems, getFieldAliasOrName, lang, callback
 }) {
@@ -167,16 +343,37 @@ export const getBrowseFieldData = function ({
 
 // Todo: Incorporate other methods into this class
 export class Metadata {
+  /**
+   * @param {{
+   *   metadataObj: MetadataObj
+   * }} cfg
+   */
   constructor ({metadataObj}) {
     this.metadataObj = metadataObj;
   }
 
+  /**
+   * @param {string} field
+   * @returns {string|undefined}
+   */
   getFieldLang (field) {
     const {metadataObj} = this;
     const fields = metadataObj && metadataObj.fields;
     return fields && fields[field] && fields[field].lang;
   }
 
+  /**
+   * @param {{
+   *   namespace: string,
+   *   preferredLocale: string,
+   *   schemaItems: {
+   *     title: string,
+   *     type: string
+   *   }[],
+   *   pluginsForWork: import('./Plugin.js').PluginsForWork
+   * }} cfg
+   * @returns {(field: string) => boolean}
+   */
   getFieldMatchesLocale ({
     namespace, preferredLocale, schemaItems,
     pluginsForWork
@@ -203,7 +400,9 @@ export class Metadata {
       const hasFieldValue = localeStrings &&
                 Object.keys(localeStrings).some((lng) => {
                   const fv = localeStrings[lng] &&
-                        localeStrings[lng].fieldvalue;
+                        /** @type {import('../../server/main.js').LocalizationStrings} */
+                        (/** @type {import('../../server/main.js').LocalizationStrings} */
+                          (localeStrings[lng]).fieldvalue);
                   return fv && fv[field];
                 });