@wordpress/components 19.12.0 → 19.15.0

package/src/form-token-field/token-input.tsx

@@ -0,0 +1,76 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+import type { ChangeEvent, ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+import type { TokenInputProps } from './types';
+
+export function UnForwardedTokenInput(
+	props: WordPressComponentProps< TokenInputProps, 'input', false >,
+	ref: ForwardedRef< HTMLInputElement >
+) {
+	const {
+		value,
+		isExpanded,
+		instanceId,
+		selectedSuggestionIndex,
+		className,
+		onChange,
+		...restProps
+	} = props;
+
+	const size = value ? value.length + 1 : 0;
+
+	const onChangeHandler = ( event: ChangeEvent< HTMLInputElement > ) => {
+		if ( onChange ) {
+			onChange( {
+				value: event.target.value,
+			} );
+		}
+	};
+
+	return (
+		<input
+			ref={ ref }
+			id={ `components-form-token-input-${ instanceId }` }
+			type="text"
+			{ ...restProps }
+			value={ value || '' }
+			onChange={ onChangeHandler }
+			size={ size }
+			className={ classnames(
+				className,
+				'components-form-token-field__input'
+			) }
+			autoComplete="off"
+			role="combobox"
+			aria-expanded={ isExpanded }
+			aria-autocomplete="list"
+			aria-owns={
+				isExpanded
+					? `components-form-token-suggestions-${ instanceId }`
+					: undefined
+			}
+			aria-activedescendant={
+				selectedSuggestionIndex !== -1
+					? `components-form-token-suggestions-${ instanceId }-${ selectedSuggestionIndex }`
+					: undefined
+			}
+			aria-describedby={ `components-form-token-suggestions-howto-${ instanceId }` }
+		/>
+	);
+}
+
+export const TokenInput = forwardRef( UnForwardedTokenInput );
+
+export default TokenInput;

package/src/form-token-field/{token.js → token.tsx}

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { noop } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -16,6 +15,9 @@ import { closeSmall } from '@wordpress/icons';
  */
 import Button from '../button';
 import { VisuallyHidden } from '../visually-hidden';
+import type { TokenProps } from './types';
+
+const noop = () => {};
 
 export default function Token( {
 	value,
@@ -30,7 +32,7 @@ export default function Token( {
 	messages,
 	termPosition,
 	termsCount,
-} ) {
+}: TokenProps ) {
 	const instanceId = useInstanceId( Token );
 	const tokenClasses = classnames( 'components-form-token-field__token', {
 		'is-error': 'error' === status,

package/src/form-token-field/types.ts

@@ -0,0 +1,185 @@
+/**
+ * External dependencies
+ */
+import type { ComponentPropsWithRef, MouseEventHandler } from 'react';
+
+type Messages = {
+	/**
+	 * The user added a new token.
+	 */
+	added: string;
+	/**
+	 * The user removed an existing token.
+	 */
+	removed: string;
+	/**
+	 * The user focused the button to remove the token.
+	 */
+	remove: string;
+	/**
+	 * The user tried to add a token that didn't pass the validation.
+	 */
+	__experimentalInvalid: string;
+};
+
+export interface TokenItem {
+	/**
+	 *  The value of the token.
+	 */
+	value: string;
+	/**
+	 * One of 'error', 'validating', or 'success'. Applies styles to token.
+	 */
+	status?: 'error' | 'success' | 'validating';
+	/**
+	 * If not falsey, will add a title to the token.
+	 */
+	title?: string;
+	/**
+	 * When true, renders tokens as without a background.
+	 */
+	isBorderless?: boolean;
+	/**
+	 * Function to call when onMouseEnter event triggered on token.
+	 */
+	onMouseEnter?: MouseEventHandler< HTMLSpanElement >;
+	/**
+	 *  Function to call when onMouseLeave is triggered on token.
+	 */
+	onMouseLeave?: MouseEventHandler< HTMLSpanElement >;
+}
+
+export interface FormTokenFieldProps
+	extends Pick<
+		ComponentPropsWithRef< 'input' >,
+		'autoCapitalize' | 'autoComplete' | 'className'
+	> {
+	label?: string;
+	/**
+	 * An array of strings to present to the user as suggested tokens.
+	 */
+	suggestions?: string[];
+	/**
+	 * The maximum number of suggestions to display at a time.
+	 *
+	 * @default 100
+	 */
+	maxSuggestions?: number;
+	/**
+	 * An array of strings or objects to display as tokens in the field.
+	 * If objects are present in the array, they **must** have a property of `value`.
+	 */
+	value?: ( string | TokenItem )[];
+	/**
+	 * Function to call to transform tokens for display.
+	 * (In the editor, this is needed to decode HTML entities embedded in tags
+	 * - otherwise entities like `&` in tag names are double-encoded like `&amp;`,
+	 * once by the REST API and once by React).
+	 */
+	displayTransform?: ( token: string ) => string;
+	/**
+	 * Function to call to transform tokens for saving. The default is to trim the token value.
+	 * This function is also applied when matching suggestions against the current value
+	 * so that matching works correctly with leading or trailing spaces. (In the editor,
+	 * this is needed to remove leading and trailing spaces from tag names, like wp-admin does.
+	 * Otherwise the REST API won't save them.)
+	 *
+	 * @default ( token: string ) => token.trim()
+	 */
+	saveTransform?: ( token: string ) => string;
+	/**
+	 * Function to call when the tokens have changed. An array of new tokens is passed to the callback.
+	 *
+	 */
+	onChange?: ( tokens: ( string | TokenItem )[] ) => void;
+	/**
+	 * Function to call when the users types in the input field. It can be used to trigger autocomplete requests.
+	 *
+	 */
+	onInputChange?: ( input: string ) => void;
+	/**
+	 * Function to call when the TokenField has been focused on. The event is passed to the callback. Useful for analytics.
+	 *
+	 */
+	onFocus?: ( event: FocusEvent ) => void;
+	/**
+	 *  When true, renders tokens as without a background.
+	 */
+	isBorderless?: boolean;
+	/**
+	 * If passed, `TokenField` will disable ability to add new tokens once number of tokens is greater than or equal to `maxLength`.
+	 */
+	maxLength?: number;
+	/**
+	 * When true, tokens are not able to be added or removed.
+	 */
+	disabled?: boolean;
+	/**
+	 * If passed, the `TokenField` input will show a placeholder string if no value tokens are present.
+	 */
+	placeholder?: string;
+	/**
+	 * If true, will add a token when `TokenField` is focused and `space` is pressed.
+	 */
+	tokenizeOnSpace?: boolean;
+	/**
+	 * Allows customizing the messages presented by screen readers in different occasions:
+	 *
+	 * -   `added`: The user added a new token.
+	 * -   `removed`: The user removed an existing token.
+	 * -   `remove` : The user focused the button to remove the token.
+	 * -   `__experimentalInvalid`: The user tried to add a token that didn't pass the validation.
+	 */
+	messages?: Messages;
+	/**
+	 * If true, the suggestions list will be always expanded when the input field has the focus.
+	 */
+	__experimentalExpandOnFocus?: boolean;
+	/**
+	 * If passed, all introduced values will be validated before being added as tokens.
+	 *
+	 * @default () => true
+	 */
+	__experimentalValidateInput?: ( token: string ) => boolean;
+	/**
+	 * If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
+	 *
+	 * @default true
+	 */
+	__experimentalShowHowTo?: boolean;
+	/**
+	 * Start opting into the larger default height that will become the
+	 * default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next36pxDefaultSize?: boolean;
+}
+
+export interface SuggestionsListProps< T = string | { value: string } > {
+	selectedIndex: number;
+	scrollIntoView: boolean;
+	match: T;
+	onHover: ( suggestion: T ) => void;
+	onSelect: ( suggestion: T ) => void;
+	suggestions: T[];
+	displayTransform: ( value: T ) => string;
+	instanceId: string | number;
+}
+
+export interface TokenProps extends TokenItem {
+	displayTransform: ( value: string ) => string;
+	disabled: boolean;
+	onClickRemove: ( { value }: { value: string } ) => void;
+	messages: Messages;
+	termPosition: number;
+	termsCount: number;
+}
+
+export interface TokenInputProps {
+	isExpanded: boolean;
+	instanceId: string | number;
+	selectedSuggestionIndex: number;
+	onChange?: ( { value }: { value: string } ) => void;
+	value: string;
+}

package/src/gradient-picker/index.js

@@ -108,9 +108,10 @@ export default function GradientPicker( {
 	__experimentalHasMultipleOrigins,
 	__experimentalIsRenderedInSidebar,
 } ) {
-	const clearGradient = useCallback( () => onChange( undefined ), [
-		onChange,
-	] );
+	const clearGradient = useCallback(
+		() => onChange( undefined ),
+		[ onChange ]
+	);
 	const Component =
 		__experimentalHasMultipleOrigins && gradients?.length
 			? MultipleOrigin

package/src/grid/README.md

@@ -27,56 +27,70 @@ function Example() {
 
 ## Props
 
-##### align
-
-**Type**: `CSS['alignItems']`
+##### `align`: `CSS['alignItems']`
 
 Adjusts the block alignment of children.
 
-##### alignment
+-   Required: No
 
-**Type**: `GridAlignment`
+##### `alignment`: `GridAlignment`
 
 Adjusts the horizontal and vertical alignment of children.
 
-##### columns
+-   Required: No
+
+##### `columnGap`: `CSSProperties['gridColumnGap']`
+
+Adjusts the `grid-column-gap`.
+
+-   Required: No
 
-**Type**: `number`,`(number`,`null)[]`
+##### `columns`: `number`
 
 Adjusts the number of columns of the `Grid`.
 
-##### gap
+-   Required: No
+-   Default: `2`
 
-**Type**: `number`
+##### `gap`: `number`
 
 Gap between each child.
 
-##### isInline
+-   Required: No
+-   Default: `3`
 
-**Type**: `boolean`
+##### `isInline`: `boolean`
 
 Changes the CSS display from `grid` to `inline-grid`.
 
-##### justify
+-   Required: No
 
-**Type**: `CSS['justifyContent']`
+##### `justify`: `CSS['justifyContent']`
 
 Adjusts the inline alignment of children.
 
-##### rows
+-   Required: No
 
-**Type**: `number`,`(number`,`null)[]`
+##### `rowGap`: `CSSProperties['gridRowGap']`
+
+Adjusts the `grid-row-gap`.
+
+-   Required: No
+
+##### `rows`: `number`
 
 Adjusts the number of rows of the `Grid`.
 
-##### templateColumns
+-   Required: No
 
-**Type**: `CSS['gridTemplateColumns']`
+##### `templateColumns`: `CSS['gridTemplateColumns']`
 
 Adjusts the CSS grid `template-columns`.
 
-##### templateRows
+-   Required: No
 
-**Type**: `CSS['gridTemplateRows']`
+##### `templateRows`: `CSS['gridTemplateRows']`
 
 Adjusts the CSS grid `template-rows`.
+
+-   Required: No

package/src/grid/{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 useGrid from './hook';
+import type { GridProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function Grid( props, forwardedRef ) {
+function UnconnectedGrid(
+	props: WordPressComponentProps< GridProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const gridProps = useGrid( props );
 
 	return <View { ...gridProps } ref={ forwardedRef } />;
@@ -18,7 +23,6 @@ function Grid( props, forwardedRef ) {
 /**
  * `Grid` is a primitive layout component that can arrange content in a grid configuration.
  *
- * @example
  * ```jsx
  * import {
  * 	__experimentalGrid as Grid,
@@ -36,6 +40,6 @@ function Grid( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedGrid = contextConnect( Grid, 'Grid' );
+export const Grid = contextConnect( UnconnectedGrid, 'Grid' );
 
-export default ConnectedGrid;
+export default Grid;

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

@@ -11,16 +11,16 @@ import { useMemo } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { useContextSystem } from '../ui/context';
+import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { getAlignmentProps } from './utils';
 import { useResponsiveValue } from '../ui/utils/use-responsive-value';
 import CONFIG from '../utils/config-values';
 import { useCx } from '../utils/hooks/use-cx';
+import type { GridProps } from './types';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export default function useGrid( props ) {
+export default function useGrid(
+	props: WordPressComponentProps< GridProps, 'div' >
+) {
 	const {
 		align,
 		alignment,

package/src/grid/stories/index.tsx

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../view';
+import { Grid } from '..';
+
+const meta: ComponentMeta< typeof Grid > = {
+	component: Grid,
+	title: 'Components (Experimental)/Grid',
+	argTypes: {
+		as: { control: { type: 'text' } },
+		align: { control: { type: 'text' } },
+		children: { control: { type: null } },
+		columnGap: { control: { type: 'text' } },
+		columns: {
+			table: { type: { summary: 'number' } },
+			control: { type: 'number' },
+		},
+		justify: { control: { type: 'text' } },
+		rowGap: { control: { type: 'text' } },
+		rows: {
+			table: { type: { summary: 'number' } },
+			control: { type: 'number' },
+		},
+		templateColumns: { control: { type: 'text' } },
+		templateRows: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Item = ( props: { children: string } ) => (
+	<View
+		style={ {
+			borderRadius: 8,
+			background: '#eee',
+			padding: 8,
+			textAlign: 'center',
+		} }
+		{ ...props }
+	/>
+);
+
+const Template: ComponentStory< typeof Grid > = ( props ) => (
+	<Grid { ...props }>
+		<Item>One</Item>
+		<Item>Two</Item>
+		<Item>Three</Item>
+		<Item>Four</Item>
+		<Item>Five</Item>
+		<Item>Six</Item>
+		<Item>Seven</Item>
+		<Item>Eight</Item>
+	</Grid>
+);
+
+export const Default: ComponentStory< typeof Grid > = Template.bind( {} );
+Default.args = {
+	alignment: 'bottom',
+	columns: 4,
+	gap: 2,
+};

package/src/grid/test/{grid.js → grid.tsx}

@@ -28,7 +28,7 @@ describe( 'props', () => {
 
 	test( 'should render gap', () => {
 		const { container } = render(
-			<Grid columns="3" gap={ 4 }>
+			<Grid columns={ 3 } gap={ 4 }>
 				<View />
 				<View />
 				<View />
@@ -44,7 +44,7 @@ describe( 'props', () => {
 
 	test( 'should render custom columns', () => {
 		const { container } = render(
-			<Grid columns="7">
+			<Grid columns={ 7 }>
 				<View />
 				<View />
 				<View />
@@ -59,7 +59,7 @@ describe( 'props', () => {
 
 	test( 'should render custom rows', () => {
 		const { container } = render(
-			<Grid rows="7">
+			<Grid rows={ 7 }>
 				<View />
 				<View />
 				<View />
@@ -120,7 +120,7 @@ describe( 'props', () => {
 
 	test( 'should render isInline', () => {
 		const { container } = render(
-			<Grid columns="3" isInline>
+			<Grid columns={ 3 } isInline>
 				<View />
 				<View />
 				<View />

package/src/grid/types.ts

@@ -1,9 +1,12 @@
 /**
  * External dependencies
  */
-import type { CSSProperties } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
-type ResponsiveCSSValue< T > = Array< T | undefined > | T;
+/**
+ * Internal dependencies
+ */
+import type { ResponsiveCSSValue } from '../ui/utils/types';
 
 type GridAlignment =
 	| 'bottom'
@@ -18,11 +21,7 @@ type GridAlignment =
 	| 'topLeft'
 	| 'topRight';
 
-type GridColumns = ResponsiveCSSValue< number >;
-
-type GridRows = ResponsiveCSSValue< number >;
-
-export type Props = {
+export type GridProps = {
 	/**
 	 * Adjusts the block alignment of children.
 	 */
@@ -31,26 +30,30 @@ export type Props = {
 	 * Adjusts the horizontal and vertical alignment of children.
 	 */
 	alignment?: GridAlignment;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
 	/**
 	 * Adjusts the number of columns of the `Grid`.
 	 *
 	 * @default 2
 	 */
-	columns?: GridColumns;
+	columns?: ResponsiveCSSValue< number >;
 	/**
 	 * Adjusts the `grid-column-gap`.
 	 */
 	columnGap?: CSSProperties[ 'gridColumnGap' ];
-	/**
-	 * Changes the CSS display from `grid` to `inline-grid`.
-	 */
-	isInline?: boolean;
 	/**
 	 * Gap between each child.
 	 *
 	 * @default 3
 	 */
 	gap?: number;
+	/**
+	 * Changes the CSS display from `grid` to `inline-grid`.
+	 */
+	isInline?: boolean;
 	/**
 	 * Adjusts the inline alignment of children.
 	 */
@@ -62,7 +65,7 @@ export type Props = {
 	/**
 	 * Adjusts the number of rows of the `Grid`.
 	 */
-	rows?: GridRows;
+	rows?: ResponsiveCSSValue< number >;
 	/**
 	 * Adjusts the CSS grid `template-columns`.
 	 */
@@ -71,8 +74,4 @@ export type Props = {
 	 * Adjusts the CSS grid `template-rows`.
 	 */
 	templateRows?: CSSProperties[ 'gridTemplateRows' ];
-	/**
-	 * The children elements.
-	 */
-	children: React.ReactNode;
 };

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

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { CSSProperties } from 'react';
+
 const ALIGNMENTS = {
 	bottom: { alignItems: 'flex-end', justifyContent: 'center' },
 	bottomLeft: { alignItems: 'flex-start', justifyContent: 'flex-end' },
@@ -12,14 +17,11 @@ const ALIGNMENTS = {
 	topRight: { alignItems: 'flex-start', justifyContent: 'flex-end' },
 };
 
-/* eslint-disable jsdoc/valid-types */
-/**
- * @param {keyof typeof ALIGNMENTS | undefined} alignment
- * @return {{ alignItems?: import('react').CSSProperties['alignItems'], justifyContent?: import('react').CSSProperties['justifyContent']}} CSS props for alignment
- */
-export function getAlignmentProps( alignment ) {
+export function getAlignmentProps( alignment?: keyof typeof ALIGNMENTS ): {
+	alignItems?: CSSProperties[ 'alignItems' ];
+	justifyContent?: CSSProperties[ 'justifyContent' ];
+} {
 	const alignmentProps = alignment ? ALIGNMENTS[ alignment ] : {};
 
 	return alignmentProps;
 }
-/* eslint-enable jsdoc/valid-types */

package/src/guide/style.scss

@@ -20,6 +20,7 @@
 		border-bottom: none;
 		padding: 0;
 		position: sticky;
+		height: $header-height;
 
 		.components-button {
 			align-self: flex-start;