@wordpress/components 25.9.1 → 25.11.0

package/src/private-apis.ts

@@ -6,6 +6,13 @@ import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/pri
 /**
  * Internal dependencies
  */
+import {
+	Composite as CompositeV2,
+	CompositeGroup as CompositeGroupV2,
+	CompositeItem as CompositeItemV2,
+	CompositeRow as CompositeRowV2,
+	useCompositeStore as useCompositeStoreV2,
+} from './composite/v2';
 import { default as CustomSelectControl } from './custom-select-control';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
 import { default as ProgressBar } from './progress-bar';
@@ -22,17 +29,32 @@ import {
 	DropdownSubMenu as DropdownSubMenuV2,
 	DropdownSubMenuTrigger as DropdownSubMenuTriggerV2,
 } from './dropdown-menu-v2';
+import {
+	DropdownMenu as DropdownMenuV2Ariakit,
+	DropdownMenuGroup as DropdownMenuGroupV2Ariakit,
+	DropdownMenuGroupLabel as DropdownMenuGroupLabelV2Ariakit,
+	DropdownMenuItem as DropdownMenuItemV2Ariakit,
+	DropdownMenuCheckboxItem as DropdownMenuCheckboxItemV2Ariakit,
+	DropdownMenuRadioItem as DropdownMenuRadioItemV2Ariakit,
+	DropdownMenuSeparator as DropdownMenuSeparatorV2Ariakit,
+} from './dropdown-menu-v2-ariakit';
 import { ComponentsContext } from './context/context-system-provider';
 import Theme from './theme';
+import Tabs from './tabs';
 
 export const { lock, unlock } =
 	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
-		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+		'I know using unstable features means my theme or plugin will inevitably break in the next version of WordPress.',
 		'@wordpress/components'
 	);
 
 export const privateApis = {};
 lock( privateApis, {
+	CompositeV2,
+	CompositeGroupV2,
+	CompositeItemV2,
+	CompositeRowV2,
+	useCompositeStoreV2,
 	CustomSelectControl,
 	__experimentalPopoverLegacyPositionToPlacement,
 	createPrivateSlotFill,
@@ -48,5 +70,13 @@ lock( privateApis, {
 	DropdownSubMenuV2,
 	DropdownSubMenuTriggerV2,
 	ProgressBar,
+	Tabs,
 	Theme,
+	DropdownMenuV2Ariakit,
+	DropdownMenuGroupV2Ariakit,
+	DropdownMenuGroupLabelV2Ariakit,
+	DropdownMenuItemV2Ariakit,
+	DropdownMenuCheckboxItemV2Ariakit,
+	DropdownMenuRadioItemV2Ariakit,
+	DropdownMenuSeparatorV2Ariakit,
 } );

package/src/progress-bar/styles.ts

@@ -27,11 +27,17 @@ export const Track = styled.div`
 	width: 100%;
 	max-width: 160px;
 	height: ${ CONFIG.borderWidthFocus };
-	background-color: var(
-		--wp-components-color-gray-300,
-		${ COLORS.gray[ 300 ] }
+	/* Text color at 10% opacity */
+	background-color: color-mix(
+		in srgb,
+		var( --wp-components-color-foreground, ${ COLORS.gray[ 900 ] } ),
+		transparent 90%
 	);
 	border-radius: ${ CONFIG.radiusBlockUi };
+
+	// Windows high contrast mode.
+	outline: 2px solid transparent;
+	outline-offset: 2px;
 `;
 
 export const Indicator = styled.div< {
@@ -43,7 +49,16 @@ export const Indicator = styled.div< {
 	top: 0;
 	height: 100%;
 	border-radius: ${ CONFIG.radiusBlockUi };
-	background-color: ${ COLORS.theme.accent };
+	/* Text color at 90% opacity */
+	background-color: color-mix(
+		in srgb,
+		var( --wp-components-color-foreground, ${ COLORS.gray[ 900 ] } ),
+		transparent 10%
+	);
+
+	// Windows high contrast mode.
+	outline: 2px solid transparent;
+	outline-offset: -2px;
 
 	${ ( { isIndeterminate, value } ) =>
 		isIndeterminate

package/src/sandbox/index.native.js

@@ -68,7 +68,7 @@ const observeAndResizeJS = `
 					style
 				) {
 					if (
-						/^\\d+(vmin|vmax|vh|vw)$/.test( ruleOrNode.style[ style ] )
+						/^\\d+(vw|vh|svw|lvw|dvw|svh|lvh|dvh|vi|svi|lvi|dvi|vb|svb|lvb|dvb|vmin|svmin|lvmin|dvmin|vmax|svmax|lvmax|dvmax)$/.test( ruleOrNode.style[ style ] )
 					) {
 						ruleOrNode.style[ style ] = '';
 					}

package/src/sandbox/index.tsx

@@ -55,7 +55,9 @@ const observeAndResizeJS = function () {
 				[ 'width', 'height', 'minHeight', 'maxHeight' ] as const
 			 ).forEach( function ( style ) {
 				if (
-					/^\\d+(vmin|vmax|vh|vw)$/.test( ruleOrNode.style[ style ] )
+					/^\\d+(vw|vh|svw|lvw|dvw|svh|lvh|dvh|vi|svi|lvi|dvi|vb|svb|lvb|dvb|vmin|svmin|lvmin|dvmin|vmax|svmax|lvmax|dvmax)$/.test(
+						ruleOrNode.style[ style ]
+					)
 				) {
 					ruleOrNode.style[ style ] = '';
 				}

package/src/select-control/styles/select-control-styles.ts

@@ -85,8 +85,8 @@ const sizeStyles = ( {
 
 	if ( ! __next40pxDefaultSize ) {
 		sizes.default = {
-			height: 30,
-			minHeight: 30,
+			height: 32,
+			minHeight: 32,
 			paddingTop: 0,
 			paddingBottom: 0,
 		};

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

@@ -66,7 +66,7 @@ function createSlotRegistry(): SlotFillBubblesVirtuallyContext {
 		const slotFills = fills.get( name );
 		if ( slotFills ) {
 			// Force update fills.
-			slotFills.map( ( fill ) => fill.current.rerender() );
+			slotFills.forEach( ( fill ) => fill.current.rerender() );
 		}
 	};
 

package/src/tabs/README.md

@@ -0,0 +1,242 @@
+# Tabs
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+Tabs is a collection of React components that combine to render an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+
+Tabs organizes content across different screens, data sets, and interactions. It has two sections: a list of tabs, and the view to show when tabs are chosen.
+
+## Development guidelines
+
+### Usage
+
+#### Uncontrolled Mode
+
+Tabs can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `initialTabId` prop can be used to set the initially selected tab. If this prop is not set, the first tab will be selected by default. In addition, in most cases where the currently active tab becomes disabled or otherwise unavailable, uncontrolled mode will automatically fall back to selecting the first available tab.
+
+```jsx
+import { Tabs } from '@wordpress/components';
+
+const onSelect = ( tabName ) => {
+	console.log( 'Selecting tab', tabName );
+};
+
+const MyUncontrolledTabs = () => (
+		<Tabs onSelect={onSelect} initialTab="tab2">
+			<Tabs.TabList >
+				<Tabs.Tab id={ 'tab1' } title={ 'Tab 1' }>
+					Tab 1
+				</Tabs.Tab>
+				<Tabs.Tab id={ 'tab2' } title={ 'Tab 2' }>
+					Tab 2
+				</Tabs.Tab>
+				<Tabs.Tab id={ 'tab3' } title={ 'Tab 3' }>
+					Tab 3
+				</Tabs.Tab>
+			</Tabs.TabList>
+			<Tabs.TabPanel id={ 'tab1' }>
+				<p>Selected tab: Tab 1</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab2' }>
+				<p>Selected tab: Tab 2</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab3' }>
+				<p>Selected tab: Tab 3</p>
+			</Tabs.TabPanel>
+		</Tabs>
+	);
+```
+
+#### Controlled Mode
+
+Tabs can also be used in a controlled mode, where the parent component specifies the `selectedTabId` and the `onSelect` props to control tab selection. In this mode, the `initialTabId` prop will be ignored if it is provided. If the `selectedTabId` is `null`, no tab is selected. In this mode, if the currently selected tab becomes disabled or otherwise unavailable, the component will _not_ fall back to another available tab, leaving the controlling component in charge of implementing the desired logic.
+
+```jsx
+import { Tabs } from '@wordpress/components';
+	const [ selectedTabId, setSelectedTabId ] = useState<
+		string | undefined | null
+	>();
+
+const onSelect = ( tabName ) => {
+	console.log( 'Selecting tab', tabName );
+};
+
+const MyControlledTabs = () => (
+		<Tabs
+			selectedTabId={ selectedTabId }
+			onSelect={ ( selectedId ) => {
+				setSelectedTabId( selectedId );
+				onSelect( selectedId );
+			} }
+		>
+			<Tabs.TabList >
+				<Tabs.Tab id={ 'tab1' } title={ 'Tab 1' }>
+					Tab 1
+				</Tabs.Tab>
+				<Tabs.Tab id={ 'tab2' } title={ 'Tab 2' }>
+					Tab 2
+				</Tabs.Tab>
+				<Tabs.Tab id={ 'tab3' } title={ 'Tab 3' }>
+					Tab 3
+				</Tabs.Tab>
+			</Tabs.TabList>
+			<Tabs.TabPanel id={ 'tab1' }>
+				<p>Selected tab: Tab 1</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab2' }>
+				<p>Selected tab: Tab 2</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab3' }>
+				<p>Selected tab: Tab 3</p>
+			</Tabs.TabPanel>
+		</Tabs>
+	);
+```
+
+### Components and Sub-components
+
+Tabs is comprised of four individual components:
+- `Tabs`: a wrapper component and context provider. It is responsible for managing the state of the tabs and rendering the `TabList` and `TabPanels`.
+- `TabList`: a wrapper component for the `Tab` components. It is responsible for rendering the list of tabs.
+- `Tab`: renders a single tab. The currently active tab receives default styling that can be overridden with CSS targeting [aria-selected="true"].
+- `TabPanel`: renders the content to display for a single tab once that tab is selected.
+
+#### Tabs
+
+##### Props
+
+###### `children`: `React.ReactNode`
+
+The children elements, which should be at least a `Tabs.Tablist` component and a series of `Tabs.TabPanel` 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.
+
+-   Required: No
+-   Default: `true`
+
+###### `initialTabId`: `string`
+
+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.
+
+_Note: this prop will be overridden by the `selectedTabId` prop if it is provided. (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.
+
+-   Required: No
+-   Default: `noop`
+
+###### `orientation`: `horizontal | vertical`
+
+The orientation of the `tablist` (`vertical` or `horizontal`)
+
+-   Required: No
+-   Default: `horizontal`
+
+###### `selectedTabId`: `string | null`
+
+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.
+
+- Required: No
+
+#### TabList
+
+##### Props
+
+###### `children`: `React.ReactNode`
+
+The children elements, which should be a series of `Tabs.TabPanel` components.
+
+-   Required: No
+
+###### `className`: `string`
+
+The class name to apply to the tablist.
+
+-   Required: No
+-   Default: ''
+
+###### `style`: `React.CSSProperties`
+
+Custom CSS styles for the tablist.
+
+- Required: No
+
+#### Tab
+
+##### Props
+
+###### `id`: `string`
+
+The id of the tab, which is prepended with the `Tabs` instance ID.
+
+- Required: Yes
+
+###### `style`: `React.CSSProperties`
+
+Custom CSS styles for the tab.
+
+- Required: No
+
+###### `children`: `React.ReactNode`
+
+The children elements, generally the text to display on the tab.
+
+- Required: No
+
+###### `className`: `string`
+
+The class name to apply to the tab.
+
+- Required: No
+
+###### `disabled`: `boolean`
+
+Determines if the tab button should be disabled.
+
+- 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.
+
+- Required: No
+
+#### TabPanel
+
+##### Props
+
+###### `children`: `React.ReactNode`
+
+The children elements, generally the content to display on the tabpanel.
+
+- Required: No
+
+###### `id`: `string`
+
+The id of the tabpanel, which is combined with the `Tabs` instance ID and the suffix `-view`
+
+- Required: Yes
+
+###### `className`: `string`
+
+The class name to apply to the tabpanel.
+
+- Required: No
+
+###### `style`: `React.CSSProperties`
+
+Custom CSS styles for the tab.
+
+- Required: No

package/src/tabs/context.ts

@@ -0,0 +1,13 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { TabsContextProps } from './types';
+
+export const TabsContext = createContext< TabsContextProps >( undefined );
+
+export const useTabsContext = () => useContext( TabsContext );

package/src/tabs/index.tsx

@@ -0,0 +1,167 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { useLayoutEffect, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { TabsProps } from './types';
+import { TabsContext } from './context';
+import { Tab } from './tab';
+import { TabList } from './tablist';
+import { TabPanel } from './tabpanel';
+
+function Tabs( {
+	selectOnMove = true,
+	initialTabId,
+	orientation = 'horizontal',
+	onSelect,
+	children,
+	selectedTabId,
+}: TabsProps ) {
+	const instanceId = useInstanceId( Tabs, 'tabs' );
+	const store = Ariakit.useTabStore( {
+		selectOnMove,
+		orientation,
+		defaultSelectedId: initialTabId && `${ instanceId }-${ initialTabId }`,
+		setSelectedId: ( selectedId ) => {
+			const strippedDownId =
+				typeof selectedId === 'string'
+					? selectedId.replace( `${ instanceId }-`, '' )
+					: selectedId;
+			onSelect?.( strippedDownId );
+		},
+		selectedId: selectedTabId && `${ instanceId }-${ selectedTabId }`,
+	} );
+
+	const isControlled = selectedTabId !== undefined;
+
+	const { items, selectedId } = store.useState();
+	const { setSelectedId } = store;
+
+	// Keep track of whether tabs have been populated. This is used to prevent
+	// certain effects from firing too early while tab data and relevant
+	// variables are undefined during the initial render.
+	const tabsHavePopulated = useRef( false );
+	if ( items.length > 0 ) {
+		tabsHavePopulated.current = true;
+	}
+
+	const selectedTab = items.find( ( item ) => item.id === selectedId );
+	const firstEnabledTab = items.find( ( item ) => {
+		// Ariakit internally refers to disabled tabs as `dimmed`.
+		return ! item.dimmed;
+	} );
+	const initialTab = items.find(
+		( item ) => item.id === `${ instanceId }-${ initialTabId }`
+	);
+
+	// Handle selecting the initial tab.
+	useLayoutEffect( () => {
+		if ( isControlled ) {
+			return;
+		}
+
+		// Wait for the denoted initial tab to be declared before making a
+		// selection. This ensures that if a tab is declared lazily it can
+		// still receive initial selection, as well as ensuring no tab is
+		// selected if an invalid `initialTabId` is provided.
+		if ( initialTabId && ! initialTab ) {
+			return;
+		}
+
+		// If the currently selected tab is missing (i.e. removed from the DOM),
+		// fall back to the initial tab or the first enabled tab if there is
+		// one. Otherwise, no tab should be selected.
+		if ( ! items.find( ( item ) => item.id === selectedId ) ) {
+			if ( initialTab && ! initialTab.dimmed ) {
+				setSelectedId( initialTab?.id );
+				return;
+			}
+
+			if ( firstEnabledTab ) {
+				setSelectedId( firstEnabledTab.id );
+			} else if ( tabsHavePopulated.current ) {
+				setSelectedId( null );
+			}
+		}
+	}, [
+		firstEnabledTab,
+		initialTab,
+		initialTabId,
+		isControlled,
+		items,
+		selectedId,
+		setSelectedId,
+	] );
+
+	// Handle the currently selected tab becoming disabled.
+	useLayoutEffect( () => {
+		if ( ! selectedTab?.dimmed ) {
+			return;
+		}
+
+		// In controlled mode, we trust that disabling tabs is done
+		// intentionally, and don't select a new tab automatically.
+		if ( isControlled ) {
+			setSelectedId( null );
+			return;
+		}
+
+		// If the currently selected tab becomes disabled, fall back to the
+		// `initialTabId` if possible. Otherwise select the first
+		// enabled tab (if there is one).
+		if ( initialTab && ! initialTab.dimmed ) {
+			setSelectedId( initialTab.id );
+			return;
+		}
+
+		if ( firstEnabledTab ) {
+			setSelectedId( firstEnabledTab.id );
+		}
+	}, [
+		firstEnabledTab,
+		initialTab,
+		isControlled,
+		selectedTab?.dimmed,
+		setSelectedId,
+	] );
+
+	// Clear `selectedId` if the active tab is removed from the DOM in controlled mode.
+	useLayoutEffect( () => {
+		if ( ! isControlled ) {
+			return;
+		}
+
+		// Once the tabs have populated, if the `selectedTabId` still can't be
+		// found, clear the selection.
+		if ( tabsHavePopulated.current && !! selectedTabId && ! selectedTab ) {
+			setSelectedId( null );
+		}
+	}, [
+		isControlled,
+		selectedId,
+		selectedTab,
+		selectedTabId,
+		setSelectedId,
+	] );
+
+	return (
+		<TabsContext.Provider value={ { store, instanceId } }>
+			{ children }
+		</TabsContext.Provider>
+	);
+}
+
+Tabs.TabList = TabList;
+Tabs.Tab = Tab;
+Tabs.TabPanel = TabPanel;
+export default Tabs;