@box/user-selector 2.2.23 → 3.0.0

package/dist/chunks/user-selector.js

@@ -1 +1 @@
-import{t as buildOptionsWithOverlay}from"./buildOptionsWithOverlay.js";import messages from"../esm/lib/messages.js";import{t as UserSelectorComboboxOption}from"./user-selector-list-item.js";import{isUserContactType}from"../esm/lib/utils/isUserContactType.js";import{defaultRenderCustomOption}from"../esm/lib/utils/defaultRenderCustomOption.js";import{getInitials}from"../esm/lib/utils/getInitials.js";import{forwardRef,useCallback}from"react";import clsx from"clsx";import{useIntl}from"react-intl";import{Avatar,Combobox,Divider,IconBadge,Text}from"@box/blueprint-web";import{ComboboxWithApi}from"@box/combobox-with-api";import{jsx}from"react/jsx-runtime";import '../styles/user-selector.css';var user_selector_module_default={overlayHeader:`_overlayHeader_u0715_1`,overlaySeparatorOption:`_overlaySeparatorOption_u0715_8`,textArea:`_textArea_u0715_15`},UserSelector=forwardRef((props,forwardedRef)=>{let{fetchedAvatarUrls,fetchUsers,onSelectedUsersChange,selectedUsers,variant,className,defaultOptions,overlayDividerIndex,overlayTitle,renderCustomOption=defaultRenderCustomOption,...rest}=props,intl=useIntl(),renderAvatar=option=>{if(!(option.value===`__combobox_overlay_header__`||option.value===`__combobox_overlay_separator__`)){if(isUserContactType(option)){let{name,isExternalUser,id}=option,avatar=jsx(Avatar,{alt:intl.formatMessage(messages.userAvatar),colorIndex:id,src:fetchedAvatarUrls[id],text:getInitials(name)});return isExternalUser?jsx(IconBadge,{offset:{right:-4,bottom:-2},size:`medium`,variant:`collaborator-external`,children:avatar}):avatar}return jsx(Avatar,{...option.avatar})}},displayChipVariant=option=>{if(!isUserContactType(option))return option.chipVariant},fetcherWithOverlay=useCallback(async inputValue=>{let options=await fetchUsers(inputValue);if(!overlayTitle||overlayDividerIndex==null||overlayDividerIndex<0)return options;let selectedValues=new Set(selectedUsers.map(s=>s.value)),visibleOptions=options.filter(opt=>!selectedValues.has(opt.value)),beforeCount=options.slice(0,overlayDividerIndex+1).filter(opt=>!selectedValues.has(opt.value)).length;return buildOptionsWithOverlay(visibleOptions,overlayTitle,beforeCount>0?beforeCount-1:-1)},[fetchUsers,overlayTitle,overlayDividerIndex,selectedUsers]);return jsx(ComboboxWithApi,{as:`input`,className:clsx(className,variant===`textarea`&&user_selector_module_default.textArea),defaultOptions,displayAvatar:renderAvatar,displayChipVariant,displayValue:option=>option.name,fetcher:fetcherWithOverlay,freeInput:!1,loadingAriaLabel:intl.formatMessage(messages.loading),multiselect:!0,noResultMessage:intl.formatMessage(messages.noResults),onValueChange:onSelectedUsersChange,renderOption:option=>option.value===`__combobox_overlay_header__`&&`label`in option?jsx(Combobox.Option,{className:user_selector_module_default.overlayHeader,disabled:!0,value:option.value,children:jsx(Text,{as:`span`,variant:`bodySmallSemibold`,color:`textOnLightSecondary`,children:option.label})}):option.value===`__combobox_overlay_separator__`?jsx(Combobox.Option,{className:user_selector_module_default.overlaySeparatorOption,disabled:!0,value:option.value,children:jsx(Divider,{"aria-hidden":!0})}):jsx(UserSelectorComboboxOption,{renderAvatar,renderCustomOption,userContact:option}),value:selectedUsers,ref:forwardedRef,...rest})});export{UserSelector as t};
+import"../esm/lib/constants.js";import{buildOptionsWithSuggestedOptions}from"../esm/lib/utils/buildOptionsWithSuggestedOptions.js";import messages from"../esm/lib/messages.js";import{t as UserSelectorComboboxOption}from"./user-selector-list-item.js";import{isUserContactType}from"../esm/lib/utils/isUserContactType.js";import{defaultRenderCustomOption}from"../esm/lib/utils/defaultRenderCustomOption.js";import{getInitials}from"../esm/lib/utils/getInitials.js";import{forwardRef,useCallback}from"react";import clsx from"clsx";import{useIntl}from"react-intl";import{Avatar,Combobox,Divider,IconBadge,Text}from"@box/blueprint-web";import{ComboboxWithApi}from"@box/combobox-with-api";import{jsx}from"react/jsx-runtime";import '../styles/user-selector.css';var user_selector_module_default={overlayHeader:`_overlayHeader_u0715_1`,overlaySeparatorOption:`_overlaySeparatorOption_u0715_8`,textArea:`_textArea_u0715_15`},isOverlayOption=option=>option.value===`__combobox_overlay_header__`||option.value===`__combobox_overlay_separator__`,UserSelector=forwardRef((props,forwardedRef)=>{let{fetchedAvatarUrls,fetchUsers,onSelectedUsersChange,selectedUsers,variant,className,defaultOptions,suggestedOptions,renderCustomOption=defaultRenderCustomOption,...rest}=props,intl=useIntl(),renderAvatar=option=>{if(!isOverlayOption(option)){if(isUserContactType(option)){let{name,isExternalUser,id}=option,avatar=jsx(Avatar,{alt:intl.formatMessage(messages.userAvatar),colorIndex:id,src:fetchedAvatarUrls[id],text:getInitials(name)});return isExternalUser?jsx(IconBadge,{offset:{right:-4,bottom:-2},size:`medium`,variant:`collaborator-external`,children:avatar}):avatar}return jsx(Avatar,{...option.avatar})}},displayChipVariant=option=>{if(!isOverlayOption(option)&&!isUserContactType(option))return option.chipVariant},getOptionsWithSuggestions=useCallback((options,inputValue)=>!suggestedOptions||suggestedOptions.length===0?options:buildOptionsWithSuggestedOptions(options,suggestedOptions,selectedUsers,inputValue),[selectedUsers,suggestedOptions]);return jsx(ComboboxWithApi,{as:`input`,className:clsx(className,variant===`textarea`&&user_selector_module_default.textArea),defaultOptions,displayAvatar:renderAvatar,displayChipVariant,displayValue:option=>isOverlayOption(option)?``:option.name,fetcher:fetchUsers,freeInput:!1,loadingAriaLabel:intl.formatMessage(messages.loading),multiselect:!0,noResultMessage:intl.formatMessage(messages.noResults),onValueChange:onSelectedUsersChange,renderOption:option=>isOverlayOption(option)?option.value===`__combobox_overlay_header__`?jsx(Combobox.Option,{className:user_selector_module_default.overlayHeader,disabled:!0,value:option.value,children:jsx(Text,{as:`span`,variant:`bodySmallSemibold`,color:`textOnLightSecondary`,children:intl.formatMessage(messages.suggestedOptionsTitle)})}):jsx(Combobox.Option,{className:user_selector_module_default.overlaySeparatorOption,disabled:!0,value:option.value,children:jsx(Divider,{"aria-hidden":!0})}):jsx(UserSelectorComboboxOption,{renderAvatar,renderCustomOption,userContact:option}),transformOptions:getOptionsWithSuggestions,value:selectedUsers,ref:forwardedRef,...rest})});export{UserSelector as t};

package/dist/esm/index.js

@@ -1 +1 @@
-import{n as OVERLAY_HEADER_VALUE,r as OVERLAY_SEPARATOR_VALUE}from"../chunks/buildOptionsWithOverlay.js";import{UserSelectorContainer}from"./lib/user-selector-container.js";import{UserSelectorHeadless}from"./lib/user-selector-headless/user-selector-headless.js";export{OVERLAY_HEADER_VALUE,OVERLAY_SEPARATOR_VALUE,UserSelectorContainer,UserSelectorHeadless};
+import{UserSelectorContainer}from"./lib/user-selector-container.js";import{UserSelectorHeadless}from"./lib/user-selector-headless/user-selector-headless.js";export{UserSelectorContainer,UserSelectorHeadless};

package/dist/esm/lib/constants.js

@@ -0,0 +1 @@
+var DEFAULT_MAX_GAPS=2,DEFAULT_MAX_SUGGESTIONS=3,DEFAULT_MIN_CHARACTERS=3,OVERLAY_HEADER_VALUE=`__combobox_overlay_header__`,OVERLAY_SEPARATOR_VALUE=`__combobox_overlay_separator__`;export{DEFAULT_MAX_GAPS,DEFAULT_MAX_SUGGESTIONS,DEFAULT_MIN_CHARACTERS,OVERLAY_HEADER_VALUE,OVERLAY_SEPARATOR_VALUE};

package/dist/esm/lib/messages.js

@@ -1 +1 @@
-import{defineMessages}from"react-intl";var messages=defineMessages({loading:{id:`groupSharedFeatures.userSelector.loading`,defaultMessage:`Loading`},noResults:{id:`groupSharedFeatures.userSelector.noResults`,defaultMessage:`No results`},tryAgain:{id:`groupSharedFeatures.userSelector.tryAgain`,defaultMessage:`Try again`},userAvatar:{id:`groupSharedFeatures.userSelector.userAvatar`,defaultMessage:`User avatar`},userName:{id:`groupSharedFeatures.userSelector.userName`,defaultMessage:`{name} {isCurrentUser, select, true { (me)} other {}}`},errorMessage:{id:`groupSharedFeatures.userSelector.errorMessage`,defaultMessage:`We were unable to load users`},errorMessageDescription:{id:`groupSharedFeatures.userSelector.errorMessageDescription`,defaultMessage:`Please try again later`},emptyMessage:{id:`groupSharedFeatures.userSelector.emptyMessage`,defaultMessage:`NO COLLABORATORS FOUND`},inviteCollaborators:{id:`groupSharedFeatures.userSelector.inviteCollaborators`,defaultMessage:`Invite Collaborators`},inviteCollaboratorsTooltip:{id:`groupSharedFeatures.userSelector.inviteCollaboratorsTooltip`,defaultMessage:`This person doesn't have access and won't be notified unless invited.`}});export{messages as default};
+import{defineMessages}from"react-intl";var messages=defineMessages({loading:{id:`groupSharedFeatures.userSelector.loading`,defaultMessage:`Loading`},noResults:{id:`groupSharedFeatures.userSelector.noResults`,defaultMessage:`No results`},suggestedOptionsTitle:{id:`groupSharedFeatures.userSelector.suggestedOptionsTitle`,defaultMessage:`SUGGESTED`},tryAgain:{id:`groupSharedFeatures.userSelector.tryAgain`,defaultMessage:`Try again`},userAvatar:{id:`groupSharedFeatures.userSelector.userAvatar`,defaultMessage:`User avatar`},userName:{id:`groupSharedFeatures.userSelector.userName`,defaultMessage:`{name} {isCurrentUser, select, true { (me)} other {}}`},errorMessage:{id:`groupSharedFeatures.userSelector.errorMessage`,defaultMessage:`We were unable to load users`},errorMessageDescription:{id:`groupSharedFeatures.userSelector.errorMessageDescription`,defaultMessage:`Please try again later`},emptyMessage:{id:`groupSharedFeatures.userSelector.emptyMessage`,defaultMessage:`NO COLLABORATORS FOUND`},inviteCollaborators:{id:`groupSharedFeatures.userSelector.inviteCollaborators`,defaultMessage:`Invite Collaborators`},inviteCollaboratorsTooltip:{id:`groupSharedFeatures.userSelector.inviteCollaboratorsTooltip`,defaultMessage:`This person doesn't have access and won't be notified unless invited.`}});export{messages as default};

package/dist/esm/lib/user-selector-container.js

@@ -1 +1 @@
-import{isUserContactType}from"./utils/isUserContactType.js";import{t as UserSelector}from"../../chunks/user-selector.js";import{defaultRenderCustomOption}from"./utils/defaultRenderCustomOption.js";import{useCallback,useEffect,useRef,useState}from"react";import{jsx}from"react/jsx-runtime";var UserSelectorContainer=({fetchAvatarUrls,fetchUsers,onSelectedUsersChange,selectedUsers,renderCustomOption=defaultRenderCustomOption,inputRef,...rest})=>{let isFirstRender=useRef(!0),[fetchedOptions,setFetchedOptions]=useState([]),[fetchedAvatarUrls,setFetchedAvatarUrls]=useState({}),fetchOptions=useCallback(async inputVal=>{let options=await fetchUsers(inputVal);return setFetchedOptions(options),options},[fetchUsers,setFetchedOptions]),getAvatarUrls=useCallback(async users=>{try{setFetchedAvatarUrls(await fetchAvatarUrls(users))}catch{setFetchedAvatarUrls({})}},[fetchAvatarUrls,setFetchedAvatarUrls]);return useEffect(()=>{isFirstRender.current&&(isFirstRender.current=!1,selectedUsers.length>0&&setFetchedOptions(selectedUsers.filter(isUserContactType)))},[selectedUsers,setFetchedOptions]),useEffect(()=>{fetchedOptions.length>0&&getAvatarUrls(fetchedOptions.filter(isUserContactType))},[fetchedOptions,getAvatarUrls]),jsx(UserSelector,{fetchedAvatarUrls,fetchUsers:fetchOptions,onSelectedUsersChange,renderCustomOption,selectedUsers,ref:inputRef,...rest})};export{UserSelectorContainer};
+import{isUserContactType}from"./utils/isUserContactType.js";import{defaultRenderCustomOption}from"./utils/defaultRenderCustomOption.js";import{t as UserSelector}from"../../chunks/user-selector.js";import{dedupeUserContactsById}from"./utils/dedupeUserContactsById.js";import{useCallback,useEffect,useRef,useState}from"react";import{jsx}from"react/jsx-runtime";var UserSelectorContainer=({fetchAvatarUrls,fetchUsers,onSelectedUsersChange,selectedUsers,suggestedOptions,renderCustomOption=defaultRenderCustomOption,inputRef,...rest})=>{let isFirstRender=useRef(!0),[fetchedOptions,setFetchedOptions]=useState([]),[fetchedAvatarUrls,setFetchedAvatarUrls]=useState({}),fetchOptions=useCallback(async inputVal=>{let options=await fetchUsers(inputVal);return setFetchedOptions(options),options},[fetchUsers,setFetchedOptions]),getAvatarUrls=useCallback(async users=>{try{setFetchedAvatarUrls(await fetchAvatarUrls(users))}catch{setFetchedAvatarUrls({})}},[fetchAvatarUrls,setFetchedAvatarUrls]);return useEffect(()=>{isFirstRender.current&&(isFirstRender.current=!1,selectedUsers.length>0&&setFetchedOptions(selectedUsers.filter(isUserContactType)))},[selectedUsers,setFetchedOptions]),useEffect(()=>{let userOptions=dedupeUserContactsById([...fetchedOptions,...suggestedOptions??[]].filter(isUserContactType));userOptions.length>0&&getAvatarUrls(userOptions)},[fetchedOptions,getAvatarUrls,suggestedOptions]),jsx(UserSelector,{fetchedAvatarUrls,fetchUsers:fetchOptions,onSelectedUsersChange,renderCustomOption,selectedUsers,suggestedOptions,ref:inputRef,...rest})};export{UserSelectorContainer};

package/dist/esm/lib/utils/buildOptionsWithSuggestedOptions.js

@@ -0,0 +1 @@
+import{OVERLAY_HEADER_VALUE,OVERLAY_SEPARATOR_VALUE}from"../constants.js";var normalizeFuzzyMatchValue=value=>value.toLowerCase().replace(/\s/g,``),getEmailAlias=email=>{let separatorIndex=email.indexOf(`@`);return separatorIndex===-1?``:email.substring(0,separatorIndex)},dedupeSortedOptionsById=sortedOptions=>{let seenIds=new Set;return sortedOptions.filter(sortedOption=>sortedOption.id===void 0?!0:seenIds.has(sortedOption.id)?!1:(seenIds.add(sortedOption.id),!0))},isFuzzyMatch=(search,content,minCharacters=3,maxGaps=2)=>{if(!content)return!1;let uniformContent=normalizeFuzzyMatchValue(content),uniformSearch=normalizeFuzzyMatchValue(search),contentLength=uniformContent.length,searchLength=uniformSearch.length;if(searchLength<minCharacters||searchLength>contentLength)return!1;let totalScore=0;for(let i=0;i<contentLength&&!(contentLength-i<searchLength);i+=1){let searchIndex=0,currentScore=0,subScore=0;for(let j=i;j<contentLength;j+=1)uniformContent[j]===uniformSearch[searchIndex]?(searchIndex+=1,currentScore+=1+currentScore):currentScore=0,subScore+=currentScore;if(searchIndex!==searchLength)break;subScore>totalScore&&(totalScore=subScore)}if(totalScore===0)return!1;let maxGroups=Math.min(maxGaps,searchLength),minScore=Math.max(maxGroups*2**Math.floor(searchLength/maxGroups-1),searchLength+1);return totalScore>=minScore},getDescendingSortedScore=(optionA,optionB)=>optionB.userScore-optionA.userScore,getMatchingSuggestedOptions=(options,suggestedOptions)=>suggestedOptions.reduce((matches,suggestedOption)=>{let option=options.find(currentOption=>currentOption.id===suggestedOption.id);return option&&matches.push({id:option.id,option,userScore:suggestedOption.userScore}),matches},[]),getFuzzySuggestedCollaborators=({exactMatchIds,inputValue,selectedIds,suggestedOptions})=>{if(!inputValue)return[];let normalizedInput=normalizeFuzzyMatchValue(inputValue);return suggestedOptions.filter(suggestedOption=>{if(selectedIds.has(suggestedOption.id)||exactMatchIds.has(suggestedOption.id))return!1;let nameMatches=isFuzzyMatch(inputValue,suggestedOption.name),emailAlias=suggestedOption.email?normalizeFuzzyMatchValue(getEmailAlias(suggestedOption.email)):``,emailMatches=!!emailAlias&&normalizedInput.length>=3&&emailAlias.includes(normalizedInput);return nameMatches||emailMatches}).map(suggestedOption=>({id:suggestedOption.id,option:suggestedOption,userScore:suggestedOption.userScore}))};function buildOptionsWithSuggestedOptions(options,suggestedOptions,selectedOptions,inputValue){let selectedIds=new Set(selectedOptions.map(({id})=>id)),matchingSuggestedOptions=getMatchingSuggestedOptions(options,suggestedOptions),exactMatchIds=new Set(matchingSuggestedOptions.reduce((ids,{id})=>(id!==void 0&&ids.push(id),ids),[])),eligibleMatchingSuggestedOptions=dedupeSortedOptionsById([...matchingSuggestedOptions].sort(getDescendingSortedScore).filter(({id})=>!selectedIds.has(id))),fuzzySuggestedOptions=eligibleMatchingSuggestedOptions.length>=3?[]:dedupeSortedOptionsById(getFuzzySuggestedCollaborators({exactMatchIds,inputValue,selectedIds,suggestedOptions}).sort(getDescendingSortedScore)),visibleSuggestedOptions=dedupeSortedOptionsById([...eligibleMatchingSuggestedOptions,...fuzzySuggestedOptions]).slice(0,3).map(({option})=>option);if(visibleSuggestedOptions.length===0)return options;let suggestedIds=new Set(visibleSuggestedOptions.map(({id})=>id)),visibleOptions=options.filter(option=>!selectedIds.has(option.id)&&!suggestedIds.has(option.id)),headerOption={disabled:!0,value:OVERLAY_HEADER_VALUE};if(visibleOptions.length===0)return[headerOption,...visibleSuggestedOptions];let dividerOption={disabled:!0,value:OVERLAY_SEPARATOR_VALUE};return[headerOption,...visibleSuggestedOptions,dividerOption,...visibleOptions]}export{buildOptionsWithSuggestedOptions};

package/dist/esm/lib/utils/dedupeUserContactsById.js

@@ -0,0 +1 @@
+var dedupeUserContactsById=users=>{let seenUserIds=new Set;return users.filter(user=>seenUserIds.has(user.id)?!1:(seenUserIds.add(user.id),!0))};export{dedupeUserContactsById};

package/dist/types/lib/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_MAX_GAPS = 2;
+export declare const DEFAULT_MAX_SUGGESTIONS = 3;
+export declare const DEFAULT_MIN_CHARACTERS = 3;
+export declare const OVERLAY_HEADER_VALUE = "__combobox_overlay_header__";
+export declare const OVERLAY_SEPARATOR_VALUE = "__combobox_overlay_separator__";

package/dist/types/lib/messages.d.ts

@@ -9,6 +9,11 @@ declare const messages: {
         description: string;
         id: string;
     };
+    suggestedOptionsTitle: {
+        defaultMessage: string;
+        description: string;
+        id: string;
+    };
     tryAgain: {
         defaultMessage: string;
         description: string;

package/dist/types/lib/types.d.ts

@@ -1,7 +1,5 @@
 import { ReactElement, SVGProps } from 'react';
-/** Option value for overlay header/divider rows (non-selectable). */
-export declare const OVERLAY_HEADER_VALUE = "__combobox_overlay_header__";
-export declare const OVERLAY_SEPARATOR_VALUE = "__combobox_overlay_separator__";
+import { OVERLAY_HEADER_VALUE, OVERLAY_SEPARATOR_VALUE } from './constants';
 export type UserContactType = {
     chipVariant?: 'error' | 'default' | 'variable';
     email: string;
@@ -13,6 +11,13 @@ export type UserContactType = {
     value: string;
     type?: string;
 };
+export interface SuggestedCollaborator extends Partial<UserContactType> {
+    id: number;
+    email: string;
+    name: string;
+    userScore: number;
+    value: string;
+}
 export type CustomUserContactType = {
     name: string;
     subtitle?: string;
@@ -31,16 +36,13 @@ export type CustomUserContactType = {
     hideOnClick?: boolean;
     chipVariant?: 'default' | 'error' | 'variable';
 };
-export type OverlayHeaderOption = {
-    name: string;
-    value: typeof OVERLAY_HEADER_VALUE;
-    label: string;
-};
-export type OverlaySeparatorOption = {
-    name: string;
-    value: typeof OVERLAY_SEPARATOR_VALUE;
-};
 export type UserSelectorOption = UserContactType | CustomUserContactType;
+type OverlayValue = typeof OVERLAY_HEADER_VALUE | typeof OVERLAY_SEPARATOR_VALUE;
+export type OverlayOption = {
+    disabled: true;
+    value: OverlayValue;
+};
 export type FetchedAvatarUrls = {
     [userId: string]: string;
 };
+export {};

package/dist/types/lib/user-selector-container.d.ts

@@ -16,4 +16,4 @@ export type UserSelectorContainerProps<T extends UserSelectorOption = UserContac
      */
     inputRef?: Ref<HTMLInputElement>;
 };
-export declare const UserSelectorContainer: <T extends UserSelectorOption = UserContactType>({ fetchAvatarUrls, fetchUsers, onSelectedUsersChange, selectedUsers, renderCustomOption, inputRef, ...rest }: UserSelectorContainerProps<T>) => import("react/jsx-runtime").JSX.Element;
+export declare const UserSelectorContainer: <T extends UserSelectorOption = UserContactType>({ fetchAvatarUrls, fetchUsers, onSelectedUsersChange, selectedUsers, suggestedOptions, renderCustomOption, inputRef, ...rest }: UserSelectorContainerProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/types/lib/user-selector.d.ts

@@ -1,18 +1,16 @@
-import { ForwardedRef, ReactElement } from 'react';
+import { ForwardedRef, ReactElement, ReactNode } from 'react';
 import { AvatarProps } from '@box/blueprint-web';
 import { ComboboxWithApiProps } from '@box/combobox-with-api';
-import { CustomUserContactType, FetchedAvatarUrls, UserContactType, UserSelectorOption } from './types';
+import { CustomUserContactType, FetchedAvatarUrls, OverlayOption, UserContactType, UserSelectorOption } from './types';
 export type BaseUserSelectorProps<T extends UserSelectorOption> = {
     /**
      * Default options to show when the input is empty
      */
     defaultOptions?: T[];
     /**
-     * 0-based index (relative to the option list only) after which to insert a divider row.
-     * The option list includes selected options when they are shown in the dropdown.
-     * E.g. 1 = divider after the second option.
+     * Suggested options to show before regular options in the dropdown
      */
-    overlayDividerIndex?: number;
+    suggestedOptions?: T[];
     /**
      * A dictionary with user ids mapped to avatar URLs
      */
@@ -21,10 +19,6 @@ export type BaseUserSelectorProps<T extends UserSelectorOption> = {
      * Function to fetch users when the input value changes
      */
     fetchUsers: (inputValue: string) => Promise<Array<T>>;
-    /**
-     * Label shown as the first row in the default options dropdown (e.g. "SUGGESTED").
-     */
-    overlayTitle?: string;
     /**
      * onChange for controlled selected users state
      */
@@ -32,7 +26,7 @@ export type BaseUserSelectorProps<T extends UserSelectorOption> = {
     /**
      * Function to render the custom option
      */
-    renderCustomOption?: (option: CustomUserContactType, renderAvatar: () => ReactElement<AvatarProps>) => React.ReactNode;
+    renderCustomOption?: (option: CustomUserContactType, renderAvatar: () => ReactElement<AvatarProps>) => ReactNode;
     /**
      * Controlled selected users state
      */
@@ -42,7 +36,7 @@ export type BaseUserSelectorProps<T extends UserSelectorOption> = {
      */
     variant?: 'input' | 'textarea';
 };
-export type UserSelectorProps<T extends UserSelectorOption = UserContactType> = BaseUserSelectorProps<T> & Omit<ComboboxWithApiProps<true, false, T>, 'as' | 'fetcher' | 'freeInput' | 'hideSelectedOptions' | 'loadingAriaLabel' | 'multiselect' | 'onValueChange' | 'value'>;
+export type UserSelectorProps<T extends UserSelectorOption = UserContactType> = BaseUserSelectorProps<T> & Omit<ComboboxWithApiProps<true, false, T, OverlayOption, UserContactType>, 'as' | 'fetcher' | 'freeInput' | 'hideSelectedOptions' | 'loadingAriaLabel' | 'multiselect' | 'onValueChange' | 'transformOptions' | 'value'>;
 declare const UserSelectorInner: <T extends UserSelectorOption = UserContactType>(props: UserSelectorProps<T>, forwardedRef: ForwardedRef<HTMLInputElement>) => import("react/jsx-runtime").JSX.Element;
 declare const UserSelector: <T extends UserSelectorOption = UserContactType>(props: UserSelectorProps<T> & {
     ref?: ForwardedRef<HTMLInputElement>;

package/dist/types/lib/utils/buildOptionsWithSuggestedOptions.d.ts

@@ -0,0 +1,6 @@
+import { OverlayOption, SuggestedCollaborator, UserContactType } from '../types';
+/**
+ * Builds a flat options array for Blueprint Combobox from selectable options
+ * and a semantic suggested options group.
+ */
+export declare function buildOptionsWithSuggestedOptions<T extends UserContactType>(options: T[], suggestedOptions: SuggestedCollaborator[], selectedOptions: T[], inputValue: string): Array<T | SuggestedCollaborator | OverlayOption>;

package/dist/types/lib/utils/dedupeUserContactsById.d.ts

@@ -0,0 +1,2 @@
+import { UserContactType } from '../types';
+export declare const dedupeUserContactsById: (users: UserContactType[]) => UserContactType[];

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@box/user-selector",
-    "version": "2.2.23",
+    "version": "3.0.0",
     "peerDependencies": {
         "@box/blueprint-web": "^16.20.6",
         "@box/blueprint-web-assets": "^5.7.13",
-        "@box/combobox-with-api": "^2.2.23",
+        "@box/combobox-with-api": "^2.2.24",
         "lodash": "^4.17.15",
         "react": "^17.0.0 || ^18.0.0",
         "react-dom": "^17.0.0 || ^18.0.0",
@@ -13,7 +13,7 @@
     "devDependencies": {
         "@box/blueprint-web": "^16.20.6",
         "@box/blueprint-web-assets": "^5.7.13",
-        "@box/combobox-with-api": "^2.2.23",
+        "@box/combobox-with-api": "^2.2.24",
         "@box/storybook-utils": "^1.2.22",
         "@types/lodash": "^4.17.14",
         "react": "^18.3.0",

package/dist/chunks/buildOptionsWithOverlay.js

@@ -1 +0,0 @@
-var OVERLAY_HEADER_VALUE=`__combobox_overlay_header__`,OVERLAY_SEPARATOR_VALUE=`__combobox_overlay_separator__`;function buildOptionsWithOverlay(options,overlayTitle,overlayDividerIndex){if(!options||options.length===0)return options??void 0;let result=[...options];if(overlayDividerIndex>=0&&overlayDividerIndex<result.length-1){let dividerOption={name:``,value:OVERLAY_SEPARATOR_VALUE};result=[...result.slice(0,overlayDividerIndex+1),dividerOption,...result.slice(overlayDividerIndex+1)]}return overlayTitle&&result.length>0&&overlayDividerIndex>=0&&(result=[{name:``,value:OVERLAY_HEADER_VALUE,label:overlayTitle},...result]),result}export{OVERLAY_HEADER_VALUE as n,OVERLAY_SEPARATOR_VALUE as r,buildOptionsWithOverlay as t};

package/dist/esm/lib/utils/buildOptionsWithOverlay.js

@@ -1 +0,0 @@
-import{t as buildOptionsWithOverlay}from"../../../chunks/buildOptionsWithOverlay.js";export{buildOptionsWithOverlay};

package/dist/types/lib/utils/buildOptionsWithOverlay.d.ts

@@ -1,8 +0,0 @@
-import { OverlayHeaderOption, OverlaySeparatorOption, UserSelectorOption } from '../types';
-/**
- * Builds an options array with optional overlay header and divider for UserSelector.
- * Used for both default options and fetcher results.
- * Divider is inserted after the given index (relative to options only). Then overlay header is prepended.
- * Returns the same reference when no overlay is needed or when options are undefined/empty.
- */
-export declare function buildOptionsWithOverlay<T extends UserSelectorOption>(options: T[] | undefined, overlayTitle: string, overlayDividerIndex: number): (T | OverlayHeaderOption | OverlaySeparatorOption)[] | undefined;