@aurodesignsystem/auro-library 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Semantic Release Automated Changelog
 
+# [2.6.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.5.1...v2.6.0) (2024-04-29)
+
+
+### Features
+
+* **tagname:** add new functions for handling custom named components. [#51](https://github.com/AlaskaAirlines/auro-library/issues/51) ([1c7addc](https://github.com/AlaskaAirlines/auro-library/commit/1c7addcb9c637bdf043470e04626b9b4328ed6b6))
+
+## [2.5.1](https://github.com/AlaskaAirlines/auro-library/compare/v2.5.0...v2.5.1) (2024-02-07)
+
+
+### Bug Fixes
+
+* update reference to index.md ([e504708](https://github.com/AlaskaAirlines/auro-library/commit/e5047082cc0e198d0ee8e35fccdd1d715e3ff940))
+
 # [2.5.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.4.7...v2.5.0) (2024-02-07)
 
 

package/README.md

@@ -2,46 +2,77 @@
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
 <!-- The below content is automatically added from ./../docs/partials/description.md -->
-This repository holds shared scripts, utilities, and workflows utilized acorss repositories along the Auro Design System.
+This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## Scripts
 
-#### Publish Surge Demo
+### Publish Surge Demo
 
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
-<!-- The below content is automatically added from ./../docs/partials/description.md -->
-This repository holds shared scripts, utilities, and workflows utilized acorss repositories along the Auro Design System.
-<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/publishDemo.md) -->
+<!-- The below content is automatically added from ./../docs/partials/publishDemo.md -->
+This is an automated workflow that utilizes GitHub Actions to generate surge demos. Upon making any change to a PR a comment will be added or updated on the PR with a link to the demo similar to the following:
+
+```md
+Surge demo deployment succeeded! 🚀🚀🚀
+
+[Auro Web Component Generator](https://surge.sh/)
+```
+
+This workflow utilizes the file `./scripts/config/useBundles.js` to update the demo HTML files to use the bundled versions of components so that they can be supported staticly in surge.
+
+In order to add this functionality to an auro component you just need to add the following snippet into the `publishDemo.yml` file in the `./.github/workflows` directory.
+
+```yml
+name: Deploy Demo
+
+on:
+  pull_request:
+    branches: [ main ]
 
-#### Surge Demo Teardown
+jobs:
+  call-publish-demo-workflow:
+    uses: AlaskaAirlines/auro-library/.github/workflows/publishDemo.yml@main
+    secrets:
+      SURGE_TOKEN: ${{secrets.AURO_SURGE_TOKEN}}
+```
 
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/demoTeardown.md) -->
-<!-- The below content is automatically added from ./../docs/partials/demoTeardown.md -->
+> Note: This will only work properly in components located in the "AlaskaAirlines" organization due to a dependency on the org-wide Actions secret `AURO_SURGE_TOKEN`.
+
+Afterwards you will want to make sure to update the script tags you want replaced with bundles in your `./demo/*.html` files with the `data-demo-scripts="true"` attribute.
+
+```diff
+--    <script type="module" src="../index.js"></script>
+++    <script type="module" src="../index.js" data-demo-script="true"></script>
+```
+
+> Note: If you fail to do this, the components will fail to register in your demo.
+<!-- AURO-GENERATED-CONTENT:END -->
+---
 
-## Dependency Tag Versioming
+### Surge Demo Teardown
 
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/demoTeardown.md) -->
+<!-- The below content is automatically added from ./../docs/partials/demoTeardown.md -->
 This workflow works to automatically delete and clear any surge demos that have been active for more than 2+ months. Surge in theory allows us to have an infinite amount of active pages but by clearing unused and stale demos we can keep our Surge account more organized in the future.
 
-> Note: This workflow exectutes on a monthly cronjob on the first of each month.
+> Note: This workflow executes on a monthly cronjob on the first of each month.
 
 In order to clear all our surge projects we rely on [this GitHub Action](https://github.com/marketplace/actions/surge-sh-teardown) to handle the deletion logic.
 <!-- AURO-GENERATED-CONTENT:END -->
+---
 
-#### Dependency Tag Versioning
+### Dependency Tag Versioning
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/dependencyTagVersioning.md) -->
-<!-- The below content is automatically added from ./../docs/partials/dependencyTagVersioning.md -->
-
-## Dependency Tag Versioming
-
+<!-- The below content is automatically added from ./../docs/partials/dependencyTagVersioning.md -->
 This is a two part utility for the purpose of generating a custom string for dependency component tag naming. This is important to prevent [version conflicts](https://www.thinktecture.com/en/web-components/web-components-flaws/#elementor-toc__heading-anchor-0) when multiple versions of a given Auro component may be loaded on a single page.
 
 _Note: The example configuration used below in all code samples assumes `auro-dropdown` is the dependency component. Substitute any Auro component in the example code as needed._
 
-### Part 1: The Build
+#### Part 1: The Build
 
-#### Configuration
+##### Configuration
 
 1. Create a new file `./scripts/version.js` with the following content:
 
@@ -63,7 +94,7 @@ versionWriter.writeDepVersionFile('@aurodesignsystem/auro-dropdown'); // duplica
 "build": "npm-run-all build:version ... etc.",
 ```
 
-#### Execution
+##### Execution
 
 Once configuration is complete, execute `npm run build`. This must be done once before `npm run dev` when developing locally. When Auro dependencies are initially installed or updated to new versions then `npm run build:version` or a complete `npm run build` must be executed.
 
@@ -71,20 +102,20 @@ Upon execution of `build:version`, for each Auro dependency defined in the `./sc
 
 For example, following these steps:
 1. Run `npm i @aurodesignsystem/auro-dropdown@1.0.0`
-1. add the following to the `./scripts/version.js` script file:
+2. add the following to the `./scripts/version.js` script file:
 ```js
 versionWriter.writeDepVersionFile('@aurodesignsystem/auro-dropdown');
 ```
-1. Run `npm run build`
+3. Run `npm run build`
 
 Will result in:
 - A new file created: `./src/dropdownVersion.js`
 - File content will export the version of the component installed. In this case:
 `export default '1.0.0'`
 
-### Part 2: The Runtime
+#### Part 2: The Runtime
 
-#### Configuration
+##### Configuration
 
 In the main component JS file located in the `./src` directory add the following:
 
@@ -110,7 +141,7 @@ In the component properties add the following:
 dropdownTag: { type: Object }
 ```
 
-#### Usage
+##### Usage
 
 The new dynamically named version of `auro-dropdown` may now be used in your component template as follows:
 
@@ -134,57 +165,31 @@ When the component is rendered during runtime the DOM will now show up as follow
 
 _Note: the numbers attached in the tag name will match the version of the dependency that was installed._
 
-#### Accessing the dynamically named element with JS
-
-The dynamic component is accessible using a the following string in a JS query selector: `this.dropdownTag._$litStatic# Auro-Library
-
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
-<!-- The below content is automatically added from ./../docs/partials/description.md -->
-This repository holds shared scripts, utilities, and workflows utilized acorss repositories along the Auro Design System.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-## Scripts
-
-#### Publish Surge Demo
-
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/description.md) -->
-<!-- The below content is automatically added from ./../docs/partials/description.md -->
-This repository holds shared scripts, utilities, and workflows utilized acorss repositories along the Auro Design System.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-#### Surge Demo Teardown
+##### Accessing the dynamically named element with JS
 
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/demoTeardown.md) -->
-<!-- The below content is automatically added from ./../docs/partials/demoTeardown.md -->
-
-## Dependency Tag Versioming
-
-This workflow works to automatically delete and clear any surge demos that have been active for more than 2+ months. Surge in theory allows us to have an infinite amount of active pages but by clearing unused and stale demos we can keep our Surge account more organized in the future.
-
-> Note: This workflow exectutes on a monthly cronjob on the first of each month.
+The dynamic component is accessible using a the following string in a JS query selector:
+```js
+this.dropdownTag._$litStatic$
+```
 
-In order to clear all our surge projects we rely on [this GitHub Action](https://github.com/marketplace/actions/surge-sh-teardown) to handle the deletion logic.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-#### Dependency Tag Versioning
-
 ```js
 firstUpdated() {
   this.dropdown = this.shadowRoot.querySelector(this.dropdownTag._$litStatic$);
 };
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+---
 
-#### Sync All Templates
+### Sync All Templates
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/syncAllTemplates.md) -->
 <!-- The below content is automatically added from ./../docs/partials/syncAllTemplates.md -->
 
-## How to Run the `syncAllTemplates.mjs` Script
+### How to Run the `syncAllTemplates.mjs` Script
 
 To run the `syncAllTemplates.mjs` script, you will need to add a new node script into the linked component and point that to the `syncAllTemplates.mjs` file. You can individually run the workflow configurations by pointing to the `syncAllTemplates.mjs` file and adding a `--github` parameter after the path. The same can be done for the linter configurations by adding a `--linters` parameter.
 
-### Example Calls
+#### Example Calls
 
 ```
 // Default

package/bin/generateDocs_index.mjs

@@ -142,7 +142,7 @@ function processDemo() {
     outputDir: './demo'
   };
 
-  const markdownPath = path.join(__dirname, '../docs/partials/demo.md');
+  const markdownPath = path.join(__dirname, '../docs/partials/index.md');
 
   markdownMagic(markdownPath, configDemo, callback);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem/auro-library",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",

package/scripts/build/generateDocs.mjs

@@ -77,7 +77,7 @@ function processDemo() {
     outputDir: './demo'
   };
 
-  const markdownPath = './docs/partials/demo.md';
+  const markdownPath = './docs/partials/index.md';
 
   markdownMagic(markdownPath, configDemo, callback);
 }

package/scripts/utils/runtimeUtils.mjs

@@ -25,5 +25,33 @@ export default class AuroLibraryRuntimeUtils {
     return __Closest(base);
   }
   /* eslint-enable jsdoc/require-param */
+
+  /**
+   * If the element passed is registered with a different tag name than what is passed in, the tag name is added as an attribute to the element.
+   * @param {Object} elem - The element to check.
+   * @param {String} tagName - The name of the Auro component to check for or add as an attribute.
+   * @returns {void}
+   */
+  handleComponentTagRename(elem, tagName) {
+    const tag = tagName.toLowerCase();
+    const elemTag = elem.tagName.toLowerCase();
+
+    if (elemTag !== tag) {
+      elem.setAttribute(tag, true);
+    }
+  }
+
+  /**
+   * Validates if an element is a specific Auro component.
+   * @param {Object} elem - The element to validate.
+   * @param {String} tagName - The name of the Auro component to check against.
+   * @returns {Boolean} - Returns true if the element is the specified Auro component.
+   */
+  elementMatch(elem, tagName) {
+    const tag = tagName.toLowerCase();
+    const elemTag = elem.tagName.toLowerCase();
+
+    return elemTag === tag || elem.hasAttribute(tag);
+  }
 }