docs: update new demo for element

This commit updates all the relative files needed to modernize the demo page for this custom web component element.
AlaskaAirlines · Jan 18, 2024 · 35132cc · 35132cc
1 parent 14f6f9e
commit 35132cc
Show file tree

Hide file tree

Showing 29 changed files with 863 additions and 101 deletions.
diff --git a/README.md b/README.md
@@ -0,0 +1,189 @@
+<!--
+The README.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
+`https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/README.md`
+and copied to `./componentDocs/README.md` each time the the docs are compiled.
+
+The following sections are editable by making changes to the following files:
+
+| SECTION                | DESCRIPTION                                       | FILE LOCATION                       |
+|------------------------|---------------------------------------------------|-------------------------------------|
+| Description            | Description of the component                      | `./docs/partials/description.md`    |
+| Use Cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
+| Additional Information | For use to add any component specific information | `./docs/partials/readmeAddlInfo.md` |
+| Component Example Code | HTML sample code of the components use            | `./apiExamples/basic.html`          |
+-->
+
+# Loader
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
+<!-- The below content is automatically added from ./../docs/partials/description.md -->
+`<auro-loader>` is a [HTML custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) for the purpose of illustrating animated loaders.
+
+Things take time. Sometimes we just need to take a second for some data to show up. For this Auro supports the `<auro-loader>` custom element. This powerful element supports multiple modes for use, `ringworm`, `orbit`, `pulse`, and `laser`.
+
+And each of these modes support five size settings, `default`, `sm`, `md`, `lg`, and `xl`.
+
+For color support `<auro-loader>` supports `currentColor`, this allows for any color set on the parent element to influence the color of the loader.
+
+The `<auro-loader>` custom element also supports three pre-defined color modes, `onlight`, `ondark` and `white`.
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/readmeAddlInfo.md) -->
+<!-- The below content is automatically added from ./../docs/partials/readmeAddlInfo.md -->
+<!-- AURO-GENERATED-CONTENT This file is to be used for any additional content that should be included in the README.md which is specific to this component. -->
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## UI development browser support
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/browserSupport.md) -->
+For the most up to date information on [UI development browser support](https://auro.alaskaair.com/support/browsersSupport)
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Install
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentInstall.md) -->
+[![Build Status](https://img.shields.io/github/actions/workflow/status/AlaskaAirlines/auro-loader/testPublish.yml?style=for-the-badge)](https://github.com/AlaskaAirlines/auro-loader/actions/workflows/testPublish.yml)
+[![See it on NPM!](https://img.shields.io/npm/v/@aurodesignsystem/auro-loader?style=for-the-badge&color=orange)](https://www.npmjs.com/package/@aurodesignsystem/auro-loader)
+[![License](https://img.shields.io/npm/l/@aurodesignsystem/auro-loader?color=blue&style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)
+
+```shell
+$ npm i @aurodesignsystem/auro-loader
+```
+
+Installing as a direct, dev or peer dependency is up to the user installing the package. If you are unsure as to what type of dependency you should use, consider reading this [stack overflow](https://stackoverflow.com/questions/18875674/whats-the-difference-between-dependencies-devdependencies-and-peerdependencies) answer.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### Design Token CSS Custom Property dependency
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/designTokens.md) -->
+The use of any Auro custom element has a dependency on the [Auro Design Tokens](https://auro.alaskaair.com/getting-started/developers/design-tokens).
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### CSS Custom Property fallbacks
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/cssFallbacks.md) -->
+[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) are [not supported](https://auro.alaskaair.com/support/custom-properties) in older browsers. For this, fallback properties are pre-generated and included with the npm.
+
+Any update to the Auro Design Tokens will be immediately reflected with browsers that support CSS custom properties, legacy browsers will require updated components with pre-generated fallback properties.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### Define dependency in project component
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentImportDescription.md) -->
+Defining the component dependency within each component that is using the `<auro-loader>` component.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/componentImport.md) -->
+
+```js
+import "@aurodesignsystem/auro-loader";
+```
+
+<!-- AURO-GENERATED-CONTENT:END -->
+**Reference component in HTML**
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Install bundled assets from CDN
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/bundleInstallDescription.md) -->
+In cases where the project is not able to process JS assets, there are pre-processed assets available for use. See -- `auro-loader__bundled.js` for modern browsers. Legacy browsers such as IE11 are no longer supported.
+
+We recommend you load these bundles using [differential serving](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/) so that the browser only loads the bundle correctly. To accomplish this, the script tag for the modern bundle should have `type="module"` and the script tag.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### Bundle example code
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/usage/bundleUse.md) -->
+
+```html
+<!-- **NOTE:** Be sure to replace `@latest` in the URL with the version of the asset you want. @latest is NOT aware of any MAJOR releases, use at your own risk. -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alaskaairux/design-tokens@latest/dist/tokens/CSSCustomProperties.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/bundled/essentials.css" />
+<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-loader@latest/dist/auro-loader__bundled.js" type="module"></script>
+```
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## auro-loader use cases
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/useCases.md) -->
+<!-- The below content is automatically added from ./../docs/partials/useCases.md -->
+The `<auro-loader>` element should be used in situations where developers may need to illustrate a wait time for their users.
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## API Code Examples
+
+### Default auro-loader
+
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/basic.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/basic.html -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## Development
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/developmentDescription.md) -->
+In order to develop against this project, if you are not part of the core team, you will be required to fork the project prior to submitting a pull request.
+
+Please be sure to review the [contribution guidelines](https://auro.alaskaair.com/contributing) for this project. Please make sure to **pay special attention** to the **conventional commits** section of the document.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### Start development environment
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/localhost.md) -->
+Once the project has been cloned to your local resource and you have installed all the dependencies you will need to open a shell session to run the **dev server**.
+
+```shell
+$ npm run dev
+```
+
+Open [localhost:8000](http://localhost:8000/)
+
+If running separate sessions is preferred, please run the following commands in individual terminal shells.
+
+```shell
+$ npm run build:watch
+
+$ npm run serve
+```
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### API generation
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/api.md) -->
+The custom element API file is generated in the build and committed back to the repo with a version change. If the API doc has changed without a version change, author's are to run `npm run build:api` to generate the doc and commit to version control.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### Testing
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/testing.md) -->
+Automated tests are required for every Auro component. See `.\test\auro-loader.test.js` for the tests for this component. Run `npm test` to run the tests and check code coverage. Tests must pass and meet a certain coverage threshold to commit. See [the testing documentation](https://auro.alaskaair.com/support/tests) for more details.
+
+<!-- AURO-GENERATED-CONTENT:END -->
+
+### Bundled assets
+
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/bundles.md) -->
+Bundled assets are only generated in the remote and not merged back to this repo. To review and/or test a bundled asset locally, run `$ npm run bundler` to generate assets.
+
+<!-- AURO-GENERATED-CONTENT:END -->
diff --git a/apiExamples/basic.html b/apiExamples/basic.html
@@ -1 +1 @@
-<auro-loader>Hello World</auro-loader>
+foo
diff --git a/apiExamples/custom_color.html b/apiExamples/custom_color.html
@@ -0,0 +1,3 @@
+<auro-loader style="color: var(--ds-color-brand-tropical-300)" ringworm md></auro-loader>
+<auro-loader style="color: var(--ds-color-brand-goldcoast-300)" orbit md></auro-loader>
+<auro-loader style="color: var(--ds-color-brand-alpine-400)" pulse md></auro-loader>
diff --git a/apiExamples/custom_speed.html b/apiExamples/custom_speed.html
@@ -0,0 +1,11 @@
+<style>
+  .slow::part(element) {
+    animation-duration: 8s;
+  }
+  .fast::part(element) {
+    animation-duration: 1s;
+  }
+</style>
+
+<auro-loader class="slow" orbit lg></auro-loader>
+<auro-loader class="fast" orbit xl></auro-loader>
diff --git a/apiExamples/loaderGallery.html b/apiExamples/loaderGallery.html
@@ -0,0 +1,4 @@
+<auro-loader ringworm md></auro-loader>
+<auro-loader orbit md></auro-loader>
+<auro-loader pulse md></auro-loader>
+<auro-loader laser></auro-loader>
diff --git a/apiExamples/loader_color.html b/apiExamples/loader_color.html
@@ -0,0 +1 @@
+<auro-loader pulse onlight md></auro-loader>
diff --git a/apiExamples/loader_color_ondark.html b/apiExamples/loader_color_ondark.html
@@ -0,0 +1,2 @@
+<auro-loader pulse ondark md></auro-loader>
+<auro-loader pulse white md></auro-loader>
diff --git a/apiExamples/loader_sizes.html b/apiExamples/loader_sizes.html
@@ -0,0 +1,5 @@
+<auro-loader ringworm></auro-loader>
+<auro-loader ringworm sm></auro-loader>
+<auro-loader ringworm md></auro-loader>
+<auro-loader ringworm lg></auro-loader>
+<auro-loader ringworm xl></auro-loader>
diff --git a/demo/apiExamples.md b/demo/apiExamples.md
@@ -0,0 +1,169 @@
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../api.md) -->
+<!-- The below content is automatically added from ./../api.md -->
+
+# auro-loader
+
+auro-loader is an easy to use animated loader component
+
+## Attributes
+
+| Attribute | Type      | Description                                      |
+|-----------|-----------|--------------------------------------------------|
+| [lg](#lg)      | `Boolean` | sets size to lg                                  |
+| [md](#md)      | `Boolean` | sets size to md                                  |
+| [ondark](#ondark)  | `Boolean` | sets color of loader to auro-color-ui-default-on-dark |
+| [onlight](#onlight) | `Boolean` | sets color of loader to auro-color-ui-default-on-light |
+| [pulse](#pulse)   | `Boolean` | sets loader type                                 |
+| [sm](#sm)      | `Boolean` | sets size to sm                                  |
+| [white](#white)   | `Boolean` | sets color of loader to white                    |
+| [xl](#xl)      | `Boolean` | sets size to xl                                  |
+| [xs](#xs)      | `Boolean` | sets size to xs                                  |
+| [xxs](#xxs)     | `Boolean` | sets size to xxs                                 |
+
+## Properties
+
+| Property   | Attribute  | Type      | Default | Description      |
+|------------|------------|-----------|---------|------------------|
+| [laser](#laser)    | `laser`    | `Boolean` | false   | sets loader type |
+| [orbit](#orbit)    | `orbit`    | `Boolean` | false   | sets loader type |
+| [ringworm](#ringworm) | `ringworm` | `Boolean` | false   | sets loader type |
+
+## CSS Shadow Parts
+
+| Part      | Description                              |
+|-----------|------------------------------------------|
+| [element](#element) | apply style to adjust speed of animation |
+<!-- AURO-GENERATED-CONTENT:END -->
+
+## API Examples
+
+### Basic
+
+<div class="twoColDemoRow">
+  <div>
+    <div class="exampleWrapper">
+      <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/basic.html) -->
+      <!-- The below content is automatically added from ./../../apiExamples/basic.html -->
+      foo
+      <!-- AURO-GENERATED-CONTENT:END -->
+    </div>
+<auro-accordion lowProfile justifyRight>
+  <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 -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Attribute Examples
+
+#### <a name="attributeName"></a>`attributeName`<a href="#auro-loader" style="float: right; font-size: 1rem; font-weight: 100;">back to top</a>
+Explanation and use description.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/basic.html) -->
+  <!-- The below content is automatically added from ./../../apiExamples/basic.html -->
+  foo
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion lowProfile justifyRight>
+  <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 -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Property Examples
+
+#### <a name="propertyName"></a>`propertyName`<a href="#auro-loader" style="float: right; font-size: 1rem; font-weight: 100;">back to top</a>
+Explanation and use description.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/basic.html) -->
+  <!-- The below content is automatically added from ./../../apiExamples/basic.html -->
+  foo
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion lowProfile justifyRight>
+  <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 -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Method Examples
+
+#### <a name="methodName"></a>`methodName`<a href="#auro-loader" style="float: right; font-size: 1rem; font-weight: 100;">back to top</a>
+Explanation and use description.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/basic.html) -->
+  <!-- The below content is automatically added from ./../../apiExamples/basic.html -->
+  foo
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion lowProfile justifyRight>
+  <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 -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Event Examples
+
+#### <a name="eventName"></a>`eventName`<a href="#auro-loader" style="float: right; font-size: 1rem; font-weight: 100;">back to top</a>
+Explanation and use description.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/basic.html) -->
+  <!-- The below content is automatically added from ./../../apiExamples/basic.html -->
+  foo
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion lowProfile justifyRight>
+  <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 -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Slot Examples
+
+#### <a name="slotName"></a>`slotName`<a href="#auro-loader" style="float: right; font-size: 1rem; font-weight: 100;">back to top</a>
+Explanation and use description.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../../apiExamples/basic.html) -->
+  <!-- The below content is automatically added from ./../../apiExamples/basic.html -->
+  foo
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion lowProfile justifyRight>
+  <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 -->
+
+```html
+foo
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>