@wordpress/dom 4.57.0 → 5.1.0

package/src/dom/{remove-invalid-html.js → remove-invalid-html.ts}

@@ -1,15 +1,20 @@
 import cleanNodeList from './clean-node-list';
+import type { Schema } from './types';
 
 /**
  * Given a schema, unwraps or removes nodes, attributes and classes on HTML.
  *
- * @param {string}                             HTML   The HTML to clean up.
- * @param {import('./clean-node-list').Schema} schema Schema for the HTML.
- * @param {boolean}                            inline Whether to clean for inline mode.
+ * @param {string}  HTML     The HTML to clean up.
+ * @param {Schema}  schema   Schema for the HTML.
+ * @param {boolean} [inline] Whether to clean for inline mode.
  *
  * @return {string} The cleaned up HTML.
  */
-export default function removeInvalidHTML( HTML, schema, inline ) {
+export default function removeInvalidHTML(
+	HTML: string,
+	schema: Schema,
+	inline?: boolean
+): string {
 	const doc = document.implementation.createHTMLDocument( '' );
 
 	doc.body.innerHTML = HTML;

package/src/dom/{remove.js → remove.ts}

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

package/src/dom/{replace-tag.js → replace-tag.ts}

@@ -3,12 +3,12 @@ import { assertIsDefined } from '../utils/assert-is-defined';
 /**
  * Replaces the given node with a new node with the given tag name.
  *
- * @param {Element} node    The node to replace
- * @param {string}  tagName The new tag name.
+ * @param node    The node to replace
+ * @param tagName The new tag name.
  *
- * @return {Element} The new node.
+ * @return The new node.
  */
-export default function replaceTag( node, tagName ) {
+export default function replaceTag( node: Element, tagName: string ): Element {
 	const newNode = node.ownerDocument.createElement( tagName );
 
 	while ( node.firstChild ) {

package/src/dom/{replace.js → replace.ts}

@@ -5,11 +5,13 @@ import remove from './remove';
 /**
  * Given two DOM nodes, replaces the former with the latter in the DOM.
  *
- * @param {Element} processedNode Node to be removed.
- * @param {Element} newNode       Node to be inserted in its place.
- * @return {void}
+ * @param processedNode Node to be removed.
+ * @param newNode       Node to be inserted in its place.
  */
-export default function replace( processedNode, newNode ) {
+export default function replace(
+	processedNode: Element,
+	newNode: Element
+): void {
 	assertIsDefined( processedNode.parentNode, 'processedNode.parentNode' );
 	insertAfter( newNode, processedNode.parentNode );
 	remove( processedNode );

package/src/dom/{safe-html.js → safe-html.ts}

@@ -3,11 +3,11 @@ import remove from './remove';
 /**
  * Strips scripts and on* attributes from HTML.
  *
- * @param {string} html HTML to sanitize.
+ * @param html HTML to sanitize.
  *
- * @return {string} The sanitized HTML.
+ * @return The sanitized HTML.
  */
-export default function safeHTML( html ) {
+export default function safeHTML( html: string ): string {
 	const { body } = document.implementation.createHTMLDocument( '' );
 	body.innerHTML = html;
 	const elements = body.getElementsByTagName( '*' );

package/src/dom/{scroll-if-no-range.js → scroll-if-no-range.ts}

@@ -2,13 +2,17 @@
  * If no range range can be created or it is outside the container, the element
  * may be out of view, so scroll it into view and try again.
  *
- * @param {HTMLElement} container  The container to scroll.
- * @param {boolean}     alignToTop True to align to top, false to bottom.
- * @param {Function}    callback   The callback to create the range.
+ * @param container  The container to scroll.
+ * @param alignToTop True to align to top, false to bottom.
+ * @param callback   The callback to create the range.
  *
- * @return {?Range} The range returned by the callback.
+ * @return The range returned by the callback.
  */
-export function scrollIfNoRange( container, alignToTop, callback ) {
+export function scrollIfNoRange(
+	container: HTMLElement,
+	alignToTop: boolean,
+	callback: () => Range | null
+): Range | null {
 	let range = callback();
 
 	// If no range range can be created or it is outside the container, the

package/src/dom/{strip-html.js → strip-html.ts}

@@ -3,11 +3,11 @@ import safeHTML from './safe-html';
 /**
  * Removes any HTML tags from the provided string.
  *
- * @param {string} html The string containing html.
+ * @param html The string containing html.
  *
- * @return {string} The text content with any html removed.
+ * @return The text content with any html removed.
  */
-export default function stripHTML( html ) {
+export default function stripHTML( html: string ): string {
 	// Remove any script tags or on* attributes otherwise their *contents* will be left
 	// in place following removal of HTML tags.
 	html = safeHTML( html );

package/src/dom/test/{get-rectangle-from-range.browser.test.js → get-rectangle-from-range.browser.test.ts}

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import getRectangleFromRange from '../get-rectangle-from-range';
 
 describe( 'getRectangleFromRange', () => {
-	let container;
+	let container: HTMLDivElement;
 
 	beforeEach( () => {
 		container = document.createElement( 'div' );
@@ -13,7 +13,7 @@ describe( 'getRectangleFromRange', () => {
 		container.remove();
 	} );
 
-	function collapsedRange( node, offset ) {
+	function collapsedRange( node: Node, offset: number ) {
 		const range = document.createRange();
 		range.setStart( node, offset );
 		range.collapse( true );
@@ -21,26 +21,26 @@ describe( 'getRectangleFromRange', () => {
 	}
 
 	// The caret rectangle the browser gives for a position in a text node.
-	function caretBox( node, offset ) {
+	function caretBox( node: Node, offset: number ) {
 		return collapsedRange( node, offset ).getClientRects()[ 0 ].toJSON();
 	}
 
-	function box( rect ) {
-		return rect.toJSON();
+	function box( rect: DOMRect | null ) {
+		return rect!.toJSON();
 	}
 
 	it( 'measures a position after the last child of an element at the end of its text', () => {
 		container.innerHTML = '<div>wordpress.org</div>';
-		const element = container.firstChild;
+		const element = container.firstChild as HTMLDivElement;
 		const range = collapsedRange( element, 1 );
-		const mutations = [];
+		const mutations: MutationRecord[] = [];
 		new window.MutationObserver( ( records ) =>
 			mutations.push( ...records )
 		).observe( element, { childList: true, subtree: true } );
 
 		expect( range.getClientRects() ).toHaveLength( 0 );
 		expect( box( getRectangleFromRange( range ) ) ).toEqual(
-			caretBox( element.firstChild, 13 )
+			caretBox( element.firstChild!, 13 )
 		);
 		expect( range.startContainer ).toBe( element );
 		return Promise.resolve().then( () => {
@@ -50,20 +50,20 @@ describe( 'getRectangleFromRange', () => {
 
 	it( 'measures a position before the first child of an element at the start of its text', () => {
 		container.innerHTML = '<div><em>abc</em>def</div>';
-		const element = container.firstChild;
+		const element = container.firstChild as HTMLDivElement;
 
 		expect(
 			box( getRectangleFromRange( collapsedRange( element, 0 ) ) )
-		).toEqual( caretBox( element.querySelector( 'em' ).firstChild, 0 ) );
+		).toEqual( caretBox( element.querySelector( 'em' )!.firstChild!, 0 ) );
 	} );
 
 	it( 'measures a position after a line break at the start of the next line', () => {
 		container.innerHTML = '<p>abc<br>def</p>';
-		const paragraph = container.firstChild;
-		const nextLine = caretBox( paragraph.lastChild, 0 );
+		const paragraph = container.firstChild as HTMLParagraphElement;
+		const nextLine = caretBox( paragraph.lastChild!, 0 );
 
 		expect( nextLine.top ).toBeGreaterThan(
-			caretBox( paragraph.firstChild, 3 ).top
+			caretBox( paragraph.firstChild!, 3 ).top
 		);
 		expect(
 			box( getRectangleFromRange( collapsedRange( paragraph, 2 ) ) )
@@ -73,11 +73,11 @@ describe( 'getRectangleFromRange', () => {
 	it( 'returns null for a position between texts on different lines', () => {
 		container.innerHTML =
 			'<p style="width: 3ch; font-family: monospace; overflow-wrap: anywhere;">abc<em>def</em></p>';
-		const paragraph = container.firstChild;
+		const paragraph = container.firstChild as HTMLParagraphElement;
 
 		expect(
-			caretBox( paragraph.lastChild.firstChild, 0 ).top
-		).toBeGreaterThan( caretBox( paragraph.firstChild, 3 ).top );
+			caretBox( paragraph.lastChild!.firstChild!, 0 ).top
+		).toBeGreaterThan( caretBox( paragraph.firstChild!, 3 ).top );
 		expect(
 			getRectangleFromRange( collapsedRange( paragraph, 1 ) )
 		).toBeNull();
@@ -85,40 +85,40 @@ describe( 'getRectangleFromRange', () => {
 
 	it( 'measures a position between texts on the same line', () => {
 		container.innerHTML = '<p>abc<em>def</em></p>';
-		const paragraph = container.firstChild;
+		const paragraph = container.firstChild as HTMLParagraphElement;
 
 		expect(
 			box( getRectangleFromRange( collapsedRange( paragraph, 1 ) ) )
-		).toEqual( caretBox( paragraph.lastChild.firstChild, 0 ) );
+		).toEqual( caretBox( paragraph.lastChild!.firstChild!, 0 ) );
 	} );
 
 	it( 'measures a position inside an empty inline element beside the text next to it', () => {
 		container.innerHTML =
 			'<p><span data-rich-text-placeholder="Type"></span></p>';
-		const paragraph = container.firstChild;
-		const placeholder = paragraph.querySelector( 'span' );
+		const paragraph = container.firstChild as HTMLParagraphElement;
+		const placeholder = paragraph.querySelector( 'span' )!;
 
 		expect(
 			box( getRectangleFromRange( collapsedRange( placeholder, 0 ) ) )
-		).toEqual( caretBox( paragraph.firstChild, 1 ) );
+		).toEqual( caretBox( paragraph.firstChild!, 1 ) );
 	} );
 
 	it( 'measures a position inside a line break at the end of the text before it', () => {
 		container.innerHTML = '<p>abc<br>def</p>';
-		const paragraph = container.firstChild;
+		const paragraph = container.firstChild as HTMLParagraphElement;
 
 		expect(
 			box(
 				getRectangleFromRange(
-					collapsedRange( paragraph.querySelector( 'br' ), 0 )
+					collapsedRange( paragraph.querySelector( 'br' )!, 0 )
 				)
 			)
-		).toEqual( caretBox( paragraph.firstChild, 3 ) );
+		).toEqual( caretBox( paragraph.firstChild!, 3 ) );
 	} );
 
 	it( 'returns null for a position with no text on either side', () => {
 		container.innerHTML = '<p><br></p>';
-		const paragraph = container.firstChild;
+		const paragraph = container.firstChild as HTMLParagraphElement;
 
 		expect(
 			getRectangleFromRange( collapsedRange( paragraph, 1 ) )

package/src/dom/types.ts

@@ -0,0 +1,28 @@
+export interface SchemaItem {
+	/**
+	 * Attributes.
+	 */
+	attributes?: string[];
+	/**
+	 * Classnames or RegExp to test against. Use '*' to keep all classes.
+	 */
+	classes?: ( string | RegExp )[];
+	/**
+	 * Child schemas.
+	 */
+	children?: '*' | { [ tag: string ]: SchemaItem };
+	/**
+	 * Selectors to test required children against. Leave empty or undefined if there are no requirements.
+	 */
+	require?: string[];
+	/**
+	 * Whether to allow nodes without children.
+	 */
+	allowEmpty?: boolean;
+	/**
+	 * Function to test whether a node is a match. If left undefined any node will be assumed to match.
+	 */
+	isMatch?: ( node: Node ) => boolean;
+}
+
+export type Schema = { [ tag: string ]: SchemaItem };

package/src/dom/{unwrap.js → unwrap.ts}

@@ -3,11 +3,9 @@ import { assertIsDefined } from '../utils/assert-is-defined';
 /**
  * Unwrap the given node. This means any child nodes are moved to the parent.
  *
- * @param {Node} node The node to unwrap.
- *
- * @return {void}
+ * @param node The node to unwrap.
  */
-export default function unwrap( node ) {
+export default function unwrap( node: Node ): void {
 	const parent = node.parentNode;
 
 	assertIsDefined( parent, 'node.parentNode' );

package/src/dom/{wrap.js → wrap.ts}

@@ -3,10 +3,10 @@ import { assertIsDefined } from '../utils/assert-is-defined';
 /**
  * Wraps the given node with a new node with the given tag name.
  *
- * @param {Element} newNode       The node to insert.
- * @param {Element} referenceNode The node to wrap.
+ * @param newNode       The node to insert.
+ * @param referenceNode The node to wrap.
  */
-export default function wrap( newNode, referenceNode ) {
+export default function wrap( newNode: Element, referenceNode: Element ) {
 	assertIsDefined( referenceNode.parentNode, 'referenceNode.parentNode' );
 	referenceNode.parentNode.insertBefore( newNode, referenceNode );
 	newNode.appendChild( referenceNode );

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

@@ -1,3 +1,5 @@
+import type { FindFocusableOptions } from './types';
+
 /**
  * References:
  *
@@ -20,15 +22,15 @@
 /**
  * Returns a CSS selector used to query for focusable elements.
  *
- * @param {boolean} sequential If set, only query elements that are sequentially
- *                             focusable. Non-interactive elements with a
- *                             negative `tabindex` are focusable but not
- *                             sequentially focusable.
- *                             https://html.spec.whatwg.org/multipage/interaction.html#the-tabindex-attribute
+ * @param sequential If set, only query elements that are sequentially
+ *                   focusable. Non-interactive elements with a
+ *                   negative `tabindex` are focusable but not
+ *                   sequentially focusable.
+ *                   https://html.spec.whatwg.org/multipage/interaction.html#the-tabindex-attribute
  *
- * @return {string} CSS selector.
+ * @return CSS selector.
  */
-function buildSelector( sequential ) {
+function buildSelector( sequential: boolean ): string {
 	return [
 		sequential ? '[tabindex]:not([tabindex^="-"])' : '[tabindex]',
 		'a[href]',
@@ -49,11 +51,11 @@ function buildSelector( sequential ) {
  * Returns true if the specified element has a layout box and is not hidden by
  * CSS visibility or content visibility.
  *
- * @param {HTMLElement} element DOM element to test.
+ * @param element DOM element to test.
  *
- * @return {boolean} Whether element is visible.
+ * @return Whether element is visible.
  */
-function isVisible( element ) {
+function isVisible( element: HTMLElement ): boolean {
 	if ( typeof element.checkVisibility === 'function' ) {
 		if ( ! element.checkVisibility( { visibilityProperty: true } ) ) {
 			return false;
@@ -80,19 +82,17 @@ function isVisible( element ) {
  * false otherwise. Area is only focusable if within a map where a named map
  * referenced by an image somewhere in the document.
  *
- * @param {HTMLAreaElement} element DOM area element to test.
+ * @param element DOM area element to test.
  *
- * @return {boolean} Whether area element is valid for focus.
+ * @return Whether area element is valid for focus.
  */
-function isValidFocusableArea( element ) {
-	/** @type {HTMLMapElement | null} */
-	const map = element.closest( 'map[name]' );
+function isValidFocusableArea( element: HTMLAreaElement ): boolean {
+	const map: HTMLMapElement | null = element.closest( 'map[name]' );
 	if ( ! map ) {
 		return false;
 	}
 
-	/** @type {HTMLImageElement | null} */
-	const img = element.ownerDocument.querySelector(
+	const img: HTMLImageElement | null = element.ownerDocument.querySelector(
 		'img[usemap="#' + map.name + '"]'
 	);
 	return !! img && ! img.closest( '[inert]' ) && isVisible( img );
@@ -101,28 +101,30 @@ function isValidFocusableArea( element ) {
 /**
  * Returns all focusable elements within a given context.
  *
- * @param {Element} context              Element in which to search.
- * @param {Object}  options
- * @param {boolean} [options.sequential] If set, only return elements that are
- *                                       sequentially focusable.
- *                                       Non-interactive elements with a
- *                                       negative `tabindex` are focusable but
- *                                       not sequentially focusable.
- *                                       https://html.spec.whatwg.org/multipage/interaction.html#the-tabindex-attribute
+ * @param context              Element in which to search.
+ * @param options
+ * @param [options.sequential] If set, only return elements that are
+ *                             sequentially focusable.
+ *                             Non-interactive elements with a
+ *                             negative `tabindex` are focusable but
+ *                             not sequentially focusable.
+ *                             https://html.spec.whatwg.org/multipage/interaction.html#the-tabindex-attribute
  *
- * @return {HTMLElement[]} Focusable elements.
+ * @return Focusable elements.
  */
-export function find( context, { sequential = false } = {} ) {
-	/** @type {NodeListOf<HTMLElement>} */
-	const elements = context.querySelectorAll( buildSelector( sequential ) );
+export function find(
+	context: Element,
+	{ sequential = false }: FindFocusableOptions = {}
+): HTMLElement[] {
+	const elements: NodeListOf< HTMLElement > = context.querySelectorAll(
+		buildSelector( sequential )
+	);
 
 	return Array.from( elements ).filter( ( element ) => {
 		const { nodeName } = element;
 		if ( 'AREA' === nodeName ) {
 			// The mapped image determines whether this region is visible or inert.
-			return isValidFocusableArea(
-				/** @type {HTMLAreaElement} */ ( element )
-			);
+			return isValidFocusableArea( element as HTMLAreaElement );
 		}
 
 		// Elements inside an inert subtree are not focusable.

package/src/index.ts

@@ -0,0 +1,33 @@
+import * as focusable from './focusable';
+import * as tabbable from './tabbable';
+
+/**
+ * Object grouping `focusable` and `tabbable` utils
+ * under the keys with the same name.
+ */
+export const focus = { focusable, tabbable };
+
+export * from './dom';
+export * from './phrasing-content';
+export * from './data-transfer';
+
+/**
+ * Schema of the content allowed inside an element, keyed by tag name.
+ */
+export type { ContentSchema } from './types';
+
+/**
+ * The attributes and children allowed for an element in a `ContentSchema`.
+ */
+export type { SemanticElementDefinition } from './types';
+
+/**
+ * Schema that `cleanNodeList` and `removeInvalidHTML` clean HTML against,
+ * keyed by tag name.
+ */
+export type { Schema } from './dom/types';
+
+/**
+ * The rules for a single tag in a `Schema`.
+ */
+export type { SchemaItem } from './dom/types';

package/src/{phrasing-content.js → phrasing-content.ts}

@@ -1,27 +1,17 @@
+import type { ContentSchema } from './types';
+
 /**
  * All phrasing content elements.
  *
  * @see https://www.w3.org/TR/2011/WD-html5-20110525/content-models.html#phrasing-content-0
  */
 
-/**
- * @typedef {Record<string,SemanticElementDefinition>} ContentSchema
- */
-
-/**
- * @typedef SemanticElementDefinition
- * @property {string[]}          [attributes] Content attributes
- * @property {ContentSchema|'*'} [children]   Content attributes
- */
-
 /**
  * All text-level semantic elements.
  *
  * @see https://html.spec.whatwg.org/multipage/text-level-semantics.html
- *
- * @type {ContentSchema}
  */
-const textContentSchema = {
+const textContentSchema: ContentSchema = {
 	strong: {},
 	em: {},
 	s: {},
@@ -60,10 +50,8 @@ const textContentSchema = {
  * Embedded content elements.
  *
  * @see https://www.w3.org/TR/2011/WD-html5-20110525/content-models.html#embedded-content-0
- *
- * @type {ContentSchema}
  */
-const embeddedContentSchema = {
+const embeddedContentSchema: ContentSchema = {
 	audio: {
 		attributes: [
 			'src',
@@ -150,19 +138,16 @@ const phrasingContentSchema = {
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content
  *
- * @param {string} [context] Set to "paste" to exclude invisible elements and
- *                           sensitive data.
+ * @param [context] Set to "paste" to exclude invisible elements and
+ *                  sensitive data.
  *
- * @return {Partial<ContentSchema>} Schema.
+ * @return Schema.
  */
-export function getPhrasingContentSchema( context ) {
+export function getPhrasingContentSchema( context?: string ): ContentSchema {
 	if ( context !== 'paste' ) {
 		return phrasingContentSchema;
 	}
 
-	/**
-	 * @type {Partial<ContentSchema>}
-	 */
 	const {
 		u, // Used to mark misspelling. Shouldn't be pasted.
 		abbr, // Invisible.
@@ -172,7 +157,7 @@ export function getPhrasingContentSchema( context ) {
 		bdi, // Invisible.
 		bdo, // Invisible.
 		...remainingContentSchema
-	} = {
+	}: ContentSchema = {
 		...phrasingContentSchema,
 		// We shouldn't paste potentially sensitive information which is not
 		// visible to the user when pasted, so strip the attributes.
@@ -188,20 +173,20 @@ export function getPhrasingContentSchema( context ) {
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content
  *
- * @param {Node} node The node to test.
+ * @param node The node to test.
  *
- * @return {boolean} True if phrasing content, false if not.
+ * @return True if phrasing content, false if not.
  */
-export function isPhrasingContent( node ) {
+export function isPhrasingContent( node: Node ): boolean {
 	const tag = node.nodeName.toLowerCase();
 	return getPhrasingContentSchema().hasOwnProperty( tag ) || tag === 'span';
 }
 
 /**
- * @param {Node} node
- * @return {boolean} Node is text content
+ * @param node
+ * @return Node is text content
  */
-export function isTextContent( node ) {
+export function isTextContent( node: Node ): boolean {
 	const tag = node.nodeName.toLowerCase();
 	return textContentSchema.hasOwnProperty( tag ) || tag === 'span';
 }