@wordpress/components 23.4.0 → 23.6.0

package/src/palette-edit/types.ts

@@ -0,0 +1,126 @@
+/**
+ * External dependencies
+ */
+import type { Key, MouseEventHandler } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { HeadingSize } from '../heading/types';
+
+export type Color = {
+	color: string;
+	name: string;
+	slug: string;
+	gradient?: never;
+};
+
+export type Gradient = {
+	gradient: string;
+	name: string;
+	slug: string;
+	color?: never;
+};
+
+export type PaletteElement = Color | Gradient;
+
+export type BasePaletteEdit = {
+	/**
+	 * Whether the user can only change the color or gradient values.
+	 * If true, they cannot change names or delete values.
+	 *
+	 * @default false
+	 */
+	canOnlyChangeValues?: boolean;
+	/**
+	 * Whether the user can reset the editor.
+	 *
+	 * @default false
+	 */
+	canReset?: boolean;
+	/**
+	 * A message to show if there's nothing to edit.
+	 */
+	emptyMessage?: string;
+	/**
+	 * A heading label for the palette.
+	 */
+	paletteLabel: string;
+	/**
+	 * The label's heading level.
+	 *
+	 * @default 2
+	 */
+	paletteLabelHeadingLevel?: HeadingSize;
+	/**
+	 * The prefix for the element slug.
+	 *
+	 * @default ''
+	 */
+	slugPrefix?: string;
+};
+
+type PaletteEditColors = {
+	/**
+	 * The colors in the palette.
+	 */
+	colors?: Color[];
+	/**
+	 * Runs on changing the value.
+	 */
+	onChange: ( values?: Color[] ) => void;
+	gradients?: never;
+};
+
+type PaletteEditGradients = {
+	/**
+	 * The gradients in the palette.
+	 */
+	gradients: Gradient[];
+	/**
+	 * Runs on changing the value.
+	 */
+	onChange: ( values?: Gradient[] ) => void;
+	colors?: never;
+};
+
+export type PaletteEditProps = BasePaletteEdit &
+	( PaletteEditColors | PaletteEditGradients );
+
+type EditingElement = number | null;
+
+export type ColorPickerPopoverProps< T extends Color | Gradient > = {
+	element: T;
+	onChange: ( newElement: T ) => void;
+	isGradient?: T extends Gradient ? true : false;
+	onClose?: () => void;
+};
+
+export type NameInputProps = {
+	label: string;
+	onChange: ( nextName?: PaletteElement[ 'name' ] ) => void;
+	value: PaletteElement[ 'name' ];
+};
+
+export type OptionProps< T extends Color | Gradient > = {
+	element: T;
+	onChange: ( newElement: T ) => void;
+	isGradient: T extends Gradient ? true : false;
+	canOnlyChangeValues: PaletteEditProps[ 'canOnlyChangeValues' ];
+	isEditing: boolean;
+	key: Key;
+	onRemove: MouseEventHandler< HTMLButtonElement >;
+	onStartEditing: () => void;
+	onStopEditing: () => void;
+	slugPrefix: string;
+};
+
+export type PaletteEditListViewProps< T extends Color | Gradient > = {
+	elements: T[];
+	onChange: ( newElements?: T[] ) => void;
+	isGradient: T extends Gradient ? true : false;
+	canOnlyChangeValues: PaletteEditProps[ 'canOnlyChangeValues' ];
+	editingElement?: EditingElement;
+	setEditingElement: ( newEditingElement?: EditingElement ) => void;
+	slugPrefix: string;
+};

package/src/panel/README.md

@@ -77,20 +77,25 @@ const MyPanel = () => (
 
 ##### Props
 
-###### className
+###### `header`: `string`
 
-The class that will be added with `components-panel`. If no `className` is passed only `components-panel__body` and `is-opened` is used.
+The text that will be rendered as the title of the panel. Text will be rendered inside an
+`<h2>` tag.
 
--   Type: `String`
 -   Required: No
 
-###### header
+###### `className`: `string`
 
-Title of the `Panel`. Text will be rendered inside an `<h2>` tag.
+The CSS class to apply to the wrapper element.
 
--   Type: `String`
 -   Required: No
 
+###### `children`: `React.ReactNode`
+
+The content to display within the panel row.
+
+-   Required: Yes
+
 ---
 
 #### PanelBody
@@ -99,64 +104,67 @@ The `PanelBody` creates a collapsible container that can be toggled open or clos
 
 ##### Props
 
-###### title
+###### `title`: `string`
 
-Title of the `PanelBody`. This shows even when it is closed.
+Title text. It shows even when the component is closed.
 
--   Type: `String`
 -   Required: No
 
-###### opened
+###### `opened`: `boolean`
 
-If opened is true then the `Panel` will remain open regardless of the `initialOpen` prop and the panel will be prevented from being closed.
+When set to `true`, the component will remain open regardless of the `initialOpen` prop and the
+panel will be prevented from being closed.
 
--   Type: `Boolean`
 -   Required: No
 
-###### className
+###### `className`: `string`
 
-The class that will be added with `components-panel__body`, if the panel is currently open, the `is-opened` class will also be passed to the classes of the wrapper div. If no `className` is passed then only `components-panel__body` and `is-opened` is used.
+The CSS class to apply to the wrapper element.
 
--   Type: `String`
 -   Required: No
 
-###### icon
+###### `icon`: `JSX.Element`
 
-An icon to be shown next to the `PanelBody` title.
+An icon to be shown next to the title.
 
--   Type: `String`
 -   Required: No
 
-###### onToggle
+###### `onToggle`: `( next: boolean ) => void;`
 
-A function that is called when the user clicks on the `PanelBody` title after the open state is changed.
+A function that is called any time the component is toggled from its closed state to its
+opened state, or vice versa.
 
--   Type: `function`
 -   Required: No
+-   Default: `noop`
 
-###### initialOpen
+###### `initialOpen`: `boolean`
 
 Whether or not the panel will start open.
 
--   Type: `Boolean`
 -   Required: No
--   Default: true
+-   Default: `true`
 
-###### children
+###### `children`: `| React.ReactNode | ( ( props: { opened: boolean } ) => React.ReactNode )`
 
-The rendered children. If the children is a `Function`, it will be called with an object with the `opened` property and return its value.
+The content to display in the `PanelBody`. If a function is provided for this prop, it will receive an object with the `opened` prop as an argument.
 
--   Type: `React.ReactNode | Function`
 -   Required: No
 
-###### buttonProps
+###### `buttonProps`: `WordPressComponentProps<Omit< ButtonAsButtonProps, 'icon' >, 'button', false>`
 
-Props that are passed to the `Button` component in the `PanelBodyTitle` within the panel body.
+Props that are passed to the `Button` component in title within the `PanelBody`.
 
--   Type: `Object`
 -   Required: No
 -   Default: `{}`
 
+###### `scrollAfterOpen`: `boolean`
+
+Scrolls the content into view when visible. This improves the UX when multiple `PanelBody`
+components are stacked in a scrollable container.
+
+-   Required: No
+-   Default: `true`
+
 ---
 
 #### PanelRow
@@ -165,11 +173,16 @@ Props that are passed to the `Button` component in the `PanelBodyTitle` within t
 
 ##### Props
 
-###### className
+###### `className`: `string`
 
-The class that will be added with `components-panel__row`. to the classes of the wrapper div. If no `className` is passed only `components-panel__row` is used.
+The CSS class to apply to the wrapper element.
+
+-   Required: No
+
+###### `children`: `React.ReactNode`
+
+The content to display within the panel row.
 
--   Type: `String`
 -   Required: No
 
 ##### Ref
@@ -186,11 +199,16 @@ PanelRow accepts a forwarded ref that will be added to the wrapper div. Usage:
 
 ##### Props
 
-###### label
+###### `label`: `string`
 
 The text that will be rendered as the title of the `Panel`. Will be rendered in an `<h2>` tag.
 
--   Type: `String`
+-   Required: No
+
+###### `children`: `React.ReactNode`
+
+The content to display within the panel row.
+
 -   Required: No
 
 ## Related components

package/src/panel/{body.js → body.tsx}

@@ -13,14 +13,19 @@ import { chevronUp, chevronDown } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import type { PanelBodyProps, PanelBodyTitleProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 import Button from '../button';
 import Icon from '../icon';
 import { useControlledState, useUpdateEffect } from '../utils';
 
 const noop = () => {};
 
-export function PanelBody(
-	{
+export function UnforwardedPanelBody(
+	props: PanelBodyProps,
+	ref: React.ForwardedRef< HTMLDivElement >
+) {
+	const {
 		buttonProps = {},
 		children,
 		className,
@@ -30,19 +35,21 @@ export function PanelBody(
 		opened,
 		title,
 		scrollAfterOpen = true,
-	},
-	ref
-) {
-	const [ isOpened, setIsOpened ] = useControlledState( opened, {
-		initial: initialOpen === undefined ? true : initialOpen,
-	} );
-	const nodeRef = useRef();
+	} = props;
+	const [ isOpened, setIsOpened ] = useControlledState< boolean | undefined >(
+		opened,
+		{
+			initial: initialOpen === undefined ? true : initialOpen,
+			fallback: false,
+		}
+	);
+	const nodeRef = useRef< HTMLElement >( null );
 
 	// Defaults to 'smooth' scrolling
 	// https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
 	const scrollBehavior = useReducedMotion() ? 'auto' : 'smooth';
 
-	const handleOnToggle = ( event ) => {
+	const handleOnToggle = ( event: React.MouseEvent ) => {
 		event.preventDefault();
 		const next = ! isOpened;
 		setIsOpened( next );
@@ -50,7 +57,7 @@ export function PanelBody(
 	};
 
 	// Ref is used so that the effect does not re-run upon scrollAfterOpen changing value.
-	const scrollAfterOpenRef = useRef();
+	const scrollAfterOpenRef = useRef< boolean | undefined >();
 	scrollAfterOpenRef.current = scrollAfterOpen;
 	// Runs after initial render.
 	useUpdateEffect( () => {
@@ -80,20 +87,28 @@ export function PanelBody(
 		<div className={ classes } ref={ useMergeRefs( [ nodeRef, ref ] ) }>
 			<PanelBodyTitle
 				icon={ icon }
-				isOpened={ isOpened }
+				isOpened={ Boolean( isOpened ) }
 				onClick={ handleOnToggle }
 				title={ title }
 				{ ...buttonProps }
 			/>
 			{ typeof children === 'function'
-				? children( { opened: isOpened } )
+				? children( { opened: Boolean( isOpened ) } )
 				: isOpened && children }
 		</div>
 	);
 }
 
 const PanelBodyTitle = forwardRef(
-	( { isOpened, icon, title, ...props }, ref ) => {
+	(
+		{
+			isOpened,
+			icon,
+			title,
+			...props
+		}: WordPressComponentProps< PanelBodyTitleProps, 'button' >,
+		ref: React.ForwardedRef< any >
+	) => {
 		if ( ! title ) return null;
 
 		return (
@@ -128,7 +143,6 @@ const PanelBodyTitle = forwardRef(
 	}
 );
 
-const ForwardedComponent = forwardRef( PanelBody );
-ForwardedComponent.displayName = 'PanelBody';
+export const PanelBody = forwardRef( UnforwardedPanelBody );
 
-export default ForwardedComponent;
+export default PanelBody;

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

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
@@ -11,7 +16,7 @@ import InputControl from '../../input-control';
  */
 import { wordpress } from '@wordpress/icons';
 
-export default {
+const meta: ComponentMeta< typeof Panel > = {
 	title: 'Components/Panel',
 	component: Panel,
 	subcomponents: { PanelRow, PanelBody },
@@ -23,10 +28,13 @@ export default {
 		docs: { source: { state: 'open' } },
 	},
 };
+export default meta;
 
-const Template = ( props ) => <Panel { ...props } />;
+const Template: ComponentStory< typeof Panel > = ( props ) => (
+	<Panel { ...props } />
+);
 
-export const Default = Template.bind( {} );
+export const Default: ComponentStory< typeof Panel > = Template.bind( {} );
 Default.args = {
 	header: 'My panel',
 	children: (
@@ -61,7 +69,7 @@ Default.args = {
  * `PanelRow` is a generic container for rows within a `PanelBody`.
  * It is a flex container with a top margin for spacing.
  */
-export const _PanelRow = Template.bind( {} );
+export const _PanelRow: ComponentStory< typeof Panel > = Template.bind( {} );
 _PanelRow.args = {
 	children: (
 		<PanelBody title="My Profile">
@@ -78,7 +86,9 @@ _PanelRow.args = {
 	),
 };
 
-export const DisabledSection = Template.bind( {} );
+export const DisabledSection: ComponentStory< typeof Panel > = Template.bind(
+	{}
+);
 DisabledSection.args = {
 	...Default.args,
 	children: (
@@ -90,7 +100,7 @@ DisabledSection.args = {
 	),
 };
 
-export const WithIcon = Template.bind( {} );
+export const WithIcon: ComponentStory< typeof Panel > = Template.bind( {} );
 WithIcon.args = {
 	...Default.args,
 	children: (

package/src/panel/test/{body.js → body.tsx}

@@ -89,9 +89,7 @@ describe( 'PanelBody', () => {
 				</PanelBody>
 			);
 
-			let panelContent = screen.getByTestId( 'inner-content' );
-
-			expect( panelContent ).toBeVisible();
+			expect( screen.getByTestId( 'inner-content' ) ).toBeVisible();
 
 			rerender(
 				<PanelBody opened={ false }>
@@ -99,9 +97,9 @@ describe( 'PanelBody', () => {
 				</PanelBody>
 			);
 
-			panelContent = screen.queryByTestId( 'inner-content' );
-
-			expect( panelContent ).not.toBeInTheDocument();
+			expect(
+				screen.queryByTestId( 'inner-content' )
+			).not.toBeInTheDocument();
 
 			rerender(
 				<PanelBody opened>
@@ -109,9 +107,7 @@ describe( 'PanelBody', () => {
 				</PanelBody>
 			);
 
-			panelContent = screen.getByTestId( 'inner-content' );
-
-			expect( panelContent ).toBeVisible();
+			expect( screen.getByTestId( 'inner-content' ) ).toBeVisible();
 		} );
 
 		it( 'should toggle when clicking header', async () => {
@@ -123,22 +119,21 @@ describe( 'PanelBody', () => {
 				</PanelBody>
 			);
 
-			let panelContent = screen.queryByTestId( 'inner-content' );
 			const panelToggle = screen.getByRole( 'button', { name: 'Panel' } );
 
-			expect( panelContent ).not.toBeInTheDocument();
+			expect(
+				screen.queryByTestId( 'inner-content' )
+			).not.toBeInTheDocument();
 
 			await user.click( panelToggle );
 
-			panelContent = screen.getByTestId( 'inner-content' );
-
-			expect( panelContent ).toBeVisible();
+			expect( screen.getByTestId( 'inner-content' ) ).toBeVisible();
 
 			await user.click( panelToggle );
 
-			panelContent = screen.queryByTestId( 'inner-content' );
-
-			expect( panelContent ).not.toBeInTheDocument();
+			expect(
+				screen.queryByTestId( 'inner-content' )
+			).not.toBeInTheDocument();
 		} );
 
 		it( 'should pass button props to panel title', async () => {

package/src/panel/types.ts

@@ -1,3 +1,9 @@
+/**
+ * Internal dependencies
+ */
+import type { ButtonAsButtonProps } from '../button/types';
+import type { WordPressComponentProps } from '../ui/context';
+
 export type PanelProps = {
 	/**
 	 * The text that will be rendered as the title of the panel.
@@ -36,3 +42,75 @@ export type PanelRowProps = {
 	 */
 	children: React.ReactNode;
 };
+
+export type PanelBodyProps = {
+	/**
+	 * Props that are passed to the `Button` component in title within the
+	 * `PanelBody`.
+	 *
+	 * @default {}
+	 */
+	buttonProps?: WordPressComponentProps<
+		Omit< ButtonAsButtonProps, 'icon' >,
+		'button',
+		false
+	>;
+	/**
+	 * The content to display in the `PanelBody`.If a function is provided for
+	 * this prop, it will receive an object with the `opened` prop as an argument.
+	 */
+	children?:
+		| React.ReactNode
+		| ( ( props: { opened: boolean } ) => React.ReactNode );
+
+	/**
+	 * The CSS class to apply to the wrapper element.
+	 */
+	className?: string;
+	/**
+	 * An icon to be shown next to the title.
+	 */
+	icon?: JSX.Element;
+	/**
+	 * Whether or not the panel will start open.
+	 */
+	initialOpen?: boolean;
+	/**
+	 * A function that is called any time the component is toggled from its closed
+	 * state to its opened state, or vice versa.
+	 *
+	 * @default noop
+	 */
+	onToggle?: ( next: boolean ) => void;
+	/**
+	 * When set to `true`, the component will remain open regardless of the
+	 * `initialOpen` prop and the panel will be prevented from being closed.
+	 */
+	opened?: boolean;
+	/**
+	 * Title text. It shows even when it is closed.
+	 */
+	title?: string;
+	/**
+	 * Scrolls the content into view when visible. This improves the UX when
+	 * multiple `PanelBody` components are stacked in a scrollable container.
+	 *
+	 * @default true
+	 */
+	scrollAfterOpen?: boolean;
+};
+
+export type PanelBodyTitleProps = Omit< ButtonAsButtonProps, 'icon' > & {
+	/**
+	 * An icon to be shown next to the title.
+	 */
+	icon?: JSX.Element;
+	/**
+	 * Whether or not the `PanelBody` is currently opened or not.
+	 */
+	isOpened?: boolean;
+	/**
+	 * The title text.
+	 */
+	title?: string;
+};

package/src/placeholder/index.tsx

@@ -38,12 +38,8 @@ const PlaceholderIllustration = (
  * const MyPlaceholder = () => <Placeholder icon={ more } label="Placeholder" />;
  * ```
  */
-export function Placeholder< IconProps = unknown >(
-	props: WordPressComponentProps<
-		PlaceholderProps< IconProps >,
-		'div',
-		false
-	>
+export function Placeholder(
+	props: WordPressComponentProps< PlaceholderProps, 'div', false >
 ) {
 	const {
 		icon,

package/src/placeholder/test/index.tsx

@@ -34,7 +34,7 @@ const testIcon = (
 
 const Placeholder = (
 	props: Omit<
-		WordPressComponentProps< PlaceholderProps< unknown >, 'div', false >,
+		WordPressComponentProps< PlaceholderProps, 'div', false >,
 		'ref'
 	>
 ) => <BasePlaceholder data-testid="placeholder" { ...props } />;

package/src/placeholder/types.ts

@@ -8,7 +8,7 @@ import type { ReactNode } from 'react';
  */
 import type { IconType } from '../icon';
 
-export type PlaceholderProps< IconProps = unknown > = {
+export type PlaceholderProps = {
 	/**
 	 * The children elements.
 	 */
@@ -20,7 +20,7 @@ export type PlaceholderProps< IconProps = unknown > = {
 	/**
 	 * If provided, renders an icon next to the label.
 	 */
-	icon?: IconType< IconProps >;
+	icon?: IconType;
 	/**
 	 * Instructions of the placeholder.
 	 */

package/src/popover/test/index.tsx

@@ -138,9 +138,12 @@ describe( 'Popover', () => {
 		} );
 
 		describe( 'focus behavior', () => {
-			it( 'should focus the popover by default when opened', async () => {
+			it( 'should focus the popover container when opened', async () => {
 				render(
-					<Popover data-testid="popover-element">
+					<Popover
+						focusOnMount={ true }
+						data-testid="popover-element"
+					>
 						Popover content
 					</Popover>
 				);

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

@@ -3,7 +3,6 @@
  */
 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( {
@@ -20,11 +19,7 @@ export default function AuthorSelect( {
 			{ ...{
 				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' ],
+				onChange: onChangeProp,
 			} }
 			tree={ termsTree }
 			selectedId={