From fb089ae297b27f51777318e3a28bca8b172a4165 Mon Sep 17 00:00:00 2001
From: Ivan Gabaldon <igabaldon@inetol.net>
Date: Tue, 2 Dec 2025 10:18:00 +0000
Subject: [mod] client/simple: client plugins (#5406)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* [mod] client/simple: client plugins

Defines a new interface for client side *"plugins"* that coexist with server
side plugin system. Each plugin (e.g., `InfiniteScroll`) extends the base
`ts Plugin`. Client side plugins are independent and lazy‑loaded via `router.ts`
when their `load()` conditions are met. On each navigation request, all
applicable plugins are instanced.

Since these are client side plugins, we can only invoke them once DOM is fully
loaded. E.g. `Calculator` will not render a new `answer` block until fully
loaded and executed.

For some plugins, we might want to handle its availability in `settings.yml`
and toggle in UI, like we do for server side plugins. In that case, we extend
`py Plugin` instancing only the information and then checking client side if
[`settings.plugins`](https://github.com/inetol/searxng/blob/1ad832b1dc33f3f388da361ff2459b05dc86a164/client/simple/src/js/toolkit.ts#L134)
array has the plugin id.

* [mod] client/simple: rebuild static
---
 client/simple/src/js/util/appendAnswerElement.ts | 34 ++++++++++++++++++++++++
 client/simple/src/js/util/assertElement.ts       |  8 ++++++
 client/simple/src/js/util/getElement.ts          | 21 +++++++++++++++
 3 files changed, 63 insertions(+)
 create mode 100644 client/simple/src/js/util/appendAnswerElement.ts
 create mode 100644 client/simple/src/js/util/assertElement.ts
 create mode 100644 client/simple/src/js/util/getElement.ts

(limited to 'client/simple/src/js/util')

diff --git a/client/simple/src/js/util/appendAnswerElement.ts b/client/simple/src/js/util/appendAnswerElement.ts
new file mode 100644
index 000000000..d21db3f48
--- /dev/null
+++ b/client/simple/src/js/util/appendAnswerElement.ts
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { getElement } from "./getElement.ts";
+
+export const appendAnswerElement = (element: HTMLElement | string | number): void => {
+  const results = getElement<HTMLDivElement>("results");
+
+  // ./searx/templates/elements/answers.html
+  let answers = getElement<HTMLDivElement>("answers", { assert: false });
+  if (!answers) {
+    // what is this?
+    const answersTitle = document.createElement("h4");
+    answersTitle.setAttribute("class", "title");
+    answersTitle.setAttribute("id", "answers-title");
+    answersTitle.textContent = "Answers : ";
+
+    answers = document.createElement("div");
+    answers.setAttribute("id", "answers");
+    answers.setAttribute("role", "complementary");
+    answers.setAttribute("aria-labelledby", "answers-title");
+    answers.appendChild(answersTitle);
+  }
+
+  if (!(element instanceof HTMLElement)) {
+    const span = document.createElement("span");
+    span.innerHTML = element.toString();
+    // biome-ignore lint/style/noParameterAssign: TODO
+    element = span;
+  }
+
+  answers.appendChild(element);
+
+  results.insertAdjacentElement("afterbegin", answers);
+};
diff --git a/client/simple/src/js/util/assertElement.ts b/client/simple/src/js/util/assertElement.ts
new file mode 100644
index 000000000..a362fcf8f
--- /dev/null
+++ b/client/simple/src/js/util/assertElement.ts
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+type AssertElement = <T>(element?: T | null) => asserts element is T;
+export const assertElement: AssertElement = <T>(element?: T | null): asserts element is T => {
+  if (!element) {
+    throw new Error("DOM element not found");
+  }
+};
diff --git a/client/simple/src/js/util/getElement.ts b/client/simple/src/js/util/getElement.ts
new file mode 100644
index 000000000..cfb2caf4e
--- /dev/null
+++ b/client/simple/src/js/util/getElement.ts
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { assertElement } from "./assertElement.ts";
+
+type Options = {
+  assert?: boolean;
+};
+
+export function getElement<T>(id: string, options?: { assert: true }): T;
+export function getElement<T>(id: string, options?: { assert: false }): T | null;
+export function getElement<T>(id: string, options: Options = {}): T | null {
+  options.assert ??= true;
+
+  const element = document.getElementById(id) as T | null;
+
+  if (options.assert) {
+    assertElement(element);
+  }
+
+  return element;
+}
-- 
cgit v1.2.3