@joist/element 4.2.1 → 4.2.3-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "4.2.1",
+  "version": "4.2.3-next.0",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -49,6 +49,9 @@
       "output": [
         "target/**",
         "tsconfig.tsbuildinfo"
+      ],
+      "dependencies": [
+        "../observable:build"
       ]
     },
     "test": {

package/src/lib/metadata.ts

@@ -8,7 +8,7 @@ export interface AttrDef {
   setPropValue: (value: unknown) => void;
 }
 
-export type ListenerSelector<T> = (el: T) => Element | ShadowRoot | null;
+export type ListenerSelector<T> = (el: T) => EventTarget | null;
 
 export interface Listener<T> {
   event: string;

package/src/lib/query.ts

@@ -4,7 +4,7 @@ type MathTags = keyof MathMLElementTagNameMap;
 
 type NodeUpdate<T extends Node> = Partial<T> | ((node: T) => Partial<T>);
 
-type QueryResult<T extends Node> = (updates?: NodeUpdate<T>) => T;
+export type QueryResult<T extends Node> = (updates?: NodeUpdate<T>) => T;
 
 export function query<K extends Tags>(
   selectors: K,

package/src/lib/templating/README.md

@@ -0,0 +1,292 @@
+# 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>
+```
+
+### 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>
+```
+
+## 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

package/src/lib/templating/bind.ts

@@ -0,0 +1,40 @@
+import { instanceMetadataStore, observe } from "@joist/observable";
+
+export function bind() {
+  return function bindDecorator<This extends HTMLElement, Value>(
+    base: ClassAccessorDecoratorTarget<This, Value>,
+    ctx: ClassAccessorDecoratorContext<This, Value>,
+  ): ClassAccessorDecoratorResult<This, Value> {
+    const internalObserve = observe()(base, ctx);
+
+    return {
+      init(value) {
+        this.addEventListener("joist::value", (e) => {
+          if (e.token.bindTo === ctx.name) {
+            const instanceMeta = instanceMetadataStore.read<This>(this);
+
+            e.stopPropagation();
+
+            e.update({ oldValue: null, newValue: ctx.access.get(this) });
+
+            instanceMeta.bindings.add((changes) => {
+              const key = ctx.name as keyof This;
+              const res = changes.get(key);
+
+              if (res) {
+                e.update(res);
+              }
+            });
+          }
+        });
+
+        if (internalObserve.init) {
+          return internalObserve.init.call(this, value);
+        }
+
+        return value;
+      },
+      set: internalObserve.set,
+    };
+  };
+}

package/src/lib/templating/define.ts

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

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

@@ -0,0 +1,39 @@
+import "./for.element.js";
+import "./value.element.js";
+
+import { fixtureSync, html } from "@open-wc/testing";
+import { assert } from "chai";
+
+import type { JoistValueEvent } from "../events.js";
+
+it("should iterate over an iterable", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({
+          oldValue: null,
+          newValue: new Set([
+            { id: "123", label: "Hello" },
+            { id: "456", label: "World" },
+          ]),
+        });
+      }}
+    >
+      <ul>
+        <j-for bind="items" key="id">
+          <template>
+            <li>
+              <j-value bind="each.value.label"></j-value>
+            </li>
+          </template>
+        </j-for>
+      </ul>
+    </div>
+  `);
+
+  const listItems = element.querySelectorAll("li");
+
+  assert.equal(listItems.length, 2);
+  assert.equal(listItems[0].textContent?.trim(), "Hello");
+  assert.equal(listItems[1].textContent?.trim(), "World");
+});

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

@@ -0,0 +1,151 @@
+import { attr } from "../../attr.js";
+import { element } from "../../element.js";
+import { query } from "../../query.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-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()
+  accessor each: EachCtx<T> = {
+    value: null,
+    index: null,
+    position: null,
+  };
+
+  @attr()
+  accessor key = "";
+}
+
+@element({
+  tagName: "j-for",
+  // prettier-ignore
+  shadowDom: [css`:host{display:contents;}`, html`<slot></slot>`],
+})
+export class JositForElement extends HTMLElement {
+  @attr()
+  accessor bind = "";
+
+  @attr()
+  accessor key = "";
+
+  #template = query("template", this);
+  #items: Iterable<unknown> = [];
+  #scopes = new Map<unknown, JForScope>();
+
+  connectedCallback(): void {
+    const template = this.#template();
+
+    if (this.firstElementChild !== template) {
+      throw new Error("The first Node in j-for needs to be a template");
+    }
+
+    let currentScope = template.nextElementSibling;
+
+    while (currentScope instanceof JForScope) {
+      this.#scopes.set(currentScope.key, currentScope);
+      currentScope = currentScope.nextElementSibling;
+    }
+
+    const token = new JToken(this.bind);
+
+    this.dispatchEvent(
+      new JoistValueEvent(token, ({ newValue, oldValue }) => {
+        if (newValue !== oldValue) {
+          if (isIterable(newValue)) {
+            this.#items = newValue;
+          } else {
+            this.#items = [];
+          }
+
+          this.updateItems();
+        }
+      }),
+    );
+  }
+
+  updateItems(): void {
+    const template = this.#template();
+    const leftoverScopes = new Map<unknown, JForScope>(this.#scopes);
+
+    let index = 0;
+
+    for (const item of this.#items) {
+      const key = hasProperty(item, this.key) ? item[this.key] : index;
+
+      let scope = leftoverScopes.get(key);
+
+      if (!scope) {
+        scope = new JForScope();
+        scope.append(document.importNode(template.content, true));
+      } else {
+        leftoverScopes.delete(key); // Remove from map to track unused scopes
+      }
+
+      scope.key = String(key);
+      scope.each = {
+        position: index + 1,
+        index: index,
+        value: item,
+      };
+
+      if (!scope.isConnected) {
+        const child = this.children[index + 1]; // skip first child since it should be the template element
+
+        if (child) {
+          child.before(scope);
+        } else {
+          this.append(scope);
+        }
+
+        this.#scopes.set(key, scope);
+      }
+
+      index++;
+    }
+
+    // Remove unused scopes
+    for (const scope of leftoverScopes.values()) {
+      scope.remove();
+    }
+  }
+
+  disconnectedCallback(): void {
+    for (const scope of this.#scopes.values()) {
+      scope.remove();
+    }
+
+    this.#scopes.clear();
+    this.#items = [];
+  }
+}
+
+function isIterable<T = unknown>(obj: any): obj is Iterable<T> {
+  return obj != null && typeof obj[Symbol.iterator] === "function";
+}
+function hasProperty(
+  item: unknown,
+  key: string,
+): item is Record<string, unknown> {
+  return Object.prototype.hasOwnProperty.call(item, key);
+}

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

@@ -0,0 +1,55 @@
+import "./if.element.js";
+
+import { fixtureSync, html } from "@open-wc/testing";
+import { assert } from "chai";
+
+import type { JoistValueEvent } from "../events.js";
+
+it("should render content when the bind value is truthy", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: true });
+      }}
+    >
+      <j-if bind="test">
+        <template>Visible Content</template>
+      </j-if>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "Visible Content");
+});
+
+it("should not render content when the bind value is falsy", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: true });
+        e.update({ oldValue: null, newValue: false });
+      }}
+    >
+      <j-if bind="test">
+        <template>Visible Content</template>
+      </j-if>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "");
+});
+
+it("should handle negated tokens correctly", () => {
+  const element = fixtureSync(html`
+    <div
+      @joist::value=${(e: JoistValueEvent) => {
+        e.update({ oldValue: null, newValue: false });
+      }}
+    >
+      <j-if bind="!test">
+        <template>Visible Content</template>
+      </j-if>
+    </div>
+  `);
+
+  assert.equal(element.textContent?.trim(), "Visible Content");
+});

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

@@ -0,0 +1,67 @@
+import { attr } from "../../attr.js";
+import { element } from "../../element.js";
+import { type QueryResult, query } from "../../query.js";
+import { css, html } from "../../tags.js";
+
+import { JoistValueEvent } from "../events.js";
+import { JToken } from "../token.js";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "j-if": JoistIfElement;
+  }
+}
+
+@element({
+  tagName: "j-if",
+  // prettier-ignore
+  shadowDom: [css`:host{display: contents;}`, html`<slot></slot>`],
+})
+export class JoistIfElement extends HTMLElement {
+  @attr()
+  accessor bind = "";
+
+  childTemplate: QueryResult<HTMLTemplateElement> = query("template", this);
+
+  connectedCallback(): void {
+    // make sure there are no other nodes after the template
+    this.#clean();
+
+    const token = new JToken(this.bind);
+
+    this.dispatchEvent(
+      new JoistValueEvent(token, ({ newValue, oldValue }) => {
+        if (newValue !== oldValue) {
+          if (typeof newValue === "object" && newValue !== null) {
+            this.apply(token.readTokenValueFrom(newValue), token.isNegated);
+          } else {
+            this.apply(newValue, token.isNegated);
+          }
+        }
+      }),
+    );
+  }
+
+  apply(value: unknown, isNegative: boolean): void {
+    const childTemplate = this.childTemplate();
+
+    if (isNegative ? !value : value) {
+      // only clone the template if it is not already in the DOM
+      if (childTemplate.nextSibling === null) {
+        const res = document.importNode(childTemplate.content, true);
+
+        this.appendChild(res);
+      }
+    } else {
+      this.#clean();
+    }
+  }
+
+  #clean() {
+    const childTemplate = this.childTemplate();
+
+    while (childTemplate.nextSibling) {
+      childTemplate.nextSibling.remove();
+    }
+  }
+}