@wordpress/components 19.14.0 → 19.17.0

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/style-provider/index.tsx

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+import { CacheProvider } from '@emotion/react';
+import createCache from '@emotion/cache';
+import memoize from 'memize';
+import * as uuid from 'uuid';
+
+/**
+ * Internal dependencies
+ */
+import type { StyleProviderProps } from './types';
+
+const uuidCache = new Set();
+
+const memoizedCreateCacheWithContainer = memoize(
+	( container: HTMLElement ) => {
+		// Emotion only accepts alphabetical and hyphenated keys so we just
+		// strip the numbers from the UUID. It _should_ be fine.
+		let key = uuid.v4().replace( /[0-9]/g, '' );
+		while ( uuidCache.has( key ) ) {
+			key = uuid.v4().replace( /[0-9]/g, '' );
+		}
+		uuidCache.add( key );
+		return createCache( { container, key } );
+	}
+);
+
+export function StyleProvider( props: StyleProviderProps ) {
+	const { children, document } = props;
+
+	if ( ! document ) {
+		return null;
+	}
+
+	const cache = memoizedCreateCacheWithContainer( document.head );
+
+	return <CacheProvider value={ cache }>{ children }</CacheProvider>;
+}
+
+export default StyleProvider;

package/src/style-provider/types.ts

@@ -0,0 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type StyleProviderProps = {
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+	/**
+	 * Current document.
+	 */
+	document: Document;
+};

package/src/swatch/{index.js → index.tsx}

@@ -7,8 +7,11 @@ import { swatch } from '@wordpress/icons';
  * Internal dependencies
  */
 import Icon from '../icon';
+import type { SwatchProps } from './types';
 
-function Swatch( { fill } ) {
+// This component will be deprecated. Use `ColorIndicator` instead.
+// TODO: Consolidate this component with `ColorIndicator`.
+function Swatch( { fill }: SwatchProps ) {
 	return fill ? (
 		<span className="components-swatch" style={ { background: fill } } />
 	) : (

package/src/swatch/types.ts

@@ -0,0 +1,11 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
+export type SwatchProps = {
+	/**
+	 * The color to display in the swatch.
+	 */
+	fill?: CSSProperties[ 'background' ];
+};

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/hook.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { css } from '@emotion/react';
-import { isPlainObject } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -167,8 +166,11 @@ export default function useText( props ) {
 	 */
 	if ( ! truncate && Array.isArray( children ) ) {
 		content = Children.map( children, ( child ) => {
-			// @ts-ignore
-			if ( ! isPlainObject( child ) || ! ( 'props' in child ) ) {
+			if (
+				typeof child !== 'object' ||
+				child === null ||
+				! ( 'props' in child )
+			) {
 				return child;
 			}
 

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;

package/src/tip/stories/index.tsx

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Tip from '..';
+
+const meta: ComponentMeta< typeof Tip > = {
+	component: Tip,
+	title: 'Components/Tip',
+	argTypes: {
+		children: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Tip > = ( args ) => {
+	return <Tip { ...args } />;
+};
+
+export const Default: ComponentStory< typeof Tip > = Template.bind( {} );
+Default.args = {
+	children: 'An example tip',
+};

package/src/tip/types.ts

@@ -0,0 +1,11 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type TipProps = {
+	/**
+	 * Children to render in the tip.
+	 */
+	children: ReactNode;
+};