@purpurds/autocomplete 5.29.0 → 5.30.1

package/dist/useAutocomplete.d.ts

@@ -9,8 +9,8 @@ export type Option = {
 };
 export type InputProps = Omit<ComponentPropsWithRef<"input">, "onFocus" | "onMouseDown"> & {
     "data-testid"?: string;
-    onFocus: () => void;
-    onMouseDown: () => void;
+    onFocus: (event: React.FocusEvent<HTMLInputElement> | undefined) => void;
+    onMouseDown: (event: React.MouseEvent<HTMLInputElement> | undefined) => void;
 };
 export type UseAutocompleteOptions<T extends Option> = {
     combobox?: boolean;
@@ -22,14 +22,18 @@ export type UseAutocompleteOptions<T extends Option> = {
     listboxLabel: string;
     listboxMaxHeight?: string | number;
     noOptionsText?: ReactNode;
+    onInputBlur?: React.FocusEventHandler<HTMLInputElement>;
     onInputChange?: (value: string) => void;
+    onInputFocus?: (event: React.FocusEvent<HTMLInputElement> | undefined) => undefined;
+    onInputKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+    onInputMouseDown?: (event: React.MouseEvent<HTMLInputElement> | undefined) => undefined;
     openOnFocus?: boolean;
     onSelect?: (option: T | undefined) => void;
     options: T[];
     selectedOption?: T;
     ["data-testid"]?: string;
 };
-export declare const useAutocomplete: <T extends Option>({ combobox, highlightFirstOption, defaultInputValue, inputValue, filterOption, id, listboxLabel, listboxMaxHeight, onInputChange, openOnFocus, noOptionsText, onSelect, options, selectedOption, ["data-testid"]: dataTestid, }: UseAutocompleteOptions<T>) => {
+export declare const useAutocomplete: <T extends Option>({ combobox, highlightFirstOption, defaultInputValue, inputValue, filterOption, id, listboxLabel, listboxMaxHeight, onInputBlur, onInputChange, onInputFocus, onInputKeyDown, onInputMouseDown, openOnFocus, noOptionsText, onSelect, options, selectedOption, ["data-testid"]: dataTestid, }: UseAutocompleteOptions<T>) => {
     id: string;
     inputProps: InputProps;
     internalRef: import('react').MutableRefObject<HTMLDivElement | null>;

package/dist/useAutocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAutocomplete.d.ts","sourceRoot":"","sources":["../src/useAutocomplete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAC;AAE7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIxE,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC,GAAG;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,MAAM,IAAI;IAIrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAInB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAI/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAI3B,UAAU,CAAC,EAAE,MAAM,CAAC;IAIpB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;IAItE,EAAE,EAAE,MAAM,CAAC;IAIX,YAAY,EAAE,MAAM,CAAC;IAIrB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAInC,aAAa,CAAC,EAAE,SAAS,CAAC;IAI1B,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAIxC,WAAW,CAAC,EAAE,OAAO,CAAC;IAItB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;IAI3C,OAAO,EAAE,CAAC,EAAE,CAAC;IAIb,cAAc,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,mOAgB7C,sBAAsB,CAAC,CAAC,CAAC;;;;;;;;kCAqLW,CAAC,SAAS,MAAM,KAAG,gBAAgB;;CAqDzE,CAAC"}
+{"version":3,"file":"useAutocomplete.d.ts","sourceRoot":"","sources":["../src/useAutocomplete.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAC;AAE7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIxE,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC,GAAG;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;IACzE,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;CAC9E,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,MAAM,IAAI;IAIrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAInB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAI/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAI3B,UAAU,CAAC,EAAE,MAAM,CAAC;IAIpB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;IAItE,EAAE,EAAE,MAAM,CAAC;IAIX,YAAY,EAAE,MAAM,CAAC;IAIrB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAInC,aAAa,CAAC,EAAE,SAAS,CAAC;IAI1B,WAAW,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAIxD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAIxC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,SAAS,KAAK,SAAS,CAAC;IAIpF,cAAc,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IAI9D,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,SAAS,KAAK,SAAS,CAAC;IAIxF,WAAW,CAAC,EAAE,OAAO,CAAC;IAItB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;IAI3C,OAAO,EAAE,CAAC,EAAE,CAAC;IAIb,cAAc,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,gSAoB7C,sBAAsB,CAAC,CAAC,CAAC;;;;;;;;kCAyLW,CAAC,SAAS,MAAM,KAAG,gBAAgB;;CAqDzE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purpurds/autocomplete",
-  "version": "5.29.0",
+  "version": "5.30.1",
   "license": "AGPL-3.0-only",
   "main": "./dist/autocomplete.cjs.js",
   "types": "./dist/autocomplete.d.ts",
@@ -15,11 +15,13 @@
   "source": "src/autocomplete.tsx",
   "dependencies": {
     "classnames": "~2.5.0",
-    "@purpurds/icon": "5.29.0",
-    "@purpurds/listbox": "5.29.0",
-    "@purpurds/text-field": "5.29.0",
-    "@purpurds/tokens": "5.29.0",
-    "@purpurds/paragraph": "5.29.0"
+    "@purpurds/heading": "5.30.1",
+    "@purpurds/icon": "5.30.1",
+    "@purpurds/listbox": "5.30.1",
+    "@purpurds/text-field": "5.30.1",
+    "@purpurds/notification": "5.30.1",
+    "@purpurds/paragraph": "5.30.1",
+    "@purpurds/tokens": "5.30.1"
   },
   "devDependencies": {
     "@rushstack/eslint-patch": "~1.10.0",
@@ -45,10 +47,10 @@
     "typescript": "^5.6.3",
     "vite": "5.4.8",
     "vitest": "^2.1.2",
-    "@purpurds/button": "5.29.0",
+    "@purpurds/icon": "5.30.1",
+    "@purpurds/button": "5.30.1",
     "@purpurds/component-rig": "1.0.0",
-    "@purpurds/icon": "5.29.0",
-    "@purpurds/search-field": "5.29.0"
+    "@purpurds/search-field": "5.30.1"
   },
   "scripts": {
     "build:dev": "vite",

package/src/autocomplete.stories.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { Notification } from "@purpurds/notification";
 import { Paragraph } from "@purpurds/paragraph";
 import { SearchField } from "@purpurds/search-field";
 import { TextField } from "@purpurds/text-field";
@@ -10,6 +11,9 @@ import "@purpurds/button/styles";
 import "@purpurds/listbox/styles";
 import "@purpurds/search-field/styles";
 import "@purpurds/text-field/styles";
+import "@purpurds/notification/styles";
+import "@purpurds/paragraph/styles";
+import "@purpurds/heading/styles";
 import { Autocomplete } from "./autocomplete";
 
 const options = [
@@ -35,6 +39,22 @@ const options = [
   { id: "19", label: "Strawberry" },
 ];
 
+const OnInputEventPitfallNotification = () => (
+  <div style={{ marginTop: "var(--purpur-spacing-150)", marginRight: "-200px" }}>
+    <Notification status="warning" heading="Pitfall alert">
+      <Paragraph>
+        To handle input events, <b>always pass handlers to Autocomplete if defined</b> instead of
+        directly to the input. Autocomplete internally uses input events, and setting them yourself
+        will override the internal functionality.
+      </Paragraph>
+      <Paragraph style={{ marginTop: "var(--purpur-spacing-150)" }} variant="paragraph-100-bold">
+        This goes for <i>onInputChange</i>, <i>onInputKeyDown</i>, <i>onInputFocus</i>,{" "}
+        <i>onInputMouseDown</i> and <i>onInputBlur</i>.
+      </Paragraph>
+    </Notification>
+  </div>
+);
+
 const meta = {
   title: "Inputs/Autocomplete",
   component: Autocomplete,
@@ -108,20 +128,23 @@ export const WithTextField: Story = {
     const [{ selectedOption }, updateArgs] = useArgs(); // eslint-disable-line react-hooks/rules-of-hooks
 
     return (
-      <Autocomplete
-        {...args}
-        selectedOption={selectedOption}
-        onSelect={(selectedOption) => updateArgs({ selectedOption })}
-        renderInput={(inputProps) => (
-          <TextField
-            {...inputProps}
-            label="With Text Field"
-            id="autocomplete-input"
-            type="text"
-            placeholder="Enter a fruit"
-          />
-        )}
-      />
+      <>
+        <Autocomplete
+          {...args}
+          selectedOption={selectedOption}
+          onSelect={(selectedOption) => updateArgs({ selectedOption })}
+          renderInput={(inputProps) => (
+            <TextField
+              {...inputProps}
+              label="With Text Field"
+              id="autocomplete-input"
+              type="text"
+              placeholder="Enter a fruit"
+            />
+          )}
+        />
+        <OnInputEventPitfallNotification />
+      </>
     );
   },
   tags: ["visual:check"],
@@ -142,7 +165,14 @@ export const WithSearchField: Story = {
         code: `
           <Autocomplete        
   selectedOption={selectedOption}
-  onSelect={(selectedOption) => updateArgs({ selectedOption })}
+  /*
+   * NOTE! To handle input change events, always use onInputChange on Autocomplete instead of
+   * onChange on the input (SearchField). Autocomplete internally uses onChange on the input,
+   * and setting it yourself will override this.
+   */
+  onInputChange={(value) => {
+    setInputValue(value); 
+  }}
   renderInput={(inputProps) => (
     <SearchField
       {...inputProps}            
@@ -157,33 +187,36 @@ export const WithSearchField: Story = {
     const [{ selectedOption }, updateArgs] = useArgs(); // eslint-disable-line react-hooks/rules-of-hooks
 
     return (
-      <Autocomplete
-        {...args}
-        selectedOption={selectedOption}
-        onSelect={(selectedOption) => updateArgs({ selectedOption })}
-        onInputChange={(value) => {
-          setInputValue(value);
-          updateArgs({ selectedOption: undefined });
-        }}
-        inputValue={inputValue}
-        renderInput={(inputProps) => (
-          <SearchField
-            {...inputProps}
-            label="With Search Field"
-            id="autocomplete-input"
-            type="text"
-            onClear={() => {
-              setInputValue("");
-              updateArgs({ selectedOption: undefined });
-            }}
-            placeholder="Find your fruit"
-            clearButtonAllyLabel="Clear search field"
-            variant="button-attached"
-            iconOnlySearchButton
-            searchButtonLabel="Search"
-          />
-        )}
-      />
+      <>
+        <Autocomplete
+          {...args}
+          selectedOption={selectedOption}
+          onSelect={(selectedOption) => updateArgs({ selectedOption })}
+          onInputChange={(value) => {
+            setInputValue(value);
+            updateArgs({ selectedOption: undefined });
+          }}
+          inputValue={inputValue}
+          renderInput={(inputProps) => (
+            <SearchField
+              {...inputProps}
+              label="With Search Field"
+              id="autocomplete-input"
+              type="text"
+              onClear={() => {
+                setInputValue("");
+                updateArgs({ selectedOption: undefined });
+              }}
+              placeholder="Find your fruit"
+              clearButtonAllyLabel="Clear search field"
+              variant="button-attached"
+              iconOnlySearchButton
+              searchButtonLabel="Search"
+            />
+          )}
+        />
+        <OnInputEventPitfallNotification />
+      </>
     );
   },
   tags: ["visual:check"],

package/src/autocomplete.test.tsx

@@ -643,4 +643,27 @@ describe("B2xAutocomplete", () => {
       expect(input.value).toEqual(options[0].label);
     });
   });
+
+  it.each([["focus" as const], ["blur" as const], ["keyDown" as const], ["mouseDown" as const]])(
+    "should invoke onInput correctly: %s",
+    async (eventName) => {
+      const onInputEventMock = vi.fn();
+      const onInputEventPropName = `onInput${eventName[0].toUpperCase()}${eventName.slice(1)}`;
+      render(
+        <Autocomplete
+          options={options}
+          id="test-id"
+          data-testid="test-id"
+          listboxLabel="Options"
+          renderInput={(props) => <input {...props} data-testid="autocomplete-input" />}
+          {...{ [onInputEventPropName]: onInputEventMock }}
+        />
+      );
+
+      const input: HTMLInputElement = screen.getByTestId("autocomplete-input");
+      fireEvent[eventName](input);
+
+      expect(onInputEventMock).toBeCalledTimes(1);
+    }
+  );
 });

package/src/autocomplete.tsx

@@ -76,8 +76,8 @@ const AutocompleteComponent = <T extends Option>(
             type="button"
             className={cx(`${rootClassName}__chevron-button`)}
             onClick={() => {
-              inputProps.onFocus();
-              inputProps.onMouseDown();
+              inputProps.onFocus(undefined);
+              inputProps.onMouseDown(undefined);
             }}
             aria-hidden="true"
           >

package/src/useAutocomplete.ts

@@ -13,8 +13,8 @@ export type Option = {
 
 export type InputProps = Omit<ComponentPropsWithRef<"input">, "onFocus" | "onMouseDown"> & {
   "data-testid"?: string;
-  onFocus: () => void;
-  onMouseDown: () => void;
+  onFocus: (event: React.FocusEvent<HTMLInputElement> | undefined) => void;
+  onMouseDown: (event: React.MouseEvent<HTMLInputElement> | undefined) => void;
 };
 
 export type UseAutocompleteOptions<T extends Option> = {
@@ -55,9 +55,25 @@ export type UseAutocompleteOptions<T extends Option> = {
    */
   noOptionsText?: ReactNode;
   /*
-   * Event handler invoked when the input value changes.
+   * NOTE! Always use this instead of onBlur directly on the input element. Event handler invoked on input blur.
+   */
+  onInputBlur?: React.FocusEventHandler<HTMLInputElement>;
+  /*
+   * NOTE! Always use this instead of onChange directly on the input element. Event handler invoked when the input value changes.
    */
   onInputChange?: (value: string) => void;
+  /*
+   * NOTE! Always use this instead of onFocus directly on the input element. Event handler invoked on input focus.
+   */
+  onInputFocus?: (event: React.FocusEvent<HTMLInputElement> | undefined) => undefined;
+  /*
+   * NOTE! Always use this instead of onKeyDown directly on the input element. Event handler invoked on input key down.
+   */
+  onInputKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+  /*
+   * NOTE! Always use this instead of onMouseDown directly on the input element. Event handler invoked on input mouse down.
+   */
+  onInputMouseDown?: (event: React.MouseEvent<HTMLInputElement> | undefined) => undefined;
   /*
    * Set to open the listbox when input gets focus.
    */
@@ -86,7 +102,11 @@ export const useAutocomplete = <T extends Option>({
   id,
   listboxLabel,
   listboxMaxHeight,
+  onInputBlur,
   onInputChange,
+  onInputFocus,
+  onInputKeyDown,
+  onInputMouseDown,
   openOnFocus,
   noOptionsText,
   onSelect,
@@ -204,12 +224,13 @@ export const useAutocomplete = <T extends Option>({
     nextOption && scrollOptionIntoView(optionRefs.current[nextOption.id]);
   };
 
-  const handleOnKeyDown: React.KeyboardEventHandler<HTMLInputElement> = (e) => {
-    switch (e.key) {
+  const handleOnKeyDown: React.KeyboardEventHandler<HTMLInputElement> = (event) => {
+    onInputKeyDown?.(event);
+    switch (event.key) {
       case "ArrowUp":
       case "ArrowDown":
-        e.preventDefault(); // Preventing default to not move cursor in input
-        highlightNextOption(e.key);
+        event.preventDefault(); // Preventing default to not move cursor in input
+        highlightNextOption(event.key);
         break;
       case "Enter": {
         const optionToSelect = highlightedOption || (highlightFirstOption ? options[0] : undefined);
@@ -234,16 +255,19 @@ export const useAutocomplete = <T extends Option>({
       scrollOptionIntoView(optionRefs.current[nextOptionsToShow[0].id]);
   };
 
-  const handleOnMouseDown = () => {
+  const handleOnMouseDown = (event: React.MouseEvent<HTMLInputElement> | undefined) => {
+    onInputMouseDown?.(event);
     showListbox ? closeListbox() : openListbox({ eventType: "CLICK" });
   };
 
-  const handleOnFocus = () => {
+  const handleOnFocus = (event: React.FocusEvent<HTMLInputElement> | undefined) => {
+    onInputFocus?.(event);
     !listboxIsOpen && openOnFocus && openListbox({ eventType: "KEYBOARD" });
     inputRef.current?.select();
   };
 
-  const handleOnBlur = () => {
+  const handleOnBlur: React.FocusEventHandler<HTMLInputElement> = (event) => {
+    onInputBlur?.(event);
     if (combobox) {
       // Use a timeout to allow click events on the listbox to fire before this check
       setTimeout(() => {