@wordpress/components 23.1.0 → 23.3.0

package/src/button/README.md

@@ -121,131 +121,125 @@ The presence of a `href` prop determines whether an `anchor` element is rendered
 
 Props not included in this set will be applied to the `a` or `button` element.
 
-#### disabled
+#### `children`: `ReactNode`
 
-Whether the button is disabled. If `true`, this will force a `button` element to be rendered.
+The button's children.
 
--   Type: `Boolean`
 -   Required: No
 
-#### href
+#### `className`: `string`
 
-If provided, renders `a` instead of `button`.
+An optional additional class name to apply to the rendered button.
 
--   Type: `String`
 -   Required: No
 
-#### variant
+#### `describedBy`: `string`
 
-Specifies the button's style. The accepted values are `'primary'` (the primary button styles), `'secondary'` (the default button styles), `'tertiary'` (the text-based button styles), and `'link'` (the link button styles).
+An accessible description for the button.
 
--   Type: `String`
 -   Required: No
 
-#### isDestructive
+#### `disabled`: `boolean`
 
-Renders a red text-based button style to indicate destructive behavior.
+Whether the button is disabled. If `true`, this will force a `button` element to be rendered.
 
--   Type: `Boolean`
 -   Required: No
 
-#### isSmall
+#### `focus`: `boolean`
 
-Decreases the size of the button.
+Whether the button is focused.
 
--   Type: `Boolean`
 -   Required: No
 
-#### isPressed
+#### `href`: `string`
 
-Renders a pressed button style.
+If provided, renders `a` instead of `button`.
 
--   Type: `Boolean`
 -   Required: No
 
-#### isBusy
+#### `icon`: `IconProps< unknown >[ 'icon' ]`
 
-Indicates activity while a action is being performed.
+If provided, renders an [Icon](/packages/components/src/icon/README.md) component inside the button.
 
--   Type: `Boolean`
 -   Required: No
 
-#### focus
+#### `iconPosition`: `'left' | 'right'`
 
-Whether the button is focused.
+If provided with `icon`, sets the position of icon relative to the `text`. Available options are `left|right`.
 
--   Type: `Boolean`
 -   Required: No
+-   Default: `left`
 
-#### target
+#### `iconSize`: `IconProps< unknown >[ 'size' ]`
 
-If provided with `href`, sets the `target` attribute to the `a`.
+If provided with `icon`, sets the icon size. Please refer to the [Icon](/packages/components/src/icon/README.md) component for more details regarding the default value of its `size` prop.
 
--   Type: `String`
 -   Required: No
 
-#### className
+#### `isBusy`: `boolean`
 
-An optional additional class name to apply to the rendered button.
+Indicates activity while a action is being performed.
 
--   Type: `String`
 -   Required: No
 
-#### icon
+#### `isDestructive`: `boolean`
 
-If provided, renders an [Icon](/packages/components/src/icon/README.md) component inside the button.
+Renders a red text-based button style to indicate destructive behavior.
 
--   Type: `String|Function|WPComponent|null`
 -   Required: No
 
-#### iconSize
+#### `isPressed`: `boolean`
 
-If provided with `icon`, sets the icon size. Please refer to the [Icon](/packages/components/src/icon/README.md) component for more details regarding the default value of its `size` prop.
+Renders a pressed button style.
 
--   Type: `Number`
 -   Required: No
 
-#### iconPosition
+#### `isSmall`: `boolean`
 
-If provided with `icon`, sets the position of icon relative to the `text`. Available options are `left|right`.
+Decreases the size of the button.
 
--   Type: `string`
 -   Required: No
--   Default: `left`
 
-#### text
+#### `label`: `string`
 
-If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.
+Sets the `aria-label` of the component, if none is provided. Sets the Tooltip content if `showTooltip` is provided.
 
--   Type: `String`
 -   Required: No
 
-#### showTooltip
+#### `shortcut`: `string | { display: string; ariaLabel: string; }`
+
+If provided with `showTooltip`, appends the Shortcut label to the tooltip content. If an object is provided, it should contain `display` and `ariaLabel` keys.
+
+-   Required: No
+
+#### `showTooltip`: `boolean`
 
 If provided, renders a [Tooltip](/packages/components/src/tooltip/README.md) component for the button.
 
--   Type: `Boolean`
 -   Required: No
 
-#### tooltipPosition
+#### `target`: `string`
 
-If provided with`showTooltip`, sets the position of the tooltip. Please refer to the [Tooltip](/packages/components/src/tooltip/README.md) component for more details regarding the defaults.
+If provided with `href`, sets the `target` attribute to the `a`.
 
--   Type: `String`
--   Require: No
+-   Required: No
 
-#### shortcut
+#### `text`: `string`
 
-If provided with `showTooltip`, appends the Shortcut label to the tooltip content. If an `Object` is provided, it should contain `display` and `ariaLabel` keys.
+If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.
 
--   Type: `String|Object`
 -   Required: No
 
-#### label
+#### `tooltipPosition`: `PopoverProps[ 'position' ]`
 
-Sets the `aria-label` of the component, if none is provided. Sets the Tooltip content if `showTooltip` is provided.
+If provided with`showTooltip`, sets the position of the tooltip. Please refer to the [Tooltip](/packages/components/src/tooltip/README.md) component for more details regarding the defaults.
+
+-   Required: No
+
+#### `variant`: `'primary' | 'secondary' | 'tertiary' | 'link'`
+
+Specifies the button's style. The accepted values are `'primary'` (the primary button styles), `'secondary'` (the default button styles), `'tertiary'` (the text-based button styles), and `'link'` (the link button styles).
 
--   Type: `String`
 -   Required: No
 
 ## Related components

package/src/button/{deprecated.js → deprecated.tsx}

@@ -1,4 +1,8 @@
-// @ts-nocheck
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * WordPress dependencies
  */
@@ -8,9 +12,20 @@ import { forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Button from '../button';
+import Button from '.';
+import type { DeprecatedIconButtonProps } from './types';
 
-function IconButton( { labelPosition, size, tooltip, label, ...props }, ref ) {
+function UnforwardedIconButton(
+	{
+		label,
+		labelPosition,
+		size,
+		tooltip,
+		...props
+	}: React.ComponentPropsWithoutRef< typeof Button > &
+		DeprecatedIconButtonProps,
+	ref: ForwardedRef< any >
+) {
 	deprecated( 'wp.components.IconButton', {
 		since: '5.4',
 		alternative: 'wp.components.Button',
@@ -29,4 +44,4 @@ function IconButton( { labelPosition, size, tooltip, label, ...props }, ref ) {
 	);
 }
 
-export default forwardRef( IconButton );
+export default forwardRef( UnforwardedIconButton );

package/src/button/{index.js → index.tsx}

@@ -1,8 +1,14 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
 import classnames from 'classnames';
+import type {
+	ComponentPropsWithoutRef,
+	ForwardedRef,
+	HTMLAttributes,
+	MouseEvent,
+	ReactElement,
+} from 'react';
 
 /**
  * WordPress dependencies
@@ -17,8 +23,9 @@ import { useInstanceId } from '@wordpress/compose';
 import Tooltip from '../tooltip';
 import Icon from '../icon';
 import { VisuallyHidden } from '../visually-hidden';
+import type { ButtonProps, DeprecatedButtonProps } from './types';
 
-const disabledEventsOnDisabledButton = [ 'onMouseDown', 'onClick' ];
+const disabledEventsOnDisabledButton = [ 'onMouseDown', 'onClick' ] as const;
 
 function useDeprecatedProps( {
 	isDefault,
@@ -28,7 +35,7 @@ function useDeprecatedProps( {
 	isLink,
 	variant,
 	...otherProps
-} ) {
+}: ButtonProps & DeprecatedButtonProps ): ButtonProps {
 	let computedVariant = variant;
 
 	if ( isPrimary ) {
@@ -63,10 +70,11 @@ function useDeprecatedProps( {
 	};
 }
 
-export function Button( props, ref ) {
+export function UnforwardedButton(
+	props: ButtonProps,
+	ref: ForwardedRef< any >
+) {
 	const {
-		href,
-		target,
 		isSmall,
 		isPressed,
 		isBusy,
@@ -85,18 +93,26 @@ export function Button( props, ref ) {
 		variant,
 		__experimentalIsFocusable: isFocusable,
 		describedBy,
-		...additionalProps
+		...buttonOrAnchorProps
 	} = useDeprecatedProps( props );
+
+	const { href, target, ...additionalProps } =
+		'href' in buttonOrAnchorProps
+			? buttonOrAnchorProps
+			: { href: undefined, target: undefined, ...buttonOrAnchorProps };
+
 	const instanceId = useInstanceId(
 		Button,
 		'components-button__description'
 	);
 
 	const hasChildren =
-		children?.[ 0 ] &&
-		children[ 0 ] !== null &&
-		// Tooltip should not considered as a child
-		children?.[ 0 ]?.props?.className !== 'components-tooltip';
+		( 'string' === typeof children && !! children ) ||
+		( Array.isArray( children ) &&
+			children?.[ 0 ] &&
+			children[ 0 ] !== null &&
+			// Tooltip should not considered as a child
+			children?.[ 0 ]?.props?.className !== 'components-tooltip' );
 
 	const classes = classnames( 'components-button', className, {
 		'is-secondary': variant === 'secondary',
@@ -113,24 +129,29 @@ export function Button( props, ref ) {
 
 	const trulyDisabled = disabled && ! isFocusable;
 	const Tag = href !== undefined && ! trulyDisabled ? 'a' : 'button';
-	const tagProps =
-		Tag === 'a'
-			? { href, target }
-			: {
+	const buttonProps: ComponentPropsWithoutRef< 'button' > =
+		Tag === 'button'
+			? {
 					type: 'button',
 					disabled: trulyDisabled,
 					'aria-pressed': isPressed,
-			  };
+			  }
+			: {};
+	const anchorProps: ComponentPropsWithoutRef< 'a' > =
+		Tag === 'a' ? { href, target } : {};
 
 	if ( disabled && isFocusable ) {
 		// In this case, the button will be disabled, but still focusable and
 		// perceivable by screen reader users.
-		tagProps[ 'aria-disabled' ] = true;
+		buttonProps[ 'aria-disabled' ] = true;
+		anchorProps[ 'aria-disabled' ] = true;
 
 		for ( const disabledEvent of disabledEventsOnDisabledButton ) {
-			additionalProps[ disabledEvent ] = ( event ) => {
-				event.stopPropagation();
-				event.preventDefault();
+			additionalProps[ disabledEvent ] = ( event: MouseEvent ) => {
+				if ( event ) {
+					event.stopPropagation();
+					event.preventDefault();
+				}
 			};
 		}
 	}
@@ -145,24 +166,24 @@ export function Button( props, ref ) {
 			// There's a label and...
 			( !! label &&
 				// The children are empty and...
-				! children?.length &&
+				! ( children as string | ReactElement[] )?.length &&
 				// The tooltip is not explicitly disabled.
 				false !== showTooltip ) );
 
-	const descriptionId = describedBy ? instanceId : null;
+	const descriptionId = describedBy ? instanceId : undefined;
 
 	const describedById =
 		additionalProps[ 'aria-describedby' ] || descriptionId;
 
-	const element = (
-		<Tag
-			{ ...tagProps }
-			{ ...additionalProps }
-			className={ classes }
-			aria-label={ additionalProps[ 'aria-label' ] || label }
-			aria-describedby={ describedById }
-			ref={ ref }
-		>
+	const commonProps = {
+		className: classes,
+		'aria-label': additionalProps[ 'aria-label' ] || label,
+		'aria-describedby': describedById,
+		ref,
+	};
+
+	const elementChildren = (
+		<>
 			{ icon && iconPosition === 'left' && (
 				<Icon icon={ icon } size={ iconSize } />
 			) }
@@ -171,9 +192,28 @@ export function Button( props, ref ) {
 				<Icon icon={ icon } size={ iconSize } />
 			) }
 			{ children }
-		</Tag>
+		</>
 	);
 
+	const element =
+		Tag === 'a' ? (
+			<a
+				{ ...anchorProps }
+				{ ...( additionalProps as HTMLAttributes< HTMLAnchorElement > ) }
+				{ ...commonProps }
+			>
+				{ elementChildren }
+			</a>
+		) : (
+			<button
+				{ ...buttonProps }
+				{ ...( additionalProps as HTMLAttributes< HTMLButtonElement > ) }
+				{ ...commonProps }
+			>
+				{ elementChildren }
+			</button>
+		);
+
 	if ( ! shouldShowTooltip ) {
 		return (
 			<>
@@ -190,7 +230,12 @@ export function Button( props, ref ) {
 	return (
 		<>
 			<Tooltip
-				text={ children?.length && describedBy ? describedBy : label }
+				text={
+					( children as string | ReactElement[] )?.length &&
+					describedBy
+						? describedBy
+						: label
+				}
 				shortcut={ shortcut }
 				position={ tooltipPosition }
 			>
@@ -205,4 +250,20 @@ export function Button( props, ref ) {
 	);
 }
 
-export default forwardRef( Button );
+/**
+ * Lets users take actions and make choices with a single click or tap.
+ *
+ * ```jsx
+ * import { Button } from '@wordpress/components';
+ * const Mybutton = () => (
+ *   <Button
+ *     variant="primary"
+ *     onClick={ handleClick }
+ *   >
+ *     Click here
+ *   </Button>
+ * );
+ * ```
+ */
+export const Button = forwardRef( UnforwardedButton );
+export default Button;

package/src/button/stories/index.tsx

@@ -0,0 +1,106 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { ReactNode } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	formatBold,
+	formatItalic,
+	link,
+	more,
+	wordpress,
+} from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import './style.css';
+import Button from '..';
+
+const meta: ComponentMeta< typeof Button > = {
+	title: 'Components/Button',
+	component: Button,
+	argTypes: {
+		// Overrides a limitation of the docgen interpreting our TS types for this as required.
+		href: { type: { name: 'string', required: false } },
+		icon: {
+			control: { type: 'select' },
+			options: [ 'wordpress', 'link', 'more' ],
+			mapping: {
+				wordpress,
+				link,
+				more,
+			},
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Button > = ( props ) => {
+	return <Button { ...props }></Button>;
+};
+
+export const Default: ComponentStory< typeof Button > = Template.bind( {} );
+Default.args = {
+	children: 'Code is poetry',
+};
+
+export const Primary: ComponentStory< typeof Button > = Template.bind( {} );
+Primary.args = {
+	...Default.args,
+	variant: 'primary',
+};
+
+export const Secondary: ComponentStory< typeof Button > = Template.bind( {} );
+Secondary.args = {
+	...Default.args,
+	variant: 'secondary',
+};
+
+export const Tertiary: ComponentStory< typeof Button > = Template.bind( {} );
+Tertiary.args = {
+	...Default.args,
+	variant: 'tertiary',
+};
+
+export const Link: ComponentStory< typeof Button > = Template.bind( {} );
+Link.args = {
+	...Default.args,
+	variant: 'link',
+};
+
+export const IsDestructive: ComponentStory< typeof Button > = Template.bind(
+	{}
+);
+IsDestructive.args = {
+	...Default.args,
+	isDestructive: true,
+};
+
+export const Icon: ComponentStory< typeof Button > = Template.bind( {} );
+Icon.args = {
+	label: 'Code is poetry',
+	icon: 'wordpress',
+};
+
+export const GroupedIcons: ComponentStory< typeof Button > = () => {
+	const GroupContainer = ( { children }: { children: ReactNode } ) => (
+		<div style={ { display: 'inline-flex' } }>{ children }</div>
+	);
+
+	return (
+		<GroupContainer>
+			<Button icon={ formatBold } label="Bold" />
+			<Button icon={ formatItalic } label="Italic" />
+			<Button icon={ link } label="Link" />
+		</GroupContainer>
+	);
+};

package/src/button/style.scss

@@ -282,14 +282,15 @@
 
 		&.has-text {
 			justify-content: start;
+			padding-right: 12px;
 		}
 
 		&.has-text svg {
-			margin-right: 8px;
+			margin-right: $grid-unit-10;
 		}
 
 		&.has-text .dashicon {
-			margin-right: 10px;
+			margin-right: $grid-unit-10 + 2px;
 		}
 	}
 

package/src/button/test/{index.js → index.tsx}

@@ -12,8 +12,8 @@ import { plusCircle } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import Button from '../';
-import { Tooltip } from '../../';
+import Button from '..';
+import Tooltip from '../../tooltip';
 
 jest.mock( '../../icon', () => () => <div data-testid="test-icon" /> );
 
@@ -126,6 +126,7 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should not pass the prop target into the element', () => {
+			// @ts-expect-error - `target` requires `href`
 			render( <Button target="_blank" /> );
 
 			expect( screen.getByRole( 'button' ) ).not.toHaveAttribute(
@@ -139,13 +140,12 @@ describe( 'Button', () => {
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'gutenberg' );
 		} );
 
-		it( 'should render an additional WordPress prop of value awesome', () => {
-			render( <Button WordPress="awesome" /> );
+		it( 'should pass additional props to the element', () => {
+			render( <Button type="submit" /> );
 
-			expect( console ).toHaveErrored();
 			expect( screen.getByRole( 'button' ) ).toHaveAttribute(
-				'wordpress',
-				'awesome'
+				'type',
+				'submit'
 			);
 		} );
 
@@ -342,6 +342,7 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should become a button again when disabled is supplied', () => {
+			// @ts-expect-error - a button should not have `href`
 			render( <Button href="https://wordpress.org/" disabled /> );
 
 			expect( screen.getByRole( 'button' ) ).toBeVisible();
@@ -360,11 +361,13 @@ describe( 'Button', () => {
 
 	describe( 'deprecated props', () => {
 		it( 'should not break when the legacy isPrimary prop is passed', () => {
+			// @ts-expect-error
 			render( <Button isPrimary /> );
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'is-primary' );
 		} );
 
 		it( 'should not break when the legacy isSecondary prop is passed', () => {
+			// @ts-expect-error
 			render( <Button isSecondary /> );
 			expect( screen.getByRole( 'button' ) ).toHaveClass(
 				'is-secondary'
@@ -372,16 +375,19 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should not break when the legacy isTertiary prop is passed', () => {
+			// @ts-expect-error
 			render( <Button isTertiary /> );
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'is-tertiary' );
 		} );
 
 		it( 'should not break when the legacy isLink prop is passed', () => {
+			// @ts-expect-error
 			render( <Button isLink /> );
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'is-link' );
 		} );
 
 		it( 'should warn when the isDefault prop is passed', () => {
+			// @ts-expect-error
 			render( <Button isDefault /> );
 			expect( screen.getByRole( 'button' ) ).toHaveClass(
 				'is-secondary'
@@ -389,4 +395,21 @@ describe( 'Button', () => {
 			expect( console ).toHaveWarned();
 		} );
 	} );
+
+	describe( 'static typing', () => {
+		<>
+			<Button href="foo" />
+			{ /* @ts-expect-error - `target` requires `href` */ }
+			<Button target="foo" />
+			{ /* @ts-expect-error - `disabled` is only for buttons */ }
+			<Button href="foo" disabled />
+			<Button href="foo" type="image/png" />
+			{ /* @ts-expect-error - if button, type must be submit/reset/button */ }
+			<Button type="image/png" />
+			{ /* @ts-expect-error */ }
+			<Button type="invalidtype" />
+			{ /* @ts-expect-error - although the runtime behavior will allow this to be an anchor, this is probably a mistake. */ }
+			<Button disabled __experimentalIsFocusable href="foo" />
+		</>;
+	} );
 } );