@react-md/core 1.0.0-next.2 → 1.0.0-next.21

package/src/autocomplete/Autocomplete.tsx

@@ -0,0 +1,361 @@
+"use client";
+
+import { type ReactElement } from "react";
+
+import { Listbox } from "../form/Listbox.js";
+import { TextField } from "../form/TextField.js";
+import { ListSubheader } from "../list/ListSubheader.js";
+import { KeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
+import { useEnsuredId } from "../useEnsuredId.js";
+import { useEnsuredRef } from "../useEnsuredRef.js";
+import { AutocompleteChip } from "./AutocompleteChip.js";
+import { AutocompleteCircularProgress } from "./AutocompleteCircularProgress.js";
+import { AutocompleteClearButton } from "./AutocompleteClearButton.js";
+import { AutocompleteDropdownButton } from "./AutocompleteDropdownButton.js";
+import { AutocompleteListboxChildren } from "./AutocompleteListboxChildren.js";
+import { autocomplete, autocompleteRightAddon } from "./autocompleteStyles.js";
+import {
+  defaultAutocompleteFilter,
+  noopAutocompleteFilter,
+} from "./defaults.js";
+import {
+  type AutocompleteMultiSelectProps,
+  type AutocompleteOption,
+  type AutocompleteProps,
+  type AutocompleteSingleSelectProps,
+} from "./types.js";
+import { useAutocomplete } from "./useAutocomplete.js";
+
+const noop = (): undefined => undefined;
+
+/**
+ * An `Autocomplete` is a component that allows for real-time suggestions from
+ * a pre-determined list as the user types by filtering data based on the
+ * current value. It can also be used to interact with an API that handles the
+ * sorting, filtering, matching, etc as well.
+ *
+ * An `Autocomplete` always requires the following props:
+ *
+ * - `options` - a list of available options that can be a list of strings,
+ *   a list of objects with a `{ label: string }`, or any list of objects
+ *   - if the list of objects do not have a `label`, the
+ *     {@link AutocompleteProps.getOptionLabel} **must** be provided to allow
+ *     filtering
+ * - `label` or `aria-label` to describe the textbox for accessibility
+ * - `listboxLabel` or `listboxLabelledBy` for an accessible label describing the options
+ *
+ * @example Simple Example
+ * ```tsx
+ * "use client";
+ *
+ * import { Autocomplete } from "@react-md/core/autocomplete/Autocomplete";
+ * import { type ReactElement } from "react";
+ *
+ * export default function SimpleExample(): ReactElement {
+ *   return (
+ *     <Autocomplete
+ *       label="Fruit"
+ *       placeholder="Apple"
+ *       listboxLabel="Fruits"
+ *       options={[
+ *         "Apple",
+ *         "Apricot",
+ *         "Banana",
+ *         "Blueberry",
+ *         "Cranberry",
+ *         "Kiwi",
+ *         "Mango",
+ *         "Orange",
+ *         "Peach",
+ *         "Plum",
+ *         "Strawberry",
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @since 6.0.0
+ */
+export function Autocomplete<Option extends AutocompleteOption>(
+  props: AutocompleteSingleSelectProps<Option>
+): ReactElement;
+/**
+ * To create an `Autocomplete` that can have multiple values selected at once,
+ * either provide an array `value` or `defaultValue`.
+ *
+ * @example Simple Example
+ * ```tsx
+ * "use client";
+ *
+ * import { Autocomplete } from "@react-md/core/autocomplete/Autocomplete";
+ * import { type ReactElement, useState } from "react";
+ *
+ * export default function SimpleExample(): ReactElement {
+ *   const [value, setValue] = useState<readonly Dessert[]>([]);
+ *   return (
+ *     <Autocomplete
+ *       label="Fruit"
+ *       placeholder="Apple"
+ *       listboxLabel="Fruits"
+ *       options={[
+ *         "Apple",
+ *         "Apricot",
+ *         "Banana",
+ *         "Blueberry",
+ *         "Cranberry",
+ *         "Kiwi",
+ *         "Mango",
+ *         "Orange",
+ *         "Peach",
+ *         "Plum",
+ *         "Strawberry",
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @since 6.0.0
+ */
+export function Autocomplete<Option extends AutocompleteOption>(
+  props: AutocompleteMultiSelectProps<Option>
+): ReactElement;
+/**
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @since 6.0.0
+ * @internal
+ */
+export function Autocomplete<Option extends AutocompleteOption>(
+  props: AutocompleteProps<Option>
+): ReactElement {
+  const {
+    id: propId,
+    onBlur,
+    onFocus,
+    onClick,
+    onChange,
+    onKeyDown,
+    onOpen,
+    type,
+    className,
+    inputRef,
+    children,
+    filter = type === "search"
+      ? noopAutocompleteFilter
+      : defaultAutocompleteFilter,
+    filterSelected,
+    value,
+    setValue,
+    defaultValue,
+    onValueChange,
+    query,
+    setQuery,
+    defaultQuery,
+    options,
+    getOptionLabel: propGetOptionLabel,
+    getOptionProps: propGetOptionProps,
+    allowAnyValue,
+    listboxProps,
+    listboxLabel,
+    listboxLabelledBy,
+    selectedIcon,
+    unselectedIcon,
+    selectedIconAfter,
+    checkboxes,
+    disableSelectedIcon,
+    loading,
+    loadingProps,
+    dropdownButtonProps,
+    disableDropdownButton,
+    clearButtonProps,
+    disableClearButton,
+    clearButtonVisibility = "query",
+    noOptionsChildren = <ListSubheader>No Options</ListSubheader>,
+    leftAddon: propLeftAddon,
+    disableLeftAddonStyles: propDisableLeftAddonStyles,
+    labelProps,
+    rightAddon,
+    rightAddonProps,
+    containerProps,
+    getChipProps = noop,
+    updateQueryOnSelect,
+    visible,
+    setVisible,
+    defaultVisible,
+    disableInlineChips,
+    disableCloseOnSelect,
+    ...remaining
+  } = props;
+  const { form, disabled } = props;
+
+  const id = useEnsuredId(propId, "autocomplete");
+  const menuId = useEnsuredId(listboxProps?.id, "autocomplete-listbox");
+  const {
+    query: currentQuery,
+    value: currentValue,
+    setValue: currentSetValue,
+    multiselect,
+    comboboxRef: inputNodeRef,
+    comboboxProps,
+    movementContext,
+    availableOptions,
+    getOptionLabel,
+    getOptionProps,
+    getListboxProps,
+    getClearButtonProps,
+    getDropdownButtonProps,
+  } = useAutocomplete({
+    form,
+    onBlur,
+    onFocus,
+    onClick,
+    onChange,
+    onKeyDown,
+    onOpen,
+    disabled,
+    filter,
+    filterSelected,
+    popupId: menuId,
+    popupRef: listboxProps?.ref,
+    comboboxId: id,
+    comboboxRef: inputRef,
+    options,
+    getOptionLabel: propGetOptionLabel,
+    getOptionProps: propGetOptionProps,
+    allowAnyValue,
+    updateQueryOnSelect,
+    value,
+    setValue,
+    defaultValue,
+    onValueChange,
+    query,
+    setQuery,
+    defaultQuery,
+    defaultVisible,
+    visible,
+    setVisible,
+    checkboxes,
+    selectedIcon,
+    unselectedIcon,
+    selectedIconAfter,
+    disableSelectedIcon,
+    disableCloseOnSelect,
+  });
+  const [containerRef, containerRefCallback] = useEnsuredRef(
+    containerProps?.ref
+  );
+
+  let leftAddon = propLeftAddon;
+  let disableLeftAddonStyles = propDisableLeftAddonStyles;
+  let inlineChips = false;
+  let floatingActive = labelProps?.floatingActive;
+  if (multiselect && !disableInlineChips) {
+    inlineChips = true;
+    // TODO: Maybe one day fix the typing? Might not be possible with
+    // destructuring though
+    const value = currentValue as readonly Option[];
+    disableLeftAddonStyles ??= true;
+    floatingActive ||= value.length > 0;
+    leftAddon = (
+      <>
+        {value.map((option, index) => {
+          const label = getOptionLabel(option);
+          const overrides = getChipProps({
+            index,
+            query: currentQuery,
+            option,
+            extractor: getOptionLabel,
+          });
+          return (
+            <AutocompleteChip
+              key={label}
+              {...overrides}
+              onClick={(event) => {
+                overrides?.onClick?.(event);
+                currentSetValue(value.filter((v) => v !== option));
+              }}
+            >
+              {overrides?.children ?? label}
+            </AutocompleteChip>
+          );
+        })}
+      </>
+    );
+  }
+
+  return (
+    <KeyboardMovementProvider value={movementContext}>
+      <TextField
+        {...remaining}
+        {...comboboxProps}
+        containerProps={{
+          ...containerProps,
+          ref: containerRefCallback,
+          onClick: (event) => {
+            containerProps?.onClick?.(event);
+            inputNodeRef.current?.focus();
+          },
+        }}
+        className={autocomplete({
+          className,
+          loading,
+          inlineChips,
+          disableClearButton,
+          disableDropdownButton,
+        })}
+        labelProps={{
+          ...labelProps,
+          floatingActive,
+        }}
+        leftAddon={leftAddon}
+        disableLeftAddonStyles={disableLeftAddonStyles}
+        rightAddon={
+          <>
+            {rightAddon}
+            {loading && <AutocompleteCircularProgress {...loadingProps} />}
+            {!disableClearButton && (
+              <AutocompleteClearButton
+                {...clearButtonProps}
+                visibility={clearButtonVisibility}
+                {...getClearButtonProps(clearButtonProps)}
+              />
+            )}
+            {!disableDropdownButton && (
+              <AutocompleteDropdownButton
+                aria-label={listboxLabel as string}
+                aria-labelledby={listboxLabelledBy}
+                {...getDropdownButtonProps(dropdownButtonProps)}
+              />
+            )}
+          </>
+        }
+        rightAddonProps={{
+          ...rightAddonProps,
+          pointerEvents: true,
+          className: autocompleteRightAddon({
+            className: rightAddonProps?.className,
+          }),
+        }}
+      />
+      <Listbox
+        aria-label={listboxLabel as string}
+        aria-labelledby={listboxLabelledBy}
+        {...getListboxProps(listboxProps)}
+        fixedTo={containerRef}
+      >
+        <AutocompleteListboxChildren
+          query={currentQuery}
+          options={availableOptions}
+          getOptionLabel={getOptionLabel}
+          getOptionProps={getOptionProps}
+          noOptionsChildren={noOptionsChildren}
+        >
+          {children}
+        </AutocompleteListboxChildren>
+      </Listbox>
+    </KeyboardMovementProvider>
+  );
+}

package/src/autocomplete/AutocompleteChip.tsx

@@ -0,0 +1,50 @@
+import { forwardRef } from "react";
+
+import { Chip } from "../chip/Chip.js";
+import { getIcon } from "../icon/config.js";
+import { autocompleteChip } from "./autocompleteStyles.js";
+import { type AutocompleteChipProps } from "./types.js";
+
+/**
+ * A small wrapper around the `Chip` that defaults the `rightAddon` to the
+ * remove icon and adds a default `aria-description`.
+ *
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @since 6.0.0
+ */
+export const AutocompleteChip = forwardRef<
+  HTMLButtonElement,
+  AutocompleteChipProps
+>(function AutocompleteChip(props, ref) {
+  const {
+    "aria-description": propAriaDescription,
+    children,
+    className,
+    removeIcon: propRemoveIcon,
+    rightAddon: propRightAddon,
+    ...remaining
+  } = props;
+
+  let rightAddon = propRightAddon;
+  let ariaDescription = propAriaDescription;
+  const removeIcon = getIcon("remove", propRemoveIcon);
+  if (typeof rightAddon === "undefined") {
+    rightAddon = removeIcon;
+  }
+
+  if (typeof ariaDescription === "undefined" && typeof children === "string") {
+    ariaDescription = `Remove "${children}"`;
+  }
+
+  return (
+    <Chip
+      {...remaining}
+      aria-description={ariaDescription}
+      ref={ref}
+      rightAddon={rightAddon}
+      className={autocompleteChip({ className })}
+    >
+      {children}
+    </Chip>
+  );
+});

package/src/autocomplete/AutocompleteCircularProgress.tsx

@@ -0,0 +1,32 @@
+import { type ReactElement } from "react";
+
+import { CircularProgress } from "../progress/CircularProgress.js";
+import { type AutocompleteCircularProgressProps } from "./types.js";
+
+/**
+ * An internal component used to handle the styling and minimal accessibility
+ * for the `CircularProgress` within the `Autocomplete`
+ *
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @internal
+ * @since 6.0.0
+ */
+export function AutocompleteCircularProgress(
+  props: AutocompleteCircularProgressProps
+): ReactElement {
+  const {
+    "aria-labelledby": ariaLabelledby,
+    "aria-label": ariaLabel = ariaLabelledby ? undefined : "Loading",
+    theme = "current-color",
+    ...remaining
+  } = props;
+
+  return (
+    <CircularProgress
+      {...remaining}
+      aria-label={ariaLabel as string}
+      aria-labelledby={ariaLabelledby}
+      theme={theme}
+    />
+  );
+}

package/src/autocomplete/AutocompleteClearButton.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { type ReactElement } from "react";
+
+import { Button } from "../button/Button.js";
+import { getIcon } from "../icon/config.js";
+import { useEnsuredId } from "../useEnsuredId.js";
+import { autocompleteClearButton } from "./autocompleteStyles.js";
+import { type AutocompleteClearButtonProps } from "./types.js";
+
+/**
+ * An internal component used for to clear the value from the `Autocomplete`.
+ *
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @internal
+ * @since 6.0.0
+ */
+export function AutocompleteClearButton(
+  props: AutocompleteClearButtonProps
+): ReactElement {
+  const {
+    id: propId,
+    className,
+    children,
+    buttonType = "icon",
+    "aria-labelledby": ariaLabelledBy,
+    "aria-label": ariaLabel = buttonType === "text" || ariaLabelledBy
+      ? undefined
+      : "Clear",
+    visibility,
+    ...remaining
+  } = props;
+  const id = useEnsuredId(propId, "autocomplete-clear");
+
+  return (
+    <Button
+      {...remaining}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      id={id}
+      className={autocompleteClearButton({ className, visibility })}
+      tabIndex={-1}
+      buttonType={buttonType}
+    >
+      {getIcon("clear", children)}
+    </Button>
+  );
+}

package/src/autocomplete/AutocompleteDropdownButton.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { type ReactElement } from "react";
+
+import { Button } from "../button/Button.js";
+import { IconRotator } from "../icon/IconRotator.js";
+import { getIcon } from "../icon/config.js";
+import { type LabelRequiredForA11y } from "../types.js";
+import { useEnsuredId } from "../useEnsuredId.js";
+import { autocompleteDropdownButton } from "./autocompleteStyles.js";
+import { type AutocompleteDropdownButtonProps } from "./types.js";
+
+/**
+ * This is a simple `Button` wrapper to be used as a dropdown button within the
+ * `Autocomplete`.
+ *
+ * @see {@link https://next.react-md.dev/components/autocomplete | Autocomplete Demos}
+ * @since 6.0.0
+ */
+export function AutocompleteDropdownButton(
+  props: LabelRequiredForA11y<AutocompleteDropdownButtonProps>
+): ReactElement {
+  const {
+    id: propId,
+    icon,
+    visible,
+    iconRotatorProps,
+    className,
+    ...remaining
+  } = props;
+
+  const id = useEnsuredId(propId, "autocomplete-dropdown");
+
+  return (
+    <Button
+      {...remaining}
+      id={id}
+      aria-expanded={visible}
+      tabIndex={-1}
+      buttonType="icon"
+      className={autocompleteDropdownButton({ className })}
+    >
+      <IconRotator {...iconRotatorProps} rotated={visible}>
+        {getIcon("dropdown", icon)}
+      </IconRotator>
+    </Button>
+  );
+}

package/src/autocomplete/AutocompleteListboxChildren.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import { type ReactElement, type ReactNode } from "react";
+
+import { useListboxContext } from "../form/ListboxProvider.js";
+import { Option } from "../form/Option.js";
+import {
+  type AutocompleteGetOptionLabel,
+  type AutocompleteGetOptionProps,
+  type AutocompleteOption,
+} from "./types.js";
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export interface AutocompleteListboxChildrenProps<
+  Option extends AutocompleteOption,
+> extends Required<AutocompleteGetOptionProps<Option>>,
+    Required<AutocompleteGetOptionLabel<Option>> {
+  query: string;
+  options: readonly Option[];
+  children: ReactNode;
+  noOptionsChildren: ReactNode;
+}
+
+/**
+ * NOTE: This was moved to a second component to improve performance so
+ * that the availableOptions aren't looped until the listbox is visible
+ *
+ * @since 6.0.0
+ * @internal
+ */
+export function AutocompleteListboxChildren<Option extends AutocompleteOption>(
+  props: AutocompleteListboxChildrenProps<Option>
+): ReactElement {
+  const {
+    children,
+    query,
+    options: availableOptions,
+    noOptionsChildren,
+    getOptionLabel,
+    getOptionProps,
+  } = props;
+  const { isOptionSelected } = useListboxContext();
+
+  return (
+    <>
+      {children}
+      {!availableOptions.length && noOptionsChildren}
+      {availableOptions.map((option, index) => {
+        const label = getOptionLabel(option);
+        const optionProps = getOptionProps({
+          index,
+          query,
+          option,
+          selected: isOptionSelected(option),
+          extractor: getOptionLabel,
+        });
+
+        return (
+          <Option key={label} value={option} {...optionProps}>
+            {optionProps?.children ?? label}
+          </Option>
+        );
+      })}
+    </>
+  );
+}