@wordpress/components 19.13.0 → 19.16.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/spinner/{index.js → index.tsx}

@@ -2,24 +2,23 @@
  * External dependencies
  */
 import classNames from 'classnames';
+import type { ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
  */
 import { StyledSpinner, SpinnerTrack, SpinnerIndicator } from './styles';
+import type { WordPressComponentProps } from '../ui/context';
 
 /**
- * @typedef OwnProps
- *
- * @property {string} [className] Class name
+ * WordPress dependencies
  */
-/** @typedef {import('react').ComponentPropsWithoutRef<'svg'> & OwnProps} Props */
+import { forwardRef } from '@wordpress/element';
 
-/**
- * @param {Props} props
- * @return {JSX.Element} Element
- */
-export default function Spinner( { className, ...props } ) {
+export function UnforwardedSpinner(
+	{ className, ...props }: WordPressComponentProps< {}, 'svg', false >,
+	forwardedRef: ForwardedRef< any >
+) {
 	return (
 		<StyledSpinner
 			className={ classNames( 'components-spinner', className ) }
@@ -28,6 +27,7 @@ export default function Spinner( { className, ...props } ) {
 			role="presentation"
 			focusable="false"
 			{ ...props }
+			ref={ forwardedRef }
 		>
 			{ /* Gray circular background */ }
 			<SpinnerTrack
@@ -45,3 +45,17 @@ export default function Spinner( { className, ...props } ) {
 		</StyledSpinner>
 	);
 }
+/**
+ * `Spinner` is a component used to notify users that their action is being processed.
+ *
+ * @example
+ * ```js
+ *   import { Spinner } from '@wordpress/components';
+ *
+ *   function Example() {
+ *     return <Spinner />;
+ *   }
+ * ```
+ */
+export const Spinner = forwardRef( UnforwardedSpinner );
+export default Spinner;

package/src/spinner/stories/index.tsx

@@ -0,0 +1,32 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Spinner from '../';
+import { space } from '../../ui/utils/space';
+
+const meta: ComponentMeta< typeof Spinner > = {
+	title: 'Components/Spinner',
+	component: Spinner,
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Spinner > = ( args ) => {
+	return <Spinner { ...args } />;
+};
+
+export const Default: ComponentStory< typeof Spinner > = Template.bind( {} );
+
+// The Spinner can be resized to any size, but the stroke width will remain unchanged.
+export const CustomSize: ComponentStory< typeof Spinner > = Template.bind( {} );
+CustomSize.args = { style: { width: space( 20 ), height: space( 20 ) } };

package/src/style.scss

@@ -17,6 +17,7 @@
 @import "./drop-zone/style.scss";
 @import "./dropdown/style.scss";
 @import "./dropdown-menu/style.scss";
+@import "./duotone-picker/style.scss";
 @import "./font-size-picker/style.scss";
 @import "./form-toggle/style.scss";
 @import "./form-token-field/style.scss";

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/types.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import type { Props as TruncateProps } from '../truncate/types';
+import type { TruncateProps } from '../truncate/types';
 
 /**
  * External dependencies

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;
+};