Append HTML string literals with components (#26)

Author: zefir-git

src/DocumentComponent.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright © 2024 Cloudnode OÜ
+ *
+ * This file is part of @cldn/components.
+ *
+ * \@cldn/components is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser
+ * General Public License as published by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * \@cldn/components is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
+ * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License along with @cldn/components.
+ * If not, see <https://www.gnu.org/licenses/>.
+ */
+import {NodeComponent} from "./index.js";
+
+/**
+ * A {@link !DocumentFragment} component
+ */
+export class DocumentComponent extends NodeComponent<DocumentFragment> {
+    public constructor(html?: string) {
+        super(html ? document.createRange().createContextualFragment(html) : document.createDocumentFragment());
+    }
+
+    /**
+     * Template literal tag function that accepts HTML code with components in a
+     * string literal
+     */
+    public static tag(strings: TemplateStringsArray, ...components: NodeComponent<any>[]): DocumentComponent {
+        const idPrefix = `tag-${crypto.randomUUID()}-`;
+        const doc = new DocumentComponent(strings.reduce((acc, str, index) => acc + `${str}${index < components.length ? `<slot name="${idPrefix}${index - 1}"></slot>` : ""}`, ""));
+        for (const [index, component] of components.entries())
+            component.slot(idPrefix + index, doc.node);
+        return doc;
+    }
+}

src/ElementComponent.ts

@@ -14,7 +14,7 @@
  * You should have received a copy of the GNU Lesser General Public License along with @cldn/components.
  * If not, see <https://www.gnu.org/licenses/>.
  */
-import {NodeComponent} from "./NodeComponent.js";
+import {DocumentComponent, NodeComponent} from "./index.js";
 
 /**
  * Non-readonly non-method keys
@@ -127,11 +127,21 @@ export abstract class ElementComponent<T extends Element> extends NodeComponent<
     }
 
     /**
-     * Set inner HTML
+     * Append HTML.
+     *
+     * Any components (provided as `${...}` inside the HTML string literal)
+     * remain fully functional and are appended (not just as HTML).
+     * @example
+     * component.html`<div>${new Component("button")
+     *      .text("Click me")
+     *      .on("click", () => console.log("clicked"))
+     * }</div>`
+     * // Event listeners etc. are preserved.
+     * // Note the lack of parentheses.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals Template literals (Template strings) - MDN}
      */
-    public html(html: string) {
-        this.node.innerHTML = html;
-        return this;
+    public html(strings: TemplateStringsArray, ...components: NodeComponent<any>[]): this {
+        return this.append(DocumentComponent.tag(strings, ...components));
     }
 
     /**
@@ -167,6 +177,11 @@ export abstract class ElementComponent<T extends Element> extends NodeComponent<
         return super.on(type as any, listener, c as any);
     }
 
+    public override empty() {
+        this.node.replaceChildren();
+        return this;
+    }
+
     /**
      * Get this component's outer HTML
      */

src/NodeComponent.ts

@@ -33,6 +33,15 @@ export abstract class NodeComponent<T extends Node> {
 		this.node = node;
 	}
 
+	/**
+	 * Run a function in the context of this component
+	 * @param fn Provides this component as the first argument and `this`.
+	 */
+	public context(fn: (this: this, component: this) => this): this {
+		fn.call(this, this);
+		return this;
+	}
+
 	/**
 	 * Insert component after the last child
 	 */
@@ -86,4 +95,13 @@ export abstract class NodeComponent<T extends Node> {
 		slotNode.replaceWith(this.node);
 		return this;
 	}
+
+	/**
+	 * Empty the component (remove children)
+	 */
+	public empty() {
+		while (this.node.firstChild)
+			this.node.removeChild(this.node.firstChild);
+		return this;
+	}
 }

src/TextComponent.ts

@@ -14,7 +14,7 @@
  * You should have received a copy of the GNU Lesser General Public License along with @cldn/components.
  * If not, see <https://www.gnu.org/licenses/>.
  */
-import {NodeComponent} from "./NodeComponent.js";
+import {NodeComponent} from "./index.js";
 
 /**
  * A text node component

src/index.ts

@@ -15,6 +15,7 @@
  * If not, see <https://www.gnu.org/licenses/>.
  */
 export {NodeComponent} from "./NodeComponent.js";
+export {DocumentComponent} from "./DocumentComponent.js";
 export {TextComponent} from "./TextComponent.js";
 export {ElementComponent} from "./ElementComponent.js";
 export {Component} from "./Component.js";