@wordpress/components 19.13.0 → 19.14.0

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/utils/math.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { clamp } from 'lodash';
-
 /**
  * Parses and retrieves a number value.
  *
@@ -61,6 +56,20 @@ function getPrecision( value ) {
 	return split[ 1 ] !== undefined ? split[ 1 ].length : 0;
 }
 
+/**
+ * Clamps a value based on a min/max range.
+ *
+ * @param {number} value The value.
+ * @param {number} min   The minimum range.
+ * @param {number} max   The maximum range.
+ *
+ * @return {number} The clamped value.
+ */
+export function clamp( value, min, max ) {
+	const baseValue = getNumber( value );
+	return Math.max( min, Math.min( baseValue, max ) );
+}
+
 /**
  * Clamps a value based on a min/max range with rounding
  *

package/src/utils/test/math.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { add, subtract, roundClamp } from '../math';
+import { add, clamp, subtract, roundClamp } from '../math';
 
 describe( 'add', () => {
 	it( 'should add string and number values', () => {
@@ -37,6 +37,27 @@ describe( 'subtract', () => {
 	} );
 } );
 
+describe( 'clamp', () => {
+	it( 'should clamp a value between min and max', () => {
+		expect( clamp( 10, 1, 10 ) ).toBe( 10 );
+		expect( clamp( 1, 1, 10 ) ).toBe( 1 );
+		expect( clamp( 0, 1, 10 ) ).toBe( 1 );
+
+		expect( clamp( 50, 1, 10 ) ).toBe( 10 );
+		expect( clamp( 50, -10, 10 ) ).toBe( 10 );
+		expect( clamp( -50, -10, 10 ) ).toBe( -10 );
+
+		expect( clamp( Infinity, -10, 10 ) ).toBe( 10 );
+		expect( clamp( -Infinity, -10, 10 ) ).toBe( -10 );
+	} );
+
+	it( 'should clamp number or string values', () => {
+		expect( clamp( '50', 1, 10 ) ).toBe( 10 );
+		expect( clamp( '50', -10, 10 ) ).toBe( 10 );
+		expect( clamp( -50, -10, '10' ) ).toBe( -10 );
+	} );
+} );
+
 describe( 'roundClamp', () => {
 	it( 'should clamp a value between min and max', () => {
 		expect( roundClamp( 10, 1, 10 ) ).toBe( 10 );

package/src/v-stack/README.md

@@ -29,9 +29,7 @@ function Example() {
 
 ## Props
 
-##### alignment
-
-**Type**: `HStackAlignment`,`CSS['alignItems']`
+##### `alignment`: `HStackAlignment | CSSProperties['alignItems']`
 
 Determines how the child elements are aligned.
 
@@ -47,35 +45,25 @@ Determines how the child elements are aligned.
 -   `edge`: Aligns content to the edges of the container.
 -   `stretch`: Stretches content to the edges of the container.
 
-##### direction
-
-**Type**: `FlexDirection`
+##### `direction`: `FlexDirection`
 
 The direction flow of the children content can be adjusted with `direction`. `column` will align children vertically and `row` will align children horizontally.
 
-##### expanded
-
-**Type**: `boolean`
+##### `expanded`: `boolean`
 
 Expands to the maximum available width (if horizontal) or height (if vertical).
 
-##### justify
-
-**Type**: `CSS['justifyContent']`
+##### `justify`: `CSSProperties['justifyContent']`
 
 Horizontally aligns content if the `direction` is `row`, or vertically aligns content if the `direction` is `column`.
 In the example below, `flex-start` will align the children content to the left.
 
-##### spacing
-
-**Type**: `CSS['width']`
+##### `spacing`: `CSSProperties['width']`
 
 The amount of space between each child element. Spacing in between each child can be adjusted by using `spacing`.
 The value of `spacing` works as a multiplier to the library's grid system (base of `4px`).
 
-##### wrap
-
-**Type**: `boolean`
+##### `wrap`: `boolean`
 
 Determines if children should wrap.
 

package/src/v-stack/{component.js → component.tsx}

@@ -1,26 +1,31 @@
+/**
+ * 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 { useVStack } from './hook';
+import type { VStackProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function VStack( props, forwardedRef ) {
+function UnconnectedVStack(
+	props: WordPressComponentProps< VStackProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const vStackProps = useVStack( props );
 
 	return <View { ...vStackProps } ref={ forwardedRef } />;
 }
 
 /**
- * `VStack` (or Vertical Stack) is a layout component that arranges child elements in a vertical line.
+ * `VStack` (or Vertical Stack) is a layout component that arranges child
+ * elements in a vertical line.
  *
  * `VStack` can render anything inside.
  *
- * @example
  * ```jsx
  * import {
  * 	__experimentalText as Text,
@@ -38,6 +43,6 @@ function VStack( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedVStack = contextConnect( VStack, 'VStack' );
+export const VStack = contextConnect( UnconnectedVStack, 'VStack' );
 
-export default ConnectedVStack;
+export default VStack;

package/src/v-stack/{hook.js → hook.ts}

@@ -1,14 +1,13 @@
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { useHStack } from '../h-stack';
+import type { VStackProps } from './types';
 
-/**
- *
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useVStack( props ) {
+export function useVStack(
+	props: WordPressComponentProps< VStackProps, 'div' >
+) {
 	const { expanded = false, ...otherProps } = useContextSystem(
 		props,
 		'VStack'

package/src/v-stack/stories/index.tsx

@@ -0,0 +1,41 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { VStack } from '..';
+
+const meta: ComponentMeta< typeof VStack > = {
+	component: VStack,
+	title: 'Components (Experimental)/VStack',
+	argTypes: {
+		alignment: { control: { type: 'text' } },
+		as: { control: { type: 'text' } },
+		direction: { control: { type: 'text' } },
+		justify: { control: { type: 'text' } },
+		spacing: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof VStack > = ( props ) => {
+	return (
+		<VStack { ...props }>
+			<View>One</View>
+			<View>Two</View>
+			<View>Three</View>
+			<View>Four</View>
+			<View>Five</View>
+		</VStack>
+	);
+};
+
+export const Default = Template.bind( {} );

package/src/v-stack/types.ts

@@ -8,7 +8,27 @@ import type { CSSProperties } from 'react';
  */
 import type { HStackAlignment, Props as HStackProps } from '../h-stack/types';
 
-export type Props = HStackProps & {
+export type VStackProps = HStackProps & {
+	/**
+	 * Determines how the child elements are aligned.
+	 *
+	 * -   `top`: Aligns content to the top.
+	 * -   `topLeft`: Aligns content to the top/left.
+	 * -   `topRight`: Aligns content to the top/right.
+	 * -   `left`: Aligns content to the left.
+	 * -   `center`: Aligns content to the center.
+	 * -   `right`: Aligns content to the right.
+	 * -   `bottom`: Aligns content to the bottom.
+	 * -   `bottomLeft`: Aligns content to the bottom/left.
+	 * -   `bottomRight`: Aligns content to the bottom/right.
+	 * -   `edge`: Aligns content to the edges of the container.
+	 * -   `stretch`: Stretches content to the edges of the container.
+	 */
 	alignment?: HStackAlignment | CSSProperties[ 'alignItems' ];
+	/**
+	 * The amount of space between each child element. Spacing in between each
+	 * child can be adjusted by using `spacing`. The value of `spacing` works as
+	 * a multiplier to the library's grid system (base of `4px`).
+	 */
 	spacing?: CSSProperties[ 'width' ];
 };

package/tsconfig.json

@@ -57,6 +57,7 @@
 		"src/external-link/**/*",
 		"src/flex/**/*",
 		"src/form-group/**/*",
+		"src/form-toggle/**/*",
 		"src/form-token-field/**/*",
 		"src/grid/**/*",
 		"src/h-stack/**/*",