@wordpress/element 6.30.0 → 6.30.1-next.836ecdcae.0

package/src/{create-interpolate-element.js → create-interpolate-element.ts}

@@ -1,15 +1,18 @@
 /**
  * Internal dependencies
  */
-import { createElement, cloneElement, Fragment, isValidElement } from './react';
+import {
+	createElement,
+	cloneElement,
+	Fragment,
+	isValidElement,
+	type Element as ReactElement,
+} from './react';
 
-/**
- * Object containing a React element.
- *
- * @typedef {import('react').ReactElement} Element
- */
-
-let indoc, offset, output, stack;
+let indoc: string;
+let offset: number;
+let output: ( string | ReactElement )[];
+let stack: Frame[];
 
 /**
  * Matches tags in the localized string
@@ -23,28 +26,40 @@ let indoc, offset, output, stack;
  * isClosing: The closing slash, if it exists.
  * name: The name portion of the tag (strong, br) (if )
  * isSelfClosed: The slash on a self closing tag, if it exists.
- *
- * @type {RegExp}
  */
 const tokenizer = /<(\/)?(\w+)\s*(\/)?>/g;
 
-/**
- * The stack frame tracking parse progress.
- *
- * @typedef Frame
- *
- * @property {Element}   element            A parent element which may still have
- * @property {number}    tokenStart         Offset at which parent element first
- *                                          appears.
- * @property {number}    tokenLength        Length of string marking start of parent
- *                                          element.
- * @property {number}    [prevOffset]       Running offset at which parsing should
- *                                          continue.
- * @property {number}    [leadingTextStart] Offset at which last closing element
- *                                          finished, used for finding text between
- *                                          elements.
- * @property {Element[]} children           Children.
- */
+interface Frame {
+	/**
+	 * A parent element which may still have nested children not yet parsed.
+	 */
+	element: ReactElement;
+
+	/**
+	 * Offset at which parent element first appears.
+	 */
+	tokenStart: number;
+
+	/**
+	 * Length of string marking start of parent element.
+	 */
+	tokenLength: number;
+
+	/**
+	 * Running offset at which parsing should continue.
+	 */
+	prevOffset?: number;
+
+	/**
+	 * Offset at which last closing element finished, used for finding text between elements.
+	 */
+	leadingTextStart?: number | null;
+
+	/**
+	 * Children.
+	 */
+	children: ( string | ReactElement )[];
+}
 
 /**
  * Tracks recursive-descent parse state.
@@ -53,27 +68,27 @@ const tokenizer = /<(\/)?(\w+)\s*(\/)?>/g;
  * parsed.
  *
  * @private
- * @param {Element} element            A parent element which may still have
- *                                     nested children not yet parsed.
- * @param {number}  tokenStart         Offset at which parent element first
- *                                     appears.
- * @param {number}  tokenLength        Length of string marking start of parent
- *                                     element.
- * @param {number}  [prevOffset]       Running offset at which parsing should
- *                                     continue.
- * @param {number}  [leadingTextStart] Offset at which last closing element
- *                                     finished, used for finding text between
- *                                     elements.
+ * @param element          A parent element which may still have
+ *                         nested children not yet parsed.
+ * @param tokenStart       Offset at which parent element first
+ *                         appears.
+ * @param tokenLength      Length of string marking start of parent
+ *                         element.
+ * @param prevOffset       Running offset at which parsing should
+ *                         continue.
+ * @param leadingTextStart Offset at which last closing element
+ *                         finished, used for finding text between
+ *                         elements.
  *
- * @return {Frame} The stack frame tracking parse progress.
+ * @return The stack frame tracking parse progress.
  */
 function createFrame(
-	element,
-	tokenStart,
-	tokenLength,
-	prevOffset,
-	leadingTextStart
-) {
+	element: ReactElement,
+	tokenStart: number,
+	tokenLength: number,
+	prevOffset?: number,
+	leadingTextStart?: number | null
+): Frame {
 	return {
 		element,
 		tokenStart,
@@ -105,13 +120,16 @@ function createFrame(
  * }
  * ```
  *
- * @param {string}                  interpolatedString The interpolation string to be parsed.
- * @param {Record<string, Element>} conversionMap      The map used to convert the string to
- *                                                     a react element.
+ * @param  interpolatedString The interpolation string to be parsed.
+ * @param  conversionMap      The map used to convert the string to
+ *                            a react element.
  * @throws {TypeError}
- * @return {Element}  A wp element.
+ * @return A wp element.
  */
-const createInterpolateElement = ( interpolatedString, conversionMap ) => {
+const createInterpolateElement = (
+	interpolatedString: string,
+	conversionMap: Record< string, ReactElement >
+): ReactElement => {
 	indoc = interpolatedString;
 	offset = 0;
 	output = [];
@@ -138,35 +156,48 @@ const createInterpolateElement = ( interpolatedString, conversionMap ) => {
  *
  * @private
  *
- * @param {Object} conversionMap The map being validated.
+ * @param conversionMap The map being validated.
  *
- * @return {boolean}  True means the map is valid.
+ * @return True means the map is valid.
  */
-const isValidConversionMap = ( conversionMap ) => {
-	const isObject = typeof conversionMap === 'object';
+const isValidConversionMap = (
+	conversionMap: Record< string, ReactElement >
+): boolean => {
+	const isObject =
+		typeof conversionMap === 'object' && conversionMap !== null;
 	const values = isObject && Object.values( conversionMap );
 	return (
 		isObject &&
-		values.length &&
+		values.length > 0 &&
 		values.every( ( element ) => isValidElement( element ) )
 	);
 };
 
+type TokenType = 'no-more-tokens' | 'self-closed' | 'opener' | 'closer';
+type TokenResult =
+	| [ TokenType & 'no-more-tokens' ]
+	| [
+			TokenType & ( 'self-closed' | 'opener' | 'closer' ),
+			string,
+			number,
+			number,
+	  ];
+
 /**
  * This is the iterator over the matches in the string.
  *
  * @private
  *
- * @param {Object} conversionMap The conversion map for the string.
+ * @param conversionMap The conversion map for the string.
  *
- * @return {boolean} true for continuing to iterate, false for finished.
+ * @return true for continuing to iterate, false for finished.
  */
-function proceed( conversionMap ) {
+function proceed( conversionMap: Record< string, ReactElement > ): boolean {
 	const next = nextToken();
 	const [ tokenType, name, startOffset, tokenLength ] = next;
 	const stackDepth = stack.length;
 	const leadingTextStart = startOffset > offset ? offset : null;
-	if ( ! conversionMap[ name ] ) {
+	if ( name && ! conversionMap[ name ] ) {
 		addText();
 		return false;
 	}
@@ -254,9 +285,9 @@ function proceed( conversionMap ) {
  *
  * @private
  *
- * @return {Array}  An array of details for the token matched.
+ * @return An array of details for the token matched.
  */
-function nextToken() {
+function nextToken(): TokenResult {
 	const matches = tokenizer.exec( indoc );
 	// We have no more tokens.
 	if ( null === matches ) {
@@ -281,7 +312,7 @@ function nextToken() {
  *
  * @private
  */
-function addText() {
+function addText(): void {
 	const length = indoc.length - offset;
 	if ( 0 === length ) {
 		return;
@@ -298,7 +329,7 @@ function addText() {
  * @param {Frame} frame The Frame containing the child element and it's
  *                      token information.
  */
-function addChild( frame ) {
+function addChild( frame: Frame ): void {
 	const { element, tokenStart, tokenLength, prevOffset, children } = frame;
 	const parent = stack[ stack.length - 1 ];
 	const text = indoc.substr(
@@ -326,7 +357,7 @@ function addChild( frame ) {
  *                           helps capture any remaining nested text nodes in
  *                           the element.
  */
-function closeOuterElement( endOffset ) {
+function closeOuterElement( endOffset: number ): void {
 	const { element, leadingTextStart, prevOffset, tokenStart, children } =
 		stack.pop();
 

package/src/{platform.js → platform.ts}

@@ -6,11 +6,15 @@
  * Copyright (c) 2015-present, Facebook, Inc.
  *
  */
-const Platform = {
-	OS: 'web',
-	select: ( spec ) => ( 'web' in spec ? spec.web : spec.default ),
-	isWeb: true,
+
+/**
+ * Specification for platform-specific value selection.
+ */
+type PlatformSelectSpec< T > = {
+	web?: T;
+	default?: T;
 };
+
 /**
  * Component used to detect the current Platform being used.
  * Use Platform.OS === 'web' to detect if running on web environment.
@@ -30,4 +34,23 @@ const Platform = {
  * } );
  * ```
  */
+const Platform = {
+	/** Platform identifier. Will always be `'web'` in this module. */
+	OS: 'web' as const,
+
+	/**
+	 * Select a value based on the platform.
+	 *
+	 * @template T
+	 * @param    spec - Object with optional platform-specific values.
+	 * @return The selected value.
+	 */
+	select< T >( spec: PlatformSelectSpec< T > ): T | undefined {
+		return 'web' in spec ? spec.web : spec.default;
+	},
+
+	/** Whether the platform is web */
+	isWeb: true,
+};
+
 export default Platform;

package/src/{raw-html.js → raw-html.ts}

@@ -3,7 +3,12 @@
  */
 import { Children, createElement } from './react';
 
-/** @typedef {{children: string} & import('react').ComponentPropsWithoutRef<'div'>} RawHTMLProps */
+/**
+ * Props for the RawHTML component.
+ */
+export type RawHTMLProps = {
+	children: string | string[];
+} & React.ComponentPropsWithoutRef< 'div' >;
 
 /**
  * Component used to render unescaped HTML.
@@ -24,9 +29,12 @@ import { Children, createElement } from './react';
  *                             of strings. Other props will be passed through
  *                             to the div wrapper.
  *
- * @return {JSX.Element} Dangerously-rendering component.
+ * @return Dangerously-rendering component.
  */
-export default function RawHTML( { children, ...props } ) {
+export default function RawHTML( {
+	children,
+	...props
+}: RawHTMLProps ): JSX.Element {
 	let rawHtml = '';
 
 	// Cast children as an array, and concatenate each element if it is a string.

package/src/{react.js → react.ts}

@@ -34,45 +34,37 @@ import {
 	lazy,
 	Suspense,
 } from 'react';
+import type { ReactNode } from 'react';
 
 /**
  * Object containing a React element.
- *
- * @typedef {import('react').ReactElement} Element
  */
+export type Element = React.ReactElement;
 
 /**
  * Object containing a React component.
- *
- * @typedef {import('react').ComponentType} ComponentType
  */
+export type ComponentType< T = any > = React.ComponentType< T >;
 
 /**
  * Object containing a React synthetic event.
- *
- * @typedef {import('react').SyntheticEvent} SyntheticEvent
  */
+export type SyntheticEvent< T = Element > = React.SyntheticEvent< T >;
 
 /**
  * Object containing a React ref object.
- *
- * @template T
- * @typedef {import('react').RefObject<T>} RefObject<T>
  */
+export type RefObject< T > = React.RefObject< T >;
 
 /**
  * Object containing a React ref callback.
- *
- * @template T
- * @typedef {import('react').RefCallback<T>} RefCallback<T>
  */
+export type RefCallback< T > = React.RefCallback< T >;
 
 /**
  * Object containing a React ref.
- *
- * @template T
- * @typedef {import('react').Ref<T>} Ref<T>
  */
+export type Ref< T > = React.Ref< T >;
 
 /**
  * Object that provides utilities for dealing with React children.
@@ -261,41 +253,52 @@ export { PureComponent };
 /**
  * Concatenate two or more React children objects.
  *
- * @param {...?Object} childrenArguments Array of children arguments (array of arrays/strings/objects) to concatenate.
- *
- * @return {Array} The concatenated value.
- */
-export function concatChildren( ...childrenArguments ) {
-	return childrenArguments.reduce( ( accumulator, children, i ) => {
-		Children.forEach( children, ( child, j ) => {
-			if ( child && 'string' !== typeof child ) {
-				child = cloneElement( child, {
-					key: [ i, j ].join(),
-				} );
-			}
-
-			accumulator.push( child );
-		} );
-
-		return accumulator;
-	}, [] );
+ * @param childrenArguments - Array of children arguments (array of arrays/strings/objects) to concatenate.
+ * @return The concatenated value.
+ */
+export function concatChildren(
+	...childrenArguments: ReactNode[][]
+): ReactNode[] {
+	return childrenArguments.reduce< ReactNode[] >(
+		( accumulator, children, i ) => {
+			Children.forEach( children, ( child, j ) => {
+				if ( isValidElement( child ) && typeof child !== 'string' ) {
+					child = cloneElement( child, {
+						key: [ i, j ].join(),
+					} );
+				}
+
+				accumulator.push( child );
+			} );
+
+			return accumulator;
+		},
+		[]
+	);
 }
 
 /**
  * Switches the nodeName of all the elements in the children object.
  *
- * @param {?Object} children Children object.
- * @param {string}  nodeName Node name.
+ * @param children Children object.
+ * @param nodeName Node name.
  *
- * @return {?Object} The updated children object.
+ * @return  The updated children object.
  */
-export function switchChildrenNodeName( children, nodeName ) {
+export function switchChildrenNodeName(
+	children: ReactNode,
+	nodeName: string
+): ReactNode {
 	return (
 		children &&
 		Children.map( children, ( elt, index ) => {
 			if ( typeof elt?.valueOf() === 'string' ) {
 				return createElement( nodeName, { key: index }, elt );
 			}
+			if ( ! isValidElement( elt ) ) {
+				return elt;
+			}
+
 			const { children: childrenProp, ...props } = elt.props;
 			return createElement(
 				nodeName,