@aurodesignsystem/auro-formkit 5.8.1 → 5.9.0

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

@@ -0,0 +1,222 @@
+export class MenuService {
+    /**
+     * CONSTRUCTOR
+     */
+    /**
+     * Creates a new MenuService instance.
+     * @param {Object} options - The options object.
+     *   @param {AuroMenu} options.host - The host element that this service will control. Required.
+     * @throws {Error} If the host is not provided.
+     */
+    constructor({ host }?: {
+        host: AuroMenu;
+    });
+    /**
+     * PROPERTIES AND GETTERS
+     */
+    /**
+     * Gets the list of registered menu options.
+     * @returns {AuroMenuOption[]}
+     */
+    get menuOptions(): AuroMenuOption[];
+    /**
+     * Gets the currently highlighted option.
+     * @returns {AuroMenuOption|null}
+     */
+    get highlightedOption(): AuroMenuOption | null;
+    /**
+     * Gets the current value(s) of the selected option(s).
+     * @returns {string|string[]|undefined}
+     */
+    get currentValue(): string | string[] | undefined;
+    /**
+     * Gets the string representation of the current value(s).
+     * For multi-select, this is a JSON stringified array.
+     * @returns {string|undefined}
+     */
+    get stringValue(): string | undefined;
+    /**
+     * Gets the key(s) of the currently selected option(s).
+     * @returns {string|string[]|undefined}
+     */
+    get currentKeys(): string | string[] | undefined;
+    host: AuroMenu;
+    size: any;
+    shape: any;
+    noCheckmark: any;
+    disabled: any;
+    matchWord: any;
+    multiSelect: any;
+    allowDeselect: any;
+    selectAllMatchingOptions: any;
+    highlightedIndex: number;
+    _menuOptions: any[];
+    _subscribers: any[];
+    internalUpdateInProgress: boolean;
+    selectedOptions: any[];
+    /**
+     * PROPERTY SYNCING
+     */
+    /**
+     * Handles host updates.
+     * This is a lit reactive lifecycle method.
+     * This comes from the Lit controller interface provided by adding this service as a controller to the host.
+     * See constructor for `this.host.addController(this)`
+     * You can read more about Lit reactive controllers here: https://lit.dev/docs/composition/controllers/
+     */
+    hostUpdated(): void;
+    /**
+     * Handles host disconnection and memory cleanup.
+     */
+    hostDisconnected(): void;
+    /**
+     * Sets a property value if it exists on the instance and the value has changed.
+     * @param {string} property
+     * @param {any} value
+     */
+    setProperty(property: string, value: any): void;
+    /**
+     * Sets multiple properties on the instance.
+     * @param {Object} properties - Key-value pairs of properties to set.
+     */
+    setProperties(properties: any): void;
+    /**
+     * MENU OPTION HIGHLIGHTING
+     */
+    /**
+     * Highlights the next active option in the menu.
+     */
+    highlightNext(): void;
+    /**
+     * Highlights the previous active option in the menu.
+     */
+    highlightPrevious(): void;
+    /**
+     * Moves the highlighted option in the specified direction.
+     * @param {string} direction - The direction to move the highlight ("next" or "previous").
+     */
+    moveHighlightedOption(direction: string): void;
+    /**
+     * Sets the highlighted index to the specified option.
+     * @param {AuroMenuOption} option - The option to highlight.
+     */
+    setHighlightedOption(option: AuroMenuOption): void;
+    /**
+     * Sets the highlighted option to the option at the specified index if it exists.
+     * @param {number} index
+     */
+    setHighlightedIndex(index: number): void;
+    /**
+     * Selects the currently highlighted option.
+     */
+    selectHighlightedOption(): void;
+    /**
+     * SELECTION AND DESELECTION METHODS
+     */
+    /**
+     * Selects one or more options in a batch operation
+     * @param {AuroMenuOption|AuroMenuOption[]} options - Single option or array of options to select
+     */
+    selectOptions(options: AuroMenuOption | AuroMenuOption[]): void;
+    /**
+     * Deselects one or more options in a batch operation
+     * @param {AuroMenuOption|AuroMenuOption[]} options - Single option or array of options to deselect
+     */
+    deselectOptions(options: AuroMenuOption | AuroMenuOption[]): void;
+    /**
+     * Selects a single option.
+     * @param {AuroMenuOption} option
+     */
+    selectOption(option: AuroMenuOption): void;
+    /**
+     * Deselects a single option.
+     * @param {AuroMenuOption} option
+     */
+    deselectOption(option: AuroMenuOption): void;
+    /**
+     * Toggles the selection state of a single option.
+     * @param {AuroMenuOption} option
+     */
+    toggleOption(option: AuroMenuOption): void;
+    /**
+     * Selects options based on their value(s) when compared to a passed value or values.
+     * Value or values are normalized to an array of strings that can be matched to option keys.
+     * @param {string|number|Array<string|number>} value - The value(s) to select.
+     */
+    selectByValue(value: string | number | Array<string | number>): void;
+    /**
+     * Resets the selected options to an empty array.
+     */
+    reset(): void;
+    /**
+     * SUBSCRIPTION, NOTIFICATION AND EVENT DISPATCH METHODS
+     */
+    /**
+     * Subscribes a callback to menu service events.
+     * @param {Function} callback - The callback to invoke on events.
+     */
+    subscribe(callback: Function): void;
+    /**
+     * Remove a previously subscribed callback from menu service events.
+     * @param {Function} callback
+     */
+    unsubscribe(callback: Function): void;
+    /**
+     * Stages an update to notify subscribers of state and value changes.
+     */
+    stageUpdate(): void;
+    /**
+     * Notifies subscribers of a menu service event.
+     * All notifications are sent to all subscribers.
+     * @param {string} event - The event to send to subscribers.
+     */
+    notify(event: string): void;
+    /**
+     * Notifies subscribers of a state change (selected options has changed).
+     */
+    notifyStateChange(): void;
+    /**
+     * Notifies subscribers of a value change (current value has changed).
+     */
+    notifyValueChange(): void;
+    /**
+     * Dispatches a custom event from the host element.
+     * @param {string} eventName
+     * @param {any} detail
+     */
+    dispatchChangeEvent(eventName: string, detail: any): void;
+    /**
+     * MENU OPTION MANAGEMENT METHODS
+     */
+    /**
+     * Adds a menu option to the service's list.
+     * @param {AuroMenuOption} option - the option to track
+     */
+    addMenuOption(option: AuroMenuOption): void;
+    /**
+     * Removes a menu option from the service's list.
+     * @param {AuroMenuOption} option - the option to remove
+     */
+    removeMenuOption(option: AuroMenuOption): void;
+    /**
+     * UTILITIES
+     */
+    /**
+     * Normalizes a value or array of values into an array of strings for option selection.
+     * This function ensures that input values are consistently formatted for matching menu options.
+     *
+     * @param {string|number|Array<string|number>} value - The value(s) to normalize.
+     * @returns {Array<string>} An array of string values suitable for option matching.
+     * @throws {Error} If any value is not a string or number.
+     */
+    _getNormalizedValues(value: string | number | Array<string | number>): Array<string>;
+    /**
+     * Returns whether two arrays of options contain the same elements.
+     * @param {AuroMenuOption[]} arr1 - First array of options.
+     * @param {AuroMenuOption[]} arr2 - Second array of options.
+     * @returns {boolean} True if arrays match, false otherwise.
+     */
+    optionsArraysMatch(arr1: AuroMenuOption[], arr2: AuroMenuOption[]): boolean;
+}
+export const MenuContext: import("@lit/context").Context<"menu-context", any>;
+import { AuroMenuOption } from "./auro-menuoption";

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

@@ -7,6 +7,10 @@
  * @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.
  * @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.
@@ -20,6 +24,13 @@
  */
 export class AuroMenu extends AuroElement {
     static get properties(): {
+        /**
+         * Allows deselecting an already selected option when clicked again in single-select mode.
+         */
+        allowDeselect: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
         noCheckmark: {
             type: BooleanConstructor;
             reflect: boolean;
@@ -49,6 +60,10 @@ export class AuroMenu extends AuroElement {
             reflect: boolean;
             attribute: string;
         };
+        selectAllMatchingOptions: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
         /**
          * Value selected for the component.
          */
@@ -66,6 +81,11 @@ export class AuroMenu extends AuroElement {
             reflect: boolean;
             attribute: boolean;
         };
+        options: {
+            type: ArrayConstructor;
+            reflect: boolean;
+            attribute: boolean;
+        };
         layout: {
             type: StringConstructor;
             attribute: string;
@@ -94,9 +114,11 @@ export class AuroMenu extends AuroElement {
     optionSelected: any;
     matchWord: any;
     noCheckmark: boolean;
-    optionActive: Element;
+    optionActive: any;
     loading: boolean;
     multiSelect: boolean;
+    allowDeselect: boolean;
+    selectAllMatchingOptions: boolean;
     /**
      * Handles keyboard navigation.
      * @private
@@ -104,22 +126,24 @@ export class AuroMenu extends AuroElement {
      */
     private handleKeyDown;
     /**
-     * Handles option selection via mouse.
+     * Handles slot change events.
      * @private
-     * @param {MouseEvent} event - Event object from the browser.
      */
-    private handleMouseSelect;
+    private handleSlotChange;
     /**
-     * Handles option hover events.
-     * @private
-     * @param {CustomEvent} event - Event object from the browser.
+     * @readonly
+     * @returns {Array<HTMLElement>} - Returns the array of available menu options.
+     * @deprecated use `options` property instead.
      */
-    private handleOptionHover;
+    readonly get items(): Array<HTMLElement>;
     /**
-     * Handles slot change events.
-     * @private
+     * @param {number} value - Sets the index of the currently active option.
      */
-    private handleSlotChange;
+    set index(value: number);
+    /**
+     * @returns {number} - Returns the index of the currently active option.
+     */
+    get index(): number;
     /**
      * Formatted value based on `multiSelect` state.
      * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
@@ -127,45 +151,75 @@ export class AuroMenu extends AuroElement {
      * @returns {String|Array<String>}
      */
     private get formattedValue();
+    /**
+     * Gets the current property values for the menu service.
+     * @private
+     * @returns {Object}
+     */
+    private get propertyValues();
+    /**
+     * Provides the menu context to child components.
+     * Initializes the MenuService and subscribes to menu changes.
+     * @protected
+     */
+    protected provideContext(): void;
+    menuService: MenuService;
+    _contextProvider: ContextProvider<import("@lit/context").Context<"menu-context", any>, this>;
+    /**
+     * Updates the currently active option in the menu.
+     * @param {HTMLElement} option - The option to set as active.
+     */
+    updateActiveOption(option: HTMLElement): void;
+    /**
+     * Sets the internal value and manages update state.
+     * @param {String|Array<String>} value - The value to set.
+     * @protected
+     */
+    protected setInternalValue(value: string | Array<string>): void;
+    internalUpdateInProgress: boolean;
+    /**
+     * Handles changes from the menu service and updates component state.
+     * @param {Object} event - The event object from the menu service.
+     * @protected
+     */
+    protected handleMenuChange(event: any): void;
+    _index: any;
+    options: any;
+    /**
+     * Gets the currently selected options.
+     * @returns {Array<HTMLElement>}
+     */
+    get selectedOptions(): Array<HTMLElement>;
+    /**
+     * Gets the first selected option, or null if none.
+     * @returns {HTMLElement|null}
+     */
+    get selectedOption(): HTMLElement | null;
     firstUpdated(): void;
     loadingSlots: NodeListOf<Element>;
+    updated(changedProperties: any): void;
     /**
      * Sets an attribute that matches the default tag name if the tag name is not the default.
      * @param {string} tagName - The tag name to set as an attribute.
      * @private
      */
     private setTagAttribute;
-    updated(changedProperties: any): void;
-    index: any;
     /**
-     * Updates the UI state and appearance of menu items based on changed properties.
-     * @private
-     * @param {Map<string, boolean>} changedProperties - LitElement's changed properties map.
+     * Sets the loading state and dispatches a loading change event.
+     * @param {boolean} isLoading - Whether the menu is loading.
+     * @protected
      */
-    private updateItemsState;
+    protected setLoadingState(isLoading: boolean): void;
     /**
      * Initializes the menu's state and structure.
      * @private
      */
     private initializeMenu;
     /**
-     * Initializes menu items and their attributes.
-     * @private
-     */
-    private initItems;
-    items: Element[];
-    /**
-     * Updates menu state when an option is selected.
-     * @private
-     * @param {HTMLElement} option - The option element to select.
-     */
-    private handleSelectState;
-    /**
-     * Deselects a menu option and updates related state.
-     * @private
-     * @param {HTMLElement} option - The menuoption to be deselected.
+     * Selects the currently highlighted option.
+     * @protected
      */
-    private handleDeselectState;
+    protected makeSelection(): void;
     /**
      * Resets all options to their default state.
      * @private
@@ -184,28 +238,12 @@ export class AuroMenu extends AuroElement {
      */
     private handleNestedMenus;
     /**
-     * Makes a selection based on the current index or clicked option.
-     * @private
-     */
-    private makeSelection;
-    /**
-     * Toggle the selection state of the menuoption.
-     * @private
-     * @param {HTMLElement} option - The menuoption to toggle.
+     * Navigates the menu options in the specified direction.
+     * @param {'up'|'down'} direction - The direction to navigate.
+     * @protected
      */
-    private toggleOption;
+    protected navigateOptions(direction: "up" | "down"): void;
     rootMenu: boolean;
-    /**
-     * Navigates through options using keyboard.
-     * @private
-     * @param {string} direction - 'up' or 'down'.
-     */
-    private navigateOptions;
-    /**
-     * Updates the active option state and dispatches events.
-     * @param {number} index - Index of the option to make active.
-     */
-    updateActiveOption(index: number): void;
     /**
      * Handles custom events defined on options.
      * @private
@@ -244,3 +282,5 @@ export class AuroMenu extends AuroElement {
     protected renderLayout(): void;
 }
 import { AuroElement } from "../../layoutElement/src/auroElement.js";
+import { MenuService } from "./auro-menu.context.js";
+import { ContextProvider } from "@lit/context";

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

@@ -9,27 +9,52 @@
  * @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.
+     *
+     * @example
+     * AuroMenuOption.register("custom-menuoption") // this will register this element to <custom-menuoption/>
+     *
+     */
+    static register(name?: string): void;
     static get properties(): {
-        nocheckmark: {
+        disabled: {
             type: BooleanConstructor;
             reflect: boolean;
         };
-        selected: {
-            type: BooleanConstructor;
+        event: {
+            type: StringConstructor;
             reflect: boolean;
         };
-        disabled: {
-            type: BooleanConstructor;
+        key: {
+            type: StringConstructor;
             reflect: boolean;
         };
-        value: {
+        menuService: {
+            type: ObjectConstructor;
+            state: boolean;
+        };
+        matchWord: {
             type: StringConstructor;
+            state: boolean;
+        };
+        nocheckmark: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        selected: {
+            type: BooleanConstructor;
             reflect: boolean;
         };
         tabIndex: {
             type: NumberConstructor;
             reflect: boolean;
         };
+        value: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
         layout: {
             type: StringConstructor;
             attribute: string;
@@ -38,14 +63,11 @@ export class AuroMenuOption extends AuroElement {
     };
     static get styles(): import("lit").CSSResult[];
     /**
-     * This will register this element with the browser.
-     * @param {string} [name="auro-menuoption"] - The name of element that you want to register to.
-     *
-     * @example
-     * AuroMenuOption.register("custom-menuoption") // this will register this element to <custom-menuoption/>
-     *
+     * Returns whether the menu option is currently active and selectable.
+     * An option is considered active if it is not hidden, not disabled, and not static.
+     * @returns {boolean} True if the option is active, false otherwise.
      */
-    static register(name?: string): void;
+    get isActive(): boolean;
     /**
      * @private
      */
@@ -62,8 +84,87 @@ export class AuroMenuOption extends AuroElement {
      * @private
      */
     private runtimeUtils;
+    menuService: any;
+    unsubscribe: any;
+    /**
+     * Handles changes from the menu service and updates the option's state.
+     * This function synchronizes the option's properties and selection/highlight state with menu events.
+     * @param {Object} event - The event object from the menu service.
+     */
+    handleMenuChange(event: any): void;
+    _contextConsumer: ContextConsumer<import("@lit/context").Context<"menu-context", any>, this>;
+    key: any;
     firstUpdated(): void;
     updated(changedProperties: any): void;
+    /**
+     * Sets up event listeners for user interaction with the menu option.
+     * This function enables click and mouse enter events to trigger selection and highlighting logic.
+     */
+    bindEvents(): void;
+    /**
+     * Attaches this menu option to a menu service and subscribes to its events.
+     * This method enables the option to participate in menu selection and highlighting logic.
+     * @param {Object} service - The menu service instance to attach to.
+     */
+    attachTo(service: any): void;
+    active: boolean;
+    /**
+     * Updates the internal selected state of the menu option bypassing 'updated' and triggers custom events if selected.
+     * This function ensures the option's selection state is synchronized with menu logic and notifies listeners.
+     * @param {boolean} isSelected - Whether the option should be marked as selected.
+     */
+    setInternalSelected(isSelected: boolean): void;
+    internalUpdateInProgress: boolean;
+    /**
+     * Sets the selected state of the menu option.
+     * This function updates whether the option is currently selected.
+     * @param {boolean} isSelected - Whether the option should be marked as selected.
+     * @deprecated Simply modify the `selected` property directly instead.
+     */
+    setSelected(isSelected: boolean): void;
+    /**
+     * Updates the active state and visual highlighting of the menu option.
+     * This function toggles the option's active status and applies or removes the active CSS class.
+     * @param {boolean} isActive - Whether the option should be marked as active.
+     * @deprecated Simply modify the `active` property directly instead.
+     */
+    updateActive(isActive: boolean): void;
+    /**
+     * Updates the CSS class for the menu option based on its active state.
+     * This function adds or removes the 'active' class to visually indicate the option's active status.
+     * @private
+     */
+    private updateActiveClasses;
+    /**
+     * Updates the visual highlighting of text within the menu option based on the current match word.
+     * This function highlights matching text segments and manages nested spacers for display formatting.
+     * @private
+     */
+    private updateTextHighlight;
+    /**
+     * Handles click events on the menu option, toggling its selected state.
+     * This function dispatches a click event and updates selection if the option is not disabled.
+     * @private
+     */
+    private handleClick;
+    /**
+     * Handles mouse enter events to highlight the menu option.
+     * This function updates the menu service to set this option as the currently highlighted item if not disabled.
+     * @private
+     */
+    private handleMouseEnter;
+    /**
+     * Dispatches custom events defined for this menu option.
+     * This function notifies listeners when a custom event is triggered by the option.
+     * @private
+     */
+    private handleCustomEvent;
+    /**
+     * Dispatches a click event for this menu option.
+     * This function notifies listeners that the option has been clicked.
+     * @private
+     */
+    private dispatchClickEvent;
     /**
      * Generates an HTML element containing an SVG icon based on the provided `svgContent`.
      *
@@ -80,3 +181,4 @@ export class AuroMenuOption extends AuroElement {
     protected renderLayout(): void;
 }
 import { AuroElement } from "../../layoutElement/src/auroElement.js";
+import { ContextConsumer } from '@lit/context';