@ni/nimble-components 24.1.6 → 24.1.7

package/dist/esm/combobox/index.d.ts

@@ -1,9 +1,10 @@
-import { Combobox as FoundationCombobox } from '@microsoft/fast-foundation';
+import { ComboboxAutocomplete, SelectPosition, ListboxOption, DelegatesARIACombobox, StartEnd } from '@microsoft/fast-foundation';
 import { ToggleButton } from '../toggle-button';
 import type { ErrorPattern } from '../patterns/error/types';
 import type { DropdownPattern } from '../patterns/dropdown/types';
 import { DropdownAppearance } from '../patterns/dropdown/types';
 import type { AnchoredRegion } from '../anchored-region';
+import { FormAssociatedCombobox } from './models/combobox-form-associated';
 declare global {
     interface HTMLElementTagNameMap {
         'nimble-combobox': Combobox;
@@ -12,23 +13,38 @@ declare global {
 /**
  * A nimble-styed HTML combobox
  */
-export declare class Combobox extends FoundationCombobox implements DropdownPattern, ErrorPattern {
+export declare class Combobox extends FormAssociatedCombobox implements DropdownPattern, ErrorPattern {
     appearance: DropdownAppearance;
     /**
-     * The ref to the internal dropdown button element.
-     *
-     * @internal
+     * A message explaining why the value is invalid.
      */
-    readonly dropdownButton?: ToggleButton;
+    errorText?: string;
+    errorVisible: boolean;
     /**
-     * A message explaining why the value is invalid.
+     * The autocomplete attribute.
+     */
+    autocomplete?: ComboboxAutocomplete;
+    /**
+     * The placement for the listbox when the combobox is open.
+     */
+    positionAttribute?: SelectPosition;
+    /**
+     * The open attribute.
+     */
+    open: boolean;
+    /**
+     * Sets the placeholder value of the element, generally used to provide a hint to the user.
+     * @remarks Using a non-null assertion to mimic FAST's original improper typing of an
+     * uninitialized property:
+     * https://github.com/microsoft/fast/blob/0c27d027ff6e8616ad4fddc17f4432aa7f6cbad0/packages/web-components/fast-foundation/src/combobox/combobox.ts#L199
+     */
+    placeholder: string;
+    /**
+     * The current state of the calculated position of the listbox.
      *
      * @public
-     * @remarks
-     * HTML Attribute: error-text
      */
-    errorText?: string;
-    errorVisible: boolean;
+    position?: SelectPosition;
     /**
      * @internal
      */
@@ -36,35 +52,169 @@ export declare class Combobox extends FoundationCombobox implements DropdownPatt
     /**
      * @internal
      */
-    controlWrapper?: HTMLElement;
+    controlWrapper: HTMLElement;
+    /**
+     * @internal
+     */
+    control: HTMLInputElement;
+    /**
+     * @internal
+     */
+    listbox: HTMLDivElement;
+    /**
+     * @internal
+     */
+    readonly dropdownButton?: ToggleButton;
+    /**
+     * The collection of currently filtered options.
+     */
+    filteredOptions: ListboxOption[];
     /** @internal */
     hasOverflow: boolean;
     get value(): string;
     set value(next: string);
+    /**
+     * The list of options.
+     *
+     * Overrides `Listbox.options`.
+     */
+    get options(): ListboxOption[];
+    set options(value: ListboxOption[]);
+    /**
+     * The unique id for the internal listbox element.
+     *
+     * @internal
+     */
+    listboxId: string;
+    /**
+     * The max height for the listbox when opened.
+     *
+     * @internal
+     */
+    maxHeight: number;
     private valueUpdatedByInput;
     private valueBeforeTextUpdate?;
-    setPositioning(): void;
+    private _value;
+    private filter;
+    /**
+     * The initial state of the position attribute.
+     */
+    private forcedPosition;
+    private get isAutocompleteInline();
+    private get isAutocompleteList();
+    private get isAutocompleteBoth();
     slottedOptionsChanged(prev: HTMLElement[], next: HTMLElement[]): void;
     connectedCallback(): void;
+    /**
+     * @internal
+     */
+    clickHandler(e: MouseEvent): boolean;
+    /**
+     * @internal
+     */
     toggleButtonClickHandler(e: Event): void;
+    /**
+     * @internal
+     */
     toggleButtonChangeHandler(e: Event): void;
+    /**
+     * @internal
+     */
     toggleButtonKeyDownHandler(e: KeyboardEvent): boolean;
+    /**
+     * @internal
+     */
     filterOptions(): void;
     /**
-     * This is a workaround for the issue described here: https://github.com/microsoft/fast/issues/6267
-     * For now, we will update the value ourselves while a user types in text. Note that there is other
-     * implementation related to this (like the 'keydownEventHandler') needed to create the complete set
-     * of desired behavior described in the issue noted above.
+     * @internal
+     */
+    inputHandler(e: InputEvent): boolean;
+    keydownHandler(e: KeyboardEvent): boolean;
+    /**
+     * @internal
+     */
+    keyupHandler(e: KeyboardEvent): boolean;
+    /**
+     * @internal
+     */
+    focusoutHandler(e: FocusEvent): boolean;
+    /**
+     * Reset the element to its first selectable option when its parent form is reset.
+     *
+     * @internal
+     */
+    formResetCallback(): void;
+    /** {@inheritDoc (FormAssociated:interface).validate} */
+    validate(): void;
+    /**
+     * Set the default selected options at initialization or reset.
+     *
+     * @internal
+     * @remarks
+     * Overrides `Listbox.setDefaultSelectedOption`
+     */
+    setDefaultSelectedOption(): void;
+    /**
+     * @internal
+     */
+    selectedIndexChanged(prev: number | undefined, next: number): void;
+    /**
+     * Synchronize the `aria-disabled` property when the `disabled` property changes.
+     *
+     * @internal
+     */
+    disabledChanged(prev: boolean, next: boolean): void;
+    /**
+     * Move focus to the previous selectable option.
+     *
+     * @internal
+     * @remarks
+     * Overrides `Listbox.selectPreviousOption`
+     */
+    selectPreviousOption(): void;
+    /**
+     * @internal
+     */
+    setPositioning(): void;
+    /**
+     * Focus the control and scroll the first selected option into view.
+     *
+     * @internal
+     * @remarks
+     * Overrides: `Listbox.focusAndScrollOptionIntoView`
      */
-    inputHandler(e: InputEvent): boolean | void;
-    keydownHandler(e: KeyboardEvent): boolean | void;
-    focusoutHandler(e: FocusEvent): boolean | void;
     protected focusAndScrollOptionIntoView(): void;
     protected openChanged(): void;
+    protected placeholderChanged(): void;
+    /**
+     * Ensure that the entire list of options is used when setting the selected property.
+     * @internal
+     * @remarks
+     * Overrides: `Listbox.selectedOptionsChanged`
+     */
+    protected selectedOptionsChanged(_: ListboxOption[] | undefined, next: ListboxOption[]): void;
+    protected positionChanged(_: SelectPosition | undefined, next: SelectPosition | undefined): void;
     private regionChanged;
     private controlWrapperChanged;
     private ariaLabelChanged;
     private maxHeightChanged;
+    /**
+     * Sets the value and to match the first selected option.
+     */
+    private updateValue;
+    /**
+     * Focus and set the content of the control based on the first selected option.
+     */
+    private setInputToSelection;
+    /**
+     * Focus, set and select the content of the control based on the first selected option.
+     */
+    private setInlineSelection;
+    private clearSelectionRange;
+    /**
+     * Determines if a value update should involve emitting a change event, then updates the value.
+     */
+    private syncValue;
     private updateListboxMaxHeightCssVariable;
     private updateInputAriaLabel;
     /**
@@ -79,4 +229,6 @@ export declare class Combobox extends FoundationCombobox implements DropdownPatt
      */
     private emitChangeIfValueUpdated;
 }
+export interface Combobox extends StartEnd, DelegatesARIACombobox {
+}
 export declare const comboboxTag = "nimble-combobox";