Components: Refactor SlotFill

docs/manifest-devhub.json

@@ -953,6 +953,12 @@
 		"markdown_source": "../packages/components/src/slot-fill/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "SlotFill2",
+		"slug": "slot-fill2",
+		"markdown_source": "../packages/components/src/slot-fill2/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Snackbar",
 		"slug": "snackbar",

packages/components/src/index.js

@@ -85,6 +85,13 @@ export {
 	Consumer as __experimentalSlotFillConsumer,
 } from './slot-fill';
 
+export {
+	createSlotFill as __experimentalCreateSlotFill,
+	Slot as __experimentalSlot,
+	Fill as __experimentalFill,
+	SlotFillProvider as __experimentalSlotFillProvider,
+} from './slot-fill2';
+
 // Higher-Order Components
 export { default as navigateRegions } from './higher-order/navigate-regions';
 export {

packages/components/src/index.native.js

@@ -11,6 +11,12 @@ export { default as Icon } from './icon';
 export { default as IconButton } from './icon-button';
 export { default as Spinner } from './spinner';
 export { createSlotFill, Slot, Fill, Provider as SlotFillProvider } from './slot-fill';
+export {
+	createSlotFill as __experimentalCreateSlotFill,
+	Slot as __experimentalSlot,
+	Fill as __experimentalFill,
+	SlotFillProvider as __experimentalSlotFillProvider,
+} from './slot-fill2';
 export { default as BaseControl } from './base-control';
 export { default as TextareaControl } from './textarea-control';
 export { default as PanelBody } from './panel/body';

packages/components/src/slot-fill2/README.md

@@ -0,0 +1,66 @@
+# 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 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](https://reactjs.org/docs/portals.html).
+
+## Usage
+
+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.
+
+Any Fill will automatically occupy 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.
+
+```jsx
+import { SlotFillProvider, Slot, Fill, Panel, PanelBody } from '@wordpress/components';
+
+const MySlotFillProvider = () => {
+	const MyPanelSlot = () => (
+		<Panel header="Panel with slot">
+			<PanelBody>
+				<Slot name="MyPanelSlot"/>
+			</PanelBody>
+		</Panel>
+	);
+
+	MyPanelSlot.Content = () => (
+		<Fill name="MyPanelSlot">
+			Panel body
+		</Fill>
+	);
+
+	return (
+		<SlotFillProvider>
+			<MyPanelSlot />
+			<MyPanelSlot.Content />
+		</SlotFillProvider>
+	);
+};
+```
+
+There is also `createSlotFill` helper method which was created to simplify the process of matching the corresponding `Slot` and `Fill` components:
+
+```jsx
+const { Fill, Slot } = createSlotFill( 'Toolbar' );
+
+const ToolbarItem = () => (
+	<Fill>
+		My item
+	</Fill>
+);
+
+const Toolbar = () => (
+	<div className="toolbar">
+		<Slot />
+	</div>
+); 
+```
+
+## Props
+
+The `SlotFillProvider` component does not accept any props.
+
+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.

packages/components/src/slot-fill2/context.js

@@ -0,0 +1,94 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	createContext,
+	useMemo,
+	useCallback,
+	useState,
+	useContext,
+} from '@wordpress/element';
+
+export const SlotFillContext = createContext();
+
+function useSlotRegistry() {
+	const [ slots, setSlots ] = useState( {} );
+
+	const register = useCallback( ( name, ref, fillProps = {} ) => {
+		setSlots( ( prevSlots ) => ( {
+			...prevSlots,
+			[ name ]: {
+				ref,
+				fillProps,
+			},
+		} ) );
+	}, [] );
+
+	const update = useCallback( ( name, ref, fillProps ) => {
+		setSlots( ( prevSlots ) => ( {
+			...prevSlots,
+			[ name ]: {
+				ref: ref || prevSlots[ name ].ref,
+				fillProps: fillProps || prevSlots[ name ].fillProps || {},
+			},
+		} ) );
+	}, [] );
+
+	const unregister = useCallback( ( name ) => {
+		setSlots( ( prevSlots ) => {
+			// eslint-disable-next-line no-unused-vars
+			const { [ name ]: _, ...nextSlots } = prevSlots;
+			return nextSlots;
+		} );
+	}, [] );
+
+	// Memoizing the return value so it can be directly passed to Provider value
+	const registry = useMemo(
+		() => ( {
+			slots,
+			register,
+			update,
+			unregister,
+		} ),
+		[ slots, register, update, unregister ]
+	);
+
+	return registry;
+}
+
+export function useSlot( name ) {
+	const registry = useContext( SlotFillContext );
+
+	const { ref, fillProps } = registry.slots[ name ] || {};
+
+	const update = useCallback(
+		( slotRef, slotFillProps ) => {
+			registry.update( name, slotRef, slotFillProps );
+		},
+		[ registry.update ]
+	);
+
+	const unregister = useCallback( () => {
+		registry.unregister( name );
+	}, [ registry.unregister ] );
+
+	if ( ! registry.slots[ name ] ) {
+		return null;
+	}
+
+	return {
+		ref,
+		fillProps,
+		update,
+		unregister,
+	};
+}
+
+export default function SlotFillProvider( { children } ) {
+	const registry = useSlotRegistry();
+	return (
+		<SlotFillContext.Provider value={ registry }>
+			{ children }
+		</SlotFillContext.Provider>
+	);
+}

packages/components/src/slot-fill2/fill.js

@@ -0,0 +1,23 @@
+/**
+ * WordPress dependencies
+ */
+import { createPortal } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useSlot } from './context';
+
+export default function Fill( { name, children } ) {
+	const slot = useSlot( name );
+
+	if ( ! slot ) {
+		return null;
+	}
+
+	if ( typeof children === 'function' ) {
+		children = children( slot.fillProps );
+	}
+
+	return createPortal( children, slot.ref.current );
+}

packages/components/src/slot-fill2/index.js

@@ -0,0 +1,23 @@
+/**
+ * Internal dependencies
+ */
+import Slot from './slot';
+import Fill from './fill';
+import SlotFillProvider from './context';
+
+export { Slot };
+export { Fill };
+export { SlotFillProvider };
+
+export function createSlotFill( name ) {
+	const FillComponent = ( props ) => <Fill name={ name } { ...props } />;
+	FillComponent.displayName = name + 'Fill';
+
+	const SlotComponent = ( props ) => <Slot name={ name } { ...props } />;
+	SlotComponent.displayName = name + 'Slot';
+
+	return {
+		Fill: FillComponent,
+		Slot: SlotComponent,
+	};
+}

packages/components/src/slot-fill2/slot.js

@@ -0,0 +1,42 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useRef, useLayoutEffect, useContext } from '@wordpress/element';
+import isShallowEqual from '@wordpress/is-shallow-equal';
+
+/**
+ * Internal dependencies
+ */
+import { SlotFillContext, useSlot } from './context';
+
+export default function Slot( {
+	name,
+	fillProps = {},
+	as: Component = 'div',
+	...props
+} ) {
+	const registry = useContext( SlotFillContext );
+	const ref = useRef();
+	const slot = useSlot( name );
+
+	useEffect( () => {
+		registry.register( name, ref, fillProps );
+		return () => {
+			registry.unregister( name );
+		};
+	// We are not including fillProps in the deps because we don't want to
+	// unregister and register the slot whenever fillProps change, which would
+	// cause the fill to be re-mounted. We are only considering the initial value
+	// of fillProps.
+	}, [ registry.register, registry.unregister, name ] );
+
+	// fillProps may be an update that interact with the layout, so
+	// we useLayoutEffect
+	useLayoutEffect( () => {
+		if ( slot && ! isShallowEqual( slot.fillProps, fillProps ) ) {
+			registry.update( name, ref, fillProps );
+		}
+	} );
+
+	return <Component ref={ ref } { ...props } />;
+}

packages/components/src/slot-fill2/stories/index.js

@@ -0,0 +1,63 @@
+/**
+ * External dependencies
+ */
+import { text, number } from '@storybook/addon-knobs';
+
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { Slot, Fill, SlotFillProvider } from '../';
+
+export default { title: 'Components|SlotFill', component: Slot };
+
+export const _default = () => {
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>Name: <Slot as="span" name="name" /></p>
+			<p>Age: <Slot as="span" name="age" /></p>
+			<Fill name="name">Grace</Fill>
+			<Fill name="age">33</Fill>
+		</SlotFillProvider>
+	);
+};
+
+export const withFillProps = () => {
+	const name = text( 'name', 'Grace' );
+	const age = number( 'age', 33 );
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>Name: <Slot as="span" name="name" fillProps={ { name } } /></p>
+			<p>Age: <Slot as="span" name="age" fillProps={ { age } } /></p>
+			<Fill name="name">{ ( fillProps ) => fillProps.name }</Fill>
+			<Fill name="age">{ ( fillProps ) => fillProps.age }</Fill>
+		</SlotFillProvider>
+	);
+};
+
+export const withContext = () => {
+	const Context = createContext();
+	const ContextFill = ( { name } ) => {
+		const value = useContext( Context );
+		return <Fill name={ name }>{ value }</Fill>;
+	};
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>Name: <Slot as="span" name="name" /></p>
+			<p>Age: <Slot as="span" name="age" /></p>
+			<Context.Provider value="Grace">
+				<ContextFill name="name" />
+			</Context.Provider>
+			<Context.Provider value={ 33 }>
+				<ContextFill name="age" />
+			</Context.Provider>
+		</SlotFillProvider>
+	);
+};

packages/components/src/slot-fill2/test/index.js

@@ -0,0 +1,28 @@
+/**
+ * External dependencies
+ */
+import { shallow } from 'enzyme';
+
+/**
+ * Internal dependencies
+ */
+import { createSlotFill, Fill, Slot } from '../';
+
+describe( 'createSlotFill', () => {
+	const SLOT_NAME = 'MySlotFill';
+	const MySlotFill = createSlotFill( SLOT_NAME );
+
+	test( 'should match snapshot for Fill', () => {
+		const wrapper = shallow( <MySlotFill.Fill /> );
+
+		expect( wrapper.type() ).toBe( Fill );
+		expect( wrapper.prop( 'name' ) ).toBe( SLOT_NAME );
+	} );
+
+	test( 'should match snapshot for Slot', () => {
+		const wrapper = shallow( <MySlotFill.Slot /> );
+
+		expect( wrapper.type() ).toBe( Slot );
+		expect( wrapper.prop( 'name' ) ).toBe( SLOT_NAME );
+	} );
+} );