@joist/element 4.0.0-next.1 → 4.0.0-next.3

package/README.md

@@ -11,31 +11,28 @@ npm i @joist/element
 #### Example:
 
 ```TS
-import { tagName, shadow, css, html, attr, listen, element } from '@joist/element';
-
-@element
+import { tagName, css, html, attr, listen, element } from '@joist/element';
+
+@element({
+  tagName: 'my-element',
+  shadow: [
+    css`
+      :host {
+        display: block;
+        color: red;
+      }
+    `,
+    html`
+      <slot></slot>
+    `
+  ]
+})
 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;
+  @attr()
+  accessor value = 0;
 
-  // listen for events
-  @listen('click') onClick() {
+  @listen('click')
+  onClick() {
     console.log('clicked!')
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "4.0.0-next.1",
+  "version": "4.0.0-next.3",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",

package/src/lib/attr.test.ts

@@ -1,20 +1,29 @@
 import { expect, fixture, html } from '@open-wc/testing';
 
 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
-      @attr accessor value2 = 0; // number
-      @attr accessor value3 = false; // boolean
-      @attr accessor value4 = 'hello'; // string
-    }
+      @attr()
+      accessor value1 = 100; // no attribute
+
+      @attr()
+      accessor value2 = 0; // number
 
-    customElements.define('attr-test-2', MyElement);
+      @attr()
+      accessor value3 = false; // boolean
+
+      @attr()
+      accessor value4 = 'hello'; // string
+    }
 
     const el = await fixture<MyElement>(
-      html`<attr-test-2 value2="2" value3 value4="world"></attr-test-2>`
+      html`<attr-test-1 value2="2" value3 value4="world"></attr-test-1>`
     );
 
     expect(el.value1).to.equal(100);
@@ -24,15 +33,21 @@ describe('@attr()', () => {
   });
 
   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 = '';
-    }
+      @attr()
+      accessor value1 = undefined;
 
-    customElements.define('attr-test-3', MyElement);
+      @attr()
+      accessor value2 = null;
 
-    const el = await fixture<MyElement>(html`<attr-test-3></attr-test-3>`);
+      @attr()
+      accessor value3 = '';
+    }
+
+    const el = await fixture<MyElement>(html`<attr-test-2></attr-test-2>`);
 
     expect(el.hasAttribute('value1')).to.be.false;
     expect(el.hasAttribute('value2')).to.be.false;
@@ -40,16 +55,24 @@ describe('@attr()', () => {
   });
 
   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
-    }
+      @attr()
+      accessor value1 = 'hello'; // no attribute
 
-    customElements.define('attr-test-4', MyElement);
+      @attr()
+      accessor value2 = 0; // number
 
-    const el = await fixture<MyElement>(html`<attr-test-4></attr-test-4>`);
+      @attr()
+      accessor value3 = true; // boolean
+
+      @attr()
+      accessor value4 = false; // boolean
+    }
+
+    const el = await fixture<MyElement>(html`<attr-test-3></attr-test-3>`);
 
     el.value1 = 'world';
     el.value2 = 100;
@@ -61,4 +84,46 @@ describe('@attr()', () => {
     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-4></attr-test-4>`);
+
+    expect([...el.attributes].map((attr) => attr.name)).to.deep.equal([
+      'value1',
+      'value-2',
+      'value-from-symbol'
+    ]);
+  });
+
+  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;
+      }
+
+      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 {
+  observe?: 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?.observe ?? 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,86 @@
-import { expect, fixture, html } from '@open-wc/testing';
+import { expect, fixture, html as litHtml } from '@open-wc/testing';
 
 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
+    @element({
+      tagName: 'element-1'
+    })
     class MyElement extends HTMLElement {
-      @tagName static tag = 'element-1';
+      @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
+
+      @attr()
+      accessor value3 = true; // boolean
     }
 
-    const el = await fixture<MyElement>(html`<element-1></element-1>`);
+    const el = await fixture<MyElement>(litHtml`<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
+
+      @attr({ observe: 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>`
+      ]
+    })
+    class MyElement extends HTMLElement {}
+
+    const el = new MyElement();
+
+    expect(el.shadowRoot!.adoptedStyleSheets.length).to.equal(1);
+    expect(el.shadowRoot!.innerHTML).to.equal(`<slot></slot>`);
+  });
 });

package/src/lib/element.ts

@@ -1,55 +1,77 @@
-import { metadataStore } from './metadata.js';
+import { AttrDef, metadataStore } from './metadata.js';
+import { ShadowResult } from './result.js';
 
-export function element<Target extends CustomElementConstructor>(
-  Base: Target,
-  ctx: ClassDecoratorContext<Target>
-) {
-  const meta = metadataStore.read(ctx.metadata);
+export interface ElementOpts<T> {
+  tagName?: string;
+  shadow?: Array<ShadowResult | ((el: T) => void)>;
+}
 
-  ctx.addInitializer(function (this: Target) {
-    if (meta.tagName) {
-      const val = meta.tagName(this);
+export function element<
+  Target extends CustomElementConstructor,
+  Instance extends InstanceType<Target>
+>(opts?: ElementOpts<Instance>) {
+  return function elementDecorator(Base: Target, ctx: ClassDecoratorContext<Target>) {
+    const meta = metadataStore.read(ctx.metadata);
 
-      if (!customElements.get(val)) {
-        customElements.define(val, this);
+    ctx.addInitializer(function (this: Target) {
+      if (opts?.tagName) {
+        if (!customElements.get(opts.tagName)) {
+          customElements.define(opts.tagName, this);
+        }
       }
-    }
-  });
+    });
 
-  return class JoistElement extends Base {
-    // make all attrs observable
-    static observedAttributes = [...meta.attrs];
-    constructor(...args: any[]) {
-      super(...args);
+    return class JoistElement extends Base {
+      static observedAttributes = meta.attrs
+        .filter(({ observe }) => observe) // filter out attributes that are not to be observed
+        .map(({ attrName }) => attrName);
 
-      const root = this.shadowRoot || this;
+      constructor(...args: any[]) {
+        super(...args);
 
-      for (let [event, listener] of meta.listeners) {
-        root.addEventListener(event, listener.bind(this));
-      }
-    }
+        if (opts?.shadow) {
+          this.attachShadow({ mode: 'open' });
 
-    connectedCallback() {
-      for (let attr of meta.attrs) {
-        const value = Reflect.get(this, attr);
-
-        // reflect values back to attributes
-        if (value !== null && value !== undefined && value !== '') {
-          if (typeof value === 'boolean') {
-            if (value === true) {
-              // set boolean attribute
-              this.setAttribute(attr, '');
+          for (let res of opts.shadow) {
+            if (typeof res === 'function') {
+              res(this as unknown as Instance);
+            } else {
+              res.run(this);
             }
-          } else {
-            // set key/value attribute
-            this.setAttribute(attr, String(value));
           }
         }
+
+        for (let [event, { cb, root }] of meta.listeners) {
+          root(this).addEventListener(event, cb.bind(this));
+        }
       }
 
-      if (super.connectedCallback) {
-        super.connectedCallback();
+      connectedCallback() {
+        reflectAttributeValues(this, meta.attrs);
+
+        if (super.connectedCallback) {
+          super.connectedCallback();
+        }
       }
-    }
+    };
   };
 }
+
+function reflectAttributeValues(el: HTMLElement, attrs: AttrDef[]) {
+  for (let { propName, attrName } of attrs) {
+    const value = Reflect.get(el, propName);
+
+    // reflect values back to attributes
+    if (value !== null && value !== undefined && value !== '') {
+      if (typeof value === 'boolean') {
+        if (value === true) {
+          // set boolean attribute
+          el.setAttribute(attrName, '');
+        }
+      } else {
+        // set key/value attribute
+        el.setAttribute(attrName, String(value));
+      }
+    }
+  }
+}

package/src/lib/listen.ts

@@ -1,9 +1,15 @@
-import { metadataStore } from './metadata.js';
+import { ListenerRootSelector, metadataStore } from './metadata.js';
 
-export function listen<This extends HTMLElement>(event: string) {
-  return (value: (e: Event) => void, ctx: ClassMethodDecoratorContext<This>) => {
+export function listen<This extends HTMLElement>(event: string, root?: ListenerRootSelector) {
+  return function listenDecorator(
+    value: (e: Event) => void,
+    ctx: ClassMethodDecoratorContext<This>
+  ) {
     const metadata = metadataStore.read(ctx.metadata);
 
-    metadata.listeners.set(event, value);
+    metadata.listeners.set(event, {
+      cb: value,
+      root: root ?? ((el: HTMLElement) => el.shadowRoot ?? el)
+    });
   };
 }

package/src/lib/metadata.ts

@@ -1,9 +1,16 @@
 (Symbol as any).metadata ??= Symbol('Symbol.metadata');
 
+export interface AttrDef {
+  propName: string | symbol;
+  attrName: string;
+  observe: boolean;
+}
+
+export type ListenerRootSelector = (el: HTMLElement) => HTMLElement | ShadowRoot;
+
 export class ElementMetadata {
-  attrs: string[] = [];
-  tagName?: (val: any) => string;
-  listeners = new Map<string, (e: Event) => void>();
+  attrs: AttrDef[] = [];
+  listeners = new Map<string, { cb: (e: Event) => void; root: ListenerRootSelector }>();
 }
 
 export class MetadataStore extends WeakMap<object, ElementMetadata> {

package/src/lib/result.ts

@@ -1,27 +1,23 @@
-export abstract class ShadowResult {
-  strings: TemplateStringsArray;
-  values: any[];
-
-  #shadow: ShadowRoot | undefined = undefined;
-
-  get shadow() {
-    if (!this.#shadow) {
-      throw new Error('ShadowResult has not been applied');
-    }
+export interface ShadowResult {
+  run(el: HTMLElement): void;
+}
 
-    return this.#shadow;
-  }
+export abstract class JoistShadowResult implements ShadowResult {
+  strings;
+  values;
 
   constructor(raw: TemplateStringsArray, ...values: any[]) {
     this.strings = raw;
     this.values = values;
   }
 
-  execute(root: ShadowRoot) {
-    this.#shadow = root;
+  run(el: HTMLElement) {
+    if (!el.shadowRoot) {
+      throw new Error('ShadowResult has not been applied');
+    }
 
-    this.apply(root);
+    this.setup(el.shadowRoot);
   }
 
-  abstract apply(root: ShadowRoot): void;
+  abstract setup(root: ShadowRoot): void;
 }