@joist/templating 4.2.4-next.9 → 4.2.4

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2019-2020 Danny Blue
+Copyright (c) 2019-2025 Danny Blue
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/templating",
-  "version": "4.2.4-next.9",
+  "version": "4.2.4",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",

package/src/lib/define.ts

@@ -1,6 +1,26 @@
-import "./elements/async.element.js";
-import "./elements/for.element.js";
-import "./elements/if.element.js";
-import "./elements/bind.element.js";
-import "./elements/value.element.js";
-import "./elements/scope.element.js";
+import { define } from "@joist/element/define.js";
+
+import { JoistAsyncElement } from "./elements/async.element.js";
+import { JoistForElement } from "./elements/for.element.js";
+import { JoistIfElement } from "./elements/if.element.js";
+import { JoistBindElement } from "./elements/bind.element.js";
+import { JoistValueElement } from "./elements/value.element.js";
+import { JoistScopeElement } from "./elements/scope.element.js";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "j-async": JoistAsyncElement;
+    "j-for": JoistForElement;
+    "j-if": JoistIfElement;
+    "j-bind": JoistBindElement;
+    "j-val": JoistValueElement;
+    "j-scope": JoistScopeElement;
+  }
+}
+
+define({ tagName: "j-async" }, JoistAsyncElement);
+define({ tagName: "j-for" }, JoistForElement);
+define({ tagName: "j-if" }, JoistIfElement);
+define({ tagName: "j-bind" }, JoistBindElement);
+define({ tagName: "j-val" }, JoistValueElement);
+define({ tagName: "j-scope" }, JoistScopeElement);

package/src/lib/elements/async.element.test.ts

@@ -1,4 +1,4 @@
-import "./async.element.js";
+import "../define.js";
 
 import { fixtureSync, html } from "@open-wc/testing";
 import { assert } from "chai";
@@ -178,3 +178,39 @@ it("should handle AsyncState transitions", () => {
     }, 150);
   });
 });
+
+it("should wait for depends-on before dispatching events", async () => {
+  let eventDispatched = false;
+
+  customElements.define("dependency-1", class extends HTMLElement {});
+  customElements.define("dependency-2", class extends HTMLElement {});
+
+  fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        if (e.expression.bindTo === "test") {
+          eventDispatched = true;
+          e.update({ oldValue: null, newValue: Promise.resolve("data") });
+        }
+      }}
+    >
+      <j-async bind="test" depends-on="dependency-1,dependency-2">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  // Initially, no event should be dispatched
+  assert.isFalse(eventDispatched);
+
+  // Wait for the custom elements to be defined
+  await Promise.all([
+    customElements.whenDefined("dependency-1"),
+    customElements.whenDefined("dependency-2"),
+  ]);
+
+  // Now the event should be dispatched
+  assert.isTrue(eventDispatched);
+});

package/src/lib/elements/async.element.ts

@@ -4,12 +4,6 @@ import { bind } from "../bind.js";
 import { JoistValueEvent } from "../events.js";
 import { JExpression } from "../expression.js";
 
-declare global {
-  interface HTMLElementTagNameMap {
-    "j-async": JoistAsyncElement;
-  }
-}
-
 export type AsyncState<T = unknown, E = unknown> = {
   status: "loading" | "error" | "success";
   data?: T;
@@ -17,7 +11,6 @@ export type AsyncState<T = unknown, E = unknown> = {
 };
 
 @element({
-  tagName: "j-async",
   // prettier-ignore
   shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
 })
@@ -25,6 +18,11 @@ export class JoistAsyncElement extends HTMLElement {
   @attr()
   accessor bind = "";
 
+  @attr({
+    name: "depends-on",
+  })
+  accessor dependsOn = "";
+
   @bind()
   accessor state: AsyncState | null = null;
 
@@ -40,7 +38,7 @@ export class JoistAsyncElement extends HTMLElement {
     success: undefined,
   };
 
-  connectedCallback(): void {
+  async connectedCallback(): Promise<void> {
     this.#clean();
 
     // Cache all templates
@@ -52,6 +50,12 @@ export class JoistAsyncElement extends HTMLElement {
       success: templates.find((t) => t.hasAttribute("success")),
     };
 
+    if (this.dependsOn) {
+      await Promise.all(
+        this.dependsOn.split(",").map((tag) => window.customElements.whenDefined(tag)),
+      );
+    }
+
     const token = new JExpression(this.bind);
 
     this.dispatchEvent(

package/src/lib/elements/bind.element.test.ts

@@ -1,4 +1,4 @@
-import "./bind.element.js";
+import "../define.js";
 
 import { fixtureSync, html } from "@open-wc/testing";
 import { assert } from "chai";
@@ -48,10 +48,10 @@ it("should pass props to specified child", () => {
         });
       }}
     >
-      <j-bind attrs="href:href" target="#test">
-        <a>Default</a>
-        <a id="test">Target</a>
-      </j-bind>
+      <j-bind attrs="href:href" target="#test"></j-bind>
+
+      <a>Default</a>
+      <a id="test">Target</a>
     </div>
   `);
 
@@ -103,3 +103,58 @@ it("should default to the mapTo value if bindTo is not provided", () => {
   assert.equal(input?.selectionStart, 8);
   assert.equal(input?.selectionEnd, 8);
 });
+
+it("should write not update if the calculated value is the same as the old value", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: { foo: "bar" }, newValue: { foo: "bar" } });
+      }}
+    >
+      <j-bind props="value:data.foo">
+        <input />
+      </j-bind>
+    </div>
+  `);
+
+  const input = element.querySelector("input");
+
+  assert.equal(input?.value, "");
+});
+
+it("should wait for depends-on before dispatching events", async () => {
+  let eventDispatched = false;
+
+  customElements.define("dependency-1", class extends HTMLElement {});
+  customElements.define("dependency-2", class extends HTMLElement {});
+
+  fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        if (e.expression.bindTo === "href") {
+          eventDispatched = true;
+          e.update({
+            oldValue: null,
+            newValue: "$foo",
+          });
+        }
+      }}
+    >
+      <j-bind attrs="href:href" depends-on="dependency-1,dependency-2">
+        <a>Hello World</a>
+      </j-bind>
+    </div>
+  `);
+
+  // Initially, no event should be dispatched
+  assert.isFalse(eventDispatched);
+
+  // Wait for the custom elements to be defined
+  await Promise.all([
+    customElements.whenDefined("dependency-1"),
+    customElements.whenDefined("dependency-2"),
+  ]);
+
+  // Now the event should be dispatched
+  assert.isTrue(eventDispatched);
+});

package/src/lib/elements/bind.element.ts

@@ -3,12 +3,6 @@ import { attr, element, css, html } from "@joist/element";
 import { JExpression } from "../expression.js";
 import { JoistValueEvent } from "../events.js";
 
-declare global {
-  interface HTMLElementTagNameMap {
-    "j-bind": JoistBindElement;
-  }
-}
-
 export class JAttrToken extends JExpression {
   mapTo: string;
 
@@ -22,7 +16,6 @@ export class JAttrToken extends JExpression {
 }
 
 @element({
-  tagName: "j-bind",
   // prettier-ignore
   shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
 })
@@ -36,30 +29,41 @@ export class JoistBindElement extends HTMLElement {
   @attr()
   accessor target = "";
 
-  connectedCallback(): void {
+  @attr({
+    name: "depends-on",
+  })
+  accessor dependsOn = "";
+
+  async connectedCallback(): Promise<void> {
     const attrBindings = this.#parseBinding(this.attrs);
     const propBindings = this.#parseBinding(this.props);
 
-    let child = this.firstElementChild;
+    let children: Iterable<Element> = this.children;
+
+    const root = this.getRootNode() as Document | ShadowRoot;
 
     if (this.target) {
-      child = this.querySelector(this.target);
+      children = root.querySelectorAll(this.target);
     }
 
-    if (!child) {
-      throw new Error("j-bind must have a child element or defined target");
+    if (this.dependsOn) {
+      await Promise.all(
+        this.dependsOn.split(",").map((tag) => window.customElements.whenDefined(tag)),
+      );
     }
 
     for (const attrValue of attrBindings) {
       const token = new JAttrToken(attrValue);
 
       this.#dispatch(token, (value) => {
-        if (value === true) {
-          child.setAttribute(token.mapTo, "");
-        } else if (value === false) {
-          child.removeAttribute(token.mapTo);
-        } else {
-          child.setAttribute(token.mapTo, String(value));
+        for (const child of children) {
+          if (value === true) {
+            child.setAttribute(token.mapTo, "");
+          } else if (value === false) {
+            child.removeAttribute(token.mapTo);
+          } else {
+            child.setAttribute(token.mapTo, String(value));
+          }
         }
       });
     }
@@ -68,7 +72,9 @@ export class JoistBindElement extends HTMLElement {
       const token = new JAttrToken(propValue);
 
       this.#dispatch(token, (value) => {
-        Reflect.set(child, token.mapTo, value);
+        for (const child of children) {
+          Reflect.set(child, token.mapTo, value);
+        }
       });
     }
   }
@@ -88,6 +94,11 @@ export class JoistBindElement extends HTMLElement {
         }
 
         let valueToWrite = token.evaluate(newValue);
+        let oldWrittenValue = token.evaluate(oldValue);
+
+        if (oldWrittenValue === valueToWrite) {
+          return;
+        }
 
         if (token.isNegated) {
           valueToWrite = !valueToWrite;

package/src/lib/elements/for.element.test.ts

@@ -1,5 +1,4 @@
-import "./for.element.js";
-import "./value.element.js";
+import "../define.js";
 
 import { fixtureSync, html } from "@open-wc/testing";
 import { assert } from "chai";
@@ -118,14 +117,17 @@ it("should provide index and position information", () => {
     >
       <j-for bind="items">
         <template>
-          <j-val bind="each.value"></j-val>
-          (index: <j-val bind="each.index"></j-val>, position: <j-val bind="each.position"></j-val>)
+          <div class="item">
+            <j-val bind="each.value"></j-val>
+            (index: <j-val bind="each.index"></j-val>, position:
+            <j-val bind="each.position"></j-val>)
+          </div>
         </template>
       </j-for>
     </div>
   `);
 
-  const items = element.querySelectorAll("j-for-scope");
+  const items = element.querySelectorAll(".item");
   assert.equal(items.length, 3);
   assert.equal(
     items[0].textContent?.trim().replaceAll("\n", "").replaceAll(" ", ""),
@@ -171,12 +173,14 @@ it("should provide index and position information", () => {
 //   const groups = element.querySelectorAll(".group");
 //   assert.equal(groups.length, 2);
 
+//   console.log(groups);
+
 //   const items = element.querySelectorAll(".child");
 //   assert.equal(items.length, 4);
-//   assert.equal(items[0].textContent?.trim(), "A");
-//   assert.equal(items[1].textContent?.trim(), "B");
-//   assert.equal(items[2].textContent?.trim(), "C");
-//   assert.equal(items[3].textContent?.trim(), "D");
+//   // assert.equal(items[0].textContent?.trim(), "A");
+//   // assert.equal(items[1].textContent?.trim(), "B");
+//   // assert.equal(items[2].textContent?.trim(), "C");
+//   // assert.equal(items[3].textContent?.trim(), "D");
 // });
 
 it("should maintain DOM order when items are reordered", () => {
@@ -218,3 +222,44 @@ it("should maintain DOM order when items are reordered", () => {
   assert.equal(items[1].textContent?.trim(), "First");
   assert.equal(items[2].textContent?.trim(), "Second");
 });
+
+it("should wait for depends-on before dispatching events", async () => {
+  let eventDispatched = false;
+
+  customElements.define("dependency-1", class extends HTMLElement {});
+  customElements.define("dependency-2", class extends HTMLElement {});
+
+  fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        if (e.expression.bindTo === "items") {
+          eventDispatched = true;
+          e.update({
+            oldValue: null,
+            newValue: ["A", "B", "C"],
+          });
+        }
+      }}
+    >
+      <j-for bind="items" depends-on="dependency-1,dependency-2">
+        <template>
+          <div class="item">
+            <j-val bind="each.value"></j-val>
+          </div>
+        </template>
+      </j-for>
+    </div>
+  `);
+
+  // Initially, no event should be dispatched
+  assert.isFalse(eventDispatched);
+
+  // Wait for the custom elements to be defined
+  await Promise.all([
+    customElements.whenDefined("dependency-1"),
+    customElements.whenDefined("dependency-2"),
+  ]);
+
+  // Now the event should be dispatched
+  assert.isTrue(eventDispatched);
+});

package/src/lib/elements/for.element.ts

@@ -1,56 +1,88 @@
 import { attr, element, query, css, html } from "@joist/element";
+import { Change, Changes, effect, observe } from "@joist/observable";
 
-import { bind } from "../bind.js";
-import { JoistValueEvent } from "../events.js";
+import { BindChange, JoistValueEvent } from "../events.js";
 import { JExpression } from "../expression.js";
 
-declare global {
-  interface HTMLElementTagNameMap {
-    "j-for": JositForElement;
-    "j-for-scope": JForScope;
-  }
-}
-
 export interface EachCtx<T> {
   value: T | null;
   index: number | null;
   position: number | null;
 }
 
-@element({
-  tagName: "j-for-scope",
-  // prettier-ignore
-  shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
-})
-export class JForScope<T = unknown> extends HTMLElement {
-  @bind()
+class JoistForScopeContainer<T = unknown> {
+  host: Element;
+
+  get key(): string | null {
+    return this.host.getAttribute("key");
+  }
+
+  #callbacks: Array<(val: BindChange<EachCtx<T>>) => void> = [];
+
+  @observe()
   accessor each: EachCtx<T> = {
     value: null,
     index: null,
     position: null,
   };
 
-  @attr()
-  accessor key: unknown;
+  constructor(host: Element | null) {
+    if (host == null) {
+      throw new Error("JForScope required a host element");
+    }
+
+    this.host = host;
+
+    this.host.addEventListener("joist::value", (e) => {
+      if (e.expression.bindTo === "each") {
+        e.stopPropagation();
+
+        this.#callbacks.push(e.update);
+
+        e.update({
+          oldValue: null,
+          newValue: this.each,
+          firstChange: true,
+        });
+      }
+    });
+  }
+
+  @effect()
+  onChange(changes: Changes<this>): void {
+    const change = changes.get("each") as Change<EachCtx<T>>;
+
+    for (let cb of this.#callbacks) {
+      cb({
+        oldValue: change.oldValue,
+        newValue: change.newValue,
+        firstChange: false,
+      });
+    }
+  }
 }
 
 @element({
-  tagName: "j-for",
   // prettier-ignore
   shadowDom: [css`:host{display:contents;}`, html`<slot></slot>`],
 })
-export class JositForElement extends HTMLElement {
+export class JoistForElement extends HTMLElement {
   @attr()
   accessor bind = "";
 
   @attr()
   accessor key = "";
 
+  @attr({
+    name: "depends-on",
+  })
+  accessor dependsOn = "";
+
   #template = query("template", this);
   #items: Iterable<unknown> = [];
-  #scopes = new Map<unknown, JForScope>();
+  #scopes = new Map<string, JoistForScopeContainer>();
 
-  connectedCallback(): void {
+  async connectedCallback(): Promise<void> {
     const template = this.#template();
 
     if (this.firstElementChild !== template) {
@@ -59,11 +91,17 @@ export class JositForElement extends HTMLElement {
 
     // collect all scopes from the template to be matched against later
     let currentScope = template.nextElementSibling;
-    while (currentScope instanceof JForScope) {
-      this.#scopes.set(currentScope.key, currentScope);
+    while (currentScope instanceof JoistForScopeContainer) {
+      this.#scopes.set(String(currentScope.key), currentScope);
       currentScope = currentScope.nextElementSibling;
     }
 
+    if (this.dependsOn) {
+      await Promise.all(
+        this.dependsOn.split(",").map((tag) => window.customElements.whenDefined(tag)),
+      );
+    }
+
     const token = new JExpression(this.bind);
 
     this.dispatchEvent(
@@ -91,8 +129,6 @@ export class JositForElement extends HTMLElement {
   // Updates the DOM by either inserting new scopes or moving existing ones
   // to their correct positions based on the current iteration order
   createFromEmpty(): void {
-    const template = this.#template();
-    const templateContent = template.content;
     const keyProperty = this.key;
     const fragment = document.createDocumentFragment();
 
@@ -104,13 +140,15 @@ export class JositForElement extends HTMLElement {
         key = value[keyProperty];
       }
 
-      const scope = new JForScope();
-      scope.append(document.importNode(templateContent, true));
-      scope.key = key;
+      const scope = this.#createScopeContainer();
+
+      scope.host.setAttribute("key", String(key));
       scope.each = { position: index + 1, index, value };
 
-      fragment.appendChild(scope);
-      this.#scopes.set(key, scope);
+      fragment.appendChild(scope.host);
+
+      this.#scopes.set(String(key), scope);
+
       index++;
     }
 
@@ -120,8 +158,7 @@ export class JositForElement extends HTMLElement {
   // Updates the DOM by either inserting new scopes or moving existing ones
   // to their correct positions based on the current iteration order
   updateItems(): void {
-    const template = this.#template();
-    const leftoverScopes = new Map<unknown, JForScope>(this.#scopes);
+    const leftoverScopes = new Map<unknown, JoistForScopeContainer>(this.#scopes);
     const keyProperty = this.key;
 
     let index = 0;
@@ -136,23 +173,23 @@ export class JositForElement extends HTMLElement {
       let scope = leftoverScopes.get(key);
 
       if (!scope) {
-        scope = new JForScope();
-        scope.append(document.importNode(template.content, true));
-        this.#scopes.set(key, scope);
+        scope = scope = this.#createScopeContainer();
+
+        this.#scopes.set(String(key), scope);
       } else {
         leftoverScopes.delete(key); // Remove from map to track unused scopes
       }
 
       // Only update if values have changed
       if (scope.key !== key || scope.each.value !== value) {
-        scope.key = key;
+        scope.host.setAttribute("key", String(key));
         scope.each = { position: index + 1, index, value };
       }
 
       const child = this.children[index + 1];
 
-      if (child !== scope) {
-        this.insertBefore(scope, child);
+      if (child !== scope.host) {
+        this.insertBefore(scope.host, child);
       }
 
       index++;
@@ -160,18 +197,31 @@ export class JositForElement extends HTMLElement {
 
     // Remove unused scopes
     for (const scope of leftoverScopes.values()) {
-      scope.remove();
+      scope.host.remove();
     }
   }
 
   disconnectedCallback(): void {
     for (const scope of this.#scopes.values()) {
-      scope.remove();
+      scope.host.remove();
     }
 
     this.#scopes.clear();
     this.#items = [];
   }
+
+  #createScopeContainer() {
+    const template = this.#template();
+    const content = template.content.firstElementChild;
+
+    if (content === null) {
+      throw new Error("template must contain a single parent element");
+    }
+
+    const fragment = document.importNode(content, true);
+
+    return new JoistForScopeContainer(fragment);
+  }
 }
 
 function isIterable<T = unknown>(obj: any): obj is Iterable<T> {