web-toolkit-x 0.0.1 → 0.70.0

package/src/core/component.ts

@@ -0,0 +1,190 @@
+import type { Child, RenderResult } from './bragi.js'
+import {
+  CommentDescription,
+  type ComponentDescription,
+  type NodeDescription,
+  type Props,
+} from './description.js'
+import type Dispatcher from './dispatcher.js'
+import type { Commands, CommandsAPI } from './dispatcher.js'
+import { runtime } from './runtime.js'
+import Sandbox, { type ComponentSandbox } from './sandbox.js'
+import Template from './template.js'
+import { type AnyFunction, invariant } from './utils.js'
+import VirtualNode, { type NodeRef } from './virtual-node.js'
+import type WebComponent from './web-component.js'
+
+/* A task run when a component is destroyed, e.g. disconnecting a service. */
+export type CleanUpTask = (() => void) & { service?: unknown }
+
+/* A service components connect to, e.g. a subclass of Service. */
+export interface Connectable {
+  connect(listeners: Record<string, unknown>): () => void
+}
+
+/* The class of any component, whatever its props. */
+export type ComponentClass = typeof Component<object>
+
+/*
+ * Node representing Component in the virtual DOM tree.
+ * Components
+ */
+class Component<P extends object = object> extends VirtualNode {
+  static NodeType = 'component'
+
+  declare static elementName?: string
+  declare static defaultProps?: Props
+  declare static commands?: CommandsAPI | CommandsAPI[]
+
+  static get displayName(): string {
+    return this.name
+  }
+
+  declare description: ComponentDescription
+  declare sandbox: ComponentSandbox
+  declare cleanUpTasks: CleanUpTask[]
+  declare isInitialized: boolean
+  declare content: VirtualNode | null
+
+  /* The component props, available on the sandbox passed as `this`. */
+  declare props: P
+
+  /* The child templates, available on the sandbox passed as `this`. */
+  declare children: Child[]
+
+  onCreated?(): void
+  onAttached?(): void
+  onPropsReceived?(nextProps: P): void
+  onUpdated?(prevProps: P): void
+  onDestroyed?(): void
+  onDetached?(): void
+
+  constructor(
+    description: ComponentDescription,
+    parent?: VirtualNode | null,
+    context?: WebComponent | null,
+    attachDOM = true,
+  ) {
+    super(description, parent, context)
+    this.sandbox = Sandbox.create(this, COMPONENT_PROPERTIES)
+    this.cleanUpTasks = []
+    this.isInitialized = attachDOM
+    if (attachDOM) {
+      this.attachDOM()
+    }
+    // the rendered content is inserted right after instantiation
+    this.content = null
+  }
+
+  /**
+   * Sets the component content.
+   */
+  setContent(node: VirtualNode) {
+    invariant(
+      node.parentNode === this,
+      'Specified node does not have a valid parent!',
+    )
+    this.content!.parentNode = null
+    node.parentNode = this
+    this.content!.ref.replaceWith(node.ref)
+    this.content = node
+  }
+
+  hasOwnMethod(method: string): boolean {
+    // eslint-disable-next-line no-prototype-builtins
+    return (this.constructor as ComponentClass).prototype.hasOwnProperty(method)
+  }
+
+  connectTo(service: Connectable, listeners: Record<string, unknown>) {
+    runtime().assert(
+      typeof service.connect === 'function',
+      'Services have to define the connect() method',
+    )
+    const disconnect: CleanUpTask = service.connect(listeners)
+    runtime().assert(
+      typeof disconnect === 'function',
+      'The result of the connect() method has to be a disconnect() method',
+    )
+    disconnect.service = service
+    this.cleanUpTasks.push(disconnect)
+  }
+
+  get childElement(): VirtualNode | null {
+    if (this.content) {
+      if (this.content.isElement() || this.content.isRoot()) {
+        return this.content
+      }
+      if (this.content.isComponent()) {
+        return this.content.childElement
+      }
+    }
+    return null
+  }
+
+  get placeholder(): VirtualNode | null {
+    if (this.content!.isComment()) {
+      return this.content
+    }
+    return (this.content as Component).placeholder || null
+  }
+
+  render(): RenderResult {
+    return undefined
+  }
+
+  /**
+   * Calls the render method and transforms the returned template
+   * into the normalised description of the rendered node.
+   */
+  renderDescription(
+    props: Props = {},
+    children: unknown[] = [],
+  ): NodeDescription | null {
+    this.sandbox.props = props
+    this.sandbox.children = children
+    const template = this.render.call(this.sandbox)
+    if (template) {
+      return Template.describe(template)
+    }
+    const text = (this.constructor as ComponentClass).displayName
+    return new CommentDescription(text)
+  }
+
+  /* The commands of the root component, whose types are not known here. */
+  get commands(): Commands<unknown> & Record<string, AnyFunction> {
+    return this.context ? this.context.commands : this.rootNode.commands
+  }
+
+  get dispatcher(): Dispatcher {
+    return this.context ? this.context.dispatcher : this.rootNode.dispatcher
+  }
+
+  destroy() {
+    for (const cleanUpTask of this.cleanUpTasks) {
+      cleanUpTask()
+    }
+  }
+
+  get nodeType(): string {
+    return Component.NodeType
+  }
+
+  get ref(): NodeRef {
+    return this.content!.ref
+  }
+
+  isCompatible(node: VirtualNode | null | undefined) {
+    return super.isCompatible(node) && this.constructor === node!.constructor
+  }
+
+  attachDOM() {
+    if (this.content) {
+      this.content.attachDOM()
+    }
+  }
+}
+
+/* The properties of the Component class hidden from the sandbox. */
+const COMPONENT_PROPERTIES = Object.getOwnPropertyNames(Component.prototype)
+
+export default Component

package/src/core/created-roots.ts

@@ -0,0 +1,38 @@
+import type { WebComponent } from './nodes.js'
+
+/* The roots created by the function called by destroyingRootsOnError(). */
+let createdRoots: WebComponent[] | null = null
+
+const CreatedRoots = {
+  /**
+   * Calls the function, destroying the roots it creates when it throws.
+   * They are neither attached nor destroyed by the lifecycle then, but
+   * would stay tracked, with the plugins installed.
+   */
+  destroyingRootsOnError<T>(fn: () => T): T {
+    const outerRoots = createdRoots
+    const roots: WebComponent[] = []
+    createdRoots = roots
+    try {
+      const result = fn()
+      outerRoots?.push(...roots)
+      return result
+    } catch (error) {
+      for (const root of roots.reverse()) {
+        root.destroy()
+      }
+      throw error
+    } finally {
+      createdRoots = outerRoots
+    }
+  },
+
+  /**
+   * Records a root being created, see destroyingRootsOnError().
+   */
+  collectRoot(root: WebComponent) {
+    createdRoots?.push(root)
+  },
+}
+
+export default CreatedRoots

package/src/core/custom-element.ts

@@ -0,0 +1,191 @@
+import DOM from './dom.js'
+import Lifecycle, { throwErrors } from './lifecycle.js'
+import type { WebComponent } from './nodes.js'
+import Plugins, { type Plugin, type PluginManifest } from './plugins.js'
+import { isSameList } from './utils.js'
+
+const cssImports = (paths: string[]) =>
+  paths.map(path => `@import url(${path});`).join('\n')
+
+type PluginOrManifest = Plugin | PluginManifest
+
+export class ComponentElement extends HTMLElement {
+  declare $root: WebComponent | null
+  declare pendingDestruction?: ReturnType<typeof setTimeout>
+  declare stylesheets: string[]
+  declare styleElement: HTMLStyleElement | null
+  declare stylesheetsLoaded: Promise<void>
+  declare install: (plugin: PluginOrManifest, cascade?: boolean) => void
+  declare uninstall: (
+    plugin: PluginOrManifest | string,
+    cascade?: boolean,
+  ) => void
+
+  constructor(root: WebComponent) {
+    super()
+    this.$root = root
+    this.stylesheets = []
+    this.styleElement = null
+    this.stylesheetsLoaded = Promise.resolve()
+
+    addPluginsAPI(this)
+
+    root.shadow = this.attachShadow({
+      mode: 'open',
+    })
+
+    const stylesheets = root.getStylesheets()
+
+    const init = () => {
+      root.init().catch((error: Error) => root.markAsFailed(error))
+    }
+
+    if (stylesheets.length) {
+      // rejects mounting, as the errors are not thrown to the caller
+      this.loadStylesheets(stylesheets).then(init, (error: Error) =>
+        root.markAsFailed(error),
+      )
+    } else {
+      init()
+    }
+  }
+
+  /**
+   * Replaces the stylesheets imported in the shadow root, keeping the
+   * previous ones until the new ones are loaded.
+   */
+  loadStylesheets(stylesheets: string[]): Promise<void> {
+    const previous = this.styleElement
+    this.stylesheets = stylesheets
+    let loaded = Promise.resolve()
+    if (stylesheets.length) {
+      const style = document.createElement('style')
+      style.textContent = cssImports(stylesheets)
+      loaded = new Promise((resolve, reject) => {
+        style.onload = () => resolve()
+        style.onerror = () =>
+          reject(
+            new Error(`Error loading stylesheets: ${stylesheets.join(', ')}`),
+          )
+      })
+      if (previous) {
+        previous.after(style)
+      } else {
+        this.shadowRoot!.prepend(style)
+      }
+      this.styleElement = style
+    } else {
+      this.styleElement = null
+    }
+    if (previous) {
+      // removed once loaded, as the root may be waiting to be initialized
+      void Promise.allSettled([this.stylesheetsLoaded, loaded]).then(() =>
+        previous.remove(),
+      )
+    }
+    this.stylesheetsLoaded = loaded
+    return loaded
+  }
+
+  get isComponentElement() {
+    return true
+  }
+
+  connectedCallback() {
+    clearTimeout(this.pendingDestruction)
+  }
+
+  disconnectedCallback() {
+    this.pendingDestruction = setTimeout(() => this.destroy(), 50)
+  }
+
+  destroy() {
+    const root = this.$root
+    if (!root) {
+      // already destroyed, e.g. directly before the scheduled destruction
+      return
+    }
+    // the hooks of all the components are called when some of them throw
+    const errors: unknown[] = []
+    Lifecycle.collectingErrors(errors, () => {
+      Lifecycle.onComponentDestroyed(root)
+      Lifecycle.onComponentDetached(root)
+    })
+    root.ref = null
+    this.$root = null
+    throwErrors(errors, 'Errors destroying the component')
+  }
+}
+
+const addPluginsAPI = (element: ComponentElement) => {
+  const { Plugin } = Plugins
+  element.install = (plugin, cascade = true) => {
+    const installTo = (root: WebComponent) => {
+      if (plugin instanceof Plugin) {
+        root.plugins!.registry.add(plugin)
+        root.plugins!.install(plugin)
+      } else {
+        root.plugins!.install(plugin)
+      }
+      if (cascade) {
+        for (const subroot of root.subroots) {
+          installTo(subroot)
+        }
+      }
+    }
+    installTo(element.$root!)
+  }
+  element.uninstall = (plugin, cascade = true) => {
+    const name = typeof plugin === 'string' ? plugin : plugin.name
+    const uninstallFrom = (root: WebComponent) => {
+      root.plugins!.uninstall(name)
+      if (cascade) {
+        for (const subroot of root.subroots) {
+          uninstallFrom(subroot)
+        }
+      }
+    }
+    uninstallFrom(element.$root!)
+  }
+}
+
+/**
+ * Loads the stylesheets of the root in its custom element when they
+ * changed, e.g. with the plugins reconfigured.
+ */
+export const updateStylesheets = (root: WebComponent) => {
+  const element = root.ref as ComponentElement
+  const stylesheets = root.getStylesheets()
+  if (!isSameList(stylesheets, element.stylesheets)) {
+    element
+      .loadStylesheets(stylesheets)
+      .catch((error: unknown) => console.error(error))
+  }
+}
+
+/**
+ * Creates a new Custom Element instance assigned to specified Web Component.
+ */
+export const createComponentElement = (
+  root: WebComponent,
+): ComponentElement => {
+  const defineCustomElementClass = (RootClass: typeof WebComponent) => {
+    let ElementClass = customElements.get(RootClass.elementName!) as
+      typeof ComponentElement | undefined
+    if (!ElementClass) {
+      ElementClass = class RootElement extends ComponentElement {}
+      customElements.define(RootClass.elementName!, ElementClass)
+      RootClass.prototype.elementClass = ElementClass
+    }
+    return ElementClass
+  }
+  const ElementClass = defineCustomElementClass(
+    root.constructor as typeof WebComponent,
+  )
+  const element = new ElementClass(root)
+  // the attributes of a root are custom, as set by the diff
+  for (const [name, value] of Object.entries(root.description.attrs ?? {})) {
+    DOM.setAttribute(element, name, value, true)
+  }
+  return element
+}

package/src/core/description.ts

@@ -0,0 +1,241 @@
+import type { ComponentClass } from './nodes.js'
+
+export type Props = Record<string, unknown>
+
+/* An event listener, possibly bound to a component by its sandbox. */
+export type Listener = ((event: Event) => unknown) & { source?: unknown }
+
+export type NodeDescription =
+  | ComponentDescription
+  | ElementDescription
+  | CommentDescription
+  | TextDescription
+
+/* A normalized template, as returned by the asTemplate getters. */
+export type NormalizedTemplate = unknown[] | string | null
+
+/*
+ * Normalized description of a template.
+ * Is used to calculate differences between nodes.
+ */
+abstract class Description {
+  declare static ElementDescription: typeof ElementDescription
+  declare static ComponentDescription: typeof ComponentDescription
+  declare static CommentDescription: typeof CommentDescription
+  declare static TextDescription: typeof TextDescription
+
+  declare key?: string
+  declare children?: NodeDescription[]
+
+  abstract get asTemplate(): NormalizedTemplate
+
+  get childrenAsTemplates(): NormalizedTemplate[] | undefined {
+    if (this.children) {
+      return this.children.map(child => child.asTemplate)
+    }
+    return undefined
+  }
+
+  isCompatible(description: Description): boolean {
+    return this.constructor === description.constructor
+  }
+}
+
+/*
+ * Defines a normalized description of a component.
+ *
+ * Enumerable properties:
+ * - key (a unique node identifier within its parent),
+ * - component (an object with meta information)
+ * - children (an array of child nodes)
+ * - props (an object of any component rendering props)
+ *
+ * Non-enumerable properties:
+ * - asTemplate: returns component description as a normalized template
+ */
+class ComponentDescription extends Description {
+  declare component: ComponentClass
+  declare type: 'component'
+  declare props?: Props
+  declare attrs?: Record<string, string>
+
+  constructor(component: ComponentClass) {
+    super()
+    this.component = component
+    this.type = 'component'
+  }
+
+  isCompatible(description: Description): boolean {
+    return (
+      super.isCompatible(description) &&
+      this.component === (description as ComponentDescription).component
+    )
+  }
+
+  get isRoot(): boolean {
+    // the node type is inherited from the Root class
+    return this.component.NodeType === 'root'
+  }
+
+  get asTemplate(): unknown[] {
+    const template: unknown[] = [this.component]
+    if (this.props) {
+      template.push(this.props)
+    }
+    if (this.children) {
+      template.push(...this.children.map(child => child.asTemplate))
+    }
+    return template
+  }
+}
+
+/*
+ * Defines a normalized description of an element.
+ *
+ * Enumerable properties:
+ * - key (a unique node identifier within its parent),
+ * - name (a string representing tag name),
+ * - children (an array of child nodes),
+ * - props (an object) defining:
+ *    - class (a class name string)
+ *    - style (an object for style property to string value mapping)
+ *    - listeners (an object for event name to listener mapping)
+ *    - attrs (an object for normalized attribute name to value mapping)
+ *    - dataset (an object representing data attributes)
+ *    - properties (an object for properties set directly on DOM element)
+ *
+ * Non-enumerable properties:
+ * - asTemplate: returns element description as a normalized template
+ */
+class ElementDescription extends Description {
+  declare name: string
+  declare type: 'element'
+  declare class?: string
+  declare style?: Record<string, string>
+  declare attrs?: Record<string, string>
+  declare dataset?: Record<string, string>
+  declare listeners?: Record<string, Listener>
+  declare properties?: Record<string, unknown>
+  declare custom?: {
+    attrs?: Record<string, string>
+    listeners?: Record<string, Listener>
+  }
+
+  constructor(name: string) {
+    super()
+    this.name = name
+    this.type = 'element'
+  }
+
+  isCompatible(description: Description): boolean {
+    return (
+      super.isCompatible(description) &&
+      this.name === (description as ElementDescription).name
+    )
+  }
+
+  get asTemplate(): unknown[] {
+    const template: unknown[] = [this.name]
+    const props: Record<string, unknown> = {}
+    if (this.key) {
+      props.key = this.key
+    }
+    if (this.class) {
+      props.class = this.class
+    }
+    if (this.style) {
+      props.style = this.style
+    }
+    if (this.attrs) {
+      Object.assign(props, this.attrs)
+    }
+    if (this.dataset) {
+      props.dataset = this.dataset
+    }
+    if (this.listeners) {
+      Object.assign(props, this.listeners)
+    }
+    if (this.properties) {
+      props.properties = this.properties
+    }
+    if (this.custom?.attrs) {
+      props.attrs = this.custom.attrs
+    }
+    if (this.custom?.listeners) {
+      props.on = this.custom.listeners
+    }
+    if (Object.keys(props).length) {
+      template.push(props)
+    }
+    if (this.children) {
+      template.push(...this.children.map(child => child.asTemplate))
+    }
+    return template
+  }
+}
+
+/*
+ * Description of a Comment node.
+ */
+class CommentDescription extends Description {
+  declare text: string
+  declare type: 'comment'
+
+  constructor(text: string) {
+    super()
+    this.text = text
+    this.type = 'comment'
+  }
+
+  get asTemplate(): null {
+    return null
+  }
+
+  isCompatible(description: Description): boolean {
+    return (
+      super.isCompatible(description) &&
+      this.text === (description as CommentDescription).text
+    )
+  }
+}
+
+/*
+ * Description of a Text node.
+ */
+class TextDescription extends Description {
+  declare text: string
+  declare type: 'text'
+
+  constructor(text: string) {
+    super()
+    this.text = text
+    this.type = 'text'
+  }
+
+  get asTemplate(): string {
+    return this.text
+  }
+
+  isCompatible(description: Description): boolean {
+    return (
+      super.isCompatible(description) &&
+      this.text === (description as TextDescription).text
+    )
+  }
+}
+
+Object.assign(Description, {
+  ElementDescription,
+  ComponentDescription,
+  CommentDescription,
+  TextDescription,
+})
+
+export {
+  ElementDescription,
+  ComponentDescription,
+  CommentDescription,
+  TextDescription,
+}
+
+export default Description