@sitecore-feaas/clientside 0.2.1 → 0.3.0

package/scripts/build.js

@@ -3,6 +3,7 @@ import * as esbuild from 'esbuild'
 import replace from 'esbuild-plugin-replace-regex'
 import * as url from 'url'
 import fs from 'fs'
+
 const __filename = url.fileURLToPath(import.meta.url)
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
 
@@ -17,7 +18,6 @@ function compile({ input, output, ...step }) {
     bundle: true,
     write: false,
     external: ['node:crypto', 'node-fetch', '_MAGIC_IMPORT_COMMENTS_ESBUILD_WORKAROUND__', 'react', 'react-dom', 'vm'],
-
     ...step,
 
     minify: true,

package/src/components/FEAASComponent.tsx

@@ -1,6 +1,8 @@
 import { DEFAULT_CDN_URL, FEAASCDNComponentParams, fetchAndRevalidateComponent, parseComponentSource } from '../cdn.js'
 import { renderDOMContent, renderDOMElement } from '../dom/rendering.js'
 import { loadStylesheetAllowStale } from '../headless.js'
+import { ControlledPromise } from '../utils/promise.js'
+import { fetchData } from '../utils/fetch.js'
 import { FEAASElement } from './FEAASElement.js'
 
 export function FEAASComponentsProps(element: FEAASElement) {
@@ -11,12 +13,17 @@ export function FEAASComponentsProps(element: FEAASElement) {
     if (!parsed) throw new Error(`Could not parse FEAAS Component source: ${src}`)
     var { cdn, library, component, version, revision } = parsed
   }
+
   const dataValue = element.getAttribute('data')
+
   if (dataValue != null && dataValue != '') {
     try {
       data = typeof dataValue == 'string' ? JSON.parse(dataValue) : {}
-    } catch (e) {}
+    } catch (e) {
+      console.error(e)
+    }
   }
+
   return {
     data: data || {},
     cdn: element.getContextAttribute('cdn') ?? cdn ?? DEFAULT_CDN_URL,
@@ -33,8 +40,40 @@ export function FEAASComponentsProps(element: FEAASElement) {
     withStylesheet: element.getAttribute('with-stylesheet') != 'false'
   }
 }
+
 export type FEAASComponentsProps = ReturnType<typeof FEAASComponentsProps>
+
+/**
+ * - Initialization lifecycle:
+ * - - `set(props)`
+ * - - `scheduleRender()` - any attribute change causes render to schedule to next frame
+ * - - `whenRendered.restart()` - rendering promise is reset and will resolve after render
+ * - - `advance()` - called on next frame
+ * - - `if (isReadyToLoad()) => boolean` - check if component has all necessary properties to load
+ * - - `load() => payload` => component is loaded
+ * - - `onLoad?(payload)` => invoke loaded callback for cached version of a component
+ * - - `advance()` => going further in state machine
+ * - - `flush()` => flushes all react changes if needed
+ * - - `update()` => component-specific method (or react) to render changes to dom
+ * - - `render(payload, props)` => render means react
+ * - - `whenRendered.resolve()` - rendering promise is resolved after rendering
+ * - - IF CACHE WAS STALE - FETCH AND RENDER AGAIN
+ * - - `fetchByPassingCache()` - load up-to-date version of a component
+ * - - `onLoad(newPayload) `
+ * - - `advance()` => going further in state machine
+ * - - `flush()` => flushes all react changes if needed
+ * - - `update()` => component-specific method (or react) to render changes to dom
+ * - - `render(payload, props)` => render means react
+ * - - `whenRendered.resolve()` - rendering promise is resolved after rendering
+ * - - `whenLoaded.resolved()` - resolved after loading of up to date component
+ */
 export class FEAASComponent extends FEAASElement<FEAASComponentsProps, string> {
+  readyData: any = {}
+  whenDataReady = ControlledPromise<any>(
+    (data) => (this.readyData = data),
+    (e) => this.onError(e)
+  )
+
   static observedAttributes = [
     'library',
     'component',
@@ -59,6 +98,7 @@ export class FEAASComponent extends FEAASElement<FEAASComponentsProps, string> {
   } as Partial<FEAASComponentsProps>
 
   needsRefresh: boolean
+
   setData(data: any) {
     this.set({ data })
   }
@@ -69,12 +109,35 @@ export class FEAASComponent extends FEAASElement<FEAASComponentsProps, string> {
 
   attributeChangedCallback(name: string, oldValue: string, newValue: string): void {
     if (oldValue === newValue) return
+
     // force component to be refreshed
     if (name == 'library' || name == 'component' || name == 'revision' || name == 'version') {
       this.payload = undefined
     }
+
     this.needsRefresh = true
+
     super.attributeChangedCallback(name, oldValue, newValue)
+
+    if (name === 'data') {
+      this.fetchData()
+    }
+  }
+
+  // Reset readyData and perform a new fetch.
+  async fetchData() {
+    this.readyData = undefined
+
+    this.whenDataReady = this.whenDataReady.restart()
+
+    const data = await fetchData(this.props.data)
+
+    const alreadyRendered = this.alreadyRendered
+
+    await this.whenDataReady.resolve(data)
+    if (alreadyRendered) {
+      this.advance()
+    }
   }
 
   getEditor(): any {
@@ -83,6 +146,11 @@ export class FEAASComponent extends FEAASElement<FEAASComponentsProps, string> {
 
   constructor() {
     super()
+
+    if (!this.getAttribute('data')) {
+      this.whenDataReady.resolve({})
+    }
+
     this.addEventListener('click', () => {
       if (this.props.editable) {
         this.edit()
@@ -125,36 +193,57 @@ export class FEAASComponent extends FEAASElement<FEAASComponentsProps, string> {
 
   async load() {
     // defer loading to original element
-    if (this.getOriginal()) {
-      return
+    if (this.getOriginal()) return
+
+    const advanceIfEverythingIsReady = () => {
+      // html is not loaded
+      if (!this.payload) return
+
+      // shared stylesheet is still being loaded
+      if (stylesheetPromise) return
+
+      // data is still loading
+      if (!this.readyData) return
+
+      this.onLoad(this.payload)
     }
+
     if (this.props.withStylesheet) {
       var stylesheetPromise = loadStylesheetAllowStale({ ...this.props, revision: 'published' }).then(() => {
         stylesheetPromise = null
-        if (this.payload) {
-          this.onLoad(this.payload)
-        }
+        advanceIfEverythingIsReady()
       })
     }
+
     return Promise.all([
       stylesheetPromise,
+      this.whenDataReady.then(() => advanceIfEverythingIsReady()),
       fetchAndRevalidateComponent(this.props, (html) => {
         this.payload = html
-        if (!stylesheetPromise) this.onLoad(html)
+        advanceIfEverythingIsReady()
       })
     ]).then(() => this.payload)
   }
 
+  alreadyRendered: boolean
+
+  flush() {
+    if (!this.readyData) return
+
+    super.flush()
+  }
+
   update() {
+    this.alreadyRendered = true
     if (Array.from(this.children).filter((c) => c.tagName != 'BR').length > 0 && !this.needsRefresh) {
-      renderDOMElement(this, this.props.data)
+      renderDOMElement(this, this.readyData)
     } else {
       this.needsRefresh = true
       // defer rendering to original element
       if (this.getOriginal()) {
         return
       }
-      renderDOMContent(this, this.payload, this.props.data)
+      renderDOMContent(this, this.payload, this.readyData)
     }
   }
 }
@@ -173,7 +262,9 @@ declare global {
         'with-stylesheet'?: 'false' | 'true' | ''
       } & (
         | {
-            /** @deprecated Use cdn instead */
+            /**
+             * @deprecated Use cdn instead.
+             */
             hostname?: string
             cdn?: string
             library: string

package/src/components/FEAASElement.tsx

@@ -21,6 +21,16 @@ export interface ReactPayload {
   ReactDOM: typeof ReactDOM
   ReactDOMClient: typeof ReactDOMClient
 }
+
+declare global {
+  interface DocumentEventMap {
+    feaasMount: Event
+    feaasUnmount: Event
+    feaasLoad: Event
+    feaasError: CustomEvent<Error>
+  }
+}
+
 /**
  * FEAASElement is a superclass for FEAAS components with optional react support.
  *
@@ -108,7 +118,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
       if (this.connected) return
       this.connected = true
       this.log('FEAAS: Mount', this.tagName, this)
-      this.dispatchEvent(new Event('feaasMount', { bubbles: true, composed: true }))
+      this.dispatchEventIndirectly(new Event('feaasMount', { bubbles: true, composed: true }))
       this.getElements().map((element: FEAASElement) => element.mount?.())
       this.set()
     } catch (e) {
@@ -116,6 +126,17 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
     }
   }
 
+  dispatchEventIndirectly(event: Event) {
+    this.dispatchEvent(event)
+    const parent = this.getParent() as FEAASElement
+
+    if (parent && !parent.contains(this)) {
+      Object.defineProperty(event, 'target', { value: this, writable: false })
+      Object.defineProperty(event, 'composedPath', { value: () => [this], writable: false })
+      parent.handleEvent(event)
+    }
+  }
+
   log(...args: any) {
     if (typeof process != 'undefined' && process.env.TESTING) return
     console.log(...args)
@@ -125,7 +146,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
   unmount() {
     if (!this.connected) return
     this.log('FEAAS: Unmount', this)
-    this.dispatchEvent(new Event('feaasUnmount', { bubbles: true, composed: true }))
+    this.dispatchEventIndirectly(new Event('feaasUnmount', { bubbles: true, composed: true }))
     this.connected = false
   }
 
@@ -137,6 +158,8 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
     ) {
       if (!onlyFeaas || p.tagName.startsWith('FEAAS-')) return p
     }
+    // feaas context anywhere in the dom acts as a root element
+    if (this.tagName != 'FEAAS-CONTEXT') return document.querySelector('feaas-context')
   }
 
   getElements(root: HTMLElement | ShadowRoot = this.getRoot(), onlyFeaas = true): HTMLElement[] {
@@ -170,7 +193,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
     const index = this.descendants.indexOf(target)
     if (index == -1) return
     this.log('FEAAS: Unnest', this, target)
-    this.descendants.splice(index, -1)
+    this.descendants.splice(index, 1)
     this.refs[target.getComponentName()] = null
     if (target.refs.parent == this) target.refs.parent = null
     if (target.refs.top == this) {
@@ -212,7 +235,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
   /** Generic error handler */
   onError(error: Error, where: string = 'uncaught', handled = false) {
     const event = new CustomEvent('feaasError', { bubbles: true, composed: true, detail: error })
-    this.dispatchEvent(event)
+    this.dispatchEventIndirectly(event)
     this.whenLoaded.reject(error)
     if (!event.defaultPrevented && !handled) {
       this.whenRendered.reject(error)
@@ -236,7 +259,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
       if (this.payload === undefined) {
         if (!this.isReadyToLoad()) return
         this.payload = null
-        this.dispatchEvent(new Event('feaasLoad', { bubbles: true, composed: true }))
+        this.dispatchEventIndirectly(new Event('feaasLoad', { bubbles: true, composed: true }))
         const loaded = await this.load().catch((e) => {
           this.payload = undefined
           throw e
@@ -251,6 +274,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
       } else if (this.payload == null) {
         return
       }
+
       this.flush()
       this.whenRendered.resolve(this)
     } catch (e) {
@@ -259,6 +283,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
   }
 
   flush() {
+    if (!this.connected) return
     const flushSync = (this.payload as ReactPayload)?.ReactDOM?.flushSync
     if (flushSync) {
       flushSync(() => this.update())

package/src/dom/rendering.ts

@@ -192,6 +192,7 @@ export function renderDOMElement(
   }
   return element
 }
+
 function isElement(node: Node): node is HTMLElement {
   return node.nodeType == 1
 }

package/src/dom/thumbnail.ts

@@ -25,9 +25,9 @@ export const responseToImage = (response: Response): Promise<HTMLImageElement> =
  * The function ensures that the version data for the component is available and selects the one that is most suitable
  * for a display width of 800 pixels.
  *
- * @param {ComponentModel} component - The component for which the version needs to be obtained.
+ * @param {ComponentModel} component  - The component for which the version needs to be obtained.
  * @returns {Promise<VersionModel>} - A promise that resolves to the most suitable version for a display width of 800
- *   pixels.
+ *                                  pixels.
  */
 export async function getVersionForThumbnail(component: ComponentModel): Promise<VersionModel> {
   if (!component.versions.length) await component.versions.fetch()
@@ -45,9 +45,9 @@ export async function getVersionForThumbnail(component: ComponentModel): Promise
  * 1. The first call can happen with the stale cached or outdated image.
  * 2. The second call occurs with the up-to-date loaded or freshly generated generated image.
  *
- * @param {ComponentModel} component - Relevant component.
- * @param {VersionModel} [version] - Relevant version (optional, falls back to responsive).
- * @param {Callback} [callback] - Callback to handle the loaded or generated image (optional).
+ * @param {ComponentModel} component   - Relevant component.
+ * @param {VersionModel}   [version]   - Relevant version (optional, falls back to responsive).
+ * @param {Callback}       [callback]  - Callback to handle the loaded or generated image (optional).
  * @returns {Promise<HTMLImageElement | null>} - The final thumbnail image (either loaded or freshly generated).
  */
 export async function get(component: ComponentModel, version?: VersionModel, callback?: Callback) {
@@ -83,16 +83,16 @@ export async function get(component: ComponentModel, version?: VersionModel, cal
  *
  * 1. The first call occurs if the image was previously cached by the browser, but the cache is stale.
  * 2. The second call happens when the image is updated from a fresh download. By this design, the user gets to see a
- *    cached image immediately while the updated image is being downloaded in the background.
+ * cached image immediately while the updated image is being downloaded in the background.
  *
  * If the version of a component is known to be newer than remote file, the function will throw `InvalidResponse` error.
  * As a way to handle that error, the `generate` function may be used to produce new thumbnail (@see render).
  *
- * @param {ComponentModel} component - The component to load a thumbnail for.
- * @param {VersionModel} [version] - The version of the component to load a thumbnail for. If not provided, a version
- *   suitable for a responsive component is selected.
- * @param {Callback} [callback] - A callback to handle the loaded image. This callback may be invoked twice for the
- *   reasons described above.
+ * @param {ComponentModel} component   - The component to load a thumbnail for.
+ * @param {VersionModel}   [version]   - The version of the component to load a thumbnail for. If not provided, a
+ *                                     version suitable for a responsive component is selected.
+ * @param {Callback}       [callback]  - A callback to handle the loaded image. This callback may be invoked twice for
+ *                                     the reasons described above.
  * @returns {Promise<HTMLImageElement>} - The thumbnail image for the component/version combination.
  */
 export async function load(
@@ -143,8 +143,8 @@ export async function load(
  * thumbnail. It then leverages `render` to generate an image with provided parameters and finally, if the component
  * isn't new, uploads the generated as a Blob onto cdn for future retrieval.
  *
- * @param {ComponentModel} component - Component instance.
- * @param {VersionModel} [version] - Version instance.
+ * @param {ComponentModel} component  - Component instance.
+ * @param {VersionModel}   [version]  - Version instance.
  * @returns {Promise<HTMLImageElement | null>} Thumbnail image or null if generation isn't possible.
  */
 export async function generate(component: ComponentModel, version?: VersionModel) {
@@ -174,15 +174,15 @@ export async function generate(component: ComponentModel, version?: VersionModel
  * injected into the iframe to capture the rendered component as an image. The image is created respecting the provided
  * design breakpoint, ensuring an accurate visual representation.
  *
- * @param {string[]} classList - Array of class names applied to the rendered component.
- * @param {Style.Rule<'breakpoint'>} breakpoint - Breakpoint style rule that dictates the viewport dimensions for
- *   rendering.
- * @param {string} template - String template of the component to render.
- * @param {any} data - Data object to be used when rendering the component.
- * @param {string} cssText - CSS rules to be applied during component rendering.
- * @param {EnvironmentVariables} env - Environment variables used to set frontend and backend endpoint URLs.
+ * @param {string[]}                 classList   - Array of class names applied to the rendered component.
+ * @param {Style.Rule<'breakpoint'>} breakpoint  - Breakpoint style rule that dictates the viewport dimensions for
+ *                                               rendering.
+ * @param {string}                   template    - String template of the component to render.
+ * @param {any}                      data        - Data object to be used when rendering the component.
+ * @param {string}                   cssText     - CSS rules to be applied during component rendering.
+ * @param {EnvironmentVariables}     env         - Environment variables used to set frontend and backend endpoint URLs.
  * @returns {Promise<BasicImage>} - Promise that resolves to an object containing the src, width, and height of the
- *   created image.
+ *                                created image.
  */
 function render(
   classList: string[],
@@ -239,8 +239,13 @@ function render(
       ${cssText}
       body, html { padding: 0; margin: 0; overflow: hidden }
     `
+    const stylesheet2 = iframe.contentWindow.document.createElement('style')
+    stylesheet2.textContent = `
+      body, html { padding: 0; margin: 0; overflow: hidden }
+    `
 
     iframe.contentWindow.document.head.appendChild(stylesheet)
+    iframe.contentWindow.document.head.appendChild(stylesheet2)
     const root = renderComponent({ template, data })
     root.classList.add(...classList, '-feaas--preview', '-emulate--' + breakpoint.details.slug)
     iframe.contentWindow.document.body.appendChild(root)
@@ -254,9 +259,9 @@ function render(
  * several metadata points, including identifiers and timestamps. Upon successful upload, it sends a no-cache fetch
  * request to the constructed URL to bust the cache.
  *
- * @param {ComponentModel} component - Component instance.
- * @param {VersionModel} version - Version instance.
- * @param {Blob} blob - Blob instance to upload.
+ * @param {ComponentModel} component  - Component instance.
+ * @param {VersionModel}   version    - Version instance.
+ * @param {Blob}           blob       - Blob instance to upload.
  * @returns {Promise<string>} URL of the uploaded Blob.
  */
 export async function upload(component: ComponentModel, version: VersionModel, blob: Blob): Promise<string> {

package/src/headless.ts

@@ -19,6 +19,11 @@ export * from './components/FEAASComponent.js'
 export * from './components/FEAASLoader.js'
 export * from './components/FEAASStylesheet.js'
 export * from './utils/datapath.js'
+export * as DOM from './dom/rendering.js'
+export * as Datascope from './dom/data.js'
+export * as Datapath from './utils/datapath.js'
+export * from './utils/fetch.js'
+export * as DataSettings from './utils/settings.js'
 export * as Thumbnail from './dom/thumbnail.js'
 
 declare global {

package/src/ui/FEAAS.tsx

@@ -0,0 +1,4 @@
+export * from '../headless.js'
+export * from './FEAASEditor.js'
+export * from './FEAASPicker.js'
+export * from './FEAASContext.js'

package/src/ui/FEAASContext.tsx

@@ -2,11 +2,14 @@ import type * as FEAASContextImports from '@sitecore-feaas/frontend/context'
 import type { AuthModel } from '@sitecore-feaas/sdk'
 import { FEAASElement, OptionalExcept } from '../components/FEAASElement.js'
 import { ControlledPromise } from '../utils/promise.js'
+import type * as FEAAS from './index.js'
 
 export function FEAASContextProps(element: HTMLElement) {
   return {
     library: element?.getAttribute('library') as string,
     src: element?.getAttribute('src') ?? '/context.js',
+    // override environment
+    environment: element?.getAttribute('environment') ?? undefined,
     frontend: element?.getAttribute('frontend') ?? 'https://components.sitecorecloud.io',
     backend: element?.getAttribute('backend') ?? 'https://components.sitecorecloud.io/api',
     cdn: element?.getAttribute('cdn') ?? 'https://feaas.blob.core.windows.net',
@@ -60,6 +63,7 @@ export class FEAASContext extends FEAASElement<FEAASContextProps, typeof FEAASCo
 
   /** Pull in children FEAAS react elements into the shadow DOM so they receieve the styles */
   connectedCallback() {
+    this.setAttribute('feaas-role', 'ui')
     //if (this.props.isolate)
     Array.from(this.children).forEach((child) => {
       this.getRoot().appendChild(child)
@@ -75,6 +79,7 @@ export class FEAASContext extends FEAASElement<FEAASContextProps, typeof FEAASCo
   }
 
   sdk: FEAASContextImports.SDK
+  clientside: typeof FEAAS
   onStatusChange: FEAASContextImports.SDKStatusCallback = (status, sdk) => {
     if (status == 'ready') {
       this.whenSDKReady.resolve(sdk)
@@ -99,6 +104,7 @@ export class FEAASContext extends FEAASElement<FEAASContextProps, typeof FEAASCo
     }
     return (
       <AppContext
+        environment={this.props.environment as any}
         backend={this.props.backend}
         libraryId={this.props.library}
         container={this.getRoot()}
@@ -109,7 +115,7 @@ export class FEAASContext extends FEAASElement<FEAASContextProps, typeof FEAASCo
           portalProps
         }}
         chakraProps={{
-          resetScope: '.feaas-reset',
+          resetScope: ':where([feaas-role="ui"])',
           cssVarsRoot: ':host',
           resetCSS: true,
           toastOptions: {
@@ -129,6 +135,9 @@ declare global {
       'feaas-context': OptionalExcept<FEAASContextProps, 'library'>
     }
   }
+  interface DocumentEventMap {
+    feaasReady: CustomEvent<FEAASContextImports.SDK>
+  }
 }
 
 export { FEAASContext as Context }

package/src/ui/FEAASExternal.tsx

@@ -4,7 +4,7 @@ import { FEAASElement } from '../components/FEAASElement.js'
 import { ReactJSX, ReactModules } from '../components/FEAASReactElement.js'
 import { kebabCase, reverseKebabCase } from '../utils/string.js'
 import { Component, FEAASComponentProps } from './react.js'
-import type { ExternalComponent, ExternalComponentOptions } from '@sitecore-feaas/sdk'
+import type { ExternalComponent, ExternalComponentOptions, JSONSchema, UISchema } from '@sitecore-feaas/sdk'
 
 /** Checks if title exists in a property and if not, it generates it from (kebab-cased) property key */
 const addTitles = (properties: { [key: string]: any }) =>
@@ -21,13 +21,14 @@ const addTitles = (properties: { [key: string]: any }) =>
     return acc
   }, {})
 
+/** Converts the keys of an object to kebab case. */
 const objectKeysToKebabCase = (object: { [key: string]: any } = {}) =>
   Object.keys(object).reduce((acc: { [key: string]: any }, key) => {
     acc[kebabCase(key)] = object[key]
     return acc
   }, {})
 
-const transformSchema = (schema: ExternalComponent['schema']) => {
+const transformSchema = (schema: JSONSchema) => {
   if (!schema) return
   if (!schema.properties) return schema
   let properties, required
@@ -44,9 +45,9 @@ const transformSchema = (schema: ExternalComponent['schema']) => {
   return { ...schema, properties, required, title }
 }
 
-const transformUiSchema = (uiSchema: ExternalComponent['uiSchema'], properties: { [key: string]: any }) => {
+const transformUiSchema = (uiSchema: UISchema, properties: { [key: string]: any }) => {
   if (!uiSchema || !properties) return
-  let transformed: ExternalComponent['uiSchema']
+  let transformed: UISchema
 
   /* kebab-case keys */
   transformed = objectKeysToKebabCase(uiSchema)
@@ -60,12 +61,8 @@ const transformUiSchema = (uiSchema: ExternalComponent['uiSchema'], properties:
 
   return transformed
 }
-
-export const parseProps = (
-  propName: string,
-  propValue: string,
-  properties: ExternalComponent['schema']['properties']
-) => {
+/** Parses a property value based on its property name and type defined in the JSON properties object. */
+export const parseProps = (propName: string, propValue: string, properties: JSONSchema['properties']) => {
   //@ts-ignore
   switch (properties?.[propName]?.type) {
     case 'string':
@@ -88,7 +85,7 @@ export const parseProps = (
 export function FEAASExternalProps(element: FEAASElement) {
   const attributes = element.getAttributeNames()
   const id = element.getAttribute('data-external-id')
-  const schema: ExternalComponent['schema'] = FEAASExternal.registered[id]?.schema
+  const schema: JSONSchema = FEAASExternal.registered[id]?.schema
   const props = attributes.reduce((prev, curr) => {
     if (!curr.startsWith('data-attribute') && !['class', 'id', 'contenteditable'].includes(curr)) {
       const value = element.getAttribute(curr)
@@ -123,11 +120,72 @@ export default class FEAASExternal extends FEAASElement<FEAASExternalProps, Reac
     return FEAASExternalProps(this)
   }
 
-  static registerComponent(component: React.FC, options: ExternalComponentOptions = {}) {
-    const id = options.name || component.name
+  /**
+   * Register React component to be renderable as Sitecore component (in Components and Pages). Properties are defined
+   * as {@link https://json-schema.org JSON Schema}, from which a configuration form will be produced using
+   * {@link https://rjsf-team.github.io/react-jsonschema-form/ RJSF library}. The library allows passing a
+   * {@link https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema UI Schema} that allows tight
+   * customization of form widgets, styles and behavior.
+   *
+   * @param {React.ComponentType}      component                     React component that will be rendered.
+   * @param {string}                   options.title                 Component name as presented to the user.
+   * @param {JSONSchema['properties']} options.properties            Object of properties.
+   * @param {JSONSchema['type']}       options.properties[].type     JSON Schema type of a property.
+   * @param {string}                   [options.properties[].title]  Optional title displayed to the user.
+   * @param {string}                   [options.group]               Optional Image to be displayed in the UI.
+   * @param {string}                   [options.thumbnail]           Optional title displayed to the user.
+   * @param {UISchema}                 [options.ui]                  Optional component groupping.
+   * @see https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema
+   * @see https://json-schema.org
+   * @example
+   *
+   *   FEAAS.External.registerComponent(MyComponent, {
+   *     // Name of a component as it will be presented to the user
+   *     name: 'My Component',
+   *     // Title of a component as it will be presented in the inputs form
+   *     title: 'My Component',
+   *     // Optional: Thumbnail image for component to be displayed in UI
+   *     thumbnail: 'http://examaple.com/component.jpg',
+   *     // Optional: Group components by name
+   *     group: 'Assorted components',
+   *     // Definitions of three configurable properties that MyComponent accepts
+   *     properties: {
+   *       // Color is a string, but only Red/Green/Blue are allowed
+   *       color: { type: 'string', enum: ['red', 'green', 'blue'] },
+   *       // Text is a property labelled as "Text summary"
+   *       text: { type: 'string', title: 'Text summary' },
+   *       // Count is a number with 1 as default value
+   *       count: { type: 'number', default: 1 }
+   *     },
+   *     // Optional UI schema customization
+   *     ui: {
+   *       // Present color choices as radio buttons
+   *       color: { 'ui:widget': 'radio' },
+   *       // Text is a textarea with 5 rows
+   *       text: { 'ui:widget': 'textarea', 'ui:options': { rows: 5 } },
+   *       // Count is a number field with spinner button
+   *       count: { 'ui:widget': 'updown' }
+   *     },
+   *     // Color and text area required properties
+   *     required: ['color', 'text']
+   *   })
+   *
+   */
+  static registerComponent(component: React.ComponentType, options: ExternalComponentOptions) {
+    if (!options.name)
+      throw new Error('Could not register external component. Please make sure you provide a name in the options')
+    const id = options.name
     const { thumbnail, group, ui: uiSchema, ...schemaOptions } = options
-    const schema = { ...schemaOptions, type: 'object' } as ExternalComponent['schema']
-    FEAASExternal.registered[id] = { component, schema, uiSchema, thumbnail, group, title: schema?.title || id }
+    const schema = { ...schemaOptions, type: 'object' } as JSONSchema
+    FEAASExternal.registered[id] = {
+      component,
+      name: id,
+      schema,
+      uiSchema,
+      thumbnail,
+      group,
+      title: schema?.title || id
+    }
     FEAASExternal.setRegistrationCallback()
   }
 
@@ -161,7 +219,7 @@ export default class FEAASExternal extends FEAASElement<FEAASExternalProps, Reac
 
   /*static loadComponents() {
     const components = JSON.parse(sessionStorage.getItem('feaas-external-components'))
-    components.forEach((c: { name: string; schema: any; component: React.FC }) => {
+    components.forEach((c: { name: string; schema: any; component: React.ComponentType }) => {
       const name = c.name
       const schema = c.schema
       const component = eval('(' + c.component + ')')
@@ -192,4 +250,5 @@ declare global {
 FEAASExternal.register('feaas-external')
 FEAASExternal.setRegistrationCallback()
 
+export const registerComponent = FEAASExternal.registerComponent
 export { FEAASExternal as External }