@wordpress/components 28.11.0 → 28.13.1-next.082ed6819.0

package/src/slot-fill/README.md

@@ -1,18 +1,18 @@
-# Slot Fill
+# Slot/Fill
 
-Slot and Fill are a pair of components which enable developers to render elsewhere in a React element tree, a pattern often referred to as "portal" rendering. It is a pattern for component extensibility, where a single Slot may be occupied by an indeterminate number of Fills elsewhere in the application.
+`Slot` and `Fill` are a pair of components which enable developers to render React UI elsewhere in a React element tree, a pattern often referred to as "portal" rendering. It is a pattern for component extensibility, where a single `Slot` may be occupied by multiple `Fill`s rendered in different parts of the application.
 
-Slot Fill is heavily inspired by the [`react-slot-fill` library](https://github.com/camwest/react-slot-fill), but uses React's own portal rendering API.
+Slot/Fill was originally inspired by the [`react-slot-fill` library](https://github.com/camwest/react-slot-fill).
 
 ## Usage
 
-At the root of your application, you must render a `SlotFillProvider` which coordinates Slot and Fill rendering.
+At the root of your application, you must render a `SlotFillProvider` which coordinates `Slot` and `Fill` rendering.
 
-Then, render a Slot component anywhere in your application, giving it a name.
+Then, render a `Slot` component anywhere in your application, giving it a `name`. The `name` is either a `string` or a symbol. Symbol names are useful for slots that are supposed to be private, accessible only to clients that have access to the symbol value.
 
-Any Fill will automatically occupy this Slot space, even if rendered elsewhere in the application.
+Any `Fill` will render its UI in this `Slot` space, even if rendered elsewhere in the application.
 
-You can either use the Fill component directly, or a wrapper component type as in the below example to abstract the slot name from consumer awareness.
+You can either use the `Fill` component directly, or create a wrapper component (as in the following example) to hide the slot name from the consumer.
 
 ```jsx
 import {
@@ -43,7 +43,7 @@ const MySlotFillProvider = () => {
 };
 ```
 
-There is also `createSlotFill` helper method which was created to simplify the process of matching the corresponding `Slot` and `Fill` components:
+There is also the `createSlotFill` helper method which was created to simplify the process of matching the corresponding `Slot` and `Fill` components:
 
 ```jsx
 const { Fill, Slot } = createSlotFill( 'Toolbar' );
@@ -59,18 +59,27 @@ const Toolbar = () => (
 
 ## Props
 
-The `SlotFillProvider` component does not accept any props.
+The `SlotFillProvider` component does not accept any props (except `children`).
 
 Both `Slot` and `Fill` accept a `name` string prop, where a `Slot` with a given `name` will render the `children` of any associated `Fill`s.
 
-`Slot` accepts a `bubblesVirtually` prop which changes the event bubbling behaviour:
+`Slot` accepts a `bubblesVirtually` prop which changes the method how the `Fill` children are rendered. With `bubblesVirtually`, the `Fill` is rendered using a React portal. That affects the event bubbling and React context propagation behaviour:
 
--   By default, events will bubble to their parents on the DOM hierarchy (native event bubbling)
--   If `bubblesVirtually` is set to true, events will bubble to their virtual parent in the React elements hierarchy instead.
+### `bubblesVirtually=false`
 
-`Slot` with `bubblesVirtually` set to true also accept optional `className` and `style` props to add to the slot container.
+-   events will bubble to their parents on the DOM hierarchy (native event bubbling)
+-   the React elements inside the `Fill` will be rendered with React context of the `Slot`
+-   renders the `Fill` elements directly, inside a `Fragment`, with no wrapper DOM element
 
-`Slot` **without** `bubblesVirtually` accepts an optional `children` function prop, which takes `fills` as a param. It allows you to perform additional processing and wrap `fills` conditionally.
+### `bubblesVirtually=true`
+
+-   events will bubble to their virtual (React) parent in the React elements hierarchy
+-   the React elements inside the `Fill` will keep the React context of the `Fill` and its parents
+-   renders a wrapper DOM element inside which the `Fill` elements are rendered (used as an argument for React `createPortal`)
+
+`Slot` with `bubblesVirtually=true` renders a wrapper DOM element (a `div` by default) and accepts additional props that customize this element, like `className` or `style`. You can also replace the `div` with another element by passing an `as` prop.
+
+`Slot` **without** `bubblesVirtually` accepts an optional `children` prop, which is a function that receives `fills` array as a param. It allows you to perform additional processing: render a placeholder when there are no fills, or render a wrapper only when there are fills.
 
 _Example_:
 
@@ -90,7 +99,9 @@ const Toolbar = ( { isMobile } ) => (
 );
 ```
 
-Props can also be passed from a `Slot` to a `Fill` by using the prop `fillProps` on the `Slot`:
+Additional information (props) can also be passed from a `Slot` to a `Fill` by a combination of:
+1. Adding a `fillProps` prop to the `Slot`.
+2. Passing a function as `children` to the `Fill`. This function will receive the `fillProps` as an argument.
 
 ```jsx
 const { Fill, Slot } = createSlotFill( 'Toolbar' );

package/src/slot-fill/bubbles-virtually/fill.tsx

@@ -1,50 +1,40 @@
 /**
  * WordPress dependencies
  */
-import { useRef, useState, useEffect, createPortal } from '@wordpress/element';
+import { useObservableValue } from '@wordpress/compose';
+import {
+	useContext,
+	useReducer,
+	useRef,
+	useEffect,
+	createPortal,
+} from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
-import useSlot from './use-slot';
+import SlotFillContext from './slot-fill-context';
 import StyleProvider from '../../style-provider';
 import type { FillComponentProps } from '../types';
 
-function useForceUpdate() {
-	const [ , setState ] = useState( {} );
-	const mountedRef = useRef( true );
-
-	useEffect( () => {
-		mountedRef.current = true;
-		return () => {
-			mountedRef.current = false;
-		};
-	}, [] );
-
-	return () => {
-		if ( mountedRef.current ) {
-			setState( {} );
-		}
-	};
-}
-
-export default function Fill( props: FillComponentProps ) {
-	const { name, children } = props;
-	const { registerFill, unregisterFill, ...slot } = useSlot( name );
-	const rerender = useForceUpdate();
+export default function Fill( { name, children }: FillComponentProps ) {
+	const registry = useContext( SlotFillContext );
+	const slot = useObservableValue( registry.slots, name );
+	const [ , rerender ] = useReducer( () => [], [] );
 	const ref = useRef( { rerender } );
 
 	useEffect( () => {
 		// We register fills so we can keep track of their existence.
 		// Some Slot implementations need to know if there're already fills
 		// registered so they can choose to render themselves or not.
-		registerFill( ref );
+		const refValue = ref.current;
+		registry.registerFill( name, refValue );
 		return () => {
-			unregisterFill( ref );
+			registry.unregisterFill( name, refValue );
 		};
-	}, [ registerFill, unregisterFill ] );
+	}, [ registry, name ] );
 
-	if ( ! slot.ref || ! slot.ref.current ) {
+	if ( ! slot || ! slot.ref.current ) {
 		return null;
 	}
 

package/src/slot-fill/bubbles-virtually/slot-fill-provider.tsx

@@ -34,15 +34,23 @@ function createSlotRegistry(): SlotFillBubblesVirtuallyContext {
 
 	const unregisterSlot: SlotFillBubblesVirtuallyContext[ 'unregisterSlot' ] =
 		( name, ref ) => {
+			const slot = slots.get( name );
+			if ( ! slot ) {
+				return;
+			}
+
 			// Make sure we're not unregistering a slot registered by another element
 			// See https://github.com/WordPress/gutenberg/pull/19242#issuecomment-590295412
-			if ( slots.get( name )?.ref === ref ) {
-				slots.delete( name );
+			if ( slot.ref !== ref ) {
+				return;
 			}
+
+			slots.delete( name );
 		};
 
 	const updateSlot: SlotFillBubblesVirtuallyContext[ 'updateSlot' ] = (
 		name,
+		ref,
 		fillProps
 	) => {
 		const slot = slots.get( name );
@@ -50,6 +58,10 @@ function createSlotRegistry(): SlotFillBubblesVirtuallyContext {
 			return;
 		}
 
+		if ( slot.ref !== ref ) {
+			return;
+		}
+
 		if ( isShallowEqual( slot.fillProps, fillProps ) ) {
 			return;
 		}
@@ -58,7 +70,7 @@ function createSlotRegistry(): SlotFillBubblesVirtuallyContext {
 		const slotFills = fills.get( name );
 		if ( slotFills ) {
 			// Force update fills.
-			slotFills.forEach( ( fill ) => fill.current.rerender() );
+			slotFills.forEach( ( fill ) => fill.rerender() );
 		}
 	};
 
@@ -69,20 +81,18 @@ function createSlotRegistry(): SlotFillBubblesVirtuallyContext {
 		fills.set( name, [ ...( fills.get( name ) || [] ), ref ] );
 	};
 
-	const unregisterFill: SlotFillBubblesVirtuallyContext[ 'registerFill' ] = (
-		name,
-		ref
-	) => {
-		const fillsForName = fills.get( name );
-		if ( ! fillsForName ) {
-			return;
-		}
+	const unregisterFill: SlotFillBubblesVirtuallyContext[ 'unregisterFill' ] =
+		( name, ref ) => {
+			const fillsForName = fills.get( name );
+			if ( ! fillsForName ) {
+				return;
+			}
 
-		fills.set(
-			name,
-			fillsForName.filter( ( fillRef ) => fillRef !== ref )
-		);
-	};
+			fills.set(
+				name,
+				fillsForName.filter( ( fillRef ) => fillRef !== ref )
+			);
+		};
 
 	return {
 		slots,

package/src/slot-fill/bubbles-virtually/slot.tsx

@@ -35,29 +35,33 @@ function Slot(
 		as,
 		// `children` is not allowed. However, if it is passed,
 		// it will be displayed as is, so remove `children`.
-		// @ts-ignore
 		children,
 		...restProps
 	} = props;
 
 	const { registerSlot, unregisterSlot, ...registry } =
 		useContext( SlotFillContext );
+
 	const ref = useRef< HTMLElement >( null );
 
+	// We don't want to unregister and register the slot whenever
+	// `fillProps` change, which would cause the fill to be re-mounted. Instead,
+	// we can just update the slot (see hook below).
+	// For more context, see https://github.com/WordPress/gutenberg/pull/44403#discussion_r994415973
+	const fillPropsRef = useRef( fillProps );
+	useLayoutEffect( () => {
+		fillPropsRef.current = fillProps;
+	}, [ fillProps ] );
+
 	useLayoutEffect( () => {
-		registerSlot( name, ref, fillProps );
+		registerSlot( name, ref, fillPropsRef.current );
 		return () => {
 			unregisterSlot( name, ref );
 		};
-		// We don't want to unregister and register the slot whenever
-		// `fillProps` change, which would cause the fill to be re-mounted. Instead,
-		// we can just update the slot (see hook below).
-		// For more context, see https://github.com/WordPress/gutenberg/pull/44403#discussion_r994415973
 	}, [ registerSlot, unregisterSlot, name ] );
-	// fillProps may be an update that interacts with the layout, so we
-	// useLayoutEffect.
+
 	useLayoutEffect( () => {
-		registry.updateSlot( name, fillProps );
+		registry.updateSlot( name, ref, fillPropsRef.current );
 	} );
 
 	return (

package/src/slot-fill/bubbles-virtually/use-slot.ts

@@ -1,40 +1,17 @@
 /**
  * WordPress dependencies
  */
-import { useMemo, useContext } from '@wordpress/element';
+import { useContext } from '@wordpress/element';
 import { useObservableValue } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
 import SlotFillContext from './slot-fill-context';
-import type {
-	SlotFillBubblesVirtuallyFillRef,
-	SlotFillBubblesVirtuallySlotRef,
-	FillProps,
-	SlotKey,
-} from '../types';
+import type { SlotKey } from '../types';
 
 export default function useSlot( name: SlotKey ) {
 	const registry = useContext( SlotFillContext );
 	const slot = useObservableValue( registry.slots, name );
-
-	const api = useMemo(
-		() => ( {
-			updateSlot: ( fillProps: FillProps ) =>
-				registry.updateSlot( name, fillProps ),
-			unregisterSlot: ( ref: SlotFillBubblesVirtuallySlotRef ) =>
-				registry.unregisterSlot( name, ref ),
-			registerFill: ( ref: SlotFillBubblesVirtuallyFillRef ) =>
-				registry.registerFill( name, ref ),
-			unregisterFill: ( ref: SlotFillBubblesVirtuallyFillRef ) =>
-				registry.unregisterFill( name, ref ),
-		} ),
-		[ name, registry ]
-	);
-
-	return {
-		...slot,
-		...api,
-	};
+	return { ...slot };
 }

package/src/slot-fill/fill.ts

@@ -11,7 +11,7 @@ import useSlot from './use-slot';
 import type { FillComponentProps } from './types';
 
 export default function Fill( { name, children }: FillComponentProps ) {
-	const { registerFill, unregisterFill } = useContext( SlotFillContext );
+	const registry = useContext( SlotFillContext );
 	const slot = useSlot( name );
 
 	const ref = useRef( {
@@ -21,32 +21,17 @@ export default function Fill( { name, children }: FillComponentProps ) {
 
 	useLayoutEffect( () => {
 		const refValue = ref.current;
-		registerFill( name, refValue );
-		return () => unregisterFill( name, refValue );
-		// The useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
-		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
-	}, [] );
+		refValue.name = name;
+		registry.registerFill( name, refValue );
+		return () => registry.unregisterFill( name, refValue );
+	}, [ registry, name ] );
 
 	useLayoutEffect( () => {
 		ref.current.children = children;
 		if ( slot ) {
-			slot.forceUpdate();
+			slot.rerender();
 		}
-		// The useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
-		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
-	}, [ children ] );
-
-	useLayoutEffect( () => {
-		if ( name === ref.current.name ) {
-			// Ignore initial effect.
-			return;
-		}
-		unregisterFill( ref.current.name, ref.current );
-		ref.current.name = name;
-		registerFill( name, ref.current );
-		// The useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
-		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
-	}, [ name ] );
+	}, [ slot, children ] );
 
 	return null;
 }

package/src/slot-fill/index.tsx

@@ -84,17 +84,15 @@ export function createSlotFill( key: SlotKey ) {
 		props: DistributiveOmit< SlotComponentProps, 'name' >
 	) => <Slot name={ key } { ...props } />;
 	SlotComponent.displayName = `${ baseName }Slot`;
+	/**
+	 * @deprecated 6.8.0
+	 * Please use `slotFill.name` instead of `slotFill.Slot.__unstableName`.
+	 */
 	SlotComponent.__unstableName = key;
 
 	return {
+		name: key,
 		Fill: FillComponent,
 		Slot: SlotComponent,
 	};
 }
-
-export const createPrivateSlotFill = ( name: string ) => {
-	const privateKey = Symbol( name );
-	const privateSlotFill = createSlotFill( privateKey );
-
-	return { privateKey, ...privateSlotFill };
-};

package/src/slot-fill/provider.tsx

@@ -1,7 +1,6 @@
 /**
  * WordPress dependencies
  */
-import type { Component } from '@wordpress/element';
 import { useState } from '@wordpress/element';
 
 /**
@@ -11,20 +10,17 @@ import SlotFillContext from './context';
 import type {
 	FillComponentProps,
 	BaseSlotFillContext,
-	BaseSlotComponentProps,
 	SlotFillProviderProps,
 	SlotKey,
+	Rerenderable,
 } from './types';
 
 function createSlotRegistry(): BaseSlotFillContext {
-	const slots: Record< SlotKey, Component< BaseSlotComponentProps > > = {};
+	const slots: Record< SlotKey, Rerenderable > = {};
 	const fills: Record< SlotKey, FillComponentProps[] > = {};
 	let listeners: Array< () => void > = [];
 
-	function registerSlot(
-		name: SlotKey,
-		slot: Component< BaseSlotComponentProps >
-	) {
+	function registerSlot( name: SlotKey, slot: Rerenderable ) {
 		const previousSlot = slots[ name ];
 		slots[ name ] = slot;
 		triggerListeners();
@@ -38,7 +34,7 @@ function createSlotRegistry(): BaseSlotFillContext {
 		// assigned into the instance, such that its own rendering of children
 		// will be empty (the new Slot will subsume all fills for this name).
 		if ( previousSlot ) {
-			previousSlot.forceUpdate();
+			previousSlot.rerender();
 		}
 	}
 
@@ -47,10 +43,7 @@ function createSlotRegistry(): BaseSlotFillContext {
 		forceUpdateSlot( name );
 	}
 
-	function unregisterSlot(
-		name: SlotKey,
-		instance: Component< BaseSlotComponentProps >
-	) {
+	function unregisterSlot( name: SlotKey, instance: Rerenderable ) {
 		// If a previous instance of a Slot by this name unmounts, do nothing,
 		// as the slot and its fills should only be removed for the current
 		// known instance.
@@ -68,15 +61,13 @@ function createSlotRegistry(): BaseSlotFillContext {
 		forceUpdateSlot( name );
 	}
 
-	function getSlot(
-		name: SlotKey
-	): Component< BaseSlotComponentProps > | undefined {
+	function getSlot( name: SlotKey ): Rerenderable | undefined {
 		return slots[ name ];
 	}
 
 	function getFills(
 		name: SlotKey,
-		slotInstance: Component< BaseSlotComponentProps >
+		slotInstance: Rerenderable
 	): FillComponentProps[] {
 		// Fills should only be returned for the current instance of the slot
 		// in which they occupy.
@@ -90,7 +81,7 @@ function createSlotRegistry(): BaseSlotFillContext {
 		const slot = getSlot( name );
 
 		if ( slot ) {
-			slot.forceUpdate();
+			slot.rerender();
 		}
 	}
 

package/src/slot-fill/slot.tsx

@@ -7,8 +7,11 @@ import type { ReactElement, ReactNode, Key } from 'react';
  * WordPress dependencies
  */
 import {
+	useContext,
+	useEffect,
+	useReducer,
+	useRef,
 	Children,
-	Component,
 	cloneElement,
 	isEmptyElement,
 } from '@wordpress/element';
@@ -17,7 +20,7 @@ import {
  * Internal dependencies
  */
 import SlotFillContext from './context';
-import type { BaseSlotComponentProps, SlotComponentProps } from './types';
+import type { SlotComponentProps } from './types';
 
 /**
  * Whether the argument is a function.
@@ -29,90 +32,50 @@ function isFunction( maybeFunc: any ): maybeFunc is Function {
 	return typeof maybeFunc === 'function';
 }
 
-class SlotComponent extends Component< BaseSlotComponentProps > {
-	private isUnmounted: boolean;
-
-	constructor( props: BaseSlotComponentProps ) {
-		super( props );
-
-		this.isUnmounted = false;
-	}
-
-	componentDidMount() {
-		const { registerSlot } = this.props;
-		this.isUnmounted = false;
-		registerSlot( this.props.name, this );
-	}
-
-	componentWillUnmount() {
-		const { unregisterSlot } = this.props;
-		this.isUnmounted = true;
-		unregisterSlot( this.props.name, this );
-	}
-
-	componentDidUpdate( prevProps: BaseSlotComponentProps ) {
-		const { name, unregisterSlot, registerSlot } = this.props;
-
-		if ( prevProps.name !== name ) {
-			unregisterSlot( prevProps.name, this );
-			registerSlot( name, this );
-		}
-	}
-
-	forceUpdate() {
-		if ( this.isUnmounted ) {
-			return;
-		}
-		super.forceUpdate();
-	}
-
-	render() {
-		const { children, name, fillProps = {}, getFills } = this.props;
-		const fills: ReactNode[] = ( getFills( name, this ) ?? [] )
-			.map( ( fill ) => {
-				const fillChildren = isFunction( fill.children )
-					? fill.children( fillProps )
-					: fill.children;
-				return Children.map( fillChildren, ( child, childIndex ) => {
-					if ( ! child || typeof child === 'string' ) {
-						return child;
-					}
-					let childKey: Key = childIndex;
-					if (
-						typeof child === 'object' &&
-						'key' in child &&
-						child?.key
-					) {
-						childKey = child.key;
-					}
-
-					return cloneElement( child as ReactElement, {
-						key: childKey,
-					} );
+function Slot( props: Omit< SlotComponentProps, 'bubblesVirtually' > ) {
+	const registry = useContext( SlotFillContext );
+	const [ , rerender ] = useReducer( () => [], [] );
+	const ref = useRef( { rerender } );
+
+	const { name, children, fillProps = {} } = props;
+
+	useEffect( () => {
+		const refValue = ref.current;
+		registry.registerSlot( name, refValue );
+		return () => registry.unregisterSlot( name, refValue );
+	}, [ registry, name ] );
+
+	const fills: ReactNode[] = ( registry.getFills( name, ref.current ) ?? [] )
+		.map( ( fill ) => {
+			const fillChildren = isFunction( fill.children )
+				? fill.children( fillProps )
+				: fill.children;
+			return Children.map( fillChildren, ( child, childIndex ) => {
+				if ( ! child || typeof child === 'string' ) {
+					return child;
+				}
+				let childKey: Key = childIndex;
+				if (
+					typeof child === 'object' &&
+					'key' in child &&
+					child?.key
+				) {
+					childKey = child.key;
+				}
+
+				return cloneElement( child as ReactElement, {
+					key: childKey,
 				} );
-			} )
-			.filter(
-				// In some cases fills are rendered only when some conditions apply.
-				// This ensures that we only use non-empty fills when rendering, i.e.,
-				// it allows us to render wrappers only when the fills are actually present.
-				( element ) => ! isEmptyElement( element )
-			);
-
-		return <>{ isFunction( children ) ? children( fills ) : fills }</>;
-	}
+			} );
+		} )
+		.filter(
+			// In some cases fills are rendered only when some conditions apply.
+			// This ensures that we only use non-empty fills when rendering, i.e.,
+			// it allows us to render wrappers only when the fills are actually present.
+			( element ) => ! isEmptyElement( element )
+		);
+
+	return <>{ isFunction( children ) ? children( fills ) : fills }</>;
 }
 
-const Slot = ( props: Omit< SlotComponentProps, 'bubblesVirtually' > ) => (
-	<SlotFillContext.Consumer>
-		{ ( { registerSlot, unregisterSlot, getFills } ) => (
-			<SlotComponent
-				{ ...props }
-				registerSlot={ registerSlot }
-				unregisterSlot={ unregisterSlot }
-				getFills={ getFills }
-			/>
-		) }
-	</SlotFillContext.Consumer>
-);
-
 export default Slot;