web-toolkit-x 0.0.1 → 0.70.0

package/src/core/template.ts

@@ -0,0 +1,472 @@
+import type { Template as BragiTemplate } from './bragi.js'
+import Browser from './browser.js'
+import {
+  ComponentDescription,
+  ElementDescription,
+  type Listener,
+  type NodeDescription,
+  type Props,
+  TextDescription,
+} from './description.js'
+import type { ComponentClass } from './nodes.js'
+import { runtime } from './runtime.js'
+import { deepFreeze, lowerDash } from './utils.js'
+
+export type ItemType =
+  | 'component'
+  | 'function'
+  | 'null'
+  | 'node'
+  | 'props'
+  | 'unknown'
+  | 'string'
+  | 'number'
+  | 'bigint'
+  | 'boolean'
+  | 'symbol'
+  | 'undefined'
+
+const isDefined = <T>(value: T): value is NonNullable<T> =>
+  value !== undefined && value !== null
+const isFalsy = (template: unknown) => template === null || template === false
+const isNotEmpty = (object: object) => Boolean(Object.keys(object).length)
+
+const Template = {
+  /**
+   * Creates a normalized Description of given template.
+   */
+  describe(template: unknown): NodeDescription | null {
+    if (isFalsy(template)) {
+      return null
+    }
+
+    if (Array.isArray(template) && template.length) {
+      let description!: ComponentDescription | ElementDescription
+      for (const [item, type, index] of (template as unknown[]).map(
+        (item, index): [unknown, ItemType, number] => [
+          item,
+          this.getItemType(item),
+          index,
+        ],
+      )) {
+        if (index === 0) {
+          switch (type) {
+            case 'string':
+              description = new ElementDescription(item as string)
+              break
+            case 'component':
+            case 'function':
+              description = new ComponentDescription(
+                runtime().resolveComponentClass(item, type),
+              )
+              break
+            default:
+              console.error(
+                'Invalid node type:',
+                item,
+                `(${type}) at index: ${index}, template:`,
+                template,
+              )
+              throw new Error(`Invalid node type specified: ${type}`)
+          }
+          continue
+        }
+        if (index === 1 && type === 'props') {
+          if (description.type === 'component') {
+            this.assignPropsToComponent(item as Props, description)
+          } else if (description.type === 'element') {
+            this.assignPropsToElement(item as Props, description)
+          }
+          continue
+        }
+        if (isFalsy(item)) {
+          continue
+        }
+        if (type === 'string' || type === 'number' || item === true) {
+          description.children = description.children || []
+          // eslint-disable-next-line @typescript-eslint/no-base-to-string -- only strings, numbers and true
+          description.children.push(new TextDescription(String(item)))
+          continue
+        } else if (type === 'node') {
+          description.children = description.children || []
+          description.children.push(this.describe(item)!)
+        } else {
+          console.error(
+            'Invalid item',
+            item,
+            `at index: ${index}, template:`,
+            template,
+          )
+          throw new Error(`Invalid item specified: ${type}`)
+        }
+      }
+
+      if (runtime().isDebug()) {
+        deepFreeze(description)
+      }
+      return description
+    }
+
+    console.error('Invalid template definition:', template)
+    throw new Error('Expecting array, null or false')
+  },
+
+  /**
+   * Returns a new props object supplemented by overridden values.
+   */
+  normalizeProps(...overrides: Array<Props | undefined>): Props {
+    const result: Props = {}
+    for (const override of overrides) {
+      for (const [key, value] of Object.entries(override || {})) {
+        if (result[key] === undefined && value !== undefined) {
+          result[key] = value
+        }
+      }
+    }
+    return result
+  },
+
+  /**
+   * Normalizes specified element props object and returns either
+   * a non-empty object containing only supported props or null.
+   */
+  normalizeComponentProps(
+    props: Props | undefined,
+    ComponentClass: { defaultProps?: Props },
+  ): Props {
+    return this.normalizeProps(props, ComponentClass.defaultProps || {})
+  },
+
+  assignPropsToComponent(object: Props, description: ComponentDescription) {
+    const props = this.getComponentProps(
+      object,
+      description.component,
+      description.isRoot,
+    )
+    if (props) {
+      description.props = props
+      if (isDefined(props.key)) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- keys are stringified as given
+        description.key = String(props.key)
+      }
+      if (props.attrs) {
+        const attrs = this.getCustomAttributes(props.attrs as Props, true)
+        if (attrs) {
+          description.attrs = attrs
+        }
+      }
+    }
+  },
+
+  getComponentProps(
+    object: Props,
+    ComponentClass: ComponentClass,
+    isRoot: boolean,
+  ): Props | null {
+    const props = isRoot
+      ? object
+      : this.normalizeComponentProps(object, ComponentClass)
+    return isNotEmpty(props) ? props : null
+  },
+
+  assignPropsToElement(props: Props, description: ElementDescription) {
+    for (const [key, value] of Object.entries(props)) {
+      if (key === 'key') {
+        if (isDefined(value)) {
+          // eslint-disable-next-line @typescript-eslint/no-base-to-string -- keys are stringified as given
+          description.key = String(value)
+        }
+      } else if (key === 'class') {
+        const className = this.getClassName(value)
+        if (className) {
+          description.class = className
+        }
+      } else if (key === 'style') {
+        const style = this.getStyle(value as Props)
+        if (style) {
+          description.style = style
+        }
+      } else if (key === 'dataset') {
+        const dataset = this.getDataset(value as Props)
+        if (dataset) {
+          description.dataset = dataset
+        }
+      } else if (key === 'properties') {
+        const properties = this.getProperties(value as Props)
+        if (properties) {
+          description.properties = properties
+        }
+      } else if (key === 'attrs') {
+        const customAttrs = this.getCustomAttributes(value as Props)
+        if (customAttrs) {
+          description.custom = description.custom || {}
+          description.custom.attrs = customAttrs
+        }
+      } else if (key === 'on') {
+        const customListeners = this.getCustomListeners(value as Props)
+        if (customListeners) {
+          description.custom = description.custom || {}
+          description.custom.listeners = customListeners
+        }
+      } else if (/^on[A-Z]/.test(key)) {
+        const listener = this.getListener(value, key)
+        if (listener) {
+          description.listeners = description.listeners || {}
+          description.listeners[key] = value as Listener
+        }
+        const element = description.name
+        // custom elements define their events themselves
+        if (
+          runtime().isDebug() &&
+          !element.includes('-') &&
+          !Browser.isEventSupported(key, element)
+        ) {
+          console.warn(
+            `The "${key}" listener is not supported on "${element}" elements.`,
+          )
+        }
+      } else {
+        const attr = this.getAttributeValue(value)
+        if (isDefined(attr)) {
+          description.attrs = description.attrs || {}
+          description.attrs[key] = attr
+        }
+        if (runtime().isDebug()) {
+          const element = description.name
+          if (attr === undefined) {
+            console.warn(
+              `Invalid undefined value for attribute "${key}"`,
+              `on element "${element}".`,
+            )
+          }
+          // custom elements define their attributes themselves
+          if (
+            !element.includes('-') &&
+            !Browser.isAttributeSupported(key, element)
+          ) {
+            console.warn(
+              `The "${key}" attribute is not supported on "${element}" elements.`,
+            )
+          }
+        }
+      }
+    }
+  },
+
+  /**
+   * Returns the type of item used in the array representing node template.
+   */
+  getItemType(item: unknown): ItemType {
+    const type = typeof item
+    switch (type) {
+      case 'function':
+        // the node type is inherited from the Component or Root class
+        if (
+          (item as ComponentClass).NodeType === 'component' ||
+          (item as ComponentClass).NodeType === 'root'
+        ) {
+          return 'component'
+        }
+        return 'function'
+      case 'object':
+        if (item === null) {
+          return 'null'
+        } else if (Array.isArray(item)) {
+          return 'node'
+        } else if ((item as object).constructor === Object) {
+          return 'props'
+        }
+        return 'unknown'
+      default:
+        return type
+    }
+  },
+
+  /**
+   * Resolves any object to a space separated string of class names.
+   */
+  getClassName(value: unknown): string {
+    if (!value) {
+      return ''
+    }
+    if (typeof value === 'string') {
+      return value
+    }
+    if (Array.isArray(value)) {
+      return value
+        .map(item => this.getClassName(item))
+        .filter(className => className)
+        .join(' ')
+    }
+    if (typeof value === 'object') {
+      return Object.keys(value)
+        .filter(key => key && (value as Props)[key])
+        .join(' ')
+    }
+    throw new Error(`Invalid value: ${JSON.stringify(value)}`)
+  },
+
+  /**
+   * Returns either a non-empty style object containing only understood
+   * styling rules or null.
+   */
+  getStyle(object: Props): Record<string, string> | null {
+    runtime().assert(
+      object.constructor === Object,
+      'Style must be a plain object!',
+    )
+
+    const style: Record<string, string> = {}
+    for (const [name, value] of Object.entries(object)) {
+      if (runtime().isDebug() && !Browser.isStyleSupported(name)) {
+        console.warn(`Unsupported style property, key: ${name}, value:`, value)
+      }
+      const string = this.getStyleProperty(value, name)
+      if (isDefined(string)) {
+        style[name] = string
+      }
+    }
+    return isNotEmpty(style) ? style : null
+  },
+
+  getStyleProperty(value: unknown, name: string): string | null {
+    if (typeof value === 'string') {
+      return value || "''"
+    } else if ([true, false, null, undefined].includes(value as boolean)) {
+      return null
+    } else if (Array.isArray(value)) {
+      return value.join('')
+    } else if (typeof value === 'number') {
+      return String(value)
+    } else if (typeof value === 'object') {
+      if (name !== 'filter' && name !== 'transform') {
+        throw new Error(`Unknown function list: ${JSON.stringify(value)}`)
+      }
+      // the filter functions are named in camel case, e.g. dropShadow for
+      // drop-shadow, the transform functions are in CSS too, e.g. translateX
+      const functions = this.getFunctionList(
+        value as Props,
+        name === 'filter' ? lowerDash : undefined,
+      )
+      if (runtime().isDebug() && functions && !CSS.supports(name, functions)) {
+        console.warn(`Unsupported ${name} functions: ${functions}`)
+      }
+      return functions
+    }
+    throw new Error(`Invalid style property value: ${JSON.stringify(value)}`)
+  },
+
+  /**
+   * Returns a multi-property string value.
+   */
+  getFunctionList(
+    object: Props,
+    getCSSName: (name: string) => string = name => name,
+  ): string {
+    const composite: Record<string, string> = {}
+    for (const [key, value] of Object.entries(object)) {
+      const stringValue = this.getAttributeValue(value, /*= allowEmpty */ false)
+      if (isDefined(stringValue)) {
+        composite[getCSSName(key)] = stringValue
+      }
+    }
+    return Object.entries(composite)
+      .map(([key, value]) => `${key}(${value})`)
+      .join(' ')
+  },
+
+  getListener(value: unknown, name: string): Listener | null {
+    if (typeof value === 'function') {
+      return value as Listener
+    }
+    if (value === null || value === false || value === undefined) {
+      return null
+    }
+    throw new Error(`Invalid listener specified for event: ${name}`)
+  },
+
+  /**
+   * Resolves given value to a string.
+   */
+  getAttributeValue(
+    value: unknown,
+    allowEmpty = true,
+  ): string | null | undefined {
+    if (value === true || value === '') {
+      return allowEmpty ? '' : null
+    } else if (typeof value === 'string') {
+      return value
+    } else if (value === null || value === false) {
+      return null
+    } else if (value === undefined) {
+      return undefined
+    } else if (Array.isArray(value)) {
+      return value.join('')
+    } else if (['object', 'function', 'symbol'].includes(typeof value)) {
+      throw new Error(`Invalid attribute value: ${JSON.stringify(value)}!`)
+    }
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string -- objects are rejected above
+    return String(value)
+  },
+
+  /**
+   * Returns either a non-empty dataset object or null.
+   */
+  getDataset(object: Props): Record<string, string> | null {
+    const dataset: Record<string, string> = {}
+    for (const key of Object.keys(object)) {
+      const value = this.getAttributeValue(object[key])
+      if (isDefined(value)) {
+        dataset[key] = value
+      }
+    }
+    return isNotEmpty(dataset) ? dataset : null
+  },
+
+  /**
+   * Returns either a non-empty object containing properties set
+   * directly on a rendered DOM Element or null.
+   */
+  getProperties(object: Props): Props | null {
+    return isNotEmpty(object) ? object : null
+  },
+
+  getCustomAttributes(
+    object: Props,
+    forComponent?: boolean,
+  ): Record<string, string> | null {
+    runtime().assert(
+      object.constructor === Object,
+      'Expecting object for custom attributes!',
+    )
+    const attrs: Record<string, string> = {}
+    for (const [key, value] of Object.entries(object)) {
+      const attr = this.getAttributeValue(value, /*= allowEmpty */ true)
+      if (isDefined(attr)) {
+        const name = forComponent ? lowerDash(key) : key
+        attrs[name] = attr
+      }
+    }
+    return isNotEmpty(attrs) ? attrs : null
+  },
+
+  getCustomListeners(object: Props): Record<string, Listener> | null {
+    runtime().assert(
+      object.constructor === Object,
+      'Expecting object for custom listeners!',
+    )
+    const listeners: Record<string, Listener> = {}
+    for (const [key, value] of Object.entries(object)) {
+      const listener = this.getListener(value, key)
+      if (listener) {
+        listeners[key] = listener
+      }
+    }
+    return isNotEmpty(listeners) ? listeners : null
+  },
+}
+
+/* A Bragi template, see bragi.ts, sharing its name with the module above. */
+type Template = BragiTemplate
+
+export default Template

package/src/core/text.ts

@@ -0,0 +1,24 @@
+import type { TextDescription } from './description.js'
+import VirtualNode from './virtual-node.js'
+
+class Text extends VirtualNode {
+  static NodeType = 'text'
+
+  declare description: TextDescription
+  declare ref: globalThis.Text
+
+  constructor(description: TextDescription, parentNode?: VirtualNode) {
+    super(description, parentNode)
+    this.attachDOM()
+  }
+
+  get nodeType(): string {
+    return Text.NodeType
+  }
+
+  attachDOM() {
+    this.ref = document.createTextNode(this.description.text)
+  }
+}
+
+export default Text

package/src/core/toolkit.ts

@@ -0,0 +1,220 @@
+import type { PureComponent, RenderResult } from './bragi.js'
+import CreatedRoots from './created-roots.js'
+import { updateStylesheets } from './custom-element.js'
+import type { ComponentDescription, Props } from './description.js'
+import { Component, type ComponentClass, WebComponent } from './nodes.js'
+import Plugins, { type PluginManifest } from './plugins.js'
+import Renderer from './renderer.js'
+import { provideRuntime } from './runtime.js'
+import Sandbox from './sandbox.js'
+import Template, { type ItemType } from './template.js'
+import { isSameList } from './utils.js'
+import VirtualDOM from './virtual-dom.js'
+
+export interface Settings {
+  readonly debug: boolean
+}
+
+export interface Options {
+  debug?: boolean
+  plugins?: PluginManifest[]
+}
+
+/*
+ * The state used by the core modules through the runtime, kept out of
+ * the public Toolkit instance.
+ */
+
+/* The top-level root components, tracking their subroots. */
+const roots = new Set<WebComponent>()
+
+/* The settings used until Toolkit is configured. */
+const defaultSettings: Settings = Object.freeze({ debug: false })
+
+/* Function to Component mapping. */
+const pureComponentClassRegistry = new Map<PureComponent, ComponentClass>()
+
+const createPlugins = (manifests: PluginManifest[] = []): Plugins => {
+  const plugins = new Plugins(null)
+  for (const manifest of manifests) {
+    plugins.register(manifest)
+  }
+  return plugins
+}
+
+/* The plugins configured for all root components. */
+let plugins = createPlugins()
+
+/**
+ * Returns a PureComponent class rendering the template
+ * provided by the specified function.
+ */
+const resolvePureComponentClass = (fn: PureComponent): ComponentClass => {
+  let ComponentClass = pureComponentClassRegistry.get(fn)
+  if (ComponentClass) {
+    return ComponentClass
+  }
+  ComponentClass = class PureComponent extends Component {
+    static renderer = fn
+
+    render(): RenderResult {
+      // the props type of a pure component is not known here
+      return fn.call(this, this.props as never)
+    }
+  }
+  pureComponentClassRegistry.set(fn, ComponentClass)
+  return ComponentClass
+}
+
+/**
+ * Returns resolved Component class.
+ */
+const resolveComponentClass = (
+  component: unknown,
+  type: ItemType,
+): ComponentClass => {
+  switch (type) {
+    case 'component':
+      return component as ComponentClass
+    case 'function':
+      return resolvePureComponentClass(component as PureComponent)
+    default:
+      throw new Error(`Unsupported component type: ${type}`)
+  }
+}
+
+const track = (root: WebComponent) => {
+  if (root.parentNode) {
+    const parentRootNode = root.parentNode.rootNode
+    parentRootNode.subroots.add(root)
+    root.stopTracking = () => {
+      parentRootNode.subroots.delete(root)
+    }
+  } else {
+    roots.add(root)
+    root.stopTracking = () => {
+      roots.delete(root)
+    }
+  }
+}
+
+class Toolkit {
+  declare settings: Settings
+  declare assert: (condition: unknown, message?: string) => void
+
+  constructor() {
+    this.settings = defaultSettings
+    this.assert = console.assert as Toolkit['assert']
+  }
+
+  /**
+   * Configures Toolkit with given options, keeping the current values
+   * of the options not provided, by default no debug mode and no plugins.
+   * Changed plugins are uninstalled from the created roots, and the new
+   * ones installed in their place, with their stylesheets loaded.
+   */
+  configure(options: Options) {
+    if (options.debug !== undefined) {
+      this.settings = Object.freeze({ debug: options.debug })
+    }
+    const manifests = options.plugins
+    const previous = [...plugins]
+    const origins = previous.map(plugin => plugin.origin)
+    if (!manifests || isSameList(origins, manifests)) {
+      return
+    }
+    // the methods of the remaining plugins are registered again below
+    Sandbox.clearPluginMethods()
+    plugins = createPlugins(manifests)
+    for (const root of this.tracked) {
+      for (const plugin of previous) {
+        root.plugins!.uninstall(plugin.name)
+      }
+      for (const plugin of root.plugins!) {
+        plugin.register?.()
+      }
+      for (const plugin of plugins) {
+        root.plugins!.register(plugin)
+        root.plugins!.install(plugin)
+      }
+      if (root.shadow) {
+        updateStylesheets(root)
+      }
+    }
+  }
+
+  /**
+   * Resets Toolkit to a pristine state, with the default settings
+   * and no plugins, forgetting the created roots.
+   */
+  reset() {
+    plugins.destroy()
+    plugins = createPlugins()
+    roots.clear()
+    this.settings = defaultSettings
+    pureComponentClassRegistry.clear()
+    Sandbox.clearPluginMethods()
+  }
+
+  /* The created root components, with their subroots, until destroyed. */
+  get tracked(): WebComponent[] {
+    const tracked: WebComponent[] = []
+    for (const root of roots) {
+      tracked.push(root, ...root.tracked)
+    }
+    return tracked
+  }
+
+  isDebug(): boolean {
+    return this.settings.debug
+  }
+
+  warn(...messages: unknown[]) {
+    if (this.isDebug()) {
+      console.warn(...messages)
+    }
+  }
+
+  async createRoot(
+    component: ComponentClass,
+    props: Props = {},
+  ): Promise<WebComponent> {
+    const description = Template.describe([
+      component,
+      props,
+    ]) as ComponentDescription
+    // not to stay tracked, with the plugins installed, when it throws
+    return CreatedRoots.destroyingRootsOnError(() =>
+      VirtualDOM.createWebComponent(description, null),
+    )
+  }
+
+  async render(
+    component: ComponentClass,
+    container: Element,
+    props: Props = {},
+  ): Promise<WebComponent> {
+    const root = await this.createRoot(component, props)
+    return root.mount(container)
+  }
+}
+
+/* The Toolkit singleton, exposed globally as toolkit. */
+export const toolkit = new Toolkit()
+
+// asserts, debug mode and warnings are read from the instance, which
+// can be configured, e.g. with the assert function throwing in tests
+provideRuntime({
+  get plugins() {
+    return plugins
+  },
+  assert: (condition, message) => toolkit.assert(condition, message),
+  isDebug: () => toolkit.isDebug(),
+  warn: (...messages) => toolkit.warn(...messages),
+  track,
+  resolveComponentClass,
+  update: (root, from, to, commands) =>
+    Renderer.update(root, from, to, commands),
+})
+
+export default Toolkit