(initState);
const setStateCallback = useCallback((newState: T): void => setState(newState), []);
return [state, setStateCallback];
};
export default useCallbackState;
================================================
FILE: __stories__/helpers/index.ts
================================================
export * from './utils';
export * from './hooks';
export * from './styled';
export * from './constants';
export * from './components';
================================================
FILE: __stories__/helpers/styled/index.ts
================================================
import styled, { css, keyframes } from 'styled-components';
export const MEDIA_QUERY_IS_MOBILE = '@media only screen and (max-width: 768px)';
export const MEDIA_QUERY_IS_MOBILE_XS = '@media only screen and (max-width: 525px)';
export const MEDIA_QUERY_IS_TABLET_OR_DESKTOP = '@media only screen and (min-width: 992px)';
export const MEDIA_QUERY_IS_TABLET = '@media only screen and (max-width: 991px) and (min-width: 769px)';
// Need to implement a div version of Paragraph since PrettyPrintJson contains an element
// ...which cannot be a child of a element
const PARAGRAPH_BASE_STYLE = css`
margin-top: 0;
display: block;
margin-bottom: 1rem;
margin-block-end: 1em;
margin-inline-end: 0px;
margin-block-start: 1em;
margin-inline-start: 0px;
`;
export const Content = styled.p`
${PARAGRAPH_BASE_STYLE}
`;
export const Paragraph = styled.p`
${PARAGRAPH_BASE_STYLE}
${MEDIA_QUERY_IS_TABLET_OR_DESKTOP} {
max-width: 85%;
}
`;
export const Container = styled.div`
width: 100%;
display: block;
margin-left: auto;
margin-right: auto;
padding: 0.25rem 1.75rem;
${MEDIA_QUERY_IS_MOBILE} {
font-size: 0.96em;
padding: 0.25rem 1.25rem;
}
`;
export const SelectContainer = styled.div`
width: 60%;
margin-top: 1rem;
${MEDIA_QUERY_IS_TABLET} {
width: 75%;
}
${MEDIA_QUERY_IS_MOBILE} {
width: 100%;
}
`;
export const Hr = styled.hr`
border: 0;
margin-top: 1rem;
margin-bottom: 1rem;
padding-bottom: .225rem;
border-top: 1px solid #ddd;
`;
export const Columns = styled.div`
width: 100%;
${MEDIA_QUERY_IS_TABLET_OR_DESKTOP} {
display: flex;
}
`;
export const Column = styled.div<{widthPercent?: number}>`
flex-grow: 1;
flex-basis: 0;
flex-shrink: 1;
display: block;
padding: 0.25rem;
${MEDIA_QUERY_IS_MOBILE} {
padding: 0.25rem 0;
width: 100% !important;
}
${({widthPercent}) =>
widthPercent &&
css`
flex: none;
width: ${widthPercent}%;
`}
`;
export const ListWrapper = styled.div`
${PARAGRAPH_BASE_STYLE}
${MEDIA_QUERY_IS_TABLET_OR_DESKTOP} {
max-width: 85%;
}
&.is-class-list {
max-width: 100% !important;
ul {
li + li {
margin-top: 0.55em !important;
}
}
}
`;
export const List = styled.ul`
display: block;
padding-left: 1.75rem;
margin-block-end: 1em;
list-style-type: disc;
margin-inline-end: 0px;
margin-block-start: 1em;
margin-inline-start: 0px;
padding-inline-start: 20px;
li + li {
margin-top: 0.6em;
}
`;
export const Li = styled.li`
display: list-item;
text-align: match-parent;
`;
export const TextHeader = styled.span`
color: #476582;
font-size: 90%;
line-height: 1.7;
border-radius: 4px;
padding: .175em .475em;
word-break: break-word;
background-color: #f1f1f1;
font-family: Consolas, Monaco, "Andale Mono", "Ubuntu Mono", monospace;
`;
export const Title = styled.h2`
font-size: 2rem;
font-weight: 700;
line-height: 1.167;
margin-top: 0.5rem;
margin-bottom: .5rem;
`;
export const SubTitle = styled.h4`
font-weight: 700;
line-height: 1.167;
font-size: 1.65rem;
margin-top: 1.25rem;
margin-bottom: 0.5rem;
letter-spacing: 0.00735em;
`;
export const Button = styled.button`
border: 0;
color: #262626;
cursor: pointer;
font-size: 1rem;
font-weight: 500;
line-height: 1.5;
overflow: visible;
user-select: none;
text-align: center;
border-radius: 3px;
display: inline-block;
vertical-align: middle;
background-color: #eaebec;
padding: 0.375rem 0.75rem;
-webkit-appearance: button;
transition: color 0.2s ease-out, background-color 0.2s ease-out;
:focus {
outline: 0;
}
:hover, :focus {
background-color: #DDDEDF;
}
${MEDIA_QUERY_IS_MOBILE} {
display: block;
width: 100% !important;
}
${MEDIA_QUERY_IS_MOBILE_XS} {
font-size: 0.9em;
}
`;
export const Buttons = styled.div`
> button {
min-width: 6.25rem;
margin-top: 0.5rem;
:not(:last-of-type) {
margin-right: 0.5rem;
}
}
`;
export const Label = styled.label`
width: 100%;
font-weight: 600;
text-align: left;
user-select: none;
display: inline-block;
vertical-align: middle;
color: rgba(0, 0, 0, 0.45);
margin: 0.5rem auto 0.25rem 0;
${MEDIA_QUERY_IS_MOBILE} {
margin: 0 auto 0.15rem 0;
}
`;
export const Checkboxes = styled.div`
font-size: 1rem;
> label {
margin-top: 0.5rem;
margin-bottom: 0.5rem;
:not(:last-of-type) {
margin-right: 1.35rem;
}
}
${MEDIA_QUERY_IS_MOBILE} {
text-align: left;
> label {
width: 100%;
margin-left: auto;
margin-top: 0.425rem;
margin-bottom: 0.425rem;
}
}
`;
export const Card = styled.div`
min-width: 0;
display: flex;
margin: 1.25rem 0;
position: relative;
border-radius: 3px;
word-wrap: break-word;
background-color: #fff;
flex-direction: column;
background-clip: border-box;
border: 1px solid rgba(0, 0, 0, 0.125);
box-shadow: rgb(0 0 0 / 10%) 0px 1px 3px 0px, rgb(0 0 0 / 5%) 0px 5px 15px 0px;
${MEDIA_QUERY_IS_MOBILE} {
border: none;
border-radius: 0;
box-shadow: none;
margin: 0;
}
`;
export const CardHeader = styled.div`
display: flex;
font-size: 1.15rem;
flex-flow: row wrap;
background-color: #fff;
padding: 0.75rem 1.25rem;
border-top-left-radius: 0.25rem;
border-top-right-radius: 0.25rem;
border-bottom: 1px solid rgba(0, 0, 0, 0.125);
${MEDIA_QUERY_IS_MOBILE} {
font-size: 1.1rem;
text-align: center;
display: inline-block;
padding: 0 1.15rem 1rem;
}
`;
export const CardBody = styled.div<{ multiComponents?: boolean }>`
flex: 1 1 auto;
min-height: 32rem;
padding: 0.75rem 1.25rem;
${({ multiComponents }) =>
multiComponents &&
css`
> div {
margin-bottom: 3rem;
:first-of-type > label {
margin-top: 0;
}
> label {
font-size: 18px;
margin-bottom: 0.5rem;
}
}
`}
${MEDIA_QUERY_IS_MOBILE} {
padding: 0.5rem 0;
}
`;
export const OtherSpan = styled.span`
opacity: 0.75;
font-size: 0.75em;
margin-top: 0.075em;
margin-left: 0.45em;
`;
export const MenuPortalElement = styled.div<{ menuOpen: boolean; }>`
width: 100%;
margin: 0.5rem 0;
min-height: 115px;
position: relative;
border-radius: 3px;
transition: background-color 0.2s ease-out;
background-color: ${({ menuOpen }) => menuOpen ? 'white' : 'whitesmoke'};
span {
font-weight: 700;
font-size: 1.5em;
text-align: center;
padding: 1.25em 1em;
color: rgba(0,0,0,0.6);
display: ${({ menuOpen }) => menuOpen ? 'none' : 'block'};
}
`;
// =======================================
// Advanced story specific
// =======================================
const SPIN_KEYFRAMES = keyframes`
from {
transform: rotate(0deg);
} to {
transform: rotate(360deg);
}
`;
const SPIN_ANIMATION_CSS = css`animation: ${SPIN_KEYFRAMES} infinite 8s linear;`;
export const ReactSvg = styled.svg<{ isDisabled?: boolean }>`
width: 30px;
height: 30px;
color: #1ea7fd;
fill: currentColor;
display: inline-block;
${({ isDisabled }) => !isDisabled && SPIN_ANIMATION_CSS}
`;
export const ChevronDownSvg = styled.svg<{ menuOpen: boolean }>`
width: 14px;
height: 14px;
fill: currentColor;
transition: transform 0.25s ease-in-out;
${({ menuOpen }) => menuOpen && css`transform: rotate(180deg);`}
`;
export const OptionContainer = styled.div`
height: 100%;
display: flex;
align-items: center;
flex-direction: row;
`;
export const OptionName = styled.span`
color: #515151;
font-weight: 600;
margin-left: 1px;
`;
================================================
FILE: __stories__/helpers/utils/index.ts
================================================
import type { Option } from '../../types';
export const numberWithCommas = (value: number): string => {
return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
};
export const getRandomInt = (min: number, max: number): number => {
return Math.floor(Math.random() * (max - min + 1)) + min;
};
export const stringifyJavaScriptObj = (data: any = {}): string => {
return JSON.stringify(data, null, 2).replace(/"(\w+)"\s*:/g, '$1:');
};
export const mockHttpRequest = async (delay: number = 500): Promise => {
await new Promise(resolve => setTimeout(resolve, delay));
};
export const createOptions = (count: number): Option[] => {
const options: Option[] = [];
for (let i = 0; i < count; i++) {
const value = i + 1;
options.push({
value,
label: `Option ${value}`
});
}
return options;
};
export const createThemeOptions = (themeEnum: any): Option[] => {
return Object.keys(themeEnum).map((key) => ({
value: themeEnum[key],
label: themeEnum[key]
}));
};
export const createAsyncOptions = (count: number, lblSuffix: string = ''): Option[] => {
const options = createOptions(count);
return options.map(({ value, label }: Option) => ({
value,
label: `${label}${lblSuffix ? (' - ' + lblSuffix) : ''}`
}));
};
export const hexToRgba = (hex: string, alpha: number = 1): string => {
const hexReplacer: string = hex.replace(
/^#?([a-f\d])([a-f\d])([a-f\d])$/i,
(_m, r, g, b) => `#${r}${r}${g}${g}${b}${b}`
);
const alphaValid: number = Math.min(1, Math.max(0, alpha));
const rgbParts: number[] = hexReplacer.substring(1).match(/.{2}/g)!.map((x) => parseInt(x, 16));
const rgbaParts = [...rgbParts, alphaValid].join(',');
return `rgba(${rgbaParts})`;
};
================================================
FILE: __stories__/index.stories.tsx
================================================
import { Select } from '../src';
import { useUpdateEffect } from '../src/hooks';
import type { SelectedOption } from '../src/types';
import { toast, ToastContainer } from 'react-toastify';
import type { CityOption, Option, PackageOption } from './types';
import type { MultiParams, MenuOption, SelectRef, Theme } from '../src';
import React, { useMemo, useRef, useState, useEffect, useCallback, Fragment } from 'react';
import {
OPTION_CLS,
OPTION_FOCUSED_CLS,
OPTION_DISABLED_CLS,
OPTION_SELECTED_CLS,
CARET_ICON_CLS,
CLEAR_ICON_CLS,
LOADING_DOTS_CLS,
AUTOSIZE_INPUT_CLS,
MENU_CONTAINER_CLS,
SELECT_CONTAINER_CLS,
CONTROL_CONTAINER_CLS,
LOADING_MSG_DEFAULT
} from '../src/constants';
import {
Button,
Buttons,
Hr,
Title,
SubTitle,
Label,
Columns,
Column,
Content,
Container,
List,
Li,
ListWrapper,
SelectContainer,
Paragraph,
TextHeader,
Checkboxes,
Card,
CardHeader,
CardBody,
OtherSpan,
OptionContainer,
OptionName,
ReactSvg,
ChevronDownSvg,
MenuPortalElement,
ThemeEnum,
ThemeConfigMap,
Checkbox,
CodeMarkup,
PackageLink,
OptionsCountButton,
mockHttpRequest,
getRandomInt,
useCallbackState,
createAsyncOptions,
createOptions,
stringifyJavaScriptObj,
THEME_DEFAULTS,
THEME_OPTIONS,
THEME_CONFIG,
CITY_OPTIONS,
PACKAGE_OPTIONS,
CLASS_NAME_HTML,
REACT_WINDOW_PACKAGE,
TOAST_CONTAINER_PROPS,
STYLED_COMPONENTS_PACKAGE,
REACT_SVG_PROPS,
REACT_SVG_CIRCLE_PROPS,
REACT_SVG_PATH_PROPS,
CHEVRON_SVG_PROPS,
CHEVRON_DOWN_PATH_PROPS
} from './helpers';
export default {
title: 'React Functional Select/Demos'
};
export const SingleSelect = () => {
const [isInvalid, setIsInvalid] = useCallbackState(false);
const [isLoading, setIsLoading] = useCallbackState(false);
const [isDisabled, setIsDisabled] = useCallbackState(false);
const [isClearable, setIsClearable] = useCallbackState(true);
const [isSearchable, setIsSearchable] = useCallbackState(true);
const getOptionValue = useCallback((option: CityOption): number => option.id, []);
const getOptionLabel = useCallback((option: CityOption): string => `${option.city}, ${option.state}`, []);
useEffect(() => {
isDisabled && setIsInvalid(false);
}, [isDisabled, setIsInvalid]);
return (
Single-Select
In this story's source code, notice that the callback function
properties getOptionValue and getOptionLabel are
wrapped in a useCallback. While not required, strongly prefer
memoization of any callback function property whenever possible. This will boost
performance and reduce the amount of renders as these properties are referenced
in the dependency arrays of useCallbacks, useEffects,
and useMemos. When defined in a functional component, wrap in
a useCallback; when defined in a legacy class component, ensure proper
binding to this. Alternatively, if there is no dependency on any state,
you can opt to hoist functions outside of the component entirely.
The options property should also be memoized. Either consume
it directly from a state management store, or make sure it is stable by
avoiding inline or render-based mutations.
Demo
);
};
export const MultiSelect = () => {
const [openMenuOnClick, setOpenMenuOnClick] = useCallbackState(true);
const [closeMenuOnSelect, setCloseMenuOnSelect] = useCallbackState(true);
const [blurInputOnSelect, setBlurInputOnSelect] = useCallbackState(false);
const [hideSelectedOptions, setHideSelectedOptions] = useCallbackState(true);
const getOptionValue = useCallback(({ id }: CityOption): number => id, []);
const getOptionLabel = useCallback(({ city, state }: CityOption): string => `${city}, ${state}`, []);
// example "renderMultiOptions" property that can be used to further customize labeling for multi-option scenarios
const renderMultiOptions = useCallback(
({ selected, renderOptionLabel }: MultiParams) => (
{selected.length && renderOptionLabel(selected[0].data)}
{selected.length > 1 && (
{`(+${selected.length - 1} other${selected.length > 2 ? 's' : ''})`}
)}
),
[]
);
return (
Multi-Select
Add the isMulti property to allow for multiple selections.
While in multi-select mode, some properties are now applicable and
others become more pertinent.
hideSelectedOptions?: boolean - Hide the
selected option from the menu. Default value is false, however,
if undefined and isMulti is true, then its value
defaults to true.
closeMenuOnSelect?: boolean - Close the
menu of options when the user selects an option. Default value is
false, however, it may be benefical to set this property to true for
convenience in multi-select scenarios.
renderMultiOptions(params: MultiParams) {'=>'} ReactNode -
Optional callback function that can be used to further customize the selection
label in multi-select scenarios. params is an object that contains
the selected and renderOptionLabel properties (array
of selected options and function used to render individual option labels,
respectively). When this function is defined, left and right arrow navigation
of individual options is disabled. When using this property, it may be be a good
idea to set the property backspaceClearsValue to false in
order to avoid accidentally clearing all selections when searching.
Demo
);
};
export const Styling = () => {
const [themeConfig, setThemeConfig] = useState(undefined);
const [selectedOption, setSelectedOption] = useCallbackState(null);
const memoizedMarkupNode = useMemo(() => (
), []);
useEffect(() => {
if (selectedOption) {
const { value } = selectedOption;
setThemeConfig(ThemeConfigMap[value!]);
}
}, [selectedOption]);
const noteCodeStyle = { fontWeight: 500 };
const selectWrapperStyle = { marginTop: '1rem' };
const noteStyle = { fontSize: 'inherit', fontWeight: 700 };
const menuItemSize = selectedOption?.value === ThemeEnum.LARGE_TEXT ? 44 : 35;
return (
Styling
Theming
react-functional-select uses to
handle its styling. The root node is wrapped in
styled-component's ThemeProvider wrapper component which gives all
child styled-components access to the provided theme via React's context API.
To override react-functional-select's default theme, pass an object to
the themeConfig property - any matching properties will replace
those in the default theme.
Starting in v2.0.0, some of the nested objects in
the themeConfig object contain a css property
of type string | FlattenSimpleInterpolation | undefined (default value
is undefined). This property can be used to pass raw CSS styles as a string or wrapped
in exported css function.
Those objects are: select, control, icon, menu, noOptions, multiValue, and input.
Starting in v2.7.0, the control object in themeConfig has
the property focusedCss - which is similar to the css property,
except that it is only applied when the select control is focused (and removed when blurred).
Using Classes
There is also the option to handle styling via CSS classes.
These are the classes that are available:
{SELECT_CONTAINER_CLS}
{CONTROL_CONTAINER_CLS}
{MENU_CONTAINER_CLS}
{AUTOSIZE_INPUT_CLS}
{CARET_ICON_CLS}
{CLEAR_ICON_CLS}
{LOADING_DOTS_CLS}
{OPTION_CLS}, {OPTION_FOCUSED_CLS}, {OPTION_SELECTED_CLS}, {OPTION_DISABLED_CLS}
{memoizedMarkupNode}
Demo
);
};
export const Events = () => {
const options = useMemo(() => createOptions(5), []);
const [addOnKeyDown, setAddOnKeyDown] = useCallbackState(false);
const [addOnMenuOpen, setAddOnMenuOpen] = useCallbackState(true);
const [addOnMenuClose, setAddOnMenuClose] = useCallbackState(false);
const [addOnInputBlur, setAddOnInputBlur] = useCallbackState(false);
const [addOnInputFocus, setAddOnInputFocus] = useCallbackState(false);
const [addOnOptionChange, setAddOnOptionChange] = useCallbackState(true);
const onMenuOpen = useCallback(() => toast.info('Menu opened'), []);
const onMenuClose = useCallback(() => toast.info('Menu closed'), []);
const onInputBlur = useCallback(() => toast.info('Control blurred'), []);
const onInputFocus = useCallback(() => toast.info('Control focused'), []);
const onKeyDown = useCallback(() => toast.info('keydown event executed'), []);
const onOptionChange = useCallback((option: Option) => toast.info(`Selected option: "${option?.value}"`), []);
return (
Events
There are various callback function properties that are executed following
their associated events:
onOptionChange(data: any) {'=>'} void -
executed after an option is selected or removed
onMenuOpen(...args: any[]) {'=>'} void -
executed after the menu is opened
onMenuClose(...args: any[]) {'=>'} void -
executed after the menu is closed
onInputChange(value: string) {'=>'} void -
executed after the input control's value changes
onInputBlur(e: FocusEvent{'<'}HTMLInputElement{'>'}) {'=>'} void -
executed after the input control is blurred
onInputFocus(e: FocusEvent{'<'}HTMLInputElement{'>'}) {'=>'} void -
executed after the input control is focused
onKeyDown(e: KeyboardEvent{'<'}HTMLDivElement{'>'}, input?: string, focusedOption?: FocusedOption) {'=>'} void
-
executed after the onKeyDown event
onSearchChange(value: string) {'=>'} void -
executed after the input value is persisted to state; this value also evaluates
the inputDelay property for debouncing - this callback is really
only useful when inputDelay is defined, and if not, it probably
makes more sense to use the onInputChange callback
Demo
);
};
export const Methods = () => {
const selectRef = useRef(null);
const options = useMemo(() => createOptions(5), []);
const blurSelect = () => selectRef.current?.blur();
const focusSelect = () => selectRef.current?.focus();
const clearValue = () => selectRef.current?.clearValue();
const toggleMenuOpen = () => selectRef.current?.toggleMenu(true);
const updateSelectedOption = () => selectRef.current?.setValue(options[0]);
return (
Methods & Properties
5 methods and 1 property are exposed to
wrapping components and are accessible via a forwarded ref.
blur() {'=>'} void - blur the control
programatically
focus() {'=>'} void - focus the control
programatically
toggleMenu(state?: boolean) {'=>'} void -
toggle the menu programatically
clearValue() {'=>'} void - clear the current
value programatically (if an option is selected)
setValue(option?: any) {'=>'} void - set the
value programatically (option will be validated)
menuOpen: boolean - Open state of the menu
Demo
);
};
export const Filtering = () => {
const [filterIgnoreCase, setFilterIgnoreCase] = useCallbackState(true);
const [useCustomFilterFunc, setUseCustomFilterFunc] = useCallbackState(false);
const [filterIgnoreAccents, setFilterIgnoreAccents] = useCallbackState(false);
const [filterMatchFromStart, setFilterMatchFromStart] = useCallbackState(false);
const getOptionValue = useCallback(({ id }: CityOption): number => id, []);
const getOptionLabel = useCallback(({ city, state }: CityOption): string => `${city}, ${state}`, []);
const getFilterOptionString = useCallback((menuOption: MenuOption): string => menuOption.data.state, []);
const options = useMemo(() => [
...CITY_OPTIONS,
{ id: 11, city: 'São Paulo', state: 'BR' }
], []);
return (
Filter Customization
The default filtering functionality can be customized via the following properties:
filterIgnoreCase?: boolean - Filter ignores
case when matching strings. Default value is true.
filterIgnoreAccents?: boolean - Filter
ignores accents when matching strings. Default value is false.
filterMatchFrom?: 'any' | 'start' -
Position in source string to perform match. Default value is 'any'.
getFilterOptionString(option: MenuOption) {'=>'} string -
When defined will take each option and generate a string used in
the filtering process. By default, the stringified version of what is
generated by getOptionLabel, if definded, or the option's label
as a fallback. The MenuOption typed parameter
that getFilterOptionString accepts contains a data property
that represents the objects that comprise your options property.
Demo
);
};
export const Virtualization = () => {
const selectRef = useRef(null);
const optionCountList = useMemo(() => [100, 1000, 10000, 25000, 50000, 100000], []);
const [optionsCount, setOptionsCount] = useState(optionCountList[0]);
const options = useMemo(() => createOptions(optionsCount), [optionsCount]);
useUpdateEffect(() => {
selectRef.current?.clearValue();
}, [options]);
return (
Menu List Virtualization
Option list data is virtualized (or windowed) using
the package. Aside from the
obvious benefits provided by only rendering a small subset of your
enumerable data (rather than bloating the DOM with an excessive amount
of nodes), list virtualization can also assist with:
Efficient memory allocation. 'Windowing' naturally
lends itself to the dynamic generation of attributes/values as each
object comes into your renderer's scope (as opposed to allocating
this data upfront for each object in your list). This way you can
perform this work just when you absolutely need to and then can
immediately release it for the GC to cleanup. As an example I am
generating the onClick, id, and{' '}
className attributes for each menuOption{' '}
as they get passed to the {'<'}Option /{'>'} renderer
component.
Functional architecture. The flexibility provided
through only having to manage subsets of your list allows for a more
dynamic application. By breaking your code out into smaller, 'pure'
child components, you can write code that scales well and becomes
open to performance optimizations - most notably, memoization.
Simple components that rely on the props passed to it (rather than
its own managed state) to generate its JSX are likely candidates for
memoization (testing & debugging becomes much easier as well).
Note: Potential performance degradation could be encountered during input
value mutations when the options count reaches the high tens of thousands.
To work around this, the inputDelay (in milliseconds) can be set to debounce
the input value. That way, the menuOptions will not be recalculated on every
keystroke. Although this is an extreme edge case, optimizations have been implemented to
handle such with ease. As proof, 50k and 100k option counts have been included in this
stress-test demo - but again, data sets this large should not be worked with in memory.
Instead, prefer to fetch subsets from a remote data store as needed. For example, using
the async functionality or custom logic in a parent component that accomplishes
something similar.
Demo
{optionCountList.map((count) => (
))}
);
};
export const Advanced = () => {
const getOptionValue = useCallback(({ id }: PackageOption): number => id, []);
const getIsOptionDisabled = useCallback(({ name }: PackageOption): boolean => name === PACKAGE_OPTIONS[3].name, []);
const renderOptionLabel = useCallback(
(option: PackageOption) => (
{option.name}
),
[getIsOptionDisabled]
);
const customCaretIcon = useCallback(
({ menuOpen }) => (
),
[]
);
return (
Advanced Customization
Implementation using a couple of the more specialized properties.
renderOptionLabel(option: any) {'=>'} ReactNode - Callback
function with a return type of ReactNode. Use this property in cases
where the standard getOptionLabel property will not meet your needs (for
instance, you want to render each option's label using custom JSX). More complex
option labels will likely equate to longer render durations - this can translate
into a flash of empty space when a user first starts scrolling. In order to prevent
this, the menuOverscanCount property can be increased to render additional
rows outside of the visible area. The default value for this property is 1 and it is
important to note that increasing this value can negatively impact performance.
getIsOptionDisabled(option: any) {'=>'} boolean - Callback
function with a return type of Boolean. When it evaluates to a value of
true, that option iteration will be rendered disabled. As an alternative, you
can also pass a property of isDisabled with each option. Use one of these two
options - they cannot both be specified.
caretIcon: ReactNode | (...args: any[]) {'=>'} ReactNode - A custom
node or a function that returns a node can used for the caretIcon property.
When using a function, an object containing stateful data is forwarded and can be used to style
your custom node accordingly. The state is {'{ menuOpen, isLoading, isInvalid, isDisabled }'} of
type Record{'<'}string, boolean{'>'}. The clearIcon property has an identical definition.
Demo
);
};
export const Portaling = () => {
const portalId = 'menu-portal-test';
const options = useMemo(() => createOptions(3), []);
const [menuOpen, setMenuOpen] = useState(false);
const [menuPortalTarget, setMenuPortalTarget] = useState(undefined);
const onMenuOpen = useCallback(() => setMenuOpen(true), []);
const onMenuClose = useCallback(() => setMenuOpen(false), []);
useEffect(() => {
const portalEl = document.getElementById(portalId) as HTMLElement;
setMenuPortalTarget(portalEl);
}, [portalId]);
return (
Portaling
react-functional-select exposes a menuPortalTarget prop, that
allows you to portal the menu component to a dom node of your choosing. Styling
should be simple enough via normal theme overriding on the menu object and style
application to the wrapping portal element.
Demo
portal node
);
};
export const Async = () => {
const delay = 500;
const selectRef = useRef(null);
const [isLoading, setIsLoading] = useState(false);
const [options, setOptions] = useState(() => createAsyncOptions(5));
const onInputChange = useCallback(() => setIsLoading(true), []);
const onSearchChange = useCallback(
async (value: string = '') => {
try {
await mockHttpRequest();
const nextOptions = createAsyncOptions(getRandomInt(1, 5), value && `'${value}'`);
selectRef.current?.clearValue();
setOptions(nextOptions);
setIsLoading(false);
} catch (e) {
console.error(e);
setIsLoading(false);
}
},
[]
);
return (
Async Mode
Add the async property to enable async mode. There is one key
difference in core functionality with async mode - changes to search input
value will not cause the useMenuOptions effect to run. The rest
of hooking into async mode is achieved using some combination of the properties
found below. Properties onInputChange and onSearchChange should be memoized.
onInputChange(value: string) {'=>'} void -
callback executed directly following the input control's onChange event.
This callback is not debounced, so it fires immediately. This is a good
place to set a stateful loading property in your parent component that is mapped to
react-functional-select's isLoading property.
onSearchChange(value: string) {'=>'} void -
callback executed following component state updates for
the debouncedInputValue. The debounce is set using
the inputDelay property. This callback is a good place for your
http fetch request and post-request logic (i.e. setting isLoading false).
inputDelay?: number - As mentioned above, this can be
set to a positive integer in order to debounce updates to the search input value
following input change events. This property directly maps to the delay in
milliseconds passed to the setTimeout method.
isLoading?: boolean - When true, a loading animation will
appear in the far-right of the control and take the place of the clear icon (if shown).
Additionally, it will hide options in the menu and instead, display a loading message.
The loading message text defaults to '{LOADING_MSG_DEFAULT}', but can be overriden via
the loadingMsg property.
Demo
);
};
================================================
FILE: __stories__/types/index.d.ts
================================================
export type Option = Readonly<{
label: string | number;
value: string | number;
}>;
export type CityOption = Readonly<{
id: number;
city: string;
state: string;
}>;
export type PackageOption = Readonly<{
id: number;
name: string;
}>;
================================================
FILE: __tests__/AriaLiveRegion.test.tsx
================================================
import React, { type ComponentProps } from 'react';
import { render } from '@testing-library/react';
import AriaLiveRegion from '../src/components/AriaLiveRegion';
import { getSelectedOptionMulti, ThemeWrapper } from './helpers';
import { ARIA_LIVE_CONTEXT_ID, ARIA_LIVE_SELECTION_ID } from '../src/constants';
import type { AriaLiveAttribute, FocusedOption, SelectedOption } from '../src/types';
type AriaLiveRegionProps = ComponentProps;
// ============================================
// Helper functions for AriaLiveRegion component
// ============================================
const renderAriaLiveRegion = (props: AriaLiveRegionProps) => {
return render(
);
};
const selectedOption: SelectedOption[] = getSelectedOptionMulti();
const focusedOption: FocusedOption = { index: 0, ...selectedOption[0] };
const BASE_PROPS: AriaLiveRegionProps = {
focusedOption,
selectedOption,
menuOpen: true,
isFocused: true,
isSearchable: true,
ariaLive: 'polite',
inputValue: 'search query',
optionCount: selectedOption.length
} as const;
// ============================================
// Test cases
// ============================================
test('AriaLiveRegion component mounts and renders without error & can query childNodes by id attributes', () => {
const { container } = renderAriaLiveRegion(BASE_PROPS);
const childNodeIds = [ARIA_LIVE_CONTEXT_ID, ARIA_LIVE_SELECTION_ID];
childNodeIds.forEach((id) => {
const childNode = container.querySelector(`#${id}`);
expect(childNode).toBeInTheDocument();
});
});
test('"ariaLive" prop can be passed as one of the accepted aria-live values and the root A11yText span element reflects it accordingly', () => {
const ariaLive: AriaLiveAttribute = 'assertive';
const props = { ...BASE_PROPS, ariaLive };
const { container } = renderAriaLiveRegion(props);
const a11yTextRootSpanEl = container.firstChild;
expect(a11yTextRootSpanEl).toHaveAttribute('aria-live', ariaLive);
});
================================================
FILE: __tests__/AutosizeInput.test.tsx
================================================
import React, { type ComponentProps } from 'react';
import { ThemeWrapper } from './helpers';
import userEvent from '@testing-library/user-event';
import { render, fireEvent } from '@testing-library/react';
import AutosizeInput from '../src/components/AutosizeInput';
import { AUTOSIZE_INPUT_CLS, AUTOSIZE_INPUT_TESTID } from '../src/constants';
type AutosizeInputProps = ComponentProps;
// ============================================
// Helper functions for AutosizeInput component
// ============================================
const renderAutosizeInput = (props: AutosizeInputProps) => {
return {
user: userEvent.setup(),
...render(
)
};
};
const onBlurSpy = jest.fn();
const onFocusSpy = jest.fn();
const onChangeSpy = jest.fn();
const BASE_PROPS: AutosizeInputProps = {
inputValue: '',
readOnly: false,
menuOpen: false,
onBlur: onBlurSpy,
onFocus: onFocusSpy,
onChange: onChangeSpy,
hasSelectedOptions: false
} as const;
// ============================================
// Test cases
// ============================================
test('input element has a static className (enables styling via classic CSS)', () => {
const { getByTestId } = renderAutosizeInput(BASE_PROPS);
expect(getByTestId(AUTOSIZE_INPUT_TESTID!)).toHaveClass(AUTOSIZE_INPUT_CLS);
});
test('input has functional, optional ARIA attributes', () => {
const props = {
...BASE_PROPS,
ariaLabel: 'test-label',
ariaLabelledBy: 'test-labelledby',
};
const { getByTestId } = renderAutosizeInput(props);
const ariaAttrs = ['aria-label', 'aria-labelledby', 'aria-autocomplete'];
ariaAttrs.forEach((attr: string) => {
expect(getByTestId(AUTOSIZE_INPUT_TESTID!)).toHaveAttribute(attr);
});
});
test('when "id" has a non-empty string value, input element should get an "id" attribute reflecting that value', () => {
const inputId = 'test-input-id';
const props = { ...BASE_PROPS, id: inputId };
const { getByTestId } = renderAutosizeInput(props);
expect(getByTestId(AUTOSIZE_INPUT_TESTID!)).toHaveAttribute('id', inputId);
});
test('when "readOnly" = true, the onChange event handler should not be attached to input and the "readonly" attribute is added', async () => {
const props = { ...BASE_PROPS, readOnly: true };
const { user, getByTestId } = renderAutosizeInput(props);
const inputElement = getByTestId(AUTOSIZE_INPUT_TESTID!);
await user.type(inputElement, 'no change');
expect(onChangeSpy).not.toBeCalled();
expect(inputElement).toHaveAttribute('readonly');
});
test('"blur" and "focus" events with callback handlers are attached to the input element', () => {
const { getByTestId } = renderAutosizeInput(BASE_PROPS);
const inputElement = getByTestId(AUTOSIZE_INPUT_TESTID!);
fireEvent.blur(inputElement);
fireEvent.focus(inputElement);
expect(onBlurSpy).toBeCalled();
expect(onFocusSpy).toBeCalled();
});
================================================
FILE: __tests__/IndicatorIcons.test.tsx
================================================
import React, { type ReactNode, type ComponentProps } from 'react';
import { ThemeWrapper } from './helpers';
import { render } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import IndicatorIcons from '../src/components/IndicatorIcons';
import { CLEAR_ICON_CLS, CLEAR_ICON_TESTID, CARET_ICON_TESTID } from '../src/constants';
type IndicatorIconsProps = ComponentProps;
// ============================================
// Helper functions for IndicatorIcons component
// ============================================
const renderIndicatorIcons = (props: IndicatorIconsProps) => {
return {
user: userEvent.setup(),
...render(
)
};
};
const onClearMouseDownSpy = jest.fn();
const onCaretMouseDownSpy = jest.fn();
const BASE_PROPS: IndicatorIconsProps = {
menuOpen: false,
showClear: true,
onClearMouseDown: onClearMouseDownSpy,
onCaretMouseDown: onCaretMouseDownSpy
} as const;
const customIconFn = (props: Partial): ReactNode => {
const { menuOpen, isLoading, isInvalid, isDisabled } = props;
const testIdText = `${menuOpen}-${isLoading}-${isInvalid}-${isDisabled}`;
return (
custom_icon
);
};
// ============================================
// Test cases
// ============================================
test('clear icon has a static className (enables styling via classic CSS)', () => {
const { getByTestId } = renderIndicatorIcons(BASE_PROPS);
const firstChildOfClearIconElement = getByTestId(CLEAR_ICON_TESTID!).firstChild;
expect(firstChildOfClearIconElement).toHaveClass(CLEAR_ICON_CLS);
});
test('clear indicator has functioning "click" user interactions', async () => {
const { user, getByTestId } = renderIndicatorIcons(BASE_PROPS);
const clearIndicatorEl = getByTestId(CLEAR_ICON_TESTID!);
await user.click(clearIndicatorEl);
expect(onClearMouseDownSpy).toBeCalled();
});
test('caret indicator has functioning "click" user interactions', async () => {
const { user, getByTestId } = renderIndicatorIcons(BASE_PROPS);
const caretIndicatorEl = getByTestId(CARET_ICON_TESTID!);
await user.click(caretIndicatorEl);
expect(onCaretMouseDownSpy).toBeCalled();
});
test('clear icon is not rendered and loading animation is rendered when "isLoading" = true', () => {
const props = { ...BASE_PROPS, isLoading: true };
const { queryByTestId } = renderIndicatorIcons(props);
expect(queryByTestId(CLEAR_ICON_TESTID!)).toBeNull();
});
test('loading can render as a custom node (instead of default LoadingDots.tsx component)', () => {
const loadingNodeText = 'loading-node';
const loadingNode = {loadingNodeText};
const props = {
...BASE_PROPS,
loadingNode,
isLoading: true,
};
const { getByText } = renderIndicatorIcons(props);
expect(getByText(loadingNodeText)).toBeInTheDocument();
});
test('clear icon can render as a ReactNode', () => {
const clearIconText = 'clear-icon-node';
const clearIcon = {clearIconText};
const props = { ...BASE_PROPS, clearIcon };
const { getByText } = renderIndicatorIcons(props);
expect(getByText(clearIconText)).toBeInTheDocument();
});
test('clear icon can render as a callback function with return type of ReactNode - callback accepts forwarded state props from wrapping component.', () => {
const props = {
...BASE_PROPS,
menuOpen: true,
clearIcon: customIconFn
};
const { getByTestId } = renderIndicatorIcons(props);
// Build test-id from forwarded state javascript object payload
const { menuOpen, isLoading, isInvalid, isDisabled } = props;
const forwardedStateId = `${menuOpen}-${isLoading}-${isInvalid}-${isDisabled}`
expect(getByTestId(forwardedStateId)).toBeInTheDocument();
});
test('caret icon can render as a ReactNode', () => {
const caretIconText = 'caret-icon-node';
const caretIcon = {caretIconText};
const props = { ...BASE_PROPS, caretIcon };
const { getByText } = renderIndicatorIcons(props);
expect(getByText(caretIconText)).toBeInTheDocument();
});
test('caret icon can render as a callback function with return type of ReactNode - callback accepts forwarded state props from wrapping component.', () => {
const props = { ...BASE_PROPS, menuOpen: true, caretIcon: customIconFn };
const { getByTestId } = renderIndicatorIcons(props);
// Build test-id from forwarded state javascript object payload
const { menuOpen, isLoading, isInvalid, isDisabled } = props;
const forwardedStateId = `${menuOpen}-${isLoading}-${isInvalid}-${isDisabled}`
expect(getByTestId(forwardedStateId)).toBeInTheDocument();
});
================================================
FILE: __tests__/LoadingDots.test.tsx
================================================
import React from 'react';
import { ThemeWrapper } from './helpers';
import { render } from '@testing-library/react';
import LoadingDots from '../src/components/IndicatorIcons/LoadingDots';
// ============================================
// Helper functions for AriaLiveRegion component
// ============================================
const renderAriaLiveRegion = () => {
return render(
);
};
// ============================================
// Test cases
// ============================================
test('LoadingDots component mounts and renders without error', () => {
const { container } = renderAriaLiveRegion();
expect(container.hasChildNodes()).toBeTruthy();
});
================================================
FILE: __tests__/MenuList.test.tsx
================================================
import React, { type ComponentProps } from 'react';
import { ThemeWrapper } from './helpers';
import type { MenuOption } from '../src';
import { render } from '@testing-library/react';
import MenuList from '../src/components/Menu/MenuList';
import { MENU_OPTIONS, renderOptionLabelMock } from './helpers/utils';
import {
MENU_ITEM_SIZE_DEFAULT,
MENU_MAX_HEIGHT_DEFAULT,
LOADING_MSG_DEFAULT,
NO_OPTIONS_MSG_DEFAULT,
FOCUSED_OPTION_DEFAULT
} from '../src/constants';
type MenuListProps = ComponentProps;
// ============================================
// Helper functions for Menu component
// ============================================
const renderMenuList = (props: MenuListProps) => {
return render(
);
};
const BASE_PROPS: MenuListProps = {
width: '100%',
memoOptions: false,
menuOptions: MENU_OPTIONS,
itemKeySelector: undefined,
fixedSizeListRef: undefined,
height: MENU_MAX_HEIGHT_DEFAULT,
loadingMsg: LOADING_MSG_DEFAULT,
itemSize: MENU_ITEM_SIZE_DEFAULT,
noOptionsMsg: NO_OPTIONS_MSG_DEFAULT,
selectOption: jest.fn(),
renderOptionLabel: renderOptionLabelMock,
focusedOptionIndex: FOCUSED_OPTION_DEFAULT.index
} as const;
// ============================================
// Test cases
// ============================================
test('MenuList component mounts and renders successfully when "menuOptions" array has items', () => {
const { getByText } = renderMenuList(BASE_PROPS);
// Assert react-window + Option.tsx renders each menuOption correctly
BASE_PROPS.menuOptions.forEach(({ label }: MenuOption) => {
expect(getByText(String(label))).toBeInTheDocument();
});
});
test('The "itemKeySelector" property is used in "react-window" function property "itemKey" to select unqiue key based on property value rather than using default index for each option', () => {
const props = { ...BASE_PROPS, itemKeySelector: 'value' };
const { getByText } = renderMenuList(props);
// Assert react-window + Option.tsx renders each menuOption correctly
props.menuOptions.forEach(({ label }: MenuOption) => {
expect(getByText(String(label))).toBeInTheDocument();
});
});
test('The "No Options" message element is NOT rendered when "menuOptions" length > 0', () => {
const { queryByText } = renderMenuList(BASE_PROPS);
expect(queryByText(BASE_PROPS.noOptionsMsg!)).toBeNull();
});
test('The "No Options" message element is rendered when "menuOptions" length === 0', () => {
const props = { ...BASE_PROPS, menuOptions: [] };
const { getByText } = renderMenuList(props);
expect(getByText(props.noOptionsMsg!)).toBeInTheDocument();
});
test('The "Loading" message element is NOT rendered when "isLoading" !== true', () => {
const { queryByText } = renderMenuList(BASE_PROPS);
expect(queryByText(BASE_PROPS.loadingMsg)).toBeNull();
});
test('The "Loading" message element is rendered when "isLoading" === true', () => {
const props = { ...BASE_PROPS, isLoading: true };
const { getByText } = renderMenuList(props);
expect(getByText(props.loadingMsg)).toBeInTheDocument();
});
================================================
FILE: __tests__/MultiValue.test.tsx
================================================
import React, { type ComponentProps } from 'react';
import { render } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { CLEAR_ICON_MV_TESTID } from '../src/constants';
import MultiValue from '../src/components/Value/MultiValue';
import { renderOptionLabelMock, getOptionSingle, ThemeWrapper, type Option } from './helpers';
type MultiValueProps = ComponentProps;
// ============================================
// Helper functions for MultiValue component
// ============================================
const renderMultiValue = (props: MultiValueProps) => {
return {
user: userEvent.setup(),
...render(
)
};
};
const removeSelectedOptionSpy = jest.fn();
const renderOptionLabelSpy = renderOptionLabelMock;
const data: Option = getOptionSingle();
const BASE_PROPS: MultiValueProps = {
data,
isFocused: false,
value: data.value,
renderOptionLabel: renderOptionLabelSpy,
removeSelectedOption: removeSelectedOptionSpy
} as const;
// ============================================
// Test cases
// ============================================
test('"renderOptionLabel" callback should be executed and should render the selected option label text', () => {
const { getByText } = renderMultiValue(BASE_PROPS);
expect(renderOptionLabelSpy).toBeCalled();
expect(getByText(BASE_PROPS.data.label)).toBeInTheDocument();
});
test('clear indicator has functioning "click" user events', async () => {
const { user, getAllByTestId } = renderMultiValue(BASE_PROPS);
const firstClearIconEl = getAllByTestId(CLEAR_ICON_MV_TESTID!)[0];
await user.click(firstClearIconEl);
expect(removeSelectedOptionSpy).toBeCalled();
});
================================================
FILE: __tests__/Option.test.tsx
================================================
import React, { type ComponentProps } from 'react';
import type { CSSProperties } from 'react';
import { render } from '@testing-library/react';
import Option from '../src/components/Menu/Option';
import userEvent from '@testing-library/user-event';
import { OPTION_DISABLED_CLS } from '../src/constants';
import { renderOptionLabelMock, stringifyCSSProperties, ThemeWrapper, MENU_OPTIONS } from './helpers';
type OptionProps = ComponentProps;
// ============================================
// Helper functions & test data for Option.tsx component
// ============================================
const renderOption = (props: OptionProps) => {
return {
user: userEvent.setup(),
...render(
)
};
};
const OPTION_STYLE: CSSProperties = {
top: '0px',
left: '0px',
width: '100%',
height: '35px',
position: 'absolute'
} as const;
const onClickSelectOptionSpy = jest.fn();
const renderOptionLabelSpy = renderOptionLabelMock;
const createOptionProps = (
index = 0,
focusedOptionIndex = 0,
memoOptions = false
) => {
const props: OptionProps = {
index,
style: OPTION_STYLE,
data: {
memoOptions,
focusedOptionIndex,
menuOptions: MENU_OPTIONS,
selectOption: onClickSelectOptionSpy,
renderOptionLabel: renderOptionLabelSpy
}
};
return {
props,
renderOptionLabelSpy,
onClickSelectOptionSpy
};
};
// ============================================
// Test cases
// ============================================
test('option parent element renders dynamic style attribute correctly', () => {
const { props } = createOptionProps();
const { container } = renderOption(props);
const optionParentEl = container.querySelector('div');
const optionCssProps = stringifyCSSProperties(OPTION_STYLE);
expect(optionParentEl).toHaveAttribute('style', optionCssProps);
});
test('"renderOptionLabel" callback should be executed and the result rendered to DOM', () => {
const { props, renderOptionLabelSpy } = createOptionProps();
const { label } = props.data.menuOptions[props.index];
const { getByText } = renderOption(props);
expect(renderOptionLabelSpy).toHaveBeenCalled();
expect(getByText(String(label))).toBeInTheDocument();
});
test(`option with "isDisabled" = TRUE should have an onClick handler and the ${OPTION_DISABLED_CLS} class added to its classList`, async () => {
const firstDisabledIdx = MENU_OPTIONS.findIndex((x) => x.isDisabled);
const { props, onClickSelectOptionSpy } = createOptionProps(firstDisabledIdx);
const { user, container } = renderOption(props);
const optionParentEl = container.querySelector('div') as HTMLDivElement;
await user.click(optionParentEl);
expect(onClickSelectOptionSpy).toBeCalled();
expect(optionParentEl).toHaveClass(OPTION_DISABLED_CLS);
});
================================================
FILE: __tests__/ReactSSR.test.tsx
================================================
import React from 'react';
import { Select } from '../src';
import { renderToString } from 'react-dom/server';
test('Select component can be rendered using react-dom/server', () => {
expect(() => renderToString()).not.toThrowError();
});
================================================
FILE: __tests__/Select.test.tsx
================================================
import { Select } from '../src';
import React, { type ComponentProps } from 'react';
import userEvent from '@testing-library/user-event';
import { render, fireEvent } from '@testing-library/react';
import {
MENU_CONTAINER_CLS,
SELECT_CONTAINER_CLS,
CONTROL_CONTAINER_CLS,
MENU_CONTAINER_TESTID,
AUTOSIZE_INPUT_TESTID,
SELECT_CONTAINER_TESTID,
CONTROL_CONTAINER_TESTID
} from '../src/constants';
type SelectProps = ComponentProps;
// ============================================
// Helper functions for Select component
// ============================================
const renderSelect = (props?: SelectProps) => ({
user: userEvent.setup(),
...render()
});
// ============================================
// Test cases
// ============================================
test('container elements have static className value (enables styling via classic CSS)', () => {
const { getByTestId } = renderSelect();
expect(getByTestId(SELECT_CONTAINER_TESTID!)).toHaveClass(SELECT_CONTAINER_CLS);
expect(getByTestId(CONTROL_CONTAINER_TESTID!)).toHaveClass(CONTROL_CONTAINER_CLS);
expect(getByTestId(MENU_CONTAINER_TESTID!)).toHaveClass(MENU_CONTAINER_CLS);
});
test('id attributes are added to DOM if defined ("menuId", "selectId", "inputId" props)', () => {
const props = {
menuId: 'test-menu-id',
inputId: 'test-input-id',
selectId: 'test-select-id'
};
const { getByTestId } = renderSelect(props);
expect(getByTestId(MENU_CONTAINER_TESTID!)).toHaveAttribute('id', props.menuId);
expect(getByTestId(AUTOSIZE_INPUT_TESTID!)).toHaveAttribute('id', props.inputId);
expect(getByTestId(SELECT_CONTAINER_TESTID!)).toHaveAttribute('id', props.selectId);
});
test('"onInputFocus" callback should be fired when input is focused (if a defined function)', () => {
const onFocusSpy = jest.fn();
const props = { onInputFocus: onFocusSpy };
const { getByTestId } = renderSelect(props);
fireEvent.focus(getByTestId(AUTOSIZE_INPUT_TESTID!));
expect(onFocusSpy).toBeCalled();
});
test('"onInputBlur" callback should be fired on blur (if a defined function)', () => {
const onBlurSpy = jest.fn();
const props = { onInputBlur: onBlurSpy };
const { getByTestId } = renderSelect(props);
fireEvent.blur(getByTestId(AUTOSIZE_INPUT_TESTID!));
expect(onBlurSpy).toBeCalled();
});
test('toggling the menu to open/close fires corresponding callbacks "onMenuOpen" and "onMenuClose" (if they are defined functions)', async () => {
const onMenuOpenSpy = jest.fn();
const onMenuCloseSpy = jest.fn();
const props = {
onMenuOpen: onMenuOpenSpy,
onMenuClose: onMenuCloseSpy,
};
const { user, getByTestId } = renderSelect(props);
const controlWrapperEl = getByTestId(CONTROL_CONTAINER_TESTID!);
await user.click(controlWrapperEl);
await user.click(controlWrapperEl);
expect(onMenuOpenSpy).toBeCalled();
expect(onMenuCloseSpy).toBeCalled();
});
test('When "lazyLoadMenu" property = true, then menu components are only rendered in DOM when "menuOpen" state = true', () => {
const props = { lazyLoadMenu: true };
const { queryByTestId } = renderSelect(props);
expect(queryByTestId(MENU_CONTAINER_TESTID!)).toBeNull();
});
================================================
FILE: __tests__/Value.test.tsx
================================================
import React, { type ComponentProps } from 'react';
import Value from '../src/components/Value';
import { render } from '@testing-library/react';
import type { CallbackFn, SelectedOption } from '../src/types';
import { PLACEHOLDER_DEFAULT, EMPTY_ARRAY } from '../src/constants';
import { renderOptionLabelMock, renderMultiOptionsMock, getSelectedOptionSingle, ThemeWrapper } from './helpers';
type ValueProps = ComponentProps;
// ============================================
// Helper functions for Value component
// ============================================
const renderValue = (props: ValueProps) => {
return render(
);
};
const rerenderValue = (props: ValueProps, rerender: CallbackFn): void => {
rerender(
);
};
const removeSelectedOptionSpy = jest.fn();
const renderOptionLabelSpy = renderOptionLabelMock;
const renderMultiOptionsSpy = renderMultiOptionsMock;
const BASE_PROPS: ValueProps = {
isMulti: false,
hasInput: false,
focusedMultiValue: null,
selectedOption: EMPTY_ARRAY,
renderMultiOptions: undefined,
placeholder: PLACEHOLDER_DEFAULT,
renderOptionLabel: renderOptionLabelSpy,
removeSelectedOption: removeSelectedOptionSpy
} as const;
// ============================================
// Test cases
// ============================================
test('"placeholder" text displays when no option is selected', () => {
const { getByText } = renderValue(BASE_PROPS);
expect(getByText(PLACEHOLDER_DEFAULT)).toBeInTheDocument();
});
test('component renders NULL if "hasInput" is true AND ("isMulti" !== true OR ("isMulti" === true AND "selectedOptions" is empty))', () => {
// Render with truthy "inputValue" and "isMulti" = false
const singleProps = { ...BASE_PROPS, hasInput: true };
const { container, rerender } = renderValue(singleProps);
expect(container.hasChildNodes()).toBeFalsy();
// Re-render with truthy "inputValue" and "isMulti" = true
const multiProps = { ...singleProps, isMulti: true };
rerenderValue(multiProps, rerender);
expect(container.hasChildNodes()).toBeFalsy();
});
test('"renderOptionLabel" callback should be executed when an option is selected and should render the selected option label text', () => {
const selectedOption = getSelectedOptionSingle();
const props = { ...BASE_PROPS, selectedOption };
const { getByText } = renderValue(props);
expect(renderOptionLabelSpy).toHaveBeenCalledTimes(1);
selectedOption.forEach(({ label }: SelectedOption) => {
expect(getByText(String(label))).toBeInTheDocument();
});
});
test('"renderMultiOptions" callback should be executed when "isMulti" = true and "renderMultiOptions" is a function and at least one option is selected', () => {
const props = {
...BASE_PROPS,
isMulti: true,
selectedOption: getSelectedOptionSingle(),
renderMultiOptions: renderMultiOptionsSpy
};
renderValue(props);
expect(renderMultiOptionsSpy).toHaveBeenCalledTimes(1);
});
================================================
FILE: __tests__/helpers/ThemeWrapper.tsx
================================================
import React from 'react';
import { ThemeProvider } from 'styled-components';
import { DEFAULT_THEME } from '../../src/constants';
const ThemeWrapper = ({ children }) => (
{children}
);
export default ThemeWrapper;
================================================
FILE: __tests__/helpers/index.ts
================================================
export * from './utils';
export { default as ThemeWrapper } from './ThemeWrapper';
================================================
FILE: __tests__/helpers/utils.ts
================================================
import type { ReactNode, CSSProperties } from 'react';
import type { MultiParams, MenuOption } from '../../src';
import type { OptionData, SelectedOption } from '../../src/types';
// ============================================
// Basic "options" & "selectedOption" data
// ============================================
export type Option = Readonly<{
label: string | number;
value: string | number;
}>;
export const OPTIONS: Option[] = [
{ value: 1, label: 'Option 1' },
{ value: 2, label: 'Option 2' }
];
export const getSelectedOptionMulti = (): SelectedOption[] => [...OPTIONS];
export const getOptionSingle = (index: number = 0): Option => ({ ...OPTIONS[index] });
export const getSelectedOptionSingle = (): SelectedOption[] => {
const data = getOptionSingle();
const { value, label } = data;
return [{ data, value, label }];
};
// ============================================
// "menuOptions" data
// ============================================
export const MENU_OPTION_SELECTED: MenuOption = {
isSelected: true,
isDisabled: false,
value: 1,
label: 'Option 1',
data: {
value: 1,
label: 'Option 1'
}
} as const;
export const MENU_OPTION_DISABLED: MenuOption = {
isDisabled: true,
isSelected: false,
value: 2,
label: 'Option 2',
data: {
value: 2,
label: 'Option 2'
}
} as const;
export const MENU_OPTIONS: MenuOption[] = [MENU_OPTION_SELECTED, MENU_OPTION_DISABLED];
// ============================================
// Generic utils & data
// ============================================
export const stringifyCSSProperties = (obj: CSSProperties = {}): string => {
return Object.keys(obj)
.map((key) => `${key}: ${obj[key]};`)
.join(' ');
};
export const renderMultiOptionsMock = jest.fn(
({selected, renderOptionLabel}: MultiParams): ReactNode => {
return selected.map((x) => renderOptionLabel(x.data)).join(', ');
}
);
export const renderOptionLabelMock = jest.fn(({ label }: OptionData): ReactNode => label);
================================================
FILE: babel.config.js
================================================
module.exports = (api) => {
const isTest = api.env('test');
const targets = isTest ? { node: 'current' } : undefined;
const presets = [
['@babel/preset-env', {targets, loose: true}],
['@babel/preset-react', {runtime: 'automatic'}],
'@babel/preset-typescript',
];
const plugins = [
[
'babel-plugin-styled-components',
{
ssr: true,
pure: true,
fileName: false,
minify: !isTest,
displayName: !isTest,
transpileTemplateLiterals: true,
},
],
];
return {
presets,
plugins
};
};
================================================
FILE: jest.config.js
================================================
module.exports = {
transform: {'\\.[jt]sx?$': 'babel-jest'},
testEnvironment: '/.test/custom-test-env.ts',
setupFilesAfterEnv: ['/.test/setup-tests.ts'],
testMatch: ['/__tests__/*?(*.)test.{ts,tsx}'],
testPathIgnorePatterns: ['/node_modules/', '/dist/', '/src/'],
};
================================================
FILE: package.json
================================================
{
"name": "react-functional-select",
"version": "5.0.0",
"description": "Micro-sized and micro-optimized select component for React.js",
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"umd": "dist/index.umd.js",
"types": "dist/index.d.ts",
"files": [
"dist",
"LICENSE",
"README.md"
],
"sideEffects": false,
"license": "MIT",
"author": {
"name": "Matt Areddia",
"email": "mareddia@proton.me"
},
"bugs": {
"url": "https://github.com/based-ghost/react-functional-select/issues"
},
"repository": {
"type": "git",
"url": "https://github.com/based-ghost/react-functional-select.git"
},
"homepage": "https://master--625676b6922472003af898b4.chromatic.com",
"keywords": [
"react",
"react-components",
"react-functional-select",
"select",
"dropdown",
"styled-components",
"virtualization",
"windowing",
"multi-select",
"performance",
"functional"
],
"engines": {
"node": ">= 14"
},
"devDependencies": {
"@babel/cli": "^7.20.7",
"@babel/core": "^7.20.7",
"@babel/plugin-transform-runtime": "^7.19.6",
"@babel/preset-env": "^7.20.2",
"@babel/preset-react": "^7.18.6",
"@babel/preset-typescript": "^7.18.6",
"@rollup/plugin-babel": "^6.0.3",
"@rollup/plugin-replace": "^5.0.2",
"@rollup/plugin-terser": "^0.2.1",
"@rollup/plugin-typescript": "^10.0.1",
"@storybook/addon-storysource": "^6.5.15",
"@storybook/addons": "^6.5.15",
"@storybook/builder-webpack5": "^6.5.15",
"@storybook/manager-webpack5": "^6.5.15",
"@storybook/react": "^6.5.15",
"@storybook/theming": "^6.5.15",
"@testing-library/jest-dom": "^5.16.5",
"@testing-library/react": "^13.4.0",
"@testing-library/user-event": "^14.4.3",
"@types/jest": "^29.2.4",
"@types/node": "^18.11.17",
"@types/react": "^18.0.26",
"@types/react-dom": "^18.0.10",
"@types/react-window": "^1.8.5",
"@types/styled-components": "^5.1.26",
"@typescript-eslint/eslint-plugin": "^5.47.0",
"@typescript-eslint/parser": "^5.47.0",
"babel-jest": "^29.3.1",
"babel-loader": "^9.1.0",
"babel-plugin-styled-components": "^2.0.7",
"chromatic": "^6.14.0",
"cross-env": "^7.0.3",
"eslint": "^8.30.0",
"eslint-config-prettier": "^8.5.0",
"eslint-plugin-prettier": "^4.2.1",
"eslint-plugin-react": "^7.31.11",
"eslint-plugin-react-hooks": "^4.6.0",
"jest": "^29.3.1",
"jest-environment-jsdom": "^29.3.1",
"npm-run-all": "^4.1.5",
"prettier": "^2.8.1",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-syntax-highlighter": "^15.5.0",
"react-toastify": "^9.1.1",
"react-window": "^1.8.8",
"rimraf": "^3.0.2",
"rollup": "^3.8.1",
"styled-components": "^5.3.6",
"typescript": "^4.9.4",
"webpack": "^5.75.0"
},
"peerDependencies": {
"react": ">=16.8.6",
"react-dom": ">=16.8.6",
"react-window": ">=1.8.5",
"styled-components": ">=4.4.0"
},
"scripts": {
"clean-build": "npm-run-all clean build",
"build": "tsc --outDir dist --declarationDir dist --declaration true --emitDeclarationOnly true && rollup --bundleConfigAsCjs -c",
"build-watch": "rollup -c -w",
"clean": "rimraf dist",
"typecheck": "tsc -p --noEmit",
"type-check:watch": "npm run type-check -- --watch",
"test": "cross-env NODE_ENV=test jest -c jest.config.js",
"test:watch": "cross-env NODE_ENV=test jest -c jest.config.js --watch",
"start": "run-s storybook",
"storybook": "start-storybook -c .storybook -p 9009 --no-manager-cache",
"build-storybook": "build-storybook -c .storybook -o storybook-static",
"lint": "eslint \"+(.storybook|__stories__|__tests__|config|src)/**/*.{ts,js}\"",
"chromatic": "chromatic --force-rebuild --auto-accept-changes --exit-zero-on-changes"
},
"dependencies": {
"@babel/runtime": "^7.20.7"
}
}
================================================
FILE: rollup.config.js
================================================
import path from 'path';
import babel from '@rollup/plugin-babel';
import terser from '@rollup/plugin-terser';
import replace from '@rollup/plugin-replace';
import { DEFAULT_EXTENSIONS } from '@babel/core';
import typescript from '@rollup/plugin-typescript';
import pkg from './package.json' assert { type: 'json' };
const globals = {
'react': 'React',
'react-dom': 'ReactDOM',
'styled-components': 'styled',
'react-window': 'ReactWindow'
};
const input = './src/index.ts';
const name = 'ReactFunctionalSelect';
const external = (id) => !id.startsWith('\0') && !id.startsWith('.') && !path.isAbsolute(id);
/**
* Replace Plugin config
*/
const replacePlugin = replace({
preventAssignment: true,
'process.env.NODE_ENV': JSON.stringify('production'),
});
// Remove data-testid attribute (since undefined in non-test environments)
// Perform as final step in transformed, bundled code (for esm and cjs builds)
const removeTestIdPlugin = replace({
preventAssignment: true,
',"data-testid":undefined': '',
delimiters: ['', '']
});
/**
* Babel Plugin config (prevents use of root babel.config.js with babelrc and configFile as false)
*/
const babelPlugin = (useESModules) => {
const targets = useESModules ? { esmodules: true } : undefined;
return babel({
babelrc: false,
configFile: false,
babelHelpers: 'runtime',
exclude: 'node_modules/**',
extensions: [...DEFAULT_EXTENSIONS, '.ts', '.tsx'],
presets: [['@babel/preset-env', {targets, loose: true}], '@babel/preset-react'],
plugins: [
['@babel/plugin-transform-runtime', {useESModules}],
[
'babel-plugin-styled-components',
{
ssr: true,
pure: true,
minify: true,
fileName: false,
displayName: true,
transpileTemplateLiterals: true,
},
],
],
});
};
/**
* Common plugins in each build
*/
const commonPlugins = (useESModules = true) => [
typescript(),
replacePlugin,
babelPlugin(useESModules),
terser(),
removeTestIdPlugin,
];
export default [
// COMMONJS
{
external,
input,
output: {
file: pkg.main,
format: 'cjs',
exports: 'named',
},
plugins: commonPlugins(false),
},
// MODULE
{
external,
input,
output: {
file: pkg.module,
format: 'esm',
},
plugins: commonPlugins(true),
},
// BROWSER/UMD
{
external: Object.keys(globals),
input,
output: {
file: pkg.umd,
format: 'umd',
globals,
name,
},
plugins: commonPlugins(true),
},
];
================================================
FILE: src/Select.tsx
================================================
import React, {
useRef,
useMemo,
useState,
useEffect,
forwardRef,
useCallback,
useImperativeHandle,
type Ref,
type ReactNode,
type FormEvent,
type FocusEvent,
type KeyboardEvent,
type SyntheticEvent,
type FocusEventHandler
} from 'react';
import {
FilterMatchEnum,
OptionIndexEnum,
MenuPositionEnum,
FUNCTIONS,
EMPTY_ARRAY,
DEFAULT_THEME,
PAGE_SIZE_DEFAULT,
PLACEHOLDER_DEFAULT,
LOADING_MSG_DEFAULT,
SELECT_CONTAINER_CLS,
CONTROL_CONTAINER_CLS,
FOCUSED_OPTION_DEFAULT,
NO_OPTIONS_MSG_DEFAULT,
MENU_ITEM_SIZE_DEFAULT,
MENU_MAX_HEIGHT_DEFAULT,
SELECT_CONTAINER_TESTID,
CONTROL_CONTAINER_TESTID
} from './constants';
import type {
Theme,
SelectRef,
OptionData,
MenuOption,
MultiParams,
IconRenderer,
FocusedOption,
SelectedOption,
CallbackFn,
MouseOrTouchEvent,
AriaLiveAttribute,
OptionLabelCallback,
OptionValueCallback,
RenderLabelCallback
} from './types';
import type { FixedSizeList } from 'react-window';
import styled, { css, ThemeProvider, type DefaultTheme } from 'styled-components';
import { Menu, Value, AriaLiveRegion, AutosizeInput, IndicatorIcons } from './components';
import { useDebounce, useLatestRef, useCallbackRef, useMenuOptions, useMountEffect, useUpdateEffect, useMenuPosition } from './hooks';
import { isBoolean, isFunction, isPlainObject, mergeDeep, suppressEvent, normalizeValue, isTouchDevice, isArrayWithLength } from './utils';
type SelectProps = Readonly<{
async?: boolean;
menuId?: string;
inputId?: string;
selectId?: string;
pageSize?: number;
isMulti?: boolean;
ariaLabel?: string;
required?: boolean;
loadingMsg?: string;
autoFocus?: boolean;
isLoading?: boolean;
isInvalid?: boolean;
inputDelay?: number;
themeConfig?: Theme;
isDisabled?: boolean;
placeholder?: string;
menuItemSize?: number;
isClearable?: boolean;
memoOptions?: boolean;
lazyLoadMenu?: boolean;
options?: OptionData[];
isSearchable?: boolean;
menuMaxHeight?: number;
loadingNode?: ReactNode;
ariaLabelledBy?: string;
clearIcon?: IconRenderer;
caretIcon?: IconRenderer;
openMenuOnClick?: boolean;
openMenuOnFocus?: boolean;
menuPortalTarget?: Element;
menuOverscanCount?: number;
tabSelectsOption?: boolean;
filterIgnoreCase?: boolean;
menuScrollDuration?: number;
blurInputOnSelect?: boolean;
closeMenuOnSelect?: boolean;
isAriaLiveEnabled?: boolean;
menuWidth?: string | number;
scrollMenuIntoView?: boolean;
noOptionsMsg?: string | null;
ariaLive?: AriaLiveAttribute;
hideSelectedOptions?: boolean;
filterIgnoreAccents?: boolean;
onMenuOpen?: CallbackFn;
onMenuClose?: CallbackFn;
backspaceClearsValue?: boolean;
menuPosition?: MenuPositionEnum;
filterMatchFrom?: FilterMatchEnum;
menuItemDirection?: 'ltr' | 'rtl';
itemKeySelector?: string | number;
getOptionLabel?: OptionLabelCallback;
getOptionValue?: OptionValueCallback;
initialValue?: OptionData | OptionData[];
onInputChange?: (value?: string) => unknown;
onSearchChange?: (value?: string) => unknown;
onOptionChange?: (data: OptionData) => unknown;
onInputBlur?: FocusEventHandler;
onInputFocus?: FocusEventHandler;
renderOptionLabel?: (data: OptionData) => ReactNode;
getIsOptionDisabled?: (data: OptionData) => boolean;
getFilterOptionString?: (option: MenuOption) => string;
renderMultiOptions?: (params: MultiParams) => ReactNode;
onKeyDown?: (e: KeyboardEvent, input?: string, focusedOption?: FocusedOption) => unknown;
}>;
type ValueWrapperProps = Readonly<{
flex: boolean;
}>;
interface ControlWrapperProps extends Pick {
readonly isFocused: boolean;
}
const SelectWrapper = styled.div`
position: relative;
box-sizing: border-box;
${({ theme }) => theme.select.css}
`;
const ValueWrapper = styled.div`
flex: 1 1 0%;
flex-wrap: wrap;
overflow: hidden;
position: relative;
align-items: center;
box-sizing: border-box;
display: ${({ flex }) => flex ? 'flex' : 'grid'};
padding: ${({ theme }) => theme.control.padding};
`;
const ControlWrapper = styled.div`
outline: 0;
display: flex;
flex-wrap: wrap;
cursor: default;
position: relative;
align-items: center;
box-sizing: border-box;
justify-content: space-between;
${({ isDisabled, isFocused, isInvalid, theme: { control, color } }) => css`
transition: ${control.transition};
border-style: ${control.borderStyle};
border-width: ${control.borderWidth};
border-radius: ${control.borderRadius};
min-height: ${control.height || control.minHeight};
border-color: ${isInvalid
? color.danger
: isFocused
? control.focusedBorderColor
: color.border};
${control.height && `height: ${control.height};`}
${isDisabled && 'pointer-events:none;user-select:none;'}
${(control.backgroundColor || isDisabled) && `background-color: ${isDisabled ? color.disabled : control.backgroundColor};`}
${isFocused && `box-shadow: ${control.boxShadow} ${isInvalid ? color.dangerLight : control.boxShadowColor};`}
`}
${({ theme }) => theme.control.css}
${({ isFocused, theme }) => isFocused && theme.control.focusedCss}
`;
const Select = forwardRef((
{
async,
menuId,
isMulti,
inputId,
selectId,
required,
ariaLive,
autoFocus,
isLoading,
onKeyDown,
clearIcon,
caretIcon,
isInvalid,
ariaLabel,
menuWidth,
isDisabled,
inputDelay,
onMenuOpen,
onMenuClose,
onInputBlur,
isClearable,
themeConfig,
loadingNode,
initialValue,
onInputFocus,
onInputChange,
ariaLabelledBy,
onOptionChange,
onSearchChange,
getOptionLabel,
getOptionValue,
itemKeySelector,
openMenuOnFocus,
menuPortalTarget,
isAriaLiveEnabled,
menuOverscanCount,
blurInputOnSelect,
menuItemDirection,
renderOptionLabel,
renderMultiOptions,
menuScrollDuration,
filterIgnoreAccents,
hideSelectedOptions,
getIsOptionDisabled,
getFilterOptionString,
isSearchable = true,
memoOptions = false,
lazyLoadMenu = false,
openMenuOnClick = true,
filterIgnoreCase = true,
tabSelectsOption = true,
closeMenuOnSelect = true,
scrollMenuIntoView = true,
backspaceClearsValue = true,
filterMatchFrom = FilterMatchEnum.ANY,
menuPosition = MenuPositionEnum.BOTTOM,
options = EMPTY_ARRAY,
pageSize = PAGE_SIZE_DEFAULT,
loadingMsg = LOADING_MSG_DEFAULT,
placeholder = PLACEHOLDER_DEFAULT,
noOptionsMsg = NO_OPTIONS_MSG_DEFAULT,
menuItemSize = MENU_ITEM_SIZE_DEFAULT,
menuMaxHeight = MENU_MAX_HEIGHT_DEFAULT
},
ref: Ref
) => {
// DOM element refs
const listRef = useRef(null);
const menuRef = useRef(null);
const inputRef = useRef(null);
const controlRef = useRef(null);
// Local state values
const [inputValue, setInputValue] = useState('');
const [menuOpen, setMenuOpen] = useState(false);
const [isFocused, setIsFocused] = useState(false);
const [focusedMultiValue, setFocusedMultiValue] = useState(null);
const [focusedOption, setFocusedOption] = useState(FOCUSED_OPTION_DEFAULT);
// Memoized DefaultTheme object for styled-components ThemeProvider
const theme = useMemo(() => {
return isPlainObject(themeConfig)
? mergeDeep(DEFAULT_THEME, themeConfig)
: DEFAULT_THEME;
}, [themeConfig]);
// Memoized callback functions referencing optional function properties on Select.tsx
const getOptionLabelFn = useMemo(() => getOptionLabel || FUNCTIONS.optionLabel, [getOptionLabel]);
const getOptionValueFn = useMemo(() => getOptionValue || FUNCTIONS.optionValue, [getOptionValue]);
const renderOptionLabelFn = useMemo(() => renderOptionLabel || getOptionLabelFn, [renderOptionLabel, getOptionLabelFn]);
// Custom hook abstraction that debounces search input value (opt-in)
const debouncedInputValue = useDebounce(inputValue, inputDelay);
// Custom ref objects
const onSearchChangeFn = useCallbackRef(onSearchChange);
const onOptionChangeFn = useCallbackRef(onOptionChange);
const onSearchChangeIsFn = useLatestRef(isFunction(onSearchChange));
const onOptionChangeIsFn = useLatestRef(isFunction(onOptionChange));
const menuOpenRef = useLatestRef(menuOpen);
const onChangeEvtValue = useRef(false);
const prevMenuOptionsLength = useRef();
// If initialValue is specified attempt to initialize, otherwise default to []
const [selectedOption, setSelectedOption] = useState(
() => normalizeValue(
initialValue,
getOptionValueFn,
getOptionLabelFn
)
);
// Custom hook abstraction that handles the creation of menuOptions
const menuOptions = useMenuOptions(
options,
debouncedInputValue,
filterMatchFrom,
selectedOption,
getOptionValueFn,
getOptionLabelFn,
getIsOptionDisabled,
getFilterOptionString,
filterIgnoreCase,
filterIgnoreAccents,
isMulti,
async,
hideSelectedOptions
);
// Custom hook abstraction that handles calculating menuHeightCalc (defaults to menuMaxHeight) / handles executing callbacks/logic on menuOpen state change.
const { menuStyleTop, menuHeightCalc } = useMenuPosition(
menuRef,
controlRef,
menuOpen,
menuPosition,
menuItemSize,
menuMaxHeight,
menuOptions.length,
!!menuPortalTarget,
onMenuOpen,
onMenuClose,
menuScrollDuration,
scrollMenuIntoView
);
const blurInput = (): void => inputRef.current?.blur();
const focusInput = (): void => inputRef.current?.focus();
const scrollToItemIndex = (idx: number): void => listRef.current?.scrollToItem(idx);
const hasSelectedOptions = isArrayWithLength(selectedOption);
const openMenuAndFocusOption = useCallback((position: OptionIndexEnum): void => {
if (!isArrayWithLength(menuOptions)) {
setMenuOpen(true);
return;
}
const selectedIdx = !isMulti
? menuOptions.findIndex((x) => x.isSelected)
: -1;
const index = selectedIdx > -1
? selectedIdx
: position === OptionIndexEnum.FIRST
? 0
: menuOptions.length - 1;
scrollToItemIndex(index);
setMenuOpen(true);
setFocusedMultiValue(null);
setFocusedOption({ index, ...menuOptions[index] });
}, [isMulti, menuOptions]);
const removeSelectedOption = useCallback((value?: string | number): void => {
setSelectedOption((so) => so.filter((x) => x.value !== value));
}, []);
const selectOption = useCallback((option: MenuOption): void => {
if (option.isDisabled) return;
if (option.isSelected) {
isMulti && removeSelectedOption(option.value);
} else {
const { isSelected, isDisabled, ...selectedOpt } = option;
setSelectedOption((so) => !isMulti ? [selectedOpt] : [...so, selectedOpt]);
}
const blurOrDefault = isBoolean(blurInputOnSelect) ? blurInputOnSelect : isTouchDevice();
if (blurOrDefault) {
blurInput();
} else if (closeMenuOnSelect) {
setInputValue('');
setMenuOpen(false);
}
}, [isMulti, closeMenuOnSelect, blurInputOnSelect, removeSelectedOption]);
/**
* `React.useImperativeHandle`
*
* Exposed API methods/properties available on a ref instance of this Select.tsx component.
* Dependency list passed as the third param to re-create the handle when one of them updates.
*/
useImperativeHandle(
ref,
() => ({
menuOpen: menuOpenRef.current,
blur: blurInput,
focus: focusInput,
clearValue: () => {
setSelectedOption(EMPTY_ARRAY);
setFocusedOption(FOCUSED_OPTION_DEFAULT);
},
setValue: (option?: OptionData) => {
setSelectedOption(
normalizeValue(option, getOptionValueFn, getOptionLabelFn)
);
},
toggleMenu: (state?: boolean) => {
if (state || (state === undefined && !menuOpenRef.current)) {
focusInput();
openMenuAndFocusOption(OptionIndexEnum.FIRST);
} else {
blurInput();
}
}
}),
[menuOpenRef, getOptionValueFn, getOptionLabelFn, openMenuAndFocusOption]
);
/**
* `useMountEffect`
*
* If 'autoFocus' true, focus the control following initial mount
*/
useMountEffect(() => {
if (autoFocus) {
focusInput();
}
});
/**
* `React.useEffect`
*
* If 'onSearchChange' function is defined, run as callback when the stateful debouncedInputValue
* updates check if onChangeEvtValue ref is set true, which indicates the inputValue change was triggered by input change event
*/
useEffect(() => {
if (onSearchChangeIsFn.current && onChangeEvtValue.current) {
onChangeEvtValue.current = false;
onSearchChangeFn(debouncedInputValue);
}
}, [onSearchChangeFn, onSearchChangeIsFn, debouncedInputValue]);
/**
* `useUpdateEffect`
*
* Handle passing 'selectedOption' value(s) to onOptionChange callback function prop (if defined)
*/
useUpdateEffect(() => {
if (onOptionChangeIsFn.current) {
const normalSelectedOpts = isMulti
? selectedOption.map((x) => x.data)
: isArrayWithLength(selectedOption)
? selectedOption[0].data
: null;
onOptionChangeFn(normalSelectedOpts);
}
}, [onOptionChangeFn, onOptionChangeIsFn, isMulti, selectedOption]);
/**
* `useUpdateEffect`
*
* Handle clearing focused option if menuOptions array has 0 length;
* Handle menuOptions changes - conditionally focus first option and do scroll to first option;
* Handle reseting scroll pos to first item after the previous search returned zero results (use prevMenuOptionsLen)
* ...or if there is a selected item and menuOptions is restored to include it, give it focus
*/
useUpdateEffect(() => {
const curLength = menuOptions.length;
const { current: prevLength } = prevMenuOptionsLength;
const inputChanged = curLength > 0 && (async || curLength !== options.length || prevLength === 0);
const menuOpenAndOptionsGrew = menuOpenRef.current && prevLength !== undefined && prevLength < curLength;
if (curLength === 0) {
setFocusedOption(FOCUSED_OPTION_DEFAULT);
} else if (curLength === 1 || inputChanged || menuOpenAndOptionsGrew) {
const index = Math.max(0, menuOptions.findIndex((x) => x.isSelected));
scrollToItemIndex(index);
setFocusedOption({ index, ...menuOptions[index] });
}
prevMenuOptionsLength.current = curLength;
}, [async, options, menuOpenRef, menuOptions]);
const selectOptionFromFocused = (): void => {
const { index, ...menuOpt } = focusedOption;
if (menuOpt.data) {
selectOption(menuOpt as MenuOption);
}
};
// only Multiselect mode supports value focusing (ArrowRight || ArrowLeft)
const focusValueOnArrowKey = (key: string): void => {
if (!hasSelectedOptions) return;
let focusedIdx = -1;
const lastValueIdx = selectedOption.length - 1;
const curFocusedIdx = focusedMultiValue ? selectedOption.findIndex((x) => x.value === focusedMultiValue) : -1;
if (key === 'ArrowRight') {
focusedIdx = (curFocusedIdx > -1 && curFocusedIdx < lastValueIdx)
? curFocusedIdx + 1
: -1;
} else {
focusedIdx = curFocusedIdx !== 0
? curFocusedIdx === -1
? lastValueIdx
: curFocusedIdx - 1
: 0;
}
const nextFocusedVal = focusedIdx > -1
? selectedOption[focusedIdx].value!
: null;
if (focusedOption.data)
setFocusedOption(FOCUSED_OPTION_DEFAULT);
if (nextFocusedVal !== focusedMultiValue)
setFocusedMultiValue(nextFocusedVal);
};
const focusOptionOnArrowKey = (direction: OptionIndexEnum): void => {
if (!isArrayWithLength(menuOptions)) return;
let index = focusedOption.index;
switch (direction) {
case OptionIndexEnum.UP: {
index = (focusedOption.index > 0) ? focusedOption.index - 1 : menuOptions.length - 1;
break;
}
case OptionIndexEnum.DOWN: {
index = (focusedOption.index + 1) % menuOptions.length;
break;
}
case OptionIndexEnum.PAGEUP: {
const pageIdx = focusedOption.index - pageSize;
index = (pageIdx < 0) ? 0 : pageIdx;
break;
}
case OptionIndexEnum.PAGEDOWN: {
const pageIdx = focusedOption.index + pageSize;
index = (pageIdx > menuOptions.length - 1) ? menuOptions.length - 1 : pageIdx;
break;
}
}
scrollToItemIndex(index);
focusedMultiValue && setFocusedMultiValue(null);
setFocusedOption({ index, ...menuOptions[index] });
};
const handleOnKeyDown = (e: KeyboardEvent): void => {
if (isDisabled) return;
if (onKeyDown) {
onKeyDown(e, inputValue, focusedOption);
if (e.defaultPrevented) return;
}
switch (e.key) {
case 'ArrowDown': {
menuOpen ? focusOptionOnArrowKey(OptionIndexEnum.DOWN) : openMenuAndFocusOption(OptionIndexEnum.FIRST);
break;
}
case 'ArrowUp': {
menuOpen ? focusOptionOnArrowKey(OptionIndexEnum.UP) : openMenuAndFocusOption(OptionIndexEnum.LAST);
break;
}
case 'ArrowLeft':
case 'ArrowRight': {
if (!isMulti || inputValue || renderMultiOptions) return;
focusValueOnArrowKey(e.key);
break;
}
case 'PageUp': {
if (!menuOpen) return;
focusOptionOnArrowKey(OptionIndexEnum.PAGEUP);
break;
}
case 'PageDown': {
if (!menuOpen) return;
focusOptionOnArrowKey(OptionIndexEnum.PAGEDOWN);
break;
}
// handle spacebar keydown events
case ' ': {
if (inputValue) return;
if (!menuOpen) {
openMenuAndFocusOption(OptionIndexEnum.FIRST);
} else if (!focusedOption.data) {
return;
} else {
selectOptionFromFocused();
}
break;
}
case 'Enter': {
if (!menuOpen) return;
selectOptionFromFocused();
break;
}
case 'Escape': {
if (menuOpen) {
setMenuOpen(false);
setInputValue('');
}
break;
}
case 'Tab': {
if (e.shiftKey || !menuOpen || !tabSelectsOption || !focusedOption.data) {
return;
}
selectOptionFromFocused();
break;
}
case 'Delete':
case 'Backspace': {
if (inputValue) return;
if (focusedMultiValue) {
const focusedIdx = selectedOption.findIndex((x) => x.value === focusedMultiValue);
const nextFocusedMultiValue = (focusedIdx > -1 && (focusedIdx < (selectedOption.length - 1)))
? selectedOption[focusedIdx + 1].value!
: null;
removeSelectedOption(focusedMultiValue);
setFocusedMultiValue(nextFocusedMultiValue);
} else {
if (!backspaceClearsValue) return;
if (!hasSelectedOptions) break;
if (isMulti && !renderMultiOptions) {
const { value } = selectedOption[selectedOption.length - 1];
removeSelectedOption(value);
} else if (isClearable) {
setSelectedOption(EMPTY_ARRAY);
}
}
break;
}
default:
return;
}
e.preventDefault();
};
const handleOnControlMouseDown = (e: MouseOrTouchEvent): void => {
if (isDisabled) return;
if (!isFocused) focusInput();
const isNotInput = (e.target as HTMLElement).nodeName !== 'INPUT';
if (!menuOpen) {
openMenuOnClick && openMenuAndFocusOption(OptionIndexEnum.FIRST);
} else if (isNotInput) {
setMenuOpen(false);
setInputValue('');
}
if (isNotInput) e.preventDefault();
};
const handleOnInputBlur = (e: FocusEvent): void => {
onInputBlur?.(e);
setIsFocused(false);
setMenuOpen(false);
setInputValue('');
};
const handleOnInputFocus = (e: FocusEvent): void => {
onInputFocus?.(e);
setIsFocused(true);
if (openMenuOnFocus) {
openMenuAndFocusOption(OptionIndexEnum.FIRST);
}
};
const handleOnInputChange = (e: FormEvent): void => {
onChangeEvtValue.current = true;
onInputChange?.(e.currentTarget.value);
setInputValue(e.currentTarget.value);
setMenuOpen(true);
};
// React Hooks linter rules require that this function be memoized in
// ...order to be referenced in deps array of callback functions below
const handleOnMouseDown = useCallback((e: SyntheticEvent): void => {
suppressEvent(e);
focusInput();
}, []);
const handleOnClearMouseDown = useCallback((e: MouseOrTouchEvent): void => {
handleOnMouseDown(e);
setSelectedOption(EMPTY_ARRAY);
}, [handleOnMouseDown]);
const handleOnCaretMouseDown = useCallback((e: MouseOrTouchEvent): void => {
if (!isDisabled && !openMenuOnClick) {
handleOnMouseDown(e);
menuOpenRef.current ? setMenuOpen(false) : openMenuAndFocusOption(OptionIndexEnum.FIRST);
}
}, [isDisabled, menuOpenRef, openMenuOnClick, handleOnMouseDown, openMenuAndFocusOption]);
const flexValueWrapper = !!isMulti && hasSelectedOptions;
const showClear = !!isClearable && !isDisabled && hasSelectedOptions;
return (
{isAriaLiveEnabled && (
)}
);
});
Select.displayName = 'Select';
export default Select;
================================================
FILE: src/components/AriaLiveRegion/index.tsx
================================================
import React from 'react';
import styled from 'styled-components';
import { ARIA_LIVE_SELECTION_ID, ARIA_LIVE_CONTEXT_ID } from '../../constants';
import type { FocusedOption, SelectedOption, AriaLiveAttribute } from '../../types';
type AriaLiveRegionProps = Readonly<{
menuOpen: boolean;
isFocused: boolean;
ariaLabel?: string;
inputValue: string;
optionCount: number;
isSearchable: boolean;
ariaLive?: AriaLiveAttribute;
focusedOption: FocusedOption;
selectedOption: SelectedOption[];
}>;
const A11yText = styled.span`
border: 0;
padding: 0;
width: 1px;
height: 1px;
z-index: 9999;
overflow: hidden;
position: absolute;
white-space: nowrap;
clip-path: inset(50%);
clip: rect(1px, 1px, 1px, 1px);
`;
const AriaLiveRegion: React.FC = ({
menuOpen,
isFocused,
inputValue,
optionCount,
isSearchable,
focusedOption,
selectedOption,
ariaLive = 'polite',
ariaLabel = 'Select'
}) => {
if (!isFocused) {
return null;
}
// message contents for "aria-context"
const { index, label, isDisabled, isSelected } = focusedOption;
const menuMsg = menuOpen
? `Use Up and Down to choose options${isDisabled ? '' : ', press Enter or Tab to select the currently focused option'}, press Escape to close the menu.`
: `${ariaLabel} is focused${isSearchable ? ', type to filter options' : ''}, press Down arrow key to open the menu.`;
const focusedMsg = label
? `Option ${label} is ${isSelected ? 'selected' : 'focused'}${isDisabled ? ' disabled' : ''}, ${index + 1} of ${optionCount}.`
: '';
const optionsMsg = `${optionCount} option(s) available${inputValue ? (' for search ' + inputValue) : ''}.`;
const ariaContextMsg = `${focusedMsg} ${optionsMsg} ${menuMsg}`.trimStart();
// message contents for "aria-selection" SPAN
const selectedLbls = selectedOption.length ? selectedOption.map((x) => x.label).join(' ') : 'N/A';
const selectionMsg = `Selected option: ${selectedLbls}`;
return (
{selectionMsg}
{ariaContextMsg}
);
};
export default AriaLiveRegion;
================================================
FILE: src/components/AutosizeInput/index.tsx
================================================
import styled, { css } from 'styled-components';
import { AUTOSIZE_INPUT_ATTRS } from '../../constants';
import React, { forwardRef, type Ref, type FormEventHandler, type FocusEventHandler } from 'react';
type AutosizeInputProps = Readonly<{
id?: string;
menuId?: string;
menuOpen: boolean;
readOnly: boolean;
ariaLabel?: string;
inputValue: string;
required?: boolean;
isInvalid?: boolean;
ariaLabelledBy?: string;
hasSelectedOptions: boolean;
onBlur: FocusEventHandler;
onFocus: FocusEventHandler;
onChange: FormEventHandler;
}>;
type InputProps = Pick;
const INPUT_BASE_STYLE = css`
border: 0;
margin: 0;
outline: 0;
padding: 0;
font: inherit;
min-width: 2px;
grid-area: 1 / 2 / auto / auto;
`;
const InputWrapper = styled.div`
margin: 2px;
flex: 1 1 auto;
display: inline-grid;
box-sizing: border-box;
grid-area: 1 / 1 / 2 / 3;
grid-template-columns: 0 min-content;
:after {
white-space: pre;
visibility: hidden;
content: attr(data-value) " ";
${INPUT_BASE_STYLE}
}
`;
const Input = styled.input.attrs(AUTOSIZE_INPUT_ATTRS)`
width: 100%;
background: 0;
color: inherit;
${INPUT_BASE_STYLE}
:read-only {
cursor: default;
}
${({ theme }) => theme.input.css}
${({ theme, isInvalid }) => isInvalid && theme.input.cssRequired}
`;
const AutosizeInput = forwardRef((
{
id,
menuId,
onBlur,
onFocus,
onChange,
readOnly,
required,
menuOpen,
ariaLabel,
isInvalid,
inputValue,
ariaLabelledBy
},
ref: Ref
) => (
));
AutosizeInput.displayName = 'AutosizeInput';
export default AutosizeInput;
================================================
FILE: src/components/IndicatorIcons/ClearIcon.tsx
================================================
import React from 'react';
import styled, { css } from 'styled-components';
import { CLEAR_ICON_CLS } from '../../constants';
const ClearSvg = styled.svg`
fill: currentColor;
${({ theme }) => css`
width: ${theme.icon.clear.width};
height: ${theme.icon.clear.height};
animation: ${theme.icon.clear.animation};
transition: ${theme.icon.clear.transition};
`}
`;
const ClearIcon: React.FC = () => (
);
export default ClearIcon;
================================================
FILE: src/components/IndicatorIcons/LoadingDots.tsx
================================================
import React from 'react';
import styled, { css } from 'styled-components';
import { LOADING_DOTS_CLS } from '../../constants';
const StyledLoadingDots = styled.div`
display: flex;
align-self: center;
text-align: center;
margin-right: 0.25rem;
padding: ${({ theme }) => theme.loader.padding};
> div {
border-radius: 100%;
display: inline-block;
${({ theme }) => css`
width: ${theme.loader.size};
height: ${theme.loader.size};
animation: ${theme.loader.animation};
background-color: ${theme.loader.color};
`}
:nth-of-type(1) {
animation-delay: -0.272s;
}
:nth-of-type(2) {
animation-delay: -0.136s;
}
}
`;
const LoadingDots: React.FC = () => (
);
export default LoadingDots;
================================================
FILE: src/components/IndicatorIcons/index.tsx
================================================
import React, { memo, type ReactNode } from 'react';
import ClearIcon from './ClearIcon';
import LoadingDots from './LoadingDots';
import { isFunction } from '../../utils';
import styled, { css } from 'styled-components';
import type { IconRenderer, MouseOrTouchEventHandler } from '../../types';
import { CARET_ICON_CLS, CLEAR_ICON_TESTID, CARET_ICON_TESTID } from '../../constants';
type IndicatorIconsProps = Readonly<{
menuOpen: boolean;
showClear: boolean;
isLoading?: boolean;
isInvalid?: boolean;
isDisabled?: boolean;
loadingNode?: ReactNode;
clearIcon?: IconRenderer;
caretIcon?: IconRenderer;
onClearMouseDown: MouseOrTouchEventHandler;
onCaretMouseDown: MouseOrTouchEventHandler;
}>;
type CaretProps = Pick;
const IndicatorIconsWrapper = styled.div`
display: flex;
flex-shrink: 0;
align-items: center;
align-self: stretch;
box-sizing: border-box;
> span {
width: 1px;
margin: 8px 0;
align-self: stretch;
box-sizing: border-box;
background-color: ${({ theme }) => theme.color.iconSeparator || theme.color.border};
}
`;
const IndicatorIcon = styled.div`
height: 100%;
display: flex;
align-items: center;
box-sizing: border-box;
color: ${({ theme }) => theme.icon.color};
padding: ${({ theme }) => theme.icon.padding};
:hover {
color: ${({ theme }) => theme.icon.hoverColor};
}
${({ theme }) => theme.icon.css}
`;
const Caret = styled.div`
transition: ${({ theme }) => theme.icon.caret.transition};
border-top: ${({ theme }) => theme.icon.caret.size} dashed;
border-left: ${({ theme }) => theme.icon.caret.size} solid transparent;
border-right: ${({ theme }) => theme.icon.caret.size} solid transparent;
${({ theme, menuOpen, isInvalid }) =>
menuOpen &&
css`
transform: rotate(180deg);
color: ${isInvalid ? theme.color.danger : theme.color.caretActive || theme.color.primary};
`}
`;
const IndicatorIcons = memo(({
menuOpen,
clearIcon,
caretIcon,
isInvalid,
showClear,
isLoading,
isDisabled,
loadingNode,
onCaretMouseDown,
onClearMouseDown
}) => {
const iconRenderer = (renderer: IconRenderer): ReactNode => {
return isFunction(renderer)
? renderer({ menuOpen, isLoading, isInvalid, isDisabled })
: renderer;
};
return (
{showClear && !isLoading && (
{iconRenderer(clearIcon) || }
)}
{isLoading && (loadingNode || )}
{iconRenderer(caretIcon) || (
)}
);
});
IndicatorIcons.displayName = 'IndicatorIcons';
export default IndicatorIcons;
================================================
FILE: src/components/Menu/MenuList.tsx
================================================
import React, { useMemo, Fragment, type MutableRefObject } from 'react';
import Option from './Option';
import styled from 'styled-components';
import { isArrayWithLength } from '../../utils';
import { FixedSizeList, type ListItemKeySelector } from 'react-window';
import type { MenuOption, ItemData, RenderLabelCallback } from '../../types';
export type MenuListProps = Readonly<{
height: number;
itemSize: number;
loadingMsg: string;
isLoading?: boolean;
memoOptions: boolean;
overscanCount?: number;
width: string | number;
direction?: 'ltr' | 'rtl';
menuOptions: MenuOption[];
focusedOptionIndex: number;
noOptionsMsg: string | null;
itemKeySelector?: string | number;
renderOptionLabel: RenderLabelCallback;
selectOption: (option: MenuOption) => void;
fixedSizeListRef: MutableRefObject | undefined;
}>;
const NoOptionsMsg = styled.div`
text-align: center;
color: ${({ theme }) => theme.noOptions.color};
margin: ${({ theme }) => theme.noOptions.margin};
padding: ${({ theme }) => theme.noOptions.padding};
font-size: ${({ theme }) => theme.noOptions.fontSize};
${({ theme }) => theme.noOptions.css}
`;
const MenuList: React.FC = ({
width,
height,
itemSize,
direction,
isLoading,
loadingMsg,
menuOptions,
memoOptions,
selectOption,
noOptionsMsg,
overscanCount,
itemKeySelector,
fixedSizeListRef,
renderOptionLabel,
focusedOptionIndex
}) => {
const itemData = useMemo(() => ({
menuOptions,
memoOptions,
selectOption,
renderOptionLabel,
focusedOptionIndex
}), [menuOptions, memoOptions, focusedOptionIndex, selectOption, renderOptionLabel]);
if (isLoading) {
return {loadingMsg};
}
const itemKey: ListItemKeySelector | undefined = itemKeySelector
? (index, data) => data.menuOptions[index][itemKeySelector]
: undefined;
return (
{Option}
{!isArrayWithLength(menuOptions) && noOptionsMsg && (
{noOptionsMsg}
)}
);
};
export default MenuList;
================================================
FILE: src/components/Menu/Option.tsx
================================================
import React, { memo, type CSSProperties } from 'react';
import { areEqual } from 'react-window';
import type { ItemData } from '../../types';
import { buildOptionClass } from '../../utils';
type OptionProps = Readonly<{
index: number;
data: ItemData;
style: CSSProperties;
}>;
// extends react-window 'areEqual'
const _areEqual = (
prevProps: OptionProps,
nextProps: OptionProps
): boolean => {
const { memoOptions } = nextProps.data;
return memoOptions && areEqual(prevProps, nextProps);
};
const Option = memo(({
index,
style,
data: {
menuOptions,
selectOption,
renderOptionLabel,
focusedOptionIndex
}
}) => {
const opt = menuOptions[index];
const className = buildOptionClass(
opt.isDisabled,
opt.isSelected,
index === focusedOptionIndex
);
return (
selectOption(opt)}
>
{renderOptionLabel(opt.data)}
);
}, _areEqual);
Option.displayName = 'Option';
export default Option;
================================================
FILE: src/components/Menu/index.tsx
================================================
import React, { type MutableRefObject } from 'react';
import { createPortal } from 'react-dom';
import styled, { css } from 'styled-components';
import type { MouseOrTouchEvent } from '../../types';
import MenuList, { type MenuListProps } from './MenuList';
import {
OPTION_CLS,
OPTION_FOCUSED_CLS,
OPTION_DISABLED_CLS,
OPTION_SELECTED_CLS,
MENU_CONTAINER_CLS,
MENU_CONTAINER_TESTID
} from '../../constants';
interface MenuProps extends MenuListProps {
readonly id?: string;
readonly menuTop?: string;
readonly menuOpen: boolean;
readonly lazyLoadMenu: boolean;
readonly menuPortalTarget?: Element;
readonly menuRef: MutableRefObject;
readonly onMenuMouseDown: (e: MouseOrTouchEvent) => void;
}
interface MenuWrapperProps extends Pick {
readonly hideNoOptionsMsg: boolean;
}
const MenuWrapper = styled.div`
z-index: 999;
cursor: default;
position: absolute;
${({ menuTop, menuOpen, hideNoOptionsMsg, theme: { menu } }) => css`
width: ${menu.width};
margin: ${menu.margin};
padding: ${menu.padding};
animation: ${menu.animation};
border-radius: ${menu.borderRadius};
background-color: ${menu.backgroundColor};
box-shadow: ${hideNoOptionsMsg ? 'none' : menu.boxShadow};
${!menuOpen && 'display: none;'}
${menuTop && `top: ${menuTop};`}
`}
${({ theme }) => theme.menu.css}
.${OPTION_CLS} {
display: block;
overflow: hidden;
user-select: none;
white-space: nowrap;
text-overflow: ellipsis;
-webkit-tap-highlight-color: transparent;
padding: ${({ theme }) => theme.menu.option.padding};
text-align: ${({ theme }) => theme.menu.option.textAlign};
&.${OPTION_FOCUSED_CLS},
&:hover:not(.${OPTION_DISABLED_CLS}):not(.${OPTION_SELECTED_CLS}) {
background-color: ${({ theme }) => theme.menu.option.focusedBgColor};
}
&.${OPTION_SELECTED_CLS} {
color: ${({ theme }) => theme.menu.option.selectedColor};
background-color: ${({ theme }) => theme.menu.option.selectedBgColor};
}
&.${OPTION_DISABLED_CLS} {
opacity: 0.35;
}
}
`;
const Menu: React.FC = ({
id,
menuRef,
menuTop,
menuOpen,
lazyLoadMenu,
onMenuMouseDown,
menuPortalTarget,
...menuListProps
}) => {
if (lazyLoadMenu && !menuOpen) {
return null;
}
const { menuOptions, noOptionsMsg } = menuListProps;
const hideNoOptionsMsg = menuOpen && !noOptionsMsg && !menuOptions.length;
const menuNode = (
);
return menuPortalTarget
? createPortal(menuNode, menuPortalTarget)
: menuNode;
};
export default Menu;
================================================
FILE: src/components/Value/MultiValue.tsx
================================================
import React from 'react';
import { suppressEvent } from '../../utils';
import styled, { css } from 'styled-components';
import { CLEAR_ICON_MV_TESTID } from '../../constants';
import type { RenderLabelCallback, SelectedOption } from '../../types';
type MultiValueProps = SelectedOption & Readonly<{
isFocused: boolean;
renderOptionLabel: RenderLabelCallback;
removeSelectedOption: (value?: string | number) => void;
}>;
type ClearProps = Pick;
const CLEAR_ICON_FOCUS_STYLE = css`
color: ${({ theme }) => theme.multiValue.clear.focusColor};
`;
const MultiValueWrapper = styled.div`
min-width: 0;
display: flex;
${({ theme: { multiValue } }) => css`
margin: ${multiValue.margin};
animation: ${multiValue.animation};
border-radius: ${multiValue.borderRadius};
background-color: ${multiValue.backgroundColor};
`}
${({ theme }) => theme.multiValue.css}
`;
const Label = styled.div`
overflow: hidden;
white-space: nowrap;
text-overflow: ellipsis;
padding: ${({ theme }) => theme.multiValue.label.padding};
font-size: ${({ theme }) => theme.multiValue.label.fontSize};
border-radius: ${({ theme }) => theme.multiValue.label.borderRadius};
`;
const Clear = styled.i`
display: flex;
font-style: inherit;
${({ theme: { multiValue: { clear } } }) => css`
color: ${clear.color};
padding: ${clear.padding};
font-size: ${clear.fontSize};
align-self: ${clear.alignSelf};
transition: ${clear.transition};
font-weight: ${clear.fontWeight};
&:hover {
${CLEAR_ICON_FOCUS_STYLE}
}
`}
${({ isFocused }) => isFocused && CLEAR_ICON_FOCUS_STYLE}
`;
const MultiValue: React.FC = ({
data,
value,
isFocused,
renderOptionLabel,
removeSelectedOption
}) => {
const handleOnClear = () => removeSelectedOption(value);
return (
✖
);
};
export default MultiValue;
================================================
FILE: src/components/Value/index.tsx
================================================
import React, { memo, Fragment, type ReactNode } from 'react';
import MultiValue from './MultiValue';
import styled from 'styled-components';
import type { MultiParams, SelectedOption, RenderLabelCallback } from '../../types';
type ValueProps = Readonly<{
isMulti?: boolean;
hasInput: boolean;
placeholder: string;
selectedOption: SelectedOption[];
focusedMultiValue: string | number | null;
renderOptionLabel: RenderLabelCallback;
removeSelectedOption: (value?: string | number) => void;
renderMultiOptions?: (params: MultiParams) => ReactNode;
}>;
const SingleValue = styled.div`
margin: 0 2px;
max-width: 100%;
overflow: hidden;
white-space: nowrap;
box-sizing: border-box;
text-overflow: ellipsis;
grid-area: 1 / 1 / 2 / 3;
`;
const Placeholder = styled(SingleValue)`
color: ${({ theme }) => theme.color.placeholder};
`;
const Value = memo(({
isMulti,
hasInput,
placeholder,
selectedOption,
focusedMultiValue,
renderOptionLabel,
renderMultiOptions,
removeSelectedOption
}) => {
if (hasInput && (!isMulti || (isMulti && (!selectedOption.length || renderMultiOptions)))) {
return null;
}
if (!selectedOption.length) {
return {placeholder};
}
if (!isMulti) {
return (
{renderOptionLabel(selectedOption[0].data)}
);
}
return (
{renderMultiOptions
? renderMultiOptions({ renderOptionLabel, selected: selectedOption })
: selectedOption.map(({ data, value }) => (
))}
);
});
Value.displayName = 'Value';
export default Value;
================================================
FILE: src/components/index.ts
================================================
export { default as Menu } from './Menu';
export { default as Value } from './Value';
export { default as AutosizeInput } from './AutosizeInput';
export { default as AriaLiveRegion } from './AriaLiveRegion';
export { default as IndicatorIcons } from './IndicatorIcons';
================================================
FILE: src/constants/defaults.ts
================================================
import type {
FocusedOption,
OptionValueCallback,
OptionLabelCallback,
OptionFilterCallback,
OptionDisabledCallback
} from '../types';
export const PAGE_SIZE_DEFAULT = 5;
export const MENU_ITEM_SIZE_DEFAULT = 35;
export const MENU_MAX_HEIGHT_DEFAULT = 300;
export const LOADING_MSG_DEFAULT = 'Loading..';
export const NO_OPTIONS_MSG_DEFAULT = 'No options';
export const PLACEHOLDER_DEFAULT = 'Select option..';
export const EMPTY_ARRAY: any[] = []; // Default for options and selectedOption props
export const FOCUSED_OPTION_DEFAULT: FocusedOption = { index: -1 };
export const FUNCTIONS = {
optionLabel: ((x) => x.label) as OptionLabelCallback,
optionValue: ((x) => x.value) as OptionValueCallback,
isOptionDisabled: ((x) => !!x.isDisabled) as OptionDisabledCallback,
optionFilter: ((x) => typeof x.label === 'string' ? x.label : '' + x.label) as OptionFilterCallback
};
================================================
FILE: src/constants/dom.ts
================================================
import type { TestableElement } from '../types';
import type { InputHTMLAttributes } from 'react';
// id attributes for AriaLiveRegion.tsx innerHTML content
export const ARIA_LIVE_CONTEXT_ID = 'aria-context';
export const ARIA_LIVE_SELECTION_ID = 'aria-selection';
// classNames (menu options)
export const OPTION_CLS = 'rfs-option';
export const OPTION_FOCUSED_CLS = `${OPTION_CLS}-focused`;
export const OPTION_SELECTED_CLS = `${OPTION_CLS}-selected`;
export const OPTION_DISABLED_CLS = `${OPTION_CLS}-disabled`;
// classNames (containers & icons)
export const CARET_ICON_CLS = 'rfs-caret-icon';
export const CLEAR_ICON_CLS = 'rfs-clear-icon';
export const LOADING_DOTS_CLS = 'rfs-loading-dots';
export const AUTOSIZE_INPUT_CLS = 'rfs-autosize-input';
export const MENU_CONTAINER_CLS = 'rfs-menu-container';
export const SELECT_CONTAINER_CLS = 'rfs-select-container';
export const CONTROL_CONTAINER_CLS = 'rfs-control-container';
// data-testid attributes used for DOM element querying in unit test cases
// ...this attribute gets rendered in development and test environments (removed in production)
const isTest = process.env.NODE_ENV === 'test';
export const CLEAR_ICON_TESTID = isTest ? CLEAR_ICON_CLS : undefined;
export const CARET_ICON_TESTID = isTest ? CARET_ICON_CLS : undefined;
export const AUTOSIZE_INPUT_TESTID = isTest ? AUTOSIZE_INPUT_CLS : undefined;
export const MENU_CONTAINER_TESTID = isTest ? MENU_CONTAINER_CLS : undefined;
export const CLEAR_ICON_MV_TESTID = isTest ? `${CLEAR_ICON_CLS}-mv` : undefined;
export const SELECT_CONTAINER_TESTID = isTest ? SELECT_CONTAINER_CLS : undefined;
export const CONTROL_CONTAINER_TESTID = isTest ? CONTROL_CONTAINER_CLS : undefined;
/**
* Static attributes for 'AutosizeInput' input element
*/
export const AUTOSIZE_INPUT_ATTRS: InputHTMLAttributes & TestableElement = {
tabIndex: 0,
type: 'text',
role: 'combobox',
spellCheck: false,
autoCorrect: 'off',
autoComplete: 'off',
'aria-haspopup': true,
autoCapitalize: 'none',
'aria-autocomplete': 'list',
className: AUTOSIZE_INPUT_CLS,
'data-testid': AUTOSIZE_INPUT_TESTID
} as const;
================================================
FILE: src/constants/enums.ts
================================================
/**
* Menu position in relation to the control.
* Defaults to 'auto' - meaning, if not enough space below control, then place above.
*/
export const MenuPositionEnum = {
TOP: 'top',
AUTO: 'auto',
BOTTOM: 'bottom'
} as const;
export type MenuPositionEnum = typeof MenuPositionEnum[keyof typeof MenuPositionEnum];
/**
* Property filterMatchFrom values. Defaults to 'any'.
* Determines where to match search input in option during filter process.
*/
export const FilterMatchEnum = {
ANY: 'any',
START: 'start'
} as const;
export type FilterMatchEnum = typeof FilterMatchEnum[keyof typeof FilterMatchEnum];
/**
* Arrow key direction OR position for cycling through menu options.
*/
export const OptionIndexEnum = {
UP: 0,
DOWN: 1,
LAST: 2,
FIRST: 3,
PAGEUP: 4,
PAGEDOWN: 5
} as const;
export type OptionIndexEnum = typeof OptionIndexEnum[keyof typeof OptionIndexEnum];
================================================
FILE: src/constants/index.ts
================================================
export * from './dom';
export * from './enums';
export * from './theme';
export * from './styled';
export * from './defaults';
================================================
FILE: src/constants/styled.ts
================================================
import { css, keyframes } from 'styled-components';
const BOUNCE_KEYFRAMES = keyframes`
0%, 80%, 100% {
transform: scale(0);
} 40% {
transform: scale(1.0);
}
`;
const FADE_IN_KEYFRAMES = keyframes`
from {
opacity: 0;
} to {
opacity: 1;
}
`;
export const FADE_IN_ANIMATION_CSS = css`${FADE_IN_KEYFRAMES} 0.2s ease-in`;
export const BOUNCE_ANIMATION_CSS = css`${BOUNCE_KEYFRAMES} 1.19s ease-in-out infinite`;
================================================
FILE: src/constants/theme.ts
================================================
import type { DefaultTheme } from 'styled-components';
import { BOUNCE_ANIMATION_CSS, FADE_IN_ANIMATION_CSS } from './styled';
const color = {
border: '#ced4da',
danger: '#dc3545',
primary: '#007bff',
disabled: '#e9ecef',
placeholder: '#6e7276',
dangerLight: 'rgba(220, 53, 69, 0.25)'
} as const;
export const DEFAULT_THEME: DefaultTheme = {
color,
input: {},
select: {},
loader: {
size: '0.625rem',
padding: '0.375rem 0.75rem',
animation: BOUNCE_ANIMATION_CSS,
color: 'rgba(0, 123, 255, 0.42)'
},
icon: {
color: '#ccc',
hoverColor: '#a6a6a6',
padding: '0 14px',
clear: {
width: '14px',
height: '16px',
animation: FADE_IN_ANIMATION_CSS,
transition: 'color 0.2s ease-out'
},
caret: {
size: '7px',
transition: 'transform 0.3s ease-in-out, color 0.2s ease-out'
}
},
control: {
minHeight: '38px',
borderWidth: '1px',
borderStyle: 'solid',
borderRadius: '3px',
padding: '2px 8px',
boxShadow: '0 0 0 0.2rem',
boxShadowColor: 'rgba(0, 123, 255, 0.25)',
focusedBorderColor: 'rgba(0, 123, 255, 0.75)',
transition: 'box-shadow 0.2s ease-out, border-color 0.2s ease-out'
},
menu: {
padding: '0',
width: '100%',
margin: '0.35rem 0',
borderRadius: '3px',
backgroundColor: '#fff',
animation: FADE_IN_ANIMATION_CSS,
boxShadow: '0 0.5em 1em -0.125em rgb(10 10 10 / 12%), 0 0 0 1px rgb(10 10 10 / 4%)',
option: {
textAlign: 'left',
selectedColor: '#fff',
padding: '0.375rem 0.75rem',
selectedBgColor: color.primary,
focusedBgColor: 'rgba(0, 123, 255, 0.15)'
}
},
noOptions: {
fontSize: '1.25rem',
margin: '0.25rem 0',
color: 'hsl(0, 0%, 60%)',
padding: '0.375rem 0.75rem'
},
multiValue: {
margin: '1px 2px',
borderRadius: '3px',
backgroundColor: '#e7edf3',
animation: FADE_IN_ANIMATION_CSS,
label: {
borderRadius: '3px',
fontSize: '0.825em',
padding: '1px 0 1px 6px'
},
clear: {
fontWeight: 600,
padding: '0 6px',
color: '#a6a6a6',
fontSize: '0.65em',
alignSelf: 'center',
focusColor: color.danger,
transition: 'color 0.2s ease-out'
}
}
} as const;
================================================
FILE: src/globals.d.ts
================================================
import type { FlattenSimpleInterpolation } from 'styled-components';
declare module 'styled-components' {
export interface DefaultTheme {
color: {
border: string;
danger: string;
primary: string;
disabled: string;
placeholder: string;
dangerLight: string;
caretActive?: string;
iconSeparator?: string;
};
select: {
css?: string | FlattenSimpleInterpolation;
};
loader: {
size: string;
color: string;
padding: string;
animation: string | FlattenSimpleInterpolation;
};
icon: {
color: string;
padding: string;
hoverColor: string;
css?: string | FlattenSimpleInterpolation;
clear: {
width: string;
height: string;
transition: string;
animation: string | FlattenSimpleInterpolation;
};
caret: {
size: string;
transition: string;
};
};
control: {
height?: string;
padding: string;
minHeight: string;
boxShadow: string;
transition: string;
borderWidth: string;
borderStyle: string;
borderRadius: string;
boxShadowColor: string;
backgroundColor?: string;
focusedBorderColor: string;
css?: string | FlattenSimpleInterpolation;
focusedCss?: string | FlattenSimpleInterpolation;
},
input: {
css?: string | FlattenSimpleInterpolation;
cssRequired?: string | FlattenSimpleInterpolation;
}
menu: {
margin: string;
padding: string;
boxShadow: string;
borderRadius: string;
width: string | number;
backgroundColor: string;
css?: string | FlattenSimpleInterpolation;
animation: string | FlattenSimpleInterpolation;
option: {
padding: string;
textAlign: string;
selectedColor: string;
focusedBgColor: string;
selectedBgColor: string;
};
};
noOptions: {
color: string;
margin: string;
padding: string;
fontSize: string;
css?: string | FlattenSimpleInterpolation;
};
multiValue: {
margin: string;
borderRadius: string;
backgroundColor: string;
css?: string | FlattenSimpleInterpolation;
animation: string | FlattenSimpleInterpolation;
label: {
padding: string;
fontSize: string;
borderRadius: string;
};
clear: {
color: string;
padding: string;
fontSize: string;
alignSelf: string;
transition: string;
focusColor: string;
fontWeight: string | number;
}
}
}
}
================================================
FILE: src/hooks/index.ts
================================================
export { default as useDebounce } from './useDebounce';
export { default as useLatestRef } from './useLatestRef';
export { default as useMountEffect } from './useMountEffect';
export { default as useMenuOptions } from './useMenuOptions';
export { default as useCallbackRef } from './useCallbackRef';
export { default as useUpdateEffect } from './useUpdateEffect';
export { default as useMenuPosition } from './useMenuPosition';
================================================
FILE: src/hooks/useCallbackRef.ts
================================================
import type { CallbackFn } from '../types';
import { useEffect, useRef, useCallback } from 'react';
/**
* Creates a stable callback function that has access to the latest
* state and can be used within event handlers and effect callbacks.
*
* @param callback the callback to write to ref object
*/
const useCallbackRef = (callback?: T): T => {
const ref = useRef(callback);
useEffect(() => {
ref.current = callback;
});
return useCallback((...args) => ref.current?.(...args), []) as T;
};
export default useCallbackRef;
================================================
FILE: src/hooks/useDebounce.ts
================================================
import { useState } from 'react';
import useUpdateEffect from './useUpdateEffect';
/**
* Debouncer hook (hacky fix to prevent unecessary state mutations if no delay is passed).
* If a number is passed for the delay parameter, use to debounce/set the value.
*
* @param value the value to debounce
* @param delay the delay (ms) for the setTimeout
*/
const useDebounce = (value: T, delay: number = 0): T => {
const [debouncedValue, setDebouncedValue] = useState(value);
useUpdateEffect(() => {
if (delay <= 0) return;
const handler = setTimeout(() => {
setDebouncedValue(value);
}, delay);
return () => {
clearTimeout(handler);
};
}, [value, delay]);
return delay <= 0 ? value : debouncedValue;
};
export default useDebounce;
================================================
FILE: src/hooks/useLatestRef.ts
================================================
import { useRef, type MutableRefObject } from "react"
/**
* Hook to persist value between renders - keeps it up-to-date on changes.
*
* @param value the value to persist
*/
const useLatestRef = (value: T): MutableRefObject => {
const ref = useRef(value);
ref.current = value;
return ref;
};
export default useLatestRef;
================================================
FILE: src/hooks/useMenuOptions.ts
================================================
import { useMemo } from 'react';
import useCallbackRef from './useCallbackRef';
import { FilterMatchEnum, FUNCTIONS } from '../constants';
import { isBoolean, trimAndFormatFilterStr } from '../utils';
import type {
MenuOption,
OptionData,
SelectedOption,
OptionValueCallback,
OptionLabelCallback,
OptionFilterCallback,
OptionDisabledCallback
} from '../types';
/**
* Parse options to array of MenuOptions and perform filtering (if applicable).
*/
const useMenuOptions = (
options: OptionData[],
debouncedInputValue: string,
filterMatchFrom: FilterMatchEnum,
selectedOption: SelectedOption[],
getOptionValue: OptionValueCallback,
getOptionLabel: OptionLabelCallback,
getIsOptionDisabled?: OptionDisabledCallback,
getFilterOptionString?: OptionFilterCallback,
filterIgnoreCase: boolean = false,
filterIgnoreAccents: boolean = false,
isMulti: boolean = false,
async: boolean = false,
hideSelectedOptions?: boolean
): MenuOption[] => {
const getIsOptionDisabledFn = useCallbackRef(getIsOptionDisabled || FUNCTIONS.isOptionDisabled);
const getFilterOptionStringFn = useCallbackRef(getFilterOptionString || FUNCTIONS.optionFilter);
const hideSelectedOptsOrDefault = isBoolean(hideSelectedOptions) ? hideSelectedOptions : isMulti;
const searchValue = !async ? debouncedInputValue : ''; // prevent recomputing on input mutations in async mode
const menuOptions = useMemo(() => {
const selectedValues = selectedOption.map((x) => x.value);
const isFilterMatchAny = filterMatchFrom === FilterMatchEnum.ANY;
const matchVal = trimAndFormatFilterStr(searchValue, filterIgnoreCase, filterIgnoreAccents);
const isOptionFilterMatch = (option: MenuOption): boolean => {
if (!matchVal) return true;
const filterVal = getFilterOptionStringFn(option);
const normalFilterVal = trimAndFormatFilterStr(filterVal, filterIgnoreCase, filterIgnoreAccents);
return isFilterMatchAny
? normalFilterVal.includes(matchVal)
: normalFilterVal.startsWith(matchVal);
};
const parseMenuOption = (data: OptionData): MenuOption | undefined => {
const value = getOptionValue(data);
const label = getOptionLabel(data);
const isDisabled = getIsOptionDisabledFn(data);
const isSelected = selectedValues.includes(value);
const menuOption: MenuOption = { data, value, label, isDisabled, isSelected };
return !isOptionFilterMatch(menuOption) || (hideSelectedOptsOrDefault && isSelected)
? undefined
: menuOption;
};
return options.reduce((acc: MenuOption[], data: OptionData) => {
const menuOption = parseMenuOption(data);
menuOption && acc.push(menuOption);
return acc;
}, []);
}, [
options,
searchValue,
getOptionValue,
getOptionLabel,
selectedOption,
filterMatchFrom,
filterIgnoreCase,
filterIgnoreAccents,
getIsOptionDisabledFn,
getFilterOptionStringFn,
hideSelectedOptsOrDefault
]);
return menuOptions;
};
export default useMenuOptions;
================================================
FILE: src/hooks/useMenuPosition.ts
================================================
import useLatestRef from './useLatestRef';
import type { CallbackFn } from '../types';
import useCallbackRef from './useCallbackRef';
import useUpdateEffect from './useUpdateEffect';
import { MenuPositionEnum } from '../constants';
import { useState, useRef, type RefObject } from 'react';
import { calculateMenuTop, menuFitsBelowControl, scrollMenuIntoViewOnOpen } from '../utils';
type MenuPosition = Readonly<{
menuStyleTop?: string;
menuHeightCalc: number;
}>;
/**
* Handle calculating and maintaining the menuHeight used by react-window.
* Handle scroll animation and callback execution when menuOpen = true.
* Handle resetting menuHeight back to the menuHeightDefault and callback execution when menuOpen = false.
* Use ref to track if the menuHeight was resized, and if so, set the menu height back to default (avoids uncessary renders) with call to setMenuHeight.
* Handle determining where to place the menu in relation to control - when menuPosition = 'top' or menuPosition = 'bottom' and there is not sufficient space below control, place on top.
*/
const useMenuPosition = (
menuRef: RefObject,
controlRef: RefObject,
menuOpen: boolean,
menuPosition: MenuPositionEnum,
menuItemSize: number,
menuHeightDefault: number,
menuOptionsLength: number,
isMenuPortaled: boolean,
onMenuOpen?: CallbackFn,
onMenuClose?: CallbackFn,
menuScrollDuration?: number,
scrollMenuIntoView?: boolean
): MenuPosition => {
const isMenuTopPosition =
menuPosition === MenuPositionEnum.TOP ||
(menuPosition === MenuPositionEnum.AUTO && !menuFitsBelowControl(menuRef.current));
const onMenuOpenFn = useCallbackRef(onMenuOpen);
const onMenuCloseFn = useCallbackRef(onMenuClose);
const resetMenuHeightRef = useRef(false);
const [menuHeight, setMenuHeight] = useState(menuHeightDefault);
const shouldScrollRef = useLatestRef(!isMenuTopPosition && !isMenuPortaled);
useUpdateEffect(() => {
if (menuOpen) {
const handleOnMenuOpen = (availableSpace?: number) => {
onMenuOpenFn();
if (availableSpace) {
resetMenuHeightRef.current = true;
setMenuHeight(availableSpace);
}
};
shouldScrollRef.current
? scrollMenuIntoViewOnOpen(
menuRef.current,
menuScrollDuration,
scrollMenuIntoView,
handleOnMenuOpen
)
: handleOnMenuOpen();
} else {
onMenuCloseFn();
if (resetMenuHeightRef.current) {
resetMenuHeightRef.current = false;
setMenuHeight(menuHeightDefault);
}
}
}, [
menuRef,
menuOpen,
shouldScrollRef,
menuHeightDefault,
scrollMenuIntoView,
menuScrollDuration,
onMenuOpenFn,
onMenuCloseFn
]);
// calculate menu height for react-window
// calculate MenuWrapper el 'top' css prop (if menu is positioned above control)
const menuHeightCalc = Math.min(menuHeight, menuOptionsLength * menuItemSize);
const menuStyleTop = isMenuTopPosition ? calculateMenuTop(menuHeightCalc, menuRef.current, controlRef.current) : undefined;
return {
menuStyleTop,
menuHeightCalc
};
};
export default useMenuPosition;
================================================
FILE: src/hooks/useMountEffect.ts
================================================
import { useEffect, type EffectCallback } from 'react';
/**
* Run an effect only once (on initial mount).
*
* @param effect the effect to execute
*/
const useMountEffect = (effect: EffectCallback): void => {
// eslint-disable-next-line react-hooks/exhaustive-deps
useEffect(effect, []);
};
export default useMountEffect;
================================================
FILE: src/hooks/useUpdateEffect.ts
================================================
import {useRef, useEffect, type EffectCallback, type DependencyList} from 'react';
/**
* `React.useEffect` that will not run on the first render.
*
* @param effect the effect to execute
* @param deps the dependency list
*/
const useUpdateEffect = (effect: EffectCallback, deps?: DependencyList): void => {
const isFirstRender = useRef(true);
useEffect(() => {
if (isFirstRender.current) {
isFirstRender.current = false;
} else {
return effect();
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, deps);
};
export default useUpdateEffect;
================================================
FILE: src/index.ts
================================================
export { default as Select } from './Select';
export type { Theme, SelectRef, MenuOption, MultiParams } from './types';
================================================
FILE: src/types.ts
================================================
import type { DefaultTheme } from 'styled-components';
import type { ReactNode, MouseEvent, TouchEvent, EventHandler } from 'react';
export type OptionData = any;
export type CallbackFn = (...args: any[]) => any;
export type AriaLiveAttribute = 'off' | 'polite' | 'assertive';
export type IconRenderer = ReactNode | ((...args: any[]) => ReactNode);
export type OptionValueCallback = (data: OptionData) => string | number;
export type OptionLabelCallback = OptionValueCallback;
export type RenderLabelCallback = (data: OptionData) => ReactNode;
export type OptionFilterCallback = (option: MenuOption) => string;
export type OptionDisabledCallback = (data: OptionData) => boolean;
export type MouseOrTouchEvent = MouseEvent | TouchEvent;
export type MouseOrTouchEventHandler = EventHandler>;
export type PartialDeep = {
[P in keyof T]?: PartialDeep;
};
export type TestableElement = Readonly<{
'data-testid'?: string;
}>;
export type SelectedOption = Readonly<{
data?: OptionData;
value?: string | number;
label?: string | number;
}>;
export interface FocusedOption extends SelectedOption {
readonly index: number;
readonly isDisabled?: boolean;
readonly isSelected?: boolean;
}
export type ItemData = Readonly<{
memoOptions: boolean;
menuOptions: MenuOption[];
focusedOptionIndex: number;
selectOption: (option: MenuOption) => void;
renderOptionLabel: (data: OptionData) => ReactNode;
}>;
export type MultiParams = Readonly<{
selected: SelectedOption[];
renderOptionLabel: (data: OptionData) => ReactNode;
}>;
export type MenuOption = Readonly<{
label: string | number;
value: string | number;
data: OptionData;
isDisabled: boolean;
isSelected: boolean;
}>;
export type SelectRef = Readonly<{
menuOpen: boolean;
blur: () => void;
focus: () => void;
clearValue: () => void;
toggleMenu: (state?: boolean) => void;
setValue: (option?: OptionData) => void;
}>;
export type Theme = PartialDeep;
================================================
FILE: src/utils/common.ts
================================================
import type { SyntheticEvent } from 'react';
import type { SelectedOption, OptionValueCallback, OptionLabelCallback, CallbackFn } from '../types';
import { OPTION_CLS, EMPTY_ARRAY, OPTION_FOCUSED_CLS, OPTION_SELECTED_CLS, OPTION_DISABLED_CLS } from '../constants';
const DIACRITICS_REG_EXP = /[\u0300-\u036f]/g;
/**
* Strips all diacritics from a string.
*/
const stripDiacritics = (val: string): string => {
return val.normalize('NFD').replace(DIACRITICS_REG_EXP, '');
};
export const isBoolean = (val: unknown): val is boolean => typeof val === 'boolean';
export const isFunction = (val: unknown): val is CallbackFn => typeof val === 'function';
export const isArrayWithLength = (val: unknown): boolean => Array.isArray(val) && !!val.length;
export const isPlainObject = (val: unknown): boolean => val !== null && typeof val === 'object' && !Array.isArray(val);
/**
* Prevent default behavior and propagation of an event
*/
export const suppressEvent = (e: SyntheticEvent): void => {
e.preventDefault();
e.stopPropagation();
};
/**
* Apply regex to string, and if the value is NOT case sensitive,
* call .toLowerCase() and return result
*/
export const trimAndFormatFilterStr = (
value: string,
filterIgnoreCase: boolean,
filterIgnoreAccents: boolean
): string => {
let trimVal = value.trim();
if (filterIgnoreCase) trimVal = trimVal.toLowerCase();
return !filterIgnoreAccents ? trimVal : stripDiacritics(trimVal);
};
/**
* Builds the className property in Option.tsx component
*/
export const buildOptionClass = (
isDisabled: boolean,
isSelected: boolean,
isFocused: boolean
): string => {
let cx = OPTION_CLS;
if (isDisabled) cx += ' ' + OPTION_DISABLED_CLS;
if (isSelected) cx += ' ' + OPTION_SELECTED_CLS;
if (isFocused) cx += ' ' + OPTION_FOCUSED_CLS;
return cx;
};
/**
* Parses an object or an array of objects into output of SelectedOption[]
*/
export const normalizeValue = (
value: unknown,
getOptionValue: OptionValueCallback,
getOptionLabel: OptionLabelCallback
): SelectedOption[] => {
const initVals = Array.isArray(value)
? value
: isPlainObject(value)
? [value]
: EMPTY_ARRAY;
if (!isArrayWithLength(initVals)) {
return initVals;
}
return initVals.map((data) => ({
data,
value: getOptionValue(data),
label: getOptionLabel(data)
}));
};
/**
* Immutable implementation of mergeDeep for two objects. Will return the merged result
* In first condition - check that property is no 'animation', since we never want to
* merge that complex styled-component object
*/
export const mergeDeep = (target: any, source: any): T => {
const output = { ...target };
Object.keys(source).forEach((key) => {
const sourceProp = source[key];
output[key] =
(key !== 'animation' && isPlainObject(sourceProp))
? target[key]
? mergeDeep(target[key], sourceProp)
: sourceProp
: sourceProp;
});
return output;
};
================================================
FILE: src/utils/device.ts
================================================
import { isBoolean } from './common';
let _isTouchDevice: boolean | undefined;
/**
* Determines if the current device is touch-enabled.
* Global, lazy evaluation.
*/
export const isTouchDevice = (): boolean => {
if (isBoolean(_isTouchDevice)) {
return _isTouchDevice;
}
return _isTouchDevice = (() => {
try {
document.createEvent('TouchEvent');
return true;
} catch (e) {
return false;
}
})();
};
================================================
FILE: src/utils/index.ts
================================================
export * from './menu';
export * from './common';
export * from './device';
================================================
FILE: src/utils/menu.ts
================================================
import type { CallbackFn } from '../types';
const getScrollTop = (el: HTMLElement): number => {
return isDocumentElement(el) ? window.pageYOffset : el.scrollTop;
};
const scrollTo = (el: HTMLElement, top: number): void => {
isDocumentElement(el) ? window.scrollTo(0, top) : (el.scrollTop = top);
};
const isDocumentElement = (el: HTMLElement | typeof window): boolean => {
return el === document.body || el === document.documentElement || el === window;
};
const getScrollParent = (el: HTMLElement): HTMLElement => {
let style = getComputedStyle(el);
if (style.position === 'fixed') {
return document.documentElement;
}
const overflowRegExp = /(auto|scroll)/;
const isParentAbs = style.position === 'absolute';
for (let parent: HTMLElement | null = el; (parent = parent?.parentElement);) {
style = getComputedStyle(parent);
if (
!(isParentAbs && style.position === 'static') &&
overflowRegExp.test(`${style.overflow}${style.overflowX}${style.overflowY}`)
) {
return parent;
}
}
return document.documentElement;
};
const smoothScrollTo = (
el: HTMLElement,
to: number,
duration: number = 250,
callback?: CallbackFn
): void => {
let currentTime = 0;
const start = getScrollTop(el);
const change = to - start;
const easeOutCubic = (t: number): number => change * ((t = t / duration - 1) * t * t + 1) + start;
const scrollFn = () => {
currentTime += 5;
const calcScrollTop = easeOutCubic(currentTime);
scrollTo(el, calcScrollTop);
(currentTime < duration) ? requestAnimationFrame(scrollFn) : callback?.();
};
requestAnimationFrame(scrollFn);
};
/**
* Calculates the top property value for the MenuWrapper element
* This property is only generated when the position of the menu is above the control
*/
export const calculateMenuTop = (
menuHeight: number,
menuEl: HTMLElement | null,
controlEl: HTMLElement | null
): string => {
const menuElStyle = menuEl && getComputedStyle(menuEl);
const marginBottom = menuElStyle ? parseInt(menuElStyle.marginBottom, 10) : 0;
const marginTop = menuElStyle ? parseInt(menuElStyle.marginTop, 10) : 0;
const controlHeight = controlEl?.getBoundingClientRect().height ?? 0;
const menuHeightCalc = menuHeight > 0 ? menuHeight : (menuEl?.getBoundingClientRect().height ?? 0);
const basePx = -Math.abs(menuHeightCalc + controlHeight);
return `calc(${basePx}px + ${marginBottom + marginTop}px)`;
};
export const menuFitsBelowControl = (el: HTMLElement | null): boolean => {
if (!el) return true;
const scrollParent = getScrollParent(el);
const { top, height } = el.getBoundingClientRect();
const spaceBelow = scrollParent.getBoundingClientRect().height - getScrollTop(scrollParent) - top;
return spaceBelow >= height;
};
/**
* Calculate space around the control and menu to determine if an animated
* scroll can performed to show the menu in full view. Also, execute a callback if defined
*/
export const scrollMenuIntoViewOnOpen = (
menuEl: HTMLElement | null,
menuScrollDuration: number | undefined,
scrollMenuIntoView: boolean | undefined,
handleOnMenuOpen: (availableSpace?: number) => void
): void => {
if (!menuEl) {
handleOnMenuOpen();
return;
}
const { top, height, bottom } = menuEl.getBoundingClientRect();
const viewInner = window.innerHeight;
const viewSpaceBelow = viewInner - top;
// Menu will fit in available space - no need to do scroll
if (viewSpaceBelow >= height) {
handleOnMenuOpen();
return;
}
const scrollParent = getScrollParent(menuEl);
const scrollTop = getScrollTop(scrollParent);
const spaceBelow = scrollParent.getBoundingClientRect().height - scrollTop - top;
const notEnoughSpaceBelow = spaceBelow < height;
// Sufficient space does not exist to scroll menu fully into view
// Calculate available space and use that as the the new menuHeight (use scrollSpaceBelow for now)
// OR scrollMenuIntoView = false
if (notEnoughSpaceBelow || !scrollMenuIntoView) {
const condensedMenuHeight = notEnoughSpaceBelow ? spaceBelow : undefined;
handleOnMenuOpen(condensedMenuHeight);
return;
}
// Do scroll and upon scroll animation completion, execute the callback if defined
const marginBottom = parseInt(getComputedStyle(menuEl).marginBottom, 10);
const scrollDown = bottom - viewInner + scrollTop + marginBottom;
smoothScrollTo(
scrollParent,
scrollDown,
menuScrollDuration,
handleOnMenuOpen
);
};
================================================
FILE: tsconfig.json
================================================
{
"compilerOptions": {
"jsx": "react",
"target": "ESNext",
"module": "ESNext",
"lib": ["DOM", "DOM.Iterable", "ESNext"],
"moduleResolution": "node",
"strict": true,
"skipLibCheck": true,
"noUnusedLocals": true,
"esModuleInterop": true,
"isolatedModules": true,
"noFallthroughCasesInSwitch": true,
"forceConsistentCasingInFileNames": true
},
"include": [
"src"
],
"exclude": [
"node_modules"
]
}