Block Editor: Add type-checking for block editor (DOM utils only)

packages/block-editor/src/utils/dom.js

@@ -5,12 +5,20 @@
  *
  * @param {string} clientId Block client ID.
  *
- * @return {Element} Block DOM node.
+ * @return {Element?} Block DOM node.
  */
 export function getBlockDOMNode( clientId ) {
 	return document.getElementById( 'block-' + clientId );
 }
 
+/**
+ * Returns the preview container DOM node for a given block client ID, or
+ * undefined if the container cannot be determined.
+ *
+ * @param {string} clientId Block client ID.
+ *
+ * @return {Node|undefined} Preview container DOM node.
+ */
 export function getBlockPreviewContainerDOMNode( clientId ) {
 	const domNode = getBlockDOMNode( clientId );
 
@@ -22,10 +30,10 @@ export function getBlockPreviewContainerDOMNode( clientId ) {
 }
 
 /**
- * Returns true if the given HTMLElement is a block focus stop. Blocks without
- * their own text fields rely on the focus stop to be keyboard navigable.
+ * Returns true if the given element is a block focus stop. Blocks without their
+ * own text fields rely on the focus stop to be keyboard navigable.
  *
- * @param {HTMLElement} element Element to test.
+ * @param {Element} element Element to test.
  *
  * @return {boolean} Whether element is a block focus stop.
  */
@@ -36,8 +44,8 @@ export function isBlockFocusStop( element ) {
 /**
  * Returns true if two elements are contained within the same block.
  *
- * @param {HTMLElement} a First element.
- * @param {HTMLElement} b Second element.
+ * @param {Element} a First element.
+ * @param {Element} b Second element.
  *
  * @return {boolean} Whether elements are in the same block.
  */
@@ -49,23 +57,25 @@ export function isInSameBlock( a, b ) {
 }
 
 /**
- * Returns true if an elements is considered part of the block and not its children.
+ * Returns true if an element is considered part of the block and not its
+ * children.
  *
- * @param {HTMLElement} blockElement Block container element.
- * @param {HTMLElement} element      Element.
+ * @param {Element} blockElement Block container element.
+ * @param {Element} element      Element.
  *
- * @return {boolean} Whether element is in the block Element but not its children.
+ * @return {boolean} Whether element is in the block Element but not its
+ *                   children.
  */
 export function isInsideRootBlock( blockElement, element ) {
 	const parentBlock = element.closest( '.block-editor-block-list__block' );
 	return parentBlock === blockElement;
 }
 
 /**
- * Returns true if the given HTMLElement contains inner blocks (an InnerBlocks
+ * Returns true if the given element contains inner blocks (an InnerBlocks
  * element).
  *
- * @param {HTMLElement} element Element to test.
+ * @param {Element} element Element to test.
  *
  * @return {boolean} Whether element contains inner blocks.
  */
@@ -79,16 +89,22 @@ export function hasInnerBlocksContext( element ) {
 /**
  * Finds the block client ID given any DOM node inside the block.
  *
- * @param {Node} node DOM node.
+ * @param {Node?} node DOM node.
  *
- * @return {string|undefined} Client ID or undefined if the node is not part of a block.
+ * @return {string|undefined} Client ID or undefined if the node is not part of
+ *                            a block.
  */
 export function getBlockClientId( node ) {
-	if ( node.nodeType !== node.ELEMENT_NODE ) {
-		node = node.parentElement;
+	while ( node && node.nodeType !== window.Node.ELEMENT_NODE ) {
+		node = node.parentNode;
+	}
+
+	if ( ! node ) {
+		return;
 	}
 
-	const blockNode = node.closest( '.block-editor-block-list__block' );
+	const elementNode = /** @type {Element} */ ( node );
+	const blockNode = elementNode.closest( '.block-editor-block-list__block' );
 
 	if ( ! blockNode ) {
 		return;

packages/block-editor/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"declarationDir": "build-types"
+	},
+	// NOTE: This package is being progressively typed. You are encouraged to
+	// expand this array with files which can be type-checked. At some point in
+	// the future, this can be simplified to an `includes` of `src/**/*`.
+	"files": [
+		"src/utils/dom.js"
+	]
+}

tsconfig.json

@@ -4,6 +4,7 @@
 		{ "path": "packages/a11y" },
 		{ "path": "packages/autop" },
 		{ "path": "packages/blob" },
+		{ "path": "packages/block-editor" },
 		{ "path": "packages/dom-ready" },
 		{ "path": "packages/escape-html" },
 		{ "path": "packages/html-entities" },