From ae58b5e6c09c522519c27a4704e4ab0a0645a13e Mon Sep 17 00:00:00 2001 From: Benny Powers Date: Tue, 26 Sep 2023 11:47:33 +0300 Subject: [PATCH] docs: tabs for installation snippets --- .../shortcodes/renderInstallation.cjs | 166 +++++++++++++----- docs/assets/rhds-installation-tabs.js | 35 ++++ 2 files changed, 158 insertions(+), 43 deletions(-) create mode 100644 docs/assets/rhds-installation-tabs.js diff --git a/docs/_plugins/shortcodes/renderInstallation.cjs b/docs/_plugins/shortcodes/renderInstallation.cjs index 20a961a1ac..19e10bb457 100644 --- 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 */` + + +
+ + ## Installation ${!docsPage.manifest?.packageJson ? '' : /* md */` + + +Red Hat CDN + + +

CDN Prerelease

+

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 Red Hat Design System Google chat.

+

In the meantime, install this component using npm

+ + +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 \`\`, pointing to the CDN, or update any existing import map. +If you are not responsible for the page's \`\`, request that the +page owner makes the change on your behalf. ~~~html - + ~~~ -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 + +~~~ - return /* html */` +Note that Modules may be placed in the \`\`: since they are deferred by default, +they will not block rendering. -
+${!lightdomcss ? '' : /* md */`${lightdomcssblock} - ## Installation ${!docsPage.manifest?.packageJson ? '' : ` +~~~html + +~~~ + +`} + +NPM + - 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 - - - - + ~~~ -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. + + `} + +JSPM + + +

Public CDNs

+

JSPM and other public CDNs should not be used on corporate domains. + Use them for development purposes only!

+ + +Add an [import map][import-maps] to the \`\`, pointing to the CDN, +or update any existing import map. + ~~~html - +~~~ + +Once the import map is established, you can load the element with the following +module, containing a [bare module specifier][bare-specifier]: + +~~~html ~~~ -`} - 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 \`\`: 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 + ~~~ -${lightdomcss ? lightDomCSSBlock : ''} +`} + + -${content ?? ''} +${content ?? ''}`}
+[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 new file mode 100644 index 0000000000..bafb91ff77 --- /dev/null +++ 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);