@wordpress/components 19.16.0 → 19.17.0

package/src/box-control/all-input-control.js

@@ -3,8 +3,8 @@
  */
 import UnitControl from './unit-control';
 import {
-	ALL_SIDES,
 	LABELS,
+	applyValueToSides,
 	getAllValue,
 	isValuesMixed,
 	isValuesDefined,
@@ -32,34 +32,10 @@ export default function AllInputControl( {
 		onFocus( event, { side: 'all' } );
 	};
 
-	// Applies a value to an object representing top, right, bottom and left
-	// sides while taking into account any custom side configuration.
-	const applyValueToSides = ( currentValues, newValue ) => {
-		const newValues = { ...currentValues };
-
-		if ( sides?.length ) {
-			sides.forEach( ( side ) => {
-				if ( side === 'vertical' ) {
-					newValues.top = newValue;
-					newValues.bottom = newValue;
-				} else if ( side === 'horizontal' ) {
-					newValues.left = newValue;
-					newValues.right = newValue;
-				} else {
-					newValues[ side ] = newValue;
-				}
-			} );
-		} else {
-			ALL_SIDES.forEach( ( side ) => ( newValues[ side ] = newValue ) );
-		}
-
-		return newValues;
-	};
-
 	const handleOnChange = ( next ) => {
 		const isNumeric = ! isNaN( parseFloat( next ) );
 		const nextValue = isNumeric ? next : undefined;
-		const nextValues = applyValueToSides( values, nextValue );
+		const nextValues = applyValueToSides( values, nextValue, sides );
 
 		onChange( nextValues );
 	};
@@ -67,7 +43,7 @@ export default function AllInputControl( {
 	// Set selected unit so it can be used as fallback by unlinked controls
 	// when individual sides do not have a value containing a unit.
 	const handleOnUnitChange = ( unit ) => {
-		const newUnits = applyValueToSides( selectedUnits, unit );
+		const newUnits = applyValueToSides( selectedUnits, unit, sides );
 		setSelectedUnits( newUnits );
 	};
 

package/src/box-control/index.js

@@ -8,13 +8,13 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
+import { BaseControl } from '../base-control';
 import Button from '../button';
 import { FlexItem, FlexBlock } from '../flex';
 import AllInputControl from './all-input-control';
 import InputControls from './input-controls';
 import AxialInputControls from './axial-input-controls';
 import BoxControlIcon from './icon';
-import { Text } from '../text';
 import LinkedButton from './linked-button';
 import {
 	Root,
@@ -120,12 +120,9 @@ export default function BoxControl( {
 		<Root id={ id } role="group" aria-labelledby={ headingId }>
 			<Header className="component-box-control__header">
 				<FlexItem>
-					<Text
-						id={ headingId }
-						className="component-box-control__label"
-					>
+					<BaseControl.VisualLabel id={ headingId }>
 						{ label }
-					</Text>
+					</BaseControl.VisualLabel>
 				</FlexItem>
 				{ allowReset && (
 					<FlexItem>
@@ -173,3 +170,5 @@ export default function BoxControl( {
 		</Root>
 	);
 }
+
+export { applyValueToSides } from './utils';

package/src/box-control/styles/box-control-styles.js

@@ -8,7 +8,7 @@ import styled from '@emotion/styled';
  */
 import { Flex } from '../../flex';
 import BaseUnitControl from '../../unit-control';
-import { COLORS, rtl } from '../../utils';
+import { rtl } from '../../utils';
 
 export const Root = styled.div`
 	box-sizing: border-box;
@@ -18,7 +18,6 @@ export const Root = styled.div`
 `;
 
 export const Header = styled( Flex )`
-	color: ${ COLORS.ui.label };
 	margin-bottom: 8px;
 `;
 

package/src/box-control/utils.js

@@ -194,3 +194,35 @@ export function normalizeSides( sides ) {
 
 	return filteredSides;
 }
+
+/**
+ * Applies a value to an object representing top, right, bottom and left sides
+ * while taking into account any custom side configuration.
+ *
+ * @param {Object}        currentValues The current values for each side.
+ * @param {string|number} newValue      The value to apply to the sides object.
+ * @param {string[]}      sides         Array defining valid sides.
+ *
+ * @return {Object} Object containing the updated values for each side.
+ */
+export function applyValueToSides( currentValues, newValue, sides ) {
+	const newValues = { ...currentValues };
+
+	if ( sides?.length ) {
+		sides.forEach( ( side ) => {
+			if ( side === 'vertical' ) {
+				newValues.top = newValue;
+				newValues.bottom = newValue;
+			} else if ( side === 'horizontal' ) {
+				newValues.left = newValue;
+				newValues.right = newValue;
+			} else {
+				newValues[ side ] = newValue;
+			}
+		} );
+	} else {
+		ALL_SIDES.forEach( ( side ) => ( newValues[ side ] = newValue ) );
+	}
+
+	return newValues;
+}

package/src/color-picker/styles.ts

@@ -11,6 +11,7 @@ import InnerSelectControl from '../select-control';
 import InnerRangeControl from '../range-control';
 import { StyledField } from '../base-control/styles/base-control-styles';
 import { space } from '../ui/utils/space';
+import { boxSizingReset } from '../utils';
 import Button from '../button';
 import { Flex } from '../flex';
 import { HStack } from '../h-stack';
@@ -70,6 +71,8 @@ export const ColorInputWrapper = styled( Flex )`
 `;
 
 export const ColorfulWrapper = styled.div`
+	${ boxSizingReset };
+
 	width: 216px;
 
 	.react-colorful {

package/src/combobox-control/README.md

@@ -116,6 +116,13 @@ The current value of the input.
 -   Type: `mixed`
 -   Required: Yes
 
+#### __experimentalRenderItem
+
+Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the `item` key, the single option's data (directly from the array of data passed to the `options` prop).
+
+-   Type: `Function` - `( args: { item: object } ) => ReactNode`
+-   Required: No
+
 ## Related components
 
 -   Like this component, but without a search input, the `CustomSelectControl` component.

package/src/combobox-control/index.js

@@ -29,6 +29,7 @@ import BaseControl from '../base-control';
 import Button from '../button';
 import { FlexBlock, FlexItem } from '../flex';
 import withFocusOutside from '../higher-order/with-focus-outside';
+import { useControlledValue } from '../utils/hooks';
 
 const noop = () => {};
 
@@ -46,10 +47,10 @@ const DetectOutside = withFocusOutside(
 
 function ComboboxControl( {
 	__next36pxDefaultSize,
-	value,
+	value: valueProp,
 	label,
 	options,
-	onChange,
+	onChange: onChangeProp,
 	onFilterValueChange = noop,
 	hideLabelFromVision,
 	help,
@@ -58,7 +59,13 @@ function ComboboxControl( {
 	messages = {
 		selected: __( 'Item selected.' ),
 	},
+	__experimentalRenderItem,
 } ) {
+	const [ value, setValue ] = useControlledValue( {
+		value: valueProp,
+		onChange: onChangeProp,
+	} );
+
 	const currentOption = options.find( ( option ) => option.value === value );
 	const currentLabel = currentOption?.label ?? '';
 	// Use a custom prefix when generating the `instanceId` to avoid having
@@ -92,7 +99,7 @@ function ComboboxControl( {
 	}, [ inputValue, options, value ] );
 
 	const onSuggestionSelected = ( newSelectedSuggestion ) => {
-		onChange( newSelectedSuggestion.value );
+		setValue( newSelectedSuggestion.value );
 		speak( messages.selected, 'assertive' );
 		setSelectedSuggestion( newSelectedSuggestion );
 		setInputValue( '' );
@@ -172,7 +179,7 @@ function ComboboxControl( {
 	};
 
 	const handleOnReset = () => {
-		onChange( null );
+		setValue( null );
 		inputContainer.current.focus();
 	};
 
@@ -279,6 +286,9 @@ function ComboboxControl( {
 							onHover={ setSelectedSuggestion }
 							onSelect={ onSuggestionSelected }
 							scrollIntoView
+							__experimentalRenderItem={
+								__experimentalRenderItem
+							}
 						/>
 					) }
 				</div>

package/src/combobox-control/stories/index.js

@@ -266,7 +266,7 @@ const mapCountryOption = ( country ) => ( {
 
 const countryOptions = countries.map( mapCountryOption );
 
-function CountryCodeComboboxControl( args ) {
+function Template( args ) {
 	const [ value, setValue ] = useState( null );
 
 	return (
@@ -275,15 +275,59 @@ function CountryCodeComboboxControl( args ) {
 				{ ...args }
 				value={ value }
 				onChange={ setValue }
-				label="Select a country"
-				options={ countryOptions }
 			/>
 			<p>Value: { value }</p>
 		</>
 	);
 }
-export const _default = CountryCodeComboboxControl.bind( {} );
-_default.args = {
+export const Default = Template.bind( {} );
+Default.args = {
 	__next36pxDefaultSize: false,
 	allowReset: false,
+	label: 'Select a country',
+	options: countryOptions,
+};
+
+const authorOptions = [
+	{
+		value: 'parsley',
+		label: 'Parsley Montana',
+		age: 48,
+		country: 'Germany',
+	},
+	{
+		value: 'cabbage',
+		label: 'Cabbage New York',
+		age: 44,
+		country: 'France',
+	},
+	{
+		value: 'jake',
+		label: 'Jake Weary',
+		age: 41,
+		country: 'United Kingdom',
+	},
+];
+
+/**
+ * The rendered output of each suggestion can be customized by passing a
+ * render function to the `__experimentalRenderItem` prop. (This is still an experimental feature
+ * and is subject to change.)
+ */
+export const WithCustomRenderItem = Template.bind( {} );
+WithCustomRenderItem.args = {
+	...Default.args,
+	label: 'Select an author',
+	options: authorOptions,
+	__experimentalRenderItem: ( { item } ) => {
+		const { label, age, country } = item;
+		return (
+			<div>
+				<div style={ { marginBottom: '0.2rem' } }>{ label }</div>
+				<small>
+					Age: { age }, Country: { country }
+				</small>
+			</div>
+		);
+	},
 };

package/src/custom-gradient-picker/style.scss

@@ -106,15 +106,3 @@ $components-custom-gradient-picker__padding: $grid-unit-20; // 48px container, 1
 		}
 	}
 }
-
-// All these styles should be made generic and changed on the inputs for all components.
-.components-custom-gradient-picker {
-	.components-input-control__label {
-		line-height: 1;
-	}
-	label {
-		text-transform: uppercase;
-		font-size: 11px;
-		font-weight: 500;
-	}
-}

package/src/custom-select-control/index.js

@@ -17,6 +17,7 @@ import { useCallback, useState } from '@wordpress/element';
 import { VisuallyHidden } from '../';
 import { Select as SelectControlSelect } from '../select-control/styles/select-control-styles';
 import InputBase from '../input-control/input-base';
+import { StyledLabel } from '../base-control/styles/base-control-styles';
 
 const itemToString = ( item ) => item?.name;
 // This is needed so that in Windows, where
@@ -138,13 +139,13 @@ export default function CustomSelectControl( {
 				</VisuallyHidden>
 			) : (
 				/* eslint-disable-next-line jsx-a11y/label-has-associated-control, jsx-a11y/label-has-for */
-				<label
+				<StyledLabel
 					{ ...getLabelProps( {
 						className: 'components-custom-select-control__label',
 					} ) }
 				>
 					{ label }
-				</label>
+				</StyledLabel>
 			) }
 			<InputBase
 				isFocused={ isOpen || isFocused }

package/src/custom-select-control/style.scss

@@ -1,10 +1,6 @@
 .components-custom-select-control {
 	position: relative;
-}
-
-.components-custom-select-control__label {
-	display: block;
-	margin-bottom: $grid-unit-10;
+	font-size: $default-font-size;
 }
 
 .components-custom-select-control__button {

package/src/date-time/time/index.tsx

@@ -12,6 +12,7 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
+import BaseControl from '../../base-control';
 import Button from '../../button';
 import ButtonGroup from '../../button-group';
 import TimeZone from './timezone';
@@ -19,7 +20,6 @@ import type { TimePickerProps } from '../types';
 import {
 	Wrapper,
 	Fieldset,
-	Legend,
 	HoursInput,
 	TimeSeparator,
 	MinutesInput,
@@ -220,11 +220,12 @@ export function TimePicker( {
 			className="components-datetime__time" // Unused, for backwards compatibility.
 		>
 			<Fieldset>
-				<Legend
+				<BaseControl.VisualLabel
+					as="legend"
 					className="components-datetime__time-legend" // Unused, for backwards compatibility.
 				>
 					{ __( 'Time' ) }
-				</Legend>
+				</BaseControl.VisualLabel>
 				<HStack
 					className="components-datetime__time-wrapper" // Unused, for backwards compatibility.
 				>
@@ -309,11 +310,12 @@ export function TimePicker( {
 				</HStack>
 			</Fieldset>
 			<Fieldset>
-				<Legend
+				<BaseControl.VisualLabel
+					as="legend"
 					className="components-datetime__time-legend" // Unused, for backwards compatibility.
 				>
 					{ __( 'Date' ) }
-				</Legend>
+				</BaseControl.VisualLabel>
 				<HStack
 					className="components-datetime__time-wrapper" // Unused, for backwards compatibility.
 				>

package/src/date-time/time/styles.ts

@@ -17,7 +17,9 @@ import NumberControl from '../../number-control';
 import SelectControl from '../../select-control';
 import { Select } from '../../select-control/styles/select-control-styles';
 
-export const Wrapper = styled.div``;
+export const Wrapper = styled.div`
+	font-size: ${ CONFIG.fontSize };
+`;
 
 export const Fieldset = styled.fieldset`
 	border: 0;
@@ -29,11 +31,6 @@ export const Fieldset = styled.fieldset`
 	}
 `;
 
-export const Legend = styled.legend`
-	margin-bottom: ${ space( 2 ) };
-	padding: 0;
-`;
-
 export const TimeWrapper = styled.div`
 	direction: ltr;
 	display: flex;

package/src/external-link/index.tsx

@@ -38,12 +38,22 @@ function UnforwardedExternalLink(
 		),
 	].join( ' ' );
 	const classes = classnames( 'components-external-link', className );
+	/* Anchor links are percieved as external links.
+	This constant helps check for on page anchor links,
+	to prevent them from being opened in the editor. */
+	const isInternalAnchor = !! href?.startsWith( '#' );
+
 	return (
 		/* eslint-disable react/jsx-no-target-blank */
 		<a
 			{ ...additionalProps }
 			className={ classes }
 			href={ href }
+			onClick={
+				isInternalAnchor
+					? ( event ) => event.preventDefault()
+					: undefined
+			}
 			target="_blank"
 			rel={ optimizedRel }
 			ref={ ref }

package/src/flex/flex/README.md

@@ -25,38 +25,44 @@ function Example() {
 
 ## Props
 
-##### align
-
-**Type**: `CSSProperties['alignItems']`
+### `align`: `CSSProperties['alignItems']`
 
 Aligns children using CSS Flexbox `align-items`. Vertically aligns content if the `direction` is `row`, or horizontally aligns content if the `direction` is `column`.
 
-##### direction
+-   Required: No
+-   Default: `center`
 
-**Type**: `[ResponsiveCSSValue<CSSProperties['flexDirection']>]`
+### `direction`: `ResponsiveCSSValue<CSSProperties['flexDirection']>`
 
 The direction flow of the children content can be adjusted with `direction`. `column` will align children vertically and `row` will align children horizontally.
 
-##### expanded
+-   Required: No
+-   Default: `row`
 
-**Type**: `[boolean]`
+### `expanded`: `boolean`
 
 Expands to the maximum available width (if horizontal) or height (if vertical).
 
-##### gap
+-   Required: No
+-   Default: `true`
 
-**Type**: `[number | string]`
+### `gap`: `number`
 
 Spacing in between each child can be adjusted by using `gap`. The value of `gap` works as a multiplier to the library's grid system (base of `4px`).
 
-##### justify
+-   Required: No
+-   Default: `2`
 
-**Type**: `[CSSProperties['justifyContent']]`
+##### `justify`: `CSSProperties['justifyContent']`
 
 Horizontally aligns content if the `direction` is `row`, or vertically aligns content if the `direction` is `column`.
 
-##### wrap
+-   Required: No
+-   Default: `space-between`
 
-**Type**: `[boolean]`
+##### `wrap`: `boolean`
 
 Determines if children should wrap.
+
+-   Required: No
+-   Default: `false`

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

@@ -1,16 +1,21 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../../ui/context';
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
 import { useFlex } from './hook';
 import { FlexContext } from './../context';
 import { View } from '../../view';
+import type { FlexProps } from '../types';
 
-/**
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                                       forwardedRef
- */
-function Flex( props, forwardedRef ) {
+function UnconnectedFlex(
+	props: WordPressComponentProps< FlexProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const { children, isColumn, ...otherProps } = useFlex( props );
 
 	return (
@@ -29,9 +34,9 @@ function Flex( props, forwardedRef ) {
  * horizontally or vertically. `Flex` powers components like `HStack` and
  * `VStack`.
  *
- * `Flex` is used with any of it's two sub-components, `FlexItem` and `FlexBlock`.
+ * `Flex` is used with any of its two sub-components, `FlexItem` and
+ * `FlexBlock`.
  *
- * @example
  * ```jsx
  * import { Flex, FlexBlock, FlexItem } from '@wordpress/components';
  *
@@ -49,6 +54,6 @@ function Flex( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedFlex = contextConnect( Flex, 'Flex' );
+export const Flex = contextConnect( UnconnectedFlex, 'Flex' );
 
-export default ConnectedFlex;
+export default Flex;

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { css } from '@emotion/react';
+import { css, SerializedStyles } from '@emotion/react';
 
 /**
  * WordPress dependencies
@@ -12,18 +12,18 @@ import deprecated from '@wordpress/deprecated';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import { useResponsiveValue } from '../../ui/utils/use-responsive-value';
 import { space } from '../../ui/utils/space';
 import * as styles from '../styles';
 import { useCx, rtl } from '../../utils';
+import type { FlexProps } from '../types';
+
+function useDeprecatedProps(
+	props: WordPressComponentProps< FlexProps, 'div' >
+): WordPressComponentProps< FlexProps, 'div' > {
+	const { isReversed, ...otherProps } = props;
 
-/**
- *
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} props
- * @return {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} Props with the deprecated props removed.
- */
-function useDeprecatedProps( { isReversed, ...otherProps } ) {
 	if ( typeof isReversed !== 'undefined' ) {
 		deprecated( 'Flex isReversed', {
 			alternative: 'Flex direction="row-reverse" or "column-reverse"',
@@ -38,10 +38,7 @@ function useDeprecatedProps( { isReversed, ...otherProps } ) {
 	return otherProps;
 }
 
-/**
- * @param {import('../../ui/context').WordPressComponentProps<import('../types').FlexProps, 'div'>} props
- */
-export function useFlex( props ) {
+export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 	const {
 		align = 'center',
 		className,
@@ -67,7 +64,11 @@ export function useFlex( props ) {
 	const rtlWatchResult = rtl.watch();
 
 	const classes = useMemo( () => {
-		const sx = {};
+		const sx: {
+			Base?: SerializedStyles;
+			Items?: SerializedStyles;
+			WrapItems?: SerializedStyles;
+		} = {};
 
 		sx.Base = css( {
 			alignItems: isColumn ? 'normal' : align,

package/src/flex/flex-block/README.md

@@ -8,8 +8,8 @@ See [`flex/README.md#usage`](/packages/components/src/flex/README.md#usage) for
 
 ## Props
 
-### display
-
-**Type**: `[CSSProperties['display']]`
+### `display`: `CSSProperties['display']`
 
 The CSS display property of `FlexBlock`.
+
+-   Required: No