@progress/kendo-react-dropdowns 13.3.0 → 13.4.0-develop.2

package/DropDownList/DropDownListProps.d.ts

@@ -0,0 +1,594 @@
+/**
+ * @license
+ *-------------------------------------------------------------------------------------------
+ * Copyright © 2026 Progress Software Corporation. All rights reserved.
+ * Licensed under commercial license. See LICENSE.md in the package root for more information
+ *-------------------------------------------------------------------------------------------
+ */
+import { FilterChangeEvent, ChangeEvent, OpenEvent, CloseEvent, FocusEvent, BlurEvent, PageChangeEvent } from './../common/events.js';
+import { VirtualizationSettings, DropDownsPopupSettings } from '../common/settings.js';
+import { ListGroupItemProps } from '../common/ListGroupItem.js';
+import { GroupStickyHeaderProps } from '../common/GroupStickyHeader.js';
+import { ListItemProps } from '../common/ListItem.js';
+import { DropDownsClassStructure, FormComponentProps, SVGIcon } from '@progress/kendo-react-common';
+import { DropDownListHandle } from './models/index.js';
+/**
+ * Represents the object of the `filterChange` DropDownList event.
+ */
+export interface DropDownListFilterChangeEvent extends FilterChangeEvent<DropDownListHandle> {
+}
+/**
+ * Represents the object of the `change` DropDownList event.
+ */
+export interface DropDownListChangeEvent extends ChangeEvent<DropDownListHandle> {
+}
+/**
+ * Represents the object of the `open` DropDownList event.
+ */
+export interface DropDownListOpenEvent extends OpenEvent<DropDownListHandle> {
+}
+/**
+ * Represents the object of the `close` DropDownList event.
+ */
+export interface DropDownListCloseEvent extends CloseEvent<DropDownListHandle> {
+}
+/**
+ * Represents the object of the `focus` DropDownList event.
+ */
+export interface DropDownListFocusEvent extends FocusEvent<DropDownListHandle> {
+}
+/**
+ * Represents the object of the `blur` DropDownList event.
+ */
+export interface DropDownListBlurEvent extends BlurEvent<DropDownListHandle> {
+}
+/**
+ * Represents the object of the `pageChange` DropDownList event.
+ */
+export interface DropDownListPageChangeEvent extends PageChangeEvent<DropDownListHandle> {
+}
+/**
+ * Represents the props of the [KendoReact DropDownList component](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist).
+ */
+export interface DropDownListProps extends FormComponentProps {
+    /**
+     * Sets the data of the DropDownList ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/binding)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList data={['Item1', 'Item2', 'Item3']} />
+     * ```
+     */
+    data?: any[];
+    /**
+     * Sets the text of the default empty item. The type of the defined value has to match the data type.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList defaultItem="Select an item" />
+     * ```
+     */
+    defaultItem?: any;
+    /**
+     * Sets the delay before an item search is performed. When filtration is disabled, use this option.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList delay={300} />
+     * ```
+     */
+    delay?: number;
+    /**
+     * Enables a case-insensitive search. When filtering is disabled, use this option.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList ignoreCase={true} />
+     * ```
+     */
+    ignoreCase?: boolean;
+    /**
+     * Sets the opened and closed state of the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList opened={true} />
+     * ```
+     */
+    opened?: boolean;
+    /**
+     * The styles that are applied to the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList style={{ width: '200px' }} />
+     * ```
+     */
+    style?: React.CSSProperties;
+    /**
+     * Sets the value of the DropDownList ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/binding)). It can either be of the primitive (string, numbers) or of the complex (objects) type.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList value="Item1" />
+     * ```
+     */
+    value?: any;
+    /**
+     * Sets the default value of the DropDownList ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/default-item)). Similar to the native `select` HTML element.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList defaultValue="Item1" />
+     * ```
+     */
+    defaultValue?: any;
+    /**
+     * Sets additional classes to the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList className="custom-class" />
+     * ```
+     */
+    className?: string;
+    /**
+     * Sets CSS classes to the expand `icon` DOM element.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList iconClassName="custom-icon-class" />
+     * ```
+     */
+    iconClassName?: string;
+    /**
+     * Sets the specified SVG icon.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList svgIcon={{ name: 'custom-icon' }} />
+     * ```
+     */
+    svgIcon?: SVGIcon;
+    /**
+     * Sets the title attribute to the DropDownList DOM element.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList title="Dropdown Title" />
+     * ```
+     */
+    title?: string;
+    /**
+     * Sets the disabled state of the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList disabled={true} />
+     * ```
+     */
+    disabled?: boolean;
+    /**
+     * Represents the `dir` HTML attribute.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList dir="rtl" />
+     * ```
+     */
+    dir?: string;
+    /**
+     * Enables the filtering functionality of the DropDownList ([more information and examples](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/filtering)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList filterable={true} />
+     * ```
+     */
+    filterable?: boolean;
+    /**
+     * Sets the value of filtering input. Useful for making the filtering input a [controlled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList filter="search text" />
+     * ```
+     */
+    filter?: string;
+    /**
+     * Sets the loading state of the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList loading={true} />
+     * ```
+     */
+    loading?: boolean;
+    /**
+     * Specifies the `tabIndex` of the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList tabIndex={0} />
+     * ```
+     */
+    tabIndex?: number;
+    /**
+     * Specifies the `accessKey` of the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList accessKey="d" />
+     * ```
+     */
+    accessKey?: string;
+    /**
+     * Sets the data item field that represents the item text ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/default-item)). If the data contains only primitive values, do not define it.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList textField="name" />
+     * ```
+     */
+    textField?: string;
+    /**
+     * Sets the key for comparing the data items of the DropDownList. If `dataItemKey` is not set, the DropDownList compares the items by reference ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/binding#toc-datasets-of-objects)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList dataItemKey="id" />
+     * ```
+     */
+    dataItemKey?: string;
+    /**
+     * Represents a callback function, which returns the value for submitting. The returned value will be rendered in an `option` of a hidden [`select`](https://react.dev/reference/react-dom/components/select) element.
+     *
+     * @example
+     * ```jsx
+     * const App = () => {
+     *    return (
+     *       <form>
+     *           <DropDownList
+     *               data={[ { text: "Austria", id: 1 } , { text: "Belarus", id: 2 } ]}
+     *               valueMap={value => value && value.id}
+     *           />
+     *           <Button type="submit">Submit</Button>
+     *       </form>
+     *    );
+     * }
+     * ```
+     */
+    valueMap?: (value: any) => any;
+    /**
+     * Renders a floating label for the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList label="Dropdown Label" />
+     * ```
+     */
+    label?: string;
+    /**
+     * Specifies the id of the component.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList id="dropdown-id" />
+     * ```
+     */
+    id?: string;
+    /**
+     * Identifies the element(s) which will describe the component, similar to [HTML aria-describedby attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute).
+     * For example these elements could contain error or hint message.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList ariaDescribedBy="error-message-id" />
+     * ```
+     */
+    ariaDescribedBy?: string;
+    /**
+     * Identifies the element(s) which will label the component.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList ariaLabelledBy="label-id" />
+     * ```
+     */
+    ariaLabelledBy?: string;
+    /**
+     * The accessible label of the component. By default is set to value of `label` prop.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList ariaLabel="Accessible Label" />
+     * ```
+     */
+    ariaLabel?: string;
+    /**
+     * Configures the popup of the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList popupSettings={{ animate: true }} />
+     * ```
+     */
+    popupSettings?: DropDownsPopupSettings;
+    /**
+     * Configures the virtual scrolling of the DropDownList ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/virtualization)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList virtual={{ pageSize: 20 }} />
+     * ```
+     */
+    virtual?: VirtualizationSettings;
+    /**
+     * If set, the DropDownList will use it to get the focused item index.
+     *
+     * Default functionality returns the first item which starts with the input text.
+     *
+     * @example
+     * ```jsx
+     * const focusedItemIndex = (data, inputText, textField) => {
+     *     let text = inputText.toLowerCase();
+     *     return data.findIndex(item =>
+     *         String(textField ? item[textField] : item).toLowerCase().includes(text));
+     * };
+     *
+     * <DropDownList focusedItemIndex={focusedItemIndex} />
+     * ```
+     */
+    focusedItemIndex?: (data: any, inputText: string, textField?: string) => number;
+    /**
+     * Fires each time the popup of the DropDownList is about to open.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onOpen={(event) => console.log('Popup opened')} />
+     * ```
+     */
+    onOpen?: (event: DropDownListOpenEvent) => void;
+    /**
+     * Fires each time the popup of the DropDownList is about to close.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onClose={(event) => console.log('Popup closed')} />
+     * ```
+     */
+    onClose?: (event: DropDownListCloseEvent) => void;
+    /**
+     * Fires each time the user focuses the DropDownList.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onFocus={(event) => console.log('Focused')} />
+     * ```
+     */
+    onFocus?: (event: DropDownListFocusEvent) => void;
+    /**
+     * Fires each time the DropDownList gets blurred.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onBlur={(event) => console.log('Blurred')} />
+     * ```
+     */
+    onBlur?: (event: DropDownListBlurEvent) => void;
+    /**
+     * Fires each time the value of the DropDownList is about to change ([see examples](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/binding)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onChange={(event) => console.log('Value changed')} />
+     * ```
+     */
+    onChange?: (event: DropDownListChangeEvent) => void;
+    /**
+     * Fires each time the user types in the filter input. You can filter the source based on the passed filtration value.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onFilterChange={(event) => console.log('Filter changed')} />
+     * ```
+     */
+    onFilterChange?: (event: DropDownListFilterChangeEvent) => void;
+    /**
+     * Fires when both the virtual scrolling of the DropDownList is enabled and the component requires data for another page ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/virtualization)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList onPageChange={(event) => console.log('Page changed')} />
+     * ```
+     */
+    onPageChange?: (event: DropDownListPageChangeEvent) => void;
+    /**
+     * Fires when a DropDownList item is about to be rendered ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/custom-rendering#toc-items)). Used to override the default appearance of the list items.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList itemRender={(li, itemProps) => <li>{itemProps.dataItem}</li>} />
+     * ```
+     */
+    itemRender?: (li: React.ReactElement<HTMLLIElement>, itemProps: ListItemProps) => React.ReactNode;
+    /**
+     * Fires when the element which renders the value is about to be rendered ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/custom-rendering#toc-values)). Used to override the default appearance of the element.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList valueRender={(element, value) => <span>{value}</span>} />
+     * ```
+     */
+    valueRender?: (element: React.ReactElement<HTMLSpanElement>, value: any) => React.ReactNode;
+    /**
+     * Fires when the element which indicates no data in the popup is about to be rendered ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/custom-rendering#toc-no-data)). Used to override the default appearance of the element.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList listNoDataRender={(element) => <div>No data available</div>} />
+     * ```
+     */
+    listNoDataRender?: (element: React.ReactElement<HTMLDivElement>) => React.ReactNode;
+    /**
+     * Sets the header component of the DropDownList ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/custom-rendering#toc-headers-and-footers)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList header={<div>Header Content</div>} />
+     * ```
+     */
+    header?: React.ReactNode;
+    /**
+     * Sets the footer component of the DropDownList ([see example](https://www.telerik.com/kendo-react-ui/components/dropdowns/dropdownlist/custom-rendering#toc-headers-and-footers)).
+     *
+     * @example
+     * ```jsx
+     * <DropDownList footer={<div>Footer Content</div>} />
+     * ```
+     */
+    footer?: React.ReactNode;
+    /**
+     * Specifies the `name` property of the `select` DOM element.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList name="dropdown-name" />
+     * ```
+     */
+    name?: string;
+    /**
+     * If set to `false`, the DropDownList will not navigate over its data through left and right keys.
+     * Useful when the DropDownList is placed inside a toolbar which needs to handle left and right keys.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList leftRightKeysNavigation={false} />
+     * ```
+     */
+    leftRightKeysNavigation?: boolean;
+    /**
+     * Configures the `size` of the DropDownList.
+     *
+     * The available options are:
+     * - small
+     * - medium
+     * - large
+     *
+     * @default undefined (theme-controlled)
+     *
+     * @example
+     * ```jsx
+     * <DropDownList size="small" />
+     * ```
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Configures the `roundness` of the DropDownList.
+     *
+     * The available options are:
+     * - small
+     * - medium
+     * - large
+     * - full
+     *
+     * @default undefined (theme-controlled)
+     *
+     * @example
+     * ```jsx
+     * <DropDownList rounded="large" />
+     * ```
+     */
+    rounded?: 'small' | 'medium' | 'large' | 'full';
+    /**
+     * Configures the `fillMode` of the DropDownList.
+     *
+     * The available options are:
+     * - solid
+     * - flat
+     * - outline
+     *
+     * @default undefined (theme-controlled)
+     *
+     * @example
+     * ```jsx
+     * <DropDownList fillMode="flat" />
+     * ```
+     */
+    fillMode?: 'solid' | 'flat' | 'outline';
+    /**
+     * Providing different rendering of the popup element based on the screen dimensions.
+     *
+     * @default `false`
+     *
+     * @example
+     * ```jsx
+     * <DropDownList adaptive={true} />
+     * ```
+     */
+    adaptive?: boolean;
+    /**
+     * Specifies the text that is rendered as title in the adaptive popup(action sheet).
+     * Applicable only when `adaptive` is set to `true`.
+     * If not provided, the title will be the same as the label.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList adaptiveTitle="Adaptive Popup Title" />
+     * ```
+     */
+    adaptiveTitle?: string;
+    /**
+     * Specifies the text that is rendered as subtitle in the adaptive popup(action sheet).
+     * Applicable only when `adaptive` is set to `true`.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList adaptiveSubtitle="Adaptive Popup Subtitle" />
+     */
+    adaptiveSubtitle?: string;
+    /**
+     * Sets the data item field that represents the start of a group. Applicable to objects data.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList groupField="category" />
+     * ```
+     */
+    groupField?: string;
+    /**
+     * Fires when a DropDownList's group header item is about to be rendered. Used to override the default appearance of the group's headers.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList groupHeaderItemRender={(li, itemProps) => <li>{itemProps.dataItem}</li>} />
+     * ```
+     */
+    groupHeaderItemRender?: (li: React.ReactElement<HTMLLIElement>, itemProps: ListGroupItemProps) => React.ReactNode;
+    /**
+     * Fires when a DropDownList's sticky group header item is about to be rendered. Used to override the default appearance of the sticky group header of the component.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList groupStickyHeaderItemRender={(div, stickyHeaderProps) => <div>{stickyHeaderProps.dataItem}</div>} />
+     * ```
+     */
+    groupStickyHeaderItemRender?: (div: React.ReactElement<HTMLDivElement>, stickyHeaderProps: GroupStickyHeaderProps) => React.ReactNode;
+    /**
+     * @hidden
+     */
+    list?: any;
+    /**
+     * Defines if DropDownList's disabled items will be skipped or focused when navigating through the list of items using a keyboard. Defaults to `true`.
+     *
+     * @example
+     * ```jsx
+     * <DropDownList skipDisabledItems={false} />
+     * ```
+     */
+    skipDisabledItems?: boolean;
+    /**
+     * @hidden
+     */
+    unstyled?: DropDownsClassStructure;
+}

package/DropDownList/models/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ *-------------------------------------------------------------------------------------------
+ * Copyright © 2026 Progress Software Corporation. All rights reserved.
+ * Licensed under commercial license. See LICENSE.md in the package root for more information
+ *-------------------------------------------------------------------------------------------
+ */
+import { FormComponentValidity } from '@progress/kendo-react-common';
+import { DropDownListProps } from '../DropDownListProps.js';
+/**
+ * Represent the `ref` of the DropDownList component.
+ */
+export interface DropDownListHandle {
+    /**
+     * The element of the DropDownList component.
+     */
+    element: HTMLSpanElement | null;
+    /**
+     * The index of the selected item.
+     */
+    index: number;
+    /**
+     * Gets the `name` property of the DropDownList.
+     */
+    name: string | undefined;
+    /**
+     * Represents the validity state into which the DropDownList is set.
+     */
+    validity: FormComponentValidity;
+    /**
+     * The value of the DropDownList.
+     */
+    value: any;
+    /**
+     * The focused state of the DropDownList.
+     */
+    focused: boolean;
+    /**
+     * The opened state of the DropDownList.
+     */
+    opened: boolean;
+    /**
+     * The props of the DropDownList component
+     */
+    props: Readonly<DropDownListProps>;
+    /**
+     * Focuses the wrapper of the DropDownList component.
+     */
+    focus: () => void;
+    /**
+     * Toggles the popup of the DropDownList component.
+     */
+    togglePopup: () => void;
+}