wip: create the documentation for the module 'forms' in flottform

flottform/forms/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+.vercel
+.output
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+/test-results
+/docs

flottform/forms/package.json

@@ -39,12 +39,15 @@
 		"lint": "prettier --check . && eslint .",
 		"format": "prettier --write .",
 		"test": "pnpm run test:unit",
-		"test:unit": "vitest"
+		"test:unit": "vitest",
+		"docs": "typedoc --options typedoc.json"
 	},
 	"devDependencies": {
 		"@types/qrcode": "^1.5.5",
 		"@vitest/browser": "^1.3.1",
+		"eslint-plugin-tsdoc": "^0.3.0",
 		"qrcode": "^1.5.3",
+		"typedoc": "^0.26.7",
 		"vite": "^5.0.3",
 		"vite-plugin-dts": "^3.7.3",
 		"vitest": "^1.3.1",

flottform/forms/src/default-component.ts

@@ -40,8 +40,66 @@ const createLinkAndQrCode = (qrCode: string, link: string) => {
 		createChannelLinkWithOffer
 	};
 };
+
+/**
+ * Creates and attaches a default Flottform UI component to the specified anchor element. This UI acts as an intermediary to facilitate WebRTC-based peer-to-peer connections between two devices, allowing one peer to send data (files or text) to the other.
+ *
+ * Developers can customize aspects of the UI, such as the button text, descriptions, and CSS classes, while using the default behavior provided by the function to quickly set up the peer-to-peer data transfer mechanism.
+ *
+ * The generated UI component will be attached as a child to `flottformAnchorElement`. The UI includes a dialog with a QR code or link that the second peer can use to connect and upload files/text to the main form.
+ *
+ * The dialog also shows the progress of receiving the file or text from the other device or any errors that can happen.
+ *
+ * The returned object allows for further interactions, such as adding the UI necessary to handle receiving a file or text, and retrieving all existing Flottform items within the UI.
+ *
+ * @param {Object} params - Configuration options for setting up the Flottform component.
+ * @param {HTMLElement} params.flottformAnchorElement - The HTML element to which the Flottform component will be attached. It determines where the UI will be built on the page.
+ * @param {string} [params.id] - Optional ID for the UI used for File of Text element.
+ * @param {HTMLElement} [params.flottformRootElement] - An optional root element to use. If not provided, a new default root element (a `div` with the class `flottform-root`) will be created.
+ * @param {string} [params.additionalComponentClass] - Optional additional class to add for custom styling of the component.
+ * @param {string} [params.flottformRootTitle] - Optional title to set for the Flottform root element This is the text displayed on the button that opens the dialog (with the class `flottform-root-opener-button`).
+ * @param {string} [params.flottformRootDescription] - Optional description text shown inside the dialog when it is opened. It provides context for the user about what the Flottform component does (e.g., "Receive files from other devices").
+ *
+ * @returns {Object} - Returns an object with methods to interact with the Flottform component.
+ * @returns {HTMLElement} returns.flottformRoot - The root element of the Flottform UI.
+ * @returns {Function} returns.createFileItem - Function to create an entry in the UI for receiving files from another peer. The entry will show the QR code/link, progress of the file transfer, and handle any errors.
+ * @returns {Function} returns.createTextItem - Function to create an entry in the UI for receiving text from another peer. Similar to `createFileItem`, it handles text input, progress tracking, and error handling.
+ * @returns {Function} returns.getAllFlottformItems - Function to retrieve all current Flottform items (file and text entries) in the dialog.
+ *
+ * @example
+ *
+ *
+ * const flottformComponent = createDefaultFlottformComponent({
+ *	flottformAnchorElement: document.getElementById('form-anchor'),
+ *	flottformRootTitle: 'Share Data via Flottform',
+ * 	flottformRootDescription: 'This form is powered by Flottform. Upload files or send text from another device using the provided QR code.'
+ *});
+ *
+ * // Create an entry to receive files
+ * flottformComponent.createFileItem({
+ *   flottformApi, // URL of the WebRTC signaling server
+ *   createClientUrl: ({ endpointId }) => `/upload/${endpointId}`, // URL of the client page for file uploads
+ *   inputField: document.querySelector('#fileInput'), // The file input field in the main form
+ *   label: 'Upload Resume', // Label for the file input
+ *   buttonLabel:'Submit File', // Button text for the file input
+ *   onSuccessText: 'File received successfully!' // Success message displayed after the file is received
+ * });
+ *
+ * // Create an entry to receive text
+ * flottformComponent.createTextItem({
+ *   flottformApi, // URL of the WebRTC signaling server
+ *   createClientUrl: ({ endpointId }) => `/text/${endpointId}`, // URL of the client page for sending text
+ *   label: 'Enter your message', // Label for the text input
+ *   buttonLabel: 'Send Message', // Button text for the text input
+ *   onErrorText: (error) => `Failed to receive text: ${error.message}` // Error message if text transfer fails
+ * });
+ *
+ * // Retrieve all Flottform items in the UI (file and text entries)
+ * const allItems = flottformComponent.getAllFlottformItems();
+ */
 export const createDefaultFlottformComponent = ({
 	flottformAnchorElement,
+	// @ts-ignore: Unused variable
 	id,
 	flottformRootElement,
 	additionalComponentClass,
@@ -74,6 +132,11 @@ export const createDefaultFlottformComponent = ({
 	flottformAnchorElement.appendChild(flottformRoot);
 	return {
 		flottformRoot,
+		/**
+		 * Retrieves all existing Flottform items (both file and text entries) in the UI.
+		 *
+		 * @returns {NodeListOf<Element> | null} - A NodeList of Flottform input items (file and text entries), or `null` if no items are found.
+		 */
 		getAllFlottformItems: () => {
 			const flottformInputsList = flottformRoot.querySelector('.flottform-inputs-list');
 			if (!flottformInputsList) {
@@ -82,6 +145,22 @@ export const createDefaultFlottformComponent = ({
 			}
 			return flottformInputsList.childNodes as NodeListOf<Element>;
 		},
+		/**
+		 * Creates a UI entry for receiving a file via WebRTC.
+		 *
+		 * @param {Object} params - Configuration options for the file input entry.
+		 * @param {string} params.flottformApi - URL of the WebRTC signaling server.
+		 * @param {Function} params.createClientUrl - A function that returns the URL where the second peer can upload the file.
+		 * @param {HTMLInputElement} params.inputField - The file input field in the main form where the received file will be displayed or processed.
+		 * @param {string} [params.id] - Optional ID for the file input entry.
+		 * @param {string} [params.additionalItemClasses] - Optional additional CSS classes for styling the file input entry.
+		 * @param {string} [params.label] - Optional label text for the file input entry.
+		 * @param {string} [params.buttonLabel] - Optional text for the button that triggers the file reception.
+		 * @param {string | Function} [params.onErrorText] - Optional error message displayed if the file transfer fails.
+		 * @param {string} [params.onSuccessText] - Optional success message displayed after the file is successfully received.
+		 *
+		 * @returns {void}
+		 */
 		createFileItem: ({
 			flottformApi,
 			createClientUrl,
@@ -137,6 +216,21 @@ export const createDefaultFlottformComponent = ({
 				onSuccessText
 			});
 		},
+		/**
+		 * Creates a UI entry for receiving text via WebRTC.
+		 *
+		 * @param {Object} params - Configuration options for the text input entry.
+		 * @param {string} params.flottformApi - URL of the WebRTC signaling server.
+		 * @param {Function} params.createClientUrl - A function that returns the URL where the second peer can send the text.
+		 * @param {string} [params.id] - Optional ID for the text input entry.
+		 * @param {string} [params.additionalItemClasses] - Optional additional CSS classes for styling the text input entry.
+		 * @param {string} [params.label] - Optional label text for the text input entry.
+		 * @param {string} [params.buttonLabel] - Optional text for the button that triggers the text reception.
+		 * @param {string | Function} [params.onErrorText] - Optional error message displayed if the text transfer fails.
+		 * @param {string} [params.onSuccessText] - Optional success message displayed after the text is successfully received.
+		 *
+		 * @returns {void}
+		 */
 		createTextItem: ({
 			flottformApi,
 			createClientUrl,
@@ -227,7 +321,9 @@ const createBaseFlottformItems = <L extends BaseListeners>({
 	});
 	flottformBaseInputHost.on('error', (error) => {
 		statusInformation.innerHTML =
-			typeof onErrorText === "function" ? onErrorText(error) : (onErrorText ?? `🚨 An error occured (${error.message}). Please try again`);
+			typeof onErrorText === 'function'
+				? onErrorText(error)
+				: onErrorText ?? `🚨 An error occured (${error.message}). Please try again`;
 		createChannelButton.innerText = 'Retry';
 		flottformStateItemsContainer.replaceChildren(statusInformation);
 		flottformStateItemsContainer.appendChild(createChannelButton);

flottform/forms/src/flottform-channel-client.ts

@@ -21,7 +21,26 @@ type Listeners = {
 	error: [e: string];
 	bufferedamountlow: [];
 };
-
+/**
+ * A class used to represent one peer (called client) to establish a WebRTC connection with another peer (called host).
+ * It handles ICE candidate gathering and sending/receiving data.
+ * The connection is initiated only when `start` method is called.
+ *
+ * This class emits various events during the connection lifecycle, such as `connected`, `disconnected`, and `error`, allowing you to respond to changes in the connection state.
+ *
+ * @fires init - Emitted when the client is initialized.
+ * @fires retrieving-info-from-endpoint - Emitted when information is being retrieved from the endpoint.
+ * @fires sending-client-info - Emitted when client information is being sent to the host.
+ * @fires connecting-to-host - Emitted when attempting to connect to the host.
+ * @fires connected - Emitted when the connection is successfully established.
+ * @fires connection-impossible - Emitted if the connection to the host cannot be established.
+ * @fires done - Emitted when the all of the data is received.
+ * @fires disconnected - Emitted when the connection is closed.
+ * @fires error - Emitted when there is an error during the connection.
+ * @fires bufferedamountlow - Emitted when the buffered amount for data channels is low.
+ *
+ * @extends EventEmitter
+ */
 export class FlottformChannelClient extends EventEmitter<Listeners> {
 	private flottformApi: string;
 	private endpointId: string;
@@ -34,7 +53,17 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 	private dataChannel: RTCDataChannel | null = null;
 	private pollForIceTimer: NodeJS.Timeout | number | null = null;
 	private BUFFER_THRESHOLD = 128 * 1024; // 128KB buffer threshold (maximum of 4 chunks in the buffer waiting to be sent over the network)
-
+	/**
+	 * Creates an instance of FlottformChannelClient
+	 *
+	 * @param {Object} config - The configuration for setting up the channel for the host.
+	 *
+	 * @param {endpointId} - The unique identifier of the endpoint to connect to.
+	 * @param {flottformApi} - The API endpoint for retrieving connection information.
+	 * @param {rtcConfiguration} - Optional RTC configuration for WebRTC connection.
+	 * @param {pollTimeForIceInMs} - Optional time in milliseconds for polling ICE candidates.
+	 * @param {logger} - Optional logger for logging connection events (default: `console`).
+	 */
 	constructor({
 		endpointId,
 		flottformApi,
@@ -62,6 +91,10 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 		this.logger.info(`**Client State changed to: ${newState}`, details == undefined ? '' : details);
 	};
 
+	/**
+	 * Starts the WebRTC connection process. The connection is not established until this method is called.
+	 *
+	 */
 	start = async () => {
 		if (this.openPeerConnection) {
 			this.close();
@@ -102,6 +135,11 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 		this.startPollingForIceCandidates(getEndpointInfoUrl);
 	};
 
+	/**
+	 * Closes the WebRTC connection if it is currently established.
+	 *
+	 * @fires disconnected - Emitted when the connection is successfully closed.
+	 */
 	close = () => {
 		if (this.openPeerConnection) {
 			this.openPeerConnection.close();
@@ -110,6 +148,12 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 		this.changeState('disconnected');
 	};
 
+	/**
+	 * Sends data to the connected peer via the WebRTC data channel.
+	 *
+	 * @param data - The data to send to the peer.
+	 * @fires error - Emits the state error if the connection is not established.
+	 */
 	sendData = (data: any) => {
 		if (this.dataChannel == null) {
 			this.changeState('error', 'dataChannel is null. Unable to send the file to the Host!');
@@ -121,6 +165,11 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 		this.dataChannel.send(data);
 	};
 
+	/**
+	 * Determines if more data can be sent based on the WebRTC data channel's buffered amount. This is useful when dealing with large amounts of data.
+	 *
+	 * @returns `true` if more data can be sent, otherwise `false`.
+	 */
 	canSendMoreData = () => {
 		return (
 			this.dataChannel &&
@@ -154,13 +203,15 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 				}
 			}
 		};
+		// @ts-ignore: Unused variable
 		this.openPeerConnection.onicegatheringstatechange = async (e) => {
 			this.logger.info(`onicegatheringstatechange - ${this.openPeerConnection!.iceGatheringState}`);
 		};
 		this.openPeerConnection.onicecandidateerror = (e) => {
 			this.logger.error(`onicecandidateerror - ${this.openPeerConnection!.connectionState}`, e);
 		};
 	};
+
 	private setUpConnectionStateGathering = (getEndpointInfoUrl: string) => {
 		if (this.openPeerConnection === null) {
 			this.changeState(
@@ -187,7 +238,7 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 				}
 			}
 		};
-
+		// @ts-ignore: Unused variable
 		this.openPeerConnection.oniceconnectionstatechange = (e) => {
 			this.logger.info(
 				`oniceconnectionstatechange - ${this.openPeerConnection!.iceConnectionState}`
@@ -198,12 +249,14 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 			}
 		};
 	};
+
 	private stopPollingForIceCandidates = async () => {
 		if (this.pollForIceTimer) {
 			clearTimeout(this.pollForIceTimer);
 		}
 		this.pollForIceTimer = null;
 	};
+
 	private startPollingForIceCandidates = async (getEndpointInfoUrl: string) => {
 		if (this.pollForIceTimer) {
 			clearTimeout(this.pollForIceTimer);
@@ -213,6 +266,7 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 
 		this.pollForIceTimer = setTimeout(this.startPollingForIceCandidates, this.pollTimeForIceInMs);
 	};
+
 	private pollForConnection = async (getEndpointInfoUrl: string) => {
 		if (this.openPeerConnection === null) {
 			this.changeState('error', "openPeerConnection is null. Unable to retrieve Host's details");
@@ -225,6 +279,7 @@ export class FlottformChannelClient extends EventEmitter<Listeners> {
 			await this.openPeerConnection.addIceCandidate(iceCandidate);
 		}
 	};
+
 	private putClientInfo = async (
 		putClientInfoUrl: string,
 		clientKey: string,

flottform/forms/src/flottform-channel-host.ts

@@ -7,7 +7,26 @@ import {
 	retrieveEndpointInfo,
 	setIncludes
 } from './internal';
-
+/**
+ * A class used to represent one peer (called client) to establish a WebRTC connection with another peer (called host).
+ * It handles ICE candidate gathering and sending/receiving data.
+ * The connection is initiated only when `start` method is called.
+ *
+ * This class emits various events throughout the connection lifecycle such as `connected`, `disconnected`, and `error`, allowing you to respond to the connection state changes.
+ *
+ * @fires new - Emitted when the host is created and ready to accept clients.
+ * @fires waiting-for-client - Emitted when waiting for a client to connect.
+ * @fires waiting-for-data - Emitted when the host is ready to receive data.
+ * @fires waiting-for-ice - Emitted when ICE candidates are being gathered.
+ * @fires receiving-data - Emitted when the host is receiving data from the client.
+ * @fires file-received - Emitted when a complete file has been received.
+ * @fires done - Emitted when the transfer is complete.
+ * @fires error - Emitted when an error occurs during connection or data transfer.
+ * @fires connected - Emitted when the host successfully connects to a client.
+ * @fires disconnected - Emitted when the connection is closed.
+ *
+ * @extends EventEmitter
+ */
 export class FlottformChannelHost extends EventEmitter<FlottformEventMap> {
 	private flottformApi: string | URL;
 	private createClientUrl: (params: { endpointId: string }) => Promise<string>;
@@ -21,6 +40,16 @@ export class FlottformChannelHost extends EventEmitter<FlottformEventMap> {
 	private dataChannel: RTCDataChannel | null = null;
 	private pollForIceTimer: NodeJS.Timeout | number | null = null;
 
+	/**
+	 * Creates an instance of FlottformChannelHost
+	 *
+	 * @param {Object} config - The configuration for setting up the channel for the host.
+	 * @param {flottformApi} - The API endpoint for retrieving connection information.
+	 * @param {createClientUrl} - A function that generates the client URL given an endpoint ID.
+	 * @param {rtcConfiguration} - The RTC configuration for the WebRTC connection.
+	 * @param {pollTimeForIceInMs} - The time interval (in ms) for polling ICE candidates.
+	 * @param {logger} - Optional logger for logging connection events.
+	 */
 	constructor({
 		flottformApi,
 		createClientUrl,
@@ -51,6 +80,9 @@ export class FlottformChannelHost extends EventEmitter<FlottformEventMap> {
 		this.logger.info(`State changed to: ${newState}`, details == undefined ? '' : details);
 	};
 
+	/**
+	 * Starts the WebRTC connection process for the host. The connection is not established until this method is called.
+	 */
 	start = async () => {
 		if (this.openPeerConnection) {
 			this.close();
@@ -92,6 +124,11 @@ export class FlottformChannelHost extends EventEmitter<FlottformEventMap> {
 		this.setupDataChannelListener();
 	};
 
+	/**
+	 * Closes the WebRTC connection if it is currently established.
+	 *
+	 * @fires disconnected - Emitted when the connection is successfully closed.
+	 */
 	close = () => {
 		if (this.openPeerConnection) {
 			this.openPeerConnection.close();
@@ -243,12 +280,12 @@ export class FlottformChannelHost extends EventEmitter<FlottformEventMap> {
 			this.changeState('error', 'dataChannel is null. Unable to setup a Data Channel');
 			return;
 		}
-
+		// @ts-ignore: Unused variable
 		this.dataChannel.onopen = (e) => {
 			this.logger.log('data channel opened');
 			this.changeState('waiting-for-data');
 		};
-
+		// @ts-ignore: Unused variable
 		this.dataChannel.onclose = (e) => {
 			this.logger.log('data channel closed');
 		};