igniteui-webcomponents 7.2.4 → 7.3.0-beta.1

package/components/combo/combo.d.ts

@@ -1,10 +1,10 @@
 import { type IComboResourceStrings } from 'igniteui-i18n-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-import { IgcBaseComboBoxComponent } from '../common/mixins/combo-box.js';
-import type { AbstractConstructor } from '../common/mixins/constructor.js';
-import type { Validator } from '../common/validators.js';
+import { IgcBaseComboBoxComponent } from '#internals/mixins/combo-box.js';
+import type { AbstractConstructor } from '#internals/mixins/constructor.js';
+import type { Validator } from '#internals/validators.js';
 import type { ComboItemTemplate, ComboRenderFunction, ComboValue, FilteringOptions, GroupingDirection, IgcComboComponentEventMap, Item, Keys } from './types.js';
-declare const IgcComboComponent_base: import("../common/mixins/constructor.js").Constructor<import("../common/mixins/forms/types.js").FormRequiredInterface & import("../common/mixins/forms/types.js").FormAssociatedElementInterface> & import("../common/mixins/constructor.js").Constructor<import("../common/mixins/event-emitter.js").EventEmitterInterface<IgcComboComponentEventMap>> & AbstractConstructor<IgcBaseComboBoxComponent>;
+declare const IgcComboComponent_base: AbstractConstructor<import("#internals/mixins/i18n.js").I18nInterface<IComboResourceStrings, Required<IComboResourceStrings>>> & import("#internals/mixins/constructor.js").Constructor<import("../../internals/mixins/forms/types.js").FormRequiredInterface & import("../../internals/mixins/forms/types.js").FormAssociatedElementInterface> & import("#internals/mixins/constructor.js").Constructor<import("#internals/mixins/event-emitter.js").EventEmitterInterface<IgcComboComponentEventMap>> & AbstractConstructor<IgcBaseComboBoxComponent>;
 /**
  * The Combo component is similar to the Select component in that it provides a list of options from which the user can make a selection.
  * In contrast to the Select component, the Combo component displays all options in a virtualized list of items,
@@ -61,37 +61,40 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
     static register(): void;
     protected get __validators(): Validator<IgcComboComponent<T>>[];
     private readonly _slots;
-    protected readonly _rootClickController: import("../common/controllers/root-click.js").RootClickController;
-    protected readonly _i18nController: import("../common/i18n/i18n-controller.js").I18nController<IComboResourceStrings>;
-    protected readonly _formValue: import("../common/mixins/forms/form-value.js").FormValue<ComboValue<T>[]>;
+    protected readonly _rootClickController: import("#internals/controllers/root-click.js").RootClickController;
+    protected readonly _formValue: import("#internals/mixins/forms/form-value.js").FormValue<ComboValue<T>[]>;
     /** The primary input of the combo component. */
     private readonly _inputRef;
+    private readonly _helperText;
     /** The search input of the combo component. */
     private readonly _searchRef;
     /** The combo virtualized dropdown list. */
     private readonly _listRef;
     private readonly _state;
     private readonly _navigation;
-    private _data;
-    private _valueKey?;
+    private _index?;
+    private _indexSize;
     private _displayKey?;
     private _placeholderSearch?;
-    private _disableFiltering;
-    private _singleSelect;
     private _selected;
     private _filteringOptions;
     private set _activeIndex(value);
     private get _activeIndex();
     private set _searchTerm(value);
     private get _searchTerm();
-    private _activeDescendant?;
     private _displayValue;
+    /** The DOM id of the option rendered at `index` in the current data state. */
+    private _itemId;
+    /**
+     * Derived from {@link _activeIndex} rather than tracked separately, so that it
+     * cannot go stale and does not have to be assigned while rendering an item.
+     */
+    private get _activeDescendant();
     private get _mainAriaLabel();
     /** The data source used to generate the list of options. */
-    set data(value: T[]);
-    get data(): T[];
+    data: T[];
     /**
-     * The outlined attribute of the control.
+     * Whether the control has an outlined appearance.
      * @attr outlined
      * @default false
      */
@@ -101,10 +104,9 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
      * @attr single-select
      * @default false
      */
-    set singleSelect(value: boolean);
-    get singleSelect(): boolean;
+    singleSelect: boolean;
     /**
-     * The autofocus attribute of the control.
+     * Whether the control should receive focus automatically.
      * @attr autofocus
      */
     autofocus: boolean;
@@ -115,38 +117,33 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
      */
     autofocusList: boolean;
     /**
-     * Gets/Sets the locale used for getting language, affecting resource strings.
+     * The locale used to resolve the component's resource strings.
+     * Falls back to the global locale when not set.
      * @attr locale
      */
     set locale(value: string);
     get locale(): string;
     /**
-     * The label attribute of the control.
+     * The label of the control.
      * @attr label
      */
     label?: string;
     /**
-     * The placeholder attribute of the control.
+     * The placeholder text of the control.
      * @attr placeholder
      */
     placeholder?: string;
     /**
-     * The placeholder attribute of the search input.
+     * The placeholder text of the search input.
      * @attr placeholder-search
      */
     set placeholderSearch(value: string | undefined);
     get placeholderSearch(): string;
-    /**
-     * The resource strings for localization.
-     */
-    set resourceStrings(value: IComboResourceStrings);
-    get resourceStrings(): IComboResourceStrings;
     /**
      * The key in the data source used when selecting items.
      * @attr value-key
      */
-    set valueKey(value: Keys<T> | undefined);
-    get valueKey(): Keys<T> | undefined;
+    valueKey?: Keys<T>;
     /**
      * The key in the data source used to display items in the list.
      * @attr display-key
@@ -182,8 +179,7 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
      * @attr disable-filtering
      * @default false
      */
-    set disableFiltering(value: boolean);
-    get disableFiltering(): boolean;
+    disableFiltering: boolean;
     /**
      * Hides the clear button.
      * @attr disable-clear
@@ -202,8 +198,8 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
     groupHeaderTemplate: ComboItemTemplate<T>;
     /**
      * Sets the value (selected items). The passed value must be a valid JSON array.
-     * If the data source is an array of complex objects, the `valueKey` attribute must be set.
-     * Note that when `displayKey` is not explicitly set, it will fall back to the value of `valueKey`.
+     * If the data source is an array of complex objects, the `valueKey` must be set.
+     * Note that when `displayKey` is not explicitly set, it falls back to the value of `valueKey`.
      *
      * @attr value
      *
@@ -238,15 +234,39 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
     get selection(): T[];
     constructor();
     protected willUpdate(props: PropertyValues<this>): void;
-    protected updated(props: PropertyValues<this>): void;
-    protected _restoreDefaultValue(): void;
+    /**
+     * Runs `callback`, restoring the pristine flag afterwards.
+     *
+     * Re-syncing the form value in reaction to a configuration change (as opposed
+     * to user interaction) must not count as the control having been dirtied.
+     */
+    private _withPristine;
     protected _setDefaultValue(current: string | null): void;
     protected _show(emitEvent?: boolean): Promise<boolean>;
     protected _hide(emitEvent?: boolean): Promise<boolean>;
     private _setSingleSelectionDisplayValue;
+    /**
+     * Maps every value representation in the data source to the positions of the
+     * records carrying it. Built on demand and dropped whenever `data` or
+     * `valueKey` changes.
+     *
+     * Positions (rather than records) are stored so that resolution can hand back
+     * matches in data-source order, and duplicate value keys keep resolving to
+     * every record that carries them.
+     *
+     * The size comparison picks up in-place growth or shrink (push/splice) of the
+     * same array. Replacing elements without changing the length is not detectable
+     * here and still requires reassigning `data`.
+     */
+    private get _dataIndex();
     /**
      * Resolves user-provided items (value keys or object references)
-     * to actual objects from the data source in a single pass.
+     * to actual objects from the data source, in data-source order.
+     *
+     * @remarks
+     * Repeating the same value in `items` resolves it once - a record cannot be
+     * selected twice, and duplicates would otherwise reach the change event
+     * payload.
      */
     private _resolveItems;
     /**
@@ -255,24 +275,48 @@ export default class IgcComboComponent<T extends object = any> extends IgcComboC
      */
     private _resolveItemValue;
     /**
-     * Maps data items to their value representations using the given key.
-     * When key is undefined, returns the items themselves.
+     * Maps data records to their value representations - the `valueKey` property
+     * of each, or the record itself when no `valueKey` is set.
+     */
+    private _toValues;
+    /**
+     * Recomputes {@link _displayValue} from the current selection and returns its
+     * value representation, walking the selection once for both projections.
      */
-    private _getValues;
+    private _projectSelection;
     private _emitSelectionChange;
-    private _selectItems;
-    private _deselectItems;
+    /**
+     * Builds the value the component would have if `resolved` were applied to the
+     * current selection. Used as the `newValue` payload of the change event.
+     */
+    private _previewValue;
+    /**
+     * Adds the given `items` to, or removes them from, the current selection.
+     *
+     * An empty collection is a "select all" / "deselect all" request. Single
+     * selection has no "select all" - it only resets the current selection.
+     *
+     * When `emit` is set, the cancellable `igcChange` event is fired *before* any
+     * mutation takes place, so cancelling it leaves the selection untouched.
+     *
+     * @returns Whether the change was committed.
+     */
+    private _updateSelection;
     /**
      * Syncs the internal `_selected` set from the current `_formValue`.
      * This is a one-way sync: source of truth (_formValue) → view (_selected).
      */
     private _syncSelectionFromValue;
+    protected _syncValueFromSelection(): void;
     /**
-     * Finds an item in the data array by its value (or value key).
-     * Returns undefined if the item is not found.
+     * The data record rendered at `index`, or undefined when that position holds
+     * a group header instead of a selectable option.
+     *
+     * Guarding on this matters: an unresolvable record would reach
+     * {@link _updateSelection} as an empty collection, which reads as
+     * "select everything".
      */
-    private _findItemByValue;
-    protected _syncValueFromSelection(initial?: boolean): void;
+    private _recordAt;
     private _toggleSelection;
     private _selectByIndex;
     private _clearSelection;