docs: Guide proofread and various tweaks

Author: keithamus

docs/_guide/actions.md

@@ -85,7 +85,7 @@ Multiple actions can be bound to multiple events, methods, and controllers. For
       data-action="
         input:hello-world#validate
         blur:hello-world#validate
-        focus:analytics-tracking#hover
+        focus:analytics-tracking#focus
       "
       type="text"
     >
@@ -105,32 +105,34 @@ Multiple actions can be bound to multiple events, methods, and controllers. For
 
 ### Custom Events
 
-A Controller may emit custom events, which may be listened to by other Controllers using the same Actions Syntax. There is no extra syntax needed for this. For example a `lazy-load` Controller may dispatch a `loaded` event, once its contents are loaded, and other controllers can listen to this event:
+A Controller may emit custom events, which may be listened to by other Controllers using the same Actions Syntax. There is no extra syntax needed for this. For example a `lazy-loader` Controller might dispatch a `loaded` event, once its contents are loaded, and other controllers can listen to this event:
 
 ```html
 <hover-card disabled>
-  <lazy-load data-url="/user/1" data-action="loaded:hover-card#enable">
+  <lazy-loader data-url="/user/1" data-action="loaded:hover-card#enable">
     <loading-spinner>
-  </lazy-load>
+  </lazy-loader>
 </hover-card>
 ```
 
-### Private Methods
-
-Actions can always be bound to any method that is available on the Controller's prototype. If you need a method on a class that _must not_ be invoked within Actions, then you can instead use a [_class field_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Class_fields) or a [_private class field_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Class_fields#Private_fields).
-
 ```js
 import {controller} from '@github/catalyst'
 
 @controller
-class HelloWorldElement extends HTMLElement {
+class LazyLoader extends HTMLElement {
 
-  hidden = () => {
-    console.log('data-action cannot call this hidden method, but other JavaScript can!')
+  connectedCallback() {
+    this.innerHTML = await (await fetch(this.dataset.url)).text()
+    this.dispatchEvent(new CustomEvent('loaded'))
   }
 
-  #reallyHidden = () => {
-    console.log('data-action cannot call this hidden method, neither can other JavaScript!')
+}
+
+@controller
+class HoverCard extenda HTMLElement {
+
+  enable() {
+    this.disabled = false
   }
 
 }

docs/_guide/decorators.md

@@ -20,7 +20,7 @@ class HelloWorldElement extends HTMLElement {}
 
 ### Class Field Decorators
 
-Catalyst comes with the `@target` and `@targets` decorators for more [read about Targets](/guide/targets). These get added on top or to the left of the field name, like so:
+Catalyst comes with the `@target` and `@targets` decorators (for more on these [read the Targets guide section](/guide/targets)). These get added on top or to the left of the field name, like so:
 
 ```js
 class HelloWorldElement extends HTMLElement {
@@ -59,9 +59,11 @@ class HelloWorldElement extends HTMLElement {
 }
 ```
 
-### Function Call Decorators
+### Function Calling Decorators
 
-Some decorators are customisable - they get called with additional arguments, just like a function call. An example of this is the `@debounce` decorator in the [`@github/mini-throttle`](https://github.com/github/mini-throttle) package:
+You might see some decorators that look like function calls, and that's because they are! Some decorators allow for customisation; calling with additional arguments. Decorators that expect to be called are generally not interchangeable with the non-call variant, a decorators documentation should tell you how to use it.
+
+Catalyst doesn't ship with any decorators that can be called like a function; but an example of one can be found in the `@debounce` decorator in the [`@github/mini-throttle`](https://github.com/github/mini-throttle) package:
 
 ```js
 class HelloWorldElement extends HTMLElement {

docs/_guide/targets.md

@@ -3,9 +3,9 @@ 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. Target use `querySelectorAll` under the hood, but make 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 `querySelectorAll` 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 and handle nesting intuitively. Targets are also a little more ergonomic to reuse in a class. We'd recommend using Targets over `querySelector` wherever you can.
+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.
 
 To create a Target, use the `@target` decorator on a class field, and add the matching `data-target` attribute to your HTML, like so:
 
@@ -66,20 +66,20 @@ Remember! There are two decorators available, `@target` which fetches only one e
   </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 _N_ elements.
+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>`
 
 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.readCheckbox">
-      <input type="checkbox" data-target="team-members.writeCheckbox">
+      <input type="checkbox" data-target="team-members.read user-settings.read">
+      <input type="checkbox" data-target="team-members.write user-settings.write">
     </user-settings>
     <user-settings data-target="user-list.user">
-      <input type="checkbox" data-target="team-members.readCheckbox">
-      <input type="checkbox" data-target="team-members.writeCheckbox">
+      <input type="checkbox" data-target="team-members.read user-settings.read">
+      <input type="checkbox" data-target="team-members.write user-settings.write">
     </user-settings>
   </user-list>
 </team-members>
@@ -88,16 +88,26 @@ Elements can be referenced as multiple targets, and targets may be referenced mu
 <br>
 
 ```js
-import { controller, targets } from "@github/catalyst"
+import { controller, target, targets } from "@github/catalyst"
 
 @controller
-class HelloWorldElement extends HTMLElement {
-  @targets readCheckbox!: HTMLElement
-  @targets writeCheckbox!: HTMLElement
+class UserSettingsElement extends HTMLElement {
+  @target read!: HTMLInputElement
+  @target write!: HTMLInputElement
 
-  validate() {
+  valid() {
     // One checkbox must be checked!
-    return this.readCheckbox.length > 0 && this.writeCheckbox.length > 0
+    return this.read.checked || this.write.checked
+  }
+}
+
+@controller
+class UserListElement extends HTMLElement {
+  @targets user!: HTMLElement
+
+  valid() {
+    // Every user must be valid!
+    return this.user.every(user => user.valid())
   }
 }
 ```
@@ -106,7 +116,7 @@ class HelloWorldElement extends HTMLElement {
 
 If you're using decorators, then the `@target` and `@targets` decorators will turn the decorated properties into getters.
 
-If you're not using decorators, then you'll need to call `findTarget(this, key)` or `findTargets(this, key)` in the getter, for example:
+If you're not using decorators, then you'll need to make a `getter`, and call `findTarget(this, key)` or `findTargets(this, key)` in the getter, for example:
 
 ```js
 import {findTarget, findTargets} from '@github/catalyst'