@wordpress/components 20.0.2-next.957ca95e4c.0 → 21.0.1

package/src/tab-panel/{index.js → index.tsx}

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { partial, find } from 'lodash';
+import { find } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -15,10 +15,16 @@ import { useInstanceId } from '@wordpress/compose';
  */
 import { NavigableMenu } from '../navigable-container';
 import Button from '../button';
+import type { TabButtonProps, TabPanelProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-const noop = () => {};
-
-const TabButton = ( { tabId, onClick, children, selected, ...rest } ) => (
+const TabButton = ( {
+	tabId,
+	onClick,
+	children,
+	selected,
+	...rest
+}: TabButtonProps ) => (
 	<Button
 		role="tab"
 		tabIndex={ selected ? null : -1 }
@@ -31,24 +37,60 @@ const TabButton = ( { tabId, onClick, children, selected, ...rest } ) => (
 	</Button>
 );
 
-export default function TabPanel( {
+/**
+ * TabPanel is an ARIA-compliant tabpanel.
+ *
+ * TabPanels organize content across different screens, data sets, and interactions.
+ * It has two sections: a list of tabs, and the view to show when tabs are chosen.
+ *
+ * ```jsx
+ * import { TabPanel } from '@wordpress/components';
+ *
+ * const onSelect = ( tabName ) => {
+ *   console.log( 'Selecting tab', tabName );
+ * };
+ *
+ * const MyTabPanel = () => (
+ *   <TabPanel
+ *     className="my-tab-panel"
+ *     activeClass="active-tab"
+ *     onSelect={ onSelect }
+ *     tabs={ [
+ *       {
+ *         name: 'tab1',
+ *         title: 'Tab 1',
+ *         className: 'tab-one',
+ *       },
+ *       {
+ *         name: 'tab2',
+ *         title: 'Tab 2',
+ *         className: 'tab-two',
+ *       },
+ *     ] }
+ *   >
+ *     { ( tab ) => <p>{ tab.title }</p> }
+ *   </TabPanel>
+ * );
+ * ```
+ */
+export function TabPanel( {
 	className,
 	children,
 	tabs,
 	initialTabName,
 	orientation = 'horizontal',
 	activeClass = 'is-active',
-	onSelect = noop,
-} ) {
+	onSelect,
+}: WordPressComponentProps< TabPanelProps, 'div', false > ) {
 	const instanceId = useInstanceId( TabPanel, 'tab-panel' );
-	const [ selected, setSelected ] = useState( null );
+	const [ selected, setSelected ] = useState< string >();
 
-	const handleClick = ( tabKey ) => {
+	const handleClick = ( tabKey: string ) => {
 		setSelected( tabKey );
-		onSelect( tabKey );
+		onSelect?.( tabKey );
 	};
 
-	const onNavigate = ( childIndex, child ) => {
+	const onNavigate = ( _childIndex: number, child: HTMLButtonElement ) => {
 		child.click();
 	};
 	const selectedTab = find( tabs, { name: selected } );
@@ -58,7 +100,8 @@ export default function TabPanel( {
 		const newSelectedTab = find( tabs, { name: selected } );
 		if ( ! newSelectedTab ) {
 			setSelected(
-				initialTabName || ( tabs.length > 0 ? tabs[ 0 ].name : null )
+				initialTabName ||
+					( tabs.length > 0 ? tabs[ 0 ].name : undefined )
 			);
 		}
 	}, [ tabs ] );
@@ -84,7 +127,7 @@ export default function TabPanel( {
 						aria-controls={ `${ instanceId }-${ tab.name }-view` }
 						selected={ tab.name === selected }
 						key={ tab.name }
-						onClick={ partial( handleClick, tab.name ) }
+						onClick={ () => handleClick( tab.name ) }
 					>
 						{ tab.title }
 					</TabButton>
@@ -104,3 +147,5 @@ export default function TabPanel( {
 		</div>
 	);
 }
+
+export default TabPanel;

package/src/tab-panel/stories/index.tsx

@@ -0,0 +1,37 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import TabPanel from '..';
+
+const meta: ComponentMeta< typeof TabPanel > = {
+	title: 'Components/TabPanel',
+	component: TabPanel,
+	parameters: {
+		controls: { expanded: true },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof TabPanel > = ( props ) => {
+	return <TabPanel { ...props } />;
+};
+
+export const Default = Template.bind( {} );
+Default.args = {
+	children: ( tab ) => <p>Selected tab: { tab.title }</p>,
+	tabs: [
+		{
+			name: 'tab1',
+			title: 'Tab 1',
+		},
+		{
+			name: 'tab2',
+			title: 'Tab 2',
+		},
+	],
+};

package/src/tab-panel/test/index.tsx

@@ -0,0 +1,120 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * Internal dependencies
+ */
+import TabPanel from '..';
+
+const setupUser = () =>
+	userEvent.setup( {
+		advanceTimers: jest.advanceTimersByTime,
+	} );
+
+const TABS = [
+	{
+		name: 'alpha',
+		title: 'Alpha',
+		className: 'alpha-class',
+	},
+	{
+		name: 'beta',
+		title: 'Beta',
+		className: 'beta-class',
+	},
+	{
+		name: 'gamma',
+		title: 'Gamma',
+		className: 'gamma-class',
+	},
+];
+
+const getSelectedTab = () => screen.getByRole( 'tab', { selected: true } );
+
+describe( 'TabPanel', () => {
+	it( 'should render a tabpanel, and clicking should change tabs', async () => {
+		const user = setupUser();
+		const panelRenderFunction = jest.fn();
+
+		render( <TabPanel tabs={ TABS } children={ panelRenderFunction } /> );
+
+		expect( getSelectedTab() ).toHaveTextContent( 'Alpha' );
+		expect(
+			screen.getByRole( 'tabpanel', { name: 'Alpha' } )
+		).toBeInTheDocument();
+		expect( panelRenderFunction ).toHaveBeenLastCalledWith( TABS[ 0 ] );
+
+		await user.click( screen.getByRole( 'tab', { name: 'Beta' } ) );
+
+		expect( getSelectedTab() ).toHaveTextContent( 'Beta' );
+		expect(
+			screen.getByRole( 'tabpanel', { name: 'Beta' } )
+		).toBeInTheDocument();
+		expect( panelRenderFunction ).toHaveBeenLastCalledWith( TABS[ 1 ] );
+
+		await user.click( screen.getByRole( 'tab', { name: 'Alpha' } ) );
+
+		expect( getSelectedTab() ).toHaveTextContent( 'Alpha' );
+		expect(
+			screen.getByRole( 'tabpanel', { name: 'Alpha' } )
+		).toBeInTheDocument();
+		expect( panelRenderFunction ).toHaveBeenLastCalledWith( TABS[ 0 ] );
+	} );
+
+	it( 'should render with a tab initially selected by prop initialTabIndex', () => {
+		render(
+			<TabPanel
+				initialTabName="beta"
+				tabs={ TABS }
+				children={ () => undefined }
+			/>
+		);
+		const selectedTab = screen.getByRole( 'tab', { selected: true } );
+		expect( selectedTab ).toHaveTextContent( 'Beta' );
+	} );
+
+	it( 'should apply the `activeClass` to the selected tab', async () => {
+		const user = setupUser();
+		const activeClass = 'my-active-tab';
+
+		render(
+			<TabPanel
+				activeClass={ activeClass }
+				tabs={ TABS }
+				children={ () => undefined }
+			/>
+		);
+		expect( getSelectedTab() ).toHaveClass( activeClass );
+		screen
+			.getAllByRole( 'tab', { selected: false } )
+			.forEach( ( unselectedTab ) => {
+				expect( unselectedTab ).not.toHaveClass( activeClass );
+			} );
+
+		await user.click( screen.getByRole( 'tab', { name: 'Beta' } ) );
+
+		expect( getSelectedTab() ).toHaveClass( activeClass );
+		screen
+			.getAllByRole( 'tab', { selected: false } )
+			.forEach( ( unselectedTab ) => {
+				expect( unselectedTab ).not.toHaveClass( activeClass );
+			} );
+	} );
+
+	it( "should apply the tab's `className` to the tab button", () => {
+		render( <TabPanel tabs={ TABS } children={ () => undefined } /> );
+
+		expect( screen.getByRole( 'tab', { name: 'Alpha' } ) ).toHaveClass(
+			'alpha-class'
+		);
+		expect( screen.getByRole( 'tab', { name: 'Beta' } ) ).toHaveClass(
+			'beta-class'
+		);
+		expect( screen.getByRole( 'tab', { name: 'Gamma' } ) ).toHaveClass(
+			'gamma-class'
+		);
+	} );
+} );

package/src/tab-panel/types.ts

@@ -0,0 +1,65 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+type Tab = {
+	/**
+	 * The key of the tab.
+	 */
+	name: string;
+	/**
+	 * The label of the tab.
+	 */
+	title: string;
+	/**
+	 * The class name to apply to the tab button.
+	 */
+	className?: string;
+} & Record< any, any >;
+
+export type TabButtonProps = {
+	children: ReactNode;
+	className?: string;
+	onClick: ( event: MouseEvent ) => void;
+	selected: boolean;
+	tabId: string;
+};
+
+export type TabPanelProps = {
+	/**
+	 * The class name to add to the active tab.
+	 *
+	 * @default 'is-active'
+	 */
+	activeClass?: string;
+	/**
+	 * A function which renders the tabviews given the selected tab.
+	 * The function is passed the active tab object as an argument as defined by the tabs prop.
+	 */
+	children: ( tab: Tab ) => ReactNode;
+	/**
+	 * The class name to give to the outer container for the TabPanel.
+	 */
+	className?: string;
+	/**
+	 * The name of the tab to be selected upon mounting of component.
+	 * If this prop is not set, the first tab will be selected by default.
+	 */
+	initialTabName?: string;
+	/**
+	 * The function called when a tab has been selected.
+	 * It is passed the `tabName` as an argument.
+	 */
+	onSelect?: ( tabName: string ) => void;
+	/**
+	 * The orientation of the tablist.
+	 *
+	 * @default `horizontal`
+	 */
+	orientation?: 'horizontal' | 'vertical';
+	/**
+	 * Array of tab objects. Each tab object should contain at least a `name` and a `title`.
+	 */
+	tabs: Tab[];
+};

package/src/text-control/index.tsx

@@ -21,6 +21,7 @@ function UnforwardedTextControl(
 	ref: ForwardedRef< HTMLInputElement >
 ) {
 	const {
+		__nextHasNoMarginBottom,
 		label,
 		hideLabelFromVision,
 		value,
@@ -37,6 +38,7 @@ function UnforwardedTextControl(
 
 	return (
 		<BaseControl
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			label={ label }
 			hideLabelFromVision={ hideLabelFromVision }
 			id={ id }

package/src/text-control/types.ts

@@ -10,7 +10,11 @@ import type { BaseControlProps } from '../base-control/types';
 
 export type TextControlProps = Pick<
 	BaseControlProps,
-	'className' | 'hideLabelFromVision' | 'help' | 'label'
+	| 'className'
+	| 'hideLabelFromVision'
+	| 'help'
+	| 'label'
+	| '__nextHasNoMarginBottom'
 > & {
 	/**
 	 * A function that receives the value of the input.

package/src/textarea-control/index.tsx

@@ -40,14 +40,10 @@ import type { WordPressComponentProps } from '../ui/context';
  * ```
  */
 export function TextareaControl(
-	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
-	// ref forwarding to TextareaControl.
-	props: Omit<
-		WordPressComponentProps< TextareaControlProps, 'textarea', false >,
-		'ref'
-	>
+	props: WordPressComponentProps< TextareaControlProps, 'textarea', false >
 ) {
 	const {
+		__nextHasNoMarginBottom,
 		label,
 		hideLabelFromVision,
 		value,
@@ -64,6 +60,7 @@ export function TextareaControl(
 
 	return (
 		<BaseControl
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			label={ label }
 			hideLabelFromVision={ hideLabelFromVision }
 			id={ id }

package/src/textarea-control/types.ts

@@ -10,7 +10,7 @@ import type { BaseControlProps } from '../base-control/types';
 
 export type TextareaControlProps = Pick<
 	BaseControlProps,
-	'hideLabelFromVision' | 'help' | 'label'
+	'hideLabelFromVision' | 'help' | 'label' | '__nextHasNoMarginBottom'
 > & {
 	/**
 	 * A function that receives the new value of the textarea each time it

package/src/toggle-control/index.tsx

@@ -0,0 +1,97 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent } from 'react';
+import { css } from '@emotion/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import FormToggle from '../form-toggle';
+import BaseControl from '../base-control';
+import type { WordPressComponentProps } from '../ui/context/wordpress-component';
+import type { ToggleControlProps } from './types';
+import { HStack } from '../h-stack';
+import { useCx } from '../utils';
+import { space } from '../ui/utils/space';
+
+/**
+ * ToggleControl is used to generate a toggle user interface.
+ *
+ * ```jsx
+ * import { ToggleControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyToggleControl = () => {
+ *   const [ value, setValue ] = useState( false );
+ *
+ *   return (
+ *     <ToggleControl
+ *       label="Fixed Background"
+ *       checked={ value }
+ *       onChange={ () => setValue( ( state ) => ! state ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function ToggleControl( {
+	__nextHasNoMarginBottom,
+	label,
+	checked,
+	help,
+	className,
+	onChange,
+	disabled,
+}: WordPressComponentProps< ToggleControlProps, 'input', false > ) {
+	function onChangeToggle( event: ChangeEvent< HTMLInputElement > ) {
+		onChange( event.target.checked );
+	}
+	const instanceId = useInstanceId( ToggleControl );
+	const id = `inspector-toggle-control-${ instanceId }`;
+
+	const cx = useCx();
+	const classes = cx(
+		'components-toggle-control',
+		className,
+		! __nextHasNoMarginBottom && css( { marginBottom: space( 3 ) } )
+	);
+
+	let describedBy, helpLabel;
+	if ( help ) {
+		describedBy = id + '__help';
+		helpLabel = typeof help === 'function' ? help( checked ) : help;
+	}
+
+	return (
+		<BaseControl
+			id={ id }
+			help={ helpLabel }
+			className={ classes }
+			__nextHasNoMarginBottom
+		>
+			<HStack justify="flex-start" spacing={ 3 }>
+				<FormToggle
+					id={ id }
+					checked={ checked }
+					onChange={ onChangeToggle }
+					aria-describedby={ describedBy }
+					disabled={ disabled }
+				/>
+				<label
+					htmlFor={ id }
+					className="components-toggle-control__label"
+				>
+					{ label }
+				</label>
+			</HStack>
+		</BaseControl>
+	);
+}
+
+export default ToggleControl;

package/src/toggle-control/stories/index.tsx

@@ -0,0 +1,58 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import ToggleControl from '..';
+
+const meta: ComponentMeta< typeof ToggleControl > = {
+	title: 'Components/ToggleControl',
+	component: ToggleControl,
+	argTypes: {
+		checked: { control: { type: null } },
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+		onChange: { action: 'onChange' },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof ToggleControl > = ( {
+	onChange,
+	...props
+} ) => {
+	const [ checked, setChecked ] = useState( true );
+	return (
+		<ToggleControl
+			{ ...props }
+			checked={ checked }
+			onChange={ ( ...changeArgs ) => {
+				setChecked( ...changeArgs );
+				onChange( ...changeArgs );
+			} }
+		/>
+	);
+};
+
+export const Default = Template.bind( {} );
+Default.args = {
+	label: 'Enable something',
+};
+
+export const WithHelpText = Template.bind( {} );
+WithHelpText.args = {
+	...Default.args,
+	help: 'This is some help text.',
+};

package/src/toggle-control/test/index.tsx

@@ -0,0 +1,53 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import ToggleControl from '..';
+
+describe( 'ToggleControl', () => {
+	it( 'should label the toggle', () => {
+		render( <ToggleControl label="My toggle" onChange={ () => {} } /> );
+
+		expect(
+			screen.getByRole( 'checkbox', { name: 'My toggle' } )
+		).toBeInTheDocument();
+	} );
+
+	it( 'triggers change callback with boolean', () => {
+		const onChange = jest.fn();
+
+		render( <ToggleControl label="My toggle" onChange={ onChange } /> );
+
+		screen.getByRole( 'checkbox' ).click();
+		expect( onChange ).toHaveBeenLastCalledWith( true );
+
+		screen.getByRole( 'checkbox' ).click();
+		expect( onChange ).toHaveBeenLastCalledWith( false );
+	} );
+
+	describe( 'help', () => {
+		it( 'should not give the input a description if no `help` prop', () => {
+			render( <ToggleControl label="My toggle" onChange={ () => {} } /> );
+			expect(
+				screen.getByRole( 'checkbox' )
+			).not.toHaveAccessibleDescription();
+		} );
+
+		it( "should associate `help` as the input's description", () => {
+			render(
+				<ToggleControl
+					help="My help text"
+					label="My toggle"
+					onChange={ () => {} }
+				/>
+			);
+			expect(
+				screen.getByRole( 'checkbox', { description: 'My help text' } )
+			).toBeInTheDocument();
+		} );
+	} );
+} );

package/src/toggle-control/types.ts

@@ -0,0 +1,28 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+import type { FormToggleProps } from '../form-toggle/types';
+
+export type ToggleControlProps = Pick<
+	FormToggleProps,
+	'checked' | 'disabled'
+> &
+	Pick<
+		BaseControlProps,
+		'__nextHasNoMarginBottom' | 'help' | 'className'
+	> & {
+		/**
+		 * The label for the toggle.
+		 */
+		label: ReactNode;
+		/**
+		 * A callback function invoked when the toggle is clicked.
+		 */
+		onChange: ( value: boolean ) => void;
+	};

package/src/toggle-group-control/stories/index.tsx

@@ -112,16 +112,23 @@ WithTooltip.args = {
 /**
  * The `ToggleGroupControlOptionIcon` component can be used for icon options. A `label` is required
  * on each option for accessibility, which will be shown in a tooltip.
- *
- * When using icon options within `ToggleGroupControl`, the `__experimentalIsIconGroup` style is preferred.
  */
 export const WithIcons: ComponentStory< typeof ToggleGroupControl > =
 	Template.bind( {} );
 WithIcons.args = {
 	...Default.args,
-	__experimentalIsIconGroup: true,
 	children: [
 		{ value: 'uppercase', label: 'Uppercase', icon: formatUppercase },
 		{ value: 'lowercase', label: 'Lowercase', icon: formatLowercase },
 	].map( mapPropsToOptionIconComponent ),
 };
+
+/**
+ * A borderless style may be preferred in some contexts.
+ */
+export const Borderless: ComponentStory< typeof ToggleGroupControl > =
+	Template.bind( {} );
+Borderless.args = {
+	...WithIcons.args,
+	__experimentalIsBorderless: true,
+};

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -45,7 +45,7 @@ function UnconnectedToggleGroupControl(
 		className,
 		isAdaptiveWidth = false,
 		isBlock = false,
-		__experimentalIsIconGroup = false,
+		__experimentalIsBorderless = false,
 		label,
 		hideLabelFromVision = false,
 		help,
@@ -88,11 +88,11 @@ function UnconnectedToggleGroupControl(
 		() =>
 			cx(
 				styles.ToggleGroupControl( { size } ),
-				! __experimentalIsIconGroup && styles.border,
+				! __experimentalIsBorderless && styles.border,
 				isBlock && styles.block,
 				className
 			),
-		[ className, cx, isBlock, __experimentalIsIconGroup, size ]
+		[ className, cx, isBlock, __experimentalIsBorderless, size ]
 	);
 	return (
 		<BaseControl