@wordpress/components 28.10.0 → 28.11.0

package/src/radio-group/index.tsx

@@ -7,6 +7,7 @@ import * as Ariakit from '@ariakit/react';
  * WordPress dependencies
  */
 import { useMemo, forwardRef } from '@wordpress/element';
+import { isRTL } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -34,6 +35,7 @@ function UnforwardedRadioGroup(
 		setValue: ( newValue ) => {
 			onChange?.( newValue ?? undefined );
 		},
+		rtl: isRTL(),
 	} );
 
 	const contextValue = useMemo(

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

@@ -14,7 +14,8 @@ import ResizableBox from '..';
 import { useState } from '@wordpress/element';
 
 const meta: Meta< typeof ResizableBox > = {
-	title: 'Components/ResizableBox',
+	title: 'Components/Utilities/ResizableBox',
+	id: 'components-resizablebox',
 	component: ResizableBox,
 	argTypes: {
 		children: { control: { type: null } },

package/src/sandbox/index.native.js

@@ -336,9 +336,7 @@ const Sandbox = forwardRef( function Sandbox(
 
 	useEffect( () => {
 		updateContentHtml();
-		// 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
 	}, [ html, title, type, styles, scripts ] );
 
 	useEffect( () => {

package/src/sandbox/index.tsx

@@ -262,23 +262,20 @@ function SandBox( {
 				checkMessageForResize
 			);
 		};
-		// Ignore reason: passing `exhaustive-deps` will likely involve a more detailed refactor.
+		// Passing `exhaustive-deps` will likely involve a more detailed refactor.
 		// See https://github.com/WordPress/gutenberg/pull/44378
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [] );
 
 	useEffect( () => {
 		trySandBox();
-		// Ignore reason: passing `exhaustive-deps` will likely involve a more detailed refactor.
+		// Passing `exhaustive-deps` will likely involve a more detailed refactor.
 		// See https://github.com/WordPress/gutenberg/pull/44378
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ title, styles, scripts ] );
 
 	useEffect( () => {
 		trySandBox( true );
-		// Ignore reason: passing `exhaustive-deps` will likely involve a more detailed refactor.
+		// Passing `exhaustive-deps` will likely involve a more detailed refactor.
 		// See https://github.com/WordPress/gutenberg/pull/44378
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ html, type ] );
 
 	return (

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

@@ -10,7 +10,8 @@ import SandBox from '..';
 
 const meta: Meta< typeof SandBox > = {
 	component: SandBox,
-	title: 'Components/SandBox',
+	title: 'Components/Utilities/SandBox',
+	id: 'components-sandbox',
 	argTypes: {
 		onFocus: { control: { type: null } },
 	},

package/src/scroll-lock/stories/index.story.tsx

@@ -17,7 +17,8 @@ import ScrollLock from '..';
 
 const meta: Meta< typeof ScrollLock > = {
 	component: ScrollLock,
-	title: 'Components/ScrollLock',
+	title: 'Components/Utilities/ScrollLock',
+	id: 'components-scrolllock',
 	parameters: {
 		controls: { hideNoControlsWarning: true },
 		docs: { canvas: { sourceState: 'shown' } },

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

@@ -122,9 +122,7 @@ function SearchControl( {
 		mergeFutureStyles( activeDarkStyles, [ isActive, isDark ] );
 
 		setCurrentStyles( futureStyles );
-		// 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
 	}, [ isActive, isDark ] );
 
 	const clearInput = useCallback( () => {

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

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

package/src/slot-fill/bubbles-virtually/slot.tsx

@@ -49,11 +49,10 @@ function Slot(
 		return () => {
 			unregisterSlot( name, ref );
 		};
-		// Ignore reason: We don't want to unregister and register the slot whenever
+		// We don't want to unregister and register the slot whenever
 		// `fillProps` change, which would cause the fill to be re-mounted. Instead,
 		// we can just update the slot (see hook below).
 		// For more context, see https://github.com/WordPress/gutenberg/pull/44403#discussion_r994415973
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ registerSlot, unregisterSlot, name ] );
 	// fillProps may be an update that interacts with the layout, so we
 	// useLayoutEffect.

package/src/slot-fill/fill.ts

@@ -23,9 +23,8 @@ export default function Fill( { name, children }: FillComponentProps ) {
 		const refValue = ref.current;
 		registerFill( name, refValue );
 		return () => unregisterFill( name, refValue );
-		// Ignore reason: the useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
+		// The useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
 		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [] );
 
 	useLayoutEffect( () => {
@@ -33,9 +32,8 @@ export default function Fill( { name, children }: FillComponentProps ) {
 		if ( slot ) {
 			slot.forceUpdate();
 		}
-		// Ignore reason: the useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
+		// The useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
 		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ children ] );
 
 	useLayoutEffect( () => {
@@ -46,9 +44,8 @@ export default function Fill( { name, children }: FillComponentProps ) {
 		unregisterFill( ref.current.name, ref.current );
 		ref.current.name = name;
 		registerFill( name, ref.current );
-		// Ignore reason: the useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
+		// The useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
 		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ name ] );
 
 	return null;

package/src/slot-fill/stories/index.story.tsx

@@ -15,7 +15,8 @@ import { Slot, Fill, Provider as SlotFillProvider } from '../';
 
 const meta: Meta< typeof Slot > = {
 	component: Slot,
-	title: 'Components/SlotFill',
+	title: 'Components/Utilities/SlotFill',
+	id: 'components-slotfill',
 	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
 	subcomponents: { Fill, SlotFillProvider },
 	argTypes: {

package/src/spacer/hook.ts

@@ -12,8 +12,9 @@ import { space } from '../utils/space';
 import { rtl, useCx } from '../utils';
 import type { SpacerProps } from './types';
 
-const isDefined = < T >( o: T ): o is Exclude< T, null | undefined > =>
-	typeof o !== 'undefined' && o !== null;
+function isDefined< T >( o: T ): o is Exclude< T, null | undefined > {
+	return typeof o !== 'undefined' && o !== null;
+}
 
 export function useSpacer(
 	props: WordPressComponentProps< SpacerProps, 'div' >

package/src/tab-panel/index.tsx

@@ -16,6 +16,7 @@ import {
 	useCallback,
 } from '@wordpress/element';
 import { useInstanceId, usePrevious } from '@wordpress/compose';
+import { isRTL } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -120,6 +121,7 @@ const UnforwardedTabPanel = (
 		orientation,
 		selectOnMove,
 		defaultSelectedId: prependInstanceId( initialTabName ),
+		rtl: isRTL(),
 	} );
 
 	const selectedTabName = extractTabName(
@@ -218,6 +220,7 @@ const UnforwardedTabPanel = (
 							) }-view` }
 							render={
 								<Button
+									__next40pxDefaultSize
 									icon={ tab.icon }
 									label={ tab.icon && tab.title }
 									showTooltip={ !! tab.icon }

package/src/tab-panel/stories/index.story.tsx

@@ -14,7 +14,8 @@ import { link, more, wordpress } from '@wordpress/icons';
 import TabPanel from '..';
 
 const meta: Meta< typeof TabPanel > = {
-	title: 'Components/TabPanel',
+	title: 'Components/Containers/TabPanel',
+	id: 'components-tabpanel',
 	component: TabPanel,
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },

package/src/tab-panel/style.scss

@@ -7,12 +7,10 @@
 	}
 }
 
-// This tab style CSS is duplicated verbatim in
-// /packages/edit-post/src/components/sidebar/settings-header/style.scss
 .components-tab-panel__tabs-item {
 	position: relative;
 	border-radius: 0;
-	height: $grid-unit-60;
+	height: $grid-unit-60 !important; // https://github.com/WordPress/gutenberg/pull/65075#discussion_r1746282734
 	background: transparent;
 	border: none;
 	box-shadow: none;

package/src/tabs/README.md

@@ -109,45 +109,81 @@ Tabs is comprised of four individual components:
 
 ###### `children`: `React.ReactNode`
 
-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.
 
 -   Required: Yes
 
 ###### `selectOnMove`: `boolean`
 
-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](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) 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](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) for more info.
 
 -   Required: No
 -   Default: `true`
 
-###### `defaultTabId`: `string`
+###### `selectedTabId`: `string | null`
+
+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.
+
+- Required: No
+
+###### `defaultTabId`: `string | null`
 
-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 a unique instance ID to avoid collisions.
+The id of the tab whose panel is currently visible.
 
-_Note: this prop will be overridden by the `selectedTabId` prop if it is provided. (Controlled Mode)_
+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 (meaning the component will be used in "controlled" mode)._
 
 -   Required: No
 
 ###### `onSelect`: `( ( selectedId: string | null | undefined ) => void )`
 
-The function called when a tab has been selected. It is passed the selected tab's ID as an argument.
+The function called when the `selectedTabId` changes.
 
 -   Required: No
 -   Default: `noop`
 
-###### `orientation`: `horizontal | vertical`
+###### `activeTabId`: `string | null`
+
+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.
+
+- Required: No
+
+###### `defaultActiveTabId`: `string | null`
+
+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.
 
-The orientation of the `tablist` (`vertical` or `horizontal`)
+_Note: this prop will be overridden by the `activeTabId` prop if it is provided._
 
 -   Required: No
--   Default: `horizontal`
 
-###### `selectedTabId`: `string | null`
+###### `onActiveTabIdChange`: `( ( activeId: string | null | undefined ) => void )`
 
-The ID of the tab to display. This id is prepended with the `Tabs` instanceId internally.
-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.
+The function called when the `selectedTabId` changes.
 
-- Required: No
+-   Required: No
+-   Default: `noop`
+
+###### `orientation`: `'horizontal' | 'vertical' | 'both'`
+
+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.
+
+-   Required: No
+-   Default: `horizontal`
 
 #### TabList
 
@@ -155,7 +191,7 @@ If left `undefined`, the component assumes it is being used in uncontrolled mode
 
 ###### `children`: `React.ReactNode`
 
-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.
 
 -   Required: No
 
@@ -165,26 +201,28 @@ The children elements, which should be a series of `Tabs.TabPanel` components.
 
 ###### `tabId`: `string`
 
-A unique identifier for the tab, which is used to generate a unique id for the underlying element. 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. If not provided, a unique ID will be automatically generated.
 
 - Required: Yes
 
 ###### `children`: `React.ReactNode`
 
-The children elements, generally the text to display on the tab.
+The contents of the tab.
 
 - Required: No
 
 ###### `disabled`: `boolean`
 
-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.
 
 - Required: No
 - Default: `false`
 
 ###### `render`: `React.ReactNode`
 
-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.
 
 - Required: No
 
@@ -194,19 +232,23 @@ The type of component to render the tab button as. If this prop is not provided,
 
 ###### `children`: `React.ReactNode`
 
-The children elements, generally the content to display on the tabpanel.
+The contents of the tab panel.
 
 - Required: No
 
 ###### `tabId`: `string`
 
-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.
 
 - Required: Yes
 
 ###### `focusable`: `boolean`
 
-Determines whether or not the tabpanel element should be focusable. If `false`, pressing the tab key will skip over the tabpanel, and instead focus on the first focusable element in the panel (if there is one).
+Determines whether or not the tabpanel element should be focusable.
+
+If `false`, pressing the tab key will skip over the tabpanel, and instead focus on the first focusable element in the panel (if there is one).
 
 - Required: No
 - Default: `true`