feat(CustomSelect): expose searchPlaceholder and default toggle label and add async option to searchable (#1280)

Author: fasih-mehmood

src/components/CustomSelect/CustomSelect.stories.tsx

@@ -169,12 +169,14 @@ const meta: Meta<StoryProps> = {
   args: {
     name: "customSelect",
     label: "Custom Select",
+    defaultToggleLabel: "Select an option",
     searchable: "auto",
+    searchPlaceholder: "Search",
     initialPosition: "left",
   },
   argTypes: {
     searchable: {
-      options: ["auto", "always", "never"],
+      options: ["auto", "always", "async", "never"],
       control: {
         type: "select",
       },
@@ -255,3 +257,14 @@ export const ManualSearchable: Story = {
     searchable: "always",
   },
 };
+
+/**
+ * Search can be enabled manually by setting `searchable` to `async`.
+ * This will always show the search input regardless of the number of options.
+ */
+export const AsyncSearchable: Story = {
+  args: {
+    options: generateStandardOptions(0),
+    searchable: "async",
+  },
+};

src/components/CustomSelect/CustomSelect.test.tsx

@@ -87,6 +87,18 @@ describe("CustomSelect", () => {
     expect(screen.getByText("Select an option")).toBeInTheDocument();
   });
 
+  it("should allow customizing the placeholder when no option is selected", () => {
+    render(
+      <CustomSelect
+        options={options}
+        defaultToggleLabel="Custom label"
+        value={null}
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByText("Custom label")).toBeInTheDocument();
+  });
+
   it("should display the standard label when selected option has no selectedLabel", () => {
     render(<CustomSelect options={options} value="1" onChange={() => {}} />);
     expect(screen.getByText("Option 1")).toBeInTheDocument();

src/components/CustomSelect/CustomSelect.tsx

@@ -38,14 +38,34 @@ export type Props = PropsWithSpread<
     name?: string;
     // Whether if the select is disabled
     disabled?: boolean;
+    /**
+     * Toggle label when no option is selected
+     *
+     * @default - "Select an option"
+     */
+    defaultToggleLabel?: string;
     // Styling for the wrapping Field component
     wrapperClassName?: ClassName;
     // The styling for the select toggle button
     toggleClassName?: ClassName;
     // The styling for the select dropdown
     dropdownClassName?: string;
-    // Whether the select is searchable. Option "auto" is the default, the select will be searchable if it has 5 or more options.
-    searchable?: "auto" | "always" | "never";
+    /**
+     * Whether the select is searchable.
+     * - `auto`: the select will be searchable if it has 5 or more options.
+     * - `always`: the select will always be searchable if there is at least 1 option.
+     * - `async`: the select will always be searchable.
+     * - `never`: the select will never be searchable.
+     *
+     * @default - "auto"
+     */
+    searchable?: "auto" | "always" | "async" | "never";
+    /**
+     * Placeholder text for the search input when searchable is enabled.
+     *
+     * @default - "Search"
+     */
+    searchPlaceholder?: string;
     // Whether to focus on the element on initial render.
     takeFocus?: boolean;
     // Additional component to display above the dropdown list.
@@ -76,7 +96,9 @@ const CustomSelect = ({
   wrapperClassName,
   toggleClassName,
   dropdownClassName,
+  defaultToggleLabel = "Select an option",
   searchable = "auto",
+  searchPlaceholder = "Search",
   takeFocus,
   header,
   selectRef,
@@ -128,7 +150,7 @@ const CustomSelect = ({
     <span className="toggle-label u-truncate">
       {selectedOption
         ? selectedOption.selectedLabel || getOptionText(selectedOption)
-        : "Select an option"}
+        : defaultToggleLabel}
     </span>
   );
 
@@ -188,6 +210,7 @@ const CustomSelect = ({
         {(close: () => void) => (
           <CustomSelectDropdown
             searchable={searchable}
+            searchPlaceholder={searchPlaceholder}
             onSearch={onSearch}
             name={name || ""}
             options={options || []}

src/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.test.tsx

@@ -141,6 +141,15 @@ describe("CustomSelectDropdown", () => {
       expect(searchBox).toBeInTheDocument();
     });
 
+    it("should render the search box when `searchable` is `async` and there are no options", () => {
+      setup("async", []);
+
+      const searchBox = screen.queryByRole("textbox", {
+        name: /search for test-dropdown/i,
+      });
+      expect(searchBox).toBeInTheDocument();
+    });
+
     it("should not render search box when `searchable` is `never`", () => {
       setup("never");
 

src/components/CustomSelect/CustomSelectDropdown/CustomSelectDropdown.tsx

@@ -24,7 +24,8 @@ export type CustomSelectOption = LiHTMLAttributes<HTMLLIElement> & {
 };
 
 export type Props = {
-  searchable?: "auto" | "always" | "never";
+  searchable?: "auto" | "always" | "async" | "never";
+  searchPlaceholder?: string;
   name: string;
   options: CustomSelectOption[];
   onSelect: (value: string) => void;
@@ -140,8 +141,36 @@ export const getOptionText = (option: CustomSelectOption): string => {
   );
 };
 
+const getIsSearchable = (
+  searchable: Props["searchable"],
+  numberOfOptions: number,
+) => {
+  if (searchable === "async") {
+    return true;
+  }
+
+  if (searchable === "never") {
+    return false;
+  }
+
+  if (numberOfOptions <= 1) {
+    return false;
+  }
+
+  if (searchable === "always") {
+    return true;
+  }
+
+  if (searchable === "auto" && numberOfOptions >= 5) {
+    return true;
+  }
+
+  return false;
+};
+
 const CustomSelectDropdown: FC<Props> = ({
   searchable,
+  searchPlaceholder,
   name,
   options,
   onSelect,
@@ -158,10 +187,8 @@ const CustomSelectDropdown: FC<Props> = ({
   const dropdownRef = useRef<HTMLDivElement>(null);
   const searchRef = useRef<HTMLInputElement>(null);
   const dropdownListRef = useRef<HTMLUListElement>(null);
-  const isSearchable =
-    searchable !== "never" &&
-    options.length > 1 &&
-    (searchable === "always" || (searchable === "auto" && options.length >= 5));
+
+  const isSearchable = getIsSearchable(searchable, options.length);
 
   useEffect(() => {
     if (dropdownRef.current) {
@@ -324,6 +351,7 @@ const CustomSelectDropdown: FC<Props> = ({
             name={`select-search-${name}`}
             type="text"
             aria-label={`Search for ${name}`}
+            placeholder={searchPlaceholder}
             className="u-no-margin--bottom"
             onChange={handleSearch}
             value={search}