@wordpress/components 25.9.1 → 25.10.0

package/src/tabs/types.ts

@@ -0,0 +1,142 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type * as Ariakit from '@ariakit/react';
+
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
+export type TabsContextProps =
+	| {
+			/**
+			 * The tabStore object returned by Ariakit's `useTabStore` hook.
+			 */
+			store: Ariakit.TabStore;
+			/**
+			 * The unique id string for this instance of the Tabs component.
+			 */
+			instanceId: string;
+	  }
+	| undefined;
+
+export type TabsProps = {
+	/**
+	 * The children elements, which should be at least a
+	 * `Tabs.Tablist` component and a series of `Tabs.TabPanel`
+	 * components.
+	 */
+	children: React.ReactNode;
+	/**
+	 * 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.
+	 *
+	 * @default true
+	 *
+	 * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/
+	 */
+	selectOnMove?: boolean;
+	/**
+	 * 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`.
+	 *
+	 * Note: this prop will be overridden by the `selectedTabId` prop if it is
+	 * provided. (Controlled Mode)
+	 */
+	initialTabId?: string;
+	/**
+	 * The function called when a tab has been selected.
+	 * It is passed the id of the newly selected tab as an argument.
+	 */
+	onSelect?: ( selectedId: string | null | undefined ) => void;
+
+	/**
+	 * The orientation of the tablist.
+	 *
+	 * @default `horizontal`
+	 */
+	orientation?: 'horizontal' | 'vertical';
+	/**
+	 * 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.
+	 */
+	selectedTabId?: string | null;
+};
+
+export type TabListProps = {
+	/**
+	 * The children elements, which should be a series of `Tabs.TabPanel` components.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * The class name to apply to the tablist.
+	 */
+	className?: string;
+	/**
+	 * Custom CSS styles for the rendered tablist.
+	 */
+	style?: React.CSSProperties;
+};
+
+export type TabProps = {
+	/**
+	 * The id of the tab, which is prepended with the `Tabs` instanceId.
+	 */
+	id: string;
+	/**
+	 * Custom CSS styles for the tab.
+	 */
+	style?: React.CSSProperties;
+	/**
+	 * The children elements, generally the text to display on the tab.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * The class name to apply to the tab button.
+	 */
+	className?: string;
+	/**
+	 * The icon used for the tab button.
+	 */
+	icon?: IconType;
+	/**
+	 * Determines if the tab button should be disabled.
+	 *
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * 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.
+	 */
+	render?: React.ReactElement;
+};
+
+export type TabPanelProps = {
+	/**
+	 * The children elements, generally the content to display on the tabpanel.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * A unique identifier for the TabPanel, which is used to generate a unique `id` for the underlying element.
+	 */
+	id: string;
+	/**
+	 * The class name to apply to the tabpanel.
+	 */
+	className?: string;
+	/**
+	 * Custom CSS styles for the rendered `TabPanel` component.
+	 */
+	style?: React.CSSProperties;
+};

package/src/text/README.md

@@ -22,7 +22,7 @@ function Example() {
 
 ### adjustLineHeightForInnerControls
 
-**Type**: `boolean`,`"large"`,`"medium"`,`"small"`,`"xSmall"`
+**Type**: `"large"`,`"medium"`,`"small"`,`"xSmall"`
 
 Automatically calculate the appropriate line-height value for contents that render text and Control elements (e.g. `TextInput`).
 
@@ -31,7 +31,7 @@ import { __experimentalText as Text, TextInput } from '@wordpress/components';
 
 function Example() {
 	return (
-		<Text adjustLineHeightForInnerControls>
+		<Text adjustLineHeightForInnerControls={"small"}>
 			Lorem ipsum dolor sit amet, consectetur
 			<TextInput value="adipiscing elit..." />
 		</Text>

package/src/text/{component.js → component.tsx}

@@ -1,15 +1,20 @@
 /**
  * Internal dependencies
  */
+import type { WordPressComponentProps } from '../context';
 import { contextConnect } from '../context';
 import { View } from '../view';
 import useText from './hook';
+import type { Props } from './types';
 
 /**
- * @param {import('../context').WordPressComponentProps<import('./types').Props, 'span'>} props
- * @param {import('react').ForwardedRef<any>}                                             forwardedRef
+ * @param props
+ * @param forwardedRef
  */
-function Text( props, forwardedRef ) {
+function UnconnectedText(
+	props: WordPressComponentProps< Props, 'span' >,
+	forwardedRef: React.ForwardedRef< any >
+) {
 	const textProps = useText( props );
 
 	return <View as="span" { ...textProps } ref={ forwardedRef } />;
@@ -31,6 +36,5 @@ function Text( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedText = contextConnect( Text, 'Text' );
-
-export default ConnectedText;
+export const Text = contextConnect( UnconnectedText, 'Text' );
+export default Text;

package/src/text/{hook.js → hook.ts}

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import type { SerializedStyles } from '@emotion/react';
 import { css } from '@emotion/react';
 
 /**
@@ -11,6 +12,7 @@ import { useMemo, Children, cloneElement } from '@wordpress/element';
 /**
  * Internal dependencies
  */
+import type { WordPressComponentProps } from '../context';
 import { hasConnectNamespace, useContextSystem } from '../context';
 import { useTruncate } from '../truncate';
 import { getOptimalTextShade } from '../utils/colors';
@@ -20,11 +22,15 @@ import { getFontSize } from '../utils/font-size';
 import { CONFIG, COLORS } from '../utils';
 import { getLineHeight } from './get-line-height';
 import { useCx } from '../utils/hooks/use-cx';
+import type { Props } from './types';
+import type React from 'react';
 
 /**
  * @param {import('../context').WordPressComponentProps<import('./types').Props, 'span'>} props
  */
-export default function useText( props ) {
+export default function useText(
+	props: WordPressComponentProps< Props, 'span' >
+) {
 	const {
 		adjustLineHeightForInnerControls,
 		align,
@@ -50,8 +56,7 @@ export default function useText( props ) {
 		...otherProps
 	} = useContextSystem( props, 'Text' );
 
-	/** @type {import('react').ReactNode} */
-	let content = children;
+	let content: React.ReactNode = children;
 	const isHighlighter = Array.isArray( highlightWords );
 	const isCaption = size === 'caption';
 
@@ -64,9 +69,7 @@ export default function useText( props ) {
 
 		content = createHighlighterText( {
 			autoEscape: highlightEscape,
-			// Disable reason: We need to disable this otherwise it erases the cast
-			// eslint-disable-next-line object-shorthand
-			children: /** @type {string} */ ( children ),
+			children,
 			caseSensitive: highlightCaseSensitive,
 			searchWords: highlightWords,
 			sanitize: highlightSanitize,
@@ -76,7 +79,7 @@ export default function useText( props ) {
 	const cx = useCx();
 
 	const classes = useMemo( () => {
-		const sx = {};
+		const sx: Record< string, SerializedStyles | null > = {};
 
 		const lineHeight = getLineHeight(
 			adjustLineHeightForInnerControls,
@@ -87,12 +90,7 @@ export default function useText( props ) {
 			color,
 			display,
 			fontSize: getFontSize( size ),
-			/* eslint-disable jsdoc/valid-types */
-			fontWeight:
-				/** @type {import('react').CSSProperties['fontWeight']} */ (
-					weight
-				),
-			/* eslint-enable jsdoc/valid-types */
+			fontWeight: weight,
 			lineHeight,
 			letterSpacing,
 			textAlign: align,
@@ -143,8 +141,7 @@ export default function useText( props ) {
 		weight,
 	] );
 
-	/** @type {undefined | 'auto' | 'none'} */
-	let finalEllipsizeMode;
+	let finalEllipsizeMode: undefined | 'auto' | 'none';
 	if ( truncate === true ) {
 		finalEllipsizeMode = 'auto';
 	}

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

@@ -0,0 +1,80 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Text } from '../component';
+
+const meta: Meta< typeof Text > = {
+	component: Text,
+	title: 'Components (Experimental)/Text',
+	argTypes: {
+		as: { control: { type: 'text' } },
+		color: { control: { type: 'color' } },
+		display: { control: { type: 'text' } },
+		lineHeight: { control: { type: 'text' } },
+		letterSpacing: { control: { type: 'text' } },
+		optimizeReadabilityFor: { control: { type: 'color' } },
+		size: { control: { type: 'text' } },
+		variant: {
+			options: [ undefined, 'muted' ],
+			control: { type: 'select' },
+		},
+		weight: { control: { type: 'text' } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { canvas: { sourceState: 'shown' } },
+	},
+};
+export default meta;
+
+const Template: StoryFn< typeof Text > = ( props ) => {
+	return <Text { ...props } />;
+};
+
+export const Default = Template.bind( {} );
+Default.args = {
+	children: 'Code is poetry',
+};
+
+export const Truncate = Template.bind( {} );
+Truncate.args = {
+	children: `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut
+facilisis dictum tortor, eu tincidunt justo scelerisque tincidunt.
+Duis semper dui id augue malesuada, ut feugiat nisi aliquam.
+Vestibulum venenatis diam sem, finibus dictum massa semper in. Nulla
+facilisi. Nunc vulputate faucibus diam, in lobortis arcu ornare vel.
+In dignissim nunc sed facilisis finibus. Etiam imperdiet mattis
+arcu, sed rutrum sapien blandit gravida. Aenean sollicitudin neque
+eget enim blandit, sit amet rutrum leo vehicula. Nunc malesuada
+ultricies eros ut faucibus. Aliquam erat volutpat. Nulla nec feugiat
+risus. Vivamus iaculis dui aliquet ante ultricies feugiat.
+Vestibulum ante ipsum primis in faucibus orci luctus et ultrices
+posuere cubilia curae; Vivamus nec pretium velit, sit amet
+consectetur ante. Praesent porttitor ex eget fermentum mattis.`,
+	numberOfLines: 2,
+	truncate: true,
+};
+
+export const Highlight = Template.bind( {} );
+Highlight.args = {
+	children: `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut
+facilisis dictum tortor, eu tincidunt justo scelerisque tincidunt.
+Duis semper dui id augue malesuada, ut feugiat nisi aliquam.
+Vestibulum venenatis diam sem, finibus dictum massa semper in. Nulla
+facilisi. Nunc vulputate faucibus diam, in lobortis arcu ornare vel.
+In dignissim nunc sed facilisis finibus. Etiam imperdiet mattis
+arcu, sed rutrum sapien blandit gravida. Aenean sollicitudin neque
+eget enim blandit, sit amet rutrum leo vehicula. Nunc malesuada
+ultricies eros ut faucibus. Aliquam erat volutpat. Nulla nec feugiat
+risus. Vivamus iaculis dui aliquet ante ultricies feugiat.
+Vestibulum ante ipsum primis in faucibus orci luctus et ultrices
+posuere cubilia curae; Vivamus nec pretium velit, sit amet
+consectetur ante. Praesent porttitor ex eget fermentum mattis.`,
+	highlightWords: [ 'con' ],
+};

package/src/text/types.ts

@@ -29,12 +29,7 @@ export interface Props extends TruncateProps {
 	/**
 	 * Automatically calculate the appropriate line-height value for contents that render text and Control elements (e.g. `TextInput`).
 	 */
-	adjustLineHeightForInnerControls?:
-		| boolean
-		| 'large'
-		| 'medium'
-		| 'small'
-		| 'xSmall';
+	adjustLineHeightForInnerControls?: 'large' | 'medium' | 'small' | 'xSmall';
 	/**
 	 * Adjusts the text color.
 	 */

package/src/text/{utils.js → utils.ts}

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import memoize from 'memize';
+import type { FindAllArgs } from 'highlight-words-core';
 import { findAll } from 'highlight-words-core';
 
 /**
@@ -14,7 +15,6 @@ import { createElement } from '@wordpress/element';
  * https://github.com/bvaughn/react-highlight-words/blob/HEAD/src/Highlighter.js
  */
 
-/* eslint-disable jsdoc/valid-types */
 /**
  * @typedef Options
  * @property {string}                                                     [activeClassName='']      Classname for active highlighted areas.
@@ -33,28 +33,55 @@ import { createElement } from '@wordpress/element';
  * @property {import('react').AllHTMLAttributes<HTMLDivElement>['style']} [unhighlightStyle]        Style to apply to unhighlighted text.
  */
 
+interface Options {
+	activeClassName?: string;
+	activeIndex?: number;
+	activeStyle?: React.AllHTMLAttributes< HTMLDivElement >[ 'style' ];
+	autoEscape?: boolean;
+	caseSensitive?: boolean;
+	children: string;
+	findChunks?: FindAllArgs[ 'findChunks' ];
+	highlightClassName?: string | Record< string, unknown >;
+	highlightStyle?: React.AllHTMLAttributes< HTMLDivElement >[ 'style' ];
+	highlightTag?: keyof JSX.IntrinsicElements;
+	sanitize?: FindAllArgs[ 'sanitize' ];
+	searchWords?: string[];
+	unhighlightClassName?: string;
+	unhighlightStyle?: React.AllHTMLAttributes< HTMLDivElement >[ 'style' ];
+}
+
 /**
  * Maps props to lowercase names.
  *
- * @template {Record<string, unknown>} T
- * @param {T} object Props to map.
- * @return {{[K in keyof T as Lowercase<string & K>]: T[K]}} The mapped props.
+ * @param object Props to map.
+ * @return The mapped props.
  */
-/* eslint-enable jsdoc/valid-types */
-const lowercaseProps = ( object ) => {
-	/** @type {any} */
-	const mapped = {};
+const lowercaseProps = < T extends Record< string, unknown > >( object: T ) => {
+	const mapped: Record< string, unknown > = {};
 	for ( const key in object ) {
 		mapped[ key.toLowerCase() ] = object[ key ];
 	}
-	return mapped;
+	return mapped as { [ K in keyof T as Lowercase< string & K > ]: T[ K ] };
 };
 
 const memoizedLowercaseProps = memoize( lowercaseProps );
 
 /**
- *
- * @param {Options} options
+ * @param options
+ * @param options.activeClassName
+ * @param options.activeIndex
+ * @param options.activeStyle
+ * @param options.autoEscape
+ * @param options.caseSensitive
+ * @param options.children
+ * @param options.findChunks
+ * @param options.highlightClassName
+ * @param options.highlightStyle
+ * @param options.highlightTag
+ * @param options.sanitize
+ * @param options.searchWords
+ * @param options.unhighlightClassName
+ * @param options.unhighlightStyle
  */
 export function createHighlighterText( {
 	activeClassName = '',
@@ -71,7 +98,7 @@ export function createHighlighterText( {
 	searchWords = [],
 	unhighlightClassName = '',
 	unhighlightStyle,
-} ) {
+}: Options ) {
 	if ( ! children ) return null;
 	if ( typeof children !== 'string' ) return children;
 
@@ -122,8 +149,7 @@ export function createHighlighterText( {
 					? Object.assign( {}, highlightStyle, activeStyle )
 					: highlightStyle;
 
-			/** @type {Record<string, any>} */
-			const props = {
+			const props: Record< string, unknown > = {
 				children: text,
 				className: highlightClassNames,
 				key: index,

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

@@ -255,6 +255,7 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-8-20"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -292,6 +293,7 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-8-21"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -500,6 +502,7 @@ exports[`ToggleGroupControl controlled should render correctly with text options
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-7-18"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -521,6 +524,7 @@ exports[`ToggleGroupControl controlled should render correctly with text options
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-7-19"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -796,6 +800,7 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-1-2"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -833,6 +838,7 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-1-3"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -1035,6 +1041,7 @@ exports[`ToggleGroupControl uncontrolled should render correctly with text optio
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-0-0"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"
@@ -1056,6 +1063,7 @@ exports[`ToggleGroupControl uncontrolled should render correctly with text optio
             data-wp-component="ToggleGroupControlOptionBase"
             id="toggle-group-control-as-radio-group-0-1"
             role="radio"
+            type="button"
           >
             <div
               class="emotion-13 emotion-14"

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

@@ -143,6 +143,7 @@ function ToggleGroupControlOptionBase(
 					<Ariakit.Radio
 						render={
 							<button
+								type="button"
 								{ ...commonProps }
 								onFocus={ ( event ) => {
 									onFocusProp?.( event );

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

@@ -52,6 +52,10 @@ const meta: Meta< typeof Toolbar > = {
 	},
 	argTypes: {
 		children: { control: { type: null } },
+		variant: {
+			options: [ undefined, 'unstyled' ],
+			control: { type: 'radio' },
+		},
 	},
 	parameters: {
 		controls: { expanded: true },
@@ -181,3 +185,14 @@ WithoutGroup.args = {
 		</>
 	),
 };
+
+/**
+ * Set the variant to `unstyled` to remove default border styles.
+ * Otherwise, leave it as `undefined` for default styles.
+ */
+
+export const Unstyled = Template.bind( {} );
+Unstyled.args = {
+	...Default.args,
+	variant: 'unstyled',
+};

package/src/toolbar/test/index.tsx

@@ -25,5 +25,13 @@ describe( 'Toolbar', () => {
 				screen.getByLabelText( 'control2', { selector: 'button' } )
 			).toBeInTheDocument();
 		} );
+
+		it( 'should apply the unstyled variant correctly via the `variant` prop', () => {
+			render( <Toolbar label="blocks" variant="unstyled" /> );
+
+			expect( screen.getByRole( 'toolbar' ) ).toHaveClass(
+				'is-unstyled'
+			);
+		} );
 	} );
 } );

package/src/toolbar/toolbar/README.md

@@ -71,6 +71,15 @@ An accessible label for the toolbar.
 
 -   Required: Yes
 
+#### `variant`: `'unstyled' | undefined`
+
+Specifies the toolbar's style.
+
+Leave undefined for the default style. Or `'unstyled'` which removes the border from the toolbar, but keeps the default popover style.
+
+-   Required: No
+-   Default: `undefined`
+
 ## Related components
 
 -   Toolbar may contain [ToolbarGroup](/packages/components/src/toolbar-group/README.md), [ToolbarButton](/packages/components/src/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar-Item/README.md) as children.

package/src/toolbar/toolbar/index.tsx

@@ -7,7 +7,7 @@ import type { ForwardedRef } from 'react';
 /**
  * WordPress dependencies
  */
-import { forwardRef } from '@wordpress/element';
+import { forwardRef, useMemo } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 
 /**
@@ -19,23 +19,30 @@ import type { ToolbarProps } from './types';
 import type { WordPressComponentProps } from '../../context';
 import { ContextSystemProvider } from '../../context';
 
-const CONTEXT_SYSTEM_VALUE = {
-	DropdownMenu: {
-		variant: 'toolbar',
-	},
-	Dropdown: {
-		variant: 'toolbar',
-	},
-};
-
 function UnforwardedToolbar(
 	{
 		className,
 		label,
+		variant,
 		...props
 	}: WordPressComponentProps< ToolbarProps, 'div', false >,
 	ref: ForwardedRef< any >
 ) {
+	const isVariantDefined = variant !== undefined;
+	const contextSystemValue = useMemo( () => {
+		if ( isVariantDefined ) {
+			return {};
+		}
+		return {
+			DropdownMenu: {
+				variant: 'toolbar',
+			},
+			Dropdown: {
+				variant: 'toolbar',
+			},
+		};
+	}, [ isVariantDefined ] );
+
 	if ( ! label ) {
 		deprecated( 'Using Toolbar without label prop', {
 			since: '5.6',
@@ -55,10 +62,12 @@ function UnforwardedToolbar(
 	// `ToolbarGroup` already uses components-toolbar for compatibility reasons.
 	const finalClassName = classnames(
 		'components-accessible-toolbar',
-		className
+		className,
+		variant && `is-${ variant }`
 	);
+
 	return (
-		<ContextSystemProvider value={ CONTEXT_SYSTEM_VALUE }>
+		<ContextSystemProvider value={ contextSystemValue }>
 			<ToolbarContainer
 				className={ finalClassName }
 				label={ label }

package/src/toolbar/toolbar/style.scss

@@ -7,6 +7,15 @@
 	& > .components-toolbar-group:last-child {
 		border-right: none;
 	}
+
+	&.is-unstyled {
+		border: none;
+
+		& > .components-toolbar-group {
+			border-right: none;
+		}
+
+	}
 }
 
 .components-accessible-toolbar,