widenarrow-ui 2.4.3 → 2.4.6

package/lib/index.d.ts

@@ -680,6 +680,12 @@ interface OptionItem {
      * reported as a string instead, so a numeric `value` comes back as e.g. `'2'`.
      */
     value: string | number;
+    /**
+     * Context shown after `text` on the same line, in a lighter colour, e.g. where a topic sits in a taxonomy.
+     * Matched by the Combobox's default filter. Not shown in pills or in the field, which show `text` only.
+     * With `nativeHtmlComponent`, shown in parentheses after `text`.
+     */
+    secondaryText?: string;
     /** Renders the option but prevents it from being picked. @default false */
     disabled?: boolean;
     /**
@@ -687,6 +693,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. */
@@ -728,14 +758,13 @@ interface SelectInputProps {
      * @default false
      */
     nativeHtmlComponent?: boolean;
-    /** Size from the smallest breakpoint up. @default SizeTypes.MEDIUM */
+    /** Size of the field, and of the list unless `listSize` is set. @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;
+    /**
+     * Size of the options in the list, when it should differ from the field's. Without it the list follows
+     * `size`, with medium options for a large field.
+     */
+    listSize?: SizeTypes.SMALL | SizeTypes.MEDIUM;
     /** Adds bottom spacing, for stacking fields in a form. @default false */
     marginBottom?: boolean;
     /** Focus the select on mount. @default false */
@@ -750,38 +779,29 @@ 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
      * saved value before its page of options is fetched, or a value picked from an earlier search.
      */
     selectedOptions?: Array<OptionItem>;
-    /**
-     * Text in the input, to control 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, with the reason. To fetch options for what the user
-     * types, use `onSearchChange` instead: the text of a `'reset'` is the selected option's label, which
-     * isn't a search.
-     */
-    onInputChange?: (inputValue: string, reason: ComboboxInputChangeReason) => void;
     /**
      * 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,
@@ -790,8 +810,8 @@ interface ComboboxBaseProps {
      */
     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
+     * Filters the options by the typed text. By default an option is shown when its `text` or
+     * `secondaryText` contains the typed text, ignoring case. Pass `false` when the options are already filtered, e.g. fetched for the
      * typed text from a server, with `onSearchChange`.
      */
     filterOptions?: ((options: OptionItem[], inputValue: string) => OptionItem[]) | false;
@@ -835,23 +855,20 @@ 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 */
+    /** Size of the field, and of the list unless `listSize` is set. @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;
+    /**
+     * Size of the options in the list, when it should differ from the field's. Without it the list follows
+     * `size`, with medium options for a large field.
+     */
+    listSize?: SizeTypes.SMALL | SizeTypes.MEDIUM;
     /** Adds bottom spacing, for stacking fields in a form. @default false */
     marginBottom?: boolean;
     /** Focus the input on mount. @default false */
@@ -866,6 +883,8 @@ interface ComboboxBaseProps {
     className?: string;
     /** Class name of the `<input>`. */
     inputClassName?: string;
+    /** Class name of the field around the input and the pills, e.g. to attach another element to it. */
+    fieldClassName?: string;
 }
 interface ComboboxSingleProps extends ComboboxBaseProps {
     /**
@@ -899,8 +918,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;
 
@@ -1111,8 +1128,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';
@@ -1138,10 +1155,6 @@ interface DropDownItemProps {
     iconClassName?: string;
     /** @default true */
     closeDropDownOnClick?: boolean;
-    descriptionColor?: Partial<ColorTypes>;
-    descriptionTextAlign?: TypographyTextAlign;
-    descriptionFontSize?: TypographyFontSize;
-    descriptionFontWeight?: TypographyFontWeight;
     descriptionClassName?: string;
     descriptionContainerClassName?: string;
 }
@@ -2097,7 +2110,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, listSize, ariaLabel, id, onChange, defaultOption, value, error, autoFocus, helperText, options, disabled, loading, name, className, inputClassName, marginBottom }: SelectInputProps): JSX.Element;
     displayName: string;
 };
 
@@ -2192,4 +2205,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 };