@joist/templating 4.2.3-next.10

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2019-2020 Danny Blue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# 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/templating";
+
+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 and attributes. The prefix determines the binding type:
+
+- `$.` prefix: Binds to element properties
+- `$` prefix: Binds to element attributes
+
+```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">
+
+  <!-- Bind to attributes -->
+  <div $class="dynamicClass">
+  <img $src="imageUrl">
+  <input $placeholder="placeholderText">
+</j-props>
+```
+
+### 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 in the iteration
+- `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:
+
+```typescript
+// AsyncState type
+type AsyncState<T = unknown, E = unknown> = {
+  status: "loading" | "error" | "success";
+  data?: T;
+  error?: E;
+};
+```
+
+Example usage with a Promise:
+
+```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>
+```
+
+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
+
+## 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: number;
+  text: string;
+}
+
+@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;
+      }
+    `,
+    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">
+            <j-value class="todo-text" bind="each.value.text"></j-value>
+            <button $.id="each.value.id" $.disabled="!each.value.text">×</button>
+          </j-props>
+        </template>
+      </j-for>
+
+      <j-value bind="todos.length"></j-value> 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: this.#nextId++, text: input.value.trim() }];
+
+    input.value = "";
+  }
+
+  @listen("click", "#todos")
+  onDelete(e: Event) {
+    if (e.target instanceof HTMLButtonElement) {
+      const id = Number(e.target.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

@@ -0,0 +1,69 @@
+{
+  "name": "@joist/templating",
+  "version": "4.2.3-next.10",
+  "type": "module",
+  "main": "./target/lib.js",
+  "module": "./target/lib.js",
+  "exports": {
+    ".": "./target/lib.js",
+    "./*": "./target/lib/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "target"
+  ],
+  "description": "Intelligently apply styles to WebComponents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joist-framework/joist.git"
+  },
+  "keywords": [
+    "TypeScript",
+    "WebComponents",
+    "CSS",
+    "ShadowDOM"
+  ],
+  "author": "deebloo",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/joist-framework/joist/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "wireit",
+    "build": "wireit"
+  },
+  "wireit": {
+    "build": {
+      "command": "tsc --build --pretty",
+      "clean": "if-file-deleted",
+      "files": [
+        "src/**",
+        "tsconfig.json",
+        "../../tsconfig.json"
+      ],
+      "output": [
+        "target/**",
+        "tsconfig.tsbuildinfo"
+      ],
+      "dependencies": [
+        "../observable:build",
+        "../element:build"
+      ]
+    },
+    "test": {
+      "command": "wtr --config wtr.config.mjs",
+      "files": [
+        "vitest.config.js",
+        "target/**"
+      ],
+      "output": [],
+      "dependencies": [
+        "build"
+      ]
+    }
+  }
+}

package/src/lib/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/define.ts

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

package/src/lib/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!");
+});