From e8aacfe94ed761815d6bcfa01bfa02a6aedebaf6 Mon Sep 17 00:00:00 2001
From: Nate Ferrero <nate@tagme.in>
Date: Wed, 3 Jul 2024 00:35:19 -0400
Subject: [PATCH 1/3] feat(javascript): add i18n to wrapper

---
 .changeset/sharp-pears-teach.md               |   5 +
 apps/vanilla/config.js                        |  10 +
 apps/vanilla/index.html                       |  24 +
 apps/vanilla/main.js                          |  11 +
 package-lock.json                             |  48 +-
 packages/javascript/FlatfileJavascript.ts     | 539 ------------------
 packages/javascript/index.ts                  |  12 +-
 packages/javascript/package.json              |   6 +-
 packages/javascript/rollup.config.js          |  11 +-
 packages/javascript/src/i18n.ts               | 138 +++++
 packages/javascript/src/initNewSpace.ts       | 118 ++++
 packages/javascript/src/listener.ts           |  99 ++++
 .../src/locales/de/translation.json           |   9 +
 .../src/locales/en-CA/translation.json        |   9 +
 .../src/locales/en-GB/translation.json        |   9 +
 .../src/locales/en-ZA/translation.json        |   9 +
 .../src/locales/en/translation.json           |   9 +
 .../src/locales/es/translation.json           |   9 +
 .../src/locales/fr-CA/translation.json        |   9 +
 .../src/locales/fr-Fr/translation.json        |   9 +
 .../src/locales/fr/translation.json           |   9 +
 .../src/locales/id/translation.json           |   9 +
 .../src/locales/it/translation.json           |   9 +
 .../src/locales/jp/translation.json           |   9 +
 .../src/locales/kr/translation.json           |   9 +
 .../src/locales/pt-BR/translation.json        |   9 +
 .../src/locales/pt/translation.json           |   9 +
 .../src/locales/tr/translation.json           |   9 +
 .../src/locales/vi/translation.json           |   9 +
 .../src/locales/zh/translation.json           |   9 +
 packages/javascript/src/startFlatfile.ts      | 220 +++++++
 .../src/types/InitialResourceData.ts          |  13 +
 packages/javascript/src/types/index.ts        |  15 +
 packages/javascript/src/utils.ts              | 109 ++++
 packages/javascript/tsconfig.json             |  25 +-
 35 files changed, 988 insertions(+), 577 deletions(-)
 create mode 100644 .changeset/sharp-pears-teach.md
 delete mode 100644 packages/javascript/FlatfileJavascript.ts
 create mode 100644 packages/javascript/src/i18n.ts
 create mode 100644 packages/javascript/src/initNewSpace.ts
 create mode 100644 packages/javascript/src/listener.ts
 create mode 100644 packages/javascript/src/locales/de/translation.json
 create mode 100644 packages/javascript/src/locales/en-CA/translation.json
 create mode 100644 packages/javascript/src/locales/en-GB/translation.json
 create mode 100644 packages/javascript/src/locales/en-ZA/translation.json
 create mode 100644 packages/javascript/src/locales/en/translation.json
 create mode 100644 packages/javascript/src/locales/es/translation.json
 create mode 100644 packages/javascript/src/locales/fr-CA/translation.json
 create mode 100644 packages/javascript/src/locales/fr-Fr/translation.json
 create mode 100644 packages/javascript/src/locales/fr/translation.json
 create mode 100644 packages/javascript/src/locales/id/translation.json
 create mode 100644 packages/javascript/src/locales/it/translation.json
 create mode 100644 packages/javascript/src/locales/jp/translation.json
 create mode 100644 packages/javascript/src/locales/kr/translation.json
 create mode 100644 packages/javascript/src/locales/pt-BR/translation.json
 create mode 100644 packages/javascript/src/locales/pt/translation.json
 create mode 100644 packages/javascript/src/locales/tr/translation.json
 create mode 100644 packages/javascript/src/locales/vi/translation.json
 create mode 100644 packages/javascript/src/locales/zh/translation.json
 create mode 100644 packages/javascript/src/startFlatfile.ts
 create mode 100644 packages/javascript/src/types/InitialResourceData.ts
 create mode 100644 packages/javascript/src/utils.ts

diff --git a/.changeset/sharp-pears-teach.md b/.changeset/sharp-pears-teach.md
new file mode 100644
index 00000000..8bc736cf
--- /dev/null
+++ b/.changeset/sharp-pears-teach.md
@@ -0,0 +1,5 @@
+---
+'@flatfile/javascript': minor
+---
+
+Add internationalization support with detected browser language or given override language.
diff --git a/apps/vanilla/config.js b/apps/vanilla/config.js
index c6d348e5..c86dc1e8 100644
--- a/apps/vanilla/config.js
+++ b/apps/vanilla/config.js
@@ -3,6 +3,16 @@ export const config = {
   labels: ['pinned'],
   sheets: [
     {
+      actions: [
+        {
+          operation: 'customAction',
+          mode: 'foreground',
+          label: 'Custom Action',
+          icon: 'none',
+          description: 'Do something custom',
+          primary: true,
+        },
+      ],
       name: 'Contacts',
       slug: 'contacts',
       allowAdditionalFields: true,
diff --git a/apps/vanilla/index.html b/apps/vanilla/index.html
index 26047769..409300d3 100644
--- a/apps/vanilla/index.html
+++ b/apps/vanilla/index.html
@@ -15,6 +15,30 @@
     <button onclick="initializeFlatfile('pk_123456')">
       Open "On Demand" Flatfile
     </button>
+
+    <label>Override language:</label>
+    <select id="override-language">
+      <option selected value=""></option>
+      <option value="de">de</option>
+      <option value="en">en</option>
+      <option value="en-GB">en-GB</option>
+      <option value="en-CA">en-CA</option>
+      <option value="en-ZA">en-ZA</option>
+      <option value="es">es</option>
+      <option value="fr">fr</option>
+      <option value="fr-CA">fr-CA</option>
+      <option value="fr-FR">fr-FR</option>
+      <option value="id">id</option>
+      <option value="it">it</option>
+      <option value="jp">jp</option>
+      <option value="kr">kr</option>
+      <option value="pt">pt</option>
+      <option value="pt-BR">pt-BR</option>
+      <option value="tr">tr</option>
+      <option value="vi">vi</option>
+      <option value="zh">zh</option>
+    </select>
+
     <script>
       window.addEventListener('load', (event) => {
         preloadFlatfile()
diff --git a/apps/vanilla/main.js b/apps/vanilla/main.js
index c0138573..f5d30376 100644
--- a/apps/vanilla/main.js
+++ b/apps/vanilla/main.js
@@ -2,6 +2,16 @@ import { createIframe, initializeFlatfile } from '@flatfile/javascript'
 
 import { config } from './config'
 import { listener } from './listener'
+
+const overrideLanguageSelect = document.getElementById('override-language')
+overrideLanguageSelect.addEventListener('change', () => {
+  localStorage.setItem('overrideLanguage', overrideLanguageSelect.value)
+})
+const overrideLanguage = localStorage.getItem('overrideLanguage')
+if (overrideLanguage) {
+  overrideLanguageSelect.value = overrideLanguage
+}
+
 /*
 // ---Get a space to reuse it, load automatically
 const flatfile = new FlatfileClient({
@@ -33,6 +43,7 @@ getSpace()
 */
 
 const BASE_OPTIONS = {
+  languageOverride: overrideLanguageSelect.value,
   spaceBody: { name: 'Hello' },
   // listener,
   // Additional parameters...
diff --git a/package-lock.json b/package-lock.json
index 614a6c0f..824df3d2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16125,6 +16125,36 @@
         "ms": "^2.0.0"
       }
     },
+    "node_modules/i18next": {
+      "version": "23.11.5",
+      "resolved": "https://registry.npmjs.org/i18next/-/i18next-23.11.5.tgz",
+      "integrity": "sha512-41pvpVbW9rhZPk5xjCX2TPJi2861LEig/YRhUkY+1FQ2IQPS0bKUDYnEqY8XPPbB48h1uIwLnP9iiEfuSl20CA==",
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://locize.com"
+        },
+        {
+          "type": "individual",
+          "url": "https://locize.com/i18next.html"
+        },
+        {
+          "type": "individual",
+          "url": "https://www.i18next.com/how-to/faq#i18next-is-awesome.-how-can-i-support-the-project"
+        }
+      ],
+      "dependencies": {
+        "@babel/runtime": "^7.23.2"
+      }
+    },
+    "node_modules/i18next-browser-languagedetector": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/i18next-browser-languagedetector/-/i18next-browser-languagedetector-8.0.0.tgz",
+      "integrity": "sha512-zhXdJXTTCoG39QsrOCiOabnWj2jecouOqbchu3EfhtSHxIB5Uugnm9JaizenOy39h7ne3+fLikIjeW88+rgszw==",
+      "dependencies": {
+        "@babel/runtime": "^7.23.2"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.4.24",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz",
@@ -33306,7 +33336,7 @@
     },
     "packages/embedded-utils": {
       "name": "@flatfile/embedded-utils",
-      "version": "1.2.4",
+      "version": "1.3.0",
       "license": "ISC",
       "dependencies": {
         "@flatfile/api": "^1.8.9",
@@ -33430,16 +33460,18 @@
     },
     "packages/javascript": {
       "name": "@flatfile/javascript",
-      "version": "1.3.7",
+      "version": "1.3.9",
       "license": "ISC",
       "dependencies": {
-        "@flatfile/embedded-utils": "^1.2.4",
+        "@flatfile/embedded-utils": "^1.3.0",
         "@flatfile/listener": "^1.0.4",
-        "@flatfile/plugin-record-hook": "^1.5.2"
+        "@flatfile/plugin-record-hook": "^1.5.2",
+        "i18next": "^23.11.5",
+        "i18next-browser-languagedetector": "^8.0.0"
       },
       "devDependencies": {
         "@rollup/plugin-commonjs": "^25.0.7",
-        "@rollup/plugin-json": "^6.0.1",
+        "@rollup/plugin-json": "^6.1.0",
         "@rollup/plugin-sucrase": "^5.0.2",
         "@rollup/plugin-terser": "^0.4.4",
         "@rollup/plugin-url": "^8.0.2",
@@ -36769,7 +36801,7 @@
     },
     "packages/react": {
       "name": "@flatfile/react",
-      "version": "7.9.9",
+      "version": "7.9.10",
       "license": "ISC",
       "dependencies": {
         "@flatfile/api": "^1.8.5",
@@ -38734,9 +38766,9 @@
     },
     "packages/vue": {
       "name": "@flatfile/vue",
-      "version": "1.0.17",
+      "version": "1.0.18",
       "dependencies": {
-        "@flatfile/embedded-utils": "1.2.4",
+        "@flatfile/embedded-utils": "1.3.0",
         "@flatfile/listener": "^1.0.4",
         "@flatfile/plugin-record-hook": "^1.5.2",
         "@vue/runtime-dom": "^3.3.4",
diff --git a/packages/javascript/FlatfileJavascript.ts b/packages/javascript/FlatfileJavascript.ts
deleted file mode 100644
index 7b472842..00000000
--- a/packages/javascript/FlatfileJavascript.ts
+++ /dev/null
@@ -1,539 +0,0 @@
-import { Flatfile, FlatfileClient } from '@flatfile/api'
-import {
-  DefaultPageType,
-  DefaultSubmitSettings,
-  ISpace,
-  JobHandler,
-  NewSpaceFromPublishableKey,
-  SheetHandler,
-  SimpleOnboarding,
-  createWorkbookFromSheet,
-  handlePostMessage,
-  updateDefaultPageInSpace,
-} from '@flatfile/embedded-utils'
-import { FlatfileRecord } from '@flatfile/hooks'
-import { Browser, FlatfileEvent, FlatfileListener } from '@flatfile/listener'
-import { recordHook } from '@flatfile/plugin-record-hook'
-import { createIframe } from './src/createIframe'
-import { createModal } from './src/createModal'
-
-const displayError = (errorTitle: string, errorMessage: string) => {
-  const display = document.createElement('div')
-  display.classList.add('ff_error_container')
-  const title = document.createElement('h1')
-  title.classList.add('ff_error_heading')
-  const error = document.createElement('p')
-  error.classList.add('ff_error_text')
-
-  title.innerText = errorTitle
-  error.innerText = errorMessage
-
-  display.appendChild(title)
-  display.appendChild(error)
-
-  return display
-}
-
-/**
- * Add a listener to handle postMessage events
- *
- * @param accessToken
- * @param apiUrl
- * @param listener
- * @param closeSpace
- * @param onClose
- * @returns Promise<() => void>
- */
-async function createlistener(
-  accessToken: string,
-  apiUrl: string,
-  listener: FlatfileListener,
-  closeSpace: NewSpaceFromPublishableKey['closeSpace'],
-  onClose: () => void
-): Promise<() => void> {
-  const browser_instance = new Browser({
-    apiUrl,
-    accessToken,
-    fetchApi: fetch,
-  })
-  const ff_message_handler = handlePostMessage(closeSpace, listener, onClose)
-
-  listener.mount(browser_instance)
-  window.addEventListener('message', ff_message_handler, false)
-
-  return () => {
-    window.removeEventListener('message', ff_message_handler)
-    listener.unmount(browser_instance)
-  }
-}
-interface SimpleListenerType
-  extends Pick<
-    SimpleOnboarding,
-    'onRecordHook' | 'onSubmit' | 'submitSettings'
-  > {
-  slug: string
-}
-
-const createSimpleListener = ({
-  onRecordHook,
-  onSubmit,
-  slug,
-  submitSettings,
-}: SimpleListenerType) =>
-  FlatfileListener.create((client: FlatfileListener) => {
-    const api = new FlatfileClient()
-    if (onRecordHook) {
-      client.use(
-        recordHook(
-          slug,
-          async (record: FlatfileRecord, event: FlatfileEvent | undefined) =>
-            onRecordHook(record, event)
-        )
-      )
-    }
-    if (onSubmit) {
-      const onSubmitSettings = { ...DefaultSubmitSettings, ...submitSettings }
-      client.filter({ job: 'workbook:simpleSubmitAction' }, (configure) => {
-        configure.on('job:ready', async (event) => {
-          const { jobId, spaceId, workbookId } = event.context
-          try {
-            await api.jobs.ack(jobId, { info: 'Starting job', progress: 10 })
-
-            const job = new JobHandler(jobId)
-            const { data: workbookSheets } = await api.sheets.list({
-              workbookId,
-            })
-
-            // this assumes we are only allowing 1 sheet here (which we've talked about doing initially)
-            const sheet = new SheetHandler(workbookSheets[0].id)
-
-            await onSubmit({ job, sheet, event })
-
-            await api.jobs.complete(jobId, {
-              outcome: {
-                message: 'complete',
-              },
-            })
-            if (onSubmitSettings.deleteSpaceAfterSubmit) {
-              await api.spaces.archiveSpace(spaceId)
-            }
-          } catch (error: any) {
-            if (jobId) {
-              await api.jobs.cancel(jobId)
-            }
-            console.error('Error:', error.stack)
-          }
-        })
-      })
-    }
-  })
-
-/**
- * Utility function with the responsibility of mounting the confirmation modal and its
- * associate behaviors to the iFrame which is actively being mounted (or was previously preloaded)
- * @param domElement
- * @param displayAsModal
- * @param exitTitle
- * @param exitText
- * @param exitPrimaryButtonText
- * @param exitSecondaryButtonText
- * @param closeSpaceNow
- * @param closeSpace
- * @param onCancel
- */
-function initializeIFrameConfirmationModal(
-  domElement: HTMLElement,
-  displayAsModal: boolean,
-  exitTitle: string,
-  exitText: string,
-  exitPrimaryButtonText: string,
-  exitSecondaryButtonText: string,
-  closeSpaceNow: () => void,
-  closeSpace?: ISpace['closeSpace'],
-  onCancel?: () => void
-) {
-  // Create the confirmation modal and hide it
-  const confirmModal = createModal(
-    () => {
-      // If user chooses to exit
-      const wrappers = Array.from(
-        document.getElementsByClassName('flatfile_iframe-wrapper')
-      ) as HTMLElement[]
-      const modals = Array.from(
-        document.getElementsByClassName('flatfile_outer-shell')
-      ) as HTMLElement[]
-
-      const elements = [...modals]
-
-      for (let item of elements) {
-        document.body.removeChild(item)
-      }
-
-      closeSpaceNow()
-      if (onCancel) {
-        onCancel()
-      }
-      closeSpace?.onClose?.({})
-    },
-    () => {
-      // If user chooses to stay, we simply hide the confirm modal
-      confirmModal.style.display = 'none'
-    },
-    exitTitle, // pass exitTitle here
-    exitText, // pass exitText here,
-    exitPrimaryButtonText,
-    exitSecondaryButtonText
-  )
-  confirmModal.style.display = 'none'
-  document.body.appendChild(confirmModal)
-
-  if (displayAsModal) {
-    const closeButton = document.createElement('div')
-    closeButton.innerHTML = `<svg
-        xmlns="http://www.w3.org/2000/svg"
-        width="24"
-        height="24"
-        viewBox="0 0 100 100"
-      >
-        <line x1="10" y1="10" x2="90" y2="90" stroke="white" stroke-width="10" />
-        <line x1="10" y1="90" x2="90" y2="10" stroke="white" stroke-width="10" />
-      </svg>`
-    closeButton.classList.add('flatfile-close-button')
-    // Add the onclick event to the button
-    closeButton.onclick = () => {
-      const outerShell = document.querySelector(
-        '.flatfile_outer-shell'
-      ) as HTMLElement
-      if (outerShell) {
-        outerShell.style.display = 'block'
-      } else {
-        // Show the confirm modal instead of creating a new one
-        confirmModal.style.display = 'block'
-      }
-    }
-
-    domElement
-      .getElementsByClassName('flatfile_iframe-wrapper')[0]
-      .appendChild(closeButton)
-  }
-}
-
-type InitSpaceType = ISpace & {
-  isAutoConfig: boolean
-}
-
-// TODO: Replace hardcoded type with imported type from Platform
-export interface InitialResourceData {
-  workbooks: Flatfile.Workbook[] | null
-  documents: Flatfile.Document[] | null
-  space: Flatfile.Space
-  actor: Flatfile.User | Flatfile.Guest | undefined
-  entitlements: any[]
-  environment: Partial<Flatfile.Environment> & {
-    hasAccess: boolean
-  }
-}
-
-/**
- * Full-service utility which takes incoming space configuration data and calls the internal backend-for-frontend
- * endpoint to create the space, workbook, and document in a single request.
- *
- * The resulting response is the full set of initial resources needed to render the UI experience
- * @param param0
- * @returns
- */
-const initNewSpace = async ({
-  publishableKey,
-  apiUrl,
-  name,
-  environmentId,
-  spaceBody,
-  namespace = 'portal',
-  translationsPath,
-  languageOverride,
-  themeConfig,
-  sidebarConfig,
-  labels,
-  metadata,
-  userInfo,
-  workbook,
-  document,
-  isAutoConfig,
-}: InitSpaceType): Promise<InitialResourceData> => {
-  const createSpaceEndpoint = `${apiUrl}/v1/internal/spaces/init?publishableKey=${publishableKey}`
-
-  let defaultPage
-  let defaultPageSet = false
-
-  let spaceRequestBody: any = {
-    space: {
-      name: name || 'Embedded Space',
-      ...spaceBody,
-      autoConfigure: isAutoConfig,
-      ...(environmentId ? { environmentId } : {}),
-      labels: ['embedded', ...(labels || [])],
-      ...(namespace ? { namespace } : {}),
-      ...(translationsPath ? { translationsPath } : {}),
-      ...(languageOverride ? { languageOverride } : {}),
-      metadata: {
-        theme: themeConfig,
-        sidebarConfig: sidebarConfig || { showSidebar: false },
-        userInfo,
-        ...(spaceBody?.metadata || {}),
-        ...(metadata || {}),
-      },
-    },
-  }
-
-  const addResourceToRequestBody = (resource: any, resourceName: string) => {
-    spaceRequestBody = {
-      ...spaceRequestBody,
-      [resourceName]: resource,
-    }
-  }
-  const setDefaultPage = (incomingDefaultPage: DefaultPageType) => {
-    if (defaultPageSet === true) {
-      console.warn(
-        'Default page is already set. Multiple default pages are not allowed.'
-      )
-    } else {
-      defaultPage = incomingDefaultPage
-      defaultPageSet = true
-    }
-  }
-
-  if (workbook) {
-    addResourceToRequestBody(workbook, 'workbook')
-
-    if (workbook.defaultPage) {
-      setDefaultPage({ workbook: workbook.name })
-    } else if (workbook.sheets) {
-      const defaultSheet = workbook.sheets.find((sheet) => sheet.defaultPage)
-      if (defaultSheet && defaultSheet.slug) {
-        setDefaultPage({ workbook: { sheet: defaultSheet.slug } })
-      }
-    }
-  }
-
-  if (document) {
-    addResourceToRequestBody(document, 'document')
-
-    if (document.defaultPage) {
-      setDefaultPage({ document: document.title })
-    }
-  }
-
-  const response = await fetch(createSpaceEndpoint, {
-    method: 'POST',
-    headers: {
-      Accept: 'text/plain',
-      'Content-Type': 'text/plain',
-    },
-    body: JSON.stringify(spaceRequestBody),
-  })
-
-  const result = await response.json()
-  if (!response.ok) {
-    const errorMessage = result?.errors[0]?.message || 'Failed to create space'
-    throw new Error(errorMessage)
-  }
-
-  const createdSpace = result.data
-
-  ;(window as any).CROSSENV_FLATFILE_API_KEY = createdSpace.space.accessToken
-
-  if (defaultPage) await updateDefaultPageInSpace(createdSpace, defaultPage)
-
-  return createdSpace
-}
-
-export async function startFlatfile(options: SimpleOnboarding | ISpace) {
-  const {
-    publishableKey,
-    displayAsModal = true,
-    mountElement = 'flatfile_iFrameContainer',
-    space,
-    spaceBody = undefined,
-    apiUrl = 'https://platform.flatfile.com/api',
-    baseUrl = 'https://platform.flatfile.com/s',
-    spaceUrl = 'https://platform.flatfile.com/s',
-    exitTitle = 'Close Window',
-    exitText = 'Are you sure you would like to close this window? This will end your current data import session.',
-    exitPrimaryButtonText = 'Yes, exit',
-    exitSecondaryButtonText = 'No, stay',
-    closeSpace,
-    errorTitle = 'Something went wrong',
-    name,
-    environmentId,
-    workbook,
-    themeConfig,
-    document: documentConfig,
-    sidebarConfig,
-    userInfo,
-    listener,
-    namespace,
-    metadata,
-    labels,
-    translationsPath,
-    languageOverride,
-  } = options
-  const simpleOnboardingOptions = options as SimpleOnboarding
-  const isReusingSpace = !!(space?.id && space?.accessToken)
-  const spacesUrl = spaceUrl || baseUrl
-  let mountIFrameWrapper = document.getElementById(mountElement)
-  const mountIFrameElement = mountIFrameWrapper
-    ? mountIFrameWrapper.getElementsByTagName('iframe')[0]
-    : null
-  ;(window as any).CROSSENV_FLATFILE_API_URL = apiUrl
-  /**
-   * Customers can proactively preload the iFrame into the DOM - If we detect that an iFrame already exists
-   * for the provided mountElementId - we can assume it has been preloaded, and simply make it visible
-   **/
-  if (mountIFrameWrapper && mountIFrameElement) {
-    mountIFrameWrapper.style.display = 'block'
-  }
-
-  try {
-    let spaceResult: any
-    let initialResourceResponse
-    let createdWorkbook = workbook
-    let isAutoConfig = false
-
-    if (!createdWorkbook) {
-      if (!simpleOnboardingOptions.sheet) {
-        isAutoConfig = true
-      } else {
-        createdWorkbook = createWorkbookFromSheet(
-          simpleOnboardingOptions.sheet,
-          !!simpleOnboardingOptions.onSubmit
-        )
-      }
-    }
-
-    if (isReusingSpace) {
-      spaceResult = space
-      ;(window as any).CROSSENV_FLATFILE_API_KEY = spaceResult?.accessToken
-    }
-    // Initialize new space / workbook / document and obtain response used to "initial resources" to hydrate embedded UI
-    else if (publishableKey) {
-      initialResourceResponse = await initNewSpace({
-        publishableKey,
-        apiUrl,
-        name,
-        spaceBody,
-        namespace,
-        environmentId,
-        translationsPath,
-        languageOverride,
-        themeConfig,
-        sidebarConfig,
-        labels,
-        metadata,
-        userInfo,
-        workbook: createdWorkbook,
-        document: documentConfig,
-        isAutoConfig,
-      })
-
-      spaceResult = initialResourceResponse.space
-    }
-
-    if (!spaceResult?.id || !spaceResult?.accessToken) {
-      throw new Error('Unable to create space, please try again.')
-    }
-    // Set these for handy use in the listeners for authenticating the @flatfile/api client
-
-    let removeMessageListener: (() => void) | undefined
-
-    const simpleListenerSlug: string =
-      createdWorkbook?.sheets?.[0].slug || 'slug'
-
-    function closeSpaceNow() {
-      removeMessageListener?.()
-      document.querySelector('.flatfile_outer-shell')?.remove?.()
-      mountIFrameWrapper?.remove?.()
-    }
-
-    if (listener) {
-      removeMessageListener = await createlistener(
-        spaceResult.accessToken,
-        apiUrl,
-        listener,
-        closeSpace,
-        closeSpaceNow
-      )
-    } else {
-      removeMessageListener = await createlistener(
-        spaceResult.accessToken,
-        apiUrl,
-        createSimpleListener({
-          onRecordHook: simpleOnboardingOptions?.onRecordHook,
-          onSubmit: simpleOnboardingOptions?.onSubmit,
-          slug: simpleListenerSlug,
-        }),
-        closeSpace,
-        closeSpaceNow
-      )
-    }
-
-    /**
-     * Customers can proactively preload the iFrame into the DOM - If we detect that an iFrame already exists
-     * for the provided mountElementId then we pass a message to direct the iFrame to the spaces-UI route for
-     * the created spaceId
-     *
-     * If it has not been created yet, the iFrame is created on-demand, and routed to the specified space-id
-     **/
-    if (!mountIFrameElement) {
-      mountIFrameWrapper = createIframe(
-        mountElement,
-        displayAsModal,
-        spaceResult.id,
-        spaceResult.accessToken,
-        spaceResult?.guestLink ?? spacesUrl,
-        isReusingSpace
-      )
-    } else {
-      const targetOrigin = new URL(spacesUrl).origin
-      const initialResources = initialResourceResponse || null
-      console.log({ initialResources })
-      mountIFrameElement.contentWindow?.postMessage(
-        {
-          flatfileEvent: {
-            topic: 'portal:initialize',
-            payload: {
-              status: 'complete',
-              spaceUrl: `${targetOrigin}/space/${
-                spaceResult.id
-              }?token=${encodeURIComponent(spaceResult.accessToken)}`,
-              initialResources,
-            },
-          },
-        },
-        targetOrigin
-      )
-    }
-
-    if (mountIFrameWrapper) {
-      initializeIFrameConfirmationModal(
-        mountIFrameWrapper,
-        displayAsModal,
-        exitTitle,
-        exitText,
-        exitPrimaryButtonText,
-        exitSecondaryButtonText,
-        closeSpaceNow,
-        closeSpace,
-        simpleOnboardingOptions?.onCancel
-      )
-    }
-
-    return { spaceId: spaceResult.id }
-  } catch (error) {
-    const wrapper = document.getElementById(mountElement)
-    const errorMessage = displayError(errorTitle, error as string)
-    wrapper?.appendChild(errorMessage)
-  }
-}
-
-export const initializeFlatfile = startFlatfile
-export { createIframe }
diff --git a/packages/javascript/index.ts b/packages/javascript/index.ts
index bf4d5d41..39ac1cda 100644
--- a/packages/javascript/index.ts
+++ b/packages/javascript/index.ts
@@ -1,7 +1,9 @@
-import * as FlatfileJavascript from './FlatfileJavascript'
-export * from './FlatfileJavascript'
-import { FlatfileListener } from '@flatfile/listener'
 import api from '@flatfile/api'
+import { FlatfileListener } from '@flatfile/listener'
 import * as RecordHookPlugin from '@flatfile/plugin-record-hook'
-export { FlatfileListener, api, RecordHookPlugin }
-export default FlatfileJavascript
+import { createIframe } from './src/createIframe'
+import { startFlatfile } from './src/startFlatfile'
+
+export { api, createIframe, FlatfileListener, RecordHookPlugin }
+
+export const initializeFlatfile = startFlatfile
diff --git a/packages/javascript/package.json b/packages/javascript/package.json
index 69177785..495aa9e9 100644
--- a/packages/javascript/package.json
+++ b/packages/javascript/package.json
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-json": "^6.0.1",
+    "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-sucrase": "^5.0.2",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-url": "^8.0.2",
@@ -54,6 +54,8 @@
   "dependencies": {
     "@flatfile/embedded-utils": "^1.3.0",
     "@flatfile/listener": "^1.0.4",
-    "@flatfile/plugin-record-hook": "^1.5.2"
+    "@flatfile/plugin-record-hook": "^1.5.2",
+    "i18next": "^23.11.5",
+    "i18next-browser-languagedetector": "^8.0.0"
   }
 }
diff --git a/packages/javascript/rollup.config.js b/packages/javascript/rollup.config.js
index 7994edb4..da07920b 100644
--- a/packages/javascript/rollup.config.js
+++ b/packages/javascript/rollup.config.js
@@ -1,13 +1,13 @@
-import { dts } from 'rollup-plugin-dts'
 import commonjs from '@rollup/plugin-commonjs'
-import css from 'rollup-plugin-import-css'
-import dotenv from 'dotenv'
 import json from '@rollup/plugin-json'
-import peerDepsExternal from 'rollup-plugin-peer-deps-external'
 import resolve from '@rollup/plugin-node-resolve'
 import sucrase from '@rollup/plugin-sucrase'
 import terser from '@rollup/plugin-terser'
 import url from '@rollup/plugin-url'
+import dotenv from 'dotenv'
+import { dts } from 'rollup-plugin-dts'
+import css from 'rollup-plugin-import-css'
+import peerDepsExternal from 'rollup-plugin-peer-deps-external'
 
 dotenv.config()
 
@@ -25,6 +25,7 @@ const external = [
 // Common plugins function
 function commonPlugins(umd = true) {
   return [
+    json(),
     umd
       ? peerDepsExternal({
           includeDependencies: true,
@@ -35,7 +36,6 @@ function commonPlugins(umd = true) {
       exclude: ['node_modules/**'],
       transforms: ['typescript'],
     }),
-    json(),
     commonjs(),
     css(),
     url({
@@ -78,7 +78,6 @@ const config = [
       name: 'FlatFileJavaScript',
     },
     plugins: commonPlugins(false),
-    include: external,
   },
   {
     input: 'index.ts',
diff --git a/packages/javascript/src/i18n.ts b/packages/javascript/src/i18n.ts
new file mode 100644
index 00000000..37c7cc4c
--- /dev/null
+++ b/packages/javascript/src/i18n.ts
@@ -0,0 +1,138 @@
+import i18n from 'i18next'
+import LanguageDetector from 'i18next-browser-languagedetector'
+
+import * as localDe from './locales/de/translation.json'
+import * as localEnCA from './locales/en-CA/translation.json'
+import * as localEnGB from './locales/en-GB/translation.json'
+import * as localEnZA from './locales/en-ZA/translation.json'
+import * as localEn from './locales/en/translation.json'
+import * as localEs from './locales/es/translation.json'
+import * as localFrCA from './locales/fr-CA/translation.json'
+import * as localFrFR from './locales/fr-Fr/translation.json'
+import * as localFr from './locales/fr/translation.json'
+import * as localId from './locales/id/translation.json'
+import * as localIt from './locales/it/translation.json'
+import * as localJp from './locales/jp/translation.json'
+import * as localKr from './locales/kr/translation.json'
+import * as localPtBR from './locales/pt-BR/translation.json'
+import * as localPt from './locales/pt/translation.json'
+import * as localTr from './locales/tr/translation.json'
+import * as localVi from './locales/vi/translation.json'
+import * as localZh from './locales/zh/translation.json'
+
+const supportedLanguages = [
+  'de',
+  'en',
+  'en-GB',
+  'en-CA',
+  'en-ZA',
+  'es',
+  'fr',
+  'fr-CA',
+  'fr-FR',
+  'id',
+  'it',
+  'jp',
+  'kr',
+  'pt',
+  'pt-BR',
+  'tr',
+  'vi',
+  'zh',
+]
+
+type SupportedLanguage = (typeof supportedLanguages)[number]
+
+type Translations = typeof localEn
+
+type StripEndings<K> = K extends `${infer R}_one`
+  ? R
+  : K extends `${infer R}_other`
+  ? R
+  : K extends `${infer R}_zero`
+  ? R
+  : K
+
+type PathKeys<T, P extends string = ''> = {
+  [K in keyof T]: K extends string | number
+    ? T[K] extends object
+      ? StripEndings<`${P}${K}`> | PathKeys<T[K], `${P}${K}.`>
+      : StripEndings<`${P}${K}`>
+    : never
+}[keyof T]
+
+export type TranslationsKeys = PathKeys<Translations>
+
+const localTranslations: Record<SupportedLanguage, Translations | any> = {
+  // the en file will often be in front of the other translation files so typing to Translations no longer works here
+  de: localDe,
+  en: localEn,
+  'en-GB': localEnGB,
+  'en-CA': localEnCA,
+  'en-ZA': localEnZA,
+  es: localEs,
+  fr: localFr,
+  'fr-CA': localFrCA,
+  'fr-FR': localFrFR,
+  id: localId,
+  it: localIt,
+  jp: localJp,
+  kr: localKr,
+  pt: localPt,
+  'pt-BR': localPtBR,
+  tr: localTr,
+  vi: localVi,
+  zh: localZh,
+}
+
+export const getI18n = (languageOverride?: string) => {
+  const loggedMissingKeys = new Set<string>()
+
+  i18n.use(LanguageDetector).init({
+    preload: [languageOverride ?? navigator.language, 'en'],
+    fallbackLng: 'en',
+    debug: false,
+    interpolation: {
+      escapeValue: false,
+    },
+    saveMissing: true, //required for missing key handler
+    missingKeyHandler: (
+      lng: readonly string[],
+      ns: string,
+      key: string,
+      fallbackValue: any
+    ): void => {
+      //check that key is not a regular string or filename
+      if (
+        !key.includes('.') ||
+        key.match(/[\s\n\t]/) ||
+        key.includes('...') ||
+        isTranslationFileName(key) ||
+        key.endsWith('.')
+      ) {
+        return
+      }
+      if (!loggedMissingKeys.has(key)) {
+        console.error(`[i18n] Missing key: ${key}`)
+        loggedMissingKeys.add(key)
+      }
+    },
+  })
+  Object.keys(localTranslations).forEach((lng) => {
+    i18n.addResourceBundle(
+      lng,
+      'translation',
+      localTranslations[languageOverride ?? lng] ?? {}
+    )
+  })
+  return i18n
+}
+
+const isTranslationFileName = (str: string) => {
+  const extensionsPattern = ['json'].join('|')
+  const filenameRegex = new RegExp(
+    `^[^\\\\/?%*:|"<>]+\\.(${extensionsPattern})$`,
+    'i'
+  )
+  return filenameRegex.test(str)
+}
diff --git a/packages/javascript/src/initNewSpace.ts b/packages/javascript/src/initNewSpace.ts
new file mode 100644
index 00000000..9534f0af
--- /dev/null
+++ b/packages/javascript/src/initNewSpace.ts
@@ -0,0 +1,118 @@
+import {
+  DefaultPageType,
+  updateDefaultPageInSpace,
+} from '@flatfile/embedded-utils'
+import { InitSpaceType, InitialResourceData } from './types'
+
+/**
+ * Full-service utility which takes incoming space configuration data and calls the internal backend-for-frontend
+ * endpoint to create the space, workbook, and document in a single request.
+ *
+ * The resulting response is the full set of initial resources needed to render the UI experience
+ * @param param0
+ * @returns
+ */
+export const initNewSpace = async ({
+  publishableKey,
+  apiUrl,
+  name,
+  environmentId,
+  spaceBody,
+  namespace = 'portal',
+  translationsPath,
+  languageOverride,
+  themeConfig,
+  sidebarConfig,
+  labels,
+  metadata,
+  userInfo,
+  workbook,
+  document,
+  isAutoConfig,
+}: InitSpaceType): Promise<InitialResourceData> => {
+  const createSpaceEndpoint = `${apiUrl}/v1/internal/spaces/init?publishableKey=${publishableKey}`
+
+  let defaultPage
+  let defaultPageSet = false
+
+  let spaceRequestBody: any = {
+    space: {
+      name: name || 'Embedded Space',
+      ...spaceBody,
+      autoConfigure: isAutoConfig,
+      ...(environmentId ? { environmentId } : {}),
+      labels: ['embedded', ...(labels || [])],
+      ...(namespace ? { namespace } : {}),
+      ...(translationsPath ? { translationsPath } : {}),
+      ...(languageOverride ? { languageOverride } : {}),
+      metadata: {
+        theme: themeConfig,
+        sidebarConfig: sidebarConfig || { showSidebar: false },
+        userInfo,
+        ...(spaceBody?.metadata || {}),
+        ...(metadata || {}),
+      },
+    },
+  }
+
+  const addResourceToRequestBody = (resource: any, resourceName: string) => {
+    spaceRequestBody = {
+      ...spaceRequestBody,
+      [resourceName]: resource,
+    }
+  }
+  const setDefaultPage = (incomingDefaultPage: DefaultPageType) => {
+    if (defaultPageSet === true) {
+      console.warn(
+        'Default page is already set. Multiple default pages are not allowed.'
+      )
+    } else {
+      defaultPage = incomingDefaultPage
+      defaultPageSet = true
+    }
+  }
+
+  if (workbook) {
+    addResourceToRequestBody(workbook, 'workbook')
+
+    if (workbook.defaultPage) {
+      setDefaultPage({ workbook: workbook.name })
+    } else if (workbook.sheets) {
+      const defaultSheet = workbook.sheets?.find?.((sheet) => sheet.defaultPage)
+      if (defaultSheet && defaultSheet.slug) {
+        setDefaultPage({ workbook: { sheet: defaultSheet.slug } })
+      }
+    }
+  }
+
+  if (document) {
+    addResourceToRequestBody(document, 'document')
+
+    if (document.defaultPage) {
+      setDefaultPage({ document: document.title })
+    }
+  }
+
+  const response = await fetch(createSpaceEndpoint, {
+    method: 'POST',
+    headers: {
+      Accept: 'text/plain',
+      'Content-Type': 'text/plain',
+    },
+    body: JSON.stringify(spaceRequestBody),
+  })
+
+  const result = await response.json()
+  if (!response.ok) {
+    const errorMessage = result?.errors[0]?.message || 'Failed to create space'
+    throw new Error(errorMessage)
+  }
+
+  const createdSpace = result.data
+
+  ;(window as any).CROSSENV_FLATFILE_API_KEY = createdSpace.space.accessToken
+
+  if (defaultPage) await updateDefaultPageInSpace(createdSpace, defaultPage)
+
+  return createdSpace
+}
diff --git a/packages/javascript/src/listener.ts b/packages/javascript/src/listener.ts
new file mode 100644
index 00000000..a790fece
--- /dev/null
+++ b/packages/javascript/src/listener.ts
@@ -0,0 +1,99 @@
+import { FlatfileClient } from '@flatfile/api'
+import {
+  DefaultSubmitSettings,
+  handlePostMessage,
+  JobHandler,
+  NewSpaceFromPublishableKey,
+  SheetHandler,
+} from '@flatfile/embedded-utils'
+import { FlatfileRecord } from '@flatfile/hooks'
+import { Browser, FlatfileEvent, FlatfileListener } from '@flatfile/listener'
+import { recordHook } from '@flatfile/plugin-record-hook'
+import { SimpleListenerType } from './types'
+
+/**
+ * Add a listener to handle postMessage events
+ *
+ * @param accessToken
+ * @param apiUrl
+ * @param listener
+ * @param closeSpace
+ * @param onClose
+ * @returns Promise<() => void>
+ */
+export async function createlistener(
+  accessToken: string,
+  apiUrl: string,
+  listener: FlatfileListener,
+  closeSpace: NewSpaceFromPublishableKey['closeSpace'],
+  onClose: () => void
+): Promise<() => void> {
+  const browser_instance = new Browser({
+    apiUrl,
+    accessToken,
+    fetchApi: fetch,
+  })
+  const ff_message_handler = handlePostMessage(closeSpace, listener, onClose)
+
+  listener.mount(browser_instance)
+  window.addEventListener('message', ff_message_handler, false)
+
+  return () => {
+    window.removeEventListener('message', ff_message_handler)
+    listener.unmount(browser_instance)
+  }
+}
+
+export const createSimpleListener = ({
+  onRecordHook,
+  onSubmit,
+  slug,
+  submitSettings,
+}: SimpleListenerType) =>
+  FlatfileListener.create((client: FlatfileListener) => {
+    const api = new FlatfileClient()
+    if (onRecordHook) {
+      client.use(
+        recordHook(
+          slug,
+          async (record: FlatfileRecord, event: FlatfileEvent | undefined) =>
+            onRecordHook(record, event)
+        )
+      )
+    }
+    if (onSubmit) {
+      const onSubmitSettings = { ...DefaultSubmitSettings, ...submitSettings }
+      client.filter({ job: 'workbook:simpleSubmitAction' }, (configure) => {
+        configure.on('job:ready', async (event) => {
+          const { jobId, spaceId, workbookId } = event.context
+          try {
+            await api.jobs.ack(jobId, { info: 'Starting job', progress: 10 })
+
+            const job = new JobHandler(jobId)
+            const { data: workbookSheets } = await api.sheets.list({
+              workbookId,
+            })
+
+            // this assumes we are only allowing 1 sheet here (which we've talked about doing initially)
+            const sheet = new SheetHandler(workbookSheets[0].id)
+
+            await onSubmit({ job, sheet, event })
+
+            await api.jobs.complete(jobId, {
+              outcome: {
+                message: 'complete',
+              },
+            })
+            if (onSubmitSettings.deleteSpaceAfterSubmit) {
+              await api.spaces.archiveSpace(spaceId)
+            }
+          } catch (error: any) {
+            if (jobId) {
+              await api.jobs.cancel(jobId)
+            }
+            console.error('Error:', error.stack)
+          }
+        })
+      })
+    }
+  })
diff --git a/packages/javascript/src/locales/de/translation.json b/packages/javascript/src/locales/de/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/de/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/en-CA/translation.json b/packages/javascript/src/locales/en-CA/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/en-CA/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/en-GB/translation.json b/packages/javascript/src/locales/en-GB/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/en-GB/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/en-ZA/translation.json b/packages/javascript/src/locales/en-ZA/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/en-ZA/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/en/translation.json b/packages/javascript/src/locales/en/translation.json
new file mode 100644
index 00000000..1489616f
--- /dev/null
+++ b/packages/javascript/src/locales/en/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": "Something went wrong",
+    "exitPrimaryButtonText": "Yes, exit",
+    "exitSecondaryButtonText": "No, stay",
+    "exitText": "Are you sure you would like to close this window? This will end your current data import session.",
+    "exitTitle": "Close Window"
+  }
+}
diff --git a/packages/javascript/src/locales/es/translation.json b/packages/javascript/src/locales/es/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/es/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/fr-CA/translation.json b/packages/javascript/src/locales/fr-CA/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/fr-CA/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/fr-Fr/translation.json b/packages/javascript/src/locales/fr-Fr/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/fr-Fr/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/fr/translation.json b/packages/javascript/src/locales/fr/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/fr/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/id/translation.json b/packages/javascript/src/locales/id/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/id/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/it/translation.json b/packages/javascript/src/locales/it/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/it/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/jp/translation.json b/packages/javascript/src/locales/jp/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/jp/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/kr/translation.json b/packages/javascript/src/locales/kr/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/kr/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/pt-BR/translation.json b/packages/javascript/src/locales/pt-BR/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/pt-BR/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/pt/translation.json b/packages/javascript/src/locales/pt/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/pt/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/tr/translation.json b/packages/javascript/src/locales/tr/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/tr/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/vi/translation.json b/packages/javascript/src/locales/vi/translation.json
new file mode 100644
index 00000000..a4b151b0
--- /dev/null
+++ b/packages/javascript/src/locales/vi/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": null,
+    "exitTitle": null
+  }
+}
diff --git a/packages/javascript/src/locales/zh/translation.json b/packages/javascript/src/locales/zh/translation.json
new file mode 100644
index 00000000..35390adc
--- /dev/null
+++ b/packages/javascript/src/locales/zh/translation.json
@@ -0,0 +1,9 @@
+{
+  "host": {
+    "errorTitle": null,
+    "exitPrimaryButtonText": null,
+    "exitSecondaryButtonText": null,
+    "exitText": "你确定要退出吗？",
+    "exitTitle": "关闭"
+  }
+}
diff --git a/packages/javascript/src/startFlatfile.ts b/packages/javascript/src/startFlatfile.ts
new file mode 100644
index 00000000..3f9799fb
--- /dev/null
+++ b/packages/javascript/src/startFlatfile.ts
@@ -0,0 +1,220 @@
+import {
+  ISpace,
+  SimpleOnboarding,
+  createWorkbookFromSheet,
+} from '@flatfile/embedded-utils'
+import { createIframe } from './createIframe'
+import { getI18n } from './i18n'
+import { initNewSpace } from './initNewSpace'
+import { createSimpleListener, createlistener } from './listener'
+import { displayError, initializeIFrameConfirmationModal } from './utils'
+
+export async function startFlatfile(options: SimpleOnboarding | ISpace) {
+  function closeSpaceNow() {
+    removeMessageListener?.()
+    document.querySelector('.flatfile_outer-shell')?.remove?.()
+    mountIFrameWrapper?.remove?.()
+  }
+
+  let removeMessageListener: (() => void) | undefined
+
+  const {
+    publishableKey,
+    displayAsModal = true,
+    mountElement = 'flatfile_iFrameContainer',
+    space,
+    spaceBody = undefined,
+    apiUrl = 'https://platform.flatfile.com/api',
+    baseUrl = 'https://platform.flatfile.com/s',
+    spaceUrl = 'https://platform.flatfile.com/s',
+    closeSpace,
+    errorTitle: customErrorTitle,
+    exitPrimaryButtonText: customExitPrimaryButtonText,
+    exitSecondaryButtonText: customExitSecondaryButtonText,
+    exitText: customExitText,
+    exitTitle: customExitTitle,
+    name,
+    environmentId,
+    workbook,
+    themeConfig,
+    document: documentConfig,
+    sidebarConfig,
+    userInfo,
+    listener,
+    namespace,
+    metadata,
+    labels,
+    translationsPath, // used inside the Space iframe only, not the wrapper
+    languageOverride, // used for both the wrapper and the Space iframe
+  } = options
+  const simpleOnboardingOptions = options as SimpleOnboarding
+  const isReusingSpace = !!(space?.id && space?.accessToken)
+  const spacesUrl = spaceUrl || baseUrl
+  let mountIFrameWrapper = document.getElementById(mountElement)
+  const mountIFrameElement = mountIFrameWrapper
+    ? mountIFrameWrapper.getElementsByTagName('iframe')[0]
+    : null
+  ;(window as any).CROSSENV_FLATFILE_API_URL = apiUrl
+  /**
+   * Customers can proactively preload the iFrame into the DOM - If we detect that an iFrame already exists
+   * for the provided mountElementId - we can assume it has been preloaded, and simply make it visible
+   **/
+  if (mountIFrameWrapper && mountIFrameElement) {
+    mountIFrameWrapper.style.display = 'block'
+  }
+
+  const i18n = getI18n(languageOverride)
+
+  /**
+   * Use custom text overrides first,
+   * falling back to i18next for translations,
+   * or finally static defaults
+   */
+  const exitTitle = customExitTitle || i18n.t('host.exitTitle', 'Close Window')
+  const exitText =
+    customExitText ||
+    i18n.t(
+      'host.exitText',
+      'Are you sure you would like to close this window? This will end your current data import session.'
+    )
+  const exitPrimaryButtonText =
+    customExitPrimaryButtonText ||
+    i18n.t('host.exitPrimaryButtonText', 'Yes, exit')
+  const exitSecondaryButtonText =
+    customExitSecondaryButtonText ||
+    i18n.t('host.exitSecondaryButtonText', 'No, stay')
+  const errorTitle =
+    customErrorTitle || i18n.t('host.errorTitle', 'Something went wrong')
+
+  try {
+    let spaceResult: any
+    let initialResourceResponse
+    let createdWorkbook = workbook
+    let isAutoConfig = false
+
+    if (!createdWorkbook) {
+      if (!simpleOnboardingOptions.sheet) {
+        isAutoConfig = true
+      } else {
+        createdWorkbook = createWorkbookFromSheet(
+          simpleOnboardingOptions.sheet,
+          !!simpleOnboardingOptions.onSubmit
+        )
+      }
+    }
+
+    if (isReusingSpace) {
+      spaceResult = space
+      ;(window as any).CROSSENV_FLATFILE_API_KEY = spaceResult?.accessToken
+    }
+    // Initialize new space / workbook / document and obtain response used to "initial resources" to hydrate embedded UI
+    else if (publishableKey) {
+      initialResourceResponse = await initNewSpace({
+        publishableKey,
+        apiUrl,
+        name,
+        spaceBody,
+        namespace,
+        environmentId,
+        translationsPath,
+        languageOverride,
+        themeConfig,
+        sidebarConfig,
+        labels,
+        metadata,
+        userInfo,
+        workbook: createdWorkbook,
+        document: documentConfig,
+        isAutoConfig,
+      })
+
+      spaceResult = initialResourceResponse.space
+    }
+
+    if (!spaceResult?.id || !spaceResult?.accessToken) {
+      throw new Error('Unable to create space, please try again.')
+    }
+    // Set these for handy use in the listeners for authenticating the @flatfile/api client
+
+    const simpleListenerSlug: string =
+      createdWorkbook?.sheets?.[0].slug || 'slug'
+
+    if (listener) {
+      removeMessageListener = await createlistener(
+        spaceResult.accessToken,
+        apiUrl,
+        listener,
+        closeSpace,
+        closeSpaceNow
+      )
+    } else {
+      removeMessageListener = await createlistener(
+        spaceResult.accessToken,
+        apiUrl,
+        createSimpleListener({
+          onRecordHook: simpleOnboardingOptions?.onRecordHook,
+          onSubmit: simpleOnboardingOptions?.onSubmit,
+          slug: simpleListenerSlug,
+        }),
+        closeSpace,
+        closeSpaceNow
+      )
+    }
+
+    /**
+     * Customers can proactively preload the iFrame into the DOM - If we detect that an iFrame already exists
+     * for the provided mountElementId then we pass a message to direct the iFrame to the spaces-UI route for
+     * the created spaceId
+     *
+     * If it has not been created yet, the iFrame is created on-demand, and routed to the specified space-id
+     **/
+    if (!mountIFrameElement) {
+      mountIFrameWrapper = createIframe(
+        mountElement,
+        displayAsModal,
+        spaceResult.id,
+        spaceResult.accessToken,
+        spaceResult?.guestLink ?? spacesUrl,
+        isReusingSpace
+      )
+    } else {
+      const targetOrigin = new URL(spacesUrl).origin
+      const initialResources = initialResourceResponse || null
+      mountIFrameElement.contentWindow?.postMessage(
+        {
+          flatfileEvent: {
+            topic: 'portal:initialize',
+            payload: {
+              status: 'complete',
+              spaceUrl: `${targetOrigin}/space/${
+                spaceResult.id
+              }?token=${encodeURIComponent(spaceResult.accessToken)}`,
+              initialResources,
+            },
+          },
+        },
+        targetOrigin
+      )
+    }
+
+    if (mountIFrameWrapper) {
+      initializeIFrameConfirmationModal(
+        mountIFrameWrapper,
+        displayAsModal,
+        exitTitle,
+        exitText,
+        exitPrimaryButtonText,
+        exitSecondaryButtonText,
+        closeSpaceNow,
+        closeSpace,
+        simpleOnboardingOptions?.onCancel
+      )
+    }
+
+    return { spaceId: spaceResult.id }
+  } catch (error) {
+    const wrapper = document.getElementById(mountElement)
+    const errorMessage = displayError(errorTitle, error as string)
+    wrapper?.appendChild(errorMessage)
+  }
+}
diff --git a/packages/javascript/src/types/InitialResourceData.ts b/packages/javascript/src/types/InitialResourceData.ts
new file mode 100644
index 00000000..dc1e4a10
--- /dev/null
+++ b/packages/javascript/src/types/InitialResourceData.ts
@@ -0,0 +1,13 @@
+import { Flatfile } from '@flatfile/api'
+
+// TODO: Replace hardcoded type with imported type from Platform
+export interface InitialResourceData {
+  workbooks: Flatfile.Workbook[] | null
+  documents: Flatfile.Document[] | null
+  space: Flatfile.Space
+  actor: Flatfile.User | Flatfile.Guest | undefined
+  entitlements: any[]
+  environment: Partial<Flatfile.Environment> & {
+    hasAccess: boolean
+  }
+}
diff --git a/packages/javascript/src/types/index.ts b/packages/javascript/src/types/index.ts
index 54b8d505..5827c9b4 100644
--- a/packages/javascript/src/types/index.ts
+++ b/packages/javascript/src/types/index.ts
@@ -1 +1,16 @@
+export * from './InitialResourceData'
 export * from './UpdateSpaceInfo'
+
+import { ISpace, SimpleOnboarding } from '@flatfile/embedded-utils'
+
+export interface SimpleListenerType
+  extends Pick<
+    SimpleOnboarding,
+    'onRecordHook' | 'onSubmit' | 'submitSettings'
+  > {
+  slug: string
+}
+
+export type InitSpaceType = ISpace & {
+  isAutoConfig: boolean
+}
diff --git a/packages/javascript/src/utils.ts b/packages/javascript/src/utils.ts
new file mode 100644
index 00000000..6ef664b2
--- /dev/null
+++ b/packages/javascript/src/utils.ts
@@ -0,0 +1,109 @@
+import { ISpace } from '@flatfile/embedded-utils'
+import { createModal } from './createModal'
+
+export const displayError = (errorTitle: string, errorMessage: string) => {
+  const display = document.createElement('div')
+  display.classList.add('ff_error_container')
+  const title = document.createElement('h1')
+  title.classList.add('ff_error_heading')
+  const error = document.createElement('p')
+  error.classList.add('ff_error_text')
+
+  title.innerText = errorTitle
+  error.innerText = errorMessage
+
+  display.appendChild(title)
+  display.appendChild(error)
+
+  return display
+}
+
+/**
+ * Utility function with the responsibility of mounting the confirmation modal and its
+ * associate behaviors to the iFrame which is actively being mounted (or was previously preloaded)
+ * @param domElement
+ * @param displayAsModal
+ * @param exitTitle
+ * @param exitText
+ * @param exitPrimaryButtonText
+ * @param exitSecondaryButtonText
+ * @param closeSpaceNow
+ * @param closeSpace
+ * @param onCancel
+ */
+export function initializeIFrameConfirmationModal(
+  domElement: HTMLElement,
+  displayAsModal: boolean,
+  exitTitle: string,
+  exitText: string,
+  exitPrimaryButtonText: string,
+  exitSecondaryButtonText: string,
+  closeSpaceNow: () => void,
+  closeSpace?: ISpace['closeSpace'],
+  onCancel?: () => void
+) {
+  // Create the confirmation modal and hide it
+  const confirmModal = createModal(
+    () => {
+      // If user chooses to exit
+      const wrappers = Array.from(
+        document.getElementsByClassName('flatfile_iframe-wrapper')
+      ) as HTMLElement[]
+      const modals = Array.from(
+        document.getElementsByClassName('flatfile_outer-shell')
+      ) as HTMLElement[]
+
+      const elements = [...modals]
+
+      for (let item of elements) {
+        document.body.removeChild(item)
+      }
+
+      closeSpaceNow()
+      if (onCancel) {
+        onCancel()
+      }
+      closeSpace?.onClose?.({})
+    },
+    () => {
+      // If user chooses to stay, we simply hide the confirm modal
+      confirmModal.style.display = 'none'
+    },
+    exitTitle, // pass exitTitle here
+    exitText, // pass exitText here,
+    exitPrimaryButtonText,
+    exitSecondaryButtonText
+  )
+  confirmModal.style.display = 'none'
+  document.body.appendChild(confirmModal)
+
+  if (displayAsModal) {
+    const closeButton = document.createElement('div')
+    closeButton.innerHTML = `<svg
+       xmlns="http://www.w3.org/2000/svg"
+       width="24"
+       height="24"
+       viewBox="0 0 100 100"
+     >
+       <line x1="10" y1="10" x2="90" y2="90" stroke="white" stroke-width="10" />
+       <line x1="10" y1="90" x2="90" y2="10" stroke="white" stroke-width="10" />
+     </svg>`
+    closeButton.classList.add('flatfile-close-button')
+    // Add the onclick event to the button
+    closeButton.onclick = () => {
+      const outerShell = document.querySelector(
+        '.flatfile_outer-shell'
+      ) as HTMLElement
+      if (outerShell) {
+        outerShell.style.display = 'block'
+      } else {
+        // Show the confirm modal instead of creating a new one
+        confirmModal.style.display = 'block'
+      }
+    }
+
+    domElement
+      .getElementsByClassName('flatfile_iframe-wrapper')[0]
+      .appendChild(closeButton)
+  }
+}
diff --git a/packages/javascript/tsconfig.json b/packages/javascript/tsconfig.json
index 09da4aa4..11f45f6a 100644
--- a/packages/javascript/tsconfig.json
+++ b/packages/javascript/tsconfig.json
@@ -1,21 +1,12 @@
 {
   "extends": "@flatfile/ts-config-platform-sdk/base.json",
-  "include": [
-    "./src",
-    "index.ts"
-  ],
-  "exclude": [
-    "dist",
-    "build",
-    "node_modules"
-  ],
+  "include": ["./src", "index.ts"],
+  "exclude": ["dist", "build", "node_modules"],
   "compilerOptions": {
-    "lib": [
-      "es2015",
-      "DOM"
-    ],
+    "lib": ["es2015", "DOM"],
     "module": "es2015",
-    "target": "es2015",
-    "noEmit": true
-  },
-}
\ No newline at end of file
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "target": "es2015"
+  }
+}

From 9ab4ff74db5dd9bd1a9789843e6617ae4b8ffd3c Mon Sep 17 00:00:00 2001
From: "komment-ai[bot]" <122626893+komment-ai[bot]@users.noreply.github.com>
Date: Wed, 3 Jul 2024 04:36:31 +0000
Subject: [PATCH 2/3] Added comments to 15 functions across 7 files

---
 apps/vanilla/main.js                     | 26 ++++++++++++++++
 packages/javascript/rollup.config.js     | 17 +++++++++++
 packages/javascript/src/i18n.ts          | 38 ++++++++++++++++++++++++
 packages/javascript/src/initNewSpace.ts  | 16 ++++++++++
 packages/javascript/src/listener.ts      | 34 +++++++++++++++++++++
 packages/javascript/src/startFlatfile.ts | 15 ++++++++++
 packages/javascript/src/utils.ts         | 22 ++++++++++++++
 7 files changed, 168 insertions(+)

diff --git a/apps/vanilla/main.js b/apps/vanilla/main.js
index f5d30376..373f709b 100644
--- a/apps/vanilla/main.js
+++ b/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 named 'overrideLanguage' to the value
+ * of the `overrideLanguageSelect` element.
+ */
 overrideLanguageSelect.addEventListener('change', () => {
   localStorage.setItem('overrideLanguage', overrideLanguageSelect.value)
 })
@@ -87,12 +91,25 @@ const BASE_OPTIONS = {
   namespace: 'my-namespace',
 }
 // ---Create a new Space + Workbook and load an iFrame
+/**
+ * @description Initializes a Flatfile client using a provided publishable key, then
+ * logs the resulting `space` object to the console.
+ * 
+ * @param {string} publishableKey - 256-bit publishable key used for signing and
+ * verifying data during the flatfile submission operation.
+ */
 window.initializeFlatfile = async (publishableKey) => {
   const flatfileOptions = {
     ...BASE_OPTIONS,
     publishableKey,
     closeSpace: {
       operation: 'submitActionFg',
+      /**
+       * @description Logs the event payload to the console in a JSON-formatted string with
+       * indentation and spacing for readability.
+       * 
+       * @param {object} event - payload of an close space event in the format of JSON string.
+       */
       onClose: (event) => {
         console.log(
           `Close space event payload: ${JSON.stringify(event, null, 2)}`
@@ -106,6 +123,10 @@ window.initializeFlatfile = async (publishableKey) => {
 }
 
 // ---Pre-load iFrame by specific mountID for faster initial load-time
+/**
+ * @description Creates an iframe and sets up a Flatfile instance within it, using
+ * the given publishable key to preload resources.
+ */
 window.preloadFlatfile = () => {
   createIframe('Flatfile_Preload_Iframe', true)
   window.initializePreloadedFlatfile = async (publishableKey) => {
@@ -115,6 +136,11 @@ window.preloadFlatfile = () => {
       mountElement: 'Flatfile_Preload_Iframe',
       closeSpace: {
         operation: 'submitActionFg',
+        /**
+         * @description Consoles the payload of a close space event as a string.
+         * 
+         * @param {object} event - payload of an event that is passed to the function for processing.
+         */
         onClose: (event) => {
           console.log(
             `Close space event payload: ${JSON.stringify(event, null, 2)}`
diff --git a/packages/javascript/rollup.config.js b/packages/javascript/rollup.config.js
index da07920b..4a68900e 100644
--- a/packages/javascript/rollup.config.js
+++ b/packages/javascript/rollup.config.js
@@ -23,6 +23,23 @@ const external = [
 ]
 
 // Common plugins function
+/**
+ * @description Returns an array of plugins for a web build configuration. It includes:
+ * 
+ * * `json()`: A JSON plugin
+ * * `peerDepsExternal()`: An external plugin for peer dependencies
+ * * `resolve()`: A resolution plugin for browser and TypeScript extensions
+ * * `sucrase()`: A transform plugin for Typescript files
+ * * `commonjs()`: A CommonJS plugin
+ * * `css()`: A CSS plugin
+ * * `url()`: An URl plugin with custom filtering
+ * 
+ * @param {true} umd - UMD configuration for the plugins in the function, which
+ * determines whether to include peer dependencies externaly or not.
+ * 
+ * @returns {array} an array of seven plugins for handling different aspects of
+ * JavaScript code.
+ */
 function commonPlugins(umd = true) {
   return [
     json(),
diff --git a/packages/javascript/src/i18n.ts b/packages/javascript/src/i18n.ts
index 37c7cc4c..c84a6c49 100644
--- a/packages/javascript/src/i18n.ts
+++ b/packages/javascript/src/i18n.ts
@@ -85,6 +85,17 @@ const localTranslations: Record<SupportedLanguage, Translations | any> = {
   zh: localZh,
 }
 
+/**
+ * @description Sets up an instance of `i18n` using the `LanguageDetector` and provides
+ * fallback languages. It also handles missing keys and adds them to a list for
+ * logging. Additionally, it adds resource bundles for specified localization files.
+ * 
+ * @param {string} languageOverride - language to be initialized for the i18n instance,
+ * and is used to customize the initialization process when it's different from the
+ * system language.
+ * 
+ * @returns {object} an initialized i18n instance with preloaded language resources.
+ */
 export const getI18n = (languageOverride?: string) => {
   const loggedMissingKeys = new Set<string>()
 
@@ -96,6 +107,22 @@ export const getI18n = (languageOverride?: string) => {
       escapeValue: false,
     },
     saveMissing: true, //required for missing key handler
+    /**
+     * @description Checks if a given key is valid and logs an error message to the console
+     * if it's not. If the key is missing, it adds it to a logging list for subsequent handling.
+     * 
+     * @param {readonly string[]} lng - 𝔄 for which to check the provided key is not a
+     * regular string or filename, and it is used to identify the language being checked.
+     * 
+     * @param {string} ns - namespace for which the function is checking the existence
+     * of the key.
+     * 
+     * @param {string} key - property that needs to be validated in order for the function
+     * to return successfully without any errors.
+     * 
+     * @param {any} fallbackValue - default value that will be used to display if the key
+     * is missing or cannot be translated.
+     */
     missingKeyHandler: (
       lng: readonly string[],
       ns: string,
@@ -128,6 +155,17 @@ export const getI18n = (languageOverride?: string) => {
   return i18n
 }
 
+/**
+ * @description Checks if a given string is a valid file name for translations by
+ * checking if it matches a pattern of accepted file extensions separated by a pipe
+ * | and a regex that matches any string starting with a letter or underscore followed
+ * by any characters except those prohibited.
+ * 
+ * @param {string} str - given string to be checked for extensions.
+ * 
+ * @returns {boolean} a boolean indicating whether a given string represents a valid
+ * translation file name.
+ */
 const isTranslationFileName = (str: string) => {
   const extensionsPattern = ['json'].join('|')
   const filenameRegex = new RegExp(
diff --git a/packages/javascript/src/initNewSpace.ts b/packages/javascript/src/initNewSpace.ts
index 9534f0af..0267b609 100644
--- a/packages/javascript/src/initNewSpace.ts
+++ b/packages/javascript/src/initNewSpace.ts
@@ -55,12 +55,28 @@ export const initNewSpace = async ({
     },
   }
 
+  /**
+   * @description Updates a request body with a specified resource name by merging the
+   * existing body with an updated value for that resource.
+   * 
+   * @param {any} resource - additional resource to be included in the space request body.
+   * 
+   * @param {string} resourceName - name of the resource for which the space request
+   * body is being constructed.
+   */
   const addResourceToRequestBody = (resource: any, resourceName: string) => {
     spaceRequestBody = {
       ...spaceRequestBody,
       [resourceName]: resource,
     }
   }
+  /**
+   * @description Sets a page as the default page for a given type, preventing multiple
+   * default pages from being set.
+   * 
+   * @param {DefaultPageType} incomingDefaultPage - default page to be set or retrieved
+   * within the function.
+   */
   const setDefaultPage = (incomingDefaultPage: DefaultPageType) => {
     if (defaultPageSet === true) {
       console.warn(
diff --git a/packages/javascript/src/listener.ts b/packages/javascript/src/listener.ts
index a790fece..0599d780 100644
--- a/packages/javascript/src/listener.ts
+++ b/packages/javascript/src/listener.ts
@@ -44,6 +44,40 @@ export async function createlistener(
   }
 }
 
+/**
+ * @description Creates a Flatfile listener that handles simple submissions and record
+ * hooks. It uses the `FlatfileClient` class to interact with the Flatfile API and
+ * listens for job "ready" events to handle submission and record hooks.
+ * 
+ * @param {SimpleListenerType} .onRecordHook - hook function that is triggered after
+ * each record has been processed during data ingestion, allowing for custom behavior
+ * or actions to be taken on individual records.
+ * 
+ * @param {SimpleListenerType} .onSubmit - onSubmit callback function that will be
+ * called after a job is submitted, allowing it to process and respond to the event.
+ * 
+ * @param {SimpleListenerType} .slug - unique identifier for the space where the
+ * Flatfile data will be stored.
+ * 
+ * @param {SimpleListenerType} .submitSettings - 3rd party application's settings for
+ * submitting data to the server, such as whether or not to delete the space after submission.
+ * 
+ * @returns {FlatfileListener} a FlatfileClient instance that can be used to handle
+ * Flatfile events.
+ * 
+ * 	* `client`: A new FlatfileClient instance is created to handle listener functions.
+ * 	* `use`: If `onRecordHook` is defined, a record hook is used to process records.
+ * The hook function takes two arguments: `record` (the current record being processed)
+ * and `event` (the event emitted by the flatfile client).
+ * 	* `onSubmitSettings`: An object containing submit settings, which are merged with
+ * the default settings provided in the `SimpleListenerType`.
+ * 	* `jobId`, `spaceId`, `workbookId`: These properties represent the context of the
+ * job being listened to, including the job ID, space ID, and workbook ID.
+ * 
+ * 	In summary, the `createSimpleListener` function creates a new FlatfileClient
+ * instance and sets up a simple listener to handle jobs and submits. It also allows
+ * for customization of submit settings through the `onSubmitSettings` property.
+ */
 export const createSimpleListener = ({
   onRecordHook,
   onSubmit,
diff --git a/packages/javascript/src/startFlatfile.ts b/packages/javascript/src/startFlatfile.ts
index 3f9799fb..b7b5ef2e 100644
--- a/packages/javascript/src/startFlatfile.ts
+++ b/packages/javascript/src/startFlatfile.ts
@@ -9,6 +9,21 @@ import { initNewSpace } from './initNewSpace'
 import { createSimpleListener, createlistener } from './listener'
 import { displayError, initializeIFrameConfirmationModal } from './utils'
 
+/**
+ * @description Sets up an Flatfile space for users. It generates a new space and
+ * workbook if one does not exist, obtains the required resources, initializes the
+ * embedded UI, and sets up listeners for authentication.
+ * 
+ * @param {SimpleOnboarding | ISpace} options - flatfile configuration object that
+ * provides various options for initialization, including display settings, space ID
+ * and access token, listeners, and more.
+ * 
+ * @returns {object} an object containing the space ID and other properties.
+ */
+/**
+ * @description Performs cleanup operations on an HTML document by removing event
+ * listeners, DOM elements, and an iframe wrapper.
+ */
 export async function startFlatfile(options: SimpleOnboarding | ISpace) {
   function closeSpaceNow() {
     removeMessageListener?.()
diff --git a/packages/javascript/src/utils.ts b/packages/javascript/src/utils.ts
index 6ef664b2..2e14d533 100644
--- a/packages/javascript/src/utils.ts
+++ b/packages/javascript/src/utils.ts
@@ -1,6 +1,28 @@
 import { ISpace } from '@flatfile/embedded-utils'
 import { createModal } from './createModal'
 
+/**
+ * @description Creates an HTML division element with a heading and paragraph containing
+ * an error message for display to the user.
+ * 
+ * @param {string} errorTitle - 1-line heading for the error message to be displayed
+ * inside the `<h1>` element, which is appended to the parent HTML element.
+ * 
+ * @param {string} errorMessage - error message to be displayed next to the error
+ * title in the generated container.
+ * 
+ * @returns {HTMLDivElement} a HTML div element containing an error heading and message.
+ * 
+ * 	* `display`: This is an HTML `div` element that contains the error message and
+ * heading. It has a class attribute set to `"ff_error_container"`.
+ * 	* `title`: This is an HTML `h1` element that contains the error title. It has a
+ * class attribute set to `"ff_error_heading"`.
+ * 	* `error`: This is an HTML `p` element that contains the error message. It has a
+ * class attribute set to `"ff_error_text"`
+ * 
+ * 	Overall, this function creates a basic structure for displaying an error message
+ * and heading in a HTML container element.
+ */
 export const displayError = (errorTitle: string, errorMessage: string) => {
   const display = document.createElement('div')
   display.classList.add('ff_error_container')

From bee7fefba276f6abd5f0a02f2b8438bd307dae55 Mon Sep 17 00:00:00 2001
From: "komment-ai[bot]" <122626893+komment-ai[bot]@users.noreply.github.com>
Date: Thu, 4 Jul 2024 13:16:29 +0000
Subject: [PATCH 3/3] Added comments to 15 functions across 7 files

---
 apps/vanilla/main.js                     | 29 ++++++-----
 packages/javascript/rollup.config.js     | 19 +++-----
 packages/javascript/src/i18n.ts          | 47 +++++++++---------
 packages/javascript/src/initNewSpace.ts  | 20 ++++----
 packages/javascript/src/listener.ts      | 62 ++++++++++++++----------
 packages/javascript/src/startFlatfile.ts | 20 ++++----
 packages/javascript/src/utils.ts         | 27 +++++------
 7 files changed, 116 insertions(+), 108 deletions(-)

diff --git a/apps/vanilla/main.js b/apps/vanilla/main.js
index 373f709b..20280cf4 100644
--- a/apps/vanilla/main.js
+++ b/apps/vanilla/main.js
@@ -5,8 +5,8 @@ import { listener } from './listener'
 
 const overrideLanguageSelect = document.getElementById('override-language')
 /**
- * @description Sets the `localStorage` item named 'overrideLanguage' to the value
- * of the `overrideLanguageSelect` element.
+ * @description Sets a item in `localStorage` with key `'overrideLanguage'` and its
+ * value is the selected option from `<overrideLanguageSelect>`.
  */
 overrideLanguageSelect.addEventListener('change', () => {
   localStorage.setItem('overrideLanguage', overrideLanguageSelect.value)
@@ -92,11 +92,12 @@ const BASE_OPTIONS = {
 }
 // ---Create a new Space + Workbook and load an iFrame
 /**
- * @description Initializes a Flatfile client using a provided publishable key, then
- * logs the resulting `space` object to the console.
+ * @description Sets up a Flatfile instance with the given `publishableKey`, and logs
+ * the resulting `space` object to the console.
  * 
- * @param {string} publishableKey - 256-bit publishable key used for signing and
- * verifying data during the flatfile submission operation.
+ * @param {string} publishableKey - 256-bitlong identifier that identifies the Spot
+ * instance, which is utilized to submit an action and produce a close space occasion
+ * with further information on the occurrence.
  */
 window.initializeFlatfile = async (publishableKey) => {
   const flatfileOptions = {
@@ -105,10 +106,11 @@ window.initializeFlatfile = async (publishableKey) => {
     closeSpace: {
       operation: 'submitActionFg',
       /**
-       * @description Logs the event payload to the console in a JSON-formatted string with
-       * indentation and spacing for readability.
+       * @description Consoles the JSON-formatted event payload upon receiving a close space
+       * event.
        * 
-       * @param {object} event - payload of an close space event in the format of JSON string.
+       * @param {object} event - space event to be logged and passed as a JSON string to
+       * the `console.log()` method.
        */
       onClose: (event) => {
         console.log(
@@ -124,8 +126,7 @@ window.initializeFlatfile = async (publishableKey) => {
 
 // ---Pre-load iFrame by specific mountID for faster initial load-time
 /**
- * @description Creates an iframe and sets up a Flatfile instance within it, using
- * the given publishable key to preload resources.
+ * @description Preloads a Flatfile application and sets up an iframe to display it.
  */
 window.preloadFlatfile = () => {
   createIframe('Flatfile_Preload_Iframe', true)
@@ -137,9 +138,11 @@ window.preloadFlatfile = () => {
       closeSpace: {
         operation: 'submitActionFg',
         /**
-         * @description Consoles the payload of a close space event as a string.
+         * @description Logs a close event's JSON-formatted payload to the console.
          * 
-         * @param {object} event - payload of an event that is passed to the function for processing.
+         * @param {object} event - space event that is passed to the function as its sole
+         * argument and whose details are logged through the `console.log()` call using JSON
+         * stringifying.
          */
         onClose: (event) => {
           console.log(
diff --git a/packages/javascript/rollup.config.js b/packages/javascript/rollup.config.js
index 4a68900e..82d0727e 100644
--- a/packages/javascript/rollup.config.js
+++ b/packages/javascript/rollup.config.js
@@ -24,21 +24,14 @@ const external = [
 
 // Common plugins function
 /**
- * @description Returns an array of plugins for a web build configuration. It includes:
+ * @description Generates a configuration array for a JavaScript build tool, comprising
+ * various plugins for tasks such as TypeScript transformation, CSS compilation, and
+ * production mode optimization with Terser.
  * 
- * * `json()`: A JSON plugin
- * * `peerDepsExternal()`: An external plugin for peer dependencies
- * * `resolve()`: A resolution plugin for browser and TypeScript extensions
- * * `sucrase()`: A transform plugin for Typescript files
- * * `commonjs()`: A CommonJS plugin
- * * `css()`: A CSS plugin
- * * `url()`: An URl plugin with custom filtering
+ * @param {true} umd - if condition for whether to include the `peerDepsExternal`
+ * plugin or not.
  * 
- * @param {true} umd - UMD configuration for the plugins in the function, which
- * determines whether to include peer dependencies externaly or not.
- * 
- * @returns {array} an array of seven plugins for handling different aspects of
- * JavaScript code.
+ * @returns {array} an array of seven plugins for building and bundling JavaScript code.
  */
 function commonPlugins(umd = true) {
   return [
diff --git a/packages/javascript/src/i18n.ts b/packages/javascript/src/i18n.ts
index c84a6c49..c017e238 100644
--- a/packages/javascript/src/i18n.ts
+++ b/packages/javascript/src/i18n.ts
@@ -86,15 +86,17 @@ const localTranslations: Record<SupportedLanguage, Translations | any> = {
 }
 
 /**
- * @description Sets up an instance of `i18n` using the `LanguageDetector` and provides
- * fallback languages. It also handles missing keys and adds them to a list for
- * logging. Additionally, it adds resource bundles for specified localization files.
+ * @description Sets up i18n for the given languageOverride optionally provided,
+ * preloads two languages (the default one and the specified one), and adds resources
+ * for the given localTranslations object or language override. It also logs any
+ * missing keys to the console if they are not already logged.
  * 
- * @param {string} languageOverride - language to be initialized for the i18n instance,
- * and is used to customize the initialization process when it's different from the
- * system language.
+ * @param {string} languageOverride - language to be initialized and used as a fallback
+ * language when no language is provided in the URL or through other means, and it
+ * defaults to the value of `navigator.language` if not provided.
  * 
- * @returns {object} an initialized i18n instance with preloaded language resources.
+ * @returns {object} an initialized i18n object with added missing key handler and
+ * resource bundles for the provided languages.
  */
 export const getI18n = (languageOverride?: string) => {
   const loggedMissingKeys = new Set<string>()
@@ -108,20 +110,21 @@ export const getI18n = (languageOverride?: string) => {
     },
     saveMissing: true, //required for missing key handler
     /**
-     * @description Checks if a given key is valid and logs an error message to the console
-     * if it's not. If the key is missing, it adds it to a logging list for subsequent handling.
+     * @description Checks if a given key is present in an array of translations, logs
+     * an error message if it's missing and adds it to a list of missed keys for further
+     * processing.
      * 
-     * @param {readonly string[]} lng - 𝔄 for which to check the provided key is not a
-     * regular string or filename, and it is used to identify the language being checked.
+     * @param {readonly string[]} lng - language code of the translations, which is a
+     * readonly string array.
      * 
-     * @param {string} ns - namespace for which the function is checking the existence
-     * of the key.
+     * @param {string} ns - namespace of the translations, which is used to check if the
+     * key provided is within the specified namespace.
      * 
-     * @param {string} key - property that needs to be validated in order for the function
-     * to return successfully without any errors.
+     * @param {string} key - string value that will be used as a key for a translation
+     * in the given namespace.
      * 
-     * @param {any} fallbackValue - default value that will be used to display if the key
-     * is missing or cannot be translated.
+     * @param {any} fallbackValue - value that will be used as the default value for the
+     * key if it is not found in the translations or if there is an error checking the key.
      */
     missingKeyHandler: (
       lng: readonly string[],
@@ -157,14 +160,12 @@ export const getI18n = (languageOverride?: string) => {
 
 /**
  * @description Checks if a given string is a valid file name for translations by
- * checking if it matches a pattern of accepted file extensions separated by a pipe
- * | and a regex that matches any string starting with a letter or underscore followed
- * by any characters except those prohibited.
+ * matching against an extensions pattern and a filename regular expression.
  * 
- * @param {string} str - given string to be checked for extensions.
+ * @param {string} str - given string to be checked for file extension pattern matches.
  * 
- * @returns {boolean} a boolean indicating whether a given string represents a valid
- * translation file name.
+ * @returns {boolean} a boolean value indicating whether a given string represents a
+ * valid file name.
  */
 const isTranslationFileName = (str: string) => {
   const extensionsPattern = ['json'].join('|')
diff --git a/packages/javascript/src/initNewSpace.ts b/packages/javascript/src/initNewSpace.ts
index 0267b609..bb1502e0 100644
--- a/packages/javascript/src/initNewSpace.ts
+++ b/packages/javascript/src/initNewSpace.ts
@@ -56,13 +56,15 @@ export const initNewSpace = async ({
   }
 
   /**
-   * @description Updates a request body with a specified resource name by merging the
-   * existing body with an updated value for that resource.
+   * @description Modifies a pre-existing request body object by adding a new key-value
+   * pair where the key is the name of a resource and the value is the corresponding
+   * resource itself.
    * 
-   * @param {any} resource - additional resource to be included in the space request body.
+   * @param {any} resource - resource to be added or updated within the space Request
+   * Body.
    * 
-   * @param {string} resourceName - name of the resource for which the space request
-   * body is being constructed.
+   * @param {string} resourceName - name of the resource that should be updated in the
+   * space Request body.
    */
   const addResourceToRequestBody = (resource: any, resourceName: string) => {
     spaceRequestBody = {
@@ -71,11 +73,11 @@ export const initNewSpace = async ({
     }
   }
   /**
-   * @description Sets a page as the default page for a given type, preventing multiple
-   * default pages from being set.
+   * @description Sets a default page for future user navigations, marking it as already
+   * set if necessary and assigning it to a variable.
    * 
-   * @param {DefaultPageType} incomingDefaultPage - default page to be set or retrieved
-   * within the function.
+   * @param {DefaultPageType} incomingDefaultPage - default page that is to be set,
+   * which determines whether a warning is issued or not.
    */
   const setDefaultPage = (incomingDefaultPage: DefaultPageType) => {
     if (defaultPageSet === true) {
diff --git a/packages/javascript/src/listener.ts b/packages/javascript/src/listener.ts
index 0599d780..3de61a2b 100644
--- a/packages/javascript/src/listener.ts
+++ b/packages/javascript/src/listener.ts
@@ -45,38 +45,50 @@ export async function createlistener(
 }
 
 /**
- * @description Creates a Flatfile listener that handles simple submissions and record
- * hooks. It uses the `FlatfileClient` class to interact with the Flatfile API and
- * listens for job "ready" events to handle submission and record hooks.
+ * @description Creates a Flatfile listener for the given slug, using the `FlatfileClient`
+ * API to interact with the Flatfile platform. It sets up an onRecordHook and an
+ * onSubmit action, if provided, and then filters the events emitted by the client
+ * to handle the onSubmit action.
  * 
- * @param {SimpleListenerType} .onRecordHook - hook function that is triggered after
- * each record has been processed during data ingestion, allowing for custom behavior
- * or actions to be taken on individual records.
+ * @param {SimpleListenerType} .onRecordHook - function to be called when a record
+ * is received, and allows for custom logic to be added before the record is processed
+ * by the Flatfile listener.
  * 
- * @param {SimpleListenerType} .onSubmit - onSubmit callback function that will be
- * called after a job is submitted, allowing it to process and respond to the event.
+ * @param {SimpleListenerType} .onSubmit - callback function that will be called when
+ * the submit action is completed successfully, with the `job`, `sheet`, and `event`
+ * objects as arguments.
  * 
- * @param {SimpleListenerType} .slug - unique identifier for the space where the
- * Flatfile data will be stored.
+ * @param {SimpleListenerType} .slug - slug of the workbook, which is used to identify
+ * the specific workbook for which the Flatfile listener is created and configured.
  * 
- * @param {SimpleListenerType} .submitSettings - 3rd party application's settings for
- * submitting data to the server, such as whether or not to delete the space after submission.
+ * @param {SimpleListenerType} .submitSettings - submit settings for the Flatfile
+ * listener, allowing you to customize how the listener handles submitted jobs.
  * 
- * @returns {FlatfileListener} a FlatfileClient instance that can be used to handle
- * Flatfile events.
+ * @returns {FlatfileListener} a Flatfile listener that listens for simple submissions
+ * and performs the specified actions on job ready events.
  * 
- * 	* `client`: A new FlatfileClient instance is created to handle listener functions.
- * 	* `use`: If `onRecordHook` is defined, a record hook is used to process records.
- * The hook function takes two arguments: `record` (the current record being processed)
- * and `event` (the event emitted by the flatfile client).
- * 	* `onSubmitSettings`: An object containing submit settings, which are merged with
- * the default settings provided in the `SimpleListenerType`.
- * 	* `jobId`, `spaceId`, `workbookId`: These properties represent the context of the
- * job being listened to, including the job ID, space ID, and workbook ID.
+ * 	* `client`: A FlatfileClient object that can be used to interact with the Flatfile
+ * API.
+ * 	* `onRecordHook`: An optional callback function that will be called when a record
+ * is hit in the Flatfile stream. The function takes two arguments: `record` (the
+ * recorded event) and `event` (the original event).
+ * 	* `onSubmit`: An optional callback function that will be called when a submission
+ * occurs. The function takes three arguments: `job`, `sheet`, and `event`. The `job`
+ * argument is an instance of JobHandler, the `sheet` argument is an instance of
+ * SheetHandler, and the `event` argument is an object containing information about
+ * the submission event.
+ * 	* `slug`: A unique identifier for the listener, used to differentiate between
+ * multiple listeners in a single space.
+ * 	* `submitSettings`: An optional object that contains settings for submission
+ * behavior. The properties of this object are:
+ * 		+ `deleteSpaceAfterSubmit`: A boolean value indicating whether the space should
+ * be archived after a successful submission.
  * 
- * 	In summary, the `createSimpleListener` function creates a new FlatfileClient
- * instance and sets up a simple listener to handle jobs and submits. It also allows
- * for customization of submit settings through the `onSubmitSettings` property.
+ * 	In summary, the `createSimpleListener` function takes in various configuration
+ * options and returns a FlatfileClient object with an optional onRecordHook callback
+ * function and an optional onSubmit callback function, as well as a unique slug
+ * identifier and an optionally passed submitSettings object containing space deletion
+ * settings after submission.
  */
 export const createSimpleListener = ({
   onRecordHook,
diff --git a/packages/javascript/src/startFlatfile.ts b/packages/javascript/src/startFlatfile.ts
index b7b5ef2e..a47231b6 100644
--- a/packages/javascript/src/startFlatfile.ts
+++ b/packages/javascript/src/startFlatfile.ts
@@ -10,19 +10,21 @@ import { createSimpleListener, createlistener } from './listener'
 import { displayError, initializeIFrameConfirmationModal } from './utils'
 
 /**
- * @description Sets up an Flatfile space for users. It generates a new space and
- * workbook if one does not exist, obtains the required resources, initializes the
- * embedded UI, and sets up listeners for authentication.
+ * @description Generates high-quality documentation for given code and handles
+ * onboarding for a Flatfile application, creating a space and workbook as needed,
+ * obtaining an access token for authentication with the Flatfile API, and displaying
+ * initial resources to the user.
  * 
- * @param {SimpleOnboarding | ISpace} options - flatfile configuration object that
- * provides various options for initialization, including display settings, space ID
- * and access token, listeners, and more.
+ * @param {SimpleOnboarding | ISpace} options - 3-level object containing information
+ * about the space creation, including properties like publishableKey, displayAsModal,
+ * baseUrl, and API URL, which are used to generate the corresponding values for the
+ * mount iframe configuration.
  * 
- * @returns {object} an object containing the space ID and other properties.
+ * @returns {object} an object containing the ID of the created space.
  */
 /**
- * @description Performs cleanup operations on an HTML document by removing event
- * listeners, DOM elements, and an iframe wrapper.
+ * @description Clears various elements associated with a web application. It removes
+ * message listeners, a specific HTML element, and an IFRAME wrapper.
  */
 export async function startFlatfile(options: SimpleOnboarding | ISpace) {
   function closeSpaceNow() {
diff --git a/packages/javascript/src/utils.ts b/packages/javascript/src/utils.ts
index 2e14d533..d282236e 100644
--- a/packages/javascript/src/utils.ts
+++ b/packages/javascript/src/utils.ts
@@ -2,26 +2,21 @@ import { ISpace } from '@flatfile/embedded-utils'
 import { createModal } from './createModal'
 
 /**
- * @description Creates an HTML division element with a heading and paragraph containing
- * an error message for display to the user.
+ * @description Creates an HTML element with a heading and a paragraph containing an
+ * error message, then returns the element.
  * 
- * @param {string} errorTitle - 1-line heading for the error message to be displayed
- * inside the `<h1>` element, which is appended to the parent HTML element.
+ * @param {string} errorTitle - heading element that is added to the error container.
  * 
- * @param {string} errorMessage - error message to be displayed next to the error
- * title in the generated container.
+ * @param {string} errorMessage - message to be displayed as an error alert to the
+ * user when the function is called.
  * 
- * @returns {HTMLDivElement} a HTML div element containing an error heading and message.
+ * @returns {HTMLDivElement} a HTML element containing an error title and message.
  * 
- * 	* `display`: This is an HTML `div` element that contains the error message and
- * heading. It has a class attribute set to `"ff_error_container"`.
- * 	* `title`: This is an HTML `h1` element that contains the error title. It has a
- * class attribute set to `"ff_error_heading"`.
- * 	* `error`: This is an HTML `p` element that contains the error message. It has a
- * class attribute set to `"ff_error_text"`
- * 
- * 	Overall, this function creates a basic structure for displaying an error message
- * and heading in a HTML container element.
+ * 	* `div`: The output is a `div` element with the class `ff_error_container`.
+ * 	* `h1`: The output includes an `h1` element with the class `ff_error_heading`
+ * containing the title specified in the `errorTitle` parameter.
+ * 	* `p`: The output includes an `p` element with the class `ff_error_text` containing
+ * the error message specified in the `errorMessage` parameter.
  */
 export const displayError = (errorTitle: string, errorMessage: string) => {
   const display = document.createElement('div')