feat: add @attr decorator

This allows for mapping class properties to attributes

Author: keithamus

src/attr.ts

@@ -0,0 +1,108 @@
+import {CustomElement} from './custom-element'
+
+const attrs = new WeakMap<Record<PropertyKey, unknown>, Set<string>>()
+type attrValue = string | number | boolean
+
+/**
+ * Attr is a decorator which tags a property as one to be initialized via
+ * `initializeAttrs`.
+ *
+ * The signature is typed such that the property must be one of a String,
+ * Number or Boolean. This matches the behavior of `initializeAttrs`.
+ */
+export function attr<K extends string>(proto: Record<K, attrValue>, key: K): void {
+  if (!attrs.has(proto)) attrs.set(proto, new Set())
+  attrs.get(proto)!.add(key)
+}
+
+/**
+ * initializeAttrs is called with a set of class property names (if omitted, it
+ * will look for any properties tagged with the `@attr` decorator). With this
+ * list it defines property descriptors for each property that map to `data-*`
+ * attributes on the HTMLElement instance.
+ *
+ * It works around Native Class Property semantics - which are equivalent to
+ * calling `Object.defineProperty` on the instance upon creation, but before
+ * `constructor()` is called.
+ *
+ * If a class property is assigned to the class body, it will infer the type
+ * (using `typeof`) and define an appropriate getter/setter combo that aligns
+ * to that type. This means class properties assigned to Numbers can only ever
+ * be Numbers, assigned to Booleans can only ever be Booleans, and assigned to
+ * Strings can only ever be Strings.
+ *
+ * This is automatically called as part of `@controller`. If a class uses the
+ * `@controller` decorator it should not call this manually.
+ */
+export function initializeAttrs(instance: HTMLElement, names?: Iterable<string>): void {
+  if (!names) names = attrs.get(Object.getPrototypeOf(instance)) || []
+  for (const key of names) {
+    const value = (<Record<PropertyKey, unknown>>(<unknown>instance))[key]
+    let descriptor: PropertyDescriptor
+    if (typeof value === 'number') {
+      descriptor = numberProperty(key)
+    } else if (typeof value === 'boolean') {
+      descriptor = booleanProperty(key)
+    } else {
+      descriptor = stringProperty(key)
+    }
+    Object.defineProperty(instance, key, descriptor)
+    if (key in instance && !instance.hasAttribute(attrToAttributeName(key))) {
+      descriptor.set!.call(instance, value)
+    }
+  }
+}
+
+function booleanProperty(key: string): PropertyDescriptor {
+  const attributeName = attrToAttributeName(key)
+  return {
+    get(this: HTMLElement): boolean {
+      return this.hasAttribute(attributeName)
+    },
+    set(this: HTMLElement, value: boolean) {
+      this.toggleAttribute(attributeName, value)
+    }
+  }
+}
+
+function stringProperty(key: string): PropertyDescriptor {
+  const attributeName = attrToAttributeName(key)
+  return {
+    get(this: HTMLElement): string {
+      return String(this.getAttribute(attributeName) || '')
+    },
+    set(this: HTMLElement, value: string) {
+      this.setAttribute(attributeName, value || '')
+    }
+  }
+}
+
+function numberProperty(key: string): PropertyDescriptor {
+  const attributeName = attrToAttributeName(key)
+  return {
+    get(this: HTMLElement): number {
+      return Number(this.getAttribute(attributeName) || 0)
+    },
+    set(this: HTMLElement, value: number) {
+      this.setAttribute(attributeName, String(value))
+    }
+  }
+}
+
+function attrToAttributeName(name: string): string {
+  return `data-${name.replace(/([A-Z]($|[a-z]))/g, '-$1')}`.replace(/--/g, '-').toLowerCase()
+}
+
+export function defineObservedAttributes(classObject: CustomElement): void {
+  let observed = classObject.observedAttributes || []
+  Object.defineProperty(classObject, 'observedAttributes', {
+    get() {
+      const attrMap = attrs.get(classObject.prototype)
+      if (!attrMap) return observed
+      return [...attrMap].map(attrToAttributeName).concat(observed)
+    },
+    set(attributes: string[]) {
+      observed = attributes
+    }
+  })
+}

src/controller.ts

@@ -1,10 +1,8 @@
 import {register} from './register'
 import {bind} from './bind'
 import {autoShadowRoot} from './auto-shadow-root'
-
-interface CustomElement {
-  new (): HTMLElement
-}
+import {defineObservedAttributes, initializeAttrs} from './attr'
+import {CustomElement} from './custom-element'
 
 /**
  * Controller is a decorator to be used over a class that extends HTMLElement.
@@ -17,8 +15,10 @@ export function controller(classObject: CustomElement): void {
   classObject.prototype.connectedCallback = function (this: HTMLElement) {
     this.toggleAttribute('data-catalyst', true)
     autoShadowRoot(this)
+    initializeAttrs(this)
     if (connect) connect.call(this)
     bind(this)
   }
+  defineObservedAttributes(classObject)
   register(classObject)
 }

src/custom-element.ts

@@ -0,0 +1,4 @@
+export interface CustomElement {
+  new (): HTMLElement
+  observedAttributes?: string[]
+}

src/index.ts

@@ -1,7 +1,6 @@
-import {bind, listenForBind} from './bind'
-import {register} from './register'
-import {findTarget, findTargets} from './findtarget'
-import {target, targets} from './target'
-import {controller} from './controller'
-
-export {bind, listenForBind, register, findTarget, findTargets, target, targets, controller}
+export {bind, listenForBind} from './bind'
+export {register} from './register'
+export {findTarget, findTargets} from './findtarget'
+export {target, targets} from './target'
+export {controller} from './controller'
+export {attr} from './attr'

src/register.ts

@@ -1,6 +1,4 @@
-interface CustomElement {
-  new (): HTMLElement
-}
+import {CustomElement} from './custom-element'
 
 /**
  * Register the controller as a custom element.

test/attr.js

@@ -0,0 +1,204 @@
+import {initializeAttrs, defineObservedAttributes, attr} from '../lib/attr.js'
+
+describe('initializeAttrs', () => {
+  class InitializeAttrTestElement extends HTMLElement {}
+  window.customElements.define('initialize-attr-test-element', InitializeAttrTestElement)
+
+  it('creates a getter/setter pair for each given attr name', () => {
+    const instance = document.createElement('initialize-attr-test-element')
+    expect(instance).to.not.have.ownPropertyDescriptor('foo')
+    initializeAttrs(instance, ['foo'])
+    expect(instance).to.have.ownPropertyDescriptor('foo')
+  })
+
+  it('reflects the `data-*` attribute name of the given key', () => {
+    const instance = document.createElement('initialize-attr-test-element')
+    initializeAttrs(instance, ['foo'])
+    expect(instance.foo).to.equal('')
+    instance.foo = 'bar'
+    expect(instance.getAttributeNames()).to.eql(['data-foo'])
+    expect(instance.getAttribute('data-foo')).to.equal('bar')
+    instance.setAttribute('data-foo', 'baz')
+    expect(instance.foo).to.equal('baz')
+  })
+
+  it('sets the attribute to a previously defined value on the key', () => {
+    const instance = document.createElement('initialize-attr-test-element')
+    instance.foo = 'hello'
+    initializeAttrs(instance, ['foo'])
+    expect(instance.foo).to.equal('hello')
+    expect(instance.getAttributeNames()).to.eql(['data-foo'])
+    expect(instance.getAttribute('data-foo')).to.equal('hello')
+  })
+
+  it('prioritises the value in the attribute over the property', () => {
+    const instance = document.createElement('initialize-attr-test-element')
+    instance.foo = 'goodbye'
+    instance.setAttribute('data-foo', 'hello')
+    initializeAttrs(instance, ['foo'])
+    expect(instance.foo).to.equal('hello')
+    expect(instance.getAttributeNames()).to.eql(['data-foo'])
+    expect(instance.getAttribute('data-foo')).to.equal('hello')
+  })
+
+  describe('types', () => {
+    it('infers number types from property and casts as number always', () => {
+      const instance = document.createElement('initialize-attr-test-element')
+      instance.foo = 1
+      initializeAttrs(instance, ['foo'])
+      expect(instance.foo).to.equal(1)
+      expect(instance.getAttributeNames()).to.eql(['data-foo'])
+      expect(instance.getAttribute('data-foo')).to.equal('1')
+      instance.setAttribute('data-foo', '7')
+      expect(instance.foo).to.equal(7)
+      instance.setAttribute('data-foo', '-3.14')
+      expect(instance.foo).to.equal(-3.14)
+      instance.setAttribute('data-foo', 'Not a Number')
+      expect(Number.isNaN(instance.foo)).to.equal(true)
+      instance.removeAttribute('data-foo')
+      expect(instance.foo).to.equal(0)
+      instance.foo = 3.14
+      expect(instance.getAttribute('data-foo')).to.equal('3.14')
+    })
+
+    it('infers boolean types from property and uses has/toggleAttribute', () => {
+      const instance = document.createElement('initialize-attr-test-element')
+      instance.foo = false
+      initializeAttrs(instance, ['foo'])
+      expect(instance.foo).to.equal(false)
+      expect(instance.getAttributeNames()).to.eql([])
+      expect(instance.getAttribute('data-foo')).to.equal(null)
+      instance.setAttribute('data-foo', '7')
+      expect(instance.foo).to.equal(true)
+      instance.setAttribute('data-foo', 'hello')
+      expect(instance.foo).to.equal(true)
+      instance.setAttribute('data-foo', 'false')
+      expect(instance.foo).to.equal(true)
+      instance.removeAttribute('data-foo')
+      expect(instance.foo).to.equal(false)
+      instance.foo = '1'
+      expect(instance.foo).to.equal(true)
+      expect(instance.getAttributeNames()).to.eql(['data-foo'])
+      expect(instance.getAttribute('data-foo')).to.equal('')
+      instance.foo = false
+      expect(instance.getAttributeNames()).to.eql([])
+    })
+
+    it('defaults to inferring string type for non-boolean non-number types', () => {
+      const instance = document.createElement('initialize-attr-test-element')
+      instance.foo = /^a regexp$/
+      initializeAttrs(instance, ['foo'])
+      expect(instance.foo).to.equal('/^a regexp$/')
+      expect(instance.getAttributeNames()).to.eql(['data-foo'])
+      expect(instance.getAttribute('data-foo')).to.equal('/^a regexp$/')
+    })
+  })
+
+  describe('naming', () => {
+    it('converts camel cased property names to their HTML dasherized equivalents', () => {
+      const instance = document.createElement('initialize-attr-test-element')
+      initializeAttrs(instance, ['fooBarBazBing'])
+      expect(instance.fooBarBazBing).to.equal('')
+      instance.fooBarBazBing = 'bar'
+      expect(instance.getAttributeNames()).to.eql(['data-foo-bar-baz-bing'])
+    })
+
+    it('will intuitively dasherize acryonyms', () => {
+      const instance = document.createElement('initialize-attr-test-element')
+      initializeAttrs(instance, ['URLBar'])
+      expect(instance.URLBar).to.equal('')
+      instance.URLBar = 'bar'
+      expect(instance.getAttributeNames()).to.eql(['data-url-bar'])
+    })
+
+    it('dasherizes cap suffixed names correctly', () => {
+      const instance = document.createElement('initialize-attr-test-element')
+      initializeAttrs(instance, ['ClipX'])
+      expect(instance.ClipX).to.equal('')
+      instance.ClipX = 'bar'
+      expect(instance.getAttributeNames()).to.eql(['data-clip-x'])
+    })
+  })
+
+  describe('class fields', () => {
+    class ClassFieldAttrTestElement extends HTMLElement {
+      foo = 1
+    }
+    customElements.define('class-field-attr-test-element', ClassFieldAttrTestElement)
+
+    it('overrides any getters assigned in constructor (like class fields)', () => {
+      const instance = document.createElement('class-field-attr-test-element')
+      initializeAttrs(instance, ['foo'])
+      instance.foo = 2
+      expect(instance.foo).to.equal(2)
+      expect(instance.getAttribute('data-foo')).to.equal('2')
+      instance.setAttribute('data-foo', '3')
+      expect(instance.foo).to.equal(3)
+    })
+
+    it('defaults to class field value attribute not present', () => {
+      const instance = document.createElement('class-field-attr-test-element')
+      initializeAttrs(instance, ['foo'])
+      expect(instance.foo).to.equal(1)
+      expect(instance.getAttribute('data-foo')).to.equal('1')
+    })
+
+    it('ignores class field value if element has attribute already', () => {
+      const instance = document.createElement('class-field-attr-test-element')
+      instance.setAttribute('data-foo', '2')
+      initializeAttrs(instance, ['foo'])
+      expect(instance.foo).to.equal(2)
+      expect(instance.getAttribute('data-foo')).to.equal('2')
+    })
+  })
+})
+
+describe('attr', () => {
+  class AttrTestElement extends HTMLElement {}
+  window.customElements.define('attr-test-element', AttrTestElement)
+
+  it('populates the "default" list for initializeAttrs', () => {
+    attr(AttrTestElement.prototype, 'foo')
+    attr(AttrTestElement.prototype, 'bar')
+    const instance = document.createElement('attr-test-element')
+    instance.foo = 'hello'
+    initializeAttrs(instance)
+    expect(instance).to.have.property('foo', 'hello')
+    expect(instance).to.have.property('bar', '')
+    expect(instance.getAttributeNames()).to.eql(['data-foo', 'data-bar'])
+    expect(instance.getAttribute('data-foo')).to.equal('hello')
+    expect(instance.getAttribute('data-bar')).to.equal('')
+  })
+
+})
+
+describe('defineObservedAttributes', () => {
+  it('defines `observedAttributes` getter/setter on class', () => {
+    class TestElement extends HTMLElement {}
+    defineObservedAttributes(TestElement)
+    expect(TestElement).to.have.ownPropertyDescriptor('observedAttributes')
+    expect(TestElement.observedAttributes).to.eql([])
+  })
+
+  it('can be set after definition', () => {
+    class TestElement extends HTMLElement {}
+    defineObservedAttributes(TestElement)
+    TestElement.observedAttributes = ['a', 'b', 'c']
+    expect(TestElement.observedAttributes).to.eql(['a', 'b', 'c'])
+  })
+
+  it('will reflect values from attr calls', () => {
+    class TestElement extends HTMLElement {}
+    defineObservedAttributes(TestElement)
+    attr(TestElement.prototype, 'foo')
+    expect(TestElement.observedAttributes).to.eql(['data-foo'])
+  })
+
+  it('will reflect values even if set after definition', () => {
+    class TestElement extends HTMLElement {}
+    defineObservedAttributes(TestElement)
+    attr(TestElement.prototype, 'foo')
+    TestElement.observedAttributes = ['a', 'b', 'c']
+    expect(TestElement.observedAttributes).to.eql(['data-foo', 'a', 'b', 'c'])
+  })
+})