@react-md/core 1.0.0-next.1 → 1.0.0-next.11

package/src/form/Select.tsx

@@ -1,58 +1,48 @@
 "use client";
 import { cnb } from "cnbuilder";
 import {
-  useEffect,
   useMemo,
   useRef,
   useState,
   type ChangeEvent,
+  type HTMLAttributes,
+  type InputHTMLAttributes,
   type ReactElement,
   type ReactNode,
   type Ref,
 } from "react";
+import { type BoxProps } from "../box/Box.js";
 import { IconRotator } from "../icon/IconRotator.js";
 import { getIcon } from "../icon/iconConfig.js";
 import { Menu, type MenuProps } from "../menu/Menu.js";
-import { findMatchIndex } from "../movement/findMatchIndex.js";
+import { KeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
 import {
-  KeyboardMovementProvider,
-  useKeyboardMovementProvider,
-} from "../movement/useKeyboardMovementProvider.js";
-import { isSearchableEvent } from "../movement/utils.js";
-import { BELOW_CENTER_ANCHOR } from "../positioning/constants.js";
-import {
-  type TransitionEnterHandler,
-  type TransitionExitHandler,
-} from "../transition/types.js";
+  type LabelA11y,
+  type PropsWithRef,
+  type RequireAtLeastOne,
+} from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
-import { useToggle } from "../useToggle.js";
-import { loop } from "../utils/loop.js";
-import { SelectValue } from "./SelectValue.js";
-import { TextField, type TextFieldProps } from "./TextField.js";
+import { label as labelStyles } from "./Label.js";
+import { SelectedOption } from "./SelectedOption.js";
+import {
+  TextFieldContainer,
+  type TextFieldContainerProps,
+} from "./TextFieldContainer.js";
 import { getFormConfig } from "./formConfig.js";
 import { select } from "./selectStyles.js";
 import { extractOptionsFromChildren } from "./selectUtils.js";
-import {
-  type FormFieldOptions,
-  type UserAgentAutoCompleteProps,
-} from "./types.js";
-import { ListboxProvider } from "./useListboxProvider.js";
-import { triggerManualChangeEvent, tryToSubmitRelatedForm } from "./utils.js";
+import { textField } from "./textFieldStyles.js";
+import { type UserAgentAutocompleteProps } from "./types.js";
+import { useFormReset } from "./useFormReset.js";
+import { ListboxProvider, type ListboxContext } from "./useListboxProvider.js";
+import { useSelectCombobox } from "./useSelectCombobox.js";
 
 const EMPTY_STRING = "" as const;
 const noop = (): void => {
   // do nothing
 };
 
-const getNonDisabledOptions = (
-  container: HTMLElement
-): readonly HTMLElement[] => [
-  ...container.querySelectorAll<HTMLLIElement>(
-    '[role="option"]:not([aria-disabled])'
-  ),
-];
-
 /**
  * This is a convenience type for casting the `event.currentTarget.value` of a
  * `Select`'s change event to be union of available values.
@@ -103,16 +93,19 @@ export type SelectChangeEvent<Value extends string> =
  * @remarks \@since 6.0.0 Rewritten with a new API.
  */
 export interface SelectProps<Value extends string>
-  extends Omit<TextFieldProps, "placeholder" | "type" | "onChange">,
-    UserAgentAutoCompleteProps,
-    FormFieldOptions {
+  extends Omit<TextFieldContainerProps, "label">,
+    Pick<InputHTMLAttributes<HTMLInputElement>, "form" | "required">,
+    UserAgentAutocompleteProps {
   /**
-   * An optional ref to pass to the hidden `<input type="text" />` element that
-   * stores the current value. This is really only useful if you'd like to keep
-   * this component uncontrolled and access the value through
-   * `inputRef.current.value`.
+   * @defaultValue `"select-" + useId()`
    */
-  inputRef?: Ref<HTMLInputElement>;
+  id?: string;
+
+  /**
+   * Optional placeholder text or element to render while no options have been
+   * selected.
+   */
+  placeholder?: ReactNode;
 
   /**
    * Set this to a custom dropdown icon or `null` to not render a dropdown icon.
@@ -138,6 +131,30 @@ export interface SelectProps<Value extends string>
   /** @see {@link SelectChangeEvent} */
   onChange?(event: SelectChangeEvent<Value>): void;
 
+  /**
+   * An optional floating label to display like other form fields.
+   */
+  label?: ReactNode;
+
+  /**
+   * Optional props to pass to the `<span>` that surrounds the {@link label}
+   */
+  labelProps?: PropsWithRef<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>;
+
+  /**
+   * An optional ref to pass to the hidden `<input type="text" />` element that
+   * stores the current value. This is really only useful if you'd like to keep
+   * this component uncontrolled and access the value through
+   * `inputRef.current.value`.
+   */
+  inputRef?: Ref<HTMLInputElement>;
+  inputProps?: InputHTMLAttributes<HTMLInputElement>;
+
+  /**
+   * A ref for the container `<div>` element.
+   */
+  containerRef?: Ref<HTMLDivElement>;
+
   /**
    * Any additional props to provide to the `Menu` component that renders all
    * the `Option`s.
@@ -145,19 +162,28 @@ export interface SelectProps<Value extends string>
    * The menu will always have these default values unless explicity
    * overwritten by this prop:
    *
-   * - `aria-labelledby={containerId}`
+   * - `aria-labelledby={label ? labelId : id}` -- this will be undefined if
+   *   `aria-label` is provided
    * - `anchor={BELOW_CENTER_ANCHOR}`
    * - `width="min"`
    */
   menuProps?: Omit<MenuProps, "visible" | "onRequestClose" | "fixedTo">;
 
   /**
-   * Set this to `true` to update all the `Option` components to no longer
-   * render an icon while selected.
+   * Any additional props to pass to the div that contains the current visible
+   * option.
+   */
+  selectedOptionProps?: BoxProps;
+
+  /**
+   * Set this to `true` if all the `Option` components should display the
+   * selected icon after the children instead of before.
+   *
+   * @see {@link disableSelectedIcon} to remove the selected icon instead.
    *
    * @defaultValue `false`
    */
-  disableSelectedIcon?: boolean;
+  selectedIconAfter?: boolean;
 
   /**
    * Set this to `true` to prevent the current option from rendering the
@@ -165,7 +191,15 @@ export interface SelectProps<Value extends string>
    *
    * @defaultValue `false`
    */
-  disableValueAddon?: boolean;
+  disableOptionAddon?: boolean;
+
+  /**
+   * Set this to `true` to update all the `Option` components to no longer
+   * render an icon while selected.
+   *
+   * @defaultValue `false`
+   */
+  disableSelectedIcon?: boolean;
 
   /**
    * This should be the available `Option`s for the select to choose from. It
@@ -178,337 +212,227 @@ export interface SelectProps<Value extends string>
 /**
  * **Client Component**
  *
+ * @example
+ * Simple Example
+ * ```tsx
+ * import { Select, Option } from "react-md";
+ * import { useState, type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const [value, setValue] = useState("");
+ *
+ *   return (
+ *     <Select
+ *       label="Select"
+ *       value={value}
+ *       onChange={(event) => setValue(event.currentTarget.value)}
+ *       placeholder="Select a value"
+ *     >
+ *       <Option value="a">Option 1</Option>
+ *       <Option value="b">Option 2</Option>
+ *       <Option value="c">Option 3</Option>
+ *       <Option value="d">Option 4</Option>
+ *     </Select>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Testing
+ * ```tsx
+ * rmdRender(
+ *   <Select label="Select" selectedOptionProps={{ "data-testid": "selected" }}>
+ *     <Option value="a">Option 1</Option>
+ *     <Option value="b">Option 2</Option>
+ *     <Option value="c">Option 3</Option>
+ *     <Option value="d">Option 4</Option>
+ *   </Select>
+ * );
+ *
+ * const user = userEvent.setup();
+ * const select = screen.getByRole("combobox", { name: "Select" });
+ * const selected = screen.getByTestId("selected")
+ * const selectInput = screen.getByRole("textbox", { hidden: true });
+ * expect(selected).toHaveTextContent("");
+ * expect(selectInput).toHaveValue("");
+ *
+ * await user.click(select);
+ * await user.click(screen.getByRole("option"), { name: "Option 2" });
+ *
+ * expect(selected).toHaveTextContent("Option 2");
+ * expect(selectInput).toHaveValue("b");
+ * ```
+ *
  * @remarks \@since 6.0.0 Rewritten with a new API.
  */
 export function Select<Value extends string>(
-  props: SelectProps<Value>
+  props: RequireAtLeastOne<SelectProps<Value>, "label" | keyof LabelA11y>
 ): ReactElement {
   const {
-    id: propId,
+    id,
+    form,
+    autoCompleteValue,
+    autoComplete = autoCompleteValue,
+    name = autoCompleteValue,
     className,
-    active = false,
+    onClick,
+    onFocus,
+    onKeyDown,
     inputRef: propInputRef,
-    inputClassName,
+    inputProps,
+    containerRef,
+    placeholder,
     menuProps = {},
-    containerProps: propContainerProps = {},
+    label,
+    labelProps = {},
+    selectedOptionProps,
     icon: propIcon,
     value,
     defaultValue,
     theme: propTheme,
     onChange = noop,
-    leftAddon,
     rightAddon: propRightAddon,
-    disableValueAddon = false,
+    active = false,
+    required,
+    selectedIconAfter = false,
+    disableOptionAddon = false,
     disableSelectedIcon = false,
     children,
     ...remaining
   } = props;
-  const { disabled = false, form } = props;
+  const { dense, error, disabled } = props;
 
-  const id = useEnsuredId(propId, "select");
-  const containerId = useEnsuredId(propContainerProps.id, "select-container");
-  const icon = getIcon("dropdown", propIcon);
-  const theme = getFormConfig("theme", propTheme);
+  const comboboxId = useEnsuredId(id, "select");
+  const inputId = useEnsuredId(inputProps?.id, "select-value");
+  const selectLabelId = useEnsuredId(labelProps.id, "select-label");
+  const labelId = label ? selectLabelId : undefined;
 
-  const { toggled: visible, enable: show, disable: hide } = useToggle();
-  const [inputRef, inputRefCallback] = useEnsuredRef(propInputRef);
-  const [containerRef, containerRefCallback] = useEnsuredRef(
-    propContainerProps.ref
-  );
-  const [menuRef, menuRefCallback] = useEnsuredRef(menuProps.nodeRef);
-  const [currentValue, setCurrentValue] = useState(() => {
+  const [localValue, setLocalValue] = useState(() => {
     if (typeof defaultValue !== "undefined") {
       return defaultValue;
     }
 
     return typeof value !== "undefined" ? value : EMPTY_STRING;
   });
+  const currentValue = typeof value === "undefined" ? localValue : value;
   const initialValue = useRef(currentValue);
+  const { options, currentOption } = extractOptionsFromChildren(
+    children,
+    currentValue
+  );
 
-  useEffect(() => {
-    const select = inputRef.current;
-    if (!select) {
-      return;
-    }
-
-    const formElement =
-      select.closest<HTMLFormElement>("form") ||
-      (form && document.getElementById(form)) ||
-      null;
-
-    if (!formElement) {
-      return;
-    }
-
-    const handleReset = (): void => {
-      triggerManualChangeEvent(select, initialValue.current);
-    };
-
-    formElement.addEventListener("reset", handleReset);
-    return () => {
-      formElement.removeEventListener("reset", handleReset);
-    };
-  }, [form, inputRef]);
-
-  const { options, searchValues, currentOption, currentIndex } =
-    extractOptionsFromChildren(
-      children,
-      typeof value === "undefined" ? currentValue : value
-    );
-  const totalOptions = options.length - 1;
-
-  let rightAddon = propRightAddon;
-  if (typeof rightAddon === "undefined" && icon) {
-    rightAddon = <IconRotator rotated={visible}>{icon}</IconRotator>;
-  }
+  const { visible, comboboxProps, movementContext, getMenuProps } =
+    useSelectCombobox({
+      form,
+      value: currentValue,
+      values: options,
+      onClick,
+      onFocus,
+      onKeyDown,
+      disabled,
+      popupId: menuProps.id,
+      popupRef: menuProps.nodeRef,
+      comboboxId,
+      comboboxRef: containerRef,
+    });
 
-  const listboxContext = useMemo(
+  const [inputRef, inputRefCallback] = useEnsuredRef(propInputRef);
+  useFormReset({
+    form,
+    elementRef: inputRef,
+    defaultValue: initialValue.current,
+  });
+  const listboxContext = useMemo<ListboxContext>(
     () => ({
       inputRef,
-      currentValue: typeof value === "undefined" ? currentValue : value,
+      currentValue,
+      selectedIconAfter,
       disableSelectedIcon,
     }),
-    [currentValue, disableSelectedIcon, inputRef, value]
+    [currentValue, disableSelectedIcon, inputRef, selectedIconAfter]
   );
 
-  // TODO: Need to update this to support editable listboxes where these props
-  // would go to the input element instead of the container
-  const a11yProps = {
-    "aria-haspopup": "listbox",
-    "aria-expanded": visible,
-    role: "combobox",
-    tabIndex: disabled ? -1 : 0,
-  } as const;
-  const {
-    movementProps,
-    movementContext,
-    currentFocusIndex,
-    setActiveDescendantId,
-  } = useKeyboardMovementProvider<HTMLDivElement>({
-    onFocus: propContainerProps.onFocus,
-    onClick(event) {
-      propContainerProps.onClick?.(event);
-      if (disabled) {
-        return;
-      }
-
-      show();
-    },
-    onKeyDown(event) {
-      propContainerProps.onKeyDown?.(event);
-      if (disabled) {
-        return;
-      }
-
-      if (visible) {
-        if (event.key === "Escape" || event.key === "Tab") {
-          event.stopPropagation();
-          hide();
-        }
-
-        return;
-      }
-
-      if (isSearchableEvent(event)) {
-        event.stopPropagation();
-
-        const nextIndex = findMatchIndex({
-          value: event.key,
-          values: searchValues,
-          startIndex: event.shiftKey ? -1 : currentIndex,
-        });
-
-        if (nextIndex !== -1) {
-          triggerManualChangeEvent(inputRef.current, options[nextIndex].value);
-        }
-        return;
-      }
-
-      switch (event.key) {
-        case " ":
-          event.preventDefault();
-          event.stopPropagation();
-          show();
-          break;
-        case "Enter":
-          tryToSubmitRelatedForm(event, form);
-          break;
-        case "Home":
-          event.preventDefault();
-          event.stopPropagation();
-          if (currentIndex !== 0) {
-            triggerManualChangeEvent(inputRef.current, options[0].value);
-          }
-          break;
-        case "End":
-          event.preventDefault();
-          event.stopPropagation();
-          if (currentIndex !== totalOptions) {
-            triggerManualChangeEvent(
-              inputRef.current,
-              options[totalOptions].value
-            );
-          }
-          break;
-        case "ArrowDown":
-        case "ArrowUp": {
-          event.preventDefault();
-          event.stopPropagation();
-
-          const increment = event.key === "ArrowDown";
-          if (currentIndex === -1 && !increment) {
-            // this matches the native select behavior where it will do
-            // nothing if there is no current value
-            return;
-          }
-
-          const nextIndex = loop({
-            max: totalOptions,
-            value: currentIndex,
-            minmax: true,
-            increment,
-          });
-
-          triggerManualChangeEvent(inputRef.current, options[nextIndex].value);
-          break;
-        }
-      }
-    },
-    loopable: false,
-    searchable: true,
-    programmatic: true,
-    includeDisabled: false,
-    tabIndexBehavior: "virtual",
-    getDefaultFocusedIndex(focusOptions) {
-      if (typeof menuProps.getDefaultFocusedIndex === "function") {
-        return menuProps.getDefaultFocusedIndex(focusOptions);
-      }
-
-      const val = typeof value === "undefined" ? currentValue : value;
-      return options.findIndex((option) => option.value === val);
-    },
-    getFocusableElements() {
-      const menu = menuRef.current;
-      if (!menu) {
-        return [];
-      }
-
-      return [
-        ...menu.querySelectorAll<HTMLLIElement>(
-          '[role="option"]:not([aria-disabled])'
-        ),
-      ];
-    },
-  });
-
-  const containerProps: Required<SelectProps<Value>>["containerProps"] = {
-    ...propContainerProps,
-    ...movementProps,
-    ...a11yProps,
-    ref: containerRefCallback,
-  };
-
-  const { onEntering, onEntered, onExiting, onExited, disableTransition } =
-    menuProps;
-  const handleMounting =
-    (callback: TransitionEnterHandler | undefined = noop, skipped = false) =>
-    (appearing: boolean) => {
-      callback(appearing);
-
-      const menu = menuRef.current;
-      if (!menu || skipped) {
-        return;
-      }
-
-      // Since the keyboard movement behavior is tied to the
-      // `TextFieldContainer` or `input` element instead of the menu for this
-      // widget, the focus index and active descendant must manually be updated
-      // whenever the menu becomes visible. Without this, no items will be
-      // focused until the first keyboard event that would move focus
-      const val = typeof value === "undefined" ? currentValue : value;
-      const focusables = getNonDisabledOptions(menu);
-      const index = Math.max(
-        0,
-        options.findIndex((option) => option.value === val)
-      );
-      focusables[index].scrollIntoView({ block: "nearest" });
-      currentFocusIndex.current = index;
-      setActiveDescendantId(focusables[index]?.id || "");
-    };
-
-  const handleUnmounting =
-    (callback: TransitionExitHandler | undefined = noop, skipped = false) =>
-    (): void => {
-      callback();
+  const icon = getIcon("dropdown", propIcon);
+  const theme = getFormConfig("theme", propTheme);
+  let rightAddon = propRightAddon;
+  if (typeof rightAddon === "undefined" && icon) {
+    rightAddon = <IconRotator rotated={visible}>{icon}</IconRotator>;
+  }
 
-      if (!skipped) {
-        // since the menu is unmounted or set to hidden while not visible, need
-        // to clear the aria-activedescendant and current focus index when
-        // hiding
-        currentFocusIndex.current = -1;
-        setActiveDescendantId("");
-      }
-    };
+  let listboxLabelledBy = menuProps["aria-labelledby"];
+  const listboxLabel = menuProps["aria-label"];
+  if (!listboxLabel && !listboxLabelledBy) {
+    listboxLabelledBy = labelId || comboboxId;
+  }
 
   return (
     <ListboxProvider value={listboxContext}>
       <KeyboardMovementProvider value={movementContext}>
-        <TextField
+        <TextFieldContainer
+          aria-labelledby={labelId}
           {...remaining}
-          aria-hidden
-          id={id}
-          ref={inputRefCallback}
-          containerProps={containerProps}
-          type="text"
-          tabIndex={-1}
+          {...comboboxProps}
+          label={!!label}
           theme={theme}
-          value={value}
-          defaultValue={defaultValue}
           active={active || visible}
-          leftAddon={leftAddon}
-          rightAddon={rightAddon}
           className={cnb("rmd-select-container", className)}
-          inputClassName={select({
-            theme,
-            className: inputClassName,
-          })}
-          onChange={(event) => {
-            onChange(event as SelectChangeEvent<Value>);
-            if (typeof value !== "undefined") {
-              return;
-            }
-
-            const nextValue = event.currentTarget.value;
-            const valueAsNumber = parseFloat(nextValue);
-            const nextOption = options.find(
-              (option) =>
-                // need to compare both here since
-                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                // @ts-expect-error
-                option.value === nextValue || option.value === valueAsNumber
-            );
-
-            setCurrentValue(
-              nextOption ? nextOption.value : initialValue.current
-            );
-          }}
+          rightAddon={rightAddon}
         >
-          <SelectValue disableAddon={disableValueAddon} {...currentOption} />
-        </TextField>
+          <SelectedOption
+            option={currentOption}
+            placeholder={placeholder}
+            disableAddon={disableOptionAddon}
+            {...selectedOptionProps}
+          />
+          <input
+            aria-hidden
+            id={inputId}
+            ref={inputRefCallback}
+            type="text"
+            autoComplete={autoComplete}
+            name={name}
+            tabIndex={-1}
+            disabled={disabled}
+            required={required}
+            placeholder=" "
+            {...inputProps}
+            value={value}
+            defaultValue={defaultValue}
+            className={cnb(select({ theme }), textField())}
+            onChange={(event) => {
+              onChange(event as SelectChangeEvent<Value>);
+              if (typeof value !== "undefined") {
+                return;
+              }
+
+              const nextValue = event.currentTarget.value;
+              const nextOption = options.find((option) => option === nextValue);
+
+              setLocalValue(nextOption ?? initialValue.current);
+            }}
+          />
+          {label && (
+            <span
+              {...labelProps}
+              id={labelId}
+              className={labelStyles({
+                dense,
+                error,
+                disabled,
+                active: active || visible,
+                floating: true,
+                floatingActive: !!placeholder || !!currentOption,
+                className: labelProps.className,
+              })}
+            >
+              {label}
+            </span>
+          )}
+        </TextFieldContainer>
         <Menu
-          aria-labelledby={containerId}
-          anchor={BELOW_CENTER_ANCHOR}
-          role="listbox"
-          width="min"
-          {...menuProps}
-          ref={menuRefCallback}
-          visible={visible}
-          fixedTo={containerRef}
-          onRequestClose={hide}
-          onEntering={handleMounting(onEntering, false)}
-          onEntered={handleMounting(onEntered, !disableTransition)}
-          onExiting={handleUnmounting(onExiting, false)}
-          onExited={handleUnmounting(onExited, !disableTransition)}
+          {...getMenuProps(menuProps)}
+          aria-label={listboxLabel}
+          aria-labelledby={listboxLabelledBy as string}
         >
           {children}
         </Menu>