@typed/template 0.14.0 → 1.0.0-beta.0

package/src/internal/buildTemplateFragement.ts

@@ -0,0 +1,82 @@
+import type * as Template from "../Template.js";
+
+export function buildTemplateFragment(
+  document: Document,
+  template: Template.Template,
+): DocumentFragment {
+  const root = document.createDocumentFragment();
+  for (const node of template.nodes) {
+    root.appendChild(buildTemplateNode(document, node));
+  }
+  return root;
+}
+
+function buildTemplateNode(document: Document, node: Template.Node): Node {
+  switch (node._tag) {
+    case "comment":
+      return document.createComment(node.value);
+    case "comment-part":
+      return document.createComment(`c_${node.index}`);
+    case "sparse-comment": {
+      return document.createComment(
+        `c_${node.nodes.map((n) => (n._tag === "text" ? "" : n.index)).join("_")}`,
+      );
+    }
+    case "doctype":
+      return document.implementation.createDocumentType(
+        node.name,
+        node.publicId ?? "",
+        node.systemId ?? "",
+      );
+    case "element":
+      return buildTemplateElement(document, node);
+    case "self-closing-element":
+      return buildTemplateSelfClosingElement(document, node);
+    case "text-only-element":
+      return buildTemplateTextOnlyElement(document, node);
+    case "text":
+      return document.createTextNode(node.value);
+    case "node":
+      return document.createComment(`/n_${node.index}`);
+  }
+}
+
+function buildTemplateElement(document: Document, node: Template.ElementNode): HTMLElement {
+  const element = document.createElement(node.tagName);
+  addStaticAttributes(element, node.attributes);
+  for (const child of node.children) {
+    element.appendChild(buildTemplateNode(document, child));
+  }
+  return element;
+}
+
+function addStaticAttributes(element: HTMLElement, attributes: Array<Template.Attribute>): void {
+  for (const attribute of attributes) {
+    if (attribute._tag === "attribute") {
+      element.setAttribute(attribute.name, attribute.value);
+    } else if (attribute._tag === "boolean") {
+      element.toggleAttribute(attribute.name, true);
+    }
+  }
+}
+
+function buildTemplateSelfClosingElement(
+  document: Document,
+  node: Template.SelfClosingElementNode,
+): HTMLElement {
+  const element = document.createElement(node.tagName);
+  addStaticAttributes(element, node.attributes);
+  return element;
+}
+
+function buildTemplateTextOnlyElement(
+  document: Document,
+  node: Template.TextOnlyElement,
+): HTMLElement {
+  const element = document.createElement(node.tagName);
+  addStaticAttributes(element, node.attributes);
+  if (node.textContent && node.textContent._tag === "text") {
+    element.textContent = node.textContent.value;
+  }
+  return element;
+}

package/src/internal/diff.ts

@@ -0,0 +1,127 @@
+// @see https://github.com/WebReflection/udomdiff
+
+export const diff = (
+  a: Array<Node>,
+  b: Array<Node>,
+  get: (entry: Node, action: number) => Node,
+  before: Node,
+) => {
+  const parentNode = before.parentNode!;
+  const bLength = b.length;
+  let aEnd = a.length;
+  let bEnd = bLength;
+  let aStart = 0;
+  let bStart = 0;
+  let map = null;
+  while (aStart < aEnd || bStart < bEnd) {
+    // append head, tail, or nodes in between: fast path
+    if (aEnd === aStart) {
+      // we could be in a situation where the rest of nodes that
+      // need to be added are not at the end, and in such case
+      // the node to `insertBefore`, if the index is more than 0
+      // must be retrieved, otherwise it's gonna be the first item.
+      const node =
+        bEnd < bLength ? (bStart ? get(b[bStart - 1], -0).nextSibling : get(b[bEnd], 0)) : before;
+      while (bStart < bEnd) {
+        parentNode!.insertBefore(get(b[bStart++], 1), node);
+      }
+    } // remove head or tail: fast path
+    else if (bEnd === bStart) {
+      while (aStart < aEnd) {
+        // remove the node only if it's unknown or not live
+        if (!map || !map.has(a[aStart])) {
+          // @ts-ignore
+          get(a[aStart], -1).remove();
+        }
+        aStart++;
+      }
+    } // same node: fast path
+    else if (a[aStart] === b[bStart]) {
+      aStart++;
+      bStart++;
+    } // same tail: fast path
+    else if (a[aEnd - 1] === b[bEnd - 1]) {
+      aEnd--;
+      bEnd--;
+    } // The once here single last swap "fast path" has been removed in v1.1.0
+    // https://github.com/WebReflection/udomdiff/blob/single-final-swap/esm/index.js#L69-L85
+    // reverse swap: also fast path
+    else if (a[aStart] === b[bEnd - 1] && b[bStart] === a[aEnd - 1]) {
+      // this is a "shrink" operation that could happen in these cases:
+      // [1, 2, 3, 4, 5]
+      // [1, 4, 3, 2, 5]
+      // or asymmetric too
+      // [1, 2, 3, 4, 5]
+      // [1, 2, 3, 5, 6, 4]
+      const node = get(a[--aEnd], -0).nextSibling;
+      parentNode.insertBefore(get(b[bStart++], 1), get(a[aStart++], -0).nextSibling);
+      parentNode.insertBefore(get(b[--bEnd], 1), node);
+      // mark the future index as identical (yeah, it's dirty, but cheap 👍)
+      // The main reason to do this, is that when a[aEnd] will be reached,
+      // the loop will likely be on the fast path, as identical to b[bEnd].
+      // In the best case scenario, the next loop will skip the tail,
+      // but in the worst one, this node will be considered as already
+      // processed, bailing out pretty quickly from the map index check
+      a[aEnd] = b[bEnd];
+    } // map based fallback, "slow" path
+    else {
+      // the map requires an O(bEnd - bStart) operation once
+      // to store all future nodes indexes for later purposes.
+      // In the worst case scenario, this is a full O(N) cost,
+      // and such scenario happens at least when all nodes are different,
+      // but also if both first and last items of the lists are different
+      if (!map) {
+        map = new Map();
+        let i = bStart;
+        while (i < bEnd) {
+          map.set(b[i], i++);
+        }
+      }
+
+      const index = map.get(a[aStart]) ?? -1;
+
+      // this node has no meaning in the future list, so it's more than safe
+      // to remove it, and check the next live node out instead, meaning
+      // that only the live list index should be forwarded
+      if (index < 0) (get(a[aStart++], -1) as ChildNode).remove();
+      // it's a future node, hence it needs some handling
+      else {
+        // if it's not already processed, look on demand for the next LCS
+        if (bStart < index && index < bEnd) {
+          let i = aStart;
+          // counts the amount of nodes that are the same in the future
+          let sequence = 1;
+          while (++i < aEnd && i < bEnd && map.get(a[i]) === index + sequence) {
+            sequence++;
+          }
+          // effort decision here: if the sequence is longer than replaces
+          // needed to reach such sequence, which would brings again this loop
+          // to the fast path, prepend the difference before a sequence,
+          // and move only the future list index forward, so that aStart
+          // and bStart will be aligned again, hence on the fast path.
+          // An example considering aStart and bStart are both 0:
+          // a: [1, 2, 3, 4]
+          // b: [7, 1, 2, 3, 6]
+          // this would place 7 before 1 and, from that time on, 1, 2, and 3
+          // will be processed at zero cost
+          if (sequence > index - bStart) {
+            const node = get(a[aStart], 0);
+            while (bStart < index) {
+              parentNode.insertBefore(get(b[bStart++], 1), node);
+            }
+          } // if the effort wasn't good enough, fallback to a replace,
+          // moving both source and target indexes forward, hoping that some
+          // similar node will be found later on, to go back to the fast path
+          else {
+            // TODO: benchmark replaceWith instead
+            parentNode.replaceChild(get(b[bStart++], 1), get(a[aStart++], -1));
+          }
+        } // otherwise move the source forward, 'cause there's nothing to do
+        else {
+          aStart++;
+        }
+      }
+    }
+  }
+  return b;
+};

package/src/internal/dom.ts

@@ -0,0 +1,357 @@
+import * as Effect from "effect/Effect";
+import { isNullish, isObject } from "effect/Predicate";
+import { CouldNotFindCommentError } from "../errors.js";
+import { type EventHandler, fromEffectOrEventHandler, isEventHandler } from "../EventHandler.js";
+import {
+  type DomRenderEvent,
+  type HtmlRenderEvent,
+  isRenderEvent,
+  type RenderEvent,
+  RenderEventTypeId,
+} from "../RenderEvent.js";
+import { diffable, isComment } from "../Wire.js";
+import { diff } from "./diff.js";
+import { renderToString } from "./encoding.js";
+
+export function makeTextContentUpdater(element: Node) {
+  return (value: unknown) => {
+    element.textContent = renderToString(value, "");
+  };
+}
+
+export function makeAttributeValueUpdater(element: HTMLElement | SVGElement, attr: Attr) {
+  let isSet = false;
+  const setValue = (value: string | null | undefined) => {
+    if (isNullish(value)) {
+      element.removeAttribute(attr.name);
+      isSet = false;
+    } else {
+      attr.value = value;
+      if (isSet === false) {
+        element.setAttributeNode(attr);
+        isSet = true;
+      }
+    }
+  };
+
+  return setValue;
+}
+
+export function makeClassListUpdater(element: HTMLElement | SVGElement) {
+  // We do double-bookeeping such that we don't assume we know everything about the classList
+  // Other DOM-based libraries might have additional classes in the classList, so we need to allow them to exist
+  // outside of our control.
+  let classList: ReadonlyArray<string> = Array.from(element.classList);
+  return (classNames: ReadonlyArray<string>) => {
+    const { added, removed } = diffStrings(classList, classNames);
+    if (added.length > 0) {
+      element.classList.add(...added);
+    }
+    if (removed.length > 0) {
+      element.classList.remove(...removed);
+    }
+    classList = classNames;
+  };
+}
+
+export function makeDatasetUpdater(element: HTMLElement | SVGElement) {
+  // We do double-bookeeping such that we don't assume we know everything about the dataset
+  // Other DOM-based libraries might have additional keys in the dataset, so we need to allow them to exist
+  // outside of our control.
+  const previous = { ...element.dataset };
+  return (value: unknown) => {
+    const diff = diffDataSet(previous, value as Record<string, string | undefined>);
+    if (diff) {
+      const { added, removed } = diff;
+      removed.forEach((k) => {
+        delete element.dataset[k];
+        delete previous[k];
+      });
+      added.forEach(([k, v]) => {
+        element.dataset[k] = v;
+        previous[k] = v;
+      });
+    }
+  };
+}
+
+export function diffStrings(
+  previous: ReadonlyArray<string> | null | undefined,
+  current: ReadonlyArray<string> | null | undefined,
+): {
+  added: ReadonlyArray<string>;
+  removed: ReadonlyArray<string>;
+  unchanged: ReadonlyArray<string>;
+} {
+  if (previous == null || previous.length === 0) {
+    return {
+      added: current || [],
+      removed: [],
+      unchanged: [],
+    };
+  } else if (current == null || current.length === 0) {
+    return {
+      added: [],
+      removed: previous,
+      unchanged: [],
+    };
+  } else {
+    const previousSet = new Set(previous);
+    const currentSet = new Set(current);
+    const added = current.filter((c) => !previousSet.has(c));
+    const removed: Array<string> = [];
+    const unchanged: Array<string> = [];
+
+    for (let i = 0; i < previous.length; ++i) {
+      if (currentSet.has(previous[i])) {
+        unchanged.push(previous[i]);
+      } else {
+        removed.push(previous[i]);
+      }
+    }
+
+    return {
+      added,
+      removed,
+      unchanged,
+    };
+  }
+}
+
+export function diffDataSet(
+  a: Record<string, string | undefined> | null | undefined,
+  b: Record<string, string | undefined> | null | undefined,
+): { added: Array<readonly [string, string | undefined]>; removed: ReadonlyArray<string> } | null {
+  if (!a) return b ? { added: Object.entries(b), removed: [] } : null;
+  if (!b) return { added: [], removed: Object.keys(a) };
+
+  const { added, removed, unchanged } = diffStrings(Object.keys(a), Object.keys(b));
+
+  return {
+    added: added.concat(unchanged).map((k) => [k, b[k]] as const),
+    removed,
+  };
+}
+
+export function getClassList(value: unknown): ReadonlyArray<string> {
+  if (isNullish(value)) return [];
+  if (Array.isArray(value)) return value.flatMap(getClassList);
+  return splitClassNames(renderToString(value, ""));
+}
+
+const ASCII_SPACE_CODE = 32;
+
+/**
+ * Splits a string of class names (like those used in HTML `class=""` attributes)
+ * into an array of individual class names (words), separated by whitespace.
+ *
+ * This function avoids creating intermediate arrays and unnecessary string copying by:
+ *   - Scanning the string one character at a time
+ *   - Skipping over all leading whitespace for each word
+ *   - Collecting all consecutive non-whitespace characters as a "word"
+ *   - Repeating until the input is exhausted
+ *
+ * All ASCII "whitespace" characters with code <= 32 are considered as delimiters.
+ * This is more efficient than `String.prototype.trim` and `String.prototype.split(/\s+/)`
+ * as it only allocates memory for the result array, not for intermediate or empty strings.
+ *
+ * Example:
+ *    splitClassNames("  foo   bar\tbaz\nqux  ") // => ["foo", "bar", "baz", "qux"]
+ */
+export function splitClassNames(value: string): Array<string> {
+  const result: Array<string> = [];
+  let start = 0;
+  const len = value.length;
+
+  while (start < len) {
+    // Skip leading whitespace (all ASCII <= 32)
+    while (start < len && value.charCodeAt(start) <= ASCII_SPACE_CODE) start++;
+    if (start >= len) break;
+    // Find the end of the word (next whitespace)
+    let end = start + 1;
+    while (end < len && value.charCodeAt(end) > ASCII_SPACE_CODE) end++;
+    result.push(value.slice(start, end));
+    // Move start past the end of the last word (one char after end)
+    start = end + 1;
+  }
+
+  return result;
+}
+
+export function matchNodeValue<A, B>(
+  document: Document,
+  value: unknown,
+  onText: (text: string) => A,
+  onNodes: (nodes: Array<Node>) => B,
+): A | B {
+  switch (typeof value) {
+    // primitives are handled as text content
+    case "string":
+    case "symbol":
+    case "number":
+    case "bigint":
+    case "boolean":
+      return onText(String(value));
+    case "undefined":
+    case "function":
+    case "object": {
+      if (isNullish(value)) {
+        return onNodes([]);
+      } else if (isRenderEvent(value)) {
+        return onNodes(unwrapRenderEvent(document, value));
+      } else if (Array.isArray(value)) {
+        return onNodes(value.flatMap((_) => renderEventToArray(document, _)));
+      } else {
+        return onNodes(renderEventToArray(document, value));
+      }
+    }
+  }
+}
+
+export function renderEventToArray(document: Document, x: unknown): Array<Node> {
+  switch (typeof x) {
+    case "string":
+    case "number":
+    case "bigint":
+    case "boolean":
+    case "symbol":
+      return [document.createTextNode(String(x))];
+    case "undefined":
+    case "function":
+    case "object":
+      if (isNullish(x)) return [];
+      if (isRenderEvent(x)) return unwrapRenderEvent(document, x);
+      if (Array.isArray(x)) return x.flatMap((_) => renderEventToArray(document, _));
+      return [x as Node];
+    default:
+      return [];
+  }
+}
+
+function unwrapRenderEvent(document: Document, x: RenderEvent): Array<Node> {
+  if (x[RenderEventTypeId] === "dom") return unwrapDomRenderEvent(x);
+  return unwrapHtmlRenderEvent(document, x);
+}
+
+function unwrapDomRenderEvent(x: DomRenderEvent): Array<Node> {
+  const value = x.content;
+  return Array.isArray(value) ? value : [value as Node];
+}
+
+function unwrapHtmlRenderEvent(document: Document, x: HtmlRenderEvent): Array<Node> {
+  const tmp = document.createElement("template");
+  tmp.innerHTML = x.html;
+  return Array.from(tmp.childNodes);
+}
+
+export function diffChildren(
+  comment: Comment,
+  currentNodes: Array<Node>,
+  nextNodes: Array<Node>,
+  get: (entry: Node, action: number) => Node,
+) {
+  return diff(currentNodes, nextNodes, get, comment);
+}
+
+const commentCache = new WeakMap<Element, Map<number, Comment>>();
+
+function getCommentCacheKey(index: number, isEnd: boolean): number {
+  return isEnd ? -index - 1 : index;
+}
+
+function findCommentInElement(parent: Element, index: number, isEnd: boolean): Comment {
+  let cache = commentCache.get(parent);
+  if (cache === undefined) {
+    cache = new Map();
+    commentCache.set(parent, cache);
+  }
+
+  const cacheKey = getCommentCacheKey(index, isEnd);
+  const cached = cache.get(cacheKey);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const childNodes = parent.childNodes;
+  const searchValue = isEnd ? `/n_${index}` : `n_${index}`;
+
+  for (let i = 0; i < childNodes.length; ++i) {
+    const node = childNodes[i];
+    if (isCommentWithValue(node, searchValue)) {
+      cache.set(cacheKey, node);
+      return node;
+    }
+  }
+
+  throw new CouldNotFindCommentError(index);
+}
+
+export function findNodePartEndComment(parent: Element, index: number) {
+  return findCommentInElement(parent, index, true);
+}
+
+export function findNodePartStartComment(parent: Element, index: number) {
+  return findCommentInElement(parent, index, false);
+}
+
+function isCommentWithValue(node: Node, value: string): node is Comment {
+  return isComment(node) && node.nodeValue === value;
+}
+
+export function makeNodeUpdater(
+  document: Document,
+  comment: Comment,
+  text: Text | null = null,
+  nodes: Array<Node> = [],
+) {
+  const element = comment.parentNode as HTMLElement | SVGElement;
+  const get = diffable(document);
+  const updateCommentText = (value: unknown) => {
+    if (text === null) {
+      text = document.createTextNode("");
+      element.insertBefore(text, comment);
+    }
+
+    text.textContent = renderToString(value, "");
+    nodes = diffChildren(comment, nodes, [text], get);
+  };
+
+  const updateNodes = (updatedNodes: Array<Node>) => {
+    nodes = diffChildren(comment, nodes, updatedNodes, get);
+  };
+
+  return (value: unknown) => {
+    matchNodeValue(document, value, updateCommentText, updateNodes);
+  };
+}
+
+export function makeBooleanUpdater(element: HTMLElement | SVGElement, name: string) {
+  return (value: boolean) => {
+    element.toggleAttribute(name, value);
+  };
+}
+
+export function getAttributeValue(value: unknown): string | null | undefined {
+  if (isNullish(value)) return null;
+  return renderToString(value, "");
+}
+
+export function getBooleanValue(value: unknown): boolean {
+  return !!value;
+}
+
+export function getDatasetValue(
+  value: unknown,
+): Record<string, string | undefined> | null | undefined {
+  if (isNullish(value)) return null;
+  if (isObject(value)) return value as Record<string, string | undefined>;
+  return null;
+}
+
+export function getEventHandlerValue<E, R>(
+  value: unknown,
+): EventHandler<Event, E, R> | null | undefined {
+  if (isNullish(value)) return null;
+  if (isEventHandler(value) || Effect.isEffect(value)) return fromEffectOrEventHandler(value);
+  return null;
+}

package/src/internal/encoding.ts

@@ -0,0 +1,147 @@
+import { isOption, match } from "effect/Option";
+import { hasProperty, isNullish } from "effect/Predicate";
+import { isHtmlRenderEvent } from "../RenderEvent.js";
+
+export function escape(s: unknown): string {
+  switch (typeof s) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "bigint":
+      return escapeHtml(String(s));
+    case "object": {
+      if (isNullish(s)) {
+        return "";
+      } else if (Array.isArray(s)) {
+        return s.map(escape).join("");
+      } else if (s instanceof Date) {
+        return escapeHtml(s.toISOString());
+      } else if (s instanceof RegExp) {
+        return escapeHtml(s.toString());
+      } else {
+        return escapeHtml(JSON.stringify(s));
+      }
+    }
+    default:
+      return escapeHtml(JSON.stringify(s));
+  }
+}
+
+export function unescape(s: string) {
+  const unescaped = unescapeHtml(s);
+  const couldBeJson = unescaped[0] === "[" || unescaped === "{";
+  if (couldBeJson) {
+    try {
+      return JSON.parse(unescaped);
+    } catch {
+      return unescaped;
+    }
+  } else {
+    return unescaped;
+  }
+}
+
+const unescapeHtmlRules = [
+  [/"/g, '"'],
+  [/'/g, "'"],
+  [/:/g, ":"],
+  [/&lt;/g, "<"],
+  [/&gt;/g, ">"],
+  [/&amp;/g, "&"],
+] as const;
+
+const matchHtmlRegExp = /["'&<>]/;
+
+export function escapeHtml(str: string): string {
+  if (str.length === 0) {
+    return str;
+  }
+
+  const match = matchHtmlRegExp.exec(str);
+
+  if (!match) {
+    return str;
+  }
+
+  let escape;
+  let html = "";
+  let index = 0;
+  let lastIndex = 0;
+
+  for (index = match.index; index < str.length; index++) {
+    switch (str.charCodeAt(index)) {
+      case 34: // "
+        escape = "&quot;";
+        break;
+      case 38: // &
+        escape = "&amp;";
+        break;
+      case 39: // '
+        escape = "&#39;";
+        break;
+      case 60: // <
+        escape = "&lt;";
+        break;
+      case 62: // >
+        escape = "&gt;";
+        break;
+      default:
+        continue;
+    }
+
+    if (lastIndex !== index) {
+      html += str.substring(lastIndex, index);
+    }
+
+    lastIndex = index + 1;
+    html += escape;
+  }
+
+  return lastIndex !== index ? html + str.substring(lastIndex, index) : html;
+}
+
+export function unescapeHtml(html: string) {
+  for (const [from, to] of unescapeHtmlRules) {
+    html = html.replace(from, to);
+  }
+
+  return html;
+}
+
+export function renderToString(value: unknown, delimiter: string = ""): string {
+  if (Array.isArray(value)) {
+    return value.map((v) => renderToString(v, delimiter)).join(delimiter);
+  }
+  if (isNullish(value)) {
+    return "";
+  }
+  if (isOption(value)) {
+    return match(value, {
+      onNone: () => "",
+      onSome: (v: unknown) => renderToString(v, delimiter),
+    });
+  }
+  if (isHtmlRenderEvent(value)) {
+    return value.html;
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (hasProperty(value, "toString") && typeof value.toString === "function") {
+    const s = value.toString();
+    if (s !== "[object Object]") {
+      return s;
+    }
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+export function renderToEscapedString(value: unknown, delimiter: string): string {
+  return escape(renderToString(value, delimiter));
+}