@aurodesignsystem/auro-formkit 5.9.0 → 5.9.2

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 -->

package/components/menu/dist/auro-menu.context.d.ts

@@ -29,6 +29,11 @@ export class MenuService {
      * @returns {string|string[]|undefined}
      */
     get currentValue(): string | string[] | undefined;
+    /**
+     * Gets the label(s) of the currently selected option(s).
+     * @returns {string}
+     */
+    get currentLabel(): string;
     /**
      * Gets the string representation of the current value(s).
      * For multi-select, this is a JSON stringified array.

package/components/menu/dist/auro-menu.d.ts

@@ -1,17 +1,7 @@
 /**
- * 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.
@@ -31,71 +21,114 @@ export class AuroMenu extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
-        noCheckmark: {
+        /**
+         * When true, the entire menu and all options are disabled.
+         */
+        disabled: {
             type: BooleanConstructor;
             reflect: boolean;
-            attribute: string;
         };
-        disabled: {
+        /**
+         * Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
+         */
+        hasLoadingPlaceholder: {
             type: BooleanConstructor;
+        };
+        /**
+         * @private
+         */
+        layout: {
+            type: StringConstructor;
+        };
+        /**
+         * Indent level for submenus.
+         * @private
+         */
+        level: {
+            type: NumberConstructor;
             reflect: boolean;
+            attribute: boolean;
         };
+        /**
+         * When true, displays a loading state using the loadingIcon and loadingText slots if provided.
+         */
         loading: {
             type: BooleanConstructor;
             reflect: boolean;
         };
-        optionSelected: {
-            type: ObjectConstructor;
-        };
-        optionActive: {
-            type: ObjectConstructor;
-            attribute: string;
-        };
+        /**
+         * Specifies a string used to highlight matched string parts in options.
+         */
         matchWord: {
             type: StringConstructor;
             attribute: string;
         };
+        /**
+         * When true, the selected option can be multiple options.
+         */
         multiSelect: {
             type: BooleanConstructor;
             reflect: boolean;
             attribute: string;
         };
-        selectAllMatchingOptions: {
+        /**
+         * When true, selected option will not show the checkmark.
+         */
+        noCheckmark: {
             type: BooleanConstructor;
             reflect: boolean;
+            attribute: string;
         };
         /**
-         * Value selected for the component.
+         * Specifies the current active menuOption.
          */
-        value: {
-            type: StringConstructor;
-            reflect: boolean;
+        optionActive: {
+            type: ObjectConstructor;
             attribute: string;
         };
         /**
-         * 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: NumberConstructor;
-            reflect: boolean;
-            attribute: boolean;
+        optionSelected: {
+            type: ObjectConstructor;
         };
         options: {
             type: ArrayConstructor;
             reflect: boolean;
             attribute: boolean;
         };
-        layout: {
+        /**
+         * Sets the size of the menu.
+         * @type {'sm' | 'md'}
+         * @default 'sm'
+         */
+        size: "sm" | "md";
+        /**
+         * When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
+         */
+        selectAllMatchingOptions: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        /**
+         * Sets the shape of the menu.
+         * @type {'box' | 'round'}
+         * @default 'box'
+         */
+        shape: "box" | "round";
+        /**
+         * The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
+         */
+        value: {
             type: StringConstructor;
-            attribute: string;
             reflect: boolean;
+            attribute: string;
         };
     };
     static get styles(): import("lit").CSSResult[];
     /**
      * 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/>
@@ -130,6 +163,11 @@ export class AuroMenu extends AuroElement {
      * @private
      */
     private handleSlotChange;
+    /**
+     * @readonly
+     * @returns {string} - Returns the label of the currently selected option(s).
+     */
+    readonly get currentLabel(): string;
     /**
      * @readonly
      * @returns {Array<HTMLElement>} - Returns the array of available menu options.

package/components/menu/dist/auro-menuoption.d.ts

@@ -1,17 +1,14 @@
 /**
- * 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.
  */
 export 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/>
@@ -19,47 +16,75 @@ export class AuroMenuOption extends AuroElement {
      */
     static register(name?: string): void;
     static get properties(): {
+        /**
+         * When true, disables the menu option.
+         */
         disabled: {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * @private
+         */
         event: {
             type: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * @private
+         */
+        layout: {
+            type: StringConstructor;
+        };
+        /**
+         * 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: StringConstructor;
             reflect: boolean;
         };
+        /**
+         * @private
+         */
         menuService: {
             type: ObjectConstructor;
             state: boolean;
         };
+        /**
+         * @private
+         */
         matchWord: {
             type: StringConstructor;
             state: boolean;
         };
-        nocheckmark: {
+        /**
+         * @private
+         */
+        noCheckmark: {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Specifies that an option is selected.
+         */
         selected: {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * Specifies the tab index of the menu option.
+         */
         tabIndex: {
             type: NumberConstructor;
             reflect: boolean;
         };
+        /**
+         * Specifies the value to be sent to a server.
+         */
         value: {
             type: StringConstructor;
             reflect: boolean;
         };
-        layout: {
-            type: StringConstructor;
-            attribute: string;
-            reflect: boolean;
-        };
     };
     static get styles(): import("lit").CSSResult[];
     /**
@@ -78,7 +103,7 @@ export class AuroMenuOption extends AuroElement {
     private size;
     iconTag: any;
     selected: boolean;
-    nocheckmark: boolean;
+    noCheckmark: boolean;
     disabled: boolean;
     /**
      * @private