perf(docs): refactor the JS examples

apiExamples/custom.html

@@ -0,0 +1,6 @@
+<custom-dropdown aria-label="custom label">
+  Lorem ipsum solar
+  <div slot="trigger">
+    Trigger
+  </div>
+</custom-dropdown>

apiExamples/programmaticallyHide.html

@@ -2,7 +2,7 @@
   <p>
     Lorem ipsum solar
   </p>
-  <auro-button onclick="document.querySelector('#hideExample').hide()">
+  <auro-button id="hideExampleBtn">
     Dismiss Dropdown
   </auro-button>
   <auro-input

apiExamples/programmaticallyHide.js

@@ -0,0 +1,8 @@
+export function hideExample() {
+  const btn = document.querySelector('#hideExampleBtn');
+  const dropdown = document.querySelector('#hideExample');
+
+  btn.addEventListener('click', () => {
+    dropdown.hide();
+  });
+}

apiExamples/programmaticallyShow.js

@@ -1,6 +1,8 @@
-export function showExample(elem) {
-  const triggerInput = document.querySelector('#showExampleTriggerInput')
+export function showExample() {
+  const triggerInput = document.querySelector('#showExampleTriggerInput');
+  const dropdownElem = document.querySelector('#showMethodExample');
+
   triggerInput.addEventListener('keydown', () => {
-    elem.show();
-  })
+    dropdownElem.show();
+  });
 }

demo/api.html

@@ -41,12 +41,15 @@
         });
     </script>
     <script type="module" src="../src/auro-dropdown.js"></script>
+    <script type="module">
+      import { initExamples } from "./api.min.js"
+      initExamples();
+    </script>
 
     <!-- If additional elements are needed for the demo, add them here. -->
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/dist/auro-accordion__bundled.js" type="module"></script>
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/dist/auro-button__bundled.js" type="module"></script>
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-icon@latest/dist/auro-icon__bundled.js" type="module"></script>
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-input@latest/dist/auro-input__bundled.js" type="module"></script>
-    <script type="module" src="./examples.js"></script>
   </body>
 </html>

demo/api.js

@@ -0,0 +1,22 @@
+/* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
+
+import { showExample } from './../apiExamples/programmaticallyShow.js';
+import { hideExample } from './../apiExamples/programmaticallyHide.js';
+
+export function initExamples(initCount) {
+  initCount = initCount || 0;
+
+  try {
+    // javascript example function calls to be added here upon creation to test examples
+    showExample();
+    hideExample();
+  } catch (err) {
+    if (initCount <= 20) {
+      // setTimeout handles issue where content is sometimes loaded after the functions get called
+      setTimeout(() => {
+        initExamples(initCount + 1);
+      }, 100);
+    }
+  }
+}
+

demo/api.md

@@ -775,7 +775,7 @@ When combined with the `error` property the `helpText` slot content is colored r
 
 #### show
 
-The `show` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').show()`.
+The `show` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').show()`. This example will execute the `show` method on a `keydown` event with focus in the input element.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/programmaticallyShow.html) -->
@@ -812,30 +812,34 @@ The `show` method may also be called from anywhere in your code by executing `do
 <!-- The below code snippet is automatically added from ./../../apiExamples/programmaticallyShow.js -->
 
 ```js
-export function showExample(elem) {
-  const triggerInput = document.querySelector('#showExampleTriggerInput')
+export function showExample() {
+  const triggerInput = document.querySelector('#showExampleTriggerInput');
+  const dropdownElem = document.querySelector('#showMethodExample');
+
   triggerInput.addEventListener('keydown', () => {
-    elem.show();
-  })
+    dropdownElem.show();
+  });
 }
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
 #### hide
 
-The `hide` method can be called from within the default slot content. This is useful for cases such as `auro-select`.
+The `hide` method can be called from within the default slot content. This is useful for cases such as `auro-select` when the dropdown should be collapsed after making a selection.
 
 The `hide` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').hide()`.
 
+This example demonstrations collapsing the dropdown by clicking a button within the dropdown bib content.
+
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/programmaticallyHide.html) -->
   <!-- The below content is automatically added from ./../../apiExamples/programmaticallyHide.html -->
   <auro-dropdown id="hideExample" aria-label="custom label" rounded bordered inset>
     <p>
       Lorem ipsum solar
     </p>
-    <auro-button onclick="document.querySelector('#hideExample').hide()">
+    <auro-button id="hideExampleBtn">
       Dismiss Dropdown
     </auro-button>
     <auro-input
@@ -855,7 +859,7 @@ The `hide` method may also be called from anywhere in your code by executing `do
   <p>
     Lorem ipsum solar
   </p>
-  <auro-button onclick="document.querySelector('#hideExample').hide()">
+  <auro-button id="hideExampleBtn">
     Dismiss Dropdown
   </auro-button>
   <auro-input

demo/api.min.js

@@ -0,0 +1,39 @@
+function showExample() {
+  const triggerInput = document.querySelector('#showExampleTriggerInput');
+  const dropdownElem = document.querySelector('#showMethodExample');
+
+  triggerInput.addEventListener('keydown', () => {
+    dropdownElem.show();
+  });
+}
+
+function hideExample() {
+  const btn = document.querySelector('#hideExampleBtn');
+  const dropdown = document.querySelector('#hideExample');
+
+  btn.addEventListener('click', () => {
+    dropdown.hide();
+  });
+}
+
+/* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
+
+
+function initExamples(initCount) {
+  initCount = initCount || 0;
+
+  try {
+    // javascript example function calls to be added here upon creation to test examples
+    showExample();
+    hideExample();
+  } catch (err) {
+    if (initCount <= 20) {
+      // setTimeout handles issue where content is sometimes loaded after the functions get called
+      setTimeout(() => {
+        initExamples(initCount + 1);
+      }, 100);
+    }
+  }
+}
+
+export { initExamples };

demo/index.html

@@ -41,8 +41,13 @@
           Prism.highlightAll();
         })
     </script>
-    <script type="module" src="../index.js"></script>
+    <script type="module">
+      import { initExamples } from "./index.min.js"
+      import { registerComponent } from '../index.js';
 
+      initExamples();
+      registerComponent('custom-dropdown');
+    </script>
     <!-- If additional elements are needed for the demo, add them here. -->
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/dist/auro-accordion__bundled.js" type="module"></script>
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/dist/auro-button__bundled.js" type="module"></script>

demo/index.js

@@ -0,0 +1,20 @@
+/* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
+
+// import { auroMenuResetExample } from '../apiExamples/reset';
+
+export function initExamples(initCount) {
+  initCount = initCount || 0;
+
+  try {
+    // javascript example function calls to be added here upon creation to test examples
+    // auroMenuResetExample();
+  } catch (err) {
+    if (initCount <= 20) {
+      // setTimeout handles issue where content is sometimes loaded after the functions get called
+      setTimeout(() => {
+        initExamples(initCount + 1);
+      }, 100);
+    }
+  }
+}
+

demo/index.md

@@ -289,12 +289,53 @@ This common example uses the default `auro-dropdown` element with the attributes
 
 The dropdown can be opened with the following actions:
 
-1. Clicking/tapping on the trigger will open the dropdown UI.
-1. Tabbing to the trigger and using the `enter` or `spacebar` keys will open the dropdown UI.
+1. Clicking/tapping on the trigger.
+1. Tabbing to the trigger and using the `enter` or `spacebar` keys.
+1. Programmatically via another control in the UI calling the `show()` method (see api).
 
 The dropdown can be closed with the following actions:
 
 1. Clicking anywhere in the view outside of the dropdown.
-1. When the `toggle` attribute is added, clicking on the trigger.
-1. Programmatically via another control in the UI calling the `hide()` method (see api).
+1. Clicking on the trigger when the `toggle` attribute is used.
 1. Using the `esc` key.
+1. Programmatically via another control in the UI calling the `hide()` method (see api).
+
+## Recommended Use and Version Control
+
+There are two important parts of every Auro component. The <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom clement. The class is exported and then used as part of defining the Web Component. When importing this component as described in the <a href="#install">install</a> section, the class is imported and the `auro-button` custom element is defined automatically.
+
+To protect from versioning conflicts with other instances of the component being loaded, it is recommended to use our `registerComponent(name)` method and pass in a unique name.
+
+```js
+import './node_modules/@aurodesignsystem/auro-button';
+registerComponent('custom-button');
+```
+
+This will create a new custom element that you can use in your HTML that will function identically to the `<auro-button>` element.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/custom.html) -->
+  <!-- The below content is automatically added from ./../../apiExamples/custom.html -->
+  <custom-dropdown aria-label="custom label">
+    Lorem ipsum solar
+    <div slot="trigger">
+      Trigger
+    </div>
+  </custom-dropdown>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/custom.html) -->
+<!-- The below code snippet is automatically added from ./../../apiExamples/custom.html -->
+
+```html
+<custom-dropdown aria-label="custom label">
+  Lorem ipsum solar
+  <div slot="trigger">
+    Trigger
+  </div>
+</custom-dropdown>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>

demo/index.min.js

@@ -0,0 +1,8 @@
+/* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
+
+// import { auroMenuResetExample } from '../apiExamples/reset';
+
+function initExamples(initCount) {
+}
+
+export { initExamples };

docs/partials/api.md

@@ -319,7 +319,7 @@ When combined with the `error` property the `helpText` slot content is colored r
 #### show
 
 
-The `show` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').show()`.
+The `show` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').show()`. This example will execute the `show` method on a `keydown` event with focus in the input element.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/programmaticallyShow.html) -->
@@ -338,10 +338,12 @@ The `show` method may also be called from anywhere in your code by executing `do
 
 #### hide
 
-The `hide` method can be called from within the default slot content. This is useful for cases such as `auro-select`.
+The `hide` method can be called from within the default slot content. This is useful for cases such as `auro-select` when the dropdown should be collapsed after making a selection.
 
 The `hide` method may also be called from anywhere in your code by executing `document.querySelector('#idOfTheDropdownElement').hide()`.
 
+This example demonstrations collapsing the dropdown by clicking a button within the dropdown bib content.
+
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/programmaticallyHide.html) -->
   <!-- AURO-GENERATED-CONTENT:END -->

docs/partials/index.md

@@ -110,12 +110,36 @@ This common example uses the default `auro-dropdown` element with the attributes
 
 The dropdown can be opened with the following actions:
 
-1. Clicking/tapping on the trigger will open the dropdown UI.
-1. Tabbing to the trigger and using the `enter` or `spacebar` keys will open the dropdown UI.
+1. Clicking/tapping on the trigger.
+1. Tabbing to the trigger and using the `enter` or `spacebar` keys.
+1. Programmatically via another control in the UI calling the `show()` method (see api).
 
 The dropdown can be closed with the following actions:
 
 1. Clicking anywhere in the view outside of the dropdown.
-1. When the `toggle` attribute is added, clicking on the trigger.
-1. Programmatically via another control in the UI calling the `hide()` method (see api).
+1. Clicking on the trigger when the `toggle` attribute is used.
 1. Using the `esc` key.
+1. Programmatically via another control in the UI calling the `hide()` method (see api).
+
+## Recommended Use and Version Control
+
+There are two important parts of every Auro component. The <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom clement. The class is exported and then used as part of defining the Web Component. When importing this component as described in the <a href="#install">install</a> section, the class is imported and the `auro-button` custom element is defined automatically.
+
+To protect from versioning conflicts with other instances of the component being loaded, it is recommended to use our `registerComponent(name)` method and pass in a unique name.
+
+```js
+import './node_modules/@aurodesignsystem/auro-button';
+registerComponent('custom-button');
+```
+
+This will create a new custom element that you can use in your HTML that will function identically to the `<auro-button>` element.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/custom.html) -->
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/custom.html) -->
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>

package.json

@@ -130,7 +130,7 @@
     "web components"
   ],
   "scripts": {
-    "build": "npm-run-all build:sass sass:render dist:js bundler postinstall build:api types",
+    "build": "npm-run-all build:sass sass:render dist:js bundler postinstall build:api types build:docs",
     "build:api": "wca analyze 'src/auro-dropdown.js' --outFiles docs/api.md",
     "build:dev:assets": "npm-run-all build:sass:component postCss:component sass:render",
     "build:sass": "npm-run-all build:sass:component postCss:component sass:render",