@wordpress/components 19.11.0 → 19.14.0

package/src/surface/stories/index.tsx

@@ -0,0 +1,40 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Surface } from '..';
+import { Text } from '../../text';
+
+const meta: ComponentMeta< typeof Surface > = {
+	component: Surface,
+	title: 'Components (Experimental)/Surface',
+	argTypes: {
+		children: { control: { type: null } },
+		as: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Surface > = ( args ) => {
+	return (
+		<Surface
+			{ ...args }
+			style={ { padding: 20, maxWidth: 400, margin: '20vh auto' } }
+		>
+			<Text>Code is Poetry</Text>
+		</Surface>
+	);
+};
+
+export const Default: ComponentStory< typeof Surface > = Template.bind( {} );
+Default.args = {};

package/src/surface/{styles.js → styles.ts}

@@ -7,6 +7,7 @@ import { css } from '@emotion/react';
  * Internal dependencies
  */
 import { CONFIG, COLORS } from '../utils';
+import type { SurfaceVariant, SurfaceProps } from './types';
 
 export const Surface = css`
 	background-color: ${ CONFIG.surfaceColor };
@@ -18,19 +19,15 @@ export const background = css`
 	background-color: ${ CONFIG.surfaceBackgroundColor };
 `;
 
-/**
- * @param {Object}  props
- * @param {boolean} [props.borderBottom]
- * @param {boolean} [props.borderLeft]
- * @param {boolean} [props.borderRight]
- * @param {boolean} [props.borderTop]
- */
 export function getBorders( {
 	borderBottom,
 	borderLeft,
 	borderRight,
 	borderTop,
-} ) {
+}: Pick<
+	SurfaceProps,
+	'borderBottom' | 'borderLeft' | 'borderRight' | 'borderTop'
+> ) {
 	const borderStyle = `1px solid ${ CONFIG.surfaceBorderColor }`;
 
 	return css( {
@@ -51,16 +48,10 @@ export const tertiary = css`
 	background: ${ CONFIG.surfaceBackgroundTertiaryColor };
 `;
 
-/**
- * @param {string} surfaceBackgroundSize
- */
-const customBackgroundSize = ( surfaceBackgroundSize ) =>
+const customBackgroundSize = ( surfaceBackgroundSize: string ) =>
 	[ surfaceBackgroundSize, surfaceBackgroundSize ].join( ' ' );
 
-/**
- * @param {string} surfaceBackgroundSizeDotted
- */
-const dottedBackground1 = ( surfaceBackgroundSizeDotted ) =>
+const dottedBackground1 = ( surfaceBackgroundSizeDotted: string ) =>
 	[
 		'90deg',
 		[ CONFIG.surfaceBackgroundColor, surfaceBackgroundSizeDotted ].join(
@@ -69,10 +60,7 @@ const dottedBackground1 = ( surfaceBackgroundSizeDotted ) =>
 		'transparent 1%',
 	].join( ',' );
 
-/**
- * @param {string} surfaceBackgroundSizeDotted
- */
-const dottedBackground2 = ( surfaceBackgroundSizeDotted ) =>
+const dottedBackground2 = ( surfaceBackgroundSizeDotted: string ) =>
 	[
 		[ CONFIG.surfaceBackgroundColor, surfaceBackgroundSizeDotted ].join(
 			' '
@@ -80,10 +68,7 @@ const dottedBackground2 = ( surfaceBackgroundSizeDotted ) =>
 		'transparent 1%',
 	].join( ',' );
 
-/**
- * @param {string} surfaceBackgroundSizeDotted
- */
-const dottedBackgroundCombined = ( surfaceBackgroundSizeDotted ) =>
+const dottedBackgroundCombined = ( surfaceBackgroundSizeDotted: string ) =>
 	[
 		`linear-gradient( ${ dottedBackground1(
 			surfaceBackgroundSizeDotted
@@ -94,14 +79,9 @@ const dottedBackgroundCombined = ( surfaceBackgroundSizeDotted ) =>
 		CONFIG.surfaceBorderBoldColor,
 	].join( ',' );
 
-/**
- *
- * @param {string} surfaceBackgroundSize
- * @param {string} surfaceBackgroundSizeDotted
- */
 export const getDotted = (
-	surfaceBackgroundSize,
-	surfaceBackgroundSizeDotted
+	surfaceBackgroundSize: string,
+	surfaceBackgroundSizeDotted: string
 ) => css`
 	background: ${ dottedBackgroundCombined( surfaceBackgroundSizeDotted ) };
 	background-size: ${ customBackgroundSize( surfaceBackgroundSize ) };
@@ -123,11 +103,7 @@ const gridBackgroundCombined = [
 	`linear-gradient( ${ gridBackground2 } )`,
 ].join( ',' );
 
-/**
- * @param {string} surfaceBackgroundSize
- * @return {import('@emotion/react').SerializedStyles} CSS.
- */
-export const getGrid = ( surfaceBackgroundSize ) => {
+export const getGrid = ( surfaceBackgroundSize: string ) => {
 	return css`
 		background: ${ CONFIG.surfaceBackgroundColor };
 		background-image: ${ gridBackgroundCombined };
@@ -135,15 +111,10 @@ export const getGrid = ( surfaceBackgroundSize ) => {
 	`;
 };
 
-/**
- * @param {'dotted' | 'grid' | 'primary' | 'secondary' | 'tertiary'} variant
- * @param {string}                                                   surfaceBackgroundSize
- * @param {string}                                                   surfaceBackgroundSizeDotted
- */
 export const getVariant = (
-	variant,
-	surfaceBackgroundSize,
-	surfaceBackgroundSizeDotted
+	variant: SurfaceVariant,
+	surfaceBackgroundSize: string,
+	surfaceBackgroundSizeDotted: string
 ) => {
 	switch ( variant ) {
 		case 'dotted': {

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { render } from '@testing-library/react';
+import type { RenderResult } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -9,7 +10,7 @@ import { render } from '@testing-library/react';
 import { Surface } from '../index';
 
 describe( 'props', () => {
-	let base;
+	let base: RenderResult;
 	beforeEach( () => {
 		base = render( <Surface>Surface</Surface> );
 	} );

package/src/surface/types.ts

@@ -5,7 +5,7 @@ export type SurfaceVariant =
 	| 'dotted'
 	| 'grid';
 
-export type Props = {
+export type SurfaceProps = {
 	/**
 	 * Determines the grid size for "dotted" and "grid" variants.
 	 *

package/src/tab-panel/index.js

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { partial, noop, find } from 'lodash';
+import { partial, find } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -16,6 +16,8 @@ import { useInstanceId } from '@wordpress/compose';
 import { NavigableMenu } from '../navigable-container';
 import Button from '../button';
 
+const noop = () => {};
+
 const TabButton = ( { tabId, onClick, children, selected, ...rest } ) => (
 	<Button
 		role="tab"

package/src/text/hook.js

@@ -89,7 +89,10 @@ export default function useText( props ) {
 			display,
 			fontSize: getFontSize( size ),
 			/* eslint-disable jsdoc/valid-types */
-			fontWeight: /** @type {import('react').CSSProperties['fontWeight']} */ ( weight ),
+			fontWeight:
+				/** @type {import('react').CSSProperties['fontWeight']} */ (
+					weight
+				),
 			/* eslint-enable jsdoc/valid-types */
 			lineHeight,
 			letterSpacing,

package/src/text/types.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import type { Props as TruncateProps } from '../truncate/types';
+import type { TruncateProps } from '../truncate/types';
 
 /**
  * External dependencies

package/src/text/utils.js

@@ -102,9 +102,8 @@ export function createHighlighterText( {
 			let highlightClass;
 			if ( typeof highlightClassName === 'object' ) {
 				if ( ! caseSensitive ) {
-					highlightClassName = memoizedLowercaseProps(
-						highlightClassName
-					);
+					highlightClassName =
+						memoizedLowercaseProps( highlightClassName );
 					highlightClass = highlightClassName[ text.toLowerCase() ];
 				} else {
 					highlightClass = highlightClassName[ text ];

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

@@ -51,14 +51,12 @@ const DefaultTemplate: ComponentStory< typeof TextControl > = ( {
 	);
 };
 
-export const Default: ComponentStory<
-	typeof TextControl
-> = DefaultTemplate.bind( {} );
+export const Default: ComponentStory< typeof TextControl > =
+	DefaultTemplate.bind( {} );
 Default.args = {};
 
-export const WithLabelAndHelpText: ComponentStory<
-	typeof TextControl
-> = DefaultTemplate.bind( {} );
+export const WithLabelAndHelpText: ComponentStory< typeof TextControl > =
+	DefaultTemplate.bind( {} );
 WithLabelAndHelpText.args = {
 	...Default.args,
 	label: 'Label Text',

package/src/textarea-control/README.md

@@ -100,47 +100,41 @@ The set of props accepted by the component will be specified below.
 
 Props not included in this set will be applied to the textarea element.
 
-#### label
+#### `help`: `string | WPElement`
 
-If this property is added, a label will be generated using label property as the content.
+If this property is added, a help text will be generated using help property as the content.
 
--   Type: `String`
 -   Required: No
 
-#### hideLabelFromVision
+#### `hideLabelFromVision`: `boolean`
 
 If true, the label will only be visible to screen readers.
 
--   Type: `Boolean`
 -   Required: No
 
-#### help
+#### `label`: `string`
 
-If this property is added, a help text will be generated using help property as the content.
+If this property is added, a label will be generated using label property as the content.
 
--   Type: `String|WPElement`
 -   Required: No
 
-#### rows
+#### `onChange`: `( value: string ) => void`
 
-The number of rows the textarea should contain. Defaults to four.
+A function that receives the new value of the textarea each time it changes.
 
--   Type: `String`
--   Required: No
--   Default: 4
+-   Required: Yes
 
-#### value
+#### `rows`: `number`
 
-The current value of the textarea.
+The number of rows the textarea should contain.
 
--   Type: `String`
--   Required: Yes
+-   Required: No
+-   Default: 4
 
-#### onChange
+#### `value`: `string`
 
-A function that receives the new value of the textarea each time it changes.
+The current value of the textarea.
 
--   Type: `function`
 -   Required: Yes
 
 ## Related components

package/src/textarea-control/index.tsx

@@ -0,0 +1,86 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import { StyledTextarea } from './styles/textarea-control-styles';
+import type { TextareaControlProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+/**
+ * TextareaControls are TextControls that allow for multiple lines of text, and
+ * wrap overflow text onto a new line. They are a fixed height and scroll
+ * vertically when the cursor reaches the bottom of the field.
+ *
+ * ```jsx
+ * import { TextareaControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyTextareaControl = () => {
+ *   const [ text, setText ] = useState( '' );
+ *
+ *   return (
+ *     <TextareaControl
+ *       label="Text"
+ *       help="Enter some text"
+ *       value={ text }
+ *       onChange={ ( value ) => setText( value ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function TextareaControl(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to TextareaControl.
+	props: Omit<
+		WordPressComponentProps< TextareaControlProps, 'textarea', false >,
+		'ref'
+	>
+) {
+	const {
+		label,
+		hideLabelFromVision,
+		value,
+		help,
+		onChange,
+		rows = 4,
+		className,
+		...additionalProps
+	} = props;
+	const instanceId = useInstanceId( TextareaControl );
+	const id = `inspector-textarea-control-${ instanceId }`;
+	const onChangeValue = ( event: ChangeEvent< HTMLTextAreaElement > ) =>
+		onChange( event.target.value );
+
+	return (
+		<BaseControl
+			label={ label }
+			hideLabelFromVision={ hideLabelFromVision }
+			id={ id }
+			help={ help }
+			className={ className }
+		>
+			<StyledTextarea
+				className="components-textarea-control__input"
+				id={ id }
+				rows={ rows }
+				onChange={ onChangeValue }
+				aria-describedby={ !! help ? id + '__help' : undefined }
+				value={ value }
+				{ ...additionalProps }
+			/>
+		</BaseControl>
+	);
+}
+
+export default TextareaControl;

package/src/textarea-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 TextareaControl from '..';
+
+const meta: ComponentMeta< typeof TextareaControl > = {
+	component: TextareaControl,
+	title: 'Components/TextareaControl',
+	argTypes: {
+		onChange: { action: 'onChange' },
+		label: { control: { type: 'text' } },
+		help: { control: { type: 'text' } },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof TextareaControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ value, setValue ] = useState( '' );
+
+	return (
+		<TextareaControl
+			{ ...args }
+			value={ value }
+			onChange={ ( v ) => {
+				setValue( v );
+				onChange( v );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof TextareaControl > = Template.bind(
+	{}
+);
+Default.args = {
+	label: 'Text',
+	help: 'Enter some text',
+};

package/src/textarea-control/types.ts

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import type { TextareaHTMLAttributes } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type TextareaControlProps = Pick<
+	BaseControlProps,
+	'hideLabelFromVision' | 'help' | 'label'
+> & {
+	/**
+	 * A function that receives the new value of the textarea each time it
+	 * changes.
+	 */
+	onChange: ( value: string ) => void;
+	/**
+	 * The current value of the textarea.
+	 */
+	value: string;
+	/**
+	 * The number of rows the textarea should contain.
+	 *
+	 * @default 4
+	 */
+	rows?: TextareaHTMLAttributes< HTMLTextAreaElement >[ 'rows' ];
+};

package/src/toggle-control/index.js

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { isFunction } from 'lodash';
 import classnames from 'classnames';
 
 /**
@@ -32,7 +31,7 @@ export default function ToggleControl( {
 	let describedBy, helpLabel;
 	if ( help ) {
 		describedBy = id + '__help';
-		helpLabel = isFunction( help ) ? help( checked ) : help;
+		helpLabel = typeof help === 'function' ? help( checked ) : help;
 	}
 
 	return (

package/src/toggle-control/index.native.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { isFunction } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -16,7 +11,8 @@ const ToggleControl = memo(
 	( { label, checked, help, instanceId, className, onChange, ...props } ) => {
 		const id = `inspector-toggle-control-${ instanceId }`;
 
-		const helpLabel = help && isFunction( help ) ? help( checked ) : help;
+		const helpLabel =
+			help && typeof help === 'function' ? help( checked ) : help;
 
 		return (
 			<SwitchCell

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

@@ -36,10 +36,8 @@ function ToggleGroupControlBackdrop( {
 		}
 
 		const computeDimensions = () => {
-			const {
-				width: offsetWidth,
-				x,
-			} = targetNode.getBoundingClientRect();
+			const { width: offsetWidth, x } =
+				targetNode.getBoundingClientRect();
 
 			const { x: parentX } = containerNode.getBoundingClientRect();
 

package/src/toolbar/index.js

@@ -30,8 +30,7 @@ function Toolbar( { className, label, ...props }, ref ) {
 		deprecated( 'Using Toolbar without label prop', {
 			since: '5.6',
 			alternative: 'ToolbarGroup component',
-			link:
-				'https://developer.wordpress.org/block-editor/components/toolbar/',
+			link: 'https://developer.wordpress.org/block-editor/components/toolbar/',
 		} );
 		return <ToolbarGroup { ...props } className={ className } />;
 	}

package/src/tools-panel/tools-panel/hook.ts

@@ -165,10 +165,8 @@ export function useToolsPanel(
 	// in order to later determine if the panel display is empty and handle
 	// conditional display of a plus icon to indicate the presence of further
 	// menu items.
-	const [
-		areAllOptionalControlsHidden,
-		setAreAllOptionalControlsHidden,
-	] = useState( false );
+	const [ areAllOptionalControlsHidden, setAreAllOptionalControlsHidden ] =
+		useState( false );
 
 	useEffect( () => {
 		if (

package/src/tools-panel/tools-panel-header/hook.ts

@@ -33,11 +33,8 @@ export function useToolsPanelHeader(
 		return cx( styles.ToolsPanelHeading );
 	}, [ cx ] );
 
-	const {
-		menuItems,
-		hasMenuItems,
-		areAllOptionalControlsHidden,
-	} = useToolsPanelContext();
+	const { menuItems, hasMenuItems, areAllOptionalControlsHidden } =
+		useToolsPanelContext();
 
 	return {
 		...otherProps,

package/src/tooltip/index.js

@@ -65,6 +65,7 @@ const addPopoverToGrandchildren = ( {
 				aria-hidden="true"
 				animate={ false }
 				offset={ 12 }
+				__unstableShift
 			>
 				{ text }
 				<Shortcut

package/src/tree-grid/roving-tab-index-item.js

@@ -14,10 +14,8 @@ export default forwardRef( function RovingTabIndexItem(
 ) {
 	const localRef = useRef();
 	const ref = forwardedRef || localRef;
-	const {
-		lastFocusedElement,
-		setLastFocusedElement,
-	} = useRovingTabIndexContext();
+	const { lastFocusedElement, setLastFocusedElement } =
+		useRovingTabIndexContext();
 	let tabIndex;
 
 	if ( lastFocusedElement ) {

package/src/tree-grid/test/index.js

@@ -35,9 +35,8 @@ describe( 'TreeGrid', () => {
 	] );
 
 	beforeAll( () => {
-		window.Element.prototype.getClientRects = jest.fn(
-			mockedGetClientRects
-		);
+		window.Element.prototype.getClientRects =
+			jest.fn( mockedGetClientRects );
 	} );
 
 	afterAll( () => {

package/src/tree-select/README.md

@@ -80,12 +80,12 @@ A function that receives the id of the new node element that is being selected.
 
 The id of the currently selected node.
 
--   Type: `Object`
+-   Type: `string` | `string[]`
 -   Required: No
 
 ### tree
 
 An array containing the tree objects with the possible nodes the user can select.
 
--   Type: `String`
+-   Type: `Object[]`
 -   Required: No