textbrowser 0.50.0 → 0.51.0

package/resources/workDisplay.js

@@ -6,6 +6,61 @@ import {dialogs} from './utils/dialogs.js';
 
 import Templates from './templates/index.js';
 
+/**
+ * @typedef {() => Promise<{
+ *   groupName: string | Text | DocumentFragment,
+ *   worksToFields: {
+ *     workName: string | Text | DocumentFragment,
+ *     shortcut: string,
+ *     fieldAliasOrNames: (
+ *       string|string[]|import('../server/main.js').LocalizationStrings
+ *     )[]|undefined
+ *   }[]
+ * }[]>} GetFieldAliasOrNames
+ */
+
+/**
+ * @typedef {(innerArg: {
+ *   form: HTMLFormElement,
+ *   random: {
+ *     checked: boolean
+ *   },
+ *   checkboxes: HTMLInputElement[],
+ *   type: string,
+ *   fieldAliasOrNames?: string[],
+ *   workName?: string,
+ * }) => string} SerializeParamsAsURL
+ */
+
+/**
+ * @typedef {(
+ *   key: string|string[],
+ *   substitutions?: Record<string, string>
+ * ) => string|Text|DocumentFragment} LDirectional
+ */
+
+/**
+ * @typedef {(
+ *   key: string,
+ *   tag: string,
+ *   attr: string,
+ *   atts: import('jamilih').JamilihAttributes,
+ *   children?: import('jamilih').JamilihChildren
+ * ) => import('jamilih').JamilihArray} LElement
+ */
+
+/**
+ * @this {import('./index.js').default}
+ * @param {{
+ *   l: import('intl-dom').I18NCallback,
+ *   languageParam: string,
+ *   lang: string[],
+ *   preferredLocale: string,
+ *   languages: import('./utils/Languages.js').Languages,
+ *   fallbackLanguages: string[],
+ *   $p: import('./utils/IntlURLSearchParams.js').default
+ * }} cfg
+ */
 export default async function workDisplay ({
   l, languageParam,
   lang, preferredLocale, languages, fallbackLanguages, $p
@@ -13,7 +68,7 @@ export default async function workDisplay ({
   const {preferencesPlugin} = this;
   const langs = this.langData.languages;
 
-  const fallbackDirection = this.getDirectionForLanguageCode(fallbackLanguages[0]);
+  // const fallbackDirection = this.getDirectionForLanguageCode(fallbackLanguages[0]);
 
   const prefI18n = localStorage.getItem(this.namespace + '-localizeParamNames');
   const localizeParamNames = $p.localizeParamNames = $p.has('i18n', true)
@@ -29,19 +84,63 @@ export default async function workDisplay ({
       prefFormatting !== 'false' && this.hideFormattingSection
     );
 
+  /**
+   * @this {import('./index.js').default}
+   * @param {{
+   *   workI18n: import('intl-dom').I18NCallback,
+   *   metadataObj: import('./utils/Metadata.js').MetadataObj,
+   *   getFieldAliasOrName: (field: string) => string|string[]|import('../server/main.js').LocalizationStrings,
+   *   schemaItems: {title: string, type: string}[],
+   *   fieldInfo: import('./utils/WorkInfo.js').FieldInfo,
+   *   metadata: import('./utils/Metadata.js').Metadata,
+   *   pluginsForWork: import('./utils/Plugin.js').PluginsForWork|null,
+   *   groupsToWorks: {
+   *     name: string | Text | DocumentFragment,
+   *     workNames: (string | Text | DocumentFragment)[],
+   *     shortcuts: string[]
+   *   }[]
+   * }} cfg
+   * @returns {Promise<void>}
+   */
   async function _displayWork ({
     workI18n, metadataObj, getFieldAliasOrName, schemaItems, // schemaObj,
     fieldInfo, metadata, pluginsForWork, groupsToWorks
   }) {
     const lParam = localizeParamNames
-      ? (key) => l(['params', key])
-      : (key) => key;
+      // eslint-disable-next-line @stylistic/operator-linebreak -- TS
+      ?
+      /**
+      * @param {string} key
+      * @returns {string}
+      */ (key) => /** @type {string} */ (l(['params', key]))
+      // eslint-disable-next-line @stylistic/operator-linebreak -- TS
+      :
+      /**
+       * @param {string} key
+       * @returns {string}
+       */
+      (key) => key;
     const lIndexedParam = localizeParamNames
-      ? (key) => l(['params', 'indexed', key])
-      : (key) => key;
+      // eslint-disable-next-line @stylistic/operator-linebreak -- TS
+      ?
+      /**
+       * @param {string} key
+       * @returns {string}
+       */
+      (key) => /** @type {string} */ (l(['params', 'indexed', key]))
+      // eslint-disable-next-line @stylistic/operator-linebreak -- TS
+      :
+      /**
+       * @param {string} key
+       * @returns {string}
+       */
+      (key) => key;
 
     // Returns element with localized option text (as Jamilih), with
     //   optional fallback direction
+    /**
+     * @type {LElement}
+     */
     const lElement = (key, el, attToLocalize, atts, children = []) => {
       atts[attToLocalize] = l(
         key
@@ -55,6 +154,10 @@ export default async function workDisplay ({
     };
 
     // Returns plain text node or element (as Jamilih) with fallback direction
+
+    /**
+     * @type {LDirectional}
+     */
     const lDirectional = (key, substitutions) => l(
       key,
       substitutions
@@ -67,15 +170,20 @@ export default async function workDisplay ({
     const fieldMatchesLocale = metadata.getFieldMatchesLocale({
       namespace: this.namespace,
       preferredLocale, schemaItems,
-      pluginsForWork
+      // eslint-disable-next-line object-shorthand -- TS
+      pluginsForWork: /** @type {import('./utils/Plugin.js').PluginsForWork} */ (
+        pluginsForWork
+      )
     });
 
+    /** @type {import('jamilih').JamilihArray[]} */
     const content = [];
     this.getBrowseFieldData({
       metadataObj, schemaItems, getFieldAliasOrName,
       callback ({browseFields, i}) {
         Templates.workDisplay.addBrowseFields({
-          browseFields, fieldInfo,
+          browseFields,
+          fieldInfo,
           lDirectional, i, lIndexedParam, $p, content
         });
       }
@@ -89,10 +197,14 @@ export default async function workDisplay ({
     const serializeParamsAsURL = getSerializeParamsAsURL({l, lParam, $p});
     const paramsSetter = getParamsSetter({l, lParam, $p});
 
-    const {groups} = await getJSON(this.files);
+    const {groups} = /** @type {import('./utils/WorkInfo.js').FilesObject} */ (
+      await getJSON(this.files)
+    );
 
     // const arabicContent = ['test1', 'test2']; // Todo: Fetch dynamically
-    const heading = getMetaProp(lang, metadataObj, 'heading');
+    const heading = /** @type {string} */ (
+      getMetaProp(lang, metadataObj, 'heading')
+    );
 
     const getFieldAliasOrNames = (() => {
       // Avoid blocking but start now
@@ -102,10 +214,12 @@ export default async function workDisplay ({
           const worksToFields = await Promise.all(workNames.map(async (workName, i) => {
             return {
               workName, shortcut: shortcuts[i],
-              fieldAliasOrNames: (await this.getWorkData({
-                lang, fallbackLanguages, preferredLocale,
-                languages, work: workName
-              })).fieldInfo.map(({fieldAliasOrName}) => fieldAliasOrName)
+              fieldAliasOrNames: (
+                await this.getWorkData({
+                  lang, fallbackLanguages, preferredLocale,
+                  languages, work: /** @type {string} */ (workName)
+                })
+              )?.fieldInfo?.map(({fieldAliasOrName}) => fieldAliasOrName)
             };
           }));
           return {
@@ -128,41 +242,53 @@ export default async function workDisplay ({
         languageDisplay: 'standard' // 'dialect'
       }
     );
+
+    /**
+     * @param {string} code
+     */
     const languageI18n = (code) => {
-      return displayNames.of(code);
+      return /** @type {string} */ (displayNames.of(code));
     };
 
     Templates.workDisplay.main({
-      languageParam, lang, workI18n,
+      languageParam,
+      // lang,
+      workI18n,
       l, namespace: this.namespace, groups, heading,
-      languageI18n, fallbackDirection,
+      languageI18n,
+      // fallbackDirection,
       langs, fieldInfo, localizeParamNames,
       serializeParamsAsURL, paramsSetter, replaceHash,
       getFieldAliasOrNames,
       hideFormattingSection, $p,
       metadataObj, lParam, lElement, lDirectional, lIndexedParam,
       fieldMatchesLocale,
-      preferredLocale, schemaItems, content,
+      preferredLocale, schemaItems,
+      content,
       preferencesPlugin
     });
   }
 
   try {
-    const {workI18n, fileData, metadataObj, ...args} = await this.getWorkData({
-      lang, fallbackLanguages, preferredLocale,
-      languages, work: $p.get('work')
-    });
+    const {workI18n, fileData, metadataObj, ...args} =
+      /** @type {import('./utils/WorkInfo.js').GetWorkDataReturn} */ (
+        await this.getWorkData({
+          lang, fallbackLanguages, preferredLocale,
+          languages,
+          work: /** @type {string} */ ($p.get('work'))
+        }));
 
-    document.title = workI18n(
+    document.title = /** @type {string} */ (workI18n(
       'browserfile-workdisplay',
       {
         work: fileData
-          ? getMetaProp(lang, metadataObj, 'alias')
+          ? /** @type {string} */ (getMetaProp(lang, metadataObj, 'alias'))
           : ''
       }
-    );
+    ));
     await _displayWork.call(this, {workI18n, metadataObj, ...args});
-  } catch (err) {
+  } catch (error) {
+    const err = /** @type {Error} */ (error);
     console.log('err', err);
     dialogs.alert(err);
   }

package/resources/workSelect.js

@@ -5,6 +5,15 @@ import {getMetaProp} from './utils/Metadata.js';
 import {dialogs} from './utils/dialogs.js';
 import Templates from './templates/index.js';
 
+/**
+ * @param {{
+ *   files: string,
+ *   lang: string[],
+ *   fallbackLanguages: string[],
+ *   $p: import('./utils/IntlURLSearchParams.js').default,
+ *   followParams: (formSelector: string, cb: () => void) => void
+ * }} cfg
+ */
 export default async function workSelect ({
   files, lang, fallbackLanguages, $p, followParams
   /* , l, defineFormatter */
@@ -12,40 +21,48 @@ export default async function workSelect ({
   // We use getJSON instead of JsonRefs as we do not necessarily need to
   //    resolve the file contents here
   try {
-    const works = await getJSON(files);
+    const works = /** @type {import('./utils/WorkInfo.js').FilesObject} */ (
+      await getJSON(files)
+    );
     const localizationStrings = works['localization-strings'];
 
-    const metadataObjs = await getJSON(works.groups.reduce((arr, fileGroup) => {
-      const metadataBaseDir = (works.metadataBaseDirectory || '') +
-                (fileGroup.metadataBaseDirectory || '') + '/';
-      return fileGroup.files.reduce((ar, fileData) => [
-        ...ar, metadataBaseDir + fileData.metadataFile
-      ],
-      arr);
-    }, []));
+    const metadataObjs = /** @type {import('./utils/Metadata.js').MetadataObj[]} */ (
+      await getJSON(works.groups.reduce((arr, fileGroup) => {
+        const metadataBaseDir = (works.metadataBaseDirectory || '') +
+                  (fileGroup.metadataBaseDirectory || '') + '/';
+        return fileGroup.files.reduce((ar, fileData) => [
+          ...ar, metadataBaseDir + fileData.metadataFile
+        ],
+        arr);
+      }, /** @type {string[]} */ ([])))
+    );
 
     const workI18n = await i18n({
       messageStyle: 'plainNested',
       locales: lang,
       defaultLocales: fallbackLanguages,
       // Todo: Could at least share this with `index.js`
-      localeStringFinder ({
+      async localeStringFinder ({
         locales, defaultLocales
-      }) {
-        const locale = [...locales, ...defaultLocales].find((language) => {
+      } = {}) {
+        const locale = [
+          ...(/** @type {string[]} */ (locales)),
+          ...(/** @type {string[]} */ (defaultLocales))
+        ].find((language) => {
           return language in localizationStrings;
         });
         return {
-          locale,
+          // eslint-disable-next-line object-shorthand -- TS
+          locale: /** @type {string} */ (locale),
           strings: {
             head: {},
-            body: localizationStrings[locale]
+            body: localizationStrings[/** @type {string} */ (locale)]
           }
         };
       }
     });
 
-    document.title = workI18n('browserfile-workselect');
+    document.title = /** @type {string} */ (workI18n('browserfile-workselect'));
     /*
     // Would need adapting now that not using IMF
     function lDirectional (key, substitutions, formats) {
@@ -64,13 +81,16 @@ export default async function workSelect ({
 
     const metadataObjsIter = metadataObjs[Symbol.iterator]();
     const getNextAlias = () => {
-      const metadataObj = metadataObjsIter.next().value;
+      const metadataObj = /** @type {import('./utils/Metadata.js').MetadataObj} */ (
+        metadataObjsIter.next().value
+      );
       return getMetaProp(lang, metadataObj, 'alias');
     };
     Templates.workSelect({
       groups: works.groups, workI18n, getNextAlias, $p, followParams
     });
-  } catch (err) {
+  } catch (error) {
+    const err = /** @type {Error} */ (error);
     console.log('Error', err);
     dialogs.alert(err);
   }

package/server/main.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 
 /* eslint-env node -- Environment here */
-import http from 'http';
+import http from 'node:http';
 
+// @ts-expect-error Todo: Needs Types
 import statik from '@brettz9/node-static';
 import fetch from 'node-fetch';
+// @ts-expect-error Todo: Needs Types
 import commandLineArgs from 'command-line-args';
 import DOMParser from 'dom-parser';
+
+// Why can't we just import `indexeddbshim` here? Because we need a UMD module?
+// @ts-expect-error Todo: Needs Types
 import setGlobalVars from 'indexeddbshim/dist/indexeddbshim-UnicodeIdentifiers-node.cjs';
 import {getJSON} from 'simple-get-json';
 import {setFetch} from 'intl-dom';
@@ -18,6 +23,8 @@ import {setServiceWorkerDefaults} from '../resources/utils/ServiceWorker.js';
 import {Languages} from '../resources/utils/Languages.js';
 import activateCallback from '../resources/activateCallback.js';
 
+// Todo: Should loosen this to not follow all of `fetch`'s API
+// @ts-expect-error Todo: Needs types
 setFetch(fetch);
 
 // Todo (low): See
@@ -26,6 +33,28 @@ setFetch(fetch);
 //   server-side and apply fetch listener as Node middleware to retrieve a
 //   locally-saved copy of pre-fetched (cached) files during install event
 
+/**
+ * @typedef {{
+ *   nodeActivate: boolean,
+ *   port: number,
+ *   domain: string,
+ *   basePath: string,
+ *   interlinearSeparator: string,
+ *   localizeParamNames: boolean,
+ *   trustFormatHTML: boolean,
+ *   allowPlugins: boolean,
+ *   showEmptyInterlinear: boolean,
+ *   showTitleOnSingleInterlinear: boolean,
+ *   serviceWorkerPath: string,
+ *   userJSON: string,
+ *   languages: string,
+ *   files: string,
+ *   namespace: string,
+ *   httpServer: string,
+ *   expressServer: string
+ * }} UserOptions
+ */
+
 const optionDefinitions = [
   // Node-server-specific
   {name: 'nodeActivate', type: Boolean},
@@ -64,6 +93,21 @@ const port = 'port' in userParams ? userParams.port : 8000;
 const domain = userParams.domain || `localhost`;
 const basePath = userParams.basePath || `http://${domain}${port ? ':' + port : ''}/`;
 
+/**
+ * @typedef {import('../resources/utils/ServiceWorker.js').ServiceWorkerConfig &
+ *   UserOptions & {
+ *     lang: string[],
+ *     langs: LanguageInfo[],
+ *     fallbackLanguages: string[],
+ *     log: (...args: any[]) => void,
+ *     nodeActivate?: boolean,
+ *     port?: number,
+ *     skipIndexedDB: false,
+ *     noDynamic: false,
+ *   }
+ * } ResultsDisplayServerContext
+ */
+
 const userParamsWithDefaults = {
   ...setServiceWorkerDefaults({}, {
     namespace: 'textbrowser',
@@ -72,6 +116,9 @@ const userParamsWithDefaults = {
     serviceWorkerPath: `${basePath}sw.js?pathToUserJSON=${encodeURIComponent(userParams.userJSON || '')}`
   }),
   ...userParams,
+  /**
+   * @param {...any} args
+   */
   log (...args) {
     console.log(...args);
   },
@@ -100,8 +147,9 @@ setGlobalVars(null, {
 }); // Adds `indexedDB` and `IDBKeyRange` to global in Node
 
 if (userParams.nodeActivate) {
+  // @ts-expect-error Ok
   // eslint-disable-next-line n/no-unsupported-features/node-builtins -- node-fetch
-  global.fetch = fetch;
+  globalThis.fetch = /** @type {fetch} */ (fetch);
   setTimeout(async () => {
     await activateCallback({...userParamsWithDefaults, basePath});
   });
@@ -109,15 +157,46 @@ if (userParams.nodeActivate) {
 }
 console.log('past activate check');
 
-global.DOMParser = DOMParser; // potentially used within resultsDisplay.js
+// @ts-expect-error Ok
+globalThis.DOMParser = DOMParser; // potentially used within resultsDisplay.js
 
 const fileServer = new statik.Server(); // Pass path; otherwise uses current directory
 
-let langData, languagesInstance;
+/**
+ * @typedef {{
+ *   code: string,
+ *   direction: "ltr"|"rtl",
+ *   locale: {
+ *     $ref: string
+ *   }
+ * }} LanguageInfo
+ */
+
+/**
+ * @typedef {{
+ *   [key: string]: string|string[]|LocalizationStrings
+ * }} LocalizationStrings
+ */
+
+/**
+ * @typedef {{
+ *   languages: LanguageInfo[],
+ *   localeFileBasePath?: string,
+ *   "localization-strings": LocalizationStrings
+ * }} LanguagesData
+ */
+
+/**
+ * @type {LanguagesData}
+ */
+let langData;
+
+/** @type {Languages} */
+let languagesInstance;
 
 const srv = http.createServer(async (req, res) => {
   // console.log('URL::', new URL(req.url));
-  const {pathname, search} = new URL(req.url, basePath);
+  const {pathname, search} = new URL(/** @type {string} */ (req.url), basePath);
   if (pathname !== '/textbrowser' || !search) {
     const staticServer = () => {
       if (pathname.includes('.git')) {
@@ -148,19 +227,25 @@ const srv = http.createServer(async (req, res) => {
       );
     };
     if (userParams.expressServer) {
+      /** @type {import('express').Application} */
       const app = (await import(userParams.expressServer)).default();
 
-      if (userParams.httpServer && (!app._router || !app._router.stack.some(({regexp}) => {
-        // Hack to ignore middleware like jsonParser (and hopefully
-        //   not get any other)
-        return regexp.source !== String.raw`^\/?(?=\\/|$)` && regexp.test(req.url);
-      }))) {
+      if (userParams.httpServer && (!app._router || !app._router.stack.some(
+        /** @type {(info: {regexp: RegExp}) => boolean} */
+        ({regexp}) => {
+          // Hack to ignore middleware like jsonParser (and hopefully
+          //   not get any other)
+          return regexp.source !== String.raw`^\/?(?=\\/|$)` &&
+            regexp.test(/** @type {string} */ (req.url));
+        }
+      ))) {
         await runHttpServer();
 
         // Ideally we could use `next` here to serve as a back-up static
         //  server (i.e., for the bahaiwritings app proper), but the indexes
         //  app apparently tries to use it (and fails) after a single
         //  successful HTML page load. So we let the Express app handle
+        // @ts-expect-error Ok
         app(req, res, () => {
           // Empty
         });
@@ -168,6 +253,7 @@ const srv = http.createServer(async (req, res) => {
       }
 
       // app.get('*', staticServer);
+      // @ts-expect-error Ok
       app(req, res, next);
 
       return;
@@ -184,6 +270,7 @@ const srv = http.createServer(async (req, res) => {
     return;
   }
   const languages = (req.headers['accept-language']?.replace(/;q=.*$/, '') ?? 'en-US').split(',');
+  // @ts-expect-error Polyglot reasons
   // eslint-disable-next-line n/no-unsupported-features/node-builtins -- Polyglot reasons
   global.navigator = {
     language: languages[0],
@@ -194,7 +281,9 @@ const srv = http.createServer(async (req, res) => {
   });
 
   if (!langData || !languagesInstance) {
-    langData = await getJSON(userParamsWithDefaults.languages);
+    langData = /** @type {LanguagesData} */ (
+      await getJSON(userParamsWithDefaults.languages)
+    );
     languagesInstance = new Languages({langData});
   }
 
@@ -207,22 +296,25 @@ const srv = http.createServer(async (req, res) => {
   });
 
   const resultsDisplay = async function () {
-    const serverOutput = $p.get('serverOutput', true);
-    let allowPlugins = $p.get('allowPlugins', true);
-    if (allowPlugins === '0') {
-      allowPlugins = false;
-    }
+    const serverOutput = /** @type {"html"|"jamilih"|"json"} */ (
+      $p.get('serverOutput', true)
+    );
+    const allowPluginsParam = $p.get('allowPlugins', true);
+    const allowPlugins = Boolean(allowPluginsParam && allowPluginsParam !== '0');
+
     const isHTML = serverOutput === 'html';
     res.writeHead(200, {'Content-Type': isHTML
       ? 'text/html;charset=utf8'
       : 'application/json;charset=utf8'
     });
+
     // Todo: Move sw-sample.js to bahaiwritings and test
     const result = await resultsDisplayServer.call(
       // Context
-      {
+      /** @type {ResultsDisplayServerContext} */
+      ({
         ...userParamsWithDefaults, lang, langs, fallbackLanguages
-      },
+      }),
       // resultsArgs
       {
         l,
@@ -235,7 +327,7 @@ const srv = http.createServer(async (req, res) => {
         allowPlugins,
         serverOutput,
         langData,
-        prefI18n: $p.get('prefI18n', true)
+        prefI18n: /** @type {"true"|"false"|null} */ ($p.get('prefI18n', true))
       }
     );
     res.end(isHTML ? result : JSON.stringify(result));

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "lib": ["es2022", "DOM", "DOM.Iterable", "webworker"],
+    "moduleResolution": "Bundler",
+    "module": "ESNext",
+    "allowJs": true,
+    "checkJs": true,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "target": "es2017",
+    "outDir": "dist"
+  },
+  "include": [
+    "*.js",
+    "resources",
+    "server",
+    "test",
+    "dist/sw-helper.js"
+    // "typings/*.d.ts"
+  ],
+  "exclude": [
+    "node_modules", "resources/vendor", "resources/user-sample.js",
+    "resources/user.js",
+    "sw-sample.js",
+    "dist"
+  ]
+}

package/resources/user.js

@@ -1,20 +0,0 @@
-import TextBrowser from '../dist/index-es.js';
-
-const tb = new TextBrowser({
-  languages: 'appdata/languages.json', // Default
-  // serviceWorkerPath: 'sw.js', // Default
-  // site: 'site.json', // Default
-  // localizeParamNames: true, // Not well-tested
-  // hideFormattingSection: true,
-  // requestPersistentStorage: false,
-  // showEmptyInterlinear: false,
-  // showTitleOnSingleInterlinear: false,
-  files: 'files.json', // Change as needed to your `files.json` location
-  stylesheets: ['@builtin'], // Add other paths for your CSS
-  namespace: 'myapp', // Used for namespacing localStorage
-  allowPlugins: true, // Enables `files.json`-specified plugins
-  // dynamicBasePath: '',
-  trustFormatHTML: true // Needed if allowing for raw HTML fields (don't use for untrusted schemas)
-  // , interlinearSeparator: '<hr />' // Defaults to `<br /><br />`
-});
-await tb.init();