implement documentation on custom web components

docs/api.md

@@ -8,10 +8,15 @@ SPDX-License-Identifier: CC-BY-4.0
 
 # API Reference
 
+The `dasf-web-components` library exposes two different kinds of APIs. One is
+for reactJS-projects, {ref}`react-api`, and one is for any other frontend
+framework using {ref}`web-components`.
+
 ```{toctree}
 ---
 maxdepth: 3
 ---
 
 react-api/index
+web-components/index
 ```

docs/web-components/class.md

+<!--
+SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum hereon GmbH
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+(dasf-class-web-component)=
+
+# `dasf-class` custom web component
+
+The `dasf-class` web component is a the framework agnostic alternative to the
+{func}`ClassContainer <ClassContainer.default>` react component.
+
+````{dropdown} Example
+
+An example implementation would be
+
+```html
+<dasf-class
+  websocket-url="ws://<someserver>/ws"
+  topic="sometopic"
+  class-name="SomeClass"
+></dasf-module>
+<script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
+```
+
+````
+
+(dasf-class-properties)=
+
+## Properties
+
+For documentation on the properties, please have a look at the
+{class}`ClassContainerOptions` interface. Note that the type of the
+property determines how the parameter of the custom web component is
+interpreted. Furthermore note that camel case (such as `websocketUrl`) will
+be converted to kebab case (i.e. `websocket-url`).
+
+```{literalinclude} ../../src/main.tsx
+---
+start-at: const WebClassContainer
+language: tsx
+name: dasf-class
+caption: dasf-class
+end-at: "});"
+---
+```

docs/web-components/function.md

+<!--
+SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum hereon GmbH
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+(dasf-function-web-component)=
+
+# `dasf-function` custom web component
+
+The `dasf-function` web component is a the framework agnostic alternative to the
+{func}`FunctionContainer <FunctionContainer.default>` react component.
+
+````{dropdown} Example
+
+An example implementation would be
+
+```html
+<dasf-function
+  websocket-url="ws://<someserver>/ws"
+  topic="sometopic"
+  output-description="Some description for the output"
+  function-name="test_function"
+>
+</dasf-function>
+<script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
+```
+
+````
+
+(dasf-function-properties)=
+
+## Properties
+
+For documentation on the properties, please have a look at the
+{class}`FunctionContainerOptions` interface. Note that the type of the
+property determines how the parameter of the custom web component is
+interpreted. Furthermore note that camel case (such as `websocketUrl`) will
+be converted to kebab case (i.e. `websocket-url`).
+
+(dasf-function-properties)=
+
+## Properties
+
+```{literalinclude} ../../src/main.tsx
+---
+start-at: const WebFunctionContainer
+language: tsx
+name: dasf-function
+caption: dasf-function
+end-at: "});"
+---
+```

docs/web-components/index.md

+<!--
+SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum hereon GmbH
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+(web-components)=
+
+# Custom Web Components
+
+Custom web components are HTML tags that you can directly embed into your HTML
+code. The advantage is that no further javascript framework is required, i.e.
+you can use the components of this library in a framework that does not use
+reactjs.
+
+This package exports three custom web components:
+
+- {ref}`dasf-module-web-component`: To render an entire DASF backend module
+- {ref}`dasf-class-web-component`: To render a single class of a DASF backend module
+- {ref}`dasf-function-web-component`: To render a single function of a DASF backend module.
+
+## Components
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+module
+class
+function
+```
+
+## General Usage
+
+The custom web components expose more or less the same API as their counter
+parts in react. The only difference is that you do not pass javascript objects
+in here but strings that are then interpreted accordingly.
+
+The most common usecase to render a DASF backend works like this:
+
+```html
+<dasf-module
+  websocket-url="ws://<someserver>/ws"
+  topic="sometopic"
+></dasf-module>
+<script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
+```
+
+Here the {ref}`dasf-module` custom web component is used with a `websocket-url`
+and a `topic` that are used to create the connection to the message broker.
+Furthermore we have to load this libary in a `script` tag.
+
+If we want to handle the response ourselve using the
+{attr}`~ModuleContainerOptions.onResponse` option, we have to create a global
+function and pass this to the `dasf-module` tag:
+
+```html
+<script>
+  function showResponseInLog(response) {
+    console.log(response);
+    return true;
+  }
+</script>
+<dasf-module
+  websocket-url="ws://<someserver>/ws"
+  topic="sometopic"
+  onResponse="showResponseInLog"
+></dasf-module>
+<script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
+```
+
+When we want to create the connection ourselve as we may want to use it in
+several places, we have to create a function that returns the connection
+we created
+
+```html
+<script type="module">
+  import {
+    DASFConnection,
+    WebsocketUrlBuilder,
+  } from '/node_modules/@dasf/dasf-messaging';
+
+  const connection = new DASFConnection(
+    new WebsocketUrlBuilder('ws://localhost:8080/ws', 'mytesttopic'),
+  );
+
+  const getConnection = () => {
+    return connection;
+  };
+  window['getConnection'] = getConnection;
+</script>
+<dasf-module connection="getConnection"></dasf-module>
+<script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
+```
+
+For more information on the properties for the components, see the
+corresponding sections for the
+{ref}`dasf-module properties <dasf-module-properties>`,
+{ref}`dasf-class properties <dasf-class-properties>` and
+{ref}`dasf-function properties <dasf-function-properties>`.

docs/web-components/module.md

+<!--
+SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum hereon GmbH
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+(dasf-module-web-component)=
+
+# `dasf-module` custom web component
+
+The `dasf-module` web component is a the framework agnostic alternative to the
+{func}`ModuleContainer <ModuleContainer.default>` react component.
+
+````{dropdown} Example
+
+An example implementation would be
+
+```html
+<dasf-module
+  websocket-url="ws://<someserver>/ws"
+  topic="sometopic"
+></dasf-module>
+<script type="module" src="/node_modules/@dasf/dasf-messaging"></script>
+```
+
+````
+
+(dasf-module-properties)=
+
+## Properties
+
+For documentation on the properties, please have a look at the
+{class}`ModuleContainerOptions` interface. Note that the type of the
+property determines how the parameter of the custom web component is
+interpreted. Furthermore note that camel case (such as `websocketUrl`) will
+be converted to kebab case (i.e. `websocket-url`).
+
+```{literalinclude} ../../src/main.tsx
+---
+start-at: const WebModuleContainer
+language: tsx
+name: dasf-module
+caption: dasf-module
+end-at: "});"
+---
+```

index.html

@@ -13,19 +13,32 @@ SPDX-License-Identifier: Apache-2.0
     <title>Demo Site for dasf-web-component</title>
   </head>
   <body>
-    <script>
+    <script type="module">
+      import {
+        DASFConnection,
+        WebsocketUrlBuilder,
+      } from '/node_modules/@dasf/dasf-messaging';
       function showinLog(response) {
         console.log(response);
         return true;
       }
+
+      const connection = new DASFConnection(
+        new WebsocketUrlBuilder('ws://localhost:8080/ws', 'mytesttopic'),
+      );
+
+      const getConnection = () => {
+        return connection;
+      };
+      window['showinLog'] = showinLog;
+      window['getConnection'] = getConnection;
     </script>
 
     <h1>Demo Site for dasf-web-component</h1>
 
     <h2>Single function</h2>
     <dasf-function
-      websocket-url="ws://localhost:8080/ws"
-      topic="mytesttopic"
+      connection="getConnection"
       output-description="A list of the grid definitions with the closest grid width."
       on-response="showinLog"
       function-name="test_function"
@@ -34,8 +47,7 @@ SPDX-License-Identifier: Apache-2.0
 
     <h2>Entire backend module</h2>
 
-    <dasf-module websocket-url="ws://localhost:8080/ws" topic="mytesttopic">
-    </dasf-module>
+    <dasf-module connection="getConnection"> </dasf-module>
 
     <script type="module" src="/src/main.tsx"></script>
   </body>

src/main.tsx

@@ -12,6 +12,7 @@ const WebFunctionContainer = r2wc(FunctionContainer, {
     schemaElement: 'string',
     schema: 'json',
     uiSchema: 'json',
+    connection: 'function',
     websocketUrl: 'string',
     topic: 'string',
     outputDescription: 'string',
@@ -28,6 +29,7 @@ const WebClassContainer = r2wc(ClassContainer, {
     apiInfoElement: 'string',
     apiInfo: 'json',
     uiSchema: 'json',
+    connection: 'function',
     websocketUrl: 'string',
     topic: 'string',
     className: 'string',
@@ -41,6 +43,7 @@ const WebModuleContainer = r2wc(ModuleContainer, {
   props: {
     apiInfoElement: 'string',
     apiInfo: 'json',
+    connection: 'function',
     websocketUrl: 'string',
     topic: 'string',
     onResponse: 'function',

src/resources/connection.ts

@@ -11,12 +11,13 @@ import { WebsocketUrlBuilder } from '@dasf/dasf-messaging';
  * to create a new :class:`dasf-messaging-typescript:DASFConnection`.
  */
 export interface ConnectionOptions {
-  /** A :class:`dasf-messaging-typescript:DASFConnection` to a backend module.
+  /** A `DASFConnection` to a backend module or a callable that creates one.
    *
-   * Provide a connection to a DASF backend module. If not provided, we will
+   * Provide a :class:`dasf-messaging-typescript:DASFConnection` to a DASF
+   * backend module, or a function that creates one. If not provided, we will
    * create one from the given `websocketUrl` and `topic`.
    */
-  connection?: DASFConnection;
+  connection?: DASFConnection | (() => DASFConnection);
 
   /** The websocket url to a DASF backend module
    *
@@ -54,6 +55,8 @@ export function getConnection({
       // @ts-expect-error:next-line
       new WebsocketUrlBuilder(websocketUrl, topic),
     );
+  } else if (typeof connection === 'function') {
+    return connection();
   } else {
     return connection;
   }