Merge pull request #42 from github/docs-guide-proofread-and-various-tweaks

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/anti-patterns.md

@@ -0,0 +1,4 @@
+---
+chapter: 8
+subtitle: Anti Patterns
+---

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/patterns.md

@@ -0,0 +1,73 @@
+---
+chapter: 7
+subtitle: Patterns
+---
+
+An aim of Catalyst is to be as light weight as possible, and so we often avoid including helper functions for otherwise fine code. We also want to keep Catalyst focussed, and so where some helper functions might be reasonable, we recommend judicious use of other small libraries.
+
+Here are a few common patterns which we've avoided introducing into the Catalyst code base, and instead encourage you to take the example code and run with that:
+
+
+### Debouncing or Throttling events
+
+Often times you'll want to do something computationally intensive (or network intensive) based on a user event. It's worth throttling the amount of times a function can be called for these events, to prevent saturation of the CPU or network. For this we can use the "debounce" or "throttle" patterns. We recommend using the [`@github/mini-throttle`](https://github.com/github/mini-throttle) library for this, which provides convenient decorators to put on methods which will add throttling to them:
+
+```typescript
+import {controller} from '@github/catalyst'
+import {debounce} from '@github/mini-throttle/decorators'
+
+@controller
+class FuzzySearchElement extends HTMLElement {
+
+  // Adding `@debounce(100)` here means this method will only be called once in a 100ms period.
+  @debounce(100)
+  search(event: Event) {
+    const value = event.currentTarget.value
+    // This function is very computationally intensive, so we should run it as little as possible
+    this.filterAllItemsWithValue(value)
+  }
+
+}
+```
+
+### Aborting Network Requests
+
+When making network requests using `fetch`, based on user input, you can cancel old requests as new ones come in, this is useful for performance as well as UI responsiveness, as old requests that aren't cancelled might complete later than newer ones causing the UI to jump around. Aborting network requests requires you to use [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) (a web platform feature).
+
+```typescript
+@controller
+class RemoveSearchElement extends HTMLElement {
+
+  #remoteSearchController: AbortController|null
+
+  async search(event: Event) {
+    // Abort the old Request
+    this.#remoteSearchController?.abort()
+
+    // To start making a new request, construct an AbortController
+    const {signal} = (this.#remoteSearchController = new AbortController())
+
+    try {
+      const res = await fetch(myUrl, {signal})
+
+      // ... Add logic here with the completed network response
+    } catch (e) {
+
+      // ... Add logic here if you need to report a failed network request.
+      // Do not rethrow for network errors!
+
+    }
+
+    if (signal.aborted) {
+      // Here you can add logic for if the request was cancelled, but
+      // usually what you want to do is just return early to avoid
+      // cleaning up the loading UI (bear in mind if the request is
+      // cancelled then another one will be in its place).
+      return
+    }
+
+    // ... Add cleanup logic here, such as removing `loading` classes.
+
+  }
+}
+```

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'