widenarrow-ui 2.4.2 → 2.4.5

package/lib/index.d.ts

@@ -687,6 +687,30 @@ interface OptionItem {
      * `nativeHtmlComponent`.
      */
     description?: string;
+    /**
+     * Icon before the text. In a Combobox with `multiple`, also shown on the option's pill. Not shown
+     * in the field of a single value, nor with `nativeHtmlComponent`.
+     */
+    leftIcon?: IconTypes;
+    /**
+     * Component before the text, e.g. an avatar or a logo. Shown in the list in place of `leftIcon`,
+     * while pills keep showing `leftIcon`. It doesn't make the option higher, so keep it to the size of an
+     * icon (24px). Not shown with `nativeHtmlComponent`.
+     */
+    leftComponent?: ReactNode;
+    /**
+     * Component after the text, e.g. status icons or an avatar. It doesn't make the option higher, so keep
+     * it to the size of an icon (24px). Must not contain buttons or links, as a click anywhere on the option
+     * picks it. Not shown with `nativeHtmlComponent`.
+     */
+    rightComponent?: ReactNode;
+    /**
+     * Heading of the group the option belongs to, e.g. `'Favorites'`. Options next to each other with
+     * the same `group` are listed under one heading, so keep each group's options together and put
+     * options without a group first. Rendered as an `<optgroup>` with `nativeHtmlComponent`. Values must
+     * be unique across groups.
+     */
+    group?: string;
 }
 interface SelectInputProps {
     /** Options to choose from, in display order. */
@@ -730,12 +754,6 @@ interface SelectInputProps {
     nativeHtmlComponent?: boolean;
     /** Size from the smallest breakpoint up. @default SizeTypes.MEDIUM */
     size?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
-    /** Size from the `$md` breakpoint up, overriding `size`. */
-    sizeMd?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
-    /** Size from the `$lg` breakpoint up, overriding `size` and `sizeMd`. */
-    sizeLg?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
-    /** Size from the `$xl` breakpoint up, overriding the smaller sizes. */
-    sizeXl?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
     /** Adds bottom spacing, for stacking fields in a form. @default false */
     marginBottom?: boolean;
     /** Focus the select on mount. @default false */
@@ -750,21 +768,23 @@ interface SelectInputProps {
     className?: string;
     /** Class name of the button that opens the list, or of the `<select>` with `nativeHtmlComponent`. */
     inputClassName?: string;
-    /** @deprecated Not used by the component. */
-    text?: string;
 }
 
-/** Why the text in the Combobox's input changed. */
-type ComboboxInputChangeReason = 
-/** The user typed. */
-'input'
-/** The text was set back to the selected option's label, e.g. after picking an option or leaving the field. */
- | 'reset'
-/** The clear button was used. */
- | 'clear';
 type ComboboxValue = string | number;
+/** Accessible names of the Combobox's buttons, e.g. to translate them. */
+interface ComboboxAriaLabels {
+    /** The button that clears the value. @default 'Clear' */
+    clearButton?: string;
+    /** The button that opens and closes the list. @default 'Show options' */
+    toggleButton?: string;
+    /** The remove button on each pill, with `multiple`. Also its tooltip. @default 'Remove' */
+    removePillButton?: string;
+}
 interface ComboboxBaseProps {
-    /** Options to choose from, in display order. Filtered by the typed text, unless `filterOptions` is false. */
+    /**
+     * Options to choose from, in display order. Filtered by the typed text, unless `filterOptions` is
+     * false. An option's `leftIcon` is also shown on its pill with `multiple`.
+     */
     options: Array<OptionItem>;
     /**
      * The options of the selected values, for their labels while they are not among `options`, e.g. a
@@ -772,19 +792,16 @@ interface ComboboxBaseProps {
      */
     selectedOptions?: Array<OptionItem>;
     /**
-     * Text in the input, to control it, e.g. to fetch options for it. Without it the Combobox keeps the
-     * text itself. When controlled, update it from `onInputChange`.
-     */
-    inputValue?: string;
-    /**
-     * Called when the text in the input changes. Fetch new options for reason `'input'` only: `'reset'`
-     * and `'clear'` set the text to the selected option's label or empty it.
+     * Called with the text to search for: what the user types, and `''` when the search ends, which is when
+     * an option is picked, the value is cleared or the field is left. Use it to fetch options per search,
+     * together with `filterOptions={false}`. Going back to `''` brings back the initial options, so the list
+     * doesn't stay filtered by an old search the next time it opens.
      */
-    onInputChange?: (inputValue: string, reason: ComboboxInputChangeReason) => void;
+    onSearchChange?: (searchText: string) => void;
     /**
      * Filters the options by the typed text. By default an option is shown when its `text` contains the
      * typed text, ignoring case. Pass `false` when the options are already filtered, e.g. fetched for the
-     * typed text from a server.
+     * typed text from a server, with `onSearchChange`.
      */
     filterOptions?: ((options: OptionItem[], inputValue: string) => OptionItem[]) | false;
     /** Visible label, associated with the input. Also its accessible name unless `ariaLabel` is set. */
@@ -827,23 +844,15 @@ interface ComboboxBaseProps {
      * all text in the input. Without it, a value can only be replaced by another. @default true
      */
     withClearButton?: boolean;
-    /** Accessible name of the clear button. @default 'Clear' */
-    clearButtonAriaLabel?: string;
-    /** Accessible name of the button that opens and closes the list. @default 'Show options' */
-    toggleButtonAriaLabel?: string;
+    /** Accessible names of the clear, toggle and pill remove buttons, e.g. to translate them. */
+    ariaLabels?: ComboboxAriaLabels;
     /**
      * Colours the input like a Button of that type, e.g. to use the Combobox as a picker in a toolbar.
      * The list is not affected. Without it, the input looks like the other form fields.
      */
     type?: HierarchyTypes.PRIMARY | HierarchyTypes.SECONDARY;
-    /** Size from the smallest breakpoint up. @default SizeTypes.MEDIUM */
+    /** @default SizeTypes.MEDIUM */
     size?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
-    /** Size from the `$md` breakpoint up, overriding `size`. */
-    sizeMd?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
-    /** Size from the `$lg` breakpoint up, overriding `size` and `sizeMd`. */
-    sizeLg?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
-    /** Size from the `$xl` breakpoint up, overriding the smaller sizes. */
-    sizeXl?: SizeTypes.SMALL | SizeTypes.MEDIUM | SizeTypes.LARGE;
     /** Adds bottom spacing, for stacking fields in a form. @default false */
     marginBottom?: boolean;
     /** Focus the input on mount. @default false */
@@ -891,8 +900,6 @@ interface ComboboxMultipleProps extends ComboboxBaseProps {
     onChange: (value: Array<ComboboxValue>) => void;
     /** Only with `multiple`: pills shown in the field. The rest are behind a "+ N" button that lists them, as in BadgeList. @default 5 */
     maxVisiblePills?: number;
-    /** Only with `multiple`: accessible name and tooltip of a pill's remove button. @default 'Remove' */
-    removePillAriaLabel?: string;
 }
 type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
 
@@ -1103,8 +1110,8 @@ interface DropDownItemProps {
      */
     active?: boolean;
     /**
-     * Where the check mark of an `active` item goes. On the right it matches the option lists of SelectInput
-     * and Combobox, and the left is free for `leftIcon`.
+     * Where the check mark of an `active` item goes. Keep it on the left in menus that pick one option, as
+     * SelectInput does, and put it on the right in menus that pick several, as a Combobox with `multiple` does.
      * @default 'left'
      */
     activeIconPosition?: 'left' | 'right';
@@ -1130,10 +1137,6 @@ interface DropDownItemProps {
     iconClassName?: string;
     /** @default true */
     closeDropDownOnClick?: boolean;
-    descriptionColor?: Partial<ColorTypes>;
-    descriptionTextAlign?: TypographyTextAlign;
-    descriptionFontSize?: TypographyFontSize;
-    descriptionFontWeight?: TypographyFontWeight;
     descriptionClassName?: string;
     descriptionContainerClassName?: string;
 }
@@ -2089,7 +2092,7 @@ declare const TabGroup: {
 };
 
 declare const SelectInput: {
-    ({ label, withLabel, inputRef, nativeHtmlComponent, size, sizeMd, sizeLg, sizeXl, ariaLabel, id, onChange, defaultOption, value, error, autoFocus, helperText, options, disabled, loading, name, className, inputClassName, marginBottom }: SelectInputProps): JSX.Element;
+    ({ label, withLabel, inputRef, nativeHtmlComponent, size, ariaLabel, id, onChange, defaultOption, value, error, autoFocus, helperText, options, disabled, loading, name, className, inputClassName, marginBottom }: SelectInputProps): JSX.Element;
     displayName: string;
 };
 
@@ -2184,4 +2187,4 @@ declare const NoDataMessage: {
     displayName: string;
 };
 
-export { AnimatedCount, AnimatedCountProps, AppColors, AspectRatioTypes, Badge, BadgeItem, BadgeList, BadgeListProps, BadgeProps, BadgeTypes, BorderInterface, Box, Button, Card, Checkbox, ColorStyleInterface, ColorTypes, Combobox, ComboboxInputChangeReason, ComboboxMultipleProps, ComboboxProps, ComboboxSingleProps, ComboboxValue, DropDown, DropDownItem, DropDownProps, DropDownRef, FacetButton, FlexStylingInterface, FontFamilyTypes, FormSkeleton, Grid, Heading, HierarchyInterface, HierarchyTypes, Icon, IconButton, IconStyleInterface, IconTypes, Image, InlineButton, Input, Label, Link, LinkTypes, ListButton, ListButtonProps, ListItem, ListSkeleton, MarginInterface, MultiActionButton, NoDataMessage, NumberBadge, NumberBadgeProps, PaddingInterface, Pagination, Paragraph, RadioButton, SelectInput, OptionItem as SelectInputOptionItem, SelectInputProps, Separator, SizeStyleInterface, SizeTypes, SkeletonItem, SolidSpinner, SortableTable, SortableTableCellInterface, SortableTableProps, Span, SwitchButton, Tab, TabGroup, TabGroupProps, TabIndicatorProps, TabProps, TabValue, TableTypes, TextAreaInput, ToolTip, borderClassNames, flexClassNames, marginClassNames, paddingClassNames };
+export { AnimatedCount, AnimatedCountProps, AppColors, AspectRatioTypes, Badge, BadgeItem, BadgeList, BadgeListProps, BadgeProps, BadgeTypes, BorderInterface, Box, Button, Card, Checkbox, ColorStyleInterface, ColorTypes, Combobox, ComboboxAriaLabels, ComboboxMultipleProps, ComboboxProps, ComboboxSingleProps, ComboboxValue, DropDown, DropDownItem, DropDownProps, DropDownRef, FacetButton, FlexStylingInterface, FontFamilyTypes, FormSkeleton, Grid, Heading, HierarchyInterface, HierarchyTypes, Icon, IconButton, IconStyleInterface, IconTypes, Image, InlineButton, Input, Label, Link, LinkTypes, ListButton, ListButtonProps, ListItem, ListSkeleton, MarginInterface, MultiActionButton, NoDataMessage, NumberBadge, NumberBadgeProps, PaddingInterface, Pagination, Paragraph, RadioButton, SelectInput, OptionItem as SelectInputOptionItem, SelectInputProps, Separator, SizeStyleInterface, SizeTypes, SkeletonItem, SolidSpinner, SortableTable, SortableTableCellInterface, SortableTableProps, Span, SwitchButton, Tab, TabGroup, TabGroupProps, TabIndicatorProps, TabProps, TabValue, TableTypes, TextAreaInput, ToolTip, borderClassNames, flexClassNames, marginClassNames, paddingClassNames };