@joist/element 3.9.1 → 4.0.0-next.10

package/README.md

@@ -1,42 +1,80 @@
 # 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)
+- [Template](#template)
+- [Styles](#styles)
+- [Listeners](#listeners)
+- [Queries](#queries)
+
+## Installation
 
 ```BASH
-npm i @joist/element
+npm i @joist/element@next
+```
+
+## Custom 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 {
+  @attr()
+  accessor greeting = 'Hello World';
+}
 ```
 
-#### Example:
+## Template
 
-```TS
-import { tagName, shadow, css, html, attr, listen, element } from '@joist/element';
+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.
 
-@element
+```ts
+@element({
+  tagName: 'my-element',
+  shadow: [
+    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>
+    `
+  ]
+})
 export class MyElement extends HTMLElement {
-  // define a custom element
-  @tagName static tagName = 'my-element';
-
-  // 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';
+
+  items = ['first', 'second', 'third', 'fourth', 'fifth'];
+
+  #render = template();
+
+  @ready()
+  onReady() {
+    this.#render();
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "3.9.1",
+  "version": "4.0.0-next.10",
   "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,64 +1,138 @@
-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 () => {
-    class MyElement extends HTMLElement {
-      @attr accessor value1 = 100; // no attribute
-      @attr accessor value2 = 0; // number
-      @attr accessor value3 = false; // boolean
-      @attr accessor value4 = 'hello'; // string
-    }
+it('should read and parse the correct values', () => {
+  @element({
+    tagName: 'attr-test-1'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = 100; // no attribute
 
-    customElements.define('attr-test-2', MyElement);
+    @attr()
+    accessor value2 = 0; // number
 
-    const el = await fixture<MyElement>(
-      html`<attr-test-2 value2="2" value3 value4="world"></attr-test-2>`
-    );
+    @attr()
+    accessor value3 = false; // boolean
 
-    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 value4 = 'hello'; // string
+  }
 
-  it('should not write falsy props to attributes', async () => {
-    class MyElement extends HTMLElement {
-      @attr accessor value1 = undefined;
-      @attr accessor value2 = null;
-      @attr accessor value3 = '';
-    }
+  const container = document.createElement('div');
+  container.innerHTML = /*html*/ `
+    <attr-test-1 value2="2" value3 value4="world"></attr-test-1>
+  `;
 
-    customElements.define('attr-test-3', MyElement);
+  document.body.append(container);
 
-    const el = await fixture<MyElement>(html`<attr-test-3></attr-test-3>`);
+  const el = document.querySelector('attr-test-1') as MyElement;
 
-    expect(el.hasAttribute('value1')).to.be.false;
-    expect(el.hasAttribute('value2')).to.be.false;
-    expect(el.hasAttribute('value3')).to.be.false;
-  });
+  expect(el.value1).to.equal(100);
+  expect(el.value2).to.equal(2);
+  expect(el.value3).to.equal(true);
+  expect(el.value4).to.equal('world');
 
-  it('should update attributes when props are changed', async () => {
-    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
-    }
+  container.remove();
+});
+
+it('should not write falsy props to attributes', async () => {
+  @element({
+    tagName: 'attr-test-2'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = undefined;
+
+    @attr()
+    accessor value2 = null;
+
+    @attr()
+    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;
+});
+
+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
 
-    customElements.define('attr-test-4', MyElement);
+    @attr()
+    accessor value4 = false; // boolean
+  }
 
-    const el = await fixture<MyElement>(html`<attr-test-4></attr-test-4>`);
+  const el = new MyElement();
 
-    el.value1 = 'world';
-    el.value2 = 100;
-    el.value3 = false;
-    el.value4 = true;
+  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 = new MyElement();
+
+  document.body.append(el);
+
+  expect([...el.attributes].map((attr) => attr.name)).to.deep.equal([
+    'value1',
+    'value-2',
+    '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 [value] = 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;
-  });
+    new MyElement();
+  }).to.throw('Cannot handle Symbol property without description');
 });

package/src/lib/attr.ts

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

package/src/lib/element.test.ts

@@ -1,24 +1,97 @@
-import { expect, fixture, html } from '@open-wc/testing';
+import { expect } from 'chai';
 
 import { attr } from './attr.js';
 import { element } from './element.js';
-import { tagName } from './tag-name.js';
+import { css, html } from './tags.js';
 
-describe('@element()', () => {
-  it('should write default value to attribute', async () => {
-    @element
-    class MyElement extends HTMLElement {
-      @tagName static tag = 'element-1';
+it('should write default value to attribute', async () => {
+  @element({
+    tagName: 'element-1'
+  })
+  class MyElement extends HTMLElement {
+    @attr()
+    accessor value1 = 'hello'; // no attribute
 
-      @attr accessor value1 = 'hello'; // no attribute
-      @attr accessor value2 = 0; // number
-      @attr accessor value3 = true; // boolean
-    }
+    @attr()
+    accessor value2 = 0; // number
 
-    const el = await fixture<MyElement>(html`<element-1></element-1>`);
+    @attr()
+    accessor value3 = true; // boolean
+  }
 
-    expect(el.getAttribute('value1')).to.equal('hello');
-    expect(el.getAttribute('value2')).to.equal('0');
-    expect(el.getAttribute('value3')).to.equal('');
-  });
+  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('');
+
+  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>`);
 });