@wordpress/dom 4.56.0 → 5.0.0

package/src/dom/{is-number-input.js → is-number-input.ts}

@@ -4,11 +4,11 @@ import isHTMLInputElement from './is-html-input-element';
 /**
  * Check whether the given element is an input field of type number.
  *
- * @param {Node} node The HTML node.
+ * @param node The HTML node.
  *
- * @return {node is HTMLInputElement} True if the node is number input.
+ * @return True if the node is number input.
  */
-export default function isNumberInput( node ) {
+export default function isNumberInput( node: Node ): node is HTMLInputElement {
 	deprecated( 'wp.dom.isNumberInput', {
 		since: '6.1',
 		version: '6.5',

package/src/dom/{is-rtl.js → is-rtl.ts}

@@ -3,10 +3,10 @@ import getComputedStyle from './get-computed-style';
 /**
  * Whether the element's text direction is right-to-left.
  *
- * @param {Element} element The element to check.
+ * @param element The element to check.
  *
- * @return {boolean} True if rtl, false if ltr.
+ * @return True if rtl, false if ltr.
  */
-export default function isRTL( element ) {
+export default function isRTL( element: Element ): boolean {
 	return getComputedStyle( element ).direction === 'rtl';
 }

package/src/dom/{is-selection-forward.js → is-selection-forward.ts}

@@ -6,11 +6,11 @@ import { assertIsDefined } from '../utils/assert-is-defined';
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition
  *
- * @param {Selection} selection Selection object to check.
+ * @param selection Selection object to check.
  *
- * @return {boolean} Whether the selection is forward.
+ * @return Whether the selection is forward.
  */
-export default function isSelectionForward( selection ) {
+export default function isSelectionForward( selection: Selection ): boolean {
 	const { anchorNode, focusNode, anchorOffset, focusOffset } = selection;
 
 	assertIsDefined( anchorNode, 'anchorNode' );

package/src/dom/{is-text-field.js → is-text-field.ts}

@@ -6,10 +6,10 @@ import isHTMLInputElement from './is-html-input-element';
  *
  * See: https://html.spec.whatwg.org/#textFieldSelection
  *
- * @param {Node} node The HTML element.
- * @return {node is HTMLElement} True if the element is an text field, false if not.
+ * @param node The HTML element.
+ * @return True if the element is an text field, false if not.
  */
-export default function isTextField( node ) {
+export default function isTextField( node: Node ): node is HTMLElement {
 	const nonTextInputs = [
 		'button',
 		'checkbox',
@@ -29,6 +29,6 @@ export default function isTextField( node ) {
 			node.type &&
 			! nonTextInputs.includes( node.type ) ) ||
 		node.nodeName === 'TEXTAREA' ||
-		/** @type {HTMLElement} */ ( node ).contentEditable === 'true'
+		( node as HTMLElement ).contentEditable === 'true'
 	);
 }

package/src/dom/{is-vertical-edge.js → is-vertical-edge.ts}

@@ -8,6 +8,9 @@ import isEdge from './is-edge';
  *
  * @return {boolean} True if at the vertical edge, false if not.
  */
-export default function isVerticalEdge( container, isReverse ) {
+export default function isVerticalEdge(
+	container: HTMLElement,
+	isReverse: boolean
+): boolean {
 	return isEdge( container, isReverse, true );
 }

package/src/dom/{place-caret-at-edge.js → place-caret-at-edge.ts}

@@ -7,13 +7,17 @@ import { scrollIfNoRange } from './scroll-if-no-range';
 /**
  * Gets the range to place.
  *
- * @param {HTMLElement}      container Focusable element.
- * @param {boolean}          isReverse True for end, false for start.
- * @param {number|undefined} x         X coordinate to vertically position.
+ * @param container Focusable element.
+ * @param isReverse True for end, false for start.
+ * @param x         X coordinate to vertically position.
  *
- * @return {Range|null} The range to place.
+ * @return The range to place.
  */
-function getRange( container, isReverse, x ) {
+function getRange(
+	container: HTMLElement,
+	isReverse: boolean,
+	x: number | undefined
+): Range | null {
 	const { ownerDocument } = container;
 	// In the case of RTL scripts, the horizontal edge is at the opposite side.
 	const isReverseDir = isRTL( container ) ? ! isReverse : isReverse;
@@ -36,11 +40,15 @@ function getRange( container, isReverse, x ) {
 /**
  * Places the caret at start or end of a given element.
  *
- * @param {HTMLElement}      container Focusable element.
- * @param {boolean}          isReverse True for end, false for start.
- * @param {number|undefined} x         X coordinate to vertically position.
+ * @param container Focusable element.
+ * @param isReverse True for end, false for start.
+ * @param x         X coordinate to vertically position.
  */
-export default function placeCaretAtEdge( container, isReverse, x ) {
+export default function placeCaretAtEdge(
+	container: HTMLElement,
+	isReverse: boolean,
+	x: number | undefined
+) {
 	if ( ! container ) {
 		return;
 	}

package/src/dom/{place-caret-at-horizontal-edge.js → place-caret-at-horizontal-edge.ts}

@@ -6,6 +6,9 @@ import placeCaretAtEdge from './place-caret-at-edge';
  * @param {HTMLElement} container Focusable element.
  * @param {boolean}     isReverse True for end, false for start.
  */
-export default function placeCaretAtHorizontalEdge( container, isReverse ) {
+export default function placeCaretAtHorizontalEdge(
+	container: HTMLElement,
+	isReverse: boolean
+) {
 	return placeCaretAtEdge( container, isReverse, undefined );
 }

package/src/dom/{place-caret-at-vertical-edge.js → place-caret-at-vertical-edge.ts}

@@ -7,6 +7,10 @@ import placeCaretAtEdge from './place-caret-at-edge';
  * @param {boolean}     isReverse True for bottom, false for top.
  * @param {DOMRect}     [rect]    The rectangle to position the caret with.
  */
-export default function placeCaretAtVerticalEdge( container, isReverse, rect ) {
+export default function placeCaretAtVerticalEdge(
+	container: HTMLElement,
+	isReverse: boolean,
+	rect?: DOMRect
+) {
 	return placeCaretAtEdge( container, isReverse, rect?.left );
 }

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/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';
 }