@joist/templating 4.2.4-next.1 → 4.2.4-next.10

package/README.md

@@ -7,7 +7,6 @@ The Joist templating system provides a powerful and flexible way to handle data
 - [Core Components](#core-components)
 - [Built-in Template Elements](#built-in-template-elements)
 - [Complete Example](#complete-example)
-- [Troubleshooting](#troubleshooting)
 
 ## Core Components
 
@@ -20,7 +19,7 @@ import { bind } from "@joist/templating";
 
 class MyElement extends HTMLElement {
   @bind()
-  accessor myProperty: string;
+  accessor myProperty = "";
 }
 ```
 
@@ -36,33 +35,13 @@ class MyElement extends HTMLElement {
   @observe()
   assessor value = "Hello World";
 
-  @bind((instance) => instance.value.toUpperCase())
+  @bind({
+    compute: (i) => i.value.toUpperCase()
+  })
   accessor formattedValue = "";
 }
 ```
 
-### Token System (`token.ts`)
-
-The `JToken` class handles parsing and evaluation of binding expressions. It supports:
-
-NOTE: Most of the time you will not be using this yourself.
-
-- Simple property bindings: `propertyName`
-- Nested property access: `user.profile.name`
-- Negation operator: `!isVisible`
-- Array access: `items.0.name`
-
-Example usage:
-
-```typescript
-const token = new JToken("user.name");
-const value = token.readTokenValueFrom(context);
-
-// With negation
-const negatedToken = new JToken("!isVisible");
-const isHidden = negatedToken.readTokenValueFrom(context);
-```
-
 ## Built-in Template Elements
 
 Joist provides several built-in template elements for common templating needs:
@@ -82,7 +61,7 @@ Displays a bound value as text content:
 <j-val bind="user.profile.address.city"></j-val>
 
 <!-- With array access -->
-<j-val bind="items[0].name"></j-val>
+<j-val bind="items.0.name"></j-val>
 ```
 
 ### Conditional Rendering (`j-if`)
@@ -104,6 +83,38 @@ Conditionally renders content based on a boolean expression:
   </template>
 </j-if>
 
+<!-- With comparison operators -->
+<j-if bind="status == active">
+  <template>
+    <div>Status is active</div>
+  </template>
+</j-if>
+
+<j-if bind="status != active">
+  <template>
+    <div>Status is not active</div>
+  </template>
+</j-if>
+
+<j-if bind="count > 5">
+  <template>
+    <div>Count is greater than 5</div>
+  </template>
+</j-if>
+
+<j-if bind="score < 100">
+  <template>
+    <div>Score is less than 100</div>
+  </template>
+</j-if>
+
+<!-- With nested paths -->
+<j-if bind="user.score > 100">
+  <template>
+    <div>User's score is above 100</div>
+  </template>
+</j-if>
+
 <!-- With else template -->
 <j-if bind="isLoggedIn">
   <template>
@@ -119,6 +130,12 @@ The `j-if` element supports:
 
 - Boolean expressions for conditional rendering
 - Negation operator (`!`) for inverse conditions
+- Comparison operators:
+  - Equality (`==`): `status == active`
+  - Inequality (`!=`): `status != active`
+  - Greater than (`>`): `count > 5`
+  - Less than (`<`): `score < 100`
+- Nested property paths: `user.score > 100`
 - Optional `else` template for fallback content
 - Automatic cleanup of removed content
 
@@ -258,141 +275,3 @@ The `j-async` element supports:
 - Promise handling with automatic state transitions
 - Loading, success, and error templates
 - State object with typed data and error fields
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Binding Not Updating**
-
-   - Check if the property is decorated with `@bind()`
-   - Verify the binding expression is correct
-   - Ensure the property is being updated correctly
-
-2. **List Rendering Issues**
-
-   - Verify the `key` attribute is unique and stable
-   - Check if the list items are properly structured
-   - Ensure the binding expression matches the data structure
-
-3. **Async State Problems**
-   - Verify the Promise is properly resolved/rejected
-   - Check if all required templates are present
-   - Ensure error handling is implemented
-
-## 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) => {
-      const token = e.token;
-
-      // Handle the value request
-      if (token.bindTo === "myValue") {
-        // Update the value
-        e.update({
-          oldValue: this.myValue,
-          newValue: this.myValue,
-        });
-      }
-    });
-  }
-}
-```
-
-## Complete Example
-
-Here's a complete todo application in a single component:
-
-```typescript
-import { bind } from "@joist/templating";
-import { element, html, css, listen, query } from "@joist/element";
-
-interface Todo {
-  id: string;
-  text: string;
-}
-
-@element({
-  tagName: "todo-list",
-  shadowDom: [
-    css`
-      :host {
-        display: block;
-        max-width: 600px;
-        margin: 2rem auto;
-      }
-      .form {
-        display: flex;
-        gap: 1rem;
-      }
-      .todo-item {
-        align-items: center;
-        display: flex;
-        gap: 0.5rem;
-        margin: 0.5rem 0;
-      }
-      .todo-text {
-        flex: 1;
-      }
-    `,
-    html`
-      <form class="form">
-        <input type="text" placeholder="What needs to be done?" />
-        <button type="submit">Add</button>
-      </form>
-
-      <j-if bind="!todos.length">
-        <template>
-          <p>No todos yet!</p>
-        </template>
-      </j-if>
-
-      <j-for id="todos" bind="todos" key="id">
-        <template>
-          <div class="todo-item">
-            <j-val class="todo-text" bind="each.value.text"></j-val>
-
-            <j-bind attrs="data-id:each.value.id">
-              <button>×</button>
-            </j-bind>
-          </div>
-        </template>
-      </j-for>
-
-      <j-val bind="todos.length"></j-val> remaining
-    `,
-  ],
-})
-export class TodoList extends HTMLElement {
-  @bind()
-  accessor todos: Todo[] = [];
-
-  #nextId = 1;
-  #input = query("input");
-
-  @listen("submit", "form")
-  onSubmit(e: SubmitEvent) {
-    e.preventDefault();
-
-    const input = this.#input();
-
-    this.todos = [...this.todos, { id: String(this.#nextId++), text: input.value.trim() }];
-
-    input.value = "";
-  }
-
-  @listen("click", "#todos")
-  onDelete(e: Event) {
-    if (e.target instanceof HTMLButtonElement) {
-      const id = Number(e.target.dataset.id);
-
-      this.todos = this.todos.filter((todo) => todo.id !== id);
-    }
-  }
-}
-```

package/package.json

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

package/src/lib/bind.test.ts

@@ -0,0 +1,72 @@
+import { assert } from "chai";
+import { bind } from "./bind.js";
+import { JoistValueEvent } from "./events.js";
+import { JExpression } from "./expression.js";
+
+describe("bind decorator", () => {
+  class TestElement extends HTMLElement {
+    @bind()
+    accessor value = "initial";
+
+    @bind({ alwaysUpdate: true })
+    accessor alwaysUpdateValue = "initial";
+  }
+
+  customElements.define("test-element", TestElement);
+
+  it("should initialize with default value", () => {
+    const element = new TestElement();
+    assert.equal(element.value, "initial");
+  });
+
+  it("should update value and trigger binding", async () => {
+    const element = new TestElement();
+    let oldValue: unknown = null;
+    let newValue: unknown = null;
+
+    element.dispatchEvent(
+      new JoistValueEvent(new JExpression("value"), (update) => {
+        oldValue = update.oldValue;
+        newValue = update.newValue;
+      }),
+    );
+
+    assert.equal(oldValue, null);
+    assert.equal(newValue, "initial");
+
+    element.value = "updated";
+
+    await Promise.resolve();
+
+    assert.equal(oldValue, "initial");
+    assert.equal(newValue, "updated");
+  });
+
+  it("should trigger binding on every change with alwaysUpdate option", async () => {
+    const element = new TestElement();
+    let bindingCount = 0;
+    let oldValue: unknown;
+    let newValue: unknown;
+
+    element.dispatchEvent(
+      new JoistValueEvent(new JExpression("alwaysUpdateValue"), (update) => {
+        bindingCount++;
+        oldValue = update.oldValue;
+        newValue = update.newValue;
+      }),
+    );
+
+    assert.equal(bindingCount, 1);
+    assert.equal(oldValue, null);
+    assert.equal(newValue, "initial");
+
+    // Change some other value in the model
+    element.value = "something else";
+
+    await Promise.resolve();
+
+    assert.equal(bindingCount, 2);
+    assert.equal(oldValue, "initial");
+    assert.equal(newValue, "initial");
+  });
+});

package/src/lib/bind.ts

@@ -1,28 +1,51 @@
-import { instanceMetadataStore, observe } from "@joist/observable";
+import { instanceMetadataStore, observe, ObserveOpts } from "@joist/observable";
 
-export function bind<This extends HTMLElement, Value>(mapper?: (instance: This) => Value) {
+export interface BindOpts<This, Value> extends ObserveOpts<This, Value> {
+  /**
+   * Trigger bindings on every change cycle, regardless of value,
+   * newValue and oldValue will be the same in that case
+   **/
+  alwaysUpdate?: boolean;
+}
+
+export function bind<This extends HTMLElement, Value>(opts: BindOpts<This, Value> = {}) {
   return function bindDecorator(
     base: ClassAccessorDecoratorTarget<This, Value>,
     ctx: ClassAccessorDecoratorContext<This, Value>,
   ): ClassAccessorDecoratorResult<This, Value> {
-    const internalObserve = observe(mapper)(base, ctx);
+    const internalObserve = observe(opts)(base, ctx);
 
     return {
       init(value) {
         this.addEventListener("joist::value", (e) => {
-          if (e.token.bindTo === ctx.name) {
+          if (e.expression.bindTo === ctx.name) {
             const instanceMeta = instanceMetadataStore.read<This>(this);
 
             e.stopPropagation();
 
-            e.update({ oldValue: null, newValue: ctx.access.get(this) });
+            e.update({
+              oldValue: null,
+              newValue: ctx.access.get(this),
+              alwaysUpdate: opts.alwaysUpdate,
+              firstChange: true,
+            });
+
+            const name = ctx.name as keyof This;
 
             instanceMeta.bindings.add((changes) => {
-              const key = ctx.name as keyof This;
-              const res = changes.get(key);
+              const change = changes.get(name);
+
+              if (change) {
+                e.update({ ...change, alwaysUpdate: opts.alwaysUpdate, firstChange: false });
+              } else if (opts.alwaysUpdate) {
+                const value = ctx.access.get(this);
 
-              if (res) {
-                e.update(res);
+                e.update({
+                  oldValue: value,
+                  newValue: value,
+                  alwaysUpdate: opts.alwaysUpdate,
+                  firstChange: false,
+                });
               }
             });
           }

package/src/lib/define.ts

@@ -3,3 +3,4 @@ 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";

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

@@ -88,3 +88,93 @@ it("should handle state transitions", async () => {
   await new Promise((resolve) => setTimeout(resolve, 150));
   assert.equal(element.textContent?.trim(), "Success!");
 });
+
+it("should show loading template when AsyncState is loading", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: { status: "loading" } });
+      }}
+    >
+      <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 AsyncState is success", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: { status: "success", data: "test data" } });
+      }}
+    >
+      <j-async bind="test">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "Success!");
+});
+
+it("should show error template when AsyncState is error", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: { status: "error", error: "test error" } });
+      }}
+    >
+      <j-async bind="test">
+        <template loading>Loading...</template>
+        <template success>Success!</template>
+        <template error>Error!</template>
+      </j-async>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "Error!");
+});
+
+it("should handle AsyncState transitions", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        // Initial state
+        e.update({ oldValue: null, newValue: { status: "loading" } });
+
+        // Simulate state transition after a short delay
+        setTimeout(() => {
+          e.update({
+            oldValue: { status: "loading" },
+            newValue: { status: "success", data: "test data" },
+          });
+        }, 100);
+      }}
+    >
+      <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 state transition
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      assert.equal(element.textContent?.trim(), "Success!");
+      resolve(undefined);
+    }, 150);
+  });
+});

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

@@ -2,7 +2,7 @@ import { attr, element, queryAll, css, html } from "@joist/element";
 
 import { bind } from "../bind.js";
 import { JoistValueEvent } from "../events.js";
-import { JToken } from "../token.js";
+import { JExpression } from "../expression.js";
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -52,13 +52,15 @@ export class JoistAsyncElement extends HTMLElement {
       success: templates.find((t) => t.hasAttribute("success")),
     };
 
-    const token = new JToken(this.bind);
+    const token = new JExpression(this.bind);
 
     this.dispatchEvent(
       new JoistValueEvent(token, ({ newValue, oldValue }) => {
         if (newValue !== oldValue) {
           if (newValue instanceof Promise) {
             this.#handlePromise(newValue);
+          } else if (this.#isAsyncState(newValue)) {
+            this.#handleState(newValue);
           } else {
             console.warn("j-async bind value must be a Promise or AsyncState");
           }
@@ -67,6 +69,15 @@ export class JoistAsyncElement extends HTMLElement {
     );
   }
 
+  #isAsyncState(value: unknown): value is AsyncState {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      "status" in value &&
+      (value.status === "loading" || value.status === "error" || value.status === "success")
+    );
+  }
+
   async #handlePromise(promise: Promise<unknown>): Promise<void> {
     try {
       this.#handleState({ status: "loading" });

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

@@ -9,14 +9,14 @@ it("should pass props to child", () => {
   const element = fixtureSync(html`
     <div
       @joist::value=${(e: JoistValueEvent) => {
-        if (e.token.bindTo === "href") {
+        if (e.expression.bindTo === "href") {
           e.update({
             oldValue: null,
             newValue: "$foo",
           });
         }
 
-        if (e.token.bindTo === "target") {
+        if (e.expression.bindTo === "target") {
           e.update({
             oldValue: null,
             newValue: {

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

@@ -1,10 +1,15 @@
 import { attr, element, css, html } from "@joist/element";
 
-// import { JoistValueEvent } from "../events.js";
-import { JToken } from "../token.js";
+import { JExpression } from "../expression.js";
 import { JoistValueEvent } from "../events.js";
 
-export class JAttrToken extends JToken {
+declare global {
+  interface HTMLElementTagNameMap {
+    "j-bind": JoistBindElement;
+  }
+}
+
+export class JAttrToken extends JExpression {
   mapTo: string;
 
   constructor(binding: string) {
@@ -21,7 +26,7 @@ export class JAttrToken extends JToken {
   // prettier-ignore
   shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
 })
-export class JoistIfElement extends HTMLElement {
+export class JoistBindElement extends HTMLElement {
   @attr()
   accessor props = "";
 
@@ -75,18 +80,14 @@ export class JoistIfElement extends HTMLElement {
       .filter((b) => b);
   }
 
-  #dispatch(token: JToken, write: (value: unknown) => void) {
+  #dispatch(token: JExpression, write: (value: unknown) => void) {
     this.dispatchEvent(
-      new JoistValueEvent(token, ({ newValue, oldValue }) => {
-        if (newValue === oldValue) {
+      new JoistValueEvent(token, ({ newValue, oldValue, alwaysUpdate }) => {
+        if (newValue === oldValue && !alwaysUpdate) {
           return;
         }
 
-        let valueToWrite = newValue;
-
-        if (typeof newValue === "object" && newValue !== null) {
-          valueToWrite = token.readTokenValueFrom(newValue);
-        }
+        let valueToWrite = token.evaluate(newValue);
 
         if (token.isNegated) {
           valueToWrite = !valueToWrite;

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

@@ -2,7 +2,7 @@ import { attr, element, query, css, html } from "@joist/element";
 
 import { bind } from "../bind.js";
 import { JoistValueEvent } from "../events.js";
-import { JToken } from "../token.js";
+import { JExpression } from "../expression.js";
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -31,7 +31,7 @@ export class JForScope<T = unknown> extends HTMLElement {
   };
 
   @attr()
-  accessor key = "";
+  accessor key: unknown;
 }
 
 @element({
@@ -64,7 +64,7 @@ export class JositForElement extends HTMLElement {
       currentScope = currentScope.nextElementSibling;
     }
 
-    const token = new JToken(this.bind);
+    const token = new JExpression(this.bind);
 
     this.dispatchEvent(
       new JoistValueEvent(token, ({ newValue, oldValue }) => {
@@ -98,11 +98,15 @@ export class JositForElement extends HTMLElement {
 
     let index = 0;
     for (const value of this.#items) {
-      const key = keyProperty && hasProperty(value, keyProperty) ? value[keyProperty] : index;
+      let key: unknown = index;
+
+      if (keyProperty && hasProperty(value, keyProperty)) {
+        key = value[keyProperty];
+      }
 
       const scope = new JForScope();
       scope.append(document.importNode(templateContent, true));
-      scope.key = String(key);
+      scope.key = key;
       scope.each = { position: index + 1, index, value };
 
       fragment.appendChild(scope);
@@ -118,13 +122,16 @@ export class JositForElement extends HTMLElement {
   updateItems(): void {
     const template = this.#template();
     const leftoverScopes = new Map<unknown, JForScope>(this.#scopes);
-    const keyProperty = this.key; // Cache the key property
+    const keyProperty = this.key;
 
     let index = 0;
 
     for (const value of this.#items) {
-      // Optimize key lookup by caching the property check
-      const key = keyProperty && hasProperty(value, keyProperty) ? value[keyProperty] : index;
+      let key: unknown = index;
+
+      if (keyProperty && hasProperty(value, keyProperty)) {
+        key = value[keyProperty];
+      }
 
       let scope = leftoverScopes.get(key);
 
@@ -138,7 +145,7 @@ export class JositForElement extends HTMLElement {
 
       // Only update if values have changed
       if (scope.key !== key || scope.each.value !== value) {
-        scope.key = String(key);
+        scope.key = key;
         scope.each = { position: index + 1, index, value };
       }