@wordpress/components 20.0.2-next.957ca95e4c.0 → 21.0.1

package/src/number-control/stories/index.js

@@ -12,13 +12,12 @@ export default {
 	title: 'Components (Experimental)/NumberControl',
 	component: NumberControl,
 	argTypes: {
-		size: {
-			control: {
-				type: 'select',
-				options: [ 'default', 'small', '__unstable-large' ],
-			},
-		},
 		onChange: { action: 'onChange' },
+		prefix: { control: { type: 'text' } },
+		step: { control: { type: 'text' } },
+		suffix: { control: { type: 'text' } },
+		type: { control: { type: 'text' } },
+		value: { control: null },
 	},
 };
 
@@ -44,16 +43,5 @@ function Template( { onChange, ...props } ) {
 
 export const Default = Template.bind( {} );
 Default.args = {
-	disabled: false,
-	hideLabelFromVision: false,
-	isPressEnterToChange: false,
-	isShiftStepEnabled: true,
-	label: 'Number',
-	min: 0,
-	max: 100,
-	placeholder: '0',
-	required: false,
-	shiftStep: 10,
-	size: 'default',
-	step: '1',
+	label: 'Value',
 };

package/src/number-control/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Internal dependencies
+ */
+import type { InputControlProps } from '../input-control/types';
+
+export type NumberControlProps = Omit<
+	InputControlProps,
+	'isDragEnabled' | 'min' | 'max' | 'required' | 'step' | 'type' | 'value'
+> & {
+	/**
+	 * If true, the default `input` HTML arrows will be hidden.
+	 *
+	 * @default false
+	 */
+	hideHTMLArrows?: boolean;
+	/**
+	 * If true, enables mouse drag gestures.
+	 *
+	 * @default true
+	 */
+	isDragEnabled?: InputControlProps[ 'isDragEnabled' ];
+	/**
+	 * If true, pressing `UP` or `DOWN` along with the `SHIFT` key will increment the
+	 * value by the `shiftStep` value.
+	 *
+	 * @default true
+	 */
+	isShiftStepEnabled?: boolean;
+	/**
+	 * The maximum `value` allowed.
+	 *
+	 * @default Infinity
+	 */
+	max?: number;
+	/**
+	 * The minimum `value` allowed.
+	 *
+	 * @default -Infinity
+	 */
+	min?: number;
+	/**
+	 * If `true` enforces a valid number within the control's min/max range.
+	 * If `false` allows an empty string as a valid value.
+	 *
+	 * @default false
+	 */
+	required?: InputControlProps[ 'required' ];
+	/**
+	 * Amount to increment by when the `SHIFT` key is held down. This shift value is
+	 * a multiplier to the `step` value. For example, if the `step` value is `5`,
+	 * and `shiftStep` is `10`, each jump would increment/decrement by `50`.
+	 *
+	 * @default 10
+	 */
+	shiftStep?: number;
+	/**
+	 * Amount by which the `value` is changed when incrementing/decrementing.
+	 * It is also a factor in validation as `value` must be a multiple of `step`
+	 * (offset by `min`, if specified) to be valid. Accepts the special string value `any`
+	 * that voids the validation constraint and causes stepping actions to increment/decrement by `1`.
+	 *
+	 * @default 1
+	 */
+	step?: InputControlProps[ 'step' ];
+	/**
+	 * The `type` attribute of the `input` element.
+	 *
+	 * @default 'number'
+	 */
+	type?: InputControlProps[ 'type' ];
+	/**
+	 * The value of the input.
+	 */
+	value?: number | string;
+};

package/src/panel/README.md

@@ -176,7 +176,7 @@ The class that will be added with `components-panel__row`. to the classes of the
 
 PanelRow accepts a forwarded ref that will be added to the wrapper div. Usage:
 
-`<PanelRow className="edit-post-post-schedule" ref={ anchorRef }>`
+`<PanelRow className="edit-post-post-schedule" ref={ panelRowRef }>`
 
 ---
 

package/src/panel/test/__snapshots__/header.js.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`PanelHeader basic rendering should render PanelHeader with empty div inside 1`] = `
+<div>
+  <div
+    class="components-panel__header"
+  />
+</div>
+`;

package/src/panel/test/__snapshots__/index.js.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Panel basic rendering should render an additional className 1`] = `
+<div>
+  <div
+    class="the-panel components-panel"
+  />
+</div>
+`;
+
+exports[`Panel basic rendering should render an empty div without any provided props 1`] = `
+<div>
+  <div
+    class="components-panel"
+  />
+</div>
+`;

package/src/panel/test/__snapshots__/row.js.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`PanelRow should render with the custom class name 1`] = `
+<div>
+  <div
+    class="components-panel__row custom"
+  />
+</div>
+`;
+
+exports[`PanelRow should render with the default class name 1`] = `
+<div>
+  <div
+    class="components-panel__row"
+  />
+</div>
+`;

package/src/panel/test/header.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { shallow } from 'enzyme';
+import { render, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -11,38 +11,45 @@ import PanelHeader from '../header.js';
 describe( 'PanelHeader', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render PanelHeader with empty div inside', () => {
-			const panelHeader = shallow( <PanelHeader /> );
-			expect( panelHeader.hasClass( 'components-panel__header' ) ).toBe(
-				true
-			);
-			expect( panelHeader.type() ).toBe( 'div' );
-			expect(
-				panelHeader.find( 'div' ).shallow().children()
-			).toHaveLength( 0 );
+			const { container } = render( <PanelHeader /> );
+
+			expect( container ).toMatchSnapshot();
 		} );
 
 		it( 'should render a label matching the text provided in the prop', () => {
-			const panelHeader = shallow( <PanelHeader label="Some Text" /> );
-			const label = panelHeader.find( 'h2' ).shallow();
-			expect( label.text() ).toBe( 'Some Text' );
-			expect( label.type() ).toBe( 'h2' );
+			render( <PanelHeader label="Some Label" /> );
+
+			const heading = screen.getByRole( 'heading' );
+			expect( heading ).toBeVisible();
+			expect( heading ).toHaveTextContent( 'Some Label' );
 		} );
 
 		it( 'should render child elements in the panel header body when provided', () => {
-			const panelHeader = shallow( <PanelHeader children="Some Text" /> );
-			expect( panelHeader.text() ).toBe( 'Some Text' );
-			expect(
-				panelHeader.find( 'div' ).shallow().children()
-			).toHaveLength( 1 );
+			render(
+				<PanelHeader>
+					<dfn>Some text</dfn>
+				</PanelHeader>
+			);
+
+			const term = screen.getByRole( 'term' );
+			expect( term ).toBeVisible();
+			expect( term ).toHaveTextContent( 'Some text' );
 		} );
 
 		it( 'should render both child elements and label when passed in', () => {
-			const panelHeader = shallow(
-				<PanelHeader label="Some Label" children="Some Text" />
+			render(
+				<PanelHeader label="Some Label">
+					<dfn>Some text</dfn>
+				</PanelHeader>
 			);
-			expect(
-				panelHeader.find( 'div' ).shallow().children()
-			).toHaveLength( 2 );
+
+			const heading = screen.getByRole( 'heading' );
+			expect( heading ).toBeVisible();
+			expect( heading ).toHaveTextContent( 'Some Label' );
+
+			const term = screen.getByRole( 'term' );
+			expect( term ).toBeVisible();
+			expect( term ).toHaveTextContent( 'Some text' );
 		} );
 	} );
 } );

package/src/panel/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { shallow } from 'enzyme';
+import { render, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -11,43 +11,51 @@ import Panel from '../';
 describe( 'Panel', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render an empty div without any provided props', () => {
-			const panel = shallow( <Panel /> );
-			expect( panel.hasClass( 'components-panel' ) ).toBe( true );
-			expect( panel.type() ).toBe( 'div' );
-			expect( panel.find( 'div' ).shallow().children() ).toHaveLength(
-				0
-			);
+			const { container } = render( <Panel /> );
+
+			expect( container ).toMatchSnapshot();
 		} );
 
-		it( 'should render a PanelHeader component when provided text in the header prop', () => {
-			const panel = shallow( <Panel header="Header Label" /> );
-			const panelHeader = panel.find( 'PanelHeader' );
-			expect( panelHeader.prop( 'label' ) ).toBe( 'Header Label' );
-			expect( panel.find( 'div' ).shallow().children() ).toHaveLength(
-				1
-			);
+		it( 'should render a heading when provided text in the header prop', () => {
+			render( <Panel header="Header Label" /> );
+
+			const heading = screen.getByRole( 'heading' );
+			expect( heading ).toBeVisible();
+			expect( heading ).toHaveTextContent( 'Header Label' );
 		} );
 
 		it( 'should render an additional className', () => {
-			const panel = shallow( <Panel className="the-panel" /> );
-			expect( panel.hasClass( 'the-panel' ) ).toBe( true );
+			const { container } = render( <Panel className="the-panel" /> );
+
+			expect( container ).toMatchSnapshot();
 		} );
 
 		it( 'should add additional child elements to be rendered in the panel', () => {
-			const panel = shallow( <Panel children="The Panel" /> );
-			expect( panel.text() ).toBe( 'The Panel' );
-			expect( panel.find( 'div' ).shallow().children() ).toHaveLength(
-				1
+			render(
+				<Panel>
+					<dfn>The Panel</dfn>
+				</Panel>
 			);
+
+			const term = screen.getByRole( 'term' );
+			expect( term ).toBeVisible();
+			expect( term ).toHaveTextContent( 'The Panel' );
 		} );
 
 		it( 'should render both children and header when provided as props', () => {
-			const panel = shallow(
-				<Panel children="The Panel" header="The Header" />
-			);
-			expect( panel.find( 'div' ).shallow().children() ).toHaveLength(
-				2
+			render(
+				<Panel header="The header">
+					<dfn>The Panel</dfn>
+				</Panel>
 			);
+
+			const heading = screen.getByRole( 'heading' );
+			expect( heading ).toBeVisible();
+			expect( heading ).toHaveTextContent( 'The header' );
+
+			const term = screen.getByRole( 'term' );
+			expect( term ).toBeVisible();
+			expect( term ).toHaveTextContent( 'The Panel' );
 		} );
 	} );
 } );

package/src/panel/test/row.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { shallow } from 'enzyme';
+import { render, screen } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -9,20 +9,27 @@ import { shallow } from 'enzyme';
 import PanelRow from '../row';
 
 describe( 'PanelRow', () => {
-	it( 'should defined default class name', () => {
-		const wrapper = shallow( <PanelRow /> );
-		expect( wrapper.hasClass( 'components-panel__row' ) ).toBe( true );
+	it( 'should render with the default class name', () => {
+		const { container } = render( <PanelRow /> );
+
+		expect( container ).toMatchSnapshot();
 	} );
-	it( 'should defined custom class name', () => {
-		const wrapper = shallow( <PanelRow className="custom" /> );
-		expect( wrapper.hasClass( 'custom' ) ).toBe( true );
+
+	it( 'should render with the custom class name', () => {
+		const { container } = render( <PanelRow className="custom" /> );
+
+		expect( container ).toMatchSnapshot();
 	} );
-	it( 'should return child components', () => {
-		const wrapper = shallow(
+
+	it( 'should render child components', () => {
+		render(
 			<PanelRow>
-				<p>children</p>
+				<dfn>Some text</dfn>
 			</PanelRow>
 		);
-		expect( wrapper.find( 'p' ).text() ).toBe( 'children' );
+
+		const term = screen.getByRole( 'term' );
+		expect( term ).toBeVisible();
+		expect( term ).toHaveTextContent( 'Some text' );
 	} );
 } );

package/src/placeholder/index.tsx

@@ -39,11 +39,10 @@ const PlaceholderIllustration = (
  * ```
  */
 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'
+	props: WordPressComponentProps<
+		PlaceholderProps< IconProps >,
+		'div',
+		false
 	>
 ) {
 	const {

package/src/placeholder/style.scss

@@ -189,6 +189,10 @@
 
 	.components-placeholder__fieldset {
 		width: auto;
+
+		// Unset intrinsic margins.
+		margin-left: 0;
+		margin-right: 0;
 	}
 
 	// Show placeholder buttons on block selection.

package/src/popover/README.md

@@ -1,10 +1,14 @@
 # Popover
 
-Popover is a React component to render a floating content modal. It is similar in purpose to a tooltip, but renders content of any sort, not only simple text. It anchors itself to its parent node, optionally by a specified direction. If the popover exceeds the bounds of the page in the direction it opens, its position will be flipped automatically.
+`Popover` renders its content in a floating modal. If no explicit anchor is passed via props, it anchors to its parent element by default.
+
+The behavior of the popover when it exceeds the viewport's edges can be controlled via its props.
 
 ## Usage
 
-Render a Popover within the parent to which it should anchor:
+Render a Popover within the parent to which it should anchor.
+
+If a Popover is returned by your component, it will be shown. To hide the popover, simply omit it from your component's render value.
 
 ```jsx
 import { Button, Popover } from '@wordpress/components';
@@ -25,7 +29,36 @@ const MyPopover = () => {
 };
 ```
 
-If a Popover is returned by your component, it will be shown. To hide the popover, simply omit it from your component's render value.
+In order to pass an explicit anchor, you can use the `anchor` prop. When doing so, **the anchor element should be stored in local state** rather than a plain React ref to ensure reactive updating when it changes.
+
+```jsx
+import { Button, Popover } from '@wordpress/components';
+import { useState } from '@wordpress/element';
+
+const MyPopover = () => {
+	// Use internal state instead of a ref to make sure that the component
+	// re-renders when the popover's anchor updates.
+	const [ popoverAnchor, setPopoverAnchor ] = useState();
+	const [ isVisible, setIsVisible ] = useState( false );
+	const toggleVisible = () => {
+		setIsVisible( ( state ) => ! state );
+	};
+
+	return (
+		<p ref={ setPopoverAnchor }>Popover s anchor</p>
+		<Button variant="secondary" onClick={ toggleVisible }>
+			Toggle Popover!
+		</Button>
+		{ isVisible && (
+			<Popover
+				anchor={ popoverAnchor }
+			>
+				Popover is toggled!
+			</Popover>
+		) }
+	);
+};
+```
 
 If you want Popover elements to render to a specific location on the page to allow style cascade to take effect, you must render a `Popover.Slot` further up the element tree:
 
@@ -49,102 +82,149 @@ render(
 
 The component accepts the following props. Props not included in this set will be applied to the element wrapping Popover content.
 
-### focusOnMount
+### `anchor`: `Element | VirtualElement | null`
 
-By default, the _first tabblable element_ in the popover will receive focus when it mounts. This is the same as setting `focusOnMount` to `"firstElement"`. If you want to focus the container instead, you can set `focusOnMount` to `"container"`.
+The element that should be used by the `Popover` as its anchor. It can either be an `Element` or, alternatively, a `VirtualElement` — ie. an object with the `getBoundingClientRect()` and the `ownerDocument` properties defined.
 
-Set this prop to `false` to disable focus changing entirely. This should only be set when an appropriately accessible substitute behavior exists.
+The element should be stored in state rather than a plain ref to ensure reactive updating when it changes.
 
--   Type: `String` or `Boolean`
 -   Required: No
--   Default: `"firstElement"`
 
-### placement
+### `anchorRect`: `DomRectWithOwnerDocument`
+
+_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+
+An object extending a `DOMRect` with an additional optional `ownerDocument` property, used to specify a fixed popover position.
 
-The direction in which the popover should open relative to its parent node or anchor node.
+-   Required: No
+
+### `anchorRef`: `Element | PopoverAnchorRefReference | PopoverAnchorRefTopBottom | Range`
 
-The available base placements are 'top', 'right', 'bottom', 'left'.
+_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
 
-Each of these base placements has an alignment in the form -start and -end. For example, 'right-start', or 'bottom-end'. These allow you to align the tooltip to the edges of the button, rather than centering it.
+Used to specify a fixed popover position. It can be an `Element`, a React reference to an `element`, an object with a `top` and a `bottom` properties (both pointing to elements), or a `range`.
 
--   Type: `String`
 -   Required: No
--   Default: `"bottom-start"`
 
-### offset
+### `animate`: `boolean`
 
-The distance (in pixels) between the anchor and popover.
+Whether the popover should animate when opening.
 
--   Type: `Number`
 -   Required: No
+-   Default: `true`
 
-### children
+### `children`: `ReactNode`
 
-The content to be displayed within the popover.
+The `children` elements rendered as the popover's content.
 
--   Type: `Element`
 -   Required: Yes
 
-### className
+### `expandOnMobile`: `boolean`
 
-An optional additional class name to apply to the rendered popover.
+Show the popover fullscreen on mobile viewports.
 
--   Type: `String`
 -   Required: No
 
-### onClose
+### `flip`: `boolean`
 
-A callback invoked when the popover should be closed.
+Specifies whether the popover should flip across its axis if there isn't space for it in the normal placement.
+
+When the using a 'top' placement, the popover will switch to a 'bottom' placement. When using a 'left' placement, the popover will switch to a `right' placement.
+
+The popover will retain its alignment of 'start' or 'end' when flipping.
+
+-   Required: No
+-   Default: `true`
+
+### `focusOnMount`: `'firstElement' | boolean`
+
+By default, the _first tabbable element_ in the popover will receive focus when it mounts. This is the same as setting this prop to `"firstElement"`.
+
+Specifying a `true` value will focus the container instead.
+
+Specifying a `false` value disables the focus handling entirely (this should only be done when an appropriately accessible substitute behavior exists).
 
--   Type: `Function`
 -   Required: No
+-   Default: `"firstElement"`
 
-### onFocusOutside
+### `onFocusOutside`: `( event: SyntheticEvent ) => void`
 
-A callback invoked when the focus leaves the opened popover. This should only be provided in advanced use-cases when a Popover should close under specific circumstances; for example, if the new `document.activeElement` is content of or otherwise controlling Popover visibility.
+A callback invoked when the focus leaves the opened popover. This should only be provided in advanced use-cases when a popover should close under specific circumstances (for example, if the new `document.activeElement` is content of or otherwise controlling popover visibility).
 
-Defaults to `onClose` when not provided.
+When not provided, the `onClose` callback will be called instead.
 
--   Type: `Function`
 -   Required: No
 
-### expandOnMobile
+### `getAnchorRect`: `( fallbackReferenceElement: Element | null ) => DomRectWithOwnerDocument`
 
-Opt-in prop to show popovers fullscreen on mobile, pass `false` in this prop to avoid this behavior.
+_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+
+A function returning the same value as the one expected by the `anchorRect` prop, used to specify a dynamic popover position.
 
--   Type: `Boolean`
 -   Required: No
--   Default: `false`
 
-### headerTitle
+### `headerTitle`: `string`
 
-Set this to customize the text that is shown in popover's header when it is fullscreen on mobile.
+Used to customize the header text shown when the popover is toggled to fullscreen on mobile viewports (see the `expandOnMobile` prop).
 
--   Type: `String`
 -   Required: No
 
-### noArrow
+### `isAlternate`: `boolean`
 
-Set this to hide the arrow which visually indicates what the popover is anchored to. Note that the arrow will not display if `position` is set to `"middle center"`.
+Used to enable a different visual style for the popover.
+
+-   Required: No
+
+### `noArrow`: `boolean`
+
+Used to show/hide the arrow that points at the popover's anchor.
 
--   Type: `Boolean`
 -   Required: No
 -   Default: `true`
 
-### anchorRect
+### `offset`: `number`
+
+The distance (in px) between the anchor and the popover.
 
-A custom `DOMRect` object at which to position the popover. `anchorRect` is used when the position (custom `DOMRect` object) of the popover needs to be fixed at one location all the time.
+-   Required: No
+
+### `onClose`: `() => void`
+
+A callback invoked when the popover should be closed.
 
--   Type: `DOMRect`
 -   Required: No
 
-### getAnchorRect
+### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
 
-A callback function which is used to override the anchor value computation algorithm. `anchorRect` will take precedence over this prop, if both are passed together.
+Used to specify the popover's position with respect to its anchor.
+
+-   Required: No
+-   Default: `"bottom-start"`
+
+### `position`: `[yAxis] [xAxis] [optionalCorner]`
+
+_Note: use the `placement` prop instead when possible._
+
+Legacy way to specify the popover's position with respect to its anchor.
+
+Possible values:
+
+- `yAxis`: `'top' | 'middle' | 'bottom'`
+- `xAxis`: `'left' | 'center' | 'right'`
+- `corner`: `'top' | 'right' | 'bottom' | 'left'`
+
+
+-   Required: No
+
+### `resize`: `boolean`
+
+Adjusts the size of the popover to prevent its contents from going out of view when meeting the viewport edges.
+
+-   Required: No
+-   Default: `true`
 
-If you need the `DOMRect` object i.e., the position of popover to be calculated on every time, the popover re-renders, then use `getAnchorRect`.
+### `range`: `unknown`
 
-`getAnchorRect` callback function receives a reference to the popover anchor element as a function parameter and it should return a `DOMRect` object. Noting that `getAnchorRect` can be called with `null`.
+_Note: this prop is deprecated and will be removed in WordPress 6.3. It has no effect on the component._
 
--   Type: `Function`
 -   Required: No