@wordpress/components 19.9.0 → 19.12.0

package/src/select-control/styles/select-control-styles.ts

@@ -8,11 +8,12 @@ import styled from '@emotion/styled';
  * Internal dependencies
  */
 import { COLORS, rtl } from '../../utils';
-import type { Size } from '../types';
+import type { SelectControlProps } from '../types';
 
-interface SelectProps {
-	disabled?: boolean;
-	selectSize?: Size;
+interface SelectProps extends Pick< SelectControlProps, 'disabled' > {
+	// Using `selectSize` instead of `size` to avoid a type conflict with the
+	// `size` HTML attribute of the `select` element.
+	selectSize?: SelectControlProps[ 'size' ];
 }
 
 const disabledStyles = ( { disabled }: SelectProps ) => {
@@ -23,14 +24,14 @@ const disabledStyles = ( { disabled }: SelectProps ) => {
 	} );
 };
 
-const fontSizeStyles = ( { selectSize }: SelectProps ) => {
+const fontSizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 	const sizes = {
 		default: '13px',
 		small: '11px',
 		'__unstable-large': '13px',
 	};
 
-	const fontSize = sizes[ selectSize as Size ];
+	const fontSize = sizes[ selectSize ];
 	const fontSizeMobile = '16px';
 
 	if ( ! fontSize ) return '';
@@ -44,26 +45,29 @@ const fontSizeStyles = ( { selectSize }: SelectProps ) => {
 	`;
 };
 
-const sizeStyles = ( { selectSize }: SelectProps ) => {
+const sizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 	const sizes = {
 		default: {
 			height: 30,
-			lineHeight: 1,
 			minHeight: 30,
+			paddingTop: 0,
+			paddingBottom: 0,
 		},
 		small: {
 			height: 24,
-			lineHeight: 1,
 			minHeight: 24,
+			paddingTop: 0,
+			paddingBottom: 0,
 		},
 		'__unstable-large': {
 			height: 40,
-			lineHeight: 1,
 			minHeight: 40,
+			paddingTop: 0,
+			paddingBottom: 0,
 		},
 	};
 
-	const style = sizes[ selectSize as Size ] || sizes.default;
+	const style = sizes[ selectSize ];
 
 	return css( style );
 };

package/src/select-control/test/{select-control.js → select-control.tsx}

@@ -32,7 +32,7 @@ describe( 'SelectControl', () => {
 
 		expect( screen.getByText( 'Option 1' ) ).toBeInTheDocument();
 
-		const selectElement = screen.queryByLabelText( 'Select' );
+		const selectElement = screen.getByLabelText( 'Select' );
 
 		fireEvent.change( selectElement, {
 			target: { value: 'option-group-option-1' },
@@ -68,7 +68,7 @@ describe( 'SelectControl', () => {
 
 		expect( screen.getByText( 'Option 1' ) ).toBeInTheDocument();
 
-		const selectElement = screen.queryByLabelText( 'Select' );
+		const selectElement = screen.getByLabelText( 'Select' );
 
 		fireEvent.change( selectElement, {
 			target: { value: 'option-2' },

package/src/select-control/types.ts

@@ -1 +1,66 @@
-export type Size = 'default' | 'small' | '__unstable-large';
+/**
+ * External dependencies
+ */
+import type { ChangeEvent, FocusEvent, ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { InputBaseProps } from '../input-control/types';
+import type { BaseControlProps } from '../base-control/types';
+
+export interface SelectControlProps
+	extends Pick<
+			InputBaseProps,
+			| 'disabled'
+			| 'hideLabelFromVision'
+			| 'label'
+			| 'labelPosition'
+			| 'prefix'
+			| 'size'
+			| 'suffix'
+		>,
+		Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > {
+	/**
+	 * If this property is added, multiple values can be selected. The value passed should be an array.
+	 *
+	 * @default false
+	 */
+	multiple?: boolean;
+	onBlur?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+	onFocus?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+	/**
+	 * A function that receives the value of the new option that is being selected as input.
+	 *
+	 * If `multiple` is `true`, the value received is an array of the selected value.
+	 * Otherwise, the value received is a single value with the new selected value.
+	 */
+	onChange?: (
+		value: string | string[],
+		extra?: { event?: ChangeEvent< HTMLSelectElement > }
+	) => void;
+	options?: {
+		/**
+		 * The label to be shown to the user.
+		 */
+		label: string;
+		/**
+		 * The internal value used to choose the selected value.
+		 * This is also the value passed to `onChange` when the option is selected.
+		 */
+		value: string;
+		id?: string;
+		/**
+		 * Whether or not the option should have the disabled attribute.
+		 *
+		 * @default false
+		 */
+		disabled?: boolean;
+	}[];
+	value?: string | string[];
+	/**
+	 * As an alternative to the `options` prop, `optgroup`s and `options` can be
+	 * passed in as `children` for more customizability.
+	 */
+	children?: ReactNode;
+}

package/src/slot-fill/README.md

@@ -2,7 +2,7 @@
 
 Slot and Fill are a pair of components which enable developers to render elsewhere in a React element tree, a pattern often referred to as "portal" rendering. It is a pattern for component extensibility, where a single Slot may be occupied by an indeterminate number of Fills elsewhere in the application.
 
-Slot Fill is heavily inspired by the [`react-slot-fill` library](https://github.com/camwest/react-slot-fill), but uses React's own portal rendering API, exposed as an unstable API in React 16 and slated to be promoted to a stable API in React 17.
+Slot Fill is heavily inspired by the [`react-slot-fill` library](https://github.com/camwest/react-slot-fill), but uses React's own portal rendering API.
 
 ## Usage
 

package/src/spacer/hook.ts

@@ -8,7 +8,7 @@ import { css } from '@emotion/react';
  */
 import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { space } from '../ui/utils/space';
-import { useCx } from '../utils/hooks/use-cx';
+import { rtl, useCx } from '../utils';
 import type { Props } from './types';
 
 const isDefined = < T >( o: T ): o is Exclude< T, null | undefined > =>
@@ -60,13 +60,13 @@ export function useSpacer( props: WordPressComponentProps< Props, 'div' > ) {
 				margin-bottom: ${ space( marginBottom ) };
 			`,
 		isDefined( marginLeft ) &&
-			css`
-				margin-left: ${ space( marginLeft ) };
-			`,
+			rtl( {
+				marginLeft: space( marginLeft ),
+			} )(),
 		isDefined( marginRight ) &&
-			css`
-				margin-right: ${ space( marginRight ) };
-			`,
+			rtl( {
+				marginRight: space( marginRight ),
+			} )(),
 		isDefined( padding ) &&
 			css`
 				padding: ${ space( padding ) };
@@ -90,13 +90,13 @@ export function useSpacer( props: WordPressComponentProps< Props, 'div' > ) {
 				padding-bottom: ${ space( paddingBottom ) };
 			`,
 		isDefined( paddingLeft ) &&
-			css`
-				padding-left: ${ space( paddingLeft ) };
-			`,
+			rtl( {
+				paddingLeft: space( paddingLeft ),
+			} )(),
 		isDefined( paddingRight ) &&
-			css`
-				padding-right: ${ space( paddingRight ) };
-			`,
+			rtl( {
+				paddingRight: space( paddingRight ),
+			} )(),
 		className
 	);
 

package/src/surface/README.md

@@ -13,7 +13,7 @@ In the example below, notice how the `Surface` renders in white (or dark gray if
 ```jsx
 import {
 	__experimentalSurface as Surface,
-	__experimentalText as Text
+	__experimentalText as Text,
 } from '@wordpress/components';
 
 function Example() {
@@ -27,46 +27,46 @@ function Example() {
 
 ## Props
 
-### `backgroundSize`: number
+### `backgroundSize`: `number`
 
-- Required: No
-- Default: `12`
+-   Required: No
+-   Default: `12`
 
 Determines the grid size for "dotted" and "grid" variants.
 
 ### `borderBottom`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a bottom border.
 
 ### `borderLeft`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a left border.
 
 ### `borderRight`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a right border.
 
 ### `borderTop`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a top border.
 
 ### `variant`: `string`
 
-- Required: No
-- Default: `false`
-- Allowed values: `primary`, `secondary`, `tertiary`, `dotted`, `grid`
+-   Required: No
+-   Default: `false`
+-   Allowed values: `primary`, `secondary`, `tertiary`, `dotted`, `grid`
 
 Modifies the background color of `Surface`.
 

package/src/surface/{component.js → component.tsx}

@@ -1,15 +1,21 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
 import { contextConnect } from '../ui/context';
 import { View } from '../view';
 import { useSurface } from './hook';
+import type { SurfaceProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function Surface( props, forwardedRef ) {
+function UnconnectedSurface(
+	props: WordPressComponentProps< SurfaceProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const surfaceProps = useSurface( props );
 
 	return <View { ...surfaceProps } ref={ forwardedRef } />;
@@ -35,6 +41,6 @@ function Surface( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedSurface = contextConnect( Surface, 'Surface' );
+export const Surface = contextConnect( UnconnectedSurface, 'Surface' );
 
-export default ConnectedSurface;
+export default Surface;

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

@@ -9,11 +9,12 @@ import { useMemo } from '@wordpress/element';
 import { useContextSystem } from '../ui/context';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
+import type { SurfaceProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useSurface( props ) {
+export function useSurface(
+	props: WordPressComponentProps< SurfaceProps, 'div' >
+) {
 	const {
 		backgroundSize = 12,
 		borderBottom = false,
@@ -28,14 +29,14 @@ export function useSurface( props ) {
 	const cx = useCx();
 
 	const classes = useMemo( () => {
-		const sx = {};
-
-		sx.borders = styles.getBorders( {
-			borderBottom,
-			borderLeft,
-			borderRight,
-			borderTop,
-		} );
+		const sx = {
+			borders: styles.getBorders( {
+				borderBottom,
+				borderLeft,
+				borderRight,
+				borderTop,
+			} ),
+		};
 
 		return cx(
 			styles.Surface,

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/style.scss

@@ -59,6 +59,6 @@
 	}
 
 	&.is-active:focus {
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color), inset 0 0 -$border-width-tab 0 0 var(--wp-admin-theme-color);
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color), inset 0 -#{$border-width-tab * 2} 0 0 var(--wp-admin-theme-color);
 	}
 }

package/src/text-control/index.tsx

@@ -0,0 +1,84 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent, ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import type { WordPressComponentProps } from '../ui/context';
+import type { TextControlProps } from './types';
+
+function UnforwardedTextControl(
+	props: WordPressComponentProps< TextControlProps, 'input', false >,
+	ref: ForwardedRef< HTMLInputElement >
+) {
+	const {
+		label,
+		hideLabelFromVision,
+		value,
+		help,
+		className,
+		onChange,
+		type = 'text',
+		...additionalProps
+	} = props;
+	const instanceId = useInstanceId( TextControl );
+	const id = `inspector-text-control-${ instanceId }`;
+	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
+		onChange( event.target.value );
+
+	return (
+		<BaseControl
+			label={ label }
+			hideLabelFromVision={ hideLabelFromVision }
+			id={ id }
+			help={ help }
+			className={ className }
+		>
+			<input
+				className="components-text-control__input"
+				type={ type }
+				id={ id }
+				value={ value }
+				onChange={ onChangeValue }
+				aria-describedby={ !! help ? id + '__help' : undefined }
+				ref={ ref }
+				{ ...additionalProps }
+			/>
+		</BaseControl>
+	);
+}
+
+/**
+ * TextControl components let users enter and edit text.
+ *
+ *
+ * @example
+ * ```jsx
+ * import { TextControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyTextControl = () => {
+ *   const [ className, setClassName ] = useState( '' );
+ *
+ *   return (
+ *     <TextControl
+ *       label="Additional CSS Class"
+ *       value={ className }
+ *       onChange={ ( value ) => setClassName( value ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export const TextControl = forwardRef( UnforwardedTextControl );
+
+export default TextControl;