@wordpress/components 19.15.0 → 20.0.0

package/src/palette-edit/styles.js

@@ -29,7 +29,7 @@ export const IndicatorStyled = styled( CircularOptionPicker.Option )`
 export const NameInputControl = styled( InputControl )`
 	${ InputControlContainer } {
 		background: ${ COLORS.gray[ 100 ] };
-		border-radius: ${ CONFIG.controlBorderRadius }};
+		border-radius: ${ CONFIG.controlBorderRadius };
 		${ Input }${ Input }${ Input }${ Input } {
 			height: ${ space( 8 ) };
 		}
@@ -58,7 +58,7 @@ export const PaletteItem = styled( View )`
 		border-top-color: transparent;
 	}
 	&.is-selected {
-		border-color: ${ COLORS.blue.wordpress[ 700 ] };
+		border-color: ${ COLORS.ui.theme };
 	}
 `;
 
@@ -69,7 +69,7 @@ export const NameContainer = styled.div`
 	white-space: nowrap;
 	overflow: hidden;
 	${ PaletteItem }:hover & {
-		color: var( --wp-admin-theme-color, ${ COLORS.blue.wordpress[ 700 ] } );
+		color: ${ COLORS.ui.theme };
 	}
 `;
 
@@ -95,8 +95,9 @@ export const PaletteHStackHeader = styled( HStack )`
 export const PaletteEditStyles = styled( View )`
 	&&& {
 		.components-button.has-icon {
-		min-width: 0;
-		padding: 0;
+			min-width: 0;
+			padding: 0;
+		}
 	}
 `;
 

package/src/panel/style.scss

@@ -35,9 +35,12 @@
 	justify-content: space-between;
 	align-items: center;
 	padding: 0 $grid-unit-20;
-	height: $grid-unit-60;
 	border-bottom: $border-width solid $gray-300;
 
+	// This helps ensure the correct panel height, including the border, avoiding subpixel rounding issues.
+	box-sizing: content-box;
+	height: $grid-unit-60 - $border-width;
+
 	h2 {
 		margin: 0;
 		font-size: inherit;

package/src/placeholder/README.md

@@ -9,12 +9,52 @@ import { more } from '@wordpress/icons';
 const MyPlaceholder = () => <Placeholder icon={ more } label="Placeholder" />;
 ```
 
-### Props
-
-| Name              | Type                | Default     | Description                                                       |
-| ----------------  | ------------------- | ----------- | ----------------------------------------------------------------- |
-| `icon`            | `string, WPElement` | `undefined` | If provided, renders an icon next to the label.                   |
-| `label`           | `string`            | `undefined` | Renders a label for the placeholder.                              |
-| `instructions`    | `string`            | `undefined` | Renders instruction text below label.                             |
-| `isColumnLayout`  | `bool`              | `false`     | Changes placeholder children layout from flex-row to flex-column. |
-| `withIllustration`| `bool`              | `false`     | Outputs a placeholder illustration.                             |
+## Props
+
+### `className`: `string`
+
+Class to set on the container div.
+
+-   Required: No
+
+### `icon`: `string|Function|WPComponent|null`
+
+If provided, renders an icon next to the label.
+
+-   Required: No
+
+### `instructions`: `string`
+
+Instructions of the placeholder.
+
+-   Required: No
+
+### `isColumnLayout`: `boolean`
+
+Changes placeholder children layout from flex-row to flex-column.
+
+-   Required: No
+
+### `label`: `string`
+
+Title of the placeholder.
+
+-   Required: No
+
+### `notices`: `ReactNode`
+
+A rendered notices list
+
+-   Required: No
+
+### `preview`: `ReactNode`
+
+Preview to be rendered in the placeholder.
+
+-   Required: No
+
+### `withIllustration`: `boolean`
+
+Outputs a placeholder illustration.
+
+-   Required: No

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

@@ -13,6 +13,8 @@ import { SVG, Path } from '@wordpress/primitives';
  * Internal dependencies
  */
 import Icon from '../icon';
+import type { PlaceholderProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
 const PlaceholderIllustration = (
 	<SVG
@@ -29,31 +31,33 @@ const PlaceholderIllustration = (
 /**
  * Renders a placeholder. Normally used by blocks to render their empty state.
  *
- * @param {Object}    props                  The component props.
- * @param {WPIcon}    props.icon             An icon rendered before the label.
- * @param {WPElement} props.children         Children to be rendered.
- * @param {string}    props.label            Title of the placeholder.
- * @param {string}    props.instructions     Instructions of the placeholder.
- * @param {string}    props.className        Class to set on the container div.
- * @param {Object}    props.notices          A rendered notices list.
- * @param {Object}    props.preview          Preview to be rendered in the placeholder.
- * @param {boolean}   props.isColumnLayout   Whether a column layout should be used.
- * @param {boolean}   props.withIllustration Whether to add an illustration to the placeholder.
+ * ```jsx
+ * import { Placeholder } from '@wordpress/components';
+ * import { more } from '@wordpress/icons';
  *
- * @return {Object} The rendered placeholder.
+ * const MyPlaceholder = () => <Placeholder icon={ more } label="Placeholder" />;
+ * ```
  */
-function Placeholder( {
-	icon,
-	children,
-	label,
-	instructions,
-	className,
-	notices,
-	preview,
-	isColumnLayout,
-	withIllustration,
-	...additionalProps
-} ) {
+export function Placeholder< IconProps = unknown >(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to Placeholder.
+	props: Omit<
+		WordPressComponentProps< PlaceholderProps< IconProps >, 'div', false >,
+		'ref'
+	>
+) {
+	const {
+		icon,
+		children,
+		label,
+		instructions,
+		className,
+		notices,
+		preview,
+		isColumnLayout,
+		withIllustration,
+		...additionalProps
+	} = props;
 	const [ resizeListener, { width } ] = useResizeObserver();
 
 	// Since `useResizeObserver` will report a width of `null` until after the

package/src/placeholder/stories/index.tsx

@@ -0,0 +1,64 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { starEmpty, starFilled, styles, wordpress } from '@wordpress/icons';
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Placeholder from '../';
+import TextControl from '../../text-control';
+
+const ICONS = { starEmpty, starFilled, styles, wordpress };
+
+const meta: ComponentMeta< typeof Placeholder > = {
+	component: Placeholder,
+	title: 'Components/Placeholder',
+	argTypes: {
+		children: { control: { type: null } },
+		notices: { control: { type: null } },
+		preview: { control: { type: null } },
+		icon: {
+			control: { type: 'select' },
+			options: Object.keys( ICONS ),
+			mapping: ICONS,
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Placeholder > = ( args ) => {
+	const [ value, setValue ] = useState( '' );
+
+	return (
+		<Placeholder { ...args }>
+			<div>
+				<TextControl
+					label="Sample Field"
+					placeholder="Enter something here"
+					value={ value }
+					onChange={ setValue }
+				/>
+			</div>
+		</Placeholder>
+	);
+};
+
+export const Default: ComponentStory< typeof Placeholder > = Template.bind(
+	{}
+);
+Default.args = {
+	icon: 'wordpress',
+	label: 'My Placeholder Label',
+	instructions: 'Here are instructions you should follow',
+};

package/src/placeholder/style.scss

@@ -26,17 +26,6 @@
 	background-color: $white;
 	box-shadow: inset 0 0 0 $border-width $gray-900;
 	outline: 1px solid transparent; // Shown for Windows 10 High Contrast mode.
-
-	.components-base-control__label {
-		font-size: $default-font-size;
-	}
-
-	&.has-illustration {
-		background: none;
-		border: none;
-		box-shadow: none;
-		min-width: 100px;
-	}
 }
 
 .components-placeholder__error,
@@ -116,11 +105,6 @@
 	width: 100%;
 }
 
-.components-placeholder__preview img {
-	margin: 3%;
-	width: 50%;
-}
-
 .components-placeholder__fieldset .components-button {
 	margin-right: $grid-unit-15;
 	margin-bottom: $grid-unit-15; // If buttons wrap we need vertical space between.
@@ -179,18 +163,75 @@
 	}
 }
 
-// Style the placeholder illustration.
-.components-placeholder__illustration {
+
+/**
+ * Dashed style placeholders
+ */
+
+// @todo
+// These styles are only applied after the has-illustration gets added.
+// This is mainly an issue in terms of Site Logo which has a brief flash of the square placeholder.
+.components-placeholder.has-illustration {
+	color: inherit;
+	display: flex;
+	box-shadow: none;
+	min-width: 100px;
+
+	// Radius fallback value.
+	border-radius: $radius-block-ui;
+
+	// Blur the background so layered dashed placeholders are still visually separate.
+	// We also provide a semitransparent background so as to allow duotones to sheen through.
+	backdrop-filter: blur(100px);
+	background-color: rgba($white, 0.1);
+
+	// Invert the colors in themes deemed dark.
+	.is-dark-theme & {
+		background-color: rgba($black, 0.1);
+	}
+
+	.components-placeholder__fieldset {
+		width: auto;
+	}
+
+	// Show placeholder buttons on block selection.
+	// Note that these can't be display: none; or visibility: hidden;, as that breaks the writing flow.
+	.components-placeholder__label,
+	.components-placeholder__instructions,
+	.components-button {
+		opacity: 0;
+		transition: opacity 0.1s linear;
+		@include reduce-motion("transition");
+	}
+
+	.is-selected > & {
+		.components-placeholder__label,
+		.components-placeholder__instructions,
+		.components-button {
+			opacity: 1;
+		}
+	}
+
+	// By painting the borders here, we enable them to be replaced by the Border control.
 	border: $border-width dashed currentColor;
-	box-sizing: border-box;
+	overflow: hidden;
+}
+
+// Position the spinner.
+// @todo these rules should ideally live with the spinner component itself.
+.components-placeholder__preview {
+	display: flex;
+	justify-content: center;
+}
+
+.components-placeholder__illustration {
+	box-sizing: content-box;
 	position: absolute;
-	top: 0;
-	right: 0;
-	bottom: 0;
-	left: 0;
+	top: 50%;
+	left: 50%;
+	transform: translate(-50%, -50%);
 	width: 100%;
 	height: 100%;
 	stroke: currentColor;
 	stroke-dasharray: 3;
-	opacity: 0.4;
 }

package/src/placeholder/test/index.tsx

@@ -0,0 +1,174 @@
+/**
+ * External dependencies
+ */
+import { render, screen, within } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useResizeObserver } from '@wordpress/compose';
+import { SVG, Path } from '@wordpress/primitives';
+
+/**
+ * Internal dependencies
+ */
+import BasePlaceholder from '../';
+import type { WordPressComponentProps } from '../../ui/context';
+import type { PlaceholderProps } from '../types';
+
+jest.mock( '@wordpress/compose', () => {
+	return {
+		...jest.requireActual( '@wordpress/compose' ),
+		useResizeObserver: jest.fn( () => [] ),
+	};
+} );
+
+/**
+ * Test icon that can be queried by `getByTestId`
+ */
+const testIcon = (
+	<SVG data-testid="icon">
+		<Path />
+	</SVG>
+);
+
+const Placeholder = (
+	props: Omit<
+		WordPressComponentProps< PlaceholderProps< unknown >, 'div', false >,
+		'ref'
+	>
+) => <BasePlaceholder data-testid="placeholder" { ...props } />;
+
+const getPlaceholder = () => screen.getByTestId( 'placeholder' );
+
+describe( 'Placeholder', () => {
+	beforeEach( () => {
+		// @ts-ignore
+		useResizeObserver.mockReturnValue( [
+			<div key="1" />,
+			{ width: 320 },
+		] );
+	} );
+
+	describe( 'basic rendering', () => {
+		it( 'should by default render label section and fieldset.', () => {
+			render( <Placeholder /> );
+			const placeholder = getPlaceholder();
+
+			expect( placeholder ).toHaveClass( 'components-placeholder' );
+
+			// Test for empty label. When the label is empty, the only way to
+			// query the div is with `querySelector`.
+			const label = placeholder.querySelector(
+				'.components-placeholder__label'
+			);
+			expect( label ).toBeInTheDocument();
+			expect( label ).toBeEmptyDOMElement();
+
+			// Test for non existent instructions. When the instructions is
+			// empty, the only way to query the div is with `querySelector`.
+			const placeholderInstructions = placeholder.querySelector(
+				'.components-placeholder__instructions'
+			);
+			expect( placeholderInstructions ).not.toBeInTheDocument();
+
+			// Test for empty fieldset.
+			const placeholderFieldset =
+				within( placeholder ).getByRole( 'group' );
+			expect( placeholderFieldset ).toBeInTheDocument();
+			expect( placeholderFieldset ).toBeEmptyDOMElement();
+		} );
+
+		it( 'should render an Icon in the label section', () => {
+			render( <Placeholder icon={ testIcon } /> );
+
+			const placeholder = getPlaceholder();
+			const icon = within( placeholder ).getByTestId( 'icon' );
+			expect( icon.parentNode ).toHaveClass(
+				'components-placeholder__label'
+			);
+			expect( icon ).toBeInTheDocument();
+		} );
+
+		it( 'should render a label section', () => {
+			const label = 'WordPress';
+			render( <Placeholder label={ label } /> );
+			const placeholderLabel = screen.getByText( label );
+
+			expect( placeholderLabel ).toHaveClass(
+				'components-placeholder__label'
+			);
+			expect( placeholderLabel ).toBeInTheDocument();
+		} );
+
+		it( 'should display a fieldset from the children property', () => {
+			const content = 'Fieldset';
+			render( <Placeholder>{ content }</Placeholder> );
+			const placeholderFieldset = screen.getByRole( 'group' );
+
+			expect( placeholderFieldset ).toBeInTheDocument();
+			expect( placeholderFieldset ).toHaveTextContent( content );
+		} );
+
+		it( 'should display a legend if instructions are passed', () => {
+			const instructions = 'Choose an option.';
+			render(
+				<Placeholder instructions={ instructions }>
+					<div>Fieldset</div>
+				</Placeholder>
+			);
+			const captionedFieldset = screen.getByRole( 'group', {
+				name: instructions,
+			} );
+
+			expect( captionedFieldset ).toBeInTheDocument();
+		} );
+
+		it( 'should add an additional className to the top container', () => {
+			render( <Placeholder className="wp-placeholder" /> );
+			const placeholder = getPlaceholder();
+
+			expect( placeholder ).toHaveClass( 'components-placeholder' );
+			expect( placeholder ).toHaveClass( 'wp-placeholder' );
+		} );
+
+		it( 'should add additional props to the top level container', () => {
+			render( <Placeholder data-test="test" /> );
+			const placeholder = getPlaceholder();
+
+			expect( placeholder ).toHaveAttribute( 'data-test', 'test' );
+		} );
+	} );
+
+	describe( 'resize aware', () => {
+		it( 'should not assign modifier class in first-pass `null` width from `useResizeObserver`', () => {
+			// @ts-ignore
+			useResizeObserver.mockReturnValue( [
+				<div key="1" />,
+				{ width: 480 },
+			] );
+
+			render( <Placeholder /> );
+			const placeholder = getPlaceholder();
+
+			expect( placeholder ).toHaveClass( 'is-large' );
+			expect( placeholder ).not.toHaveClass( 'is-medium' );
+			expect( placeholder ).not.toHaveClass( 'is-small' );
+		} );
+
+		it( 'should assign modifier class', () => {
+			// @ts-ignore
+			useResizeObserver.mockReturnValue( [
+				<div key="1" />,
+				{ width: null },
+			] );
+
+			render( <Placeholder /> );
+			const placeholder = getPlaceholder();
+
+			expect( placeholder ).not.toHaveClass( 'is-large' );
+			expect( placeholder ).not.toHaveClass( 'is-medium' );
+			expect( placeholder ).not.toHaveClass( 'is-small' );
+		} );
+	} );
+} );

package/src/placeholder/types.ts

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
+export type PlaceholderProps< IconProps = unknown > = {
+	/**
+	 * The children elements.
+	 */
+	children?: ReactNode;
+	/**
+	 * Class to set on the container div.
+	 */
+	className?: string;
+	/**
+	 * If provided, renders an icon next to the label.
+	 */
+	icon?: IconType< IconProps >;
+	/**
+	 * Instructions of the placeholder.
+	 */
+	instructions?: string;
+	/**
+	 * Changes placeholder children layout from flex-row to flex-column.
+	 */
+	isColumnLayout?: boolean;
+	/**
+	 * Title of the placeholder.
+	 */
+	label?: string;
+	/**
+	 * A rendered notices list
+	 */
+	notices?: ReactNode;
+	/**
+	 * Preview to be rendered in the placeholder.
+	 */
+	preview?: ReactNode;
+	/**
+	 * Outputs a placeholder illustration.
+	 */
+	withIllustration?: boolean;
+};

package/src/popover/README.md

@@ -71,6 +71,13 @@ Each of these base placements has an alignment in the form -start and -end. For
 -   Required: No
 -   Default: `"bottom-start"`
 
+### offset
+
+The distance (in pixels) between the anchor and popover.
+
+-   Type: `Number`
+-   Required: No
+
 ### children
 
 The content to be displayed within the popover.