Merge branch 'main' into patch-1

Author: keithamus

.github/workflows/lighthouse.yml

@@ -51,7 +51,7 @@ jobs:
           JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Run Lighthouse CI
-        run: npx lhci autorun
+        run: npx @lhci/cli@0.7.x autorun
         env:
           JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           LHCI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/Gemfile.lock

@@ -1,7 +1,7 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     colorator (1.1.0)
     commonmarker (0.17.13)

docs/_guide/actions.md

@@ -94,7 +94,7 @@ data-action: Fires all of these methods depending on the event
       data-action="
         click:hello-world#greetSomeone
         click:analytics-tracking#click
-        hover:analytics-tracking#hover
+        mouseover:analytics-tracking#hover
       "
     >
       Greet Someone

docs/_guide/anti-patterns.md

@@ -305,18 +305,18 @@ class UserFilter {
 ```
 
 ```html
-<user-list>
+<user-filter>
   <label><input type="checkbox"
-    data-action="change:user-list.filter"
-    data-targets="user-list.filters"
+    data-action="change:user-filter#filter"
+    data-targets="user-filter.filters"
     data-filter="all">Show all</label>
   <label><input type="checkbox"
-    data-action="change:user-list.filter"
-    data-targets="user-list.filters"
+    data-action="change:user-filter#filter"
+    data-targets="user-filter.filters"
     data-filter="new">New Users</label>
   <label><input type="checkbox"
-    data-action="change:user-list.filter"
-    data-targets="user-list.filters"
+    data-action="change:user-filter#filter"
+    data-targets="user-filter.filters"
     data-filter="admin">Admins</label>
   <!-- ... --->
 </user-filter>
@@ -347,17 +347,17 @@ class UserFilter {
 ```html
 <user-filter>
   <label><input type="checkbox"
-    data-action="change:user-list.filter"
-    data-target="user-list.allFilter"
-    data-targets="user-list.filters"
+    data-action="change:user-filter#filter"
+    data-target="user-filter.allFilter"
+    data-targets="user-filter.filters"
     data-filter="all">Show all</label>
   <label><input type="checkbox"
-    data-action="change:user-list.filter"
-    data-targets="user-list.filters"
+    data-action="change:user-filter#filter"
+    data-targets="user-filter.filters"
     data-filter="new">New Users</label>
   <label><input type="checkbox"
-    data-action="change:user-list.filter"
-    data-targets="user-list.filters"
+    data-action="change:user-filter#filter"
+    data-targets="user-filter.filters"
     data-filter="admin">Admins</label>
   <!-- ... --->
 </user-filter>

docs/_guide/introduction.md

@@ -11,15 +11,15 @@ GitHub's first page interactions were written using jQuery, which was widely use
 
 Rather than moving to entirely new paradigms, GitHub continued to use the same concepts within jQuery. Event Delegation was still heavily used, as well as querySelector. The event delegation concept was also extended to "element delegation" - discovering when Elements were added to the DOM, using the [Selector Observer](https://github.com/josh/selector-observer) library.
 
-From this emerged a set of patterns which were reduced down to their first principles. _Observing_ elements on the page, _listening_ to the events these elements or their children emit, and _querying_ the children of an element to mutate or extend them.
+These patterns were reduced to first principles: _Observing_ elements on the page, _listening_ to the events these elements or their children emit, and _querying_ the children of an element to mutate or extend them.
 
 The Web Systems team at GitHub explored other tools that adopt these set of patterns and principles. The closest match to those goals was [Stimulus](https://stimulusjs.org/) (from which Catalyst is heavily inspired), but ultimately the desire to leverage technology that engineers at GitHub were already familiar with was the motivation to create Catalyst.
 
 ## Three core concepts: Observe, Listen, Query
 
 Catalyst takes these three core concepts and delivers them in the lightest possible way they can be delivered.
 
- - **Observability** Catalyst solves observability by leveraging [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Custom Elements are given unique names within a system, and the browser will automatically use the Custom Element registry to observe these Elements entering and leaving the DOM. Read more about this in the Guide Section entitled [Custom Elements]({{ site.baseurl }}/guide/your-first-component).
+ - **Observability** Catalyst solves observability by leveraging [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). Custom Elements are given unique names within a system, and the browser will automatically use the Custom Element registry to observe these Elements entering and leaving the DOM. Read more about this in the Guide Section entitled [Your First Component]({{ site.baseurl }}/guide/your-first-component).
 
  - **Listening** Event Delegation makes a great deal of sense when observing events "high up the tree" - registering global event listeners on the Window element - but Custom Elements sit much closer to their children within the tree, and so Direct Event binding is preferred. Catalyst solves this by binding event listeners to any descendants with `data-action` attributes. Read more about this in the Guide Section entitled [Actions]({{ site.baseurl }}/guide/actions).
 

docs/_guide/you-will-need.md

@@ -18,3 +18,9 @@ Catalyst uses modern browser standards, and so requires evergreen browsers or ma
  - [`MutationObserver`](https://caniuse.com/#search=MutationObserver). [`mutation-observer`](https://github.com/webmodules/mutation-observer) can polyfill this.
 
 Please note this list may increase over time. Catalyst will never ship with polyfills that add missing browser functionality, but will continue to use the latest Web Standards, and so may require more polyfills as new releases come out.
+
+### Build considerations
+
+When using build tools, some JavaScript minifiers modify the class name that Catalyst relies on. You know you have an issue if you encounter the error `"c" is not a valid custom element name`.
+
+A best practice is to allow class names that end with `Element`. For instance, for Terser, you can use the following config: `{ keep_classnames: /Element$/ }`

docs/_guide/your-first-component.md

@@ -39,7 +39,7 @@ Remember! A class name _must_ include at least two CamelCased words (not includi
 The `@controller` decorator ties together the various other decorators within Catalyst, plus a few extra conveniences such as automatically registering the element, which saves you writing some boilerplate that you'd otherwise have to write by hand. Specifically the `@controller` decorator:
 
  - Derives a tag name based on your class name, removing the trailing `Element` suffix and lowercasing all capital letters, separating them with a dash.
- - Calls `window.customElements.register` with the newly derived tag name and your class.
+ - Calls `window.customElements.define` with the newly derived tag name and your class.
  - Calls `defineObservedAttributes` with the class to add map any `@attr` decorators. See [attrs]({{ site.baseurl }}/guide/attrs) for more on this.
  - Injects the following code inside of the `connectedCallback()` function of your class:
    - `bind(this)`; ensures that as your element connects it picks up any `data-action` handlers. See [actions]({{ site.baseurl }}/guide/actions) for more on this.
@@ -59,7 +59,7 @@ class HelloWorldElement extends HTMLElement {
   }
 }
 defineObservedAttributes(HelloWorldElement)
-window.customElements.register('hello-world', HelloWorldElement)
+window.customElements.define('hello-world', HelloWorldElement)
 ```
 
 Using the `@controller` decorator saves on having to write this boilerplate for each element.

docs/custom.css

@@ -45,7 +45,7 @@ body {
 /* Code Blocks & Syntax */
 .markdown-body .highlight pre, .markdown-body pre {
   background-color: var(--color-bg-canvas-tertiary);
-  overflow: inherit
+  overflow: auto;
 }
 
 /* Inline Code */

lighthouserc.json

@@ -2,7 +2,8 @@
   "ci": {
     "collect": {
       "url": ["http://localhost:4000/?prefers-color-scheme=light", "http://localhost:4000/?prefers-color-scheme=dark"],
-      "startServerCommand": "cd docs && bundle exec jekyll serve"
+      "startServerCommand": "cd docs && bundle exec jekyll serve",
+      "startServerReadyPattern": "Server running..."
     },
     "assert": {
       "preset": "lighthouse:no-pwa",