@sitecore-feaas/clientside 0.1.27 → 0.1.29

package/src/cdn.ts

@@ -0,0 +1,188 @@
+import {
+  fetchAndRevalidate,
+  fetchWithCacheAwareness,
+  fetchBypassingCache,
+  fetchToValidateCache,
+  ValidatableRequestPhase
+} from './fetch.js'
+
+export const DEFAULT_CDN_URL = `https://feaascomponentsapidev.blob.core.windows.net`
+export type FEAASCDNComponentParams = {
+  cdn?: string
+  revision?: 'staging' | 'published' | 'saved' | number
+  library: string
+  component: string
+  version: string
+
+  /** @deprecated Use `cdn` instead */
+  hostname?: string
+}
+export type FEAASCDNComponentSource = {
+  src: string
+}
+export type FEAASCDNComponentParamsCustomizations = {
+  instance?: string
+}
+export type FEAASCDNComponentProps = (FEAASCDNComponentParams | FEAASCDNComponentSource) &
+  FEAASCDNComponentParamsCustomizations
+
+export interface FEAASCDNStylesheetParams {
+  cdn?: string
+  library: string
+  revision?: 'staging' | 'published' | 'saved' | number
+
+  /** @deprecated Use `cdn` instead */
+  hostname?: string
+}
+
+export type FEAASCDNStylesheetSource = {
+  src: string
+}
+export type FEAASCDNStylesheetProps = FEAASCDNStylesheetParams | FEAASCDNStylesheetSource
+
+export function parseComponentSource(source: string): FEAASCDNComponentParams {
+  const match = source.match(/^(?:(.*?)\/components)?\/?([^\/]+)\/([^\/]+)(?:\/([^\/]+)(?:\/([^\/]+?)(?:\.html?)?)?)?$/)
+  if (match) {
+    var [, cdn, library, component, version, revision] = match
+    return { cdn, library, component, version, revision: revision as any }
+  }
+}
+export function getComponentSource(props: FEAASCDNComponentParams) {
+  if (!props || !props.library || !props.component)
+    throw new Error('Component requires `library` and `component` properties')
+  return `${props.cdn && props.cdn != DEFAULT_CDN_URL ? `${props.cdn}/components` : ''}/${props.library}/${
+    props.component
+  }/${
+    !props.version || (props.version == 'responsive' && (!props.revision || props.revision == 'published'))
+      ? ''
+      : props.version
+  }/${!props.revision || props.revision == 'published' ? '' : props.revision}`.replace(
+    /(^\/|\/$|(?<!:)\/\/)(?!.+\/components\/)/g,
+    ''
+  )
+}
+
+export function getStylesheetSource(props: FEAASCDNStylesheetParams) {
+  return `${props.cdn && props.cdn != DEFAULT_CDN_URL ? `${props.cdn}/styles` : ''}/${props.library}/${
+    props.revision == 'published' ? '' : props.revision
+  }`.replace(/^\/|\/$|(?<!:)\/\//g, '')
+}
+
+export function parseStylesheetSource(source: string): FEAASCDNStylesheetParams {
+  const match = source.match(/^(?:(.*?)\/styles)?\/([^\/]+)\/([^\/]+)(?:.css?)?$/)
+  if (match) {
+    var [, cdn, library, revision] = match
+    return { cdn, library, revision: revision as any }
+  }
+}
+export function getComponentURL(props: FEAASCDNComponentProps) {
+  if ('src' in props) {
+    props = {
+      ...parseComponentSource(props.src)
+    }
+  }
+  return `${props.cdn || props.hostname || DEFAULT_CDN_URL}/components/${props.library}/${props.component}/${
+    props.version
+  }/${props.revision || 'published'}.html`
+}
+
+export function getStylesheetURL(props: FEAASCDNStylesheetProps) {
+  if ('src' in props) {
+    props = {
+      ...parseComponentSource(props.src)
+    }
+  }
+  return `${props.cdn || props.hostname || DEFAULT_CDN_URL}/styles/${props.library}/${
+    props.revision || 'published'
+  }.css`
+}
+
+export async function fetchAndRevalidateComponent(
+  props: FEAASCDNComponentProps,
+  callback?: (html: string) => void,
+  dontRevalidate = false
+) {
+  const onlyIfNotDeleted = (response: Response) => {
+    return response.headers.get('x-ms-meta-versionDeletedAt') == null
+  }
+  const parseResponse = (response: Response) => {
+    return response.clone().text().then(callback)
+  }
+
+  // Fetch two requests in parallel: One optimistically checking if component was forked,
+  // and another checking original definition of a component
+  const results = await Promise.all([
+    props.instance &&
+      fetchWithCacheAwareness({
+        options: {
+          headers: {
+            Accept: 'text/html'
+          }
+        },
+        url: getComponentURL({ ...props, version: props.instance }),
+        validator: onlyIfNotDeleted
+      }).catch((e) => e as Error),
+    fetchWithCacheAwareness({ url: getComponentURL(props), validator: onlyIfNotDeleted }).catch((e) => e as Error)
+  ])
+  const result = results.find((result) => result && 'isCached' in result && result)
+  if (!result || result instanceof Error) {
+    const error = results.find((result) => result && result instanceof Error)
+    throw error || new Error('Can not fetch component')
+  }
+  if (results[0] == result) {
+    console.log('Using fork!', results)
+  }
+  await parseResponse(result.response)
+  if (dontRevalidate) return result
+  return fetchToValidateCache({ ...result, callback: parseResponse }).catch((e) => {
+    if (results[0] == result) {
+      fetchBypassingCache({ ...result, callback: null, validator: null })
+      console.log('Fork was deleted')
+      // forked version was cached, but it's now deleted
+      if (!(results[1] instanceof Error)) {
+        parseResponse(results[1].response)
+        return fetchToValidateCache({ ...results[1], callback: parseResponse })
+      }
+    }
+    throw e
+  })
+}
+
+/** Fetches HTML of a component. */
+export async function fetchComponent(props: FEAASCDNComponentProps | string) {
+  if (typeof props == 'string') props = { src: props }
+  var template: string
+  const { response } = await fetchAndRevalidateComponent(
+    props,
+    (result) => {
+      template = result
+    },
+    true
+  )
+  return { ...props, template, lastModified: response.headers.get('last-modified') }
+}
+
+export type ValidatableStylesheetCallback = (css: string, phase: ValidatableRequestPhase) => void
+export async function fetchAndRevalidateStylesheet(
+  props: FEAASCDNStylesheetProps | string,
+  callback: ValidatableStylesheetCallback
+) {
+  if (typeof props == 'string') props = { src: props }
+  return fetchAndRevalidate(
+    getStylesheetURL(props),
+    {
+      headers: {
+        Accept: 'text/css'
+      }
+    },
+    (response) => {
+      return response.headers.get('x-ms-meta-deletedAt') == null
+    },
+    (response, phase) => {
+      return response
+        .clone()
+        .text()
+        .then((text) => callback(text, phase))
+    }
+  )
+}

package/src/components/FEAASBase.tsx

@@ -1,21 +1,47 @@
-import { JSXElementConstructor, ReactElement, ReactNode } from 'react'
+import type { JSXElementConstructor, ReactElement, ReactNode } from 'react'
 import type ReactDOMClient from 'react-dom/client'
 import type ReactDOM from 'react-dom'
 import type React from 'react'
+import { ControlledPromise } from '../utils/promise.js'
 
 export type OptionalExcept<T, K extends keyof T> = Pick<T, K> & Partial<Omit<T, K>>
 
 // Shim in case it's required in node.js environment
-var WebComponent = typeof HTMLElement == 'undefined' ? (class {} as unknown as typeof HTMLElement) : HTMLElement
-interface ReactPayload {
+var WebComponent =
+  typeof HTMLElement == 'undefined'
+    ? // @ts-ignore
+      typeof windowJSDOM != 'undefined'
+      ? // @ts-ignore
+        (windowJSDOM.HTMLElement as typeof HTMLElement)
+      : (class {} as unknown as typeof HTMLElement)
+    : HTMLElement
+
+export interface ReactPayload {
   React: typeof React
   ReactDOM: typeof ReactDOM
   ReactDOMClient: typeof ReactDOMClient
 }
-
+/**
+ * FEAASBase is a superclass for FEAAS components with optional react support.
+ *
+ * Initialization lifecycle:
+ *
+ * - `set(props)`
+ * - `load() => payload`
+ * - `onLoad?(payload)`
+ * - `update()`
+ * - `render(payload, props)`
+ * - `whenRendered`
+ * - - / If needs to reload, e.g. bypass cache /
+ * - - `onLoad(newPayload) `
+ * - - `whenRendered`
+ * - `whenLoaded`
+ */
 export class FEAASBase<Props = any, Payload = any> extends WebComponent {
   static observedAttributes: string[]
 
+  defaultProps = {} as Partial<Props>
+
   /** Return attributes as parsed values */
   getProps(context?: HTMLElement): any {
     return {}
@@ -31,16 +57,19 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
   /** Is/was component in the dom? */
   connected = false
 
-  /** Result of lazy loading */
-  payload: Payload
-
   refs: Record<string, FEAASBase> = {}
   descendants: FEAASBase[] = []
 
+  /** Result of lazy loading */
+  payload: Payload
+  whenLoaded = ControlledPromise<Payload>((payload) => {
+    this.payload = payload
+  })
+
   constructor() {
     super()
-    this.addEventListener('feaasConnected', this)
-    this.addEventListener('feaasDisconnected', this)
+    this.addEventListener('feaasMount', this)
+    this.addEventListener('feaasUnmount', this)
   }
 
   /** Attaches shadow root if getShadowRootOptions any settings, or uses element itself */
@@ -55,7 +84,10 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
 
   /** Components parses its attributes when connected, and schedules rendeirng */
   connectedCallback() {
-    this.initialize()
+    this.mount()
+  }
+  disconnectedCallback() {
+    this.unmount()
   }
 
   /**
@@ -63,20 +95,35 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
    * attempts to avoid this and inverts the initialization logic, so that children are initialized in the context of its
    * already-initialized parents.
    *
-   * FEAAS components dispatch `feaasConnected` event that allows components to store references to each other. In
-   * addition it allows external scripts to listen for initialization of FEAAS components
+   * FEAAS components dispatch `feaasMount` event that allows components to store references to each other. In addition
+   * it allows external scripts to listen for initialization of FEAAS components
    */
-  initialize() {
-    const parent = this.getParent() as FEAASBase
-    // Allow parent component to initialize first
-    if (parent && !parent.connected) return
-    if (this.connected) return
-    this.connected = true
-    console.log('FEAAS: Connected', this.tagName, this)
-    this.dispatchEvent(new Event('feaasConnected', { bubbles: true, composed: true }))
-    this.getElements().map((element: FEAASBase) => element.initialize?.())
-    this.set()
-    return true
+  mount() {
+    try {
+      const parent = this.getParent() as FEAASBase
+      // Allow parent component to initialize first
+      if (parent && !parent.connected) return
+      if (this.connected) return
+      this.connected = true
+      this.log('FEAAS: Mount', this.tagName, this)
+      this.dispatchEvent(new Event('feaasMount', { bubbles: true, composed: true }))
+      this.getElements().map((element: FEAASBase) => element.mount?.())
+      this.set()
+    } catch (e) {
+      this.onError(e)
+    }
+  }
+
+  log(...args: any) {
+    console.log(...args)
+  }
+
+  /** Nothing special happens on unmount, except setting a flag */
+  unmount() {
+    if (!this.connected) return
+    this.log('FEAAS: Unmount', this)
+    this.dispatchEvent(new Event('feaasUnmount', { bubbles: true, composed: true }))
+    this.connected = false
   }
 
   getParent(onlyFeaas = true) {
@@ -102,22 +149,14 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
       .filter(Boolean)
   }
 
-  /** Nothing special happens on disconnect, except setting a flag */
-  disconnectedCallback() {
-    if (!this.connected) return
-    console.log('FEAAS: Disconnected', this)
-    this.dispatchEvent(new Event('feaasDisconnected', { bubbles: true, composed: true }))
-    this.connected = null
-  }
-
   /** Catch-all event handler that dispatches events to callback */
   handleEvent(event: Event) {
     const target = event.composedPath()[0] as FEAASBase
     switch (event.type) {
-      case 'feaasConnected':
+      case 'feaasMount':
         if (target != this) this.nestedCallback(target)
         break
-      case 'feaasDisconnected':
+      case 'feaasUnmount':
         if (target != this) this.unnestedCallback(target)
         break
     }
@@ -127,7 +166,7 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
   unnestedCallback(target: FEAASBase) {
     const index = this.descendants.indexOf(target)
     if (index == -1) return
-    console.log('FEAAS: Unnest', this, target)
+    this.log('FEAAS: Unnest', this, target)
     this.descendants.splice(index, -1)
     this.refs[target.getComponentName()] = null
     if (target.refs.parent == this) target.refs.parent = null
@@ -141,7 +180,7 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
     const index = this.descendants.indexOf(target)
     if (index != -1) return
     this.descendants.push(target)
-    console.log('FEAAS: Nest', this, target)
+    this.log('FEAAS: Nest', this, target)
     this.refs[target.getComponentName()] = target
     target.refs.top = this
     target.refs.parent ||= this
@@ -167,13 +206,61 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
     return this.payload === undefined && this.getAttribute('hidden') == null
   }
 
+  /** 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.whenLoaded.reject(error)
+    if (!event.defaultPrevented && !handled) {
+      this.whenRendered.reject(error)
+      try {
+        this.unmount()
+      } catch (e) {}
+      return true
+    }
+    return false
+  }
+
+  shouldUpdateOnLoad() {
+    return true
+  }
+
+  onLoad: (payload: Payload) => void
+
   /** Load lazy component & render */
-  async reify() {
-    if (this.payload !== undefined) {
+  async advance() {
+    try {
+      if (this.payload === undefined) {
+        if (!this.isReadyToLoad()) return
+        this.payload = null
+        this.dispatchEvent(new Event('feaasLoad', { bubbles: true, composed: true }))
+        const loaded = await this.load().catch((e) => {
+          this.payload = undefined
+          throw e
+        })
+
+        this.whenLoaded.resolve(loaded)
+
+        // Allow component to handle the post-loading
+        if (this.onLoad) {
+          return
+        }
+      } else if (this.payload == null) {
+        return
+      }
+      this.flush()
+      this.whenRendered.resolve(this)
+    } catch (e) {
+      this.onError(e)
+    }
+  }
+
+  flush() {
+    const flushSync = (this.payload as ReactPayload)?.ReactDOM?.flushSync
+    if (flushSync) {
+      flushSync(() => this.update())
+    } else {
       this.update()
-    } else if (this.isReadyToLoad()) {
-      this.payload = null
-      this.load().then(this.onLoad)
     }
   }
 
@@ -182,31 +269,24 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
     return Promise.resolve(null)
   }
 
-  /** Payload is inside onLoad callback. For web components that use react, it has to provide React & ReactDOM props */
-  onLoad = (payload: Payload) => {
-    if (payload == null) return
-
-    this.payload = payload
-    this.update()
-  }
-
   /**
    * Component-specific logic that updates the DOM. Default render implementation assume react rendering, in that case
    * the component needs to provide React & ReactDOM references in its payload. Web component redefine its render to not
    * use react at all
    */
-  update(nested = false): any {
-    console.log('FEAAS: React', this.tagName, this.payload)
+  update(): any {
+    //this.log('FEAAS: React', this.tagName, this.payload)
     if (this.payload == null) return
+    if (!this.render) return
     const { React, ReactDOM, ReactDOMClient } = (this.payload as ReactPayload) || {}
     if (!React) throw new Error(`${this.tagName}: React is not present in payload`)
     if (!ReactDOM) throw new Error(`${this.tagName}: ReactDOM is not present in payload`)
     if (!this.refs.topReact && !this.forceUpdateReact) {
       if (ReactDOMClient) {
         this.reactRoot ||= ReactDOMClient.createRoot(this.getReactRootElement())
-        this.reactRoot.render(React.createElement(this.getReactWrapper()))
+        this.reactRoot.render(this.getReactElement())
       } else {
-        ReactDOM.render(React.createElement(this.getReactWrapper()), this.getReactRootElement())
+        ReactDOM.render(this.getReactElement(), this.getReactRootElement())
       }
     } else if (this.forceUpdateReact) {
       this.forceUpdateReact?.()
@@ -217,37 +297,88 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
 
   invokeReactRendering(): ReactNode {
     const { React, ReactDOM } = (this.payload as ReactPayload) || {}
+    if (!this.connected) return null
     const children = this.descendants
       .filter((r) => {
         return r.refs.parentReact == this && r.payload
       })
       .map((child: FEAASBase<any, any>, index) => {
-        return React.createElement(this.getReactWrapper(child), {
-          key: child.tagName + '-' + child.getUID(),
-          slot: child.getAttribute('slot')
-        })
+        return this.getReactElement(child)
       })
     return this.render({ ...this.props, children }, this.payload)
   }
 
-  reactWrapper: (props?: any) => ReactNode
+  reactWrapper: React.FunctionComponent
+  reactErrorBoundary: new (...args: any) => React.Component<{ children: any; slot: string }, { error: Error }>
   reactRoot: ReactDOMClient.Root
+
+  getReactErrorBoundary(target: FEAASBase = this, displayName = target.tagName) {
+    if (this.reactErrorBoundary) return this.reactErrorBoundary
+
+    const { React, ReactDOM } = (target.payload as ReactPayload) || {}
+    return (this.reactErrorBoundary ||= class FEAASErrorBoundary extends React.Component<
+      { children: any; slot: string },
+      { error: Error }
+    > {
+      state = {
+        error: null as Error
+      }
+
+      static getDerivedStateFromError(error: Error) {
+        return { error: error }
+      }
+
+      componentDidCatch(error: Error, errorInfo: any) {
+        console.error(`FEAAS: ${target.tagName} Error:`, error, errorInfo)
+        target.onError(error, 'react')
+        //this.setState({ error: error })
+      }
+
+      render() {
+        if (this.state.error) {
+          // target.classList.add('feaas-error')
+          return
+          //return <h1>There seems to be a problem.</h1>
+        }
+        //if (target.classList.contains('feaas-error')) target.classList.remove('feaas-error')
+
+        return this.props.children
+      }
+    })
+  }
+
+  getReactElement(target: FEAASBase = this, props?: any) {
+    const { React, ReactDOM } = (target.payload as ReactPayload) || {}
+    const ErrorBoundary = this.getReactErrorBoundary()
+    const Wrapper = this.getReactWrapper(target)
+    return (
+      <ErrorBoundary key={target.tagName + '-' + target.getUID()} slot={target.getAttribute('slot')}>
+        <Wrapper />
+      </ErrorBoundary>
+    )
+  }
+
   getReactWrapper(target: FEAASBase = this, displayName = target.tagName) {
-    const Wrapper = (target.reactWrapper ||= (props?: any) => {
+    if (target.reactWrapper) return target.reactWrapper
+
+    const { React, ReactDOM } = (target.payload as ReactPayload) || {}
+
+    target.reactWrapper = (props?: any) => {
       if (target.render) {
-        const { React, ReactDOM } = (target.payload as ReactPayload) || {}
         const [value, forceUpdateReact] = React.useReducer((r) => r + 1, 0)
         target.forceUpdateReact = forceUpdateReact
         return ReactDOM.createPortal(<>{target.invokeReactRendering()}</>, target.getReactRootElement())
       } else {
         return target.update()
       }
-    })
-    Object.assign(Wrapper, {
-      key: this.tagName + '-' + this.getUID(),
+    }
+
+    Object.assign(target.reactWrapper, {
+      key: target.tagName + '-' + target.getUID(),
       displayName: displayName
     })
-    return Wrapper
+
+    return target.reactWrapper
   }
 
   uid: string
@@ -275,30 +406,50 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
 
   /** Set props and return values on new next tick */
   set(overrides?: Partial<Props>) {
-    this.overrides = {
-      ...this.overrides,
-      ...overrides
-    }
-    this.props = {
-      ...this.getProps(),
-      ...this.overrides
-    }
-    for (var property in this.props) {
-      const value = this.props[property as keyof typeof this.props]
-      if (this.props[property] == null) {
-        this.removeAttribute(property)
-      } else if (typeof value == 'string' || typeof value == 'number') {
-        if (this.getAttribute(property) != String(value)) this.setAttribute(property, String(value))
+    try {
+      this.scheduleRender()
+      this.overrides = {
+        ...this.overrides,
+        ...overrides
+      }
+      this.props = {
+        ...this.getProps(),
+        ...this.overrides
+      }
+      for (var property in this.props) {
+        const value = this.props[property]
+        const attribute = property.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+        if (value == null || value === this.defaultProps[property as keyof typeof this.defaultProps]) {
+          this.removeAttribute(attribute)
+        } else if (typeof value == 'string' || typeof value == 'number' || typeof value == 'boolean') {
+          if (this.getAttribute(attribute) != String(value)) this.setAttribute(attribute, String(value))
+        }
       }
+    } catch (e) {
+      this.whenRendered.reject(e)
+      this.onError(e, 'set')
     }
-    this.scheduleRender()
+    return this
+  }
+
+  import(path: string): Promise<Payload> {
+    return import(/* @vite-ignore */ /* webpackIgnore: true */ path)
   }
 
   /** Schedule rendering on next tick, to batch multiple attribute changes */
+  initialized: boolean
+  whenRendered = ControlledPromise<this>(
+    () => (this.initialized = true),
+    () => cancelAnimationFrame(this.nextRender)
+  )
   scheduleRender() {
+    if (this.nextRender == null) {
+      this.whenRendered = this.whenRendered.restart()
+    }
     cancelAnimationFrame(this.nextRender)
     this.nextRender = requestAnimationFrame(() => {
-      this.reify()
+      this.nextRender = null
+      this.advance().catch((e) => {})
     })
   }
 
@@ -321,9 +472,10 @@ export class FEAASBase<Props = any, Payload = any> extends WebComponent {
     return this.getAttribute(name)
   }
 
-  static register(tagName: string) {
-    if (typeof window != 'undefined' && !window.customElements.get(tagName)) {
-      window.customElements.define(tagName, this)
+  static register(tagName: string, win?: Window) {
+    if (win == null) win = typeof window != 'undefined' ? window : null
+    if (!win?.customElements.get(tagName)) {
+      win.customElements.define(tagName, this)
     }
   }
 }