glass-easel 0.1.0

package/src/func_arr.ts

@@ -0,0 +1,198 @@
+import {
+  Component,
+  GeneralComponent,
+} from '.'
+import {
+  globalOptions,
+} from './global_options'
+
+export type GeneralFuncType = (this: any, ...args: any[]) => any
+
+type ErrorInfo = {
+  message: string
+  type: string
+  element: unknown
+  method: unknown
+  args: unknown[]
+}
+
+function dispatchError(err: unknown, info: ErrorInfo, avoidErrorHandler?: boolean) {
+  if (!avoidErrorHandler && errorFuncArr.call(err as any, [err, info]) === false) return
+  if (globalOptions.throwGlobalError) {
+    throw err
+  } else {
+    // eslint-disable-next-line no-console
+    console.error(err instanceof Error ? `${err.message}\n${err.stack || ''}` : String(err))
+  }
+}
+
+export class FuncArr<F extends GeneralFuncType> {
+  empty = true
+  private _$type = ''
+  private _$arr: F[] | null = null
+  _$avoidErrorHandler = false
+
+  add(func: F) {
+    if (!this._$arr) this._$arr = [func]
+    else this._$arr = this._$arr.concat(func)
+    this.empty = false
+  }
+
+  remove(func: F): F | null {
+    let ret: F | null = null
+    if (this._$arr) {
+      const newArr: F[] = []
+      const oldArr = this._$arr
+      for (let i = 0; i < oldArr.length; i += 1) {
+        if (oldArr[i] === func) {
+          newArr.push(...oldArr.slice(i + 1))
+          ret = func
+          break
+        }
+        newArr.push(oldArr[i]!)
+      }
+      this._$arr = newArr
+      this.empty = this._$arr.length === 0
+    }
+    return ret
+  }
+
+  call(
+    caller: ThisType<F>,
+    args: Parameters<F>,
+    relatedComponent?: GeneralComponent,
+  ): boolean {
+    const arr = this._$arr
+    let ret = true
+    if (arr) {
+      for (let i = 0; i < arr.length; i += 1) {
+        const r = safeCallback(
+          this._$type,
+          arr[i]!,
+          caller,
+          args,
+          relatedComponent,
+          this._$avoidErrorHandler,
+        )
+        if (r === false) ret = false
+      }
+    }
+    return ret
+  }
+
+  static safeCallback<F extends GeneralFuncType>(
+    this: void,
+    type: string,
+    method: F,
+    caller: ThisType<F>,
+    args: Parameters<F>,
+    relatedComponent?: GeneralComponent,
+    avoidErrorHandler = false,
+  ): ReturnType<F> | undefined {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return method.apply(caller, args)
+    } catch (e) {
+      let msg = `[Error] [Component] ${type || 'Error Listener'} Error @ `
+      if (caller instanceof Component) msg += caller.is
+      msg += `#${method.name || '(anonymous)'}`
+      if (relatedComponent) {
+        relatedComponent.triggerLifetime('error', [e])
+      }
+      dispatchError(e, {
+        message: msg,
+        type,
+        element: caller,
+        method,
+        args,
+      }, avoidErrorHandler)
+      return undefined
+    }
+  }
+
+  static addGlobalErrorListener(this: void, func: (err: Error, info: ErrorInfo) => boolean) {
+    errorFuncArr.add(func)
+  }
+
+  static removeGlobalErrorListener(this: void, func: (err: Error, info: ErrorInfo) => boolean) {
+    errorFuncArr.remove(func)
+  }
+
+  static addGlobalWarningListener(this: void, func: (msg: string) => void) {
+    warningFuncArr.add(func)
+  }
+
+  static removeGlobalWarningListener(this: void, func: (msg: string) => void) {
+    warningFuncArr.remove(func)
+  }
+}
+
+export function triggerWarning(msg: string) {
+  const message = `[Warning] [Component] ${msg}`
+  if (warningFuncArr.call(message, [message])) {
+    // eslint-disable-next-line no-console
+    console.warn(message)
+  }
+}
+
+const errorFuncArr = new FuncArr()
+errorFuncArr._$avoidErrorHandler = true
+const warningFuncArr = new FuncArr()
+
+export class FuncArrWithMeta<F extends GeneralFuncType, T> {
+  empty = true
+  private _$type = ''
+  private _$arr: { f: F, data: T }[] | null = null
+
+  add(func: F, data: T) {
+    const item = { f: func, data }
+    if (!this._$arr) this._$arr = [item]
+    else this._$arr = this._$arr.concat(item)
+    this.empty = false
+  }
+
+  remove(func: F): T | null {
+    let ret: T | null = null
+    if (this._$arr) {
+      const newArr: { f: F, data: T }[] = []
+      const oldArr = this._$arr
+      for (let i = 0; i < oldArr.length; i += 1) {
+        const v = oldArr[i]!
+        if (v.f === func) {
+          newArr.push(...oldArr.slice(i + 1))
+          ret = v.data
+          break
+        }
+        newArr.push(v)
+      }
+      this._$arr = newArr
+      this.empty = this._$arr.length === 0
+    }
+    return ret
+  }
+
+  call(
+    caller: ThisType<F>,
+    args: Parameters<F>,
+    retainFn: (data: T) => boolean,
+    relatedComponent?: GeneralComponent,
+  ): boolean {
+    const arr = this._$arr
+    let ret = true
+    if (arr) {
+      for (let i = 0; i < arr.length; i += 1) {
+        const { f, data } = arr[i]!
+        if (!retainFn(data)) continue
+        const r = FuncArr.safeCallback(this._$type, f, caller, args, relatedComponent)
+        if (r === false) ret = false
+      }
+    }
+    return ret
+  }
+}
+
+export const safeCallback = FuncArr.safeCallback
+export const addGlobalErrorListener = FuncArr.addGlobalErrorListener
+export const removeGlobalErrorListener = FuncArr.removeGlobalErrorListener
+export const addGlobalWarningListener = FuncArr.addGlobalWarningListener
+export const removeGlobalWarningListener = FuncArr.removeGlobalWarningListener

package/src/global_options.ts

@@ -0,0 +1,242 @@
+import * as backend from './backend/backend_protocol'
+import * as composedBackend from './backend/composed_backend_protocol'
+import * as domlikeBackend from './backend/domlike_backend_protocol'
+import {
+  StyleScopeId,
+  StyleScopeManager,
+} from './class_list'
+import {
+  Context as BackendContext,
+} from './backend/backend_protocol'
+import {
+  TemplateEngine,
+} from './template_engine'
+import {
+  ComponentSpace,
+} from './component_space'
+import {
+  GlassEaselTemplateEngine,
+} from './tmpl'
+import {
+  GeneralComponent,
+  GeneralBackendContext,
+} from '.'
+import {
+  BM,
+} from './backend/mode'
+
+/**
+ * The deep copy strategy
+ *
+ * Higher level indicates more accuracy but probably less performance.
+ */
+export enum DeepCopyKind {
+  /**
+   * Avoid deep copy
+   *
+   * This avoids any copy, and recursive objects can be handled without any failing.
+   * However, changing non-copied data will sometimes break the logic.
+   */
+  None = 'none',
+  /**
+   * Do a simple deep copy
+   *
+   * This simply clones each enumerable fields in an object to a new object.
+   * It causes stack overflow in recursive objects.
+   * Everything in prototypes is ignored.
+   */
+  Simple = 'simple',
+  /**
+   * Do a deep copy with recursion detection
+   *
+   * This clones each enumerable fields in an object to a new object.
+   * It can handle recursive objects by recursive detection.
+   * Everything in prototypes is ignored.
+   */
+  SimpleWithRecursion = 'simple-recursion',
+}
+
+let defaultComponentSpace: ComponentSpace | null = null
+
+export const getDefaultComponentSpace = (): ComponentSpace => {
+  if (defaultComponentSpace) {
+    return defaultComponentSpace
+  }
+  const cs = new ComponentSpace()
+  defaultComponentSpace = cs
+  return cs
+}
+
+let defaultBackendContext: GeneralBackendContext | null = null
+
+export const getDefaultBackendContext = (): GeneralBackendContext => {
+  if (defaultBackendContext) return defaultBackendContext
+  let c: GeneralBackendContext
+  if (BM.DOMLIKE) {
+    c = new domlikeBackend.CurrentWindowBackendContext()
+  } else if (BM.COMPOSED) {
+    c = new composedBackend.EmptyComposedBackendContext()
+  } else {
+    c = new backend.EmptyBackendContext()
+  }
+  defaultBackendContext = c
+  return c
+}
+
+/**
+ * Options for a component
+ */
+export type ComponentOptions = {
+  /** Is external component or not */
+  externalComponent?: boolean
+  /** The template engine */
+  templateEngine?: TemplateEngine
+  /** The style scope */
+  styleScope?: StyleScopeId
+  /** An extra style scope assigned to the component */
+  extraStyleScope?: StyleScopeId | null
+  /** Enable multiple slots or not */
+  multipleSlots?: boolean
+  /** Enable dynamic slots or not */
+  dynamicSlots?: boolean
+  /** Write property values of components to backend with `setAttribute` */
+  reflectToAttributes?: boolean
+  /** Allow properties and methods to be able to visit directly in component instance */
+  writeFieldsToNode?: boolean
+  /** Write node ID to backend node */
+  writeIdToDOM?: boolean
+  /** Generate a prefix for ID written to backend node */
+  idPrefixGenerator?: ((this: GeneralComponent) => string) | null
+  /** Filter some fields out when applying to templates */
+  pureDataPattern?: RegExp | null
+  /** Decide how to deep copy component data when updates */
+  dataDeepCopy?: DeepCopyKind
+  /** Decide how to deep copy when a property changes */
+  propertyPassingDeepCopy?: DeepCopyKind
+  /** Enable listener change events or not */
+  listenerChangeLifetimes?: boolean
+  /** Component host node is virtual or not */
+  virtualHost?: boolean
+  /** Init component with property values or not */
+  propertyEarlyInit?: boolean
+}
+
+export type NormalizedComponentOptions = {
+  externalComponent: boolean
+  templateEngine: TemplateEngine
+  styleScope: StyleScopeId
+  extraStyleScope: StyleScopeId | null
+  multipleSlots: boolean
+  dynamicSlots: boolean
+  reflectToAttributes: boolean
+  writeFieldsToNode: boolean
+  writeIdToDOM: boolean
+  idPrefixGenerator: ((this: GeneralComponent) => string) | null
+  pureDataPattern: RegExp | null
+  dataDeepCopy: DeepCopyKind
+  propertyPassingDeepCopy: DeepCopyKind
+  listenerChangeLifetimes: boolean
+  virtualHost: boolean
+  propertyEarlyInit: boolean
+}
+
+/**
+ * Options for global environment
+ */
+export type EnvironmentOptions = {
+  /** The default component space */
+  defaultComponentSpace: ComponentSpace | null
+  /** Throw errors when errors caught in event callbacks (useful in testing scripts) */
+  throwGlobalError: boolean
+  /** Write some extra attributes to DOM backend (for testing) */
+  writeExtraInfoToAttr: boolean
+  /** The default backend context */
+  backendContext: BackendContext | null
+}
+
+/**
+ * The default options
+ */
+export const globalOptions: NormalizedComponentOptions & EnvironmentOptions = {
+  defaultComponentSpace: null,
+  externalComponent: false,
+  templateEngine: new GlassEaselTemplateEngine(),
+  styleScope: StyleScopeManager.globalScope(),
+  extraStyleScope: null,
+  multipleSlots: false,
+  dynamicSlots: false,
+  reflectToAttributes: false,
+  writeFieldsToNode: true,
+  writeIdToDOM: false,
+  idPrefixGenerator: null,
+  pureDataPattern: null,
+  dataDeepCopy: DeepCopyKind.Simple,
+  propertyPassingDeepCopy: DeepCopyKind.Simple,
+  listenerChangeLifetimes: false,
+  virtualHost: false,
+  propertyEarlyInit: false,
+  throwGlobalError: false,
+  writeExtraInfoToAttr: false,
+  backendContext: null,
+}
+
+export const normalizeComponentOptions = (
+  componentOptions: ComponentOptions | undefined,
+  baseComponentOptions?: NormalizedComponentOptions,
+): NormalizedComponentOptions => {
+  const b = baseComponentOptions === undefined ? globalOptions : baseComponentOptions
+  if (componentOptions === undefined && b !== globalOptions) {
+    return b
+  }
+  const p = componentOptions ?? {}
+  return {
+    externalComponent: p.externalComponent !== undefined
+      ? p.externalComponent
+      : b.externalComponent,
+    templateEngine: p.templateEngine !== undefined
+      ? p.templateEngine
+      : b.templateEngine,
+    styleScope: p.styleScope !== undefined
+      ? p.styleScope
+      : b.styleScope,
+    extraStyleScope: p.extraStyleScope !== undefined
+      ? p.extraStyleScope
+      : b.extraStyleScope,
+    multipleSlots: p.multipleSlots !== undefined
+      ? p.multipleSlots
+      : b.multipleSlots,
+    dynamicSlots: p.dynamicSlots !== undefined
+      ? p.dynamicSlots
+      : b.dynamicSlots,
+    reflectToAttributes: p.reflectToAttributes !== undefined
+      ? p.reflectToAttributes
+      : b.reflectToAttributes,
+    writeFieldsToNode: p.writeFieldsToNode !== undefined
+      ? p.writeFieldsToNode
+      : b.writeFieldsToNode,
+    writeIdToDOM: p.writeIdToDOM !== undefined
+      ? p.writeIdToDOM
+      : b.writeIdToDOM,
+    idPrefixGenerator: p.idPrefixGenerator !== undefined
+      ? p.idPrefixGenerator
+      : b.idPrefixGenerator,
+    pureDataPattern: p.pureDataPattern !== undefined
+      ? p.pureDataPattern
+      : b.pureDataPattern,
+    dataDeepCopy: p.dataDeepCopy !== undefined
+      ? p.dataDeepCopy
+      : b.dataDeepCopy,
+    propertyPassingDeepCopy: p.propertyPassingDeepCopy !== undefined
+      ? p.propertyPassingDeepCopy
+      : b.propertyPassingDeepCopy,
+    listenerChangeLifetimes: p.listenerChangeLifetimes !== undefined
+      ? p.listenerChangeLifetimes
+      : b.listenerChangeLifetimes,
+    virtualHost: p.virtualHost !== undefined
+      ? p.virtualHost
+      : b.virtualHost,
+    propertyEarlyInit: p.propertyEarlyInit !== undefined
+      ? p.propertyEarlyInit
+      : b.propertyEarlyInit,
+  }
+}

package/src/index.ts

@@ -0,0 +1,187 @@
+/* eslint-disable import/first */
+/* eslint-disable arrow-body-style */
+
+export {
+  TextNode,
+} from './text_node'
+export {
+  NativeNode,
+} from './native_node'
+export {
+  ShadowRoot,
+} from './shadow_root'
+export {
+  VirtualNode,
+} from './virtual_node'
+export {
+  globalOptions,
+  DeepCopyKind,
+  ComponentOptions,
+  EnvironmentOptions,
+  NormalizedComponentOptions,
+  getDefaultComponentSpace,
+} from './global_options'
+export {
+  Element,
+  StyleSegmentIndex,
+} from './element'
+export * as dataUtils from './data_utils'
+export * as dataPath from './data_path'
+export {
+  DataGroup,
+  GeneralDataGroup,
+  DataValue,
+  DataObserver,
+  DataChange,
+  PropertyChange,
+  DataUpdateCallback,
+} from './data_proxy'
+export {
+  Event,
+  ShadowedEvent,
+  EventBubbleStatus,
+  EventOptions,
+} from './event'
+export * as typeUtils from './component_params'
+export {
+  Behavior,
+  GeneralBehavior,
+  BehaviorBuilder,
+  GeneralBehaviorBuilder,
+  BuilderContext,
+} from './behavior'
+export {
+  Component,
+  ComponentDefinition,
+  GeneralComponent,
+  GeneralComponentDefinition,
+} from './component'
+export {
+  MutationObserver as Observer,
+  MutationObserver,
+} from './mutation_observer'
+export * as mutationObserver from './mutation_observer'
+export {
+  Node,
+  dumpElement,
+  dumpElementToString,
+  dumpSingleElementToString,
+  GeneralBackendElement,
+  GeneralBackendContext,
+  NodeCast,
+} from './node'
+export {
+  ElementIterator,
+  ElementIteratorType,
+} from './element_iterator'
+export {
+  FuncArr,
+  GeneralFuncType,
+  safeCallback,
+  addGlobalErrorListener,
+  removeGlobalErrorListener,
+  addGlobalWarningListener,
+  removeGlobalWarningListener,
+} from './func_arr'
+export {
+  ParsedSelector,
+} from './selector'
+export {
+  StyleScopeManager,
+  ClassList,
+  StyleScopeId,
+} from './class_list'
+export {
+  RelationType,
+  RelationListener,
+  RelationFailedListener,
+} from './relation'
+export {
+  TraitBehavior,
+} from './trait_behaviors'
+export {
+  triggerRender,
+} from './render'
+export {
+  ComponentSpace,
+} from './component_space'
+export {
+  ExternalShadowRoot,
+} from './external_shadow_tree'
+export * as template from './tmpl'
+export * as backend from './backend/backend_protocol'
+export * as composedBackend from './backend/composed_backend_protocol'
+export * as domlikeBackend from './backend/domlike_backend_protocol'
+export {
+  BackendMode,
+} from './backend/mode'
+export * as templateEngine from './template_engine'
+export * as glassEaselTemplate from './tmpl'
+
+import {
+  ComponentParams,
+  DataList,
+  PropertyList,
+  MethodList,
+  ComponentInstance,
+  GeneralComponentInstance,
+  Empty,
+} from './component_params'
+import {
+  Behavior,
+} from './behavior'
+import {
+  Component,
+  ComponentDefinition,
+  GeneralComponentDefinition,
+} from './component'
+import {
+  Event,
+} from './event'
+import {
+  getDefaultComponentSpace,
+} from './global_options'
+
+export const registerBehavior = <
+  TData extends DataList = Empty,
+  TProperty extends PropertyList = Empty,
+  TMethod extends MethodList = Empty,
+>(
+    def: ComponentParams<TData, TProperty, TMethod> &
+      ThisType<ComponentInstance<TData, TProperty, TMethod>>,
+  ): Behavior<TData, TProperty, TMethod, never> => {
+  return getDefaultComponentSpace().defineBehavior(def)
+}
+
+export const registerElement = <
+  TData extends DataList = Empty,
+  TProperty extends PropertyList = Empty,
+  TMethod extends MethodList = Empty,
+>(
+    def: ComponentParams<TData, TProperty, TMethod> &
+      ThisType<ComponentInstance<TData, TProperty, TMethod>>,
+  ): ComponentDefinition<TData, TProperty, TMethod> => {
+  return getDefaultComponentSpace().defineComponent(def)
+}
+
+export function createElement(
+  tagName: string,
+  compDef?: GeneralComponentDefinition
+): GeneralComponentInstance
+export function createElement <
+  TData extends DataList,
+  TProperty extends PropertyList,
+  TMethod extends MethodList,
+>(
+  tagName: string,
+  compDef: ComponentDefinition<TData, TProperty, TMethod>,
+): ComponentInstance<TData, TProperty, TMethod>
+export function createElement(
+  tagName: string,
+  compDef?: GeneralComponentDefinition,
+): GeneralComponentInstance {
+  return Component.create(tagName, compDef || null)
+}
+
+export const triggerEvent = Event.triggerEvent
+export const triggerExternalEvent = Event.triggerExternalEvent