@aurodesignsystem-dev/auro-formkit 0.0.0-pr1498.0 → 0.0.0-pr1499.0

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

@@ -0,0 +1,238 @@
+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 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.
+     * @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: any;
+    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[];
+    _pendingValue: string | number | (string | number)[] | null;
+    _pendingRetryScheduled: boolean;
+    _pendingRetryCount: number;
+    /**
+     * 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: Object): 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;
+    /**
+     * Queues a pending value and schedules a bounded retry.
+     * @param {string|number|Array<string|number>} value - The value to retry.
+     */
+    queuePendingValue(value: string | number | Array<string | number>): void;
+    /**
+     * Clears pending retry state.
+     */
+    clearPendingValue(): 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(meta?: {}): 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(meta?: {}): void;
+    /**
+     * Notifies subscribers of a value change (current value has changed).
+     */
+    notifyValueChange(meta?: {}): 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>;

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

@@ -6,6 +6,7 @@
  * @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<{ values: HTMLElement[] }>} auroMenu-deselectPrevented - Notifies that deselection was prevented and includes the affected options in `detail.values`.
  * @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
@@ -14,6 +15,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;
+        };
         /**
          * When true, the entire menu and all options are disabled.
          */
@@ -21,6 +29,18 @@ export class AuroMenu extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * 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
@@ -73,6 +93,30 @@ export class AuroMenu extends AuroElement {
         optionSelected: {
             type: ObjectConstructor;
         };
+        options: {
+            type: ArrayConstructor;
+            reflect: boolean;
+            attribute: boolean;
+        };
+        /**
+         * 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.
          */
@@ -81,16 +125,11 @@ export class AuroMenu extends AuroElement {
             reflect: boolean;
             attribute: string;
         };
-        layout: {
-            type: StringConstructor;
-            attribute: string;
-            reflect: boolean;
-        };
     };
     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/>
@@ -105,41 +144,30 @@ export class AuroMenu extends AuroElement {
      * @private
      */
     private size;
-    value: any;
     optionSelected: any;
     matchWord: any;
     noCheckmark: boolean;
-    optionActive: Element | undefined;
+    optionActive: any;
     loading: boolean;
     multiSelect: boolean;
-    /**
-     * Handles keyboard navigation and selection.
-     * @private
-     * @param {KeyboardEvent} event - The keydown event.
-     */
-    private handleKeyDown;
-    /**
-     * Handles option selection via click events from menuoptions.
-     * @private
-     * @param {CustomEvent} event - The auroMenuOption-click event.
-     */
-    private handleMouseSelect;
-    /**
-     * Handles option hover events.
-     * @private
-     * @param {CustomEvent} event - Event object from the browser.
-     */
-    private handleOptionHover;
+    allowDeselect: boolean;
+    selectAllMatchingOptions: boolean;
     /**
      * Handles slot change events.
      * @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.
+     * @deprecated Use `options` property instead.
      */
-    readonly get options(): Array<HTMLElement>;
+    readonly get items(): Array<HTMLElement>;
     /**
      * @param {number} value - Sets the index of the currently active option.
      */
@@ -149,72 +177,83 @@ export class AuroMenu extends AuroElement {
      */
     get index(): number;
     /**
-     * Gets the currently selected options as an array.
-     * @returns {Array<HTMLElement>}
+     * Formatted value based on `multiSelect` state.
+     * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
+     * @private
+     * @returns {String|Array<String>}
      */
-    get selectedOptions(): Array<HTMLElement>;
+    private get formattedValue();
     /**
-     * Gets the first selected option, or null if none.
-     * @returns {HTMLElement|null}
+     * Gets the current property values for the menu service.
+     * @private
+     * @returns {Object}
      */
-    get selectedOption(): HTMLElement | null;
+    private get propertyValues();
     /**
-     * @readonly
-     * @returns {string} - Returns the label of the currently selected option(s).
+     * Provides the menu context to child components.
+     * Initializes the MenuService and subscribes to menu changes.
+     * @protected
      */
-    readonly get currentLabel(): string;
+    protected provideContext(): void;
+    rootMenu: boolean | undefined;
+    menuService: any;
+    _contextProvider: any;
     /**
-     * Formatted value based on `multiSelect` state.
-     * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
-     * @private
-     * @returns {String|Array<String>}
+     * Updates the currently active option in the menu.
+     * @param {HTMLElement} option - The option to set as active.
      */
-    private get formattedValue();
+    updateActiveOption(option: HTMLElement): void;
     /**
-     * Selects options by value.
-     * @param {string|string[]|undefined|null} value - The value(s) to select.
-     * @public
+     * 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 | undefined;
+    value: any;
+    /**
+     * Handles changes from the menu service and updates component state.
+     * @param {Object} event - The event object from the menu service.
+     * @protected
+     */
+    protected handleMenuChange(event: Object): 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}
      */
-    public selectByValue(value: string | string[] | undefined | null): void;
+    get selectedOption(): HTMLElement | null;
     firstUpdated(): void;
     loadingSlots: NodeListOf<Element> | undefined;
+    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: number | undefined;
     /**
-     * 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[] | undefined;
-    /**
-     * 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
@@ -233,28 +272,11 @@ export class AuroMenu extends AuroElement {
      */
     private handleNestedMenus;
     /**
-     * Makes a selection based on the current index.
-     * @private
-     */
-    private makeSelection;
-    /**
-     * Toggle the selection state of the menuoption.
-     * @private
-     * @param {HTMLElement} option - The menuoption to toggle.
-     */
-    private toggleOption;
-    rootMenu: boolean | undefined;
-    /**
-     * Navigates through options using keyboard.
-     * @param {string} direction - 'up' or 'down'.
-     */
-    navigateOptions(direction: string): void;
-    /**
-     * Updates the active option state and dispatches events.
-     * Accepts either a numeric index or an HTMLElement option.
-     * @param {number|HTMLElement} indexOrOption - Index of the option or the option element to make active.
+     * Navigates the menu options in the specified direction.
+     * @param {'up'|'down'} direction - The direction to navigate.
+     * @protected
      */
-    updateActiveOption(indexOrOption: number | HTMLElement): void;
+    protected navigateOptions(direction: "up" | "down"): void;
     /**
      * Handles custom events defined on options.
      * @private
@@ -267,13 +289,6 @@ export class AuroMenu extends AuroElement {
      * @private
      */
     private notifySelectionChange;
-    /**
-     * @private
-     * @param {any} current - Current selection.
-     * @param {any} next - New selection to compare.
-     * @returns {boolean} Whether the selections are equal.
-     */
-    private selectionEquals;
     /**
      * Checks if an option is currently selected.
      * @private