aberdeen 1.17.1 → 2.0.0

package/src/server-dom.ts

@@ -0,0 +1,508 @@
+/**
+ * A minimal, dependency-free DOM implementation that Aberdeen can render into when no
+ * real browser DOM is available (server-side rendering, automated tests).
+ *
+ * It implements just enough of the `Node`/`Element`/`Text` interfaces for Aberdeen's
+ * renderer, plus two serializers:
+ *  - {@link serializeHtml} produces real HTML (used for SSR output).
+ *  - `Element.toString()` produces a terse, test-oriented representation (used by the
+ *    test suite's `assertBody`).
+ *
+ * The same classes back both the test fake-DOM (`tests/fakedom.ts`) and the public
+ * `aberdeen/server` entry point, so there is a single source of truth for DOM behaviour.
+ */
+
+// ---------------------------------------------------------------------------
+// Instrumentation (used by the test suite to count DOM operations)
+// ---------------------------------------------------------------------------
+
+let newCount: number = 0, changeCount: number = 0;
+export const resetCounts = function(): void { newCount = changeCount = 0; };
+export const getCounts = function(): { new: number, changed: number } {
+  return { new: newCount, changed: changeCount };
+};
+
+// ---------------------------------------------------------------------------
+// DOM node classes
+// ---------------------------------------------------------------------------
+
+export class Node {
+  parentNode: Element | null = null;
+  childNodes: Node[] = [];
+  /** The document that created this node; its `defaultView` is the owning window. */
+  ownerDocument: any = null;
+
+  get nextSibling(): Node | undefined {
+    return this.getSibling(+1);
+  }
+
+  get previousSibling(): Node | undefined {
+    return this.getSibling(-1);
+  }
+
+  getSibling(delta: number): Node | undefined {
+    if (!this.parentNode) return undefined;
+    let siblings = this.parentNode.childNodes;
+    let idx = siblings.indexOf(this);
+    if (idx < 0) throw new Error("not part of siblings!?");
+    return siblings[idx + delta];
+  }
+}
+
+type ClassList = {
+  add: (...names: string[]) => void;
+  remove: (...names: string[]) => void;
+  toggle: (name: string, force?: boolean) => void;
+  contains: (name: string) => boolean;
+};
+
+export class Element extends Node {
+  tagName: string;
+  namespaceURI?: string;
+  _style: Record<string, string> = {};
+  attrs: Record<string, string> = {};
+  events: Record<string, Set<Function>> = {};
+  _classList?: ClassList;
+  _scrollTop?: number;
+  _scrollLeft?: number;
+
+  constructor(tag: string, namespaceURI?: string) {
+    super();
+    this.tagName = tag;
+    this.namespaceURI = namespaceURI;
+    this.childNodes = [];
+    newCount++;
+  }
+
+  appendChild(node: Node): void {
+    this.insertBefore(node, null);
+  }
+
+  insertBefore(node: Node, ref: Node | null): void {
+    if (node.parentNode) node.parentNode.removeChild(node);
+    else changeCount++;
+    node.parentNode = this;
+    if (ref) {
+      let idx = this.childNodes.indexOf(ref);
+      if (idx < 0) throw new Error("non-existing ref node");
+      this.childNodes.splice(idx, 0, node);
+    } else {
+      this.childNodes.push(node);
+    }
+  }
+
+  removeChild(node: Node): void {
+    let idx = this.childNodes.indexOf(node);
+    if (idx < 0) throw new Error("no such child");
+    this.childNodes.splice(idx, 1);
+    node.parentNode = null;
+    changeCount++;
+  }
+
+  remove(): void {
+    this.parentNode?.removeChild(this);
+  }
+
+  replaceChild(newNode: Node, oldNode: Node): void {
+    this.insertBefore(newNode, oldNode);
+    this.removeChild(oldNode);
+  }
+
+  setAttribute(k: string, v: any): void {
+    if (v == null || v === '') delete this.attrs[k];
+    else this.attrs[k] = '' + v;
+    changeCount++;
+  }
+
+  getAttribute(k: string): string | undefined {
+    return this.attrs[k];
+  }
+
+  removeAttribute(k: string): void {
+    delete this.attrs[k];
+    changeCount++;
+  }
+
+  get classList(): ClassList {
+    return this._classList || (this._classList = {
+      add: (...names: string[]) => {
+        let set = this._getClassSet();
+        for(const name of names) set.add(name);
+        this._setClassSet(set);
+      },
+      remove: (...names: string[]) => {
+        let set = this._getClassSet();
+        for(const name of names) set.delete(name);
+        this._setClassSet(set);
+      },
+      toggle: (name: string, force?: boolean) => {
+        if (force === true || (force !== false && !this._getClassSet().has(name))) this._classList!.add(name);
+        else this._classList!.remove(name);
+      },
+      contains: (name: string) => this._getClassSet().has(name),
+    });
+  }
+
+  get parentElement(): Element | undefined {
+    if (this.parentNode instanceof Element) return this.parentNode;
+    return undefined;
+  }
+
+  _getClassSet(): Set<string> {
+    return new Set(this.attrs.class ? this.attrs.class.split(' ') : []);
+  }
+
+  _setClassSet(map: Set<string>): void {
+    this.setAttribute('class', Array.from(map).sort().join(' ') || undefined);
+  }
+
+  get firstChild(): Node | undefined {
+    return this.childNodes[0];
+  }
+
+  get lastChild(): Node | undefined {
+    return this.childNodes[this.childNodes.length - 1];
+  }
+
+  set textContent(text: string) {
+    this.childNodes = [new TextNode(text)];
+  }
+
+  get textContent() {
+    let text = '';
+    for(let child of this.childNodes) {
+      if (child instanceof TextNode) {
+        text += child.textContent;
+      }
+    }
+    return text;
+  }
+
+  querySelectorAll(selector: string): Element[] {
+    const results: Element[] = [];
+    this._querySelectorAllRecursive(selector, results);
+    return results;
+  }
+
+  private _querySelectorAllRecursive(selector: string, results: Element[]): void {
+    for (const child of this.childNodes) {
+      if (child instanceof Element) {
+        if (child.tagName === selector) {
+          results.push(child);
+        }
+        child._querySelectorAllRecursive(selector, results);
+      }
+    }
+  }
+
+  set innerHTML(html: string) {
+    this.childNodes = [];
+    if (html) {
+      let n = new Element('fake-emulated-html');
+      n.textContent = html;
+      this.appendChild(n);
+    }
+  }
+
+  set style(val: string) {
+    if (val !== '') throw new Error("non-empty style string cannot be emulated");
+    this._style = {};
+    changeCount++;
+  }
+
+  get style(): Record<string, string> {
+    for(let k in this._style) {
+      if (this._style[k] === '') delete this._style[k];
+    }
+    return this._style;
+  }
+
+  set className(v: string) {
+    this.attrs.class = v;
+    changeCount++;
+  }
+
+  get offsetHeight(): number {
+    return 20;
+  }
+
+  get offsetWidth(): number {
+    return 200;
+  }
+
+  get scrollTop(): number {
+    return this._scrollTop || 0;
+  }
+
+  set scrollTop(value: number) {
+    this._scrollTop = value;
+  }
+
+  get scrollLeft(): number {
+    return this._scrollLeft || 0;
+  }
+
+  set scrollLeft(value: number) {
+    this._scrollLeft = value;
+  }
+
+  /**
+   * Terse, test-oriented serialization (NOT valid HTML). Shows attributes (`=`),
+   * DOM properties (`->`), styles (`:`) and nested children. Used by `assertBody`.
+   */
+  toString(): string {
+    let arr: string[] = [];
+    for(let [symbol, items, toKebab] of [['=', this.attrs, false], ['->', this, false], [':', this.style, true]] as [string, Record<string, any>, boolean][]) {
+      for(let key of Object.keys(items).sort()) {
+        const outputKey = toKebab ? key.replace(/[A-Z]/g, l => `-${l.toLowerCase()}`) : key;
+        const prefix = outputKey + symbol;
+        if (key[0] === '_' || IGNORE_OUTPUT.has(prefix)) continue;
+        let value = '' + items[key];
+        if (value.indexOf(" ") >= 0 || value.indexOf("}") >= 0 || !value.length) value = JSON.stringify(value);
+        arr.push(prefix + value);
+      }
+    }
+    for(let child of this.childNodes) arr.push(child.toString());
+
+    const cls = this.attrs['class'] ? "." + this.attrs['class'].replace(/ /g, '.') : '';
+    return this.tagName + cls + (arr.length ? `{${arr.join(' ')}}` : '');
+  }
+
+  addEventListener(name: string, func: Function): void {
+    this.events[name] = this.events[name] || new Set();
+    this.events[name].add(func);
+    changeCount++;
+  }
+
+  removeEventListener(name: string, func: Function): void {
+    if (this.events[name]) {
+      if (this.events[name].delete(func)) {
+        changeCount++;
+      }
+    }
+  }
+
+  event(info: string | { type: string; [key: string]: any }): void {
+    if (typeof info === 'string') info = {type: info};
+    let type = info.type;
+    info.target = this;
+    info.preventDefault = function() {};
+    info.stopPropagation = function() { info.stopped = true; };
+    let node: Element | null = this;
+    while(node && !info.stopped) {
+      let funcs = node.events[type];
+      if (funcs) {
+        for(let func of funcs) {
+          func.call(node, info);
+        }
+      }
+      node = node.parentNode;
+    }
+  }
+
+  getElementById(id: string): Element | undefined {
+    if (this.attrs.id === id) return this;
+    for(let child of this.childNodes) {
+      if (child instanceof Element) {
+        let el = child.getElementById(id);
+        if (el) return el;
+      }
+    }
+    return undefined;
+  }
+}
+
+const IGNORE_OUTPUT = new Set("tagName-> attrs-> events-> childNodes-> parentNode-> class= namespaceURI-> ownerDocument->".split(" "));
+
+export class TextNode extends Node {
+  textContent: string;
+
+  constructor(textContent: string) {
+    super();
+    this.textContent = '' + textContent;
+    newCount++;
+  }
+
+  toString(): string {
+    return JSON.stringify(this.textContent);
+  }
+
+  remove() {
+    this.parentNode?.removeChild(this);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Document factory
+// ---------------------------------------------------------------------------
+
+export interface ServerDocument {
+  createElement(tag: string): Element;
+  createElementNS(namespaceURI: string, tag: string): Element;
+  createTextNode(text: string): TextNode;
+  head: Element;
+  body: Element;
+  /** The owning window, set by {@link createWindow}. */
+  defaultView: any;
+}
+
+const XHTML_NS = 'http://www.w3.org/1999/xhtml';
+
+/** Create a fresh, isolated document. Use one per SSR request to avoid cross-request state. */
+export function createDocument(): ServerDocument {
+  const doc: ServerDocument = {
+    createElement: (tag: string) => own(new Element(tag, XHTML_NS)),
+    createElementNS: (namespaceURI: string, tag: string) => own(new Element(tag, namespaceURI)),
+    createTextNode: (text: string) => own(new TextNode(text)),
+    head: new Element('head', XHTML_NS),
+    body: new Element('body', XHTML_NS),
+    defaultView: null,
+  };
+  function own<T extends Node>(node: T): T { node.ownerDocument = doc; return node; }
+  own(doc.head);
+  own(doc.body);
+  return doc;
+}
+
+// ---------------------------------------------------------------------------
+// HTML serialization
+// ---------------------------------------------------------------------------
+
+const VOID_ELEMENTS = new Set("area base br col embed hr img input link meta param source track wbr".split(" "));
+// Elements whose text content must NOT be HTML-escaped.
+const RAW_TEXT_ELEMENTS = new Set(["script", "style"]);
+
+function escapeText(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function styleToString(style: Record<string, string>): string {
+  let out = '';
+  for (const key of Object.keys(style)) {
+    const value = style[key];
+    if (value === '') continue;
+    const prop = key.replace(/[A-Z]/g, l => `-${l.toLowerCase()}`);
+    out += `${prop}:${value};`;
+  }
+  return out;
+}
+
+/**
+ * Serialize a node (and its descendants) to an HTML string.
+ *
+ * Notes/limitations:
+ *  - Event listeners are dropped (they are client-only by design).
+ *  - DOM properties set directly on elements (e.g. `input.value` via `value:` arg) are not
+ *    reflected as attributes and therefore do not appear in the output.
+ */
+export function serializeHtml(node: Node): string {
+  if (node instanceof TextNode) return escapeText(node.textContent);
+  if (!(node instanceof Element)) return '';
+
+  const tag = node.tagName;
+  // Wrapper produced by `innerHTML` / the `html:` arg — emit its content verbatim.
+  if (tag === 'fake-emulated-html') return node.textContent;
+
+  let html = '<' + tag;
+  for (const key of Object.keys(node.attrs)) {
+    html += ` ${key}="${escapeAttr(node.attrs[key])}"`;
+  }
+  const styleStr = styleToString(node.style);
+  if (styleStr) html += ` style="${escapeAttr(styleStr)}"`;
+  html += '>';
+
+  if (VOID_ELEMENTS.has(tag)) return html;
+
+  if (RAW_TEXT_ELEMENTS.has(tag)) {
+    html += node.textContent;
+  } else {
+    for (const child of node.childNodes) html += serializeHtml(child);
+  }
+  return html + '</' + tag + '>';
+}
+
+/** Serialize the children of a container element to an HTML string (the container tag itself is omitted). */
+export function serializeChildren(node: Element): string {
+  let html = '';
+  for (const child of node.childNodes) html += serializeHtml(child);
+  return html;
+}
+
+// ---------------------------------------------------------------------------
+// Minimal injectable window / location / history (sufficient for SSR routing)
+// ---------------------------------------------------------------------------
+
+export class ServerLocation {
+  private _href: string = 'http://localhost/';
+  constructor(href: string = 'http://localhost/') {
+    // Goes through the setter, which absolutizes path-only URLs (e.g. Express `req.originalUrl`).
+    this.href = href;
+  }
+
+  get href(): string { return this._href; }
+  set href(value: string) {
+    this._href = value.startsWith('/')
+      ? `${new URL(this._href).origin}${value}`
+      : value;
+  }
+  get origin(): string { return new URL(this._href).origin; }
+  get host(): string { return new URL(this._href).host; }
+  get pathname(): string { return new URL(this._href).pathname; }
+  set pathname(v: string) { const u = new URL(this._href); u.pathname = v; this._href = u.href; }
+  get search(): string { return new URL(this._href).search; }
+  set search(v: string) { const u = new URL(this._href); u.search = v; this._href = u.href; }
+  get hash(): string { return new URL(this._href).hash; }
+  set hash(v: string) { const u = new URL(this._href); u.hash = v; this._href = u.href; }
+}
+
+export class ServerHistory {
+  state: any = null;
+  constructor(private location: ServerLocation) {}
+  pushState(state: any, _title: string, url: string): void { this.state = state; this.location.href = url; }
+  replaceState(state: any, _title: string, url: string): void { this.state = state; this.location.href = url; }
+  go(_delta: number): void { /* no navigation during SSR */ }
+  back(): void {}
+  forward(): void {}
+}
+
+export interface ServerWindow {
+  document: ServerDocument;
+  Node: typeof Node;
+  Element: typeof Element;
+  location: ServerLocation;
+  history: ServerHistory;
+  addEventListener(type: string, listener: Function): void;
+  removeEventListener(type: string, listener: Function): void;
+  dispatchEvent(event: any): void;
+  matchMedia(query: string): { matches: boolean; media: string; addEventListener(): void; removeEventListener(): void };
+}
+
+/**
+ * Create a fresh, isolated window (carrying its own document and the `Node`/`Element`
+ * constructors) bound to `url`. Use one per SSR request. Satisfies Aberdeen's `WindowLike`.
+ */
+export function createWindow(url: string = 'http://localhost/'): ServerWindow {
+  const location = new ServerLocation(url);
+  const history = new ServerHistory(location);
+  const listeners: Record<string, Set<Function>> = {};
+  const document = createDocument();
+  const win: ServerWindow = {
+    document,
+    Node,
+    Element,
+    location,
+    history,
+    addEventListener(type, listener) { (listeners[type] ||= new Set()).add(listener); },
+    removeEventListener(type, listener) { listeners[type]?.delete(listener); },
+    dispatchEvent(event) { listeners[event.type]?.forEach(l => l.call(this, event)); },
+    matchMedia(query) {
+      return { matches: false, media: query, addEventListener() {}, removeEventListener() {} };
+    },
+  };
+  document.defaultView = win;
+  return win;
+}

package/src/server.ts

@@ -0,0 +1,74 @@
+/**
+ * Server-side rendering entry point for Aberdeen (`aberdeen/server`).
+ *
+ * It renders an Aberdeen component to an HTML string against a fresh, isolated instance (via
+ * {@link createA}) bound to a dependency-free server DOM. Because each call gets its own instance
+ * and window, concurrent renders never share reactive state.
+ *
+ * This produces the initial, synchronous render — ideal for fast first paint, link-preview
+ * bots and crawlers that don't run JavaScript. Reactive updates driven by asynchronously
+ * arriving data are not awaited; the output reflects the component's initial state (including
+ * any loading placeholders). Orchestrating async data and instance lifecycles is left to the
+ * caller (the higher level in the stack).
+ *
+ * @example Express
+ * ```ts
+ * import { renderToString } from 'aberdeen/server';
+ * import { init as initRoute } from 'aberdeen/route';
+ *
+ * app.get('*', (req, res) => {
+ *   const { html, head } = renderToString((A) => {
+ *     const route = initRoute(A);   // optional: routing bound to this request
+ *     App(A, route);
+ *   }, { url: req.originalUrl });
+ *   res.send(`<!doctype html><html><head>${head}</head>` +
+ *            `<body><div id="app">${html}</div><script type="module" src="/client.js"></script></body></html>`);
+ * });
+ * ```
+ */
+import { createA } from "./aberdeen.js";
+import { createWindow, serializeChildren } from "./server-dom.js";
+import type { ServerWindow } from "./server-dom.js";
+
+export { createDocument, createWindow, serializeHtml, serializeChildren } from "./server-dom.js";
+export type { ServerDocument, ServerWindow } from "./server-dom.js";
+
+/** Options for {@link renderToString}. */
+export interface RenderToStringOptions {
+	/** The request URL used to populate `window.location` so routing renders the right page. Defaults to `http://localhost/`. */
+	url?: string;
+	/** Use an existing server window instead of creating a fresh one (advanced). */
+	window?: ServerWindow;
+}
+
+/** The result of {@link renderToString}. */
+export interface RenderToStringResult {
+	/** The rendered HTML of the mounted content (the children of the internal root container). */
+	html: string;
+	/** The serialized `<head>` content Aberdeen produced for this render (the `<style>` tag from `cssVars`/{@link aberdeen!Aberdeen.insertCss}), ready to drop into your document's `<head>`. */
+	head: string;
+}
+
+/**
+ * Render an Aberdeen component function to an HTML string.
+ *
+ * @param render Builds the DOM. It receives the fresh Aberdeen instance `A` for this render;
+ *   use it (and pass it to your components) so everything renders against this isolated instance.
+ * @param options See {@link RenderToStringOptions}.
+ * @returns The rendered `html` and `head`. See {@link RenderToStringResult}.
+ */
+export function renderToString(render: (A: ReturnType<typeof createA>) => void, options: RenderToStringOptions = {}): RenderToStringResult {
+	const win = options.window ?? createWindow(options.url);
+	// A fresh, isolated instance per render. `transitions: false` keeps SSR output stable
+	// (no transient `create` classes baked into the HTML).
+	const A = createA(win as any, { transitions: false });
+
+	const root = win.document.createElement("div");
+	A.mount(root as any, () => render(A));
+	A.runQueue();
+
+	return {
+		html: serializeChildren(root as any),
+		head: serializeChildren(win.document.head as any),
+	};
+}

package/src/transitions.ts

@@ -1,9 +1,15 @@
 const FADE_TIME = 400;
 const GROW_SHRINK_TRANSITION = `margin ${FADE_TIME}ms ease-out, transform ${FADE_TIME}ms ease-out`;
 
+// Resolve `getComputedStyle`/`setTimeout` from the element's own window (the one Aberdeen was
+// initialised with) rather than the global, so this works under any injected DOM.
+function windowOf(el: any): any {
+	return el?.ownerDocument?.defaultView ?? globalThis;
+}
+
 function getGrowShrinkProps(el: HTMLElement): Partial<CSSStyleDeclaration> {
 	if (el.parentElement) {
-		const parentStyle = getComputedStyle(el.parentElement);
+		const parentStyle = windowOf(el).getComputedStyle(el.parentElement);
 		const isHorizontal =
 			parentStyle.display === "flex" &&
 			(parentStyle.flexDirection || "").startsWith("row");
@@ -39,7 +45,7 @@ export async function grow(el: HTMLElement) {
 
 	el.style.transition = GROW_SHRINK_TRANSITION;
 	for (const prop in props) el.style[prop] = "";
-	setTimeout(() => {
+	windowOf(el).setTimeout(() => {
 		// Disable transitions.
 		el.style.transition = "";
 	}, FADE_TIME);
@@ -62,7 +68,7 @@ export async function shrink(el: HTMLElement) {
 	Object.assign(el.style, props);
 
 	// Remove the element after the transition is done.
-	setTimeout(() => {
+	windowOf(el).setTimeout(() => {
 		el.remove();
 	}, FADE_TIME);
 }

package/dist/tests/fakedom.d.ts

@@ -1,9 +0,0 @@
-export declare const resetCounts: () => void;
-export declare const getCounts: () => {
-    new: number;
-    changed: number;
-};
-export declare const clearBody: () => void;
-export declare const resetBrowserState: () => void;
-export declare const passTime: (ms?: number) => Promise<void>;
-export declare function setMediaQuery(query: string, matches: boolean): void;