@react-md/core 1.0.0-next.13 → 1.0.0-next.14

package/dist/useMutationObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useMutationObserver.ts"],"sourcesContent":["import { useEffect, type RefCallback, type Ref } from \"react\";\nimport { useEnsuredRef } from \"./useEnsuredRef.js\";\n\n/**\n * @since 6.0.0\n */\nexport interface MutationObserverHookOptions<E extends HTMLElement>\n  extends MutationObserverInit {\n  ref?: Ref<E>;\n\n  /**\n   * @see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options\n   * @defaultValue `!childList && !attributes && !characterData`\n   */\n  disabled?: boolean;\n\n  onObserved(mutation: MutationRecord): void;\n}\n\n/**\n * The mutation observer is used to track the changes made to the DOM tree.\n *\n * @example Simple Example\n * ```tsx\n * import { useMutationObserver } from \"@react-md/core\";\n * import { useCallback, type HTMLAttributes, type ReactElement } from \"react\";\n *\n * function Example(props: HTMLAttributes<HTMLDivElement>): ReactElement {\n *   const { children, ...remaining } = props;\n *\n *   const targetRef = useMutationObserver({\n *     subtree: true,\n *     attributes: true,\n *     childList: true,\n *     onUpdate: useCallback((mutation) => {\n *       switch (mutation.type) {\n *         case \"childList\":\n *           console.log(\"A child node has been added or removed\");\n *           break;\n *         case \"attributes\":\n *           console.log(`The ${mutation.attributeName} attribute was modified`);\n *           break\n *       }\n *\n *     }, []),\n *   });\n *\n *   return (\n *     <div {...remaining} ref={targetRef}>\n *       {children}\n *     </div>\n *   );\n * }\n * ```\n *\n * @since 6.0.0\n */\nexport function useMutationObserver<E extends HTMLElement>(\n  options: MutationObserverHookOptions<E>\n): RefCallback<E> {\n  const {\n    ref,\n    onObserved,\n    attributes,\n    attributeFilter,\n    attributeOldValue,\n    subtree,\n    childList,\n    characterData,\n    characterDataOldValue,\n    disabled = !childList && !attributes && !characterData,\n  } = options;\n\n  const [targetNodeRef, refCallback] = useEnsuredRef(ref);\n  useEffect(() => {\n    if (disabled) {\n      return;\n    }\n\n    const observerTarget = targetNodeRef.current;\n    if (!observerTarget) {\n      return;\n    }\n\n    const observer = new MutationObserver((records) => {\n      const [entry] = records;\n      if (entry) {\n        onObserved(entry);\n      }\n    });\n\n    observer.observe(observerTarget, {\n      attributes,\n      attributeFilter,\n      attributeOldValue,\n      subtree,\n      childList,\n      characterData,\n      characterDataOldValue,\n    });\n    return () => {\n      observer.disconnect();\n    };\n  }, [\n    attributeFilter,\n    attributeOldValue,\n    attributes,\n    characterData,\n    characterDataOldValue,\n    childList,\n    disabled,\n    onObserved,\n    subtree,\n    targetNodeRef,\n  ]);\n\n  return refCallback;\n}\n"],"names":["useEffect","useEnsuredRef","useMutationObserver","options","ref","onObserved","attributes","attributeFilter","attributeOldValue","subtree","childList","characterData","characterDataOldValue","disabled","targetNodeRef","refCallback","observerTarget","current","observer","MutationObserver","records","entry","observe","disconnect"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"AAAA,SAASA,SAAS,QAAoC,QAAQ;AAC9D,SAASC,aAAa,QAAQ,qBAAqB;AAkBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCC,GACD,OAAO,SAASC,oBACdC,OAAuC;IAEvC,MAAM,EACJC,GAAG,EACHC,UAAU,EACVC,UAAU,EACVC,eAAe,EACfC,iBAAiB,EACjBC,OAAO,EACPC,SAAS,EACTC,aAAa,EACbC,qBAAqB,EACrBC,WAAW,CAACH,aAAa,CAACJ,cAAc,CAACK,aAAa,EACvD,GAAGR;IAEJ,MAAM,CAACW,eAAeC,YAAY,GAAGd,cAAcG;IACnDJ,UAAU;QACR,IAAIa,UAAU;YACZ;QACF;QAEA,MAAMG,iBAAiBF,cAAcG,OAAO;QAC5C,IAAI,CAACD,gBAAgB;YACnB;QACF;QAEA,MAAME,WAAW,IAAIC,iBAAiB,CAACC;YACrC,MAAM,CAACC,MAAM,GAAGD;YAChB,IAAIC,OAAO;gBACThB,WAAWgB;YACb;QACF;QAEAH,SAASI,OAAO,CAACN,gBAAgB;YAC/BV;YACAC;YACAC;YACAC;YACAC;YACAC;YACAC;QACF;QACA,OAAO;YACLM,SAASK,UAAU;QACrB;IACF,GAAG;QACDhB;QACAC;QACAF;QACAK;QACAC;QACAF;QACAG;QACAR;QACAI;QACAK;KACD;IAED,OAAOC;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-md/core",
-  "version": "1.0.0-next.13",
+  "version": "1.0.0-next.14",
   "description": "The core components and functionality for react-md.",
   "type": "module",
   "sass": "./dist/_core.scss",
@@ -58,21 +58,21 @@
   "devDependencies": {
     "@jest/globals": "^29.7.0",
     "@jest/types": "^29.6.3",
-    "@microsoft/api-extractor": "^7.43.1",
+    "@microsoft/api-extractor": "^7.46.2",
     "@swc/cli": "^0.3.12",
-    "@swc/core": "1.4.16",
+    "@swc/core": "1.5.24",
     "@swc/jest": "^0.2.36",
-    "@testing-library/dom": "^10.0.0",
-    "@testing-library/jest-dom": "^6.4.2",
-    "@testing-library/react": "^15.0.2",
+    "@testing-library/dom": "^10.1.0",
+    "@testing-library/jest-dom": "^6.4.5",
+    "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.5.2",
-    "@types/lodash": "^4.17.0",
-    "@types/node": "^20.12.7",
-    "@types/react": "^18.2.79",
-    "@types/react-dom": "^18.2.25",
+    "@types/lodash": "^4.17.4",
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
     "chokidar": "^3.6.0",
-    "filesize": "^10.1.1",
-    "glob": "10.3.12",
+    "filesize": "^10.1.2",
+    "glob": "10.4.1",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-watch-typeahead": "^2.2.2",
@@ -81,14 +81,14 @@
     "npm-run-all": "^4.1.5",
     "postcss": "^8.4.38",
     "postcss-scss": "^4.0.9",
-    "prettier": "^3.2.5",
-    "stylelint": "^16.3.1",
+    "prettier": "^3.3.0",
+    "stylelint": "^16.6.1",
     "stylelint-config-prettier-scss": "^1.0.0",
     "stylelint-config-recommended-scss": "^14.0.0",
     "stylelint-order": "^6.0.4",
-    "stylelint-scss": "^6.2.1",
+    "stylelint-scss": "^6.3.1",
     "ts-node": "^10.9.2",
-    "tsx": "^4.7.2",
+    "tsx": "^4.11.2",
     "typescript": "^5.4.5"
   },
   "peerDependencies": {

package/src/__tests__/{useAsyncAction.tsx → useAsyncFunction.tsx}

@@ -11,7 +11,7 @@ import {
 import { box } from "../box/styles.js";
 import { Button, type ButtonProps } from "../button/Button.js";
 import { CircularProgress } from "../progress/CircularProgress.js";
-import { useAsyncAction } from "../useAsyncAction.js";
+import { useAsyncFunction } from "../useAsyncFunction.js";
 
 interface TestProps extends ButtonProps {
   onClick(event: MouseEvent<HTMLButtonElement>): Promise<void>;
@@ -27,7 +27,7 @@ function Test(props: TestProps): ReactElement {
     hookDisabled,
     ...remaining
   } = props;
-  const { handleAsync, pending } = useAsyncAction({
+  const { handleAsync, pending } = useAsyncFunction({
     disabled: disabled || hookDisabled,
   });
 
@@ -54,7 +54,7 @@ function Test(props: TestProps): ReactElement {
   );
 }
 
-describe("useAsyncAction", () => {
+describe("useAsyncFunction", () => {
   it("should start the async flow once clicked, prevent additional actions from being fired while pending, and not trigger the action if unmounted", async () => {
     const user = userEvent.setup();
 

package/src/__tests__/useWindowSize.tsx

@@ -1,8 +1,7 @@
 import { beforeAll, beforeEach, describe, expect, it } from "@jest/globals";
 import { createRef, type MutableRefObject, type ReactElement } from "react";
-import { act } from "react-dom/test-utils";
 import { SsrProvider } from "../SsrProvider.js";
-import { render, screen, waitFor } from "../test-utils/index.js";
+import { act, render, screen, waitFor } from "../test-utils/index.js";
 import { type ElementSize } from "../types.js";
 import { useWindowSize, type WindowSizeOptions } from "../useWindowSize.js";
 

package/src/_box-shadows.scss

@@ -1,4 +1,7 @@
+@use "sass:list";
 @use "sass:map";
+@use "sass:math";
+@use "sass:meta";
 @use "sass:string";
 @use "theme/theme";
 @use "transition/transition";
@@ -92,7 +95,7 @@ $box-shadow-3-layers: (
 ) !default;
 
 @function box-shadow($z-value, $color: $box-shadow-color, $opacity-boost: 0) {
-  @if type-of($z-value) != "number" or not unitless($z-value) {
+  @if meta.type-of($z-value) != "number" or not math.is-unitless($z-value) {
     @error "$z-value must be a unitless number, but received '#{$z-value}'";
   }
 
@@ -157,10 +160,10 @@ $box-shadow-3-layers: (
       transition: opacity $duration transition.$linear-timing-function;
     }
 
-    @if type-of($active-selectors) == string {
+    @if meta.type-of($active-selectors) == string {
       $active-string: $active-selectors + $suffix;
-    } @else if type-of($active-selectors) == list {
-      @for $i from 1 to length($active-selectors) + 1 {
+    } @else if meta.type-of($active-selectors) == list {
+      @for $i from 1 to list.length($active-selectors) + 1 {
         $selector: list.nth($active-selectors, $i);
 
         $prefix: $active-string + if($i > 1, ", ", "");

package/src/_core.scss

@@ -33,12 +33,14 @@
 @forward "expansion-panel/expansion-panel" as expansion-panel-*;
 @forward "menu/menu" as menu-*;
 @forward "form/form" as form-*;
+@forward "autocomplete/autocomplete" as autocomplete-*;
 @forward "layout/layout" as layout-*;
 @forward "navigation/navigation" as navigation-*;
 @forward "segmented-button/segmented-button" as segmented-button-*;
 
-@use "avatar/avatar";
 @use "app-bar/app-bar";
+@use "autocomplete/autocomplete";
+@use "avatar/avatar";
 @use "box/box";
 @use "button/button";
 @use "segmented-button/segmented-button";
@@ -102,6 +104,7 @@ $_layer-order: (
   window-splitter,
   menu,
   form,
+  autocomplete,
   layout,
   navigation,
   snackbar,
@@ -382,6 +385,7 @@ $_layer-order: (
   }
 
   @include app-bar.styles($disable-layer);
+  @include autocomplete.styles($disable-layer);
   @include avatar.styles($disable-layer);
   @include badge.styles($disable-layer);
   @include box.styles($disable-layer);

package/src/_utils.scss

@@ -1,7 +1,7 @@
-@use "sass:string";
+@use "sass:list";
 @use "sass:map";
 @use "sass:meta";
-@use "sass:list";
+@use "sass:string";
 
 $disable-rtl: false !default;
 $disable-validation: false !default;
@@ -67,7 +67,7 @@ $_swappable-properties: text-align;
   }
 
   $choices: if($is-map, map.keys($list-or-map), $list-or-map);
-  @if not index($choices, $key-or-value) {
+  @if not list.index($choices, $key-or-value) {
     @error "Invalid #{$error-message}: '#{$key-or-value}'. Choose one of: #{$choices}";
   }
 

package/src/autocomplete/Autocomplete.tsx

@@ -0,0 +1,294 @@
+"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 { 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 { autocomplete, autocompleteRightAddon } from "./autocompleteStyles.js";
+import {
+  type AutocompleteMenuLabel,
+  type AutocompleteOptionsProps,
+} from "./types.js";
+
+const noop = (): void => {
+  // do nothing
+};
+
+/**
+ * @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;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function Autocomplete<T extends string | { label: string }>(
+  props: AutocompleteMenuLabel<Omit<AutocompleteProps<T>, "extractor">>
+): ReactElement;
+/**
+ * @since 6.0.0
+ */
+export function Autocomplete<T>(
+  props: AutocompleteMenuLabel<
+    AutocompleteProps<T> & { extractor: TextExtractor<T> }
+  >
+): ReactElement;
+export function Autocomplete<T>(
+  props: AutocompleteMenuLabel<AutocompleteProps<T>>
+): ReactElement {
+  const {
+    id: propId,
+    value: propValue,
+    defaultValue = "",
+    onClick,
+    onFocus,
+    onKeyDown,
+    onChange = noop,
+    onFocusChange,
+    className,
+    options,
+    children,
+    inputRef,
+    extractor,
+    onAutocomplete = noop,
+    getOptionProps,
+    clearOnAutocomplete,
+    menuProps,
+    menuLabel,
+    menuLabelledBy,
+    containerProps,
+    filter,
+    whitespace,
+    disableFilter,
+    noOptionsChildren,
+    dropdownButtonProps,
+    disableDropdownButton,
+    loading,
+    loadingProps,
+    rightAddon,
+    rightAddonProps,
+    ...remaining
+  } = 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 {
+    visible,
+    setVisible,
+    getMenuProps,
+    comboboxRef,
+    comboboxProps,
+    movementContext,
+  } = useEditableCombobox({
+    form,
+    onClick,
+    onFocus,
+    onKeyDown,
+    onFocusChange,
+    popupId: menuId,
+    popupRef: menuProps?.ref,
+    comboboxId: id,
+    comboboxRef: inputRef,
+  });
+  const [containerNodeRef, containerRef] = useEnsuredRef(containerProps?.ref);
+  useEffect(() => {
+    const input = comboboxRef.current;
+    if (!input || document.activeElement !== input) {
+      return;
+    }
+
+    const target = input.value.length;
+    input.setSelectionRange(target, target);
+  }, [comboboxRef, loading]);
+
+  return (
+    <KeyboardMovementProvider value={movementContext}>
+      <TextField
+        aria-autocomplete="list"
+        {...remaining}
+        value={query}
+        {...comboboxProps}
+        containerProps={{
+          ...containerProps,
+          ref: containerRef,
+        }}
+        className={autocomplete({
+          className,
+          loading,
+          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
+          );
+        }}
+        rightAddon={
+          <>
+            {rightAddon}
+            {loading && <AutocompleteCircularProgress {...loadingProps} />}
+            {!disableDropdownButton && (
+              <AutocompleteDropdownButton
+                aria-label={menuLabel}
+                aria-labelledby={menuLabelledBy}
+                aria-controls={comboboxProps.id}
+                {...dropdownButtonProps}
+                visible={visible}
+                onClick={() => {
+                  comboboxRef.current?.focus();
+                  setVisible((prev) => !prev);
+                }}
+              />
+            )}
+          </>
+        }
+        rightAddonProps={{
+          ...rightAddonProps,
+          pointerEvents: true,
+          className: autocompleteRightAddon({
+            className: rightAddonProps?.className,
+          }),
+        }}
+      />
+      <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}
+      >
+        {children}
+        <FilterAutocompleteOptions
+          query={query}
+          filter={filter}
+          options={options}
+          noOptionsChildren={noOptionsChildren}
+          extractor={extractor}
+          whitespace={whitespace}
+          comboboxRef={comboboxRef}
+          disableFilter={disableFilter || props["aria-autocomplete"] === "none"}
+          getOptionProps={getOptionProps}
+          onAutocomplete={onAutocomplete}
+          clearOnAutocomplete={clearOnAutocomplete}
+        />
+      </Menu>
+    </KeyboardMovementProvider>
+  );
+}

package/src/autocomplete/AutocompleteCircularProgress.tsx

@@ -0,0 +1,41 @@
+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;
+}
+
+/**
+ * @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/AutocompleteDropdownButton.tsx

@@ -0,0 +1,66 @@
+"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 { getIcon } from "../icon/iconConfig.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;
+}
+
+/**
+ * This is a simple `Button` wrapper to be used as a dropdown button within the
+ * `Autocomplete`.
+ *
+ * @since 6.0.0
+ */
+export function AutocompleteDropdownButton(
+  props: AutocompleteDropdownButtonProps
+): ReactElement {
+  const { id: propId, icon, visible, iconRotatorProps, ...remaining } = props;
+
+  const id = useEnsuredId(propId, "autocomplete-dropdown");
+
+  return (
+    <Button
+      {...remaining}
+      id={id}
+      aria-expanded={visible}
+      tabIndex={-1}
+      buttonType="icon"
+    >
+      <IconRotator {...iconRotatorProps} rotated={visible}>
+        {getIcon("dropdown", icon)}
+      </IconRotator>
+    </Button>
+  );
+}

package/src/autocomplete/FilterAutocompleteOptions.tsx

@@ -0,0 +1,86 @@
+"use client";
+import { useMemo, type ReactElement, type RefObject } from "react";
+import {
+  triggerManualChangeEvent,
+  type EditableHTMLElement,
+} from "../form/utils.js";
+import { ListSubheader } from "../list/ListSubheader.js";
+import { MenuItem } from "../menu/MenuItem.js";
+import {
+  defaultAutocompleteExtractor,
+  defaultAutocompleteFilter,
+  defaultAutocompleteOptionProps,
+} from "./defaults.js";
+import { type AutocompleteOptionsProps } from "./types.js";
+
+const noop = (): void => {
+  // do nothing
+};
+
+export interface FilterAutocompleteOptionsProps<T>
+  extends AutocompleteOptionsProps<T> {
+  query: string;
+  comboboxRef: RefObject<EditableHTMLElement>;
+}
+
+export function FilterAutocompleteOptions<T>(
+  props: FilterAutocompleteOptionsProps<T>
+): ReactElement {
+  const {
+    query,
+    filter = defaultAutocompleteFilter,
+    options,
+    extractor = defaultAutocompleteExtractor,
+    whitespace = "keep",
+    comboboxRef,
+    disableFilter,
+    onAutocomplete = noop,
+    getOptionProps = defaultAutocompleteOptionProps,
+    clearOnAutocomplete,
+    noOptionsChildren = <ListSubheader>No Options</ListSubheader>,
+  } = props;
+  const filtered = useMemo(() => {
+    if (disableFilter) {
+      return options;
+    }
+
+    return filter({
+      list: options,
+      query,
+      extractor,
+      whitespace,
+    });
+  }, [disableFilter, extractor, filter, options, query, whitespace]);
+
+  return (
+    <>
+      {!filtered.length && noOptionsChildren}
+      {filtered.map((option, index) => {
+        const label = extractor(option);
+        const optionProps = getOptionProps({
+          index,
+          option,
+        });
+
+        return (
+          <MenuItem
+            key={label}
+            role="option"
+            {...optionProps}
+            onClick={(event) => {
+              optionProps?.onClick?.(event);
+
+              triggerManualChangeEvent(
+                comboboxRef.current,
+                clearOnAutocomplete ? "" : label
+              );
+              onAutocomplete(option);
+            }}
+          >
+            {optionProps?.children ?? label}
+          </MenuItem>
+        );
+      })}
+    </>
+  );
+}