@eui/components 19.1.2-snapshot-1741681025211 → 19.1.2-snapshot-1741955106555

package/fesm2022/eui-components-eui-autocomplete.mjs

@@ -4,15 +4,15 @@ import * as i7 from '@angular/common';
 import { isPlatformBrowser, CommonModule } from '@angular/common';
 import * as i6 from '@angular/forms';
 import { FormControl, Validators, ReactiveFormsModule } from '@angular/forms';
-import { BehaviorSubject, Subject, Subscription, fromEvent, takeUntil, filter } from 'rxjs';
+import { BehaviorSubject, Subject, Subscription, takeUntil, fromEvent, filter } from 'rxjs';
 import { TemplatePortal } from '@angular/cdk/portal';
 import * as i1$1 from '@angular/cdk/overlay';
 import { ConnectionPositionPair, OverlayModule } from '@angular/cdk/overlay';
 import { EuiChip, EuiChipTooltip, EuiChipModule } from '@eui/components/eui-chip';
 import { EuiTemplateDirective } from '@eui/components/directives';
-import { trigger, state, transition, style, group, animate } from '@angular/animations';
 import * as i1 from '@eui/components/shared';
 import { BaseStatesDirective } from '@eui/components/shared';
+import { trigger, state, transition, style, group, animate } from '@angular/animations';
 import * as i2 from '@angular/cdk/a11y';
 import { A11yModule } from '@angular/cdk/a11y';
 import * as i3 from '@angular/cdk/scrolling';
@@ -29,7 +29,7 @@ import { EuiIconModule } from '@eui/components/eui-icon';
  * @description
  * Validator checking if the user choose the value in the panel.
  *
- * @usageNotes
+ * @example
  * ```typescript
  * autocompleteData: EuiAutoCompleteItem[] = [
  *    { id: 1, label: 'Ananas' },
@@ -66,7 +66,17 @@ const panelAnimation = trigger('panelAnimation', [
     transition(':leave, visible => hidden', [animate('0.05s linear', style({ opacity: 0 }))]),
 ]);
 
+/**
+ * @description
+ * Component used internally by `eui-autocomplete` to display the options in the panel.
+ */
 class EuiAutocompleteOptionComponent {
+    /**
+     * @description
+     * Computes and returns the CSS classes for the component based on its current state.
+     *
+     * @returns {string} Space-separated string of CSS class names
+     */
     get cssClasses() {
         return [
             this.baseStatesDirective.getCssClasses('eui-autocomplete-option'),
@@ -79,9 +89,28 @@ class EuiAutocompleteOptionComponent {
     }
     constructor(baseStatesDirective) {
         this.baseStatesDirective = baseStatesDirective;
+        /**
+         * ARIA role for the host element to ensure proper accessibility.
+         * @default 'option'
+         */
         this.role = 'option';
+        /**
+         * Wheter the option is active in the panel.
+         *
+         * @default false
+         */
         this.isActive = false;
+        /**
+         * Wheter the option is disabled in the panel.
+         *
+         * @default false
+         */
         this.isDisabled = false;
+        /**
+         * Wheter the option is displayed inside a group.
+         *
+         * @default false
+         */
         this.isGroupItem = false;
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.1", ngImport: i0, type: EuiAutocompleteOptionComponent, deps: [{ token: i1.BaseStatesDirective }], target: i0.ɵɵFactoryTarget.Component }); }
@@ -114,10 +143,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.1", ngImpor
                 args: [{ transform: booleanAttribute }]
             }] } });
 
+/**
+ * @description
+ * Component used internally by `eui-autocomplete` with the option `groupBy`. It allows to display the options in groups.
+ */
 class EuiAutocompleteOptionGroupComponent {
     constructor() {
+        /**
+         * ARIA role for the host element to ensure proper accessibility.
+         * @default 'optgroup'
+         */
         this.role = 'optgroup';
     }
+    /**
+     * @description
+     * Computes and returns the CSS classes for the component based on its current state.
+     *
+     * @returns {string} Space-separated string of CSS class names
+     */
     get cssClasses() {
         return ['eui-autocomplete-option-group'].join(' ').trim();
     }
@@ -137,7 +180,34 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.1", ngImpor
                 type: Input
             }] } });
 
+/**
+ * @description
+ * `eui-autocomplete` is a text input showing some suggestions when the user types letters. It can be enhanced with chips to allow user to select multiple values.
+ *
+ * @example
+ * ```
+ * <eui-autocomplete [autocompleteData]="autocompleteData"></eui-autocomplete>
+ * ```
+ *
+ * ```
+ * public autocompleteData: EuiAutoCompleteItem[] = [
+ *    { id: 1, label: 'Ananas' },
+ *    { id: 2, label: 'Apple' },
+ *    { id: 3, label: 'Banana' },
+ *    { id: 4, label: 'Blackberry' },
+ *    { id: 5, label: 'Coconut' },
+ * ];
+ * ```
+ *
+ * See {@link https://eui.ecdevops.eu/eui-showcase-ux-components-19.x/style-guide/components/eui-autocomplete}.
+ */
 class EuiAutocompleteComponent {
+    /**
+     * @description
+     * Computes and returns the CSS classes for the component based on its current state.
+     *
+     * @returns {string} Space-separated string of CSS class names
+     */
     get cssClasses() {
         return [
             this.baseStatesDirective.getCssClasses('eui-autocomplete'),
@@ -157,32 +227,154 @@ class EuiAutocompleteComponent {
         this.baseStatesDirective = baseStatesDirective;
         this.control = control;
         this.platformId = platformId;
+        /**
+         * Datas to be used in the autocomplete.
+         */
         this.autocompleteData = [];
+        /**
+         * Sets the maximum number of options that will be visible in the autocomplete panel.
+         *
+         * @default 5
+         */
         this.visibleOptions = 5;
+        /**
+         * Sets the way the options should be retrieved.
+         *
+         * @default 'contains'
+         */
         this.matching = 'contains';
+        /**
+         * Sets the placeholder of the text input.
+         */
         this.placeholder = '';
+        /**
+         * Sets the options that will be selected selected by default.
+         */
         this.autocompleteDataSelected = [];
+        /**
+         * Sets the sort criteria of the chips.
+         *
+         * @type {('ASC' | 'DESC')}
+         * @default 'ASC'
+         */
         this.chipsSortOrder = 'ASC';
+        /**
+         * In combination with `isChipsSorted`. Sets the sort criteria of the options in the panel.
+         *
+         * @type {('ASC' | 'DESC')}
+         * @default 'ASC'
+         */
         this.itemsSortOrder = 'ASC';
+        /**
+         * In Combination with `isItemsSorted`. Sets the position of the chips relative to the text input.
+         *
+         * @type {('top' | 'bottom' | 'inside')}
+         * @default 'top''
+         */
         this.chipsPosition = 'top';
+        /**
+         * In combination with `maxVisibleChipsCount`, sets the label of the 'more label' button, if not provided an arrow right icon will be displayed only.
+         */
         this.toggleLinkMoreLabel = null;
+        /**
+         * In combination with `maxVisibleChipsCount`, sets the label of the 'less label' button, if not provided an arrow left icon will be displayed only.
+         */
         this.toggleLinkLessLabel = null;
+        /**
+         * Sets a CSS class to be added on the options panel container.
+         */
         this.classList = null;
+        /**
+         * In combination with `isChipsDragAndDrop`, sets the name to the chips source with which a drag and drop will be done.
+         */
         this.dragAndDropConnectedTo = [];
+        /**
+         * In combination with `hasChips`. Wheter the user can add a value, which is not part of the options, to craete a chip.
+         *
+         * @default true
+         */
         this.isFreeValueAllowed = true;
+        /**
+         * Wheter autocomplete is in readonly mode.
+         *
+         * @default false
+         */
         this.isReadonly = false;
+        /**
+         * Wheter loading spinner is displayed in text input.
+         *
+         * @default false
+         */
         this.isLoading = false;
+        /**
+         * Wheter autocomplete will display the selected values with chips.
+         *
+         * @default false
+         */
         this.hasChips = false;
+        /**
+         * Wheter autocomplete will get the data in an asynchronous way.
+         *
+         * @default false
+         */
         this.isAsync = false;
+        /**
+         * Wheter this chips are sorted on their label.
+         *
+         * @default false
+         */
         this.isChipsSorted = false;
+        /**
+         * Wheter this items in the panel are sorted on their label.
+         *
+         * @default false
+         */
         this.isItemsSorted = false;
+        /**
+         * Wheter the chip can be removed from the selection.
+         * When a chip is removed, its value goes back in the panel.
+         *
+         * @default true
+         */
         this.isChipsRemovable = true;
+        /**
+         * Wheter the chips can have multiple times the same value.
+         * With this option, the value is not removed from the panel when choosen.
+         *
+         * @default false
+         */
         this.isDuplicateValueAllowed = false;
+        /**
+         * In combination with `hasChips`. Wheter the chip is added when the text input is blurred.
+         *
+         * @default false
+         */
         this.isAddOnBlur = false;
+        /**
+         * In combination with `hasChips` and `isFreeValueAllowed=false`. Wheter the text input is empty after blurring when no value has been selected in the panel.
+         *
+         * @default false
+         */
         this.isForceSelection = false;
+        /**
+         * Wheter a limitated amount, defined by this option, is used to diplay the chips.
+         */
         this.maxVisibleChipsCount = null;
+        /**
+         * Wheter the chips label length are limitated by the value of this option.
+         */
         this.chipsLabelTruncateCount = null;
+        /**
+         * In combination with `maxVisibleChipsCount`. Wheter all chips are shown by default.
+         *
+         * @default false
+         */
         this.isMaxVisibleChipsOpened = false;
+        /**
+         * Wheter the chips can be drag and dropped.
+         *
+         * @default false
+         */
         this.isChipsDragAndDrop = false;
         this.autocompleteOptions = new BehaviorSubject(this.autocompleteData);
         this.selectedOptionIndex = 0;
@@ -192,17 +384,53 @@ class EuiAutocompleteComponent {
         this.groupedOptions = new BehaviorSubject({});
         this.globalOptionIndex = 0;
         this.itemSize = 40;
+        /**
+         * Event emitted when the panel is closed.
+         */
         this.panelClose = new EventEmitter();
+        /**
+         * Event emitted when the panel is opened.
+         */
         this.panelOpen = new EventEmitter();
+        /**
+         * Event emitted when the text input gets the focus.
+         */
         this.inputFocus = new EventEmitter();
+        /**
+         * Event emitted when the text input is blurred.
+         */
         this.inputBlur = new EventEmitter();
+        /**
+         * Event emitted when the text input is cleared.
+         */
         this.clear = new EventEmitter();
+        /**
+         * Event emitted when an option is selected or when the selection is modified.
+         */
         this.selectionChange = new EventEmitter();
+        /**
+         * Event emitted when an option is selected.
+         */
         this.itemAdd = new EventEmitter();
+        /**
+         * Event emitted when an option is removed.
+         */
         this.itemRemove = new EventEmitter();
+        /**
+         * Event emitted when the value of the text input changes.
+         */
         this.inputChange = new EventEmitter();
+        /**
+         * Event emitted when a chip drag starts.
+         */
         this.chipDragStart = new EventEmitter();
+        /**
+         * Event emitted when a chip drag is released.
+         */
         this.chipDragRelease = new EventEmitter();
+        /**
+         * Event emitted when a chip is dropped.
+         */
         this.chipDrop = new EventEmitter();
         this.destroy$ = new Subject();
         this.isOpen$ = new BehaviorSubject(false);
@@ -244,7 +472,6 @@ class EuiAutocompleteComponent {
         }
     }
     ngOnInit() {
-        fromEvent(this.elementRef.nativeElement, 'focus');
         this.euiAppShellService.state$.pipe(takeUntil(this.destroy$)).subscribe((state) => {
             this.itemSize = state.appBaseFontSize === '16px' ? 40 : 35;
         });
@@ -319,6 +546,11 @@ class EuiAutocompleteComponent {
         this.autocompleteOptionsSubscription.unsubscribe();
         this.windowResizeSubscription.unsubscribe();
     }
+    /**
+     * Calculates the height that the virtual scroll need to have.
+     *
+     * @type {number}
+     */
     get cdkVirtualScrollViewport() {
         if (this.groupBy) {
             const filteredOptionGroups = this.autocompleteOptions.value
@@ -341,12 +573,25 @@ class EuiAutocompleteComponent {
                 this.autocompleteOptions.value.length * this.itemSize;
         }
     }
+    /**
+     * Returns the opening state of the panel.
+     *
+     * @type {boolean}
+     */
     get isOpen() {
         return this.isOpen$.value;
     }
+    /**
+     * Checks if autocomplete options are available.
+     *
+     * @returns {boolean} `true` if options are present, otherwise `false`.
+     */
     get hasOptionsResult() {
         return this.autocompleteOptions.value.length > 0;
     }
+    /**
+     * Method that creates and opens the panel containing autocomplete options.
+     */
     openPanel() {
         if (!this.isOpen && !this.isReadonly) {
             this.scrollDispatcherSubscription = this.scrollDispatcher
@@ -531,6 +776,9 @@ class EuiAutocompleteComponent {
             this.panelOpen.emit();
         }
     }
+    /**
+     * Closes the autocomplete panel.
+     */
     closePanel() {
         this.selectedOptionIndex = 0;
         this.overlayRef.dispose();
@@ -543,6 +791,11 @@ class EuiAutocompleteComponent {
         this.windowResizeSubscription.unsubscribe();
         this.panelClose.emit();
     }
+    /**
+     * Method called when an option is selected.
+     *
+     * @param e Selected option
+     */
     onOptionSelected(e) {
         if (!e.isDisabled) {
             if (this.hasChips) {
@@ -564,6 +817,11 @@ class EuiAutocompleteComponent {
             this.closePanel();
         }
     }
+    /**
+     * Method called when an option is added through the text input.
+     *
+     * @param value Value to add
+     */
     add(value) {
         if (!value || (!this.isFreeValueAllowed && !this.autocompleteData.find(a => a.label === value.trim()))) {
             return;
@@ -618,6 +876,9 @@ class EuiAutocompleteComponent {
     onClear() {
         this.clear.emit();
     }
+    /**
+     * Text input focus handler.
+     */
     onFocus() {
         this.keyboardSubscription = fromEvent(this.input.nativeElement, 'keydown')
             .pipe(filter((event) => /^[a-zA-Z0-9]$/.test(event.key) ||
@@ -642,11 +903,19 @@ class EuiAutocompleteComponent {
         }
         this.inputFocus.emit();
     }
+    /**
+     * Text input blur handler.
+     */
     onBlur() {
         this.keyboardSubscription.unsubscribe();
         this.inputBlur.emit();
         this.onTouch();
     }
+    /**
+     * Called when a chip is removed.
+     *
+     * @param e Object containing the chip to remove.
+     */
     onChipRemove(e) {
         const event = e;
         const itemRemoved = this.autocompleteDataSelected.find(i => i.id === event.removed.id);
@@ -659,6 +928,11 @@ class EuiAutocompleteComponent {
         this.selectionChange.emit(this.autocompleteDataSelected);
         this.itemRemove.emit(itemRemoved);
     }
+    /**
+     * Called when a chip is dropped for reordering or from a source to another.
+     *
+     * @param e Object containing the chip dropped.
+     */
     onChipDropped(e) {
         const data = this.autocompleteData;
         this.autocompleteDataSelected = e.chips.map(c => data.find((a) => a.id === c.id));
@@ -668,16 +942,37 @@ class EuiAutocompleteComponent {
         this.selectionChange.emit(this.autocompleteDataSelected);
         this.chipDrop.emit(e);
     }
+    /**
+     * Called when a chip is dragged for reordering or from a source to another.
+     *
+     * @param e Object containing the chip dragged.
+     */
     onChipDragStarted(e) {
         this.chipDragStart.emit(e);
     }
+    /**
+     * Called when a chip is released for reordering or from a source to another.
+     *
+     * @param e Object containing the chip released.
+     */
     onChipDragReleased(e) {
         this.chipDragRelease.emit(e);
     }
+    /**
+     * Calculates the item size for virtual scrolling.
+     *
+     * @returns a number representing the item size.
+     */
     getItemSize() {
         const optionHeight = this.overlayRef?.hostElement?.querySelector('.eui-autocomplete__panel')?.querySelectorAll('.eui-autocomplete-option')[0]?.clientHeight + 1;
         return optionHeight || 48;
     }
+    /**
+     * Re-order options panel based on the input valuea and sort order.
+     *
+     * @param value Value to filter the options.
+     * @param isItemsSorted If the items are sorted.
+     */
     setOptions(value, isItemsSorted) {
         this.autocompleteOptions.next(isItemsSorted ? (this.orderArray(this.filterOptions(value), this.itemsSortOrder)) : this.filterOptions(value));
         if (this.groupBy) {
@@ -686,6 +981,11 @@ class EuiAutocompleteComponent {
             this.distinctOptionGroups = distinctOptionGroups;
         }
     }
+    /**
+     * Return the position strategy for the panel.
+     *
+     * @returns A CDK position strategy.
+     */
     getPositionStrategy() {
         return this.overlay
             .position()
@@ -694,9 +994,20 @@ class EuiAutocompleteComponent {
             .withFlexibleDimensions(false)
             .withLockedPosition(true);
     }
+    /**
+     * Return the scroll strategy for the panel.
+     *
+     * @returns A CDK scroll strategy.
+     */
     getScrollStrategy() {
         return this.overlay.scrollStrategies.reposition({ scrollThrottle: 10 });
     }
+    /**
+     * Refine the options based on the input value.
+     *
+     * @param inputValue Value to filter the options.
+     * @returns An array of options.
+     */
     filterOptions(inputValue) {
         let data = [];
         if (inputValue) {
@@ -722,6 +1033,12 @@ class EuiAutocompleteComponent {
         }
         return data;
     }
+    /**
+     * Converts EuiAutoCompleteItem array to EuiChip array.
+     *
+     * @param items Array of EuiAutoCompleteItem.
+     * @returns An array of EuiChip
+     */
     mapToChip(items) {
         const chips = items.map((selected) => {
             return new EuiChip({
@@ -741,6 +1058,13 @@ class EuiAutocompleteComponent {
         });
         return this.isChipsSorted && chips.length > 0 ? this.orderArray(chips, this.chipsSortOrder) : chips;
     }
+    /**
+     * Sort an array of objects based on their label.
+     *
+     * @param tab Array to order
+     * @param sortOrder Sort order criteria
+     * @returns A sorted array
+     */
     orderArray(tab, sortOrder) {
         tab.sort((a, b) => {
             const aObj = a.label.toLowerCase();
@@ -766,6 +1090,13 @@ class EuiAutocompleteComponent {
         });
         return tab;
     }
+    /**
+     * Transforms array of EuiAutoCompleteItem into a grouped object.
+     *
+     * @param options Array of EuiAutoCompleteItem
+     * @param groupBy Label of the group
+     * @returns An object containing the grouped options and the distinct option groups.
+     */
     groupingHandler(options, groupBy) {
         const distinctGroups = this.autocompleteData.map(item => groupBy.split('.').reduce((prev, curr) => (prev ? prev[curr] : null), item || self));
         const distinctOptionGroups = [...new Set(distinctGroups)].sort((a, b) => (a > b ? 1 : -1));
@@ -781,6 +1112,13 @@ class EuiAutocompleteComponent {
         }
         return { groupedOptions, distinctOptionGroups };
     }
+    /**
+     * Indicates if the origin element is visible in the scrollable parent.
+     *
+     * @param origin Origin of the autocomplete
+     * @param scrollableParent Scrollable container
+     * @returns A boolean, true if visible else false.
+     */
     isVisible(origin, scrollableParent) {
         const originY = origin.getBoundingClientRect().y;
         const scrollableParentY = Math.abs(scrollableParent.getBoundingClientRect().y);
@@ -942,6 +1280,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.1", ngImpor
                 type: Output
             }] } });
 
+/**
+ * @description
+ * Module that provides the EuiAutocomplete component and its dependencies
+ *
+ * @example
+ * ```typescript
+ * \@NgModule({
+ *   imports: [EuiAutocompleteModule]
+ * })
+ * export class YourModule { }
+ * ```
+ */
 class EuiAutocompleteModule {
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.1", ngImport: i0, type: EuiAutocompleteModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
     static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "19.2.1", ngImport: i0, type: EuiAutocompleteModule, declarations: [EuiAutocompleteComponent,