/src/dom.ts at 33c22babfaa9aa563c16457eaea2c50db63747fd

// This module contains bare minimum DOM helper functions with Signal support.
// This module should only contain fundamental building block.
// This module should not have convenient helpers or opinionated ones.

import { effect, isReactive, type ReactiveOrStatic } from "./signals.js";

export type ElementSetup<T extends Element> = (el: T) => void;

// (internal) For code deduplication (candidate for inlining)
function setAttribute(
  el: Element,
  name: string,
  value: string | boolean,
): void {
  if (typeof value === "string") {
    el.setAttribute(name, value);
    return;
  }

  if (value) {
    el.setAttribute(name, "");
    return;
  }

  el.removeAttribute(name);
}

/**
 * Sets an attribute.
 * When the value is `false`, removes the attribute.
 */
export function attr<T extends Element>(
  name: string,
  value: ReactiveOrStatic<string | boolean>,
): ElementSetup<T> {
  return (el) => {
    if (isReactive(value)) {
      effect(() => {
        setAttribute(el, name, value.get());
      });
      return;
    }

    setAttribute(el, name, value);
  };
}

/**
 * Sets an element property.
 */
export function prop<T extends Element, K extends keyof T = keyof T>(
  name: K,
  value: ReactiveOrStatic<T[K]>,
): ElementSetup<T> {
  return (el) => {
    if (isReactive(value)) {
      effect(() => {
        el[name] = value.get();
      });
      return;
    }

    el[name] = value;
  };
}

/**
 * Adds an event listener for the element.
 */
export function on<T extends Element, E extends Event>(
  eventName: string,
  listener: ReactiveOrStatic<(event: E) => void>,
  options?: AddEventListenerOptions,
): ElementSetup<T> {
  return (el) => {
    if (isReactive(listener)) {
      effect(() => {
        const f = listener.get();

        // @ts-expect-error: TypeScript incorrectly models event target things.
        el.addEventListener(eventName, f, options);

        return () => {
          // @ts-expect-error: TypeScript incorrectly models event target things.
          el.removeEventListener(eventName, f, options);
        };
      });
      return;
    }

    // @ts-expect-error: TypeScript incorrectly models event target things.
    el.addEventListener(eventName, listener, options);
  };
}

/**
 * A set of types ef accept for node children.
 *
 * - `Node`      ... Appended as-is.
 * - `string`    ... Appended as `Text` (DOM text node).
 * - `null`      ... Do nothing (skip).
 * - `undefined` ... Do nothing (skip).
 */
export type NodeChild = Node | string | null | undefined;

// (internal) Append children to a Node (parent).
function adapt(
  node: Node,
  children: readonly ReactiveOrStatic<NodeChild>[],
): void {
  for (const child of children) {
    if (isReactive(child)) {
      const start = document.createTextNode("");
      const end = document.createTextNode("");

      node.appendChild(start);
      node.appendChild(end);

      effect(() => {
        // Due to the DocumentFragment disappears from Node Tree once appended,
        // we need to use `.parentNode` because `node` does not exist in the tree.
        // What a mess.
        const parent = start.parentNode || node;

        let oldNode: Node | null = null;

        if (start.nextSibling && start.nextSibling !== end) {
          oldNode = start.nextSibling;

          // Remove excess (= nodes between `oldNode` and `end`).
          // Cleanup approach cannot be used because how DocumentFragment works:
          // its children is appended to the parent and the node itself disappears.
          while (oldNode.nextSibling && oldNode.nextSibling !== end) {
            parent.removeChild(oldNode.nextSibling);
          }
        }

        const c = child.get();

        if (c === null || typeof c === "undefined") {
          if (oldNode) {
            parent.removeChild(oldNode);
          }
          return;
        }

        // TextNode value rewrite shortcut
        if (oldNode && oldNode instanceof Text && typeof c === "string") {
          oldNode.nodeValue = c;
          return;
        }

        const newNode = typeof c === "string" ? document.createTextNode(c) : c;

        if (oldNode) {
          // Use `replaceChild` for easy performance boost
          parent.replaceChild(newNode, oldNode);
        } else {
          parent.insertBefore(newNode, end);
        }
      });
      continue;
    }

    if (child === null || typeof child === "undefined") {
      continue;
    }

    node.appendChild(
      typeof child === "string" ? document.createTextNode(child) : child,
    );
  }
}

/**
 * Create a DocumentFragment node.
 */
export function fragment(
  children: readonly ReactiveOrStatic<NodeChild>[],
): DocumentFragment {
  const f = document.createDocumentFragment();

  adapt(f, children);

  return f;
}

/**
 * Create an HTMLElement element.
 */
export function el<TagName extends keyof HTMLElementTagNameMap>(
  tagName: TagName,
  setups?: readonly ElementSetup<HTMLElementTagNameMap[TagName]>[],
  children?: readonly ReactiveOrStatic<NodeChild>[],
): HTMLElementTagNameMap[TagName];
export function el<T extends Element>(
  tagName: string,
  setups?: readonly ElementSetup<T>[],
  children?: readonly ReactiveOrStatic<NodeChild>[],
): T;
export function el<TagName extends keyof HTMLElementTagNameMap>(
  tagName: TagName,
  setups: readonly ElementSetup<HTMLElementTagNameMap[TagName]>[] = [],
  children: readonly ReactiveOrStatic<NodeChild>[] = [],
): HTMLElementTagNameMap[TagName] {
  const e = document.createElement(tagName);

  for (const f of setups) {
    f(e);
  }

  adapt(e, children);

  return e;
}

/**
 * Create a SVGElement element.
 *
 * You don't need to set `xmlns` attribute for elements created by this function.
 * Namespace is configured on element creation.
 */
export function svg<TagName extends keyof SVGElementTagNameMap>(
  tagName: TagName,
  setups?: readonly ElementSetup<SVGElementTagNameMap[TagName]>[],
  children?: readonly ReactiveOrStatic<NodeChild>[],
): SVGElementTagNameMap[TagName];
export function svg<T extends SVGElement>(
  tagName: string,
  setups?: readonly ElementSetup<T>[],
  children?: readonly ReactiveOrStatic<NodeChild>[],
): T;
export function svg<TagName extends keyof SVGElementTagNameMap>(
  tagName: TagName,
  setups: readonly ElementSetup<SVGElementTagNameMap[TagName]>[] = [],
  children: readonly ReactiveOrStatic<NodeChild>[] = [],
): SVGElementTagNameMap[TagName] {
  const e = document.createElementNS("http://www.w3.org/2000/svg", tagName);

  for (const f of setups) {
    f(e);
  }

  adapt(e, children);

  return e;
}

/**
 * Create a MathMLElement element.
 */
export function mathml<TagName extends keyof MathMLElementTagNameMap>(
  tagName: TagName,
  setups?: readonly ElementSetup<MathMLElementTagNameMap[TagName]>[],
  children?: readonly ReactiveOrStatic<NodeChild>[],
): MathMLElementTagNameMap[TagName];
export function mathml<T extends MathMLElement>(
  tagName: string,
  setups?: readonly ElementSetup<T>[],
  children?: readonly ReactiveOrStatic<NodeChild>[],
): T;
export function mathml<TagName extends keyof MathMLElementTagNameMap>(
  tagName: TagName,
  setups: readonly ElementSetup<MathMLElementTagNameMap[TagName]>[] = [],
  children: readonly ReactiveOrStatic<NodeChild>[] = [],
): MathMLElementTagNameMap[TagName] {
  const e = document.createElementNS(
    "http://www.w3.org/1998/Math/MathML",
    tagName,
  );

  for (const f of setups) {
    f(e);
  }

  adapt(e, children);

  return e;
}