@react-md/core 1.0.0-next.16 → 1.0.0-next.18

package/src/autocomplete/Autocomplete.tsx

@@ -1,258 +1,249 @@
 "use client";
-import {
-  useEffect,
-  type AriaAttributes,
-  type ReactElement,
-  type Ref,
-} from "react";
-import { TextField, type TextFieldProps } from "../form/TextField.js";
-import { type ConfigurableComboboxMenuProps } from "../form/useCombobox.js";
-import { useEditableCombobox } from "../form/useEditableCombobox.js";
-import { Menu } from "../menu/Menu.js";
-import { type KeyboardMovementFocusChangeEventHandler } from "../movement/types.js";
+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 {
-  type PropsWithRef,
-  type TextExtractor,
-  type UseStateSetter,
-} from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
-import { useEnsuredState } from "../useEnsuredState.js";
-import {
-  AutocompleteCircularProgress,
-  type AutocompleteCircularProgressProps,
-} from "./AutocompleteCircularProgress.js";
-import {
-  AutocompleteDropdownButton,
-  type ConfigurableAutocompleteDropdownButtonProps,
-} from "./AutocompleteDropdownButton.js";
-import { FilterAutocompleteOptions } from "./FilterAutocompleteOptions.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 {
-  type AutocompleteMenuLabel,
-  type AutocompleteOptionsProps,
+  defaultAutocompleteFilter,
+  noopAutocompleteFilter,
+} from "./defaults.js";
+import {
+  type AutocompleteMultiSelectProps,
+  type AutocompleteOption,
+  type AutocompleteProps,
+  type AutocompleteSingleSelectProps,
 } from "./types.js";
+import { useAutocomplete } from "./useAutocomplete.js";
 
-const noop = (): void => {
-  // do nothing
-};
+const noop = (): undefined => undefined;
 
 /**
+ * This is the single select autocomplete implementation.
+ *
  * @since 6.0.0
  */
-export interface AutocompleteProps<T>
-  extends Omit<TextFieldProps, "value" | "defaultValue">,
-    AutocompleteOptionsProps<T> {
-  /** @defaultValue `"list"` */
-  "aria-autocomplete"?: AriaAttributes["aria-autocomplete"];
-  inputRef?: Ref<HTMLInputElement>;
-  value?: string;
-  defaultValue?: string;
-
-  /**
-   * An `aria-label` to pass to the `Menu` component that describes the list of
-   * {@link options}. Either this or the {@link menuLabelledBy} are required for
-   * accessibility.
-   */
-  menuLabel?: string;
-
-  /**
-   * An `aria-labelledby` to pass to the `Menu` component that describes the
-   * list of {@link options}. Either this or the {@link menuLabel} are required
-   * for accessibility.
-   */
-  menuLabelledBy?: string;
-
-  /**
-   * Any additional props that should be passed to the `Menu` component.
-   */
-  menuProps?: PropsWithRef<
-    ConfigurableComboboxMenuProps & { id?: string },
-    HTMLDivElement
-  >;
-
-  /**
-   * This prop should only be used when `aria-autocomplete` is set to
-   * `"inline"` or `"both"`.
-   */
-  onFocusChange?: KeyboardMovementFocusChangeEventHandler;
-
-  /**
-   * This can be used to add any custom styling, change the icon, change the
-   * label, etc for the dropdown button.
-   *
-   * @example Simple Example
-   * ```tsx
-   * dropdownButtonProps={{
-   *   "aria-label": "Open",
-   *   className: styles.dropdownButton,
-   *   icon: <MyCustomDropdownIcon />,
-   * }}
-   * ```
-   */
-  dropdownButtonProps?: ConfigurableAutocompleteDropdownButtonProps;
-
-  /**
-   * Set this to `true` to remove the {@link DropdownButton} from being rendered
-   * after the input element.
-   *
-   * @defaultValue `false`
-   */
-  disableDropdownButton?: boolean;
-
-  /**
-   * Set this to `true` to disable a `<CircularProgress />` after the input and
-   * before the `<DropdownButton />`.
-   *
-   * @defaultValue `false`
-   */
-  loading?: boolean;
-
-  /**
-   * @defaultValue `{ "aria-label": "Loading", ...loadingProps }`
-   */
-  loadingProps?: AutocompleteCircularProgressProps;
-}
-
+export function Autocomplete<Option extends AutocompleteOption>(
+  props: AutocompleteSingleSelectProps<Option>
+): ReactElement;
 /**
+ * This is the multiselect autocomplete implementation.
+ *
  * @since 6.0.0
  */
-export function Autocomplete<T extends string | { label: string }>(
-  props: AutocompleteMenuLabel<Omit<AutocompleteProps<T>, "extractor">>
+export function Autocomplete<Option extends AutocompleteOption>(
+  props: AutocompleteMultiSelectProps<Option>
 ): ReactElement;
 /**
  * @since 6.0.0
+ * @internal
  */
-export function Autocomplete<T>(
-  props: AutocompleteMenuLabel<
-    AutocompleteProps<T> & { extractor: TextExtractor<T> }
-  >
-): ReactElement;
-export function Autocomplete<T>(
-  props: AutocompleteMenuLabel<AutocompleteProps<T>>
+export function Autocomplete<Option extends AutocompleteOption>(
+  props: AutocompleteProps<Option>
 ): ReactElement {
   const {
     id: propId,
-    value: propValue,
-    defaultValue = "",
-    onClick,
+    onBlur,
     onFocus,
+    onClick,
+    onChange,
     onKeyDown,
-    onChange = noop,
-    onFocusChange,
+    onOpen,
+    type,
     className,
-    options,
-    children,
     inputRef,
-    extractor,
-    onAutocomplete = noop,
-    getOptionProps,
-    clearOnAutocomplete,
-    menuProps,
-    menuLabel,
-    menuLabelledBy,
-    containerProps,
-    filter,
-    whitespace,
-    disableFilter,
-    noOptionsChildren,
-    dropdownButtonProps,
-    disableDropdownButton,
+    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,
+    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 { form } = props;
   const id = useEnsuredId(propId, "autocomplete");
-  const menuId = useEnsuredId(menuProps?.id, "autocomplete-listbox");
-
-  const [query, setQuery] = useEnsuredState<string, UseStateSetter<string>>({
-    value: propValue,
-    setValue: typeof propValue === "string" ? noop : undefined,
-    defaultValue,
-  });
-
+  const menuId = useEnsuredId(listboxProps?.id, "autocomplete-listbox");
   const {
-    visible,
-    setVisible,
-    getMenuProps,
-    comboboxRef,
+    query: currentQuery,
+    value: currentValue,
+    setValue: currentSetValue,
+    multiselect,
+    comboboxRef: inputNodeRef,
     comboboxProps,
     movementContext,
-  } = useEditableCombobox({
+    availableOptions,
+    getOptionLabel,
+    getOptionProps,
+    getListboxProps,
+    getClearButtonProps,
+    getDropdownButtonProps,
+  } = useAutocomplete({
     form,
-    onClick,
+    onBlur,
     onFocus,
+    onClick,
+    onChange,
     onKeyDown,
-    onFocusChange,
+    onOpen,
+    disabled,
+    filter,
+    filterSelected,
     popupId: menuId,
-    popupRef: menuProps?.ref,
+    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 [containerNodeRef, containerRef] = useEnsuredRef(containerProps?.ref);
-  useEffect(() => {
-    const input = comboboxRef.current;
-    if (!input || document.activeElement !== input) {
-      return;
-    }
+  const [containerRef, containerRefCallback] = useEnsuredRef(
+    containerProps?.ref
+  );
 
-    const target = input.value.length;
-    input.setSelectionRange(target, target);
-  }, [comboboxRef, loading]);
+  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
-        aria-autocomplete="list"
         {...remaining}
-        value={query}
         {...comboboxProps}
         containerProps={{
           ...containerProps,
-          ref: containerRef,
+          ref: containerRefCallback,
+          onClick: (event) => {
+            containerProps?.onClick?.(event);
+            inputNodeRef.current?.focus();
+          },
         }}
         className={autocomplete({
           className,
           loading,
+          inlineChips,
+          disableClearButton,
           disableDropdownButton,
         })}
-        onChange={(event) => {
-          onChange(event);
-          setQuery(event.currentTarget.value);
-        }}
-        onKeyDown={(event) => {
-          comboboxProps.onKeyDown(event);
-          if (!visible && event.key === "Escape") {
-            onAutocomplete(null);
-          }
-        }}
-        onFocus={(event) => {
-          comboboxProps.onFocus(event);
-          event.currentTarget.setSelectionRange(
-            0,
-            event.currentTarget.value.length
-          );
+        labelProps={{
+          ...labelProps,
+          floatingActive,
         }}
+        leftAddon={leftAddon}
+        disableLeftAddonStyles={disableLeftAddonStyles}
         rightAddon={
           <>
             {rightAddon}
             {loading && <AutocompleteCircularProgress {...loadingProps} />}
+            {!disableClearButton && !!currentQuery && (
+              <AutocompleteClearButton
+                {...clearButtonProps}
+                {...getClearButtonProps(clearButtonProps)}
+              />
+            )}
             {!disableDropdownButton && (
               <AutocompleteDropdownButton
-                aria-label={menuLabel}
-                aria-labelledby={menuLabelledBy}
-                aria-controls={comboboxProps.id}
-                {...dropdownButtonProps}
-                visible={visible}
-                onClick={() => {
-                  comboboxRef.current?.focus();
-                  setVisible((prev) => !prev);
-                }}
+                aria-label={listboxLabel as string}
+                aria-labelledby={listboxLabelledBy}
+                {...getDropdownButtonProps(dropdownButtonProps)}
               />
             )}
           </>
@@ -265,30 +256,22 @@ export function Autocomplete<T>(
           }),
         }}
       />
-      <Menu
-        aria-label={menuLabel as string}
-        aria-labelledby={menuLabelledBy}
-        {...getMenuProps(menuProps)}
-        // since the `afterInputChildren` is not included in the `comboboxRef`'s
-        // width, the menu will no longer be equal width without changing the
-        // fixedTo node to the container
-        fixedTo={containerNodeRef}
+      <Listbox
+        aria-label={listboxLabel as string}
+        aria-labelledby={listboxLabelledBy}
+        {...getListboxProps(listboxProps)}
+        fixedTo={containerRef}
       >
-        {children}
-        <FilterAutocompleteOptions
-          query={query}
-          filter={filter}
-          options={options}
-          noOptionsChildren={noOptionsChildren}
-          extractor={extractor}
-          whitespace={whitespace}
-          comboboxRef={comboboxRef}
-          disableFilter={disableFilter || props["aria-autocomplete"] === "none"}
+        <AutocompleteListboxChildren
+          query={currentQuery}
+          options={availableOptions}
+          getOptionLabel={getOptionLabel}
           getOptionProps={getOptionProps}
-          onAutocomplete={onAutocomplete}
-          clearOnAutocomplete={clearOnAutocomplete}
-        />
-      </Menu>
+          noOptionsChildren={noOptionsChildren}
+        >
+          {children}
+        </AutocompleteListboxChildren>
+      </Listbox>
     </KeyboardMovementProvider>
   );
 }

package/src/autocomplete/AutocompleteChip.tsx

@@ -0,0 +1,48 @@
+import { forwardRef } from "react";
+import { Chip } from "../chip/Chip.js";
+import { getIcon } from "../icon/iconConfig.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`.
+ *
+ * @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

@@ -1,23 +1,12 @@
 import { type ReactElement } from "react";
-import {
-  CircularProgress,
-  type CircularProgressProps,
-} from "../progress/CircularProgress.js";
-import { type ProgressTheme } from "../progress/types.js";
-
-/**
- * @since 6.0.0
- */
-export interface AutocompleteCircularProgressProps
-  extends CircularProgressProps {
-  /** @defaultValue `"Loading"` */
-  "aria-label"?: string;
-
-  /** @defaultValue `"current-color"` */
-  theme?: ProgressTheme;
-}
+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`
+ *
+ * @internal
  * @since 6.0.0
  */
 export function AutocompleteCircularProgress(

package/src/autocomplete/AutocompleteClearButton.tsx

@@ -0,0 +1,44 @@
+"use client";
+import { type ReactElement } from "react";
+import { Button } from "../button/Button.js";
+import { getIcon } from "../icon/iconConfig.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`.
+ *
+ * @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",
+    ...remaining
+  } = props;
+  const id = useEnsuredId(propId, "autocomplete-clear");
+
+  return (
+    <Button
+      {...remaining}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      id={id}
+      className={autocompleteClearButton({ className })}
+      tabIndex={-1}
+      buttonType={buttonType}
+    >
+      {getIcon("clear", children)}
+    </Button>
+  );
+}

package/src/autocomplete/AutocompleteDropdownButton.tsx

@@ -1,41 +1,12 @@
 "use client";
-import {
-  type MouseEventHandler,
-  type ReactElement,
-  type ReactNode,
-} from "react";
-import { Button, type ButtonProps } from "../button/Button.js";
-import { IconRotator, type IconRotatorProps } from "../icon/IconRotator.js";
+import { type ReactElement } from "react";
+import { Button } from "../button/Button.js";
+import { IconRotator } from "../icon/IconRotator.js";
 import { getIcon } from "../icon/iconConfig.js";
+import { type LabelRequiredForA11y } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
-
-/**
- * @since 6.0.0
- */
-export interface ConfigurableAutocompleteDropdownButtonProps
-  extends ButtonProps {
-  /** @defaultValue `AutocompleteProps.menuLabel` */
-  "aria-label"?: string;
-  /** @defaultValue `AutocompleteProps.menuLabelledby` */
-  "aria-labelledby"?: string;
-
-  /** @defaultValue `"autocomplete-dropdown-" + useId()` */
-  id?: string;
-
-  /** @defaultValue `getIcon("dropdown")` */
-  icon?: ReactNode;
-  iconRotatorProps?: Omit<IconRotatorProps, "rotated">;
-}
-
-/**
- * @since 6.0.0
- */
-export interface AutocompleteDropdownButtonProps
-  extends ConfigurableAutocompleteDropdownButtonProps {
-  "aria-controls": string;
-  onClick: MouseEventHandler<HTMLButtonElement>;
-  visible: boolean;
-}
+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
@@ -44,9 +15,16 @@ export interface AutocompleteDropdownButtonProps
  * @since 6.0.0
  */
 export function AutocompleteDropdownButton(
-  props: AutocompleteDropdownButtonProps
+  props: LabelRequiredForA11y<AutocompleteDropdownButtonProps>
 ): ReactElement {
-  const { id: propId, icon, visible, iconRotatorProps, ...remaining } = props;
+  const {
+    id: propId,
+    icon,
+    visible,
+    iconRotatorProps,
+    className,
+    ...remaining
+  } = props;
 
   const id = useEnsuredId(propId, "autocomplete-dropdown");
 
@@ -57,6 +35,7 @@ export function AutocompleteDropdownButton(
       aria-expanded={visible}
       tabIndex={-1}
       buttonType="icon"
+      className={autocompleteDropdownButton({ className })}
     >
       <IconRotator {...iconRotatorProps} rotated={visible}>
         {getIcon("dropdown", icon)}