From 0b913053a76e83a43846e19097963f98c8519a1d Mon Sep 17 00:00:00 2001
From: Ivan Gabaldon <igabaldon@inetol.net>
Date: Sun, 6 Jul 2025 12:27:28 +0200
Subject: [mod] theme/simple: migrate codebase to TypeScript

TypeScript is a superset of JavaScript, converting the entire theme to
TypeScript allows us to receive much more feedback on possible issues made in
package updates or our own typos, furthermore, it allows to transpile properly
to lower specs. This PR couldn't be done in smaller commits, a lot of work
needed to make everything *work properly*:

- A browser baseline has been set that requires minimum **Chromium 93, Firefox
  92 and Safari 15** (proper visuals/operation on older browser versions is not
  guaranteed)
- LightningCSS now handles minification and prefix creation for CSS.
- All hardcoded polyfills and support for previous browser baseline versions
  have been removed.
- Convert codebase to TypeScript.
- Convert IIFE to ESM, handling globals with IIFE is cumbersome, ESM is the
  standard for virtually any use of JS nowadays.
- Vite now builds the theme without the need for `vite-plugin-static-copy`.
- `searxng.ready` now accepts an array of conditions for the callback to be
  executed.
- Replace `leaflet` with `ol` as there were some issues with proper Vite
  bundling.
- Merged `head` with `main` script, as head was too small now.
- Add `assertElement` to properly check the existence of critical DOM elements.
- `searxng.on` renamed to `searxng.listen` with some handling improvements.
---
 client/simple/tools/img.js               |  64 -----------------
 client/simple/tools/img.ts               |  62 ++++++++++++++++
 client/simple/tools/jinja_svg_catalog.js | 119 ------------------------------
 client/simple/tools/jinja_svg_catalog.ts | 120 +++++++++++++++++++++++++++++++
 client/simple/tools/plg.js               |  44 ------------
 client/simple/tools/plg.ts               |  43 +++++++++++
 6 files changed, 225 insertions(+), 227 deletions(-)
 delete mode 100644 client/simple/tools/img.js
 create mode 100644 client/simple/tools/img.ts
 delete mode 100644 client/simple/tools/jinja_svg_catalog.js
 create mode 100644 client/simple/tools/jinja_svg_catalog.ts
 delete mode 100644 client/simple/tools/plg.js
 create mode 100644 client/simple/tools/plg.ts

(limited to 'client/simple/tools')

diff --git a/client/simple/tools/img.js b/client/simple/tools/img.js
deleted file mode 100644
index 0b1b96ed8..000000000
--- a/client/simple/tools/img.js
+++ /dev/null
@@ -1,64 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import sharp from "sharp";
-import { optimize as svgo } from "svgo";
-
-/**
- * @typedef {object} Src2Dest - Mapping of src to dest
- * @property {string} src - Name of the source file.
- * @property {string} dest - Name of the destination file.
- */
-
-/**
- * Convert a list of SVG files to PNG.
- *
- * @param {Src2Dest[]} items - Array of SVG files (src: SVG, dest:PNG) to convert.
- */
-async function svg2png(items) {
-  for (const item of items) {
-    try {
-      fs.mkdir(path.dirname(item.dest), { recursive: true }, (err) => {
-        if (err) throw err;
-      });
-
-      const info = await sharp(item.src)
-        .png({
-          force: true,
-          compressionLevel: 9,
-          palette: true
-        })
-        .toFile(item.dest);
-
-      console.log(`[svg2png] created ${item.dest} -- bytes: ${info.size}, w:${info.width}px,  h:${info.height}px`);
-    } catch (err) {
-      console.error(`ERROR: ${item.dest} -- ${err}`);
-      throw err;
-    }
-  }
-}
-
-/**
- * Optimize SVG images for WEB.
- *
- * @param {Src2Dest[]} items - Array of SVG files (src:SVG, dest:SVG) to optimize.
- * @param {import('svgo').Config} svgo_opts - Options passed to svgo.
- */
-async function svg2svg(items, svgo_opts) {
-  for (const item of items) {
-    try {
-      fs.mkdir(path.dirname(item.dest), { recursive: true }, (err) => {
-        if (err) throw err;
-      });
-
-      const raw = fs.readFileSync(item.src, "utf8");
-      const opt = svgo(raw, svgo_opts);
-      fs.writeFileSync(item.dest, opt.data);
-      console.log(`[svg2svg] optimized: ${item.dest} -- src: ${item.src}`);
-    } catch (err) {
-      console.error(`ERROR: optimize src: ${item.src} -- ${err}`);
-      throw err;
-    }
-  }
-}
-
-export { svg2png, svg2svg };
diff --git a/client/simple/tools/img.ts b/client/simple/tools/img.ts
new file mode 100644
index 000000000..db4e08645
--- /dev/null
+++ b/client/simple/tools/img.ts
@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import sharp from "sharp";
+import type { Config } from "svgo";
+import { optimize as svgo } from "svgo";
+
+// Mapping of src to dest
+export type Src2Dest = {
+  // Name of the source file.
+  src: string;
+  // Name of the destination file.
+  dest: string;
+};
+
+/**
+ * Convert a list of SVG files to PNG.
+ *
+ * @param items - Array of SVG files (src: SVG, dest:PNG) to convert.
+ */
+export const svg2png = async (items: Src2Dest[]) => {
+  for (const item of items) {
+    try {
+      fs.mkdirSync(path.dirname(item.dest), { recursive: true });
+
+      const info = await sharp(item.src)
+        .png({
+          force: true,
+          compressionLevel: 9,
+          palette: true
+        })
+        .toFile(item.dest);
+
+      console.log(`[svg2png] created ${item.dest} -- bytes: ${info.size}, w:${info.width}px,  h:${info.height}px`);
+    } catch (err) {
+      console.error(`ERROR: ${item.dest} -- ${err}`);
+      throw err;
+    }
+  }
+};
+
+/**
+ * Optimize SVG images for WEB.
+ *
+ * @param items - Array of SVG files (src:SVG, dest:SVG) to optimize.
+ * @param svgo_opts - Options passed to svgo.
+ */
+export const svg2svg = (items: Src2Dest[], svgo_opts: Config) => {
+  for (const item of items) {
+    try {
+      fs.mkdirSync(path.dirname(item.dest), { recursive: true });
+
+      const raw = fs.readFileSync(item.src, "utf8");
+      const opt = svgo(raw, svgo_opts);
+
+      fs.writeFileSync(item.dest, opt.data);
+      console.log(`[svg2svg] optimized: ${item.dest} -- src: ${item.src}`);
+    } catch (err) {
+      console.error(`ERROR: optimize src: ${item.src} -- ${err}`);
+      throw err;
+    }
+  }
+};
diff --git a/client/simple/tools/jinja_svg_catalog.js b/client/simple/tools/jinja_svg_catalog.js
deleted file mode 100644
index b7b0347b5..000000000
--- a/client/simple/tools/jinja_svg_catalog.js
+++ /dev/null
@@ -1,119 +0,0 @@
-import fs from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { Edge } from "edge.js";
-import { optimize as svgo } from "svgo";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const __jinja_class_placeholder__ = "__jinja_class_placeholder__";
-
-// -- types
-
-/**
- * @typedef {object} IconSet - A set of icons
- * @property {object} set - Object of SVG icons, where property name is the
- * name of the icon and value is the src of the SVG (relative to base).
- * @property {string} base - Folder in which the SVG src files are located.
- * @property {import("svgo").Config} svgo_opts - svgo options for this set.
- */
-
-/**
- * @typedef {object} IconSVG - Mapping of icon name to SVG source file.
- * @property {string} name - Name of the icon isource file.
- * @property {string} src - Name of the destination file.
- * @property {import("svgo").Config} svgo_opts - Options passed to svgo.
- */
-
-/**
- * @typedef {object} JinjaMacro - Arguments to create a jinja macro
- * @property {string} name - Name of the jinja macro.
- * @property {string} class - SVG's class name (value of XML class attribute)
- */
-
-// -- functions
-
-/**
- * Generate a jinja template with a catalog of SVG icons that can be
- * used in in other HTML jinja templates.
- *
- * @param {string} dest - filename of the generate jinja template.
- * @param {JinjaMacro} macros - Jinja macros to create.
- * @param {IconSVG[]} items - Array of SVG items.
- */
-
-function jinja_svg_catalog(dest, macros, items) {
-  const svg_catalog = {};
-  const edge_template = resolve(__dirname, "jinja_svg_catalog.html.edge");
-
-  items.forEach((item) => {
-    /** @type {import("svgo").Config} */
-    // JSON.stringify & JSON.parse are used to create a deep copy of the
-    // item.svgo_opts object
-    const svgo_opts = JSON.parse(JSON.stringify(item.svgo_opts));
-    svgo_opts.plugins.push({
-      name: "addClassesToSVGElement",
-      params: {
-        classNames: [__jinja_class_placeholder__]
-      }
-    });
-
-    try {
-      const raw = fs.readFileSync(item.src, "utf8");
-      const opt = svgo(raw, svgo_opts);
-      svg_catalog[item.name] = opt.data;
-    } catch (err) {
-      console.error(`ERROR: jinja_svg_catalog processing ${item.name} src: ${item.src} -- ${err}`);
-      throw err;
-    }
-  });
-
-  fs.mkdir(dirname(dest), { recursive: true }, (err) => {
-    if (err) throw err;
-  });
-
-  const ctx = {
-    svg_catalog: svg_catalog,
-    macros: macros,
-    edge_template: edge_template,
-    __jinja_class_placeholder__: __jinja_class_placeholder__,
-    // see https://github.com/edge-js/edge/issues/162
-    open_curly_brace: "{{",
-    close_curly_brace: "}}"
-  };
-
-  const jinjatmpl = Edge.create().renderRawSync(fs.readFileSync(edge_template, "utf-8"), ctx);
-
-  fs.writeFileSync(dest, jinjatmpl);
-  console.log(`[jinja_svg_catalog] created: ${dest}`);
-}
-
-/**
- * Calls jinja_svg_catalog for a collection of icon sets where each set has its
- * own parameters.
- *
- * @param {string} dest - filename of the generate jinja template.
- * @param {JinjaMacro} macros - Jinja macros to create.
- * @param {IconSet[]} sets - Array of SVG sets.
- */
-function jinja_svg_sets(dest, macros, sets) {
-  /** @type IconSVG[] */
-  const items = [];
-  const all = [];
-  for (const obj of sets) {
-    for (const [name, file] of Object.entries(obj.set)) {
-      if (all.includes(name)) {
-        throw new Error(`ERROR: ${name} has already been defined`);
-      }
-      items.push({
-        name: name,
-        src: resolve(obj.base, file),
-        svgo_opts: obj.svgo_opts
-      });
-    }
-    jinja_svg_catalog(dest, macros, items);
-  }
-}
-
-// -- exports
-
-export { jinja_svg_sets, jinja_svg_catalog };
diff --git a/client/simple/tools/jinja_svg_catalog.ts b/client/simple/tools/jinja_svg_catalog.ts
new file mode 100644
index 000000000..1fa1a6676
--- /dev/null
+++ b/client/simple/tools/jinja_svg_catalog.ts
@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Edge } from "edge.js";
+import { type Config as SvgoConfig, optimize as svgo } from "svgo";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const __jinja_class_placeholder__ = "__jinja_class_placeholder__";
+
+// A set of icons
+export type IconSet = {
+  // Object of SVG icons, where property name is the name of the icon and value is the src of the SVG (relative to base)
+  set: Record<string, string>;
+  // Folder in which the SVG src files are located
+  base: string;
+  // svgo options for this set
+  svgo_opts: SvgoConfig;
+};
+
+// Mapping of icon name to SVG source file
+type IconSVG = {
+  // Name of the icon isource file
+  name: string;
+  // Name of the destination file
+  src: string;
+  // Options passed to svgo
+  svgo_opts: SvgoConfig;
+};
+
+// Arguments to create a jinja macro
+export type JinjaMacro = {
+  // Name of the jinja macro
+  name: string;
+  // SVG's class name (value of XML class attribute)
+  class: string;
+};
+
+/**
+ * Generate a jinja template with a catalog of SVG icons that can be
+ * used in other HTML jinja templates.
+ *
+ * @param dest - filename of the generate jinja template.
+ * @param macros - Jinja macros to create.
+ * @param items - Array of SVG items.
+ */
+export const jinja_svg_catalog = (dest: string, macros: JinjaMacro[], items: IconSVG[]) => {
+  const svg_catalog: Record<string, string> = {};
+  const edge_template = resolve(__dirname, "jinja_svg_catalog.html.edge");
+
+  for (const item of items) {
+    // JSON.stringify & JSON.parse are used to create a deep copy of the item.svgo_opts object
+    const svgo_opts: SvgoConfig = JSON.parse(JSON.stringify(item.svgo_opts));
+
+    svgo_opts.plugins?.push({
+      name: "addClassesToSVGElement",
+      params: {
+        classNames: [__jinja_class_placeholder__]
+      }
+    });
+
+    try {
+      const raw = fs.readFileSync(item.src, "utf8");
+      const opt = svgo(raw, svgo_opts);
+
+      svg_catalog[item.name] = opt.data;
+    } catch (err) {
+      console.error(`ERROR: jinja_svg_catalog processing ${item.name} src: ${item.src} -- ${err}`);
+      throw err;
+    }
+  }
+
+  fs.mkdir(dirname(dest), { recursive: true }, (err) => {
+    if (err) throw err;
+  });
+
+  const ctx = {
+    svg_catalog: svg_catalog,
+    macros: macros,
+    edge_template: edge_template,
+    __jinja_class_placeholder__: __jinja_class_placeholder__,
+    // see https://github.com/edge-js/edge/issues/162
+    open_curly_brace: "{{",
+    close_curly_brace: "}}"
+  };
+
+  const jinjatmpl = Edge.create().renderRawSync(fs.readFileSync(edge_template, "utf-8"), ctx);
+
+  fs.writeFileSync(dest, jinjatmpl);
+  console.log(`[jinja_svg_catalog] created: ${dest}`);
+};
+
+/**
+ * Calls jinja_svg_catalog for a collection of icon sets where each set has its
+ * own parameters.
+ *
+ * @param dest - filename of the generate jinja template.
+ * @param macros - Jinja macros to create.
+ * @param sets - Array of SVG sets.
+ */
+export const jinja_svg_sets = (dest: string, macros: JinjaMacro[], sets: IconSet[]) => {
+  const items: IconSVG[] = [];
+  const all: string[] = [];
+
+  for (const obj of sets) {
+    for (const [name, file] of Object.entries(obj.set)) {
+      if (all.includes(name)) {
+        throw new Error(`ERROR: ${name} has already been defined`);
+      }
+
+      all.push(name);
+      items.push({
+        name: name,
+        src: resolve(obj.base, file),
+        svgo_opts: obj.svgo_opts
+      });
+    }
+  }
+
+  jinja_svg_catalog(dest, macros, items);
+};
diff --git a/client/simple/tools/plg.js b/client/simple/tools/plg.js
deleted file mode 100644
index 74e488fc4..000000000
--- a/client/simple/tools/plg.js
+++ /dev/null
@@ -1,44 +0,0 @@
-/**
- * Custom vite plugins to build the web-client components of the simple theme.
- *
- * HINT:
- *
- *   This is an inital implementation for the migration of the build process
- *   from grunt to vite.  For fully support (vite: build & serve) more work is
- *   needed.
- */
-
-import { svg2png, svg2svg } from "./img.js";
-
-/**
- * Vite plugin to convert a list of SVG files to PNG.
- *
- * @param {import('./img.js').Src2Dest[]} items - Array of SVG files (src: SVG, dest:PNG) to convert.
- */
-function plg_svg2png(items) {
-  return {
-    name: "searxng-simple-svg2png",
-    apply: "build", // or 'serve'
-    async writeBundle() {
-      await svg2png(items);
-    }
-  };
-}
-
-/**
- * Vite plugin to optimize SVG images for WEB.
- *
- * @param {import('./img.js').Src2Dest[]} items - Array of SVG files (src:SVG, dest:SVG) to optimize.
- * @param {import('svgo').Config} svgo_opts - Options passed to svgo.
- */
-function plg_svg2svg(items, svgo_opts) {
-  return {
-    name: "searxng-simple-svg2png",
-    apply: "build", // or 'serve'
-    async writeBundle() {
-      await svg2svg(items, svgo_opts);
-    }
-  };
-}
-
-export { plg_svg2png, plg_svg2svg };
diff --git a/client/simple/tools/plg.ts b/client/simple/tools/plg.ts
new file mode 100644
index 000000000..2db891d4f
--- /dev/null
+++ b/client/simple/tools/plg.ts
@@ -0,0 +1,43 @@
+/**
+ * Custom vite plugins to build the web-client components of the simple theme.
+ *
+ * HINT:
+ *   This is an inital implementation for the migration of the build process
+ *   from grunt to vite.  For fully support (vite: build & serve) more work is
+ *   needed.
+ */
+
+import type { Config } from "svgo";
+import type { Plugin } from "vite";
+import { type Src2Dest, svg2png, svg2svg } from "./img.ts";
+
+/**
+ * Vite plugin to convert a list of SVG files to PNG.
+ *
+ * @param items - Array of SVG files (src: SVG, dest:PNG) to convert.
+ */
+export const plg_svg2png = (items: Src2Dest[]): Plugin => {
+  return {
+    name: "searxng-simple-svg2png",
+    apply: "build",
+    async writeBundle() {
+      await svg2png(items);
+    }
+  };
+};
+
+/**
+ * Vite plugin to optimize SVG images for WEB.
+ *
+ * @param items - Array of SVG files (src:SVG, dest:SVG) to optimize.
+ * @param svgo_opts - Options passed to svgo.
+ */
+export const plg_svg2svg = (items: Src2Dest[], svgo_opts: Config): Plugin => {
+  return {
+    name: "searxng-simple-svg2svg",
+    apply: "build",
+    writeBundle() {
+      svg2svg(items, svgo_opts);
+    }
+  };
+};
-- 
cgit v1.2.3