@wordpress/components 19.12.0 → 19.15.0

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

@@ -33,11 +33,8 @@ export function useToolsPanelHeader(
 		return cx( styles.ToolsPanelHeading );
 	}, [ cx ] );
 
-	const {
-		menuItems,
-		hasMenuItems,
-		areAllOptionalControlsHidden,
-	} = useToolsPanelContext();
+	const { menuItems, hasMenuItems, areAllOptionalControlsHidden } =
+		useToolsPanelContext();
 
 	return {
 		...otherProps,

package/src/tooltip/index.js

@@ -65,6 +65,7 @@ const addPopoverToGrandchildren = ( {
 				aria-hidden="true"
 				animate={ false }
 				offset={ 12 }
+				__unstableShift
 			>
 				{ text }
 				<Shortcut

package/src/tree-grid/roving-tab-index-item.js

@@ -14,10 +14,8 @@ export default forwardRef( function RovingTabIndexItem(
 ) {
 	const localRef = useRef();
 	const ref = forwardedRef || localRef;
-	const {
-		lastFocusedElement,
-		setLastFocusedElement,
-	} = useRovingTabIndexContext();
+	const { lastFocusedElement, setLastFocusedElement } =
+		useRovingTabIndexContext();
 	let tabIndex;
 
 	if ( lastFocusedElement ) {

package/src/tree-grid/test/index.js

@@ -35,9 +35,8 @@ describe( 'TreeGrid', () => {
 	] );
 
 	beforeAll( () => {
-		window.Element.prototype.getClientRects = jest.fn(
-			mockedGetClientRects
-		);
+		window.Element.prototype.getClientRects =
+			jest.fn( mockedGetClientRects );
 	} );
 
 	afterAll( () => {

package/src/tree-select/README.md

@@ -80,12 +80,12 @@ A function that receives the id of the new node element that is being selected.
 
 The id of the currently selected node.
 
--   Type: `Object`
+-   Type: `string` | `string[]`
 -   Required: No
 
 ### tree
 
 An array containing the tree objects with the possible nodes the user can select.
 
--   Type: `String`
+-   Type: `Object[]`
 -   Required: No

package/src/tree-select/index.tsx

@@ -0,0 +1,99 @@
+/**
+ * External dependencies
+ */
+import { unescape as unescapeString, compact } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+import { useMemo } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import { SelectControl } from '../select-control';
+import type { TreeSelectProps, Tree, SelectOptions } from './types';
+
+function getSelectOptions( tree: Tree[], level = 0 ): SelectOptions {
+	return tree.flatMap( ( treeNode ) => [
+		{
+			value: treeNode.id,
+			label:
+				'\u00A0'.repeat( level * 3 ) + unescapeString( treeNode.name ),
+		},
+		...getSelectOptions( treeNode.children || [], level + 1 ),
+	] );
+}
+
+/**
+ * TreeSelect component is used to generate select input fields.
+ *
+ * @example
+ * ```jsx
+ * import { TreeSelect } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyTreeSelect = () => {
+ * 	const [ page, setPage ] = useState( 'p21' );
+ *
+ * 	return (
+ * 		<TreeSelect
+ * 			label="Parent page"
+ * 			noOptionLabel="No parent page"
+ * 			onChange={ ( newPage ) => setPage( newPage ) }
+ * 			selectedId={ page }
+ * 			tree={ [
+ * 				{
+ * 					name: 'Page 1',
+ * 					id: 'p1',
+ * 					children: [
+ * 						{ name: 'Descend 1 of page 1', id: 'p11' },
+ * 						{ name: 'Descend 2 of page 1', id: 'p12' },
+ * 					],
+ * 				},
+ * 				{
+ * 					name: 'Page 2',
+ * 					id: 'p2',
+ * 					children: [
+ * 						{
+ * 							name: 'Descend 1 of page 2',
+ * 							id: 'p21',
+ * 							children: [
+ * 								{
+ * 									name: 'Descend 1 of Descend 1 of page 2',
+ * 									id: 'p211',
+ * 								},
+ * 							],
+ * 						},
+ * 					],
+ * 				},
+ * 			] }
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
+export function TreeSelect( {
+	label,
+	noOptionLabel,
+	onChange,
+	selectedId,
+	tree = [],
+	...props
+}: TreeSelectProps ) {
+	const options = useMemo( () => {
+		return compact( [
+			noOptionLabel && { value: '', label: noOptionLabel },
+			...getSelectOptions( tree ),
+		] );
+	}, [ noOptionLabel, tree ] );
+
+	return (
+		<SelectControl
+			{ ...{ label, options, onChange } }
+			value={ selectedId }
+			{ ...props }
+		/>
+	);
+}
+
+export default TreeSelect;

package/src/tree-select/stories/index.tsx

@@ -0,0 +1,80 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { ComponentProps } from 'react';
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import TreeSelect from '../';
+
+const meta: ComponentMeta< typeof TreeSelect > = {
+	title: 'Components/TreeSelect',
+	component: TreeSelect,
+	argTypes: {
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+		prefix: { control: { type: 'text' } },
+		suffix: { control: { type: 'text' } },
+		selectedId: { control: { type: null } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+
+export default meta;
+
+const TreeSelectWithState: ComponentStory< typeof TreeSelect > = ( props ) => {
+	const [ selection, setSelection ] =
+		useState< ComponentProps< typeof TreeSelect >[ 'selectedId' ] >();
+
+	return (
+		<TreeSelect
+			{ ...props }
+			onChange={ setSelection }
+			selectedId={ selection }
+		/>
+	);
+};
+
+export const Default = TreeSelectWithState.bind( {} );
+Default.args = {
+	label: 'Label Text',
+	noOptionLabel: 'No parent page',
+	help: 'Help text to explain the select control.',
+	tree: [
+		{
+			name: 'Page 1',
+			id: 'p1',
+			children: [
+				{ name: 'Descend 1 of page 1', id: 'p11' },
+				{ name: 'Descend 2 of page 1', id: 'p12' },
+			],
+		},
+		{
+			name: 'Page 2',
+			id: 'p2',
+			children: [
+				{
+					name: 'Descend 1 of page 2',
+					id: 'p21',
+					children: [
+						{
+							name: 'Descend 1 of Descend 1 of page 2',
+							id: 'p211',
+						},
+					],
+				},
+			],
+		},
+	],
+};

package/src/tree-select/types.ts

@@ -0,0 +1,35 @@
+/**
+ * External dependencies
+ */
+import type { ComponentProps } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type SelectControl from '../select-control';
+import type { SelectControlProps } from '../select-control/types';
+
+export type SelectOptions = Required<
+	ComponentProps< typeof SelectControl >
+>[ 'options' ];
+
+export interface Tree {
+	id: string;
+	name: string;
+	children?: Tree[];
+}
+
+export interface TreeSelectProps extends Omit< SelectControlProps, 'value' > {
+	/**
+	 * If this property is added, an option will be added with this label to represent empty selection.
+	 */
+	noOptionLabel?: string;
+	/**
+	 * An array containing the tree objects with the possible nodes the user can select.
+	 */
+	tree?: Tree[];
+	/**
+	 * The id of the currently selected node.
+	 */
+	selectedId?: ComponentProps< typeof SelectControl >[ 'value' ];
+}

package/src/truncate/README.md

@@ -24,15 +24,14 @@ function Example() {
 
 ## Props
 
-##### ellipsis
+##### `ellipsis`: `string`
 
-**Type**: `string`
+The ellipsis string when truncating the text by the `limit` prop's value.
 
-The ellipsis string when `truncate` is set.
+-   Required: No
+-   Default: `…`
 
-##### ellipsizeMode
-
-**Type**: `"auto"`,`"head"`,`"tail"`,`"middle"`
+##### `ellipsizeMode`: `'auto' | 'head' | 'tail' | 'middle' | 'none'`
 
 Determines where to truncate. For example, we can truncate text right in the middle. To do this, we need to set `ellipsizeMode` to `middle` and a text `limit`.
 
@@ -41,17 +40,22 @@ Determines where to truncate. For example, we can truncate text right in the mid
 -   `middle`: Trims content in the middle. Requires a `limit`.
 -   `tail`: Trims content at the end. Requires a `limit`.
 
-##### limit
+-   Required: No
+-   Default: `auto`
+
+##### `limit`: `number`
 
-**Type**: `number`
+Determines the max number of characters to be displayed before the rest of the text gets truncated. Requires `ellipsizeMode` to assume values different from `auto` and `none`.
 
-Determines the max characters when `truncate` is set.
+-   Required: No
+-   Default: `0`
 
-##### numberOfLines
+##### `numberOfLines`: `number`
 
-**Type**: `number`
+Clamps the text content to the specified `numberOfLines`, adding an ellipsis at the end. Note: this feature ignores the value of the `ellipsis` prop and always displays the default `…` ellipsis.
 
-Clamps the text content to the specifiec `numberOfLines`, adding the `ellipsis` at the end.
+-   Required: No
+-   Default: `0`
 
 ```jsx
 import { __experimentalTruncate as Truncate } from '@wordpress/components';

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

@@ -1,15 +1,20 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
-import { contextConnect } from '../ui/context';
+import { contextConnect, WordPressComponentProps } from '../ui/context';
 import { View } from '../view';
 import useTruncate from './hook';
+import type { TruncateProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'span'>} props
- * @param {import('react').ForwardedRef<any>}                                                forwardedRef
- */
-function Truncate( props, forwardedRef ) {
+function UnconnectedTruncate(
+	props: WordPressComponentProps< TruncateProps, 'span' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const truncateProps = useTruncate( props );
 
 	return <View as="span" { ...truncateProps } ref={ forwardedRef } />;
@@ -21,7 +26,6 @@ function Truncate( props, forwardedRef ) {
  * `Subheading` is used to render text content. However,`Truncate` is
  * available for custom implementations.
  *
- * @example
  * ```jsx
  * import { __experimentalTruncate as Truncate } from `@wordpress/components`;
  *
@@ -36,6 +40,6 @@ function Truncate( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedTruncate = contextConnect( Truncate, 'Truncate' );
+export const Truncate = contextConnect( UnconnectedTruncate, 'Truncate' );
 
-export default ConnectedTruncate;
+export default Truncate;

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

@@ -11,15 +11,15 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import * as styles from './styles';
 import { TRUNCATE_ELLIPSIS, TRUNCATE_TYPE, truncateContent } from './utils';
 import { useCx } from '../utils/hooks/use-cx';
+import type { TruncateProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'span'>} props
- */
-export default function useTruncate( props ) {
+export default function useTruncate(
+	props: WordPressComponentProps< TruncateProps, 'span' >
+) {
 	const {
 		className,
 		children,
@@ -33,7 +33,7 @@ export default function useTruncate( props ) {
 	const cx = useCx();
 
 	const truncatedContent = truncateContent(
-		typeof children === 'string' ? /** @type {string} */ ( children ) : '',
+		typeof children === 'string' ? children : '',
 		{
 			ellipsis,
 			ellipsizeMode,
@@ -45,9 +45,7 @@ export default function useTruncate( props ) {
 	const shouldTruncate = ellipsizeMode === TRUNCATE_TYPE.auto;
 
 	const classes = useMemo( () => {
-		const sx = {};
-
-		sx.numberOfLines = css`
+		const truncateLines = css`
 			-webkit-box-orient: vertical;
 			-webkit-line-clamp: ${ numberOfLines };
 			display: -webkit-box;
@@ -56,7 +54,7 @@ export default function useTruncate( props ) {
 
 		return cx(
 			shouldTruncate && ! numberOfLines && styles.Truncate,
-			shouldTruncate && !! numberOfLines && sx.numberOfLines,
+			shouldTruncate && !! numberOfLines && truncateLines,
 			className
 		);
 	}, [ className, cx, numberOfLines, shouldTruncate ] );

package/src/truncate/stories/index.tsx

@@ -0,0 +1,49 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Truncate } from '..';
+
+const meta: ComponentMeta< typeof Truncate > = {
+	component: Truncate,
+	title: 'Components (Experimental)/Truncate',
+	argTypes: {
+		children: { control: { type: 'text' } },
+		as: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const defaultText =
+	'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.';
+
+const Template: ComponentStory< typeof Truncate > = ( args ) => {
+	return <Truncate { ...args } />;
+};
+
+export const Default: ComponentStory< typeof Truncate > = Template.bind( {} );
+Default.args = {
+	numberOfLines: 2,
+	children: defaultText,
+};
+
+export const CharacterCount: ComponentStory< typeof Truncate > = Template.bind(
+	{}
+);
+CharacterCount.args = {
+	limit: 23,
+	children: defaultText,
+	ellipsizeMode: 'tail',
+	ellipsis: '[---]',
+};
+CharacterCount.storyName = 'Truncate by character count';

package/src/truncate/test/{index.js → index.tsx}

@@ -11,7 +11,7 @@ import { Truncate } from '..';
 describe( 'props', () => {
 	test( 'should render correctly', () => {
 		const { container } = render( <Truncate>Lorem ipsum.</Truncate> );
-		expect( container.firstChild.textContent ).toEqual( 'Lorem ipsum.' );
+		expect( container.firstChild?.textContent ).toEqual( 'Lorem ipsum.' );
 	} );
 
 	test( 'should render limit', () => {
@@ -20,7 +20,7 @@ describe( 'props', () => {
 				Lorem ipsum.
 			</Truncate>
 		);
-		expect( container.firstChild.textContent ).toEqual( 'L…' );
+		expect( container.firstChild?.textContent ).toEqual( 'L…' );
 	} );
 
 	test( 'should render custom ellipsis', () => {
@@ -29,7 +29,7 @@ describe( 'props', () => {
 				Lorem ipsum.
 			</Truncate>
 		);
-		expect( container.firstChild.textContent ).toEqual( 'Lorem!!!' );
+		expect( container.firstChild?.textContent ).toEqual( 'Lorem!!!' );
 	} );
 
 	test( 'should render custom ellipsizeMode', () => {
@@ -38,6 +38,6 @@ describe( 'props', () => {
 				Lorem ipsum.
 			</Truncate>
 		);
-		expect( container.firstChild.textContent ).toEqual( 'Lo!!!m.' );
+		expect( container.firstChild?.textContent ).toEqual( 'Lo!!!m.' );
 	} );
 } );

package/src/truncate/types.ts

@@ -1,14 +1,26 @@
-export type TruncateEllisizeMode = 'auto' | 'head' | 'tail' | 'middle' | 'none';
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
 
-export interface Props {
+export type TruncateEllipsizeMode =
+	| 'auto'
+	| 'head'
+	| 'tail'
+	| 'middle'
+	| 'none';
+
+export type TruncateProps = {
 	/**
-	 * The ellipsis string when `truncate` is set.
+	 * The ellipsis string when truncating the text by the `limit` prop's value.
 	 *
-	 * @default '...'
+	 * @default '…'
 	 */
 	ellipsis?: string;
 	/**
-	 * Determines where to truncate.  For example, we can truncate text right in the middle. To do this, we need to set `ellipsizeMode` to `middle` and a text `limit`.
+	 * Determines where to truncate.  For example, we can truncate text right in
+	 * the middle. To do this, we need to set `ellipsizeMode` to `middle` and a
+	 * text `limit`.
 	 *
 	 * * `auto`: Trims content at the end automatically without a `limit`.
 	 * * `head`: Trims content at the beginning. Requires a `limit`.
@@ -17,19 +29,25 @@ export interface Props {
 	 *
 	 * @default 'auto'
 	 */
-	ellipsizeMode?: TruncateEllisizeMode;
+	ellipsizeMode?: TruncateEllipsizeMode;
 	/**
-	 * Determines the max characters when `truncate` is set.
+	 * Determines the max number of characters to be displayed before the rest
+	 * of the text gets truncated. Requires `ellipsizeMode` to assume values
+	 * different from `auto` and `none`.
 	 *
 	 * @default 0
 	 */
 	limit?: number;
 	/**
-	 * Clamps the text content to the specified `numberOfLines`, adding the `ellipsis` at the end.
+	 * Clamps the text content to the specified `numberOfLines`, adding an
+	 * ellipsis at the end. Note: this feature ignores the value of the
+	 * `ellipsis` prop and always displays the default `…` ellipsis.
+	 *
+	 * @default 0
 	 */
 	numberOfLines?: number;
 	/**
 	 * The children elements.
 	 */
-	children: React.ReactNode;
-}
+	children: ReactNode;
+};

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

@@ -1,7 +1,8 @@
 /**
- * External dependencies
+ * Internal dependencies
  */
-import { isNil } from 'lodash';
+import { isValueDefined } from '../utils/values';
+import type { TruncateProps } from './types';
 
 export const TRUNCATE_ELLIPSIS = '…';
 export const TRUNCATE_TYPE = {
@@ -10,7 +11,7 @@ export const TRUNCATE_TYPE = {
 	middle: 'middle',
 	tail: 'tail',
 	none: 'none',
-};
+} as const;
 
 export const TRUNCATE_DEFAULT_PROPS = {
 	ellipsis: TRUNCATE_ELLIPSIS,
@@ -21,13 +22,12 @@ export const TRUNCATE_DEFAULT_PROPS = {
 
 // Source
 // https://github.com/kahwee/truncate-middle
-/**
- * @param {string} word
- * @param {number} headLength
- * @param {number} tailLength
- * @param {string} ellipsis
- */
-export function truncateMiddle( word, headLength, tailLength, ellipsis ) {
+export function truncateMiddle(
+	word: string,
+	headLength: number,
+	tailLength: number,
+	ellipsis: string
+) {
 	if ( typeof word !== 'string' ) {
 		return '';
 	}
@@ -38,7 +38,9 @@ export function truncateMiddle( word, headLength, tailLength, ellipsis ) {
 	// eslint-disable-next-line no-bitwise
 	const backLength = ~~tailLength;
 	/* istanbul ignore next */
-	const truncateStr = ! isNil( ellipsis ) ? ellipsis : TRUNCATE_ELLIPSIS;
+	const truncateStr = isValueDefined( ellipsis )
+		? ellipsis
+		: TRUNCATE_ELLIPSIS;
 
 	if (
 		( frontLength === 0 && backLength === 0 ) ||
@@ -57,12 +59,10 @@ export function truncateMiddle( word, headLength, tailLength, ellipsis ) {
 	);
 }
 
-/**
- *
- * @param {string}                        words
- * @param {typeof TRUNCATE_DEFAULT_PROPS} props
- */
-export function truncateContent( words = '', props ) {
+export function truncateContent(
+	words: string = '',
+	props: Omit< TruncateProps, 'children' >
+) {
 	const mergedProps = { ...TRUNCATE_DEFAULT_PROPS, ...props };
 	const { ellipsis, ellipsizeMode, limit } = mergedProps;
 
@@ -70,8 +70,8 @@ export function truncateContent( words = '', props ) {
 		return words;
 	}
 
-	let truncateHead;
-	let truncateTail;
+	let truncateHead: number;
+	let truncateTail: number;
 
 	switch ( ellipsizeMode ) {
 		case TRUNCATE_TYPE.head:

package/src/ui/context/wordpress-component.ts

@@ -47,8 +47,7 @@ export type WordPressComponent<
 	selector: `.${ string }`;
 };
 
-export type WordPressComponentFromProps<
-	Props
-> = Props extends WordPressComponentProps< infer P, infer T, infer I >
-	? WordPressComponent< T, P, I >
-	: never;
+export type WordPressComponentFromProps< Props > =
+	Props extends WordPressComponentProps< infer P, infer T, infer I >
+		? WordPressComponent< T, P, I >
+		: never;