Merge pull request #114 from github/docs-add-annotations-for-code-samples

docs: add annotations for code samples

Author: keithamus

docs/_guide/actions.md

@@ -14,6 +14,10 @@ Remember! Actions are _automatically_ bound using the `@controller` decorator. T
 <div class="d-flex my-4">
   <div class="">
 
+<!-- annotations
+data-action "click.*": Will call `greet()` when clicked
+-->
+
 ```html
 <hello-world>
   <input
@@ -35,6 +39,10 @@ Remember! Actions are _automatically_ bound using the `@controller` decorator. T
   </div>
   <div class="ml-4">
 
+<!-- annotations
+greet: All public methods can be called with `data-action`
+-->
+
 ```js
 import { controller, target } from "@github/catalyst"
 
@@ -65,6 +73,10 @@ The actions syntax follows a pattern of `event:controller#method`.
 
 Multiple actions can be bound to multiple events, methods, and controllers. For example:
 
+<!-- annotations
+data-action: Fires all of these methods depending on the event
+-->
+
 ```html
 <analytics-tracking>
   <hello-world>
@@ -95,6 +107,10 @@ Multiple actions can be bound to multiple events, methods, and controllers. For
 
 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:
 
+<!-- annotations
+data-action "loaded: Calls enable() on the `loaded` custom event
+-->
+
 ```html
 <hover-card disabled>
   <lazy-loader data-url="/user/1" data-action="loaded:hover-card#enable">
@@ -103,6 +119,11 @@ A Controller may emit custom events, which may be listened to by other Controlle
 </hover-card>
 ```
 
+<!-- annotations
+this . dispatchEvent . new CustomEvent . . loaded . . : Dispatches custom "loaded" event
+enable: All public methods can be called with `data-action`
+-->
+
 ```js
 import {controller} from '@github/catalyst'
 

docs/_guide/attrs.md

@@ -18,6 +18,10 @@ To use the `@attr` decorator, attach it to a class field, and it will get/set th
 
 ### Example
 
+<!-- annotations
+attr foo: Maps to get/setAttribute('datafoo')
+-->
+
 ```js
 import { controller, attr } from "@github/catalyst"
 
@@ -66,6 +70,10 @@ Below is a handy reference for the small differences, this is all explained in m
 
 If an attribute is first set to a `string`, then it can only ever be a `string` during the lifetime of an element. The property will return an empty string (`''`) if the attribute doesn't exist, and trying to set it to something that isn't a string will turn it into one before assignment.
 
+<!-- annotations
+attr foo: Maps to get/setAttribute('data-foo')
+-->
+
 ```js
 import { controller, attr } from "@github/catalyst"
 
@@ -87,6 +95,10 @@ class HelloWorldElement extends HTMLElement {
 
 If an attribute is first set to a boolean, then it can only ever be a boolean during the lifetime of an element. Boolean properties check for _presence_ of an attribute, sort of like how [`required`, `disabled` & `readonly` attributes work on forms](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes) The property will return `false` if the attribute doesn't exist, and `true` if it does, regardless of the value. If the property is set to `false` then `removeAttribute` is called, whereas `setAttribute(name, '')` is called when setting to a truthy value.
 
+<!-- annotations
+attr foo: Maps to has/toggleAttribute('data-foo')
+-->
+
 ```js
 import { controller, attr } from "@github/catalyst"
 
@@ -108,6 +120,10 @@ class HelloWorldElement extends HTMLElement {
 
 If an attribute is first set to a number, then it can only ever be a number during the lifetime of an element. This is sort of like the [`maxlength` attribute on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength). The property will return `0` if the attribute doesn't exist, and will be coerced to `Number` if it does - this means it is _possible_ to get back `NaN`. Negative numbers and floats are also valid.
 
+<!-- annotations
+attr foo: Maps to get/setAttribute('data-foo')
+-->
+
 ```js
 import { controller, attr } from "@github/catalyst"
 
@@ -139,6 +155,10 @@ Remember! The values defined in the class field are the _default_. They won't be
 
 The following example illustrates this behavior:
 
+<!-- annotations
+attr name: Maps to get/setAttribute('data-name')
+-->
+
 ```js
 import { controller, attr } from "@github/catalyst"
 @controller
@@ -150,6 +170,10 @@ class HelloWorldElement extends HTMLElement {
 }
 ```
 
+<!-- annotations
+data-name ".*": Will set the value of `name`
+-->
+
 ```html
 <hello-world></hello-world>
 // This will render `Hello World`

docs/_guide/targets.md

@@ -13,6 +13,9 @@ To create a Target, use the `@target` decorator on a class field, and add the ma
 
 <div class="d-flex my-4">
   <div>
+<!-- annotations
+data-target ".*": This maps to the `@target output` property
+-->
 
 ```html
 <hello-world>
@@ -25,6 +28,10 @@ To create a Target, use the `@target` decorator on a class field, and add the ma
   </div>
   <div class="ml-4">
 
+<!-- annotations
+@ target output: This maps to the data-target attribute
+-->
+
 ```js
 import { controller, target } from "@github/catalyst"
 
@@ -58,23 +65,35 @@ The `@target` decorator will only ever return _one_ element, just like `querySel
 
 Elements can be referenced as multiple targets, and targets may be referenced multiple times within the HTML:
 
+<!-- annotations
+data-targets ".*users": This maps to the `@targets users` property
+data-target ".*read": This maps to the `@target read` property
+data-target ".*write": This maps to the `@target write` property
+-->
+
 ```html
 <team-members>
   <user-list>
     <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">
+      <input type="checkbox" data-target="user-settings.read">
+      <input type="checkbox" data-target="user-settings.write">
     </user-settings>
     <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">
+      <input type="checkbox" data-target="user-settings.read">
+      <input type="checkbox" data-target="user-settings.write">
     </user-settings>
   </user-list>
 </team-members>
 ```
 
 <br>
 
+<!-- annotations
+@ targets users: This maps to the data-targets attribute
+@ target read: This maps to the data-target attribute
+@ target write: This maps to the data-target attribute
+-->
+
 ```js
 import { controller, target, targets } from "@github/catalyst"
 
@@ -84,7 +103,7 @@ class UserSettingsElement extends HTMLElement {
   @target write: HTMLInputElement
 
   valid() {
-    // One checkbox must be checked!
+    // At least one checkbox must be checked!
     return this.read.checked || this.write.checked
   }
 }
@@ -125,8 +144,8 @@ If you're not using decorators, then you'll need to make a `getter`, and call `f
 import {findTarget, findTargets} from '@github/catalyst'
 class HelloWorldElement extends HTMLElement {
 
-  get outputTarget() {
-    return findTarget(this, 'outputTarget')
+  get output() {
+    return findTarget(this, 'output')
   }
 
   get pages() {

docs/_guide/your-first-component.md

@@ -7,8 +7,15 @@ chapter: 3
 
 Catalyst's `@controller` decorator lets you create Custom Elements with virtually no boilerplate, by automatically calling `customElements.register`, and by adding ["Actions"]({{ site.baseurl }}/guide/actions) and ["Targets"]({{ site.baseurl }}/guide/targets) features described later. Using TypeScript (with `decorators` support enabled), simply add `@controller` to the top of your class:
 
+<!-- annotations
+controller: This must be added to all Catalyst controllers.
+extends HTMLElement: This must be added to all Catalyst controllers.
+connectedCallback: This runs when the element is added to the DOM | {{ site.baseurl }}/guide/lifecycle-hooks/#codeconnectedcallbackcode
+-->
+
 ```js
 import {controller} from '@github/catalyst'
+
 @controller
 class HelloWorldElement extends HTMLElement {
   connectedCallback() {
@@ -62,6 +69,8 @@ Using the `@controller` decorator saves on having to write this boilerplate for
 If you don't want to use TypeScript decorators, you can use `controller` as a regular function, and just pass it your class:
 
 ```js
+import {controller} from '@github/catalyst'
+
 controller(
   class HelloWorldElement extends HTMLElement {
     //...

docs/custom.css

@@ -43,11 +43,22 @@ body {
 .bg-gray { background-color: var(--color-bg-canvas-tertiary) !important }
 
 /* Code Blocks & Syntax */
-.markdown-body .highlight pre, .markdown-body pre { background-color: var(--color-bg-canvas-tertiary) }
+.markdown-body .highlight pre, .markdown-body pre {
+  background-color: var(--color-bg-canvas-tertiary);
+  overflow: inherit
+}
 
 /* Inline Code */
 .markdown-body code, .markdown-body tt { background-color: var(--color-markdown-code-bg) }
 
 /* Tables */
 .markdown-body table tr:nth-of-type(odd) th, .markdown-body table tr:nth-of-type(odd) td { background-color: var(--color-bg-canvas) }
 .markdown-body table tr:nth-of-type(even) th, .markdown-body table tr:nth-of-type(even) td { background-color: var(--color-bg-canvas-tertiary) }
+
+/* Override Primer .tooltipped default aria-label */
+.code-tooltip:after { content: attr(data-title); text-align: left; font-size: 100%; }
+/* :after text will be announced by AT, this adds a separation between textContent and :after text */
+.code-tooltip:before { content: ': '; font-size: 0; }
+.code-tooltip {
+  scroll-margin-top: 150px;
+}

docs/github-syntax.css

@@ -47,6 +47,9 @@ html[data-prefers-color-scheme=dark] {
 
 .highlight .hll { background-color: var(--color-syntax-highlight) }
 
+.highlight .nx,
+.highlight .p { color: var(--color-syntax-primary); }
+
 /* Comment, Comment.Multiline, Comment.Single */
 .highlight .c,
 .highlight .cm,
@@ -90,6 +93,7 @@ html[data-prefers-color-scheme=dark] {
 .highlight .sr,
 .highlight .s1,
 .highlight .ss,
+.highlight .dl,
 .highlight .il { color: var(--color-syntax-string) }
 
 /* Name.Attribute, Name.Constant, Name.Variable, Name.Variable.Class, Name.Variable.Global, Name.Variable.Instance */

docs/index.js

@@ -38,3 +38,83 @@ function applyColorSchemePreference() {
 
 storeColorSchemePreference()
 applyColorSchemePreference()
+
+function addAnnotations() {
+  for (const codeBlock of document.querySelectorAll('.highlighter-rouge')) {
+    const comment = parseCommentNode(codeBlock)
+    if (comment.annotations) annotate(codeBlock, comment.annotations)
+  }
+}
+
+function parseCommentNode(el) {
+  const stopAtEl = el.previousElementSibling
+  let t = el.previousSibling
+  if (!stopAtEl && !t) return
+  let comment
+  while (t && t !== stopAtEl) {
+    if (t.nodeType === 8) {
+      comment = t
+      break
+    } else {
+      t = t.previousSibling
+    }
+  }
+
+  if (!comment) return {}
+
+  const [type, ...details] = comment.textContent.trim().split('\n')
+
+  return {
+    noDemo: type.match(/no_demo/),
+    onlyDemo: type.match(/only_demo/),
+    annotations: type.match(/annotations/) && details
+  }
+}
+
+let matchIndex = 0
+function annotate(codeBlock, items) {
+  const noMatch = new Set(items)
+  const annotated = new WeakMap()
+  for (const el of codeBlock.querySelectorAll('code > span')) {
+    for (const item of items) {
+      let currentNode = el
+      const [pattern, rest] = item.split(/: /)
+      const [title, link] = (rest || '').split(/ \| /)
+      const parts = pattern.split(' ')
+      let toAnnotate = []
+      for (const part of parts) {
+        if (currentNode && currentNode.textContent.match(part)) {
+          toAnnotate.push(currentNode)
+          currentNode = currentNode.nextElementSibling
+        } else {
+          toAnnotate = []
+          break
+        }
+      }
+      for (const node of toAnnotate) {
+        noMatch.delete(item)
+        if (title) {
+          if (annotated.get(node)) {
+            continue
+          }
+          annotated.set(node, title)
+          const a = document.createElement('a')
+          a.className = `${node.className} code-tooltip tooltipped tooltipped-multiline tooltipped-se bg-gray text-underline`
+          a.id = `match-${matchIndex++}`
+          a.href = link || `#${a.id}`
+          a.setAttribute('data-title', title)
+          a.textContent = node.textContent
+          node.replaceWith(a)
+        } else {
+          node.classList.add('bg-gray')
+        }
+      }
+    }
+  }
+  for (const pattern of noMatch) {
+    // eslint-disable-next-line no-console
+    console.error(`Code annotations: No match found for "${pattern}"`)
+  }
+}
+
+addAnnotations()