web-toolkit-x 0.0.1 → 0.71.0

package/src/core/utils.ts

@@ -0,0 +1,148 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFunction = (...args: any[]) => unknown
+
+/*
+ * Checks a condition the toolkit relies on internally. Unlike
+ * toolkit.assert, which reports invalid usage, it throws in all modes.
+ */
+export function invariant(
+  condition: unknown,
+  message: string,
+): asserts condition {
+  if (!condition) {
+    throw new Error(message)
+  }
+}
+
+const throttle = <T extends AnyFunction>(
+  fn: T,
+  wait = 200,
+  delayFirstEvent = false,
+) => {
+  let lastTimestamp = 0
+  let taskId: ReturnType<typeof setTimeout> | null = null
+
+  let context: unknown
+  let params: Parameters<T>
+
+  return function throttled(this: unknown, ...args: Parameters<T>) {
+    if (!taskId) {
+      const timestamp = Date.now()
+      const elapsed = timestamp - lastTimestamp
+      const scheduleTask = (delay: number) => {
+        taskId = setTimeout(() => {
+          taskId = null
+          lastTimestamp = Date.now()
+          return fn.call(context, ...params)
+        }, delay)
+      }
+      if (elapsed >= wait) {
+        lastTimestamp = timestamp
+        if (!delayFirstEvent) {
+          return fn.call(this, ...args)
+        }
+        scheduleTask(wait)
+      } else {
+        scheduleTask(wait - elapsed)
+      }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-this-alias -- kept for the delayed call
+    context = this
+    params = args
+  }
+}
+
+const debounce = <T extends AnyFunction>(
+  fn: T,
+  wait = 200,
+  leading = false,
+) => {
+  let taskId: ReturnType<typeof setTimeout> | null = null
+  // whether the delayed call is needed, not when only the leading call was made
+  let isTrailing = false
+
+  let context: unknown
+  let params: Parameters<T>
+
+  return function debounced(this: unknown, ...args: Parameters<T>) {
+    const isFirstInvocation = !taskId
+    if (taskId) {
+      clearTimeout(taskId)
+    }
+    isTrailing = !(isFirstInvocation && leading)
+    taskId = setTimeout(() => {
+      taskId = null
+      if (isTrailing) {
+        fn.call(context, ...params)
+      }
+    }, wait)
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias -- kept for the delayed call
+    context = this
+    params = args
+
+    if (!isTrailing) {
+      return fn.call(context, ...params)
+    }
+  }
+}
+
+const createUUID = () => {
+  const s4 = () =>
+    Math.floor((1 + Math.random()) * 0x10000)
+      .toString(16)
+      .substring(1)
+  return `${s4()}${s4()}-${s4()}-${s4()}-${s4()}-${s4()}${s4()}${s4()}`
+}
+
+export const lowerDash = (name: string) =>
+  name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+
+export const getAttributeName = (key: string) => {
+  if (key === 'acceptCharset' || key === 'httpEquiv') {
+    return lowerDash(key)
+  } else if (key.startsWith('aria')) {
+    return `aria-${key.slice(4).toLowerCase()}`
+  }
+  return key.toLowerCase()
+}
+
+export const getEventName = (key: string) =>
+  key === 'onDoubleClick' ? 'dblclick' : key.slice(2).toLowerCase()
+
+const postRender = (fn: FrameRequestCallback) => {
+  // since Chromium 64 there are some problems with animations not being
+  // triggered correctly, this hack solves the problem across all OS-es
+
+  /* eslint-disable prefer-arrow-callback */
+  requestAnimationFrame(function () {
+    requestAnimationFrame(fn)
+  })
+  /* eslint-enable prefer-arrow-callback */
+}
+
+/* Checks if the arrays have the same items, in the same order. */
+export const isSameList = (a: readonly unknown[], b: readonly unknown[]) =>
+  a.length === b.length && a.every((item, index) => item === b[index])
+
+export const deepFreeze = <T>(obj: T): T => {
+  if (obj === null || typeof obj !== 'object' || Object.isFrozen(obj)) {
+    // functions are intentionally not frozen
+    return obj
+  }
+  Object.freeze(obj)
+  for (const property of Object.getOwnPropertyNames(obj)) {
+    deepFreeze((obj as Record<string, unknown>)[property])
+  }
+  return obj
+}
+
+/* The helpers of the public API, the others are used internally. */
+const Utils = {
+  throttle,
+  debounce,
+  createUUID,
+  postRender,
+}
+
+export default Utils

package/src/core/virtual-dom.ts

@@ -0,0 +1,118 @@
+import type { ComponentDescription, NodeDescription } from './description.js'
+import {
+  Comment,
+  type Component,
+  type ParentVirtualNode,
+  Text,
+  VirtualElement,
+  type VirtualNode,
+  WebComponent,
+} from './nodes.js'
+
+const VirtualDOM = {
+  /**
+   * Creates a new Virtual DOM structure from given description.
+   */
+  createFromDescription(
+    description: NodeDescription | null,
+    parent?: VirtualNode | null,
+    context?: WebComponent | null,
+  ): VirtualNode | null {
+    if (!description) {
+      return null
+    }
+    switch (description.type) {
+      case 'component':
+        return this.createComponent(description, parent, context)
+      case 'element': {
+        const element = new VirtualElement(description, parent, context)
+        this.createChildNodes(element)
+        return element
+      }
+      case 'comment':
+        return new Comment(description, parent!)
+      case 'text':
+        return new Text(description, parent!)
+      default:
+        throw new Error(
+          `Unsupported node type: ${(description as NodeDescription).type}`,
+        )
+    }
+  },
+
+  /**
+   * Creates the child nodes of an element or a Web Component.
+   */
+  createChildNodes(parent: ParentVirtualNode) {
+    const { children } = parent.description
+    if (children) {
+      parent.setChildNodes(
+        children.map(description =>
+          this.createFromDescription(description, parent, parent.context)!,
+        ),
+      )
+    }
+  },
+
+  /**
+   * Creates a new component instance from given description.
+   */
+  createComponent(
+    description: ComponentDescription,
+    parent?: VirtualNode | null,
+    context?: WebComponent | null,
+  ): Component {
+    const ComponentClass = description.component
+    if (ComponentClass.prototype instanceof WebComponent) {
+      return this.createWebComponent(
+        description,
+        parent && parent.rootNode,
+        context,
+        /*= requireCustomElement */ true,
+      )
+    }
+    const component = new ComponentClass(description, parent, context)
+    const nodeDescription = component.renderDescription(
+      description.props,
+      description.childrenAsTemplates,
+    )
+    component.content = this.createFromDescription(
+      nodeDescription,
+      component,
+      context,
+    )
+    return component
+  },
+
+  /**
+   * Creates a new Web Component instance from given description.
+   */
+  createWebComponent(
+    description: ComponentDescription,
+    parent?: VirtualNode | null,
+    context?: WebComponent | null,
+    requireCustomElement = false,
+  ): WebComponent {
+    try {
+      const ComponentClass = description.component as typeof WebComponent
+      if (requireCustomElement && !ComponentClass.elementName) {
+        throw new Error(
+          `Root component "${
+            ComponentClass.displayName
+          }" does not define custom element name!`,
+        )
+      }
+      const root = new ComponentClass(description, parent, context)
+      if (ComponentClass.elementName) {
+        // rendered in the light DOM of the custom element
+        this.createChildNodes(root)
+      }
+      return root
+    } catch (error) {
+      console.error('Error rendering root component:', description)
+      throw error
+    }
+  },
+}
+
+export default VirtualDOM

package/src/core/virtual-element.ts

@@ -0,0 +1,72 @@
+import ChildNodes from './child-nodes.js'
+import type { ElementDescription } from './description.js'
+import DOM from './dom.js'
+import VirtualNode from './virtual-node.js'
+import type WebComponent from './web-component.js'
+
+class VirtualElement extends VirtualNode {
+  static NodeType = 'element'
+
+  declare description: ElementDescription
+  declare ref: HTMLElement
+  declare children?: VirtualNode[]
+
+  constructor(
+    description: ElementDescription,
+    parent?: VirtualNode | null,
+    context?: WebComponent | null,
+  ) {
+    super(description, parent, context)
+    this.attachDOM()
+  }
+
+  /* The child nodes, as shared with Web Components. */
+  get childNodes(): VirtualNode[] | undefined {
+    return this.children
+  }
+
+  set childNodes(nodes: VirtualNode[] | undefined) {
+    if (nodes) {
+      this.children = nodes
+    } else {
+      delete this.children
+    }
+  }
+
+  get nodeType(): string {
+    return VirtualElement.NodeType
+  }
+
+  isCompatible(node: VirtualNode | null | undefined) {
+    return (
+      super.isCompatible(node) &&
+      this.description.name === (node as VirtualElement).description.name
+    )
+  }
+
+  setChildNodes(nodes: VirtualNode[]) {
+    ChildNodes.set(this, nodes)
+  }
+
+  insertChild(child: VirtualNode, index?: number) {
+    ChildNodes.insert(this, child, index)
+  }
+
+  replaceChild(child: VirtualNode, node: VirtualNode) {
+    ChildNodes.replace(this, child, node)
+  }
+
+  moveChild(child: VirtualNode, from: number, to: number) {
+    ChildNodes.move(this, child, from, to)
+  }
+
+  removeChild(child: VirtualNode) {
+    ChildNodes.remove(this, child)
+  }
+
+  attachDOM() {
+    this.ref = DOM.createElement(this.description)
+  }
+}
+
+export default VirtualElement

package/src/core/virtual-node.ts

@@ -0,0 +1,87 @@
+import type Comment from './comment.js'
+import type Component from './component.js'
+import type { NodeDescription } from './description.js'
+import type Text from './text.js'
+import type VirtualElement from './virtual-element.js'
+import type WebComponent from './web-component.js'
+
+/* The DOM node rendered for a virtual node. */
+export type NodeRef = Element | CharacterData
+
+/*
+ * An abstract parent node.
+ */
+abstract class VirtualNode {
+  declare description: NodeDescription
+  declare key?: string
+  declare parentNode: VirtualNode | null
+  declare context: WebComponent | null
+
+  abstract ref: NodeRef
+  abstract get nodeType(): string
+  abstract attachDOM(): void
+
+  constructor(
+    description: NodeDescription,
+    parentNode: VirtualNode | null = null,
+    context: WebComponent | null = null,
+  ) {
+    this.description = description
+    this.key = description.key
+    this.parentNode = parentNode
+    this.context = context
+  }
+
+  get parentElement(): VirtualNode | null {
+    if (this.parentNode) {
+      return this.parentNode.isElement()
+        ? this.parentNode
+        : this.parentNode.parentElement
+    }
+    return null
+  }
+
+  get container(): Element | VirtualNode | undefined {
+    if (this.parentNode) {
+      return this.parentNode.container
+    }
+    return this
+  }
+
+  get rootNode(): WebComponent {
+    if (this.isRoot()) {
+      return this
+    }
+    if (this.parentNode) {
+      return this.parentNode.rootNode
+    }
+    throw new Error('Inconsistent virtual DOM tree detected!')
+  }
+
+  isRoot(): this is WebComponent {
+    return this.nodeType === 'root'
+  }
+
+  isComponent(): this is Component {
+    const { nodeType } = this
+    return nodeType === 'component' || nodeType === 'root'
+  }
+
+  isElement(): this is VirtualElement {
+    return this.nodeType === 'element'
+  }
+
+  isComment(): this is Comment {
+    return this.nodeType === 'comment'
+  }
+
+  isText(): this is Text {
+    return this.nodeType === 'text'
+  }
+
+  isCompatible(node: VirtualNode | null | undefined) {
+    return node && this.nodeType === node.nodeType && this.key === node.key
+  }
+}
+
+export default VirtualNode

package/src/core/web-component.ts

@@ -0,0 +1,285 @@
+import ChildNodes from './child-nodes.js'
+import Comment from './comment.js'
+import Component from './component.js'
+import CreatedRoots from './created-roots.js'
+import { createComponentElement } from './custom-element.js'
+import { CommentDescription, type ComponentDescription } from './description.js'
+import Dispatcher, {
+  type BoundCommands,
+  type Commands,
+  type CommandsAPI,
+  type State,
+} from './dispatcher.js'
+import Plugins from './plugins.js'
+import { runtime } from './runtime.js'
+import Template from './template.js'
+import type VirtualNode from './virtual-node.js'
+import type { NodeRef } from './virtual-node.js'
+
+const CONTAINER = Symbol('container')
+const CUSTOM_ELEMENT = Symbol('custom-element')
+const DISPATCHER = Symbol('dispatcher')
+
+/*
+ * A root component with its own state, commands and plugins, rendered
+ * in a custom element when elementName is defined.
+ *
+ * P: props received from the parent,
+ * S: state, available as `this.props` when rendering,
+ * C: commands API set as the static commands, changing the state.
+ */
+class WebComponent<
+  P extends object = object,
+  S extends object = P,
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- no commands besides the core ones
+  C extends CommandsAPI<S> = {},
+> extends Component<S> {
+  static NodeType = 'root'
+
+  static styles: string[] = []
+
+  /*
+   * The child nodes rendered in the light DOM of the custom element,
+   * separate from the `children` templates available when rendering.
+   */
+  declare childNodes?: VirtualNode[]
+  declare subroots: Set<WebComponent>
+  declare ready: Promise<void>
+  declare markAsReady: () => void
+  declare markAsFailed: (error: Error) => void
+  declare plugins: Plugins | null
+  declare shadow: ShadowRoot | null
+  declare state?: S
+  declare pendingDescription?: ComponentDescription
+  declare stopTracking?: () => void
+  declare elementClass?: CustomElementConstructor;
+  declare [CONTAINER]?: Element;
+  declare [CUSTOM_ELEMENT]?: HTMLElement | null;
+  declare [DISPATCHER]: Dispatcher
+
+  constructor(
+    description: ComponentDescription,
+    parent: VirtualNode | null = null,
+    context: WebComponent | null = null,
+  ) {
+    super(description, parent, context, /*= attachDOM */ false)
+    // before being tracked, to be destroyed when rendering it fails
+    CreatedRoots.collectRoot(this)
+    this.subroots = new Set()
+    this.dispatcher = new Dispatcher(this)
+    this.ready = new Promise((resolve, reject) => {
+      this.markAsReady = resolve
+      this.markAsFailed = reject
+    })
+    this.plugins = this.createPlugins()
+    // from the start, for the plugins to be replaced when reconfigured
+    runtime().track(this)
+    this.content = this.createPlaceholder()
+    this.shadow = null
+    this.attachDOM()
+  }
+
+  attachDOM() {
+    if ((this.constructor as typeof WebComponent).elementName) {
+      this.ref = createComponentElement(this)
+      this.plugins!.installAll()
+    } else {
+      this.plugins!.installAll()
+      super.attachDOM()
+    }
+  }
+
+  createPlaceholder(): VirtualNode {
+    return new Comment(
+      new CommentDescription(
+        (this.constructor as typeof WebComponent).displayName,
+      ),
+    )
+  }
+
+  /**
+   * Triggers the initial rendering of the component in given container.
+   */
+  async init() {
+    // props are passed from templates, which are not checked against P
+    const state = await this.getInitialState.call(
+      this.sandbox,
+      (this.description.props || {}) as P,
+    )
+    this.setState(state)
+
+    if (this.pendingDescription) {
+      const description = this.pendingDescription
+      delete this.pendingDescription
+      setTimeout(() => this.update(description))
+    }
+    this.isInitialized = true
+    this.markAsReady()
+  }
+
+  setState(state: S) {
+    if (state.constructor !== Object) {
+      throw new Error('Web Component state must be a plain object!')
+    }
+    this.dispatcher.setState(
+      Template.normalizeComponentProps(
+        state as State,
+        this.constructor as typeof WebComponent,
+      ),
+    )
+  }
+
+  /**
+   * Triggers the component update.
+   */
+  update(description: ComponentDescription) {
+    if (!this.isInitialized) {
+      this.pendingDescription = description
+      return
+    }
+    const state = this.getUpdatedState(
+      (description.props || {}) as P,
+      this.state || ({} as S),
+    )
+    this.setState(state)
+  }
+
+  /**
+   * The default implementation delegating the calculation of initial state
+   * to the state manager.
+   */
+  getInitialState(props: P): S | Promise<S> {
+    // the default state is a copy of the props
+    return { ...props } as unknown as S
+  }
+
+  /**
+   * The default implementation delegating the calculation of updated state
+   * to the state manager.
+   */
+  getUpdatedState(props: P, state: S): S {
+    return {
+      ...state,
+      ...props,
+    }
+  }
+
+  get dispatcher(): Dispatcher {
+    return this[DISPATCHER]
+  }
+
+  set dispatcher(dispatcher: Dispatcher) {
+    this[DISPATCHER] = dispatcher
+  }
+
+  get commands(): Commands<S> & BoundCommands<C> {
+    return this.dispatcher.commands as Commands<S> & BoundCommands<C>
+  }
+
+  createPlugins(): Plugins {
+    const plugins = new Plugins(this)
+    const inherited = this.parentNode
+      ? (this.parentNode as WebComponent).plugins
+      : runtime().plugins
+    for (const plugin of inherited!) {
+      plugins.register(plugin)
+    }
+    return plugins
+  }
+
+  async mount(container: Element): Promise<this> {
+    if ((this.constructor as typeof WebComponent).elementName) {
+      // triggers this.init() from element's connected callback
+      container.appendChild(this.ref)
+      await this.ready
+    } else {
+      this.container = container
+      await this.init()
+    }
+    return this
+  }
+
+  getStylesheets(): string[] {
+    const stylesheets: string[] = []
+    const stylesheetProviders = [...this.plugins!].filter(plugin =>
+      plugin.isStylesheetProvider(),
+    )
+    for (const plugin of stylesheetProviders) {
+      if (typeof plugin.getStylesheets !== 'function') {
+        throw new Error(
+          `Plugin '${plugin.name}' must provide the getStylesheets() method!`,
+        )
+      }
+      stylesheets.push(...plugin.getStylesheets())
+    }
+    const RootClass = this.constructor as typeof WebComponent
+    if (Array.isArray(RootClass.styles)) {
+      stylesheets.push(...RootClass.styles)
+    }
+    return stylesheets
+  }
+
+  get ref(): NodeRef {
+    return this[CUSTOM_ELEMENT] || super.ref
+  }
+
+  set ref(ref: HTMLElement | null) {
+    this[CUSTOM_ELEMENT] = ref
+  }
+
+  set container(container: Element | undefined) {
+    this[CONTAINER] = container
+  }
+
+  get container(): Element | undefined {
+    return this[CONTAINER]
+  }
+
+  get tracked(): WebComponent[] {
+    const tracked: WebComponent[] = []
+    for (const root of this.subroots) {
+      tracked.push(root, ...root.tracked)
+    }
+    return tracked
+  }
+
+  destroy() {
+    if (!this.plugins) {
+      // already destroyed
+      return
+    }
+    super.destroy()
+    // not tracked when destroyed before being initialized
+    this.stopTracking?.()
+    this.dispatcher.ignoreIncoming()
+    this.plugins.destroy()
+    this.plugins = null
+    this.parentNode = null
+  }
+
+  setChildNodes(nodes: VirtualNode[]) {
+    ChildNodes.set(this, nodes)
+  }
+
+  insertChild(child: VirtualNode, index?: number) {
+    ChildNodes.insert(this, child, index)
+  }
+
+  replaceChild(child: VirtualNode, node: VirtualNode) {
+    ChildNodes.replace(this, child, node)
+  }
+
+  moveChild(child: VirtualNode, from: number, to: number) {
+    ChildNodes.move(this, child, from, to)
+  }
+
+  removeChild(child: VirtualNode) {
+    ChildNodes.remove(this, child)
+  }
+
+  get nodeType(): string {
+    return WebComponent.NodeType
+  }
+}
+
+export default WebComponent