@fluentui/react-northstar

import { AccessibilityAttributes } from '@fluentui/accessibility'; import * as React from 'react'; import * as PropTypes from 'prop-types'; import { ShorthandRenderFunction, ShorthandValue, ShorthandCollection, FluentComponentStaticProps } from '../../types'; import { A11yStatusMessageOptions } from 'downshift'; import { UIComponentProps } from '../../utils'; import { ListProps } from '../List/List'; import { DropdownItem, DropdownItemProps } from './DropdownItem'; import { DropdownSelectedItem, DropdownSelectedItemProps } from './DropdownSelectedItem'; import { DropdownSearchInput, DropdownSearchInputProps } from './DropdownSearchInput'; import { ButtonProps } from '../Button/Button'; import { BoxProps } from '../Box/Box'; import { PositioningProps, PopperShorthandProps } from '../../utils/positioner'; export interface DownshiftA11yStatusMessageOptions<Item> extends Required<A11yStatusMessageOptions<Item>> { } export interface DropdownSlotClassNames { clearIndicator: string; container: string; toggleIndicator: string; item: string; itemsCount: string; itemsList: string; searchInput: string; selectedItem: string; selectedItems: string; triggerButton: string; } export interface DropdownProps extends UIComponentProps<DropdownProps>, PositioningProps { /** The index of the currently selected item, if the dropdown supports multiple selection. */ activeSelectedIndex?: number; /** Whether the ComboBox allows freeform user input, rather than restricting to the provided options. */ allowFreeform?: boolean; /** Identifies the element (or elements) that labels the current element. Will be passed to `triggerButton`. */ 'aria-labelledby'?: AccessibilityAttributes['aria-labelledby']; 'aria-describedby'?: AccessibilityAttributes['aria-describedby']; /** Indicates the entered value does not conform to the format expected by the application. Will be passed to `triggerButton`. */ 'aria-invalid'?: AccessibilityAttributes['aria-invalid']; /** A dropdown item can show a check indicator if it is selected. */ checkable?: boolean; /** A slot for a selected indicator in the dropdown list. */ checkableIndicator?: ShorthandValue<BoxProps>; /** A dropdown can be clearable to let users remove their selection. */ clearable?: boolean; /** A slot for the clearing indicator. */ clearIndicator?: ShorthandValue<BoxProps>; /** The initial value for the index of the currently selected item in a multiple selection. */ defaultActiveSelectedIndex?: number; /** The initial value for 'open' in uncontrolled mode. */ defaultOpen?: boolean; /** The initial list item index to highlight. */ defaultHighlightedIndex?: number; /** The initial value for the search query if the dropdown has `search` enabled. */ defaultSearchQuery?: string; /** The initial value (or value array if the array has multiple selection). */ defaultValue?: ShorthandValue<DropdownItemProps> | ShorthandCollection<DropdownItemProps>; /** A dropdown can show that it cannot be interacted with. */ disabled?: boolean; /** A dropdown can fill the width of its container. */ fluid?: boolean; /** Object with callbacks for generating announcements for item selection and removal. */ getA11ySelectionMessage?: { /** * Callback that creates custom accessibility message a screen reader narrates on item added to selection. * @param item - Dropdown added element. */ onAdd?: (item: ShorthandValue<DropdownItemProps>) => string; /** * Callback that creates custom accessibility message a screen reader narrates on item removed from selection. * @param item - Dropdown removed element. */ onRemove?: (item: ShorthandValue<DropdownItemProps>) => string; /** * Callback that creates custom accessibility message about the selected items count a screen reader narrates on input field focus. * @param count - number of items selected. */ itemsCount?: (count: number) => string; }; /** A label for selected items listbox. */ a11ySelectedItemsMessage?: string; /** * Callback that provides status announcement message with number of items in the list, using Arrow Up/Down keys to navigate through them and, if multiple, using Arrow Left/Right to navigate through selected items. * @param messageGenerationProps - Object with properties to generate message from. See getA11yStatusMessage from Downshift repo. */ getA11yStatusMessage?: (options: DownshiftA11yStatusMessageOptions<ShorthandValue<DropdownItemProps>>) => string; /** A dropdown can highlight the first option when it opens. */ highlightFirstItemOnOpen?: boolean; /** The index of the list item to highlight. */ highlightedIndex?: number; /** A dropdown can be formatted to appear inline next to other elements. */ inline?: boolean; /** A dropdown can have inverted colors. */ inverted?: boolean; /** Array of props for generating list options (Dropdown.Item[]) and selected item labels (Dropdown.SelectedItem[]), if it's a multiple selection. */ items?: ShorthandCollection<DropdownItemProps>; /** * A function that converts an item to string. Used when dropdown has `search` enabled. * By default, it: * - returns the `header` property if it exists on an item * - stringifies the item if it is a primitive type */ itemToString?: (item: ShorthandValue<DropdownItemProps>) => string; /** Used when comparing two items in multiple selection. Default comparison is by the header prop. */ itemToValue?: (item: ShorthandValue<DropdownItemProps>) => any; /** A message to be displayed in the list header. */ headerMessage?: ShorthandValue<DropdownItemProps>; /** A slot for dropdown list. */ list?: ShorthandValue<ListProps & { popper?: PopperShorthandProps; }>; /** A dropdown can show that it is currently loading data. */ loading?: boolean; /** A message to be displayed in the list when the dropdown is loading. */ loadingMessage?: ShorthandValue<DropdownItemProps>; /** When selecting an element with Tab, focus stays on the dropdown by default. If true, the focus will jump to next/previous element in DOM. Only available to multiple selection dropdowns. */ moveFocusOnTab?: boolean; /** A dropdown can allow a user to select multiple items. */ multiple?: boolean; /** A message to be displayed in the list when the dropdown has no items. */ noResultsMessage?: ShorthandValue<DropdownItemProps>; /** * Called when the dropdown's selected items index change. * @param event - React's original SyntheticEvent. * @param data - All props and the new selected value(s). */ onActiveSelectedIndexChange?: (event: React.MouseEvent | React.KeyboardEvent | null, data: DropdownProps) => void; /** * Called when the dropdown's highlighted index change. * @param event - React's original SyntheticEvent. * @param data - All props and the new selected value(s). */ onHighlightedIndexChange?: (event: React.MouseEvent | React.KeyboardEvent | null, data: DropdownProps) => void; /** * Called when the dropdown opens or closes. * @param event - React's original SyntheticEvent. * @param data - All props, with `open` reflecting the new open state. */ onOpenChange?: (event: React.MouseEvent | React.KeyboardEvent | null, data: DropdownProps) => void; /** * Called when the dropdown's search query changes. * @param event - React's original SyntheticEvent. * @param data - All props, with `searchQuery` reflecting its new value. */ onSearchQueryChange?: (event: React.MouseEvent | React.KeyboardEvent | null, data: DropdownProps) => void; /** * Called when the dropdown's selected item(s) change. * @param event - React's original SyntheticEvent. * @param data - All props and the new selected value(s). */ onChange?: (event: React.MouseEvent | React.KeyboardEvent | null, data: DropdownProps) => void; /** * Called when the focus moves out from dropdown. * @param event - React's original SyntheticEvent. */ onBlur?: (event: React.FocusEvent | null) => void; /** A dropdown's open state can be controlled. */ open?: boolean; /** A placeholder message for the input field. */ placeholder?: string; /** * A render function to customize how items are rendered in the dropdown. * * @param Component - The computed component for this slot. * @param props - The computed props for this slot. * @param children - The computed children for this slot. */ renderItem?: ShorthandRenderFunction<DropdownItemProps>; /** * A custom render function for the selected item. Only applicable with the `multiple` prop. * * @param Component - The computed component for this slot. * @param props - The computed props for this slot. * @param children - The computed children for this slot. */ renderSelectedItem?: ShorthandRenderFunction<DropdownSelectedItemProps>; /** A dropdown can have a search field instead of trigger button. Can receive a custom search function that will replace the default equivalent. */ search?: boolean | ((items: ShorthandCollection<DropdownItemProps>, searchQuery: string) => ShorthandCollection<DropdownItemProps>); /** A search dropdown's input can be customized. */ searchInput?: ShorthandValue<DropdownSearchInputProps>; /** Sets search query value (controlled mode). */ searchQuery?: string; /** Controls the appearance of the indicator that shows/hides the list of items. */ toggleIndicator?: ShorthandValue<BoxProps>; /** Controls the appearance of the trigger button if it's a selection dropdown (not a search). */ triggerButton?: ShorthandValue<ButtonProps>; /** Sets the dropdown's currently selected value(s) in controlled mode. */ value?: ShorthandValue<DropdownItemProps> | ShorthandCollection<DropdownItemProps>; /** Dropdown can have errors status */ error?: boolean; } export declare type DropdownStylesProps = Required<Pick<DropdownProps, 'disabled' | 'error' | 'fluid' | 'inline' | 'inverted' | 'multiple' | 'position' | 'open'>> & { focused: boolean; isEmptyClearIndicator: boolean; hasToggleIndicator: boolean; isFromKeyboard: boolean; search: boolean; hasItemsSelected: boolean; }; export declare const dropdownClassName = "ui-dropdown"; export declare const dropdownSlotClassNames: DropdownSlotClassNames; /** * A Dropdown allows user to select one or more values from a list of options. * Can be created with search and multi-selection capabilities. * * @accessibility * Implements [ARIA Combo Box](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox) design pattern, uses aria-live to announce state changes. * @accessibilityIssues * [Issue 991203: VoiceOver doesn't narrate properly elements in the input/combobox](https://bugs.chromium.org/p/chromium/issues/detail?id=991203) * [JAWS - ESC (ESCAPE) not closing collapsible listbox (dropdown) on first time #528](https://github.com/FreedomScientific/VFO-standards-support/issues/528) */ export declare const Dropdown: (<TExtendedElementType extends React.ElementType<any> = "div">(props: React.RefAttributes<HTMLDivElement> & Omit<import("@fluentui/react-bindings").PropsOfElement<TExtendedElementType>, "as" | keyof DropdownProps> & { as?: TExtendedElementType; } & DropdownProps) => JSX.Element) & { propTypes?: React.WeakValidationMap<DropdownProps> & { as: React.Requireable<string | ((props: any, context?: any) => any) | (new (props: any, context?: any) => any)>; }; contextTypes?: PropTypes.ValidationMap<any>; defaultProps?: Partial<DropdownProps & { as: "div"; }>; displayName?: string; readonly __PRIVATE_PROPS?: React.RefAttributes<HTMLDivElement> & Omit<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & { ref?: React.Ref<HTMLDivElement>; }, "as" | keyof DropdownProps> & { as?: "div"; } & DropdownProps; } & FluentComponentStaticProps<DropdownProps> & { Item: typeof DropdownItem; SearchInput: typeof DropdownSearchInput; SelectedItem: typeof DropdownSelectedItem; };