@coopdigital/react 1.29.1 → 1.30.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coopdigital/react",
   "type": "module",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -107,7 +107,7 @@
     "storybook": "$storybook"
   },
   "dependencies": {
-    "@coopdigital/styles": "^1.20.0",
+    "@coopdigital/styles": "^1.21.0",
     "@radix-ui/react-popover": "^1.2.0",
     "clsx": "^2.1.1",
     "date-fns": "^4.4.0",
@@ -116,5 +116,5 @@
     "merge-refs": "^2.0.0",
     "react-day-picker": "^10.0.2"
   },
-  "gitHead": "3072c248f8c6fd325dae0835245b13b74aceced5"
+  "gitHead": "3f7a257781401d8700ddc0e16feeaeab452bd79e"
 }

package/src/components/Combobox/Combobox.context.ts

@@ -1,4 +1,6 @@
 "use client"
+import type { UseComboboxReturnValue } from "downshift"
+
 import { createContext, useContext } from "react"
 
 import type { ComboboxItem } from "@/components/Combobox/combobox-utils"
@@ -6,22 +8,19 @@ import type { ComboboxItem } from "@/components/Combobox/combobox-utils"
 import { StandardSizes } from "@/types"
 
 interface ComboboxContextValue {
-  disabled?: boolean
-  error?: boolean
-  items?: ComboboxItem[]
-  props?: {
-    getInputProps: Function
-    getItemProps: Function
-    getMenuProps: Function
-    getToggleButtonProps: Function
-    isOpen: boolean
-  }
+  disabled: boolean
+  downshift: UseComboboxReturnValue<ComboboxItem>
+  error: boolean
+  // The options currently shown, after filtering and the maxResults cap
+  items: ComboboxItem[]
+  // The number of options that match the input, before the cap
+  matchCount: number
   size?: StandardSizes
 }
 
-export const ComboboxContext = createContext<ComboboxContextValue>({})
+export const ComboboxContext = createContext<ComboboxContextValue | null>(null)
 
-export const useComboboxContext = () => {
+export const useComboboxContext = (): ComboboxContextValue => {
   const context = useContext(ComboboxContext)
   if (!context) throw new Error("Combobox components must be used inside <Combobox>")
   return context

package/src/components/Combobox/Combobox.tsx

@@ -4,13 +4,13 @@ import type { ButtonHTMLAttributes, HTMLAttributes, JSX, ReactNode, Ref } from "
 import clsx from "clsx"
 import {
   useCombobox,
-  UseComboboxHighlightedIndexChange,
-  UseComboboxInputValueChange,
-  UseComboboxIsOpenChange,
-  UseComboboxSelectedItemChange,
-  UseComboboxStateChange,
+  type UseComboboxHighlightedIndexChange,
+  type UseComboboxInputValueChange,
+  type UseComboboxIsOpenChange,
+  type UseComboboxState,
+  type UseComboboxStateChange,
 } from "downshift"
-import { useState } from "react"
+import { useEffect, useMemo, useRef, useState } from "react"
 
 import {
   type ComboboxItem,
@@ -18,19 +18,34 @@ import {
   defaultFilter,
   defaultIsItemDisabled,
   defaultItemToString,
+  isMatchingText,
   normalizeOptions,
+  resolveOption,
 } from "@/components/Combobox/combobox-utils"
 import { ComboboxContext, useComboboxContext } from "@/components/Combobox/Combobox.context"
 import { getFieldError, useField } from "@/components/Field/Field.context"
 import { ChevronDownIcon } from "@/components/icons"
-import { TextInput, TextInputProps } from "@/components/TextInput"
-import { useSlots } from "@/hooks"
+import { TextInput, type TextInputProps } from "@/components/TextInput"
+import { useDebounce, useId, useSlots } from "@/hooks"
 import { StandardSizes } from "@/types"
 import { getSlotProp } from "@/utils"
 
+export type { ComboboxItem, ComboboxOption } from "@/components/Combobox/combobox-utils"
+
+export interface ComboboxSelectEvent {
+  /** Whether the selection is a custom value, entered by users when `allowCustom` is set,
+   * rather than one of the options.
+   */
+  custom: boolean
+  /** The selected item, or `null` when the selection is cleared. For a custom value, this is a new item with that value. */
+  selectedItem: ComboboxItem | null
+  /** The value of the selected option, or `null` when the selection is cleared. */
+  value: string | null
+}
+
 export interface ComboboxProps extends Omit<
   HTMLAttributes<HTMLDivElement>,
-  "onChange" | "onSelect" | "onToggle"
+  "defaultValue" | "onChange" | "onSelect" | "onToggle"
 > {
   /** Specify whether custom values are accepted.
    *
@@ -41,9 +56,14 @@ export interface ComboboxProps extends Omit<
    *
    * This should be a set of `<Combobox.Controls>` and `<Combobox.Options>`.
    */
-  children?: string | ReactNode
+  children?: ReactNode
   /** Specify additional CSS classes. */
   className?: string
+  /** Specify the initial selected option, when the selection is not controlled with `selected`.
+   *
+   * Accepts a `ComboboxOption`, matched to the options by its value.
+   */
+  defaultSelected?: ComboboxOption | null
   /** Specify the disabled state. */
   disabled?: boolean
   /** Specify the component error state. */
@@ -59,10 +79,10 @@ export interface ComboboxProps extends Omit<
   inputFilter?: (items: ComboboxItem[], value: string) => ComboboxItem[]
   /** Custom function to mark item as disabled.
    *
-   * Default: `disabled` prop on `.ComboboxOption`
+   * Default: the `disabled` property of the option.
    */
   isItemDisabled?: (item: ComboboxItem) => boolean
-  /** Custom function to render text in the input field after selecting a value.
+  /** Custom function that gives the text shown in the input for an item. Typed text is matched against this text.
    *
    * Default: Uses item label or value: `item.label ?? item.value`.
    */
@@ -77,11 +97,11 @@ export interface ComboboxProps extends Omit<
    * This is a `downshift` event.
    */
   onHighlight?: (event: UseComboboxHighlightedIndexChange<ComboboxItem>) => void
-  /** Callback fired when users select an option from the list.
+  /** Callback fired when the selection changes, including when it is cleared.
    *
-   * This is a `downshift` event.
+   * The event contains the full option object in `selectedItem`, and its value in `value`. Both are `null` when the selection is cleared.
    */
-  onSelect?: (event: UseComboboxSelectedItemChange<ComboboxItem>) => void
+  onSelect?: (event: ComboboxSelectEvent) => void
   /** Callback fired whenever the state changes.
    *
    * This is a `downshift` event.
@@ -91,16 +111,19 @@ export interface ComboboxProps extends Omit<
    *
    * This is a `downshift` event.
    */
-  onToggle?: (changes: UseComboboxIsOpenChange<ComboboxItem>) => void
+  onToggle?: (event: UseComboboxIsOpenChange<ComboboxItem>) => void
   /** Specify whether the menu should appear immediately when clicking the input field.
    *
    * Default: `true`.
    */
   openOnClick?: boolean
-  /** Specify placeholder text. Do not use in place of a form label. */
-  placeholder?: string
   /** Specify a custom React ref for this component. */
   ref?: Ref<HTMLDivElement>
+  /** Specify the selected option, when the selection is controlled. Update it from `onSelect`.
+   *
+   * Accepts a `ComboboxOption`, matched to the options by its value, or `null` for no selection.
+   */
+  selected?: ComboboxOption | null
   /** Specify the component size. */
   size?: StandardSizes
 }
@@ -110,35 +133,76 @@ export interface ComboboxControlsProps extends HTMLAttributes<HTMLDivElement> {
    *
    * This should be a set of `<Combobox.Input>` and `<Combobox.Button>`.
    */
-  children?: React.ReactNode
+  children?: ReactNode
   /** Specify additional CSS classes. */
   className?: string
+  /** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLDivElement>
+}
+
+// Prefixes and suffixes are not supported on ComboboxInput
+export type ComboboxInputProps = Omit<
+  TextInputProps,
+  "defaultValue" | "prefix" | "prefixInline" | "suffix" | "suffixInline" | "value"
+>
+
+export interface ComboboxButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Specify the accessible label for the button.
+   *
+   * Default: `Toggle menu`
+   */
+  "aria-label"?: string
+  /** Content inside the component.
+   *
+   * Default: `ChevronIconDown`. */
+  children?: ReactNode
+  /** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLButtonElement>
 }
 
 export interface ComboboxOptionsProps extends HTMLAttributes<HTMLUListElement> {
   /** Specify additional CSS classes. */
   className?: string
+  /** Specify the maximum number of options to show in the list. Set to `false` to show all matching options.
+   *
+   * Default: `50`
+   */
+  maxResults?: false | number
+  /** Specify the message shown when more options match than `maxResults`.
+   *
+   * Default: `Showing X of Y results.`
+   */
+  maxResultsText?: (shown: number, total: number) => string
   /** Specify text to display when there are no matching options. */
   noResultsText?: string
   /** Specify array of options to choose from.
    *
-   * Can be either a simple string array or a complex `ComboboxOption` array.
+   * Accepts a `ComboboxOption` array: strings, or `ComboboxItem` objects with a `value` and an optional `label`.
    */
   options: ComboboxOption[]
+  /** Specify a custom React ref for this component. */
+  ref?: Ref<HTMLUListElement>
 }
 
-export type ComboboxInputProps = TextInputProps
+type ComboboxState = UseComboboxState<ComboboxItem>
+
+const DEFAULT_MAX_RESULTS = 50
+const ANNOUNCEMENT_DELAY = 750
+
+const defaultMaxResultsText = (shown: number, total: number): string =>
+  `Showing ${shown} of ${total} results.`
 
 const componentSlots = {
   ComboboxControls: null,
   ComboboxOptions: null,
 }
 
-export const Combobox = ({
+const Combobox = ({
   allowCustom = false,
   children,
   className,
-  disabled,
+  defaultSelected,
+  disabled = false,
   error,
   id,
   inputFilter,
@@ -151,79 +215,175 @@ export const Combobox = ({
   onToggle,
   openOnClick = true,
   ref,
+  selected,
   size,
   ...props
-}: ComboboxProps): JSX.Element | null => {
+}: ComboboxProps): JSX.Element => {
   const field = useField()
-  const uid = id ?? field?.id
+  const uid = useId(id ?? field?.id)
   const hasError = getFieldError(error, field)
 
   const slots = useSlots(componentSlots, children)
+  const options = getSlotProp<ComboboxOption[]>(slots.ComboboxOptions, "options")
+  const maxResults =
+    getSlotProp<false | number>(slots.ComboboxOptions, "maxResults") ?? DEFAULT_MAX_RESULTS
+  const items = useMemo(() => normalizeOptions(options ?? []), [options])
 
-  const userOptions = getSlotProp<ComboboxOption[]>(slots.ComboboxOptions, "options") ?? []
-  const items = normalizeOptions(userOptions)
+  const filter = inputFilter ?? defaultFilter
+  const toString = itemToString ?? defaultItemToString
+  const isDisabled = isItemDisabled ?? defaultIsItemDisabled
 
-  const [inputItems, setInputItems] = useState(items)
+  // Typing filters the list, and the input is cleared when the
+  // menu closes, so reopening after a selection shows every option
+  const [filterText, setFilterText] = useState("")
+  const matchingItems = useMemo(() => filter(items, filterText), [filter, items, filterText])
 
-  const componentProps = {
-    className: clsx("coop-combobox", className),
-    "data-field": "",
-    "data-size": size ?? undefined,
-    id: uid,
-    ...props,
+  // Rendering a long list is slow, as every option renders again when the
+  // highlight moves, so only the first matches are shown. Typed text is
+  // still checked against every option.
+  const visibleItems = useMemo(
+    () => (maxResults === false ? matchingItems : matchingItems.slice(0, maxResults)),
+    [matchingItems, maxResults]
+  )
+
+  const [initialSelectedItem] = useState(() => resolveOption(defaultSelected, items))
+  const selectedItem = selected === undefined ? undefined : resolveOption(selected, items)
+
+  // Work out the selection from the text in the input, so the two always
+  // agree. Returns null when the text does not match and custom values are
+  // not allowed.
+  const commit = (
+    changes: Partial<ComboboxState>,
+    closeMenu: boolean
+  ): Partial<ComboboxState> | null => {
+    const text = (changes.inputValue ?? "").trim()
+    if (text === "") return { ...changes, inputValue: "", selectedItem: null }
+
+    // Prefer the option downshift picked, such as the highlighted one, then
+    // look for an option with the same text
+    const picked = changes.selectedItem
+    const match =
+      picked && isMatchingText(toString(picked), text)
+        ? picked
+        : items.find((item) => !isDisabled(item) && isMatchingText(toString(item), text))
+
+    const closed = closeMenu ? { isOpen: false } : {}
+
+    if (match) return { ...changes, ...closed, inputValue: toString(match), selectedItem: match }
+    if (allowCustom)
+      return { ...changes, ...closed, inputValue: text, selectedItem: { value: text } }
+    return null
   }
 
-  const inputFilterActual = inputFilter ?? defaultFilter
-  const itemToStringActual = itemToString ?? defaultItemToString
+  const getChanges = (
+    state: ComboboxState,
+    type: string,
+    changes: Partial<ComboboxState>
+  ): Partial<ComboboxState> => {
+    const { InputBlur, InputChange, InputClick, InputKeyDownEnter, InputKeyDownEscape } =
+      useCombobox.stateChangeTypes
 
-  const comboboxProps = useCombobox<ComboboxItem>({
+    switch (type) {
+      // downshift keeps the selection when the input is emptied
+      case InputChange:
+        return changes.inputValue === "" ? { ...changes, selectedItem: null } : changes
+      case InputClick:
+        return openOnClick ? changes : { ...changes, isOpen: false }
+      // Closing the menu puts back the text of the selection, as the input
+      // is only checked against the options while the menu is open
+      case InputKeyDownEscape:
+        return state.isOpen ? { ...changes, inputValue: toString(state.selectedItem) } : changes
+      case InputBlur:
+        return commit(changes, false) ?? { ...changes, inputValue: "", selectedItem: null }
+      // Without a match, keep the menu open so users can pick an option
+      case InputKeyDownEnter:
+        return commit(changes, true) ?? { ...changes, isOpen: true }
+      default:
+        return changes
+    }
+  }
+
+  const downshift = useCombobox<ComboboxItem>({
+    getItemId: (index) => visibleItems[index]?.id ?? `${uid}_item_${index}`,
     id: uid,
-    inputId: uid + "_input",
-    isItemDisabled: isItemDisabled ?? defaultIsItemDisabled,
-    items: inputItems,
-    itemToString: itemToStringActual,
-    labelId: uid + "_label",
-    menuId: uid + "_menu",
+    initialSelectedItem,
+    inputId: `${uid}_input`,
+    isItemDisabled: isDisabled,
+    items: visibleItems,
+    // Compare options by value, as they are recreated when options change
+    itemToKey: (item) => item?.value,
+    itemToString: toString,
+    labelId: `${uid}_label`,
+    menuId: `${uid}_menu`,
     onHighlightedIndexChange: onHighlight,
     onInputValueChange: (event) => {
-      setInputItems(inputFilterActual(items, event.inputValue))
+      if (event.type === useCombobox.stateChangeTypes.InputChange) setFilterText(event.inputValue)
       onChange?.(event)
     },
-    onIsOpenChange: onToggle,
-    onSelectedItemChange: (event) => {
-      onSelect?.(event) // This might need to broadcast just the value to work with RHF - need to check
+    onIsOpenChange: (event) => {
+      if (!event.isOpen) setFilterText("")
+      onToggle?.(event)
     },
+    onSelectedItemChange: ({ selectedItem }) =>
+      onSelect?.({
+        custom: !!selectedItem && !items.some(({ value }) => value === selectedItem.value),
+        selectedItem,
+        value: selectedItem?.value ?? null,
+      }),
     onStateChange,
-    stateReducer(_, actionAndChanges) {
-      const { InputBlur, InputClick, InputKeyDownEnter } = useCombobox.stateChangeTypes
-
-      const { changes: state, type } = actionAndChanges
-      const currentInput = state.inputValue ?? ""
-      const hasMatch = items.some((item) => itemToStringActual(item) === currentInput)
-
-      switch (type) {
-        case openOnClick === false && InputClick:
-          return { ...state, isOpen: false }
-        case allowCustom === false && InputBlur:
-          return hasMatch ? state : { ...state, inputValue: "" }
-        case allowCustom === false && InputKeyDownEnter:
-          return hasMatch ? state : { ...state, isOpen: true }
-        default:
-          return state
-      }
+    selectedItem,
+    stateReducer(state, { changes, type }) {
+      const next = getChanges(state, type, changes)
+
+      // downshift reports a change when the selected object changes, so
+      // keep the current one when the value is the same
+      return next.selectedItem && next.selectedItem.value === state.selectedItem?.value
+        ? { ...next, selectedItem: state.selectedItem }
+        : next
     },
   })
 
-  // if (!slots.ComboboxControls || !slots.ComboboxOptions) {
-  //   console.warn("Combobox must contain Combobox.Controls and Combobox.Options")
-  //   return null
-  // }
+  // Options can arrive after the selection, such as when they are fetched,
+  // so show the option text once it is known. Text that users are typing is
+  // left alone.
+  const selection = resolveOption(downshift.selectedItem, items)
+  const selectionText = toString(selection)
+  const selectionValue = selection?.value
+  const previousSelection = useRef({ text: selectionText, value: selectionValue })
+  const { inputValue, setInputValue } = downshift
+
+  useEffect(() => {
+    const previous = previousSelection.current
+    previousSelection.current = { text: selectionText, value: selectionValue }
+
+    if (
+      selectionValue === previous.value &&
+      selectionText !== previous.text &&
+      inputValue === previous.text
+    ) {
+      setInputValue(selectionText)
+    }
+  }, [inputValue, selectionText, selectionValue, setInputValue])
 
   return (
     <ComboboxContext.Provider
-      value={{ disabled, error: hasError, items: inputItems, props: comboboxProps, size }}
+      value={{
+        disabled,
+        downshift,
+        error: hasError,
+        items: visibleItems,
+        matchCount: matchingItems.length,
+        size,
+      }}
     >
-      <div {...componentProps} ref={ref}>
+      <div
+        {...props}
+        className={clsx("coop-combobox", className)}
+        data-field=""
+        data-size={size ?? undefined}
+        id={uid}
+        ref={ref}
+      >
         {slots.ComboboxControls}
         {slots.ComboboxOptions}
       </div>
@@ -231,83 +391,125 @@ export const Combobox = ({
   )
 }
 
-const ComboboxInput = ({ className, placeholder, ...props }: ComboboxInputProps): JSX.Element => {
-  const combobox = useComboboxContext()
-  const componentProps = {
-    className,
-    disabled: combobox.disabled,
-    error: combobox.error,
-    placeholder,
-    size: combobox.size,
-    ...props,
-  }
-  return <TextInput {...componentProps} {...combobox.props?.getInputProps({})} />
-}
-
-const ComboboxButton = ({
+const ComboboxControls = ({
   children,
   className,
   ...props
-}: ButtonHTMLAttributes<HTMLButtonElement>): JSX.Element => {
+}: ComboboxControlsProps): JSX.Element => (
+  <div {...props} className={clsx("coop-combobox-controls", className)}>
+    {children}
+  </div>
+)
+
+const ComboboxInput = ({ error, name, size, ...props }: ComboboxInputProps): JSX.Element => {
   const combobox = useComboboxContext()
-  const componentProps = {
-    "aria-label": props["aria-label"] ?? "Toggle menu",
-    className,
-    disabled: combobox.disabled,
-    ...props,
-  }
+  const disabled = combobox.disabled || props.disabled
 
+  // Pass the props through downshift, so it combines its handlers and ref
+  // with those given here
+  const inputProps = combobox.downshift.getInputProps({ ...props, disabled })
+
+  // The visible input shows the option text, which can be a label, so it has
+  // no name. The form submits the selected value from a hidden input
+  // instead. The hidden input comes first, so the button still follows the
+  // visible input.
   return (
-    <button type="button" {...componentProps} {...combobox.props?.getToggleButtonProps()}>
-      {children ?? <ChevronDownIcon stroke="black" strokeWidth={1} width={"1.25rem"} />}
-    </button>
+    <>
+      {name && (
+        <input
+          disabled={disabled}
+          name={name}
+          type="hidden"
+          value={combobox.downshift.selectedItem?.value ?? ""}
+        />
+      )}
+      <TextInput {...inputProps} error={error ?? combobox.error} size={size ?? combobox.size} />
+    </>
   )
 }
 
-const ComboboxControls = ({
+const ComboboxButton = ({
+  "aria-label": ariaLabel = "Toggle menu",
   children,
-  className,
   ...props
-}: ComboboxControlsProps): JSX.Element => {
-  const componentProps = {
-    className: clsx("coop-combobox-controls", className),
+}: ComboboxButtonProps): JSX.Element => {
+  const combobox = useComboboxContext()
+
+  const buttonProps = combobox.downshift.getToggleButtonProps({
     ...props,
-  }
-  return <div {...componentProps}>{children}</div>
+    "aria-label": ariaLabel,
+    disabled: combobox.disabled || props.disabled,
+  })
+
+  return (
+    <button type="button" {...buttonProps}>
+      {children ?? <ChevronDownIcon stroke="black" strokeWidth={1} width="1.25rem" />}
+    </button>
+  )
 }
 
 const ComboboxOptions = ({
   className,
+  maxResults: _maxResults,
+  maxResultsText = defaultMaxResultsText,
   noResultsText = "No results",
-  options,
+  options: _options,
   ...props
-}: ComboboxOptionsProps): JSX.Element | null => {
-  const combobox = useComboboxContext()
+}: ComboboxOptionsProps): JSX.Element => {
+  const { downshift, items, matchCount } = useComboboxContext()
+  const { getItemProps, getMenuProps, isOpen } = downshift
 
-  const componentProps = {
-    className: clsx("coop-combobox-options", className),
-    ...props,
+  const getMessage = (): string => {
+    if (!isOpen) return ""
+    if (items.length === 0) return noResultsText
+    if (matchCount > items.length) return maxResultsText(items.length, matchCount)
+    return ""
   }
 
-  if (!options) {
-    return null
-  }
+  const message = getMessage()
+  const announcement = useDebounce(message, ANNOUNCEMENT_DELAY)
 
   return (
-    <ul {...componentProps} {...combobox.props?.getMenuProps()}>
-      {combobox.props?.isOpen && combobox.items?.length
-        ? combobox.items.map((item, index) => {
-            const itemProps = { ...combobox.props?.getItemProps({ index, item }) }
+    <>
+      <ul {...getMenuProps({ ...props, className: clsx("coop-combobox-options", className) })}>
+        {isOpen &&
+          items.map((item, index) => {
+            // Keep the option fields off the element, and pass its handlers
+            // through downshift so they are combined with its own
+            const {
+              children,
+              disabled: _disabled,
+              icon,
+              label,
+              onClick,
+              onMouseDown,
+              onMouseMove,
+              value,
+              ...attributes
+            } = item
+
             return (
-              <li key={item.value} {...itemProps} {...item}>
-                {item?.icon}
-                {item.children ?? item.label ?? item.value}
+              <li
+                key={value}
+                {...attributes}
+                {...getItemProps({ index, item, onClick, onMouseDown, onMouseMove })}
+              >
+                {icon}
+                {children ?? label ?? value}
               </li>
             )
-          })
-        : null}
-      {combobox.props?.isOpen && !combobox.items?.length && <li>{noResultsText}</li>}
-    </ul>
+          })}
+
+        {message && (
+          <li aria-hidden className="coop-combobox-message">
+            {message}
+          </li>
+        )}
+      </ul>
+      <span aria-live="polite" className="sr-only">
+        {announcement}
+      </span>
+    </>
   )
 }
 
@@ -326,3 +528,4 @@ Combobox.Button = ComboboxButton
 Combobox.Options = ComboboxOptions
 
 export default Combobox
+export { Combobox, ComboboxButton, ComboboxControls, ComboboxInput, ComboboxOptions }