glass-easel 0.1.0

package/src/element_iterator.ts

@@ -0,0 +1,158 @@
+import {
+  Element,
+} from './element'
+import {
+  TextNode,
+} from './text_node'
+import {
+  Component,
+} from './component'
+import {
+  Node,
+} from './node'
+
+/** The iterator direction and order */
+export const enum ElementIteratorType {
+  /** Iterate all ancestors in shadow tree */
+  ShadowAncestors = 'shadow-ancestors',
+  /** Iterate all ancestors in composed tree */
+  ComposedAncestors = 'composed-ancestors',
+  /** Iterate all descendants in shadow tree, returning parents before their children */
+  ShadowDescendantsRootFirst = 'shadow-descendants-root-first',
+  /** Iterate all descendants in shadow tree, returning parents after their children */
+  ShadowDescendantsRootLast = 'shadow-descendants-root-last',
+  /** Iterate all descendants in composed tree, returning parents before their children */
+  ComposedDescendantsRootFirst = 'composed-descendants-root-first',
+  /** Iterate all descendants in composed tree, returning parents after their children */
+  ComposedDescendantsRootLast = 'composed-descendants-root-last',
+}
+
+/**
+ * An iterator for node tree traversal
+ *
+ * This iterator is convinient but seems a little slower.
+ */
+export class ElementIterator {
+  private _$node: Node
+  private _$nodeTypeLimit: unknown
+  private _$composed: boolean
+  private _$isAncestor: boolean
+  private _$rootFirst: boolean
+
+  /**
+   * Create an iterator with type specified
+   *
+   * The `nodeTypeLimit` is used to limit which kind of nodes will be returned.
+   * It limits the returned result by an `instanceof` call.
+   * The default value is `Element` ,
+   * which means only elements will be returned (text nodes will not).
+   * Consider specifying `Node` if text nodes need to be returned as well as elements.
+   * Specify `Component` will only return components.
+   */
+  constructor(node: Node, type: ElementIteratorType, nodeTypeLimit: unknown = Element) {
+    if (!(node instanceof Element) && !(node instanceof TextNode)) {
+      throw new Error('Element iterators can only be used in elements or text nodes')
+    }
+    this._$node = node
+    this._$nodeTypeLimit = nodeTypeLimit || Element
+    if (
+      type === ElementIteratorType.ShadowAncestors
+      || type === ElementIteratorType.ShadowDescendantsRootFirst
+      || type === ElementIteratorType.ShadowDescendantsRootLast
+    ) {
+      this._$composed = false
+    } else if (
+      type === ElementIteratorType.ComposedAncestors
+      || type === ElementIteratorType.ComposedDescendantsRootFirst
+      || type === ElementIteratorType.ComposedDescendantsRootLast
+    ) {
+      this._$composed = true
+    } else {
+      throw new Error(`Unrecognized iterator type "${String(type)}"`)
+    }
+    if (
+      type === ElementIteratorType.ShadowAncestors
+      || type === ElementIteratorType.ComposedAncestors
+    ) {
+      this._$isAncestor = true
+    } else {
+      this._$isAncestor = false
+    }
+    if (
+      type === ElementIteratorType.ShadowDescendantsRootFirst
+      || type === ElementIteratorType.ComposedDescendantsRootFirst
+    ) {
+      this._$rootFirst = true
+    } else {
+      this._$rootFirst = false
+    }
+  }
+
+  /** Same as constructor (for backward compatibility) */
+  static create(node: Node, type: ElementIteratorType, nodeTypeLimit?: unknown): ElementIterator {
+    return new ElementIterator(node, type, nodeTypeLimit)
+  }
+
+  forEach(f: (node: Node) => boolean) {
+    const nodeTypeLimit: any = this._$nodeTypeLimit
+    const composed = this._$composed
+    if (this._$isAncestor) {
+      const rec = (node: Node): boolean => {
+        let prev: Node | null = null
+        let cur = node
+        for (;;) {
+          if (composed && prev) {
+            if (cur instanceof Component && !cur._$external) {
+              const slot = cur.getShadowRoot()!.getContainingSlot(prev)
+              if (slot) {
+                if (rec(slot) === false) break
+              } else {
+                return false
+              }
+            }
+          }
+          if (cur instanceof nodeTypeLimit) {
+            if (f(cur) === false) return false
+          }
+          if (!cur.parentNode) break
+          prev = cur
+          cur = cur.parentNode
+        }
+        return true
+      }
+      rec(this._$node)
+    } else {
+      const rootFirst = this._$rootFirst
+      const rec = (node: Node): boolean => {
+        if (rootFirst) {
+          if (node instanceof nodeTypeLimit) {
+            if (f(node) === false) return false
+          }
+        }
+        if (node instanceof Element) {
+          let interrupted = false
+          const childFn = (child: Node) => {
+            if (rec(child) === false) {
+              interrupted = true
+              return false
+            }
+            return true
+          }
+          if (composed) {
+            node.forEachComposedChild(childFn)
+          } else {
+            node.childNodes.forEach(childFn)
+          }
+          if (interrupted) return false
+        }
+        if (!rootFirst) {
+          if (node instanceof nodeTypeLimit) {
+            if (f(node) === false) return false
+          }
+        }
+        return true
+      }
+      rec(this._$node)
+    }
+  }
+}

package/src/event.ts

@@ -0,0 +1,401 @@
+import {
+  FuncArrWithMeta,
+} from './func_arr'
+import {
+  Element,
+  Component,
+  GeneralComponent,
+  ShadowRoot,
+  GeneralBackendElement,
+  ExternalShadowRoot,
+} from '.'
+
+/**
+ * Options for an event
+ */
+export type EventOptions = {
+  originalEvent?: unknown
+  bubbles?: boolean
+  composed?: boolean
+  capturePhase?: boolean
+  extraFields?: { [key: string]: unknown }
+}
+
+/**
+ * Options for an event listener
+ */
+export type EventListenerOptions = {
+  /** Always stop bubbling after this listener */
+  final?: boolean
+  /** Mark mutated after this listener (ignored if `final` is true) */
+  mutated?: boolean
+  /** Listen in the capture phase */
+  capture?: boolean
+  /** The same as `capture` for compatibility */
+  useCapture?: boolean
+}
+
+/**
+ * Event bubbling control
+ */
+export const enum EventBubbleStatus {
+  Normal = 0,
+  NoDefault = 1,
+}
+
+export type EventListener<TDetail> = (ev: ShadowedEvent<TDetail>) => boolean | void
+
+let relativeTimeStamp = Date.now()
+let prevTimeStamp = relativeTimeStamp
+
+const getCurrentTimeStamp = () => {
+  const ts = Date.now()
+  if (ts < prevTimeStamp) {
+    relativeTimeStamp += ts - prevTimeStamp
+  }
+  prevTimeStamp = ts
+  return ts - relativeTimeStamp
+}
+
+const enum MutLevel {
+  None = 0,
+  Mut = 1,
+  Final = 2,
+}
+
+type EventFuncArr<TDetail> = {
+  mutCount: number,
+  finalCount: number,
+  funcArr: FuncArrWithMeta<EventListener<TDetail>, MutLevel>,
+}
+
+export const enum FinalChanged {
+  NotChanged = 0,
+  Failed,
+  Init,
+  Added,
+  Removed,
+}
+
+/** The target of an event */
+export class EventTarget<TEvents extends { [type: string]: unknown }> {
+  listeners = Object.create(null) as {
+    [T in keyof TEvents]: EventFuncArr<TEvents[T]>
+  }
+  captureListeners: {
+    [T in keyof TEvents]: EventFuncArr<TEvents[T]>
+  } | null = null
+
+  addListener<T extends string>(
+    name: T,
+    func: EventListener<TEvents[T]>,
+    options: EventListenerOptions = {},
+  ): FinalChanged {
+    // eslint-disable-next-line no-nested-ternary
+    const mutLevel = options.final
+      ? MutLevel.Final
+      : (options.mutated ? MutLevel.Mut : MutLevel.None)
+    let listeners: { [T in keyof TEvents]: EventFuncArr<TEvents[T]> }
+    if (options.capture || options.useCapture) {
+      if (this.captureListeners) {
+        listeners = this.captureListeners
+      } else {
+        listeners = Object.create(null) as {
+          [T in keyof TEvents]: EventFuncArr<TEvents[T]>
+        }
+        this.captureListeners = listeners
+      }
+    } else {
+      listeners = this.listeners
+    }
+    let efa: EventFuncArr<TEvents[T]>
+    let initialized: boolean
+    if (listeners[name]) {
+      initialized = true
+      efa = listeners[name]!
+    } else {
+      initialized = false
+      efa = listeners[name] = {
+        mutCount: 0,
+        finalCount: 0,
+        funcArr: new FuncArrWithMeta(),
+      }
+    }
+    efa.funcArr.add(func, mutLevel)
+    if (mutLevel === MutLevel.Final) efa.finalCount += 1
+    else if (mutLevel === MutLevel.Mut) efa.mutCount += 1
+    if (initialized) {
+      return mutLevel === MutLevel.Final && efa.finalCount === 1
+        ? FinalChanged.Added
+        : FinalChanged.NotChanged
+    }
+    return MutLevel.Final ? FinalChanged.Added : FinalChanged.Init
+  }
+
+  removeListener<T extends string>(
+    name: T,
+    func: EventListener<TEvents[T]>,
+    options: EventListenerOptions = {},
+  ): FinalChanged {
+    const listeners = (options.capture || options.useCapture)
+      ? this.captureListeners
+      : this.listeners
+    if (!listeners) return FinalChanged.Failed
+    const efa = listeners[name]
+    if (!efa) return FinalChanged.Failed
+    const mutLevel = efa.funcArr.remove(func)
+    if (mutLevel === null) return FinalChanged.Failed
+    if (mutLevel === MutLevel.Final) efa.finalCount -= 1
+    else if (mutLevel === MutLevel.Mut) efa.mutCount -= 1
+    return mutLevel === MutLevel.Final && efa.finalCount === 0
+      ? FinalChanged.Removed
+      : FinalChanged.NotChanged
+  }
+}
+
+export type ShadowedEvent<TDetail> = Required<Event<TDetail>> & {
+  target: Element
+  mark: { [name: string]: unknown } | null
+  currentTarget: Element
+}
+
+export class Event<TDetail> {
+  type: string
+  timeStamp: number
+  detail: TDetail
+  bubbles: boolean
+  composed: boolean
+  /** @internal */
+  private _$capturePhase: boolean
+  /** @internal */
+  private _$originalEvent: unknown
+  /** @internal */
+  private _$dispatched: boolean
+  /** @internal */
+  private _$eventBubblingControl: {
+    stopped: boolean
+    mutated: boolean
+    noDefault: boolean
+  }
+
+  constructor(name: string, detail: TDetail, options: EventOptions = {}) {
+    const ts = getCurrentTimeStamp()
+    this.type = name
+    this.timeStamp = ts
+    this.detail = detail
+    this.bubbles = options.bubbles || false
+    this.composed = options.composed || false
+    this._$capturePhase = options.capturePhase || false
+    this._$eventBubblingControl = {
+      stopped: false,
+      mutated: false,
+      noDefault: false,
+    }
+    this._$originalEvent = options.originalEvent
+    this._$dispatched = false
+    if (options.extraFields) {
+      Object.assign(this, options.extraFields)
+    }
+  }
+
+  getEventBubbleStatus(): EventBubbleStatus {
+    if (this._$eventBubblingControl.noDefault) return EventBubbleStatus.NoDefault
+    return EventBubbleStatus.Normal
+  }
+
+  wrapShadowedEvent(
+    targetCaller: Element,
+    mark: { [name: string]: unknown } | null,
+    currentTargetCaller: Element,
+  ): ShadowedEvent<TDetail> {
+    const ret = Object.create(this) as ShadowedEvent<TDetail>
+    ret.target = targetCaller
+    ret.mark = mark
+    ret.currentTarget = currentTargetCaller
+    return ret
+  }
+
+  getOriginalEvent(): unknown {
+    return this._$originalEvent
+  }
+
+  preventDefault() {
+    this._$eventBubblingControl.noDefault = true
+  }
+
+  defaultPrevented() {
+    return this._$eventBubblingControl.noDefault
+  }
+
+  stopPropagation() {
+    this._$eventBubblingControl.stopped = true
+  }
+
+  propagationStopped() {
+    return this._$eventBubblingControl.stopped
+  }
+
+  markMutated() {
+    this._$eventBubblingControl.mutated = true
+  }
+
+  mutatedMarked() {
+    return this._$eventBubblingControl.mutated
+  }
+
+  dispatch(target: Element, externalTarget?: GeneralBackendElement) {
+    if (this._$dispatched) {
+      throw new Error('Event cannot be dispatched twice')
+    }
+    this._$dispatched = true
+    const evName = this.type
+    const crossShadow = this.composed
+    const bubbles = this.bubbles
+    const inExternalOnly = externalTarget && !crossShadow
+    const eventBubblingControl = this._$eventBubblingControl
+
+    // calls listeners on a single element
+    const callEventFuncArr = (
+      targetCaller: Element,
+      mark: Record<string, unknown> | null,
+      cur: Element,
+      isCapture: boolean,
+    ) => {
+      const eventTarget = cur._$eventTarget
+      if (!eventTarget) return
+      const listeners = isCapture ? eventTarget.captureListeners : eventTarget.listeners
+      if (!listeners) return
+      const efa = listeners[evName]
+      if (!efa) return
+      const skipMut = this.mutatedMarked()
+      const isComp = cur instanceof Component
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const curCaller = isComp ? cur.getMethodCaller() : cur
+      const ev = this.wrapShadowedEvent(targetCaller, mark, curCaller)
+      const ret = efa.funcArr.call(
+        curCaller,
+        [ev],
+        (mulLevel) => !skipMut || mulLevel !== MutLevel.Mut,
+        isComp ? cur as GeneralComponent : undefined,
+      )
+      if (ret === false || efa.finalCount > 0) {
+        ev.stopPropagation()
+        ev.preventDefault()
+      } else if (efa.mutCount > 0) {
+        ev.markMutated()
+      }
+    }
+
+    const forEachBubblePath = (
+      target: Element,
+      f: (target: Element, targetCaller: Element, mark: Record<string, unknown>) => boolean | void,
+    ) => {
+      const recShadow = (target: Element): Element | null => {
+        let cur = target
+        const targetCaller = target instanceof Component
+          ? target.getMethodCaller() as Element
+          : target
+        const mark = target.collectMarks()
+        for (;;) {
+          if (f(cur, targetCaller, mark) === false) return null
+          let next
+          if (crossShadow) {
+            if (cur instanceof ShadowRoot) return cur.getHostNode()
+            next = cur.parentNode
+            while (next?._$inheritSlots) {
+              next = next.parentNode
+            }
+            if (next instanceof Component && !next._$external) {
+              const slot = (next.shadowRoot as ShadowRoot).getContainingSlot(cur)
+              if (!slot) return null
+              next = recShadow(slot)
+            }
+          } else {
+            next = cur.parentNode
+          }
+          if (!next) return null
+          cur = next
+        }
+      }
+      let cur = target
+      for (;;) {
+        const next = recShadow(cur)
+        if (!next) break
+        cur = next
+      }
+    }
+
+    // capture phase
+    if (this._$capturePhase && !eventBubblingControl.stopped && !inExternalOnly) {
+      const bubblingPath: [Element, Element, Record<string, unknown>][] = []
+      forEachBubblePath(target, (target, targetCaller, mark) => {
+        bubblingPath.push([target, targetCaller, mark])
+      })
+      for (let i = bubblingPath.length - 1; i >= 0; i -= 1) {
+        const [cur, targetCaller, mark] = bubblingPath[i]!
+        if (cur._$eventTarget) {
+          callEventFuncArr(targetCaller, mark, cur, true)
+          if (eventBubblingControl.stopped) break
+        }
+      }
+    }
+
+    // bubble phase in external component
+    if (!eventBubblingControl.stopped && externalTarget) {
+      if (target instanceof Component && target._$external) {
+        (target.shadowRoot as ExternalShadowRoot).handleEvent(externalTarget, this)
+      }
+    }
+
+    // bubble phase
+    if (!eventBubblingControl.stopped && !inExternalOnly) {
+      let atTarget = true
+      forEachBubblePath(target, (target, targetCaller, mark) => {
+        if (!atTarget && target instanceof Component && target._$external) {
+          const sr = target.shadowRoot as ExternalShadowRoot
+          sr.handleEvent(sr.slot, this)
+        }
+        atTarget = false
+        if (target._$eventTarget) {
+          callEventFuncArr(targetCaller, mark, target, false)
+        }
+        return bubbles && !eventBubblingControl.stopped
+      })
+    }
+  }
+
+  static dispatchEvent<TDetail>(target: Element, event: Event<TDetail>) {
+    return event.dispatch(target)
+  }
+
+  static dispatchExternalEvent<TDetail>(
+    component: GeneralComponent,
+    target: GeneralBackendElement,
+    event: Event<TDetail>,
+  ) {
+    return event.dispatch(component, target)
+  }
+
+  static triggerEvent<TDetail>(
+    this: void,
+    target: Element,
+    name: string,
+    detail: TDetail,
+    options?: EventOptions,
+  ) {
+    const ev = new Event(name, detail, options)
+    Event.dispatchEvent(target, ev)
+  }
+
+  static triggerExternalEvent<TDetail>(
+    this: void,
+    component: GeneralComponent,
+    target: GeneralBackendElement,
+    name: string,
+    detail: TDetail,
+    options?: EventOptions,
+  ) {
+    const ev = new Event(name, detail, options)
+    Event.dispatchExternalEvent(component, target, ev)
+  }
+}

package/src/external_shadow_tree.ts

@@ -0,0 +1,27 @@
+import {
+  Event,
+  ShadowedEvent,
+} from './event'
+import {
+  GeneralBackendElement,
+} from './node'
+
+/**
+ * An external shadow root
+ *
+ * It can be used to build an external component.
+ * External component is a customizable subtree that can be composed with normal components.
+ * It allows third-party frameworks to render a subtree and then compose it together.
+ * However, the subtree must be created in the same backend context.
+ */
+export interface ExternalShadowRoot {
+  root: GeneralBackendElement
+  slot: GeneralBackendElement
+  getIdMap(): { [id: string]: GeneralBackendElement }
+  handleEvent<T>(target: GeneralBackendElement, event: Event<T>): void
+  setListener<T>(
+    elem: GeneralBackendElement,
+    ev: string,
+    listener: (event: ShadowedEvent<T>) => unknown,
+  ): void
+}