docs: tabs for installation snippets

RedHat-UX · Sep 26, 2023 · ae58b5e · ae58b5e
1 parent a3b12e5
commit ae58b5e
Show file tree

Hide file tree

Showing 2 changed files with 158 additions and 43 deletions.
diff --git a/docs/_plugins/shortcodes/renderInstallation.cjs b/docs/_plugins/shortcodes/renderInstallation.cjs
@@ -3,7 +3,10 @@
 /**
  * @param {string} content
  */
-function renderInstallation(content, { lightdomcss = false } = {}) {
+function renderInstallation(content, {
+  lightdomcss = false,
+  cdnVersion = 'v1-alpha',
+} = {}) {
   /**
    * NB: since the data for this shortcode is no a POJO,
    * but a DocsPage instance, 11ty assigns it to this.ctx._
@@ -12,82 +15,159 @@ function renderInstallation(content, { lightdomcss = false } = {}) {
    */
   const docsPage = this.ctx._;
 
-  const lightDomCSSBlock = `
-
+  const lightdomcssblock = /* md */`
 ### Lightdom CSS
 
-Lightdom CSS is required for this element to ensure a reduced [Cumulative Layout Shift (CLS)](https://web.dev/cls/) experience before the element has fully initialized.
+Lightdom CSS is required for this element to ensure a reduced
+[Cumulative Layout Shift (CLS)][cls] experience before the element has
+fully initialized.
+  `;
+
+  return /* md */`
+<script type="module" src="/assets/rhds-installation-tabs.js"></script>
+
+<section class="band">
+
+  ## Installation ${!docsPage.manifest?.packageJson ? '' : /* md */`
+
+<rhds-installation-tabs>
+<rh-tab slot="tab">Red Hat CDN</rh-tab>
+<rh-tab-panel>
+  <rh-alert state="warning">
+    <h3 slot="header">CDN Prerelease</h3>
+    <p>We are currently working on our CDN, which will be soon moving
+       into beta. This will be the preferred method of installation in
+       the near future. If you are a Red Hat associate and have questions
+       or comments about the CDN or installation process please join us
+       in our <a href="https://red.ht/43bBaB0">Red Hat Design System Google chat</a>.</p>
+    <p>In the meantime, install this component using npm</p>
+  </rh-alert>
+
+The recommended way to load RHDS is via the Red Hat Digital Experience CDN,
+and using an [import map][import-maps].
+
+If you have full control over the page you are using, add an import map
+to the \`<head>\`, pointing to the CDN, or update any existing import map.
+If you are not responsible for the page's \`<head>\`, request that the
+page owner makes the change on your behalf.
 
 ~~~html
-<link rel="stylesheet" href="/path/to/${docsPage.tagName}/${docsPage.tagName}-lightdom.css">
+<script type="importmap">
+  {
+    "imports": {
+      "@rhds/elements/": "https://www.redhatstatic.com/dx/${cdnVersion}/@rhds/[email protected]/elements/",
+      "@patternfly/elements/": "https://www.redhatstatic.com/dx/${cdnVersion}/@patternfly/[email protected]/"
+    }
+  }
+</script>
 ~~~
 
-Replace \`/path/to\` in the \`href\` attribute with the installation path to the \`${docsPage.tagName}\` directory in your project.
+Once the import map is established, you can load the element with the following
+module, containing a [bare module specifier][bare-specifier]:
 
-`;
+~~~html
+<script type="module">
+  import '@rhds/elements/${docsPage.tagName}/${docsPage.tagName}.js';
+</script>
+~~~
 
-  return /* html */`
+Note that Modules may be placed in the \`<head>\`: since they are deferred by default,
+they will not block rendering.
 
-<section class="band">
+${!lightdomcss ? '' : /* md */`${lightdomcssblock}
 
-  ## Installation ${!docsPage.manifest?.packageJson ? '' : `
+~~~html
+<link rel="stylesheet" href="https://www.redhatstatic.com/dx/${cdnVersion}/@rhds/[email protected]/${docsPage.tagName}/${docsPage.tagName}-lightdom.css">
+~~~
+
+`}
+</rh-tab-panel>
+<rh-tab slot="tab">NPM</rh-tab>
+<rh-tab-panel>
 
-  We are currently working on our CDN which will be soon moving into beta.  This will be the preferred method of installation in the near future.  If you are a Red Hat employee and have questions or comments about the CDN or installation process please join us in our [Red Hat Design System Google chat](https://red.ht/43bBaB0).
-  
-  In the meantime, install this component using npm:
+Install RHDS using your team's preferred NPM package manager, e.g.
 
-npm
 ~~~shell
 npm install ${docsPage.manifest.packageJson.name}
 ~~~
 
-Red Hat CDN (recommended)
+Once that's been accomplished, you will need to use a bundler to resolve
+the bare module specifiers and optionally optimize the package for your
+site's particular use case and needs. Comprehensive guides to bundling are
+beyond the scope of this page; read more about bundlers on their websites:
+
+- [Rollup][rollup]
+- [esbuild][esbuild]
+- [Parcel][parcel]
+- [Webpack][webpack]
+
+${!lightdomcss ? '' : /* md */`${lightdomcssblock}
+
 ~~~html
-<head>
-  <script type="importmap">
-    {
-      "imports": {
-        "@rhds/elements/": "https://www.redhatstatic.com/dx/v1-alpha/@rhds/[email protected]/elements/",
-        "@patternfly/elements/": "https://www.redhatstatic.com/dx/v1-alpha/@patternfly/[email protected]/"
-      }
-    }
-  </script>
-  <script type="module">
-    import '@rhds/elements/${docsPage.tagName}/${docsPage.tagName}.js';
-  </script>
-</head>
+<link rel="stylesheet" href="/path/to/@rhds/elements/elements/${docsPage.tagName}/${docsPage.tagName}-lightdom.css">
 ~~~
 
-jspm.dev (for development purposes only)
+Replace \`/path/to\` in the \`href\` attribute with the installation path
+to the \`${docsPage.tagName}\` directory in your project.
+
+  `}
+</rh-tab-panel>
+<rh-tab slot="tab">JSPM</rh-tab>
+<rh-tab-panel>
+  <rh-alert state="warning">
+    <h3 slot="header">Public CDNs</h3>
+    <p>JSPM and other public CDNs should not be used on corporate domains.
+       Use them for <strong>development purposes only</strong>!</p>
+  </rh-alert>
+
+Add an [import map][import-maps] to the \`<head>\`, pointing to the CDN,
+or update any existing import map.
+
 ~~~html
-<script type="importmap"> 
-  { 
-    "imports": { 
-      "@rhds/elements/": "https://jspm.dev/@rhds/elements/", 
-      "@patternfly/elements/": "https://jspm.dev/@patternfly/elements/" 
-    } 
-  } 
+<script type="importmap">
+  {
+    "imports": {
+      "@rhds/elements/": "https://jspm.dev/@rhds/elements/",
+      "@patternfly/elements/": "https://jspm.dev/@patternfly/elements/"
+    }
+  }
 </script>
+~~~
+
+Once the import map is established, you can load the element with the following
+module, containing a [bare module specifier][bare-specifier]:
+
+~~~html
 <script type="module">
   import '@rhds/elements/${docsPage.tagName}/${docsPage.tagName}.js';
 </script>
 ~~~
-`}
 
-  We recommend using an import map to manage your dependencies. For more information on import maps and how to use them, see the [import map reference on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap/).
+Note that Modules may be placed in the \`<head>\`: since they are deferred by default,
+they will not block rendering.
 
-  Then import this component into your project by using a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules):
+${!lightdomcss ? '' : /* md */ `${lightdomcssblock}
 
-~~~js
-import '@rhds/elements/${docsPage.tagName}/${docsPage.tagName}.js';
+~~~html
+<link rel="stylesheet" href="https://jspm.dev/@rhds/elements@1.1.0/elements/${docsPage.tagName}/${docsPage.tagName}-lightdom.css">
 ~~~
 
-${lightdomcss ? lightDomCSSBlock : ''}
+`}
+  </rh-tab-panel>
+</rhds-installation-tabs>
 
-${content ?? ''}
+${content ?? ''}`}
 
 </section>
 
+[import-maps]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
+[bare-specifier]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+[rollup]: https://rollupjs.org/
+[esbuild]: https://esbuild.github.io/
+[parcel]: https://parceljs.org/
+[webpack]: https://webpack.js.org/
+[cls]: https://web.dev/cls/
+
       `;
 }
 

diff --git a/docs/assets/rhds-installation-tabs.js b/docs/assets/rhds-installation-tabs.js
@@ -0,0 +1,35 @@
+import '@rhds/elements/rh-alert/rh-alert.js';
+import { RhTabs } from '@rhds/elements/rh-tabs/rh-tabs.js';
+
+import { TabExpandEvent } from '@patternfly/elements/pf-tabs/BaseTab.js';
+
+const TABS_KEY = 'rhds-installation-tabs-selected-index';
+
+export class InstallationTabs extends RhTabs {
+  static stored = localStorage.getItem(TABS_KEY);
+
+  #onExpand(event) {
+    if (event instanceof TabExpandEvent) {
+      localStorage.setItem(TABS_KEY, this.activeIndex.toString());
+    }
+  }
+
+  async firstUpdated() {
+    super.firstUpdated?.();
+    await Promise.all(Array.from(
+      this.querySelectorAll('rh-tab'),
+      x => x.updateComplete,
+    ));
+    if (InstallationTabs.stored !== null) {
+      const index = parseInt(InstallationTabs.stored);
+      if (!Number.isNaN(index) &&
+          index !== this.activeIndex &&
+          this.panels[index]) {
+        this.activeIndex = index;
+      }
+    }
+    this.addEventListener('expand', this.#onExpand);
+  }
+}
+
+customElements.define('rhds-installation-tabs', InstallationTabs);