/**
 * Copyright IBM Corp. 2016, 2025
 *
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
import { UseComboboxProps, UseComboboxActions } from 'downshift';
import React, { type ComponentType, type InputHTMLAttributes, type MouseEvent, type PropsWithChildren, type PropsWithRef, type ReactElement, type ReactNode, type RefAttributes } from 'react';
import { type ListBoxSize } from '../ListBox';
import { TranslateWithId } from '../../types/common';
type ExcludedAttributes = 'id' | 'onChange' | 'onClick' | 'type' | 'size';
export interface OnChangeData<ItemType> {
    selectedItem: ItemType | null | undefined;
    inputValue?: string | null;
}
/**
 * Message ids that will be passed to translateWithId().
 * Combination of message ids from ListBox/next/ListBoxSelection.js and
 * ListBox/next/ListBoxTrigger.js, but we can't access those values directly
 * because those components aren't Typescript.  (If you try, TranslationKey
 * ends up just being defined as "string".)
 */
export type TranslationKey = 'close.menu' | 'open.menu' | 'clear.all' | 'clear.selection';
export type ItemToStringHandler<ItemType> = (item: ItemType | null) => string;
export interface ComboBoxProps<ItemType> extends Omit<InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes>, TranslateWithId<TranslationKey> {
    /**
     * Specify whether or not the ComboBox should allow a value that is
     * not in the list to be entered in the input
     */
    allowCustomValue?: boolean;
    /**
     * Specify a label to be read by screen readers on the container node
     * 'aria-label' of the ListBox component.
     */
    ['aria-label']?: string;
    /**
     * @deprecated please use `aria-label` instead.
     * 'aria-label' of the ListBox component.
     */
    ariaLabel?: string;
    /**
     * **Experimental**: Will attempt to automatically align the floating
     * element to avoid collisions with the viewport and being clipped by
     * ancestor elements. Requires React v17+
     * @see https://github.com/carbon-design-system/carbon/issues/18714
     */
    autoAlign?: boolean;
    /**
     * An optional className to add to the container node
     */
    className?: string;
    /**
     * **Experimental**: Provide a `decorator` component to be rendered inside the `ComboBox` component
     */
    decorator?: ReactNode;
    /**
     * Specify the direction of the combobox dropdown. Can be either top or bottom.
     */
    direction?: 'top' | 'bottom';
    /**
     * Specify if the control should be disabled, or not
     */
    disabled?: boolean;
    /**
     * Additional props passed to Downshift.
     *
     * **Use with caution:** anything you define here overrides the components'
     * internal handling of that prop. Downshift APIs and internals are subject to
     * change, and in some cases they can not be shimmed by Carbon to shield you
     * from potentially breaking changes.
     *
     */
    downshiftProps?: Partial<UseComboboxProps<ItemType>>;
    /**
     * Provide a ref that will be mutated to contain an object of downshift
     * action functions. These can be called to change the internal state of the
     * downshift useCombobox hook.
     *
     * **Use with caution:** calling these actions modifies the internal state of
     * downshift. It may conflict with or override the state management used within
     * Combobox. Downshift APIs and internals are subject to change, and in some
     * cases they can not be shimmed by Carbon to shield you from potentially breaking
     * changes.
     */
    downshiftActions?: React.MutableRefObject<UseComboboxActions<ItemType> | undefined>;
    /**
     * Provide helper text that is used alongside the control label for
     * additional help
     */
    helperText?: ReactNode;
    /**
     * Specify a custom `id` for the input
     */
    id: string;
    /**
     * Allow users to pass in an arbitrary item or a string (in case their items are an array of strings)
     * from their collection that are pre-selected
     */
    initialSelectedItem?: ItemType;
    /**
     * Specify if the currently selected value is invalid.
     */
    invalid?: boolean;
    /**
     * Message which is displayed if the value is invalid.
     */
    invalidText?: ReactNode;
    /**
     * Optional function to render items as custom components instead of strings.
     * Defaults to null and is overridden by a getter
     */
    itemToElement?: ComponentType<ItemType> | null;
    /**
     * Helper function passed to downshift that allows the library to render a
     * given item to a string label. By default, it extracts the `label` field
     * from a given item to serve as the item label in the list
     */
    itemToString?: ItemToStringHandler<ItemType>;
    /**
     * We try to stay as generic as possible here to allow individuals to pass
     * in a collection of whatever kind of data structure they prefer
     */
    items: ItemType[];
    /**
     * @deprecated
     * should use "light theme" (white background)?
     */
    light?: boolean;
    /**
     * `onChange` is a utility for this controlled component to communicate to a
     * consuming component when a specific dropdown item is selected.
     * `({ selectedItem }) => void`
    //  * @param {{ selectedItem }}
     */
    onChange: (data: OnChangeData<ItemType>) => void;
    /**
     * Callback function to notify consumer when the text input changes.
     * This provides support to change available items based on the text.
     * `(inputText) => void`
     * @param {string} inputText
     */
    onInputChange?: (inputText: string) => void;
    /**
     * Callback function that fires when the combobox menu toggle is clicked
     * `(evt) => void`
     * @param {MouseEvent} event
     */
    onToggleClick?: (evt: MouseEvent<HTMLButtonElement>) => void;
    /**
     * Used to provide a placeholder text node before a user enters any input.
     * This is only present if the control has no items selected
     */
    placeholder?: string;
    /**
     * Whether or not the component is read-only
     */
    readOnly?: boolean;
    /**
     * For full control of the selection
     */
    selectedItem?: ItemType | null;
    /**
     * Specify your own filtering logic by passing in a `shouldFilterItem`
     * function that takes in the current input and an item and passes back
     * whether or not the item should be filtered.
     * this prop will be ignored if `typeahead` prop is enabled
     */
    shouldFilterItem?: (input: {
        item: ItemType;
        itemToString?: ItemToStringHandler<ItemType>;
        inputValue: string | null;
    }) => boolean;
    /**
     * Specify the size of the ListBox. Currently supports either `sm`, `md` or `lg` as an option.
     */
    size?: ListBoxSize;
    /**
     * @deprecated please use decorator instead.
     * **Experimental**: Provide a `Slug` component to be rendered inside the `ComboBox` component
     */
    slug?: ReactNode;
    /**
     * Provide text to be used in a `<label>` element that is tied to the
     * combobox via ARIA attributes.
     */
    titleText?: ReactNode;
    /**
     * **Experimental**: will enable autocomplete and typeahead for the input field
     */
    typeahead?: boolean;
    /**
     * Specify whether the control is currently in warning state
     */
    warn?: boolean;
    /**
     * Provide the text that is displayed when the control is in warning state
     */
    warnText?: ReactNode;
    /**
     * Specify native input attributes to place on the `<input>`, like maxLength.
     * These are passed to downshift's getInputProps() and will override the
     * internal input props.
     * https://github.com/downshift-js/downshift?tab=readme-ov-file#getinputprops
     */
    inputProps?: InputHTMLAttributes<HTMLInputElement>;
}
type ComboboxComponentProps<ItemType> = PropsWithRef<PropsWithChildren<ComboBoxProps<ItemType>> & RefAttributes<HTMLInputElement>>;
export interface ComboBoxComponent {
    <ItemType>(props: ComboboxComponentProps<ItemType>): ReactElement<any> | null;
}
declare const _default: ComboBoxComponent;
export default _default;