Typeaheads: export typeahead utils and hide placeholder on multiple selection (#129)

This PR aims to:
1- export typeahead utils and debounce hook
2- fix placeholder on both static and async typeahead: the expected
behavior is to hide the placeholder when at least one option has been
selected
3- adjust a bit the typescript on the typeahead helpers, since types
should not be mixed

Author: Michele-Masciave

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Export typeahead helpers and `useDebounceHook` hook.
+
+### Fixed
+
+- Hide placeholder on multiple `AsyncTypeAheadInput` and `StaticTypeAheadInput` when at least one option is selected.
+- Typeahead helpers return type from `TypeaheadOption[]` to `TypeaheadOptions`, since typeaheads are not intended to be used with mixed `string` and `LabelValueOption` options.
+
 ## [3.1.1] - 2025-04-10
 
 ### Fixed

cypress/cypress/component/Typeahead/AsyncTypeaheadInput.cy.tsx

@@ -641,9 +641,6 @@ it("placeholder", () => {
         onSubmit={() => {
           // Nothing to do
         }}
-        defaultValues={{
-          [name]: simpleOptions,
-        }}
       >
         <AsyncTypeaheadInput
           multiple
@@ -662,7 +659,10 @@ it("placeholder", () => {
       </Form>
     </div>,
   );
+
   cy.get(`#${name}`).should("have.attr", "placeholder", placeholder);
+  simpleOptions.slice(0, 2).forEach((option) => selectOption(name, option));
+  cy.get(`#${name}`).should("not.have.attr", "placeholder");
 });
 
 it("test on input change", () => {

cypress/cypress/component/Typeahead/StaticTypeaheadInput.cy.tsx

@@ -398,19 +398,16 @@ it("placeholder", () => {
 
   cy.mount(
     <div className="p-4">
-      <Form
-        onSubmit={cy.spy().as("onSubmitSpy")}
-        defaultValues={{
-          [name]: simpleOptions,
-        }}
-      >
+      <Form onSubmit={cy.spy().as("onSubmitSpy")}>
         <StaticTypeaheadInput multiple name={name} label={name} options={simpleOptions} placeholder={placeholder} />
         <input type="submit" className="mt-4" />
       </Form>
     </div>,
   );
 
   cy.get(`#${name}`).should("have.attr", "placeholder", placeholder);
+  simpleOptions.slice(0, 2).forEach((option) => selectOption(name, option));
+  cy.get(`#${name}`).should("not.have.attr", "placeholder");
 });
 
 it("test on input change", () => {

src/index.ts

@@ -8,5 +8,8 @@ export * from "./lib/types/LabelValueOption";
 export * from "./lib/DatePickerInput";
 export * from "./lib/ColorPickerInput";
 export * from "./lib/helpers/dateUtils";
+export * from "./lib/helpers/mui";
+export * from "./lib/helpers/typeahead";
+export * from "./lib/hooks/useDebounceHook";
 
 export { useFormContext } from "./lib/context/FormContext";

src/lib/AsyncTypeaheadInput.tsx

@@ -69,8 +69,8 @@ const AsyncTypeaheadInput = <T extends FieldValues>(props: AsyncTypeaheadInputPr
     autocompleteProps,
   } = props;
 
-  const [options, setOptions] = useState<TypeaheadOption[]>(defaultOptions);
-  const [value, setValue] = useState<TypeaheadOption[]>(defaultSelected);
+  const [options, setOptions] = useState<TypeaheadOptions>(defaultOptions);
+  const [value, setValue] = useState<TypeaheadOptions>(defaultSelected);
   const [page, setPage] = useState(1);
   const [loadMoreOptions, setLoadMoreOptions] = useState(limitResults !== undefined && limitResults < defaultOptions.length);
   const { name, id } = useSafeNameId(props.name ?? "", props.id);
@@ -107,7 +107,7 @@ const AsyncTypeaheadInput = <T extends FieldValues>(props: AsyncTypeaheadInputPr
           defaultSelected.map((x) => (typeof x === "string" ? x : x.value)),
         );
       },
-      updateValues: (options: TypeaheadOption[]) => {
+      updateValues: (options: TypeaheadOptions) => {
         const values = convertAutoCompleteOptionsToStringArray(options);
         const finalValue = multiple ? values : values[0];
         setValue(options);
@@ -171,7 +171,9 @@ const AsyncTypeaheadInput = <T extends FieldValues>(props: AsyncTypeaheadInputPr
           field.onBlur();
         }}
         onChange={(_e, value) => {
-          const optionsArray = value ? (Array.isArray(value) ? value : [value]) : undefined;
+          // value is typed as Autocomplete<Value> (aka TypeaheadOption) or an array of Autocomplete<Value> (aka TypeaheadOption[])
+          // however, the component is not intended to be used with mixed types
+          const optionsArray = value ? ((Array.isArray(value) ? value : [value]) as TypeaheadOptions) : undefined;
           setValue(optionsArray ?? []);
           const values = convertAutoCompleteOptionsToStringArray(optionsArray);
           const finalValue = multiple ? values : values[0];
@@ -206,7 +208,7 @@ const AsyncTypeaheadInput = <T extends FieldValues>(props: AsyncTypeaheadInputPr
             hideValidationMessage={hideValidationMessage}
             useBootstrapStyle={useBootstrapStyle}
             helpText={helpText}
-            placeholder={placeholder}
+            placeholder={multiple && value.length > 0 ? undefined : placeholder}
             paginationIcon={paginationIcon}
             paginationText={paginationText}
             variant={variant}

src/lib/StaticTypeaheadInput.tsx

@@ -140,7 +140,9 @@ const StaticTypeaheadInput = <T extends FieldValues>(props: StaticTypeaheadInput
           field.onBlur();
         }}
         onChange={(_, value) => {
-          const optionsArray = value ? (Array.isArray(value) ? value : [value]) : undefined;
+          // value is typed as Autocomplete<Value> (aka TypeaheadOption) or an array of Autocomplete<Value> (aka TypeaheadOption[])
+          // however, the component is not intended to be used with mixed types
+          const optionsArray = value ? ((Array.isArray(value) ? value : [value]) as TypeaheadOptions) : undefined;
           const values = convertAutoCompleteOptionsToStringArray(optionsArray);
           const finalValue = multiple ? values : values[0];
           clearErrors(field.name);
@@ -169,7 +171,7 @@ const StaticTypeaheadInput = <T extends FieldValues>(props: StaticTypeaheadInput
             hideValidationMessage={hideValidationMessage}
             useBootstrapStyle={useBootstrapStyle}
             helpText={helpText}
-            placeholder={placeholder}
+            placeholder={multiple && value.length > 0 ? undefined : placeholder}
             paginationIcon={paginationIcon}
             paginationText={paginationText}
             variant={variant}

src/lib/helpers/typeahead.tsx

@@ -1,12 +1,13 @@
 import { AutocompleteRenderOptionState } from "@mui/material/Autocomplete";
 import { LabelValueOption } from "../types/LabelValueOption";
-import { TypeaheadOption } from "../types/Typeahead";
+import { TypeaheadOption, TypeaheadOptions } from "../types/Typeahead";
 import AutosuggestHighlightMatch from "autosuggest-highlight/match";
 import AutosuggestHighlightParse from "autosuggest-highlight/parse";
 
-const isStringArray = (options: TypeaheadOption[]): boolean => options.length > 0 && options.every((value) => typeof value === "string");
+const isStringArray = (options: TypeaheadOptions): boolean =>
+  options.length > 0 && (options as TypeaheadOption[]).every((value) => typeof value === "string");
 
-const convertAutoCompleteOptionsToStringArray = (options: TypeaheadOption[] | undefined): string[] => {
+const convertAutoCompleteOptionsToStringArray = (options: TypeaheadOptions | undefined): string[] => {
   if (!options) {
     return [];
   }
@@ -18,29 +19,29 @@ const convertAutoCompleteOptionsToStringArray = (options: TypeaheadOption[] | un
   return (options as LabelValueOption[]).map((option) => option.value) as string[];
 };
 
-const getSingleAutoCompleteValue = (options: TypeaheadOption[], fieldValue: string | number | undefined): TypeaheadOption[] => {
+const getSingleAutoCompleteValue = (options: TypeaheadOptions, fieldValue: string | number | undefined): TypeaheadOptions => {
   if (fieldValue == undefined) {
     return [];
   }
-  return options.filter((x) =>
+  return (options as TypeaheadOption[]).filter((x) =>
     // loose equality check to handle different types between form value and option value
     typeof x === "string" ? x == fieldValue : x.value == fieldValue,
-  );
+  ) as TypeaheadOptions;
 };
 
-const getMultipleAutoCompleteValue = (options: TypeaheadOption[], fieldValue: (string | number)[] | undefined): TypeaheadOption[] => {
+const getMultipleAutoCompleteValue = (options: TypeaheadOptions, fieldValue: (string | number)[] | undefined): TypeaheadOptions => {
   if (fieldValue == undefined) {
     return [];
   }
-  return options.filter((x) =>
+  return (options as TypeaheadOption[]).filter((x) =>
     typeof x === "string"
       ? fieldValue.includes(x)
       : // ensure that form values matches options values even if they are of different types
         fieldValue.map(String).includes(String(x.value as string | number)),
-  );
+  ) as TypeaheadOptions;
 };
 
-const sortOptionsByGroup = (options: TypeaheadOption[]): TypeaheadOption[] =>
+const sortOptionsByGroup = (options: TypeaheadOptions): TypeaheadOptions =>
   options.sort((x, y) => (typeof x === "string" ? x : x.group?.name ?? "").localeCompare(typeof y === "string" ? y : y.group?.name ?? ""));
 
 const groupOptions = (option: TypeaheadOption): string => (typeof option === "string" ? option : option.group?.name ?? "");

src/lib/hooks/useDebounceHook.ts

@@ -1,12 +1,12 @@
 import { useEffect, useRef, useState } from "react";
-import { TypeaheadOption, TypeaheadOptions } from "../types/Typeahead";
+import { TypeaheadOptions } from "../types/Typeahead";
 
 interface DebounceSearch {
   query: string;
   delay: number;
 }
 
-const useDebounceHook = (queryFn: (query: string) => Promise<TypeaheadOptions>, setOptions: (results: TypeaheadOption[]) => void) => {
+const useDebounceHook = (queryFn: (query: string) => Promise<TypeaheadOptions>, setOptions: (results: TypeaheadOptions) => void) => {
   const queryRef = useRef("");
   const [isLoading, setIsLoading] = useState(false);
   const [debounceSearch, setDebounceSearch] = useState<DebounceSearch | undefined>(undefined);