@wordpress/components 23.2.0 → 23.3.0

package/src/query-controls/README.md

@@ -28,10 +28,10 @@ const QUERY_DEFAULTS = {
 		},
 	],
 	maxItems: 20,
-	minItems: 1,	
+	minItems: 1,
 	numberOfItems: 10,
 	order: 'asc',
-	orderBy: 'title',	
+	orderBy: 'title',
 };
 
 const MyQueryControls = () => {
@@ -66,24 +66,35 @@ The `QueryControls` component now supports multiple category selection, to repla
 const QUERY_DEFAULTS = {
 	orderBy: 'title',
 	order: 'asc',
-	selectedCategories: [ 1 ],
-	categories: [
+	selectedCategories: [
 		{
 			id: 1,
-			name: 'Category 1',
+			value: 'Category 1',
 			parent: 0,
 		},
 		{
+			id: 2,
+			value: 'Category 1b',
+			parent: 1,
+		},
+	],
+	categories: {
+		'Category 1': {
+			id: 1,
+			name: 'Category 1',
+			parent: 0,
+		},
+		'Category 1b': {
 			id: 2,
 			name: 'Category 1b',
 			parent: 1,
 		},
-		{
+		'Category 2': {
 			id: 3,
 			name: 'Category 2',
 			parent: 0,
 		},
-	],
+	},
 	numberOfItems: 10,
 };
 
@@ -111,132 +122,121 @@ const MyQueryControls = () => {
 };
 ```
 
-The format of the categories list also needs to be updated to match what `FormTokenField` expects for making suggestions.
+The format of the categories list also needs to be updated to match the expected type for the category suggestions.
 
 ### Props
 
-#### authorList
+#### `authorList`: `Author[]`
 
-An array of author IDs that is passed into an `AuthorSelect` sub-component.
+An array of the authors to select from.
 
--   Type: `Array`
 -   Required: No
 -   Platform: Web
 
-#### selectedAuthorId
+#### `categoriesList`: `Category[]`
 
-The selected author ID.
+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.
 
--   Type: `Number`
 -   Required: No
 -   Platform: Web
 
-#### categoriesList
+#### `categorySuggestions`: `Record< Category[ 'name' ], Category >`
 
-An array of category IDs; renders a `CategorySelect` sub-component when passed in conjunction with `onCategoryChange`.
+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.
 
--   Type: `Array`
 -   Required: No
 -   Platform: Web
 
-#### categorySuggestions
+#### `maxItems`: `number`
 
-An array of category names; renders a `FormTokenField` component when passed in conjunction with `onCategoryChange`.
+The maximum number of items.
 
--   Type: `Array`
 -   Required: No
+-   Default: 100
 -   Platform: Web
 
-#### maxItems
+#### `minItems`: `number`
+
+The minimum number of items.
 
--   Type: `Number`
 -   Required: No
--   Default: 100
+-   Default: 1
 -   Platform: Web
 
-#### minItems
+#### `numberOfItems`: `number`
+
+The selected number of items to retrieve via the query.
 
--   Type: `Number`
 -   Required: No
--   Default: 1
 -   Platform: Web
 
-#### numberOfItems
+#### `onAuthorChange`: `( newAuthor: string ) => void`
 
-The selected number of items to retrieve via the query.
+A function that receives the new author value. If not specified, the author controls are not rendered.
 
--   Type: `Number`
 -   Required: No
 -   Platform: Web
 
-#### onAuthorChange
+#### `onCategoryChange`: `( newCategory: string ) => void | FormTokenFieldProps[ 'onChange' ]`
 
-A function that receives the new author value. If this is not specified, the author controls are not included.
+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.
 
--   Type: `Function`
 -   Required: No
 -   Platform: Web
 
-#### onCategoryChange
+#### `onNumberOfItemsChange`: `( newNumber?: number ) => void`
 
-A function that receives the new category value. If this is not specified, the category controls are not included.
+A function that receives the new number of items. If not specified, then the number of items range control is not rendered.
 
--   Type: `Function`
 -   Required: No
 -   Platform: Web
 
-#### onNumberOfItemsChange
+#### `onOrderChange`: `( newOrder: 'asc' | 'desc' ) => void`
 
-A function that receives the new number of items value. If this is not specified, then the number of items range control is not included.
+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.
 
--   Type: `Function`
 -   Required: No
 -   Platform: Web
 
-#### onOrderChange
+#### `onOrderByChange`: `( newOrderBy: 'date' | 'title' ) => void`
 
-A function that receives the new order value. If this or onOrderByChange are not specified, then the order controls are not included.
+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.
 
--   Type: `Function`
 -   Required: No
 -   Platform: Web
 
-#### onOrderByChange
+#### `order`: `'asc' | 'desc'`
 
-A function that receives the new orderby value. If this or onOrderChange are not specified, then the order controls are not included.
+The order in which to retrieve posts.
 
--   Type: `Function`
 -   Required: No
 -   Platform: Web
 
-#### order
+#### `orderBy`: `'date' | 'title'`
 
-The order in which to retrieve posts. Can be 'asc' or 'desc'.
+The meta key by which to order posts.
 
--   Type: `String`
 -   Required: No
 -   Platform: Web
 
-#### orderBy
+#### `selectedAuthorId`: `number`
 
-The meta key by which to order posts. Can be 'date' or 'title'.
+The selected author ID.
 
--   Type: `String`
 -   Required: No
 -   Platform: Web
 
-#### selectedCategories
+#### `selectedCategories`: `Category[]`
 
-The selected categories for the `categorySuggestions`.
+The selected categories for the `categorySuggestions` prop.
 
--   Type: `Array`
 -   Required: No
 -   Platform: Web
 
-#### selectedCategoryId
+#### `selectedCategoryId`: `number`
 
-The selected category for the `categoriesList`.
+The selected category for the `categoriesList` prop.
 
--   Type: `Number`
 -   Required: No
 -   Platform: Web

package/src/query-controls/author-select.tsx

@@ -0,0 +1,37 @@
+/**
+ * Internal dependencies
+ */
+import { buildTermsTree } from './terms';
+import TreeSelect from '../tree-select';
+import type { TreeSelectProps } from '../tree-select/types';
+import type { AuthorSelectProps } from './types';
+
+export default function AuthorSelect( {
+	label,
+	noOptionLabel,
+	authorList,
+	selectedAuthorId,
+	onChange: onChangeProp,
+}: AuthorSelectProps ) {
+	if ( ! authorList ) return null;
+	const termsTree = buildTermsTree( authorList );
+	return (
+		<TreeSelect
+			{ ...{
+				label,
+				noOptionLabel,
+				// Since the `multiple` attribute is not passed to `TreeSelect`, it is
+				// safe to assume that the argument of `onChange` cannot be `string[]`.
+				// The correct solution would be to type `SelectControl` better, so that
+				// the type of `value` and `onChange` vary depending on `multiple`.
+				onChange: onChangeProp as TreeSelectProps[ 'onChange' ],
+			} }
+			tree={ termsTree }
+			selectedId={
+				selectedAuthorId !== undefined
+					? String( selectedAuthorId )
+					: undefined
+			}
+		/>
+	);
+}

package/src/query-controls/category-select.tsx

@@ -0,0 +1,46 @@
+/**
+ * Internal dependencies
+ */
+import { buildTermsTree } from './terms';
+import TreeSelect from '../tree-select';
+import type { TreeSelectProps } from '../tree-select/types';
+
+/**
+ * WordPress dependencies
+ */
+import { useMemo } from '@wordpress/element';
+import type { CategorySelectProps } from './types';
+
+export default function CategorySelect( {
+	label,
+	noOptionLabel,
+	categoriesList,
+	selectedCategoryId,
+	onChange: onChangeProp,
+	...props
+}: CategorySelectProps ) {
+	const termsTree = useMemo( () => {
+		return buildTermsTree( categoriesList );
+	}, [ categoriesList ] );
+
+	return (
+		<TreeSelect
+			{ ...{
+				label,
+				noOptionLabel,
+				// Since the `multiple` attribute is not passed to `TreeSelect`, it is
+				// safe to assume that the argument of `onChange` cannot be `string[]`.
+				// The correct solution would be to type `SelectControl` better, so that
+				// the type of `value` and `onChange` vary depending on `multiple`.
+				onChange: onChangeProp as TreeSelectProps[ 'onChange' ],
+			} }
+			tree={ termsTree }
+			selectedId={
+				selectedCategoryId !== undefined
+					? String( selectedCategoryId )
+					: undefined
+			}
+			{ ...props }
+		/>
+	);
+}

package/src/query-controls/index.tsx

@@ -0,0 +1,192 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import AuthorSelect from './author-select';
+import CategorySelect from './category-select';
+import FormTokenField from '../form-token-field';
+import RangeControl from '../range-control';
+import SelectControl from '../select-control';
+import type {
+	QueryControlsProps,
+	QueryControlsWithMultipleCategorySelectionProps,
+	QueryControlsWithSingleCategorySelectionProps,
+} from './types';
+
+const DEFAULT_MIN_ITEMS = 1;
+const DEFAULT_MAX_ITEMS = 100;
+const MAX_CATEGORIES_SUGGESTIONS = 20;
+
+function isSingleCategorySelection(
+	props: QueryControlsProps
+): props is QueryControlsWithSingleCategorySelectionProps {
+	return 'categoriesList' in props;
+}
+
+function isMultipleCategorySelection(
+	props: QueryControlsProps
+): props is QueryControlsWithMultipleCategorySelectionProps {
+	return 'categorySuggestions' in props;
+}
+
+/**
+ * Controls to query for posts.
+ *
+ * ```jsx
+ * const MyQueryControls = () => (
+ *   <QueryControls
+ *     { ...{ maxItems, minItems, numberOfItems, order, orderBy } }
+ *     onOrderByChange={ ( newOrderBy ) => {
+ *       updateQuery( { orderBy: newOrderBy } )
+ *     }
+ *     onOrderChange={ ( newOrder ) => {
+ *       updateQuery( { order: newOrder } )
+ *     }
+ *     categoriesList={ categories }
+ *     selectedCategoryId={ category }
+ *     onCategoryChange={ ( newCategory ) => {
+ *       updateQuery( { category: newCategory } )
+ *     }
+ *     onNumberOfItemsChange={ ( newNumberOfItems ) => {
+ *       updateQuery( { numberOfItems: newNumberOfItems } )
+ *     } }
+ *   />
+ * );
+ * ```
+ */
+export function QueryControls( {
+	authorList,
+	selectedAuthorId,
+	numberOfItems,
+	order,
+	orderBy,
+	maxItems = DEFAULT_MAX_ITEMS,
+	minItems = DEFAULT_MIN_ITEMS,
+	onAuthorChange,
+	onNumberOfItemsChange,
+	onOrderChange,
+	onOrderByChange,
+	// Props for single OR multiple category selection are not destructured here,
+	// but instead are destructured inline where necessary.
+	...props
+}: QueryControlsProps ) {
+	return (
+		<>
+			{ [
+				onOrderChange && onOrderByChange && (
+					<SelectControl
+						__nextHasNoMarginBottom
+						key="query-controls-order-select"
+						label={ __( 'Order by' ) }
+						value={ `${ orderBy }/${ order }` }
+						options={ [
+							{
+								label: __( 'Newest to oldest' ),
+								value: 'date/desc',
+							},
+							{
+								label: __( 'Oldest to newest' ),
+								value: 'date/asc',
+							},
+							{
+								/* translators: label for ordering posts by title in ascending order */
+								label: __( 'A → Z' ),
+								value: 'title/asc',
+							},
+							{
+								/* translators: label for ordering posts by title in descending order */
+								label: __( 'Z → A' ),
+								value: 'title/desc',
+							},
+						] }
+						onChange={ ( value ) => {
+							if ( typeof value !== 'string' ) {
+								return;
+							}
+
+							const [ newOrderBy, newOrder ] = value.split( '/' );
+							if ( newOrder !== order ) {
+								onOrderChange(
+									newOrder as NonNullable<
+										QueryControlsProps[ 'order' ]
+									>
+								);
+							}
+							if ( newOrderBy !== orderBy ) {
+								onOrderByChange(
+									newOrderBy as NonNullable<
+										QueryControlsProps[ 'orderBy' ]
+									>
+								);
+							}
+						} }
+					/>
+				),
+				isSingleCategorySelection( props ) &&
+					props.categoriesList &&
+					props.onCategoryChange && (
+						<CategorySelect
+							key="query-controls-category-select"
+							categoriesList={ props.categoriesList }
+							label={ __( 'Category' ) }
+							noOptionLabel={ __( 'All' ) }
+							selectedCategoryId={ props.selectedCategoryId }
+							onChange={ props.onCategoryChange }
+						/>
+					),
+				isMultipleCategorySelection( props ) &&
+					props.categorySuggestions &&
+					props.onCategoryChange && (
+						<FormTokenField
+							key="query-controls-categories-select"
+							label={ __( 'Categories' ) }
+							value={
+								props.selectedCategories &&
+								props.selectedCategories.map( ( item ) => ( {
+									id: item.id,
+									// Keeping the fallback to `item.value` for legacy reasons,
+									// even if items of `selectedCategories` should not have a
+									// `value` property.
+									// @ts-expect-error
+									value: item.name || item.value,
+								} ) )
+							}
+							suggestions={ Object.keys(
+								props.categorySuggestions
+							) }
+							onChange={ props.onCategoryChange }
+							maxSuggestions={ MAX_CATEGORIES_SUGGESTIONS }
+						/>
+					),
+				onAuthorChange && (
+					<AuthorSelect
+						key="query-controls-author-select"
+						authorList={ authorList }
+						label={ __( 'Author' ) }
+						noOptionLabel={ __( 'All' ) }
+						selectedAuthorId={ selectedAuthorId }
+						onChange={ onAuthorChange }
+					/>
+				),
+				onNumberOfItemsChange && (
+					<RangeControl
+						__nextHasNoMarginBottom
+						key="query-controls-range-control"
+						label={ __( 'Number of items' ) }
+						value={ numberOfItems }
+						onChange={ onNumberOfItemsChange }
+						min={ minItems }
+						max={ maxItems }
+						required
+					/>
+				),
+			] }
+		</>
+	);
+}
+
+export default QueryControls;

package/src/query-controls/stories/index.tsx

@@ -0,0 +1,205 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import QueryControls from '..';
+import type {
+	Category,
+	QueryControlsWithSingleCategorySelectionProps,
+	QueryControlsWithMultipleCategorySelectionProps,
+} from '../types';
+
+const meta: ComponentMeta< typeof QueryControls > = {
+	title: 'Components/QueryControls',
+	component: QueryControls,
+	argTypes: {
+		numberOfItems: { control: { type: null } },
+		order: { control: { type: null } },
+		orderBy: { control: { type: null } },
+		selectedAuthorId: { control: { type: null } },
+		selectedCategories: { control: { type: null } },
+		selectedCategoryId: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+export const Default: ComponentStory< typeof QueryControls > = ( args ) => {
+	const {
+		onAuthorChange,
+		onCategoryChange,
+		onNumberOfItemsChange,
+		onOrderByChange,
+		onOrderChange,
+		...props
+	} = args as QueryControlsWithMultipleCategorySelectionProps;
+	const [ ownNumberOfItems, setOwnNumberOfItems ] = useState(
+		props.numberOfItems
+	);
+	const [ ownOrder, setOwnOrder ] = useState( props.order );
+	const [ ownOrderBy, setOwnOrderBy ] = useState( props.orderBy );
+	const [ ownSelectedAuthorId, setOwnSelectedAuthorId ] = useState(
+		props.selectedAuthorId
+	);
+	const [ ownSelectedCategories, setOwnSelectedCategories ] = useState(
+		props.selectedCategories
+	);
+
+	const handleCategoryChange: QueryControlsWithMultipleCategorySelectionProps[ 'onCategoryChange' ] =
+		( tokens ) => {
+			onCategoryChange?.( tokens );
+
+			const hasNoSuggestion = tokens.some(
+				( token ) =>
+					typeof token === 'string' &&
+					! props.categorySuggestions?.[ token ]
+			);
+			if ( hasNoSuggestion ) {
+				return;
+			}
+			const allCategories = tokens
+				.map( ( token ) => {
+					return typeof token === 'string'
+						? props.categorySuggestions?.[ token ]
+						: token;
+				} )
+				.filter( Boolean ) as Array< Required< Category > >;
+
+			setOwnSelectedCategories( allCategories );
+		};
+
+	return (
+		<QueryControls
+			{ ...props }
+			numberOfItems={ ownNumberOfItems }
+			onCategoryChange={ handleCategoryChange }
+			onOrderByChange={ ( newOrderBy ) => {
+				onOrderByChange?.( newOrderBy );
+				setOwnOrderBy( newOrderBy );
+			} }
+			onOrderChange={ ( newOrder ) => {
+				onOrderChange?.( newOrder );
+				setOwnOrder( newOrder );
+			} }
+			order={ ownOrder }
+			orderBy={ ownOrderBy }
+			onNumberOfItemsChange={ ( newNumber ) => {
+				onNumberOfItemsChange?.( newNumber );
+				setOwnNumberOfItems( newNumber );
+			} }
+			onAuthorChange={ ( newAuthor ) => {
+				onAuthorChange?.( newAuthor );
+				setOwnSelectedAuthorId( Number( newAuthor ) );
+			} }
+			selectedAuthorId={ ownSelectedAuthorId }
+			selectedCategories={ ownSelectedCategories }
+		/>
+	);
+};
+
+Default.args = {
+	authorList: [
+		{
+			id: 1,
+			name: 'admin',
+		},
+		{
+			id: 2,
+			name: 'editor',
+		},
+	],
+	categorySuggestions: {
+		TypeScript: {
+			id: 11,
+			name: 'TypeScript',
+			parent: 0,
+		},
+		JavaScript: {
+			id: 12,
+			name: 'JavaScript',
+			parent: 0,
+		},
+	},
+	selectedCategories: [
+		{
+			id: 11,
+			name: 'JavaScript',
+			parent: 0,
+		},
+	],
+	numberOfItems: 5,
+	order: 'desc',
+	orderBy: 'date',
+	selectedAuthorId: 1,
+};
+
+const SingleCategoryTemplate: ComponentStory< typeof QueryControls > = (
+	args
+) => {
+	const {
+		onAuthorChange,
+		onCategoryChange,
+		onNumberOfItemsChange,
+		onOrderByChange,
+		onOrderChange,
+		...props
+	} = args as QueryControlsWithSingleCategorySelectionProps;
+	const [ ownOrder, setOwnOrder ] = useState( props.order );
+	const [ ownOrderBy, setOwnOrderBy ] = useState( props.orderBy );
+	const [ ownSelectedCategoryId, setSelectedCategoryId ] = useState(
+		props.selectedCategoryId
+	);
+
+	const handleCategoryChange: QueryControlsWithSingleCategorySelectionProps[ 'onCategoryChange' ] =
+		( newCategory ) => {
+			onCategoryChange?.( newCategory );
+			setSelectedCategoryId( Number( newCategory ) );
+		};
+
+	return (
+		<QueryControls
+			{ ...props }
+			onCategoryChange={ handleCategoryChange }
+			onOrderByChange={ ( newOrderBy ) => {
+				setOwnOrderBy( newOrderBy );
+			} }
+			onOrderChange={ ( newOrder ) => {
+				onOrderChange?.( newOrder );
+				setOwnOrder( newOrder );
+			} }
+			order={ ownOrder }
+			orderBy={ ownOrderBy }
+			selectedCategoryId={ ownSelectedCategoryId }
+		/>
+	);
+};
+export const SelectSingleCategory: ComponentStory< typeof QueryControls > =
+	SingleCategoryTemplate.bind( {} );
+SelectSingleCategory.args = {
+	categoriesList: [
+		{
+			id: 11,
+			name: 'TypeScript',
+			parent: 0,
+		},
+		{
+			id: 12,
+			name: 'JavaScript',
+			parent: 0,
+		},
+	],
+	selectedCategoryId: 11,
+};