Skip to content

Commit

Permalink
feat(api): add register static method #210
Browse files Browse the repository at this point in the history 
`AuroSelect.register` is to easily register the element without extra importing
`import '@aurodesignsystem/auro-select'` will still register this element to `<auro-select>`
`import { AuroSelect } from '../src/auro-select.js` wont register this element until `AuroSelect.register` gets called
  • Loading branch information
@sun-mota
sun-mota committed Oct 30, 2024
1 parent db981f8 commit fab6e53
Show file tree
Hide file tree
Showing 11 changed files with 687 additions and 104 deletions.
8 changes: 0 additions & 8 deletions demo/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,11 @@
Prism.highlightAll();
});
</script>
<script type="module" data-demo-script="true" src="../index.js"></script>
<script type="module">
import { initExamples } from "./index.min.js"
initExamples();
</script>

<script type="module">
import { AuroSelect } from '../src/auro-select.js';
import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';

RuntimeUtils.default.prototype.registerComponent('custom-select', AuroSelect);
</script>

<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-icon@latest/dist/auro-icon__bundled.js" type="module"></script>
<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@latest/dist/auro-button__bundled.js" type="module"></script>
Expand Down
6 changes: 6 additions & 0 deletions demo/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

/* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */

import { AuroSelect } from '../src/auro-select.js';

AuroSelect.register(); // registering to `auro-select`
AuroSelect.register('custom-select');


export function initExamples(initCount) {
initCount = initCount || 0;

Expand Down
157 changes: 78 additions & 79 deletions demo/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ The demo.md file is a compiled document. No edits should be made directly to thi
demo.md is created by running `npm run build:markdownDocs`.
This file is generated based on a template fetched from `./docs/partials/demo.md`
-->

-->

# Select

<!-- AURO-GENERATED-CONTENT:START (FILE:src=./description.md) -->
<!-- The below content is automatically added from ./description.md -->
`<auro-select>` is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom element</auro-hyperlink> that consists of a pre-defined trigger element, `<auro-menu>` for the panel content. See the <auro-hyperlink href="https://auro.alaskaair.com/components/auro/menu/api">auro-menu API docs</auro-hyperlink> for additional information.

`<auro-select>` is a combination <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements">HTML custom element</auro-hyperlink> that consists of a pre-defined trigger element, `<auro-menu>` for the panel content. See the <auro-hyperlink href="https://auro.alaskaair.com/components/auro/menu/api">auro-menu API docs</auro-hyperlink> for additional information.

## About auro-select

The `<auro-select>` element presents a menu of options. The options within the menu are represented by `<auro-menu>` and `<auro-menuoption>` elements. You can pre-select options for the user with the `selected` attribute as part of the `<auro-menuoption>` API.

The `<auro-select>` element presents a menu of options. The options within the menu are represented by `<auro-menu>` and `<auro-menuoption>` elements. You can pre-select options for the user with the `selected` attribute as part of the `<auro-menuoption>` API.

## Install instructions

The `<auro-select>` custom element is a combo-element using independent primitives for the most flexibility. To allow consumers the most control over the versioning their dependencies, `<auro-select>` requires the following peer dependencies along with `<auro-select>`.
Expand All @@ -26,8 +26,8 @@ $ npm i @aurodesignsystem/auro-select
$ npm i @aurodesignsystem/auro-dropdown
$ npm i @aurodesignsystem/auro-menu
```
<!-- AURO-GENERATED-CONTENT:END -->

<!-- AURO-GENERATED-CONTENT:END -->

## Default example

A baseline `<auro-select>` using `<auro-menu>` and `<auro-menuoption>` elements. Notice a default `Please select option` placeholder in the trigger.
Expand All @@ -46,12 +46,12 @@ A baseline `<auro-select>` using `<auro-menu>` and `<auro-menuoption>` elements.
</auro-menu>
</auro-select>
<!-- 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-select>
<auro-menu>
Expand All @@ -62,11 +62,11 @@ A baseline `<auro-select>` using `<auro-menu>` and `<auro-menuoption>` elements.
<auro-menuoption value="arrival">Arrival</auro-menuoption>
<auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

## Example with auro-icons in options

Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
Expand Down Expand Up @@ -94,12 +94,12 @@ Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
</auro-menu>
</auro-select>
<!-- 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/withIcons.html) -->
<!-- The below code snippet is automatically added from ./../../apiExamples/withIcons.html -->

<!-- The below code snippet is automatically added from ./../../apiExamples/withIcons.html -->

```html
<auro-select>
<auro-menu>
Expand All @@ -119,11 +119,11 @@ Displays an `<auro-select>` element with `<auro-icon>` elements in each option.
<auro-icon label customColor category="health" name="spraybottle">Spray Bottle</auro-icon>
</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

## Example with nested menus

This example shows nesting `<auro-menu>` elements to create submenus.
Expand Down Expand Up @@ -165,12 +165,12 @@ This example shows nesting `<auro-menu>` elements to create submenus.
</auro-menu>
</auro-select>
<!-- 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/withSubmenus.html) -->
<!-- The below code snippet is automatically added from ./../../apiExamples/withSubmenus.html -->

<!-- The below code snippet is automatically added from ./../../apiExamples/withSubmenus.html -->

```html
<auro-select>
<auro-menu>
Expand Down Expand Up @@ -204,11 +204,11 @@ This example shows nesting `<auro-menu>` elements to create submenus.
<auro-menuoption value="planes">Planes</auro-menuoption>
<auro-menuoption value="motorcycles">Motorcycles</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

## Example with no checkmark

Applying the `noCheckmark` attribute will prevent the checkmark icon from being shown on the selected option. The left padding to reserve space for the checkmark will not be shown.
Expand All @@ -227,12 +227,12 @@ Applying the `noCheckmark` attribute will prevent the checkmark icon from being
</auro-menu>
</auro-select>
<!-- 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/noCheckmark.html) -->
<!-- The below code snippet is automatically added from ./../../apiExamples/noCheckmark.html -->

<!-- The below code snippet is automatically added from ./../../apiExamples/noCheckmark.html -->

```html
<auro-select nocheckmark>
<auro-menu>
Expand All @@ -243,11 +243,11 @@ Applying the `noCheckmark` attribute will prevent the checkmark icon from being
<auro-menuoption value="arrival">Arrival</auro-menuoption>
<auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

## Label and help text slots

The following example illustrates the use of the `label` and `helptext` slots for additional placement of content around the select menu.
Expand All @@ -268,12 +268,12 @@ The following example illustrates the use of the `label` and `helptext` slots fo
</auro-menu>
</auro-select>
<!-- 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/slots.html) -->
<!-- The below code snippet is automatically added from ./../../apiExamples/slots.html -->

<!-- The below code snippet is automatically added from ./../../apiExamples/slots.html -->

```html
<auro-select>
<span slot="label">Please choose a preference</span>
Expand All @@ -286,11 +286,11 @@ The following example illustrates the use of the `label` and `helptext` slots fo
<auro-menuoption value="arrival">Arrival</auro-menuoption>
<auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

## Error State

Use the `error` boolean attribute to toggle the error UI.
Expand All @@ -309,12 +309,12 @@ Use the `error` boolean attribute to toggle the error UI.
</auro-menu>
</auro-select>
<!-- 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/error.html) -->
<!-- The below code snippet is automatically added from ./../../apiExamples/error.html -->

<!-- The below code snippet is automatically added from ./../../apiExamples/error.html -->

```html
<auro-select error="Custom error message">
<auro-menu>
Expand All @@ -325,11 +325,11 @@ Use the `error` boolean attribute to toggle the error UI.
<auro-menuoption value="arrival">Arrival</auro-menuoption>
<auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

## Disabled state

Use the `disabled` boolean attribute to toggle the disabled UI.
Expand All @@ -348,12 +348,12 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
</auro-menu>
</auro-select>
<!-- 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-select disabled>
<auro-menu>
Expand All @@ -364,22 +364,21 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
<auro-menuoption value="arrival">Arrival</auro-menuoption>
<auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
</auro-menu>
</auro-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>

</auro-select>
```
<!-- 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-select` 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-select` 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 `AuroSelect.register(name)` method and pass in a unique name.

```js
import { AuroSelect } from './src/auro-select.js';
import * as RuntimeUtils from '@aurodesignsystem/auro-library/scripts/utils/runtimeUtils.mjs';

RuntimeUtils.default.prototype.registerComponent('custom-select', AuroSelect);
AuroSelect.register('custom-select');
```

This will create a new custom element that you can use in your HTML that will function identically to the `<auro-select>` element.
Expand All @@ -402,8 +401,8 @@ This will create a new custom element that you can use in your HTML that will fu
<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 -->

<!-- The below code snippet is automatically added from ./../../apiExamples/custom.html -->

```html
<custom-select>
<auro-menu>
Expand All @@ -414,7 +413,7 @@ This will create a new custom element that you can use in your HTML that will fu
<auro-menuoption value="arrival">Arrival</auro-menuoption>
<auro-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
</auro-menu>
</custom-select>
```
</custom-select>
```
<!-- AURO-GENERATED-CONTENT:END -->
</auro-accordion>
Loading

0 comments on commit fab6e53

Please sign in to comment.