@nova-design-system/nova-webcomponents 3.0.0-beta.28 → 3.0.0-beta.30

package/dist/types/components/nv-fieldmultiselect/nv-fieldmultiselect.d.ts

@@ -0,0 +1,405 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { TextInputAutocomplete } from '../../utils/constants';
+import { DropdownItemSelectedEventDetail } from '../nv-fielddropdownitem/DropdownItemSelectedEventDetail';
+/**
+ * @slot content - The content of the list.
+ * @slot leading-input - Content to be placed before the input text, within the input container.
+ * @slot before-input - Content to be placed before the input text, outside the input container.
+ * @slot after-input - Content to be placed after the input text, outside the input container.
+ * @slot label - Content to be placed as the label, will override the label prop.
+ * @slot description - Content to be placed as the description, will override the description prop.
+ * @slot error-description - Content to be placed as the error description, will override the errorDescription prop.
+ */
+export declare class NvFieldmultiselect {
+    el: HTMLNvFieldmultiselectElement;
+    private inputElement;
+    private popoverElement;
+    /**
+     * Timer for debouncing input events.
+     * Private property preferred over @State as it:
+     * - Doesn't need to trigger re-renders
+     * - Is purely for internal logic
+     * - Improves performance by avoiding Stencil's reactivity system
+     */
+    private debounceTimer;
+    /**
+     * Flag to prevent concurrent reordering operations.
+     * Private property preferred over @State as it:
+     * - Manages internal component logic without affecting UI
+     * - Avoids unnecessary re-renders
+     * - Provides better performance for rapid state changes
+     * - Only needs class-level scope
+     */
+    private isReordering;
+    /****************************************************************************/
+    /**
+     * Sets the ID for the input element and the for attribute of the associated
+     * label. If no ID is provided, a random one will be automatically generated
+     * to ensure unique identification, facilitating proper label association and
+     * accessibility.
+     */
+    readonly inputId: string;
+    /**
+     * Defines the name attribute of the input field, which is crucial for form
+     * submission. This value is used as the key in the key-value pair sent to
+     * the server, representing the input's data in form submissions. It should be
+     * unique within the form to avoid conflicts.
+     */
+    readonly name: string;
+    /**
+     * Lets you define the text that explains what users should enter in the text
+     * input field. It's a crucial element for making forms clear and user-friendly.
+     */
+    readonly label: string;
+    /**
+     * Add helpful hints or extra information under the text input field.
+     */
+    readonly description: string;
+    /**
+     * Display temporary text inside the input field.
+     */
+    readonly placeholder: string;
+    /**
+     * Defines the maximum height of the multiselect list when open.
+     */
+    readonly maxHeight: string;
+    /**
+     * Text for the badge showing the number of selected items.
+     */
+    readonly badgeLabel: string;
+    /**
+     * The text to display when no items match the filter.
+     */
+    readonly emptyresult: string;
+    /**
+     * Marks the input field as required.
+     */
+    readonly required: boolean;
+    /**
+     * Alters the input field's appearance to indicate an error.
+     */
+    readonly error: boolean;
+    /**
+     * A description that appears when there is an error.
+     */
+    readonly errorDescription: string;
+    /**
+     * Display the input field's content without allowing users to change it.
+     */
+    readonly readonly: boolean;
+    /**
+     * Disables the input field.
+     */
+    readonly disabled: boolean;
+    /**
+     * The autocomplete prop for faster input filling.
+     */
+    readonly autocomplete: `${TextInputAutocomplete}`;
+    /**
+     * Enables or disables the filtering feature for the multiselect items.
+     */
+    filterable: boolean;
+    /**
+     * Specifies the value of the input field.
+     */
+    value: string;
+    /**
+     * State of the multiselect popover.
+     */
+    open: boolean;
+    /**
+     * Multiselect mode: 'options' (JSON data) or 'slots' (custom items).
+     * This property is now reflected in the modeState.
+     */
+    readonly mode: 'options' | 'slots';
+    /**
+     * List of options available in the multiselect.
+     * @description The options are passed as a JSON string.
+     * @example options='[{"label": "Option 1", "value": "option1"}, {"label": "Option 2", "value": "option2"}]'
+     */
+    readonly options?: string;
+    /**
+     * Options configuration for the multiselect items.
+     */
+    parsedOptions: Array<{
+        /** Label to display for the option */
+        label: string;
+        /** Value associated with the option */
+        value: string;
+        /** Whether this option is a divider */
+        isDivider?: boolean;
+        /** Whether this option is disabled */
+        disabled?: boolean;
+        /** Additional description for the option */
+        description?: string;
+        /** Whether this option is pre-checked */
+        checked?: boolean;
+    }>;
+    /**
+     * List of selected values in the multiselect.
+     */
+    selectedValues: string[];
+    /**
+     * Sorted options for display.
+     */
+    sortedOptions: Array<{
+        /** Label to display for the option */
+        label: string;
+        /** Value associated with the option */
+        value: string;
+        /** Whether this option is a divider */
+        isDivider?: boolean;
+    }>;
+    /**
+     * The text entered by the user for filtering multiselect items.
+     */
+    filterText: string;
+    /**
+     * Determines whether the multiselect is filterable.
+     */
+    isFilterable: boolean;
+    /**
+     * Delay in milliseconds before the search is triggered when typing in the filter input.
+     * @default 300
+     */
+    readonly debounceDelay: number;
+    /**
+     * State for the mode of the multiselect.
+     * @type {'options' | 'slots'}
+     * @default 'options'
+     */
+    modeState: 'options' | 'slots';
+    /****************************************************************************/
+    /**
+     * Subscribe to click outside event.
+     */
+    connectedCallback(): void;
+    /**
+     * Unsubscribe from click outside event.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Event emitted when an item is selected.
+     */
+    dropdownItemSelected: EventEmitter<DropdownItemSelectedEventDetail>;
+    /**
+     * Emitted when the input value changes.
+     * @bind value
+     */
+    valueChanged: EventEmitter<string>;
+    /**
+     * Event emitted when the selection changes in the multiselect.
+     * Emits the current list of selected values.
+     */
+    multiselectChange: EventEmitter<string[]>;
+    /**
+     * Emitted when the input loses focus.
+     * @param {CustomEvent<boolean>} event - The event object containing the focus state.
+     */
+    handleOpenChanged(event: CustomEvent<boolean>): void;
+    /**
+     * Listen for the `itemChecked` event emitted by child items.
+     * @param {CustomEvent<{ value: string; checked: boolean }>} event - The event object containing the selected value and its checked state.
+     */
+    handleItemChecked(event: CustomEvent): void;
+    /**
+     * Emitted when the options change.
+     * @param {string | Array<{label: string, value: string, isDivider?: boolean, disabled?: boolean, description?: string, checked?: boolean}>} newValue - The new value of the options.
+     */
+    handleOptionsChange(newValue: string | Array<{
+        /** Label to display for the option */
+        label: string;
+        /** Value associated with the option */
+        value: string;
+        /** Whether this option is a divider */
+        isDivider?: boolean;
+        /** Whether this option is disabled */
+        disabled?: boolean;
+        /** Additional description for the option */
+        description?: string;
+        /** Whether this option is pre-checked */
+        checked?: boolean;
+    }>): void;
+    /**
+     * Emitted when the value changes.
+     */
+    watchValueHandler(): void;
+    /**
+     * Emitted when the filterable property changes.
+     * @param {boolean} newValue - The new value of the filterable property.
+     */
+    watchFilterableHandler(newValue: boolean): void;
+    handleSlotChange(event: Event): void;
+    /****************************************************************************/
+    /**
+     * Retrieves the current filter text entered by the user.
+     * @returns {string} The filter text.
+     */
+    getFilterText(): Promise<string>;
+    /**
+     * Set the initial selection based on the current value and update the inputElement value.
+     */
+    private setInitialSelection;
+    /**
+     * Reset the filter and make all items visible.
+     */
+    resetFilter(): Promise<void>;
+    /**
+     * Returns the list of selected values.
+     * @returns {string[]} The selected values.
+     */
+    getSelectedValues(): Promise<string[]>;
+    /**
+     * Reorder the content of the slot.
+     */
+    private reorderSlotContent;
+    /**
+     * Reorder the content for options mode with async handling
+     */
+    private reorderOptionsContent;
+    /**
+     * Filter multiselect items based on the text entered by the user.
+     */
+    private filterItems;
+    /**
+     * Filter multiselect items in options mode.
+     */
+    private filterOptionsItems;
+    /**
+     * Filter multiselect items in slots mode
+     */
+    private filterSlotsItems;
+    /**
+     * Handle badge close for options mode.
+     */
+    private handleBadgeCloseOptions;
+    /**
+     * Handle badge close for slots mode.
+     */
+    private handleBadgeCloseSlots;
+    /**
+     * Normalizes text by removing accents and converting to lowercase
+     * @param {string} text - The text to normalize
+     * @returns {string} The normalized text
+     *
+     * @example
+     * normalizeText("Café Latte") => "cafe latte"
+     *
+     * @description
+     * This function performs text normalization in three steps:
+     * 1. Decomposes characters into their base form and combining characters (NFD)
+     * 2. Removes all diacritical marks (accents, umlauts, etc.)
+     * 3. Converts to lowercase and trims whitespace
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize} - MDN documentation on String.normalize()
+     * @see {@link https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms} - More info about Unicode normalization forms
+     */
+    private normalizeText;
+    /**
+     * Handle click outside the component.
+     * @param {MouseEvent} event - The click event.
+     */
+    private handleClickOutside;
+    /**
+     * Handle popover close
+     */
+    private handlePopoverClose;
+    /**
+     * Handle keyboard events for options mode.
+     * @param {KeyboardEvent} event - The keyboard event.
+     */
+    private handleKeyDownOptions;
+    /**
+     * Handle input blur for options mode.
+     */
+    private handleInputBlurOptions;
+    /**
+     * Handle keyboard events & arrow key navigation.
+     * If the multiselect is not open, opens it and focuses on the first item if the list is not filterable.
+     * If the multiselect is open, handles arrow key navigation and closes it if the focus is outside the component.
+     * @param {KeyboardEvent} event - The keyboard event.
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * Updates the highlighted item in the dropdown list.
+     *
+     * @param {(HTMLNvFielddropdownitemElement | HTMLNvFielddropdownitemcheckElement)[]} items - The items to update.
+     * @param {number} index - The index of the item to highlight.
+     */
+    private updateHighlightedItem;
+    /**
+     * Focus on the first item in the dropdown list.
+     */
+    private focusFirstItem;
+    /**
+     * Handle click on the input container for options mode.
+     * @param {MouseEvent} event - The click event.
+     */
+    private handleInputContainerClickOptions;
+    /**
+     * Handle click on the input container for slots mode.
+     * @param {MouseEvent} event - The click event.
+     */
+    private handleInputContainerClickSlots;
+    /**
+     * Handle input change for options mode.
+     * @param {Event} event - The input event.
+     */
+    private readonly handleInputOptions;
+    /**
+     * Handle input change for slots mode
+     * @param {Event} event - The input event.
+     */
+    private readonly handleInputSlots;
+    /**
+     * Handle input focus for options mode.
+     */
+    private handleInputFocusOptions;
+    /**
+     * Handle input focus for slots mode.
+     */
+    private handleInputFocusSlots;
+    /**
+     * Handle input blur for slots mode.
+     */
+    private handleInputBlurSlots;
+    /**
+     * Toggle the multiselect popover for options mode.
+     */
+    private togglePopoverOptions;
+    /**
+     * Toggle the multiselect popover for slots mode.
+     */
+    private togglePopoverSlots;
+    /**
+     * Handle keyboard events for slots mode.
+     * @param {KeyboardEvent} event - The keyboard event.
+     */
+    private handleKeyDownSlots;
+    /**
+     * Watch for changes in the mode prop and update modeState accordingly
+     * @param {string} newValue - The new mode value
+     */
+    handleModeChange(newValue: 'options' | 'slots'): void;
+    /****************************************************************************/
+    /**
+     * Renders the component in options mode
+     * @returns {any} The JSX for options mode
+     */
+    private renderOptionsMode;
+    /**
+     * Renders the component in slots mode
+     * @returns {any} The JSX for slots mode
+     */
+    private renderSlotsMode;
+    /**
+     * Renders description and error description sections
+     * @returns {any} The JSX for descriptions
+     */
+    private renderDescriptions;
+    /**
+     * Main render method that decides which mode to render
+     * @returns {any} The JSX for the component
+     */
+    render(): any;
+}

package/dist/types/components/nv-fieldmultiselect/nv-fieldmultiselect.docs.d.ts

@@ -0,0 +1,4 @@
+import type { NovaDocs } from '../../nova-docs';
+import { Components } from '../../components';
+declare const NvFieldmultiselectDocs: NovaDocs<Components.NvFieldmultiselect>;
+export default NvFieldmultiselectDocs;