@wordpress/components 19.14.0 → 19.17.0

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

@@ -1,15 +1,20 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import useGrid from './hook';
+import type { GridProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function Grid( props, forwardedRef ) {
+function UnconnectedGrid(
+	props: WordPressComponentProps< GridProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const gridProps = useGrid( props );
 
 	return <View { ...gridProps } ref={ forwardedRef } />;
@@ -18,7 +23,6 @@ function Grid( props, forwardedRef ) {
 /**
  * `Grid` is a primitive layout component that can arrange content in a grid configuration.
  *
- * @example
  * ```jsx
  * import {
  * 	__experimentalGrid as Grid,
@@ -36,6 +40,6 @@ function Grid( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedGrid = contextConnect( Grid, 'Grid' );
+export const Grid = contextConnect( UnconnectedGrid, 'Grid' );
 
-export default ConnectedGrid;
+export default Grid;

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

@@ -11,16 +11,16 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { getAlignmentProps } from './utils';
 import { useResponsiveValue } from '../ui/utils/use-responsive-value';
 import CONFIG from '../utils/config-values';
 import { useCx } from '../utils/hooks/use-cx';
+import type { GridProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export default function useGrid( props ) {
+export default function useGrid(
+	props: WordPressComponentProps< GridProps, 'div' >
+) {
 	const {
 		align,
 		alignment,

package/src/grid/stories/index.tsx

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { Grid } from '..';
+
+const meta: ComponentMeta< typeof Grid > = {
+	component: Grid,
+	title: 'Components (Experimental)/Grid',
+	argTypes: {
+		as: { control: { type: 'text' } },
+		align: { control: { type: 'text' } },
+		children: { control: { type: null } },
+		columnGap: { control: { type: 'text' } },
+		columns: {
+			table: { type: { summary: 'number' } },
+			control: { type: 'number' },
+		},
+		justify: { control: { type: 'text' } },
+		rowGap: { control: { type: 'text' } },
+		rows: {
+			table: { type: { summary: 'number' } },
+			control: { type: 'number' },
+		},
+		templateColumns: { control: { type: 'text' } },
+		templateRows: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Item = ( props: { children: string } ) => (
+	<View
+		style={ {
+			borderRadius: 8,
+			background: '#eee',
+			padding: 8,
+			textAlign: 'center',
+		} }
+		{ ...props }
+	/>
+);
+
+const Template: ComponentStory< typeof Grid > = ( props ) => (
+	<Grid { ...props }>
+		<Item>One</Item>
+		<Item>Two</Item>
+		<Item>Three</Item>
+		<Item>Four</Item>
+		<Item>Five</Item>
+		<Item>Six</Item>
+		<Item>Seven</Item>
+		<Item>Eight</Item>
+	</Grid>
+);
+
+export const Default: ComponentStory< typeof Grid > = Template.bind( {} );
+Default.args = {
+	alignment: 'bottom',
+	columns: 4,
+	gap: 2,
+};

package/src/grid/test/{grid.js → grid.tsx}

@@ -28,7 +28,7 @@ describe( 'props', () => {
 
 	test( 'should render gap', () => {
 		const { container } = render(
-			<Grid columns="3" gap={ 4 }>
+			<Grid columns={ 3 } gap={ 4 }>
 				<View />
 				<View />
 				<View />
@@ -44,7 +44,7 @@ describe( 'props', () => {
 
 	test( 'should render custom columns', () => {
 		const { container } = render(
-			<Grid columns="7">
+			<Grid columns={ 7 }>
 				<View />
 				<View />
 				<View />
@@ -59,7 +59,7 @@ describe( 'props', () => {
 
 	test( 'should render custom rows', () => {
 		const { container } = render(
-			<Grid rows="7">
+			<Grid rows={ 7 }>
 				<View />
 				<View />
 				<View />
@@ -120,7 +120,7 @@ describe( 'props', () => {
 
 	test( 'should render isInline', () => {
 		const { container } = render(
-			<Grid columns="3" isInline>
+			<Grid columns={ 3 } isInline>
 				<View />
 				<View />
 				<View />

package/src/grid/types.ts

@@ -1,9 +1,12 @@
 /**
  * External dependencies
  */
-import type { CSSProperties } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
-type ResponsiveCSSValue< T > = Array< T | undefined > | T;
+/**
+ * Internal dependencies
+ */
+import type { ResponsiveCSSValue } from '../ui/utils/types';
 
 type GridAlignment =
 	| 'bottom'
@@ -18,11 +21,7 @@ type GridAlignment =
 	| 'topLeft'
 	| 'topRight';
 
-type GridColumns = ResponsiveCSSValue< number >;
-
-type GridRows = ResponsiveCSSValue< number >;
-
-export type Props = {
+export type GridProps = {
 	/**
 	 * Adjusts the block alignment of children.
 	 */
@@ -31,26 +30,30 @@ export type Props = {
 	 * Adjusts the horizontal and vertical alignment of children.
 	 */
 	alignment?: GridAlignment;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
 	/**
 	 * Adjusts the number of columns of the `Grid`.
 	 *
 	 * @default 2
 	 */
-	columns?: GridColumns;
+	columns?: ResponsiveCSSValue< number >;
 	/**
 	 * Adjusts the `grid-column-gap`.
 	 */
 	columnGap?: CSSProperties[ 'gridColumnGap' ];
-	/**
-	 * Changes the CSS display from `grid` to `inline-grid`.
-	 */
-	isInline?: boolean;
 	/**
 	 * Gap between each child.
 	 *
 	 * @default 3
 	 */
 	gap?: number;
+	/**
+	 * Changes the CSS display from `grid` to `inline-grid`.
+	 */
+	isInline?: boolean;
 	/**
 	 * Adjusts the inline alignment of children.
 	 */
@@ -62,7 +65,7 @@ export type Props = {
 	/**
 	 * Adjusts the number of rows of the `Grid`.
 	 */
-	rows?: GridRows;
+	rows?: ResponsiveCSSValue< number >;
 	/**
 	 * Adjusts the CSS grid `template-columns`.
 	 */
@@ -71,8 +74,4 @@ export type Props = {
 	 * Adjusts the CSS grid `template-rows`.
 	 */
 	templateRows?: CSSProperties[ 'gridTemplateRows' ];
-	/**
-	 * The children elements.
-	 */
-	children: React.ReactNode;
 };

package/src/grid/{utils.js → utils.ts}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
 const ALIGNMENTS = {
 	bottom: { alignItems: 'flex-end', justifyContent: 'center' },
 	bottomLeft: { alignItems: 'flex-start', justifyContent: 'flex-end' },
@@ -12,14 +17,11 @@ const ALIGNMENTS = {
 	topRight: { alignItems: 'flex-start', justifyContent: 'flex-end' },
 };
 
-/* eslint-disable jsdoc/valid-types */
-/**
- * @param {keyof typeof ALIGNMENTS | undefined} alignment
- * @return {{ alignItems?: import('react').CSSProperties['alignItems'], justifyContent?: import('react').CSSProperties['justifyContent']}} CSS props for alignment
- */
-export function getAlignmentProps( alignment ) {
+export function getAlignmentProps( alignment?: keyof typeof ALIGNMENTS ): {
+	alignItems?: CSSProperties[ 'alignItems' ];
+	justifyContent?: CSSProperties[ 'justifyContent' ];
+} {
 	const alignmentProps = alignment ? ALIGNMENTS[ alignment ] : {};
 
 	return alignmentProps;
 }
-/* eslint-enable jsdoc/valid-types */

package/src/guide/style.scss

@@ -20,6 +20,7 @@
 		border-bottom: none;
 		padding: 0;
 		position: sticky;
+		height: $header-height;
 
 		.components-button {
 			align-self: flex-start;

package/src/h-stack/{component.js → component.tsx}

@@ -1,15 +1,15 @@
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import { useHStack } from './hook';
+import type { Props } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function HStack( props, forwardedRef ) {
+function UnconnectedHStack(
+	props: WordPressComponentProps< Props, 'div' >,
+	forwardedRef: React.ForwardedRef< any >
+) {
 	const hStackProps = useHStack( props );
 
 	return <View { ...hStackProps } ref={ forwardedRef } />;
@@ -38,6 +38,6 @@ function HStack( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedHStack = contextConnect( HStack, 'HStack' );
+export const HStack = contextConnect( UnconnectedHStack, 'HStack' );
 
-export default ConnectedHStack;
+export default HStack;

package/src/h-stack/{hook.js → hook.tsx}

@@ -1,16 +1,22 @@
+/**
+ * External dependencies
+ */
+import type { ReactElement } from 'react';
+
 /**
  * Internal dependencies
  */
-import { hasConnectNamespace, useContextSystem } from '../ui/context';
+import {
+	hasConnectNamespace,
+	useContextSystem,
+	WordPressComponentProps,
+} from '../ui/context';
 import { FlexItem, useFlex } from '../flex';
 import { getAlignmentProps } from './utils';
 import { getValidChildren } from '../ui/utils/get-valid-children';
+import type { Props } from './types';
 
-/**
- *
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useHStack( props ) {
+export function useHStack( props: WordPressComponentProps< Props, 'div' > ) {
 	const {
 		alignment = 'edge',
 		children,
@@ -22,19 +28,18 @@ export function useHStack( props ) {
 	const align = getAlignmentProps( alignment, direction );
 
 	const validChildren = getValidChildren( children );
-	const clonedChildren = validChildren.map(
-		// @ts-ignore
-		( /** @type {import('react').ReactElement} */ child, index ) => {
-			const _key = child.key || `hstack-${ index }`;
-			const _isSpacer = hasConnectNamespace( child, [ 'Spacer' ] );
+	const clonedChildren = validChildren.map( ( child, index ) => {
+		const _isSpacer = hasConnectNamespace( child, [ 'Spacer' ] );
 
-			if ( _isSpacer ) {
-				return <FlexItem isBlock key={ _key } { ...child.props } />;
-			}
+		if ( _isSpacer ) {
+			const childElement = child as ReactElement;
+			const _key = childElement.key || `hstack-${ index }`;
 
-			return child;
+			return <FlexItem isBlock key={ _key } { ...childElement.props } />;
 		}
-	);
+
+		return child;
+	} );
 
 	const propsForFlex = {
 		children: clonedChildren,

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 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' ) {
+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/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

@@ -30,7 +30,10 @@ export {
 	isEmptyBorder as __experimentalIsEmptyBorder,
 } from './border-box-control';
 export { BorderControl as __experimentalBorderControl } from './border-control';
-export { default as __experimentalBoxControl } from './box-control';
+export {
+	default as __experimentalBoxControl,
+	applyValueToSides as __experimentalApplyValueToSides,
+} from './box-control';
 export { default as Button } from './button';
 export { default as ButtonGroup } from './button-group';
 export {
@@ -66,6 +69,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 +95,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 }