@joist/element 4.0.0-next.9 → 4.0.0

package/README.md

@@ -7,7 +7,6 @@ Utilities for building web compnennts. Especially targeted at
 - [Installation](#installation)
 - [Custom Element](#custom-element)
 - [Attributes](#attributes)
-- [Template](#template)
 - [Styles](#styles)
 - [Listeners](#listeners)
 - [Queries](#queries)
@@ -15,7 +14,7 @@ Utilities for building web compnennts. Especially targeted at
 ## Installation
 
 ```BASH
-npm i @joist/element
+npm i @joist/element@next
 ```
 
 ## Custom Element
@@ -43,38 +42,114 @@ export class MyElement extends HTMLElement {
 }
 ```
 
-## Template
+## HTML and CSS
 
-Joist ships with a very simple template library. It is designed to be very small and is only responsible for updating text in different DOM nodes.
+HTML templates can be applied by passing the result of the `html` tag to the shaodw list.
+CSS can be applied by passing the result of the `css` tag to the shadow list. 
+Any new tagged template literal that returns a `ShadowResult` can be used.
 
 ```ts
 @element({
   tagName: 'my-element',
-  shadow: [
+  shadowDom: [
+    css`
+      h1 {
+        color: red;
+      }
+    `,
+    html`<h1>Hello World</h1>`
+  ]
+})
+export class MyElement extends HTMLElement {}
+```
+
+## Listeners
+
+The `@listen` decorator allows you to easy setup event listeners. By default the listener will be attached to the shadow root if it exists or the host element if it doesn't. This can be customized by pass a selector function to the decorator
+
+```ts
+@element({
+  tagName: 'my-element',
+  shadowDom: []
+})
+export class MyElement extends HTMLElement {
+  @listen('eventname')
+  onEventName1() {
+    // all listener to the shadow root
+  }
+
+  @listen('eventname', (host) => host)
+  onEventName2() {
+    // all listener to the host element
+  }
+
+  @listen('eventname', (host) => host.querySelector('button'))
+  onEventName3() {
+    // add listener to a button found in the light dom
+  }
+
+  @listen('eventname', '#test')
+  onEventName4() {
+    // add listener to element with the id of "test" that is found in the shadow dom
+  }
+}
+```
+
+## Query
+
+The `query` function will query for a particular element and allow you to easily patch that element with new properties.
+
+```ts
+@element({
+  tagName: 'my-element',
+  shadowDom: [
     html`
-      <h1 #:bind="greeting" #:hidden="!greeting"></h1>
-
-      <ul>
-        <li #:bind="items.0"></li>
-        <li #:bind="items.1"></li>
-        <li #:bind="items.2"></li>
-        <li #:bind="items.3"></li>
-        <li #:bind="items.4"></li>
-      </ul>
+      <label for="my-input">
+        <slot></slot>
+      </label>
+
+      <input id="my-input" />
     `
   ]
 })
 export class MyElement extends HTMLElement {
-  @attr()
-  accessor greeting = 'Hello World';
+  @observe()
+  value: string;
+
+  #input = query('input');
+
+  @effect()
+  onChange() {
+    const input = this.#input({ value: this.value});
+  }
+}
+```
+
+## QueryAll
+
+The `queryAll` function will get all elements that match the given query. A patching function can be passed to update any or all items in the list
 
-  items = ['first', 'second', 'third', 'fourth', 'fifth'];
+```ts
+@element({
+  tagName: 'my-element',
+  shadowDom: [
+    html`
+      <input id="first" />
+      <input id="second" />
+    `
+  ]
+})
+export class MyElement extends HTMLElement {
+  @observe()
+  value: string;
 
-  #render = template();
+  #inputs = queryAll('input');
 
-  @ready()
-  onReady() {
-    this.#render();
+  @effect()
+  onChange() {
+    this.#input(() => {
+      return { value: this.value }
+    })
   }
 }
 ```

package/package.json

@@ -1,33 +1,22 @@
 {
   "name": "@joist/element",
-  "version": "4.0.0-next.9",
+  "version": "4.0.0",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
   "exports": {
-    ".": {
-      "import": "./target/lib.js"
-    },
-    "./*": {
-      "import": "./target/lib"
-    }
+    ".": "./target/lib.js",
+    "./*": "./target/lib/*",
+    "./package.json": "./package.json"
   },
-  "files": [
-    "src",
-    "target"
-  ],
+  "files": ["src", "target"],
   "sideEffects": false,
   "description": "Intelligently apply styles to WebComponents",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joist-framework/joist.git"
   },
-  "keywords": [
-    "TypeScript",
-    "WebComponents",
-    "CSS",
-    "ShadowDOM"
-  ],
+  "keywords": ["TypeScript", "WebComponents", "CSS", "ShadowDOM"],
   "author": "deebloo",
   "license": "MIT",
   "bugs": {
@@ -44,26 +33,14 @@
     "build": {
       "command": "tsc --build --pretty",
       "clean": "if-file-deleted",
-      "files": [
-        "src/**",
-        "tsconfig.json",
-        "../../tsconfig.json"
-      ],
-      "output": [
-        "target/**",
-        "tsconfig.tsbuildinfo"
-      ]
+      "files": ["src/**", "tsconfig.json", "../../tsconfig.json"],
+      "output": ["target/**", "tsconfig.tsbuildinfo"]
     },
     "test": {
       "command": "wtr --config wtr.config.mjs",
-      "files": [
-        "vitest.config.js",
-        "target/**"
-      ],
+      "files": ["vitest.config.js", "target/**"],
       "output": [],
-      "dependencies": [
-        "build"
-      ]
+      "dependencies": ["build"]
     }
   }
 }

package/src/lib/attr-changed.test.ts

@@ -0,0 +1,34 @@
+import { assert } from "chai";
+
+import { attrChanged } from "./attr-changed.js";
+import { attr } from "./attr.js";
+import { element } from "./element.js";
+
+it("should call specific attrbute callback", () => {
+  let args: string[] = [];
+
+  @element({
+    tagName: "attr-changed-1",
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor test = "hello";
+
+    @attrChanged("test")
+    onTestChanged(oldValue: string, newValue: string) {
+      args = [oldValue, newValue];
+    }
+  }
+
+  const el = new MyElement();
+
+  document.body.append(el);
+
+  assert.deepEqual(args, [null, "hello"]);
+
+  el.setAttribute("test", "world");
+
+  assert.deepEqual(args, ["hello", "world"]);
+
+  el.remove();
+});

package/src/lib/attr-changed.ts

@@ -0,0 +1,15 @@
+import { type AttrChangedCallback, metadataStore } from "./metadata.js";
+
+export function attrChanged(name: string) {
+  return function attrChangedDecorator<This extends HTMLElement>(
+    cb: AttrChangedCallback,
+    ctx: ClassMethodDecoratorContext<This>,
+  ): void {
+    const meta = metadataStore.read(ctx.metadata);
+    const val = meta.attrChanges.get(name) ?? new Set();
+
+    val.add(cb);
+
+    meta.attrChanges.set(name, val);
+  };
+}

package/src/lib/attr.test.ts

@@ -1,11 +1,11 @@
-import { expect } from 'chai';
+import { expect } from "chai";
 
-import { attr } from './attr.js';
-import { element } from './element.js';
+import { attr } from "./attr.js";
+import { element } from "./element.js";
 
-it('should read and parse the correct values', () => {
+it("should read and parse the correct values", () => {
   @element({
-    tagName: 'attr-test-1'
+    tagName: "attr-test-1",
   })
   class MyElement extends HTMLElement {
     @attr()
@@ -18,29 +18,29 @@ it('should read and parse the correct values', () => {
     accessor value3 = false; // boolean
 
     @attr()
-    accessor value4 = 'hello'; // string
+    accessor value4 = "hello"; // string
   }
 
-  const container = document.createElement('div');
+  const container = document.createElement("div");
   container.innerHTML = /*html*/ `
     <attr-test-1 value2="2" value3 value4="world"></attr-test-1>
   `;
 
   document.body.append(container);
 
-  const el = document.querySelector('attr-test-1') as MyElement;
+  const el = document.querySelector("attr-test-1") as MyElement;
 
   expect(el.value1).to.equal(100);
   expect(el.value2).to.equal(2);
   expect(el.value3).to.equal(true);
-  expect(el.value4).to.equal('world');
+  expect(el.value4).to.equal("world");
 
   container.remove();
 });
 
-it('should not write falsy props to attributes', async () => {
+it("should not write falsy props to attributes", async () => {
   @element({
-    tagName: 'attr-test-2'
+    tagName: "attr-test-2",
   })
   class MyElement extends HTMLElement {
     @attr()
@@ -50,23 +50,23 @@ it('should not write falsy props to attributes', async () => {
     accessor value2 = null;
 
     @attr()
-    accessor value3 = '';
+    accessor value3 = "";
   }
 
   const el = new MyElement();
 
-  expect(el.hasAttribute('value1')).to.be.false;
-  expect(el.hasAttribute('value2')).to.be.false;
-  expect(el.hasAttribute('value3')).to.be.false;
+  expect(el.hasAttribute("value1")).to.be.false;
+  expect(el.hasAttribute("value2")).to.be.false;
+  expect(el.hasAttribute("value3")).to.be.false;
 });
 
-it('should update attributes when props are changed', async () => {
+it("should update attributes when props are changed", async () => {
   @element({
-    tagName: 'attr-test-3'
+    tagName: "attr-test-3",
   })
   class MyElement extends HTMLElement {
     @attr()
-    accessor value1 = 'hello'; // no attribute
+    accessor value1 = "hello"; // no attribute
 
     @attr()
     accessor value2 = 0; // number
@@ -80,29 +80,30 @@ it('should update attributes when props are changed', async () => {
 
   const el = new MyElement();
 
-  el.value1 = 'world';
+  el.value1 = "world";
   el.value2 = 100;
   el.value3 = false;
   el.value4 = true;
 
-  expect(el.getAttribute('value1')).to.equal('world');
-  expect(el.getAttribute('value2')).to.equal('100');
-  expect(el.hasAttribute('value3')).to.be.false;
-  expect(el.hasAttribute('value4')).to.be.true;
+  expect(el.getAttribute("value1")).to.equal("world");
+  expect(el.getAttribute("value2")).to.equal("100");
+  expect(el.hasAttribute("value3")).to.be.false;
+  expect(el.hasAttribute("value4")).to.be.true;
 });
 
-it('should normalize attribute names', async () => {
-  const value3 = Symbol('Value from SYMBOL');
+it("should normalize attribute names", async () => {
+  const value2 = "Value 2";
+  const value3 = Symbol("Value from SYMBOL");
 
   @element({
-    tagName: 'attr-test-4'
+    tagName: "attr-test-4",
   })
   class MyElement extends HTMLElement {
     @attr()
-    accessor Value1 = 'hello';
+    accessor Value1 = "hello";
 
     @attr()
-    accessor ['Value 2'] = 0;
+    accessor [value2] = 0;
 
     @attr()
     accessor [value3] = true;
@@ -113,20 +114,20 @@ it('should normalize attribute names', async () => {
   document.body.append(el);
 
   expect([...el.attributes].map((attr) => attr.name)).to.deep.equal([
-    'value1',
-    'value-2',
-    'value-from-symbol'
+    "value1",
+    "value-2",
+    "value-from-symbol",
   ]);
 
   el.remove();
 });
 
-it('should throw an error for symbols with no description', async () => {
+it("should throw an error for symbols with no description", async () => {
   expect(() => {
     const value = Symbol();
 
     @element({
-      tagName: 'attr-test-4'
+      tagName: "attr-test-4",
     })
     class MyElement extends HTMLElement {
       @attr()
@@ -134,5 +135,58 @@ it('should throw an error for symbols with no description', async () => {
     }
 
     new MyElement();
-  }).to.throw('Cannot handle Symbol property without description');
+  }).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",
+  })
+  class MyElement extends HTMLElement {
+    @attr({ reflect: false })
+    accessor value = "foo";
+  }
+
+  const el = new MyElement();
+  el.setAttribute("value", "bar");
+
+  expect(el.value).to.equal("bar");
+});
+
+it("should allow a manually defined attribute name", async () => {
+  @element({
+    tagName: "attr-test-7",
+  })
+  class MyElement extends HTMLElement {
+    @attr({
+      name: "aria-label",
+    })
+    accessor value = "";
+  }
+
+  const el = new MyElement();
+  el.setAttribute("aria-label", "TEST");
+
+  document.body.append(el);
+
+  expect(el.value).to.equal("TEST");
+
+  el.remove();
 });

package/src/lib/attr.ts

@@ -1,57 +1,50 @@
-import { metadataStore } from './metadata.js';
+import { metadataStore } from "./metadata.js";
 
 export interface AttrOpts {
+  name?: string;
   observed?: boolean;
+  reflect?: boolean;
 }
 
 export function attr(opts?: AttrOpts) {
   return function attrDecorator<This extends HTMLElement>(
     { get, set }: ClassAccessorDecoratorTarget<This, unknown>,
-    ctx: ClassAccessorDecoratorContext<This>
+    ctx: ClassAccessorDecoratorContext<This>,
   ): ClassAccessorDecoratorResult<This, any> {
-    const attrName = parseAttrName(ctx.name);
-    const meta = metadataStore.read(ctx.metadata);
+    const attrName = opts?.name ?? parseAttrName(ctx.name);
+    const meta = metadataStore.read<This>(ctx.metadata);
+    const reflect = opts?.reflect ?? true;
 
-    meta.attrs.push({
+    meta.attrs.set(attrName, {
       propName: ctx.name,
-      attrName,
-      observe: opts?.observed ?? true
+      observe: opts?.observed ?? true,
+      reflect,
+      getPropValue: get,
+      setPropValue: set,
     });
 
     return {
       set(value: unknown) {
-        if (value === true) {
-          this.setAttribute(attrName, '');
-        } else if (value === false) {
-          this.removeAttribute(attrName);
-        } else {
-          this.setAttribute(attrName, String(value));
-        }
+        if (reflect) {
+          if (value === true) {
+            if (!this.hasAttribute(attrName)) {
+              this.setAttribute(attrName, "");
+            }
+          } else if (value === false) {
+            if (this.hasAttribute(attrName)) {
+              this.removeAttribute(attrName);
+            }
+          } else {
+            const strValue = String(value);
 
-        set.call(this, value);
-      },
-      get() {
-        const ogValue = get.call(this);
-        const attr = this.getAttribute(attrName);
-
-        if (attr !== null) {
-          // treat as boolean
-          if (attr === '') {
-            return true;
+            if (this.getAttribute(attrName) !== strValue) {
+              this.setAttribute(attrName, strValue);
+            }
           }
-
-          // treat as number
-          if (typeof ogValue === 'number') {
-            return Number(attr);
-          }
-
-          // treat as string
-          return attr;
         }
 
-        // no readable value return original
-        return ogValue;
-      }
+        set.call(this, value);
+      },
     };
   };
 }
@@ -59,15 +52,15 @@ export function attr(opts?: AttrOpts) {
 function parseAttrName(val: string | symbol): string {
   let value: string;
 
-  if (typeof val === 'symbol') {
+  if (typeof val === "symbol") {
     if (val.description) {
       value = val.description;
     } else {
-      throw new Error('Cannot handle Symbol property without description');
+      throw new Error("Cannot handle Symbol property without description");
     }
   } else {
     value = val;
   }
 
-  return value.toLowerCase().replaceAll(' ', '-');
+  return value.toLowerCase().replaceAll(" ", "-");
 }