@bloomreach/react-banana-ui 1.43.0 → 1.44.0

package/dist/src/components/inputs/autocomplete/autocomplete.filters.d.ts

@@ -0,0 +1,6 @@
+import { FilterOptionsState } from '@mui/base';
+/**
+ * A `filterOptions` implementation that returns all options unchanged.
+ * Used to bypass client-side filtering when options are already filtered by a server/API.
+ */
+export declare function passthroughFilter<AutocompleteOption>(options: AutocompleteOption[], _state: FilterOptionsState<AutocompleteOption>): AutocompleteOption[];

package/dist/src/components/inputs/autocomplete/autocomplete.qa.stories.d.ts

@@ -1,5 +1,5 @@
 import { default as Autocomplete } from './autocomplete';
-import { ControlledMultipleValue as ControlledMultipleValueStory, ControlledSingleValue as ControlledSingleValueStory, CustomOptionLabel as CustomOptionLabelStory, FreeSoloMultiple as FreeSoloMultipleStory, FreeSoloSingle as FreeSoloSingleStory, HideSelectedOptions as HideSelectedOptionsStory, Multiple as MultipleStory, PasteMultipleValues as PasteMultipleValuesStory, PasteWithFreeSolo as PasteWithFreeSoloStory, Story } from './autocomplete.stories';
+import { AsyncLoadOptionsFreeSolo as AsyncLoadOptionsFreeSoloStory, AsyncLoadOptionsMinInputLength as AsyncLoadOptionsMinInputLengthStory, AsyncLoadOptionsMultiple as AsyncLoadOptionsMultipleStory, AsyncLoadOptions as AsyncLoadOptionsStory, AsyncLoadOptionsWithPostFilter as AsyncLoadOptionsWithPostFilterStory, ControlledMultipleValue as ControlledMultipleValueStory, ControlledSingleValue as ControlledSingleValueStory, CustomOptionLabel as CustomOptionLabelStory, DisableClientFilter as DisableClientFilterStory, FreeSoloMultiple as FreeSoloMultipleStory, FreeSoloSingle as FreeSoloSingleStory, HideSelectedOptions as HideSelectedOptionsStory, Multiple as MultipleStory, PasteMultipleValues as PasteMultipleValuesStory, PasteWithFreeSolo as PasteWithFreeSoloStory, Story } from './autocomplete.stories';
 import { Meta } from '@storybook/react-vite';
 declare const meta: Meta<typeof Autocomplete>;
 export default meta;
@@ -27,3 +27,9 @@ export declare const CustomOptionRendering: Story<{
 }, true, true>;
 export declare const PasteMultipleValues: typeof PasteMultipleValuesStory;
 export declare const PasteWithFreeSolo: typeof PasteWithFreeSoloStory;
+export declare const DisableClientFilter: typeof DisableClientFilterStory;
+export declare const AsyncLoadOptions: typeof AsyncLoadOptionsStory;
+export declare const AsyncLoadOptionsMultiple: typeof AsyncLoadOptionsMultipleStory;
+export declare const AsyncLoadOptionsMinInputLength: typeof AsyncLoadOptionsMinInputLengthStory;
+export declare const AsyncLoadOptionsWithPostFilter: typeof AsyncLoadOptionsWithPostFilterStory;
+export declare const AsyncLoadOptionsFreeSolo: typeof AsyncLoadOptionsFreeSoloStory;

package/dist/src/components/inputs/autocomplete/autocomplete.stories.d.ts

@@ -61,3 +61,18 @@ export declare const PasteWithRegexDelimiter: Story<string, true>;
 export declare const WithLeftElement: Story;
 export declare const WithRightElement: Story;
 export declare const WithBothElements: Story;
+/**
+ * Server returns valid options for "india kar", but default client filter hides them
+ * because labels don't contain "kar".
+ */
+export declare const ServerFilterComparison: Story;
+/**
+ * Consumer-managed API fetch with disableClientFilter.
+ */
+export declare const ConsumerManagedApiFetch: Story;
+export declare const DisableClientFilter: Story;
+export declare const AsyncLoadOptions: Story;
+export declare const AsyncLoadOptionsMultiple: Story<string, true>;
+export declare const AsyncLoadOptionsMinInputLength: Story;
+export declare const AsyncLoadOptionsWithPostFilter: Story;
+export declare const AsyncLoadOptionsFreeSolo: Story<string, false, true>;

package/dist/src/components/inputs/autocomplete/autocomplete.types.d.ts

@@ -29,18 +29,38 @@ export interface AutocompleteProps<AutocompleteOption extends NonNullable<unknow
      * It is `false` by default when `multiple` is `true`.
      */
     closeOnSelect?: boolean;
+    /**
+     * Milliseconds to debounce `loadOptions` calls after the user types.
+     * Only applies when `loadOptions` is provided.
+     * @default 300
+     */
+    debounceMs?: number;
     /**
      * The default selected value. Use when the component is not controlled.
      * The value must be an array when `multiple` is `true`.
      */
     defaultValue?: AutocompleteValue<AutocompleteOption, Multiple, FreeSolo>;
+    /**
+     * If `true`, client-side filtering is disabled and all provided options are shown.
+     * Use when options are already filtered by a server/API.
+     * Automatically enabled when `loadOptions` is provided unless `filterOptions` is set.
+     * @default false
+     */
+    disableClientFilter?: boolean;
     /**
      * If `true`, the component is disabled.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Text shown in the dropdown when `loadOptions` rejects.
+     * @default "Failed to load options"
+     */
+    errorText?: string;
     /**
      * Filter function to determine which options to show based on user input.
+     * When `disableClientFilter` is `true` or `loadOptions` is provided, defaults to showing all options.
+     * Use this to post-process options returned from an API.
      * @param options The array of options to filter
      * @param state The current state of the autocomplete
      */
@@ -111,11 +131,24 @@ export interface AutocompleteProps<AutocompleteOption extends NonNullable<unknow
      * @default "Loading..."
      */
     loadingText?: string;
+    /**
+     * Async callback to load options based on the current input value.
+     * When provided, the component manages debouncing, loading state, and request cancellation.
+     * Client-side filtering is disabled by default; use `filterOptions` to post-process API results.
+     */
+    loadOptions?: (inputValue: string, context: AutocompleteLoadOptionsContext) => Promise<AutocompleteOption[]>;
     /**
      * The maximum number of visible tag rows before the tag area becomes scrollable while the popup is closed.
      * Only works when `multiple` is `true`.
      */
     maxRows?: number;
+    /**
+     * Minimum number of trimmed characters required before `loadOptions` is called.
+     * Set to `0` to load on popup open / empty input (e.g. to show default suggestions).
+     * Only applies when `loadOptions` is provided.
+     * @default 1
+     */
+    minInputLength?: number;
     /**
      * If `true`, the component allows multiple selections.
      * @default false
@@ -141,6 +174,10 @@ export interface AutocompleteProps<AutocompleteOption extends NonNullable<unknow
      * @param reason The reason for the input change ('input' | 'reset' | 'clear')
      */
     onInputChange?: (event: SyntheticEvent, value: string, reason?: string) => void;
+    /**
+     * Callback fired when `loadOptions` rejects.
+     */
+    onLoadOptionsError?: (error: unknown) => void;
     /**
      * Callback fired when the popup opens.
      */
@@ -166,7 +203,7 @@ export interface AutocompleteProps<AutocompleteOption extends NonNullable<unknow
      */
     onTagClick?: (event: SyntheticEvent, option: AutocompleteOption, index: number) => void;
     /**
-     * Array ot options to display.
+     * Array of options to display.
      */
     options: AutocompleteOption[];
     /**
@@ -246,6 +283,12 @@ export interface AutocompleteProps<AutocompleteOption extends NonNullable<unknow
      */
     width?: number | string;
 }
+export interface AutocompleteLoadOptionsContext {
+    /**
+     * AbortSignal to cancel the request when the input changes or the component unmounts.
+     */
+    signal: AbortSignal;
+}
 export interface AutocompleteRenderGroupParams extends AutocompleteGroupedOption<object> {
     children: ReactNode;
 }

package/dist/src/components/inputs/autocomplete/index.d.ts

@@ -1,2 +1,2 @@
 export { default as Autocomplete } from './autocomplete';
-export type { AutocompleteProps } from './autocomplete.types';
+export type { AutocompleteLoadOptionsContext, AutocompleteProps } from './autocomplete.types';

package/dist/src/components/inputs/autocomplete/use-load-options.d.ts

@@ -0,0 +1,22 @@
+import { AutocompleteLoadOptionsContext } from './autocomplete.types';
+export interface UseLoadOptionsParams<AutocompleteOption> {
+    debounceMs?: number;
+    loadOptions?: (inputValue: string, context: AutocompleteLoadOptionsContext) => Promise<AutocompleteOption[]>;
+    minInputLength?: number;
+    onLoadOptionsError?: (error: unknown) => void;
+}
+export interface TriggerLoadOptions {
+    /**
+     * When `true`, reuse the last successful fetch for the same input instead of calling `loadOptions` again.
+     * Used when the popup opens on refocus.
+     */
+    useCache?: boolean;
+}
+export interface UseLoadOptionsResult<AutocompleteOption> {
+    asyncOptions: AutocompleteOption[];
+    clearCache: () => void;
+    internalLoading: boolean;
+    loadError: boolean;
+    triggerLoad: (inputValue: string, options?: TriggerLoadOptions) => void;
+}
+export declare function useLoadOptions<AutocompleteOption>(params: UseLoadOptionsParams<AutocompleteOption>): UseLoadOptionsResult<AutocompleteOption>;

package/dist/src/components/inputs/autocomplete-field/autocomplete-field.stories.d.ts

@@ -16,6 +16,7 @@ export declare const ControlledSingleValue: Story;
 export declare const Multiple: Story<(typeof fruits)[0], true>;
 export declare const DefaultValueMultiple: Story<(typeof fruits)[0], true>;
 export declare const ControlledMultipleValue: Story<(typeof fruits)[0], true>;
+export declare const SelectableTags: Story<(typeof fruits)[0], true>;
 export declare const Clearable: Story;
 export declare const Disabled: Story;
 export declare const DisabledMultiple: Story<(typeof fruits)[0], true>;
@@ -42,3 +43,8 @@ export declare const CustomOptionRendering: Story<{
 export declare const FieldsInColumn: Story;
 export declare const FieldsInRow: Story;
 export declare const PasteWithRegexDelimiter: Story<string, true>;
+export declare const DisableClientFilter: Story;
+export declare const ConsumerManagedApiFetch: Story;
+export declare const AsyncLoadOptions: Story;
+export declare const AsyncLoadOptionsMultiple: Story<string, true>;
+export declare const AsyncLoadOptionsFreeSolo: Story<string, false, true>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bloomreach/react-banana-ui",
   "type": "module",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "private": false,
   "repository": {
     "type": "git",