web-toolkit-x 0.0.1 → 0.70.0

package/src/core/plugins.ts

@@ -0,0 +1,231 @@
+import type { WebComponent } from './nodes.js'
+import type { Update } from './renderer.js'
+import Sandbox from './sandbox.js'
+import { runtime } from './runtime.js'
+
+const Permission = {
+  LISTEN_FOR_UPDATES: 'listen-for-updates',
+  REGISTER_METHOD: 'register-method',
+  INJECT_STYLESHEETS: 'inject-stylesheets',
+}
+
+/* The API a plugin receives in its register() method. */
+export interface PluginSandbox {
+  registerMethod?(name: string): void
+}
+
+export interface PluginManifest {
+  name: string
+  permissions?: string[]
+  register?(sandbox: PluginSandbox): void
+  install?(root: WebComponent): () => void
+  onBeforeUpdate?(update: Update): void
+  onAfterUpdate?(update: Update): void
+  getStylesheets?(): string[]
+  [key: string]: unknown
+}
+
+class Plugin {
+  declare name: string
+  declare permissions: string[]
+  declare origin: PluginManifest
+  declare register?: () => void
+  declare install?: (root: WebComponent) => () => void
+  declare onBeforeUpdate?: (update: Update) => void
+  declare onAfterUpdate?: (update: Update) => void
+  declare getStylesheets?: () => string[]
+
+  constructor(manifest: PluginManifest) {
+    runtime().assert(
+      typeof manifest.name === 'string' && manifest.name.length,
+      'Plugin name must be a non-empty string!',
+    )
+
+    Object.assign(this, manifest)
+    this.origin = manifest
+
+    if (this.permissions === undefined) {
+      this.permissions = []
+    } else {
+      runtime().assert(
+        Array.isArray(this.permissions),
+        'Plugin permissions must be an array',
+      )
+      this.permissions = this.permissions.filter(permission =>
+        Object.values(Permission).includes(permission),
+      )
+    }
+
+    const sandbox = this.createSandbox()
+    if (typeof manifest.register === 'function') {
+      this.register = () => manifest.register!(sandbox)
+    }
+    if (typeof manifest.install === 'function') {
+      this.install = root => {
+        const uninstall = manifest.install!(root)
+        runtime().assert(
+          typeof uninstall === 'function',
+          'The plugin installation must return the uninstall function!',
+        )
+        return uninstall
+      }
+    }
+  }
+
+  isListener(): boolean {
+    return this.permissions.includes(Permission.LISTEN_FOR_UPDATES)
+  }
+
+  isStylesheetProvider(): boolean {
+    return this.permissions.includes(Permission.INJECT_STYLESHEETS)
+  }
+
+  createSandbox(): PluginSandbox {
+    const sandbox: PluginSandbox = {}
+    for (const permission of this.permissions) {
+      switch (permission) {
+        case Permission.REGISTER_METHOD:
+          sandbox.registerMethod = name => Sandbox.registerPluginMethod(name)
+      }
+    }
+    return sandbox
+  }
+}
+
+class Registry {
+  declare plugins: Map<string, Plugin>
+  declare cache: { listeners: Plugin[] };
+  declare [Symbol.iterator]: () => Iterator<Plugin>
+
+  constructor() {
+    this.plugins = new Map()
+    this.cache = {
+      listeners: [],
+    }
+    this[Symbol.iterator] = () => this.plugins.values()[Symbol.iterator]()
+  }
+
+  /**
+   * Adds the plugin to the registry
+   */
+  add(plugin: Plugin) {
+    runtime().assert(
+      !this.isRegistered(plugin.name),
+      `Plugin '${plugin.name}' is already registered!`,
+    )
+    this.plugins.set(plugin.name, plugin)
+    this.updateCache()
+  }
+
+  /**
+   * Removes the plugin with specified name from the registry.
+   */
+  remove(name: string) {
+    this.plugins.delete(name)
+    this.updateCache()
+  }
+
+  /**
+   * Checks if plugin with specified name exists in the registry.
+   */
+  isRegistered(name: string): boolean {
+    return this.plugins.has(name)
+  }
+
+  /**
+   * Updates the cache.
+   */
+  updateCache() {
+    const plugins = [...this.plugins.values()]
+    this.cache.listeners = plugins.filter(plugin => plugin.isListener())
+  }
+}
+
+class Plugins {
+  static Plugin = Plugin
+
+  declare root: WebComponent | null
+  declare registry: Registry
+  declare uninstalls: Map<string, () => void>;
+  declare [Symbol.iterator]: () => Iterator<Plugin>
+
+  constructor(root: WebComponent | null) {
+    this.root = root
+    this.registry = new Registry()
+    this.uninstalls = new Map()
+    this[Symbol.iterator] = () => this.registry[Symbol.iterator]()
+  }
+
+  /**
+   * Creates a Plugin instance from the manifest object and registers it.
+   */
+  register(plugin: Plugin | PluginManifest) {
+    if (!(plugin instanceof Plugin)) {
+      plugin = new Plugin(plugin)
+    }
+    if (plugin.register) {
+      plugin.register()
+    }
+    this.registry.add(plugin)
+  }
+
+  installAll() {
+    for (const plugin of this.registry) {
+      this.install(plugin)
+    }
+  }
+
+  install(plugin: Plugin | PluginManifest) {
+    if (this.root && plugin.install) {
+      const uninstall = plugin.install(this.root)
+      this.uninstalls.set(plugin.name, uninstall)
+    }
+  }
+
+  /**
+   * Removes the plugin from the registry and invokes it's uninstall method
+   * if present.
+   */
+  uninstall(name: string) {
+    const uninstall = this.uninstalls.get(name)
+    this.uninstalls.delete(name)
+    this.registry.remove(name)
+    if (uninstall) {
+      uninstall()
+    }
+  }
+
+  /**
+   * Uninstalls all the plugins from the registry.
+   */
+  destroy() {
+    for (const plugin of this.registry) {
+      this.uninstall(plugin.name)
+    }
+    this.root = null
+  }
+
+  /**
+   * Invokes listener methods on registered listener plugins.
+   */
+  notify(action: 'before-update' | 'after-update', event: Update) {
+    switch (action) {
+      case 'before-update':
+        for (const listener of this.registry.cache.listeners) {
+          listener.onBeforeUpdate!(event)
+        }
+        return
+      case 'after-update':
+        for (const listener of this.registry.cache.listeners) {
+          listener.onAfterUpdate!(event)
+        }
+        return
+      default:
+        throw new Error(`Unknown action: ${action as string}`)
+    }
+  }
+}
+
+export type { Plugin }
+
+export default Plugins

package/src/core/reconciler.ts

@@ -0,0 +1,185 @@
+const Name = {
+  INSERT: Symbol('insert'),
+  MOVE: Symbol('move'),
+  REMOVE: Symbol('remove'),
+}
+
+interface MoveProps {
+  at?: number
+  from?: number
+  to?: number
+}
+
+class Move<T = unknown> {
+  static Name = Name
+
+  declare name: symbol
+  declare item: T
+  declare at?: number
+  declare from?: number
+  declare to?: number
+  declare make: (items: T[]) => void
+
+  constructor(
+    name: symbol,
+    item: T,
+    props: MoveProps,
+    make: (items: T[]) => void,
+  ) {
+    this.name = name
+    this.item = item
+    this.at = props.at
+    this.from = props.from
+    this.to = props.to
+    this.make = make
+  }
+
+  static insert<T>(item: T, at: number): Move<T> {
+    return new Move(Name.INSERT, item, { at }, items => {
+      items.splice(at, 0, item)
+    })
+  }
+
+  static move<T>(item: T, from: number, to: number): Move<T> {
+    return new Move(Name.MOVE, item, { from, to }, items => {
+      items.splice(from, 1)
+      items.splice(to, 0, item)
+    })
+  }
+
+  static remove<T>(item: T, at: number): Move<T> {
+    return new Move(Name.REMOVE, item, { at }, items => {
+      items.splice(at, 1)
+    })
+  }
+}
+
+/* The moves transforming the source into the target, with the result. */
+export type Moves = Move<string>[] & { result?: string[] }
+
+interface Item {
+  key: string
+  index: number
+}
+
+const Reconciler = {
+  comparator(this: void, a: Item, b: Item): number {
+    if (Object.is(a.key, b.key)) {
+      return 0
+    }
+    return a.key > b.key ? 1 : -1
+  },
+
+  calculateMoves(source: string[], target: string[]): Moves {
+    const moves: Moves = []
+
+    const createItem = function (key: string, index: number): Item {
+      return { key, index }
+    }
+
+    const before = source.map(createItem).sort(this.comparator)
+    const after = target.map(createItem).sort(this.comparator)
+
+    let removed: Item[] = []
+    let inserted: Item[] = []
+
+    while (before.length || after.length) {
+      if (!before.length) {
+        inserted = inserted.concat(after)
+        break
+      }
+      if (!after.length) {
+        removed = removed.concat(before)
+        break
+      }
+      const result = this.comparator(after[0]!, before[0]!)
+      if (result === 0) {
+        before.shift()
+        after.shift()
+      } else if (result === 1) {
+        removed.push(before.shift()!)
+      } else {
+        inserted.push(after.shift()!)
+      }
+    }
+
+    const sortByIndex = function (foo: Item, bar: Item) {
+      return foo.index - bar.index
+    }
+
+    removed.sort(sortByIndex).reverse()
+    inserted.sort(sortByIndex)
+
+    const result = [...source]
+
+    for (const item of removed) {
+      const move = Move.remove(item.key, item.index)
+      move.make(result)
+      moves.push(move)
+    }
+    for (const item of inserted) {
+      const move = Move.insert(item.key, item.index)
+      move.make(result)
+      moves.push(move)
+    }
+
+    if (
+      result.length === target.length &&
+      result.every((key, index) => key === target[index])
+    ) {
+      moves.result = result
+      return moves
+    }
+
+    const calculateIndexChanges = (
+      source: string[],
+      target: string[],
+      reversed = false,
+    ) => {
+      const moves: Moves = []
+
+      const moveItemIfNeeded = (index: number) => {
+        const item = target[index]!
+        if (source[index] !== item) {
+          const from = source.indexOf(item)
+          const move = Move.move(item, from, index)
+          move.make(source)
+          moves.push(move)
+        }
+      }
+
+      if (reversed) {
+        for (let i = target.length - 1; i >= 0; i--) {
+          moveItemIfNeeded(i)
+        }
+      } else {
+        for (let i = 0; i < target.length; i++) {
+          moveItemIfNeeded(i)
+        }
+      }
+      moves.result = source
+      return moves
+    }
+
+    const defaultMoves = calculateIndexChanges([...result], target)
+    if (defaultMoves.length > 1) {
+      const alternativeMoves = calculateIndexChanges(
+        [...result],
+        target,
+        /*= reversed */ true,
+      )
+      if (alternativeMoves.length <= defaultMoves.length) {
+        moves.push(...alternativeMoves)
+        moves.result = alternativeMoves.result
+        return moves
+      }
+    }
+    moves.push(...defaultMoves)
+    moves.result = defaultMoves.result
+    return moves
+  },
+
+  Move,
+}
+
+export default Reconciler

package/src/core/renderer.ts

@@ -0,0 +1,75 @@
+import type { NodeDescription, Props } from './description.js'
+import Diff from './diff.js'
+import type { Command, State } from './dispatcher.js'
+import type { Component, WebComponent } from './nodes.js'
+import type Patch from './patch.js'
+
+/* Information about a root component update, passed to plugin listeners. */
+export interface Update {
+  commands: Command[]
+  root: WebComponent
+  state: {
+    from: State | undefined
+    to: State
+  }
+  patches?: Patch[]
+}
+
+const Renderer = {
+  /**
+   * Calls the component render method and transforms the returned template
+   * into the normalised description of the rendered node.
+   */
+  render(
+    component: Component,
+    props: Props = {},
+    children: unknown[] = [],
+  ): NodeDescription | null {
+    return component.renderDescription(props, children)
+  },
+
+  /**
+   * Updates the Web component and patches the DOM tree
+   * to match the new component state.
+   */
+  update(
+    root: WebComponent,
+    from: State | undefined,
+    to: State,
+    commands: Command[],
+  ) {
+    const update: Update = {
+      commands,
+      root,
+      state: {
+        from,
+        to,
+      },
+    }
+
+    this.onBeforeUpdate(update, root)
+
+    const diff = new Diff(root, from, to)
+    // set when the patches are calculated, kept when rendering them fails
+    root.state = to
+    update.patches = diff.apply()
+
+    this.onAfterUpdate(update, root)
+  },
+
+  /**
+   * Notifies the observers about upcoming update.
+   */
+  onBeforeUpdate(update: Update, root: WebComponent) {
+    root.plugins!.notify('before-update', update)
+  },
+
+  /**
+   * Notifies the observers about completed update.
+   */
+  onAfterUpdate(update: Update, root: WebComponent) {
+    root.plugins!.notify('after-update', update)
+  },
+}
+
+export default Renderer

package/src/core/runtime.ts

@@ -0,0 +1,36 @@
+import type { Command, State } from './dispatcher.js'
+import type { ComponentClass, WebComponent } from './nodes.js'
+import type Plugins from './plugins.js'
+import type { ItemType } from './template.js'
+import { invariant } from './utils.js'
+
+/*
+ * The services of the Toolkit instance the core modules rely on,
+ * provided by the instance, so that the modules do not import it.
+ */
+export interface Runtime {
+  readonly plugins: Plugins
+  assert(condition: unknown, message?: string): void
+  isDebug(): boolean
+  warn(...messages: unknown[]): void
+  track(root: WebComponent): void
+  resolveComponentClass(component: unknown, type: ItemType): ComponentClass
+  /* Renders the state of the root, see Renderer.update(). */
+  update(
+    root: WebComponent,
+    from: State | undefined,
+    to: State,
+    commands: Command[],
+  ): void
+}
+
+let provided: Runtime | null = null
+
+export const provideRuntime = (runtime: Runtime) => {
+  provided = runtime
+}
+
+export const runtime = (): Runtime => {
+  invariant(provided, 'No Toolkit runtime provided!')
+  return provided
+}

package/src/core/sandbox.ts

@@ -0,0 +1,128 @@
+import type { Props } from './description.js'
+import type { Component, WebComponent } from './nodes.js'
+import type { AnyFunction } from './utils.js'
+
+/*
+ * The component proxy passed as `this` to render and lifecycle methods,
+ * exposing props and children and binding the component methods.
+ */
+export type ComponentSandbox = Omit<Component, 'children'> & {
+  props: Props
+  children: unknown[]
+}
+
+type BoundListener = AnyFunction & { source?: unknown; component?: Component }
+
+/* Reads a property as `target[property]` does. */
+const get = (target: object, property: PropertyKey): unknown =>
+  Reflect.get(target, property)
+
+const isFunction = (target: object, property: PropertyKey) =>
+  typeof get(target, property) === 'function'
+
+const delegated: PropertyKey[] = [
+  'commands',
+  'constructor',
+  'container',
+  'elementName',
+]
+const methods: PropertyKey[] = ['connectTo']
+/* Registered again with each root the plugins are inherited by. */
+const pluginMethods = new Set<PropertyKey>()
+
+const createBoundListener = (
+  listener: AnyFunction,
+  component: Component,
+  context: unknown,
+) => {
+  const boundListener: BoundListener = listener.bind(context)
+  boundListener.source = listener
+  boundListener.component = component
+  return boundListener
+}
+
+class Sandbox {
+  static registerPluginMethod(name: string) {
+    pluginMethods.add(name)
+  }
+
+  static clearPluginMethods() {
+    pluginMethods.clear()
+  }
+
+  /**
+   * Creates the sandbox of a component, hiding the given properties
+   * of the Component class from the component methods.
+   */
+  static create(
+    component: Component,
+    hidden: readonly PropertyKey[],
+  ): ComponentSandbox {
+    const state: { props?: Props; children?: unknown[] } = {}
+    const autobound: Record<PropertyKey, BoundListener> = {}
+    return new Proxy(component, {
+      get: (target, property, receiver) => {
+        if (property === 'props') {
+          return state.props || (target as WebComponent).state || {}
+        }
+        if (property === 'children') {
+          return state.children || []
+        }
+        if (property === 'host') {
+          return target.isRoot() ? target.shadow!.host : null
+        }
+        if (property === 'ref') {
+          if (target.isRoot()) {
+            // returns rendered node instead of custom element for usage of
+            // this.ref.querySelector
+            return target.content!.ref
+          }
+          return target.ref
+        }
+        if (property === '$component') {
+          return component
+        }
+        if (delegated.includes(property)) {
+          return get(target, property)
+        }
+        if (methods.includes(property) && isFunction(target, property)) {
+          return createBoundListener(
+            get(target, property) as AnyFunction,
+            target,
+            target,
+          )
+        }
+        if (pluginMethods.has(property)) {
+          return get(target.rootNode, property)
+        }
+        if (hidden.includes(property)) {
+          return undefined
+        }
+        if (isFunction(autobound, property)) {
+          return autobound[property]
+        }
+        if (isFunction(target, property)) {
+          return (autobound[property] = createBoundListener(
+            get(target, property) as AnyFunction,
+            target,
+            receiver,
+          ))
+        }
+        return get(target, property)
+      },
+      set: (target, property, value) => {
+        if (property === 'props') {
+          state.props = value as Props
+          return true
+        }
+        if (property === 'children') {
+          state.children = (value as unknown[]) || []
+          return true
+        }
+        return false
+      },
+    }) as ComponentSandbox
+  }
+}
+
+export default Sandbox

package/src/core/service.ts

@@ -0,0 +1,39 @@
+import { runtime } from './runtime.js'
+
+class Service {
+  declare static events: string[]
+
+  static validate(listeners: Record<string, unknown>): string[] {
+    if (runtime().isDebug()) {
+      const keys = Object.keys(listeners)
+      runtime().assert(
+        this.events instanceof Array,
+        `Service "${this.name}" does not provide information about valid events, implement "static events = ['foo', 'bar']"`,
+      )
+      runtime().assert(
+        this.events.length > 0,
+        `Service "${this.name}" returned an empty list of valid events, the "static events" list must contain at least one event name`,
+      )
+      const unsupportedKeys = keys.filter(key => !this.events.includes(key))
+      for (const unsupportedKey of unsupportedKeys) {
+        runtime().warn(
+          `Unsupported listener specified "${unsupportedKey}" when connecting to ${this.name}`,
+        )
+      }
+      const supportedKeys = this.events.filter(event => keys.includes(event))
+      runtime().assert(
+        supportedKeys.length > 0,
+        `No valid listener specified when connecting to ${this.name}, use one of [${this.events.join(', ')}]`,
+      )
+      for (const supportedKey of supportedKeys) {
+        runtime().assert(
+          listeners[supportedKey] instanceof Function,
+          `Specified listener "${supportedKey}" for ${this.name} is not a function`,
+        )
+      }
+    }
+    return this.events.filter(event => listeners[event] instanceof Function)
+  }
+}
+
+export default Service