@availity/mui-autocomplete 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [0.4.0](https://github.com/Availity/element/compare/@availity/mui-autocomplete@0.3.2...@availity/mui-autocomplete@0.4.0) (2024-04-11)
+
+
+### Features
+
+* **mui-autocomplete:** add AsyncAutocomplete component ([2318b3f](https://github.com/Availity/element/commit/2318b3fd70055322c5e0ea2f28514a6886c29a98))
+
 ## [0.3.2](https://github.com/Availity/element/compare/@availity/mui-autocomplete@0.3.1...@availity/mui-autocomplete@0.3.2) (2024-04-01)
 
 

package/README.md

@@ -34,7 +34,7 @@ yarn add @availity/element
 
 #### NPM
 
-_This package has a few peer dependencies. Add `@mui/material`, `@emotion/react`, @availity/mui-form-utils, & @availity/mui-textfield to your project if not already installed._
+_This package has a few peer dependencies. Add `@mui/material`, `@emotion/react`, `@availity/mui-form-utils`, & `@availity/mui-textfield` to your project if not already installed._
 
 ```bash
 npm install @availity/mui-autocomplete
@@ -50,8 +50,26 @@ yarn add @availity/mui-autocomplete
 
 #### Import through @availity/element
 
+The `Autcomplete` component can be used standalone or with a form state library like [react-hook-form](https://react-hook-form.com/).
+
+`Autocomplete` uses the `TextField` component to render the input. You must pass your field related props: `label`, `helperText`, `error`, etc. to the the `FieldProps` prop.
+
 ```tsx
 import { Autocomplete } from '@availity/element';
+
+const MyAutocomplete = () => {
+  return (
+    <Autocomplete
+      options={[
+        { label: 'Option 1', value: 1 },
+        { label: 'Option 2', value: 2 },
+        { label: 'Option 3', value: 3 },
+      ]}
+      getOptionLabel={(value) => value.label}
+      FieldProps={{ label: 'My Autocomplete Field', helperText: 'Text that helps the user' }}
+    />
+  );
+};
 ```
 
 #### Direct import
@@ -59,3 +77,65 @@ import { Autocomplete } from '@availity/element';
 ```tsx
 import { Autocomplete } from '@availity/mui-autocomplete';
 ```
+
+#### Usage with `react-hook-form`
+
+```tsx
+import { useForm, Controller } from 'react-hook-form';
+import { Autocomplete, Button } from '@availity/element';
+
+const Form = () => {
+  const { handleSubmit } = useForm();
+
+  const onSubmit = (values) => {
+    console.log(values);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        control={control}
+        name="dropdown"
+        render={({ field: { onChange, value, onBlur } }) => {
+          return (
+            <Autocomplete
+              onChange={(event, value, reason) => {
+                if (reason === 'clear') {
+                  onChange(null);
+                }
+                onChange(value);
+              }}
+              onBlur={onBlur}
+              FieldProps={{ label: 'Dropdown', helperText: 'This is helper text', placeholder: 'Value' }}
+              options={['Bulbasaur', 'Squirtle', 'Charmander']}
+              value={value || null}
+            />
+          );
+        }}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+};
+```
+
+#### `AsyncAutocomplete` Usage
+
+An `AsyncAutocomplete` component is exported for use cases that require fetching paginated results from an api. You will need to use the `loadOptions` prop. The `loadOptions` function will be called when the user scrolls to the bottom of the dropdown. It will be passed the current page and limit. The `limit` prop controls what is passed to `loadOptions` and is defaulted to `50`. The `loadOptions` function must return an object that has an array of `options` and a `hasMore` property. `hasMore` tells the `AsyncAutocomplete` component whether or not it should call `loadOptions` again. The returned `options` will be concatenated to the existing options array.
+
+```tsx
+import { Autocomplete } from '@availity/element';
+
+const Example = () => {
+  const loadOptions = async (page: number) => {
+    const response = await callApi(page);
+
+    return {
+      options: repsonse.data,
+      hasMore: response.totalCount > response.count,
+    };
+  };
+
+  return <Autocomplete FieldProps={{ label: 'Async Dropdown' }} loadOptions={loadOptions} />;
+};
+```

package/dist/index.d.ts

@@ -10,4 +10,16 @@ interface AutocompleteProps<T, Multiple extends boolean | undefined, DisableClea
 }
 declare const Autocomplete: <T, Multiple extends boolean | undefined = false, DisableClearable extends boolean | undefined = false, FreeSolo extends boolean | undefined = false, ChipComponent extends react.ElementType<any> = "div">({ FieldProps, ...props }: AutocompleteProps<T, Multiple, DisableClearable, FreeSolo, ChipComponent>) => JSX.Element;
 
-export { Autocomplete, AutocompleteProps };
+interface AsyncAutocompleteProps<Option, Multiple extends boolean | undefined, DisableClearable extends boolean | undefined, FreeSolo extends boolean | undefined, ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent']> extends Omit<AutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>, 'options'> {
+    /** Function that returns a promise with options and hasMore */
+    loadOptions: (page: number, limit: number) => Promise<{
+        options: Option[];
+        hasMore: boolean;
+    }>;
+    /** The number of options to request from the api
+     * @default 50 */
+    limit?: number;
+}
+declare const AsyncAutocomplete: <Option, Multiple extends boolean | undefined = false, DisableClearable extends boolean | undefined = false, FreeSolo extends boolean | undefined = false, ChipComponent extends react.ElementType<any> = "div">({ loadOptions, limit, ...rest }: AsyncAutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>) => JSX.Element;
+
+export { AsyncAutocomplete, AsyncAutocompleteProps, Autocomplete, AutocompleteProps };

package/dist/index.js

@@ -26,6 +26,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AsyncAutocomplete: () => AsyncAutocomplete,
   Autocomplete: () => Autocomplete
 });
 module.exports = __toCommonJS(src_exports);
@@ -33,6 +34,7 @@ module.exports = __toCommonJS(src_exports);
 // src/lib/Autocomplete.tsx
 var import_react = require("react");
 var import_Autocomplete = __toESM(require("@mui/material/Autocomplete"));
+var import_CircularProgress = __toESM(require("@mui/material/CircularProgress"));
 var import_IconButton = __toESM(require("@mui/material/IconButton"));
 var import_mui_textfield = require("@availity/mui-textfield");
 var import_mui_form_utils = require("@availity/mui-form-utils");
@@ -49,6 +51,11 @@ var PopupIndicatorWrapper = (0, import_react.forwardRef)((props, ref) => /* @__P
     })
   ]
 }));
+var progressSx = { marginRight: ".5rem" };
+var LoadingIndicator = () => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_CircularProgress.default, {
+  size: 20,
+  sx: progressSx
+});
 var Autocomplete = ({
   FieldProps,
   ...props
@@ -60,7 +67,13 @@ var Autocomplete = ({
   const resolvedProps = (params) => ({
     InputProps: {
       ...FieldProps == null ? void 0 : FieldProps.InputProps,
-      ...params == null ? void 0 : params.InputProps
+      ...params == null ? void 0 : params.InputProps,
+      endAdornment: props.loading ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, {
+        children: [
+          (params == null ? void 0 : params.InputProps.endAdornment) || null,
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LoadingIndicator, {})
+        ]
+      }) : (params == null ? void 0 : params.InputProps.endAdornment) || null
     },
     inputProps: {
       ...FieldProps == null ? void 0 : FieldProps.inputProps,
@@ -81,7 +94,54 @@ var Autocomplete = ({
     ...defaultProps
   });
 };
+
+// src/lib/AsyncAutocomplete.tsx
+var import_react2 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var AsyncAutocomplete = ({
+  loadOptions,
+  limit = 50,
+  ...rest
+}) => {
+  const [page, setPage] = (0, import_react2.useState)(0);
+  const [options, setOptions] = (0, import_react2.useState)([]);
+  const [loading, setLoading] = (0, import_react2.useState)(false);
+  const [hasMore, setHasMore] = (0, import_react2.useState)(true);
+  (0, import_react2.useEffect)(() => {
+    const getInitialOptions = async () => {
+      setLoading(true);
+      const result = await loadOptions(page, limit);
+      setOptions(result.options);
+      setHasMore(result.hasMore);
+      setPage((prev) => prev + 1);
+      setLoading(false);
+    };
+    if (!loading && hasMore && page === 0) {
+      getInitialOptions();
+    }
+  }, [page, loading, loadOptions]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Autocomplete, {
+    ...rest,
+    loading,
+    options,
+    ListboxProps: {
+      onScroll: async (event) => {
+        const listboxNode = event.currentTarget;
+        const difference = listboxNode.scrollHeight - (listboxNode.scrollTop + listboxNode.clientHeight);
+        if (difference <= 5 && !loading && hasMore) {
+          setLoading(true);
+          const result = await loadOptions(page, limit);
+          setOptions([...options, ...result.options]);
+          setHasMore(result.hasMore);
+          setPage((prev) => prev + 1);
+          setLoading(false);
+        }
+      }
+    }
+  });
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AsyncAutocomplete,
   Autocomplete
 });

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { forwardRef } from "react";
 import {
   default as MuiAutocomplete
 } from "@mui/material/Autocomplete";
+import CircularProgress from "@mui/material/CircularProgress";
 import { default as MuiIconButton } from "@mui/material/IconButton";
 import { TextField } from "@availity/mui-textfield";
 import { SelectDivider, SelectExpandIcon } from "@availity/mui-form-utils";
@@ -19,6 +20,11 @@ var PopupIndicatorWrapper = forwardRef((props, ref) => /* @__PURE__ */ jsxs(Frag
     })
   ]
 }));
+var progressSx = { marginRight: ".5rem" };
+var LoadingIndicator = () => /* @__PURE__ */ jsx(CircularProgress, {
+  size: 20,
+  sx: progressSx
+});
 var Autocomplete = ({
   FieldProps,
   ...props
@@ -30,7 +36,13 @@ var Autocomplete = ({
   const resolvedProps = (params) => ({
     InputProps: {
       ...FieldProps == null ? void 0 : FieldProps.InputProps,
-      ...params == null ? void 0 : params.InputProps
+      ...params == null ? void 0 : params.InputProps,
+      endAdornment: props.loading ? /* @__PURE__ */ jsxs(Fragment, {
+        children: [
+          (params == null ? void 0 : params.InputProps.endAdornment) || null,
+          /* @__PURE__ */ jsx(LoadingIndicator, {})
+        ]
+      }) : (params == null ? void 0 : params.InputProps.endAdornment) || null
     },
     inputProps: {
       ...FieldProps == null ? void 0 : FieldProps.inputProps,
@@ -51,6 +63,53 @@ var Autocomplete = ({
     ...defaultProps
   });
 };
+
+// src/lib/AsyncAutocomplete.tsx
+import { useState, useEffect } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var AsyncAutocomplete = ({
+  loadOptions,
+  limit = 50,
+  ...rest
+}) => {
+  const [page, setPage] = useState(0);
+  const [options, setOptions] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+  useEffect(() => {
+    const getInitialOptions = async () => {
+      setLoading(true);
+      const result = await loadOptions(page, limit);
+      setOptions(result.options);
+      setHasMore(result.hasMore);
+      setPage((prev) => prev + 1);
+      setLoading(false);
+    };
+    if (!loading && hasMore && page === 0) {
+      getInitialOptions();
+    }
+  }, [page, loading, loadOptions]);
+  return /* @__PURE__ */ jsx2(Autocomplete, {
+    ...rest,
+    loading,
+    options,
+    ListboxProps: {
+      onScroll: async (event) => {
+        const listboxNode = event.currentTarget;
+        const difference = listboxNode.scrollHeight - (listboxNode.scrollTop + listboxNode.clientHeight);
+        if (difference <= 5 && !loading && hasMore) {
+          setLoading(true);
+          const result = await loadOptions(page, limit);
+          setOptions([...options, ...result.options]);
+          setHasMore(result.hasMore);
+          setPage((prev) => prev + 1);
+          setLoading(false);
+        }
+      }
+    }
+  });
+};
 export {
+  AsyncAutocomplete,
   Autocomplete
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@availity/mui-autocomplete",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Availity MUI Autocomplete Component - part of the @availity/element design system",
   "keywords": [
     "react",
@@ -43,8 +43,8 @@
     "typescript": "^4.6.4"
   },
   "peerDependencies": {
-    "@availity/mui-form-utils": "^0.10.0",
-    "@availity/mui-textfield": "^0.5.14",
+    "@availity/mui-form-utils": "^0.10.1",
+    "@availity/mui-textfield": "^0.5.15",
     "@mui/material": "^5.11.9",
     "react": ">=16.3.0"
   },

package/src/index.ts

@@ -1 +1,2 @@
 export * from './lib/Autocomplete';
+export * from './lib/AsyncAutocomplete';

package/src/lib/AsyncAutocomplete.test.tsx

@@ -0,0 +1,86 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { AsyncAutocomplete } from './AsyncAutocomplete';
+
+describe('AsyncAutocomplete', () => {
+  test('should render successfully', () => {
+    const { getByLabelText } = render(
+      <AsyncAutocomplete
+        FieldProps={{ label: 'Test' }}
+        loadOptions={async () => ({
+          options: ['1', '2', '3'],
+          hasMore: false,
+        })}
+      />
+    );
+    expect(getByLabelText('Test')).toBeTruthy();
+  });
+
+  test('options should be available', async () => {
+    const loadOptions = () =>
+      Promise.resolve({
+        options: [{ label: 'Option 1' }],
+        getOptionLabel: (option: { label: string }) => option.label,
+        hasMore: false,
+      });
+
+    render(<AsyncAutocomplete loadOptions={loadOptions} FieldProps={{ label: 'Test' }} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.click(input);
+    fireEvent.keyDown(input, { key: 'ArrowDown' });
+
+    waitFor(() => {
+      expect(screen.getByText('Option 1')).toBeDefined();
+    });
+
+    fireEvent.click(await screen.findByText('Option 1'));
+
+    waitFor(() => {
+      expect(screen.getByText('Option 1')).toBeDefined();
+    });
+  });
+
+  test('should call loadOptions when scroll to the bottom', async () => {
+    const loadOptions = jest.fn();
+    loadOptions.mockResolvedValueOnce({
+      options: [
+        { label: 'Option 1' },
+        { label: 'Option 2' },
+        { label: 'Option 3' },
+        { label: 'Option 4' },
+        { label: 'Option 5' },
+        { label: 'Option 6' },
+      ],
+      hasMore: true,
+    });
+    render(<AsyncAutocomplete loadOptions={loadOptions} FieldProps={{ label: 'Test' }} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.click(input);
+    fireEvent.keyDown(input, { key: 'ArrowDown' });
+
+    await waitFor(() => {
+      expect(screen.getByText('Option 1')).toBeDefined();
+    });
+
+    expect(loadOptions).toHaveBeenCalled();
+    expect(loadOptions).toHaveBeenCalledTimes(1);
+    expect(loadOptions).toHaveBeenCalledWith(0, 50);
+
+    loadOptions.mockResolvedValueOnce({
+      options: [{ label: 'Option 7' }],
+      hasMore: false,
+    });
+
+    await act(async () => {
+      const options = await screen.findByRole('listbox');
+      fireEvent.scroll(options, { target: { scrollTop: options.scrollHeight } });
+    });
+
+    await waitFor(() => {
+      expect(loadOptions).toHaveBeenCalled();
+      expect(loadOptions).toHaveBeenCalledTimes(2);
+      expect(loadOptions).toHaveBeenLastCalledWith(1, 50);
+    });
+  });
+});

package/src/lib/AsyncAutocomplete.tsx

@@ -0,0 +1,74 @@
+import { useState, useEffect } from 'react';
+import type { ChipTypeMap } from '@mui/material/Chip';
+
+import { Autocomplete, AutocompleteProps } from './Autocomplete';
+
+export interface AsyncAutocompleteProps<
+  Option,
+  Multiple extends boolean | undefined,
+  DisableClearable extends boolean | undefined,
+  FreeSolo extends boolean | undefined,
+  ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent']
+> extends Omit<AutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>, 'options'> {
+  /** Function that returns a promise with options and hasMore */
+  loadOptions: (page: number, limit: number) => Promise<{ options: Option[]; hasMore: boolean }>;
+  /** The number of options to request from the api
+   * @default 50 */
+  limit?: number;
+}
+
+export const AsyncAutocomplete = <
+  Option,
+  Multiple extends boolean | undefined = false,
+  DisableClearable extends boolean | undefined = false,
+  FreeSolo extends boolean | undefined = false,
+  ChipComponent extends React.ElementType = ChipTypeMap['defaultComponent']
+>({
+  loadOptions,
+  limit = 50,
+  ...rest
+}: AsyncAutocompleteProps<Option, Multiple, DisableClearable, FreeSolo, ChipComponent>) => {
+  const [page, setPage] = useState(0);
+  const [options, setOptions] = useState<Option[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+
+  useEffect(() => {
+    const getInitialOptions = async () => {
+      setLoading(true);
+      const result = await loadOptions(page, limit);
+      setOptions(result.options);
+      setHasMore(result.hasMore);
+      setPage((prev) => prev + 1);
+      setLoading(false);
+    };
+
+    if (!loading && hasMore && page === 0) {
+      getInitialOptions();
+    }
+  }, [page, loading, loadOptions]);
+
+  return (
+    <Autocomplete
+      {...rest}
+      loading={loading}
+      options={options}
+      ListboxProps={{
+        onScroll: async (event: React.SyntheticEvent) => {
+          const listboxNode = event.currentTarget;
+          const difference = listboxNode.scrollHeight - (listboxNode.scrollTop + listboxNode.clientHeight);
+
+          // Only fetch if we are near the bottom, not already fetching, and there are more results
+          if (difference <= 5 && !loading && hasMore) {
+            setLoading(true);
+            const result = await loadOptions(page, limit);
+            setOptions([...options, ...result.options]);
+            setHasMore(result.hasMore);
+            setPage((prev) => prev + 1);
+            setLoading(false);
+          }
+        },
+      }}
+    />
+  );
+};

package/src/lib/Autocomplete.stories.tsx

@@ -1,7 +1,7 @@
 // Each exported component in the package should have its own stories file
-
 import type { Meta, StoryObj } from '@storybook/react';
 import { Autocomplete } from './Autocomplete';
+import { AsyncAutocomplete } from './AsyncAutocomplete';
 
 const meta: Meta<typeof Autocomplete> = {
   title: 'Components/Autocomplete/Autocomplete',
@@ -42,3 +42,111 @@ export const _Multi: StoryObj<typeof Autocomplete> = {
     multiple: true,
   },
 };
+
+type Org = {
+  id: string;
+  name: string;
+};
+
+const organizations: Org[] = [
+  {
+    id: '1',
+    name: 'Org 1',
+  },
+  {
+    id: '2',
+    name: 'Org 2',
+  },
+  {
+    id: '3',
+    name: 'Org 3',
+  },
+  {
+    id: '4',
+    name: 'Org 4',
+  },
+  {
+    id: '5',
+    name: 'Org 5',
+  },
+  {
+    id: '6',
+    name: 'Org 6',
+  },
+  {
+    id: '7',
+    name: 'Org 7',
+  },
+  {
+    id: '8',
+    name: 'Org 8',
+  },
+  {
+    id: '9',
+    name: 'Org 9',
+  },
+  {
+    id: '10',
+    name: 'Org 10',
+  },
+  {
+    id: '11',
+    name: 'Org 11',
+  },
+  {
+    id: '12',
+    name: 'Org 12',
+  },
+  {
+    id: '13',
+    name: 'Org 13',
+  },
+  {
+    id: '14',
+    name: 'Org 14',
+  },
+  {
+    id: '15',
+    name: 'Org 15',
+  },
+];
+
+async function sleep(duration = 2500) {
+  await new Promise((resolve) => setTimeout(resolve, duration));
+}
+
+const getResults = (page: number, limit: number) => {
+  const offset = page * limit;
+  const orgs = organizations.slice(page * offset, page * offset + limit);
+
+  return {
+    totalCount: organizations.length,
+    offset,
+    limit,
+    orgs,
+    count: orgs.length,
+  };
+};
+
+const loadOptions = async (page: number, limit: number) => {
+  await sleep(1000);
+
+  const { orgs, totalCount, offset } = getResults(page, limit);
+
+  return {
+    options: orgs,
+    hasMore: offset + limit < totalCount,
+  };
+};
+
+export const _Async: StoryObj<typeof AsyncAutocomplete> = {
+  render: (args) => {
+    return <AsyncAutocomplete {...args} />;
+  },
+  args: {
+    FieldProps: { label: 'Async Select', helperText: 'Helper Text', fullWidth: false },
+    getOptionLabel: (val: Org) => val.name,
+    loadOptions,
+    limit: 10,
+  },
+};

package/src/lib/Autocomplete.tsx

@@ -5,6 +5,7 @@ import {
   AutocompleteRenderInputParams,
   AutocompletePropsSizeOverrides,
 } from '@mui/material/Autocomplete';
+import CircularProgress from '@mui/material/CircularProgress';
 import { default as MuiIconButton, IconButtonProps as MuiIconButtonProps } from '@mui/material/IconButton';
 import { ChipTypeMap } from '@mui/material/Chip';
 import { OverridableStringUnion } from '@mui/types';
@@ -50,6 +51,10 @@ const PopupIndicatorWrapper = forwardRef<HTMLButtonElement, MuiIconButtonProps>(
   </>
 ));
 
+const progressSx = { marginRight: '.5rem' };
+
+const LoadingIndicator = () => <CircularProgress size={20} sx={progressSx} />;
+
 export const Autocomplete = <
   T,
   Multiple extends boolean | undefined = false,
@@ -71,6 +76,14 @@ export const Autocomplete = <
     InputProps: {
       ...FieldProps?.InputProps,
       ...params?.InputProps,
+      endAdornment: props.loading ? (
+        <>
+          {params?.InputProps.endAdornment || null}
+          <LoadingIndicator />
+        </>
+      ) : (
+        params?.InputProps.endAdornment || null
+      ),
     },
     inputProps: {
       ...FieldProps?.inputProps,