@gravityforms/components/react/admin/modules/SortableList/index.js

UI components for use in Gravity Forms development. Both React and vanilla js flavors.

import { React, PropTypes, classnames } from '@gravityforms/libraries';
import { spacerClasses, trigger } from '@gravityforms/utils';
import SortableItem from './SortableItem';
import Button from '../../elements/Button';
import Box from '../../elements/Box';

const { useRef, useState, useCallback, useEffect } = React;

/**
 * @module SortableList
 * @description A SortableList component to display a list of items that can be reordered with drag and drop or keyboard navigation.
 *
 * @since 3.3.6
 *
 * @param {object}                      props                    Component props.
 * @param {string}                      props.border             The border type.
 * @param {object}                      props.customAttributes   Custom attributes for the component.
 * @param {string|Array|object}         props.customClasses      Custom classes for the component.
 * @param {number}                      props.depth              The current depth of this list.
 * @param {Array}                       props.items              The items for this list.
 * @param {number}                      props.maxNesting         The max number of levels of nesting to allow.
 * @param {object}                      props.newItemProps       The props to use for new items.
 * @param {string | Function | element} props.NewItemTemplate    The template to use for new items.
 * @param {boolean}                     props.showAdd            Whether to show the add button.
 * @param {boolean}                     props.showArrows         Whether to show the navigation arrows.
 * @param {boolean}                     props.showDragHandle     Whether to show the drag handle.
 * @param {boolean}                     props.showDropZone       Whether to show the drop zone.
 * @param                               props.formFieldId
 * @param {string|number|Array|object}  props.spacing            The spacing for the component, as a string, number, array, or object.
 * @param {boolean}                     props.enableExternalDrag Whether to enable drag and drop from external sources.
 * @param {boolean}                     props.showDropIndicators Whether to show visual drop indicators during external drag operations.
 * @param {object}                      props.externalDragConfig Configuration for external drag behavior including selectors and data attributes.
 *
 * @return {JSX.Element} The Sortable List component.
 */
const SortableList = ( {
	customAttributes = {},
	customClasses = [],
	spacing = '',
	items = [],
	formFieldId = 0,
	depth = 0,
	maxNesting = -1,
	showDragHandle = true,
	showArrows = true,
	showAdd = true,
	NewItemTemplate = '',
	newItemProps = {},
	showDropZone = false,
	border = 'dashed',
	enableExternalDrag = false,
	showDropIndicators = false,
	externalDragConfig = {
		dragSourceSelectors: [],
		targetSelector: '',
		dataAttributes: {
			isOver: 'data-is-over-target',
			insertIndex: 'data-insert-index',
		},
	},
} ) => {
	const ref = useRef( null );
	const [ sortableItems, setSortableItems ] = useState( items );
	const [ screenReaderText, setScreenReaderText ] = useState( null );
	const [ dragOverIndex, setDragOverIndex ] = useState( null );
	const [ isReceivingExternalDrag, setIsReceivingExternalDrag ] = useState( false );
	const [ isGloballyDragging, setIsGloballyDragging ] = useState( false );
	const [ newlyAddedId, setNewlyAddedId ] = useState( null );

	const insertionIndexRef = useRef( null );

	useEffect( () => {
		document.addEventListener( 'gform/sortable_list/add_item', addExternalItem );

		// Only add external drag detection if enabled
		if ( enableExternalDrag ) {
			const handleExternalDragStart = ( e ) => {
				if ( ! isValidDragSource( e.target ) ) {
					return;
				}

				setIsGloballyDragging( true );
			};

			const handleExternalDragEnd = () => {
				setIsGloballyDragging( false );
				setIsReceivingExternalDrag( false );
				setDragOverIndex( null );
				insertionIndexRef.current = null;
				clearAllTargetStates();
				clearExternalDragState();
			};

			// Listen for drag events
			document.addEventListener( 'mousedown', handleExternalDragStart );
			document.addEventListener( 'mouseup', handleExternalDragEnd );

			// Listen for mouse movement when dragging from external sources
			document.addEventListener( 'mousemove', handleExternalDragMove );

			return () => {
				document.removeEventListener( 'gform/sortable_list/add_item', addExternalItem );
				document.removeEventListener( 'mousedown', handleExternalDragStart );
				document.removeEventListener( 'mouseup', handleExternalDragEnd );
				document.removeEventListener( 'mousemove', handleExternalDragMove );
			};
		}
		return () => {
			document.removeEventListener( 'gform/sortable_list/add_item', addExternalItem );
		};
	} );

	/**
	 * @function isValidDragSource
	 * @description Check if the target element is a valid drag source based on configuration.
	 *
	 * @since 1.0.0
	 *
	 * @param {Element} target The target element to check.
	 *
	 * @return {boolean} Whether the element is a valid drag source.
	 */
	const isValidDragSource = useCallback( ( target ) => {
		if ( ! externalDragConfig.dragSourceSelectors || externalDragConfig.dragSourceSelectors.length === 0 ) {
			return false;
		}

		return externalDragConfig.dragSourceSelectors.some( ( selector ) =>
			target.closest( selector )
		);
	}, [ externalDragConfig.dragSourceSelectors ] );

	/**
	 * @function clearAllTargetStates
	 * @description Clear data attributes from all target elements to prevent conflicts between multiple lists.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	const clearAllTargetStates = useCallback( () => {
		if ( ! externalDragConfig.targetSelector ) {
			return;
		}

		const allTargets = document.querySelectorAll( externalDragConfig.targetSelector );
		allTargets.forEach( ( target ) => {
			if ( target.hasAttribute( externalDragConfig.dataAttributes.isOver ) ) {
				target.setAttribute( externalDragConfig.dataAttributes.isOver, 'false' );
			}
			if ( target.hasAttribute( externalDragConfig.dataAttributes.insertIndex ) ) {
				target.removeAttribute( externalDragConfig.dataAttributes.insertIndex );
			}
		} );
	}, [ externalDragConfig ] );

	/**
	 * @function calculateDropIndex
	 * @description Calculate the insertion index based on mouse position relative to existing items.
	 *
	 * @since 1.0.0
	 *
	 * @param {number} mouseY The Y position of the mouse relative to the document.
	 *
	 * @return {number} The calculated insertion index.
	 */
	const calculateDropIndex = useCallback( ( mouseY ) => {
		if ( ! ref.current ) {
			return sortableItems.length;
		}

		const siblings = Array.from( ref.current.querySelectorAll( '.gform-sortable-list-item' ) );

		for ( let idx = 0; idx < siblings.length; idx++ ) {
			const el = siblings[ idx ];
			const rect = el.getBoundingClientRect();
			const thisTop = rect.top + document.documentElement.scrollTop;
			const thisMiddle = thisTop + ( rect.height / 2 );

			// For first item, use middle point for more intuitive insertion
			if ( idx === 0 && mouseY < thisMiddle ) {
				return 0;
			}

			// For all items, if mouse is above top, insert before this item
			if ( mouseY < thisTop ) {
				return idx;
			}
		}

		// If we reach here, insert at the end
		return siblings.length;
	}, [ sortableItems.length ] );

	/**
	 * @function isMouseOverThisList
	 * @description Check if the mouse coordinates are over this specific list container.
	 *
	 * @since 1.0.0
	 *
	 * @param {number} clientX The X coordinate of the mouse.
	 * @param {number} clientY The Y coordinate of the mouse.
	 *
	 * @return {boolean} Whether the mouse is over this list.
	 */
	const isMouseOverThisList = useCallback( ( clientX, clientY ) => {
		if ( ! ref.current ) {
			return false;
		}

		const rect = ref.current.getBoundingClientRect();
		const isOverThisListBounds =
			clientX >= rect.left && clientX <= rect.right &&
			clientY >= rect.top && clientY <= rect.bottom;

		if ( ! isOverThisListBounds ) {
			return false;
		}

		// Check if mouse is over any child SortableList
		const childLists = ref.current.querySelectorAll( '.gform-sortable-list' );
		for ( const childList of childLists ) {
			// Skip if it's the current list itself
			if ( childList === ref.current ) {
				continue;
			}

			const childRect = childList.getBoundingClientRect();
			const isOverChild = clientX >= childRect.left && clientX <= childRect.right &&
								clientY >= childRect.top && clientY <= childRect.bottom;

			if ( isOverChild ) {
				// Mouse is over a child list, so it's not over this parent list
				return false;
			}
		}

		return true;
	}, [] );

	/**
	 * @function updateExternalDragState
	 * @description Update the visual state and data attributes when receiving external drag.
	 *
	 * @since 1.0.0
	 *
	 * @param {number} insertIndex The calculated insertion index.
	 *
	 * @return void
	 */
	const updateExternalDragState = useCallback( ( insertIndex ) => {
		if ( ! isReceivingExternalDrag ) {
			setIsReceivingExternalDrag( true );
		}

		if ( ref.current && externalDragConfig.dataAttributes ) {
			ref.current.setAttribute( externalDragConfig.dataAttributes.isOver, 'true' );
			ref.current.setAttribute( externalDragConfig.dataAttributes.insertIndex, insertIndex );
		}

		// Only show drop indicators if enabled
		if ( showDropIndicators ) {
			setDragOverIndex( insertIndex );
		}

		insertionIndexRef.current = insertIndex;
	}, [ isReceivingExternalDrag, showDropIndicators, externalDragConfig ] );

	/**
	 * @function clearExternalDragState
	 * @description Clear the visual state when no longer receiving external drag.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	const clearExternalDragState = useCallback( () => {
		setIsReceivingExternalDrag( false );
		setDragOverIndex( null );
		if ( ref.current && externalDragConfig.dataAttributes ) {
			ref.current.setAttribute( externalDragConfig.dataAttributes.isOver, 'false' );
			// Remove the insert index attribute to prevent interference
			if ( ref.current.hasAttribute( externalDragConfig.dataAttributes.insertIndex ) ) {
				ref.current.removeAttribute( externalDragConfig.dataAttributes.insertIndex );
			}
		}
		insertionIndexRef.current = null;
	}, [ externalDragConfig ] );

	const handleExternalDragMove = useCallback( ( e ) => {
		// Only process if external drag is enabled and we know something is being dragged globally
		if ( ! enableExternalDrag || ! isGloballyDragging || ! ref.current ) {
			return;
		}

		const isOverList = isMouseOverThisList( e.clientX, e.clientY );

		if ( ! isOverList ) {
			if ( isReceivingExternalDrag ) {
				clearExternalDragState();
			}
			return;
		}

		clearAllTargetStates();

		const insertIndex = calculateDropIndex( e.clientY + document.documentElement.scrollTop );
		updateExternalDragState( insertIndex );
	}, [ enableExternalDrag, isGloballyDragging, isReceivingExternalDrag, isMouseOverThisList, calculateDropIndex, clearAllTargetStates, updateExternalDragState, clearExternalDragState ] );

	/**
	 * @function moveItem
	 * @description Moves an item within a list by a given set of positions.
	 *
	 * @since 1.0.0
	 *
	 * @param {number} originIndex The original index of the item.
	 * @param {number} newIndex    The new index of the item.
	 *
	 * @return void
	 */
	const moveItem = useCallback( ( originIndex, newIndex ) => {
		const moved = sortableItems[ originIndex ];
		const filtered = sortableItems.filter( ( item, idx ) => idx !== originIndex );
		const inserted = [ ...filtered.slice( 0, newIndex ), moved, ...filtered.slice( newIndex ) ];
		setSortableItems( inserted );
		trigger( { event: 'gform/sortable_list/item_moved', native: false, data: {
			itemMoved: moved,
			listItems: inserted,
			formFieldId,
		} } );
	}, [ sortableItems ] );

	/**
	 * @function renderSortableList
	 * @description Render a nested SortableList component.
	 *
	 * @since 1.0.0
	 *
	 * @param {number}          origDepth The original depth of the item.
	 * @param {Array | boolean} children  The children of the item.
	 *
	 * @return {JSX.Element|null} The nested SortableList component or null.
	 */
	const renderSortableList = ( origDepth, children ) => {
		if ( maxNesting !== -1 && origDepth >= maxNesting ) {
			return null;
		}

		if ( children === false ) {
			return null;
		}

		const newDepth = origDepth + 1;

		const sortableAttrs = {
			customAttributes,
			customClasses,
			spacing,
			items: children,
			depth: newDepth,
			maxNesting,
			showDragHandle,
			showArrows,
			showAdd,
			showDropZone,
			NewItemTemplate,
			newItemProps,
		};

		return (
			<SortableList { ...sortableAttrs } />
		);
	};

	/**
	 * @function addItem
	 * @description Add an item to the list.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	const addItem = () => {
		const newSortableItem = {
			id: `new-item-${ Date.now() }`,
			body: <NewItemTemplate { ...newItemProps } />,
			children: false,
		};

		const newList = [ ...sortableItems, newSortableItem ];

		setSortableItems( newList );

		trigger( { event: 'gform/sortable_list/item_added', native: false, data: {
			itemAdded: newSortableItem,
			listItems: sortableItems,
			formFieldId,
		} } );
	};

	/**
	 * @function deleteItem
	 * @description Delete an item from the list.
	 *
	 * @since 1.0.0
	 *
	 * @param {string} deleteId ID of the item to be deleted.
	 *
	 * @return void
	 */
	const deleteItem = ( deleteId ) => {
		const filteredItems = sortableItems.filter( ( item ) => deleteId !== item.id );

		setSortableItems( filteredItems );

		trigger( { event: 'gform/sortable_list/item_deleted', native: false, data: {
			deletedId: deleteId,
			listItems: filteredItems,
			formFieldId,
		} } );
	};

	/**
	 * @function addExternalItem
	 * @description Add an item to the list from an external source.
	 *
	 * @since 1.0.0
	 *
	 * @param {Event} e The triggering event with item data in detail property.
	 *
	 * @return void
	 */
	const addExternalItem = ( e ) => {
		if ( ! ref.current ) {
			return;
		}

		let Component;

		const data = e?.detail || {};
		const parent = data?.parent || null;
		const props = data?.props || newItemProps;
		const id = data?.id || `new-item-${ Date.now() }`;
		const children = data?.children || false;
		const componentType = data?.component || 'default';

		if ( parent !== ref.current ) {
			return;
		}

		if ( componentType === 'default' ) {
			Component = NewItemTemplate;
		} else {
			Component = data.component;
		}

		props.deleteItem = deleteItem;
		props.id = id;

		const insertIndex = data.insertIndex !== false ? data.insertIndex : sortableItems.length;

		const newSortableItem = {
			id,
			children,
			body: <Component { ...props } />,
		};

		const inserted = [ ...sortableItems.slice( 0, insertIndex ), newSortableItem, ...sortableItems.slice( insertIndex ) ];

		setSortableItems( inserted );
		setNewlyAddedId( id );

		// Remove the 'new' status after the animation completes
		setTimeout( () => {
			setNewlyAddedId( null );
		}, 100 );
	};

	/**
	 * @function renderListItem
	 * @description Render a list item with all necessary props.
	 *
	 * @since 1.0.0
	 *
	 * @param {object} listItem The list item to render.
	 * @param {number} index    The index to render at.
	 *
	 * @return {JSX.Element|null} The rendered list item component.
	 */
	const renderListItem = ( listItem, index ) => {
		if ( ! listItem ) {
			return null;
		}

		let contents;

		// Handle function-based bodies as in Storybook mock data
		if ( typeof listItem.body === 'function' ) {
			contents = listItem.body( { deleteItem, id: listItem.id } );
		} else {
			contents = React.cloneElement( listItem.body, {
				...listItem.body.props,
				deleteItem,
			} );
		}

		const sortableItemAttrs = {
			totalItems: sortableItems.length,
			depth,
			children: listItem.children,
			listIndex: index,
			key: listItem.id,
			contents,
			id: listItem.id,
			moveItem,
			speak: setScreenReaderText,
			renderSortableList,
			showDragHandle,
			showArrows,
			showDropZone,
			deleteItem,
			isNew: listItem.id === newlyAddedId,
		};

		return (
			<SortableItem { ...sortableItemAttrs } />
		);
	};

	/**
	 * @function renderDropIndicator
	 * @description Render a visual indicator showing where an external item will be dropped.
	 *
	 * @since 1.0.0
	 *
	 * @param {number} index    The index where the indicator should appear.
	 * @param {string} position Additional identifier for unique keys (e.g., 'start', 'end', 'empty').
	 *
	 * @return {JSX.Element} The drop indicator component.
	 */
	const renderDropIndicator = ( index, position = '' ) => {
		const key = position ? `drop-indicator-${ position }-${ index }` : `drop-indicator-${ index }`;
		const isActive = isReceivingExternalDrag && dragOverIndex === index;

		return (
			<div
				key={ key }
				className={ `gform-sortable-list-drop-indicator ${ isActive ? 'is-active' : '' }` }
			/>
		);
	};

	const dropIndicatorStyles = `
		.gform-sortable-list-drop-indicator {
			background: none;
			border: 2px dashed #a7a7a7;
			border-radius: 4px;
			margin: 8px 0;
			height: 60px;
			max-height: 0;
			opacity: 0;
			overflow: hidden;
			pointer-events: none;
			width: 100%;
		}
		.gform-sortable-list-drop-indicator.is-active {
			max-height: 60px;
			opacity: 1;
		}
		.gform-sortable-list-item-wrapper.is-new {
			animation: gform-sortable-list-item-enter 100ms ease-out;
			overflow: hidden;
		}
		@keyframes gform-sortable-list-item-enter {
			from {
				max-height: 60px;
				opacity: 0;
			}
			to {
				max-height: 200px;
				opacity: 1;
			}
		}
	`;

	/**
	 * @function renderEmptyState
	 * @description Render the emptyh state UI.
	 *
	 * @since 1.0.0
	 *
	 * @return {JSX.Element} A JSX element.
	 */
	const renderEmptyState = () => {
		const boxAttrs = {
			customClasses: [
				'gform-sortable-list-empty-wrapper',
			],
			y: 172,
			display: 'flex',
		};

		const buttonArgs = {
			type: 'unstyled',
			size: 'large',
			label: 'Drag Fields Here',
			customClasses: [
				'gform-sortable-list-empty-add-button',
			],
			onClick: addItem,
		};

		return (
			<Box { ...boxAttrs }>
				<Button { ...buttonArgs } />
			</Box>
		);
	};

	const componentAttrs = {
		className: classnames( {
			'gform-sortable-list': true,
			[ `gform-sortable-list--${ border }` ]: true,
			'gform-sortable-list__populated': sortableItems.length,
			...spacerClasses( spacing ),
		}, customClasses ),
		id: `list-wrapper`,
		// Data attributes used by layout_editor.js for drop targeting
		...( formFieldId && { 'data-repeater-field-id': formFieldId } ),
		style: {
			minHeight: sortableItems.length === 0 ? '180px' : 'auto',
			...customAttributes.style,
		},
		...customAttributes,
	};

	const srAttrs = {
		id: 'sortable-list-sr-text',
		className: 'gform-visually-hidden',
		'aria-live': 'polite',
	};

	const addAttrs = {
		label: 'Add',
		type: 'white',
		iconPosition: 'leading',
		onClick: addItem,
		iconPrefix: 'gform-icon',
		icon: 'plus-regular',
	};

	if ( ! showDropZone && ! sortableItems.length ) {
		return null;
	}

	/**
	 * @function renderItemsWithIndicators
	 * @description Render all items with drop indicators interspersed between them.
	 *
	 * @since 1.0.0
	 *
	 * @return {Array} Array of JSX elements including items and indicators.
	 */
	const renderItemsWithIndicators = () => {
		const itemsToRender = [];

		// Handle empty list case
		if ( sortableItems.length === 0 ) {
			if ( showDropIndicators && isReceivingExternalDrag ) {
				return (
					<div
						key="drop-indicator-empty"
						className="gform-sortable-list-drop-indicator is-active"
					/>
				);
			}
			return itemsToRender;
		}

		// Render indicator at the beginning
		itemsToRender.push( renderDropIndicator( 0, 'start' ) );

		sortableItems.forEach( ( listItem, index ) => {
			itemsToRender.push( renderListItem( listItem, index ) );
			// Render indicator after each item
			itemsToRender.push( renderDropIndicator( index + 1, 'after' ) );
		} );

		return itemsToRender;
	};

	return (
		<div { ...componentAttrs } ref={ ref } >
			<style>{ dropIndicatorStyles }</style>
			<div { ...srAttrs } >
				{ screenReaderText }
			</div>
			{ ( ! sortableItems.length > 0 && showDropZone && ! isReceivingExternalDrag ) && renderEmptyState() }
			{ renderItemsWithIndicators() }
			{ ( ( sortableItems.length > 0 || ! showDropZone ) && showAdd ) && <Button { ...addAttrs } /> }
		</div>
	);
};

SortableList.propTypes = {
	customAttributes: PropTypes.object,
	customClasses: PropTypes.oneOfType( [
		PropTypes.string,
		PropTypes.array,
		PropTypes.object,
	] ),
	spacing: PropTypes.oneOfType( [
		PropTypes.string,
		PropTypes.number,
		PropTypes.array,
		PropTypes.object,
	] ),
	items: PropTypes.array,
	formFieldId: PropTypes.number,
	depth: PropTypes.number,
	maxNesting: PropTypes.number,
	showDragHandle: PropTypes.bool,
	showArrows: PropTypes.bool,
	showAdd: PropTypes.bool,
	NewItemTemplate: PropTypes.oneOfType( [
		PropTypes.element,
		PropTypes.func,
		PropTypes.string,
	] ),
	newItemProps: PropTypes.object,
	showDropZone: PropTypes.bool,
	border: PropTypes.string,
	enableExternalDrag: PropTypes.bool,
	showDropIndicators: PropTypes.bool,
	externalDragConfig: PropTypes.shape( {
		dragSourceSelectors: PropTypes.arrayOf( PropTypes.string ).isRequired,
		targetSelector: PropTypes.string.isRequired,
		dataAttributes: PropTypes.shape( {
			isOver: PropTypes.string.isRequired,
			insertIndex: PropTypes.string.isRequired,
		} ).isRequired,
	} ),
};

SortableList.displayName = 'SortableList';

export default SortableList;