docs: update installation / get started (#2561)

brianferry · bennypowers · web-flow · commit cb9556dc986c · 2023-08-04T07:35:57.000+03:00
* docs: adding renderInstallation, updating get-started

* docs: updating pfe-tools with install template

* docs: updating gists to 2.3.2

* docs: triple backtick on new line

* docs: generating quick start importmap

* docs: moving create import map into plugin, adding to quick start and get started

* docs: createImportMap adding content to return value for templating

* Update tools/pfe-tools/11ty/templates/install.njk

Co-authored-by: Benny Powers &lt;bennypowers@users.noreply.github.com&gt;

* Update docs/quick-start.md

Co-authored-by: Benny Powers &lt;bennypowers@users.noreply.github.com&gt;

* Update docs/get-started.md

Co-authored-by: Benny Powers &lt;bennypowers@users.noreply.github.com&gt;

* Update tools/pfe-tools/11ty/templates/install.njk

Co-authored-by: Benny Powers &lt;bennypowers@users.noreply.github.com&gt;

* docs: expand details on jspm / npm, add warning message about using both

---------

Co-authored-by: Benny Powers &lt;bennypowers@users.noreply.github.com&gt;
diff --git a/docs/_plugins/create-import-map.cjs b/docs/_plugins/create-import-map.cjs
@@ -0,0 +1,17 @@
+module.exports = function(eleventyConfig) {
+  eleventyConfig.addPairedAsyncShortcode('generateImportMap', async content => {
+    const { Generator } = await import('@jspm/generator');
+
+    const generator = new Generator({
+      defaultProvider: 'jspm',
+      env: ['production', 'browser', 'module']
+    });
+
+    const pins = await generator.addMappings(content);
+
+    const html = await generator.htmlInject(content, { pins, esModuleShims: true, whitespace: true });
+
+    return html;
+  });
+};
+
diff --git a/docs/docs/develop/import-maps.md b/docs/docs/develop/import-maps.md
@@ -12,7 +12,7 @@ tags:
   }
 </style>
 
-{% band %}
+{% band header="" %}
 
 Import maps provide a way for developers to use shorter and more descriptive module specifiers in their code, which can improve code readability and maintainability. Instead of having to remember and type out lengthy URLs for each module, developers can use simple and memorable module specifiers that map to the correct URLs in the import map. Developers can still use tools like bundlers and minifiers, but now they can ship bare modules specifiers to production, and map those specifiers to the original source or to minified bundles.
 
diff --git a/docs/get-started.md b/docs/get-started.md
@@ -21,7 +21,7 @@ title: Get started
   npm install --save @patternfly/elements
   ```
 
-  This will install not only the pf-card, but also the core utilities and 
+  This will install not only the web components, but also the core utilities and 
   styles,
   and will save it to your package.json.
 {% endband %}
@@ -41,46 +41,23 @@ title: Get started
   ```
 
   ### In HTML
-  To load the PatternFly Element web components in HTML you will need to use an importmap type script tag:
+  Alternatively, to load the PatternFly Elements web components in HTML you will need to use an importmap type script tag:
   `<script type="importmap"> ... </script>` and module type script tag `<script type="module"> ... </script>`. 
 
   In this example, we load the [card](/components/card/) modules using an importmap from JSPM.
 
   ```html
-  <!--
-    JSPM Generator Import Map
-    Edit URL: https://generator.jspm.io/#U2NgYGBkDM0rySzJSU1hcChILClJLcpLy6nUT81JzU3NKyl2MNIz0DPQL0jTTU4sSoHRelnFAN524ZI8AA
-  -->
-  <script type="importmap">
-  {
-    "imports": {
-      "@patternfly/elements/pf-card/pf-card.js": "https://ga.jspm.io/npm:@patternfly/elements@2.0.0/pf-card/pf-card.js"
-    },
-    "scopes": {
-      "https://ga.jspm.io/": {
-        "@lit/reactive-element": "https://ga.jspm.io/npm:@lit/reactive-element@1.6.1/reactive-element.js",
-        "@lit/reactive-element/decorators/": "https://ga.jspm.io/npm:@lit/reactive-element@1.6.1/decorators/",
-        "@patternfly/pfe-core/controllers/slot-controller.js": "https://ga.jspm.io/npm:@patternfly/pfe-core@2.0.0/controllers/slot-controller.js",
-        "lit": "https://ga.jspm.io/npm:lit@2.6.1/index.js",
-        "lit-element/lit-element.js": "https://ga.jspm.io/npm:lit-element@3.2.2/lit-element.js",
-        "lit-html": "https://ga.jspm.io/npm:lit-html@2.6.1/lit-html.js",
-        "lit-html/": "https://ga.jspm.io/npm:lit-html@2.6.1/",
-        "lit/": "https://ga.jspm.io/npm:lit@2.6.1/",
-        "tslib": "https://ga.jspm.io/npm:tslib@2.5.0/modules/index.js"
-      }
-    }
-  }
-  </script>
-  
+  {% generateImportMap %}
   <script type="module">
     import "@patternfly/elements/pf-card/pf-card.js";
   </script>
+  {% endgenerateImportMap %}
   ```
 
   To learn more about how to create importmaps, read our [creating an import map](/docs/develop/import-maps/) section, and go into more detail at [developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) or the [import map specification](https://html.spec.whatwg.org/multipage/webappapis.html#import-maps). 
   
   ### Add PatternFly Elements markup
-  Add a [card component](/components/card).
+  When you have the import map script loaded on the page, you can add a [card component](/components/card) using html.
 
   ```html
   <pf-card>
@@ -96,6 +73,11 @@ title: Get started
     <pf-button slot="footer">OK</pf-button>
   </pf-card>
 
+### Importmap and Markup
+
+Altogether your import map code could look something like this [Lit Playground Demo](https://lit.dev/playground/#gist=453dc9f83854ff7ba09d02a0fc6a79d5).
+
+
 {% endband %}
 
 {% band header="Add attributes" %}
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -39,38 +39,12 @@ production.
     h1, h2, h3, h4 {
       font-family: "Red Hat Display";
     }
-  </style>
-  <!--
-    JSPM Generator Import Map
-    Edit URL: https://generator.jspm.io/#U2VhYGBkDM0rySzJSU1hcChILClJLcpLy6nUT81JzU3NKyl2MNIz0DMAADWC5vEpAA
-  -->
-  <script type="importmap">
-  {
-    "imports": {
-      "@patternfly/elements": "https://ga.jspm.io/npm:@patternfly/elements@2.0.0/pfe.min.js"
-    },
-    "scopes": {
-      "https://ga.jspm.io/": {
-        "@floating-ui/core": "https://ga.jspm.io/npm:@floating-ui/core@1.2.3/dist/floating-ui.core.browser.mjs",
-        "@floating-ui/dom": "https://ga.jspm.io/npm:@floating-ui/dom@1.2.4/dist/floating-ui.dom.browser.mjs",
-        "@lit/reactive-element": "https://ga.jspm.io/npm:@lit/reactive-element@1.6.1/development/reactive-element.js",
-        "@lit/reactive-element/decorators/": "https://ga.jspm.io/npm:@lit/reactive-element@1.6.1/development/decorators/",
-        "lit": "https://ga.jspm.io/npm:lit@2.6.1/index.js",
-        "lit-element/lit-element.js": "https://ga.jspm.io/npm:lit-element@3.2.2/development/lit-element.js",
-        "lit-html": "https://ga.jspm.io/npm:lit-html@2.6.1/development/lit-html.js",
-        "lit-html/": "https://ga.jspm.io/npm:lit-html@2.6.1/development/",
-        "lit/": "https://ga.jspm.io/npm:lit@2.6.1/",
-        "tslib": "https://ga.jspm.io/npm:tslib@2.5.0/tslib.es6.js"
-      }
-    }
-  }
-  </script>
-  <!-- ES Module Shims: Import maps polyfill for modules browsers without import maps support (all except Chrome 89+) -->
-  <script async src="https://ga.jspm.io/npm:es-module-shims@1.5.1/dist/es-module-shims.js" crossorigin="anonymous"></script>
-  
+  </style> 
+  {% generateImportMap %}
   <script type="module">
-    import * as Elements from "@patternfly/elements";
+    import '@patternfly/elements';
   </script>
+  {% endgenerateImportMap %}
 </head>
 <body>
   <header>
@@ -148,6 +122,6 @@ production.
 </html>
 ```
 
-[Lit Playground](https://lit.dev/playground/#gist=1540e63845ed8eeb88957a11ec234674&view-mode=code) example of the HTML above
+[Lit Playground](https://lit.dev/playground/#gist=77a0cb2d080de958f4415a4716908bf9) example of the HTML above
 
 </section>
diff --git a/elements/pf-accordion/docs/pf-accordion.md b/elements/pf-accordion/docs/pf-accordion.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
 <pf-accordion>
   <pf-accordion-header>
@@ -84,4 +86,4 @@
 
 {% renderCssCustomProperties %}{% endrenderCssCustomProperties %}
 
-{% renderCssParts %}{% endrenderCssParts %}
+{% renderCssParts %}{% endrenderCssParts %}
diff --git a/elements/pf-avatar/docs/pf-avatar.md b/elements/pf-avatar/docs/pf-avatar.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-avatar alt="Libbie Koscinski"></pf-avatar>
 {% endrenderOverview %}
diff --git a/elements/pf-badge/docs/pf-badge.md b/elements/pf-badge/docs/pf-badge.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-badge state="read" number="17">17</pf-badge>
   <pf-badge number="900" threshold="100">900</pf-badge>
diff --git a/elements/pf-button/docs/pf-button.md b/elements/pf-button/docs/pf-button.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 <style>
 pf-button + pf-button {
   margin-inline-start: 4px;
diff --git a/elements/pf-card/docs/pf-card.md b/elements/pf-card/docs/pf-card.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
 
   Cards are flexible surfaces used to group information in a small layout. They give small previews of information or provide secondary content in relation to the content it's near. Several cards can be used together to group related information.
diff --git a/elements/pf-clipboard-copy/docs/pf-clipboard-copy.md b/elements/pf-clipboard-copy/docs/pf-clipboard-copy.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-clipboard-copy value="This is editable"></pf-clipboard-copy>
 {% endrenderOverview %}
diff --git a/elements/pf-code-block/docs/pf-code-block.md b/elements/pf-code-block/docs/pf-code-block.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   Code Block is a component that contains two or more lines of read-only code. The code in a code block can be copied to the clipboard.
 
diff --git a/elements/pf-icon/docs/pf-icon.md b/elements/pf-icon/docs/pf-icon.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 <style>
   main.basic pf-icon[circled] {
     margin-right: 8px;
diff --git a/elements/pf-jump-links/docs/pf-jump-links.md b/elements/pf-jump-links/docs/pf-jump-links.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
 <section>
   <h2>Basic</h2>
diff --git a/elements/pf-label/docs/pf-label.md b/elements/pf-label/docs/pf-label.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-label>Default</pf-label>
 {% endrenderOverview %}
diff --git a/elements/pf-modal/docs/pf-modal.md b/elements/pf-modal/docs/pf-modal.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-modal trigger="overview-trigger">
     <h2 slot="header">Modal with a header</h2>
diff --git a/elements/pf-panel/docs/pf-panel.md b/elements/pf-panel/docs/pf-panel.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-panel>
     <p>Main content</p>
diff --git a/elements/pf-popover/docs/pf-popover.md b/elements/pf-popover/docs/pf-popover.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
 
 <pf-popover heading="Popover heading"
diff --git a/elements/pf-progress-stepper/docs/pf-progress-stepper.md b/elements/pf-progress-stepper/docs/pf-progress-stepper.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
 <pf-progress-stepper>
   <pf-progress-step variant="success">Completed</pf-progress-step>
diff --git a/elements/pf-spinner/docs/pf-spinner.md b/elements/pf-spinner/docs/pf-spinner.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   A spinner is used to indicate to users that an action is in progress.
 
diff --git a/elements/pf-switch/docs/pf-switch.md b/elements/pf-switch/docs/pf-switch.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   A switch toggles the state of a setting (between on and off). Switches 
   provide a more explicit, visible representation on a setting.
diff --git a/elements/pf-tabs/docs/pf-tabs.md b/elements/pf-tabs/docs/pf-tabs.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 <style>
   .overflow-tab-wrapper {
     width: 94vw;
diff --git a/elements/pf-tile/docs/pf-tile.md b/elements/pf-tile/docs/pf-tile.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   <pf-tile>
     <h3 slot="title">Default</h3>
diff --git a/elements/pf-timestamp/docs/pf-timestamp.md b/elements/pf-timestamp/docs/pf-timestamp.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   A timestamp provides consistent formats for displaying date and time values.
 
diff --git a/elements/pf-tooltip/docs/pf-tooltip.md b/elements/pf-tooltip/docs/pf-tooltip.md
@@ -1,3 +1,5 @@
+{% renderInstallation %} {% endrenderInstallation %}
+
 {% renderOverview %}
   ### Default <pf-tooltip>
     <pf-button>Tooltip</pf-button>
diff --git a/eleventy.config.cjs b/eleventy.config.cjs
@@ -4,6 +4,7 @@ const DirectoryOutputPlugin = require('@11ty/eleventy-plugin-directory-output');
 
 const PfeAssetsPlugin = require('./docs/_plugins/pfe-assets.cjs');
 const EmptyParagraphPlugin = require('./docs/_plugins/empty-p.cjs');
+const createImportMapPlugin = require('./docs/_plugins/create-import-map.cjs');
 
 const AnchorsPlugin = require('@patternfly/pfe-tools/11ty/plugins/anchors.cjs');
 const CustomElementsManifestPlugin = require('@patternfly/pfe-tools/11ty/plugins/custom-elements-manifest.cjs');
@@ -54,6 +55,9 @@ module.exports = function(eleventyConfig) {
   /** Strip empty paragraphs */
   eleventyConfig.addPlugin(EmptyParagraphPlugin);
 
+  /** Create import maps from script tags */
+  eleventyConfig.addPlugin(createImportMapPlugin);
+
   /** Add IDs to heading elements */
   eleventyConfig.addPlugin(AnchorsPlugin, {
     exclude: /\/components\/.*\/demo\//,
diff --git a/tools/pfe-tools/11ty/DocsPage.ts b/tools/pfe-tools/11ty/DocsPage.ts
@@ -39,6 +39,7 @@ export declare class DocsPageRenderer {
   renderProperties(content: string, kwargs?: RenderKwargs): string;
   renderCssCustomProperties(content: string, kwargs?: RenderKwargs): string;
   renderEvents(content: string, kwargs?: RenderKwargs): string;
+  renderInstallation(content: string, kwargs?: RenderKwargs): string;
   renderCssParts(content: string, kwargs?: RenderKwargs): string;
   renderMethods(content: string, kwargs?: RenderKwargs): string;
   renderSlots(content: string, kwargs?: RenderKwargs): string;
@@ -174,6 +175,11 @@ export class DocsPage implements DocsPageRenderer {
     return this.templates.render('events.njk', { content, events, deprecated, ...kwargs });
   }
 
+  /** Render the installation instructions for the element */
+  renderInstallation(content: string, kwargs: RenderKwargs = {}) {
+    return `${this.templates.render('install.njk', { content, ...kwargs })}`;
+  }
+
   /** Render the list of element methods */
   renderMethods(content: string, kwargs: RenderKwargs = {}) {
     const allMethods = this.manifest.getMethods(this.#packageTagName(kwargs)) ?? [];
diff --git a/tools/pfe-tools/11ty/plugins/custom-elements-manifest.cjs b/tools/pfe-tools/11ty/plugins/custom-elements-manifest.cjs
@@ -136,6 +136,7 @@ module.exports = function configFunction(eleventyConfig, pluginOpts = {}) {
     'renderMethods',
     'renderOverview',
     'renderProperties',
+    'renderInstallation',
     'renderSlots',
   ];
 
diff --git a/tools/pfe-tools/11ty/templates/install.njk b/tools/pfe-tools/11ty/templates/install.njk
@@ -0,0 +1,27 @@
+{% set level = level or 2 %}
+{% set header = header or 'Installation' %}
+
+<section class="band">
+  {{ header | mdHeading(level) | safe }} {% if not content and not slots.length %}
+
+  <em>None</em> {%- else -%}
+
+We recommend loading elements via a CDN such as [JSPM](https://jspm.dev) and 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/).
+
+If you are using node and NPM, you can install this component using npm:
+
+```shell
+npm install {{ package.name }}
+```
+
+Then import this component into your project by using a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules):
+```js
+import '@patternfly/elements/{{ tagName }}/{{ tagName }}.js'
+```
+
+<strong>Please Note:</strong> You should either load elements via a CDN or install them locally through NPM. <em>Do not do both.</em>
+
+</section>
+{%- endif -%}

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ tags:`
`12`	`12`	`}`
`13`	`13`	`</style>`
`14`	`14`
`15`		`-{% band %}`
	`15`	`+{% band header="" %}`
`16`	`16`
`17`	`17`	Import maps provide a way for developers to use shorter and more descriptive module specifiers in their code, which can improve code readability and maintainability. Instead of having to remember and type out lengthy URLs for each module, developers can use simple and memorable module specifiers that map to the correct URLs in the import map. Developers can still use tools like bundlers and minifiers, but now they can ship bare modules specifiers to production, and map those specifiers to the original source or to minified bundles.
`18`	`18`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+{% renderInstallation %} {% endrenderInstallation %}`
	`2`	`+`
`1`	`3`	`{% renderOverview %}`
`2`	`4`	`<pf-avatar alt="Libbie Koscinski"></pf-avatar>`
`3`	`5`	`{% endrenderOverview %}`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+{% renderInstallation %} {% endrenderInstallation %}`
	`2`	`+`
`1`	`3`	`<style>`
`2`	`4`	`pf-button + pf-button {`
`3`	`5`	`margin-inline-start: 4px;`