Add tabbed widget JS and CSS to build (#2180)

Author: bmorelli25

README.asciidoc

@@ -656,7 +656,7 @@ endif::[]
 == Shared attributes
 
 To facilitate consistency across the documentation, there are shared attributes
-for common terms and URLs: https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc. 
+for common terms and URLs: https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc.
 There are also attributes related to the versions and branches that are used to
 build our books
 (for example: https://github.com/elastic/docs/blob/master/shared/versions/stack/master.asciidoc).
@@ -1893,3 +1893,82 @@ named for their IDs:
 
 To link to "Section two" from an external
 document, you would use the URL: `section-one.html#section-two`
+
+[[tabbed-widgets]]
+== Tabbed widgets
+
+Improve the usability of your docs by adding tabbed widgets.
+These handy widgets let you conditionally display content based on the selected tab.
+Best of all, tabbed widgets listen to each other – all widgets on the same page and with the same `data-tab-group` will change content when any tab on the page is selected.
+
+How do they work? I'm glad you asked.
+Tabbed widgets use https://docs.asciidoctor.org/asciidoc/latest/pass/pass-block/[HTML passthrough blocks] to pass raw HTML into the build.
+Because of this hack, you must use `include::` statements to render content within a tabbed widget.
+
+Here's an example:
+
+**`widget.asciidoc`**
+
+[source,asciidoc]
+----
+++++
+<div class="tabs" data-tab-group="custom-tab-group-name"> <1>
+  <div role="tablist" aria-label="Human readable name of tab group">
+    <button role="tab"
+            aria-selected="true" <2>
+            aria-controls="cloud-tab-config-agent" <3>
+            id="cloud-config-agent"> <4>
+      Tab #1 title
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="self-managed-tab-config-agent"
+            id="self-managed-config-agent"
+            tabindex="-1"> <5>
+      Tab #2 title
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="cloud-tab-config-agent"
+       aria-labelledby="cloud-config-agent">
+++++
+
+// You must use a tagged region for Asciidoc content to render. For example:
+// include::content.asciidoc[tag=central-config]
+
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="self-managed-tab-config-agent"
+       aria-labelledby="self-managed-config-agent"
+       hidden="">
+++++
+
+// You must use a tagged region for Asciidoc content to render. For example:
+// include::content.asciidoc[tag=reg-config]
+
+++++
+  </div>
+</div>
+++++
+----
+<1> Any tabbed widgets on the same page and with the same name will sync tabs when switched
+<2> Only one tab should have aria-selected set to true. This tab will be selected by default
+<3> The `button.aria-controls` value must match the `div.id` value of its corresponding content bucket
+<4> The `button.id` value must match the `div.aria-labelledby` value of its corresponding content bucket
+<5> All unselected tabs must have a `tabindex` of `-1`
+
+**`content.asciidoc`**
+
+[source,asciidoc]
+----
+// tag::central-config[]
+This is where the content for tab #1 goes.
+// end::central-config[]
+
+// tag::reg-config[]
+This is the content for tab #2 goes.
+// end::reg-config[]
+----

resources/web/docs.js.licenses

@@ -53,19 +53,19 @@
  * limitations under the License. */
 /* details-polyfill
  * The MIT License (MIT)
- * 
+ *
  * Copyright (c) 2018 Rico Sta. Cruz
- * 
+ *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
  * in the Software without restriction, including without limitation the rights
  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the Software is
  * furnished to do so, subject to the following conditions:
- * 
+ *
  * The above copyright notice and this permission notice shall be included in all
  * copies or substantial portions of the Software.
- * 
+ *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -86,7 +86,7 @@
  * distribute, sublicense, and/or sell copies of the Software, and to
  * permit persons to whom the Software is furnished to do so, subject to
  * the following conditions:
- * 
+ *
  * The above copyright notice and this permission notice shall be
  * included in all copies or substantial portions of the Software.
  *
@@ -130,10 +130,10 @@
  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the Software is
  * furnished to do so, subject to the following conditions:
- * 
+ *
  * The above copyright notice and this permission notice shall be included in
  * all copies or substantial portions of the Software.
- * 
+ *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -289,4 +289,4 @@
  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE. */
+ * THE SOFTWARE. */

resources/web/docs_js/components/tabbed_widget.js

@@ -0,0 +1,85 @@
+export const switchTabs = () => {
+  window.addEventListener("DOMContentLoaded", () => {
+    const tabs = document.querySelectorAll('[role="tab"]');
+    const tabList = document.querySelector('[role="tablist"]');
+    // Add a click event handler to each tab
+    tabs.forEach(tab => {
+      tab.addEventListener("click", changeTabs);
+    });
+    // Enable arrow navigation between tabs in the tab list
+    let tabFocus = 0;
+    tabList.addEventListener("keydown", e => {
+      // Move right
+      if (e.keyCode === 39 || e.keyCode === 37) {
+        tabs[tabFocus].setAttribute("tabindex", -1);
+        if (e.keyCode === 39) {
+          tabFocus++;
+          // If we're at the end, go to the start
+          if (tabFocus >= tabs.length) {
+            tabFocus = 0;
+          }
+          // Move left
+        } else if (e.keyCode === 37) {
+          tabFocus--;
+          // If we're at the start, move to the end
+          if (tabFocus < 0) {
+            tabFocus = tabs.length - 1;
+          }
+        }
+        tabs[tabFocus].setAttribute("tabindex", 0);
+        tabs[tabFocus].focus();
+      }
+    });
+  });
+}
+
+const setActiveTab = (target) => {
+  const parent = target.parentNode;
+  const grandparent = parent.parentNode;
+  // Remove all current selected tabs
+  parent
+    .querySelectorAll('[aria-selected="true"]')
+    .forEach(t => t.setAttribute("aria-selected", false));
+  // Set this tab as selected
+  target.setAttribute("aria-selected", true);
+  // Hide all tab panels
+  grandparent
+    .querySelectorAll('[role="tabpanel"]')
+    .forEach(p => p.setAttribute("hidden", true));
+  // Show the selected panel
+  grandparent.parentNode
+    .querySelector(`#${target.getAttribute("aria-controls")}`)
+    .removeAttribute("hidden");
+}
+
+const changeTabs = (e) => {
+  // get the containing list of the tab that was just clicked
+  const tabList = e.target.parentNode;
+
+  // get all of the sibling tabs
+  const buttons = Array.apply(null, tabList.querySelectorAll('button'));
+
+  // loop over the siblings to discover which index thje clicked one was
+  const { index } = buttons.reduce(({ found, index }, button) => {
+    if (!found && buttons[index] === e.target) {
+      return { found: true, index };
+    } else if (!found) {
+      return { found, index: index + 1 };
+    } else {
+      return { found, index };
+    }
+  }, { found: false, index: 0 });
+
+  // get the tab container
+  const container = tabList.parentNode;
+  // read the data-tab-group value from the container, e.g. "os"
+  const { tabGroup } = container.dataset;
+  // get a list of all the tab groups that match this value on the page
+  const groups = document.querySelectorAll('[data-tab-group=' + tabGroup + ']');
+
+  // for each of the found tab groups, find the tab button at the previously discovered index and select it for each group
+  groups.forEach((group) => {
+    const target = group.querySelectorAll('button')[index];
+    setActiveTab(target);
+  });
+}

resources/web/docs_js/index.js

@@ -2,6 +2,7 @@ import AlternativeSwitcher from "./components/alternative_switcher";
 import ConsoleWidget from "./components/console_widget";
 import Modal from "./components/modal";
 import mount from "./components/mount";
+import {switchTabs} from "./components/tabbed_widget";
 import {Cookies, $} from "./deps";
 import {lang_strings} from "./localization";
 import store from "./store";
@@ -281,3 +282,6 @@ $(function() {
 
   // Test comment used to detect unminifed JS in tests
 });
+
+// Tabbed widgets
+switchTabs();

resources/web/style/tabbed_widget.pcss

@@ -0,0 +1,76 @@
+#guide {
+  .tabs {
+    width: 100%;
+  }
+  [role=tablist] {
+    margin: 0 0 -0.1em;
+    overflow: visible;
+  }
+  [role=tab] {
+    position: relative;
+    padding: 0.3em 0.5em 0.4em;
+    border: 1px solid hsl(219, 1%, 72%);
+    border-radius: 0.2em 0.2em 0 0;
+    overflow: visible;
+    font-family: inherit;
+    font-size: inherit;
+    background: hsl(220, 20%, 94%);
+  }
+  [role=tab]:hover::before,
+  [role=tab]:focus::before,
+  [role=tab][aria-selected="true"]::before {
+    position: absolute;
+    bottom: 100%;
+    right: -1px;
+    left: -1px;
+    border-radius: 0.2em 0.2em 0 0;
+    border-top: 3px solid hsl(219, 1%, 72%);
+    content: '';
+  }
+  [role=tab][aria-selected="true"] {
+    border-radius: 0;
+    background: hsl(220, 43%, 99%);
+    outline: 0;
+  }
+  [role=tab][aria-selected="true"]:not(:focus):not(:hover)::before {
+    border-top: 5px solid hsl(218, 96%, 48%);
+  }
+  [role=tab][aria-selected="true"]::after {
+    position: absolute;
+    z-index: 3;
+    bottom: -1px;
+    right: 0;
+    left: 0;
+    height: 0.3em;
+    background: hsl(220, 43%, 99%);
+    box-shadow: none;
+    content: '';
+  }
+  [role="tab"]:hover,
+  [role="tab"]:focus,
+  [role="tab"]:active {
+    outline: 0;
+    border-radius: 0;
+    color: inherit;
+  }
+  [role="tab"]:hover::before,
+  [role="tab"]:focus::before {
+    border-color: hsl(218, 96%, 48%);
+  }
+  [role="tabpanel"] {
+    position: relative;
+    z-index: 2;
+    padding: 1em;
+    border: 1px solid hsl(219, 1%, 72%);
+    border-radius: 0 0.2em 0.2em 0.2em;
+    box-shadow: 0 0 0.2em hsl(219, 1%, 72%);
+    background: hsl(220, 43%, 99%);
+    margin-bottom: 1em;
+  }
+  [role="tabpanel"] p {
+    margin: 0;
+  }
+  [role="tabpanel"] * + p {
+    margin-top: 1em;
+  }
+}

resources/web/styles.pcss

@@ -24,6 +24,7 @@
 @import './style/settings_modal.pcss';
 @import './style/sidebar.pcss';
 @import './style/table.pcss';
+@import './style/tabbed_widget.pcss';
 @import './style/this_page.pcss';
 @import './style/toc.pcss';
 @import './style/util.pcss';

resources/web/template.html

@@ -50,7 +50,7 @@
     <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
     <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
     <!-- End Google Tag Manager -->
-    
+
     <!-- Global site tag (gtag.js) - Google Analytics -->
     <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
     <script>