feat(api): add register static method #267

AuroButton.register is to easily register the element without extra importing `import '@aurodesignsystem/auro-button'` will still register this element to `<auro-button>` `import { AuroButton } from '../src/auro-button.js'` wont register this element until `AuroButton.register` gets called
AlaskaAirlines · Oct 23, 2024 · b60a17e · b60a17e
1 parent 06866e9
commit b60a17e
Show file tree

Hide file tree

Showing 9 changed files with 358 additions and 104 deletions.
diff --git a/demo/index.html b/demo/index.html
@@ -29,14 +29,7 @@
         });
     </script>
     <script type="module" data-demo-script="true">
-      import { AuroButton } from '../src/auro-button.js';
-      import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';
-
-      RuntimeUtils.default.prototype.registerComponent('custom-button', AuroButton);
-
-      import { initExamples } from './index.min.js'; 
-
-      registerComponent('custom-button');
+      import { initExamples } from './index.min.js';
       initExamples();
     </script>
     <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/dist/auro-accordion__bundled.js" type="module"></script>

diff --git a/demo/index.js b/demo/index.js
@@ -1,3 +1,6 @@
+import { AuroButton } from '../src/auro-button.js';
+
+AuroButton.register('custom-button');
 
 export function initExamples(initCount) {
   initCount = initCount || 0;

diff --git a/demo/index.md b/demo/index.md
@@ -2,15 +2,15 @@
 The index.md file is a compiled document. No edits should be made directly to this file.
 README.md is created by running `npm run build:docs`.
 This file is generated based on a template fetched from `./docs/partials/index.md`
--->
-
+-->
+
 # Button
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./description.md) -->
 <!-- The below content is automatically added from ./description.md -->
 `<auro-button>` is a [HTML custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) for the purpose being a clickable element to trigger a specific action.
-<!-- AURO-GENERATED-CONTENT:END -->
-
+<!-- AURO-GENERATED-CONTENT:END -->
+
 ## Auro-Button use cases
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./useCases.md) -->
@@ -21,12 +21,12 @@ The auro-button element should be used in situations where users may:
 * begin a new task
 * trigger a new UI element to appear to the page
 * specificy a new or next step in a process
-<!-- AURO-GENERATED-CONTENT:END -->
-
+<!-- AURO-GENERATED-CONTENT:END -->
+
 ## Buttons are not Hyperlinks
 
-In cases were the action of the button would not fit the criteria above, it is most likely a Hyperlink. In that situation it is recommended that the [auro-hyperlink](https://www.alaskaair.com/components/auro/hyperlink) element be used.
-
+In cases were the action of the button would not fit the criteria above, it is most likely a Hyperlink. In that situation it is recommended that the [auro-hyperlink](https://www.alaskaair.com/components/auro/hyperlink) element be used.
+
 ## Default Example
 
 <div class="exampleWrapper">
@@ -36,20 +36,20 @@ In cases were the action of the button would not fit the criteria above, it is m
   <auro-button variant="secondary">Secondary</auro-button>
   <auro-button variant="tertiary">Tertiary</auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/basic.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/basic.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/basic.html -->
+
 ```html
 <auro-button>Primary</auro-button>
 <auro-button variant="secondary">Secondary</auro-button>
-<auro-button variant="tertiary">Tertiary</auro-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
+<auro-button variant="tertiary">Tertiary</auro-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## On Dark
 
 These examples illustrate the core button types and a `disabled` state on dark backgrounds using the `onDark` attribute.
@@ -61,20 +61,20 @@ These examples illustrate the core button types and a `disabled` state on dark b
   <auro-button variant="secondary" ondark>Secondary</auro-button>
   <auro-button variant="tertiary" ondark>Tertiary</auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/onDark.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/onDark.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/onDark.html -->
+
 ```html
 <auro-button ondark>Primary</auro-button>
 <auro-button variant="secondary" ondark>Secondary</auro-button>
-<auro-button variant="tertiary" ondark>Tertiary</auro-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
+<auro-button variant="tertiary" ondark>Tertiary</auro-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## Disabled
 
 This example demonstrates `auro-button` in it's `disabled` state.
@@ -86,40 +86,40 @@ This example demonstrates `auro-button` in it's `disabled` state.
   <auro-button variant="secondary" disabled>Secondary</auro-button>
   <auro-button variant="tertiary" disabled>Tertiary</auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/disabled.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/disabled.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/disabled.html -->
+
 ```html
 <auro-button disabled>Primary</auro-button>
 <auro-button variant="secondary" disabled>Secondary</auro-button>
-<auro-button variant="tertiary" disabled>Tertiary</auro-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
+<auro-button variant="tertiary" disabled>Tertiary</auro-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
 <div class="exampleWrapper--ondark">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/disabledOnDark.html) -->
   <!-- The below content is automatically added from ./../../apiExamples/disabledOnDark.html -->
   <auro-button disabled ondark>Primary</auro-button>
   <auro-button variant="secondary" disabled ondark>Secondary</auro-button>
   <auro-button variant="tertiary" disabled ondark>Tertiary</auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/disabledOnDark.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/disabledOnDark.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/disabledOnDark.html -->
+
 ```html
 <auro-button disabled ondark>Primary</auro-button>
 <auro-button variant="secondary" disabled ondark>Secondary</auro-button>
-<auro-button variant="tertiary" disabled ondark>Tertiary</auro-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
+<auro-button variant="tertiary" disabled ondark>Tertiary</auro-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## Icon Support
 
 Adding icons to the auro-button component is as easy as nesting any other HTML. The [auro-icon component](https://www.alaskaair.com/components/auro/icon) has access to all the icons listed in the [Auro Icons library](https://www.alaskaair.com/icons/usage) for quick and easy use.
@@ -142,12 +142,12 @@ Be sure to use the `customColor` attribute on the auro-icon component to allow c
     <auro-icon customcolor category="interface" name="heart-filled" slot="icon"></auro-icon>
   </auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/icon.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/icon.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/icon.html -->
+
 ```html
 <auro-button aria-label="wifi">
   Activate WiFi
@@ -160,11 +160,11 @@ Be sure to use the `customColor` attribute on the auro-icon component to allow c
 <auro-button variant="tertiary" aria-label="heart-filled">
   Love this ...
   <auro-icon customcolor category="interface" name="heart-filled" slot="icon"></auro-icon>
-</auro-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
+</auro-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## Pass a Function to Button
 
 These examples illustrate a common use case where a user will want to pass a function into a button to support a click event. See the code examples for how this is achieved.
@@ -176,20 +176,20 @@ These examples illustrate a common use case where a user will want to pass a fun
   <auro-button disabled onclick="alert('YOU CLICKED ME!');">Primary</auro-button>
   <auro-button loading onclick="alert('YOU CLICKED ME!');">Primary</auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/passFunction.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/passFunction.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/passFunction.html -->
+
 ```html
 <auro-button onclick="alert('YOU CLICKED ME!');">Primary</auro-button>
 <auro-button disabled onclick="alert('YOU CLICKED ME!');">Primary</auro-button>
-<auro-button loading onclick="alert('YOU CLICKED ME!');">Primary</auro-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
+<auro-button loading onclick="alert('YOU CLICKED ME!');">Primary</auro-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ## Do's and don'ts
 
 Don't combine `disabled` and `loading` attributes on any single instance of `auro-button`. An `auro-button` with `loading` *is* affectively a disabled instance. There is no need for both.
@@ -204,34 +204,33 @@ Don't combine `disabled` and `loading` attributes on any single instance of `aur
     <auro-button loading>Primary</auro-button>
   </auro-alert>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../../apiExamples/doAndDont.html) -->
-<!-- The below code snippet is automatically added from ./../../apiExamples/doAndDont.html -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/doAndDont.html -->
+
 ```html
 <auro-alert type="error" noIcon>
   <auro-button loading disabled>Primary</auro-button>
 </auro-alert>
 <auro-alert type="success" noIcon style="padding-top: 5px;">
   <auro-button loading>Primary</auro-button>
-</auro-alert>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
+</auro-alert>
+```
+<!-- 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-button` custom element is defined automatically.
+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 element. 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.
+To protect from versioning conflicts with other instances of the component being loaded, it is recommended to use our `AuroButton.register(name)` method and pass in a unique name.
 
 ```js
 import { AuroButton } from './src/auro-button.js';
-import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';
 
-RuntimeUtils.default.prototype.registerComponent('custom-button', AuroButton);
+AuroButton.register('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.
@@ -243,16 +242,16 @@ This will create a new custom element that you can use in your HTML that will fu
   <custom-button variant="secondary">Secondary</custom-button>
   <custom-button variant="tertiary">Tertiary</custom-button>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
-  <span slot="trigger">See code</span>
+  <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 -->
-
+<!-- The below code snippet is automatically added from ./../../apiExamples/custom.html -->
+
 ```html
 <custom-button>Primary</custom-button>
 <custom-button variant="secondary">Secondary</custom-button>
-<custom-button variant="tertiary">Tertiary</custom-button>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
+<custom-button variant="tertiary">Tertiary</custom-button>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
diff --git a/demo/index.min.js b/demo/index.min.js
diff --git a/docs/partials/index.md b/docs/partials/index.md
@@ -136,15 +136,14 @@ Don't combine `disabled` and `loading` attributes on any single instance of `aur
 
 ## 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.
+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 element. 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.
+To protect from versioning conflicts with other instances of the component being loaded, it is recommended to use our `AuroButton.register(name)` method and pass in a unique name.
 
 ```js
 import { AuroButton } from './src/auro-button.js';
-import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';
 
-RuntimeUtils.default.prototype.registerComponent('custom-button', AuroButton);
+AuroButton.register('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.

diff --git a/index.js b/index.js
@@ -1,4 +1,3 @@
 import { AuroButton } from './src/auro-button.js';
-import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';
 
-RuntimeUtils.default.prototype.registerComponent('custom-button', AuroButton);
+AuroButton.register();
diff --git a/package-lock.json b/package-lock.json
diff --git a/src/auro-button.js b/src/auro-button.js
@@ -5,9 +5,13 @@
 
 import { LitElement } from "lit";
 import { html } from 'lit/static-html.js';
+
 import { classMap } from 'lit/directives/class-map.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
+
 import { AuroDependencyVersioning } from '@aurodesignsystem/auro-library/scripts/runtime/dependencyTagVersioning.mjs';
+import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';
+
 import styleCss from "./style-css.js";
 import colorCss from "./color-css.js";
 import tokensCss from "./tokens-css.js";
@@ -150,6 +154,18 @@ export class AuroButton extends LitElement {
     };
   }
 
+  /**
+   * This will register this element with the browser.
+   * @param {string} [name="auro-button"] - The name of element that you want to register to.
+   *
+   * @example
+   * AuroButton.register("custom-button") // this will register this element to <custom-button/>
+   *
+   */
+  static register(name = "auro-button") {
+    RuntimeUtils.default.prototype.registerComponent(name, AuroButton);
+  }
+
   /**
    * Internal method to apply focus to the HTML5 button.
    * @private
@@ -231,8 +247,3 @@ export class AuroButton extends LitElement {
     `;
   }
 }
-
-// default internal definition
-if (!customElements.get("auro-button")) {
-  customElements.define("auro-button", AuroButton);
-}