dom: Add types to clean-node-list (#30412)

* dom: Type dependencies of clean-node-list

* dom: Add types to clean-node-list

* Fix property descriptions

packages/dom/README.md

@@ -151,8 +151,8 @@ the latter.
 
 _Parameters_
 
--   _newNode_ `Element`: Node to be inserted.
--   _referenceNode_ `Element`: Node after which to perform the insertion.
+-   _newNode_ `Node`: Node to be inserted.
+-   _referenceNode_ `Node`: Node after which to perform the insertion.
 
 _Returns_
 
@@ -291,7 +291,7 @@ Given a DOM node, removes it from the DOM.
 
 _Parameters_
 
--   _node_ `Element`: Node to be removed.
+-   _node_ `Node`: Node to be removed.
 
 _Returns_
 

packages/dom/src/dom/clean-node-list.js

@@ -11,27 +11,44 @@ import remove from './remove';
 import unwrap from './unwrap';
 import { isPhrasingContent } from '../phrasing-content';
 import insertAfter from './insert-after';
+import isElement from './is-element';
+
+/* eslint-disable jsdoc/valid-types */
+/**
+ * @typedef SchemaItem
+ * @property {string[]} [attributes] Attributes.
+ * @property {(string | RegExp)[]} [classes] Classnames or RegExp to test against.
+ * @property {'*' | { [tag: string]: SchemaItem }} [children] Child schemas.
+ * @property {string[]} [require] Selectors to test required children against. Leave empty or undefined if there are no requirements.
+ * @property {boolean} allowEmpty Whether to allow nodes without children.
+ * @property {(node: Node) => boolean} [isMatch] Function to test whether a node is a match. If left undefined any node will be assumed to match.
+ */
+
+/** @typedef {{ [tag: string]: SchemaItem }} Schema */
+/* eslint-enable jsdoc/valid-types */
 
 /**
  * Given a schema, unwraps or removes nodes, attributes and classes on a node
  * list.
  *
  * @param {NodeList} nodeList The nodeList to filter.
  * @param {Document} doc      The document of the nodeList.
- * @param {Object}   schema   An array of functions that can mutate with the provided node.
- * @param {Object}   inline   Whether to clean for inline mode.
+ * @param {Schema}   schema   An array of functions that can mutate with the provided node.
+ * @param {boolean}  inline   Whether to clean for inline mode.
  */
 export default function cleanNodeList( nodeList, doc, schema, inline ) {
-	Array.from( nodeList ).forEach( ( node ) => {
+	Array.from( nodeList ).forEach( (
+		/** @type {Node & { nextElementSibling?: unknown }} */ node
+	) => {
 		const tag = node.nodeName.toLowerCase();
 
 		// It's a valid child, if the tag exists in the schema without an isMatch
 		// function, or with an isMatch function that matches the node.
 		if (
 			schema.hasOwnProperty( tag ) &&
-			( ! schema[ tag ].isMatch || schema[ tag ].isMatch( node ) )
+			( ! schema[ tag ].isMatch || schema[ tag ].isMatch?.( node ) )
 		) {
-			if ( node.nodeType === node.ELEMENT_NODE ) {
+			if ( isElement( node ) ) {
 				const {
 					attributes = [],
 					classes = [],
@@ -64,9 +81,11 @@ export default function cleanNodeList( nodeList, doc, schema, inline ) {
 					if ( node.classList && node.classList.length ) {
 						const mattchers = classes.map( ( item ) => {
 							if ( typeof item === 'string' ) {
-								return ( className ) => className === item;
+								return ( /** @type {string} */ className ) =>
+									className === item;
 							} else if ( item instanceof RegExp ) {
-								return ( className ) => item.test( className );
+								return ( /** @type {string} */ className ) =>
+									item.test( className );
 							}
 
 							return noop;
@@ -113,6 +132,7 @@ export default function cleanNodeList( nodeList, doc, schema, inline ) {
 							// contains children that are block content, unwrap
 							// the node because it is invalid.
 						} else if (
+							node.parentNode &&
 							node.parentNode.nodeName === 'BODY' &&
 							isPhrasingContent( node )
 						) {

packages/dom/src/dom/insert-after.js

@@ -1,11 +1,17 @@
+/**
+ * Internal dependencies
+ */
+import { assertIsDefined } from '../utils/assert-is-defined';
+
 /**
  * Given two DOM nodes, inserts the former in the DOM as the next sibling of
  * the latter.
  *
- * @param {Element} newNode       Node to be inserted.
- * @param {Element} referenceNode Node after which to perform the insertion.
+ * @param {Node} newNode       Node to be inserted.
+ * @param {Node} referenceNode Node after which to perform the insertion.
  * @return {void}
  */
 export default function insertAfter( newNode, referenceNode ) {
+	assertIsDefined( referenceNode.parentNode, 'referenceNode.parentNode' );
 	referenceNode.parentNode.insertBefore( newNode, referenceNode.nextSibling );
 }

packages/dom/src/dom/is-element.js

@@ -0,0 +1,9 @@
+/* eslint-disable jsdoc/valid-types */
+/**
+ * @param {Node | null | undefined} node
+ * @return {node is Element} True if node is an Element node
+ */
+export default function isElement( node ) {
+	/* eslint-enable jsdoc/valid-types */
+	return !! node && node.nodeType === node.ELEMENT_NODE;
+}

packages/dom/src/dom/is-empty.js

@@ -11,15 +11,17 @@ export default function isEmpty( element ) {
 		case element.TEXT_NODE:
 			// We cannot use \s since it includes special spaces which we want
 			// to preserve.
-			return /^[ \f\n\r\t\v\u00a0]*$/.test( element.nodeValue );
+			return /^[ \f\n\r\t\v\u00a0]*$/.test( element.nodeValue || '' );
 		case element.ELEMENT_NODE:
 			if ( element.hasAttributes() ) {
 				return false;
 			} else if ( ! element.hasChildNodes() ) {
 				return true;
 			}
 
-			return Array.from( element.childNodes ).every( isEmpty );
+			return /** @type {Element[]} */ ( Array.from(
+				element.childNodes
+			) ).every( isEmpty );
 		default:
 			return true;
 	}

packages/dom/src/dom/remove.js

@@ -1,9 +1,15 @@
+/**
+ * Internal dependencies
+ */
+import { assertIsDefined } from '../utils/assert-is-defined';
+
 /**
  * Given a DOM node, removes it from the DOM.
  *
- * @param {Element} node Node to be removed.
+ * @param {Node} node Node to be removed.
  * @return {void}
  */
 export default function remove( node ) {
+	assertIsDefined( node.parentNode, 'node.parentNode' );
 	node.parentNode.removeChild( node );
 }

packages/dom/src/dom/unwrap.js

@@ -1,3 +1,8 @@
+/**
+ * Internal dependencies
+ */
+import { assertIsDefined } from '../utils/assert-is-defined';
+
 /**
  * Unwrap the given node. This means any child nodes are moved to the parent.
  *
@@ -8,6 +13,8 @@
 export default function unwrap( node ) {
 	const parent = node.parentNode;
 
+	assertIsDefined( parent, 'node.parentNode' );
+
 	while ( node.firstChild ) {
 		parent.insertBefore( node.firstChild, node );
 	}

packages/dom/tsconfig.json

@@ -7,8 +7,14 @@
 	"include": [
 		"src/data-transfer.js",
 		"src/dom/caret-range-from-point.js",
+		"src/dom/clean-node-list.js",
 		"src/dom/compute-caret-rect.js",
 		"src/dom/get-rectangle-from-range.js",
+		"src/dom/is-empty.js",
+		"src/dom/is-element.js",
+		"src/dom/insert-after.js",
+		"src/dom/remove.js",
+		"src/dom/unwrap.js",
 		"src/utils/**/*",
 		"src/focusable.js",
 		"src/phrasing-content.js",