@joist/element 4.2.3-next.0 → 4.2.3-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "4.2.3-next.0",
+  "version": "4.2.3-next.1",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",

package/src/lib/attr-changed.test.ts

@@ -16,7 +16,6 @@ it("should call specific attrbute callback", () => {
 
     @attrChanged("test")
     onTestChanged(name: string, oldValue: string, newValue: string) {
-      console.log("onTestChanged", name, oldValue, newValue);
       args = [name, oldValue, newValue];
     }
   }

package/src/lib/templating/README.md

@@ -65,8 +65,31 @@ Conditionally renders content based on a boolean expression:
     <div>This content is shown when isHidden is false</div>
   </template>
 </j-if>
+
+<!-- With else template -->
+<j-if bind="isLoggedIn">
+  <template>
+    <div>Welcome back!</div>
+  </template>
+  <template else>
+    <div>Please log in</div>
+  </template>
+</j-if>
 ```
 
+The `j-if` element supports:
+- Boolean expressions for conditional rendering
+- Negation operator (`!`) for inverse conditions
+- Optional `else` template for fallback content
+- Automatic cleanup of removed content
+
+Common use cases:
+- Toggling visibility of UI elements
+- Conditional form fields
+- Feature flags
+- Authentication states
+- Loading states
+
 ### Property Binding (`j-props`)
 
 Binds values to element properties (rather than attributes). This is particularly useful for boolean properties, form inputs, and other cases where attribute binding isn't sufficient:
@@ -134,6 +157,48 @@ Displays a bound value as text content:
 <j-value bind="formattedPrice"></j-value>
 ```
 
+### Async State Handling (`j-async`)
+
+Handles asynchronous operations and state management with loading, success, and error states:
+
+```html
+<j-async bind="userPromise">
+  <template loading>Loading user data...</template>
+  <template success>
+    <div>Welcome, <j-value bind="data.name"></j-value>!</div>
+  </template>
+  <template error>
+    <div>Error loading user data: <j-value bind="error"></j-value></div>
+  </template>
+</j-async>
+```
+
+The `j-async` element supports:
+- Promise handling with automatic state transitions
+- Loading, success, and error templates
+- Automatic cleanup on disconnection
+
+Example usage:
+```typescript
+// In your component
+@bind()
+accessor userPromise = fetch('/api/user').then(r => r.json());
+```
+
+```html
+<j-async bind="userPromise">
+  <template loading>Loading...</template>
+  
+  <template success>
+    <div>Welcome, <j-value bind="state.data.name"></j-value>!</div>
+  </template>
+
+  <template error>
+    <div>Error: <j-value bind="state.error"></j-value></div>
+  </template>
+</j-async>
+```
+
 ## Complete Example
 
 Here's a complete todo application in a single component:
@@ -289,4 +354,53 @@ The templating system is built on top of Joist's observable system (`@joist/obse
 2. Keep binding expressions simple and avoid deep nesting
 3. Consider performance implications when binding to frequently changing values
 4. Always use a `key` attribute with `j-for` when items can be reordered
-5. Place template content directly inside `j-if` and `j-for` elements
+5. Place template content directly inside `j-if` and `j-for` elements
+
+## Manual Value Handling
+
+You can manually handle value requests and updates by listening for the `joist::value` event. This is useful when you need more control over the binding process or want to implement custom binding logic:
+
+```typescript
+class MyElement extends HTMLElement {
+  connectedCallback() {
+    // Listen for value requests
+    this.addEventListener('joist::value', (e: JoistValueEvent) => {
+      const token = e.token;
+      
+      // Handle the value request
+      if (token.bindTo === 'myValue') {
+        // Update the value
+        e.update({ 
+          oldValue: this.myValue, 
+          newValue: this.myValue 
+        });
+      }
+    });
+  }
+}
+```
+
+Example with async value handling:
+```typescript
+class MyElement extends HTMLElement {
+  connectedCallback() {
+    this.addEventListener('joist::value', (e: JoistValueEvent) => {
+      const token = e.token;
+      
+      if (token.bindTo === 'userData') {
+        e.update({ 
+          oldValue: this.userData, 
+          newValue: data 
+        });
+      }
+    });
+  }
+}
+```
+
+Common use cases for manual value handling:
+- Custom data transformation before binding
+- Async data loading and caching
+- Complex state management
+- Integration with external data sources
+- Custom validation or error handling

package/src/lib/templating/define.ts

@@ -1,3 +1,4 @@
+import "./elements/async.element.js";
 import "./elements/for.element.js";
 import "./elements/if.element.js";
 import "./elements/props.element.js";

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

@@ -0,0 +1,90 @@
+import "./async.element.js";
+
+import { fixtureSync, html } from "@open-wc/testing";
+import { assert } from "chai";
+
+import type { JoistValueEvent } from "../events.js";
+
+it("should show loading template when promise is pending", async () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: new Promise(() => {}) });
+      }}
+    >
+      <j-async bind="test">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "Loading...");
+});
+
+it("should show success template when promise resolves", async () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: Promise.resolve("data") });
+      }}
+    >
+      <j-async bind="test">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  // Wait for promise to resolve
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(element.textContent?.trim(), "Success!");
+});
+
+it("should show error template when promise rejects", async () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: Promise.reject("error") });
+      }}
+    >
+      <j-async bind="test">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  // Wait for promise to reject
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(element.textContent?.trim(), "Error!");
+});
+
+it("should handle state transitions", async () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        const promise = new Promise((resolve) => {
+          setTimeout(() => resolve("data"), 100);
+        });
+        e.update({ oldValue: null, newValue: promise });
+      }}
+    >
+      <j-async bind="test">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  // Initially should show loading
+  assert.equal(element.textContent?.trim(), "Loading...");
+
+  // Wait for promise to resolve
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  assert.equal(element.textContent?.trim(), "Success!");
+});

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

@@ -0,0 +1,122 @@
+import { attr } from "../../attr.js";
+import { element } from "../../element.js";
+import { queryAll } from "../../query-all.js";
+import { css, html } from "../../tags.js";
+import { bind } from "../bind.js";
+
+import { JoistValueEvent } from "../events.js";
+import { JToken } from "../token.js";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "j-async": JoistAsyncElement;
+  }
+}
+
+export type AsyncState<T = unknown, E = unknown> = {
+  status: "loading" | "error" | "success";
+  data?: T;
+  error?: E;
+};
+
+@element({
+  tagName: "j-async",
+  // prettier-ignore
+  shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
+})
+export class JoistAsyncElement extends HTMLElement {
+  @attr()
+  accessor bind = "";
+
+  @bind()
+  accessor state: AsyncState | null = null;
+
+  #templates = queryAll<HTMLTemplateElement>("template", this);
+  #currentNodes: Node[] = [];
+  #cachedTemplates: {
+    loading?: HTMLTemplateElement;
+    error?: HTMLTemplateElement;
+    success?: HTMLTemplateElement;
+  } = {
+    loading: undefined,
+    error: undefined,
+    success: undefined,
+  };
+
+  connectedCallback(): void {
+    this.#clean();
+
+    // Cache all templates
+    const templates = Array.from(this.#templates());
+
+    this.#cachedTemplates = {
+      loading: templates.find((t) => t.hasAttribute("loading")),
+      error: templates.find((t) => t.hasAttribute("error")),
+      success: templates.find((t) => t.hasAttribute("success")),
+    };
+
+    const token = new JToken(this.bind);
+
+    this.dispatchEvent(
+      new JoistValueEvent(token, ({ newValue, oldValue }) => {
+        if (newValue !== oldValue) {
+          if (newValue instanceof Promise) {
+            this.#handlePromise(newValue);
+          } else {
+            console.warn("j-async bind value must be a Promise or AsyncState");
+          }
+        }
+      }),
+    );
+  }
+
+  async #handlePromise(promise: Promise<unknown>): Promise<void> {
+    try {
+      this.#handleState({ status: "loading" });
+      const data = await promise;
+      this.#handleState({ status: "success", data });
+    } catch (error) {
+      this.#handleState({ status: "error", error });
+    }
+  }
+
+  #handleState(state: AsyncState): void {
+    this.#clean();
+
+    let template: HTMLTemplateElement | undefined = undefined;
+
+    this.state = state;
+
+    switch (state.status) {
+      case "loading":
+        template = this.#cachedTemplates.loading;
+        break;
+
+      case "error":
+        template = this.#cachedTemplates.error;
+        break;
+
+      case "success":
+        template = this.#cachedTemplates.success;
+        break;
+    }
+
+    if (template) {
+      const content = document.importNode(template.content, true);
+      const nodes = Array.from(content.childNodes);
+      this.appendChild(content);
+      this.#currentNodes = nodes;
+    }
+  }
+
+  #clean(): void {
+    for (const node of this.#currentNodes) {
+      node.parentNode?.removeChild(node);
+    }
+    this.#currentNodes = [];
+  }
+
+  disconnectedCallback(): void {
+    this.#clean();
+  }
+}

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

@@ -37,3 +37,185 @@ it("should iterate over an iterable", () => {
   assert.equal(listItems[0].textContent?.trim(), "Hello");
   assert.equal(listItems[1].textContent?.trim(), "World");
 });
+
+it("should handle empty arrays", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({
+          oldValue: null,
+          newValue: [],
+        });
+      }}
+    >
+      <j-for bind="items">
+        <template>
+          <div>Item</div>
+        </template>
+      </j-for>
+    </div>
+  `);
+
+  assert.equal(element.querySelectorAll("div").length, 0);
+});
+
+it("should update when items are added or removed", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        // Initial items
+        e.update({
+          oldValue: null,
+          newValue: [
+            { id: "1", text: "First" },
+            { id: "2", text: "Second" },
+          ],
+        });
+
+        // Add an item
+        e.update({
+          oldValue: null,
+          newValue: [
+            { id: "1", text: "First" },
+            { id: "2", text: "Second" },
+            { id: "3", text: "Third" },
+          ],
+        });
+
+        // Remove an item
+        e.update({
+          oldValue: null,
+          newValue: [
+            { id: "1", text: "First" },
+            { id: "3", text: "Third" },
+          ],
+        });
+      }}
+    >
+      <j-for bind="items" key="id">
+        <template>
+          <j-value bind="each.value.text"></j-value>
+        </template>
+      </j-for>
+    </div>
+  `);
+
+  const items = element.querySelectorAll("j-value");
+  assert.equal(items.length, 2);
+  assert.equal(items[0].textContent?.trim(), "First");
+  assert.equal(items[1].textContent?.trim(), "Third");
+});
+
+it("should provide index and position information", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({
+          oldValue: null,
+          newValue: ["A", "B", "C"],
+        });
+      }}
+    >
+      <j-for bind="items">
+        <template>
+          <j-value bind="each.value"></j-value>
+          (index: <j-value bind="each.index"></j-value>,
+          position: <j-value bind="each.position"></j-value>)
+        </template>
+      </j-for>
+    </div>
+  `);
+
+  const items = element.querySelectorAll("j-for-scope");
+  assert.equal(items.length, 3);
+  assert.equal(
+    items[0].textContent?.trim().replaceAll("\n", "").replaceAll(" ", ""),
+    "A(index:0,position:1)",
+  );
+  assert.equal(
+    items[1].textContent?.trim().replaceAll("\n", "").replaceAll(" ", ""),
+    "B(index:1,position:2)",
+  );
+  assert.equal(
+    items[2].textContent?.trim().replaceAll("\n", "").replaceAll(" ", ""),
+    "C(index:2,position:3)",
+  );
+});
+
+// it("should handle nested j-for elements", () => {
+//   const element = fixtureSync(html`
+//     <div
+//       @joist::value=${(e: JoistValueEvent) => {
+//         e.update({
+//           oldValue: null,
+//           newValue: [
+//             { id: "1", items: ["A", "B"] },
+//             { id: "2", items: ["C", "D"] },
+//           ],
+//         });
+//       }}
+//     >
+//       <j-for bind="groups" key="id">
+//         <template>
+//           <div class="group">
+//             <j-for bind="each.value.items">
+//               <template>
+//                 <j-value class="child" bind="each.value"></j-value>
+//               </template>
+//             </j-for>
+//           </div>
+//         </template>
+//       </j-for>
+//     </div>
+//   `);
+
+//   const groups = element.querySelectorAll(".group");
+//   assert.equal(groups.length, 2);
+
+//   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");
+// });
+
+it("should maintain DOM order when items are reordered", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        // Initial order
+        e.update({
+          oldValue: null,
+          newValue: [
+            { id: "1", text: "First" },
+            { id: "2", text: "Second" },
+            { id: "3", text: "Third" },
+          ],
+        });
+
+        // Reorder items
+        e.update({
+          oldValue: null,
+          newValue: [
+            { id: "3", text: "Third" },
+            { id: "1", text: "First" },
+            { id: "2", text: "Second" },
+          ],
+        });
+      }}
+    >
+      <j-for bind="items" key="id">
+        <template>
+          <j-value bind="each.value.text"></j-value>
+        </template>
+      </j-for>
+    </div>
+  `);
+
+  const items = element.querySelectorAll("j-value");
+  assert.equal(items.length, 3);
+  assert.equal(items[0].textContent?.trim(), "Third");
+  assert.equal(items[1].textContent?.trim(), "First");
+  assert.equal(items[2].textContent?.trim(), "Second");
+});

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

@@ -109,18 +109,20 @@ export class JositForElement extends HTMLElement {
         value: item,
       };
 
-      if (!scope.isConnected) {
-        const child = this.children[index + 1]; // skip first child since it should be the template element
+      const child = this.children[index + 1]; // skip first child since it should be the template element
 
+      if (!scope.isConnected) {
         if (child) {
           child.before(scope);
         } else {
           this.append(scope);
         }
-
-        this.#scopes.set(key, scope);
+      } else if (child !== scope) {
+        child.before(scope);
       }
 
+      this.#scopes.set(key, scope);
+
       index++;
     }
 

package/src/lib/templating/elements/if.element.test.ts

@@ -53,3 +53,38 @@ it("should handle negated tokens correctly", () => {
 
   assert.equal(element.textContent?.trim(), "Visible Content");
 });
+
+it("should render else template when condition is falsy", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: false });
+      }}
+    >
+      <j-if bind="test">
+        <template>If Content</template>
+        <template else>Else Content</template>
+      </j-if>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "Else Content");
+});
+
+it("should switch between if and else templates", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: false });
+        e.update({ oldValue: false, newValue: true });
+      }}
+    >
+      <j-if bind="test">
+        <template>If Content</template>
+        <template else>Else Content</template>
+      </j-if>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "If Content");
+});