@stackline/react-multiselect-dropdown 18.0.0 → 18.0.1

package/dist/index.d.cts

@@ -1,7 +1,20 @@
-import { CSSProperties, ReactNode, ForwardedRef, ReactElement } from 'react';
+import { CSSProperties, ReactNode, HTMLAttributes, Ref, AriaAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ForwardedRef, ReactElement } from 'react';
 
 type PrimitiveItem = string | number | boolean;
 type DropdownItem = PrimitiveItem | Record<string, any>;
+type DropdownItemKey<T = DropdownItem> = T extends PrimitiveItem ? string : Extract<keyof T, string>;
+type DropdownSpaceOptionAction = 'toggle' | 'toggle-and-next';
+interface DropdownKeyboardSettings {
+    space?: boolean;
+    spaceOptionAction?: DropdownSpaceOptionAction;
+    tab?: boolean;
+    arrows?: boolean;
+    escape?: boolean;
+    backspaceRemovesLastWhenSearchEmpty?: boolean;
+    deleteRemovesFocusedBadge?: boolean;
+    /** @deprecated Use `backspaceRemovesLastWhenSearchEmpty` instead. */
+    backspace?: boolean;
+}
 interface DropdownSettings<T = DropdownItem> {
     singleSelection?: boolean;
     text?: string;
@@ -12,20 +25,20 @@ interface DropdownSettings<T = DropdownItem> {
     filterUnSelectAllText?: string;
     enableFilterSelectAll?: boolean;
     enableSearchFilter?: boolean;
-    searchBy?: string[];
+    searchBy?: DropdownItemKey<T>[];
     maxHeight?: number;
     badgeShowLimit?: number;
     classes?: string;
     limitSelection?: number;
     disabled?: boolean;
     searchPlaceholderText?: string;
-    groupBy?: string | ((item: T) => string);
+    groupBy?: DropdownItemKey<T> | ((item: T) => string);
     showCheckbox?: boolean;
     noDataLabel?: string;
     searchAutofocus?: boolean;
     lazyLoading?: boolean;
-    labelKey?: string;
-    primaryKey?: string;
+    labelKey?: DropdownItemKey<T>;
+    primaryKey?: DropdownItemKey<T>;
     position?: 'top' | 'bottom';
     autoPosition?: boolean;
     loading?: boolean;
@@ -49,7 +62,11 @@ interface DropdownSettings<T = DropdownItem> {
     openDropdownAriaLabel?: string;
     closeDropdownAriaLabel?: string;
     loadingText?: string;
+    keyboard?: DropdownKeyboardSettings;
 }
+type ResolvedDropdownSettings<T = DropdownItem> = Required<Omit<DropdownSettings<T>, 'keyboard'>> & {
+    keyboard: Required<DropdownKeyboardSettings>;
+};
 interface DropdownRenderContext<T = DropdownItem> {
     item: T;
     label: string;
@@ -59,6 +76,208 @@ interface DropdownRenderContext<T = DropdownItem> {
     toggle: () => void;
     remove: () => void;
 }
+interface MultiSelectDropdownSlotActions<T = DropdownItem> {
+    openDropdown: () => void;
+    closeDropdown: () => void;
+    toggleDropdown: () => void;
+    clearSelection: () => void;
+    selectItem: (item: T) => void;
+    removeItem: (item: T) => void;
+    selectAll: (items?: T[]) => void;
+    deSelectAll: (items?: T[]) => void;
+    toggleGroup: (groupName: string, items: T[]) => void;
+    addFilterNewItem: () => Promise<void>;
+    setFilter: (value: string) => void;
+}
+interface MultiSelectDropdownSlotState<T = DropdownItem> {
+    settings: ResolvedDropdownSettings<T>;
+    isOpen: boolean;
+    filter: string;
+    selectedItems: T[];
+    visibleBadges: T[];
+    hiddenBadgeCount: number;
+    filteredItems: T[];
+    selectableItems: T[];
+    allFilteredSelected: boolean;
+    hasFilteredResults: boolean;
+    loading: boolean;
+    listboxId: string;
+    activeDescendantId?: string;
+    label: string;
+}
+interface MultiSelectDropdownSlotBase<T = DropdownItem> {
+    state: MultiSelectDropdownSlotState<T>;
+    actions: MultiSelectDropdownSlotActions<T>;
+}
+interface MultiSelectDropdownOptionSlot<T = DropdownItem> {
+    item: T;
+    id: string;
+    key: string;
+    label: string;
+    selected: boolean;
+    disabled: boolean;
+    index: number;
+    groupName?: string;
+}
+interface MultiSelectDropdownGroupSlot<T = DropdownItem> {
+    name: string;
+    items: T[];
+    enabledItems: T[];
+    selected: boolean;
+    disabled: boolean;
+    index: number;
+}
+type MultiSelectDropdownSlotComponent<P> = (props: P) => ReactNode;
+interface MultiSelectDropdownSlots<T = DropdownItem> {
+    Root?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement> & {
+            ref: Ref<HTMLDivElement>;
+        };
+        children: ReactNode;
+    }>;
+    Trigger?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement> & AriaAttributes & {
+            ref: Ref<HTMLDivElement>;
+        };
+        children: ReactNode;
+    }>;
+    Value?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        children: ReactNode;
+    }>;
+    Placeholder?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLSpanElement>;
+        text: string;
+    }>;
+    SingleValue?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLSpanElement>;
+        item: T;
+        label: string;
+    }>;
+    BadgeList?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        items: T[];
+        children: ReactNode;
+    }>;
+    Badge?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLSpanElement>;
+        item: T;
+        label: string;
+        children: ReactNode;
+        removeButton: ReactNode;
+    }>;
+    BadgeLabel?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLSpanElement>;
+        item: T;
+        label: string;
+        children: ReactNode;
+    }>;
+    BadgeRemove?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: ButtonHTMLAttributes<HTMLButtonElement>;
+        item: T;
+        label: string;
+        icon: ReactNode;
+    }>;
+    Actions?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        children: ReactNode;
+    }>;
+    OverflowCounter?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLSpanElement>;
+        count: number;
+    }>;
+    ClearAll?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: ButtonHTMLAttributes<HTMLButtonElement>;
+        icon: ReactNode;
+    }>;
+    Arrow?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: ButtonHTMLAttributes<HTMLButtonElement> & AriaAttributes;
+        icon: ReactNode;
+        direction: 'up' | 'down';
+    }>;
+    Menu?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement> & {
+            ref: Ref<HTMLDivElement>;
+        };
+        children: ReactNode;
+        position: 'top' | 'bottom';
+        appendToBody: boolean;
+    }>;
+    Toolbar?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        children: ReactNode;
+    }>;
+    BulkActions?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        children: ReactNode;
+    }>;
+    SelectAll?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: ButtonHTMLAttributes<HTMLButtonElement>;
+        checked: boolean;
+        label: string;
+        checkbox: ReactNode;
+    }>;
+    AddNewItem?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: ButtonHTMLAttributes<HTMLButtonElement>;
+        query: string;
+        label: string;
+    }>;
+    Search?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        inputProps: InputHTMLAttributes<HTMLInputElement> & {
+            ref: Ref<HTMLInputElement>;
+        };
+        clearButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
+        query: string;
+        icon: ReactNode;
+        clearIcon: ReactNode;
+    }>;
+    OptionList?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement> & AriaAttributes & {
+            ref: Ref<HTMLDivElement>;
+        };
+        children: ReactNode;
+    }>;
+    Group?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement> & AriaAttributes;
+        group: MultiSelectDropdownGroupSlot<T>;
+        header: ReactNode;
+        children: ReactNode;
+    }>;
+    GroupHeader?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        group: MultiSelectDropdownGroupSlot<T>;
+        action: ReactNode;
+    }>;
+    GroupAction?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: ButtonHTMLAttributes<HTMLButtonElement>;
+        group: MultiSelectDropdownGroupSlot<T>;
+        label: string;
+    }>;
+    Option?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement> & AriaAttributes;
+        option: MultiSelectDropdownOptionSlot<T>;
+        checkbox: ReactNode;
+        children: ReactNode;
+    }>;
+    Checkbox?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLSpanElement>;
+        checked: boolean;
+        context: 'option' | 'selectAll';
+    }>;
+    LoadingState?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        text: string;
+    }>;
+    EmptyState?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+        query: string;
+        text: string;
+    }>;
+    MenuFooter?: MultiSelectDropdownSlotComponent<MultiSelectDropdownSlotBase<T> & {
+        props: HTMLAttributes<HTMLDivElement>;
+    }>;
+}
 interface MultiSelectDropdownHandle<T = DropdownItem> {
     openDropdown: () => void;
     closeDropdown: () => void;
@@ -102,6 +321,112 @@ interface MultiSelectDropdownProps<T = DropdownItem> {
         closeDropdown: () => void;
     }) => ReactNode;
     renderEmptyState?: (query: string) => ReactNode;
+    slots?: MultiSelectDropdownSlots<T>;
+}
+interface HeadlessDropdownOption<T = DropdownItem> {
+    item: T;
+    key: string;
+    id: string;
+    label: string;
+    selected: boolean;
+    disabled: boolean;
+    index: number;
+    groupName?: string;
+}
+interface HeadlessDropdownGroup<T = DropdownItem> {
+    name: string;
+    items: HeadlessDropdownOption<T>[];
+    selected: boolean;
+    disabled: boolean;
+}
+interface UseMultiSelectDropdownProps<T = DropdownItem> extends Omit<MultiSelectDropdownProps<T>, 'className' | 'style' | 'renderItem' | 'renderBadge' | 'renderSearch' | 'renderEmptyState'> {
+    id?: string;
+}
+interface UseMultiSelectStateProps<T = DropdownItem> extends Omit<MultiSelectDropdownProps<T>, 'className' | 'style' | 'loading' | 'renderItem' | 'renderBadge' | 'renderSearch' | 'renderEmptyState'> {
+    onSelectionShouldClose?: () => void;
+}
+interface UseMultiSelectStateReturn<T = DropdownItem> {
+    settings: ResolvedDropdownSettings<T>;
+    filter: string;
+    setFilter: (value: string) => void;
+    selectedItems: T[];
+    allItems: T[];
+    filteredItems: T[];
+    selectableItems: T[];
+    visibleBadges: T[];
+    hiddenBadgeCount: number;
+    allFilteredSelected: boolean;
+    isSelected: (item: T) => boolean;
+    isDisabled: (item: T) => boolean;
+    getItemLabel: (item: T) => string;
+    getItemKey: (item: T) => string;
+    selectItem: (item: T) => void;
+    removeItem: (item: T) => void;
+    removeLastSelectedItem: () => void;
+    selectAll: (items?: T[], filteredSelection?: boolean) => void;
+    deSelectAll: (items?: T[], filteredSelection?: boolean) => void;
+    clearSelection: () => void;
+    toggleGroup: (groupName: string, items: T[]) => void;
+    addFilterNewItem: () => Promise<void>;
+}
+interface UseMultiSelectDropdownReturn<T = DropdownItem> {
+    settings: ResolvedDropdownSettings<T>;
+    isOpen: boolean;
+    filter: string;
+    setFilter: (value: string) => void;
+    selectedItems: T[];
+    selectedOptions: HeadlessDropdownOption<T>[];
+    options: HeadlessDropdownOption<T>[];
+    groups: HeadlessDropdownGroup<T>[];
+    visibleOptions: HeadlessDropdownOption<T>[];
+    visibleBadges: T[];
+    hiddenBadgeCount: number;
+    allFilteredSelected: boolean;
+    hasFilteredResults: boolean;
+    activeDescendantId?: string;
+    listboxId: string;
+    label: string;
+    openDropdown: () => void;
+    closeDropdown: () => void;
+    toggleDropdown: () => void;
+    clearSelection: () => void;
+    selectItem: (item: T) => void;
+    removeItem: (item: T) => void;
+    selectAll: (items?: T[]) => void;
+    deSelectAll: (items?: T[]) => void;
+    toggleGroup: (groupName: string, items: T[]) => void;
+    addFilterNewItem: () => Promise<void>;
+    isSelected: (item: T) => boolean;
+    isDisabled: (item: T) => boolean;
+    getItemLabel: (item: T) => string;
+    getItemKey: (item: T) => string;
+    getRootProps: <E extends HTMLElement = HTMLDivElement>(props?: HTMLAttributes<E> & {
+        ref?: Ref<E>;
+    }) => HTMLAttributes<E> & {
+        ref: (node: E | null) => void;
+    };
+    getTriggerProps: <E extends HTMLElement = HTMLButtonElement>(props?: ButtonHTMLAttributes<E> & {
+        ref?: Ref<E>;
+    }) => ButtonHTMLAttributes<E> & AriaAttributes & {
+        ref: (node: E | null) => void;
+    };
+    getListboxProps: <E extends HTMLElement = HTMLDivElement>(props?: HTMLAttributes<E> & {
+        ref?: Ref<E>;
+    }) => HTMLAttributes<E> & AriaAttributes & {
+        ref: (node: E | null) => void;
+    };
+    getOptionProps: <E extends HTMLElement = HTMLDivElement>(optionOrItem: HeadlessDropdownOption<T> | T, props?: HTMLAttributes<E> & {
+        ref?: Ref<E>;
+    }) => HTMLAttributes<E> & AriaAttributes & {
+        ref: (node: E | null) => void;
+    };
+    getSearchInputProps: <E extends HTMLInputElement = HTMLInputElement>(props?: InputHTMLAttributes<E> & {
+        ref?: Ref<E>;
+    }) => InputHTMLAttributes<E> & AriaAttributes & {
+        ref: (node: E | null) => void;
+    };
+    getClearAllButtonProps: <E extends HTMLElement = HTMLButtonElement>(props?: ButtonHTMLAttributes<E>) => ButtonHTMLAttributes<E> & AriaAttributes;
+    getRemoveButtonProps: <E extends HTMLElement = HTMLButtonElement>(item: T, props?: ButtonHTMLAttributes<E>) => ButtonHTMLAttributes<E> & AriaAttributes;
 }
 
 type MultiSelectComponent = <T extends DropdownItem = DropdownItem>(props: MultiSelectDropdownProps<T> & {
@@ -110,4 +435,21 @@ type MultiSelectComponent = <T extends DropdownItem = DropdownItem>(props: Multi
 declare const ReactMultiSelectDropdown: MultiSelectComponent;
 declare const MultiSelectDropdown: MultiSelectComponent;
 
-export { type DropdownItem, type DropdownRenderContext, type DropdownSettings, MultiSelectDropdown, type MultiSelectDropdownHandle, type MultiSelectDropdownProps, type PrimitiveItem, ReactMultiSelectDropdown };
+declare function useMultiSelectDropdown<T extends DropdownItem = DropdownItem>({ id, data, settings: incomingSettings, selectedItems: controlledSelectedItems, defaultSelectedItems, onChange, onSelect, onDeSelect, onSelectAll, onDeSelectAll, onOpen, onClose, onScrollToEnd, onFilterSelectAll, onFilterDeSelectAll, onAddFilterNewItem, onGroupSelect, onGroupDeSelect }: UseMultiSelectDropdownProps<T>): UseMultiSelectDropdownReturn<T>;
+
+declare function useMultiSelectState<T extends DropdownItem = DropdownItem>({ data, settings: incomingSettings, selectedItems: controlledSelectedItems, defaultSelectedItems, onChange, onSelect, onDeSelect, onSelectAll, onDeSelectAll, onFilterSelectAll, onFilterDeSelectAll, onAddFilterNewItem, onGroupSelect, onGroupDeSelect, onSelectionShouldClose }: UseMultiSelectStateProps<T>): UseMultiSelectStateReturn<T>;
+
+type TypedMultiSelectDropdownComponent<T extends DropdownItem> = (props: MultiSelectDropdownProps<T> & {
+    ref?: ForwardedRef<MultiSelectDropdownHandle<T>>;
+}) => ReactElement | null;
+interface TypedMultiSelectDropdownFamily<T extends DropdownItem> {
+    Dropdown: TypedMultiSelectDropdownComponent<T>;
+    MultiSelectDropdown: TypedMultiSelectDropdownComponent<T>;
+    useDropdown: (props: UseMultiSelectDropdownProps<T>) => UseMultiSelectDropdownReturn<T>;
+    useSelectionState: (props: UseMultiSelectStateProps<T>) => UseMultiSelectStateReturn<T>;
+    defineSettings: (settings: DropdownSettings<T>) => DropdownSettings<T>;
+    defineSlots: (slots: MultiSelectDropdownSlots<T>) => MultiSelectDropdownSlots<T>;
+}
+declare function createMultiSelectDropdown<T extends DropdownItem = never>(): TypedMultiSelectDropdownFamily<T>;
+
+export { type DropdownItem, type DropdownItemKey, type DropdownKeyboardSettings, type DropdownRenderContext, type DropdownSettings, type DropdownSpaceOptionAction, type HeadlessDropdownGroup, type HeadlessDropdownOption, MultiSelectDropdown, type MultiSelectDropdownGroupSlot, type MultiSelectDropdownHandle, type MultiSelectDropdownOptionSlot, type MultiSelectDropdownProps, type MultiSelectDropdownSlotActions, type MultiSelectDropdownSlotBase, type MultiSelectDropdownSlotComponent, type MultiSelectDropdownSlotState, type MultiSelectDropdownSlots, type PrimitiveItem, ReactMultiSelectDropdown, type ResolvedDropdownSettings, type TypedMultiSelectDropdownComponent, type TypedMultiSelectDropdownFamily, type UseMultiSelectDropdownProps, type UseMultiSelectDropdownReturn, type UseMultiSelectStateProps, type UseMultiSelectStateReturn, createMultiSelectDropdown, useMultiSelectDropdown, useMultiSelectState };