feat(@clayui/drop-down): add api for controlling the active state of …

…the menu

packages/clay-drop-down/src/DropDown.tsx

@@ -21,6 +21,10 @@ import Section from './Section';
 interface IProps extends React.HTMLAttributes<HTMLDivElement | HTMLLIElement> {
 	/**
 	 * Flag to indicate if the DropDown menu is active or not.
+	 *
+	 * This API is generally used in conjunction with `closeOnClickOutside=true`
+	 * since often we are controlling the active state by clicking another element
+	 * within the document.
 	 */
 	active: boolean;
 
@@ -34,6 +38,10 @@ interface IProps extends React.HTMLAttributes<HTMLDivElement | HTMLLIElement> {
 	 */
 	containerElement?: React.JSXElementConstructor<any> | 'div' | 'li';
 
+	closeOnClickOutside?: React.ComponentProps<
+		typeof Menu
+	>['closeOnClickOutside'];
+
 	/**
 	 * Flag to indicate if menu contains icon symbols on the right side.
 	 */
@@ -55,6 +63,10 @@ interface IProps extends React.HTMLAttributes<HTMLDivElement | HTMLLIElement> {
 
 	/**
 	 * Callback for when the active state changes.
+	 *
+	 * This API is generally used in conjunction with `closeOnClickOutside=true`
+	 * since often we are controlling the active state by clicking another element
+	 * within the document.
 	 */
 	onActiveChange: (val: boolean) => void;
 
@@ -87,6 +99,7 @@ const ClayDropDown: React.FunctionComponent<IProps> & {
 	alignmentPosition,
 	children,
 	className,
+	closeOnClickOutside,
 	containerElement: ContainerElement = 'div',
 	hasLeftSymbols,
 	hasRightSymbols,
@@ -156,6 +169,7 @@ const ClayDropDown: React.FunctionComponent<IProps> & {
 					active={active}
 					alignElementRef={triggerElementRef}
 					alignmentPosition={alignmentPosition}
+					closeOnClickOutside={closeOnClickOutside}
 					hasLeftSymbols={hasLeftSymbols}
 					hasRightSymbols={hasRightSymbols}
 					height={menuHeight}

packages/clay-drop-down/src/DropDownWithItems.tsx

@@ -4,6 +4,7 @@
  */
 
 import {ClayCheckbox, ClayRadio} from '@clayui/form';
+import {useInternalState} from '@clayui/shared';
 import React from 'react';
 import warning from 'warning';
 
@@ -46,6 +47,8 @@ interface IDropDownContentProps {
 }
 
 export interface IProps extends IDropDownContentProps {
+	active?: React.ComponentProps<typeof ClayDropDown>['active'];
+
 	/**
 	 * Default position of menu element. Values come from `./Menu`.
 	 */
@@ -60,6 +63,10 @@ export interface IProps extends IDropDownContentProps {
 
 	className?: string;
 
+	closeOnClickOutside?: React.ComponentProps<
+		typeof ClayDropDown
+	>['closeOnClickOutside'];
+
 	/**
 	 * HTML element tag that the container should render.
 	 */
@@ -99,6 +106,10 @@ export interface IProps extends IDropDownContentProps {
 	 */
 	offsetFn?: React.ComponentProps<typeof ClayDropDown>['offsetFn'];
 
+	onActiveChange?: React.ComponentProps<
+		typeof ClayDropDown
+	>['onActiveChange'];
+
 	/**
 	 * Callback will always be called when the user is interacting with search.
 	 */
@@ -291,9 +302,11 @@ const findNested = <
 	});
 
 export const ClayDropDownWithItems: React.FunctionComponent<IProps> = ({
+	active,
 	alignmentPosition,
 	caption,
 	className,
+	closeOnClickOutside,
 	containerElement,
 	footerContent,
 	helpText,
@@ -302,14 +315,20 @@ export const ClayDropDownWithItems: React.FunctionComponent<IProps> = ({
 	menuHeight,
 	menuWidth,
 	offsetFn,
+	onActiveChange,
 	onSearchValueChange = () => {},
 	searchable,
 	searchProps,
 	searchValue = '',
 	spritemap,
 	trigger,
 }: IProps) => {
-	const [active, setActive] = React.useState(false);
+	const [internalActive, setInternalActive] = useInternalState({
+		initialValue: false,
+		onChange: onActiveChange,
+		value: active,
+	});
+
 	const hasRightSymbols = React.useMemo(
 		() => !!findNested(items, 'symbolRight'),
 		[items]
@@ -323,21 +342,26 @@ export const ClayDropDownWithItems: React.FunctionComponent<IProps> = ({
 
 	return (
 		<ClayDropDown
-			active={active}
+			active={internalActive}
 			alignmentPosition={alignmentPosition}
 			className={className}
+			closeOnClickOutside={closeOnClickOutside}
 			containerElement={containerElement}
 			hasLeftSymbols={hasLeftSymbols}
 			hasRightSymbols={hasRightSymbols}
 			menuElementAttrs={menuElementAttrs}
 			menuHeight={menuHeight}
 			menuWidth={menuWidth}
 			offsetFn={offsetFn}
-			onActiveChange={setActive}
+			onActiveChange={
+				setInternalActive as React.ComponentProps<
+					typeof ClayDropDown
+				>['onActiveChange']
+			}
 			trigger={trigger}
 		>
 			<ClayDropDownContext.Provider
-				value={{close: () => setActive(false)}}
+				value={{close: () => setInternalActive(false)}}
 			>
 				{helpText && <Help>{helpText}</Help>}
 

packages/clay-drop-down/src/Menu.tsx

@@ -120,6 +120,11 @@ interface IProps extends React.HTMLAttributes<HTMLDivElement> {
 	 */
 	alignmentPosition?: number | TPointOptions;
 
+	/**
+	 * Flag to indicate if clicking outside of the menu should automatically close it.
+	 */
+	closeOnClickOutside?: boolean;
+
 	/**
 	 * Flag to indicate if menu is displaying a clay-icon on the left.
 	 */
@@ -165,6 +170,7 @@ const ClayDropDownMenu = React.forwardRef<HTMLDivElement, IProps>(
 			autoBestAlign = true,
 			children,
 			className,
+			closeOnClickOutside = true,
 			hasLeftSymbols,
 			hasRightSymbols,
 			height,
@@ -186,31 +192,33 @@ const ClayDropDownMenu = React.forwardRef<HTMLDivElement, IProps>(
 		const subPortalRef = useRef<HTMLDivElement | null>(null);
 
 		useEffect(() => {
-			const handleClick = (event: MouseEvent) => {
-				const nodeRefs = [alignElementRef, subPortalRef];
-				const nodes: Array<Node> = (Array.isArray(nodeRefs)
-					? nodeRefs
-					: [nodeRefs]
-				)
-					.filter((ref) => ref.current)
-					.map((ref) => ref.current!);
-
-				if (
-					event.target instanceof Node &&
-					!nodes.find((element) =>
-						element.contains(event.target as Node)
+			if (closeOnClickOutside) {
+				const handleClick = (event: MouseEvent) => {
+					const nodeRefs = [alignElementRef, subPortalRef];
+					const nodes: Array<Node> = (Array.isArray(nodeRefs)
+						? nodeRefs
+						: [nodeRefs]
 					)
-				) {
-					onSetActive(false);
-				}
-			};
+						.filter((ref) => ref.current)
+						.map((ref) => ref.current!);
+
+					if (
+						event.target instanceof Node &&
+						!nodes.find((element) =>
+							element.contains(event.target as Node)
+						)
+					) {
+						onSetActive(false);
+					}
+				};
 
-			window.addEventListener('mousedown', handleClick);
+				window.addEventListener('mousedown', handleClick);
 
-			return () => {
-				window.removeEventListener('mousedown', handleClick);
-			};
-		}, []);
+				return () => {
+					window.removeEventListener('mousedown', handleClick);
+				};
+			}
+		}, [closeOnClickOutside]);
 
 		useEffect(() => {
 			const handleEsc = (event: KeyboardEvent) => {