From 4959fe8d44f9607029bcda565f3d80ba9cbbadb5 Mon Sep 17 00:00:00 2001
From: Jason Baker <jason@capsule42.com>
Date: Tue, 20 Feb 2024 22:00:06 -0800
Subject: [PATCH] perf(docs): add custom registration example to index page

---
 apiExamples/custom.html |  2 ++
 demo/index.html         |  5 +++++
 demo/index.md           | 32 ++++++++++++++++++++++++++++++++
 docs/partials/index.md  | 23 +++++++++++++++++++++++
 4 files changed, 62 insertions(+)
 create mode 100644 apiExamples/custom.html

diff --git a/apiExamples/custom.html b/apiExamples/custom.html
new file mode 100644
index 0000000..c410217
--- /dev/null
+++ b/apiExamples/custom.html
@@ -0,0 +1,2 @@
+<custom-hyperlink>No href supplied</custom-hyperlink><br>
+Welcome to <custom-hyperlink href="https://www.alaskaair.com">Alaska Airlines</custom-hyperlink>.
diff --git a/demo/index.html b/demo/index.html
index e61f452..4a4b585 100644
--- a/demo/index.html
+++ b/demo/index.html
@@ -42,6 +42,11 @@
         });
     </script>
     <script type="module" src="../index.js"></script>
+    <script type="module">
+      import { registerComponent } from '../index.js';
+
+      registerComponent('custom-hyperlink');
+    </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>
diff --git a/demo/index.md b/demo/index.md
index 0fa8b09..1c8cf13 100644
--- a/demo/index.md
+++ b/demo/index.md
@@ -116,4 +116,36 @@ function handleKeyPress(event) {
 }
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+## 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-hyperlink` 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-hyperlink';
+registerComponent('custom-hyperlink');
+```
+
+This will create a new custom element that you can use in your HTML that will function identically to the `<auro-hyperlink>` 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-hyperlink>No href supplied</custom-hyperlink><br>
+  Welcome to <custom-hyperlink href="https://www.alaskaair.com">Alaska Airlines</custom-hyperlink>.
+  <!-- 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-hyperlink>No href supplied</custom-hyperlink><br>
+Welcome to <custom-hyperlink href="https://www.alaskaair.com">Alaska Airlines</custom-hyperlink>.
+```
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
diff --git a/docs/partials/index.md b/docs/partials/index.md
index 34ac37a..cb05482 100644
--- a/docs/partials/index.md
+++ b/docs/partials/index.md
@@ -66,3 +66,26 @@ Aside from the standard hyperlink use-case, the `auro-hyperlink` element is inte
 <!-- AURO-GENERATED-CONTENT:END -->
 
 </auro-accordion>
+
+## 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-hyperlink` 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-hyperlink';
+registerComponent('custom-hyperlink');
+```
+
+This will create a new custom element that you can use in your HTML that will function identically to the `<auro-hyperlink>` 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>