web-toolkit-x 0.0.1 → 0.70.0

package/src/core/dispatcher.ts

@@ -0,0 +1,221 @@
+import { produce } from './draft.js'
+import type { WebComponent } from './nodes.js'
+import { runtime } from './runtime.js'
+import type { AnyFunction } from './utils.js'
+
+/* The state of a root component. */
+export type State = Record<string, unknown>
+
+/* A state transformation, calculating the next state. */
+export type StateUpdate<S = State> = (state: S) => S
+
+/*
+ * A command changing a draft of the state, available as `this`,
+ * which becomes the next immutable state.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- commands take any arguments
+export type CommandMethod<S> = (this: S, ...args: any[]) => void
+
+/* A map of command names to their methods. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- commands of any state by default
+export type CommandsAPI<S = any> = Record<string, CommandMethod<S>>
+
+/* The core commands available on every component. */
+export type Commands<S = State> = {
+  update(overrides: Partial<S>): Promise<boolean>
+  replace(state: S): Promise<boolean>
+}
+
+/*
+ * The commands of an API, called with the arguments of the API methods.
+ * They resolve with true once rendered, or with false when ignored.
+ */
+export type BoundCommands<C extends CommandsAPI> = {
+  [K in keyof C]: (...args: Parameters<C[K]>) => Promise<boolean>
+}
+
+const Mode = {
+  EXECUTE: Symbol('execute-commands'),
+  IGNORE: Symbol('ignore-commands'),
+}
+
+/*
+ * The limit of updates in a row, the one with the commands issued together
+ * followed by the ones with the commands issued in lifecycle methods.
+ */
+const MAX_FLUSH_CYCLES = 4
+
+/* The core commands, also setting the initial state, with no draft yet. */
+const coreAPI: Record<keyof Commands, (arg: State) => StateUpdate> = {
+  update(overrides) {
+    return state => ({
+      ...state,
+      ...overrides,
+    })
+  },
+  replace(state) {
+    return () => state
+  },
+}
+
+class Command {
+  declare name: string
+  declare args: unknown[]
+  declare update: StateUpdate
+  declare resolve?: (executed: boolean) => void
+  declare reject?: (error: unknown) => void
+
+  constructor(name: string, args: unknown[], update: StateUpdate) {
+    this.name = name
+    this.args = args
+    this.update = update
+  }
+
+  invoke(state: State | undefined): State {
+    return this.update(state as State)
+  }
+}
+
+const createCommandsAPI = (...apis: CommandsAPI[]) => {
+  const commandsAPI: CommandsAPI = {}
+  for (const api of apis) {
+    const overridden = Object.keys(api).find(
+      key => Object.hasOwn(coreAPI, key) || Object.hasOwn(commandsAPI, key),
+    )
+    if (overridden) {
+      throw new Error(`The "${overridden}" command is already defined!`)
+    }
+    Object.assign(commandsAPI, api)
+  }
+  return commandsAPI
+}
+
+export type { Command }
+
+/*
+ * Queues the issued commands and executes the ones issued together
+ * in a single update, once the current task has completed.
+ */
+class Dispatcher {
+  declare mode: symbol
+  declare queue: Command[]
+  declare isFlushing: boolean
+  declare root: WebComponent
+  declare api: CommandsAPI
+  declare commands: Commands & Record<string, AnyFunction>
+  declare names: string[]
+
+  ignoreIncoming() {
+    this.mode = Mode.IGNORE
+  }
+
+  constructor(root: WebComponent) {
+    this.mode = Mode.EXECUTE
+    this.queue = []
+    this.isFlushing = false
+    this.root = root
+    this.commands = {} as Commands & Record<string, AnyFunction>
+
+    const { commands = [] } = root.constructor as typeof WebComponent
+    this.api = createCommandsAPI(
+      ...(Array.isArray(commands) ? commands : [commands]),
+    )
+    this.names = [...Object.keys(coreAPI), ...Object.keys(this.api)]
+
+    for (const name of this.names) {
+      this.commands[name] = (...args: unknown[]) => this.issue(name, args)
+    }
+  }
+
+  createCommand(name: string, args: unknown[]) {
+    const method = this.api[name]
+    const update: StateUpdate = method
+      ? state =>
+          produce(state, draft => {
+            const result: unknown = method.apply(draft, args)
+            // the draft is revoked before the rest of an async command runs
+            if (result instanceof Promise) {
+              result.catch(() => {})
+              throw new Error(`The "${name}" command must be synchronous!`)
+            }
+          })
+      : coreAPI[name as keyof Commands](...(args as [State]))
+    return new Command(name, args, update)
+  }
+
+  issue(name: string, args: unknown[]): Promise<boolean> {
+    if (this.mode === Mode.IGNORE) {
+      return Promise.resolve(false)
+    }
+    const command = this.createCommand(name, args)
+    const done = new Promise<boolean>((resolve, reject) => {
+      command.resolve = resolve
+      command.reject = reject
+    })
+    this.queue.push(command)
+    // the commands issued while flushing are executed in the next cycle
+    if (this.queue.length === 1 && !this.isFlushing) {
+      queueMicrotask(() => this.flush())
+    }
+    return done
+  }
+
+  /**
+   * Sets the state right away, when the root is rendered or receives
+   * new props from its parent.
+   */
+  setState(state: State) {
+    if (this.mode === Mode.IGNORE) {
+      return
+    }
+    this.execute([this.createCommand('replace', [state])])
+  }
+
+  /**
+   * Updates the root with the state calculated by the commands in turn.
+   */
+  execute(commands: Command[]) {
+    const prevState = this.root.state as State | undefined
+    const nextState = commands.reduce<State | undefined>(
+      (state, command) => command.invoke(state),
+      prevState,
+    )!
+    runtime().update(this.root, prevState, nextState, commands)
+  }
+
+  /**
+   * Executes the queued commands, followed by the ones issued in lifecycle
+   * methods in turn, until there are none left. When an update fails, its
+   * commands reject, and the ones issued in its lifecycle methods are still
+   * executed, as the update is completed.
+   */
+  flush() {
+    this.isFlushing = true
+    try {
+      for (let cycle = 1; this.queue.length; cycle++) {
+        const commands = this.queue.splice(0)
+        // the root can be destroyed before the queued commands are executed
+        if (this.mode === Mode.IGNORE) {
+          commands.forEach(command => command.resolve!(false))
+          continue
+        }
+        try {
+          if (cycle > MAX_FLUSH_CYCLES) {
+            throw new Error(
+              'Too many cycles updating state in lifecycle methods!',
+            )
+          }
+          this.execute(commands)
+        } catch (error) {
+          commands.forEach(command => command.reject!(error))
+          continue
+        }
+        commands.forEach(command => command.resolve!(true))
+      }
+    } finally {
+      this.isFlushing = false
+    }
+  }
+}
+
+export default Dispatcher

package/src/core/dom.ts

@@ -0,0 +1,124 @@
+import type { ElementDescription, Listener } from './description.js'
+import { getAttributeName, getEventName } from './utils.js'
+
+/* Style and properties are set by name, as by the original assignments. */
+type StyleMap = Record<string, string | null>
+type PropertyMap = Record<string, unknown>
+
+/*
+ * Writes to the rendered elements, shared by the initial rendering and
+ * the patches, so that both follow the same rules. Custom attributes and
+ * listeners use the names as given, others are mapped to the DOM names.
+ */
+const DOM = {
+  setClassName(element: HTMLElement, className: string) {
+    element.className = className
+  },
+
+  setStyleProperty(element: HTMLElement, name: string, value: string) {
+    if (name.startsWith('--')) {
+      element.style.setProperty(name, ` ${value}`)
+    } else {
+      ;(element.style as unknown as StyleMap)[name] = value
+    }
+  },
+
+  removeStyleProperty(element: HTMLElement, name: string) {
+    if (name.startsWith('--')) {
+      element.style.removeProperty(name)
+    } else {
+      ;(element.style as unknown as StyleMap)[name] = null
+    }
+  },
+
+  setAttribute(
+    element: HTMLElement,
+    name: string,
+    value: string,
+    isCustom: boolean,
+  ) {
+    const attr = isCustom ? name : getAttributeName(name)
+    element.setAttribute(attr, value)
+  },
+
+  removeAttribute(element: HTMLElement, name: string, isCustom: boolean) {
+    const attr = isCustom ? name : getAttributeName(name)
+    element.removeAttribute(attr)
+  },
+
+  setDataAttribute(element: HTMLElement, name: string, value: string) {
+    element.dataset[name] = value
+  },
+
+  removeDataAttribute(element: HTMLElement, name: string) {
+    delete element.dataset[name]
+  },
+
+  addListener(
+    element: HTMLElement,
+    name: string,
+    listener: Listener,
+    isCustom: boolean,
+  ) {
+    const event = isCustom ? name : getEventName(name)
+    element.addEventListener(event, listener)
+  },
+
+  removeListener(
+    element: HTMLElement,
+    name: string,
+    listener: Listener,
+    isCustom: boolean,
+  ) {
+    const event = isCustom ? name : getEventName(name)
+    element.removeEventListener(event, listener)
+  },
+
+  setProperty(element: HTMLElement, key: string, value: unknown) {
+    ;(element as unknown as PropertyMap)[key] = value
+  },
+
+  deleteProperty(element: HTMLElement, key: string) {
+    delete (element as unknown as PropertyMap)[key]
+  },
+
+  /**
+   * Creates a new DOM Element based on the specified description.
+   */
+  createElement(description: ElementDescription): HTMLElement {
+    const element = document.createElement(description.name)
+    if (description.class) {
+      this.setClassName(element, description.class)
+    }
+    for (const [name, value] of Object.entries(description.style ?? {})) {
+      this.setStyleProperty(element, name, value)
+    }
+    for (const [name, listener] of Object.entries(
+      description.listeners ?? {},
+    )) {
+      this.addListener(element, name, listener, false)
+    }
+    for (const [name, value] of Object.entries(description.attrs ?? {})) {
+      this.setAttribute(element, name, value, false)
+    }
+    for (const [name, value] of Object.entries(description.dataset ?? {})) {
+      this.setDataAttribute(element, name, value)
+    }
+    for (const [key, value] of Object.entries(description.properties ?? {})) {
+      this.setProperty(element, key, value)
+    }
+    for (const [name, value] of Object.entries(
+      description.custom?.attrs ?? {},
+    )) {
+      this.setAttribute(element, name, value, true)
+    }
+    for (const [name, listener] of Object.entries(
+      description.custom?.listeners ?? {},
+    )) {
+      this.addListener(element, name, listener, true)
+    }
+    return element
+  },
+}
+
+export default DOM