@aurodesignsystem/auro-formkit 5.9.1 → 5.9.2

package/components/menu/demo/index.min.js

@@ -377,12 +377,9 @@ function dispatchMenuEvent(element, eventName, detail = null) {
 
 
 /**
- * The auro-menu element provides users a way to define a menu option.
+ * The `auro-menuoption` element provides users a way to define a menu option.
+ * @customElement auro-menuoption
  *
- * @attr {String} value - Specifies the value to be sent to a server.
- * @attr {String} noCheckmark - When true, selected option will not show the checkmark.
- * @attr {Boolean} disabled - When true specifies that the menuoption is disabled.
- * @attr {Boolean} selected - Specifies that an option is selected.
  * @event auroMenuOption-mouseover - Notifies that this option has been hovered over.
  * @slot - Specifies text for an option, but is not the value.
  */
@@ -390,7 +387,7 @@ class AuroMenuOption extends AuroElement {
 
   /**
    * This will register this element with the browser.
-   * @param {string} [name="auro-menuoption"] - The name of element that you want to register to.
+   * @param {string} [name="auro-menuoption"] - The name of the element that you want to register.
    *
    * @example
    * AuroMenuOption.register("custom-menuoption") // this will register this element to <custom-menuoption/>
@@ -454,38 +451,81 @@ class AuroMenuOption extends AuroElement {
   static get properties() {
     return {
       ...super.properties,
+
+      /**
+       * When true, disables the menu option.
+       */
       disabled: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * @private
+       */
       event: {
         type: String,
         reflect: true
       },
+
+      /**
+       * @private
+       */
+      layout: {
+        type: String
+      },
+
+      /**
+       * Allows users to set a unique key for the menu option for specified option selection. If no key is provided, the value property will be used.
+       */
       key: {
         type: String,
         reflect: true
       },
+
+      /**
+       * @private
+       */
       menuService: {
         type: Object,
         state: true
       },
+
+      /**
+       * @private
+       */
       matchWord: {
         type: String,
         state: true
       },
+
+      /**
+       * @private
+       */
       noCheckmark: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * Specifies that an option is selected.
+       */
       selected: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * Specifies the tab index of the menu option.
+       */
       tabIndex: {
         type: Number,
         reflect: true
       },
+
+      /**
+       * Specifies the value to be sent to a server.
+       */
       value: {
         type: String,
         reflect: true
@@ -1436,19 +1476,9 @@ const MenuContext = n$1('menu-context');
 
 
 /**
- * The auro-menu element provides users a way to select from a list of options.
- * @attr {HTMLElement|Array<HTMLElement>} optionSelected - An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
- * @attr {object} optionactive - Specifies the current active menuOption.
- * @attr {string} matchword - Specifies a string used to highlight matched string parts in options.
- * @attr {boolean} disabled - When true, the entire menu and all options are disabled;
- * @attr {boolean} nocheckmark - When true, selected option will not show the checkmark.
- * @attr {boolean} loading - When true, displays a loading state using the loadingIcon and loadingText slots if provided.
- * @attr {boolean} multiselect - When true, the selected option can be multiple options.
- * @attr {boolean} selectAllMatchingOptions - When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
- * @attr {string} value - The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
- * @prop {string} size - Sets the size of the menu. Accepted values are 'sm' and 'md'. Default is 'sm'.
- * @prop {string} shape - Sets the shape of the menu options. Accepted values are 'box' and 'round'. Default is 'box'.
- * @prop {boolean} hasLoadingPlaceholder - Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
+ * The `auro-menu` element provides users a way to select from a list of options.
+ * @customElement auro-menu
+ *
  * @event {CustomEvent<Element>} auroMenu-activatedOption - Notifies that a menuoption has been made `active`.
  * @event {CustomEvent<any>} auroMenu-customEventFired - Notifies that a custom event has been fired.
  * @event {CustomEvent<{ loading: boolean; hasLoadingPlaceholder: boolean; }>} auroMenu-loadingChange - Notifies when the loading attribute is changed.
@@ -1539,58 +1569,87 @@ class AuroMenu extends AuroElement {
         type: Boolean,
         reflect: true,
       },
-      noCheckmark: {
-        type: Boolean,
-        reflect: true,
-        attribute: 'nocheckmark'
-      },
+
+      /**
+       * When true, the entire menu and all options are disabled.
+       */
       disabled: {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
+       */
+      hasLoadingPlaceholder: {
+        type: Boolean
+      },
+
+      /**
+       * @private
+       */
+      layout: {
+        type: String
+      },
+
+      /**
+       * Indent level for submenus.
+       * @private
+       */
+      level: {
+        type: Number,
+        reflect: false,
+        attribute: false
+      },
+
+      /**
+       * When true, displays a loading state using the loadingIcon and loadingText slots if provided.
+       */
       loading: {
         type: Boolean,
         reflect: true
       },
-      optionSelected: {
-        // Allow HTMLElement, HTMLElement[] arrays and undefined
-        type: Object
-      },
-      optionActive: {
-        type: Object,
-        attribute: 'optionactive'
-      },
+
+      /**
+       * Specifies a string used to highlight matched string parts in options.
+       */
       matchWord: {
         type: String,
         attribute: 'matchword'
       },
+
+      /**
+       * When true, the selected option can be multiple options.
+       */
       multiSelect: {
         type: Boolean,
         reflect: true,
         attribute: 'multiselect'
       },
-      selectAllMatchingOptions: {
+
+      /**
+       * When true, selected option will not show the checkmark.
+       */
+      noCheckmark: {
         type: Boolean,
         reflect: true,
+        attribute: 'nocheckmark'
       },
 
       /**
-       * Value selected for the component.
+       * Specifies the current active menuOption.
        */
-      value: {
-        type: String,
-        reflect: true,
-        attribute: 'value'
+      optionActive: {
+        type: Object,
+        attribute: 'optionactive'
       },
 
       /**
-       * Indent level for submenus.
-       * @private
+       * An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
        */
-      level: {
-        type: Number,
-        reflect: false,
-        attribute: false
+      optionSelected: {
+        // Allow HTMLElement, HTMLElement[] arrays and undefined
+        type: Object
       },
 
       /**
@@ -1601,6 +1660,43 @@ class AuroMenu extends AuroElement {
         type: Array,
         reflect: false,
         attribute: false
+      },
+
+      /**
+       * Sets the size of the menu.
+       * @type {'sm' | 'md'}
+       * @default 'sm'
+       */
+      size: {
+        type: String,
+        reflect: true
+      },
+
+      /**
+       * When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
+       */
+      selectAllMatchingOptions: {
+        type: Boolean,
+        reflect: true,
+      },
+
+      /**
+       * Sets the shape of the menu.
+       * @type {'box' | 'round'}
+       * @default 'box'
+       */
+      shape: {
+        type: String,
+        reflect: true
+      },
+
+      /**
+       * The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
+       */
+      value: {
+        type: String,
+        reflect: true,
+        attribute: 'value'
       }
     };
   }
@@ -1646,7 +1742,7 @@ class AuroMenu extends AuroElement {
 
   /**
    * This will register this element with the browser.
-   * @param {string} [name="auro-menu"] - The name of element that you want to register to.
+   * @param {string} [name="auro-menu"] - The name of the element that you want to register.
    *
    * @example
    * AuroMenu.register("custom-menu") // this will register this element to <custom-menu/>
@@ -2053,43 +2149,6 @@ class AuroMenu extends AuroElement {
   }
 }
 
-function initKeysExample() {
-  const menu = document.getElementById('keys-menu');
-  const stopsButton = document.getElementById('stopsButton');
-  const stopsTopButton = document.getElementById('stopsTopButton');
-  const output = document.getElementById('output');
-
-  const createConsoleEntry = (message) => {
-    const node = document.createElement('span');
-    node.innerHTML = message;
-    output.appendChild(node);
-    output.appendChild(document.createElement('br'));
-  };
-
-  const resetConsole = () => {
-    output.innerHTML = '';
-  };
-
-  const updateMenuValue = (value) => {
-    resetConsole();
-    createConsoleEntry(`Setting menu.value: <em>"${value}"</em>`);
-    menu.value = '';
-    menu.value = value;
-    createConsoleEntry(`menu.value before next lifecycle: <em>"${menu.value}"</em>`);
-    setTimeout(() => {
-      createConsoleEntry(`menu.value after lifecycle: <em>"${menu.value}"</em>`);
-    });
-  };
-
-  stopsButton.addEventListener('click', () => {
-    updateMenuValue('stops');
-  });
-
-  stopsTopButton.addEventListener('click', () => {
-    updateMenuValue('stops-top');
-  });
-}
-
 /* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
 
 
@@ -2099,20 +2158,6 @@ AuroMenu.register('custom-menu');
 AuroMenuOption.register('custom-menuoption');
 
 function initExamples(initCount) {
-  initCount = initCount || 0;
-
-  try {
-    // javascript example function calls to be added here upon creation to test examples
-    // auroMenuResetExample();
-    initKeysExample();
-  } catch (err) {
-    if (initCount <= 20) {
-      // setTimeout handles issue where content is sometimes loaded after the functions get called
-      setTimeout(() => {
-        initExamples(initCount + 1);
-      }, 100);
-    }
-  }
 }
 
 export { initExamples };

package/components/menu/demo/readme.html

@@ -48,10 +48,9 @@
           Prism.highlightAll();
         })
     </script>
-    <script type="module">
-      import { initExamples } from "./index.min.js";
+    <script src="./index.min.js" data-demo-script="true" type="module"></script>
 
-      initExamples();
-    </script>
+    <!-- If additional elements are needed for the demo, add them here. -->
+    <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/+esm" type="module"></script>
   </body>
 </html>

package/components/menu/demo/readme.md

@@ -18,6 +18,7 @@ The following sections are editable by making changes to the following files:
 -->
 
 # Menu
+
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
 <!-- The below content is automatically added from ./docs/partials/description.md -->
 The `<auro-menu>` element provides a list of options for a user to select from.
@@ -31,7 +32,17 @@ The `<auro-menu>` element is designed for contextual menus, e.g. a dropdown menu
 <!-- 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 -->
 
+## Menu 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-menu>` element should be used in situations where users may:
+
+* A user needs to select one option from a list of options.
+<!-- AURO-GENERATED-CONTENT:END -->
+
 ## Getting Started
+
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/componentInstall.md) -->
 <!-- The below content is automatically added from ../../docs/templates/componentInstall.md -->
 
@@ -44,30 +55,7 @@ $ npm i @aurodesignsystem/auro-formkit
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/gettingStarted.md) -->
 <!-- The below content is automatically added from ../../docs/templates/gettingStarted.md -->
 
-### Import Options
-
-#### Automatic Registration
-
-For automatic registration, simply import the component:
-
-```javascript
-// Registers <auro-menu> automatically
-import '@aurodesignsystem/auro-formkit/auro-menu';
-```
-
-#### Custom Registration
-
-To protect from versioning conflicts with other instances of the component being loaded, it is recommended to use our static `AuroMenu.register('custom-menu')` method on the component class and pass in a unique name.
-
-```javascript
-// Import the class only
-import { AuroMenu } from '@aurodesignsystem/auro-formkit/auro-menu/class';
-
-// Register with a custom name if desired
-AuroMenu.register('custom-menu');
-```
-
-#### TypeScript Module Resolution
+### TypeScript Module Resolution
 
 When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
 
@@ -80,31 +68,10 @@ When using TypeScript set `moduleResolution` to `bundler`, add the following to
 ```
 
 This configuration enables proper module resolution for the component's TypeScript files.
-<!-- 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
-<auro-menu>
-  <auro-menuoption value="stops">Stops</auro-menuoption>
-  <auro-menuoption value="price">Price</auro-menuoption>
-  <auro-menuoption value="duration">Duration</auro-menuoption>
-  <auro-menuoption value="departure">Departure</auro-menuoption>
-  <auro-menuoption value="arrival">Arrival</auro-menuoption>
-</auro-menu>
-```
-<!-- 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 -->
 
 ## Install from CDN
+
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/bundleInstallDescription.md) -->
 <!-- The below content is automatically added from ../../docs/templates/bundleInstallDescription.md -->
 In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
@@ -114,21 +81,7 @@ In cases where the project is not able to process JS assets, there are pre-proce
 ```
 <!-- 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 -->
-
-## auro-menu 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-menu>` element should be used in situations where users may:
-
-* A user needs to select one option from a list of options.
-<!-- AURO-GENERATED-CONTENT:END -->
-
-## Formkit development
+## Formkit Development
 
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/partials/developmentDescription.md) -->
 <!-- The below content is automatically added from ../../docs/partials/developmentDescription.md -->
@@ -142,4 +95,51 @@ To only develop a single component, use the `--filter` flag:
 ```shell
 npx turbo dev --filter=@aurodesignsystem/auro-input
 ```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
+<!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
+
+## Custom Component Registration for Version Management
+
+There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition. The class defines the component’s behavior, while the custom element registers it under a specific name so it can be used in HTML.
+
+When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
+
+However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
+
+You can do this by importing only the component class and using the `register(name)` method with a unique name:
+
+```js
+// Import the class only
+import { AuroMenu, AuroMenuOption } from '@aurodesignsystem/auro-formkit/auro-menu/class';
+
+// Register with a custom name if desired
+AuroMenu.register('custom-menu');
+AuroMenuOption.register('custom-menu-option');
+```
+
+This will create a new custom element `<custom-menu>` and `<custom-menu-option>` that behaves exactly like `<auro-menu>` and `<auro-menu-option>`, allowing both to coexist on the same page without interfering with each other.
+
+<div class="exampleWrapper exampleWrapper--flex">
+  <custom-menu>
+    <custom-menuoption value="stops">Stops</custom-menuoption>
+    <custom-menuoption value="price">Price</custom-menuoption>
+    <custom-menuoption value="duration">Duration</custom-menuoption>
+    <custom-menuoption value="departure">Departure</custom-menuoption>
+    <custom-menuoption value="arrival">Arrival</custom-menuoption>
+  </custom-menu>
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+
+```html
+  <custom-menu>
+    <custom-menuoption value="stops">Stops</custom-menuoption>
+    <custom-menuoption value="price">Price</custom-menuoption>
+    <custom-menuoption value="duration">Duration</custom-menuoption>
+    <custom-menuoption value="departure">Departure</custom-menuoption>
+    <custom-menuoption value="arrival">Arrival</custom-menuoption>
+  </custom-menu>
+```
+</auro-accordion>
 <!-- AURO-GENERATED-CONTENT:END -->