@wordpress/components 23.1.0 → 23.3.0

package/src/query-controls/terms.ts

@@ -0,0 +1,57 @@
+/**
+ * External dependencies
+ */
+import { groupBy } from 'lodash';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	Author,
+	Category,
+	TermWithParentAndChildren,
+	TermsByParent,
+} from './types';
+
+/**
+ * Returns terms in a tree form.
+ *
+ * @param  flatTerms Array of terms in flat format.
+ *
+ * @return Terms in tree format.
+ */
+export function buildTermsTree( flatTerms: readonly ( Author | Category )[] ) {
+	const flatTermsWithParentAndChildren: TermWithParentAndChildren[] =
+		flatTerms.map( ( term ) => {
+			return {
+				children: [],
+				parent: null,
+				...term,
+				id: String( term.id ),
+			};
+		} );
+
+	const termsByParent: TermsByParent = groupBy(
+		flatTermsWithParentAndChildren,
+		'parent'
+	);
+	if ( termsByParent.null && termsByParent.null.length ) {
+		return flatTermsWithParentAndChildren;
+	}
+	const fillWithChildren = (
+		terms: TermWithParentAndChildren[]
+	): TermWithParentAndChildren[] => {
+		return terms.map( ( term ) => {
+			const children = termsByParent[ term.id ];
+			return {
+				...term,
+				children:
+					children && children.length
+						? fillWithChildren( children )
+						: [],
+			};
+		} );
+	};
+
+	return fillWithChildren( termsByParent[ '0' ] || [] );
+}

package/src/query-controls/test/{terms.js → terms.ts}

@@ -6,38 +6,53 @@ import { buildTermsTree } from '../terms';
 describe( 'buildTermsTree()', () => {
 	it( 'Should return same array as input with null parent and empty children added if parent is never specified.', () => {
 		const input = Object.freeze( [
-			{ id: 2232, dummy: true },
-			{ id: 2245, dummy: true },
+			{ id: 2232, name: 'foo', dummy: true },
+			{ id: 2245, name: 'baz', dummy: true },
 		] );
 		const output = Object.freeze( [
-			{ id: 2232, parent: null, children: [], dummy: true },
-			{ id: 2245, parent: null, children: [], dummy: true },
+			{
+				id: '2232',
+				name: 'foo',
+				parent: null,
+				children: [],
+				dummy: true,
+			},
+			{
+				id: '2245',
+				name: 'baz',
+				parent: null,
+				children: [],
+				dummy: true,
+			},
 		] );
 		const termsTreem = buildTermsTree( input );
 		expect( termsTreem ).toEqual( output );
 	} );
 	it( 'Should return same array as input with empty children added if all the elements are top level', () => {
 		const input = Object.freeze( [
-			{ id: 2232, parent: 0, dummy: true },
-			{ id: 2245, parent: 0, dummy: false },
+			{ id: 2232, name: 'foo', parent: 0, dummy: true },
+			{ id: 2245, name: 'baz', parent: 0, dummy: false },
 		] );
 		const output = [
-			{ id: 2232, parent: 0, children: [], dummy: true },
-			{ id: 2245, parent: 0, children: [], dummy: false },
+			{ id: '2232', name: 'foo', parent: 0, children: [], dummy: true },
+			{ id: '2245', name: 'baz', parent: 0, children: [], dummy: false },
 		];
 		const termsTreem = buildTermsTree( input );
 		expect( termsTreem ).toEqual( output );
 	} );
 	it( 'Should return element with its child if a child exists', () => {
 		const input = Object.freeze( [
-			{ id: 2232, parent: 0 },
-			{ id: 2245, parent: 2232 },
+			{ id: 2232, name: 'foo', parent: 0 },
+			{ id: 2245, name: 'baz', parent: 2232 },
 		] );
 		const output = [
 			{
-				id: 2232,
+				id: '2232',
+				name: 'foo',
 				parent: 0,
-				children: [ { id: 2245, parent: 2232, children: [] } ],
+				children: [
+					{ id: '2245', name: 'baz', parent: 2232, children: [] },
+				],
 			},
 		];
 		const termsTreem = buildTermsTree( input );
@@ -45,21 +60,22 @@ describe( 'buildTermsTree()', () => {
 	} );
 	it( 'Should return elements with multiple children and elements with no children', () => {
 		const input = Object.freeze( [
-			{ id: 2232, parent: 0 },
-			{ id: 2245, parent: 2232 },
-			{ id: 2249, parent: 0 },
-			{ id: 2246, parent: 2232 },
+			{ id: 2232, name: 'a', parent: 0 },
+			{ id: 2245, name: 'b', parent: 2232 },
+			{ id: 2249, name: 'c', parent: 0 },
+			{ id: 2246, name: 'd', parent: 2232 },
 		] );
 		const output = [
 			{
-				id: 2232,
+				id: '2232',
+				name: 'a',
 				parent: 0,
 				children: [
-					{ id: 2245, parent: 2232, children: [] },
-					{ id: 2246, parent: 2232, children: [] },
+					{ id: '2245', name: 'b', parent: 2232, children: [] },
+					{ id: '2246', name: 'd', parent: 2232, children: [] },
 				],
 			},
-			{ id: 2249, parent: 0, children: [] },
+			{ id: '2249', name: 'c', parent: 0, children: [] },
 		];
 		const termsTreem = buildTermsTree( input );
 		expect( termsTreem ).toEqual( output );

package/src/query-controls/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Internal dependencies
+ */
+import type { FormTokenFieldProps } from '../form-token-field/types';
+import type { TreeSelectProps } from '../tree-select/types';
+
+export type Author = {
+	id: number;
+	name: string;
+};
+
+export type Category = {
+	id: number;
+	name: string;
+	parent: number;
+};
+
+export type TermWithParentAndChildren = {
+	id: string;
+	name: string;
+	parent: number | null;
+	children: TermWithParentAndChildren[];
+};
+
+export type TermsByParent = Record< string, TermWithParentAndChildren[] >;
+
+export type CategorySelectProps = Pick<
+	TreeSelectProps,
+	'label' | 'noOptionLabel'
+> & {
+	categoriesList: Category[];
+	onChange: ( newCategory: string ) => void;
+	selectedCategoryId?: Category[ 'id' ];
+};
+
+export type AuthorSelectProps = Pick<
+	TreeSelectProps,
+	'label' | 'noOptionLabel'
+> & {
+	authorList?: Author[];
+	onChange: ( newAuthor: string ) => void;
+	selectedAuthorId?: Author[ 'id' ];
+};
+
+type Order = 'asc' | 'desc';
+type OrderBy = 'date' | 'title';
+
+type BaseQueryControlsProps = {
+	/**
+	 * An array of the authors to select from.
+	 */
+	authorList?: AuthorSelectProps[ 'authorList' ];
+	/**
+	 * The maximum number of items.
+	 *
+	 * @default 100
+	 */
+	maxItems?: number;
+	/**
+	 * The minimum number of items.
+	 *
+	 * @default 1
+	 */
+	minItems?: number;
+	/**
+	 * The selected number of items to retrieve via the query.
+	 */
+	numberOfItems?: number;
+	/**
+	 * A function that receives the new author value.
+	 * If not specified, the author controls are not rendered.
+	 */
+	onAuthorChange?: AuthorSelectProps[ 'onChange' ];
+	/**
+	 * A function that receives the new number of items.
+	 * If not specified, then the number of items
+	 * range control is not rendered.
+	 */
+	onNumberOfItemsChange?: ( newNumber?: number ) => void;
+	/**
+	 * A function that receives the new order value.
+	 * If this prop or the `onOrderByChange` prop are not specified,
+	 * then the order controls are not rendered.
+	 */
+	onOrderChange?: ( newOrder: Order ) => void;
+	/**
+	 * A function that receives the new orderby value.
+	 * If this prop or the `onOrderChange` prop are not specified,
+	 * then the order controls are not rendered.
+	 */
+	onOrderByChange?: ( newOrderBy: OrderBy ) => void;
+	/**
+	 * The order in which to retrieve posts.
+	 */
+	order?: Order;
+	/**
+	 * The meta key by which to order posts.
+	 */
+	orderBy?: OrderBy;
+	/**
+	 * The selected author ID.
+	 */
+	selectedAuthorId?: AuthorSelectProps[ 'selectedAuthorId' ];
+};
+
+export type QueryControlsWithSingleCategorySelectionProps =
+	BaseQueryControlsProps & {
+		/**
+		 * An array of categories. When passed in conjunction with the
+		 * `onCategoryChange` prop, it causes the component to render UI that allows
+		 * selecting one category at a time.
+		 */
+		categoriesList?: CategorySelectProps[ 'categoriesList' ];
+		/**
+		 * The selected category for the `categoriesList` prop.
+		 */
+		selectedCategoryId?: CategorySelectProps[ 'selectedCategoryId' ];
+		/**
+		 * A function that receives the new category value. If not specified, the
+		 * category controls are not rendered.
+		 * The function's signature changes depending on whether multiple category
+		 * selection is enabled or not.
+		 */
+		onCategoryChange?: CategorySelectProps[ 'onChange' ];
+	};
+
+export type QueryControlsWithMultipleCategorySelectionProps =
+	BaseQueryControlsProps & {
+		/**
+		 * An object of categories with the category name as the key. When passed in
+		 * conjunction with the `onCategoryChange` prop, it causes the component to
+		 * render UI that enables multiple selection.
+		 */
+		categorySuggestions?: Record< Category[ 'name' ], Category >;
+		/**
+		 * The selected categories for the `categorySuggestions` prop.
+		 */
+		selectedCategories?: Category[];
+		/**
+		 * A function that receives the new category value. If not specified, the
+		 * category controls are not rendered.
+		 * The function's signature changes depending on whether multiple category
+		 * selection is enabled or not.
+		 */
+		onCategoryChange?: FormTokenFieldProps[ 'onChange' ];
+	};
+
+export type QueryControlsProps =
+	| QueryControlsWithSingleCategorySelectionProps
+	| QueryControlsWithMultipleCategorySelectionProps;

package/src/resizable-box/README.md

@@ -38,8 +38,8 @@ const Edit = ( props ) => {
 			} }
 			onResizeStop={ ( event, direction, elt, delta ) => {
 				setAttributes( {
-					height: parseInt( height + delta.height, 10 ),
-					width: parseInt( width + delta.width, 10 ),
+					height: height + delta.height,
+					width: width + delta.width,
 				} );
 				toggleSelection( true );
 			} }

package/src/resizable-box/index.tsx

@@ -88,14 +88,13 @@ const HANDLE_STYLES = {
 };
 
 type ResizableBoxProps = ResizableProps & {
-	className: string;
 	children: ReactNode;
-	showHandle: boolean;
-	__experimentalShowTooltip: boolean;
-	__experimentalTooltipProps: Parameters< typeof ResizeTooltip >[ 0 ];
+	showHandle?: boolean;
+	__experimentalShowTooltip?: boolean;
+	__experimentalTooltipProps?: Parameters< typeof ResizeTooltip >[ 0 ];
 };
 
-function ResizableBox(
+function UnforwardedResizableBox(
 	{
 		className,
 		children,
@@ -124,4 +123,6 @@ function ResizableBox(
 	);
 }
 
-export default forwardRef( ResizableBox );
+export const ResizableBox = forwardRef( UnforwardedResizableBox );
+
+export default ResizableBox;

package/src/resizable-box/stories/index.tsx

@@ -0,0 +1,92 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import ResizableBox from '..';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+const meta: ComponentMeta< typeof ResizableBox > = {
+	title: 'Components/ResizableBox',
+	component: ResizableBox,
+	argTypes: {
+		children: { control: { type: null } },
+		enable: { control: 'object' },
+		onResizeStop: { action: 'onResizeStop' },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof ResizableBox > = ( {
+	onResizeStop,
+	...props
+} ) => {
+	const [ { height, width }, setAttributes ] = useState( {
+		height: 200,
+		width: 400,
+	} );
+
+	return (
+		<ResizableBox
+			{ ...props }
+			size={ {
+				height,
+				width,
+			} }
+			onResizeStop={ ( event, direction, elt, delta ) => {
+				onResizeStop?.( event, direction, elt, delta );
+				setAttributes( {
+					height: height + delta.height,
+					width: width + delta.width,
+				} );
+			} }
+		/>
+	);
+};
+
+export const Default = Template.bind( {} );
+Default.args = {
+	children: (
+		<div
+			style={ {
+				background: '#eee',
+				display: 'flex',
+				height: '100%',
+				width: '100%',
+				alignItems: 'center',
+				justifyContent: 'center',
+			} }
+		>
+			Resize
+		</div>
+	),
+};
+
+/**
+ * The `enable` prop can be used to disable resizing in specific directions.
+ */
+export const DisabledDirections = Template.bind( {} );
+DisabledDirections.args = {
+	...Default.args,
+	enable: {
+		top: false,
+		right: true,
+		bottom: true,
+		left: false,
+		topRight: false,
+		bottomRight: true,
+		bottomLeft: false,
+		topLeft: false,
+	},
+};

package/src/responsive-wrapper/README.md

@@ -1,5 +1,7 @@
 # ResponsiveWrapper
 
+A wrapper component that maintains its aspect ratio when resized.
+
 ## Usage
 
 ```jsx
@@ -14,3 +16,30 @@ const MyResponsiveWrapper = () => (
 	</ResponsiveWrapper>
 );
 ```
+
+## Props
+
+### `children`: `React.ReactElement`
+
+The element to wrap.
+
+-   Required: Yes
+
+### `isInline`: `boolean`
+
+If true, the wrapper will be `span` instead of `div`.
+
+-   Required: No
+-   Default: `false`
+
+### `naturalHeight`: `number`
+
+The intrinsic height of the element to wrap. Will be used to determine the aspect ratio.
+
+-   Required: Yes
+
+### `naturalWidth`: `number`
+
+The intrinsic width of the element to wrap. Will be used to determine the aspect ratio.
+
+-   Required: Yes

package/src/responsive-wrapper/{index.js → index.tsx}

@@ -9,12 +9,33 @@ import classnames from 'classnames';
 import { cloneElement, Children } from '@wordpress/element';
 import { useResizeObserver } from '@wordpress/compose';
 
+/**
+ * Internal dependencies
+ */
+import type { ResponsiveWrapperProps } from './types';
+
+/**
+ * A wrapper component that maintains its aspect ratio when resized.
+ *
+ * ```jsx
+ * import { ResponsiveWrapper } from '@wordpress/components';
+ *
+ * const MyResponsiveWrapper = () => (
+ * 	<ResponsiveWrapper naturalWidth={ 2000 } naturalHeight={ 680 }>
+ * 		<img
+ * 			src="https://s.w.org/style/images/about/WordPress-logotype-standard.png"
+ * 			alt="WordPress"
+ * 		/>
+ * 	</ResponsiveWrapper>
+ * );
+ * ```
+ */
 function ResponsiveWrapper( {
 	naturalWidth,
 	naturalHeight,
 	children,
 	isInline = false,
-} ) {
+}: ResponsiveWrapperProps ) {
 	const [ containerResizeListener, { width: containerWidth } ] =
 		useResizeObserver();
 	if ( Children.count( children ) !== 1 ) {
@@ -22,7 +43,7 @@ function ResponsiveWrapper( {
 	}
 	const imageStyle = {
 		paddingBottom:
-			naturalWidth < containerWidth
+			naturalWidth < ( containerWidth ?? 0 )
 				? naturalHeight
 				: ( naturalHeight / naturalWidth ) * 100 + '%',
 	};

package/src/responsive-wrapper/stories/index.tsx

@@ -0,0 +1,38 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import ResponsiveWrapper from '..';
+
+const meta: ComponentMeta< typeof ResponsiveWrapper > = {
+	component: ResponsiveWrapper,
+	title: 'Components/ResponsiveWrapper',
+	argTypes: {
+		children: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof ResponsiveWrapper > = ( args ) => (
+	<ResponsiveWrapper { ...args } />
+);
+
+export const Default = Template.bind( {} );
+Default.args = {
+	naturalWidth: 2000,
+	naturalHeight: 680,
+	children: (
+		<img
+			src="https://s.w.org/style/images/about/WordPress-logotype-standard.png"
+			alt="WordPress"
+		/>
+	),
+};

package/src/responsive-wrapper/types.ts

@@ -0,0 +1,20 @@
+export type ResponsiveWrapperProps = {
+	/**
+	 * The intrinsic width of the element to wrap. Will be used to determine the aspect ratio.
+	 */
+	naturalWidth: number;
+	/**
+	 * The intrinsic height of the element to wrap. Will be used to determine the aspect ratio.
+	 */
+	naturalHeight: number;
+	/**
+	 * The element to wrap.
+	 */
+	children: React.ReactElement;
+	/**
+	 * If true, the wrapper will be `span` instead of `div`.
+	 *
+	 * @default false
+	 */
+	isInline?: boolean;
+};

package/src/sandbox/README.md

@@ -1,4 +1,4 @@
-# Sandbox
+# SandBox
 
 This component provides an isolated environment for arbitrary HTML via iframes.
 
@@ -8,6 +8,49 @@ This component provides an isolated environment for arbitrary HTML via iframes.
 import { SandBox } from '@wordpress/components';
 
 const MySandBox = () => (
-	<SandBox html="<p>Content</p>" title="Sandbox" type="embed" />
+	<SandBox html="<p>Content</p>" title="SandBox" type="embed" />
 );
 ```
+
+## Props
+
+### `html`: `string`
+
+The HTML to render in the body of the iframe document.
+
+-   Required: No
+-   Default: ""
+
+### `onFocus`: `React.DOMAttributes< HTMLIFrameElement >[ 'onFocus' ]`
+
+The `onFocus` callback for the iframe.
+
+-   Required: No
+
+### `scripts`: `string[]`
+
+An array of script URLs to inject as `<script>` tags into the bottom of the `<body>` of the iframe document.
+
+-   Required: No
+-   Default: []
+
+### `styles`: `string[]`
+
+An array of CSS strings to inject into the `<head>` of the iframe document.
+
+-   Required: No
+-   Default: []
+
+### `title`: `string`
+
+The `<title>` of the iframe document.
+
+-   Required: No
+-   Default: ""
+
+### `type`: `string`
+
+The CSS class name to apply to the `<html>` and `<body>` elements of the iframe.
+
+-   Required: No
+-   Default: ""