Merge pull request #38 from github/bind-dynamically-injected-actions

Bind dynamically injected actions

Author: keithamus

docs/_guide/actions.md

@@ -144,14 +144,26 @@ If you're using decorators, then the `@controller` decorator automatically handl
 
 If you're not using decorators, then you'll need to call `bind(this)` somewhere inside of `connectedCallback()`.
 
-```
+```js
 import {bind} from '@github/catalyst'
 
 class HelloWorldElement extends HTMLElement {
-
   connectedCallback() {
     bind(this)
   }
-
 }
 ```
+
+### Binding dynamically added actions
+
+Catalyst doesn't automatically bind actions to elements that are dynamically injected into the DOM. If you need to dynamically inject actions (for example you're injecting HTML via AJAX) you can call the `listenForBind` function to set up a observer that will bind actions when they are added to a controller.
+
+You can provide the element you'd like to observe as a first argument and the number of items to process in a batch as a second argument. Those arguments default to `document` and `30` respectively.
+
+Batch processing binds events in small batches to maintain UI stability (using `requestAnimationFrame` behind the scenes). We recommend the default of `30` as a sensible default, but you may find changing this number helps depending on your requirements.
+
+```js
+import {listenForBind} from '@github/catalyst'
+
+listenForBind(document, 30)
+```

docs/_layouts/guide.html

@@ -7,7 +7,7 @@
   {% include sidebar.html %}
 
   <section class="col-9 px-5 f4">
-    <div class="container-md markdown-body">
+    <div class="container-md markdown-body mb-5">
       <h1 class="mb-4 f0-light">{{ page.title }}</h1>
       {{ content }}
     </div>

src/bind.ts

@@ -1,9 +1,11 @@
+const bound = new Set<string>()
 /*
  * Bind `[data-action]` elements from the DOM to their actions.
  *
  */
 export function bind(controller: HTMLElement): void {
   const tag = controller.tagName.toLowerCase()
+  bound.add(tag)
   const actionAttributeMatcher = `[data-action*=":${tag}#"]`
 
   for (const el of controller.querySelectorAll(actionAttributeMatcher)) {
@@ -18,32 +20,103 @@ export function bind(controller: HTMLElement): void {
   }
 }
 
-// Bind the data-action attribute of a single element to the controller
-function bindActionsToController(controller: HTMLElement, el: Element) {
-  const tag = controller.tagName.toLowerCase()
-
-  // Match the pattern of `eventName:constructor#method`.
+// Match the pattern of `eventName:constructor#method`.
+function* getActions(el: Element): Generator<[string, string, string]> {
   for (const binding of (el.getAttribute('data-action') || '').split(' ')) {
-    const [rest, method] = binding.split('#')
+    const [rest, methodName] = binding.split('#')
+    if (!methodName) continue
 
     // eventName may contain `:` so account for that
     // by splitting by the last instance of `:`
     const colonIndex = rest.lastIndexOf(':')
     if (colonIndex < 0) continue
 
-    const handler = rest.slice(colonIndex + 1)
-    if (handler !== tag) continue
+    yield [rest.slice(0, colonIndex), rest.slice(colonIndex + 1), methodName]
+  }
+}
+
+function bindActionToController(controller: HTMLElement, el: Element, methodName: string, eventName: string) {
+  // Check the `method` is present on the prototype
+  const methodDescriptor =
+    Object.getOwnPropertyDescriptor(controller, methodName) ||
+    Object.getOwnPropertyDescriptor(Object.getPrototypeOf(controller), methodName)
+  if (methodDescriptor && typeof methodDescriptor.value == 'function') {
+    el.addEventListener(eventName, (event: Event) => {
+      methodDescriptor.value.call(controller, event)
+    })
+  }
+}
 
-    const eventName = rest.slice(0, colonIndex)
+// Bind the data-action attribute of a single element to the controller
+function bindActionsToController(controller: HTMLElement, el: Element) {
+  const tag = controller.tagName.toLowerCase()
 
-    // Check the `method` is present on the prototype
-    const methodDescriptor =
-      Object.getOwnPropertyDescriptor(controller, method) ||
-      Object.getOwnPropertyDescriptor(Object.getPrototypeOf(controller), method)
-    if (methodDescriptor && typeof methodDescriptor.value == 'function') {
-      el.addEventListener(eventName, (event: Event) => {
-        methodDescriptor.value.call(controller, event)
-      })
+  for (const [eventName, tagName, methodName] of getActions(el)) {
+    if (tagName === tag) {
+      bindActionToController(controller, el, methodName, eventName)
     }
   }
 }
+
+interface Subscription {
+  closed: boolean
+  unsubscribe(): void
+}
+
+/**
+ * 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 = document, batchSize = 30): Subscription {
+  let closed = false
+
+  const observer = new MutationObserver(mutations => {
+    const queue = new Set<Element>()
+    for (const mutation of mutations) {
+      if (mutation.type === 'childList' && mutation.addedNodes.length) {
+        for (const node of mutation.addedNodes) {
+          if (!(node instanceof Element)) continue
+          if (node.hasAttribute('data-action')) {
+            queue.add(node)
+          }
+        }
+      }
+    }
+    if (queue.size) requestAnimationFrame(() => processQueue(queue, batchSize))
+  })
+
+  observer.observe(el, {childList: true, subtree: true})
+
+  return {
+    get closed() {
+      return closed
+    },
+    unsubscribe() {
+      closed = true
+      observer.disconnect()
+    }
+  }
+}
+
+function processQueue(queue: Set<Element>, batchSize: number) {
+  let counter = batchSize
+  for (const el of queue) {
+    for (const [eventName, controllerTag, methodName] of getActions(el)) {
+      if (!bound.has(controllerTag)) continue
+      const controller = el.closest(controllerTag)
+      if (!(controller instanceof HTMLElement)) continue
+
+      bindActionToController(controller, el, methodName, eventName)
+    }
+    queue.delete(el)
+
+    counter -= 1
+    if (counter === 0) break
+  }
+  if (queue.size !== 0) {
+    requestAnimationFrame(() => processQueue(queue, batchSize))
+  }
+}

src/index.ts

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

test/bind.js

@@ -1,8 +1,25 @@
-import {bind} from '../lib/bind.js'
+import {bind, listenForBind} from '../lib/bind.js'
+
+async function waitForNextAnimationFrame() {
+  return new Promise(resolve => {
+    window.requestAnimationFrame(resolve)
+  })
+}
 
 describe('bind', () => {
   window.customElements.define('bind-test-element', class extends HTMLElement {})
 
+  let root
+
+  beforeEach(() => {
+    root = document.createElement('div')
+    document.body.appendChild(root)
+  })
+
+  afterEach(() => {
+    root.remove()
+  })
+
   it('queries for Elements matching data-action*="tagname"', () => {
     const instance = document.createElement('bind-test-element')
     chai.spy.on(instance, 'querySelectorAll', () => [])
@@ -138,4 +155,55 @@ describe('bind', () => {
     el2.addEventListener.__spy.calls[0][1]('b')
     expect(instance.foo).to.have.been.called.twice.second.with('b')
   })
+
+  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')
+      chai.spy.on(instance, 'foo')
+      root.appendChild(instance)
+      listenForBind(root)
+      const button = document.createElement('button')
+      button.setAttribute('data-action', 'click:bind-test-element#foo')
+      instance.appendChild(button)
+      // 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()
+      button.click()
+      expect(instance.foo).to.have.been.called.exactly(1)
+    })
+
+    it('will not re-bind actions after unsubscribe() is called', async function () {
+      const instance = document.createElement('bind-test-element')
+      chai.spy.on(instance, 'foo')
+      root.appendChild(instance)
+      listenForBind(root).unsubscribe()
+      const button = document.createElement('button')
+      button.setAttribute('data-action', 'click:bind-test-element#foo')
+      instance.appendChild(button)
+      // 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()
+      button.click()
+      expect(instance.foo).to.have.been.called.exactly(0)
+    })
+
+    it('will not re-bind elements that havent already had `bind()` called', async function () {
+      customElements.define('bind-test-not-element', class BindTestNotController extends HTMLElement {})
+      const instance = document.createElement('bind-test-not-element')
+      chai.spy.on(instance, 'foo')
+      root.appendChild(instance)
+      listenForBind(root)
+      const button = document.createElement('button')
+      button.setAttribute('data-action', 'click:bind-test-not-element#foo')
+      instance.appendChild(button)
+      // 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()
+      button.click()
+      expect(instance.foo).to.have.been.called.exactly(0)
+    })
+  })
 })

test/findtarget.js

@@ -4,7 +4,6 @@ describe('findTarget', () => {
   window.customElements.define('find-target-test-element', class extends HTMLElement {})
 
   let root
-
   beforeEach(() => {
     root = document.createElement('div')
     document.body.appendChild(root)