@joist/templating 4.2.3 → 4.2.4-next.1

package/README.md

@@ -2,6 +2,13 @@
 
 The Joist templating system provides a powerful and flexible way to handle data binding and templating in web components. This documentation covers the core components and their usage.
 
+## Table of Contents
+
+- [Core Components](#core-components)
+- [Built-in Template Elements](#built-in-template-elements)
+- [Complete Example](#complete-example)
+- [Troubleshooting](#troubleshooting)
+
 ## Core Components
 
 ### Bind Decorator (`bind.ts`)
@@ -19,42 +26,71 @@ class MyElement extends HTMLElement {
 
 The decorator:
 
-- Creates a two-way binding between component properties and templates
+- Creates a one-way binding between component properties and templates
 - Automatically handles value propagation through the `joist::value` event
 - Integrates with Joist's observable system for efficient change detection
+- Supports computed properties
+
+```typescript
+class MyElement extends HTMLElement {
+  @observe()
+  assessor value = "Hello World";
+
+  @bind((instance) => instance.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);
 ```
 
-### Events (`events.ts`)
+## Built-in Template Elements
 
-The system uses custom events for value propagation:
+Joist provides several built-in template elements for common templating needs:
 
-- `JoistValueEvent`: A custom event that handles value updates in the templating system
-- Bubbles through the DOM tree
-- Carries both the token and update mechanism
+### Value Display (`j-val`)
 
-## Built-in Template Elements
+Displays a bound value as text content:
 
-Joist provides several built-in template elements for common templating needs:
+```html
+<!-- Basic usage -->
+<j-val bind="user.name"></j-val>
+
+<!-- With formatting -->
+<j-val bind="formattedPrice"></j-val>
+
+<!-- With nested properties -->
+<j-val bind="user.profile.address.city"></j-val>
+
+<!-- With array access -->
+<j-val bind="items[0].name"></j-val>
+```
 
 ### Conditional Rendering (`j-if`)
 
 Conditionally renders content based on a boolean expression:
 
 ```html
+<!-- Basic usage -->
 <j-if bind="isVisible">
   <template>
     <div>This content is only shown when isVisible is true</div>
@@ -86,37 +122,64 @@ The `j-if` element supports:
 - Optional `else` template for fallback content
 - Automatic cleanup of removed content
 
-Common use cases:
+### Property Binding (`j-bind`)
+
+Binds values to element properties and attributes. By default it will bind values to the first child element of `j-bind`
 
-- Toggling visibility of UI elements
-- Conditional form fields
-- Feature flags
-- Authentication states
-- Loading states
+- `props` Binds to element properties
+- `attrs` prefix: Binds to element attributes
 
-### Property Binding (`j-props`)
+#### Binding Syntax
 
-Binds values to element properties and attributes. The prefix determines the binding type:
+The binding syntax follows the format `target:source` where:
 
-- `$.` prefix: Binds to element properties
-- `$` prefix: Binds to element attributes
+- `target` is the property/attribute name to bind to
+- `source` is the value to bind from
 
 ```html
-<j-props>
-  <!-- Bind to boolean properties -->
-  <input type="checkbox" $.checked="isComplete">
+<!-- Basic attribute binding -->
+<j-bind attrs="href:href">
+  <a>Link</a>
+</j-bind>
+
+<!-- Property binding -->
+<j-bind props="target:some.value">
+  <a>Link</a>
+</j-bind>
+
+<!-- Multiple bindings -->
+<j-bind props="selectionStart:foo, selectionEnd:foo">
+  <input value="1234567890" />
+</j-bind>
+
+<!-- Style binding -->
+<j-bind props="style.color:color, style.backgroundColor:bgColor">
+  <div>Styled content</div>
+</j-bind>
+```
 
-  <!-- Bind to form input values -->
-  <input type="text" $.value="userName">
+#### Targeting Specific Elements
 
-  <!-- Bind to custom element properties -->
-  <my-element $.data="complexObject">
+You can target a specific child element using the `target` attribute:
 
-  <!-- Bind to attributes -->
-  <div $class="dynamicClass">
-  <img $src="imageUrl">
-  <input $placeholder="placeholderText">
-</j-props>
+```html
+<j-bind attrs="href:href" target="#test">
+  <a>Default</a>
+  <a id="test">Target</a>
+</j-bind>
+```
+
+#### Boolean Attributes
+
+Boolean attributes are handled specially:
+
+- `true` values set the attribute
+- `false` values remove the attribute
+
+```html
+<j-bind attrs="disabled:isDisabled">
+  <button>Click me</button>
+</j-bind>
 ```
 
 ### List Rendering (`j-for`)
@@ -124,25 +187,26 @@ Binds values to element properties and attributes. The prefix determines the bin
 Renders lists of items with support for keyed updates:
 
 ```html
+<!-- Basic list rendering -->
 <j-for bind="todos" key="id">
   <template>
-    <j-props>
-      <div
-        class="todo-item"
-        $.dataset.id="each.value.id"
-        $.dataset.completed="each.value.completed"
-      >
-        <j-props>
-          <input type="checkbox" $.checked="each.value.completed" />
-        </j-props>
-
-        <j-value bind="each.value.text"></j-value>
-
-        <j-props>
-          <button $.disabled="!each.value.text">×</button>
-        </j-props>
-      </div>
-    </j-props>
+    <div class="todo-item">
+      <j-val bind="each.value.text"></j-val>
+    </div>
+  </template>
+</j-for>
+
+<!-- With complex item structure -->
+<j-for bind="users" key="id">
+  <template>
+    <div class="user-card">
+      <j-bind>
+        <img props="src:each.value.avatar" />
+      </j-bind>
+
+      <h3><j-val bind="each.value.name"></j-val></h3>
+      <p><j-val bind="each.value.bio"></j-val></p>
+    </div>
   </template>
 </j-for>
 ```
@@ -153,17 +217,9 @@ The `j-for` element provides context variables:
 - `each.index`: The zero-based index of the current item
 - `each.position`: The one-based position of the current item
 
-### Value Display (`j-value`)
-
-Displays a bound value as text content:
-
-```html
-<j-value bind="user.name"></j-value> <j-value bind="formattedPrice"></j-value>
-```
-
 ### Async State Handling (`j-async`)
 
-Handles asynchronous operations and state management with loading, success, and error states. The element accepts either a Promise or an AsyncState object:
+Handles asynchronous operations and state management with loading, success, and error states:
 
 ```typescript
 // AsyncState type
@@ -183,15 +239,16 @@ accessor userPromise = fetch('/api/user').then(r => r.json());
 ```
 
 ```html
+<!-- Basic async handling -->
 <j-async bind="userPromise">
   <template loading>Loading...</template>
 
   <template success>
-    <div>Welcome, <j-value bind="state.data.name"></j-value>!</div>
+    <div>Welcome, <j-val bind="state.data.name"></j-val>!</div>
   </template>
 
   <template error>
-    <div>Error: <j-value bind="state.error"></j-value></div>
+    <div>Error: <j-val bind="state.error"></j-val></div>
   </template>
 </j-async>
 ```
@@ -200,9 +257,53 @@ The `j-async` element supports:
 
 - Promise handling with automatic state transitions
 - Loading, success, and error templates
-- Automatic cleanup on disconnection
 - 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:
@@ -212,7 +313,7 @@ import { bind } from "@joist/templating";
 import { element, html, css, listen, query } from "@joist/element";
 
 interface Todo {
-  id: number;
+  id: string;
   text: string;
 }
 
@@ -230,6 +331,7 @@ interface Todo {
         gap: 1rem;
       }
       .todo-item {
+        align-items: center;
         display: flex;
         gap: 0.5rem;
         margin: 0.5rem 0;
@@ -252,14 +354,17 @@ interface Todo {
 
       <j-for id="todos" bind="todos" key="id">
         <template>
-          <j-props class="todo-item">
-            <j-value class="todo-text" bind="each.value.text"></j-value>
-            <button $.id="each.value.id" $.disabled="!each.value.text">×</button>
-          </j-props>
+          <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-value bind="todos.length"></j-value> remaining
+      <j-val bind="todos.length"></j-val> remaining
     `,
   ],
 })
@@ -276,7 +381,7 @@ export class TodoList extends HTMLElement {
 
     const input = this.#input();
 
-    this.todos = [...this.todos, { id: this.#nextId++, text: input.value.trim() }];
+    this.todos = [...this.todos, { id: String(this.#nextId++), text: input.value.trim() }];
 
     input.value = "";
   }
@@ -284,87 +389,10 @@ export class TodoList extends HTMLElement {
   @listen("click", "#todos")
   onDelete(e: Event) {
     if (e.target instanceof HTMLButtonElement) {
-      const id = Number(e.target.id);
+      const id = Number(e.target.dataset.id);
 
       this.todos = this.todos.filter((todo) => todo.id !== id);
     }
   }
 }
 ```
-
-## Usage
-
-1. Use the `@bind()` decorator on properties you want to make bindable
-2. Properties will automatically integrate with the templating system
-3. Changes are propagated through the component tree using the custom event system
-
-## Integration with Observable
-
-The templating system is built on top of Joist's observable system (`@joist/observable`), providing:
-
-- Automatic change detection
-- Efficient updates
-- Integration with the component lifecycle
-
-## Best Practices
-
-1. Use the `@bind()` decorator only on properties that need reactivity
-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
-
-## 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
-import { JoistValueEvent } from "@joist/templating";
-
-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
-import { JoistValueEvent } from "@joist/templating";
-
-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/templating",
-  "version": "4.2.3",
+  "version": "4.2.4-next.1",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -60,7 +60,6 @@
         "vitest.config.js",
         "target/**"
       ],
-      "output": [],
       "dependencies": [
         "build"
       ]

package/src/lib/define.ts

@@ -1,5 +1,5 @@
 import "./elements/async.element.js";
 import "./elements/for.element.js";
 import "./elements/if.element.js";
-import "./elements/props.element.js";
+import "./elements/bind.element.js";
 import "./elements/value.element.js";

package/src/lib/elements/{props.element.test.ts → bind.element.test.ts}

@@ -1,4 +1,4 @@
-import "./props.element.js";
+import "./bind.element.js";
 
 import { fixtureSync, html } from "@open-wc/testing";
 import { assert } from "chai";
@@ -26,9 +26,9 @@ it("should pass props to child", () => {
         }
       }}
     >
-      <j-props>
-        <a $href="href" $target="target.value">Hello World</a>
-      </j-props>
+      <j-bind attrs="href:href" props="target:target.value">
+        <a>Hello World</a>
+      </j-bind>
     </div>
   `);
 
@@ -48,10 +48,10 @@ it("should pass props to specified child", () => {
         });
       }}
     >
-      <j-props>
+      <j-bind attrs="href:href" target="#test">
         <a>Default</a>
-        <a id="test" $href="href">Target</a>
-      </j-props>
+        <a id="test">Target</a>
+      </j-bind>
     </div>
   `);
 
@@ -60,3 +60,46 @@ it("should pass props to specified child", () => {
   assert.equal(anchor[0].getAttribute("href"), null);
   assert.equal(anchor[1].getAttribute("href"), "#foo");
 });
+
+it("should be case sensitive", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: 8 });
+      }}
+    >
+      <j-bind
+        props="
+          selectionStart:foo,
+          selectionEnd:foo
+        "
+      >
+        <input value="1234567890" />
+      </j-bind>
+    </div>
+  `);
+
+  const input = element.querySelector("input");
+
+  assert.equal(input?.selectionStart, 8);
+  assert.equal(input?.selectionEnd, 8);
+});
+
+it("should default to the mapTo value if bindTo is not provided", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: 8 });
+      }}
+    >
+      <j-bind props="selectionStart, selectionEnd">
+        <input value="1234567890" />
+      </j-bind>
+    </div>
+  `);
+
+  const input = element.querySelector("input");
+
+  assert.equal(input?.selectionStart, 8);
+  assert.equal(input?.selectionEnd, 8);
+});

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

@@ -0,0 +1,99 @@
+import { attr, element, css, html } from "@joist/element";
+
+// import { JoistValueEvent } from "../events.js";
+import { JToken } from "../token.js";
+import { JoistValueEvent } from "../events.js";
+
+export class JAttrToken extends JToken {
+  mapTo: string;
+
+  constructor(binding: string) {
+    const [mapTo, bindTo] = binding.split(":");
+
+    super(bindTo ?? mapTo);
+
+    this.mapTo = mapTo;
+  }
+}
+
+@element({
+  tagName: "j-bind",
+  // prettier-ignore
+  shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
+})
+export class JoistIfElement extends HTMLElement {
+  @attr()
+  accessor props = "";
+
+  @attr()
+  accessor attrs = "";
+
+  @attr()
+  accessor target = "";
+
+  connectedCallback(): void {
+    const attrBindings = this.#parseBinding(this.attrs);
+    const propBindings = this.#parseBinding(this.props);
+
+    let child = this.firstElementChild;
+
+    if (this.target) {
+      child = this.querySelector(this.target);
+    }
+
+    if (!child) {
+      throw new Error("j-bind must have a child element or defined target");
+    }
+
+    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 propValue of propBindings) {
+      const token = new JAttrToken(propValue);
+
+      this.#dispatch(token, (value) => {
+        Reflect.set(child, token.mapTo, value);
+      });
+    }
+  }
+
+  #parseBinding(binding: string) {
+    return binding
+      .split(",")
+      .map((b) => b.trim())
+      .filter((b) => b);
+  }
+
+  #dispatch(token: JToken, write: (value: unknown) => void) {
+    this.dispatchEvent(
+      new JoistValueEvent(token, ({ newValue, oldValue }) => {
+        if (newValue === oldValue) {
+          return;
+        }
+
+        let valueToWrite = newValue;
+
+        if (typeof newValue === "object" && newValue !== null) {
+          valueToWrite = token.readTokenValueFrom(newValue);
+        }
+
+        if (token.isNegated) {
+          valueToWrite = !valueToWrite;
+        }
+
+        write(valueToWrite);
+      }),
+    );
+  }
+}