diff --git a/package-lock.json b/package-lock.json index 07704e855..95050f2e6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2399,6 +2399,7 @@ }, "node_modules/@clack/prompts/node_modules/is-unicode-supported": { "version": "1.3.0", + "extraneous": true, "inBundle": true, "license": "MIT", "engines": { @@ -33344,6 +33345,16 @@ "name": "@spark-ui/combobox", "version": "0.1.0", "license": "MIT", + "dependencies": { + "@radix-ui/react-id": "1.0.1", + "@spark-ui/form-field": "^1.4.1", + "@spark-ui/icon": "^2.1.1", + "@spark-ui/icons": "^1.21.6", + "@spark-ui/popover": "^1.5.2", + "@spark-ui/visually-hidden": "^1.2.0", + "class-variance-authority": "0.7.0", + "downshift": "^8.2.3" + }, "peerDependencies": { "react": "^16.8 || ^17.0 || ^18.0", "react-dom": "^16.8 || ^17.0 || ^18.0", diff --git a/packages/components/combobox/package.json b/packages/components/combobox/package.json index 44f625c18..4ec32848b 100644 --- a/packages/components/combobox/package.json +++ b/packages/components/combobox/package.json @@ -27,6 +27,16 @@ "react-dom": "^16.8 || ^17.0 || ^18.0", "tailwindcss": "^3.0.0" }, + "dependencies": { + "@radix-ui/react-id": "1.0.1", + "@spark-ui/form-field": "^1.4.1", + "@spark-ui/icon": "^2.1.1", + "@spark-ui/icons": "^1.21.6", + "@spark-ui/popover": "^1.5.2", + "@spark-ui/visually-hidden": "^1.2.0", + "class-variance-authority": "0.7.0", + "downshift": "^8.2.3" + }, "repository": { "type": "git", "url": "https://github.com/adevinta/spark.git", diff --git a/packages/components/combobox/src/Combobox.doc.mdx b/packages/components/combobox/src/Combobox.doc.mdx index d3cb04900..d39ac4619 100644 --- a/packages/components/combobox/src/Combobox.doc.mdx +++ b/packages/components/combobox/src/Combobox.doc.mdx @@ -1,5 +1,6 @@ import { Meta, Canvas } from '@storybook/addon-docs' -import { ArgTypes } from '@storybook/blocks' +import { ArgTypes as ExtendedArgTypes } from '@docs/helpers/ArgTypes' +import { Callout } from '@docs/helpers/Callout' import { Combobox } from '.' @@ -9,7 +10,7 @@ import * as stories from './Combobox.stories' # Combobox -An input that behaves similarly to a select, with the addition of a free text input to filter options. +TODO ## Install @@ -25,8 +26,197 @@ import { Combobox } from '@spark-ui/combobox' ## Props - + -## Variants +## Usage + +### Default + +AutoSuggest is used as the default behaviour. The user can type anything in the input, the list is showing optional suggestions. + +### Controlled + + + +### Controlled open state + + + +### Disabled + +Use `disabled` on the root component to disable the combobox entirely. + + + +### Disabled Item + +Use `disabled` on individual `Combobox.Item` to disable them. + + + +### Filtering - AutoFilter + +Use `autoFilter` to filter out items that does not match the input value. This behaviour is not case-sensitive. + +For more custom filtering, logic should be done on call-site to render only desired items. + + + +### Filtering - Manual + +Use your own logic to filter out items depending on the inputValue or some external logic. + +This example showcases case-sensitive filtering. + + + +### Groups + +Similar to `optgroup` HTML tag, you can gather your items in groups. + +It is important to use `Combobox.Label` inside each `Combobox.Group` to give it an accessible name. + + + +### Item indicator + +Renders when the parent `ComboboxMenu.Item` is selected. + +You can style this element directly, or you can use it as a wrapper to put an icon into, or both. + + + +### Leading icon + +Use `Combobox.LeadingIcon` inside `Combobox.Input` to prefix your trigger with an icon. + + + +### Read only + +Use `readOnly` prop to indicate the combobox is only readable. + + + +### Status + +Use `state` prop to assign a specific state to the combobox, choosing from: `error`, `alert` and `success`. By doing so, the outline styles will be updated, and a status indicator will be displayed accordingly. + +You could also wrap `Combobox` with a `FormField` and pass the prop to `Formfield` instead. + + + +## Multiple selection + +### Default + +When using `multiple` mode, the component manages an array of values and no longer a single value. + +It means you must adapt `value`, `onValueChange` and `defaultValue` accordingly. + +In `multiple` mode, the combobox won't close when the user selects an item, and it is possible to unselect every item. + +In multiple selection mode, the input will go back to empty state after each selection in the list. +This is up to the developer to make it clear to the user which items are selected, by using other components such as chips, for example. + + + +### Controlled + + + +## Advanced usage + +### Custom item + +If your `Combobox.Item` contains anything else than raw text, you may use any JSX markup to customize it. + +**If you do so, you MUST use `Combobox.ItemText` inside of your item to give it a proper accessible name.** + + + +## Form field + +### Label + +Use `FormField.Label` to add a label to the input. + + + +### Hidden label + +In certain cases, a visible label may not be necessary. To achieve this behavior, use the `VisuallyHidden` component. + + + +### Required + +Use the `isRequired` prop of the `FormField` to indicate that the combobox is required. + + + +### Disabled + +The combobox `disabled` field status can be managed by the FormField `disabled` flag. + + + +### ReadOnly + +Apply `readOnly` to the wrapping `FormField` to indicate the combobox is only readable. + + + +### Validation + +Set the `state` prop of the `FormField` to `error` to indicate that the combobox is invalid. Optionally use the `FormField.ErrorMessage` to describe why the combobox is invalid. + + diff --git a/packages/components/combobox/src/Combobox.stories.tsx b/packages/components/combobox/src/Combobox.stories.tsx index 8e41b24b0..b4bd620bf 100644 --- a/packages/components/combobox/src/Combobox.stories.tsx +++ b/packages/components/combobox/src/Combobox.stories.tsx @@ -1,4 +1,10 @@ +/* eslint-disable max-lines */ +import { Button } from '@spark-ui/button' +import { FormField } from '@spark-ui/form-field' +import { Tag } from '@spark-ui/tag' +import { VisuallyHidden } from '@spark-ui/visually-hidden' import { Meta, StoryFn } from '@storybook/react' +import React, { ComponentProps, useState } from 'react' import { Combobox } from '.' @@ -9,4 +15,637 @@ const meta: Meta = { export default meta -export const Default: StoryFn = _args => +/** + * Minimal anatomy: + * - Combobox + * - Combobox.Trigger + * - Combobox.Input + * - Combobox.Popover + * - Combobox.Items + * - Combobox.Item + * + * Full anatomy: + * - Combobox + * - Combobox.Trigger + * - Combobox.LeadingIcon + * - Combobox.SelectedItems + * - Combobox.Input + * - Combobox.ClearButton + * - Combobox.Disclosure + * - Combobox.Popover + * - Combobox.Items + * - Combobox.Group + * - Combobox.Label + * - Combobox.Item + * - Combobox.ItemIndicator + * - Combobox.ItemText + * + * Filtering behaviour: + * - default: no filtering. + * - autoFilter: filters out values not matching the input. + * - autoSelect: filters out values not matching the input AND highlight the first matching item. + * - autoComplete: restrict typing in the input to any of the items values and highlight the rest of the first matching item behind the typing cursor + * - custom filtering: controlled mode for advancer filtering. Not managed by Spark. + * + * Optional parts: + * - Combobox.LeadingIcon + * - Combobox.ClearButton + * - Combobox.Disclosure + * - Combobox.Empty + * - Combobox.SelectedItems (chips) + * - Combobox.Popover + * + * Selection type: + * - single + * - multiple + */ + +export const Default: StoryFn = _args => { + return ( +
+ + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +export const Controlled: StoryFn = () => { + const [value, setValue] = useState('book-1') + const [inputValue, setInputValue] = useState('') + + return ( +
+ + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +export const ControlledOpenState: StoryFn = () => { + const [open, setOpen] = useState(false) + + return ( +
+
+ + +
+ +
+ + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+
+ ) +} + +export const CustomItem: StoryFn = _args => { + return ( +
+ + + + + + + To Kill a Mockingbird + New + + + War and Peace + New + + + The Idiot + New + + + A Picture of Dorian Gray + New + + + 1984 + New + + + Pride and Prejudice + New + + + + +
+ ) +} + +export const Disabled: StoryFn = _args => { + return ( +
+ + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +export const FilteringAutoFilter: StoryFn = _args => { + const items = { + 'book-1': 'To Kill a Mockingbird', + 'book-2': 'War and Peace', + 'book-3': 'The Idiot', + 'book-4': 'A Picture of Dorian Gray', + 'book-5': '1984', + 'book-6': 'Pride and Prejudice', + } + + return ( +
+ + + + + + No results found + {Object.entries(items).map(([value, text]) => ( + + {text} + + ))} + + + +
+ ) +} + +export const FilteringManual: StoryFn = () => { + const items = { + 'book-1': 'To Kill a Mockingbird', + 'book-2': 'War and Peace', + 'book-3': 'The Idiot', + 'book-4': 'A Picture of Dorian Gray', + 'book-5': '1984', + 'book-6': 'Pride and Prejudice', + } + const [inputValue, setInputValue] = useState('') + + return ( +
+ + + + + + No results found + {Object.entries(items).map(([value, text]) => { + if (!text.includes(inputValue)) return null + + return ( + + {text} + + ) + })} + + + +
+ ) +} + +export const ReadOnly: StoryFn = _args => { + return ( +
+ + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +export const DisabledItem: StoryFn = _args => { + return ( +
+ + + + + + To Kill a Mockingbird + War and Peace + + The Idiot + + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +export const Grouped: StoryFn = _args => { + return ( +
+ + + + + + Best-sellers + To Kill a Mockingbird + War and Peace + The Idiot + + + + + + Novelties + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + +
+ ) +} + +export const LeadingIcon: StoryFn = _args => { + return ( +
+ + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +// ClearIcon + +export const ItemIndicator: StoryFn = _args => { + return ( +
+ + + + + + + + To Kill a Mockingbird + + + + War and Peace + + + + The Idiot + + + + A Picture of Dorian Gray + + + + 1984 + + + + Pride and Prejudice + + + + +
+ ) +} + +export const Statuses: StoryFn = () => { + type Status = ComponentProps['state'] + + const statuses: Status[] = ['error', 'alert', 'success'] + + return ( +
+ {statuses.map(status => { + return ( + + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + ) + })} +
+ ) +} + +export const MultipleSelection: StoryFn = _args => { + return ( +
+ + + + + + No results found + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + +
+ ) +} + +export const MultipleSelectionControlled: StoryFn = () => { + const [inputValue, setInputValue] = useState('a') + const [selectedValues, setSelectedValues] = useState(['book-1', 'book-2']) + const items = { + 'book-1': 'To Kill a Mockingbird', + 'book-2': 'War and Peace', + 'book-3': 'The Idiot', + 'book-4': 'A Picture of Dorian Gray', + 'book-5': '1984', + 'book-6': 'Pride and Prejudice', + } + + return ( +
+ + + + + + No results found + {Object.entries(items).map(([key, value]) => { + return ( + + {value} + + ) + })} + + + +
+ ) +} + +export const FormFieldLabel: StoryFn = _args => { + return ( +
+ + Book + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + +
+ ) +} + +export const FormFieldHiddenLabel: StoryFn = _args => { + return ( +
+ + + Book + + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + +
+ ) +} + +export const FormFieldReadOnly: StoryFn = _args => { + return ( +
+ + Book + + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + +
+ ) +} + +export const FormFieldDisabled: StoryFn = _args => { + return ( +
+ + Book + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + +
+ ) +} + +export const FormFieldRequired: StoryFn = _args => { + return ( +
+ + Book + + + + + To Kill a Mockingbird + War and Peace + The Idiot + A Picture of Dorian Gray + 1984 + Pride and Prejudice + + + + +
+ ) +} + +export const FormFieldValidation: StoryFn = () => { + const [state, setState] = useState('error') + + return ( +
+ + Statuses + { + setState(value === 'default' ? undefined : (value as 'success' | 'alert' | 'error')) + }} + > + + + + default + success + alert + error + + + + + An effective title significantly increases your chances of making a sale + + Well done! + Take care of this field + The field is invalid + +
+ ) +} diff --git a/packages/components/combobox/src/Combobox.styles.ts b/packages/components/combobox/src/Combobox.styles.ts deleted file mode 100644 index e69de29bb..000000000 diff --git a/packages/components/combobox/src/Combobox.test.tsx b/packages/components/combobox/src/Combobox.test.tsx deleted file mode 100644 index 18ec46b06..000000000 --- a/packages/components/combobox/src/Combobox.test.tsx +++ /dev/null @@ -1,12 +0,0 @@ -import { render, screen } from '@testing-library/react' -import { describe, expect, it } from 'vitest' - -import { Combobox } from './Combobox' - -describe('Combobox', () => { - it('should render', () => { - render() - - expect(screen.getByText(/combobox/)).toBeInTheDocument() - }) -}) diff --git a/packages/components/combobox/src/Combobox.tsx b/packages/components/combobox/src/Combobox.tsx index ce8dac473..6bff53235 100644 --- a/packages/components/combobox/src/Combobox.tsx +++ b/packages/components/combobox/src/Combobox.tsx @@ -1 +1,19 @@ -export const Combobox = () => <>combobox +import { type ComboboxContextProps, ComboboxProvider } from './ComboboxContext' + +export type ComboboxProps = ComboboxContextProps + +export const Combobox = ({ + children, + autoFilter = false, + disabled = false, + readOnly = false, + ...props +}: ComboboxProps) => { + return ( + + {children} + + ) +} + +Combobox.displayName = 'Combobox' diff --git a/packages/components/combobox/src/ComboboxContext.tsx b/packages/components/combobox/src/ComboboxContext.tsx new file mode 100644 index 000000000..f2e9e0517 --- /dev/null +++ b/packages/components/combobox/src/ComboboxContext.tsx @@ -0,0 +1,251 @@ +import { useId } from '@radix-ui/react-id' +import { useFormFieldControl } from '@spark-ui/form-field' +import { Popover } from '@spark-ui/popover' +import { + createContext, + Dispatch, + Fragment, + PropsWithChildren, + SetStateAction, + useContext, + useEffect, + useState, +} from 'react' + +import { type ComboboxItem, type DownshiftState, type ItemsMap } from './types' +import { useCombobox } from './useCombobox' +import { getElementByIndex, getItemsFromChildren, hasChildComponent } from './utils' + +export interface ComboboxContextState extends DownshiftState { + itemsMap: ItemsMap + filteredItemsMap: ItemsMap + highlightedItem: ComboboxItem | undefined + hasPopover: boolean + setHasPopover: Dispatch> + multiple: boolean + disabled: boolean + readOnly: boolean + state?: 'error' | 'alert' | 'success' + lastInteractionType: 'mouse' | 'keyboard' + setLastInteractionType: (type: 'mouse' | 'keyboard') => void + setIsInputControlled: Dispatch> + setOnInputValueChange: Dispatch void) | undefined>> +} + +export type ComboboxContextCommonProps = PropsWithChildren<{ + /** + * The controlled open state of the select. Must be used in conjunction with `onOpenChange`. + */ + open?: boolean + /** + * Event handler called when the open state of the select changes. + */ + onOpenChange?: (isOpen: boolean) => void + /** + * The open state of the select when it is initially rendered. Use when you do not need to control its open state. + */ + defaultOpen?: boolean + /** + * Use `state` prop to assign a specific state to the combobox, choosing from: `error`, `alert` and `success`. By doing so, the outline styles will be updated, and a state indicator will be displayed accordingly. + */ + state?: 'error' | 'alert' | 'success' + /** + * When true, prevents the user from interacting with the combobox. + */ + disabled?: boolean + /** + * Sets the combobox as interactive or not. + */ + readOnly?: boolean + /** + * When true, the items will be filtered depending on the value of the input (not case-sensitive). + */ + autoFilter?: boolean +}> + +interface ComboboxPropsSingle { + /** + * Prop 'multiple' indicating whether multiple values are allowed. + */ + multiple?: false + /** + * The value of the select when initially rendered. Use when you do not need to control the state of the select. + */ + defaultValue?: string + /** + * The controlled value of the select. Should be used in conjunction with `onValueChange`. + */ + value?: string + /** + * Event handler called when the value changes. + */ + onValueChange?: (value: string) => void +} + +interface ComboboxPropsMultiple { + /** + * Prop 'multiple' indicating whether multiple values are allowed. + */ + multiple: true + /** + * The value of the select when initially rendered. Use when you do not need to control the state of the select. + */ + defaultValue?: string[] + /** + * The controlled value of the select. Should be used in conjunction with `onValueChange`. + */ + value?: string[] + /** + * Event handler called when the value changes. + */ + onValueChange?: (value: string[]) => void +} + +export type ComboboxContextProps = ComboboxContextCommonProps & + (ComboboxPropsSingle | ComboboxPropsMultiple) + +const ComboboxContext = createContext(null) + +const getFilteredItemsMap = (map: ItemsMap, inputValue: string | undefined): ItemsMap => { + if (!inputValue) return map + + return new Map( + Array.from(map).filter(([_, { text }]) => text.toLowerCase().includes(inputValue.toLowerCase())) + ) +} + +export const ComboboxProvider = ({ + autoFilter = true, + children, + defaultValue, + value, + onValueChange, + open, + onOpenChange, + defaultOpen, + multiple = false, + disabled: disabledProp = false, + readOnly: readOnlyProp = false, + state: stateProp, +}: ComboboxContextProps) => { + // Input state + const field = useFormFieldControl() + const [inputValue, setInputValue] = useState('') + const [onInputValueChange, setOnInputValueChange] = useState<(value: string) => void>() + const [isInputControlled, setIsInputControlled] = useState(false) + const state = field.state || stateProp + const id = useId(field.id) + const labelId = useId(field.labelId) + const disabled = field.disabled ?? disabledProp + const readOnly = field.readOnly ?? readOnlyProp + + // Items state + const [itemsMap, setItemsMap] = useState(getItemsFromChildren(children)) + const [filteredItemsMap, setFilteredItems] = useState( + autoFilter ? getFilteredItemsMap(itemsMap, inputValue) : itemsMap + ) + const [hasPopover, setHasPopover] = useState( + hasChildComponent(children, 'Combobox.Popover') + ) + const [lastInteractionType, setLastInteractionType] = useState<'mouse' | 'keyboard'>('mouse') + + useEffect(() => { + setFilteredItems(autoFilter ? getFilteredItemsMap(itemsMap, inputValue) : itemsMap) + }, [inputValue, itemsMap]) + + const handleDownshiftInputChange = (value: string | undefined) => { + if (!isInputControlled) { + setInputValue(value) + } + } + + // Downshift state + const comboboxState = useCombobox({ + itemsMap, + defaultValue, + value, + onValueChange, + open, + onOpenChange, + defaultOpen, + multiple, + id, + labelId, + inputValue, + setInputValue: handleDownshiftInputChange, + onInputValueChange, + filteredItems: filteredItemsMap, + }) + + /** + * Indices in a Map are set when an element is added to the Map. + * If for some reason, in the Combobox: + * - items order changes + * - items are added + * - items are removed + * + * The Map must be rebuilt from the new children in order to preserve logical indices. + * + * Downshift is heavily indices based for keyboard navigation, so it it important. + */ + useEffect(() => { + const newMap = getItemsFromChildren(children) + + const previousItems = [...itemsMap.values()] + const newItems = [...newMap.values()] + + const hasItemsChanges = + previousItems.length !== newItems.length || + previousItems.some((item, index) => { + const hasUpdatedValue = item.value !== newItems[index]?.value + const hasUpdatedText = item.text !== newItems[index]?.text + + return hasUpdatedValue || hasUpdatedText + }) + + if (hasItemsChanges) { + setItemsMap(newMap) + } + }, [children]) + + /** + * Warning: + * Downshift is expecting the items list to always be rendered, as per a11y guidelines. + * This is why the `Popover` is always opened in this component, but visually hidden instead from Combobox.Popover. + */ + const [WrapperComponent, wrapperProps] = hasPopover ? [Popover, { open: true }] : [Fragment, {}] + + return ( + + {children} + + ) +} + +export const useComboboxContext = () => { + const context = useContext(ComboboxContext) + + if (!context) { + throw Error('useComboboxContext must be used within a Combobox provider') + } + + return context +} diff --git a/packages/components/combobox/src/ComboboxDivider.tsx b/packages/components/combobox/src/ComboboxDivider.tsx new file mode 100644 index 000000000..72f284087 --- /dev/null +++ b/packages/components/combobox/src/ComboboxDivider.tsx @@ -0,0 +1,14 @@ +import { cx } from 'class-variance-authority' +import { forwardRef, type Ref } from 'react' + +interface DividerProps { + className?: string +} + +export const Divider = forwardRef( + ({ className }: DividerProps, forwardedRef: Ref) => { + return
+ } +) + +Divider.displayName = 'Combobox.Divider' diff --git a/packages/components/combobox/src/ComboboxEmpty.tsx b/packages/components/combobox/src/ComboboxEmpty.tsx new file mode 100644 index 000000000..efc67c8ae --- /dev/null +++ b/packages/components/combobox/src/ComboboxEmpty.tsx @@ -0,0 +1,22 @@ +import { forwardRef, type ReactNode, type Ref } from 'react' + +import { useComboboxContext } from './ComboboxContext' + +interface EmptyProps { + className?: string + children: ReactNode +} + +export const Empty = forwardRef( + ({ className, children }: EmptyProps, forwardedRef: Ref) => { + const { filteredItemsMap } = useComboboxContext() + + return filteredItemsMap.size === 0 ? ( +
+ {children} +
+ ) : null + } +) + +Empty.displayName = 'Combobox.Empty' diff --git a/packages/components/combobox/src/ComboboxGroup.tsx b/packages/components/combobox/src/ComboboxGroup.tsx new file mode 100644 index 000000000..c9df016e3 --- /dev/null +++ b/packages/components/combobox/src/ComboboxGroup.tsx @@ -0,0 +1,35 @@ +import { cx } from 'class-variance-authority' +import { forwardRef, ReactNode, type Ref } from 'react' + +import { ComboboxGroupProvider, useComboboxGroupContext } from './ComboboxItemsGroupContext' + +interface GroupProps { + children: ReactNode + className?: string +} + +export const Group = forwardRef( + ({ children, ...props }: GroupProps, forwardedRef: Ref) => { + return ( + + + {children} + + + ) + } +) + +const GroupContent = forwardRef( + ({ children, className }: GroupProps, forwardedRef: Ref) => { + const { labelId } = useComboboxGroupContext() + + return ( +
+ {children} +
+ ) + } +) + +Group.displayName = 'Combobox.Group' diff --git a/packages/components/combobox/src/ComboboxInput.styles.tsx b/packages/components/combobox/src/ComboboxInput.styles.tsx new file mode 100644 index 000000000..64d144ff5 --- /dev/null +++ b/packages/components/combobox/src/ComboboxInput.styles.tsx @@ -0,0 +1,33 @@ +import { cva } from 'class-variance-authority' + +export const styles = cva( + [ + 'flex w-full items-center justify-between', + 'min-h-sz-44 rounded-lg bg-surface text-on-surface px-lg', + // outline styles + 'ring-1 outline-none ring-inset focus:ring-2', + ], + { + variants: { + state: { + undefined: 'ring-outline focus:ring-outline-high', + error: 'ring-error', + alert: 'ring-alert', + success: 'ring-success', + }, + disabled: { + true: 'disabled:bg-on-surface/dim-5 cursor-not-allowed text-on-surface/dim-3', + }, + readOnly: { + true: 'disabled:bg-on-surface/dim-5 cursor-not-allowed text-on-surface/dim-3', + }, + }, + compoundVariants: [ + { + disabled: false, + state: undefined, + class: 'hover:ring-outline-high', + }, + ], + } +) diff --git a/packages/components/combobox/src/ComboboxInput.tsx b/packages/components/combobox/src/ComboboxInput.tsx new file mode 100644 index 000000000..cf4237955 --- /dev/null +++ b/packages/components/combobox/src/ComboboxInput.tsx @@ -0,0 +1,148 @@ +/* eslint-disable complexity */ +import { Icon } from '@spark-ui/icon' +import { IconButton } from '@spark-ui/icon-button' +import { ArrowHorizontalDown } from '@spark-ui/icons/dist/icons/ArrowHorizontalDown' +import { Popover } from '@spark-ui/popover' +import { useMergeRefs } from '@spark-ui/use-merge-refs' +import { VisuallyHidden } from '@spark-ui/visually-hidden' +import { ComponentPropsWithoutRef, forwardRef, Fragment, type Ref, useEffect } from 'react' + +import { useComboboxContext } from './ComboboxContext' +import { styles } from './ComboboxInput.styles' +import { LeadingIcon } from './ComboboxLeadingIcon' + +type InputPrimitiveProps = ComponentPropsWithoutRef<'input'> + +interface InputProps extends InputPrimitiveProps { + className?: string + onValueChange?: (value: string) => void +} + +export const Input = forwardRef( + ( + { + 'aria-label': ariaLabel, + className, + value: valueProp, + placeholder: placeholderProp, + onValueChange, + ...props + }: InputProps, + forwardedRef: Ref + ) => { + const { + getToggleButtonProps, + getDropdownProps, + getInputProps, + getLabelProps, + hasPopover, + disabled, + readOnly, + inputValue, + setInputValue, + setIsInputControlled, + state, + setLastInteractionType, + setOnInputValueChange, + multiple, + selectedItem, + selectedItems, + } = useComboboxContext() + + const isControlled = valueProp != null + const placeholder = + multiple && selectedItems.length ? selectedItems.map(i => i.text).join(', ') : placeholderProp + + useEffect(() => { + setIsInputControlled(isControlled) + if (isControlled) { + setInputValue(valueProp as string) + } + }, [isControlled, valueProp]) + + useEffect(() => { + // Make Downshift aware of `onValueChange` prop to dispatch it + if (onValueChange) { + setOnInputValueChange(() => onValueChange) + } + + // Sync input with combobox default value + if (!multiple && selectedItem && !isControlled) { + setInputValue(selectedItem.text) + } + }, []) + + const [PopoverAnchor, popoverAnchorProps] = hasPopover + ? [Popover.Anchor, { asChild: true, type: undefined }] + : [Fragment, {}] + + const [PopoverTrigger, popoverTriggerProps] = hasPopover + ? [Popover.Trigger, { asChild: true, type: undefined }] + : [Fragment, {}] + + const { ref: downshiftRef, ...downshiftInputProps } = getInputProps({ + ...getDropdownProps(), + onKeyDown: () => { + setLastInteractionType('keyboard') + }, + }) + + const ref = useMergeRefs(forwardedRef, downshiftRef) + + return ( + <> + {ariaLabel && ( + + + + )} + +
+ {/* 1 - Leading icon (optional) */} + + + + + {/* 2 - TODO - selected items (optional, multiple selection only) */} +

[selected items chips (v2)]

+ + {/* 3 - Input typing area - MANDATORY */} + + + + + {/* 4 - Combobox clear button (optional) */} +

[clear]

+ + {/* 5 - Combobox disclosure button (optional, advised for autoComplete not autoSuggest) */} + + + + + + + +
+ + + ) + } +) + +Input.displayName = 'Combobox.Input' diff --git a/packages/components/combobox/src/ComboboxItem.tsx b/packages/components/combobox/src/ComboboxItem.tsx new file mode 100644 index 000000000..85656ebd0 --- /dev/null +++ b/packages/components/combobox/src/ComboboxItem.tsx @@ -0,0 +1,101 @@ +import { useMergeRefs } from '@spark-ui/use-merge-refs' +import { cva, cx } from 'class-variance-authority' +import { forwardRef, type HTMLAttributes, type ReactNode, type Ref } from 'react' + +import { useComboboxContext } from './ComboboxContext' +import { ComboboxItemProvider, useComboboxItemContext } from './ComboboxItemContext' + +export interface ItemProps extends HTMLAttributes { + disabled?: boolean + value: string + children: ReactNode + className?: string +} + +export const Item = forwardRef( + ({ children, ...props }: ItemProps, forwardedRef: Ref) => { + const { value, disabled } = props + + return ( + + + {children} + + + ) + } +) + +const styles = cva('px-lg py-md text-body-1', { + variants: { + selected: { + true: 'font-bold', + }, + disabled: { + true: 'opacity-dim-3 cursor-not-allowed', + false: 'cursor-pointer', + }, + highlighted: { + true: '', + }, + interactionType: { + mouse: '', + keyboard: '', + }, + }, + compoundVariants: [ + { + highlighted: true, + interactionType: 'mouse', + class: 'bg-surface-hovered', + }, + { + highlighted: true, + interactionType: 'keyboard', + class: 'u-ring', + }, + ], +}) + +const ItemContent = forwardRef( + ( + { className, disabled = false, value, children }: ItemProps, + forwardedRef: Ref + ) => { + const { getItemProps, highlightedItem, lastInteractionType, filteredItemsMap } = + useComboboxContext() + const { textId, index, itemData, isSelected } = useComboboxItemContext() + + const isHighlighted = highlightedItem?.value === value + + const isVisible = Array.from(filteredItemsMap).some(([key]) => key === value) + + const { ref: downshiftRef, ...downshiftItemProps } = getItemProps({ item: itemData, index }) + const ref = useMergeRefs(forwardedRef, downshiftRef) + + if (!isVisible) return null + + return ( +
  • + {children} +
    • + ) + } +) + +Item.displayName = 'Combobox.Item' diff --git a/packages/components/combobox/src/ComboboxItemContext.tsx b/packages/components/combobox/src/ComboboxItemContext.tsx new file mode 100644 index 000000000..1068a9ad7 --- /dev/null +++ b/packages/components/combobox/src/ComboboxItemContext.tsx @@ -0,0 +1,53 @@ +import React, { createContext, type PropsWithChildren, useContext, useState } from 'react' + +import { useComboboxContext } from './ComboboxContext' +import { ComboboxItem } from './types' +import { getIndexByKey, getItemText } from './utils' + +type ItemTextId = string | undefined + +interface ComboboxItemContextState { + textId: ItemTextId + setTextId: React.Dispatch> + isSelected: boolean + itemData: ComboboxItem + index: number + disabled: boolean +} + +const ComboboxItemContext = createContext(null) + +export const ComboboxItemProvider = ({ + value, + disabled = false, + children, +}: PropsWithChildren<{ value: string; disabled?: boolean }>) => { + const { multiple, itemsMap, selectedItem, selectedItems } = useComboboxContext() + + const [textId, setTextId] = useState(undefined) + + const index = getIndexByKey(itemsMap, value) + const itemData: ComboboxItem = { disabled, value, text: getItemText(children) } + + const isSelected = multiple + ? selectedItems.some(selectedItem => selectedItem.value === value) + : selectedItem?.value === value + + return ( + + {children} + + ) +} + +export const useComboboxItemContext = () => { + const context = useContext(ComboboxItemContext) + + if (!context) { + throw Error('useComboboxItemContext must be used within a ComboboxItem provider') + } + + return context +} diff --git a/packages/components/combobox/src/ComboboxItemIndicator.tsx b/packages/components/combobox/src/ComboboxItemIndicator.tsx new file mode 100644 index 000000000..51d44c801 --- /dev/null +++ b/packages/components/combobox/src/ComboboxItemIndicator.tsx @@ -0,0 +1,35 @@ +import { Icon } from '@spark-ui/icon' +import { Check } from '@spark-ui/icons/dist/icons/Check' +import { cx } from 'class-variance-authority' +import { forwardRef, ReactNode, type Ref } from 'react' + +import { useComboboxItemContext } from './ComboboxItemContext' + +export interface ItemIndicatorProps { + children?: ReactNode + className?: string + label?: string +} + +export const ItemIndicator = forwardRef( + ({ className, children, label }: ItemIndicatorProps, forwardedRef: Ref) => { + const { disabled, isSelected } = useComboboxItemContext() + + const childElement = children || ( + + + + ) + + return ( + + {isSelected && childElement} + + ) + } +) + +ItemIndicator.displayName = 'Combobox.ItemIndicator' diff --git a/packages/components/combobox/src/ComboboxItemText.tsx b/packages/components/combobox/src/ComboboxItemText.tsx new file mode 100644 index 000000000..336d138e1 --- /dev/null +++ b/packages/components/combobox/src/ComboboxItemText.tsx @@ -0,0 +1,31 @@ +import { useId } from '@radix-ui/react-id' +import { cx } from 'class-variance-authority' +import { forwardRef, type Ref, useEffect } from 'react' + +import { useComboboxItemContext } from './ComboboxItemContext' + +export interface ItemTextProps { + children: string +} + +export const ItemText = forwardRef( + ({ children }: ItemTextProps, forwardedRef: Ref) => { + const id = useId() + + const { setTextId } = useComboboxItemContext() + + useEffect(() => { + setTextId(id) + + return () => setTextId(undefined) + }) + + return ( + + {children} + + ) + } +) + +ItemText.displayName = 'Combobox.ItemText' diff --git a/packages/components/combobox/src/ComboboxItems.tsx b/packages/components/combobox/src/ComboboxItems.tsx new file mode 100644 index 000000000..9ef298798 --- /dev/null +++ b/packages/components/combobox/src/ComboboxItems.tsx @@ -0,0 +1,43 @@ +import { useMergeRefs } from '@spark-ui/use-merge-refs' +import { cx } from 'class-variance-authority' +import { forwardRef, ReactNode, type Ref } from 'react' + +import { useComboboxContext } from './ComboboxContext' + +interface ItemsProps { + children: ReactNode + className?: string +} + +export const Items = forwardRef( + ({ children, className, ...props }: ItemsProps, forwardedRef: Ref) => { + const { isOpen, getMenuProps, hasPopover, setLastInteractionType } = useComboboxContext() + + const { ref: downshiftRef, ...downshiftMenuProps } = getMenuProps({ + onMouseMove: () => { + setLastInteractionType('mouse') + }, + }) + + const ref = useMergeRefs(forwardedRef, downshiftRef) + + return ( +
      + {children} +
    + ) + } +) + +Items.displayName = 'Combobox.Items' diff --git a/packages/components/combobox/src/ComboboxItemsGroupContext.tsx b/packages/components/combobox/src/ComboboxItemsGroupContext.tsx new file mode 100644 index 000000000..2f93c6c84 --- /dev/null +++ b/packages/components/combobox/src/ComboboxItemsGroupContext.tsx @@ -0,0 +1,28 @@ +import { useId } from '@radix-ui/react-id' +import React, { createContext, type PropsWithChildren, useContext } from 'react' + +export interface ComboboxContextState { + labelId: string +} + +type ComboboxContextProps = PropsWithChildren + +const ComboboxGroupContext = createContext(null) + +export const ComboboxGroupProvider = ({ children }: ComboboxContextProps) => { + const labelId = useId() + + return ( + {children} + ) +} + +export const useComboboxGroupContext = () => { + const context = useContext(ComboboxGroupContext) + + if (!context) { + throw Error('useComboboxGroupContext must be used within a ComboboxGroup provider') + } + + return context +} diff --git a/packages/components/combobox/src/ComboboxLabel.tsx b/packages/components/combobox/src/ComboboxLabel.tsx new file mode 100644 index 000000000..8bb8fc191 --- /dev/null +++ b/packages/components/combobox/src/ComboboxLabel.tsx @@ -0,0 +1,27 @@ +import { cx } from 'class-variance-authority' +import { forwardRef, type Ref } from 'react' + +import { useComboboxGroupContext } from './ComboboxItemsGroupContext' + +interface LabelProps { + children: string + className?: string +} + +export const Label = forwardRef( + ({ children, className }: LabelProps, forwardedRef: Ref) => { + const { labelId } = useComboboxGroupContext() + + return ( +
    + {children} +
    + ) + } +) + +Label.displayName = 'Combobox.Label' diff --git a/packages/components/combobox/src/ComboboxLeadingIcon.tsx b/packages/components/combobox/src/ComboboxLeadingIcon.tsx new file mode 100644 index 000000000..9c91f968c --- /dev/null +++ b/packages/components/combobox/src/ComboboxLeadingIcon.tsx @@ -0,0 +1,12 @@ +import { Icon } from '@spark-ui/icon' +import { ReactElement } from 'react' + +export const LeadingIcon = ({ children }: { children: ReactElement }) => { + return ( + + {children} + + ) +} + +LeadingIcon.displayName = 'Combobox.LeadingIcon' diff --git a/packages/components/combobox/src/ComboboxPopover.tsx b/packages/components/combobox/src/ComboboxPopover.tsx new file mode 100644 index 000000000..5641a358f --- /dev/null +++ b/packages/components/combobox/src/ComboboxPopover.tsx @@ -0,0 +1,50 @@ +import { Popover as SparkPopover } from '@spark-ui/popover' +import { cx } from 'class-variance-authority' +import { ComponentProps, forwardRef, Ref, useEffect } from 'react' + +import { useComboboxContext } from './ComboboxContext' + +export const Popover = forwardRef( + ( + { + children, + matchTriggerWidth = true, + sideOffset = 4, + className, + ...props + }: ComponentProps, + forwardedRef: Ref + ) => { + const { isOpen, setHasPopover } = useComboboxContext() + + useEffect(() => { + setHasPopover(true) + + return () => setHasPopover(false) + }, []) + + return ( + { + /** + * With a combobox pattern, the focus should remain on the trigger at all times. + * Passing the focus to the combobox popover would break keyboard navigation. + */ + e.preventDefault() + }} + {...props} + data-spark-component="combobox-popover" + > + {children} + + ) + } +) + +Popover.displayName = 'Combobox.Popover' diff --git a/packages/components/combobox/src/index.ts b/packages/components/combobox/src/index.ts index 79749a4f8..ec95b688a 100644 --- a/packages/components/combobox/src/index.ts +++ b/packages/components/combobox/src/index.ts @@ -1 +1,56 @@ -export { Combobox } from './Combobox' +import type { FC } from 'react' + +import { Combobox as Root, type ComboboxProps } from './Combobox' +import { ComboboxProvider, useComboboxContext } from './ComboboxContext' +import { Divider } from './ComboboxDivider' +import { Empty } from './ComboboxEmpty' +import { Group } from './ComboboxGroup' +import { Input } from './ComboboxInput' +import { Item } from './ComboboxItem' +import { ItemIndicator } from './ComboboxItemIndicator' +import { Items } from './ComboboxItems' +import { ItemText } from './ComboboxItemText' +import { Label } from './ComboboxLabel' +import { LeadingIcon } from './ComboboxLeadingIcon' +import { Popover } from './ComboboxPopover' + +export { useComboboxContext, ComboboxProvider } + +export const Combobox: FC & { + Group: typeof Group + Item: typeof Item + Items: typeof Items + ItemText: typeof ItemText + ItemIndicator: typeof ItemIndicator + Label: typeof Label + Popover: typeof Popover + Divider: typeof Divider + Input: typeof Input + LeadingIcon: typeof LeadingIcon + Empty: typeof Empty +} = Object.assign(Root, { + Group, + Item, + Items, + ItemText, + ItemIndicator, + Label, + Popover, + Divider, + Input, + LeadingIcon, + Empty, +}) + +Combobox.displayName = 'Combobox' +Group.displayName = 'Combobox.Group' +Items.displayName = 'Combobox.Items' +Item.displayName = 'Combobox.Item' +ItemText.displayName = 'Combobox.ItemText' +ItemIndicator.displayName = 'Combobox.ItemIndicator' +Label.displayName = 'Combobox.Label' +Popover.displayName = 'Combobox.Popover' +Divider.displayName = 'Combobox.Divider' +Input.displayName = 'Combobox.Input' +LeadingIcon.displayName = 'Combobox.LeadingIcon' +Empty.displayName = 'Combobox.Empty' diff --git a/packages/components/combobox/src/tests/Combobox.test.tsx b/packages/components/combobox/src/tests/Combobox.test.tsx new file mode 100644 index 000000000..5e65439d5 --- /dev/null +++ b/packages/components/combobox/src/tests/Combobox.test.tsx @@ -0,0 +1,333 @@ +import { render, screen } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import { useState } from 'react' +import { describe, expect, it } from 'vitest' + +import { Combobox } from '..' +import { getInput, getItem, getListbox, queryItem } from './test-utils' + +describe('Combobox', () => { + it('should render input and list of items', () => { + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + expect(getInput('Book')).toBeInTheDocument() + + expect(getListbox('Book')).toBeInTheDocument() + + expect(getItem('War and Peace')).toBeInTheDocument() + expect(getItem('1984')).toBeInTheDocument() + expect(getItem('Pride and Prejudice')).toBeInTheDocument() + }) + + describe('Popover behaviour', () => { + it('should open/close the popover when interacting with its input', async () => { + const user = userEvent.setup() + + // Given a close combobox (default state) + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + const input = getInput('Book') + + expect(input).toHaveAttribute('aria-expanded', 'false') + + // When the user interact with the input + await user.click(input) + + // Then the combobox has expanded + expect(input).toHaveAttribute('aria-expanded', 'true') + + // When the user interact with the input while expanded + await user.click(input) + + // Then the combobox is closed again + expect(input).toHaveAttribute('aria-expanded', 'false') + }) + + it('should open/close the items list when interacting with its input (no popover)', async () => { + const user = userEvent.setup() + + // Given a close combobox without a popover(default state) + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + ) + + const input = getInput('Book') + + expect(input).toHaveAttribute('aria-expanded', 'false') + + // When the user interact with the input + await user.click(input) + + // Then the combobox has expanded + expect(input).toHaveAttribute('aria-expanded', 'true') + + // When the user interact with the input while expanded + await user.click(input) + + // Then the combobox is closed again + expect(input).toHaveAttribute('aria-expanded', 'false') + }) + + it('should remain forced opened', async () => { + const user = userEvent.setup() + + // Given a combobox that should remain opened + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + expect(getInput('Book')).toHaveAttribute('aria-expanded', 'true') + + // When the user interacts with the input + await user.click(getInput('Book')) + + // Then the combobox remains opened + expect(getInput('Book')).toHaveAttribute('aria-expanded', 'true') + }) + + it('should be opened by default but close upon interaction', async () => { + const user = userEvent.setup() + + // Given a combobox that should remain opened + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + expect(getInput('Book')).toHaveAttribute('aria-expanded', 'true') + + // When the user interacts with the input + await user.click(getInput('Book')) + + // Then the combobox remains opened + expect(getInput('Book')).toHaveAttribute('aria-expanded', 'false') + }) + + it('should display Combobox.Empty when no items matches the input value', async () => { + const user = userEvent.setup() + + // Given a combobox with no selected value yet + render( + + + + + No results found + War and Peace + 1984 + Pride and Prejudice + + + + ) + + expect(screen.queryByText('No results found')).not.toBeInTheDocument() + + // When the user type "pri" to filter first item matching, then select it + await user.click(getInput('Book')) + await user.keyboard('{z}{z}{z}') + + // Then placeholder is replaced by the selected value + expect(screen.getByText('No results found')).toBeInTheDocument() + }) + }) + + describe('single selection', () => { + it('should select item', async () => { + const user = userEvent.setup() + + // Given a combobox with no selected value yet + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + // Then placeholder should be displayed + expect(getInput('Book').getAttribute('placeholder')).toBe('Pick a book') + expect(getInput('Book').getAttribute('value')).toBe('') + + // When the user select an item + await user.click(getInput('Book')) + await user.click(getItem('Pride and Prejudice')) + + // Then placeholder is replaced by the selected value + expect(screen.getByDisplayValue('Pride and Prejudice')).toBeInTheDocument() + + // Then the proper item is selected + expect(getItem('War and Peace')).toHaveAttribute('aria-selected', 'false') + expect(getItem('1984')).toHaveAttribute('aria-selected', 'false') + expect(getItem('Pride and Prejudice')).toHaveAttribute('aria-selected', 'true') + }) + + it('should render default selected option', () => { + // Given a combobox with a default selected value + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + // Then the corresponding item is selected + expect(getItem('1984')).toHaveAttribute('aria-selected', 'true') + }) + + it('should render default selected option with proper indicator when including it', () => { + // Given a combobox with a default selected value + render( + + + + + + + War and Peace + + + + 1984 + + + + Pride and Prejudice + + + + + ) + + // Then the corresponding item is selected + expect(screen.getByLabelText('selected')).toBeVisible() + }) + + it('should control value', async () => { + const user = userEvent.setup() + + // Given we control value by outside state and selected value + const ControlledImplementation = () => { + const [value, setValue] = useState('book-1') + const [inputValue, setInputValue] = useState('') + + return ( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + } + + render() + + expect(getItem('War and Peace')).toHaveAttribute('aria-selected', 'true') + + expect(screen.getByDisplayValue('')).toBeInTheDocument() + + // when the user select another item + await user.click(getInput('Book')) + await user.click(getItem('Pride and Prejudice')) + + // Then the selected value has been updated + expect(screen.getByDisplayValue('Pride and Prejudice')).toBeInTheDocument() + }) + + it('should select item using autoFilter (keyboard)', async () => { + const user = userEvent.setup() + + // Given a combobox with no selected value yet + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + // Then placeholder should be displayed + expect(getInput('Book').getAttribute('placeholder')).toBe('Pick a book') + + // When the user type "pri" to filter first item matching, then select it + await user.click(getInput('Book')) + await user.keyboard('{p}{r}{i}{ArrowDown}{Enter}') + + // Then placeholder is replaced by the selected value + expect(screen.getByDisplayValue('Pride and Prejudice')).toBeInTheDocument() + + // Then the proper item is selected + expect(queryItem('War and Peace')).not.toBeInTheDocument() + expect(queryItem('1984')).not.toBeInTheDocument() + expect(getItem('Pride and Prejudice')).toHaveAttribute('aria-selected', 'true') + }) + }) +}) diff --git a/packages/components/combobox/src/tests/contextErrors.test.tsx b/packages/components/combobox/src/tests/contextErrors.test.tsx new file mode 100644 index 000000000..94f09b8bb --- /dev/null +++ b/packages/components/combobox/src/tests/contextErrors.test.tsx @@ -0,0 +1,34 @@ +import { render } from '@testing-library/react' +import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest' + +import { Combobox } from '..' + +describe('Combobox', () => { + describe('context errors', () => { + beforeEach(() => { + vi.spyOn(console, 'error').mockImplementation(vi.fn(() => undefined)) + }) + + afterAll(() => { + vi.restoreAllMocks() + }) + + it('should throw when combobox context is missing', () => { + const renderComponent = () => render(My item) + + expect(renderComponent).toThrowError() + }) + + it('should throw when combobox item context is missing', () => { + const renderComponent = () => render() + + expect(renderComponent).toThrowError() + }) + + it('should throw when combobox items group context is missing', () => { + const renderComponent = () => render(Group label) + + expect(renderComponent).toThrowError() + }) + }) +}) diff --git a/packages/components/combobox/src/tests/itemsGroups.test.tsx b/packages/components/combobox/src/tests/itemsGroups.test.tsx new file mode 100644 index 000000000..9c01c24bd --- /dev/null +++ b/packages/components/combobox/src/tests/itemsGroups.test.tsx @@ -0,0 +1,37 @@ +import { render } from '@testing-library/react' +import { describe, expect, it } from 'vitest' + +import { Combobox } from '..' +import { getItemsGroup } from './test-utils' + +describe('Combobox', () => { + describe('Combobox.Group', () => { + it('should link items groups with their label', () => { + // Given a combobox with items groups and group labels + render( + + + + + + Best-sellers + War and Peace + 1984 + + + + Novelties + Pride and Prejudice + Pride and Prejudice + + + + + ) + + // Then each group have an accessible label + expect(getItemsGroup('Best-sellers')).toBeInTheDocument() + expect(getItemsGroup('Novelties')).toBeInTheDocument() + }) + }) +}) diff --git a/packages/components/combobox/src/tests/multipleSelection.test.tsx b/packages/components/combobox/src/tests/multipleSelection.test.tsx new file mode 100644 index 000000000..c03fdd931 --- /dev/null +++ b/packages/components/combobox/src/tests/multipleSelection.test.tsx @@ -0,0 +1,112 @@ +import { render } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import { describe, expect, it } from 'vitest' + +import { Combobox } from '..' +import { getInput, getItem } from './test-utils' + +describe('Combobox', () => { + describe('multiple selection', () => { + it('should select items', async () => { + const user = userEvent.setup() + + // Given a combobox with no selected value yet + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + // Then placeholder should be displayed + expect(getInput('Book').getAttribute('placeholder')).toBe('Pick a book') + + // When the user select two items + await user.click(getInput('Book')) + await user.click(getItem('1984')) + await user.click(getItem('Pride and Prejudice')) + + // Then placeholder is replaced by the selected value and suffix indicating remaining items + expect(getInput('Book').getAttribute('placeholder')).toBe('1984, Pride and Prejudice') + + // Then the proper items are selected + expect(getItem('War and Peace')).toHaveAttribute('aria-selected', 'false') + expect(getItem('1984')).toHaveAttribute('aria-selected', 'true') + expect(getItem('Pride and Prejudice')).toHaveAttribute('aria-selected', 'true') + }) + + it('should select all items using keyboard navigation', async () => { + const user = userEvent.setup() + + // Given a combobox with no selected value yet + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + // Then placeholder should be displayed + expect(getInput('Book').getAttribute('placeholder')).toBe('Pick a book') + + // When the user select all the items one by one using the keyboard + await user.click(getInput('Book')) + await user.keyboard('[ArrowDown][Enter]') + await user.keyboard('[ArrowDown][Enter]') + await user.keyboard('[ArrowDown][Enter]') + + // Then all items are selected + expect(getInput('Book').getAttribute('placeholder')).toBe( + 'War and Peace, 1984, Pride and Prejudice' + ) + expect(getItem('War and Peace')).toHaveAttribute('aria-selected', 'true') + expect(getItem('1984')).toHaveAttribute('aria-selected', 'true') + expect(getItem('Pride and Prejudice')).toHaveAttribute('aria-selected', 'true') + }) + + it('should be able to unselect a selected item', async () => { + const user = userEvent.setup() + + // Given a combobox with no selected value yet + render( + + + + + War and Peace + 1984 + Pride and Prejudice + + + + ) + + // When the user select an item + await user.click(getInput('Book')) + await user.click(getItem('1984')) + + // Then placeholder is replaced by the selected value + expect(getInput('Book').getAttribute('placeholder')).toBe('1984') + expect(getItem('1984')).toHaveAttribute('aria-selected', 'true') + + // When the user unselect that item + await user.click(getItem('1984')) + + // Then placeholder is shown again as the item is no longer selected + expect(getInput('Book').getAttribute('placeholder')).toBe('Pick a book') + expect(getItem('1984')).toHaveAttribute('aria-selected', 'false') + }) + }) +}) diff --git a/packages/components/combobox/src/tests/test-utils.ts b/packages/components/combobox/src/tests/test-utils.ts new file mode 100644 index 000000000..29213d683 --- /dev/null +++ b/packages/components/combobox/src/tests/test-utils.ts @@ -0,0 +1,21 @@ +import { screen } from '@testing-library/react' + +export const getInput = (accessibleName: string) => { + return screen.getByRole('combobox', { name: accessibleName }) +} + +export const getListbox = (accessibleName: string) => { + return screen.getByRole('listbox', { name: accessibleName }) +} + +export const getItemsGroup = (accessibleName: string) => { + return screen.getByRole('group', { name: accessibleName }) +} + +export const getItem = (accessibleName: string) => { + return screen.getByRole('option', { name: accessibleName }) +} + +export const queryItem = (accessibleName: string) => { + return screen.queryByRole('option', { name: accessibleName }) +} diff --git a/packages/components/combobox/src/tests/withFormField.test.tsx b/packages/components/combobox/src/tests/withFormField.test.tsx new file mode 100644 index 000000000..689c28a66 --- /dev/null +++ b/packages/components/combobox/src/tests/withFormField.test.tsx @@ -0,0 +1,33 @@ +import { FormField } from '@spark-ui/form-field' +import { render, screen } from '@testing-library/react' +import { describe, expect, it } from 'vitest' + +import { Combobox } from '..' +import { getInput } from './test-utils' + +describe('Combobox', () => { + describe('with FormField', () => { + it('should render error message when field is in error', () => { + render( + + Book + + + + + War and Peace + 1984 + Pride and Prejudice + + + + You forgot to select a book + + ) + + expect(getInput('Book')).toBeInTheDocument() + + expect(screen.getByText('You forgot to select a book')).toBeInTheDocument() + }) + }) +}) diff --git a/packages/components/combobox/src/types.ts b/packages/components/combobox/src/types.ts new file mode 100644 index 000000000..27b08eb43 --- /dev/null +++ b/packages/components/combobox/src/types.ts @@ -0,0 +1,12 @@ +import { type UseComboboxReturnValue, type UseMultipleSelectionReturnValue } from 'downshift' + +export interface ComboboxItem { + disabled: boolean + value: string + text: string +} + +export type ItemsMap = Map + +export type DownshiftState = UseComboboxReturnValue & + UseMultipleSelectionReturnValue diff --git a/packages/components/combobox/src/useCombobox.ts b/packages/components/combobox/src/useCombobox.ts new file mode 100644 index 000000000..44821ecde --- /dev/null +++ b/packages/components/combobox/src/useCombobox.ts @@ -0,0 +1,171 @@ +/* eslint-disable complexity */ +/* eslint-disable max-lines-per-function */ +/* eslint-disable no-console */ +import { + useCombobox as useDownshiftCombobox, + UseComboboxProps, + useMultipleSelection, +} from 'downshift' + +import { type ComboboxItem, type ItemsMap } from './types' + +type OnChangeValueType = string & string[] + +export interface DownshiftProps { + itemsMap: ItemsMap + filteredItems: ItemsMap + inputValue?: string + setInputValue: (value: string | undefined) => void + onInputValueChange?: (value: string) => void + value: string | string[] | undefined + defaultValue: string | string[] | undefined + onValueChange: ((value: string) => void) | ((value: string[]) => void) | undefined + open: boolean | undefined + onOpenChange: ((isOpen: boolean) => void) | undefined + defaultOpen: boolean | undefined + multiple: boolean | undefined + id: string + labelId: string +} + +/** + * This hooks abstract the complexity of using downshift with both single and multiple selection. + */ +export const useCombobox = ({ + itemsMap, + defaultValue, + value, + onValueChange, + open, + onOpenChange, + defaultOpen, + inputValue, + filteredItems, + setInputValue, + multiple, + id, + labelId, + onInputValueChange, +}: DownshiftProps) => { + const items = [...itemsMap.values()] + + const downshiftMultipleSelection = useMultipleSelection({ + selectedItems: value + ? items.filter(item => (value as string[]).includes(item.value)) + : undefined, + initialSelectedItems: defaultValue + ? items.filter(item => (defaultValue as string[]).includes(item.value)) + : undefined, + + onSelectedItemsChange: ({ selectedItems }) => { + const selectedValues = (selectedItems as ComboboxItem[]).map(item => item.value) + onValueChange?.(selectedValues as OnChangeValueType) + }, + }) + + /** + * Custom state reducer for multiple selection behaviour: + * - keeps the component opened when the user selects an item + * - preserves the higlighted index when the user select an item + * - selected items can be unselected, even the last selected item (as opposed to single selection behaviour) + */ + const stateReducer: UseComboboxProps['stateReducer'] = ( + state, + { changes, type } + ) => { + if (!multiple) return changes + + const { selectedItems, removeSelectedItem, addSelectedItem } = downshiftMultipleSelection + + switch (type) { + case useDownshiftCombobox.stateChangeTypes.InputKeyDownEnter: + case useDownshiftCombobox.stateChangeTypes.ItemClick: + if (changes.selectedItem != null) { + const isAlreadySelected = selectedItems.some( + selectedItem => selectedItem.value === changes.selectedItem?.value + ) + + if (isAlreadySelected) removeSelectedItem(changes.selectedItem) + else addSelectedItem(changes.selectedItem) + } + + return { + ...changes, + isOpen: true, // keep the menu open after selection. + highlightedIndex: state.highlightedIndex, // preserve highlighted index position + } + default: + return changes + } + } + + const onStateChange: UseComboboxProps['onStateChange'] = ({ + inputValue: newInputValue, + type, + selectedItem: newSelectedItem, + }) => { + const updateInputValue = (inputValue: string | undefined) => { + if (onInputValueChange) { + if (inputValue != null) onInputValueChange(inputValue) + } else { + setInputValue(inputValue) + } + } + + switch (type) { + case useDownshiftCombobox.stateChangeTypes.InputKeyDownEnter: + case useDownshiftCombobox.stateChangeTypes.ItemClick: + case useDownshiftCombobox.stateChangeTypes.InputBlur: + if (newSelectedItem) { + updateInputValue(multiple ? '' : newInputValue) + } + break + + case useDownshiftCombobox.stateChangeTypes.InputChange: + updateInputValue(newInputValue) + + break + default: + break + } + } + + const downshift = useDownshiftCombobox({ + items, + isItemDisabled: item => { + const isFilteredOut = + !!inputValue && + ![...filteredItems].some(([_, filteredItem]) => { + return item.value === filteredItem.value + }) + + return item.disabled || isFilteredOut + }, + itemToString: item => item?.text ?? '', + // a11y attributes + id, + labelId, + // Controlled open state + isOpen: open, // undefined must be passed for stateful behaviour (uncontrolled) + onIsOpenChange: ({ isOpen }) => { + if (isOpen != null) onOpenChange?.(isOpen) + }, + initialIsOpen: defaultOpen ?? false, + stateReducer, + // Controlled mode (single selection) + selectedItem: value ? itemsMap.get(value as string) : undefined, + initialSelectedItem: defaultValue ? itemsMap.get(defaultValue as string) : undefined, + onSelectedItemChange: ({ selectedItem }) => { + if (selectedItem?.value && !multiple) { + onValueChange?.(selectedItem?.value as OnChangeValueType) + } + }, + inputValue, + onStateChange, + }) + + return { + ...downshift, + ...downshiftMultipleSelection, + } +} diff --git a/packages/components/combobox/src/utils.ts b/packages/components/combobox/src/utils.ts new file mode 100644 index 000000000..6818c1ec3 --- /dev/null +++ b/packages/components/combobox/src/utils.ts @@ -0,0 +1,109 @@ +import React, { type FC, isValidElement, type ReactElement, type ReactNode } from 'react' + +import { type ItemProps } from './ComboboxItem' +import { type ComboboxItem, type ItemsMap } from './types' + +export function getIndexByKey(map: ItemsMap, targetKey: string) { + let index = 0 + for (const [key] of map.entries()) { + if (key === targetKey) { + return index + } + index++ + } + + return -1 +} + +const getKeyAtIndex = (map: ItemsMap, index: number) => { + let i = 0 + for (const key of map.keys()) { + if (i === index) return key + i++ + } + + return undefined +} + +export const getElementByIndex = (map: ItemsMap, index: number) => { + const key = getKeyAtIndex(map, index) + + return key !== undefined ? map.get(key) : undefined +} + +const getElementDisplayName = (element?: ReactElement) => { + return element ? (element.type as FC & { displayName?: string }).displayName : '' +} + +export const getOrderedItems = ( + children: ReactNode, + result: ComboboxItem[] = [] +): ComboboxItem[] => { + React.Children.forEach(children, child => { + if (!isValidElement(child)) return + + if (getElementDisplayName(child) === 'Combobox.Item') { + const childProps = child.props as ItemProps + result.push({ + value: childProps.value, + disabled: !!childProps.disabled, + text: getItemText(childProps.children), + }) + } + + if (child.props.children) { + getOrderedItems(child.props.children, result) + } + }) + + return result +} + +/** + * If Combobox.Item children: + * - is a string, then the string is used. + * - is JSX markup, then we look for Combobox.ItemText to get its string value. + */ +export const getItemText = (children: ReactNode, itemText = ''): string => { + if (typeof children === 'string') { + return children + } + + React.Children.forEach(children, child => { + if (!isValidElement(child)) return + + if (getElementDisplayName(child) === 'Combobox.ItemText') { + itemText = child.props.children + } + + if (child.props.children) { + getItemText(child.props.children, itemText) + } + }) + + return itemText +} + +export const getItemsFromChildren = (children: ReactNode): ItemsMap => { + const newMap: ItemsMap = new Map() + + getOrderedItems(children).forEach(itemData => { + newMap.set(itemData.value, itemData) + }) + + return newMap +} + +export const hasChildComponent = (children: ReactNode, displayName: string): boolean => { + return React.Children.toArray(children).some(child => { + if (!isValidElement(child)) return false + + if (getElementDisplayName(child) === displayName) { + return true + } else if (child.props.children) { + return hasChildComponent(child.props.children, displayName) + } + + return false + }) +} diff --git a/packages/components/input/src/Input.styles.ts b/packages/components/input/src/Input.styles.ts index 324fd2eb4..49f0c25cb 100644 --- a/packages/components/input/src/Input.styles.ts +++ b/packages/components/input/src/Input.styles.ts @@ -10,14 +10,10 @@ export const inputStyles = cva( 'bg-surface', 'text-ellipsis text-body-1 text-on-surface', 'caret-neutral', - 'autofill:shadow-surface', - 'autofill:shadow-[inset_0_0_0px_1000px]', - 'disabled:cursor-not-allowed', - 'disabled:bg-on-surface/dim-5 disabled:text-on-surface/dim-3', - 'read-only:cursor-default', - 'read-only:bg-on-surface/dim-5', + 'autofill:shadow-surface autofill:shadow-[inset_0_0_0px_1000px]', + 'disabled:cursor-not-allowed disabled:border-outline disabled:bg-on-surface/dim-5 disabled:text-on-surface/dim-3', + 'read-only:cursor-default read-only:bg-on-surface/dim-5', 'focus:ring-1 focus:ring-inset', - 'disabled:border-outline', ], { variants: {