@wordpress/components 19.12.0 → 19.15.0

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 { 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,59 +2,19 @@
  * 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' >
 ) {
-	const { as: asProp, level = 2, ...otherProps } = useContextSystem(
-		props,
-		'Heading'
-	);
+	const {
+		as: asProp,
+		level = 2,
+		...otherProps
+	} = useContextSystem( props, 'Heading' );
 
 	const as = ( asProp || `h${ level }` ) as keyof JSX.IntrinsicElements;
 

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/higher-order/navigate-regions/index.js

@@ -95,10 +95,12 @@ export function useNavigateRegions( shortcuts = defaultShortcuts ) {
 }
 
 export default createHigherOrderComponent(
-	( Component ) => ( { shortcuts, ...props } ) => (
-		<div { ...useNavigateRegions( shortcuts ) }>
-			<Component { ...props } />
-		</div>
-	),
+	( Component ) =>
+		( { shortcuts, ...props } ) =>
+			(
+				<div { ...useNavigateRegions( shortcuts ) }>
+					<Component { ...props } />
+				</div>
+			),
 	'navigateRegions'
 );

package/src/higher-order/with-filters/test/index.js

@@ -81,12 +81,13 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-compose',
-			( FilteredComponent ) => () => (
-				<div>
-					<FilteredComponent />
-					<ComposedComponent />
-				</div>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<div>
+						<FilteredComponent />
+						<ComposedComponent />
+					</div>
+				)
 		);
 		const EnhancedComponent = withFilters( hookName )( MyComponent );
 
@@ -106,11 +107,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -143,11 +145,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		jest.runAllTimers();
 
@@ -174,20 +177,22 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-2',
-			( FilteredComponent ) => () => (
-				<section>
-					<FilteredComponent />
-				</section>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<section>
+						<FilteredComponent />
+					</section>
+				)
 		);
 		jest.runAllTimers();
 
@@ -213,11 +218,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy',
-			( FilteredComponent ) => () => (
-				<div>
-					<FilteredComponent />
-				</div>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<div>
+						<FilteredComponent />
+					</div>
+				)
 		);
 		jest.runAllTimers();
 
@@ -249,11 +255,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		jest.runAllTimers();
 

package/src/higher-order/with-focus-return/index.js

@@ -31,18 +31,20 @@ function isComponentLike( object ) {
  * @return {Function} Higher Order Component with the focus restauration behaviour.
  */
 export default createHigherOrderComponent( ( options ) => {
-	const HoC = ( { onFocusReturn } = {} ) => ( WrappedComponent ) => {
-		const WithFocusReturn = ( props ) => {
-			const ref = useFocusReturn( onFocusReturn );
-			return (
-				<div ref={ ref }>
-					<WrappedComponent { ...props } />
-				</div>
-			);
-		};
+	const HoC =
+		( { onFocusReturn } = {} ) =>
+		( WrappedComponent ) => {
+			const WithFocusReturn = ( props ) => {
+				const ref = useFocusReturn( onFocusReturn );
+				return (
+					<div ref={ ref }>
+						<WrappedComponent { ...props } />
+					</div>
+				);
+			};
 
-		return WithFocusReturn;
-	};
+			return WithFocusReturn;
+		};
 
 	if ( isComponentLike( options ) ) {
 		const WrappedComponent = options;
@@ -55,8 +57,7 @@ export default createHigherOrderComponent( ( options ) => {
 export const Provider = ( { children } ) => {
 	deprecated( 'wp.components.FocusReturnProvider component', {
 		since: '5.7',
-		hint:
-			'This provider is not used anymore. You can just remove it from your codebase',
+		hint: 'This provider is not used anymore. You can just remove it from your codebase',
 	} );
 
 	return children;