@sitecore-feaas/clientside 0.2.1 → 0.2.2

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) {
@@ -33,8 +35,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 +93,7 @@ export class FEAASComponent extends FEAASElement<FEAASComponentsProps, string> {
   } as Partial<FEAASComponentsProps>
 
   needsRefresh: boolean
+
   setData(data: any) {
     this.set({ data })
   }
@@ -69,12 +104,34 @@ 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 +140,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 +187,58 @@ 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)
     }
   }
 }

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.
  *
@@ -137,6 +147,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[] {
@@ -251,6 +263,7 @@ export class FEAASElement<Props = any, Payload = any> extends WebComponent {
       } else if (this.payload == null) {
         return
       }
+
       this.flush()
       this.whenRendered.resolve(this)
     } catch (e) {

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,70 @@ 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 JSON schema, from which a configuration form will be produced using RJSF library. The library allows passing a
+   * UI schema that allows tight customization of form widgets, styles and its behavior.
+   *
+   * @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']
+   *   })
+   *
+   * @param {React.ComponentType} component React component that will be rendered.
+   * @param {string} options.name Component name as presented to the user.
+   * @param {string} options.title Component title to be used in the inputs form. Defaults to component name.
+   * @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
+   */
+  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 +217,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 +248,5 @@ declare global {
 FEAASExternal.register('feaas-external')
 FEAASExternal.setRegistrationCallback()
 
+export const registerComponent = FEAASExternal.registerComponent
 export { FEAASExternal as External }

package/src/ui/FEAASPicker.tsx

@@ -5,7 +5,7 @@ export function FEAASPickerProps(element: FEAASElement<any, any>) {
   return {
     part: element?.getAttribute('part') || 'picker',
     slot: element?.getAttribute('part') || 'picker',
-    mode: element?.getAttribute('mode') as 'library' | 'element' | 'themes',
+    mode: element?.getAttribute('mode') as 'library' | 'element' | 'themes' | 'datasources',
     placeholder: element?.getAttribute('placeholder') || 'No theme',
     frontend: element?.getContextAttribute('frontend') ?? 'https://components.sitecorecloud.io',
     src: element?.getAttribute('src') ?? '/picker.js',
@@ -32,7 +32,10 @@ export class FEAASPicker extends FEAASElement<FEAASPickerProps, typeof FEAASPick
   load() {
     return this.import(this.formatURL(this.props.src, this.props.frontend))
   }
-
+  connectedCallback() {
+    this.setAttribute('feaas-role', 'ui')
+    super.connectedCallback()
+  }
   render(
     { placeholder, context, mode, children, variant }: React.PropsWithChildren<FEAASPickerProps>,
     { Picker, React, useLibrary }: typeof FEAASPickerImports

package/src/ui/index.ts

@@ -1,4 +1,4 @@
-export * from '../headless.js'
-export * from './FEAASEditor.js'
-export * from './FEAASPicker.js'
-export * from './FEAASContext.js'
+export * from './FEAAS.js'
+import * as FEAAS from './FEAAS.js'
+
+FEAAS.Context.prototype.clientside = FEAAS

package/src/ui/react.tsx

@@ -1,7 +1,10 @@
+import { DatasourceModel, SDK } from '@sitecore-feaas/sdk'
+
 export * from './index.js'
 import { FEAASComponentProps, parseComponentSource } from './index.js'
 import React from 'react'
 import { renderHTMLContent } from '../dom/html.js'
+
 export { renderHTMLContent }
 export { External } from './FEAASExternal.js'
 
@@ -9,12 +12,14 @@ export function FEAASEmbed({ data, ...props }: FEAASComponentProps<any>) {
   if ('template' in props && props.template) {
     var html = renderHTMLContent(props.template, data || {})
   }
+
   if ('src' in props) {
     props = {
       ...parseComponentSource(props.src),
       ...props
     }
   }
+
   return (
     <feaas-component
       {...props}

package/src/utils/fetch.ts

@@ -0,0 +1,44 @@
+type Data = object | any[]
+
+type DataSettings = { jsonpath: string; url: string }
+
+export const isDataSettings = (data: any): data is DataSettings =>
+  typeof data === 'object' && 'jsonpath' in data && 'url' in data
+
+const performFetch = async (
+  settings: Parameters<typeof fetch>[1] & {
+    url: Parameters<typeof fetch>[0]
+  }
+): Promise<Data> => {
+  try {
+    const response = await fetch(settings.url, settings)
+
+    if (!response) return {}
+
+    return await response.json()
+  } catch (e) {
+    return {}
+  }
+}
+
+export async function fetchData(data: DataSettings | Record<string, DataSettings | Data> | Data): Promise<Data> {
+  if (!data) return data
+
+  console.log(data)
+
+  if (isDataSettings(data)) return performFetch(data)
+
+  const keys = Object.keys(data)
+
+  const allRequests = await Promise.all(
+    keys.map((key: keyof typeof data) => (isDataSettings(data[key]) ? performFetch(data[key]) : null)).filter(Boolean)
+  )
+
+  return keys.reduce(
+    (obj, key: keyof typeof data) => ({
+      ...obj,
+      [key]: isDataSettings(data[key]) ? allRequests.shift() : data[key]
+    }),
+    {}
+  )
+}

package/test/FEAASComponent.test.tsx

@@ -6,6 +6,7 @@ import { clearFetchCache } from '../src/fetch.js'
 const earliest = new Date(2000, 1, 1, 0, 0, 0)
 const earlier = new Date(2000, 1, 2, 0, 0, 0)
 const now = new Date(2000, 1, 2, 12, 0, 0)
+
 describe('Components', () => {
   beforeAll(() => {
     // vi.useFakeTimers()