Added comments to 15 functions across 7 files

apps/vanilla/main.js

@@ -4,6 +4,10 @@ import { config } from './config'
 import { listener } from './listener'
 
 const overrideLanguageSelect = document.getElementById('override-language')
+/**
+ * @description Sets the `localStorage` item `overrideLanguage` to the selected value
+ * from the `overrideLanguageSelect` dropdown.
+ */
 overrideLanguageSelect.addEventListener('change', () => {
   localStorage.setItem('overrideLanguage', overrideLanguageSelect.value)
 })
@@ -87,12 +91,24 @@ const BASE_OPTIONS = {
   namespace: 'my-namespace',
 }
 // ---Create a new Space + Workbook and load an iFrame
+/**
+ * @description Initializes a Flatfile space using options passed as argument and
+ * logs the created space to the console.
+ * 
+ * @param {string} publishableKey - 256-bit long, base64-encoded ID of the Spacy
+ * model's publisher and is used to configure the Flatfile close space operation.
+ */
 window.initializeFlatfile = async (publishableKey) => {
   const flatfileOptions = {
     ...BASE_OPTIONS,
     publishableKey,
     closeSpace: {
       operation: 'submitActionFg',
+      /**
+       * @description Logs a space event payload to the console using JSON.stringify.
+       * 
+       * @param {string} event - payload of an event to be logged.
+       */
       onClose: (event) => {
         console.log(
           `Close space event payload: ${JSON.stringify(event, null, 2)}`
@@ -106,6 +122,10 @@ window.initializeFlatfile = async (publishableKey) => {
 }
 
 // ---Pre-load iFrame by specific mountID for faster initial load-time
+/**
+ * @description Preloads a flatfile container and mounts it to the provided element,
+ * providing an option to close the space when closed.
+ */
 window.preloadFlatfile = () => {
   createIframe('Flatfile_Preload_Iframe', true)
   window.initializePreloadedFlatfile = async (publishableKey) => {
@@ -115,6 +135,11 @@ window.preloadFlatfile = () => {
       mountElement: 'Flatfile_Preload_Iframe',
       closeSpace: {
         operation: 'submitActionFg',
+        /**
+         * @description Logs the payload of a close space event to the console using `console.log()`.
+         * 
+         * @param {string} event - payload of an event that is being logged through the function.
+         */
         onClose: (event) => {
           console.log(
             `Close space event payload: ${JSON.stringify(event, null, 2)}`

packages/javascript/rollup.config.js

@@ -23,6 +23,17 @@ const external = [
 ]
 
 // Common plugins function
+/**
+ * @description Generates a configuration for plugins to be used in a bundling process,
+ * including JSON, peer dependencies, resolution, sourcemaps, commonJS, CSS, and URL
+ * manipulation, with optional Terser optimization.
+ * 
+ * @param {true} umd - 16-digit code object that, when passed to the function,
+ * configures the plugin generation for UMD bundles.
+ * 
+ * @returns {array} an array of seven plugins used for various purposes such as
+ * Typescript transformation, CSS compression, and file naming.
+ */
 function commonPlugins(umd = true) {
   return [
     json(),

packages/javascript/src/i18n.ts

@@ -85,6 +85,22 @@ const localTranslations: Record<SupportedLanguage, Translations | any> = {
   zh: localZh,
 }
 
+/**
+ * @description Sets up an instance of i18n, configuring the language detection and
+ * interpolation, and adds translation resources for given localizations.
+ * 
+ * @param {string} languageOverride - language to be used as the fallback language
+ * if no translation is found for a given key, and it can be used to specify a custom
+ * language for the initial load of i18n.
+ * 
+ * @returns {i18n` instance} an initialized `i18n` object with a handler for missing
+ * keys and added resource bundles.
+ * 
+ * 	* `loggedMissingKeys`: a set of missing keys that were encountered during the
+ * initialization process, indicating potential issues with the input data.
+ * 	* `i18n`: the initialized i18n instance, which provides access to various functions
+ * and methods for managing translations and other linguistic assets.
+ */
 export const getI18n = (languageOverride?: string) => {
   const loggedMissingKeys = new Set<string>()
 
@@ -96,6 +112,21 @@ export const getI18n = (languageOverride?: string) => {
       escapeValue: false,
     },
     saveMissing: true, //required for missing key handler
+    /**
+     * @description Checks that the provided `key` is not a regular string, file path,
+     * or empty value, and logs an error message to console if it's missing.
+     * 
+     * @param {readonly string[]} lng - readonly string array of translations to check
+     * for validity.
+     * 
+     * @param {string} ns - name of the namespace in which the key is being searched for.
+     * 
+     * @param {string} key - translation key for which the fallback value should be
+     * provided if it is not found in the given language.
+     * 
+     * @param {any} fallbackValue - value that is returned if the specified key is not
+     * found in the provided data or if there is an error during the i18n process.
+     */
     missingKeyHandler: (
       lng: readonly string[],
       ns: string,
@@ -128,6 +159,16 @@ export const getI18n = (languageOverride?: string) => {
   return i18n
 }
 
+/**
+ * @description Takes a string argument `str`, which it then checks if the given file
+ * name adheres to a specified pattern `extensionsPattern`. If it does, the function
+ * returns `true`. Otherwise, it returns `false`.
+ * 
+ * @param {string} str - input string to be tested against the file extension pattern.
+ * 
+ * @returns {boolean} a boolean indicating whether the given string represents a valid
+ * translation file name.
+ */
 const isTranslationFileName = (str: string) => {
   const extensionsPattern = ['json'].join('|')
   const filenameRegex = new RegExp(

packages/javascript/src/initNewSpace.ts

@@ -55,12 +55,29 @@ export const initNewSpace = async ({
     },
   }
 
+  /**
+   * @description Updates the `spaceRequestBody` object by adding a new key-value pair,
+   * where the key is the specified `resourceName`, and the value is the given `resource`.
+   * 
+   * @param {any} resource - specific resource for which the documentation is being generated.
+   * 
+   * @param {string} resourceName - name of the resource that is being updated or added
+   * to the space.
+   */
   const addResourceToRequestBody = (resource: any, resourceName: string) => {
     spaceRequestBody = {
       ...spaceRequestBody,
       [resourceName]: resource,
     }
   }
+  /**
+   * @description Updates a setting within an application, modifying its behavior
+   * according to input values. It warns against defining multiple default pages when
+   * setting one and stores the new default page value for future references.
+   * 
+   * @param {DefaultPageType} incomingDefaultPage - default page that is passed to the
+   * function when no default page has been previously set.
+   */
   const setDefaultPage = (incomingDefaultPage: DefaultPageType) => {
     if (defaultPageSet === true) {
       console.warn(

packages/javascript/src/listener.ts

@@ -44,6 +44,47 @@ export async function createlistener(
   }
 }
 
+/**
+ * @description Creates a Flatfile listener that listens for simple submit actions
+ * and invokes the `onSubmit` function with the workbook ID, sheet ID, and submit
+ * event data.
+ * 
+ * @param {SimpleListenerType} .onRecordHook - a callback function that is triggered
+ * for each record that is processed by the Flatfile listener, providing an opportunity
+ * to perform custom operations or modifications on the records before they are saved
+ * to the target system.
+ * 
+ * @param {SimpleListenerType} .onSubmit - function that will be called once the
+ * workbook has been successfully submitted, and it takes as its argument an object
+ * representing the result of the `DefaultSubmitSettings` merging with any custom
+ * `submitSettings` provided.
+ * 
+ * @param {SimpleListenerType} .slug - ID of a Flatfile space, which is used to
+ * identify the specific space for which the listener is created and configured to
+ * handle events related to that space.
+ * 
+ * @param {SimpleListenerType} .submitSettings - submision settings for the job, which
+ * are used to customize the submission process based on specific requirements.
+ * 
+ * @returns {FlatfileClient} a Flatfile listener that listens for events related to
+ * simple submissions and performs the specified actions.
+ * 
+ * 	* `client`: An instance of `FlatfileClient` that provides an interface for
+ * interacting with Flatfile API.
+ * 	* `recordHook`: A function that can be used to modify the behavior of the listener
+ * by passing a record and event as arguments, which can be used to perform any actions
+ * desired before or after the record is processed.
+ * 	* `onSubmitSettings`: An object that contains configuration options for handling
+ * the `workbook:simpleSubmitAction` event, such as deleting the space after submission.
+ * 
+ * 	The `client` property is an instance of `FlatfileClient`, which is a class that
+ * provides methods for interacting with the Flatfile API. The `recordHook` property
+ * is a function that can be used to modify the behavior of the listener by passing
+ * a record and event as arguments, which can be used to perform any actions desired
+ * before or after the record is processed. Finally, the `onSubmitSettings` property
+ * is an object that contains configuration options for handling the `workbook:simpleSubmitAction`
+ * event, such as deleting the space after submission.
+ */
 export const createSimpleListener = ({
   onRecordHook,
   onSubmit,

packages/javascript/src/startFlatfile.ts

@@ -9,6 +9,22 @@ import { initNewSpace } from './initNewSpace'
 import { createSimpleListener, createlistener } from './listener'
 import { displayError, initializeIFrameConfirmationModal } from './utils'
 
+/**
+ * @description Initialization for Flat File. It creates an iframe with the embedded
+ * Flat File application and hydrates it with response from initial resources API.
+ * It also listens to message events, and on-demand creation of new spaces and documents
+ * is supported.
+ * 
+ * @param {SimpleOnboarding | ISpace} options - 3-part data object that provides
+ * information required for initiating an import session in FlatFile, and includes
+ * values such as publishable key, space ID, display modal, API URL, and more.
+ * 
+ * @returns {object} an object containing the space ID.
+ */
+/**
+ * @description Clears up space-related DOM components and removes listeners for
+ * message events.
+ */
 export async function startFlatfile(options: SimpleOnboarding | ISpace) {
   function closeSpaceNow() {
     removeMessageListener?.()

packages/javascript/src/utils.ts

@@ -1,6 +1,31 @@
 import { ISpace } from '@flatfile/embedded-utils'
 import { createModal } from './createModal'
 
+/**
+ * @description Creates a HTML div element to display an error message, and adds
+ * headings and paragraphs with respective class names to represent the error title
+ * and text.
+ * 
+ * @param {string} errorTitle - HTML element to which the error message should be
+ * displayed as a heading.
+ * 
+ * @param {string} errorMessage - message to be displayed below the error title in
+ * the HTML element created by the function.
+ * 
+ * @returns {HTML division element} a HTML div element containing a heading and a
+ * paragraph of text.
+ * 
+ * 	* `div`: This is a `div` element that is created using `document.createElement()`.
+ * It has the class `ff_error_container`.
+ * 	* `h1`: This is an `h1` element that is created using `document.createElement()`.
+ * It has the class `ff_error_heading`.
+ * 	* `p`: This is a `p` element that is created using `document.createElement()`.
+ * It has the class `ff_error_text`.
+ * 	* `title`: This is an `h1` element that contains the title of the error message.
+ * It has the class `ff_error_heading`.
+ * 	* `error`: This is a `p` element that contains the error message itself. It has
+ * the class `ff_error_text`.
+ */
 export const displayError = (errorTitle: string, errorMessage: string) => {
   const display = document.createElement('div')
   display.classList.add('ff_error_container')