@wordpress/components 23.3.1 → 23.4.0

package/src/popover/utils.ts

@@ -74,7 +74,7 @@ const POSITION_TO_PLACEMENT: Record<
  * Converts the `Popover`'s legacy "position" prop to the new "placement" prop
  * (used by `floating-ui`).
  *
- * @param  position The legacy position
+ * @param position The legacy position
  * @return The corresponding placement
  */
 export const positionToPlacement = (
@@ -105,13 +105,14 @@ const PLACEMENT_TO_ANIMATION_ORIGIN: Record<
 	left: { originX: 1, originY: 0.5 }, // open from middle, right
 	'left-start': { originX: 1, originY: 0 }, // open from top, right
 	'left-end': { originX: 1, originY: 1 }, // open from bottom, right
+	overlay: { originX: 0.5, originY: 0.5 }, // open from center, center
 };
 
 /**
  * Given the floating-ui `placement`, compute the framer-motion props for the
  * popover's entry animation.
  *
- * @param  placement A placement string from floating ui
+ * @param placement A placement string from floating ui
  * @return The object containing the motion props
  */
 export const placementToMotionAnimationProps = (
@@ -141,7 +142,7 @@ export const placementToMotionAnimationProps = (
 /**
  * Returns the offset of a document's frame element.
  *
- * @param  document The iframe's owner document.
+ * @param document The iframe's owner document.
  *
  * @return The offset of the document's frame element, or undefined if the
  * document has no frame element.
@@ -157,6 +158,23 @@ export const getFrameOffset = (
 	return { x: iframeRect.left, y: iframeRect.top };
 };
 
+export const getFrameScale = (
+	document?: Document
+): {
+	x: number;
+	y: number;
+} => {
+	const frameElement = document?.defaultView?.frameElement as HTMLElement;
+	if ( ! frameElement ) {
+		return { x: 1, y: 1 };
+	}
+	const rect = frameElement.getBoundingClientRect();
+	return {
+		x: rect.width / frameElement.offsetWidth,
+		y: rect.height / frameElement.offsetHeight,
+	};
+};
+
 export const getReferenceOwnerDocument = ( {
 	anchor,
 	anchorRef,
@@ -213,11 +231,13 @@ export const getReferenceElement = ( {
 	anchorRect,
 	getAnchorRect,
 	fallbackReferenceElement,
+	scale,
 }: Pick<
 	PopoverProps,
 	'anchorRef' | 'anchorRect' | 'getAnchorRect' | 'anchor'
 > & {
 	fallbackReferenceElement: Element | null;
+	scale: { x: number; y: number };
 } ): ReferenceType | null => {
 	let referenceElement = null;
 
@@ -279,6 +299,22 @@ export const getReferenceElement = ( {
 		referenceElement = fallbackReferenceElement.parentElement;
 	}
 
+	if ( referenceElement && ( scale.x !== 1 || scale.y !== 1 ) ) {
+		// If the popover is inside an iframe, the coordinates of the
+		// reference element need to be scaled to match the iframe's scale.
+		const rect = referenceElement.getBoundingClientRect();
+		referenceElement = {
+			getBoundingClientRect() {
+				return new window.DOMRect(
+					rect.x * scale.x,
+					rect.y * scale.y,
+					rect.width * scale.x,
+					rect.height * scale.y
+				);
+			},
+		};
+	}
+
 	// Convert any `undefined` value to `null`.
 	return referenceElement ?? null;
 };

package/src/private-apis.js

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+/**
+ * Internal dependencies
+ */
+import { default as CustomSelectControl } from './custom-select-control';
+import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+		'@wordpress/components'
+	);
+
+export const privateApis = {};
+lock( privateApis, {
+	CustomSelectControl,
+	__experimentalPopoverLegacyPositionToPlacement,
+} );

package/src/query-controls/terms.ts

@@ -16,7 +16,7 @@ import type {
 /**
  * Returns terms in a tree form.
  *
- * @param  flatTerms Array of terms in flat format.
+ * @param flatTerms Array of terms in flat format.
  *
  * @return Terms in tree format.
  */

package/src/range-control/utils.ts

@@ -14,9 +14,9 @@ import type { UseControlledRangeValueArgs } from './types';
 /**
  * A float supported clamp function for a specific value.
  *
- * @param  value The value to clamp.
- * @param  min   The minimum value.
- * @param  max   The maximum value.
+ * @param value The value to clamp.
+ * @param min   The minimum value.
+ * @param max   The maximum value.
  *
  * @return A (float) number
  */
@@ -31,7 +31,7 @@ export function floatClamp( value: number | null, min: number, max: number ) {
 /**
  * Hook to store a clamped value, derived from props.
  *
- * @param  settings
+ * @param settings
  * @return The controlled value and the value setter.
  */
 export function useControlledRangeValue(

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

@@ -34,12 +34,12 @@ interface UseResizeLabelArgs {
  * Custom hook that manages resize listener events. It also provides a label
  * based on current resize width x height values.
  *
- * @param  props
- * @param  props.axis        Only shows the label corresponding to the axis.
- * @param  props.fadeTimeout Duration (ms) before deactivating the resize label.
- * @param  props.onResize    Callback when a resize occurs. Provides { width, height } callback.
- * @param  props.position    Adjusts label value.
- * @param  props.showPx      Whether to add `PX` to the label.
+ * @param props
+ * @param props.axis        Only shows the label corresponding to the axis.
+ * @param props.fadeTimeout Duration (ms) before deactivating the resize label.
+ * @param props.onResize    Callback when a resize occurs. Provides { width, height } callback.
+ * @param props.position    Adjusts label value.
+ * @param props.showPx      Whether to add `PX` to the label.
  *
  * @return Properties for hook.
  */
@@ -174,14 +174,14 @@ interface GetSizeLabelArgs {
 /**
  * Gets the resize label based on width and height values (as well as recent changes).
  *
- * @param  props
- * @param  props.axis     Only shows the label corresponding to the axis.
- * @param  props.height   Height value.
- * @param  props.moveX    Recent width (x axis) changes.
- * @param  props.moveY    Recent width (y axis) changes.
- * @param  props.position Adjusts label value.
- * @param  props.showPx   Whether to add `PX` to the label.
- * @param  props.width    Width value.
+ * @param props
+ * @param props.axis     Only shows the label corresponding to the axis.
+ * @param props.height   Height value.
+ * @param props.moveX    Recent width (x axis) changes.
+ * @param props.moveY    Recent width (y axis) changes.
+ * @param props.position Adjusts label value.
+ * @param props.showPx   Whether to add `PX` to the label.
+ * @param props.width    Width value.
  *
  * @return The rendered label.
  */

package/src/select-control/README.md

@@ -187,7 +187,9 @@ If this property is added, a help text will be generated using help property as
 
 #### multiple
 
-If this property is added, multiple values can be selected. The value passed should be an array.
+If this property is added, multiple values can be selected. The `value` passed should be an array.
+
+In most cases, it is preferable to use the `FormTokenField` or `CheckboxControl` components instead.
 
 -   Type: `Boolean`
 -   Required: No

package/src/select-control/index.tsx

@@ -101,7 +101,9 @@ function UnforwardedSelectControl(
 				isFocused={ isFocused }
 				label={ label }
 				size={ size }
-				suffix={ suffix || <SelectControlChevronDown /> }
+				suffix={
+					suffix || ( ! multiple && <SelectControlChevronDown /> )
+				}
 				prefix={ prefix }
 				labelPosition={ labelPosition }
 				__next36pxDefaultSize={ __next36pxDefaultSize }

package/src/select-control/style.scss

@@ -1,16 +1,6 @@
 .components-select-control__input {
-	background: $white;
-	height: 36px;
-	line-height: 36px;
-	margin: 1px;
 	outline: 0;
-	width: 100%;
 	-webkit-tap-highlight-color: rgba(0, 0, 0, 0) !important;
-
-	@include break-medium() {
-		height: 28px;
-		line-height: 28px;
-	}
 }
 
 @media (max-width: #{ ($break-medium) }) {

package/src/select-control/styles/select-control-styles.ts

@@ -13,7 +13,10 @@ import type { SelectControlProps } from '../types';
 import InputControlSuffixWrapper from '../../input-control/input-suffix-wrapper';
 
 interface SelectProps
-	extends Pick< SelectControlProps, '__next36pxDefaultSize' | 'disabled' > {
+	extends Pick<
+		SelectControlProps,
+		'__next36pxDefaultSize' | 'disabled' | 'multiple'
+	> {
 	// Using `selectSize` instead of `size` to avoid a type conflict with the
 	// `size` HTML attribute of the `select` element.
 	selectSize?: SelectControlProps[ 'size' ];
@@ -50,8 +53,15 @@ const fontSizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 
 const sizeStyles = ( {
 	__next36pxDefaultSize,
+	multiple,
 	selectSize = 'default',
 }: SelectProps ) => {
+	if ( multiple ) {
+		// When `multiple`, just use the native browser styles
+		// without setting explicit height.
+		return;
+	}
+
 	const sizes = {
 		default: {
 			height: 36,
@@ -91,33 +101,37 @@ export const chevronIconSize = 18;
 
 const sizePaddings = ( {
 	__next36pxDefaultSize,
+	multiple,
 	selectSize = 'default',
 }: SelectProps ) => {
-	const iconWidth = chevronIconSize;
-
-	const sizes = {
-		default: {
-			paddingLeft: 16,
-			paddingRight: 16 + iconWidth,
-		},
-		small: {
-			paddingLeft: 8,
-			paddingRight: 8 + iconWidth,
-		},
-		'__unstable-large': {
-			paddingLeft: 16,
-			paddingRight: 16 + iconWidth,
-		},
+	const padding = {
+		default: 16,
+		small: 8,
+		'__unstable-large': 16,
 	};
 
 	if ( ! __next36pxDefaultSize ) {
-		sizes.default = {
-			paddingLeft: 8,
-			paddingRight: 8 + iconWidth,
-		};
+		padding.default = 8;
 	}
 
-	return rtl( sizes[ selectSize ] || sizes.default );
+	const selectedPadding = padding[ selectSize ] || padding.default;
+
+	return rtl( {
+		paddingLeft: selectedPadding,
+		paddingRight: selectedPadding + chevronIconSize,
+		...( multiple
+			? {
+					paddingTop: selectedPadding,
+					paddingBottom: selectedPadding,
+			  }
+			: {} ),
+	} );
+};
+
+const overflowStyles = ( { multiple }: SelectProps ) => {
+	return {
+		overflow: multiple ? 'auto' : 'hidden',
+	};
 };
 
 // TODO: Resolve need to use &&& to increase specificity
@@ -137,7 +151,6 @@ export const Select = styled.select< SelectProps >`
 		width: 100%;
 		max-width: none;
 		cursor: pointer;
-		overflow: hidden;
 		white-space: nowrap;
 		text-overflow: ellipsis;
 
@@ -145,6 +158,7 @@ export const Select = styled.select< SelectProps >`
 		${ fontSizeStyles };
 		${ sizeStyles };
 		${ sizePaddings };
+		${ overflowStyles }
 	}
 `;
 

package/src/select-control/types.ts

@@ -23,7 +23,9 @@ export interface SelectControlProps
 		>,
 		Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > {
 	/**
-	 * If this property is added, multiple values can be selected. The value passed should be an array.
+	 * If this property is added, multiple values can be selected. The `value` passed should be an array.
+	 *
+	 * In most cases, it is preferable to use the `FormTokenField` or `CheckboxControl` components instead.
 	 *
 	 * @default false
 	 */

package/src/snackbar/index.tsx

@@ -26,8 +26,8 @@ const NOTICE_TIMEOUT = 10000;
  * Custom hook which announces the message with the given politeness, if a
  * valid message is provided.
  *
- * @param  message    Message to announce.
- * @param  politeness Politeness to announce.
+ * @param message    Message to announce.
+ * @param politeness Politeness to announce.
  */
 function useSpokenMessage(
 	message: SnackbarProps[ 'spokenMessage' ],

package/src/toolbar/stories/{index.js → index.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -18,6 +23,7 @@ import {
 	arrowRight,
 	chevronDown,
 } from '@wordpress/icons';
+import { SVG, Path } from '@wordpress/primitives';
 
 /**
  * Internal dependencies
@@ -29,9 +35,9 @@ import {
 	ToolbarItem,
 	ToolbarDropdownMenu,
 } from '..';
-import { SVG, Path, DropdownMenu } from '../../';
+import DropdownMenu from '../../dropdown-menu';
 
-export default {
+const meta: ComponentMeta< typeof Toolbar > = {
 	title: 'Components/Toolbar',
 	component: Toolbar,
 	subcomponents: {
@@ -49,6 +55,8 @@ export default {
 	},
 };
 
+export default meta;
+
 function InlineImageIcon() {
 	return (
 		<SVG xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
@@ -57,7 +65,7 @@ function InlineImageIcon() {
 	);
 }
 
-const Template = ( props ) => (
+const Template: ComponentStory< typeof Toolbar > = ( props ) => (
 	<div style={ { height: 280 } }>
 		<Toolbar { ...props } />
 	</div>
@@ -74,29 +82,32 @@ Default.args = {
 			</ToolbarGroup>
 			<ToolbarGroup>
 				<ToolbarItem>
-					{ ( toggleProps ) => (
-						<DropdownMenu
-							hasArrowIndicator
-							icon={ alignLeft }
-							label="Align"
-							controls={ [
-								{
-									icon: alignLeft,
-									title: 'Align left',
-									isActive: true,
-								},
-								{
-									icon: alignCenter,
-									title: 'Align center',
-								},
-								{
-									icon: alignRight,
-									title: 'Align right',
-								},
-							] }
-							toggleProps={ toggleProps }
-						/>
-					) }
+					{
+						// @ts-expect-error TODO: Remove when ToolbarItem/DropdownMenu is typed
+						( toggleProps ) => (
+							<DropdownMenu
+								hasArrowIndicator
+								icon={ alignLeft }
+								label="Align"
+								controls={ [
+									{
+										icon: alignLeft,
+										title: 'Align left',
+										isActive: true,
+									},
+									{
+										icon: alignCenter,
+										title: 'Align center',
+									},
+									{
+										icon: alignRight,
+										title: 'Align right',
+									},
+								] }
+								toggleProps={ toggleProps }
+							/>
+						)
+					}
 				</ToolbarItem>
 			</ToolbarGroup>
 			<ToolbarGroup>
@@ -106,6 +117,7 @@ Default.args = {
 				<ToolbarButton icon={ link } label="Link" />
 				<ToolbarGroup
 					isCollapsed
+					// @ts-expect-error TODO: Remove when ToolbarGroup is typed
 					icon={ false }
 					label="More rich text controls"
 					controls={ [
@@ -119,6 +131,7 @@ Default.args = {
 				/>
 			</ToolbarGroup>
 			<ToolbarGroup
+				// @ts-expect-error TODO: Remove when ToolbarGroup is typed
 				icon={ more }
 				label="Align"
 				isCollapsed

package/src/toolbar/test/{toolbar-group.js → toolbar-group.tsx}

@@ -23,7 +23,7 @@ describe( 'ToolbarGroup', () => {
 		} );
 
 		it( 'should render a list of controls with buttons', () => {
-			const clickHandler = ( event ) => event;
+			const clickHandler = ( event: Event ) => event;
 			const controls = [
 				{
 					icon: 'wordpress',
@@ -41,7 +41,7 @@ describe( 'ToolbarGroup', () => {
 		} );
 
 		it( 'should render a list of controls with buttons and active control', () => {
-			const clickHandler = ( event ) => event;
+			const clickHandler = ( event: Event ) => event;
 			const controls = [
 				{
 					icon: 'wordpress',

package/src/toolbar/toolbar/README.md

@@ -59,11 +59,16 @@ function MyToolbar() {
 
 Toolbar will pass all HTML props to the underlying element. Additionally, you can pass the custom props specified below.
 
-#### label
+#### `className`: `string`
+
+Class to set on the container div.
+
+-   Required: No
+
+#### `label`: `string`
 
 An accessible label for the toolbar.
 
--   Type: `String`
 -   Required: Yes
 
 ## Related components

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -14,18 +15,17 @@ import deprecated from '@wordpress/deprecated';
  */
 import ToolbarGroup from '../toolbar-group';
 import ToolbarContainer from './toolbar-container';
+import type { ToolbarProps } from './types';
+import type { WordPressComponentProps } from '../../ui/context';
 
-/**
- * Renders a toolbar.
- *
- * To add controls, simply pass `ToolbarButton` components as children.
- *
- * @param {Object} props             Component props.
- * @param {string} [props.className] Class to set on the container div.
- * @param {string} [props.label]     ARIA label for toolbar container.
- * @param {Object} ref               React Element ref.
- */
-function Toolbar( { className, label, ...props }, ref ) {
+function UnforwardedToolbar(
+	{
+		className,
+		label,
+		...props
+	}: WordPressComponentProps< ToolbarProps, 'div', false >,
+	ref: ForwardedRef< any >
+) {
 	if ( ! label ) {
 		deprecated( 'Using Toolbar without label prop', {
 			since: '5.6',
@@ -49,4 +49,25 @@ function Toolbar( { className, label, ...props }, ref ) {
 	);
 }
 
-export default forwardRef( Toolbar );
+/**
+ * Renders a toolbar.
+ *
+ * To add controls, simply pass `ToolbarButton` components as children.
+ *
+ * ```jsx
+ * import { Toolbar, ToolbarButton } from '@wordpress/components';
+ * import { formatBold, formatItalic, link } from '@wordpress/icons';
+ *
+ * function MyToolbar() {
+ *   return (
+ *     <Toolbar label="Options">
+ *       <ToolbarButton icon={ formatBold } label="Bold" />
+ *       <ToolbarButton icon={ formatItalic } label="Italic" />
+ *       <ToolbarButton icon={ link } label="Link" />
+ *     </Toolbar>
+ *   );
+ * }
+ * ```
+ */
+export const Toolbar = forwardRef( UnforwardedToolbar );
+export default Toolbar;

package/src/toolbar/toolbar/{toolbar-container.js → toolbar-container.tsx}

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { useToolbarState, Toolbar } from 'reakit/Toolbar';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -13,8 +14,13 @@ import { isRTL } from '@wordpress/i18n';
  * Internal dependencies
  */
 import ToolbarContext from '../toolbar-context';
+import type { ToolbarProps } from './types';
+import type { WordPressComponentProps } from '../../ui/context';
 
-function ToolbarContainer( { label, ...props }, ref ) {
+function UnforwardedToolbarContainer(
+	{ label, ...props }: WordPressComponentProps< ToolbarProps, 'div', false >,
+	ref: ForwardedRef< any >
+) {
 	// https://reakit.io/docs/basic-concepts/#state-hooks
 	// Passing baseId for server side rendering (which includes snapshots)
 	// If an id prop is passed to Toolbar, toolbar items will use it as a base for their ids
@@ -37,4 +43,5 @@ function ToolbarContainer( { label, ...props }, ref ) {
 	);
 }
 
-export default forwardRef( ToolbarContainer );
+export const ToolbarContainer = forwardRef( UnforwardedToolbarContainer );
+export default ToolbarContainer;

package/src/toolbar/toolbar/types.ts

@@ -0,0 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type ToolbarProps = {
+	/**
+	 * Children to be rendered inside the toolbar.
+	 */
+	children?: ReactNode;
+	/**
+	 * An accessible label for the toolbar.
+	 */
+	label: string;
+};

package/src/toolbar/toolbar-button/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/toolbar/toolbar-button/toolbar-button-container.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 const ToolbarButtonContainer = ( props ) => (
 	<div className={ props.className }>{ props.children }</div>
 );

package/src/toolbar/toolbar-context/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * WordPress dependencies
  */

package/src/toolbar/toolbar-dropdown-menu/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * WordPress dependencies
  */

package/src/toolbar/toolbar-group/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/toolbar/toolbar-group/toolbar-group-collapsed.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * WordPress dependencies
  */