@wordpress/components 20.0.0 → 21.0.0

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/text-highlight/index.tsx

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { escapeRegExp } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -11,6 +6,7 @@ import { createInterpolateElement } from '@wordpress/element';
 /**
  * Internal dependencies
  */
+import { escapeRegExp } from '../utils/strings';
 import type { TextHighlightProps } from './types';
 
 /**

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,
+};