npm - @aurodesignsystem/auro-formkit - Versions diffs - 2.0.0-beta.8 → 2.0.0 - Mend

@aurodesignsystem/auro-formkit 2.0.0-beta.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (968) hide show

package/components/menu/demo/readme.html ADDED Viewed

@@ -0,0 +1,49 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/index.md
+  With the exception of adding custom elements if needed for the demo.
+  ----------------------- DO NOT EDIT -----------------------------
+-->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Generator | auro-menu custom element</title>
+    <link
+      rel="stylesheet"
+      type="text/css"
+      href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism.css"
+    />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/tokens/CSSCustomProperties.css">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+    <script type="module">
+      import 'https://cdn.jsdelivr.net/npm/marked@latest/marked.min.js';
+      import 'https://cdn.jsdelivr.net/npm/prismjs@latest/prism.js';
+      fetch('./readme.md')
+        .then((response) => response.text())
+        .then((text) => {
+          const rawHtml = marked.parse(text);
+          document.querySelector('main').innerHTML = rawHtml;
+          Prism.highlightAll();
+        })
+    </script>
+    <script type="module">
+      import { initExamples } from "./index.min.js";
+      initExamples();
+    </script>
+  </body>
+</html>

package/components/menu/demo/readme.md ADDED Viewed

@@ -0,0 +1,145 @@
+<!--
+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
+`../../docs/templates/componentReadmeTemplate.md`
+and copied to `./componentDocs/README.md` each time 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`          |
+-->
+# 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.
+A list of options is created within the `<slot>` of the `<auro-menu>` element by using the `<auro-menuoption>` element to define options. Use a standard `<hr>` element to create dividers within the list of options.
+The `<auro-menu>` element is designed for contextual menus, e.g. a dropdown menus. They are not intended to be used for navigation menus which have a different semantic meaning. The `<auro-menu>` element does not support hide/show functionality within its scope. This functionality will be managed by a wrapping element such as a drop-down menu composite element.
+<!-- 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 -->
+## Getting Started
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ../../docs/templates/componentInstall.md -->
+#### NPM Installation
+```shell
+$ npm i @aurodesignsystem/auro-formkit
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- 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
+When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
+```json
+{
+    "compilerOptions": {
+        "moduleResolution": "bundler"
+    }
+}
+```
+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.
+```html
+<script type="module "src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@2.0.0-beta.54/auro-menu/+esm"></script>
+```
+<!-- 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
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/partials/developmentDescription.md) -->
+<!-- The below content is automatically added from ../../docs/partials/developmentDescription.md -->
+### Filtering
+Running the `dev` command will open a `localhost` development server for all components in the monorepo at once.
+To only develop a single component, use the `--filter` flag:
+```shell
+npx turbo dev --filter=@aurodesignsystem/auro-input
+```
+<!-- AURO-GENERATED-CONTENT:END -->

package/components/menu/dist/auro-menu-utils.d.ts ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * Converts value to an array.
+ * If the value is a JSON string representing an array, it will be parsed.
+ * If the value is already an array, it is returned.
+ * If the value is undefined, it returns undefined.
+ * @private
+ * @param {any} value - The value to be converted. Can be a string, array, or undefined.
+ * @returns {Array|undefined} - The converted array or undefined.
+ * @throws {Error} - Throws an error if the value is not an array, undefined,
+ * or if the value cannot be parsed into an array from a JSON string.
+ */
+export function arrayConverter(value: any): any[] | undefined;
+/**
+ * Compare two arrays for equality.
+ * @private
+ * @param {Array} arr1 - First array to compare.
+ * @param {Array} arr2 - Second array to compare.
+ * @returns {boolean} True if arrays are equal.
+ */
+export function arraysAreEqual(arr1: any[], arr2: any[]): boolean;
+/**
+ * Compares array for changes.
+ * @private
+ * @param {Array|any} newVal - New value to compare.
+ * @param {Array|any} oldVal - Old value to compare.
+ * @returns {boolean} True if arrays have changed.
+ */
+export function arrayOrUndefinedHasChanged(newVal: any[] | any, oldVal: any[] | any): boolean;
+/**
+ * Validates if an option can be interacted with.
+ * @private
+ * @param {HTMLElement} option - The option to check.
+ * @returns {boolean} True if option is interactive.
+ */
+export function isOptionInteractive(option: HTMLElement): boolean;
+/**
+ * Helper method to dispatch custom events.
+ * @param {HTMLElement} element - Element to dispatch event from.
+ * @param {string} eventName - Name of the event to dispatch.
+ * @param {Object} [detail] - Optional detail object to include with the event.
+ */
+export function dispatchMenuEvent(element: HTMLElement, eventName: string, detail?: any): void;

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

@@ -1,18 +1,20 @@
 /**
  * The auro-menu element provides users a way to select from a list of options.
- * @attr {Object} optionSelected - Specifies the current selected 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 {String} value - Value selected for the menu.
- * @prop {Boolean} hasLoadingPlaceholder - Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
- * @event auroMenu-selectedOption - Notifies that a new menuoption selection has been made.
- * @event auroMenu-activatedOption - Notifies that a menuoption has been made `active`.
- * @event auroMenu-selectValueFailure - Notifies that a an attempt to select a menuoption by matching a value has failed.
- * @event auroMenu-selectValueReset - Notifies that the component value has been reset.
- * @event auroMenu-customEventFired - Notifies that a custom event has been fired.
- * @event auroMenu-loadingChange - Notifies when the loading attribute is changed.
+ * @attr {Array<HTMLElement>|undefined} optionselected - An array of currently selected menu options. In single-select mode, the array will contain only one HTMLElement. `undefined` when no options are selected.
+ * @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 {Array<string>|undefined} value - Value selected for the menu. `undefined` when no selection has been made, otherwise an array of strings. In single-select mode, the array will contain only one value.
+ * @prop {boolean} hasLoadingPlaceholder - Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
+ * @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.
+ * @event {CustomEvent<any>} auroMenu-selectValueFailure - Notifies that an attempt to select a menuoption by matching a value has failed.
+ * @event {CustomEvent<any>} auroMenu-selectValueReset - Notifies that the component value has been reset.
+ * @event {CustomEvent<any>} auroMenu-selectedOption - Notifies that a new menuoption selection has been made.
  * @slot loadingText - Text to show while loading attribute is set
  * @slot loadingIcon - Icon to show while loading attribute is set
  * @slot - Slot for insertion of menu options.
@@ -22,6 +24,7 @@ export class AuroMenu extends LitElement {
         noCheckmark: {
             type: BooleanConstructor;
             reflect: boolean;
+            attribute: string;
         };
         disabled: {
             type: BooleanConstructor;
@@ -32,16 +35,26 @@ export class AuroMenu extends LitElement {
             reflect: boolean;
         };
         optionSelected: {
-            type: ObjectConstructor;
+            converter: typeof arrayConverter;
+            hasChanged: typeof arrayOrUndefinedHasChanged;
         };
         optionActive: {
             type: ObjectConstructor;
+            attribute: string;
         };
         matchWord: {
             type: StringConstructor;
+            attribute: string;
+        };
+        multiSelect: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            attribute: string;
         };
         value: {
-            type: StringConstructor;
+            type: ObjectConstructor;
+            converter: typeof arrayConverter;
+            hasChanged: typeof arrayOrUndefinedHasChanged;
         };
     };
     static get styles(): import("lit").CSSResult[];
@@ -60,131 +73,133 @@ export class AuroMenu extends LitElement {
     noCheckmark: boolean;
     optionActive: Element;
     loading: boolean;
+    multiSelect: boolean;
     /**
+     * Handles keyboard navigation.
      * @private
+     * @param {KeyboardEvent} event - Event object from the browser.
      */
-    private rootMenu;
+    private handleKeyDown;
     /**
+     * Handles option selection via mouse.
      * @private
+     * @param {MouseEvent} event - Event object from the browser.
      */
-    private runtimeUtils;
+    private handleMouseSelect;
     /**
+     * Handles option hover events.
      * @private
+     * @param {CustomEvent} event - Event object from the browser.
      */
-    private nestingSpacer;
+    private handleOptionHover;
     /**
+     * Handles slot change events.
      * @private
      */
-    private loadingSlots;
+    private handleSlotChange;
+    firstUpdated(): void;
+    loadingSlots: NodeListOf<Element>;
+    updated(changedProperties: any): void;
+    index: any;
     /**
-     * Passes the noCheckmark attribute to all nested auro-menuoptions.
+     * Updates the UI state and appearance of menu items based on changed properties.
      * @private
-     * @returns {void}
+     * @param {Map<string, boolean>} changedProperties - LitElement's changed properties map.
      */
-    private handleNoCheckmarkAttr;
-    firstUpdated(): void;
-    updated(changedProperties: any): void;
+    private updateItemsState;
     /**
+     * Initializes the menu's state and structure.
      * @private
-     * @param {Object} option - The menuoption to check for interactive state.
-     * @returns {Boolean} Returns true if the option is interactive.
      */
-    private optionInteractive;
+    private initializeMenu;
     /**
+     * Initializes menu items and their attributes.
      * @private
-     * @returns {void} When called will update the DOM with visible suggest text matches.
      */
-    private markOptions;
+    private initItems;
+    items: Element[];
     /**
-     * Reset the menu and all options.
+     * Updates menu state when an option is selected.
+     * @private
+     * @param {HTMLElement} option - The option element to select.
      */
-    resetOptionsStates(): void;
+    private handleSelectState;
     /**
-     * Set the attributes on the selected menuoption, the menu value and stored option.
-     * @param {Object} option - The menuoption to be selected.
+     * Deselects a menu option and updates related state.
      * @private
+     * @param {HTMLElement} option - The menuoption to be deselected.
      */
-    private handleLocalSelectState;
-    index: number;
+    private handleDeselectState;
     /**
-     * Notify selection change.
+     * Resets all options to their default state.
      * @private
-     * @return {void}
      */
-    private notifySelectionChange;
+    private clearSelection;
     /**
-     * Process actions for making making a menuoption selection.
+     * Resets the menu to its initial state.
+     * This is the only way to return value to undefined.
+     * @public
      */
-    makeSelection(): void;
+    public reset(): void;
     /**
-     * Manage ArrowDown, ArrowUp and Enter keyboard events.
+     * Handles nested menu structure.
      * @private
-     * @param {Object} event - Event object from the browser.
+     * @param {HTMLElement} menu - Root menu element.
      */
-    private handleKeyDown;
+    private handleNestedMenus;
     /**
-     * Initializes all menu options in the DOM. This must be re-run every time the options are changed.
+     * Makes a selection based on the current index or clicked option.
      * @private
      */
-    private initItems;
-    items: Element[];
+    private makeSelection;
     /**
-     * Sets the index value of the selected item or first non-disabled menuoption.
+     * Toggle the selection state of the menuoption.
      * @private
+     * @param {HTMLElement} option - The menuoption to toggle.
      */
-    private getSelectedIndex;
+    private toggleOption;
+    rootMenu: boolean;
     /**
-     * Using value of current this.index evaluates index
-     * of next :focus to set based on array of this.items ignoring items
-     * with disabled attr.
-     *
-     * The event.target is not used as the function needs to know where to go,
-     * versus knowing where it is.
-     * @param {String} moveDirection - Up or Down based on keyboard event.
+     * Navigates through options using keyboard.
+     * @private
+     * @param {string} direction - 'up' or 'down'.
      */
-    selectNextItem(moveDirection: string): void;
+    private navigateOptions;
     /**
-     * Used for applying indentation to each level of nested menu.
+     * Updates the active option state and dispatches events.
      * @private
-     * @param {String} menu - Root level menu object.
+     * @param {number} index - Index of the option to make active.
      */
-    private handleNestedMenus;
+    private updateActiveOption;
     /**
-     * Method to apply `selected` attribute to `menuoption` via `value`.
+     * Handles custom events defined on options.
      * @private
-     * @param {String} value - Must match a unique `menuoption` value.
+     * @param {HTMLElement} option - Option with custom event.
      */
-    private selectByValue;
+    private handleCustomEvent;
     /**
-     * Used to make the active state for options follow mouseover.
-     * @param {Number} index - Index of the menuoption that will be made active.
+     * Notifies selection change to parent components.
      * @private
      */
-    private updateActiveOption;
+    private notifySelectionChange;
     /**
-     * Used to only make a selection when a menuoption is receiving a mousedown event.
-     * @param {Event} evt - Mousedown event.
+     * Checks if an option is currently selected.
      * @private
+     * @param {HTMLElement} option - The option to check.
+     * @returns {boolean}
      */
-    private handleMenuMouseDown;
+    private isOptionSelected;
     /**
-     * Checks if there are any loading placeholders in the component.
-     *
-     * This getter evaluates the `loadingSlots` collection to determine if it contains any items.
-     * If the size of the collection is greater than zero, it indicates the presence of loading
-     * placeholders, returning true; otherwise, it returns false.
-     *
-     * @getter hasLoadingPlaceholder
-     * @type {boolean}
-     * @returns {boolean} Returns true if loading placeholders exist; false otherwise.
+     * Getter for loading placeholder state.
+     * @returns {boolean} - True if loading slots are present and non-empty.
      */
     get hasLoadingPlaceholder(): boolean;
     /**
-     * Used for @slotchange event on slotted element.
-     * @private
+     * Renders the component.
+     * @returns {boolean} - True if loading slots are present and non-empty.
      */
-    private handleSlotItems;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): boolean;
 }
 import { LitElement } from "lit";
-//# sourceMappingURL=auro-menu.d.ts.map
+import { arrayConverter } from './auro-menu-utils.js';
+import { arrayOrUndefinedHasChanged } from './auro-menu-utils.js';

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

@@ -61,4 +61,3 @@ export class AuroMenuOption extends LitElement {
     render(): import("lit-html").TemplateResult;
 }
 import { LitElement } from "lit";
-//# sourceMappingURL=auro-menuoption.d.ts.map

package/components/menu/dist/dropdownVersion.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ declare const _default: "3.0.0";
2	+ export default _default;

package/components/menu/dist/iconVersion.d.ts CHANGED Viewed

@@ -1,3 +1,2 @@
 declare const _default: "6.1.2";
 export default _default;
-//# sourceMappingURL=iconVersion.d.ts.map

package/components/menu/dist/index.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
 import { AuroMenu } from './auro-menu.js';
 import { AuroMenuOption } from './auro-menuoption.js';
 export { AuroMenu, AuroMenuOption };
-//# sourceMappingURL=index.d.ts.map
+export { arrayConverter, arrayOrUndefinedHasChanged, isOptionInteractive, dispatchMenuEvent } from "./auro-menu-utils.js";