From 690bf61ea1e3c9e13908958089dc0c09dff6ecbe Mon Sep 17 00:00:00 2001 From: Mohammer5 Date: Sun, 10 Nov 2024 14:49:10 +0800 Subject: [PATCH] chore(select a11y): add TS types --- components/select/types/index.d.ts | 185 ++++++++++++++++++++++++++++- 1 file changed, 184 insertions(+), 1 deletion(-) diff --git a/components/select/types/index.d.ts b/components/select/types/index.d.ts index d994784026..28ef7ba027 100644 --- a/components/select/types/index.d.ts +++ b/components/select/types/index.d.ts @@ -30,6 +30,16 @@ export type SelectKeyHandler = SelectEventHandler< export type SelectChangeHandler = SelectEventHandler +type TranslateableProp = string | ((interpolationObject: any) => string) + +/** + * ==================== + * + * + * + * ==================== + **/ + export interface MultiSelectProps { children?: React.ReactNode className?: string @@ -74,7 +84,13 @@ export interface MultiSelectProps { export const MultiSelect: React.FC -type TranslateableProp = string | ((interpolationObject: any) => string) +/** + * ==================== + * + * + * + * ==================== + **/ export interface MultiSelectFieldProps { /** @@ -205,6 +221,14 @@ export class MultiSelectField extends React.Component< render(): JSX.Element } +/** + * ==================== + * + * + * + * ==================== + **/ + export interface MultiSelectOptionProps { label: string value: string @@ -217,6 +241,14 @@ export interface MultiSelectOptionProps { export const MultiSelectOption: React.FC +/** + * ==================== + * + * + * + * ==================== + **/ + export interface SingleSelectProps { children?: React.ReactNode className?: string @@ -273,6 +305,149 @@ export interface SingleSelectProps { export const SingleSelect: React.FC +/** + * ==================== + * + * + * + * ==================== + **/ + +type SingleSelectA11yCustomOptionProp = (props: { + value: string + label: string + index: number + disabled: boolean + highlighted: boolean +}) => JSX.Element + +export interface SingleSelectA11yProps { + /** necessary for IDs that are required for accessibility **/ + idPrefix: string.isRequired + + /** An array of options **/ + options: Array<{ + label: string + value: string + component?: SingleSelectA11yCustomOptionProp + disabled?: boolean + }> + + /** A callback that will be called with the new value or an empty string **/ + onChange: (value: string) => void + + /** Will focus the select initially **/ + autoFocus?: boolean + + /** Additional class names that will be applied to the root element **/ + className?: string + + /** This will allow us to put an aria-label on the clear button **/ + clearText?: string + + /** Whether a clear button should be displayed or not **/ + clearable?: boolean + + /** Allows to override what's rendered inside the `button[role="option"]`. + * Can be overriden on an individual option basis **/ + customOption?: SingleSelectA11yCustomOptionProp + + /** A value for a `data-test` attribute on the root element **/ + dataTest?: string + + /** Renders a select with lower height **/ + dense?: boolean + + /** Disables all interactions with the select (except focussing) **/ + disabled?: boolean + + /** Text or component to display when there are no options **/ + empty?: React.ReactNode + + /** Applies 'error' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props **/ + error?: boolean + + /** Help text that will be displayed below the input **/ + filterHelpText?: string + + /** Value will be used as aria-label attribute on the filter input **/ + filterLabel?: string + + /** Placeholder for the filter input **/ + filterPlaceholder?: string + + /** Value of the filter input **/ + filterValue?: string + + /** Whether the select should display a filter input **/ + filterable?: boolean + + /** Should contain the id of the element that labels the select, if applicable **/ + labelledBy?: string + + /** Will show a loading indicator at the end of the options-list **/ + loading?: boolean + + /** Text that will be displayed next to the loading indicator **/ + menuLoadingText?: string + + /** Allows to modify the max height of the menu **/ + menuMaxHeight?: string + + /** String that will be displayed when the select is being filtered but the options array is empty **/ + noMatchText?: string + + /** For a11y: How aggressively the user should be updated about changes in options **/ + optionUpdateStrategy?: 'off' | 'polite' | 'assertive' + + /** String to show when there's no value and no valueLabel **/ + placeholder?: string + + /** String that will be displayed before the label of the selected option **/ + prefix?: string + + /** Standard HTML tab-index attribute that will be put on the combobox's root element **/ + tabIndex?: number | string + + /** Applies 'valid' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props **/ + valid?: boolean + + /** As of now, this component does not support being uncontrolled **/ + value?: string + + /** + * When the option is not in the options list (e.g. not loaded or list is + * filtered), but a selected value needs to be displayed, then this prop can + * be used to supply the text to be shown. + **/ + valueLabel?: string + + /** Applies 'warning' appearance for validation feedback. Mutually exclusive with `warning` and `valid` props **/ + warning?: boolean + + /** Will be called when the combobox is loses focus **/ + onBlur?: (e: React.FocusEvent) => void + + /** Will be called when the last option is scrolled into the visible area **/ + onEndReached?: () => void + + /** Will be called when the filter value changes **/ + onFilterChange?: (value: string) => void + + /** Will be called when the combobox is being focused **/ + onFocus?: (e: React.FocusEvent) => void +} + +export const SingleSelectA11y: React.FC + +/** + * ==================== + * + * + * + * ==================== + **/ + export interface SingleSelectFieldProps { /** * Should be `SingleSelectOption` components @@ -402,6 +577,14 @@ export class SingleSelectField extends React.Component< render(): JSX.Element } +/** + * ==================== + * + * + * + * ==================== + **/ + export interface SingleSelectOptionProps { label: string value: string