@wordpress/components 19.14.0 → 19.15.0

package/src/spacer/README.md

@@ -33,87 +33,93 @@ function Example() {
 
 ## Props
 
-### `margin`: `number`
-
-Adjusts all margins.
-
-- Required: No
-
-### `marginY`: `number`
+### `children`: `ReactNode`
 
-Adjusts top and bottom margins, potentially overriding the value from the more generic `margin` prop.
-
-- Required: No
-
-### `marginX`: `number`
-
-Adjusts left and right margins, potentially overriding the value from the more generic `margin` prop.
+The children elements.
 
-- Required: No
+-   Required: No
 
-### `marginTop`: `number`
+### `margin`: `number`
 
-Adjusts top margin, potentially overriding the value from the more generic `margin` and `marginY` props.
+Adjusts all margins.
 
-- Required: No
+-   Required: No
 
 ### `marginBottom`: `number`
 
 Adjusts bottom margin, potentially overriding the value from the more generic `margin` and `marginY` props.
 
-- Required: No
-- Default: `2`
+-   Required: No
+-   Default: `2`
 
 ### `marginLeft`: `number`
 
 Adjusts left margin, potentially overriding the value from the more generic `margin` and `marginX` props.
 
-- Required: No
+-   Required: No
 
 ### `marginRight`: `number`
 
 Adjusts right margin, potentially overriding the value from the more generic `margin` and `marginX` props.
 
-- Required: No
+-   Required: No
 
-### `padding`: `number`
+### `marginTop`: `number`
 
-Adjusts all padding.
+Adjusts top margin, potentially overriding the value from the more generic `margin` and `marginY` props.
 
-- Required: No
+-   Required: No
 
-### `paddingY`: `number`
+### `marginX`: `number`
 
-Adjusts top and bottom padding, potentially overriding the value from the more generic `padding` prop.
+Adjusts left and right margins, potentially overriding the value from the more generic `margin` prop.
 
-- Required: No
+-   Required: No
 
-### `paddingX`: `number`
+### `marginY`: `number`
 
-Adjusts left and right padding, potentially overriding the value from the more generic `padding` prop.
+Adjusts top and bottom margins, potentially overriding the value from the more generic `margin` prop.
 
-- Required: No
+-   Required: No
 
-### `paddingTop`: `number`
+### `padding`: `number`
 
-Adjusts top padding, potentially overriding the value from the more generic `padding` and `paddingY` props.
+Adjusts all padding.
 
-- Required: No
+-   Required: No
 
 ### `paddingBottom`: `number`
 
 Adjusts bottom padding, potentially overriding the value from the more generic `padding` and `paddingY` props.
 
-- Required: No
+-   Required: No
 
 ### `paddingLeft`: `number`
 
 Adjusts left padding, potentially overriding the value from the more generic `padding` and `paddingX` props.
 
-- Required: No
+-   Required: No
 
 ### `paddingRight`: `number`
 
 Adjusts right padding, potentially overriding the value from the more generic `padding` and `paddingX` props.
 
-- Required: No
+-   Required: No
+
+### `paddingTop`: `number`
+
+Adjusts top padding, potentially overriding the value from the more generic `padding` and `paddingY` props.
+
+-   Required: No
+
+### `paddingX`: `number`
+
+Adjusts left and right padding, potentially overriding the value from the more generic `padding` prop.
+
+-   Required: No
+
+### `paddingY`: `number`
+
+Adjusts top and bottom padding, potentially overriding the value from the more generic `padding` prop.
+
+-   Required: No

package/src/spacer/component.tsx

@@ -9,10 +9,10 @@ import type { ForwardedRef } from 'react';
 import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import { useSpacer } from './hook';
-import type { Props } from './types';
+import type { SpacerProps } from './types';
 
 function UnconnectedSpacer(
-	props: WordPressComponentProps< Props, 'div' >,
+	props: WordPressComponentProps< SpacerProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
 	const spacerProps = useSpacer( props );

package/src/spacer/hook.ts

@@ -9,12 +9,14 @@ import { css } from '@emotion/react';
 import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { space } from '../ui/utils/space';
 import { rtl, useCx } from '../utils';
-import type { Props } from './types';
+import type { SpacerProps } from './types';
 
 const isDefined = < T >( o: T ): o is Exclude< T, null | undefined > =>
 	typeof o !== 'undefined' && o !== null;
 
-export function useSpacer( props: WordPressComponentProps< Props, 'div' > ) {
+export function useSpacer(
+	props: WordPressComponentProps< SpacerProps, 'div' >
+) {
 	const {
 		className,
 		margin,

package/src/spacer/index.ts

@@ -1,3 +1,3 @@
 export { default as Spacer } from './component';
 export { useSpacer } from './hook';
-export type { Props as SpacerProps } from './types';
+export type { SpacerProps } from './types';

package/src/spacer/test/__snapshots__/{index.js.snap → index.tsx.snap}

@@ -39,6 +39,7 @@ exports[`props should render correctly 1`] = `
 
 <div
   class="components-spacer emotion-0 emotion-1"
+  data-testid="spacer"
   data-wp-c16t="true"
   data-wp-component="Spacer"
 />

package/src/spacer/test/index.tsx

@@ -0,0 +1,149 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { Spacer } from '../index';
+
+describe( 'props', () => {
+	beforeEach( () => {
+		render( <Spacer data-testid="spacer" /> );
+	} );
+
+	test( 'should render correctly', () => {
+		expect( screen.getByTestId( 'spacer' ) ).toMatchSnapshot();
+	} );
+
+	test( 'should render margin', () => {
+		render( <Spacer margin={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render marginX', () => {
+		render( <Spacer marginX={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render marginY', () => {
+		render( <Spacer marginY={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render marginTop', () => {
+		render( <Spacer marginTop={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render marginBottom', () => {
+		render( <Spacer marginBottom={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render marginLeft', () => {
+		render( <Spacer marginLeft={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render marginRight', () => {
+		render( <Spacer marginRight={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should override margin props from less to more specific', () => {
+		render(
+			<Spacer
+				margin={ 10 }
+				marginX={ 3 }
+				marginRight={ 5 }
+				marginBottom={ 1 }
+				data-testid="customized-spacer"
+			/>
+		);
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render padding', () => {
+		render( <Spacer padding={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render paddingX', () => {
+		render( <Spacer paddingX={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render paddingY', () => {
+		render( <Spacer paddingY={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render paddingTop', () => {
+		render( <Spacer paddingTop={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render paddingBottom', () => {
+		render(
+			<Spacer paddingBottom={ 5 } data-testid="customized-spacer" />
+		);
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render paddingLeft', () => {
+		render( <Spacer paddingLeft={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should render paddingRight', () => {
+		render( <Spacer paddingRight={ 5 } data-testid="customized-spacer" /> );
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+
+	test( 'should override padding props from less to more specific', () => {
+		render(
+			<Spacer
+				padding={ 10 }
+				paddingY={ 2 }
+				paddingTop={ 5 }
+				paddingLeft={ 3 }
+				data-testid="customized-spacer"
+			/>
+		);
+		expect(
+			screen.getByTestId( 'customized-spacer' )
+		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
+	} );
+} );

package/src/spacer/types.ts

@@ -8,67 +8,79 @@ import type { ReactNode } from 'react';
  */
 import type { SpaceInput } from '../ui/utils/space';
 
-export type Props = {
+export type SpacerProps = {
 	/**
-	 * Adjusts all margins.
-	 */
-	margin?: SpaceInput;
-	/**
-	 * Adjusts top and bottom margins.
-	 */
-	marginY?: SpaceInput;
-	/**
-	 * Adjusts left and right margins.
+	 * The children elements.
 	 */
-	marginX?: SpaceInput;
+	children?: ReactNode;
 	/**
-	 * Adjusts top margins.
+	 * Adjusts all margins.
 	 */
-	marginTop?: SpaceInput;
+	margin?: SpaceInput;
 	/**
-	 * Adjusts bottom margins.
+	 * Adjusts bottom margin, potentially overriding the value from the more
+	 * generic `margin` and `marginY` props.
 	 *
 	 * @default 2
 	 */
 	marginBottom?: SpaceInput;
 	/**
-	 * Adjusts left margins.
+	 * Adjusts left margin, potentially overriding the value from the more
+	 * generic `margin` and `marginX` props.
 	 */
 	marginLeft?: SpaceInput;
 	/**
-	 * Adjusts right margins.
+	 * Adjusts right margin, potentially overriding the value from the more
+	 * generic `margin` and `marginX` props.
 	 */
 	marginRight?: SpaceInput;
 	/**
-	 * Adjusts all padding.
+	 * Adjusts top margin, potentially overriding the value from the more
+	 * generic `margin` and `marginY` props.
 	 */
-	padding?: SpaceInput;
+	marginTop?: SpaceInput;
 	/**
-	 * Adjusts top and bottom padding.
+	 * Adjusts left and right margins, potentially overriding the value from the
+	 * more generic `margin` prop.
 	 */
-	paddingY?: SpaceInput;
+	marginX?: SpaceInput;
 	/**
-	 * Adjusts left and right padding.
+	 * Adjusts top and bottom margins, potentially overriding the value from the
+	 * more generic `margin` prop.
 	 */
-	paddingX?: SpaceInput;
+	marginY?: SpaceInput;
 	/**
-	 * Adjusts top padding.
+	 * Adjusts all padding.
 	 */
-	paddingTop?: SpaceInput;
+	padding?: SpaceInput;
 	/**
-	 * Adjusts bottom padding.
+	 * Adjusts bottom padding, potentially overriding the value from the more
+	 * generic `padding` and `paddingY` props.
 	 */
 	paddingBottom?: SpaceInput;
 	/**
-	 * Adjusts left padding.
+	 * Adjusts left padding, potentially overriding the value from the more
+	 * generic `padding` and `paddingX` props.
 	 */
 	paddingLeft?: SpaceInput;
 	/**
-	 * Adjusts right padding.
+	 * Adjusts right padding, potentially overriding the value from the more
+	 * generic `padding` and `paddingX` props.
 	 */
 	paddingRight?: SpaceInput;
 	/**
-	 * The children elements.
+	 * Adjusts top padding, potentially overriding the value from the more
+	 * generic `padding` and `paddingY` props.
 	 */
-	children?: ReactNode;
+	paddingTop?: SpaceInput;
+	/**
+	 * Adjusts left and right padding, potentially overriding the value from the
+	 * more generic `padding` prop.
+	 */
+	paddingX?: SpaceInput;
+	/**
+	 * Adjusts top and bottom padding, potentially overriding the value from the
+	 * more generic `padding` prop.
+	 */
+	paddingY?: SpaceInput;
 };

package/src/tab-panel/README.md

@@ -144,7 +144,7 @@ Optionally provide a tab name for a tab to be selected upon mounting of componen
 
 #### children
 
-A function which renders the tabviews given the selected tab. The function is passed the active tab object as an argument as defined the the tabs prop.
+A function which renders the tabviews given the selected tab. The function is passed the active tab object as an argument as defined the tabs prop.
 The element to which the tooltip should anchor.
 
 -   Type: (`Object`) => `Element`

package/src/text-highlight/README.md

@@ -23,16 +23,16 @@ const MyTextHighlight = () => (
 
 The component accepts the following props.
 
-### text
+### `highlight`: `string`
 
-The string of text to be tested for occurrences of then given `highlight`.
+The string to search for and highlight within the `text`. Case insensitive. Multiple matches.
 
--   Type: `String`
 -   Required: Yes
+-   Default: `''`
 
-### highlight
+### `text`: `string`
 
-The string to search for and highlight within the `text`. Case insensitive. Multiple matches.
+The string of text to be tested for occurrences of then given `highlight`.
 
--   Type: `String`
 -   Required: Yes
+-   Default: `''`

package/src/text-highlight/index.tsx

@@ -0,0 +1,49 @@
+/**
+ * External dependencies
+ */
+import { escapeRegExp } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+import { createInterpolateElement } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { TextHighlightProps } from './types';
+
+/**
+ * Highlights occurrences of a given string within another string of text. Wraps
+ * each match with a `<mark>` tag which provides browser default styling.
+ *
+ * ```jsx
+ * import { TextHighlight } from '@wordpress/components';
+ *
+ * const MyTextHighlight = () => (
+ *   <TextHighlight
+ *     text="Why do we like Gutenberg? Because Gutenberg is the best!"
+ *     highlight="Gutenberg"
+ *   />
+ * );
+ * ```
+ */
+export const TextHighlight = ( props: TextHighlightProps ) => {
+	const { text = '', highlight = '' } = props;
+	const trimmedHighlightText = highlight.trim();
+
+	if ( ! trimmedHighlightText ) {
+		return <>{ text }</>;
+	}
+
+	const regex = new RegExp(
+		`(${ escapeRegExp( trimmedHighlightText ) })`,
+		'gi'
+	);
+
+	return createInterpolateElement( text.replace( regex, '<mark>$&</mark>' ), {
+		mark: <mark />,
+	} );
+};
+
+export default TextHighlight;

package/src/text-highlight/stories/index.tsx

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import TextHighlight from '..';
+
+const meta: ComponentMeta< typeof TextHighlight > = {
+	component: TextHighlight,
+	title: 'Components/TextHighlight',
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof TextHighlight > = ( args ) => {
+	return <TextHighlight { ...args } />;
+};
+
+export const Default: ComponentStory< typeof TextHighlight > = Template.bind(
+	{}
+);
+Default.args = {
+	text: 'We call the new editor Gutenberg. The entire editing experience has been rebuilt for media rich pages and posts.',
+	highlight: 'Gutenberg',
+};

package/src/text-highlight/test/index.tsx

@@ -0,0 +1,93 @@
+/**
+ * External dependencies
+ */
+import { render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import TextHighlight from '..';
+
+const getMarks = ( container: Element ) =>
+	// Use querySelectorAll because the `mark` role is not officially supported
+	// yet. This should be changed to `getByRole` when it is.
+	Array.from( container.querySelectorAll( 'mark' ) );
+
+const defaultText =
+	'We call the new editor Gutenberg. The entire editing experience has been rebuilt for media rich pages and posts.';
+
+describe( 'TextHighlight', () => {
+	describe( 'Basic rendering', () => {
+		it.each( [ [ 'Gutenberg' ], [ 'media' ] ] )(
+			'should highlight the singular occurance of the text "%s" in the text if it exists',
+			( highlight ) => {
+				const { container } = render(
+					<TextHighlight
+						text={ defaultText }
+						highlight={ highlight }
+					/>
+				);
+
+				const highlightedEls = getMarks( container );
+
+				highlightedEls.forEach( ( el ) => {
+					expect( el ).toHaveTextContent(
+						new RegExp( `^${ highlight }$` )
+					);
+				} );
+			}
+		);
+
+		it( 'should highlight multiple occurances of the string every time it exists in the text', () => {
+			const highlight = 'edit';
+
+			const { container } = render(
+				<TextHighlight text={ defaultText } highlight={ highlight } />
+			);
+
+			const highlightedEls = getMarks( container );
+
+			expect( highlightedEls ).toHaveLength( 2 );
+
+			highlightedEls.forEach( ( el ) => {
+				expect( el.textContent ).toEqual(
+					expect.stringContaining( highlight )
+				);
+			} );
+		} );
+
+		it( 'should highlight occurances of a string regardless of capitalisation', () => {
+			// Note that `The` occurs twice in the default text, once in
+			// lowercase and once capitalized.
+			const highlight = 'The';
+
+			const { container } = render(
+				<TextHighlight text={ defaultText } highlight={ highlight } />
+			);
+
+			const highlightedEls = getMarks( container );
+
+			expect( highlightedEls ).toHaveLength( 2 );
+
+			// Make sure the matcher is case insensitive, since the test should
+			// match regardless of the case of the string.
+			const regex = new RegExp( highlight, 'i' );
+
+			highlightedEls.forEach( ( el ) => {
+				expect( el.innerHTML ).toMatch( regex );
+			} );
+		} );
+
+		it( 'should not highlight a string that is not in the text', () => {
+			const highlight = 'Antidisestablishmentarianism';
+
+			const { container } = render(
+				<TextHighlight text={ defaultText } highlight={ highlight } />
+			);
+
+			const highlightedEls = getMarks( container );
+
+			expect( highlightedEls ).toHaveLength( 0 );
+		} );
+	} );
+} );

package/src/text-highlight/types.ts

@@ -0,0 +1,16 @@
+export type TextHighlightProps = {
+	/**
+	 * The string to search for and highlight within the `text`. Case
+	 * insensitive. Multiple matches.
+	 *
+	 * @default ''
+	 */
+	highlight: string;
+	/**
+	 * The string of text to be tested for occurrences of then given
+	 * `highlight`.
+	 *
+	 * @default ''
+	 */
+	text: string;
+};

package/src/tip/index.tsx

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import { Icon, tip } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import type { TipProps } from './types';
+
+export function Tip( props: TipProps ) {
+	const { children } = props;
+
+	return (
+		<div className="components-tip">
+			<Icon icon={ tip } />
+			<p>{ children }</p>
+		</div>
+	);
+}
+
+export default Tip;