web-toolkit-x 0.0.1 → 0.70.0

package/src/core/lifecycle.ts

@@ -0,0 +1,301 @@
+import type {
+  ComponentDescription,
+  NodeDescription,
+  Props,
+} from './description.js'
+import type {
+  Component,
+  ParentVirtualNode,
+  VirtualNode,
+  WebComponent,
+} from './nodes.js'
+import Patch from './patch.js'
+
+/* The errors of the hooks called while collecting them, if collecting. */
+let hookErrors: unknown[] | null = null
+
+/*
+ * Calls a hook, collecting its error if collecting, so that a throwing hook
+ * does not stop the other hooks from being called.
+ */
+const callHook = (hook: () => void) => {
+  if (!hookErrors) {
+    return hook()
+  }
+  try {
+    hook()
+  } catch (error) {
+    hookErrors.push(error)
+  }
+}
+
+/*
+ * Calls the hook of a component being removed, ignoring the commands it
+ * issues. The dispatcher is shared with the root, so its mode is restored.
+ */
+const callIgnoringCommands = (component: Component, hook: () => void) => {
+  const { dispatcher } = component
+  const { mode } = dispatcher
+  dispatcher.ignoreIncoming()
+  try {
+    callHook(hook)
+  } finally {
+    dispatcher.mode = mode
+  }
+}
+
+/* Throws the errors, aggregated when there are more of them. */
+export const throwErrors = (errors: unknown[], message: string) => {
+  if (errors.length === 1) {
+    throw errors[0]
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, message)
+  }
+}
+
+const Lifecycle = {
+  /**
+   * Calls the hooks in the callback, collecting the errors they throw in
+   * the given list instead of stopping at the first one.
+   */
+  collectingErrors(errors: unknown[], callback: () => void) {
+    const prevErrors = hookErrors
+    hookErrors = errors
+    try {
+      callback()
+    } finally {
+      hookErrors = prevErrors
+    }
+  },
+
+  onComponentCreated(component: Component) {
+    if (component.hasOwnMethod('onCreated')) {
+      callHook(() => component.onCreated!.call(component.sandbox))
+    }
+    if (component.content) {
+      this.onNodeCreated(component.content)
+    }
+  },
+
+  onElementCreated(element: ParentVirtualNode) {
+    if (element.childNodes) {
+      for (const child of element.childNodes) {
+        this.onNodeCreated(child)
+      }
+    }
+  },
+
+  onNodeCreated(node: VirtualNode): void {
+    if (node.isElement()) {
+      return this.onElementCreated(node)
+    } else if (node.isComponent() && !node.isRoot()) {
+      return this.onComponentCreated(node)
+    }
+  },
+
+  onRootCreated(root: WebComponent) {
+    if (root.hasOwnMethod('onCreated')) {
+      callHook(() => root.onCreated!.call(root.sandbox))
+    }
+    const { childNodes } = root
+    if (childNodes) {
+      for (const child of childNodes) {
+        this.onNodeCreated(child)
+      }
+    }
+  },
+
+  onComponentAttached(component: Component) {
+    if (component.content) {
+      this.onNodeAttached(component.content)
+    }
+    if (component.hasOwnMethod('onAttached')) {
+      callHook(() => component.onAttached!.call(component.sandbox))
+    }
+  },
+
+  onElementAttached(element: ParentVirtualNode) {
+    if (element.childNodes) {
+      for (const child of element.childNodes) {
+        this.onNodeAttached(child)
+      }
+    }
+  },
+
+  onNodeAttached(node: VirtualNode): void {
+    if (node.isElement()) {
+      return this.onElementAttached(node)
+    } else if (node.isComponent() && !node.isRoot()) {
+      return this.onComponentAttached(node)
+    }
+  },
+
+  onNodeReceivedDescription(node: VirtualNode, description: NodeDescription) {
+    if (node.isComponent()) {
+      this.onComponentReceivedProps(
+        node,
+        (description as ComponentDescription).props,
+      )
+    }
+  },
+
+  onNodeUpdated(node: VirtualNode, prevDescription: NodeDescription) {
+    if (node.isComponent()) {
+      this.onComponentUpdated(
+        node,
+        (prevDescription as ComponentDescription).props,
+      )
+    }
+  },
+
+  onRootAttached(root: WebComponent) {
+    const { childNodes } = root
+    if (childNodes) {
+      for (const child of childNodes) {
+        this.onNodeAttached(child)
+      }
+    }
+    if (root.hasOwnMethod('onAttached')) {
+      callHook(() => root.onAttached!.call(root.sandbox))
+    }
+  },
+
+  onComponentReceivedProps(component: Component, nextProps: Props = {}) {
+    if (component.hasOwnMethod('onPropsReceived')) {
+      callHook(() =>
+        component.onPropsReceived!.call(component.sandbox, nextProps),
+      )
+    }
+  },
+
+  onComponentUpdated(component: Component, prevProps: Props = {}) {
+    if (component.hasOwnMethod('onUpdated')) {
+      callHook(() => component.onUpdated!.call(component.sandbox, prevProps))
+    }
+  },
+
+  onComponentDestroyed(component: Component) {
+    component.destroy()
+    if (component.hasOwnMethod('onDestroyed')) {
+      callIgnoringCommands(component, () =>
+        component.onDestroyed!.call(component.sandbox),
+      )
+    }
+    if (component.content) {
+      this.onNodeDestroyed(component.content)
+    }
+    if (component.isRoot()) {
+      this.onElementDestroyed(component)
+    }
+  },
+
+  onElementDestroyed(element: ParentVirtualNode) {
+    if (element.childNodes) {
+      for (const child of element.childNodes) {
+        this.onNodeDestroyed(child)
+      }
+    }
+  },
+
+  onNodeDestroyed(node: VirtualNode): void {
+    if (node.isElement()) {
+      return this.onElementDestroyed(node)
+    } else if (node.isComponent() && !node.isRoot()) {
+      return this.onComponentDestroyed(node)
+    }
+  },
+
+  onComponentDetached(component: Component) {
+    if (component.isRoot()) {
+      this.onElementDetached(component)
+    }
+    if (component.content) {
+      this.onNodeDetached(component.content)
+    }
+    if (component.hasOwnMethod('onDetached')) {
+      callIgnoringCommands(component, () =>
+        component.onDetached!.call(component.sandbox),
+      )
+    }
+  },
+
+  onElementDetached(element: ParentVirtualNode) {
+    if (element.childNodes) {
+      for (const child of element.childNodes) {
+        this.onNodeDetached(child)
+      }
+    }
+  },
+
+  onNodeDetached(node: VirtualNode) {
+    if (node.isElement()) {
+      this.onElementDetached(node)
+      node.parentNode = null
+    } else if (node.isComponent() && !node.isRoot()) {
+      this.onComponentDetached(node)
+      node.parentNode = null
+    }
+  },
+
+  beforeUpdate(patches: Patch[]) {
+    for (const patch of patches) {
+      this.beforePatchApplied(patch)
+    }
+  },
+
+  beforePatchApplied(patch: Patch) {
+    const Type = Patch.Type
+    switch (patch.type) {
+      case Type.INIT_ROOT_COMPONENT:
+        this.onRootCreated(patch.root)
+        return
+      case Type.INSERT_CHILD:
+        this.onNodeCreated(patch.node)
+        return
+      case Type.REPLACE_CHILD:
+      case Type.SET_CONTENT:
+        this.onNodeDestroyed(patch.child)
+        this.onNodeCreated(patch.node)
+        return
+      case Type.REMOVE_CHILD:
+        this.onNodeDestroyed(patch.child)
+        return
+      case Type.UPDATE_NODE:
+        this.onNodeReceivedDescription(patch.node, patch.description)
+        return
+    }
+  },
+
+  afterUpdate(patches: Patch[]) {
+    patches = [...patches].reverse()
+    for (const patch of patches) {
+      this.afterPatchApplied(patch)
+    }
+  },
+
+  afterPatchApplied(patch: Patch) {
+    const Type = Patch.Type
+    switch (patch.type) {
+      case Type.INIT_ROOT_COMPONENT:
+        this.onRootAttached(patch.root)
+        return
+      case Type.INSERT_CHILD:
+        this.onNodeAttached(patch.node)
+        return
+      case Type.REPLACE_CHILD:
+      case Type.SET_CONTENT:
+        this.onNodeDetached(patch.child)
+        this.onNodeAttached(patch.node)
+        return
+      case Type.REMOVE_CHILD:
+        this.onNodeDetached(patch.child)
+        return
+      case Type.UPDATE_NODE:
+        this.onNodeUpdated(patch.node, patch.prevDescription)
+        return
+    }
+  },
+}
+
+export default Lifecycle

package/src/core/nodes.ts

@@ -0,0 +1,13 @@
+/* The virtual DOM nodes, each one defined in its own module. */
+export type { ParentVirtualNode } from './child-nodes.js'
+export { default as Comment } from './comment.js'
+export {
+  default as Component,
+  type CleanUpTask,
+  type ComponentClass,
+  type Connectable,
+} from './component.js'
+export { default as Text } from './text.js'
+export { default as VirtualElement } from './virtual-element.js'
+export { default as VirtualNode, type NodeRef } from './virtual-node.js'
+export { default as WebComponent, default as Root } from './web-component.js'

package/src/core/patch.ts

@@ -0,0 +1,412 @@
+import type {
+  ComponentDescription,
+  Listener,
+  NodeDescription,
+} from './description.js'
+import DOM from './dom.js'
+import type {
+  Component,
+  ParentVirtualNode,
+  VirtualElement,
+  VirtualNode,
+  WebComponent,
+} from './nodes.js'
+
+/* A node rendered as an HTML element, e.g. a root with a custom element. */
+type PatchTarget = VirtualNode & { ref: HTMLElement }
+
+const Type = {
+  INIT_ROOT_COMPONENT: 'init-root-component',
+  UPDATE_NODE: 'update-node',
+  UPDATE_ROOT: 'update-root',
+  SET_ATTRIBUTE: 'set-attribute',
+  REMOVE_ATTRIBUTE: 'remove-attribute',
+  SET_DATA_ATTRIBUTE: 'set-data-attribute',
+  REMOVE_DATA_ATTRIBUTE: 'remove-data-attribute',
+  SET_STYLE_PROPERTY: 'set-style-property',
+  REMOVE_STYLE_PROPERTY: 'remove-style-property',
+  SET_CLASS_NAME: 'set-class-name',
+  ADD_LISTENER: 'add-listener',
+  REPLACE_LISTENER: 'replace-listener',
+  REMOVE_LISTENER: 'remove-listener',
+  SET_PROPERTY: 'set-property',
+  DELETE_PROPERTY: 'delete-property',
+  INSERT_CHILD: 'insert-child',
+  REPLACE_CHILD: 'replace-child',
+  MOVE_CHILD: 'move-child',
+  REMOVE_CHILD: 'remove-child',
+  SET_CONTENT: 'set-content',
+} as const
+
+/*
+ * A single change of the virtual and rendered DOM, applied by Patch.apply().
+ */
+type Patch =
+  | { type: 'init-root-component'; root: WebComponent }
+  | {
+      type: 'update-node'
+      node: VirtualNode
+      prevDescription: NodeDescription
+      description: NodeDescription
+    }
+  | {
+      type: 'update-root'
+      root: WebComponent
+      description: ComponentDescription
+    }
+  | {
+      type: 'set-attribute'
+      name: string
+      value: string
+      target: PatchTarget
+      isCustom: boolean
+    }
+  | {
+      type: 'remove-attribute'
+      name: string
+      target: PatchTarget
+      isCustom: boolean
+    }
+  | {
+      type: 'set-data-attribute'
+      name: string
+      value: string
+      target: PatchTarget
+    }
+  | { type: 'remove-data-attribute'; name: string; target: PatchTarget }
+  | {
+      type: 'set-style-property'
+      property: string
+      value: string
+      target: PatchTarget
+    }
+  | { type: 'remove-style-property'; property: string; target: PatchTarget }
+  | { type: 'set-class-name'; className: string; target: PatchTarget }
+  | {
+      type: 'add-listener'
+      name: string
+      listener: Listener
+      target: PatchTarget
+      isCustom: boolean
+    }
+  | {
+      type: 'replace-listener'
+      name: string
+      removed: Listener
+      added: Listener
+      target: PatchTarget
+      isCustom: boolean
+    }
+  | {
+      type: 'remove-listener'
+      name: string
+      listener: Listener
+      target: PatchTarget
+      isCustom: boolean
+    }
+  | { type: 'set-property'; key: string; value: unknown; target: PatchTarget }
+  | { type: 'delete-property'; key: string; target: PatchTarget }
+  | {
+      type: 'insert-child'
+      node: VirtualNode
+      at: number
+      parent: ParentVirtualNode
+    }
+  | {
+      type: 'replace-child'
+      child: VirtualNode
+      node: VirtualNode
+      parent: ParentVirtualNode
+    }
+  | {
+      type: 'move-child'
+      child: VirtualNode
+      from: number
+      to: number
+      parent: ParentVirtualNode
+    }
+  | {
+      type: 'remove-child'
+      child: VirtualNode
+      at: number
+      parent: ParentVirtualNode
+    }
+  | {
+      type: 'set-content'
+      node: VirtualNode
+      child: VirtualNode
+      parent: Component
+    }
+
+/* The patch of the given type. */
+type PatchOf<T extends Patch['type']> = Extract<Patch, { type: T }>
+
+const Patch = {
+  Type,
+
+  /**
+   * Applies the change to the virtual and rendered DOM.
+   */
+  apply(patch: Patch) {
+    switch (patch.type) {
+      case Type.INIT_ROOT_COMPONENT: {
+        const container = patch.root.container
+          ? patch.root.container
+          : patch.root.shadow!
+        container.appendChild(patch.root.content!.ref)
+        return
+      }
+      case Type.UPDATE_NODE:
+        patch.node.description = patch.description
+        return
+      case Type.UPDATE_ROOT:
+        patch.root.update(patch.description)
+        return
+      case Type.SET_ATTRIBUTE: {
+        const { target, name, value, isCustom } = patch
+        DOM.setAttribute(target.ref, name, value, isCustom)
+        return
+      }
+      case Type.REMOVE_ATTRIBUTE:
+        DOM.removeAttribute(patch.target.ref, patch.name, patch.isCustom)
+        return
+      case Type.SET_DATA_ATTRIBUTE:
+        DOM.setDataAttribute(patch.target.ref, patch.name, patch.value)
+        return
+      case Type.REMOVE_DATA_ATTRIBUTE:
+        DOM.removeDataAttribute(patch.target.ref, patch.name)
+        return
+      case Type.SET_STYLE_PROPERTY:
+        DOM.setStyleProperty(patch.target.ref, patch.property, patch.value)
+        return
+      case Type.REMOVE_STYLE_PROPERTY:
+        DOM.removeStyleProperty(patch.target.ref, patch.property)
+        return
+      case Type.SET_CLASS_NAME:
+        DOM.setClassName(patch.target.ref, patch.className)
+        return
+      case Type.ADD_LISTENER: {
+        const { target, name, listener, isCustom } = patch
+        DOM.addListener(target.ref, name, listener, isCustom)
+        return
+      }
+      case Type.REPLACE_LISTENER: {
+        const { target, name, removed, added, isCustom } = patch
+        DOM.removeListener(target.ref, name, removed, isCustom)
+        DOM.addListener(target.ref, name, added, isCustom)
+        return
+      }
+      case Type.REMOVE_LISTENER: {
+        const { target, name, listener, isCustom } = patch
+        DOM.removeListener(target.ref, name, listener, isCustom)
+        return
+      }
+      case Type.SET_PROPERTY:
+        DOM.setProperty(patch.target.ref, patch.key, patch.value)
+        return
+      case Type.DELETE_PROPERTY:
+        DOM.deleteProperty(patch.target.ref, patch.key)
+        return
+      case Type.INSERT_CHILD:
+        patch.parent.insertChild(patch.node, patch.at)
+        return
+      case Type.REPLACE_CHILD:
+        patch.parent.replaceChild(patch.child, patch.node)
+        return
+      case Type.MOVE_CHILD:
+        patch.parent.moveChild(patch.child, patch.from, patch.to)
+        return
+      case Type.REMOVE_CHILD:
+        patch.parent.removeChild(patch.child)
+        return
+      case Type.SET_CONTENT:
+        patch.parent.setContent(patch.node)
+        return
+      default: {
+        // fails to compile when a patch type is not handled above
+        const unsupported: never = patch
+        throw new Error(
+          `Unsupported patch type: ${(unsupported as Patch).type}`,
+        )
+      }
+    }
+  },
+
+  initRootComponent(root: WebComponent): PatchOf<'init-root-component'> {
+    return { type: Type.INIT_ROOT_COMPONENT, root }
+  },
+
+  updateNode(
+    node: VirtualNode,
+    description: NodeDescription,
+  ): PatchOf<'update-node'> {
+    return {
+      type: Type.UPDATE_NODE,
+      node,
+      prevDescription: node.description,
+      description,
+    }
+  },
+
+  /* Passes the props to a nested root, which renders them itself. */
+  updateRoot(
+    root: WebComponent,
+    description: ComponentDescription,
+  ): PatchOf<'update-root'> {
+    return { type: Type.UPDATE_ROOT, root, description }
+  },
+
+  insertChild(
+    node: VirtualNode,
+    at: number,
+    parent: ParentVirtualNode,
+  ): PatchOf<'insert-child'> {
+    return { type: Type.INSERT_CHILD, node, at, parent }
+  },
+
+  moveChild(
+    child: VirtualNode,
+    from: number,
+    to: number,
+    parent: ParentVirtualNode,
+  ): PatchOf<'move-child'> {
+    return { type: Type.MOVE_CHILD, child, from, to, parent }
+  },
+
+  replaceChild(
+    child: VirtualNode,
+    node: VirtualNode,
+    parent: ParentVirtualNode,
+  ): PatchOf<'replace-child'> {
+    return { type: Type.REPLACE_CHILD, child, node, parent }
+  },
+
+  removeChild(
+    child: VirtualNode,
+    at: number,
+    parent: ParentVirtualNode,
+  ): PatchOf<'remove-child'> {
+    return { type: Type.REMOVE_CHILD, child, at, parent }
+  },
+
+  setContent(node: VirtualNode, parent: Component): PatchOf<'set-content'> {
+    return { type: Type.SET_CONTENT, node, child: parent.content!, parent }
+  },
+
+  setAttribute(
+    name: string,
+    value: string,
+    target: VirtualElement | WebComponent,
+    isCustom: boolean,
+  ): PatchOf<'set-attribute'> {
+    return {
+      type: Type.SET_ATTRIBUTE,
+      name,
+      value,
+      target: target as PatchTarget,
+      isCustom,
+    }
+  },
+
+  removeAttribute(
+    name: string,
+    target: VirtualElement | WebComponent,
+    isCustom: boolean,
+  ): PatchOf<'remove-attribute'> {
+    return {
+      type: Type.REMOVE_ATTRIBUTE,
+      name,
+      target: target as PatchTarget,
+      isCustom,
+    }
+  },
+
+  setDataAttribute(
+    name: string,
+    value: string,
+    target: VirtualElement,
+  ): PatchOf<'set-data-attribute'> {
+    return { type: Type.SET_DATA_ATTRIBUTE, name, value, target }
+  },
+
+  removeDataAttribute(
+    name: string,
+    target: VirtualElement,
+  ): PatchOf<'remove-data-attribute'> {
+    return { type: Type.REMOVE_DATA_ATTRIBUTE, name, target }
+  },
+
+  setStyleProperty(
+    property: string,
+    value: string,
+    target: VirtualElement,
+  ): PatchOf<'set-style-property'> {
+    return { type: Type.SET_STYLE_PROPERTY, property, value, target }
+  },
+
+  removeStyleProperty(
+    property: string,
+    target: VirtualElement,
+  ): PatchOf<'remove-style-property'> {
+    return { type: Type.REMOVE_STYLE_PROPERTY, property, target }
+  },
+
+  setClassName(
+    className: string,
+    target: VirtualElement,
+  ): PatchOf<'set-class-name'> {
+    return { type: Type.SET_CLASS_NAME, className, target }
+  },
+
+  addListener(
+    name: string,
+    listener: Listener,
+    target: VirtualElement,
+    isCustom: boolean,
+  ): PatchOf<'add-listener'> {
+    return { type: Type.ADD_LISTENER, name, listener, target, isCustom }
+  },
+
+  replaceListener(
+    name: string,
+    removed: Listener,
+    added: Listener,
+    target: VirtualElement,
+    isCustom: boolean,
+  ): PatchOf<'replace-listener'> {
+    return {
+      type: Type.REPLACE_LISTENER,
+      name,
+      removed,
+      added,
+      target,
+      isCustom,
+    }
+  },
+
+  removeListener(
+    name: string,
+    listener: Listener,
+    target: VirtualElement,
+    isCustom: boolean,
+  ): PatchOf<'remove-listener'> {
+    return { type: Type.REMOVE_LISTENER, name, listener, target, isCustom }
+  },
+
+  setProperty(
+    key: string,
+    value: unknown,
+    target: VirtualElement,
+  ): PatchOf<'set-property'> {
+    return { type: Type.SET_PROPERTY, key, value, target }
+  },
+
+  deleteProperty(
+    key: string,
+    target: VirtualElement,
+  ): PatchOf<'delete-property'> {
+    return { type: Type.DELETE_PROPERTY, key, target }
+  },
+}
+
+export default Patch