Update event, docs, and tests (breaking change)

[muan]

Ref: https://github.com/github/web-systems/issues/190#issuecomment-472536055.

[koddsson]

Do we normally use this pattern to denote the element that changed? Could we just use target and currentTarget rather then relatedTarget?

Something like:

diff --git a/index.js b/index.js
index e6695c4..494c79a 100644
--- a/index.js
+++ b/index.js
@@ -61,12 +61,7 @@ class TabContainerElement extends HTMLElement {
     tab.focus()
     panel.hidden = false
 
-    this.dispatchEvent(
-      new CustomEvent('tab-container-change', {
-        bubbles: true,
-        detail: {relatedTarget: panel}
-      })
-    )
+    panel.dispatchEvent(new CustomEvent('tab-container-change', {bubbles: true}))
   }
 }
 
diff --git a/test/test.js b/test/test.js
index 468535f..83f05c1 100644
--- a/test/test.js
+++ b/test/test.js
@@ -44,7 +44,7 @@ describe('tab-container', function() {
       let counter = 0
       tabContainer.addEventListener('tab-container-change', event => {
         counter++
-        assert.equal(event.detail.relatedTarget, panels[1])
+        assert.equal(event.target, panels[1])
       })
 
       tabs[1].click()

[mislav]

I dig the relatedTarget approach. If tab-container-change keeps being fired from the <tab-container> element, then it's easier to detect in delegated handlers whether the current tab-container-change came from the current <tab-container> element or from a nested one:

on('tab-container-change', '.my-container', function(event) {
  if (event.target !== event.currentTarget) return
  // ...
})

[muan]

Talked to @koddsson F2F- for posterity, to add to @mislav's points, also:

• This ensures that event alway has the two things we care about no matter where/how it was caught, without needing extra queries. target is always <tab-container> and event.detail.relatedTarget is always the panel. (For comparison, previously if you listen for the event bubbling up to document, we will need a query to find the <tab-container>.
• Custom Element always fires Custom Event from/on itself, instead of from its non-custom children (unexpected).
• These guidelines are flexible enough to be applicable to all our elements with/without the need for relatedTarget or bubbles.

[mislav]

I dig the relatedTarget approach. If tab-container-change keeps being fired from the <tab-container> element, then it's easier to detect in delegated handlers whether the current tab-container-change came from the current <tab-container> element or from a nested one:

on('tab-container-change', '.my-container', function(event) {
  if (event.target !== event.currentTarget) return
  // ...
})

[dgraham]

Looks great for a 0.2.0 release.