@react-md/core 1.0.0-next.15 → 1.0.0-next.17

package/src/autocomplete/useAutocomplete.ts

@@ -0,0 +1,428 @@
+"use client";
+import { useCallback, useMemo, useRef } from "react";
+import { useEditableCombobox } from "../form/useEditableCombobox.js";
+import {
+  triggerManualChangeEvent,
+  type EditableHTMLElement,
+} from "../form/utils.js";
+import { getIcon } from "../icon/iconConfig.js";
+import { useUserInteractionMode } from "../interaction/UserInteractionModeProvider.js";
+import { TRANSITION_CONFIG } from "../transition/config.js";
+import { type TransitionEnterHandler } from "../transition/types.js";
+import { useEnsuredState } from "../useEnsuredState.js";
+import {
+  defaultAutocompleteExtractor,
+  defaultAutocompleteFilter,
+  defaultAutocompleteGetOptionProps,
+  noopAutocompleteFilter,
+} from "./defaults.js";
+import {
+  type AutocompleteImplementation,
+  type AutocompleteMultiSelectImplementation,
+  type AutocompleteMultiSelectOptions,
+  type AutocompleteOption,
+  type AutocompleteOptions,
+  type AutocompleteSingleSelectImplementation,
+  type AutocompleteSingleSelectOptions,
+} from "./types.js";
+import {
+  enforceSelectedValue,
+  getDefaultQuery,
+  getDefaultValue,
+  isMultipleValues,
+} from "./utils.js";
+
+const noop = (): void => {
+  // do nothing
+};
+
+/**
+ * This is the single select autocomplete implementation.
+ *
+ * @since 6.0.0
+ */
+export function useAutocomplete<
+  Option extends AutocompleteOption,
+  ComboboxEl extends EditableHTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+>(
+  options: AutocompleteSingleSelectOptions<Option, ComboboxEl, PopupEl>
+): AutocompleteSingleSelectImplementation<Option, ComboboxEl, PopupEl>;
+/**
+ * This is the multiselect autocomplete implementation.
+ *
+ * @since 6.0.0
+ */
+export function useAutocomplete<
+  Option extends AutocompleteOption,
+  ComboboxEl extends EditableHTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+>(
+  options: AutocompleteMultiSelectOptions<Option, ComboboxEl, PopupEl>
+): AutocompleteMultiSelectImplementation<Option, ComboboxEl, PopupEl>;
+/**
+ * This is an internal override implementation where the types are less strict
+ * so it can be used with the `Autocomplete` component.
+ *
+ * @since 6.0.0
+ * @internal
+ */
+export function useAutocomplete<
+  Option extends AutocompleteOption,
+  ComboboxEl extends EditableHTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+>(
+  options: AutocompleteOptions<Option, ComboboxEl, PopupEl>
+): AutocompleteImplementation<Option, ComboboxEl, PopupEl>;
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function useAutocomplete<
+  Option extends AutocompleteOption,
+  ComboboxEl extends EditableHTMLElement = HTMLInputElement,
+  PopupEl extends HTMLElement = HTMLElement,
+>(
+  options: AutocompleteOptions<Option, ComboboxEl, PopupEl>
+): AutocompleteImplementation<Option, ComboboxEl, PopupEl> {
+  const {
+    value: propValue,
+    setValue: propSetValue,
+    defaultValue,
+    onValueChange = noop,
+    query: propQuery,
+    setQuery: propSetQuery,
+    defaultQuery,
+    options: values,
+    getOptionLabel = defaultAutocompleteExtractor,
+    getOptionProps = defaultAutocompleteGetOptionProps,
+    onBlur = noop,
+    onChange = noop,
+    onOpen = noop,
+    filter = defaultAutocompleteFilter,
+    filterSelected,
+    allowAnyValue = filter === noopAutocompleteFilter,
+    multiselect: propMultiselect,
+    checkboxes,
+    selectedIcon: propSelectedIcon,
+    unselectedIcon: propUnselectedIcon,
+    selectedIconAfter,
+    disableSelectedIcon: propDisableSelectedIcon,
+    updateQueryOnSelect: propUpdateQueryOnSelect,
+    disableCloseOnSelect: propDisableCloseOnSelect,
+    ...comboboxOptions
+  } = options;
+
+  const mode = useUserInteractionMode();
+  const [value, setValueState] = useEnsuredState({
+    value: propValue,
+    setValue: propSetValue,
+    defaultValue: getDefaultValue({
+      query: propQuery,
+      filter,
+      multiselect: propMultiselect,
+      defaultQuery,
+      defaultValue,
+      options: values,
+      getOptionLabel,
+    }),
+  });
+  const multiselect =
+    propMultiselect ??
+    (!!value && typeof value === "object" && "length" in value);
+  let updateQueryOnSelect = propUpdateQueryOnSelect;
+  if (typeof propUpdateQueryOnSelect === "undefined") {
+    updateQueryOnSelect = multiselect ? "clear" : "selected";
+  }
+
+  const disableCloseOnSelect =
+    propDisableCloseOnSelect ?? (multiselect && checkboxes);
+
+  const [query, setQuery] = useEnsuredState({
+    value: propQuery,
+    setValue: propSetQuery,
+    defaultValue: getDefaultQuery({
+      value,
+      getOptionLabel,
+      defaultQuery,
+    }),
+  });
+  const setValue = useCallback(
+    (value: Option | null | readonly Option[]) => {
+      onValueChange(value);
+      setValueState(value);
+    },
+    [onValueChange, setValueState]
+  );
+
+  const combobox = useEditableCombobox<ComboboxEl, PopupEl>({
+    ...comboboxOptions,
+    multiselect,
+  });
+  const {
+    visible,
+    setVisible,
+    popupRef,
+    comboboxRef,
+    comboboxProps,
+    getMenuProps,
+  } = combobox;
+
+  // These refs are used to make it so that the options are not filtered until
+  // the user types a new query while the listbox is visible. The filtered
+  // options will be "cached" while:
+  // - the listbox is closing
+  // - the listbox is opening and:
+  //   - the user has not typed at least one letter
+  //   - the options have not changed
+  const entered = useRef(visible);
+  const initialQuery = useRef("");
+  const prevAvailableOptions = useRef<readonly Option[] | null>(null);
+  const isQueryChange =
+    query && query !== initialQuery.current && entered.current;
+
+  let availableOptions = prevAvailableOptions.current || values;
+  if (
+    isQueryChange &&
+    filter !== noopAutocompleteFilter &&
+    !prevAvailableOptions.current
+  ) {
+    initialQuery.current = "";
+    availableOptions = filter({
+      list: values,
+      query,
+      extractor: getOptionLabel,
+    });
+  }
+
+  // This is probably overkill, but `filterSelected` will create a quick-lookup
+  // for all the selected values in a `Set` since it is much faster than
+  // `Array.includes()`. The lookup will only be re-created whenever the `value`
+  // changes or is uninitialized to prevent it being created each render as
+  // well.
+  //
+  // These optimizations only start mattering when there are around 5000 items
+  // selected...
+  const selectedOptions = useMemo(() => {
+    if (!filterSelected) {
+      return null;
+    }
+
+    let optionList: readonly Option[] = [];
+    if (isMultipleValues(value)) {
+      optionList = value;
+    } else if (value) {
+      optionList = [value];
+    }
+
+    return new Set(optionList);
+  }, [filterSelected, value]);
+
+  if (filterSelected && selectedOptions?.size) {
+    availableOptions = availableOptions.filter(
+      (option) => !selectedOptions.has(option)
+    );
+  }
+
+  return {
+    ...combobox,
+    value,
+    setValue,
+    query,
+    setQuery,
+    availableOptions,
+    multiselect,
+    comboboxProps: {
+      ...comboboxProps,
+      "aria-autocomplete": "list",
+      value: query,
+      onKeyDown(event) {
+        comboboxProps.onKeyDown(event);
+        if (!visible && event.key === "Escape") {
+          setQuery("");
+        }
+      },
+      onBlur(event) {
+        onBlur(event);
+
+        if (allowAnyValue) {
+          return;
+        }
+
+        enforceSelectedValue({
+          value,
+          visible,
+          popupRef,
+          container: event.currentTarget.parentElement,
+          comboboxRef,
+          getOptionLabel,
+          availableOptions,
+          prevAvailableOptions,
+        });
+      },
+      onFocus(event) {
+        comboboxProps.onFocus(event);
+        event.currentTarget.select();
+      },
+      onChange(event) {
+        onChange(event);
+
+        const { value } = event.currentTarget;
+        setQuery(value);
+        if (!value && !multiselect) {
+          setValue(null);
+        }
+      },
+    },
+    getListboxProps(overrides) {
+      const {
+        ref,
+        onEnter,
+        onEntered,
+        onExited,
+        disableTransition,
+        ...listboxProps
+      } = getMenuProps(overrides);
+
+      const isTransitionCompleteSkipped =
+        !disableTransition && !TRANSITION_CONFIG.disabled;
+
+      const handleEntering =
+        (callback: TransitionEnterHandler = noop, skipped: boolean) =>
+        (appearing: boolean) => {
+          callback(appearing);
+
+          if (skipped) {
+            return;
+          }
+
+          onOpen();
+
+          // when the listbox is opened, need to flag the entered state to show
+          // that new `query` values should be accepted. Also store the initial
+          // query.
+          entered.current = true;
+          initialQuery.current = query;
+        };
+
+      let selectedIcon = propSelectedIcon;
+      let unselectedIcon = propUnselectedIcon;
+      let disableSelectedIcon = propDisableSelectedIcon;
+      if (multiselect && checkboxes) {
+        if (typeof selectedIcon === "undefined") {
+          selectedIcon = getIcon("checkboxChecked");
+        }
+        if (typeof unselectedIcon === "undefined") {
+          unselectedIcon = getIcon("checkbox");
+        }
+      } else if (typeof disableSelectedIcon === "undefined") {
+        disableSelectedIcon = true;
+      }
+
+      return {
+        selectedIcon,
+        unselectedIcon,
+        selectedIconAfter,
+        disableSelectedIcon,
+        ...listboxProps,
+        disableTransition,
+        onRequestClose() {
+          // Make it so clicking on the text field, clear button, dropdown
+          // button, etc does not close the listbox
+          if (
+            mode !== "keyboard" &&
+            comboboxRef.current?.parentElement?.contains(document.activeElement)
+          ) {
+            return;
+          }
+
+          listboxProps.onRequestClose();
+        },
+        nodeRef: ref,
+        value,
+        setValue(option) {
+          if (!disableCloseOnSelect) {
+            // this makes it so that the options are not filtered again while the
+            // listbox is closing after selecting a value
+            prevAvailableOptions.current = availableOptions;
+          }
+
+          if (value && typeof value === "object" && "length" in value) {
+            const nextValue = [...value];
+            const i = value.indexOf(option);
+            if (i === -1) {
+              nextValue.push(option);
+            } else {
+              nextValue.splice(i, 1);
+            }
+
+            setValue(nextValue);
+          } else {
+            setValue(option);
+          }
+
+          if (updateQueryOnSelect === "as-is") {
+            return;
+          }
+
+          const nextQuery =
+            updateQueryOnSelect === "clear" ? "" : getOptionLabel(option);
+          triggerManualChangeEvent(comboboxRef.current, nextQuery);
+        },
+        onEnter: handleEntering(onEnter, false),
+        onEntered: handleEntering(onEntered, isTransitionCompleteSkipped),
+        onExited() {
+          onExited();
+
+          // once the listbox has exited, reset any cached states so the next
+          // time the listbox is opened the filtering behaves the same
+          entered.current = false;
+          prevAvailableOptions.current = null;
+        },
+      };
+    },
+    getOptionLabel,
+    getOptionProps(options) {
+      const overrides = getOptionProps(options);
+
+      return {
+        ...overrides,
+        onClick: (event) => {
+          overrides?.onClick?.(event);
+          if (disableCloseOnSelect) {
+            event.stopPropagation();
+          }
+        },
+      };
+    },
+    getClearButtonProps(overrides) {
+      return {
+        ...overrides,
+        onClick(event) {
+          overrides?.onClick?.(event);
+          comboboxRef.current?.focus();
+
+          if (!multiselect) {
+            setValue(null);
+          }
+          triggerManualChangeEvent(comboboxRef.current, "");
+        },
+      };
+    },
+    getDropdownButtonProps(overrides) {
+      return {
+        "aria-controls": comboboxProps.id,
+        visible,
+        ...overrides,
+        onClick(event) {
+          overrides?.onClick?.(event);
+          comboboxRef.current?.focus();
+          if (visible) {
+            prevAvailableOptions.current = availableOptions;
+          }
+          setVisible((prev) => !prev);
+        },
+      };
+    },
+  };
+}

package/src/autocomplete/utils.ts

@@ -0,0 +1,211 @@
+import { type RefObject } from "react";
+import {
+  type EditableHTMLElement,
+  triggerManualChangeEvent,
+} from "../form/utils.js";
+import { type NonNullMutableRef, type UseStateInitializer } from "../types.js";
+import { noopAutocompleteFilter } from "./defaults.js";
+import {
+  type AutocompleteFilterOptions,
+  type AutocompleteGetOptionLabel,
+  type AutocompleteOption,
+} from "./types.js";
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export interface GetDefaultValueOptions<Option extends AutocompleteOption> {
+  query: string | undefined;
+  multiselect?: boolean;
+  defaultQuery: UseStateInitializer<string> | undefined;
+  defaultValue:
+    | UseStateInitializer<Option | null | readonly Option[]>
+    | undefined;
+  options: readonly Option[];
+  getOptionLabel: AutocompleteGetOptionLabel<Option>;
+  filter: (options: AutocompleteFilterOptions<Option>) => readonly Option[];
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function getDefaultValue<Option extends AutocompleteOption>(
+  options: GetDefaultValueOptions<Option>
+): UseStateInitializer<Option | null | readonly Option[]> {
+  const {
+    query,
+    filter,
+    multiselect,
+    defaultQuery,
+    defaultValue,
+    options: values,
+    getOptionLabel,
+  } = options;
+
+  if (typeof defaultValue !== "undefined") {
+    return defaultValue;
+  }
+
+  // do not support determining the default value for a multiselect
+  // autocomplete if only a query was provided.
+  if (multiselect) {
+    return [];
+  }
+
+  // do not support a default value out of the box for this case
+  if (filter === noopAutocompleteFilter) {
+    return null;
+  }
+
+  return () => {
+    let q = "";
+    if (query) {
+      q = query;
+    } else if (defaultQuery) {
+      q = defaultQuery instanceof Function ? defaultQuery() : defaultQuery;
+    }
+
+    if (!q) {
+      return null;
+    }
+
+    const filtered = filter({
+      list: values,
+      query: q,
+      extractor: getOptionLabel,
+    });
+
+    return filtered[0] ?? null;
+  };
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+interface GetDefaultQueryOptions<Option extends AutocompleteOption> {
+  value: Option | null | readonly Option[];
+  getOptionLabel: AutocompleteGetOptionLabel<Option>;
+  defaultQuery?: UseStateInitializer<string>;
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function getDefaultQuery<Option extends AutocompleteOption>(
+  options: GetDefaultQueryOptions<Option>
+): UseStateInitializer<string> {
+  const { value, getOptionLabel, defaultQuery } = options;
+
+  if (defaultQuery) {
+    return defaultQuery;
+  }
+
+  return () => {
+    if (typeof value === "string") {
+      return value;
+    }
+
+    if (value && typeof value === "object" && !("length" in value)) {
+      return getOptionLabel(value);
+    }
+
+    return "";
+  };
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export interface EnforceSelectedValueOptions<
+  Option extends AutocompleteOption,
+> {
+  value: Option | readonly Option[] | null;
+  visible: boolean;
+  container: HTMLElement | null;
+  popupRef: RefObject<HTMLElement>;
+  comboboxRef: RefObject<EditableHTMLElement>;
+  getOptionLabel: AutocompleteGetOptionLabel<Option>;
+  availableOptions: readonly Option[];
+  prevAvailableOptions: NonNullMutableRef<readonly Option[] | null>;
+}
+
+/**
+ * This enforces that if the user clicks away, touches somewhere else on the
+ * page, tabs to the next element, or focuses another element programmatically
+ * the autocomplete will set the `value` back to the previous selected value if
+ * there was one. i.e.
+ *
+ * Case 1:
+ * - User selects "Apple"
+ * - User hits backspace twice. Input displays "App"
+ * - User clicks somewhere else on the page
+ * - Input now displays "Apple" again
+ *
+ * Case 2:
+ * - User selects "Apple"
+ * - User clears the input
+ * - User types "app"
+ * - User clicks somewhere else on the page
+ * - Input now displays "" and the value is set to `null`
+ *
+ * NOTE: This mutates the {@link EnforceSelectedValueOptions.prevAvailableOptions}
+ *
+ * @since 6.0.0
+ * @internal
+ */
+export function enforceSelectedValue<Option extends AutocompleteOption>(
+  options: EnforceSelectedValueOptions<Option>
+): void {
+  const {
+    value,
+    visible,
+    container,
+    popupRef,
+    comboboxRef,
+    getOptionLabel,
+    availableOptions,
+    prevAvailableOptions,
+  } = options;
+
+  if (!container) {
+    return;
+  }
+
+  window.requestAnimationFrame(() => {
+    if (
+      container.contains(document.activeElement) ||
+      popupRef.current?.contains(document.activeElement)
+    ) {
+      return;
+    }
+
+    if (visible) {
+      // this makes it so that the options are not filtered again while closing
+      prevAvailableOptions.current = availableOptions;
+    }
+
+    let label = "";
+    if (typeof value === "string") {
+      label = value;
+    } else if (typeof value === "object" && value && !("length" in value)) {
+      label = getOptionLabel(value);
+    }
+
+    triggerManualChangeEvent(comboboxRef.current, label);
+  });
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function isMultipleValues<Option extends AutocompleteOption>(
+  value: Option | null | readonly Option[]
+): value is readonly Option[] {
+  return !!value && typeof value === "object" && "length" in value;
+}

package/src/avatar/Avatar.tsx

@@ -80,8 +80,6 @@ export interface AvatarProps
 }
 
 /**
- * **Server Component**
- *
  * An `Avatar` is generally used to represent objects or people within your app.
  * The avatar can consist of an image, an icon, or some text to display. When
  * the avatar is not an image, different themes can be applied to make the

package/src/badge/Badge.tsx

@@ -1,54 +1,14 @@
-import { cnb } from "cnbuilder";
 import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
-import { cssUtils, type BackgroundColor } from "../cssUtils.js";
-import { bem } from "../utils/bem.js";
-
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-badge-size"?: string | number;
-    "--rmd-badge-offset"?: string | number;
-    "--rmd-badge-offset-top"?: string | number;
-    "--rmd-badge-offset-right"?: string | number;
-  }
-}
-
-const styles = bem("rmd-badge");
-
-/**
- * @since 6.0.0 Renamed `"default"` to `"greyscale"` and added all
- * theme colors.
- */
-export type BadgeTheme = BackgroundColor | "greyscale" | "clear";
-
-export interface BadgeClassNameOptions {
-  className?: string;
-
-  /** @defaultValue `""greyscale` */
-  theme?: BadgeTheme;
-}
-
-export function badge(options: BadgeClassNameOptions = {}): string {
-  const { className, theme = "greyscale" } = options;
-  const greyscale = theme === "greyscale";
-  const clear = theme === "clear";
-
-  return cnb(
-    styles({ greyscale }),
-    cssUtils({ backgroundColor: !clear && !greyscale ? theme : undefined }),
-    className
-  );
-}
+import { badge, type BadgeTheme } from "./styles.js";
 
 export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
-  /** @defaultValue `""greyscale` */
+  /** @defaultValue `"greyscale"` */
   theme?: BadgeTheme;
 
   children: ReactNode;
 }
 
 /**
- * **Server Component**
- *
  * @example Simple Example
  * ```tsx
  * import type { ReactElement } from "react";