From 21e0190a5e0d92f4c48f168f77232ba8fb638c7c Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Mon, 2 May 2022 14:18:24 +0000
Subject: [PATCH 01/13] remove controller or component suffix from registered
 elements

---
 docs/_guide/conventions.md          | 11 ++++++++---
 docs/_guide/your-first-component.md |  4 ++--
 src/register.ts                     |  2 +-
 test/register.ts                    | 12 ++++++++++++
 4 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/docs/_guide/conventions.md b/docs/_guide/conventions.md
index 4d9d01fd..a7548a07 100644
--- a/docs/_guide/conventions.md
+++ b/docs/_guide/conventions.md
@@ -5,13 +5,18 @@ subtitle: Conventions
 
 Catalyst strives for convention over code. Here are a few conventions we recommend when writing Catalyst code:
 
-### Use `Element` to suffix your controller class
+### Use `Element` or `Component` to suffix your controller class
 
-Built in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components should be no different, they should behave as closely to the built-ins as possible.
+Built in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element`, but the other suffixes might be useful for symettry with other server side comoponent frameworks such as [ViewComponent](https://viewcomponent.org/).
 
 ```typescript
 @controller
-class UserListElement extends HTMLElement {}
+class UserListElement extends HTMLElement {} // `<user-list />`
+```
+
+```typescript
+@controller
+class UserListComponent extends HTMLElement {} // `<user-list />`
 ```
 
 ### The best class-names are two word descriptions
diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md
index 338a46d0..9df2e747 100644
--- a/docs/_guide/your-first-component.md
+++ b/docs/_guide/your-first-component.md
@@ -27,10 +27,10 @@ class HelloWorldElement extends HTMLElement {
 
 Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
 
-By convention Catalyst controllers end in `Element`; Catalyst will omit this when generating a tag name. The `Element` suffix is _not_ required - just convention. All examples in this guide use `Element` suffixed names.
+Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names.
 
 {% capture callout %}
-Remember! A class name _must_ include at least two CamelCased words (not including the `Element` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskElement`, `PagerContainerElement`
+Remember! A class name _must_ include at least two CamelCased words (not including the `Element`, `Controller` or `Component` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskController`, `PagerContainerComponent`
 {% endcapture %}{% include callout.md %}
 
 
diff --git a/src/register.ts b/src/register.ts
index 97cc1484..60cd8e6c 100644
--- a/src/register.ts
+++ b/src/register.ts
@@ -9,7 +9,7 @@ import {dasherize} from './dasherize.js'
  * Example: HelloController => hello-controller
  */
 export function register(classObject: CustomElementClass): CustomElementClass {
-  const name = dasherize(classObject.name).replace(/-element$/, '')
+  const name = dasherize(classObject.name).replace(/-(element|controller|component)$/, '')
 
   try {
     window.customElements.define(name, classObject)
diff --git a/test/register.ts b/test/register.ts
index 7b923f96..b98aa737 100644
--- a/test/register.ts
+++ b/test/register.ts
@@ -70,4 +70,16 @@ describe('register', () => {
     class FirstSuffixElement extends HTMLElement {}
     expect(window.customElements.get('first-suffix')).to.equal(FirstSuffixElement)
   })
+
+  it('automatically drops the `Controller` suffix', () => {
+    @register
+    class SecondSuffixController {}
+    expect(window.customElements.get('second-suffix')).to.equal(SecondSuffixController)
+  })
+
+  it('automatically drops the `Component` suffix', () => {
+    @register
+    class ThirdSuffixComponent {}
+    expect(window.customElements.get('third-suffix')).to.equal(ThirdSuffixComponent)
+  })
 })

From cb446c8ad7b10063aa795308da20e7d557c5a4ed Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 3 May 2022 12:42:51 +0100
Subject: [PATCH 02/13] improve convention node on controller suffixes

---
 docs/_guide/conventions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/_guide/conventions.md b/docs/_guide/conventions.md
index a7548a07..8577a57c 100644
--- a/docs/_guide/conventions.md
+++ b/docs/_guide/conventions.md
@@ -5,9 +5,9 @@ subtitle: Conventions
 
 Catalyst strives for convention over code. Here are a few conventions we recommend when writing Catalyst code:
 
-### Use `Element` or `Component` to suffix your controller class
+### Suffix your controllers consistently, for symmetry
 
-Built in HTML elements all extend from the `HTMLElement` constructor, and are all suffixed with `Element` (for example `HTMLElement`, `SVGElement`, `HTMLInputElement` and so on). Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element`, but the other suffixes might be useful for symettry with other server side comoponent frameworks such as [ViewComponent](https://viewcomponent.org/).
+Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that component framework.
 
 ```typescript
 @controller

From b90895a18039ed8496b9ffcf933d9cda2e05c46c Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 3 May 2022 12:45:45 +0100
Subject: [PATCH 03/13] improve your-first-component docs around suffixes

---
 docs/_guide/your-first-component.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md
index 9df2e747..01705173 100644
--- a/docs/_guide/your-first-component.md
+++ b/docs/_guide/your-first-component.md
@@ -27,7 +27,7 @@ class HelloWorldElement extends HTMLElement {
 
 Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
 
-Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names.
+Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names (see our [convention note on this for more]({{ site.baseurl }}/guide/conventions#suffix-your-controllers-consistently-for-symmetry)).
 
 {% capture callout %}
 Remember! A class name _must_ include at least two CamelCased words (not including the `Element`, `Controller` or `Component` suffix). One-word elements will raise exceptions. Example of good names: `UserListElement`, `SubTaskController`, `PagerContainerComponent`

From 5d40d7dc4d3e6f45c51b9d45106aa262d1876a43 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 3 May 2022 12:46:57 +0100
Subject: [PATCH 04/13] add exact example for tag name in your-first-component

---
 docs/_guide/your-first-component.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md
index 01705173..280f9081 100644
--- a/docs/_guide/your-first-component.md
+++ b/docs/_guide/your-first-component.md
@@ -25,7 +25,7 @@ class HelloWorldElement extends HTMLElement {
 ```
 <br>
 
-Catalyst will automatically convert the classes name; removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
+Catalyst will automatically convert the classes name so the HTML tag will be `<hello-world>`. It removes the trailing `Element` suffix and lowercases all capital letters, separating them with a dash.
 
 Catalyst controllers can end in `Element`, `Controller`, or `Component` and Catalyst will remove this suffix when generating a tag name. Adding one of these suffixes is _not_ required - just convention. All examples in this guide use `Element` suffixed names (see our [convention note on this for more]({{ site.baseurl }}/guide/conventions#suffix-your-controllers-consistently-for-symmetry)).
 

From 60a822c21489e084265a2f23790b191dc2911bbf Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 3 May 2022 12:48:17 +0100
Subject: [PATCH 05/13] drop the the

---
 docs/_guide/conventions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/_guide/conventions.md b/docs/_guide/conventions.md
index 8577a57c..e38472af 100644
--- a/docs/_guide/conventions.md
+++ b/docs/_guide/conventions.md
@@ -7,7 +7,7 @@ Catalyst strives for convention over code. Here are a few conventions we recomme
 
 ### Suffix your controllers consistently, for symmetry
 
-Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that component framework.
+Catalyst components can be suffixed with `Element`, `Component` or `Controller`. We think elements should behave as closely to the built-ins as possible, so we like to use `Element` (existing elements do this, for example `HTMLDivElement`, `SVGElement`). If you're using a server side comoponent framework such as [ViewComponent](https://viewcomponent.org/), it's probably better to suffix `Component` for symmetry with that framework.
 
 ```typescript
 @controller

From caa9ed4d3b4d6023f562aa99a840b30939939654 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Wed, 4 May 2022 10:14:56 +0100
Subject: [PATCH 06/13] remove autoshadowroot

---
 docs/_guide/rendering.md            | 34 +++++++++---
 docs/_guide/your-first-component.md |  4 +-
 src/auto-shadow-root.ts             | 11 ----
 src/core.ts                         |  2 -
 src/index.ts                        |  1 -
 test/auto-shadow-root.ts            | 80 -----------------------------
 test/controller.ts                  | 24 ---------
 7 files changed, 29 insertions(+), 127 deletions(-)
 delete mode 100644 src/auto-shadow-root.ts
 delete mode 100644 test/auto-shadow-root.ts

diff --git a/docs/_guide/rendering.md b/docs/_guide/rendering.md
index c380a92f..69bcd601 100644
--- a/docs/_guide/rendering.md
+++ b/docs/_guide/rendering.md
@@ -11,15 +11,15 @@ Remember to _always_ make your JavaScript progressively enhanced, where possible
 
 By leveraging the native [`ShadowDOM`](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) feature, Catalyst components can render complex sub-trees, fully encapsulated from the rest of the page.
 
-Catalyst will automatically look for elements that match the `template[data-shadowroot]` selector, within your controller. If it finds one as a direct-child of your controller, it will use that to create a shadowRoot. 
+[Actions]({{ site.baseurl }}/guide/actions) and [Targets]({{ site.baseurl }}/guide/targets) all work within an elements ShadowRoot.
 
-Catalyst Controllers will search for a direct child of `template[data-shadowroot]` and load its contents as the `shadowRoot` of the element. [Actions]({{ site.baseurl }}/guide/actions) and [Targets]({{ site.baseurl }}/guide/targets) all work within an elements ShadowRoot.
+You can also leverage the [declarative shadow DOM](https://web.dev/declarative-shadow-dom/) and render a template inline to your HTML, which will automatically be attached (this may require a polyfill for browsers which are yet to support this feature).
 
 ### Example
 
 ```html
 <hello-world>
-  <template data-shadowroot>
+  <template shadowroot="open">
     <p>
       Hello <span data-target="hello-world.nameEl">World</span>
     </p>
@@ -41,12 +41,34 @@ class HelloWorldElement extends HTMLElement {
 }
 ```
 
-Providing the `<template data-shadowroot>` element as a direct child of the `hello-world` element tells Catalyst to render the templates contents automatically, and so all `HelloWorldElements` with this template will be rendered with the contents.
-
 {% capture callout %}
-Remember that _all_ instances of your controller _must_ add the `<template data-shadowroot>` HTML. If an instance does not have the `<template data-shadowroot>` as a direct child, then the shadow DOM won't be rendered for it!
+Remember that _all_ instances of your controller _must_ add the `<template shadowroot>` HTML. If an instance does not have the `<template data-shadowroot>` as a direct child, then the shadow DOM won't be rendered for it!
 {% endcapture %}{% include callout.md %}
 
+
+It is also possible to attach a shadowRoot to your element during the `connectedCallback`, like so:
+
+```typescript
+import { controller, target } from "@github/catalyst"
+
+@controller
+class HelloWorldElement extends HTMLElement {
+  @target nameEl: HTMLElement
+  get name() {
+    return this.nameEl.textContent
+  }
+  set name(value: string) {
+    this.nameEl.textContent = value
+  }
+
+  connectedCallback() {
+    this.attachShadow({ mode: 'open' }).innerHTML = `<p>
+      Hello <span data-target="hello-world.nameEl">World</span>
+    </p>`
+  }
+}
+```
+
 ### Updating a Template element using JS templates
 
 Sometimes you wont have a template that is server rendered, and instead want to make a template using JS. Catalyst does not support this out of the box, but it is possible to use another library: `@github/jtml`. This library can be used to write declarative templates using JS. Let's re-work the above example using `@github/jtml`:
diff --git a/docs/_guide/your-first-component.md b/docs/_guide/your-first-component.md
index 280f9081..d930d2ba 100644
--- a/docs/_guide/your-first-component.md
+++ b/docs/_guide/your-first-component.md
@@ -43,16 +43,14 @@ The `@controller` decorator ties together the various other decorators within Ca
  - Calls `defineObservedAttributes` with the class to add map any `@attr` decorators. See [attrs]({{ site.baseurl }}/guide/attrs) for more on this.
  - Injects the following code inside of the `connectedCallback()` function of your class:
    - `bind(this)`; ensures that as your element connects it picks up any `data-action` handlers. See [actions]({{ site.baseurl }}/guide/actions) for more on this.
-   - `autoShadowRoot(this)`; ensures that your element loads any `data-shadowroot` templates. See [rendering]({{ site.baseurl }}/guide/rendering) for more on this.
    - `initializeAttrs(this)`; ensures that your element binds any `data-*` attributes to props. See [attrs]({{ site.baseurl }}/guide/attrs) for more on this.
  
 You can do all of this manually; for example here's the above `HelloWorldElement`, written without the `@controller` annotation:
 
 ```js
-import {bind, autoShadowRoot, initializeAttrs, defineObservedAttributes} from '@github/catalyst'
+import {bind, initializeAttrs, defineObservedAttributes} from '@github/catalyst'
 class HelloWorldElement extends HTMLElement {
   connectedCallback() {
-    autoShadowRoot(this)
     initializeAttrs(this)
     this.innerHTML = 'Hello World!'
     bind(this)
diff --git a/src/auto-shadow-root.ts b/src/auto-shadow-root.ts
deleted file mode 100644
index c30fb0e7..00000000
--- a/src/auto-shadow-root.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-export function autoShadowRoot(element: HTMLElement): void {
-  for (const template of element.querySelectorAll<HTMLTemplateElement>('template[data-shadowroot]')) {
-    if (template.parentElement === element) {
-      element
-        .attachShadow({
-          mode: template.getAttribute('data-shadowroot') === 'closed' ? 'closed' : 'open'
-        })
-        .append(template.content.cloneNode(true))
-    }
-  }
-}
diff --git a/src/core.ts b/src/core.ts
index 22759e0b..01e07f9a 100644
--- a/src/core.ts
+++ b/src/core.ts
@@ -1,6 +1,5 @@
 import {register} from './register.js'
 import {bind, bindShadow} from './bind.js'
-import {autoShadowRoot} from './auto-shadow-root.js'
 import {defineObservedAttributes, initializeAttrs} from './attr.js'
 import type {CustomElementClass} from './custom-element.js'
 
@@ -53,7 +52,6 @@ export class CatalystDelegate {
   connectedCallback(instance: HTMLElement, connectedCallback: () => void) {
     instance.toggleAttribute('data-catalyst', true)
     customElements.upgrade(instance)
-    autoShadowRoot(instance)
     initializeAttrs(instance)
     bind(instance)
     connectedCallback?.call(instance)
diff --git a/src/index.ts b/src/index.ts
index 0cb35f27..0f100a8f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -4,4 +4,3 @@ export {findTarget, findTargets} from './findtarget.js'
 export {target, targets} from './target.js'
 export {controller} from './controller.js'
 export {attr, initializeAttrs, defineObservedAttributes} from './attr.js'
-export {autoShadowRoot} from './auto-shadow-root.js'
diff --git a/test/auto-shadow-root.ts b/test/auto-shadow-root.ts
deleted file mode 100644
index 221c3da9..00000000
--- a/test/auto-shadow-root.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import {expect, fixture, html} from '@open-wc/testing'
-import {replace, fake} from 'sinon'
-import {autoShadowRoot} from '../src/auto-shadow-root.js'
-
-describe('autoShadowRoot', () => {
-  class ShadowRootTestElement extends HTMLElement {
-    declare shadowRoot: ShadowRoot
-  }
-  window.customElements.define('shadowroot-test-element', ShadowRootTestElement)
-
-  let instance: ShadowRootTestElement
-  beforeEach(async () => {
-    instance = await fixture(html`<shadowroot-test-element />`)
-  })
-
-  it('automatically declares shadowroot for elements with `template[data-shadowroot]` children', async () => {
-    instance = await fixture(html`<shadowroot-test-element>
-      <template data-shadowroot="open">Hello World</template>
-    </shadowroot-test-element>`)
-    autoShadowRoot(instance)
-
-    expect(instance).to.have.property('shadowRoot').not.equal(null)
-    expect(instance.shadowRoot.textContent).to.equal('Hello World')
-  })
-
-  it('does not attach shadowroot without a template`data-shadowroot` child', async () => {
-    instance = await fixture(html`<shadowroot-test-element>
-      <template data-notshadowroot="open">Hello</template>
-      <div data-shadowroot="open">World</div>
-    </shadowroot-test-element>`)
-
-    autoShadowRoot(instance)
-
-    expect(instance).to.have.property('shadowRoot').equal(null)
-  })
-
-  it('does not attach shadowroots which are not direct children of the element', async () => {
-    instance = await fixture(html`<shadowroot-test-element>
-      <div>
-        <template data-shadowroot="open">Hello World</template>
-      </div>
-    </shadowroot-test-element>`)
-
-    autoShadowRoot(instance)
-
-    expect(instance).to.have.property('shadowRoot').equal(null)
-  })
-
-  it('attaches shadowRoot nodes open by default', async () => {
-    instance = await fixture(html`<shadowroot-test-element>
-      <template data-shadowroot>Hello World</template>
-    </shadowroot-test-element>`)
-
-    autoShadowRoot(instance)
-
-    expect(instance).to.have.property('shadowRoot').not.equal(null)
-    expect(instance.shadowRoot.textContent).to.equal('Hello World')
-  })
-
-  it('attaches shadowRoot nodes closed if `data-shadowroot` is `closed`', async () => {
-    instance = await fixture(html`<shadowroot-test-element>
-      <template data-shadowroot="closed">Hello World</template>
-    </shadowroot-test-element>`)
-    let shadowRoot: ShadowRoot | null = null
-    replace(
-      instance,
-      'attachShadow',
-      fake((...args) => {
-        shadowRoot = Element.prototype.attachShadow.apply(instance, args)
-        return shadowRoot
-      })
-    )
-
-    autoShadowRoot(instance)
-
-    expect(instance).to.have.property('shadowRoot').equal(null)
-    expect(instance.attachShadow).to.have.been.calledOnceWith({mode: 'closed'})
-    expect(shadowRoot!.textContent).to.equal('Hello World')
-  })
-})
diff --git a/test/controller.ts b/test/controller.ts
index cb6abe57..56715d49 100644
--- a/test/controller.ts
+++ b/test/controller.ts
@@ -65,30 +65,6 @@ describe('controller', () => {
     expect(instance.foo).to.have.callCount(1)
   })
 
-  it('binds auto shadowRoots', async () => {
-    @controller
-    class ControllerBindAutoShadowElement extends HTMLElement {
-      foo() {
-        return 'foo'
-      }
-    }
-    instance = await fixture<ControllerBindAutoShadowElement>(html`
-      <controller-bind-auto-shadow>
-        <template data-shadowroot="open">
-          <button data-action="click:controller-bind-auto-shadow#foo" />
-        </template>
-      </controller-bind-auto-shadow>
-    `)
-    replace(instance, 'foo', fake(instance.foo))
-
-    expect(instance.shadowRoot).to.exist
-    expect(instance).to.have.property('shadowRoot').not.equal(null)
-    expect(instance.shadowRoot!.children).to.have.lengthOf(1)
-    instance.shadowRoot!.querySelector('button')!.click()
-
-    expect(instance.foo).to.have.callCount(1)
-  })
-
   it('upgrades child decendants when connected', async () => {
     @controller
     // eslint-disable-next-line @typescript-eslint/no-unused-vars

From 2dab272f7f94f16db1691f95159f9e253fb151f5 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Mon, 16 May 2022 08:53:15 +0100
Subject: [PATCH 07/13] ensure register tests extend HTMLElement

---
 test/register.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/register.ts b/test/register.ts
index b98aa737..68de49a1 100644
--- a/test/register.ts
+++ b/test/register.ts
@@ -73,13 +73,13 @@ describe('register', () => {
 
   it('automatically drops the `Controller` suffix', () => {
     @register
-    class SecondSuffixController {}
+    class SecondSuffixController extends HTMLElement {}
     expect(window.customElements.get('second-suffix')).to.equal(SecondSuffixController)
   })
 
   it('automatically drops the `Component` suffix', () => {
     @register
-    class ThirdSuffixComponent {}
+    class ThirdSuffixComponent extends HTMLElement {}
     expect(window.customElements.get('third-suffix')).to.equal(ThirdSuffixComponent)
   })
 })

From 4ac4a5e3143014c36613c13eb163c02c70a6bc2a Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 24 May 2022 10:17:36 +0100
Subject: [PATCH 08/13] refactor attr into attrable

---
 src/attr.ts        |  96 ---------------
 src/attrable.ts    | 114 +++++++++++++++++
 src/controller.ts  |   3 +-
 src/core.ts        |   5 -
 src/index.ts       |   2 +-
 test/attr.ts       | 159 ------------------------
 test/attrable.ts   | 298 +++++++++++++++++++++++++++++++++++++++++++++
 test/controller.ts |  32 -----
 8 files changed, 415 insertions(+), 294 deletions(-)
 delete mode 100644 src/attr.ts
 create mode 100644 src/attrable.ts
 delete mode 100644 test/attr.ts
 create mode 100644 test/attrable.ts

diff --git a/src/attr.ts b/src/attr.ts
deleted file mode 100644
index 07f6a2e3..00000000
--- a/src/attr.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-import type {CustomElementClass} from './custom-element.js'
-import {dasherize} from './dasherize.js'
-import {meta} from './core.js'
-
-const attrKey = 'attr'
-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 {
-  meta(proto, attrKey).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.
- */
-const initialized = new WeakSet<Element>()
-export function initializeAttrs(instance: HTMLElement, names?: Iterable<string>): void {
-  if (initialized.has(instance)) return
-  initialized.add(instance)
-  if (!names) names = meta(Object.getPrototypeOf(instance), attrKey)
-  for (const key of names) {
-    const value = (<Record<PropertyKey, unknown>>(<unknown>instance))[key]
-    const name = attrToAttributeName(key)
-    let descriptor: PropertyDescriptor = {
-      configurable: true,
-      get(this: HTMLElement): string {
-        return this.getAttribute(name) || ''
-      },
-      set(this: HTMLElement, newValue: string) {
-        this.setAttribute(name, newValue || '')
-      }
-    }
-    if (typeof value === 'number') {
-      descriptor = {
-        configurable: true,
-        get(this: HTMLElement): number {
-          return Number(this.getAttribute(name) || 0)
-        },
-        set(this: HTMLElement, newValue: string) {
-          this.setAttribute(name, newValue)
-        }
-      }
-    } else if (typeof value === 'boolean') {
-      descriptor = {
-        configurable: true,
-        get(this: HTMLElement): boolean {
-          return this.hasAttribute(name)
-        },
-        set(this: HTMLElement, newValue: boolean) {
-          this.toggleAttribute(name, newValue)
-        }
-      }
-    }
-    Object.defineProperty(instance, key, descriptor)
-    if (key in instance && !instance.hasAttribute(name)) {
-      descriptor.set!.call(instance, value)
-    }
-  }
-}
-
-const attrToAttributeName = (name: string) => `data-${dasherize(name)}`
-
-export function defineObservedAttributes(classObject: CustomElementClass): void {
-  let observed = classObject.observedAttributes || []
-  Object.defineProperty(classObject, 'observedAttributes', {
-    configurable: true,
-    get() {
-      return [...meta(classObject.prototype, attrKey)].map(attrToAttributeName).concat(observed)
-    },
-    set(attributes: string[]) {
-      observed = attributes
-    }
-  })
-}
diff --git a/src/attrable.ts b/src/attrable.ts
new file mode 100644
index 00000000..ba8637b3
--- /dev/null
+++ b/src/attrable.ts
@@ -0,0 +1,114 @@
+import type {CustomElementClass} from './custom-element.js'
+import type {ControllableClass} from './controllable.js'
+import {controllable} from './controllable.js'
+import {dasherize, mustDasherize} from './dasherize.js'
+import {createMark} from './mark.js'
+import {createAbility} from './ability.js'
+
+const attrChangedCallback = Symbol()
+
+export interface Attrable {
+  [key: PropertyKey]: unknown
+  [attrChangedCallback](changed: Map<PropertyKey, unknown>): void
+}
+
+export interface AttrableClass {
+  new (): Attrable
+}
+
+const Identity = (v: unknown) => v
+let setFromMutation = false
+const attrs = new WeakMap<Element, Map<string, PropertyKey>>()
+
+const handleMutations = (mutations: MutationRecord[]) => {
+  for (const mutation of mutations) {
+    if (mutation.type === 'attributes') {
+      const name = mutation.attributeName!
+      const el = mutation.target as Element & {[key: PropertyKey]: unknown}
+      const key = attrs.get(el)?.get(name)
+      if (key) {
+        setFromMutation = true
+        el[key] = el.getAttribute(name)
+        setFromMutation = false
+      }
+    }
+  }
+}
+const observer = new MutationObserver(handleMutations)
+
+const [attr, getAttr, initializeAttrs] = createMark<Element & Attrable>(
+  ({name}) => mustDasherize(name, '@attr'),
+  (instance: Element & Attrable, {name, kind, access}) => {
+    let cast: typeof Identity | typeof Boolean | typeof Number | typeof String = Identity
+    let initialValue: unknown
+    if (access.get) {
+      initialValue = access.get.call(instance)
+    } else if ('value' in access && kind !== 'method') {
+      initialValue = access.value
+    }
+    let value = initialValue
+    const attributeName = dasherize(name)
+    const setCallback = (kind === 'method' ? access.value : access.set) || Identity
+    const getCallback = access.get || (() => value)
+    if (!attrs.get(instance)) attrs.set(instance, new Map())
+    attrs.get(instance)!.set(attributeName, name)
+    if (typeof value === 'number') {
+      cast = Number
+    } else if (typeof value === 'boolean') {
+      cast = Boolean
+    } else if (typeof value === 'string') {
+      cast = String
+    }
+    const queue = new Map()
+    const requestAttrChanged = async (newValue: unknown) => {
+      queue.set(name, newValue)
+      if (queue.size > 1) return
+      await Promise.resolve()
+      const changed = new Map(queue)
+      queue.clear()
+      instance[attrChangedCallback](changed)
+    }
+    return {
+      get() {
+        const has = instance.hasAttribute(attributeName)
+        if (has) {
+          return cast === Boolean ? has : cast(instance.getAttribute(attributeName))
+        }
+        return cast(getCallback.call(instance))
+      },
+      set(newValue: unknown) {
+        const isInitial = newValue === null
+        if (isInitial) newValue = initialValue
+        const same = Object.is(value, newValue)
+        value = newValue
+        setCallback.call(instance, value)
+        if (setFromMutation || same || isInitial) return
+        requestAttrChanged(newValue)
+      }
+    }
+  }
+)
+
+export {attr, getAttr, attrChangedCallback}
+export const attrable = createAbility(
+  <T extends CustomElementClass>(Class: T): T & ControllableClass & AttrableClass =>
+    class extends controllable(Class) {
+      [key: PropertyKey]: unknown
+      constructor() {
+        super()
+        initializeAttrs(this)
+        observer.observe(this, {attributeFilter: Array.from(getAttr(this)).map(dasherize)})
+      }
+
+      [attrChangedCallback](changed: Map<PropertyKey, unknown>) {
+        if (!this.isConnected) return
+        for (const [name, value] of changed) {
+          if (typeof value === 'boolean') {
+            this.toggleAttribute(dasherize(name), value)
+          } else {
+            this.setAttribute(dasherize(name), String(value))
+          }
+        }
+      }
+    }
+)
diff --git a/src/controller.ts b/src/controller.ts
index 13365c8a..ee757c44 100644
--- a/src/controller.ts
+++ b/src/controller.ts
@@ -1,5 +1,6 @@
 import {CatalystDelegate} from './core.js'
 import type {CustomElementClass} from './custom-element.js'
+import {attrable} from './attrable.js'
 /**
  * Controller is a decorator to be used over a class that extends HTMLElement.
  * It will automatically `register()` the component in the customElement
@@ -7,5 +8,5 @@ import type {CustomElementClass} from './custom-element.js'
  * wrapping the classes `connectedCallback` method if needed.
  */
 export function controller(classObject: CustomElementClass): void {
-  new CatalystDelegate(classObject)
+  new CatalystDelegate(attrable(classObject))
 }
diff --git a/src/core.ts b/src/core.ts
index 01e07f9a..ee1eda1d 100644
--- a/src/core.ts
+++ b/src/core.ts
@@ -1,6 +1,4 @@
 import {register} from './register.js'
-import {bind, bindShadow} from './bind.js'
-import {defineObservedAttributes, initializeAttrs} from './attr.js'
 import type {CustomElementClass} from './custom-element.js'
 
 const symbol = Symbol.for('catalyst')
@@ -41,7 +39,6 @@ export class CatalystDelegate {
       }
     })
 
-    defineObservedAttributes(classObject)
     register(classObject)
   }
 
@@ -52,7 +49,6 @@ export class CatalystDelegate {
   connectedCallback(instance: HTMLElement, connectedCallback: () => void) {
     instance.toggleAttribute('data-catalyst', true)
     customElements.upgrade(instance)
-    initializeAttrs(instance)
     bind(instance)
     connectedCallback?.call(instance)
     if (instance.shadowRoot) bindShadow(instance.shadowRoot)
@@ -69,7 +65,6 @@ export class CatalystDelegate {
     newValue: string | null,
     attributeChangedCallback: (...args: unknown[]) => void
   ) {
-    initializeAttrs(instance)
     if (name !== 'data-catalyst' && attributeChangedCallback) {
       attributeChangedCallback.call(instance, name, oldValue, newValue)
     }
diff --git a/src/index.ts b/src/index.ts
index 0f100a8f..2f9761f0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,4 +3,4 @@ export {register} from './register.js'
 export {findTarget, findTargets} from './findtarget.js'
 export {target, targets} from './target.js'
 export {controller} from './controller.js'
-export {attr, initializeAttrs, defineObservedAttributes} from './attr.js'
+export {attr, getAttr, attrable, attrChangedCallback} from './attrable.js'
diff --git a/test/attr.ts b/test/attr.ts
deleted file mode 100644
index 211bbdaf..00000000
--- a/test/attr.ts
+++ /dev/null
@@ -1,159 +0,0 @@
-import {expect, fixture, html} from '@open-wc/testing'
-import {controller} from '../src/controller.js'
-import {attr} from '../src/attr.js'
-
-describe('Attr', () => {
-  {
-    @controller
-    class InitializeAttrTest extends HTMLElement {
-      @attr fooBar = 'hello'
-      fooBaz = 1
-
-      getCount = 0
-      setCount = 0
-      #bing = 'world'
-      get bingBaz() {
-        this.getCount += 1
-        return this.#bing
-      }
-      @attr set bingBaz(value: string) {
-        this.setCount += 1
-        this.#bing = value
-      }
-    }
-
-    let instance: InitializeAttrTest
-    beforeEach(async () => {
-      instance = await fixture(html`<initialize-attr-test />`)
-    })
-
-    it('does not error during creation', () => {
-      document.createElement('initialize-attr-test')
-    })
-
-    it('does not alter field values from their initial value', () => {
-      expect(instance).to.have.property('fooBar', 'hello')
-      expect(instance).to.have.property('fooBaz', 1)
-      expect(instance).to.have.property('bingBaz', 'world')
-    })
-
-    it('reflects the initial value as an attribute, if not present', () => {
-      expect(instance).to.have.attribute('data-foo-bar', 'hello')
-      expect(instance).to.not.have.attribute('data-foo-baz')
-      expect(instance).to.have.attribute('data-bing-baz', 'world')
-    })
-
-    it('prioritises the value in the attribute over the property', async () => {
-      instance = await fixture(html`<initialize-attr-test data-foo-bar="goodbye" data-bing-baz="universe" />`)
-      expect(instance).to.have.property('fooBar', 'goodbye')
-      expect(instance).to.have.attribute('data-foo-bar', 'goodbye')
-      expect(instance).to.have.property('bingBaz', 'universe')
-      expect(instance).to.have.attribute('data-bing-baz', 'universe')
-    })
-
-    it('changes the property when the attribute changes', async () => {
-      instance.setAttribute('data-foo-bar', 'goodbye')
-      await Promise.resolve()
-      expect(instance).to.have.property('fooBar', 'goodbye')
-      instance.setAttribute('data-bing-baz', 'universe')
-      await Promise.resolve()
-      expect(instance).to.have.property('bingBaz', 'universe')
-    })
-
-    it('changes the attribute when the property changes', () => {
-      instance.fooBar = 'goodbye'
-      expect(instance).to.have.attribute('data-foo-bar', 'goodbye')
-      instance.bingBaz = 'universe'
-      expect(instance).to.have.attribute('data-bing-baz', 'universe')
-    })
-  }
-
-  describe('types', () => {
-    it('infers boolean types from property and uses has/toggleAttribute', async () => {
-      @controller
-      class BooleanAttrTest extends HTMLElement {
-        @attr fooBar = false
-      }
-
-      const instance = await fixture<BooleanAttrTest>(html`<boolean-attr-test />`)
-
-      expect(instance).to.have.property('fooBar', false)
-      expect(instance).to.not.have.attribute('data-foo-bar')
-      instance.setAttribute('data-foo-bar', '7')
-      await Promise.resolve()
-      expect(instance).to.have.property('fooBar', true)
-      instance.setAttribute('data-foo-bar', 'hello')
-      await Promise.resolve()
-      expect(instance).to.have.property('fooBar', true)
-      instance.setAttribute('data-foo-bar', 'false')
-      await Promise.resolve()
-      expect(instance).to.have.property('fooBar', true)
-      instance.removeAttribute('data-foo-bar')
-      await Promise.resolve()
-      expect(instance).to.have.property('fooBar', false)
-      instance.fooBar = true
-      await Promise.resolve()
-      expect(instance).to.have.attribute('data-foo-bar', '')
-      instance.fooBar = false
-      await Promise.resolve()
-      expect(instance).to.not.have.attribute('data-foo-bar')
-      instance.removeAttribute('data-foo-bar')
-      await Promise.resolve()
-      expect(instance).to.have.property('fooBar', false)
-    })
-
-    it('avoids infinite loops', async () => {
-      @controller
-      class LoopAttrTest extends HTMLElement {
-        count = 0
-        @attr
-        get fooBar() {
-          return ++this.count
-        }
-        set fooBar(value) {
-          this.count += 1
-        }
-      }
-
-      const instance = await fixture<LoopAttrTest>(html`<loop-attr-test />`)
-
-      expect(instance).to.have.property('fooBar')
-      instance.fooBar = 1
-      instance.setAttribute('data-foo-bar', '2')
-      instance.fooBar = 3
-      instance.setAttribute('data-foo-bar', '4')
-    })
-  })
-
-  describe('naming', () => {
-    @controller
-    class NamingAttrTest extends HTMLElement {
-      @attr fooBarBazBing = 'a'
-      @attr URLBar = 'b'
-      @attr ClipX = 'c'
-    }
-
-    let instance: NamingAttrTest
-    beforeEach(async () => {
-      instance = await fixture(html`<naming-attr-test />`)
-    })
-
-    it('converts camel cased property names to their HTML dasherized equivalents', async () => {
-      expect(instance.fooBarBazBing).to.equal('a')
-      instance.fooBarBazBing = 'bar'
-      expect(instance.getAttributeNames()).to.include('data-foo-bar-baz-bing')
-    })
-
-    it('will intuitively dasherize acryonyms', async () => {
-      expect(instance.URLBar).to.equal('b')
-      instance.URLBar = 'bar'
-      expect(instance.getAttributeNames()).to.include('data-url-bar')
-    })
-
-    it('dasherizes cap suffixed names correctly', async () => {
-      expect(instance.ClipX).to.equal('c')
-      instance.ClipX = 'bar'
-      expect(instance.getAttributeNames()).to.include('data-clip-x')
-    })
-  })
-})
diff --git a/test/attrable.ts b/test/attrable.ts
new file mode 100644
index 00000000..1a497ccc
--- /dev/null
+++ b/test/attrable.ts
@@ -0,0 +1,298 @@
+import {expect, fixture, html} from '@open-wc/testing'
+import {attr, attrable} from '../src/attrable.js'
+
+describe('Attrable', () => {
+  {
+    @attrable
+    class InitializeAttrTest extends HTMLElement {
+      @attr fooBar = 'hello'
+      fooBaz = 1
+
+      getCount = 0
+      setCount = 0
+      #bing = 'world'
+      get bingBaz() {
+        this.getCount += 1
+        return this.#bing
+      }
+      @attr set bingBaz(value: string) {
+        this.setCount += 1
+        this.#bing = value
+      }
+    }
+    window.customElements.define('initialize-attr-test', InitializeAttrTest)
+
+    let instance: InitializeAttrTest
+    beforeEach(async () => {
+      instance = await fixture(html`<initialize-attr-test />`)
+    })
+
+    it('does not error during creation', () => {
+      document.createElement('initialize-attr-test')
+    })
+
+    it('does not alter field values from their initial value', () => {
+      expect(instance).to.have.property('fooBar', 'hello')
+      expect(instance).to.have.property('fooBaz', 1)
+      expect(instance).to.have.property('bingBaz', 'world')
+    })
+
+    it('does not create attributes based on the initial value', () => {
+      expect(instance).to.not.have.attribute('foo-bar')
+      expect(instance).to.not.have.attribute('foo-baz')
+      expect(instance).to.not.have.attribute('bing-baz')
+    })
+
+    it('prioritises the value in the attribute over the property', async () => {
+      instance = await fixture(html`<initialize-attr-test foo-bar="goodbye" bing-baz="universe" />`)
+      expect(instance).to.have.property('fooBar', 'goodbye')
+      expect(instance).to.have.attribute('foo-bar', 'goodbye')
+      expect(instance).to.have.property('bingBaz', 'universe')
+      expect(instance).to.have.attribute('bing-baz', 'universe')
+    })
+
+    it('changes the property when the attribute changes', async () => {
+      instance.setAttribute('foo-bar', 'goodbye')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', 'goodbye')
+      instance.setAttribute('bing-baz', 'universe')
+      await Promise.resolve()
+      expect(instance).to.have.property('bingBaz', 'universe')
+    })
+
+    it('resets to the default value when the attribute is removed', async () => {
+      instance.setAttribute('foo-bar', 'goodbye')
+      expect(instance).to.have.property('fooBar', 'goodbye')
+      instance.setAttribute('foo-bar', 'goodbye')
+      instance.removeAttribute('foo-bar')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', 'hello')
+    })
+
+    it('changes the attribute when the property changes', async () => {
+      instance.fooBar = 'goodbye'
+      await Promise.resolve()
+      expect(instance).to.have.attribute('foo-bar', 'goodbye')
+      instance.bingBaz = 'universe'
+      await Promise.resolve()
+      expect(instance).to.have.attribute('bing-baz', 'universe')
+    })
+
+    it('calls underlying get when retrieving, with no attribute set', async () => {
+      instance.getCount = 0
+      instance.setCount = 0
+      instance.removeAttribute('bing-baz')
+      instance.bingBaz
+      expect(instance).to.have.property('getCount', 1)
+    })
+
+    it('does not overly eagerly call get/set on attribute change', async () => {
+      instance.getCount = 0
+      instance.setCount = 0
+      instance.setAttribute('bing-baz', 'one')
+      instance.setAttribute('bing-baz', 'one')
+      instance.setAttribute('bing-baz', 'one')
+      instance.setAttribute('bing-baz', 'one')
+      await Promise.resolve()
+      expect(instance).to.have.property('getCount', 0)
+      expect(instance).to.have.property('setCount', 4)
+    })
+  }
+
+  describe('types', () => {
+    it('infers number types from property and casts as number always', async () => {
+      @attrable
+      class NumberAttrTest extends HTMLElement {
+        @attr fooBar = 1
+      }
+      window.customElements.define('number-attr-test', NumberAttrTest)
+      const instance = await fixture<NumberAttrTest>(html`<number-attr-test />`)
+
+      expect(instance).to.have.property('fooBar', 1)
+      expect(instance).to.not.have.attribute('foo-bar')
+      instance.setAttribute('foo-bar', '7')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', 7)
+      instance.setAttribute('foo-bar', '-3.14')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', -3.14)
+      instance.setAttribute('foo-bar', 'Not a Number')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar').satisfy(Number.isNaN)
+      instance.fooBar = 3.14
+      await Promise.resolve()
+      expect(instance.getAttribute('foo-bar')).to.equal('3.14')
+      instance.removeAttribute('foo-bar')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', 1)
+    })
+
+    it('infers boolean types from property and uses has/toggleAttribute', async () => {
+      @attrable
+      class BooleanAttrTest extends HTMLElement {
+        @attr fooBar = false
+      }
+      window.customElements.define('boolean-attr-test', BooleanAttrTest)
+
+      const instance = await fixture<BooleanAttrTest>(html`<boolean-attr-test />`)
+
+      expect(instance).to.have.property('fooBar', false)
+      expect(instance).to.not.have.attribute('foo-bar')
+      instance.setAttribute('foo-bar', '7')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', true)
+      instance.setAttribute('foo-bar', 'hello')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', true)
+      instance.setAttribute('foo-bar', 'false')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', true)
+      instance.removeAttribute('foo-bar')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', false)
+      instance.fooBar = true
+      await Promise.resolve()
+      expect(instance).to.have.attribute('foo-bar', '')
+      instance.fooBar = false
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', false)
+      expect(instance).to.not.have.attribute('foo-bar')
+      instance.removeAttribute('foo-bar')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', false)
+      expect(instance).to.not.have.attribute('foo-bar')
+    })
+
+    it('defaults to inferring string type for non-boolean non-number types', async () => {
+      const regexp = /^a regexp$/
+      @attrable
+      class RegExpAttrTest extends HTMLElement {
+        @attr fooBar = regexp
+      }
+      window.customElements.define('reg-exp-attr-test', RegExpAttrTest)
+      const instance = await fixture<RegExpAttrTest>(html`<reg-exp-attr-test />`)
+
+      expect(instance).to.have.property('fooBar', regexp)
+      expect(instance).to.not.have.attribute('foo-bar')
+      instance.setAttribute('foo-bar', '/^another$/')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', '/^another$/')
+      instance.removeAttribute('foo-bar')
+      await Promise.resolve()
+      expect(instance).to.have.property('fooBar', regexp)
+      expect(instance).to.not.have.attribute('foo-bar')
+    })
+
+    it('uses get logic to retrieve value without attribute set', async () => {
+      let n = 0.5
+      @attrable
+      class SeedValueAttrTest extends HTMLElement {
+        @attr
+        get seedValue() {
+          return n
+        }
+        set seedValue(newValue: number) {}
+      }
+      window.customElements.define('seed-value-attr-test', SeedValueAttrTest)
+      const instance = await fixture<SeedValueAttrTest>(html`<seed-value-attr-test />`)
+
+      expect(instance).to.have.property('seedValue', 0.5)
+      n = 1
+      expect(instance).to.have.property('seedValue', 1)
+      expect(instance).to.not.have.attribute('seed-value')
+      instance.setAttribute('seed-value', '3')
+      expect(instance).to.have.property('seedValue', 3)
+      instance.seedValue = 8
+      await Promise.resolve()
+      expect(instance).to.have.attribute('seed-value', '8')
+      expect(instance).to.have.property('seedValue', 8)
+      n = 17
+      instance.removeAttribute('seed-value')
+      expect(instance).to.have.property('seedValue', 17)
+    })
+
+    it('can derive from internal state', async () => {
+      @attrable
+      class InternalStateAttrTest extends HTMLElement {
+        state = 'b'
+        @attr
+        get isA(): boolean {
+          return this.state === 'a'
+        }
+        set isA(value: boolean) {
+          this.state = value ? 'a' : 'b'
+        }
+      }
+      window.customElements.define('internal-state-attr-test', InternalStateAttrTest)
+      const instance = await fixture<InternalStateAttrTest>(html`<internal-state-attr-test />`)
+
+      expect(instance).to.have.property('state', 'b')
+      expect(instance).to.have.property('isA', false)
+      expect(instance).to.not.have.attribute('is-a', '')
+      instance.isA = true
+      expect(instance).to.have.property('state', 'a')
+      await Promise.resolve()
+      expect(instance).to.have.property('state', 'a')
+      expect(instance).to.have.property('isA', true)
+      expect(instance).to.have.attribute('is-a')
+    })
+
+    it('avoids infinite loops', async () => {
+      @attrable
+      class LoopAttrTest extends HTMLElement {
+        count = 0
+        @attr
+        get fooBar() {
+          return ++this.count
+        }
+        set fooBar(value) {
+          this.count += 1
+        }
+      }
+      window.customElements.define('loop-attr-test', LoopAttrTest)
+      const instance = await fixture<LoopAttrTest>(html`<loop-attr-test />`)
+
+      expect(instance).to.have.property('fooBar')
+      instance.fooBar = 1
+      instance.setAttribute('foo-bar', '2')
+      instance.fooBar = 3
+      instance.setAttribute('foo-bar', '4')
+    })
+  })
+
+  describe('naming', () => {
+    @attrable
+    class NamingAttrTest extends HTMLElement {
+      @attr fooBarBazBing = 'a'
+      @attr URLBar = 'b'
+      @attr ClipX = 'c'
+    }
+    window.customElements.define('naming-attr-test', NamingAttrTest)
+
+    let instance: NamingAttrTest
+    beforeEach(async () => {
+      instance = await fixture(html`<naming-attr-test />`)
+    })
+
+    it('converts camel cased property names to their HTML dasherized equivalents', async () => {
+      expect(instance.fooBarBazBing).to.equal('a')
+      instance.fooBarBazBing = 'bar'
+      await Promise.resolve()
+      expect(instance.getAttributeNames()).to.include('foo-bar-baz-bing')
+    })
+
+    it('will intuitively dasherize acryonyms', async () => {
+      expect(instance.URLBar).to.equal('b')
+      instance.URLBar = 'bar'
+      await Promise.resolve()
+      expect(instance.getAttributeNames()).to.include('url-bar')
+    })
+
+    it('dasherizes cap suffixed names correctly', async () => {
+      expect(instance.ClipX).to.equal('c')
+      instance.ClipX = 'bar'
+      await Promise.resolve()
+      expect(instance.getAttributeNames()).to.include('clip-x')
+    })
+  })
+})
diff --git a/test/controller.ts b/test/controller.ts
index 56715d49..9416f66a 100644
--- a/test/controller.ts
+++ b/test/controller.ts
@@ -1,7 +1,6 @@
 import {expect, fixture, html} from '@open-wc/testing'
 import {replace, fake} from 'sinon'
 import {controller} from '../src/controller.js'
-import {attr} from '../src/attr.js'
 
 describe('controller', () => {
   let instance
@@ -83,35 +82,4 @@ describe('controller', () => {
       </parent-element>
     `)
   })
-
-  describe('attrs', () => {
-    let attrValues: string[] = []
-    @controller
-    class AttributeTestElement extends HTMLElement {
-      foo = 'baz'
-      attributeChangedCallback() {
-        attrValues.push(this.getAttribute('data-foo')!)
-        attrValues.push(this.foo)
-      }
-    }
-    attr(AttributeTestElement.prototype, 'foo')
-
-    beforeEach(() => {
-      attrValues = []
-    })
-
-    it('initializes attrs as attributes in attributeChangedCallback', async () => {
-      instance = await fixture<AttributeTestElement>(html`<attribute-test></attribute-test>`)
-      instance.foo = 'bar'
-      instance.attributeChangedCallback()
-      expect(attrValues).to.eql(['bar', 'bar'])
-    })
-
-    it('initializes attributes as attrs in attributeChangedCallback', async () => {
-      instance = await fixture<AttributeTestElement>(html`<attribute-test />`)
-      instance.setAttribute('data-foo', 'bar')
-      instance.attributeChangedCallback()
-      expect(attrValues).to.eql(['bar', 'bar'])
-    })
-  })
 })

From b3f7ce614743b4cf72e21999d72fb386ddfed17d Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 24 May 2022 09:45:52 +0100
Subject: [PATCH 09/13] refactor bind into actionable

---
 src/actionable.ts               |  58 +++++++++++++++++
 src/bind.ts                     | 111 --------------------------------
 src/controller.ts               |   4 +-
 src/core.ts                     |   2 -
 src/index.ts                    |   2 +-
 test/{bind.ts => actionable.ts} |  27 ++++++--
 6 files changed, 84 insertions(+), 120 deletions(-)
 create mode 100644 src/actionable.ts
 delete mode 100644 src/bind.ts
 rename test/{bind.ts => actionable.ts} (90%)

diff --git a/src/actionable.ts b/src/actionable.ts
new file mode 100644
index 00000000..fa940021
--- /dev/null
+++ b/src/actionable.ts
@@ -0,0 +1,58 @@
+import type {CustomElementClass, CustomElement} from './custom-element.js'
+import type {ControllableClass} from './controllable.js'
+import {registerTag, observeElementForTags, parseElementTags} from './tag-observer.js'
+import {controllable, attachShadowCallback} from './controllable.js'
+import {createAbility} from './ability.js'
+
+const parse = (tag: string): [tagName: string, event: string, method: string] => {
+  const eventSep = tag.lastIndexOf(':')
+  const methodSep = Math.max(0, tag.lastIndexOf('#')) || tag.length
+  return [tag.slice(eventSep + 1, methodSep), tag.slice(0, eventSep), tag.slice(methodSep + 1) || 'handleEvent']
+}
+registerTag(
+  'data-action',
+  parseActionAttribute,
+  (el: Element, controller: Element | ShadowRoot, tag: string, event: string) => {
+    el.addEventListener(event, handleEvent)
+  }
+)
+
+const actionables = new WeakSet<CustomElement>()
+// Bind a single function to all events to avoid anonymous closure performance penalty.
+function handleEvent(event: Event) {
+  const el = event.currentTarget as Element
+  for (const [tag, type, method] of parseElementTags(el, 'data-action', parseActionAttribute)) {
+    if (event.type === type) {
+      type EventDispatcher = CustomElement & Record<string, (ev: Event) => unknown>
+      const controller = el.closest<EventDispatcher>(tag)!
+      if (actionables.has(controller) && typeof controller[method] === 'function') {
+        controller[method](event)
+      }
+      const root = el.getRootNode()
+      if (root instanceof ShadowRoot) {
+        const shadowController = root.host as EventDispatcher
+        if (shadowController.matches(tag) && actionables.has(shadowController)) {
+          if (typeof shadowController[method] === 'function') {
+            shadowController[method](event)
+          }
+        }
+      }
+    }
+  }
+}
+
+export const actionable = createAbility(
+  <T extends CustomElementClass>(Class: T): T & ControllableClass =>
+    class extends controllable(Class) {
+      constructor() {
+        super()
+        actionables.add(this)
+        observeElementForTags(this)
+      }
+
+      [attachShadowCallback](root: ShadowRoot) {
+        super[attachShadowCallback]?.(root)
+        observeElementForTags(root)
+      }
+    }
+)
diff --git a/src/bind.ts b/src/bind.ts
deleted file mode 100644
index 6b4dc64b..00000000
--- a/src/bind.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-const controllers = new WeakSet<Element>()
-
-/*
- * Bind `[data-action]` elements from the DOM to their actions.
- *
- */
-export function bind(controller: HTMLElement): void {
-  controllers.add(controller)
-  if (controller.shadowRoot) bindShadow(controller.shadowRoot)
-  bindElements(controller)
-  listenForBind(controller.ownerDocument)
-}
-
-export function bindShadow(root: ShadowRoot): void {
-  bindElements(root)
-  listenForBind(root)
-}
-
-const observers = new WeakMap<Node, Subscription>()
-/**
- * Set up observer that will make sure any actions that are dynamically
- * injected into `el` will be bound to it's controller.
- *
- * This returns a Subscription object which you can call `unsubscribe()` on to
- * stop further live updates.
- */
-export function listenForBind(el: Node = document): Subscription {
-  if (observers.has(el)) return observers.get(el)!
-  let closed = false
-  const observer = new MutationObserver(mutations => {
-    for (const mutation of mutations) {
-      if (mutation.type === 'attributes' && mutation.target instanceof Element) {
-        bindActions(mutation.target)
-      } else if (mutation.type === 'childList' && mutation.addedNodes.length) {
-        for (const node of mutation.addedNodes) {
-          if (node instanceof Element) {
-            bindElements(node)
-          }
-        }
-      }
-    }
-  })
-  observer.observe(el, {childList: true, subtree: true, attributeFilter: ['data-action']})
-  const subscription = {
-    get closed() {
-      return closed
-    },
-    unsubscribe() {
-      closed = true
-      observers.delete(el)
-      observer.disconnect()
-    }
-  }
-  observers.set(el, subscription)
-  return subscription
-}
-
-interface Subscription {
-  closed: boolean
-  unsubscribe(): void
-}
-
-function bindElements(root: Element | ShadowRoot) {
-  for (const el of root.querySelectorAll('[data-action]')) {
-    bindActions(el)
-  }
-  // Also bind the controller to itself
-  if (root instanceof Element && root.hasAttribute('data-action')) {
-    bindActions(root)
-  }
-}
-
-// Bind a single function to all events to avoid anonymous closure performance penalty.
-function handleEvent(event: Event) {
-  const el = event.currentTarget as Element
-  for (const binding of bindings(el)) {
-    if (event.type === binding.type) {
-      type EventDispatcher = HTMLElement & Record<string, (ev: Event) => unknown>
-      const controller = el.closest<EventDispatcher>(binding.tag)!
-      if (controllers.has(controller) && typeof controller[binding.method] === 'function') {
-        controller[binding.method](event)
-      }
-      const root = el.getRootNode()
-      if (root instanceof ShadowRoot && controllers.has(root.host) && root.host.matches(binding.tag)) {
-        const shadowController = root.host as EventDispatcher
-        if (typeof shadowController[binding.method] === 'function') {
-          shadowController[binding.method](event)
-        }
-      }
-    }
-  }
-}
-
-type Binding = {type: string; tag: string; method: string}
-function* bindings(el: Element): Iterable<Binding> {
-  for (const action of (el.getAttribute('data-action') || '').trim().split(/\s+/)) {
-    const eventSep = action.lastIndexOf(':')
-    const methodSep = Math.max(0, action.lastIndexOf('#')) || action.length
-    yield {
-      type: action.slice(0, eventSep),
-      tag: action.slice(eventSep + 1, methodSep),
-      method: action.slice(methodSep + 1) || 'handleEvent'
-    } || 'handleEvent'
-  }
-}
-
-function bindActions(el: Element) {
-  for (const binding of bindings(el)) {
-    el.addEventListener(binding.type, handleEvent)
-  }
-}
diff --git a/src/controller.ts b/src/controller.ts
index ee757c44..d66355ee 100644
--- a/src/controller.ts
+++ b/src/controller.ts
@@ -1,6 +1,8 @@
 import {CatalystDelegate} from './core.js'
 import type {CustomElementClass} from './custom-element.js'
 import {attrable} from './attrable.js'
+import {actionable} from './actionable.js'
+
 /**
  * Controller is a decorator to be used over a class that extends HTMLElement.
  * It will automatically `register()` the component in the customElement
@@ -8,5 +10,5 @@ import {attrable} from './attrable.js'
  * wrapping the classes `connectedCallback` method if needed.
  */
 export function controller(classObject: CustomElementClass): void {
-  new CatalystDelegate(attrable(classObject))
+  new CatalystDelegate(actionable(attrable(classObject)))
 }
diff --git a/src/core.ts b/src/core.ts
index ee1eda1d..274f88cd 100644
--- a/src/core.ts
+++ b/src/core.ts
@@ -49,9 +49,7 @@ export class CatalystDelegate {
   connectedCallback(instance: HTMLElement, connectedCallback: () => void) {
     instance.toggleAttribute('data-catalyst', true)
     customElements.upgrade(instance)
-    bind(instance)
     connectedCallback?.call(instance)
-    if (instance.shadowRoot) bindShadow(instance.shadowRoot)
   }
 
   disconnectedCallback(element: HTMLElement, disconnectedCallback: () => void) {
diff --git a/src/index.ts b/src/index.ts
index 2f9761f0..99225f7c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,4 @@
-export {bind, listenForBind} from './bind.js'
+export {actionable} from './actionable.js'
 export {register} from './register.js'
 export {findTarget, findTargets} from './findtarget.js'
 export {target, targets} from './target.js'
diff --git a/test/bind.ts b/test/actionable.ts
similarity index 90%
rename from test/bind.ts
rename to test/actionable.ts
index 1047aca0..124619ce 100644
--- a/test/bind.ts
+++ b/test/actionable.ts
@@ -1,15 +1,15 @@
 import {expect, fixture, html} from '@open-wc/testing'
 import {fake} from 'sinon'
-import {controller} from '../src/controller.js'
-import {bindShadow} from '../src/bind.js'
+import {actionable} from '../src/actionable.js'
 
 describe('Actionable', () => {
-  @controller
+  @actionable
   class BindTestElement extends HTMLElement {
     foo = fake()
     bar = fake()
     handleEvent = fake()
   }
+  window.customElements.define('bind-test', BindTestElement)
   let instance: BindTestElement
   beforeEach(async () => {
     instance = await fixture(html`<bind-test data-action="foo:bind-test#foo">
@@ -126,7 +126,25 @@ describe('Actionable', () => {
     el1.setAttribute('data-action', 'click:bind-test#foo')
     el2.setAttribute('data-action', 'submit:bind-test#foo')
     const shadowRoot = instance.attachShadow({mode: 'open'})
-    bindShadow(shadowRoot)
+    shadowRoot.append(el1, el2)
+
+    // We need to wait for one microtask after injecting the HTML into to
+    // controller so that the actions have been bound to the controller.
+    await Promise.resolve()
+
+    expect(instance.foo).to.have.callCount(0)
+    el1.click()
+    expect(instance.foo).to.have.callCount(1)
+    el2.dispatchEvent(new CustomEvent('submit'))
+    expect(instance.foo).to.have.callCount(2)
+  })
+
+  it('can bind elements within a closed shadowDOM', async () => {
+    const el1 = document.createElement('div')
+    const el2 = document.createElement('div')
+    el1.setAttribute('data-action', 'click:bind-test#foo')
+    el2.setAttribute('data-action', 'submit:bind-test#foo')
+    const shadowRoot = instance.attachShadow({mode: 'closed'})
     shadowRoot.append(el1, el2)
 
     // We need to wait for one microtask after injecting the HTML into to
@@ -158,7 +176,6 @@ describe('Actionable', () => {
       const el1 = document.createElement('div')
       const el2 = document.createElement('div')
       const shadowRoot = instance.attachShadow({mode: 'open'})
-      bindShadow(shadowRoot)
       shadowRoot.append(el1, el2)
 
       // We need to wait for one microtask after injecting the HTML into to

From d2eddfca1ef9b087eda4265b0e0a87ca2dd30fff Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 24 May 2022 10:24:57 +0100
Subject: [PATCH 10/13] rename parse to parseActionAttribute

---
 src/actionable.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/actionable.ts b/src/actionable.ts
index fa940021..97f66b9b 100644
--- a/src/actionable.ts
+++ b/src/actionable.ts
@@ -4,7 +4,7 @@ import {registerTag, observeElementForTags, parseElementTags} from './tag-observ
 import {controllable, attachShadowCallback} from './controllable.js'
 import {createAbility} from './ability.js'
 
-const parse = (tag: string): [tagName: string, event: string, method: string] => {
+const parseActionAttribute = (tag: string): [tagName: string, event: string, method: string] => {
   const eventSep = tag.lastIndexOf(':')
   const methodSep = Math.max(0, tag.lastIndexOf('#')) || tag.length
   return [tag.slice(eventSep + 1, methodSep), tag.slice(0, eventSep), tag.slice(methodSep + 1) || 'handleEvent']

From cd24a46b43a7341fcc1c01d2e00f4924c9bef467 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 24 May 2022 11:33:54 +0100
Subject: [PATCH 11/13] bump size to 2.6kb

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 98aaaa57..19492d9a 100644
--- a/package.json
+++ b/package.json
@@ -54,7 +54,7 @@
     {
       "path": "lib/index.js",
       "import": "{controller, attr, target, targets}",
-      "limit": "2.5kb"
+      "limit": "2.6kb"
     },
     {
       "path": "lib/abilities.js",

From d4c3f20b95bee85d47c92c2a70215fa56bb9587e Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Tue, 24 May 2022 11:57:20 +0100
Subject: [PATCH 12/13] add new attr docs

---
 docs/_guide/attrs.md | 189 ++++++++++++++++++++++++++++++-------------
 1 file changed, 132 insertions(+), 57 deletions(-)

diff --git a/docs/_guide/attrs.md b/docs/_guide/attrs.md
index 1947af2e..38273340 100644
--- a/docs/_guide/attrs.md
+++ b/docs/_guide/attrs.md
@@ -7,19 +7,70 @@ Components may sometimes manage state, or configuration. We encourage the use of
 
 As Catalyst elements are really just Web Components, they have the `hasAttribute`, `getAttribute`, `setAttribute`, `toggleAttribute`, and `removeAttribute` set of methods available, as well as [`dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/dataset), but these can be a little tedious to use; requiring null checking code with each call.
 
-Catalyst includes the `@attr` decorator, which provides nice syntax sugar to simplify, standardise, and encourage use of attributes. `@attr` has the following benefits over the basic `*Attribute` methods:
+Catalyst includes the `@attr` decorator which provides nice syntax sugar to simplify, standardise, and encourage use of attributes. `@attr` has the following benefits over the basic `*Attribute` methods:
+
+ - It dasherizes a property name, making it safe for HTML serialization without conflicting with [built-in global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes). This works the same as the class name, so for example `@attr pathName` will be `path-name` in HTML, `@attr srcURL` will be `src-url` in HTML.
+ - An `@attr` property automatically casts based on the initial value - if the initial value is a `string`, `boolean`, or `number` - it will never be `null` or `undefined`. No more null checking!
+ - It is automatically synced with the HTML attribute. This means setting the class property will update the HTML attribute, and setting the HTML attribute will update the class property!
+ - Assigning a value in the class description will make that value the _default_ value so if the HTML attribute isn't set, or is set but later removed the _default_ value will apply.
+
+This behaves similarly to existing HTML elements where the class field is synced with the html attribute, for example the `<input>` element's `type` field:
+
+```ts
+const input = document.createElement('input')
+console.assert(input.type === 'text') // default value
+console.assert(input.hasAttribute('type') === false) // no attribute to override
+input.setAttribute('type', 'number')
+console.assert(input.type === 'number') // overrides based on attribute
+input.removeAttribute('type')
+console.assert(input.type === 'text') // back to default value
+```
 
- - It maps whatever the property name is to `data-*`, [similar to how `dataset` does](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/dataset#name_conversion), but with more intuitive naming (e.g. `URL` maps to `data-url` not `data--u-r-l`).
- - An `@attr` property is limited to `string`, `boolean`, or `number`, it will never be `null` or `undefined` - instead it has an "empty" value. No more null checking!
- - The attribute name is automatically [observed, meaning `attributeChangedCallback` will fire when it changes](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks).
- - Assigning a value in the class description will make that value the _default_ value, so when the element is connected that value is set (unless the element has the attribute defined already).
+{% capture callout %} 
+An important part of `@attr`s is that they _must_ comprise of two words, so that they get a dash when serialised to HTML. This is intentional, to avoid conflicting with [built-in global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes).  To see how JavaScript property names convert to HTML dasherized names, try typing the name of an `@attr` below:
+{% endcapture %}{% include callout.md %}
 
-To use the `@attr` decorator, attach it to a class field, and it will get/set the value of the matching `data-*` attribute.
+<form>
+  <label>
+    <h4>I want my `@attr` to be named...</h4>
+    <input class="js-attr-dasherize-test mb-4">
+  </label>
+  <div hidden class="js-attr-dasherize-bad text-red">
+    {{ octx }} An attr name must be two words, so that the HTML version includes a dash!
+  </div>
+  <div hidden class="js-attr-dasherize-good text-green">
+    {{ octick }} This will be <code></code> in HTML.
+  </div>
+  <script type="module">
+    import {mustDasherize} from 'https://unpkg.com/@github/catalyst/lib/index.js'
+    document.querySelector('.js-attr-dasherize-test').addEventListener('input', () => {
+      let name = event.target.value
+      const goodEl = document.querySelector('.js-attr-dasherize-good')
+      const badEl = document.querySelector('.js-attr-dasherize-bad')
+      if (name === '') {
+        goodEl.hidden = true
+        badEl.hidden = true
+        return
+      }
+      let pass = true
+      try {
+        name = mustDasherize(name)
+      } catch (e) {
+        pass = false
+      }
+      goodEl.querySelector('code').textContent = name
+      goodEl.hidden = !pass
+      badEl.hidden = pass
+    })
+  </script>
+</form>
+
+To use the `@attr` decorator, attach it to a class field, and it will get/set the value of the matching dasherized HTML attribute.
 
 ### Example
 
 <!-- annotations
-attr foo: Maps to get/setAttribute('datafoo')
+attr fooBar: Maps to get/setAttribute('foo-bar')
 -->
 
 ```js
@@ -27,51 +78,50 @@ import { controller, attr } from "@github/catalyst"
 
 @controller
 class HelloWorldElement extends HTMLElement {
-  @attr foo = 'hello'
+  @attr fooBar = 'hello'
 }
 ```
 
-This is the equivalent to:
+This is somewhat equivalent to:
 
 ```js
 import { controller } from "@github/catalyst"
 
 @controller
 class HelloWorldElement extends HTMLElement {
-  get foo(): string {
-    return this.getAttribute('data-foo') || ''
+  get fooBar(): string {
+    return this.getAttribute('foo-bar') || ''
   }
 
-  set foo(value: string): void {
-    return this.setAttribute('data-foo', value)
+  set fooBar(value: string): void {
+    return this.setAttribute('foo-bar', value)
   }
 
   connectedCallback() {
-    if (!this.hasAttribute('data-foo')) this.foo = 'Hello'
+    if (!this.hasAttribute('foo-bar')) this.fooBar = 'Hello'
   }
 
-  static observedAttributes = ['data-foo']
 }
 ```
 
 ### Attribute Types
 
-The _type_ of an attribute is automatically inferred based on the type it is first set to. This means once a value is set it cannot change type; if it is set a `string` it will never be anything but a `string`. An attribute can only be one of either a `string`, `number`, or `boolean`. The types have small differences in how they behave in the DOM.
+The _type_ of an attribute is automatically inferred based on the type it is first set to. This means once a value is initially set it cannot change type; if it is set a `string` it will never be anything but a `string`. An attribute can only be one of either a `string`, `number`, or `boolean`. The types have small differences in how they behave in the DOM.
 
 Below is a handy reference for the small differences, this is all explained in more detail below that. 
 
-| Type      | "Empty" value | When `get` is called | When `set` is called |
-|:----------|:--------------|----------------------|:---------------------|
-| `string`  | `''`          | `getAttribute`       | `setAttribute`       |
-| `number`  | `0`           | `getAttribute`       | `setAttribute`       |
-| `boolean` | `false`       | `hasAttribute`       | `toggleAttribute`    |
+| Type      | When `get` is called | When `set` is called |
+|:----------|----------------------|:---------------------|
+| `string`  | `getAttribute`       | `setAttribute`       |
+| `number`  | `getAttribute`       | `setAttribute`       |
+| `boolean` | `hasAttribute`       | `toggleAttribute`    |
 
 #### String Attributes
 
-If an attribute is first set to a `string`, then it can only ever be a `string` during the lifetime of an element. The property will return an empty string (`''`) if the attribute doesn't exist, and trying to set it to something that isn't a string will turn it into one before assignment.
+If an attribute is first set to a `string`, then it can only ever be a `string` during the lifetime of an element. The property will revert to the initial value if the attribute doesn't exist, and trying to set it to something that isn't a string will turn it into one before assignment.
 
 <!-- annotations
-attr foo: Maps to get/setAttribute('data-foo')
+attr foo: Maps to get/setAttribute('foo-bar')
 -->
 
 ```js
@@ -79,14 +129,17 @@ import { controller, attr } from "@github/catalyst"
 
 @controller
 class HelloWorldElement extends HTMLElement {
-  @attr foo = 'Hello'
+  @attr fooBar = 'Hello'
 
   connectedCallback() {
-    console.assert(this.foo === 'Hello')
-    this.foo = null // TypeScript won't like this!
-    console.assert(this.foo === 'null')
-    delete this.dataset.foo // Removes the attribute
-    console.assert(this.foo === '') // If the attribute doesn't exist, its an empty string!
+    console.assert(this.fooBar === 'Hello')
+    this.fooBar = 'Goodbye'
+    console.assert(this.fooBar === 'Goodbye'')
+    console.assert(this.getAttribute('foo-bar') === 'Goodbye')
+
+    this.removeAttribute('foo-bar')
+    // If the attribute doesn't exist, it'll output the initial value!
+    console.assert(this.fooBar === 'Hello') 
   }
 }
 ```
@@ -104,24 +157,24 @@ import { controller, attr } from "@github/catalyst"
 
 @controller
 class HelloWorldElement extends HTMLElement {
-  @attr foo = false
+  @attr fooBar = false
 
   connectedCallback() {
-    console.assert(this.hasAttribute('data-foo') === false)
-    this.foo = true
-    console.assert(this.hasAttribute('data-foo') === true)
-    this.setAttribute('data-foo', 'this value doesnt matter!')
-    console.assert(this.foo === true)
+    console.assert(this.hasAttribute('foo-bar') === false)
+    this.fooBar = true
+    console.assert(this.hasAttribute('foo-bar') === true)
+    this.setAttribute('foo-bar', 'this value doesnt matter!')
+    console.assert(this.fooBar === true)
   }
 }
 ```
 
 #### Number Attributes
 
-If an attribute is first set to a number, then it can only ever be a number during the lifetime of an element. This is sort of like the [`maxlength` attribute on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength). The property will return `0` if the attribute doesn't exist, and will be coerced to `Number` if it does - this means it is _possible_ to get back `NaN`. Negative numbers and floats are also valid.
+If an attribute is first set to a number, then it can only ever be a number during the lifetime of an element. This is sort of like the [`maxlength` attribute on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength). The property will return the initial value if the attribute doesn't exist, and will be coerced to `Number` if it does - this means it is _possible_ to get back `NaN`. Negative numbers and floats are also valid.
 
 <!-- annotations
-attr foo: Maps to get/setAttribute('data-foo')
+attr foo: Maps to get/setAttribute('foo-bar')
 -->
 
 ```js
@@ -129,14 +182,15 @@ import { controller, attr } from "@github/catalyst"
 
 @controller
 class HelloWorldElement extends HTMLElement {
-  @attr foo = 1
+  @attr fooBar = 1
 
   connectedCallback() {
-    console.assert(this.getAttribute('data-foo') === '1')
-    this.setAttribute('data-foo', 'not a number')
-    console.assert(Number.isNaN(this.foo))
-    this.foo = -3.14
-    console.assert(this.getAttribute('data-foo') === '-3.14')
+    this.fooBar = 2
+    console.assert(this.getAttribute('foo-bar') === '2')
+    this.setAttribute('foo-bar', 'not a number')
+    console.assert(Number.isNaN(this.fooBar))
+    this.fooBar = -3.14
+    console.assert(this.getAttribute('foo-bar') === '-3.14')
   }
 }
 ```
@@ -146,7 +200,7 @@ class HelloWorldElement extends HTMLElement {
 When an element gets connected to the DOM, the attr is initialized. During this phase Catalyst will determine if the default value should be applied. The default value is defined in the class property. The basic rules are as such:
 
  - If the class property has a value, that is the _default_
- - When connected, if the element _does not_ have a matching attribute, the default _is_ applied.
+ - When connected, if the element _does not_ have a matching attribute, the _default is_ applied.
  - When connected, if the element _does_ have a matching attribute, the default _is not_ applied, the property will be assigned to the value of the attribute instead.
 
 {% capture callout %}
@@ -163,9 +217,9 @@ attr name: Maps to get/setAttribute('data-name')
 import { controller, attr } from "@github/catalyst"
 @controller
 class HelloWorldElement extends HTMLElement {
-  @attr name = 'World'
+  @attr dataName = 'World'
   connectedCallback() {
-    this.textContent = `Hello ${this.name}`
+    this.textContent = `Hello ${this.dataName}`
   }
 }
 ```
@@ -185,24 +239,45 @@ data-name ".*": Will set the value of `name`
 // This will render `Hello `
 ```
 
-### What about without Decorators?
+### Advanced usage
 
-If you're not using decorators, then you won't be able to use the `@attr` decorator, but there is still a way to achieve the same result. Under the hood `@attr` simply tags a field, but `initializeAttrs` and `defineObservedAttributes` do all of the logic.
+#### Determining when an @attr changes value
 
-Calling `initializeAttrs` in your connected callback, with the list of properties you'd like to initialize, and calling `defineObservedAttributes` with the class, can achieve the same result as `@attr`. The class fields can still be defined in your class, and they'll be overridden as described above. For example:
-
-```js
-import {initializeAttrs, defineObservedAttributes} from '@github/catalyst'
+To be notified when an `@attr` changes value, you can use the decorator over
+"setter" method instead, and the method will be called with the new value
+whenever it is re-assigned, either through HTML or JavaScript:
 
+```typescript
+import { controller, attr } from "@github/catalyst"
+@controller
 class HelloWorldElement extends HTMLElement {
-  foo = 1
 
-  connectedCallback() {
-    initializeAttrs(this, ['foo'])
+  @attr get dataName() {
+    return 'World' // Used to get the intial value
   }
+  // Called whenever `name` changes
+  @attr set dataName(newValue: string) {
+    this.textContent = `Hello ${newValue}`
+  }
+}
+```
+
+### What about without Decorators?
+
+If you're not using decorators, then the `@attr` decorator has an escape hatch: You can define a static class field using the `[attr.static]` computed property, as an array of key names. Like so:
+
+```js
+import {controller, attr} from '@github/catalyst'
+
+controller(
+class HelloWorldElement extends HTMLElement {
+  // Same as @attr fooBar
+  [attr.static] = ['fooBar']
 
+  // Field can still be defined
+  fooBar = 1
 }
-defineObservedAttributes(HelloWorldElement, ['foo'])
+)
 ```
 
 This example is functionally identical to:
@@ -212,6 +287,6 @@ import {controller, attr} from '@github/catalyst'
 
 @controller
 class HelloWorldElement extends HTMLElement {
-  @attr foo = 1
+  @attr fooBar = 1
 }
 ```

From a46b8125f985eb54b5b0198573f555e92cc81661 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Wed, 25 May 2022 09:44:33 +0100
Subject: [PATCH 13/13] clean up abilities docs

---
 docs/_guide/abilities.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/_guide/abilities.md b/docs/_guide/abilities.md
index dabc750b..592751a8 100644
--- a/docs/_guide/abilities.md
+++ b/docs/_guide/abilities.md
@@ -1,10 +1,9 @@
 ---
 chapter: 14
 subtitle: Abilities
-hidden: true
 ---
 
-Under the hood Catalyst's controller decorator is comprised of a handful of separate "abilities". Each of these abilities is created with the `createAbility` function. An "ability" is essentially a mixin or perhaps "higher order class". An ability takes a class and returns an extended class that adds additional behaviours. Importantly abilities are idempotent, meaning applying an ability to a class multiple times is safe and the ability is only applied once. By convention all abilities exported by Catalyst are suffixed with `able` which we think is a nice way to denote that something is an ability and should be used as such. Catalyst also exposes all of the tooling to create your own abilities in your own code which we'd encourage if you find yourself repeating patterns within components (if you think you've got a really useful ability, we'd love for you to contribute it)!
+Under the hood Catalyst's controller decorator is comprised of a handful of separate "abilities". An "ability" is essentially a mixin or perhaps "higher order class". An ability takes a class and returns an extended class that adds additional behaviours. By convention all abilities exported by Catalyst are suffixed with `able` which we think is a nice way to denote that something is an ability and should be used as such.
 
 ### Using Abilities
 
@@ -47,4 +46,6 @@ The `@controller` decorator also applies the `@register` decorator which automat
 
 The following abilities are shipped with Catalyst but require manually applying as they aren't considered critical functionality:
 
- - `providable` - the ability to define `provider` and `consumer` properties. See [Providable]({{ side.baseurl }}/guide/providable) for more.
+ - `providable` - the ability to define `provider` and `consumer` properties. See [Providable]({{ site.baseurl }}/guide/providable) for more.
+
+In addition to the provided abilities, Catalyst provides all of the tooling to create your own custom abilities. Take a look at the [Create Ability]({{ site.baseurl }}/guide/create-ability) documentation for more!