@purpurds/autocomplete 0.0.1

package/src/listbox.tsx

@@ -0,0 +1,96 @@
+import React, {
+  Children,
+  ComponentPropsWithRef,
+  ForwardedRef,
+  forwardRef,
+  isValidElement,
+  ReactElement,
+  ReactNode,
+  ReactPortal,
+} from "react";
+import { checkmark, Icon } from "@purpurds/icon";
+import { Paragraph } from "@purpurds/paragraph";
+import c from "classnames/bind";
+
+import styles from "./listbox.module.scss";
+
+export * from "./useAutocomplete";
+const cx = c.bind(styles);
+
+const rootClassName = "purpur-listbox";
+
+type ListboxProps = Omit<ComponentPropsWithRef<"ul">, "role"> & {
+  "data-testid"?: string;
+  "aria-label": NonNullable<ComponentPropsWithRef<"ul">["aria-label"]>;
+  "aria-expanded": NonNullable<ComponentPropsWithRef<"ul">["aria-expanded"]>;
+};
+
+const Listbox = forwardRef(
+  ({ children, ...listboxProps }: ListboxProps, ref: ForwardedRef<HTMLUListElement>) => (
+    <ul
+      {...listboxProps}
+      ref={ref}
+      className={cx(rootClassName, listboxProps.className)}
+      role="listbox"
+    >
+      {Children.toArray(children).filter(isListboxItem)}
+    </ul>
+  )
+);
+Listbox.displayName = "ListBox";
+
+type ListboxItemProps = Omit<ComponentPropsWithRef<"li">, "role"> & {
+  "data-testid"?: string;
+  highlighted?: boolean;
+  hovered?: boolean;
+  key?: string;
+  selected?: boolean;
+  disabled?: boolean;
+  noninteractive?: boolean;
+};
+
+const ListboxItem = forwardRef((props: ListboxItemProps, ref: ForwardedRef<HTMLLIElement>) => {
+  const { disabled, highlighted, hovered, selected, children, noninteractive, ...liProps } = props;
+  const className = cx(`${rootClassName}-item`, liProps.className, {
+    [`${rootClassName}-item--highlighted`]: highlighted,
+    [`${rootClassName}-item--selected`]: selected,
+    [`${rootClassName}-item--hovered`]: hovered,
+    [`${rootClassName}-item--disabled`]: disabled,
+    [`${rootClassName}-item--noninteractive`]: noninteractive,
+  });
+
+  return (
+    <li
+      {...liProps}
+      ref={ref}
+      className={className}
+      aria-selected={!!selected}
+      role="option"
+      aria-disabled={!!disabled}
+    >
+      {typeof children === "string" ? <Paragraph>{children}</Paragraph> : children}
+      {selected && <Icon svg={checkmark} size="xs" className={cx(`${rootClassName}-item__icon`)} />}
+    </li>
+  );
+});
+ListboxItem.displayName = "ListBoxItem";
+
+function isListboxItem(
+  child:
+    | ReactElement
+    | Iterable<ReactNode>
+    | ReactPortal
+    | string
+    | number
+    | boolean
+    | null
+    | undefined
+): child is ReactElement<ListboxItemProps> {
+  return isValidElement<ListboxItemProps>(child) && child?.type === ListboxItem;
+}
+
+const Root = Listbox;
+const Item = ListboxItem;
+
+export { Item, Root };
+export type { ListboxItemProps, ListboxProps };

package/src/useAutocomplete.ts

@@ -0,0 +1,302 @@
+import { ComponentPropsWithRef, CSSProperties, ReactNode, useRef, useState } from "react";
+
+import { ListboxItemProps, ListboxProps } from "./listbox";
+import { useMutableRefObject, useOnClickOutside } from "./utils";
+
+export type Option = {
+  label: string;
+  id: string;
+  value?: string;
+  disabled?: boolean;
+};
+
+export type UseAutocompleteOptions<T extends Option> = {
+  /*
+   * Set to highlight the first option in the listbox when the input is focused.
+   */
+  highlightFirstOption?: boolean;
+  /*
+   * The default input value. Only to use when the input is uncontrolled.
+   */
+  defaultInputValue?: string;
+  /*
+   * The input value. Use this to control the input value.
+   */
+  inputValue?: string;
+  /*
+   * Invoked for each option. Use to control which options are shown.
+   */
+  filterOption?: (inputValue: string | undefined, option: T) => boolean;
+  /*
+   * Id will be used to prefix id:s of all elements.
+   */
+  id: string;
+  /*
+   * The label of the listbox (dropdown) displaying the options.
+   */
+  listboxLabel: string;
+  /*
+   * The height of the listbox. Number will be interpreted as px value. defaults to `calc(2 * var(--purpur-spacing-1200))`.
+   */
+  listboxMaxHeight?: string | number;
+  /*
+   * Shown when there are no options to show. Will be displayed inside a listbox item.
+   */
+  noOptionsText?: ReactNode;
+  /*
+   * Event handler invoked when the input value changes.
+   */
+  onInputChange?: (value: string) => void;
+  /*
+   * Set to open the listbox when input gets focus.
+   */
+  openOnFocus?: boolean;
+  /*
+   * Event handler invoked when an option is selected.
+   */
+  onSelect?: (option: T | undefined) => void;
+  /*
+   * The list of options. Could include custom props.
+   */
+  options: T[];
+  /*
+   * The selected option.
+   */
+  selectedOption?: T;
+  ["data-testid"]?: string;
+};
+
+export const useAutocomplete = <T extends Option>({
+  highlightFirstOption,
+  defaultInputValue,
+  inputValue,
+  filterOption,
+  id,
+  listboxLabel,
+  listboxMaxHeight,
+  onInputChange,
+  openOnFocus,
+  noOptionsText,
+  onSelect,
+  options,
+  selectedOption,
+  ["data-testid"]: dataTestid,
+}: UseAutocompleteOptions<T>) => {
+  const [internalInputValue, setInternalInputValue] = useState(
+    (typeof inputValue === "string" ? inputValue : defaultInputValue) || selectedOption?.label
+  );
+  const definiteInputValue = typeof inputValue === "string" ? inputValue : internalInputValue;
+  const [highlightedOption, setHighlightedOption] = useState<
+    (T & { isSetByClickEvent?: false }) | undefined
+  >(highlightFirstOption ? options[0] : undefined);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const internalRef = useMutableRefObject<HTMLDivElement | null>(null);
+  const listboxRef = useRef<HTMLUListElement>(null);
+  const optionRefs = useRef<Record<string, HTMLLIElement>>({});
+  const [listboxIsOpen, setListboxIsOpen] = useState(false);
+
+  function getTestId(name: string) {
+    return dataTestid ? `${dataTestid}-${name}` : undefined;
+  }
+
+  const closeListbox = () => {
+    setListboxIsOpen(false);
+    setHighlightedOption(undefined);
+  };
+
+  useOnClickOutside(internalRef.current, closeListbox);
+
+  const openListbox = ({ eventType }: { eventType: "CLICK" | "KEYBOARD" }) => {
+    setListboxIsOpen(true);
+    if (selectedOption) {
+      requestAnimationFrame(() => {
+        const isSetByClickEvent = eventType === "CLICK";
+        setHighlightedOption({ ...selectedOption, isSetByClickEvent });
+        scrollOptionIntoView(optionRefs.current[selectedOption.id]);
+      });
+    }
+  };
+
+  const filterOptions = (searchTerm: string | undefined) => {
+    if (filterOption) {
+      return options.filter((option) => filterOption(searchTerm, option));
+    }
+
+    if (!searchTerm) {
+      return options;
+    }
+
+    const searchTermChunks = searchTerm.toUpperCase().split(" ") || [];
+    return options.filter((option) =>
+      searchTermChunks.every((chunk) =>
+        (option.value || option.label).toUpperCase().includes(chunk)
+      )
+    );
+  };
+
+  const getOptionsToShow = (searchTerm: string | undefined): (T | undefined)[] => {
+    return selectedOption && selectedOption?.label === searchTerm
+      ? options
+      : filterOptions(searchTerm);
+  };
+
+  const optionsToShow = getOptionsToShow(definiteInputValue);
+
+  const populateInputField = (value: string) => {
+    onInputChange?.(value);
+    setInternalInputValue(value);
+  };
+
+  const scrollOptionIntoView = (option: HTMLLIElement | undefined) => {
+    if (option) {
+      const optionRect = option.getBoundingClientRect();
+      const listboxRect = listboxRef.current?.getBoundingClientRect() || { top: 0, bottom: 0 };
+      const isOptionOutsideView =
+        optionRect.top < listboxRect.top || optionRect.bottom > listboxRect.bottom;
+
+      if (isOptionOutsideView) {
+        option.scrollIntoView({ block: "nearest" });
+      }
+    }
+  };
+
+  const selectOption = (option: T | undefined) => {
+    if (option) {
+      inputRef.current?.focus();
+      populateInputField(option.label);
+      onSelect?.(option);
+    }
+    closeListbox();
+  };
+
+  const findNextOption = (key: "ArrowUp" | "ArrowDown"): T | undefined => {
+    const index =
+      highlightFirstOption && !highlightedOption
+        ? 0
+        : optionsToShow.findIndex((option) => option && highlightedOption?.id === option.id);
+
+    const optionsLength = optionsToShow.length;
+
+    return key === "ArrowDown"
+      ? optionsToShow[(index ?? -1) + 1] || optionsToShow[0]
+      : optionsToShow[(index ?? optionsLength) - 1] || optionsToShow[optionsLength - 1];
+  };
+
+  const showListbox = listboxIsOpen && (!!optionsToShow.length || !!noOptionsText);
+
+  const highlightNextOption = (key: "ArrowUp" | "ArrowDown") => {
+    !showListbox && openListbox({ eventType: "KEYBOARD" });
+    const nextOption = findNextOption(key);
+
+    setHighlightedOption(nextOption);
+    nextOption && scrollOptionIntoView(optionRefs.current[nextOption.id]);
+  };
+
+  const handleOnKeyDown: React.KeyboardEventHandler<HTMLInputElement> = (e) => {
+    switch (e.key) {
+      case "ArrowUp":
+      case "ArrowDown":
+        e.preventDefault(); // Preventing default to not move cursor in input
+        highlightNextOption(e.key);
+        break;
+      case "Enter": {
+        const optionToSelect = highlightedOption || (highlightFirstOption ? options[0] : undefined);
+        showListbox && selectOption(optionToSelect);
+        !showListbox && openListbox({ eventType: "KEYBOARD" });
+        break;
+      }
+      case "Escape":
+      case "Tab":
+        closeListbox();
+        break;
+    }
+  };
+
+  const handleOnChange: React.ChangeEventHandler<HTMLInputElement> = (e) => {
+    const nextOptionsToShow = getOptionsToShow(e.target.value);
+    populateInputField(e.target.value);
+    setHighlightedOption(undefined);
+    !showListbox && openListbox({ eventType: "KEYBOARD" });
+    highlightFirstOption &&
+      nextOptionsToShow[0] &&
+      scrollOptionIntoView(optionRefs.current[nextOptionsToShow[0].id]);
+  };
+
+  const handleOnMouseDown: React.MouseEventHandler<HTMLInputElement> = () => {
+    showListbox ? closeListbox() : openListbox({ eventType: "CLICK" });
+  };
+
+  const handleOnFocus = () => {
+    !listboxIsOpen && openOnFocus && openListbox({ eventType: "KEYBOARD" });
+    inputRef.current?.select();
+  };
+
+  const listboxStyle: CSSProperties = {
+    maxHeight: typeof listboxMaxHeight === "number" ? `${listboxMaxHeight}px` : listboxMaxHeight,
+  };
+
+  const listboxProps: ListboxProps = {
+    "aria-label": listboxLabel,
+    "aria-expanded": showListbox,
+    "data-testid": getTestId("listbox"),
+    id: `${id}-listbox`,
+    ref: listboxRef,
+    onMouseLeave: () => setHighlightedOption(undefined),
+    style: listboxMaxHeight ? listboxStyle : undefined,
+  };
+
+  const createListboxItemId = (option: T) => `${id}-listbox-item-${option.id}`;
+
+  const getListBoxItemProps = (option: T, index: number): ListboxItemProps => {
+    const handleOnMouseMove = () =>
+      option.id !== highlightedOption?.id &&
+      setHighlightedOption({ ...option, isSetByClickEvent: true });
+
+    const highlighted =
+      (option.id === highlightedOption?.id ||
+        (!!highlightFirstOption && !highlightedOption && index === 0)) &&
+      !highlightedOption?.isSetByClickEvent;
+
+    return {
+      "data-testid": getTestId(`listbox-item-${option.id}`),
+      id: createListboxItemId(option),
+      key: option.id,
+      onMouseMove: handleOnMouseMove,
+      onMouseUp: () => selectOption(option),
+      ref: (el) => el && (optionRefs.current[option.id] = el),
+      tabIndex: -1,
+      selected: option.id === selectedOption?.id,
+      disabled: option.disabled,
+      highlighted,
+      hovered: option.id === highlightedOption?.id && !!highlightedOption?.isSetByClickEvent,
+    };
+  };
+
+  const inputProps: ComponentPropsWithRef<"input"> & { "data-testid"?: string } = {
+    "aria-activedescendant": highlightedOption ? createListboxItemId(highlightedOption) : undefined,
+    "aria-autocomplete": "list",
+    "aria-controls": listboxProps.id,
+    "aria-expanded": showListbox,
+    "data-testid": getTestId("input"),
+    autoComplete: "off",
+    id: `${id}-input`,
+    onChange: handleOnChange,
+    onMouseDown: handleOnMouseDown,
+    onFocus: handleOnFocus,
+    onKeyDown: handleOnKeyDown,
+    ref: inputRef,
+    role: "combobox",
+    value: definiteInputValue,
+  };
+
+  return {
+    id,
+    inputProps,
+    internalRef,
+    optionsToShow,
+    showListbox,
+    noOptionsText,
+    getListBoxItemProps,
+    listboxProps,
+  };
+};

package/src/utils.ts

@@ -0,0 +1,28 @@
+import { MutableRefObject, useCallback, useEffect, useRef } from "react";
+
+// Used to "merge" "intersection types". Used to get comments on the props to the docs.
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {}; // eslint-disable-line @typescript-eslint/ban-types
+
+export const useMutableRefObject = <T>(value: T): MutableRefObject<T> => {
+  return useRef<T>(value) as MutableRefObject<T>;
+};
+
+export const useOnClickOutside = (element: HTMLElement | null, callback: () => void) => {
+  const handleClickOutside = useCallback(
+    (event: MouseEvent) => {
+      if (element && !element.contains(event.target as Node)) {
+        callback();
+      }
+    },
+    [callback, element]
+  );
+
+  useEffect(() => {
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => {
+      document.removeEventListener("mousedown", handleClickOutside);
+    };
+  }, [handleClickOutside]);
+};