@wordpress/components 28.10.0 → 28.12.0

package/src/tabs/types.ts

@@ -18,98 +18,138 @@ export type TabsContextProps =
 
 export type TabsProps = {
 	/**
-	 * The children elements, which should be at least a
-	 * `Tabs.Tablist` component and a series of `Tabs.TabPanel`
-	 * components.
+	 * The children elements, which should include one instance of the
+	 * `Tabs.Tablist` component and as many instances of the `Tabs.TabPanel`
+	 * components as there are `Tabs.Tab` components.
 	 */
-	children: React.ReactNode;
+	children: Ariakit.TabProps[ 'children' ];
 	/**
-	 * When `true`, the tab will be selected when receiving focus (automatic tab
-	 * activation). When `false`, the tab will be selected only when clicked
-	 * (manual tab activation). See the official W3C docs for more info.
+	 * Determines if the tab should be selected when it receives focus. If set to
+	 * `false`, the tab will only be selected upon clicking, not when using arrow
+	 * keys to shift focus (manual tab activation). See the official W3C docs
+	 * for more info.
 	 *
 	 * @default true
 	 *
 	 * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/
 	 */
-	selectOnMove?: boolean;
+	selectOnMove?: Ariakit.TabStoreProps[ 'selectOnMove' ];
 	/**
-	 * The id of the tab to be selected upon mounting of component.
-	 * If this prop is not set, the first tab will be selected by default.
-	 * The id provided will be internally prefixed with the
-	 * `TabsContextProps.instanceId`.
+	 * The id of the tab whose panel is currently visible.
+	 *
+	 * If left `undefined`, it will be automatically set to the first enabled
+	 * tab, and the component assumes it is being used in "uncontrolled" mode.
+	 *
+	 * Consequently, any value different than `undefined` will set the component
+	 * in "controlled" mode. When in "controlled" mode, the `null` value will
+	 * result in no tabs being selected, and the tablist becoming tabbable.
+	 */
+	selectedTabId?: Ariakit.TabStoreProps[ 'selectedId' ];
+	/**
+	 * The id of the tab whose panel is currently visible.
+	 *
+	 * If left `undefined`, it will be automatically set to the first enabled
+	 * tab. If set to `null`, no tab will be selected, and the tablist will be
+	 * tabbable.
 	 *
 	 * Note: this prop will be overridden by the `selectedTabId` prop if it is
-	 * provided. (Controlled Mode)
+	 * provided (meaning the component will be used in "controlled" mode).
 	 */
-	defaultTabId?: string;
+	defaultTabId?: Ariakit.TabStoreProps[ 'defaultSelectedId' ];
 	/**
-	 * The function called when a tab has been selected.
-	 * It is passed the id of the newly selected tab as an argument.
+	 * The function called when the `selectedTabId` changes.
 	 */
-	onSelect?: ( selectedId: string | null | undefined ) => void;
-
+	onSelect?: Ariakit.TabStoreProps[ 'setSelectedId' ];
 	/**
-	 * The orientation of the tablist.
+	 * The current active tab `id`. The active tab is the tab element within the
+	 * tablist widget that has DOM focus.
+	 * - `null` represents the tablist (ie. the base composite element). Users
+	 *   will be able to navigate out of it using arrow keys.
+	 * - If `activeTabId` is initially set to `null`, the base composite element
+	 *   itself will have focus and users will be able to navigate to it using
+	 *   arrow keys.activeTabId
+	 */
+	activeTabId?: Ariakit.TabStoreProps[ 'activeId' ];
+	/**
+	 * The tab id that should be active by default when the composite widget is
+	 * rendered. If `null`, the tablist element itself will have focus
+	 * and users will be able to navigate to it using arrow keys. If `undefined`,
+	 * the first enabled item will be focused.
 	 *
-	 * @default `horizontal`
+	 * Note: this prop will be overridden by the `activeTabId` prop if it is
+	 * provided.
+	 */
+	defaultActiveTabId?: Ariakit.TabStoreProps[ 'defaultActiveId' ];
+	/**
+	 * A callback that gets called when the `activeTabId` state changes.
 	 */
-	orientation?: 'horizontal' | 'vertical';
+	onActiveTabIdChange?: Ariakit.TabStoreProps[ 'setActiveId' ];
 	/**
-	 * The Id of the tab to display. This id is prepended with the `Tabs`
-	 * instanceId internally.
+	 * Defines the orientation of the tablist and determines which arrow keys
+	 * can be used to move focus:
+	 * - `both`: all arrow keys work.
+	 * - `horizontal`: only left and right arrow keys work.
+	 * - `vertical`: only up and down arrow keys work.
 	 *
-	 * If left `undefined`, the component assumes it is being used in
-	 * uncontrolled mode. Consequently, any value different than `undefined`
-	 * will set the component in `controlled` mode.
-	 * When in controlled mode, the `null` value will result in no tab being selected.
+	 * @default "horizontal"
 	 */
-	selectedTabId?: string | null;
+	orientation?: Ariakit.TabStoreProps[ 'orientation' ];
 };
 
 export type TabListProps = {
 	/**
-	 * The children elements, which should be a series of `Tabs.TabPanel` components.
+	 * The children elements, which should include one or more instances of the
+	 * `Tabs.Tab` component.
 	 */
-	children?: React.ReactNode;
+	children: Ariakit.TabListProps[ 'children' ];
 };
 
+// TODO: consider prop name changes (tabId, selectedTabId)
+// switch to auto-generated README
+// compound technique
+
 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.
+	 * The unique ID of the tab. It will be used to register the tab and match
+	 * it to a corresponding `Tabs.TabPanel` component.
 	 */
-	tabId: string;
+	tabId: NonNullable< Ariakit.TabProps[ 'id' ] >;
 	/**
-	 * The children elements, generally the text to display on the tab.
+	 * The contents of the tab.
 	 */
-	children?: React.ReactNode;
+	children?: Ariakit.TabProps[ 'children' ];
 	/**
-	 * Determines if the tab button should be disabled.
+	 * Determines if the tab should be disabled. Note that disabled tabs can
+	 * still be accessed via the keyboard when navigating through the tablist.
 	 *
 	 * @default false
 	 */
-	disabled?: boolean;
+	disabled?: Ariakit.TabProps[ 'disabled' ];
 	/**
-	 * The type of component to render the tab button as. If this prop is not
-	 * provided, the tab button will be rendered as a `button` element.
+	 * Allows the component to be rendered as a different HTML element or React
+	 * component. The value can be a React element or a function that takes in the
+	 * original component props and gives back a React element with the props
+	 * merged.
+	 *
+	 * By default, the tab will be rendered as a `button` element.
 	 */
-	render?: React.ReactElement;
+	render?: Ariakit.TabProps[ 'render' ];
 };
 
 export type TabPanelProps = {
 	/**
-	 * The children elements, generally the content to display on the tabpanel.
+	 * The contents of the tab panel.
 	 */
-	children?: React.ReactNode;
+	children?: Ariakit.TabPanelProps[ 'children' ];
 	/**
-	 * 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.
+	 * The unique `id` of the `Tabs.Tab` component controlling this panel. This
+	 * connection is used to assign the `aria-labelledby` attribute to the tab
+	 * panel and to determine if the tab panel should be visible.
+	 *
+	 * If not provided, this link is automatically established by matching the
+	 * order of `Tabs.Tab` and `Tabs.TabPanel` elements in the DOM.
 	 */
-	tabId: string;
+	tabId: NonNullable< Ariakit.TabPanelProps[ 'tabId' ] >;
 	/**
 	 * Determines whether or not the tabpanel element should be focusable.
 	 * If `false`, pressing the tab key will skip over the tabpanel, and instead
@@ -117,5 +157,5 @@ export type TabPanelProps = {
 	 *
 	 * @default true
 	 */
-	focusable?: boolean;
+	focusable?: Ariakit.TabPanelProps[ 'focusable' ];
 };

package/src/text/stories/index.story.tsx

@@ -10,7 +10,8 @@ import { Text } from '../component';
 
 const meta: Meta< typeof Text > = {
 	component: Text,
-	title: 'Components (Experimental)/Text',
+	title: 'Components (Experimental)/Typography/Text',
+	id: 'components-experimental-text',
 	argTypes: {
 		as: { control: { type: 'text' } },
 		color: { control: { type: 'color' } },

package/src/text-highlight/stories/index.story.tsx

@@ -10,7 +10,8 @@ import TextHighlight from '..';
 
 const meta: Meta< typeof TextHighlight > = {
 	component: TextHighlight,
-	title: 'Components/TextHighlight',
+	title: 'Components/Typography/TextHighlight',
+	id: 'components-texthighlight',
 	parameters: {
 		controls: {
 			expanded: true,

package/src/theme/stories/index.story.tsx

@@ -13,7 +13,8 @@ import { HStack } from '../../h-stack';
 
 const meta: Meta< typeof Theme > = {
 	component: Theme,
-	title: 'Components/Theme',
+	title: 'Components/Utilities/Theme',
+	id: 'components-theme',
 	argTypes: {
 		accent: { control: { type: 'color' } },
 		background: { control: { type: 'color' } },

package/src/tip/stories/index.story.tsx

@@ -10,7 +10,8 @@ import Tip from '..';
 
 const meta: Meta< typeof Tip > = {
 	component: Tip,
-	title: 'Components/Tip',
+	title: 'Components/Feedback/Tip',
+	id: 'components-tip',
 	argTypes: {
 		children: { control: { type: 'text' } },
 	},

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -52,12 +52,13 @@ function UnconnectedToggleGroupControl(
 	const [ controlElement, setControlElement ] = useState< HTMLElement >();
 	const refs = useMergeRefs( [ setControlElement, forwardedRef ] );
 	const selectedRect = useTrackElementOffsetRect(
-		value ? selectedElement : undefined
+		value || value === 0 ? selectedElement : undefined
 	);
 	useAnimatedOffsetRect( controlElement, selectedRect, {
 		prefix: 'selected',
 		dataAttribute: 'indicator-animated',
 		transitionEndFilter: ( event ) => event.pseudoElement === '::before',
+		roundRect: true,
 	} );
 
 	const cx = useCx();

package/src/toolbar/toolbar/index.tsx

@@ -40,6 +40,9 @@ function UnforwardedToolbar(
 			Dropdown: {
 				variant: 'toolbar',
 			},
+			Menu: {
+				variant: 'toolbar',
+			},
 		};
 	}, [ isVariantDefined ] );
 

package/src/tools-panel/tools-panel-header/component.tsx

@@ -106,7 +106,7 @@ const OptionalControlsGroup = ( {
 					  )
 					: sprintf(
 							// translators: %s: The name of the control to display e.g. "Padding".
-							__( 'Show %s' ),
+							_x( 'Show %s', 'input control' ),
 							label
 					  );
 

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

@@ -54,11 +54,9 @@ export function useToolsPanelItem(
 
 	// 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 );
 

package/src/tooltip/index.native.js

@@ -62,9 +62,7 @@ const useKeyboardVisibility = () => {
 			showListener.remove();
 			hideListener.remove();
 		};
-		// Disable reason: deferring this refactor to the native team.
-		// see https://github.com/WordPress/gutenberg/pull/41166
-		// eslint-disable-next-line react-hooks/exhaustive-deps
+		// See https://github.com/WordPress/gutenberg/pull/41166
 	}, [] );
 
 	return keyboardVisible;
@@ -105,9 +103,7 @@ const Tooltip = ( {
 			} );
 		}
 		return () => onHandleScreenTouch( null );
-		// Disable reason: deferring this refactor to the native team.
-		// see https://github.com/WordPress/gutenberg/pull/41166
-		// eslint-disable-next-line react-hooks/exhaustive-deps
+		// See https://github.com/WordPress/gutenberg/pull/41166
 	}, [ visible ] );
 
 	// Manage visibility animation.
@@ -121,9 +117,7 @@ const Tooltip = ( {
 			setAnimating( true );
 			startAnimation();
 		}
-		// Disable reason: deferring this refactor to the native team.
-		// see https://github.com/WordPress/gutenberg/pull/41166
-		// eslint-disable-next-line react-hooks/exhaustive-deps
+		// See https://github.com/WordPress/gutenberg/pull/41166
 	}, [ visible ] );
 
 	// Manage tooltip visibility and position in relation to keyboard.
@@ -142,9 +136,7 @@ const Tooltip = ( {
 			setAnimating( true );
 			setVisible( false );
 		}
-		// Disable reason: deferring this refactor to the native team.
-		// see https://github.com/WordPress/gutenberg/pull/41166
-		// eslint-disable-next-line react-hooks/exhaustive-deps
+		// See https://github.com/WordPress/gutenberg/pull/41166
 	}, [ visible, keyboardVisible ] );
 
 	// Manage tooltip position during keyboard frame changes.
@@ -273,9 +265,7 @@ const TooltipSlot = ( { children, ...rest } ) => {
 		setHandleScreenTouch( null );
 	};
 	// Memoize context value to avoid unnecessary rerenders of the Provider's children
-	// Disable reason: deferring this refactor to the native team.
-	// see https://github.com/WordPress/gutenberg/pull/41166
-	// eslint-disable-next-line react-hooks/exhaustive-deps
+	// See https://github.com/WordPress/gutenberg/pull/41166
 	const value = useMemo( () => ( { onHandleScreenTouch } ) );
 
 	return (

package/src/tooltip/stories/index.story.tsx

@@ -15,7 +15,8 @@ import Tooltip from '..';
 import Button from '../../button';
 
 const meta: Meta< typeof Tooltip > = {
-	title: 'Components/Tooltip',
+	title: 'Components/Overlays/Tooltip',
+	id: 'components-tooltip',
 	component: Tooltip,
 	argTypes: {
 		children: { control: { type: null } },

package/src/tree-grid/stories/index.story.tsx

@@ -16,7 +16,8 @@ import { Button } from '../../button';
 import InputControl from '../../input-control';
 
 const meta: Meta< typeof TreeGrid > = {
-	title: 'Components (Experimental)/TreeGrid',
+	title: 'Components (Experimental)/Navigation/TreeGrid',
+	id: 'components-experimental-treegrid',
 	component: TreeGrid,
 	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
 	subcomponents: { TreeGridRow, TreeGridCell },

package/src/truncate/stories/index.story.tsx

@@ -10,7 +10,8 @@ import { Truncate } from '..';
 
 const meta: Meta< typeof Truncate > = {
 	component: Truncate,
-	title: 'Components (Experimental)/Truncate',
+	title: 'Components (Experimental)/Typography/Truncate',
+	id: 'components-experimental-truncate',
 	argTypes: {
 		children: { control: { type: 'text' } },
 		as: { control: { type: 'text' } },

package/src/unit-control/index.native.js

@@ -47,10 +47,8 @@ function UnitControl( {
 		if ( pickerRef?.current ) {
 			pickerRef.current.presentPicker();
 		}
-		// Disable reason: this should be fixed by the native team.
-		// It would be great if this could be done in the context of
+		// It would be great if the deps could be addressed in the context of
 		// https://github.com/WordPress/gutenberg/pull/39218
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ pickerRef?.current ] );
 
 	const currentInputValue = currentInput === null ? value : currentInput;
@@ -106,10 +104,8 @@ function UnitControl( {
 			anchorNodeRef?.current
 				? findNodeHandle( anchorNodeRef?.current )
 				: undefined,
-		// Disable reason: this should be fixed by the native team.
-		// It would be great if this could be done in the context of
+		// It would be great if the deps could be addressed in the context of
 		// https://github.com/WordPress/gutenberg/pull/39218
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 		[ anchorNodeRef?.current ]
 	);
 

package/src/utils/deprecated-36px-size.ts

@@ -0,0 +1,27 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
+export function maybeWarnDeprecated36pxSize( {
+	componentName,
+	__next40pxDefaultSize,
+	size,
+}: {
+	componentName: string;
+	__next40pxDefaultSize: boolean | undefined;
+	size: string | undefined;
+} ) {
+	if (
+		__next40pxDefaultSize ||
+		( size !== undefined && size !== 'default' )
+	) {
+		return;
+	}
+
+	deprecated( `36px default size for wp.components.${ componentName }`, {
+		since: '6.8',
+		version: '7.1',
+		hint: 'Set the `__next40pxDefaultSize` prop to true to start opting into the new default size, which will become the default in a future version.',
+	} );
+}

package/src/utils/element-rect.ts

@@ -134,14 +134,17 @@ const POLL_RATE = 100;
  * milliseconds until it succeeds.
  */
 export function useTrackElementOffsetRect(
-	targetElement: HTMLElement | undefined | null
+	targetElement: HTMLElement | undefined | null,
+	deps: unknown[] = []
 ) {
 	const [ indicatorPosition, setIndicatorPosition ] =
 		useState< ElementOffsetRect >( NULL_ELEMENT_OFFSET_RECT );
 	const intervalRef = useRef< ReturnType< typeof setInterval > >();
 
 	const measure = useEvent( () => {
-		if ( targetElement ) {
+		// Check that the targetElement is still attached to the DOM, in case
+		// it was removed since the last `measure` call.
+		if ( targetElement && targetElement.isConnected ) {
 			const elementOffsetRect = getElementOffsetRect( targetElement );
 			if ( elementOffsetRect ) {
 				setIndicatorPosition( elementOffsetRect );
@@ -171,6 +174,15 @@ export function useTrackElementOffsetRect(
 		}
 	}, [ setElement, targetElement ] );
 
+	// Escape hatch to force a remeasurement when something else changes rather
+	// than the target elements' ref or size (for example, the target element
+	// can change its position within the tablist).
+	useLayoutEffect( () => {
+		measure();
+		// `measure` is a stable function, so it's safe to omit it from the deps array.
+		// deps can't be statically analyzed by ESLint
+	}, deps );
+
 	return indicatorPosition;
 }
 

package/src/utils/hooks/use-animated-offset-rect.ts

@@ -46,6 +46,7 @@ export function useAnimatedOffsetRect(
 		prefix = 'subelement',
 		dataAttribute = `${ prefix }-animated`,
 		transitionEndFilter = () => true,
+		roundRect = false,
 	}: {
 		/**
 		 * The prefix used for the CSS variables, e.g. if `prefix` is `selected`, the
@@ -72,6 +73,13 @@ export function useAnimatedOffsetRect(
 		 * @default () => true
 		 */
 		transitionEndFilter?: ( event: TransitionEvent ) => boolean;
+		/**
+		 * Whether the `rect` measurements should be rounded down when applied
+		 * to the CSS variables. This can be useful to avoid blurry animations or
+		 * to avoid subpixel rendering issues.
+		 * @default false
+		 */
+		roundRect?: boolean;
 	} = {}
 ) {
 	const setProperties = useEvent( () => {
@@ -80,7 +88,11 @@ export function useAnimatedOffsetRect(
 				property !== 'element' &&
 				container?.style.setProperty(
 					`--${ prefix }-${ property }`,
-					String( rect[ property ] )
+					String(
+						roundRect
+							? Math.floor( rect[ property ] )
+							: rect[ property ]
+					)
 				)
 		);
 	} );

package/src/utils/hooks/use-update-effect.js

@@ -19,11 +19,9 @@ function useUpdateEffect( effect, deps ) {
 		}
 		mountedRef.current = true;
 		return undefined;
-		// Disable reasons:
 		// 1. This hook needs to pass a dep list that isn't an array literal
 		// 2. `effect` is missing from the array, and will need to be added carefully to avoid additional warnings
 		// see https://github.com/WordPress/gutenberg/pull/41166
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, deps );
 
 	useEffect(

package/src/visually-hidden/stories/index.story.tsx

@@ -10,7 +10,8 @@ import { VisuallyHidden } from '..';
 
 const meta: Meta< typeof VisuallyHidden > = {
 	component: VisuallyHidden,
-	title: 'Components/VisuallyHidden',
+	title: 'Components/Typography/VisuallyHidden',
+	id: 'components-visuallyhidden',
 	argTypes: {
 		children: { control: { type: null } },
 		as: { control: { type: 'text' } },