Merge branch 'master' into docs-add-interactive-name-checker

Author: keithamus

docs/_data/reference.json

@@ -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/_guide/actions.md

@@ -304,15 +304,15 @@ class UserFilter {
 <user-list>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="all">Show all</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="new">New Users</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="admin">Admins</label>
   <!-- ... --->
 </user-filter>
@@ -344,15 +344,16 @@ class UserFilter {
 <user-filter>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters user-list.allFilter"
+    data-target="user-list.allFilter"
+    data-targets="user-list.filters"
     data-filter="all">Show all</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="new">New Users</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="admin">Admins</label>
   <!-- ... --->
 </user-filter>

docs/_guide/anti-patterns.md

@@ -35,3 +35,7 @@ Be careful not to go too short! We'd recommend avoiding contracting words such a
 ### Method names should describe what they do
 
 A good method name, much like a good class name, describes what it does, not how it was invoked. While methods can be given most names, you should avoid names that conflict with existing methods on the `HTMLElement` prototype (more on that in [anti-patterns](/guide/anti-patterns#avoid-shadowing-method-names)). Names like `onClick` are best avoided, overly generic names like `toggle` should also be avoided. Just like class names it is a good idea to ask "how" and "what", so for example `showAdmins`, `filterUsers`, `updateURL`.
+
+### `@target` should use singular naming, while `@targets` should use plural
+
+To help differentiate the two `@target`/`@targets` decorators, the properties should be named with respective to their cardinality. That is to say, if you're using an `@target` decorator, then the name should be singular (e.g. `user`, `field`) while the `@targets` decorator should be coupled with plural property names (e.g. `users`, `fields`).

docs/_guide/conventions.md

@@ -3,7 +3,7 @@ chapter: 5
 subtitle: Querying Descendants
 ---
 
-One of the three [core patterns](/guide/introduction#three-core-concepts-observe-listen-query) is Querying. In Catalyst, Targets are the preferred way to query. Targets use `querySelectorAll` under the hood, but in a way that makes it a lot simpler to work with.
+One of the three [core patterns](/guide/introduction#three-core-concepts-observe-listen-query) is Querying. In Catalyst, Targets are the preferred way to query. Targets use `querySelector` under the hood, but in a way that makes it a lot simpler to work with.
 
 Catalyst Components are really just Web Components, so you could simply use `querySelector` or `querySelectorAll` to select descendants of the element. Targets avoid some of the problems of `querySelector`; they provide a more consistent interface, avoid coupling CSS classes or HTML tag names to JS, and they handle subtle issues like nested components. Targets are also a little more ergonomic to reuse in a class. We'd recommend using Targets over `querySelector` wherever you can.
 
@@ -61,25 +61,25 @@ The target syntax follows a pattern of `controller.target`.
   </span>
   <div class="p-3">
 
-Remember! There are two decorators available, `@target` which fetches only one element, and `@targets` which fetches multiple. This is the only difference, but it's an important one.
+Remember! There are two decorators available, `@target` which fetches only one `data-target` element, and `@targets` which fetches multiple `data-targets` elements!
 
   </div>
 </div>
 
-The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost identically, but it'll return an _array_ of elements. To put this into types: `@target` returns `Element|undefined` while `@targets` returns `Array<Element>`
+The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost the same, but returns an Array of elements, and it searches the `data-targets` attribute (not `data-target`). 
 
 Elements can be referenced as multiple targets, and targets may be referenced multiple times within the HTML:
 
 ```html
 <team-members>
   <user-list>
-    <user-settings data-target="user-list.user">
-      <input type="checkbox" data-target="team-members.read user-settings.read">
-      <input type="checkbox" data-target="team-members.write user-settings.write">
+    <user-settings data-targets="user-list.users">
+      <input type="checkbox" data-targets="team-members.reads user-settings.reads">
+      <input type="checkbox" data-targets="team-members.writes user-settings.writes">
     </user-settings>
-    <user-settings data-target="user-list.user">
-      <input type="checkbox" data-target="team-members.read user-settings.read">
-      <input type="checkbox" data-target="team-members.write user-settings.write">
+    <user-settings data-targets="user-list.users">
+      <input type="checkbox" data-targets="team-members.reads user-settings.reads">
+      <input type="checkbox" data-targets="team-members.writes user-settings.writes">
     </user-settings>
   </user-list>
 </team-members>
@@ -112,6 +112,15 @@ class UserListElement extends HTMLElement {
 }
 ```
 
+### Target Vs Targets
+
+To clarify the difference between `@target` and `@targets` here is a handy table:
+
+| Decorator  | Equivalent Native Method | Selector           | Returns          | 
+|:-----------|:-------------------------|:-------------------|:-----------------|
+| `@target`  | `querySelector`          | `data-target="*"`  | `Element`        | 
+| `@targets` | `querySelectorAll`       | `data-targets="*"` | `Array<Element>` | 
+
 ### What about without Decorators?
 
 If you're using decorators, then the `@target` and `@targets` decorators will turn the decorated properties into getters.

docs/_guide/targets.md

@@ -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>

docs/_layouts/guide.html

@@ -1,6 +1,6 @@
 {
   "name": "@github/catalyst",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Helpers for creating HTML Elements as Controllers",
   "homepage": "https://github.github.io/catalyst",
   "bugs": {

package-lock.json

@@ -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))
+  }
+}

package.json

@@ -20,7 +20,7 @@ export function findTarget(controller: HTMLElement, name: string): Element | und
 export function findTargets(controller: HTMLElement, name: string): Element[] {
   const tag = controller.tagName.toLowerCase()
   const targets = []
-  for (const el of controller.querySelectorAll(`[data-target~="${tag}.${name}"]`)) {
+  for (const el of controller.querySelectorAll(`[data-targets~="${tag}.${name}"]`)) {
     if (el.closest(tag) === controller) targets.push(el)
   }
   return targets