@wordpress/components 25.12.0 → 25.14.0

package/src/tabs/types.ts

@@ -78,8 +78,10 @@ export type TabListProps = {
 export type TabProps = {
 	/**
 	 * The id of the tab, which is prepended with the `Tabs` instanceId.
+	 * The value of this prop should match with the value of the `tabId` prop on
+	 * the corresponding `Tabs.TabPanel` component.
 	 */
-	id: string;
+	tabId: string;
 	/**
 	 * The children elements, generally the text to display on the tab.
 	 */
@@ -103,9 +105,12 @@ export type TabPanelProps = {
 	 */
 	children?: React.ReactNode;
 	/**
-	 * A unique identifier for the tabpanel, which is used to generate a unique `id` for the underlying element.
+	 * A unique identifier for the tabpanel, which is used to generate an
+	 * instanced id for the underlying element.
+	 * The value of this prop should match with the value of the `tabId` prop on
+	 * the corresponding `Tabs.Tab` component.
 	 */
-	id: string;
+	tabId: string;
 	/**
 	 * Determines whether or not the tabpanel element should be focusable.
 	 * If `false`, pressing the tab key will skip over the tabpanel, and instead

package/src/text/README.md

@@ -132,6 +132,8 @@ function Example() {
 
 Sets `Text` to have `display: block`.
 
+Note: text truncation only works when `isBlock` is `false`.
+
 ### isDestructive
 
 **Type**: `boolean`
@@ -196,7 +198,9 @@ function Example() {
 
 **Type**: `boolean`
 
-Enables text truncation. When `truncate` is set,we are able to truncate the long text in a variety of ways.
+Enables text truncation. When `truncate` is set, we are able to truncate the long text in a variety of ways.
+
+Note: text truncation won't work if the `isBlock` property is set to `true`
 
 ```jsx
 import { __experimentalText as Text } from '@wordpress/components';

package/src/text/types.ts

@@ -46,10 +46,14 @@ export interface Props extends TruncateProps {
 	isDestructive?: boolean;
 	/**
 	 * Escape characters in `highlightWords` which are meaningful in regular expressions.
+	 *
+	 * @default false
 	 */
 	highlightEscape?: boolean;
 	/**
 	 * Determines if `highlightWords` should be case sensitive.
+	 *
+	 * @default false
 	 */
 	highlightCaseSensitive?: boolean;
 	/**
@@ -57,7 +61,10 @@ export interface Props extends TruncateProps {
 	 */
 	highlightSanitize?: FindAllArgs[ 'sanitize' ];
 	/**
-	 * Sets `Text` to have `display: block`.
+	 * Sets `Text` to have `display: block`. Note: text truncation only works
+	 * when `isBlock` is `false`.
+	 *
+	 * @default false
 	 */
 	isBlock?: boolean;
 	/**
@@ -73,11 +80,15 @@ export interface Props extends TruncateProps {
 	 */
 	size?: CSSProperties[ 'fontSize' ] | TextSize;
 	/**
-	 * Enables text truncation. When `truncate` is set,we are able to truncate the long text in a variety of ways.
+	 * Enables text truncation. When `truncate` is set, we are able to truncate the long text in a variety of ways. Note: text truncation won't work if the `isBlock` property is set to `true`
+	 *
+	 * @default false
 	 */
 	truncate?: boolean;
 	/**
 	 * Uppercases the text content.
+	 *
+	 * @default false
 	 */
 	upperCase?: boolean;
 	/**
@@ -86,6 +97,8 @@ export interface Props extends TruncateProps {
 	variant?: TextVariant;
 	/**
 	 * Adjusts font-weight of the text.
+	 *
+	 * @default 'normal'
 	 */
 	weight?: CSSProperties[ 'fontWeight' ] | TextWeight;
 	/**

package/src/toggle-control/README.md

@@ -22,8 +22,8 @@ const MyToggleControl = () => {
 					: 'No fixed background.'
 			}
 			checked={ hasFixedBackground }
-			onChange={ () => {
-				setHasFixedBackground( ( state ) => ! state );
+			onChange={ (newValue) => {
+				setHasFixedBackground( newValue );
 			} }
 		/>
 	);

package/src/toggle-group-control/test/index.tsx

@@ -25,8 +25,11 @@ import cleanupTooltip from '../../tooltip/test/utils';
 const ControlledToggleGroupControl = ( {
 	value: valueProp,
 	onChange,
+	extraButtonOptions,
 	...props
-}: ToggleGroupControlProps ) => {
+}: ToggleGroupControlProps & {
+	extraButtonOptions?: { name: string; value: string }[];
+} ) => {
 	const [ value, setValue ] = useState( valueProp );
 
 	return (
@@ -40,6 +43,14 @@ const ControlledToggleGroupControl = ( {
 				value={ value }
 			/>
 			<Button onClick={ () => setValue( undefined ) }>Reset</Button>
+			{ extraButtonOptions?.map( ( obj ) => (
+				<Button
+					key={ obj.value }
+					onClick={ () => setValue( obj.value ) }
+				>
+					{ obj.name }
+				</Button>
+			) ) }
 		</>
 	);
 };
@@ -192,6 +203,48 @@ describe.each( [
 			expect( rigasOption ).not.toBeChecked();
 			expect( jackOption ).not.toBeChecked();
 		} );
+
+		it( 'should update correctly when triggered by external updates', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Component
+					value="rigas"
+					label="Test Toggle Group Control"
+					extraButtonOptions={ [
+						{ name: 'Rigas', value: 'rigas' },
+						{ name: 'Jack', value: 'jack' },
+					] }
+				>
+					{ options }
+				</Component>
+			);
+
+			expect( screen.getByRole( 'radio', { name: 'R' } ) ).toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'J' } )
+			).not.toBeChecked();
+
+			await user.click( screen.getByRole( 'button', { name: 'Jack' } ) );
+			expect( screen.getByRole( 'radio', { name: 'J' } ) ).toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'R' } )
+			).not.toBeChecked();
+
+			await user.click( screen.getByRole( 'button', { name: 'Rigas' } ) );
+			expect( screen.getByRole( 'radio', { name: 'R' } ) ).toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'J' } )
+			).not.toBeChecked();
+
+			await user.click( screen.getByRole( 'button', { name: 'Reset' } ) );
+			expect(
+				screen.getByRole( 'radio', { name: 'R' } )
+			).not.toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'J' } )
+			).not.toBeChecked();
+		} );
 	}
 
 	describe( 'isDeselectable', () => {

package/src/toggle-group-control/toggle-group-control/utils.ts

@@ -21,30 +21,25 @@ type ValueProp = ToggleGroupControlProps[ 'value' ];
 export function useComputeControlledOrUncontrolledValue(
 	valueProp: ValueProp
 ): { value: ValueProp; defaultValue: ValueProp } {
-	const hasEverBeenUsedInControlledMode = useRef( false );
-	const previousValueProp = usePrevious( valueProp );
+	const prevValueProp = usePrevious( valueProp );
+	const prevIsControlled = useRef( false );
 
+	// Assume the component is being used in controlled mode on the first re-render
+	// that has a different `valueProp` from the previous render.
+	const isControlled =
+		prevIsControlled.current ||
+		( prevValueProp !== undefined &&
+			valueProp !== undefined &&
+			prevValueProp !== valueProp );
 	useEffect( () => {
-		if ( ! hasEverBeenUsedInControlledMode.current ) {
-			// Assume the component is being used in controlled mode if:
-			// - the `value` prop is not `undefined`
-			// - the `value` prop was not previously `undefined` and was given a new value
-			hasEverBeenUsedInControlledMode.current =
-				valueProp !== undefined &&
-				previousValueProp !== undefined &&
-				valueProp !== previousValueProp;
-		}
-	}, [ valueProp, previousValueProp ] );
+		prevIsControlled.current = isControlled;
+	}, [ isControlled ] );
 
-	let value, defaultValue;
-
-	if ( hasEverBeenUsedInControlledMode.current ) {
+	if ( isControlled ) {
 		// When in controlled mode, use `''` instead of `undefined`
-		value = valueProp ?? '';
-	} else {
-		// When in uncontrolled mode, the `value` should be intended as the initial value
-		defaultValue = valueProp;
+		return { value: valueProp ?? '', defaultValue: undefined };
 	}
 
-	return { value, defaultValue };
+	// When in uncontrolled mode, the `value` should be intended as the initial value
+	return { value: undefined, defaultValue: valueProp };
 }

package/src/tools-panel/tools-panel-item/hook.ts

@@ -2,7 +2,12 @@
  * WordPress dependencies
  */
 import { usePrevious } from '@wordpress/compose';
-import { useCallback, useEffect, useMemo } from '@wordpress/element';
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+} from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -47,11 +52,14 @@ export function useToolsPanelItem(
 		__experimentalLastVisibleItemClass,
 	} = useToolsPanelContext();
 
-	const hasValueCallback = useCallback( hasValue, [ panelId, hasValue ] );
-	const resetAllFilterCallback = useCallback( resetAllFilter, [
-		panelId,
-		resetAllFilter,
-	] );
+	// hasValue is a new function on every render, so do not add it as a
+	// dependency to the useCallback hook! If needed, we should use a ref.
+	// eslint-disable-next-line react-hooks/exhaustive-deps
+	const hasValueCallback = useCallback( hasValue, [ panelId ] );
+	// resetAllFilter is a new function on every render, so do not add it as a
+	// dependency to the useCallback hook! If needed, we should use a ref.
+	// eslint-disable-next-line react-hooks/exhaustive-deps
+	const resetAllFilterCallback = useCallback( resetAllFilter, [ panelId ] );
 	const previousPanelId = usePrevious( currentPanelId );
 
 	const hasMatchingPanel =
@@ -59,7 +67,11 @@ export function useToolsPanelItem(
 
 	// Registering the panel item allows the panel to include it in its
 	// automatically generated menu and determine its initial checked status.
-	useEffect( () => {
+	//
+	// This is performed in a layout effect to ensure that the panel item
+	// is registered before it is rendered preventing a rendering glitch.
+	// See: https://github.com/WordPress/gutenberg/issues/56470
+	useLayoutEffect( () => {
 		if ( hasMatchingPanel && previousPanelId !== null ) {
 			registerPanelItem( {
 				hasValue: hasValueCallback,
@@ -117,27 +129,13 @@ export function useToolsPanelItem(
 	const newValueSet = isValueSet && ! wasValueSet;
 
 	// Notify the panel when an item's value has been set.
-	//
-	// 1. For default controls, this is so "reset" appears beside its menu item.
-	// 2. For optional controls, when the panel ID is `null`, it allows the
-	// panel to ensure the item is toggled on for display in the menu, given the
-	// value has been set external to the control.
 	useEffect( () => {
 		if ( ! newValueSet ) {
 			return;
 		}
 
-		if ( isShownByDefault || currentPanelId === null ) {
-			flagItemCustomization( label, menuGroup );
-		}
-	}, [
-		currentPanelId,
-		newValueSet,
-		isShownByDefault,
-		menuGroup,
-		label,
-		flagItemCustomization,
-	] );
+		flagItemCustomization( label, menuGroup );
+	}, [ newValueSet, menuGroup, label, flagItemCustomization ] );
 
 	// Determine if the panel item's corresponding menu is being toggled and
 	// trigger appropriate callback if it is.