Merge pull request #49 from github/data-targets

Use `data-targets` for `@targets`.

Author: keithamus

docs/_guide/anti-patterns.md

@@ -250,15 +250,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>
@@ -290,15 +290,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/conventions.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 any name, 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/targets.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.

src/findtarget.ts

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

test/findtarget.js

@@ -87,7 +87,7 @@ describe('findTargets', () => {
     chai.spy.on(instance, 'querySelectorAll', () => [])
     findTargets(instance, 'foo')
     expect(instance.querySelectorAll).to.have.been.called.once.with.exactly(
-      '[data-target~="find-target-test-element.foo"]'
+      '[data-targets~="find-target-test-element.foo"]'
     )
   })