custom-elements-ts 0.1.0 → 0.2.0

package/src/template-runtime.ts

@@ -1,3 +1,5 @@
+import { Signal, isSignal, signalTargetCollected } from './signal';
+
 export type PrimitiveTemplateValue = string | number | boolean | null | undefined;
 export type TemplateEventHandler = (event: any) => void;
 
@@ -6,10 +8,86 @@ export type TemplateValue =
   | Node
   | TemplateResult
   | TemplateValue[]
+  | MappedTemplates<unknown>
+  | Signal<unknown>
   | (() => TemplateValue)
   | TemplateEventHandler
   | EventListenerObject;
 
+/** Minimal WeakRef typing so the library can keep targeting ES5 lib. */
+declare const WeakRef:
+  | (new <T extends object>(target: T) => { deref(): T | undefined })
+  | undefined;
+
+const createRef = <T extends object>(target: T): { deref(): T | undefined } =>
+  typeof WeakRef === 'function' ? new WeakRef(target) : { deref: () => target };
+
+/**
+ * Subscribes a DOM write to a signal and performs the initial write. The
+ * subscriber holds the node behind a WeakRef: once the node is garbage
+ * collected, the next notification unsubscribes it automatically (see
+ * signalTargetCollected), so wholesale-discarded subtrees never leak
+ * subscriptions.
+ */
+const bindSignal = <N extends object>(
+  sig: Signal<unknown>,
+  target: N,
+  write: (node: N, value: unknown) => void
+): (() => void) => {
+  write(target, sig.value);
+  const ref = createRef(target);
+  const observer = (value: unknown) => {
+    const node = ref.deref();
+    if (!node) {
+      throw signalTargetCollected;
+    }
+    write(node, value);
+  };
+  sig.subscribe(observer);
+  return () => sig.unsubscribe(observer);
+};
+
+const writeSignalText = (node: Text, value: unknown): void => {
+  node.nodeValue = value === null || value === undefined ? '' : String(value);
+};
+
+const applyAttribute = (element: Element, name: string, value: unknown): void => {
+  if (value === false || value === null || value === undefined) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, String(value));
+  }
+};
+
+/**
+ * A lazily-mapped list, as returned by `map()`. Handing the list and the
+ * mapping function to the renderer (instead of an array of TemplateResults)
+ * lets it skip rows whose item is identical (`===`) to the item the row was
+ * built from — no template call, no part updates, no visit.
+ */
+export interface MappedTemplates<T> {
+  readonly items: readonly T[];
+  readonly fn: (item: T, index: number) => TemplateValue;
+  readonly __customElementsTsMapped: true;
+}
+
+export const map = <T>(
+  items: readonly T[],
+  fn: (item: T, index: number) => TemplateValue
+): MappedTemplates<T> => ({
+  items,
+  fn,
+  __customElementsTsMapped: true,
+});
+
+const isMappedTemplates = (value: unknown): value is MappedTemplates<unknown> => {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      (value as MappedTemplates<unknown>).__customElementsTsMapped === true
+  );
+};
+
 export interface TemplateResult {
   readonly strings: TemplateStringsArray;
   readonly values: TemplateValue[];
@@ -33,9 +111,26 @@ export interface RenderState {
   part?: ChildPart;
 }
 
+type PartKind = 'child' | 'attr' | 'prop' | 'event';
+
+interface PartDescriptor {
+  kind: PartKind;
+  /** Attribute / property / event name. Empty string for child parts. */
+  name: string;
+  /** childNodes index path from the template root to the part's node. */
+  path: number[];
+}
+
 interface ParsedTemplate {
-  html: string;
-  markers: string[];
+  /** Pristine parsed content, cloned for each instance. */
+  content: DocumentFragment;
+  /** Part descriptors indexed by expression position. */
+  parts: PartDescriptor[];
+  /**
+   * True when the template has exactly one root element; instances then
+   * clone that element directly, skipping a DocumentFragment per clone.
+   */
+  singleRoot: boolean;
 }
 
 const templateCache = new WeakMap<TemplateStringsArray, ParsedTemplate>();
@@ -93,19 +188,51 @@ export const renderIntoAnchor = (
 
 const createTemplateInstance = (result: TemplateResult, host?: unknown): TemplateInstance => {
   const parsed = getParsedTemplate(result.strings);
-  const template = document.createElement('template');
-  template.innerHTML = parsed.html;
 
-  const fragment = document.importNode(template.content, true);
-  const parts = discoverParts(fragment, parsed.markers, host);
-  const nodes = Array.from(fragment.childNodes);
-  parts.forEach((part, index) => part.update(result.values[index]));
+  let root: Node;
+  let nodes: ChildNode[];
+  if (parsed.singleRoot) {
+    root = parsed.content.firstChild!.cloneNode(true);
+    nodes = [root as ChildNode];
+  } else {
+    root = parsed.content.cloneNode(true);
+    nodes = Array.from(root.childNodes);
+  }
+
+  // Resolve each precompiled index path directly to its node — no tree
+  // walking or attribute scanning per instance.
+  const descriptors = parsed.parts;
+  const count = descriptors.length;
+  const parts: Part[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const d = descriptors[i];
+    let node: Node = root;
+    const path = d.path;
+    for (let j = 0; j < path.length; j++) {
+      node = node.childNodes[path[j]];
+    }
+    if (d.kind === 'child') {
+      parts[i] = new ChildPart(node as Comment, host);
+    } else if (d.kind === 'event') {
+      parts[i] = new EventPart(node as Element, d.name, host);
+    } else if (d.kind === 'prop') {
+      parts[i] = new PropertyPart(node as Element, d.name);
+    } else {
+      parts[i] = new AttributePart(node as Element, d.name);
+    }
+  }
+  const values = result.values;
+  for (let i = 0; i < count; i++) {
+    parts[i].update(values[i]);
+  }
 
   return {
     strings: result.strings,
     nodes,
-    update(values: TemplateValue[]) {
-      parts.forEach((part, index) => part.update(values[index]));
+    update(newValues: TemplateValue[]) {
+      for (let i = 0; i < count; i++) {
+        parts[i].update(newValues[i]);
+      }
     },
     dispose() {
       parts.forEach((part) => part.dispose());
@@ -130,67 +257,105 @@ const getParsedTemplate = (strings: TemplateStringsArray): ParsedTemplate => {
   }
   parsedHtml += strings[strings.length - 1];
 
-  const parsed = { html: parsedHtml, markers };
-  templateCache.set(strings, parsed);
-  return parsed;
-};
+  const template = document.createElement('template');
+  template.innerHTML = parsedHtml;
+  const content = template.content;
 
-const isAttributePosition = (text: string): boolean => {
-  const lastOpen = text.lastIndexOf('<');
-  const lastClose = text.lastIndexOf('>');
-  if (lastOpen < lastClose) {
-    return false;
-  }
-  return /[^\s<>"'=/]+\s*=\s*["']?$/.test(text);
-};
+  // Whitespace-only text nodes inside table-structure elements are never
+  // rendered; removing them once here makes every clone smaller and faster.
+  stripTableWhitespace(content);
 
-const discoverParts = (fragment: DocumentFragment, markers: string[], host?: unknown): Part[] => {
-  const parts: Part[] = new Array(markers.length);
+  // Discover parts once at parse time and record index paths to their nodes.
   const markerToIndex = new Map(markers.map((marker, index) => [marker, index]));
+  const descriptors: PartDescriptor[] = new Array(markers.length);
   const walker = document.createTreeWalker(
-    fragment,
+    content,
     NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT
   );
-
   let current = walker.nextNode();
   while (current) {
     if (current.nodeType === Node.COMMENT_NODE) {
-      const marker = current.nodeValue || '';
-      const index = markerToIndex.get(marker);
+      const index = markerToIndex.get(current.nodeValue || '');
       if (index !== undefined) {
-        parts[index] = new ChildPart(current as Comment, host);
+        (current as Comment).textContent = '';
+        descriptors[index] = { kind: 'child', name: '', path: getNodePath(current, content) };
       }
-    } else if (current.nodeType === Node.ELEMENT_NODE) {
-      discoverAttributeParts(current as Element, markerToIndex, parts, host);
+    } else {
+      const element = current as Element;
+      let elementPath: number[] | undefined;
+      Array.from(element.attributes).forEach((attribute) => {
+        const index = markerToIndex.get(attribute.value);
+        if (index === undefined) {
+          return;
+        }
+        const name = attribute.name;
+        element.removeAttribute(name);
+        elementPath ||= getNodePath(element, content);
+        const kind: PartKind = name.startsWith('@')
+          ? 'event'
+          : name.startsWith('.')
+            ? 'prop'
+            : 'attr';
+        descriptors[index] = {
+          kind,
+          name: kind === 'attr' ? name : name.slice(1),
+          path: elementPath,
+        };
+      });
     }
     current = walker.nextNode();
   }
 
-  return parts;
+  const singleRoot =
+    content.childNodes.length === 1 && content.firstChild!.nodeType === Node.ELEMENT_NODE;
+  if (singleRoot) {
+    // Paths become relative to the root element instead of the fragment.
+    for (const descriptor of descriptors) {
+      descriptor?.path.shift();
+    }
+  }
+
+  const parsed: ParsedTemplate = { content, parts: descriptors, singleRoot };
+  templateCache.set(strings, parsed);
+  return parsed;
 };
 
-const discoverAttributeParts = (
-  element: Element,
-  markerToIndex: Map<string, number>,
-  parts: Part[],
-  host?: unknown
-) => {
-  Array.from(element.attributes).forEach((attribute) => {
-    const index = markerToIndex.get(attribute.value);
-    if (index === undefined) {
-      return;
-    }
+const getNodePath = (node: Node, root: Node): number[] => {
+  const path: number[] = [];
+  let current: Node = node;
+  while (current !== root) {
+    const parent = current.parentNode!;
+    path.push(Array.prototype.indexOf.call(parent.childNodes, current));
+    current = parent;
+  }
+  return path.reverse();
+};
 
-    const name = attribute.name;
-    element.removeAttribute(name);
-    if (name.startsWith('@')) {
-      parts[index] = new EventPart(element, name.slice(1), host);
-    } else if (name.startsWith('.')) {
-      parts[index] = new PropertyPart(element, name.slice(1));
-    } else {
-      parts[index] = new AttributePart(element, name);
+/** Elements whose whitespace-only text children are never rendered. */
+const tableTags = ['TABLE', 'THEAD', 'TBODY', 'TFOOT', 'TR'];
+
+const stripTableWhitespace = (el: Node): void => {
+  const isTable =
+    el.nodeType === Node.ELEMENT_NODE && tableTags.indexOf((el as Element).tagName) !== -1;
+  let child = el.firstChild;
+  while (child) {
+    const next = child.nextSibling;
+    if (child.nodeType === Node.ELEMENT_NODE) {
+      stripTableWhitespace(child);
+    } else if (isTable && child.nodeType === Node.TEXT_NODE && !child.nodeValue!.trim()) {
+      (child as ChildNode).remove();
     }
-  });
+    child = next;
+  }
+};
+
+const isAttributePosition = (text: string): boolean => {
+  const lastOpen = text.lastIndexOf('<');
+  const lastClose = text.lastIndexOf('>');
+  if (lastOpen < lastClose) {
+    return false;
+  }
+  return /[^\s<>"'=/]+\s*=\s*["']?$/.test(text);
 };
 
 class ChildPart implements Part {
@@ -198,6 +363,10 @@ class ChildPart implements Part {
   private nodes: ChildNode[] = [];
   private templateInstance?: TemplateInstance;
   private arrayItems: Array<{ anchor: Comment; part: ChildPart }> = [];
+  /** Items a map() list was last rendered from, aligned with arrayItems. */
+  private lastItems: unknown[] | null = null;
+  private boundSignal?: Signal<unknown>;
+  private unbindSignal?: () => void;
 
   constructor(
     private anchor: Comment,
@@ -206,11 +375,34 @@ class ChildPart implements Part {
 
   update(value: TemplateValue): void {
     const resolved = resolveValue(value);
+    if (this.boundSignal) {
+      if (resolved === this.boundSignal) {
+        // Same signal as last render: the text node updates itself.
+        return;
+      }
+      this.detachSignal();
+    }
+    if (isSignal(resolved)) {
+      this.updateSignal(resolved);
+      return;
+    }
     if (resolved === null || resolved === undefined || resolved === false) {
       this.clear();
       return;
     }
+    if (isMappedTemplates(resolved)) {
+      this.updateMapped(resolved);
+      return;
+    }
     if (Array.isArray(resolved)) {
+      this.lastItems = null;
+      if (resolved.length === 0) {
+        // Clearing a list routes through clear() so it can take the
+        // whole-parent fast path instead of removing items one by one.
+        this.clear();
+        this.kind = 'array';
+        return;
+      }
       this.updateArray(resolved);
       return;
     }
@@ -229,7 +421,34 @@ class ChildPart implements Part {
     this.clear();
   }
 
+  private updateSignal(sig: Signal<unknown>): void {
+    this.clear();
+    const text = document.createTextNode('');
+    insertAfter(this.anchor, [text]);
+    this.nodes = [text];
+    this.kind = 'text';
+    this.unbindSignal = bindSignal(sig, text, writeSignalText);
+    this.boundSignal = sig;
+  }
+
+  private detachSignal(): void {
+    this.unbindSignal?.();
+    this.unbindSignal = undefined;
+    this.boundSignal = undefined;
+  }
+
   private clear(): void {
+    this.detachSignal();
+    this.lastItems = null;
+    if (this.fastClear()) {
+      // The subtree was discarded wholesale; just drop references. Event
+      // listeners and nested parts are garbage-collected with their nodes.
+      this.templateInstance = undefined;
+      this.arrayItems = [];
+      this.nodes = [];
+      this.kind = 'empty';
+      return;
+    }
     this.templateInstance?.dispose();
     this.templateInstance = undefined;
     this.arrayItems.forEach((item) => {
@@ -242,6 +461,29 @@ class ChildPart implements Part {
     this.kind = 'empty';
   }
 
+  /**
+   * When this part's content spans its whole parent (the anchor is the
+   * parent's first child and the content ends the parent), the parent can be
+   * emptied with one textContent write instead of removing every node
+   * individually — much faster for large lists.
+   */
+  private fastClear(): boolean {
+    if (this.kind === 'empty') {
+      return false;
+    }
+    const parent = this.anchor.parentNode;
+    if (!parent || this.anchor.previousSibling) {
+      return false;
+    }
+    const end = this.getEndNode();
+    if (end === this.anchor || end.nextSibling) {
+      return false;
+    }
+    parent.textContent = '';
+    parent.appendChild(this.anchor);
+    return true;
+  }
+
   private updateText(value: string): void {
     if (this.kind === 'text' && this.nodes[0]?.nodeType === Node.TEXT_NODE) {
       if (this.nodes[0].nodeValue !== value) {
@@ -278,6 +520,84 @@ class ChildPart implements Part {
     this.kind = 'template';
   }
 
+  private updateMapped(mapped: MappedTemplates<unknown>): void {
+    const items = mapped.items as unknown[];
+    const fn = mapped.fn as (item: unknown, index: number) => TemplateValue;
+    const length = items.length;
+
+    if (length === 0) {
+      this.clear();
+      this.kind = 'array';
+      this.lastItems = [];
+      return;
+    }
+    if (this.kind !== 'array') {
+      this.clear();
+      this.kind = 'array';
+    }
+
+    const last = this.lastItems;
+    // Identity skips are only valid while lastItems mirrors arrayItems.
+    const canSkip = last !== null && last.length === this.arrayItems.length;
+
+    // Pure contiguous removal: when identity shows the tail simply shifted
+    // left, detach just the removed rows' DOM and keep every other row
+    // untouched — instead of rewriting every row after the removal point.
+    if (canSkip && last!.length > length) {
+      let start = 0;
+      while (start < length && last![start] === items[start]) {
+        start++;
+      }
+      const removed = last!.length - length;
+      let isShift = true;
+      for (let i = start; i < length; i++) {
+        if (last![i + removed] !== items[i]) {
+          isShift = false;
+          break;
+        }
+      }
+      if (isShift) {
+        const dropped = this.arrayItems.splice(start, removed);
+        for (let i = 0; i < dropped.length; i++) {
+          dropped[i].part.dispose();
+          dropped[i].anchor.parentNode?.removeChild(dropped[i].anchor);
+        }
+        last!.splice(start, removed);
+        return;
+      }
+    }
+
+    while (this.arrayItems.length > length) {
+      const item = this.arrayItems.pop()!;
+      item.part.dispose();
+      item.anchor.parentNode?.removeChild(item.anchor);
+    }
+
+    for (let index = 0; index < length; index++) {
+      let entry = this.arrayItems[index];
+      if (!entry) {
+        const itemAnchor = document.createComment('');
+        insertAfter(this.getEndNode(), [itemAnchor]);
+        entry = { anchor: itemAnchor, part: new ChildPart(itemAnchor, this.host) };
+        this.arrayItems[index] = entry;
+      } else if (canSkip && last![index] === items[index]) {
+        // The row still holds the item it was built from: nothing to do.
+        continue;
+      }
+      entry.part.update(fn(items[index], index));
+    }
+
+    // Remember the items so the next render can identity-skip unchanged rows.
+    let copy = this.lastItems;
+    if (copy === null || copy.length !== length) {
+      copy = new Array(length);
+      this.lastItems = copy;
+    }
+    for (let index = 0; index < length; index++) {
+      copy[index] = items[index];
+    }
+  }
+
   private updateArray(values: TemplateValue[]): void {
     if (this.kind !== 'array') {
       this.clear();
@@ -316,6 +636,7 @@ class ChildPart implements Part {
 
 class AttributePart implements Part {
   private currentValue: TemplateValue | typeof noValue = noValue;
+  private unbindSignal?: () => void;
 
   constructor(
     private element: Element,
@@ -327,15 +648,26 @@ class AttributePart implements Part {
     if (Object.is(this.currentValue, resolved)) {
       return;
     }
+    if (this.unbindSignal) {
+      this.unbindSignal();
+      this.unbindSignal = undefined;
+    }
     this.currentValue = resolved;
-    if (resolved === false || resolved === null || resolved === undefined) {
-      this.element.removeAttribute(this.name);
-    } else {
-      this.element.setAttribute(this.name, String(resolved));
+    if (isSignal(resolved)) {
+      const name = this.name;
+      this.unbindSignal = bindSignal(resolved, this.element, (el, v) =>
+        applyAttribute(el, name, v)
+      );
+      return;
     }
+    applyAttribute(this.element, this.name, resolved);
   }
 
   dispose(): void {
+    if (this.unbindSignal) {
+      this.unbindSignal();
+      this.unbindSignal = undefined;
+    }
     this.currentValue = noValue;
     this.element.removeAttribute(this.name);
   }
@@ -343,6 +675,7 @@ class AttributePart implements Part {
 
 class PropertyPart implements Part {
   private currentValue: TemplateValue | typeof noValue = noValue;
+  private unbindSignal?: () => void;
 
   constructor(
     private element: Element,
@@ -354,11 +687,26 @@ class PropertyPart implements Part {
     if (Object.is(this.currentValue, resolved)) {
       return;
     }
+    if (this.unbindSignal) {
+      this.unbindSignal();
+      this.unbindSignal = undefined;
+    }
     this.currentValue = resolved;
+    if (isSignal(resolved)) {
+      const name = this.name;
+      this.unbindSignal = bindSignal(resolved, this.element, (el, v) => {
+        (el as any)[name] = v === null || v === undefined ? '' : v;
+      });
+      return;
+    }
     (this.element as any)[this.name] = resolved === null || resolved === undefined ? '' : resolved;
   }
 
   dispose(): void {
+    if (this.unbindSignal) {
+      this.unbindSignal();
+      this.unbindSignal = undefined;
+    }
     this.currentValue = noValue;
     (this.element as any)[this.name] = '';
   }