@wordpress/components 19.9.0 → 19.12.0

package/src/popover/style.scss

@@ -1,222 +1,41 @@
-$arrow-size: 8px;
-
-/*!rtl:begin:ignore*/
 .components-popover {
-	position: fixed;
 	z-index: z-index(".components-popover");
-	top: 0;
-	left: 0;
-
-	// Hide the popover element until the position has been calculated. The position
-	// cannot be calculated until the popover element is rendered because the
-	// position depends on the size of the popover.
-	opacity: 0;
-
-	&.is-expanded,
-	&[data-x-axis][data-y-axis] {
-		opacity: 1;
-	}
 
 	&.is-expanded {
+		position: fixed;
 		top: 0;
 		left: 0;
 		right: 0;
 		bottom: 0;
 		z-index: z-index(".components-popover") !important;
 	}
-
-	&:not(.is-without-arrow) {
-		margin-left: 2px;
-
-		&::before {
-			border: $arrow-size solid $gray-400;
-		}
-
-		&.is-alternate::before {
-			border-color: $gray-900;
-		}
-
-		&::after {
-			border: $arrow-size solid $white;
-		}
-
-		&::before,
-		&::after {
-			content: "";
-			position: absolute;
-			height: 0;
-			width: 0;
-			line-height: 0;
-		}
-
-		&[data-y-axis="top"] {
-			margin-top: - $arrow-size;
-
-			&::before {
-				bottom: - $arrow-size;
-			}
-
-			&::after {
-				bottom: -6px;
-			}
-
-			&::before,
-			&::after {
-				border-bottom: none;
-				border-left-color: transparent;
-				border-right-color: transparent;
-				border-top-style: solid;
-				margin-left: -10px;
-			}
-		}
-
-		&[data-y-axis="bottom"] {
-			margin-top: $arrow-size;
-
-			&::before {
-				top: -$arrow-size;
-			}
-
-			&::after {
-				top: -6px;
-			}
-
-			&::before,
-			&::after {
-				border-bottom-style: solid;
-				border-left-color: transparent;
-				border-right-color: transparent;
-				border-top: none;
-				margin-left: -10px;
-			}
-		}
-
-		&[data-y-axis="middle"][data-x-axis="left"] {
-			margin-left: -$arrow-size;
-
-			&::before {
-				right: -$arrow-size;
-			}
-
-			&::after {
-				right: -6px;
-			}
-
-			&::before,
-			&::after {
-				border-bottom-color: transparent;
-				border-left-style: solid;
-				border-right: none;
-				border-top-color: transparent;
-			}
-		}
-
-		&[data-y-axis="middle"][data-x-axis="right"] {
-			margin-left: $arrow-size;
-
-			&::before {
-				left: -$arrow-size;
-			}
-
-			&::after {
-				left: -6px;
-			}
-
-			&::before,
-			&::after {
-				border-bottom-color: transparent;
-				border-left: none;
-				border-right-style: solid;
-				border-top-color: transparent;
-			}
-		}
-	}
-
-	&[data-y-axis="top"] {
-		bottom: 100%;
-	}
-
-	&[data-y-axis="bottom"] {
-		top: 100%;
-	}
-
-	&[data-y-axis="middle"] {
-		align-items: center;
-		display: flex;
-	}
-
-	// Add spacing.
-	&.is-from-top {
-		margin-top: $grid-unit-15;
-	}
-
-	&.is-from-bottom {
-		margin-top: -$grid-unit-15;
-	}
-
-	&.is-from-left:not(.is-from-top):not(.is-from-bottom) {
-		margin-left: $grid-unit-15;
-	}
-
-	&.is-from-right:not(.is-from-top):not(.is-from-bottom) {
-		margin-right: $grid-unit-15;
-	}
 }
 
 .components-popover__content {
-	height: 100%;
 	background: $white;
-	border: $border-width solid $gray-400;
+	// Using outline instead of border to avoid impacting
+	// popover computations.
+	outline: $border-width solid $gray-400;
 	box-shadow: $shadow-popover;
 	border-radius: $radius-block-ui;
+	box-sizing: border-box;
+	width: min-content;
 
 	// Alternate treatment for popovers that put them at elevation zero with high contrast.
 	.is-alternate & {
-		border: $border-width solid $gray-900;
+		outline: $border-width solid $gray-900;
 		box-shadow: none;
 	}
 
-	.components-popover & {
-		position: absolute;
-		height: auto;
-		overflow-y: auto;
-	}
-
 	.components-popover.is-expanded & {
 		position: static;
 		height: calc(100% - #{ $panel-header-height });
 		overflow-y: visible;
 		min-width: auto;
 		border: none;
+		outline: none;
 		border-top: $border-width solid $gray-900;
 	}
-
-	.components-popover[data-y-axis="top"] & {
-		bottom: 100%;
-	}
-
-	.components-popover[data-x-axis="center"] & {
-		left: 50%;
-		transform: translateX(-50%);
-	}
-
-	.components-popover[data-x-axis="right"] & {
-		position: absolute;
-		left: 100%;
-	}
-
-	.components-popover:not([data-y-axis="middle"])[data-x-axis="right"] & {
-		margin-left: -($grid-unit-30 + $border-width);
-	}
-
-	.components-popover[data-x-axis="left"] & {
-		position: absolute;
-		right: 100%;
-	}
-
-	.components-popover:not([data-y-axis="middle"])[data-x-axis="left"] & {
-		margin-right: -($grid-unit-30 + $border-width);
-	}
 }
 
 .components-popover__header {
@@ -238,4 +57,15 @@ $arrow-size: 8px;
 .components-popover__close.components-button {
 	z-index: z-index(".components-popover__close");
 }
-/*!rtl:end:ignore*/
+
+.components-popover__arrow {
+	position: absolute;
+	background: $gray-400;
+	width: 8px;
+	height: 8px;
+	transform: rotate(45deg);
+	z-index: -1;
+	.is-alternate & {
+		background: $gray-900;
+	}
+}

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

@@ -3,21 +3,15 @@
 exports[`Popover should pass additional props to portaled element 1`] = `
 <span>
   <div
-    class="components-popover components-animate__appear is-from-top is-from-left is-without-arrow"
-    data-x-axis="right"
-    data-y-axis="bottom"
+    class="components-popover components-animate__appear is-from-left is-from-top"
     role="tooltip"
-    style="top: 0px; left: 0px;"
+    style="position: absolute;"
     tabindex="-1"
   >
     <div
       class="components-popover__content"
     >
-      <div
-        style="position: relative;"
-      >
-        Hello
-      </div>
+      Hello
     </div>
   </div>
 </span>
@@ -26,20 +20,14 @@ exports[`Popover should pass additional props to portaled element 1`] = `
 exports[`Popover should render content 1`] = `
 <span>
   <div
-    class="components-popover components-animate__appear is-from-top is-from-left is-without-arrow"
-    data-x-axis="right"
-    data-y-axis="bottom"
-    style="top: 0px; left: 0px;"
+    class="components-popover components-animate__appear is-from-left is-from-top"
+    style="position: absolute;"
     tabindex="-1"
   >
     <div
       class="components-popover__content"
     >
-      <div
-        style="position: relative;"
-      >
-        Hello
-      </div>
+      Hello
     </div>
   </div>
 </span>

package/src/query-controls/README.md

@@ -179,7 +179,7 @@ A function that receives the new author value. If this is not specified, the aut
 
 #### onCategoryChange
 
-A function that receives the new author value. If this is not specified, the category controls are not included.
+A function that receives the new category value. If this is not specified, the category controls are not included.
 
 -   Type: `Function`
 -   Required: No

package/src/resizable-box/resize-tooltip/utils.ts

@@ -2,12 +2,12 @@
  * External dependencies
  */
 import { noop } from 'lodash';
-import useResizeAware from 'react-resize-aware';
 
 /**
  * WordPress dependencies
  */
 import { useEffect, useRef, useState } from '@wordpress/element';
+import { useResizeObserver } from '@wordpress/compose';
 
 const { clearTimeout, setTimeout } = window;
 
@@ -56,11 +56,10 @@ export function useResizeLabel( {
 	showPx = false,
 }: UseResizeLabelArgs ): UseResizeLabelProps {
 	/*
-	 * The width/height values derive from this special useResizeAware hook.
-	 * This custom hook uses injects an iFrame into the element, allowing it
-	 * to tap into the onResize (window) callback events.
+	 * The width/height values derive from this special useResizeObserver hook.
+	 * This custom hook uses the ResizeObserver API to listen for resize events.
 	 */
-	const [ resizeListener, sizes ] = useResizeAware();
+	const [ resizeListener, sizes ] = useResizeObserver();
 
 	/*
 	 * Indicates if the x/y axis is preferred.

package/src/sandbox/index.native.js

@@ -110,7 +110,7 @@ const style = `
 	/**
 	 * Add responsiveness to embeds with aspect ratios.
 	 *
-	 * These styles have been copied from the web version (https://git.io/JEFcX) and
+	 * These styles have been copied from the web version (https://github.com/WordPress/gutenberg/blob/7901895ca20cf61e402925e31571d659dab64721/packages/block-library/src/embed/style.scss#L42-L89) and
 	 * adapted for the native version.
 	 */
 	.wp-has-aspect-ratio.wp-block-embed__wrapper::before {

package/src/search-control/index.js

@@ -6,17 +6,16 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { useInstanceId } from '@wordpress/compose';
+import { useInstanceId, useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import { Icon, search, closeSmall } from '@wordpress/icons';
-import { forwardRef } from '@wordpress/element';
+import { forwardRef, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import { Button } from '../';
 import BaseControl from '../base-control';
-import { useCombinedRef } from '../utils';
 
 function SearchControl(
 	{
@@ -30,10 +29,10 @@ function SearchControl(
 		help,
 		onClose,
 	},
-	ref
+	forwardedRef
 ) {
+	const searchRef = useRef();
 	const instanceId = useInstanceId( SearchControl );
-	const searchInput = useCombinedRef( ref );
 	const id = `components-search-control-${ instanceId }`;
 
 	const renderRightButton = () => {
@@ -54,7 +53,7 @@ function SearchControl(
 					label={ __( 'Reset search' ) }
 					onClick={ () => {
 						onChange( '' );
-						searchInput.current.focus();
+						searchRef.current.focus();
 					} }
 				/>
 			);
@@ -73,7 +72,7 @@ function SearchControl(
 		>
 			<div className="components-search-control__input-wrapper">
 				<input
-					ref={ searchInput }
+					ref={ useMergeRefs( [ searchRef, forwardedRef ] ) }
 					className="components-search-control__input"
 					id={ id }
 					type="search"

package/src/select-control/README.md

@@ -98,6 +98,7 @@ const MySelectControl = () => {
 				{ label: 'Small', value: '25%' },
 			] }
 			onChange={ ( newSize ) => setSize( newSize ) }
+			__nextHasNoMarginBottom
 		/>
 	);
 };
@@ -114,11 +115,12 @@ Render a user interface to select multiple users from a list.
 		this.setState( { users } );
 	} }
 	options={ [
-		{ value: null, label: 'Select a User', disabled: true },
+		{ value: '', label: 'Select a User', disabled: true },
 		{ value: 'a', label: 'User A' },
 		{ value: 'b', label: 'User B' },
 		{ value: 'c', label: 'User c' },
 	] }
+	__nextHasNoMarginBottom
 />
 ```
 
@@ -133,6 +135,7 @@ const [ item, setItem ] = useState( '' );
     label={ __( 'Select an item:' ) }
     value={ item } // e.g: value = 'a'
     onChange={ ( selection ) => { setItem( selection ) } }
+    __nextHasNoMarginBottom
 >
 	<optgroup label="Theropods">
 		<option value="Tyrannosaurus">Tyrannosaurus</option>
@@ -194,7 +197,7 @@ If this property is added, multiple values can be selected. The value passed sho
 An array of objects containing the following properties:
 
 -   `label`: (string) The label to be shown to the user.
--   `value`: (Object) The internal value used to choose the selected value. This is also the value passed to onChange when the option is selected.
+-   `value`: (string) The internal value used to choose the selected value. This is also the value passed to onChange when the option is selected.
 -   `disabled`: (boolean) Whether or not the option should have the disabled attribute.
 -   Type: `Array`
 -   Required: No
@@ -215,6 +218,14 @@ If multiple is false the value received is a single value with the new selected
 -   Type: `function`
 -   Required: Yes
 
+### __nextHasNoMarginBottom
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
+
 ## Related components
 
 -   To select one option from a set, and you want to show them all the available options at once, use the `Radio` component.

package/src/select-control/index.tsx

@@ -3,7 +3,7 @@
  */
 import { isEmpty, noop } from 'lodash';
 import classNames from 'classnames';
-import type { ChangeEvent, FocusEvent, ReactNode, ForwardedRef } from 'react';
+import type { ChangeEvent, FocusEvent, ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -17,10 +17,9 @@ import { Icon, chevronDown } from '@wordpress/icons';
  */
 import BaseControl from '../base-control';
 import InputBase from '../input-control/input-base';
-import type { InputBaseProps, LabelPosition } from '../input-control/types';
 import { Select, DownArrowWrapper } from './styles/select-control-styles';
-import type { Size } from './types';
 import type { WordPressComponentProps } from '../ui/context';
+import type { SelectControlProps } from './types';
 
 function useUniqueId( idProp?: string ) {
 	const instanceId = useInstanceId( SelectControl );
@@ -29,30 +28,7 @@ function useUniqueId( idProp?: string ) {
 	return idProp || id;
 }
 
-export interface SelectControlProps
-	extends Omit< InputBaseProps, 'children' | 'isFocused' > {
-	help?: string;
-	hideLabelFromVision?: boolean;
-	multiple?: boolean;
-	onBlur?: ( event: FocusEvent< HTMLSelectElement > ) => void;
-	onFocus?: ( event: FocusEvent< HTMLSelectElement > ) => void;
-	onChange?: (
-		value: string | string[],
-		extra?: { event?: ChangeEvent< HTMLSelectElement > }
-	) => void;
-	options?: {
-		label: string;
-		value: string;
-		id?: string;
-		disabled?: boolean;
-	}[];
-	size?: Size;
-	value?: string | string[];
-	labelPosition?: LabelPosition;
-	children?: ReactNode;
-}
-
-function SelectControl(
+function UnforwardedSelectControl(
 	{
 		className,
 		disabled = false,
@@ -71,6 +47,7 @@ function SelectControl(
 		children,
 		prefix,
 		suffix,
+		__nextHasNoMarginBottom = false,
 		...props
 	}: WordPressComponentProps< SelectControlProps, 'select', false >,
 	ref: ForwardedRef< HTMLSelectElement >
@@ -109,7 +86,11 @@ function SelectControl(
 
 	/* eslint-disable jsx-a11y/no-onchange */
 	return (
-		<BaseControl help={ help } id={ id }>
+		<BaseControl
+			help={ help }
+			id={ id }
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+		>
 			<InputBase
 				className={ classes }
 				disabled={ disabled }
@@ -165,6 +146,31 @@ function SelectControl(
 	/* eslint-enable jsx-a11y/no-onchange */
 }
 
-const ForwardedComponent = forwardRef( SelectControl );
+/**
+ * `SelectControl` allows users to select from a single or multiple option menu.
+ * It functions as a wrapper around the browser's native `<select>` element.
+ *
+ * @example
+ * import { SelectControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MySelectControl = () => {
+ *   const [ size, setSize ] = useState( '50%' );
+ *
+ *   return (
+ *     <SelectControl
+ *       label="Size"
+ *       value={ size }
+ *       options={ [
+ *         { label: 'Big', value: '100%' },
+ *         { label: 'Medium', value: '50%' },
+ *         { label: 'Small', value: '25%' },
+ *       ] }
+ *       onChange={ setSize }
+ *     />
+ *   );
+ * };
+ */
+export const SelectControl = forwardRef( UnforwardedSelectControl );
 
-export default ForwardedComponent;
+export default SelectControl;

package/src/select-control/stories/index.tsx

@@ -0,0 +1,90 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { ComponentProps } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import SelectControl from '..';
+
+const meta: ComponentMeta< typeof SelectControl > = {
+	title: 'Components/SelectControl',
+	component: SelectControl,
+	argTypes: {
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+		prefix: { control: { type: 'text' } },
+		suffix: { control: { type: 'text' } },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const SelectControlWithState: ComponentStory< typeof SelectControl > = (
+	args
+) => {
+	const [ selection, setSelection ] = useState<
+		ComponentProps< typeof SelectControl >[ 'value' ]
+	>();
+
+	return (
+		<SelectControl
+			{ ...args }
+			value={ selection }
+			onChange={ setSelection }
+		/>
+	);
+};
+
+export const Default = SelectControlWithState.bind( {} );
+Default.args = {
+	options: [
+		{ value: '', label: 'Select an Option', disabled: true },
+		{ value: 'a', label: 'Option A' },
+		{ value: 'b', label: 'Option B' },
+		{ value: 'c', label: 'Option C' },
+	],
+};
+
+export const WithLabelAndHelpText = SelectControlWithState.bind( {} );
+WithLabelAndHelpText.args = {
+	...Default.args,
+	help: 'Help text to explain the select control.',
+	label: 'Value',
+};
+
+/**
+ * As an alternative to the `options` prop, `optgroup`s and `options` can be
+ * passed in as `children` for more customizability.
+ */
+export const WithCustomChildren: ComponentStory< typeof SelectControl > = (
+	args
+) => {
+	return (
+		<SelectControlWithState { ...args }>
+			<option value="option-1">Option 1</option>
+			<option value="option-2" disabled>
+				Option 2 - Disabled
+			</option>
+			<optgroup label="Option Group 1">
+				<option value="option-group-1-option-1">
+					Option Group 1 - Option 1
+				</option>
+				<option value="option-group-1-option-2" disabled>
+					Option Group 1 - Option 2 - Disabled
+				</option>
+			</optgroup>
+		</SelectControlWithState>
+	);
+};