@wordpress/components 25.8.3 → 25.9.0

package/src/slot-fill/provider.tsx

@@ -0,0 +1,129 @@
+/**
+ * WordPress dependencies
+ */
+import type { Component } from '@wordpress/element';
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import SlotFillContext from './context';
+import type {
+	FillComponentProps,
+	BaseSlotFillContext,
+	BaseSlotComponentProps,
+	SlotFillProviderProps,
+	SlotKey,
+} from './types';
+
+function createSlotRegistry(): BaseSlotFillContext {
+	const slots: Record< SlotKey, Component< BaseSlotComponentProps > > = {};
+	const fills: Record< SlotKey, FillComponentProps[] > = {};
+	let listeners: Array< () => void > = [];
+
+	function registerSlot(
+		name: SlotKey,
+		slot: Component< BaseSlotComponentProps >
+	) {
+		const previousSlot = slots[ name ];
+		slots[ name ] = slot;
+		triggerListeners();
+
+		// Sometimes the fills are registered after the initial render of slot
+		// But before the registerSlot call, we need to rerender the slot.
+		forceUpdateSlot( name );
+
+		// If a new instance of a slot is being mounted while another with the
+		// same name exists, force its update _after_ the new slot has been
+		// 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();
+		}
+	}
+
+	function registerFill( name: SlotKey, instance: FillComponentProps ) {
+		fills[ name ] = [ ...( fills[ name ] || [] ), instance ];
+		forceUpdateSlot( name );
+	}
+
+	function unregisterSlot(
+		name: SlotKey,
+		instance: Component< BaseSlotComponentProps >
+	) {
+		// 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.
+		if ( slots[ name ] !== instance ) {
+			return;
+		}
+
+		delete slots[ name ];
+		triggerListeners();
+	}
+
+	function unregisterFill( name: SlotKey, instance: FillComponentProps ) {
+		fills[ name ] =
+			fills[ name ]?.filter( ( fill ) => fill !== instance ) ?? [];
+		forceUpdateSlot( name );
+	}
+
+	function getSlot(
+		name: SlotKey
+	): Component< BaseSlotComponentProps > | undefined {
+		return slots[ name ];
+	}
+
+	function getFills(
+		name: SlotKey,
+		slotInstance: Component< BaseSlotComponentProps >
+	): FillComponentProps[] {
+		// Fills should only be returned for the current instance of the slot
+		// in which they occupy.
+		if ( slots[ name ] !== slotInstance ) {
+			return [];
+		}
+		return fills[ name ];
+	}
+
+	function forceUpdateSlot( name: SlotKey ) {
+		const slot = getSlot( name );
+
+		if ( slot ) {
+			slot.forceUpdate();
+		}
+	}
+
+	function triggerListeners() {
+		listeners.forEach( ( listener ) => listener() );
+	}
+
+	function subscribe( listener: () => void ) {
+		listeners.push( listener );
+
+		return () => {
+			listeners = listeners.filter( ( l ) => l !== listener );
+		};
+	}
+
+	return {
+		registerSlot,
+		unregisterSlot,
+		registerFill,
+		unregisterFill,
+		getSlot,
+		getFills,
+		subscribe,
+	};
+}
+
+export function SlotFillProvider( { children }: SlotFillProviderProps ) {
+	const contextValue = useMemo( createSlotRegistry, [] );
+	return (
+		<SlotFillContext.Provider value={ contextValue }>
+			{ children }
+		</SlotFillContext.Provider>
+	);
+}
+
+export default SlotFillProvider;

package/src/slot-fill/{slot.js → slot.tsx}

@@ -1,4 +1,8 @@
-// @ts-nocheck
+/**
+ * External dependencies
+ */
+import type { ReactElement, ReactNode, Key } from 'react';
+
 /**
  * WordPress dependencies
  */
@@ -13,20 +17,23 @@ import {
  * Internal dependencies
  */
 import SlotFillContext from './context';
+import type { BaseSlotComponentProps, SlotComponentProps } from './types';
 
 /**
  * Whether the argument is a function.
  *
- * @param {*} maybeFunc The argument to check.
- * @return {boolean} True if the argument is a function, false otherwise.
+ * @param maybeFunc The argument to check.
+ * @return True if the argument is a function, false otherwise.
  */
-function isFunction( maybeFunc ) {
+function isFunction( maybeFunc: any ): maybeFunc is Function {
 	return typeof maybeFunc === 'function';
 }
 
-class SlotComponent extends Component {
-	constructor() {
-		super( ...arguments );
+class SlotComponent extends Component< BaseSlotComponentProps > {
+	private isUnmounted: boolean;
+
+	constructor( props: BaseSlotComponentProps ) {
+		super( props );
 
 		this.isUnmounted = false;
 	}
@@ -43,11 +50,11 @@ class SlotComponent extends Component {
 		unregisterSlot( this.props.name, this );
 	}
 
-	componentDidUpdate( prevProps ) {
+	componentDidUpdate( prevProps: BaseSlotComponentProps ) {
 		const { name, unregisterSlot, registerSlot } = this.props;
 
 		if ( prevProps.name !== name ) {
-			unregisterSlot( prevProps.name );
+			unregisterSlot( prevProps.name, this );
 			registerSlot( name, this );
 		}
 	}
@@ -61,20 +68,27 @@ class SlotComponent extends Component {
 
 	render() {
 		const { children, name, fillProps = {}, getFills } = this.props;
-
-		const fills = ( getFills( name, this ) ?? [] )
+		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;
+					}
 
-					const childKey = child.key || childIndex;
-					return cloneElement( child, { key: childKey } );
+					return cloneElement( child as ReactElement, {
+						key: childKey,
+					} );
 				} );
 			} )
 			.filter(
@@ -88,7 +102,7 @@ class SlotComponent extends Component {
 	}
 }
 
-const Slot = ( props ) => (
+const Slot = ( props: Omit< SlotComponentProps, 'bubblesVirtually' > ) => (
 	<SlotFillContext.Consumer>
 		{ ( { registerSlot, unregisterSlot, getFills } ) => (
 			<SlotComponent

package/src/slot-fill/stories/index.story.tsx

@@ -0,0 +1,140 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { Slot, Fill, Provider as SlotFillProvider } from '../';
+
+const meta: Meta< typeof Slot > = {
+	component: Slot,
+	title: 'Components/SlotFill',
+	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+	subcomponents: { Fill, SlotFillProvider },
+	argTypes: {
+		name: { control: { type: null } },
+		as: { control: { type: 'text' } },
+		fillProps: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+
+export default meta;
+
+export const Default: StoryFn< typeof Slot > = ( props ) => {
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>
+				Name: <Slot { ...props } name="name" />
+			</p>
+			<p>
+				Age: <Slot { ...props } name="age" />
+			</p>
+			<Fill name="name">Grace</Fill>
+			<Fill name="age">33</Fill>
+		</SlotFillProvider>
+	);
+};
+Default.args = {
+	bubblesVirtually: true,
+	as: 'span',
+};
+
+export const WithFillProps: StoryFn< typeof Slot > = ( props ) => {
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>
+				Name:{ ' ' }
+				<Slot
+					{ ...props }
+					name="name"
+					fillProps={ { name: 'Grace' } }
+				/>
+			</p>
+			<p>
+				Age: <Slot { ...props } name="age" fillProps={ { age: 33 } } />
+			</p>
+
+			<Fill name="name">{ ( fillProps ) => fillProps.name }</Fill>
+			<Fill name="age">{ ( fillProps ) => fillProps.age }</Fill>
+		</SlotFillProvider>
+	);
+};
+WithFillProps.args = {
+	...Default.args,
+};
+
+export const WithSlotChildren: StoryFn< typeof Slot > = ( props ) => {
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>
+				Name:
+				{ /* @ts-expect-error Not supported children for `<Slot />` when `bubblesVirtually` is true. */ }
+				<Slot { ...props } name="name">
+					{ ( fills ) => {
+						return (
+							<span style={ { color: 'red' } }>{ fills }</span>
+						);
+					} }
+				</Slot>
+			</p>
+			<p>
+				Age:
+				{ /* @ts-expect-error Not support children for `<Slot />` when `bubblesVirtually` is true. */ }
+				<Slot { ...props } name="age">
+					{ ( fills ) => {
+						return (
+							<span style={ { color: 'red' } }>{ fills }</span>
+						);
+					} }
+				</Slot>
+			</p>
+			<Fill name="name">Alice</Fill>
+			<Fill name="age">18</Fill>
+		</SlotFillProvider>
+	);
+};
+WithSlotChildren.args = {
+	...Default.args,
+};
+
+export const WithContext: StoryFn< typeof Slot > = ( props ) => {
+	const Context = createContext< string | number >( '' );
+	const ContextFill = ( { name }: { name: string } ) => {
+		const value = useContext( Context );
+		return <Fill name={ name }>{ value }</Fill>;
+	};
+	return (
+		<SlotFillProvider>
+			<h2>Profile</h2>
+			<p>
+				Name: <Slot { ...props } name="name" />
+			</p>
+			<p>
+				Age: <Slot { ...props } name="age" />
+			</p>
+			<Context.Provider value="Grace">
+				<ContextFill name="name" />
+			</Context.Provider>
+			<Context.Provider value={ 33 }>
+				<ContextFill name="age" />
+			</Context.Provider>
+		</SlotFillProvider>
+	);
+};
+WithContext.args = {
+	...Default.args,
+};

package/src/slot-fill/types.ts

@@ -0,0 +1,155 @@
+/**
+ * External dependencies
+ */
+import type { Component, MutableRefObject, ReactNode, RefObject } from 'react';
+
+export type DistributiveOmit< T, K extends keyof any > = T extends any
+	? Omit< T, K >
+	: never;
+
+export type SlotKey = string | symbol;
+
+export type FillProps = Record< string, any >;
+
+type SlotPropBase = {
+	/**
+	 * Slot name.
+	 */
+	name: SlotKey;
+
+	/**
+	 * props to pass from `Slot` to `Fill`.
+	 *
+	 * @default {}
+	 */
+	fillProps?: FillProps;
+};
+
+export type SlotComponentProps =
+	| ( SlotPropBase & {
+			/**
+			 * By default, events will bubble to their parents on the DOM hierarchy (native event bubbling).
+			 * If set to true, events will bubble to their virtual parent in the React elements hierarchy instead,
+			 * also accept an optional `className`, `id`, etc.  to add to the slot container.
+			 */
+			bubblesVirtually: true;
+
+			/**
+			 * A function that returns nodes to be rendered.
+			 * Not supported when `bubblesVirtually` is true.
+			 */
+			children?: never;
+
+			/**
+			 * className.
+			 * Not supported when `bubblesVirtually` is true.
+			 */
+			className?: string;
+	  } )
+	| ( SlotPropBase & {
+			/**
+			 * By default, events will bubble to their parents on the DOM hierarchy (native event bubbling).
+			 * If set to true, events will bubble to their virtual parent in the React elements hierarchy instead,
+			 * also accept an optional `className`, `id`, etc.  to add to the slot container.
+			 */
+			bubblesVirtually?: false;
+
+			/**
+			 * A function that returns nodes to be rendered.
+			 * Not supported when `bubblesVirtually` is true.
+			 */
+			children?: ( fills: ReactNode ) => ReactNode;
+
+			/**
+			 * className.
+			 * Not supported when `bubblesVirtually` is false.
+			 */
+			className?: never;
+	  } );
+
+export type FillComponentProps = {
+	/**
+	 * The name of the slot to fill into.
+	 */
+	name: SlotKey;
+
+	/**
+	 * Children elements or render function.
+	 */
+	children?: ReactNode | ( ( fillProps: FillProps ) => ReactNode );
+};
+
+export type SlotFillProviderProps = {
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+};
+
+export type SlotFillBubblesVirtuallySlotRef = RefObject< HTMLElement >;
+export type SlotFillBubblesVirtuallyFillRef = MutableRefObject< {
+	rerender: () => void;
+} >;
+
+export type SlotFillBubblesVirtuallyContext = {
+	slots: Map<
+		SlotKey,
+		{
+			ref: SlotFillBubblesVirtuallySlotRef;
+			fillProps: FillProps;
+		}
+	>;
+	fills: Map< SlotKey, SlotFillBubblesVirtuallyFillRef[] >;
+	registerSlot: (
+		name: SlotKey,
+		ref: SlotFillBubblesVirtuallySlotRef,
+		fillProps: FillProps
+	) => void;
+	unregisterSlot: (
+		name: SlotKey,
+		ref: SlotFillBubblesVirtuallySlotRef
+	) => void;
+	updateSlot: ( name: SlotKey, fillProps: FillProps ) => void;
+	registerFill: (
+		name: SlotKey,
+		ref: SlotFillBubblesVirtuallyFillRef
+	) => void;
+	unregisterFill: (
+		name: SlotKey,
+		ref: SlotFillBubblesVirtuallyFillRef
+	) => void;
+
+	/**
+	 * This helps the provider know if it's using the default context value or not.
+	 */
+	isDefault?: boolean;
+};
+
+export type BaseSlotFillContext = {
+	registerSlot: (
+		name: SlotKey,
+		slot: Component< BaseSlotComponentProps >
+	) => void;
+	unregisterSlot: (
+		name: SlotKey,
+		slot: Component< BaseSlotComponentProps >
+	) => void;
+	registerFill: ( name: SlotKey, instance: FillComponentProps ) => void;
+	unregisterFill: ( name: SlotKey, instance: FillComponentProps ) => void;
+	getSlot: (
+		name: SlotKey
+	) => Component< BaseSlotComponentProps > | undefined;
+	getFills: (
+		name: SlotKey,
+		slotInstance: Component< BaseSlotComponentProps >
+	) => FillComponentProps[];
+	subscribe: ( listener: () => void ) => () => void;
+};
+
+export type BaseSlotComponentProps = Pick<
+	BaseSlotFillContext,
+	'registerSlot' | 'unregisterSlot' | 'getFills'
+> &
+	Omit< SlotComponentProps, 'bubblesVirtually' > & {
+		children?: ( fills: ReactNode ) => ReactNode;
+	};

package/src/slot-fill/{use-slot.js → use-slot.ts}

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * WordPress dependencies
  */
@@ -8,14 +7,15 @@ import { useContext, useSyncExternalStore } from '@wordpress/element';
  * Internal dependencies
  */
 import SlotFillContext from './context';
+import type { SlotKey } from './types';
 
 /**
  * React hook returning the active slot given a name.
  *
- * @param {string} name Slot name.
- * @return {Object} Slot object.
+ * @param name Slot name.
+ * @return Slot object.
  */
-const useSlot = ( name ) => {
+const useSlot = ( name: SlotKey ) => {
 	const { getSlot, subscribe } = useContext( SlotFillContext );
 	return useSyncExternalStore(
 		subscribe,

package/src/snackbar/index.tsx

@@ -18,7 +18,7 @@ import warning from '@wordpress/warning';
 import Button from '../button';
 import type { SnackbarProps } from './types';
 import type { NoticeAction } from '../notice/types';
-import type { WordPressComponentProps } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
 
 const NOTICE_TIMEOUT = 10000;
 

package/src/snackbar/list.tsx

@@ -18,7 +18,7 @@ import {
 	__unstableAnimatePresence as AnimatePresence,
 } from '../animation';
 import type { SnackbarListProps } from './types';
-import type { WordPressComponentProps } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
 
 const SNACKBAR_VARIANTS = {
 	init: {

package/src/spacer/component.tsx

@@ -6,8 +6,8 @@ import type { ForwardedRef } from 'react';
 /**
  * Internal dependencies
  */
-import type { WordPressComponentProps } from '../ui/context';
-import { contextConnect } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
+import { contextConnect } from '../context';
 import { View } from '../view';
 import { useSpacer } from './hook';
 import type { SpacerProps } from './types';

package/src/spacer/hook.ts

@@ -6,9 +6,9 @@ import { css } from '@emotion/react';
 /**
  * Internal dependencies
  */
-import type { WordPressComponentProps } from '../ui/context';
-import { useContextSystem } from '../ui/context';
-import { space } from '../ui/utils/space';
+import type { WordPressComponentProps } from '../context';
+import { useContextSystem } from '../context';
+import { space } from '../utils/space';
 import { rtl, useCx } from '../utils';
 import type { SpacerProps } from './types';
 

package/src/spacer/types.ts

@@ -6,7 +6,7 @@ import type { ReactNode } from 'react';
 /**
  * Internal dependencies
  */
-import type { SpaceInput } from '../ui/utils/space';
+import type { SpaceInput } from '../utils/space';
 
 export type SpacerProps = {
 	/**

package/src/spinner/index.tsx

@@ -8,7 +8,7 @@ import type { ForwardedRef } from 'react';
  * Internal dependencies
  */
 import { StyledSpinner, SpinnerTrack, SpinnerIndicator } from './styles';
-import type { WordPressComponentProps } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
 
 /**
  * WordPress dependencies

package/src/spinner/stories/index.story.tsx

@@ -7,7 +7,7 @@ import type { StoryFn, Meta } from '@storybook/react';
  * Internal dependencies
  */
 import Spinner from '../';
-import { space } from '../../ui/utils/space';
+import { space } from '../../utils/space';
 
 const meta: Meta< typeof Spinner > = {
 	title: 'Components/Spinner',

package/src/surface/component.tsx

@@ -6,11 +6,11 @@ import type { ForwardedRef } from 'react';
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect } from '../context';
 import { View } from '../view';
 import { useSurface } from './hook';
 import type { SurfaceProps } from './types';
-import type { WordPressComponentProps } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
 
 function UnconnectedSurface(
 	props: WordPressComponentProps< SurfaceProps, 'div' >,

package/src/surface/hook.ts

@@ -6,11 +6,11 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem } from '../context';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
 import type { SurfaceProps } from './types';
-import type { WordPressComponentProps } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
 
 export function useSurface(
 	props: WordPressComponentProps< SurfaceProps, 'div' >

package/src/tab-panel/index.tsx

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
 import classnames from 'classnames';
 import type { ForwardedRef } from 'react';
@@ -22,7 +23,7 @@ import { useInstanceId, usePrevious } from '@wordpress/compose';
 
 import Button from '../button';
 import type { TabPanelProps } from './types';
-import type { WordPressComponentProps } from '../ui/context';
+import type { WordPressComponentProps } from '../context';
 
 // Separate the actual tab name from the instance ID. This is
 // necessary because Ariakit internally uses the element ID when

package/src/text/component.js

@@ -1,13 +1,13 @@
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect } from '../context';
 import { View } from '../view';
 import useText from './hook';
 
 /**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'span'>} props
- * @param {import('react').ForwardedRef<any>}                                                forwardedRef
+ * @param {import('../context').WordPressComponentProps<import('./types').Props, 'span'>} props
+ * @param {import('react').ForwardedRef<any>}                                             forwardedRef
  */
 function Text( props, forwardedRef ) {
 	const textProps = useText( props );