@wordpress/components 19.13.0 → 19.16.0

package/src/h-stack/stories/index.tsx

@@ -0,0 +1,92 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { HStack } from '..';
+
+const ALIGNMENTS = {
+	top: 'top',
+	topLeft: 'topLeft',
+	topRight: 'topRight',
+	left: 'left',
+	center: 'center',
+	right: 'right',
+	bottom: 'bottom',
+	bottomLeft: 'bottomLeft',
+	bottomRight: 'bottomRight',
+	edge: 'edge',
+	stretch: 'stretch',
+};
+
+const DIRECTIONS = {
+	row: 'row',
+	column: 'column',
+	responsive: [ 'column', 'row' ],
+};
+
+const JUSTIFICATIONS = {
+	'space-around': 'space-around',
+	'space-between': 'space-between',
+	'space-evenly': 'space-evenly',
+	stretch: 'stretch',
+	center: 'center',
+	end: 'end',
+	'flex-end': 'flex-end',
+	'flex-start': 'flex-start',
+	start: 'start',
+};
+
+const meta: ComponentMeta< typeof HStack > = {
+	component: HStack,
+	title: 'Components (Experimental)/HStack',
+	argTypes: {
+		as: {
+			control: { type: null },
+		},
+		children: {
+			control: { type: null },
+		},
+		alignment: {
+			control: { type: 'select' },
+			options: Object.keys( ALIGNMENTS ),
+			mapping: ALIGNMENTS,
+		},
+		direction: {
+			control: { type: 'select' },
+			options: Object.keys( DIRECTIONS ),
+			mapping: DIRECTIONS,
+		},
+		justify: {
+			control: { type: 'select' },
+			options: Object.keys( JUSTIFICATIONS ),
+			mapping: JUSTIFICATIONS,
+		},
+		spacing: {
+			control: { type: 'text' },
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof HStack > = ( args ) => (
+	<HStack { ...args } style={ { background: '#eee', minHeight: '3rem' } }>
+		{ [ 'One', 'Two', 'Three', 'Four', 'Five' ].map( ( text ) => (
+			<View key={ text } style={ { background: '#b9f9ff' } }>
+				{ text }
+			</View>
+		) ) }
+	</HStack>
+);
+
+export const Default: ComponentStory< typeof HStack > = Template.bind( {} );
+Default.args = {
+	spacing: '3',
+};

package/src/h-stack/{utils.js → utils.ts}

@@ -1,10 +1,15 @@
 /**
  * External dependencies
  */
-import { isNil } from 'lodash';
+import type { CSSProperties } from 'react';
+/**
+ * Internal dependencies
+ */
+import type { FlexDirection } from '../flex/types';
+import type { HStackAlignment, AlignmentProps, Alignments } from './types';
+import { isValueDefined } from '../utils/values';
 
-/** @type {import('./types').Alignments} */
-const ALIGNMENTS = {
+const H_ALIGNMENTS: Alignments = {
 	bottom: { align: 'flex-end', justify: 'center' },
 	bottomLeft: { align: 'flex-start', justify: 'flex-end' },
 	bottomRight: { align: 'flex-end', justify: 'flex-end' },
@@ -18,8 +23,7 @@ const ALIGNMENTS = {
 	topRight: { align: 'flex-start', justify: 'flex-end' },
 };
 
-/** @type {import('./types').Alignments} */
-const V_ALIGNMENTS = {
+const V_ALIGNMENTS: Alignments = {
 	bottom: { justify: 'flex-end', align: 'center' },
 	bottomLeft: { justify: 'flex-start', align: 'flex-end' },
 	bottomRight: { justify: 'flex-end', align: 'flex-end' },
@@ -33,23 +37,19 @@ const V_ALIGNMENTS = {
 	topRight: { justify: 'flex-start', align: 'flex-end' },
 };
 
-/* eslint-disable jsdoc/valid-types */
-/**
- * @param {import('./types').HStackAlignment | import('react').CSSProperties[ 'alignItems' ]} alignment         Where to align.
- * @param {import('../flex/types').FlexDirection}                                             [direction='row'] Direction to align.
- * @return {import('./types').AlignmentProps} Alignment props.
- */
-/* eslint-enable jsdoc/valid-types */
-export function getAlignmentProps( alignment, direction = 'row' ) {
-	if ( isNil( alignment ) ) {
+export function getAlignmentProps(
+	alignment: HStackAlignment | CSSProperties[ 'alignItems' ],
+	direction: FlexDirection = 'row'
+): AlignmentProps {
+	if ( ! isValueDefined( alignment ) ) {
 		return {};
 	}
 	const isVertical = direction === 'column';
-	const props = isVertical ? V_ALIGNMENTS : ALIGNMENTS;
+	const props = isVertical ? V_ALIGNMENTS : H_ALIGNMENTS;
 
 	const alignmentProps =
 		alignment in props
-			? props[ /** @type {keyof typeof ALIGNMENTS} */ ( alignment ) ]
+			? props[ alignment as keyof typeof props ]
 			: { align: alignment };
 
 	return alignmentProps;

package/src/heading/README.md

@@ -20,8 +20,9 @@ function Example() {
 
 `Heading` uses `Text` underneath, so we have access to all of `Text`'s props except for `size` which is replaced by `level`. For a complete list of those props, check out [`Text`](/packages/components/src/text/README.md#props).
 
-##### level
-
-**Type**: `1 | 2 | 3 | 4 | 5 | 6`
+##### `level`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 
 Passing any of the heading levels to `level` will both render the correct typographic text size as well as the semantic element corresponding to the level (`h1` for `1` for example).
+
+-   Required: No
+-   Default: `2`

package/src/heading/component.tsx

@@ -8,7 +8,8 @@ import type { ForwardedRef } from 'react';
  */
 import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
-import { useHeading, HeadingProps } from './hook';
+import { useHeading } from './hook';
+import type { HeadingProps } from './types';
 
 function UnconnectedHeading(
 	props: WordPressComponentProps< HeadingProps, 'h1' >,
@@ -22,7 +23,6 @@ function UnconnectedHeading(
 /**
  * `Heading` renders headings and titles using the library's typography system.
  *
- * @example
  * ```jsx
  * import { __experimentalHeading as Heading } from "@wordpress/components";
  *

package/src/heading/hook.ts

@@ -2,51 +2,10 @@
  * Internal dependencies
  */
 import { useContextSystem, WordPressComponentProps } from '../ui/context';
-import type { Props as TextProps } from '../text/types';
 import { useText } from '../text';
 import { getHeadingFontSize } from '../ui/utils/font-size';
 import { CONFIG, COLORS } from '../utils';
-
-export type HeadingSize =
-	| 1
-	| 2
-	| 3
-	| 4
-	| 5
-	| 6
-	| '1'
-	| '2'
-	| '3'
-	| '4'
-	| '5'
-	| '6';
-
-export interface HeadingProps extends Omit< TextProps, 'size' > {
-	/**
-	 * `Heading` will typically render the sizes `1`, `2`, `3`, `4`, `5`, or `6`, which map to `h1`-`h6`.
-	 *
-	 * @default 2
-	 *
-	 * @example
-	 * ```jsx
-	 * import { __experimentalHeading as Heading } from `@wordpress/components`
-	 *
-	 * function Example() {
-	 *   return (
-	 *     <div>
-	 *       <Heading level="1">Code is Poetry</Heading>
-	 *       <Heading level="2">Code is Poetry</Heading>
-	 *       <Heading level="3">Code is Poetry</Heading>
-	 *       <Heading level="4">Code is Poetry</Heading>
-	 *       <Heading level="5">Code is Poetry</Heading>
-	 *       <Heading level="6">Code is Poetry</Heading>
-	 *     </div>
-	 *   );
-	 * }
-	 * ```
-	 */
-	level: HeadingSize;
-}
+import type { HeadingProps } from './types';
 
 export function useHeading(
 	props: WordPressComponentProps< HeadingProps, 'h1' >

package/src/heading/stories/index.tsx

@@ -19,7 +19,11 @@ const meta: ComponentMeta< typeof Heading > = {
 		letterSpacing: { control: { type: 'text' } },
 		lineHeight: { control: { type: 'text' } },
 		optimizeReadabilityFor: { control: { type: 'color' } },
-		variant: { control: { type: 'radio' }, options: [ 'muted' ] },
+		variant: {
+			control: { type: 'radio' },
+			options: [ 'undefined', 'muted' ],
+			mapping: { undefined, muted: 'muted' },
+		},
 		weight: { control: { type: 'text' } },
 	},
 	parameters: {

package/src/heading/test/index.tsx

@@ -0,0 +1,68 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { Heading } from '../';
+
+describe( 'props', () => {
+	test( 'should render correctly', () => {
+		render( <Heading>Code is Poetry</Heading> );
+		expect( screen.getByRole( 'heading' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render level as a number', () => {
+		render( <Heading>Code is Poetry</Heading> );
+		render( <Heading level={ 4 }>Code is Poetry</Heading> );
+		expect(
+			screen.getByRole( 'heading', { level: 4 } )
+		).toMatchStyleDiffSnapshot(
+			screen.getByRole( 'heading', { level: 2 } )
+		);
+	} );
+
+	test( 'should render level as a string', () => {
+		render( <Heading>Code is Poetry</Heading> );
+		render( <Heading level="4">Code is Poetry</Heading> );
+		expect(
+			screen.getByRole( 'heading', { level: 4 } )
+		).toMatchStyleDiffSnapshot(
+			screen.getByRole( 'heading', { level: 2 } )
+		);
+	} );
+
+	test( 'should allow as prop', () => {
+		render(
+			<Heading level="1" as="span">
+				Code is Poetry
+			</Heading>
+		);
+		expect( screen.getByRole( 'heading' ).tagName ).toBe( 'SPAN' );
+	} );
+
+	test( 'should render a11y props when not using a semantic element', () => {
+		render(
+			<Heading level="3" as="div">
+				Code is Poetry
+			</Heading>
+		);
+		expect(
+			screen.getByRole( 'heading', { level: 3 } )
+		).toBeInTheDocument();
+	} );
+
+	test( 'should not render a11y props when using a semantic element', () => {
+		render(
+			<Heading level="1" as="h4">
+				Code is Poetry
+			</Heading>
+		);
+		expect( screen.getByRole( 'heading' ) ).not.toHaveAttribute( 'role' );
+		expect( screen.getByRole( 'heading' ) ).not.toHaveAttribute(
+			'aria-level'
+		);
+	} );
+} );

package/src/heading/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal dependencies
+ */
+import type { Props as TextProps } from '../text/types';
+
+export type HeadingSize =
+	| 1
+	| 2
+	| 3
+	| 4
+	| 5
+	| 6
+	| '1'
+	| '2'
+	| '3'
+	| '4'
+	| '5'
+	| '6';
+
+export type HeadingProps = Omit< TextProps, 'size' > & {
+	/**
+	 * Passing any of the heading levels to `level` will both render the correct
+	 * typographic text size as well as the semantic element corresponding to
+	 * the level (`h1` for `1` for example).
+	 *
+	 * @default 2
+	 */
+	level?: HeadingSize;
+};

package/src/higher-order/navigate-regions/README.md

@@ -1,6 +1,6 @@
 # navigateRegions
 
-`navigateRegions` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html) adding keyboard navigation to switch between the different DOM elements marked as "regions" (role="region"). These regions should be focusable (By adding a tabIndex attribute for example). For better accessibility, these elements must be properly labelled to briefly describe the purpose of the content in the region. For more details, see "ARIA landmarks" in the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria/).
+`navigateRegions` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html) adding keyboard navigation to switch between the different DOM elements marked as "regions" (role="region"). These regions should be focusable (By adding a tabIndex attribute for example). For better accessibility, these elements must be properly labelled to briefly describe the purpose of the content in the region. For more details, see "Landmark Roles" in the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria/) and "Landmark Regions" in the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/).
 
 ## Example:
 
@@ -21,3 +21,6 @@ const MyComponentWithNavigateRegions = navigateRegions( () => (
 	</div>
 ) );
 ```
+
+## Notes:
+It's important to note that an ARIA `role="region"` is an ARIA landmark role. It should be reserved for sections of content sufficiently important to have it listed in a summary of the page. Only use this ARIA role for the main sections of a page. All perceivable content should reside in a semantically meaningful landmark in order that content is not missed by the user.

package/src/icon/index.tsx

@@ -20,7 +20,7 @@ import { SVG } from '@wordpress/primitives';
 import Dashicon from '../dashicon';
 import type { IconKey as DashiconIconKey } from '../dashicon/types';
 
-type IconType< P > = DashiconIconKey | ComponentType< P > | JSX.Element;
+export type IconType< P > = DashiconIconKey | ComponentType< P > | JSX.Element;
 
 interface BaseProps< P > {
 	/**

package/src/index.js

@@ -66,6 +66,7 @@ export { default as Draggable } from './draggable';
 export { default as DropZone } from './drop-zone';
 export { default as DropZoneProvider } from './drop-zone/provider';
 export { default as Dropdown } from './dropdown';
+export { default as __experimentalDropdownContentWrapper } from './dropdown/dropdown-content-wrapper';
 export { default as DropdownMenu } from './dropdown-menu';
 export { DuotoneSwatch, DuotonePicker } from './duotone-picker';
 export { Elevation as __experimentalElevation } from './elevation';
@@ -91,6 +92,8 @@ export {
 	Item as __experimentalItem,
 } from './item-group';
 export { default as __experimentalInputControl } from './input-control';
+export { default as __experimentalInputControlPrefixWrapper } from './input-control/input-prefix-wrapper';
+export { default as __experimentalInputControlSuffixWrapper } from './input-control/input-suffix-wrapper';
 export { default as KeyboardShortcuts } from './keyboard-shortcuts';
 export { default as MenuGroup } from './menu-group';
 export { default as MenuItem } from './menu-item';

package/src/input-control/index.tsx

@@ -16,6 +16,7 @@ import { useState, forwardRef } from '@wordpress/element';
 import InputBase from './input-base';
 import InputField from './input-field';
 import type { InputControlProps } from './types';
+import { space } from '../ui/utils/space';
 import { useDraft } from './utils';
 
 const noop = () => {};
@@ -29,6 +30,7 @@ function useUniqueId( idProp?: string ) {
 
 export function UnforwardedInputControl(
 	{
+		__next36pxDefaultSize,
 		__unstableStateReducer: stateReducer = ( state ) => state,
 		__unstableInputWidth,
 		className,
@@ -62,6 +64,7 @@ export function UnforwardedInputControl(
 
 	return (
 		<InputBase
+			__next36pxDefaultSize={ __next36pxDefaultSize }
 			__unstableInputWidth={ __unstableInputWidth }
 			className={ classes }
 			disabled={ disabled }
@@ -78,6 +81,7 @@ export function UnforwardedInputControl(
 		>
 			<InputField
 				{ ...props }
+				__next36pxDefaultSize={ __next36pxDefaultSize }
 				className="components-input-control__input"
 				disabled={ disabled }
 				id={ id }
@@ -85,6 +89,8 @@ export function UnforwardedInputControl(
 				isPressEnterToChange={ isPressEnterToChange }
 				onKeyDown={ onKeyDown }
 				onValidate={ onValidate }
+				paddingInlineStart={ prefix ? space( 2 ) : undefined }
+				paddingInlineEnd={ suffix ? space( 2 ) : undefined }
 				ref={ ref }
 				setIsFocused={ setIsFocused }
 				size={ size }

package/src/input-control/input-base.tsx

@@ -7,7 +7,7 @@ import type { ForwardedRef } from 'react';
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import { forwardRef } from '@wordpress/element';
+import { forwardRef, useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -20,8 +20,10 @@ import {
 	Prefix,
 	Suffix,
 	LabelWrapper,
+	getSizeConfig,
 } from './styles/input-control-styles';
 import type { InputBaseProps, LabelPosition } from './types';
+import { ContextSystemProvider } from '../ui/context';
 
 function useUniqueId( idProp?: string ) {
 	const instanceId = useInstanceId( InputBase );
@@ -52,6 +54,7 @@ function getUIFlexProps( labelPosition?: LabelPosition ) {
 
 export function InputBase(
 	{
+		__next36pxDefaultSize,
 		__unstableInputWidth,
 		children,
 		className,
@@ -71,6 +74,17 @@ export function InputBase(
 	const id = useUniqueId( idProp );
 	const hideLabel = hideLabelFromVision || ! label;
 
+	const { paddingLeft, paddingRight } = getSizeConfig( {
+		inputSize: size,
+		__next36pxDefaultSize,
+	} );
+	const prefixSuffixContextValue = useMemo( () => {
+		return {
+			InputControlPrefixWrapper: { paddingLeft },
+			InputControlSuffixWrapper: { paddingRight },
+		};
+	}, [ paddingLeft, paddingRight ] );
+
 	return (
 		// @ts-expect-error The `direction` prop from Flex (FlexDirection) conflicts with legacy SVGAttributes `direction` (string) that come from React intrinsic prop definitions.
 		<Root
@@ -99,17 +113,19 @@ export function InputBase(
 				hideLabel={ hideLabel }
 				labelPosition={ labelPosition }
 			>
-				{ prefix && (
-					<Prefix className="components-input-control__prefix">
-						{ prefix }
-					</Prefix>
-				) }
-				{ children }
-				{ suffix && (
-					<Suffix className="components-input-control__suffix">
-						{ suffix }
-					</Suffix>
-				) }
+				<ContextSystemProvider value={ prefixSuffixContextValue }>
+					{ prefix && (
+						<Prefix className="components-input-control__prefix">
+							{ prefix }
+						</Prefix>
+					) }
+					{ children }
+					{ suffix && (
+						<Suffix className="components-input-control__suffix">
+							{ suffix }
+						</Suffix>
+					) }
+				</ContextSystemProvider>
 				<Backdrop disabled={ disabled } isFocused={ isFocused } />
 			</Container>
 		</Root>

package/src/input-control/input-prefix-wrapper.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { Spacer } from '../spacer';
+import {
+	WordPressComponentProps,
+	contextConnect,
+	useContextSystem,
+} from '../ui/context';
+import type { InputControlPrefixWrapperProps } from './types';
+
+function UnconnectedInputControlPrefixWrapper(
+	props: WordPressComponentProps< InputControlPrefixWrapperProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const derivedProps = useContextSystem( props, 'InputControlPrefixWrapper' );
+
+	return (
+		<Spacer marginBottom={ 0 } { ...derivedProps } ref={ forwardedRef } />
+	);
+}
+
+/**
+ * A convenience wrapper for the `prefix` when you want to apply
+ * standard padding in accordance with the size variant.
+ *
+ * ```jsx
+ * import {
+ *   __experimentalInputControl as InputControl,
+ *   __experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
+ * } from '@wordpress/components';
+ *
+ * <InputControl
+ *   prefix={<InputControlPrefixWrapper>@</InputControlPrefixWrapper>}
+ * />
+ * ```
+ */
+export const InputControlPrefixWrapper = contextConnect(
+	UnconnectedInputControlPrefixWrapper,
+	'InputControlPrefixWrapper'
+);
+
+export default InputControlPrefixWrapper;

package/src/input-control/input-suffix-wrapper.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { Spacer } from '../spacer';
+import {
+	WordPressComponentProps,
+	contextConnect,
+	useContextSystem,
+} from '../ui/context';
+import type { InputControlSuffixWrapperProps } from './types';
+
+function UnconnectedInputControlSuffixWrapper(
+	props: WordPressComponentProps< InputControlSuffixWrapperProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const derivedProps = useContextSystem( props, 'InputControlSuffixWrapper' );
+
+	return (
+		<Spacer marginBottom={ 0 } { ...derivedProps } ref={ forwardedRef } />
+	);
+}
+
+/**
+ * A convenience wrapper for the `suffix` when you want to apply
+ * standard padding in accordance with the size variant.
+ *
+ * ```jsx
+ * import {
+ *   __experimentalInputControl as InputControl,
+ *   __experimentalInputControlSuffixWrapper as InputControlSuffixWrapper,
+ * } from '@wordpress/components';
+ *
+ * <InputControl
+ *   suffix={<InputControlSuffixWrapper>%</InputControlSuffixWrapper>}
+ * />
+ * ```
+ */
+export const InputControlSuffixWrapper = contextConnect(
+	UnconnectedInputControlSuffixWrapper,
+	'InputControlSuffixWrapper'
+);
+
+export default InputControlSuffixWrapper;

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

@@ -7,10 +7,13 @@ import type { ComponentMeta, ComponentStory } from '@storybook/react';
  * Internal dependencies
  */
 import InputControl from '..';
+import { InputControlPrefixWrapper } from '../input-prefix-wrapper';
+import { InputControlSuffixWrapper } from '../input-suffix-wrapper';
 
 const meta: ComponentMeta< typeof InputControl > = {
 	title: 'Components (Experimental)/InputControl',
 	component: InputControl,
+	subcomponents: { InputControlPrefixWrapper, InputControlSuffixWrapper },
 	argTypes: {
 		__unstableInputWidth: { control: { type: 'text' } },
 		__unstableStateReducer: { control: { type: null } },
@@ -37,16 +40,26 @@ Default.args = {
 	placeholder: 'Placeholder',
 };
 
+/**
+ * A `prefix` can be inserted before the input. By default, the prefix is aligned with the edge of the input border,
+ * with no padding. If you want to apply standard padding in accordance with the size variant, use the provided
+ * `<InputControlPrefixWrapper>` convenience wrapper.
+ */
 export const WithPrefix = Template.bind( {} );
 WithPrefix.args = {
 	...Default.args,
-	prefix: <span style={ { paddingLeft: 8 } }>@</span>,
+	prefix: <InputControlPrefixWrapper>@</InputControlPrefixWrapper>,
 };
 
+/**
+ * A `suffix` can be inserted after the input. By default, the suffix is aligned with the edge of the input border,
+ * with no padding. If you want to apply standard padding in accordance with the size variant, use the provided
+ * `<InputControlSuffixWrapper>` convenience wrapper.
+ */
 export const WithSuffix = Template.bind( {} );
 WithSuffix.args = {
 	...Default.args,
-	suffix: <button style={ { marginRight: 4 } }>Send</button>,
+	suffix: <InputControlSuffixWrapper>%</InputControlSuffixWrapper>,
 };
 
 export const WithSideLabel = Template.bind( {} );