@joist/element 4.2.3-next.13 → 4.2.3-next.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "4.2.3-next.13",
+  "version": "4.2.3-next.3",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -14,7 +14,7 @@
     "target"
   ],
   "sideEffects": [
-    "**/define.js"
+    "./target/lib/templating/define.js"
   ],
   "description": "Intelligently apply styles to WebComponents",
   "repository": {
@@ -51,6 +51,9 @@
       "output": [
         "target/**",
         "tsconfig.tsbuildinfo"
+      ],
+      "dependencies": [
+        "../observable:build"
       ]
     },
     "test": {

package/src/lib/attr.test.ts

@@ -138,6 +138,23 @@ it("should throw an error for symbols with no description", async () => {
   }).to.throw("Cannot handle Symbol property without description");
 });
 
+it("should not reflect property to attribute", async () => {
+  @element({
+    tagName: "attr-test-5",
+  })
+  class MyElement extends HTMLElement {
+    @attr({ reflect: false })
+    accessor value = "foo";
+  }
+
+  const el = new MyElement();
+  el.value = "bar";
+
+  expect(el.value).to.equal("bar");
+
+  expect(el.hasAttribute("value")).to.be.false;
+});
+
 it("non reflective attributes should still read new attribute values", async () => {
   @element({
     tagName: "attr-test-6",
@@ -173,39 +190,3 @@ it("should allow a manually defined attribute name", async () => {
 
   el.remove();
 });
-
-it("should update property when attribute changes", async () => {
-  @element({
-    tagName: "attr-test-8",
-  })
-  class MyElement extends HTMLElement {
-    @attr()
-    accessor value = "foo";
-
-    @attr()
-    accessor count = 0;
-
-    @attr()
-    accessor enabled = false;
-  }
-
-  const el = new MyElement();
-  document.body.append(el);
-
-  // Test string property
-  el.setAttribute("value", "bar");
-  expect(el.value).to.equal("bar");
-
-  // Test number property
-  el.setAttribute("count", "42");
-  expect(el.count).to.equal(42);
-
-  // Test boolean property
-  el.setAttribute("enabled", "");
-  expect(el.enabled).to.equal(true);
-
-  el.removeAttribute("enabled");
-  expect(el.enabled).to.equal(false);
-
-  el.remove();
-});

package/src/lib/element.test.ts

@@ -34,39 +34,31 @@ it("should write default value to attribute", async () => {
   el.remove();
 });
 
-it("should register attributes", async () => {
-  const observedAttrs: string[] = [];
-
-  @element({
-    tagName: "element-2",
-  })
-  class MyElement extends HTMLElement {
-    @attr()
-    accessor value1 = "hello";
-
-    @attr()
-    accessor value2 = 0;
-
-    @attr()
-    accessor value3 = true;
-
-    @attr({ observed: false })
-    accessor value4 = "hello world";
-
-    attributeChangedCallback(name: string) {
-      observedAttrs.push(name);
-    }
-  }
-
-  const el = new MyElement();
-
-  el.setAttribute("value1", "foo");
-  el.setAttribute("value2", "1");
-  el.setAttribute("value3", "false");
-  el.setAttribute("value4", "bar");
-
-  expect(observedAttrs).to.deep.equal(["value1", "value2", "value3"]);
-});
+// TODO: Figure out test
+// it('should register attributes', async () => {
+//   @element({
+//     tagName: 'element-2'
+//   })
+//   class MyElement extends HTMLElement {
+//     @attr()
+//     accessor value1 = 'hello'; // no attribute
+
+//     @attr()
+//     accessor value2 = 0; // number
+
+//     @attr()
+//     accessor value3 = true; // boolean
+
+//     @attr({ observed: false }) // should be filtered out
+//     accessor value4 = 'hello world';
+//   }
+
+//   expect(Reflect.get(MyElement, 'observedAttributes')).to.deep.equal([
+//     'value1',
+//     'value2',
+//     'value3'
+//   ]);
+// });
 
 it("should attach shadow root when the shadow property exists", async () => {
   @element({

package/src/lib/element.ts

@@ -47,7 +47,11 @@ export function element<T extends ElementConstructor>(opts?: ElementOpts) {
           }
         }
 
-        attributeChangedCallback(name: string, oldValue: string, newValue: string) {
+        attributeChangedCallback(
+          name: string,
+          oldValue: string,
+          newValue: string,
+        ) {
           const attr = meta.attrs.get(name);
           const cbs = meta.attrChanges.get(name);
 
@@ -55,9 +59,9 @@ export function element<T extends ElementConstructor>(opts?: ElementOpts) {
             if (oldValue !== newValue) {
               const ogValue = attr.getPropValue.call(this);
 
-              if (typeof ogValue === "boolean") {
+              if (newValue === "") {
                 // treat as boolean
-                attr.setPropValue.call(this, newValue !== null);
+                attr.setPropValue.call(this, true);
               } else if (typeof ogValue === "number") {
                 // treat as number
                 attr.setPropValue.call(this, Number(newValue));
@@ -82,13 +86,13 @@ export function element<T extends ElementConstructor>(opts?: ElementOpts) {
         }
 
         connectedCallback() {
-          if (!this.#abortController) {
-            this.#abortController = new AbortController();
-
+          if (this.isConnected) {
             for (const { event, cb, selector } of meta.listeners) {
               const root = selector(this);
 
               if (root) {
+                this.#abortController = new AbortController();
+
                 root.addEventListener(event, cb.bind(this), {
                   signal: this.#abortController.signal,
                 });
@@ -96,12 +100,12 @@ export function element<T extends ElementConstructor>(opts?: ElementOpts) {
                 throw new Error(`could not add listener to ${root}`);
               }
             }
-          }
 
-          reflectAttributeValues(this, meta.attrs);
+            reflectAttributeValues(this, meta.attrs);
 
-          if (super.connectedCallback) {
-            super.connectedCallback();
+            if (super.connectedCallback) {
+              super.connectedCallback();
+            }
           }
         }
 
@@ -122,7 +126,10 @@ export function element<T extends ElementConstructor>(opts?: ElementOpts) {
   };
 }
 
-function reflectAttributeValues<T extends HTMLElement>(el: T, attrs: AttrMetadata) {
+function reflectAttributeValues<T extends HTMLElement>(
+  el: T,
+  attrs: AttrMetadata,
+) {
   for (const [attrName, { getPropValue, reflect }] of attrs) {
     if (reflect) {
       const value = getPropValue.call(el);

package/src/lib/listen.test.ts

@@ -102,78 +102,3 @@ describe("@listen()", () => {
     el.remove();
   });
 });
-
-it("should remove event listeners during cleanup", () => {
-  let clickCount = 0;
-
-  @element({
-    tagName: "listener-cleanup",
-    shadowDom: [],
-  })
-  class MyElement extends HTMLElement {
-    @listen("click")
-    onClick1() {
-      clickCount++;
-    }
-
-    @listen("click")
-    onClick2() {
-      clickCount++;
-    }
-  }
-
-  const el = new MyElement();
-  document.body.append(el);
-
-  // First click should increment counter
-  el.shadowRoot?.dispatchEvent(new Event("click"));
-  assert.equal(clickCount, 2);
-
-  // Remove element which should cleanup listeners
-  el.remove();
-
-  // Second click after removal should not increment counter
-  el.shadowRoot?.dispatchEvent(new Event("click"));
-  assert.equal(clickCount, 2);
-});
-
-it("should not add event listeners multiple times when element is moved", () => {
-  let clickCount = 0;
-
-  @element({
-    tagName: "listener-move",
-    shadowDom: [],
-  })
-  class MyElement extends HTMLElement {
-    @listen("click")
-    onClick() {
-      clickCount++;
-    }
-  }
-
-  const el = new MyElement();
-  const container1 = document.createElement("div");
-  const container2 = document.createElement("div");
-
-  document.body.append(container1);
-  document.body.append(container2);
-
-  // Add to first container
-  container1.append(el);
-
-  // Click should increment once
-  el.shadowRoot?.dispatchEvent(new Event("click"));
-  assert.equal(clickCount, 1);
-
-  // Move to second container
-  container2.append(el);
-
-  // Click should still only increment once
-  el.shadowRoot?.dispatchEvent(new Event("click"));
-  assert.equal(clickCount, 2);
-
-  // Cleanup
-  el.remove();
-  container1.remove();
-  container2.remove();
-});

package/src/lib/templating/README.md

@@ -0,0 +1,406 @@
+# Joist Templating System
+
+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.
+
+## Core Components
+
+### Bind Decorator (`bind.ts`)
+
+The `bind` decorator enables reactive data binding for web component properties. It integrates with Joist's observable system to automatically track and propagate changes.
+
+```typescript
+import { bind } from '@joist/element/templating.js';
+
+class MyElement extends HTMLElement {
+  @bind()
+  myProperty: string;
+}
+```
+
+The decorator:
+- Creates a two-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
+
+### Token System (`token.ts`)
+
+The `JToken` class handles parsing and evaluation of binding expressions. It supports:
+
+- Simple property bindings: `propertyName`
+- Nested property access: `user.profile.name`
+- Negation operator: `!isVisible`
+
+Example usage:
+```typescript
+const token = new JToken('user.name');
+const value = token.readTokenValueFrom(context);
+```
+
+### Events (`events.ts`)
+
+The system uses custom events for value propagation:
+
+- `JoistValueEvent`: A custom event that handles value updates in the templating system
+- Bubbles through the DOM tree
+- Carries both the token and update mechanism
+
+## Built-in Template Elements
+
+Joist provides several built-in template elements for common templating needs:
+
+### Conditional Rendering (`j-if`)
+
+Conditionally renders content based on a boolean expression:
+
+```html
+<j-if bind="isVisible">
+  <template>
+    <div>This content is only shown when isVisible is true</div>
+  </template>
+</j-if>
+
+<!-- With negation -->
+<j-if bind="!isHidden">
+  <template>
+    <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:
+
+```html
+<j-props>
+  <!-- Bind to boolean properties -->
+  <input type="checkbox" $.checked="isComplete">
+  
+  <!-- Bind to form input values -->
+  <input type="text" $.value="userName">
+  
+  <!-- Bind to custom element properties -->
+  <my-element $.data="complexObject">
+</j-props>
+```
+
+Note the `$.` prefix for property bindings. This distinguishes property bindings from attribute bindings.
+
+Common use cases:
+- Form input states (`checked`, `value`, `disabled`)
+- Boolean properties that don't work well as attributes
+- Complex objects that need to be passed as properties
+- Custom element properties
+
+### List Rendering (`j-for`)
+
+Renders lists of items with support for keyed updates:
+
+```html
+<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>
+  </template>
+</j-for>
+```
+
+The `j-for` element provides context variables:
+- `each.value`: The current item
+- `each.index`: Zero-based index
+- `each.position`: One-based position
+
+### 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:
+
+```html
+<j-async bind="userPromise">
+  <template loading>Loading user data...</template>
+  <template success>
+    <div>Welcome, <j-value bind="state.data.name"></j-value>!</div>
+  </template>
+  <template error>
+    <div>Error loading user data: <j-value bind="state.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:
+
+```typescript
+import { bind } from '@joist/element/templating.js';
+import { element, html, css, listen, query } from '@joist/element';
+
+interface Todo {
+  id: number;
+  text: string;
+  completed: boolean;
+}
+
+@element({
+  tagName: 'todo-list',
+  shadowDom: [
+    css`
+      :host {
+        display: block;
+        max-width: 600px;
+        margin: 2rem auto;
+      }
+      .form {
+        display: flex;
+        gap: 1rem;
+      }
+      .todo-item {
+        display: flex;
+        gap: 0.5rem;
+        margin: 0.5rem 0;
+      }
+      .todo-text {
+        flex: 1;
+      }
+      [data-completed="true"] .todo-text {
+        text-decoration: line-through;
+        opacity: 0.6;
+      }
+    `,
+    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>
+          <j-props class="todo-item" $.dataset.completed="each.value.completed">
+            <j-props>
+              <input type="checkbox" $.id="each.value.id" $.checked="each.value.completed">
+              <j-value class="todo-text" bind="each.value.text"></j-value>
+              <button $.id="each.value.id" $.disabled="!each.value.text">×</button>
+            </j-props>
+          </j-props>
+        </template>
+      </j-for>
+
+      <j-value bind="stats.remaining"></j-value> remaining
+    `
+  ]
+})
+export class TodoList extends HTMLElement {
+  @bind()
+  accessor todos: Todo[] = [];
+
+  @bind()
+  accessor stats = {
+    remaining: 0,
+    completed: 0
+  };
+
+  #nextId = 1;
+  #input = query('input');
+
+  #updateStats() {
+    this.stats = {
+      completed: this.todos.filter(todo => todo.completed).length,
+      remaining: this.todos.length - this.stats.completed
+    };
+  }
+
+  @listen('submit', 'form')
+  onSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    const input = this.#input();
+    const text = input.value.trim();
+    
+    if (text) {
+      this.todos = [
+        ...this.todos,
+        { id: this.#nextId++, text, completed: false }
+      ];
+      
+      input.value = '';
+      
+      this.#updateStats();
+    }
+  }
+
+  @listen('change', '#todos')
+  onToggle(e: Event) {
+    if(e.target instanceof HTMLInputElement) {
+      const id = Number(e.target.id);
+      
+      this.todos = this.todos.map(todo => {
+        if (todo.id === id) {
+          return { ...todo, completed: checkbox.checked };
+        }
+      
+        return todo;
+      });
+      
+      this.#updateStats();
+    }
+  }
+
+  @listen('click', '#todos')
+  onDelete(e: Event) {
+    if(e.target instanceof HTMLElement) {
+      const id = Number(e.target.id);
+
+      this.todos = this.todos.filter(todo => todo.id !== id);
+        
+      this.#updateStats();
+    }
+  }
+}
+```
+
+## 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
+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