@joist/element 4.0.0-next.2 → 4.0.0-next.20

package/README.md

@@ -1,41 +1,126 @@
 # Element
 
-Create a shadow root and apply styles and html as defined
+Utilities for building web compnennts. Especially targeted at
 
-#### Installation:
+## Table of Contents
+
+- [Installation](#installation)
+- [Custom Element](#custom-element)
+- [Attributes](#attributes)
+- [Styles](#styles)
+- [Listeners](#listeners)
+- [Queries](#queries)
+
+## Installation
 
 ```BASH
-npm i @joist/element
+npm i @joist/element@next
 ```
 
-#### Example:
+## Custom Element
 
-```TS
-import { tagName, shadow, css, html, attr, listen, element } from '@joist/element';
+To define a custom element decorate your custom element class and add a tagName
 
+```ts
+@element({
+  tagName: 'my-element'
+})
+export class MyElement extends HTMLElement {}
+```
+
+## Attributes
+
+Attributes can be managed using the `@attr` decorator. This decorator will read attribute values and and write properties back to attributes;
+
+```ts
 @element({
   tagName: 'my-element'
 })
 export class MyElement extends HTMLElement {
-  // apply styles to shadow dom
-  @shadow styles = css`
-    :host {
-      display: block;
-      color: red;
-    }
-  `;
-
-  // apply html to shadow dom
-  @shadow template = html`
-    <slot></slot>
-  `;
-
-  // define attributes
-  @attr() accessor value = 0;
-
-  // listen for events
-  @listen('click') onClick() {
-    console.log('clicked!')
+  @attr()
+  accessor greeting = 'Hello World';
+}
+```
+
+## HTML and CSS
+
+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.
+
+```ts
+@element({
+  tagName: 'my-element',
+  shadow: [
+    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',
+  shadow: []
+})
+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
+  }
+}
+```
+
+## Queries
+
+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',
+  shadow: [
+    html`
+      <label for="my-input">
+        <slot></slot>
+      </label>
+
+      <input id="my-input" />
+    `
+  ]
+})
+export class MyElement extends HTMLElement {
+  @observe()
+  value: string;
+
+  #input = query('input');
+
+  @effect()
+  onChange() {
+    const input = this.#input();
+    input.value = this.value;
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "4.0.0-next.2",
+  "version": "4.0.0-next.20",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -9,7 +9,7 @@
       "import": "./target/lib.js"
     },
     "./*": {
-      "import": "./target/lib/*.js"
+      "import": "./target/lib"
     }
   },
   "files": [
@@ -20,7 +20,7 @@
   "description": "Intelligently apply styles to WebComponents",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/deebloo/joist.git"
+    "url": "git+https://github.com/joist-framework/joist.git"
   },
   "keywords": [
     "TypeScript",
@@ -31,7 +31,7 @@
   "author": "deebloo",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/deebloo/joist/issues"
+    "url": "https://github.com/joist-framework/joist/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -57,6 +57,7 @@
     "test": {
       "command": "wtr --config wtr.config.mjs",
       "files": [
+        "vitest.config.js",
         "target/**"
       ],
       "output": [],

package/src/lib/attr.test.ts

@@ -1,113 +1,170 @@
-import { expect, fixture, html } from '@open-wc/testing';
+import { expect } from 'chai';
 
 import { attr } from './attr.js';
 import { element } from './element.js';
 
-describe('@attr()', () => {
-  it('should read and parse the correct values', async () => {
-    @element({
-      tagName: 'attr-test-1'
-    })
-    class MyElement extends HTMLElement {
-      @attr()
-      accessor value1 = 100; // no attribute
+it('should read and parse the correct values', () => {
+  @element({
+    tagName: 'attr-test-1'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = 100; // no attribute
 
-      @attr()
-      accessor value2 = 0; // number
+    @attr()
+    accessor value2 = 0; // number
 
-      @attr()
-      accessor value3 = false; // boolean
+    @attr()
+    accessor value3 = false; // boolean
 
-      @attr()
-      accessor value4 = 'hello'; // string
-    }
+    @attr()
+    accessor value4 = 'hello'; // string
+  }
 
-    const el = await fixture<MyElement>(
-      html`<attr-test-1 value2="2" value3 value4="world"></attr-test-1>`
-    );
+  const container = document.createElement('div');
+  container.innerHTML = /*html*/ `
+    <attr-test-1 value2="2" value3 value4="world"></attr-test-1>
+  `;
 
-    expect(el.value1).to.equal(100);
-    expect(el.value2).to.equal(2);
-    expect(el.value3).to.equal(true);
-    expect(el.value4).to.equal('world');
-  });
+  document.body.append(container);
 
-  it('should not write falsy props to attributes', async () => {
-    @element({
-      tagName: 'attr-test-2'
-    })
-    class MyElement extends HTMLElement {
-      @attr()
-      accessor value1 = undefined;
+  const el = document.querySelector('attr-test-1') as MyElement;
 
-      @attr()
-      accessor value2 = null;
+  expect(el.value1).to.equal(100);
+  expect(el.value2).to.equal(2);
+  expect(el.value3).to.equal(true);
+  expect(el.value4).to.equal('world');
 
-      @attr()
-      accessor value3 = '';
-    }
+  container.remove();
+});
 
-    const el = await fixture<MyElement>(html`<attr-test-2></attr-test-2>`);
+it('should not write falsy props to attributes', async () => {
+  @element({
+    tagName: 'attr-test-2'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = undefined;
 
-    expect(el.hasAttribute('value1')).to.be.false;
-    expect(el.hasAttribute('value2')).to.be.false;
-    expect(el.hasAttribute('value3')).to.be.false;
-  });
+    @attr()
+    accessor value2 = null;
 
-  it('should update attributes when props are changed', async () => {
-    @element({
-      tagName: 'attr-test-3'
-    })
-    class MyElement extends HTMLElement {
-      @attr()
-      accessor value1 = 'hello'; // no attribute
+    @attr()
+    accessor value3 = '';
+  }
 
-      @attr()
-      accessor value2 = 0; // number
+  const el = new MyElement();
 
-      @attr()
-      accessor value3 = true; // boolean
+  expect(el.hasAttribute('value1')).to.be.false;
+  expect(el.hasAttribute('value2')).to.be.false;
+  expect(el.hasAttribute('value3')).to.be.false;
+});
 
-      @attr()
-      accessor value4 = false; // boolean
-    }
+it('should update attributes when props are changed', async () => {
+  @element({
+    tagName: 'attr-test-3'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = 'hello'; // no attribute
+
+    @attr()
+    accessor value2 = 0; // number
+
+    @attr()
+    accessor value3 = true; // boolean
+
+    @attr()
+    accessor value4 = false; // boolean
+  }
+
+  const el = new MyElement();
+
+  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;
+});
+
+it('should normalize attribute names', async () => {
+  const value3 = Symbol('Value from SYMBOL');
+
+  @element({
+    tagName: 'attr-test-4'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor Value1 = 'hello';
+
+    @attr()
+    accessor ['Value 2'] = 0;
+
+    @attr()
+    accessor [value3] = true;
+  }
 
-    const el = await fixture<MyElement>(html`<attr-test-3></attr-test-3>`);
+  const el = new MyElement();
 
-    el.value1 = 'world';
-    el.value2 = 100;
-    el.value3 = false;
-    el.value4 = true;
+  document.body.append(el);
 
-    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.attributes].map((attr) => attr.name)).to.deep.equal([
+    'value1',
+    'value-2',
+    'value-from-symbol'
+  ]);
 
-  it('should normalize attribute names', async () => {
-    const value3 = Symbol('Value from SYMBOL');
+  el.remove();
+});
+
+it('should throw an error for symbols with no description', async () => {
+  expect(() => {
+    const value = Symbol();
 
     @element({
       tagName: 'attr-test-4'
     })
     class MyElement extends HTMLElement {
       @attr()
-      accessor Value1 = 'hello';
+      accessor [value] = true;
+    }
 
-      @attr()
-      accessor ['Value 2'] = 0;
+    new MyElement();
+  }).to.throw('Cannot handle Symbol property without description');
+});
 
-      @attr()
-      accessor [value3] = true;
-    }
+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 = await fixture<MyElement>(html`<attr-test-4></attr-test-4>`);
+  const el = new MyElement();
+  el.setAttribute('value', 'bar');
 
-    expect([...el.attributes].map((attr) => attr.name)).to.deep.equal([
-      'value1',
-      'value-2',
-      'value-from-symbol'
-    ]);
-  });
+  expect(el.value).to.equal('bar');
 });

package/src/lib/attr.ts

@@ -1,48 +1,40 @@
 import { metadataStore } from './metadata.js';
 
-export function attr() {
-  return <This extends HTMLElement>(
+export interface AttrOpts {
+  observed?: boolean;
+  reflect?: boolean;
+}
+
+export function attr(opts?: AttrOpts) {
+  return function attrDecorator<This extends HTMLElement>(
     { get, set }: ClassAccessorDecoratorTarget<This, unknown>,
     ctx: ClassAccessorDecoratorContext<This>
-  ): ClassAccessorDecoratorResult<This, any> => {
+  ): ClassAccessorDecoratorResult<This, any> {
     const attrName = parseAttrName(ctx.name);
     const meta = metadataStore.read(ctx.metadata);
+    const reflect = opts?.reflect ?? true;
 
-    meta.attrs.push({ propName: ctx.name, attrName });
+    meta.attrs.set(attrName, {
+      propName: ctx.name,
+      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));
-        }
-
-        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;
-          }
-
-          // treat as number
-          if (typeof ogValue === 'number') {
-            return Number(attr);
+        if (reflect) {
+          if (value === true) {
+            this.setAttribute(attrName, '');
+          } else if (value === false) {
+            this.removeAttribute(attrName);
+          } else {
+            this.setAttribute(attrName, String(value));
           }
-
-          // treat as string
-          return attr;
         }
 
-        // no readable value return original
-        return ogValue;
+        set.call(this, value);
       }
     };
   };

package/src/lib/element.test.ts

@@ -1,50 +1,101 @@
-import { expect, fixture, html } from '@open-wc/testing';
+import { expect } from 'chai';
 
 import { attr } from './attr.js';
 import { element } from './element.js';
+import { css, html } from './tags.js';
 
-describe('@element()', () => {
-  it('should write default value to attribute', async () => {
-    @element({
-      tagName: 'element-1'
-    })
-    class MyElement extends HTMLElement {
-      @attr()
-      accessor value1 = 'hello'; // no attribute
-
-      @attr()
-      accessor value2 = 0; // number
-
-      @attr()
-      accessor value3 = true; // boolean
-    }
-
-    const el = await fixture<MyElement>(html`<element-1></element-1>`);
-
-    expect(el.getAttribute('value1')).to.equal('hello');
-    expect(el.getAttribute('value2')).to.equal('0');
-    expect(el.getAttribute('value3')).to.equal('');
-  });
-
-  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
-    }
-
-    expect(Reflect.get(MyElement, 'observedAttributes')).to.deep.equal([
-      'value1',
-      'value2',
-      'value3'
-    ]);
-  });
+it('should write default value to attribute', async () => {
+  @element({
+    tagName: 'element-1'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = 'hello'; // no attribute
+
+    @attr()
+    accessor value2 = 0; // number
+
+    @attr()
+    accessor value3 = true; // boolean
+
+    @attr({ reflect: false })
+    accessor value4 = 'foo';
+  }
+
+  const el = new MyElement();
+
+  document.body.append(el);
+
+  expect(el.getAttribute('value1')).to.equal('hello');
+  expect(el.getAttribute('value2')).to.equal('0');
+  expect(el.getAttribute('value3')).to.equal('');
+  expect(el.getAttribute('value4')).to.equal(null);
+
+  el.remove();
+});
+
+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({
+    tagName: 'element-3',
+    shadow: []
+  })
+  class MyElement extends HTMLElement {}
+
+  const el = new MyElement();
+
+  expect(el.shadowRoot).to.be.instanceOf(ShadowRoot);
+});
+
+it('should apply html and css', async () => {
+  @element({
+    tagName: 'element-4',
+    shadow: [
+      css`
+        :host {
+          display: contents;
+        }
+      `,
+      html`<slot></slot>`,
+      {
+        apply(el) {
+          const div = document.createElement('div');
+          div.innerHTML = 'hello world';
+
+          el.append(div);
+        }
+      }
+    ]
+  })
+  class MyElement extends HTMLElement {}
+
+  const el = new MyElement();
+
+  expect(el.shadowRoot!.adoptedStyleSheets.length).to.equal(1);
+  expect(el.shadowRoot!.innerHTML).to.equal(`<slot></slot>`);
+  expect(el.innerHTML).to.equal(`<div>hello world</div>`);
 });