Merge pull request #73 from github/support-shadowdom

Support shadowdom

Author: keithamus

docs/_guide/actions.md

@@ -138,6 +138,10 @@ class HoverCard extends HTMLElement {
 }
 ```
 
+### Targets and "ShadowRoots"
+
+Custom elements can create encapsulated DOM trees known as "Shadow" DOM. Catalyst actions support Shadow DOM by traversing the `shadowRoot`, if present, and also automatically watching shadowRoots for changes; auto-binding new elements as they are added.
+
 ### What about without Decorators?
 
 If you're using decorators, then the `@controller` decorator automatically handles binding of actions to a Controller.

docs/_guide/targets.md

@@ -121,6 +121,12 @@ To clarify the difference between `@target` and `@targets` here is a handy table
 | `@target`  | `querySelector`          | `data-target="*"`  | `Element`        | 
 | `@targets` | `querySelectorAll`       | `data-targets="*"` | `Array<Element>` | 
 
+### Targets and "ShadowRoots"
+
+Custom elements can create encapsulated DOM trees known as "Shadow" DOM. Catalyst targets support Shadow DOM by traversing the `shadowRoot` first, if present.
+
+Important to note here is that nodes from the `shadowRoot` get returned _first_. So `@targets` will return an array of nodes, where shadowRoot nodes are at the start of the Array, and `@target` will return a ShadowRoot target if it exists, otherwise it will fall back to traversing the elements direct children.
+
 ### What about without Decorators?
 
 If you're using decorators, then the `@target` and `@targets` decorators will turn the decorated properties into getters.

src/bind.ts

@@ -6,6 +6,10 @@ const controllers = new Set<string>()
  */
 export function bind(controller: HTMLElement): void {
   controllers.add(controller.tagName.toLowerCase())
+  if (controller.shadowRoot) {
+    bindElements(controller.shadowRoot)
+    listenForBind(controller.shadowRoot)
+  }
   bindElements(controller)
 }
 
@@ -48,12 +52,12 @@ interface Subscription {
   unsubscribe(): void
 }
 
-function bindElements(root: Element) {
+function bindElements(root: Element | ShadowRoot) {
   for (const el of root.querySelectorAll('[data-action]')) {
     bindActions(el)
   }
   // Also bind the controller to itself
-  if (root.hasAttribute('data-action')) {
+  if (root instanceof Element && root.hasAttribute('data-action')) {
     bindActions(root)
   }
 }
@@ -63,10 +67,18 @@ function handleEvent(event: Event) {
   const el = event.currentTarget as Element
   for (const binding of bindings(el)) {
     if (event.type === binding.type && controllers.has(binding.tag)) {
-      const controller = el.closest(binding.tag) as Element & Record<string, (ev: Event) => unknown>
+      type EventDispatcher = Element & Record<string, (ev: Event) => unknown>
+      const controller = el.closest(binding.tag) as EventDispatcher
       if (controller && typeof controller[binding.method] === 'function') {
         controller[binding.method](event)
       }
+      const root = el.getRootNode()
+      if (root instanceof ShadowRoot && root.host.matches(binding.tag)) {
+        const shadowController = root.host as EventDispatcher
+        if (typeof shadowController[binding.method] === 'function') {
+          shadowController[binding.method](event)
+        }
+      }
     }
   }
 }

src/findtarget.ts

@@ -1,6 +1,6 @@
 /**
- * findTarget will run `querySelectorAll` against the given controller,
- * returning any the first child that:
+ * findTarget will run `querySelectorAll` against the given controller, plus
+ * its shadowRoot, returning any the first child that:
  *
  *  - Matches the selector of `[data-target~="tag.name"]` where tag is the
  *  tagName of the given HTMLElement, and `name` is the given `name` argument.
@@ -12,6 +12,11 @@
  */
 export function findTarget(controller: HTMLElement, name: string): Element | undefined {
   const tag = controller.tagName.toLowerCase()
+  if (controller.shadowRoot) {
+    for (const el of controller.shadowRoot.querySelectorAll(`[data-target~="${tag}.${name}"]`)) {
+      if (!el.closest(tag)) return el
+    }
+  }
   for (const el of controller.querySelectorAll(`[data-target~="${tag}.${name}"]`)) {
     if (el.closest(tag) === controller) return el
   }
@@ -20,6 +25,11 @@ export function findTarget(controller: HTMLElement, name: string): Element | und
 export function findTargets(controller: HTMLElement, name: string): Element[] {
   const tag = controller.tagName.toLowerCase()
   const targets = []
+  if (controller.shadowRoot) {
+    for (const el of controller.shadowRoot.querySelectorAll(`[data-targets~="${tag}.${name}"]`)) {
+      if (!el.closest(tag)) targets.push(el)
+    }
+  }
   for (const el of controller.querySelectorAll(`[data-targets~="${tag}.${name}"]`)) {
     if (el.closest(tag) === controller) targets.push(el)
   }

test/bind.js

@@ -138,6 +138,45 @@ describe('bind', () => {
     expect(instance.foo).to.have.been.called.exactly(2)
   })
 
+  it('can bind elements within the shadowDOM', () => {
+    const instance = document.createElement('bind-test-element')
+    chai.spy.on(instance, 'foo')
+    instance.attachShadow({mode: 'open'})
+    const el1 = document.createElement('div')
+    const el2 = document.createElement('div')
+    el1.setAttribute('data-action', 'click:bind-test-element#foo')
+    el2.setAttribute('data-action', 'submit:bind-test-element#foo')
+    instance.shadowRoot.append(el1, el2)
+    bind(instance)
+    expect(instance.foo).to.have.not.been.called()
+    el1.click()
+    expect(instance.foo).to.have.been.called.exactly(1)
+    el2.dispatchEvent(new CustomEvent('submit'))
+    expect(instance.foo).to.have.been.called.exactly(2)
+  })
+
+  it('binds elements added to shadowDOM', async () => {
+    const instance = document.createElement('bind-test-element')
+    chai.spy.on(instance, 'foo')
+    instance.attachShadow({mode: 'open'})
+    const el1 = document.createElement('div')
+    const el2 = document.createElement('div')
+    el1.setAttribute('data-action', 'click:bind-test-element#foo')
+    el2.setAttribute('data-action', 'submit:bind-test-element#foo')
+    bind(instance)
+    instance.shadowRoot.append(el1)
+    instance.shadowRoot.append(el2)
+    // We need to wait for a couple of frames after injecting the HTML into to
+    // controller so that the actions have been bound to the controller.
+    await waitForNextAnimationFrame()
+    await waitForNextAnimationFrame()
+    expect(instance.foo).to.have.not.been.called()
+    el1.click()
+    expect(instance.foo).to.have.been.called.exactly(1)
+    el2.dispatchEvent(new CustomEvent('submit'))
+    expect(instance.foo).to.have.been.called.exactly(2)
+  })
+
   describe('listenForBind', () => {
     it('re-binds actions that are denoted by HTML that is dynamically injected into the controller', async function () {
       const instance = document.createElement('bind-test-element')

test/findtarget.js

@@ -79,29 +79,66 @@ describe('findTarget', () => {
     expect(foundElement1).to.equal(el)
     expect(foundElement2).to.equal(undefined)
   })
+
+  it('returns targets from the shadowRoot, if available', () => {
+    const instance = document.createElement('find-target-test-element')
+    instance.attachShadow({mode: 'open'})
+    const el = document.createElement('div')
+    el.setAttribute('data-target', 'find-target-test-element.foobar')
+
+    instance.shadowRoot.appendChild(el)
+
+    expect(findTarget(instance, 'foobar')).to.equal(el)
+  })
+
+  it('prioritises shadowRoot targets over others', () => {
+    const instance = document.createElement('find-target-test-element')
+    instance.attachShadow({mode: 'open'})
+    const shadowEl = document.createElement('div')
+    shadowEl.setAttribute('data-target', 'find-target-test-element.foobar')
+    const lightEl = document.createElement('div')
+    lightEl.setAttribute('data-target', 'find-target-test-element.foobar')
+
+    instance.shadowRoot.appendChild(shadowEl)
+    instance.appendChild(lightEl)
+
+    expect(findTarget(instance, 'foobar')).to.equal(shadowEl)
+  })
 })
 
 describe('findTargets', () => {
   it('calls querySelectorAll with the controller name and target name', () => {
     const instance = document.createElement('find-target-test-element')
-    chai.spy.on(instance, 'querySelectorAll', () => [])
-    findTargets(instance, 'foo')
-    expect(instance.querySelectorAll).to.have.been.called.once.with.exactly(
-      '[data-targets~="find-target-test-element.foo"]'
-    )
+    const els = [document.createElement('div'), document.createElement('div'), document.createElement('div')]
+    instance.append(...els)
+
+    els[0].setAttribute('data-targets', 'find-target-test-element.foo')
+    els[1].setAttribute('data-targets', 'find-target-test-element.foo')
+
+    expect(findTargets(instance, 'foo')).to.eql([els[0], els[1]])
   })
 
   it('returns all elements where closest tag is the controller', () => {
+    const instance = document.createElement('find-target-test-element')
     const els = [document.createElement('div'), document.createElement('div'), document.createElement('div')]
+    for (const el of els) el.setAttribute('data-targets', 'find-target-test-element.foo')
+    const nested = document.createElement('find-target-test-element')
+
+    nested.append(els[1])
+    instance.append(els[0], nested, els[2])
+
+    expect(findTargets(instance, 'foo')).to.eql([els[0], els[2]])
+  })
+
+  it('returns all elements inside a shadow root', () => {
     const instance = document.createElement('find-target-test-element')
-    chai.spy.on(instance, 'querySelectorAll', () => els)
-    chai.spy.on(els[0], 'closest', () => instance)
-    chai.spy.on(els[1], 'closest', () => null)
-    chai.spy.on(els[2], 'closest', () => instance)
-    const targets = findTargets(instance, 'foo')
-    expect(els[0].closest).to.have.been.called.once.with.exactly('find-target-test-element')
-    expect(els[1].closest).to.have.been.called.once.with.exactly('find-target-test-element')
-    expect(els[2].closest).to.have.been.called.once.with.exactly('find-target-test-element')
-    expect(targets).to.deep.equal([els[0], els[2]])
+    instance.attachShadow({mode: 'open'})
+    const els = [document.createElement('div'), document.createElement('div'), document.createElement('div')]
+    for (const el of els) el.setAttribute('data-targets', 'find-target-test-element.foo')
+
+    instance.shadowRoot.append(els[1])
+    instance.append(els[0], els[2])
+
+    expect(findTargets(instance, 'foo')).to.eql([els[1], els[0], els[2]])
   })
 })