@wordpress/dom 4.57.0 → 5.1.0

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

@@ -1,3 +1,4 @@
+import type { MaybeHTMLInputElement, ObjectTabbable } from './types';
 import { find as findFocusable } from './focusable';
 
 /**
@@ -8,11 +9,11 @@ import { find as findFocusable } from './focusable';
  *
  * @see https://bugzilla.mozilla.org/show_bug.cgi?id=1190261
  *
- * @param {Element} element Element from which to retrieve.
+ * @param element Element from which to retrieve.
  *
- * @return {number} Tab index of element (default 0).
+ * @return Tab index of element (default 0).
  */
-function getTabIndex( element ) {
+function getTabIndex( element: Element ): number {
 	const tabIndex = element.getAttribute( 'tabindex' );
 	return tabIndex === null ? 0 : parseInt( tabIndex, 10 );
 }
@@ -20,31 +21,31 @@ function getTabIndex( element ) {
 /**
  * Returns true if the specified element is tabbable, or false otherwise.
  *
- * @param {Element} element Element to test.
+ * @param element Element to test.
  *
- * @return {boolean} Whether element is tabbable.
+ * @return Whether element is tabbable.
  */
-export function isTabbableIndex( element ) {
+export function isTabbableIndex( element: Element ): boolean {
 	return getTabIndex( element ) !== -1;
 }
 
-/** @typedef {HTMLElement & { type?: string, checked?: boolean, name?: string }} MaybeHTMLInputElement */
-
 /**
  * Returns a stateful reducer function which constructs a filtered array of
  * tabbable elements, where at most one radio input is selected for a given
  * name, giving priority to checked input, falling back to the first
  * encountered.
  *
- * @return {(acc: MaybeHTMLInputElement[], el: MaybeHTMLInputElement) => MaybeHTMLInputElement[]} Radio group collapse reducer.
+ * @return Radio group collapse reducer.
  */
-function createStatefulCollapseRadioGroup() {
-	/** @type {Record<string, MaybeHTMLInputElement>} */
-	const CHOSEN_RADIO_BY_NAME = {};
+function createStatefulCollapseRadioGroup(): (
+	acc: MaybeHTMLInputElement[],
+	el: MaybeHTMLInputElement
+) => MaybeHTMLInputElement[] {
+	const CHOSEN_RADIO_BY_NAME: Record< string, MaybeHTMLInputElement > = {};
 
 	return function collapseRadioGroup(
-		/** @type {MaybeHTMLInputElement[]} */ result,
-		/** @type {MaybeHTMLInputElement} */ element
+		result: MaybeHTMLInputElement[],
+		element: MaybeHTMLInputElement
 	) {
 		const { nodeName, type, checked, name } = element;
 
@@ -81,12 +82,15 @@ function createStatefulCollapseRadioGroup() {
  * sort where equal tabIndex should be left in order of their occurrence in the
  * document.
  *
- * @param {HTMLElement} element Element.
- * @param {number}      index   Array index of element.
+ * @param element Element.
+ * @param index   Array index of element.
  *
- * @return {{ element: HTMLElement, index: number }} Mapped object with element, index.
+ * @return Mapped object with element, index.
  */
-function mapElementToObjectTabbable( element, index ) {
+function mapElementToObjectTabbable(
+	element: HTMLElement,
+	index: number
+): ObjectTabbable {
 	return { element, index };
 }
 
@@ -94,11 +98,13 @@ function mapElementToObjectTabbable( element, index ) {
  * An array map callback, returning an element of the given mapped object's
  * element value.
  *
- * @param {{ element: HTMLElement }} object Mapped object with element.
+ * @param object Mapped object with element.
  *
- * @return {HTMLElement} Mapped object element.
+ * @return Mapped object element.
  */
-function mapObjectTabbableToElement( object ) {
+function mapObjectTabbableToElement(
+	object: Pick< ObjectTabbable, 'element' >
+): HTMLElement {
 	return object.element;
 }
 
@@ -107,12 +113,15 @@ function mapObjectTabbableToElement( object ) {
  *
  * @see mapElementToObjectTabbable
  *
- * @param {{ element: HTMLElement, index: number }} a First object to compare.
- * @param {{ element: HTMLElement, index: number }} b Second object to compare.
+ * @param a First object to compare.
+ * @param b Second object to compare.
  *
- * @return {number} Comparator result.
+ * @return Comparator result.
  */
-function compareObjectTabbables( a, b ) {
+function compareObjectTabbables(
+	a: ObjectTabbable,
+	b: ObjectTabbable
+): number {
 	const aTabIndex = getTabIndex( a.element );
 	const bTabIndex = getTabIndex( b.element );
 
@@ -126,11 +135,11 @@ function compareObjectTabbables( a, b ) {
 /**
  * Given focusable elements, filters out tabbable element.
  *
- * @param {HTMLElement[]} focusables Focusable elements to filter.
+ * @param focusables Focusable elements to filter.
  *
- * @return {HTMLElement[]} Tabbable elements.
+ * @return Tabbable elements.
  */
-function filterTabbable( focusables ) {
+function filterTabbable( focusables: HTMLElement[] ): HTMLElement[] {
 	return focusables
 		.filter( isTabbableIndex )
 		.map( mapElementToObjectTabbable )
@@ -140,22 +149,22 @@ function filterTabbable( focusables ) {
 }
 
 /**
- * @param {Element} context
- * @return {HTMLElement[]} Tabbable elements within the context.
+ * @param context
+ * @return Tabbable elements within the context.
  */
-export function find( context ) {
+export function find( context: Element ): HTMLElement[] {
 	return filterTabbable( findFocusable( context ) );
 }
 
 /**
  * Given a focusable element, find the preceding tabbable element.
  *
- * @param {Element} element The focusable element before which to look. Defaults
- *                          to the active element.
+ * @param element The focusable element before which to look. Defaults
+ *                to the active element.
  *
- * @return {HTMLElement|undefined} Preceding tabbable element.
+ * @return Preceding tabbable element.
  */
-export function findPrevious( element ) {
+export function findPrevious( element: Element ): HTMLElement | undefined {
 	return filterTabbable( findFocusable( element.ownerDocument.body ) )
 		.reverse()
 		.find(
@@ -169,12 +178,12 @@ export function findPrevious( element ) {
 /**
  * Given a focusable element, find the next tabbable element.
  *
- * @param {Element} element The focusable element after which to look. Defaults
- *                          to the active element.
+ * @param element The focusable element after which to look. Defaults
+ *                to the active element.
  *
- * @return {HTMLElement|undefined} Next tabbable element.
+ * @return Next tabbable element.
  */
-export function findNext( element ) {
+export function findNext( element: Element ): HTMLElement | undefined {
 	return filterTabbable( findFocusable( element.ownerDocument.body ) ).find(
 		( focusable ) =>
 			// eslint-disable-next-line no-bitwise

package/src/test/{dom.jsdom.test.js → dom.jsdom.test.ts}

@@ -5,11 +5,12 @@ import {
 	isTextField,
 	removeInvalidHTML,
 	isEmpty,
+	getOffsetParent,
 } from '../dom';
 import { getPhrasingContentSchema } from '../phrasing-content';
 
 describe( 'DOM', () => {
-	let parent;
+	let parent: HTMLDivElement;
 
 	beforeEach( () => {
 		parent = document.createElement( 'div' );
@@ -109,9 +110,8 @@ describe( 'DOM', () => {
 		/**
 		 * A sampling of input types expected not to be text eligible.
 		 *
-		 * @type {string[]}
 		 */
-		const NON_TEXT_INPUT_TYPES = [
+		const NON_TEXT_INPUT_TYPES: string[] = [
 			'button',
 			'checkbox',
 			'hidden',
@@ -128,9 +128,13 @@ describe( 'DOM', () => {
 		/**
 		 * A sampling of input types expected to be text eligible.
 		 *
-		 * @type {string[]}
 		 */
-		const TEXT_INPUT_TYPES = [ 'text', 'password', 'search', 'url' ];
+		const TEXT_INPUT_TYPES: string[] = [
+			'text',
+			'password',
+			'search',
+			'url',
+		];
 
 		it( 'should return false for non-text input elements', () => {
 			NON_TEXT_INPUT_TYPES.forEach( ( type ) => {
@@ -170,6 +174,26 @@ describe( 'DOM', () => {
 			);
 		} );
 	} );
+
+	describe( 'getOffsetParent', () => {
+		it( 'should return the closest element when it is positioned', () => {
+			parent.style.position = 'relative';
+			const text = document.createTextNode( 'text' );
+			parent.appendChild( text );
+
+			expect( getOffsetParent( text ) ).toBe( parent );
+		} );
+
+		it( 'should return null when no ancestor is an element', () => {
+			expect( getOffsetParent( document.documentElement ) ).toBe( null );
+
+			const fragment = document.createDocumentFragment();
+			const text = document.createTextNode( 'text' );
+			fragment.appendChild( text );
+
+			expect( getOffsetParent( text ) ).toBe( null );
+		} );
+	} );
 } );
 
 describe( 'removeInvalidHTML', () => {
@@ -304,7 +328,7 @@ describe( 'removeInvalidHTML', () => {
 } );
 
 describe( 'isEmpty', () => {
-	function isEmptyHTML( HTML ) {
+	function isEmptyHTML( HTML: string ) {
 		const doc = document.implementation.createHTMLDocument( '' );
 
 		doc.body.innerHTML = HTML;

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

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { find } from '../focusable';
 
 describe( 'focusable.find() CSS visibility', () => {
-	let node;
+	let node: HTMLDivElement;
 
 	beforeEach( () => {
 		node = document.createElement( 'div' );
@@ -28,7 +28,7 @@ describe( 'focusable.find() CSS visibility', () => {
 		'excludes inputs with %s even when they have layout boxes',
 		( _, html ) => {
 			node.innerHTML = html;
-			const input = node.querySelector( 'input' );
+			const input = node.querySelector( 'input' )!;
 			const checkVisibility = vi.spyOn( input, 'checkVisibility' );
 
 			expect( input.offsetWidth ).toBeGreaterThan( 0 );
@@ -46,7 +46,7 @@ describe( 'focusable.find() CSS visibility', () => {
 	it( 'includes inputs that restore visibility inside a hidden ancestor', () => {
 		node.style.visibility = 'hidden';
 		node.innerHTML = '<input style="visibility: visible">';
-		const input = node.querySelector( 'input' );
+		const input = node.querySelector( 'input' )!;
 
 		input.focus();
 		expect( input ).toHaveFocus();
@@ -56,7 +56,7 @@ describe( 'focusable.find() CSS visibility', () => {
 	it( 'uses the owning window for the computed-style fallback', () => {
 		const iframe = document.createElement( 'iframe' );
 		node.appendChild( iframe );
-		const iframeDocument = iframe.contentDocument;
+		const iframeDocument = iframe.contentDocument!;
 		iframeDocument.body.innerHTML = `
 			<div style="visibility: hidden">
 				<input>
@@ -72,7 +72,7 @@ describe( 'focusable.find() CSS visibility', () => {
 			checkVisibility: { value: undefined },
 		} );
 		const getComputedStyle = vi.spyOn(
-			iframeDocument.defaultView,
+			iframeDocument.defaultView!,
 			'getComputedStyle'
 		);
 
@@ -82,11 +82,12 @@ describe( 'focusable.find() CSS visibility', () => {
 	} );
 } );
 
-const createElement = ( type ) => document.createElement( type );
+const createElement = < K extends keyof HTMLElementTagNameMap >( type: K ) =>
+	document.createElement( type );
 const IMAGE_SOURCE =
 	'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
 
-function findFocusable( context ) {
+function findFocusable( context: Element ) {
 	if ( ! context.isConnected ) {
 		document.body.appendChild( context );
 	}
@@ -125,7 +126,7 @@ describe( 'focusable', () => {
 		it( 'finds nested focusable child', () => {
 			const node = createElement( 'div' );
 			node.appendChild( createElement( 'div' ) );
-			node.firstChild.appendChild( createElement( 'input' ) );
+			node.firstChild!.appendChild( createElement( 'input' ) );
 
 			const focusable = findFocusable( node );
 
@@ -150,8 +151,8 @@ describe( 'focusable', () => {
 				</map>
 				<img src="${ IMAGE_SOURCE }" usemap="#testfocus" width="40" height="40" alt="">
 			`;
-			const area = node.querySelector( 'area' );
-			const image = node.querySelector( 'img' );
+			const area = node.querySelector( 'area' )!;
+			const image = node.querySelector( 'img' )!;
 
 			document.body.appendChild( node );
 			await image.decode();
@@ -171,7 +172,7 @@ describe( 'focusable', () => {
 				</map>
 				<img src="${ IMAGE_SOURCE }" usemap="#testfocus" width="40" height="40" alt="" style="visibility: hidden">
 			`;
-			const image = node.querySelector( 'img' );
+			const image = node.querySelector( 'img' )!;
 
 			document.body.appendChild( node );
 
@@ -203,8 +204,8 @@ describe( 'focusable', () => {
 				</div>
 				<img src="${ IMAGE_SOURCE }" usemap="#testfocus" width="40" height="40" alt="">
 			`;
-			const area = node.querySelector( 'area' );
-			const image = node.querySelector( 'img' );
+			const area = node.querySelector( 'area' )!;
+			const image = node.querySelector( 'img' )!;
 
 			document.body.appendChild( node );
 			await image.decode();

package/src/test/{tabbable.browser.test.js → tabbable.browser.test.ts}

@@ -1,9 +1,10 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import { find } from '../tabbable';
 
-const createElement = ( type ) => document.createElement( type );
+const createElement = < K extends keyof HTMLElementTagNameMap >( type: K ) =>
+	document.createElement( type );
 
-function findTabbable( context ) {
+function findTabbable( context: Element ) {
 	document.body.appendChild( context );
 	return find( context );
 }

package/src/types.ts

@@ -0,0 +1,32 @@
+export interface SemanticElementDefinition {
+	/**
+	 * Content attributes
+	 */
+	attributes?: string[];
+	/**
+	 * Allowed child elements, or `'*'` for any
+	 */
+	children?: ContentSchema | '*';
+}
+
+export type ContentSchema = Record< string, SemanticElementDefinition >;
+
+export interface FindFocusableOptions {
+	/**
+	 * If set, only return elements that are sequentially focusable.
+	 * Non-interactive elements with a negative `tabindex` are focusable but
+	 * not sequentially focusable.
+	 */
+	sequential?: boolean;
+}
+
+export type MaybeHTMLInputElement = HTMLElement & {
+	type?: string;
+	checked?: boolean;
+	name?: string;
+};
+
+export interface ObjectTabbable {
+	element: HTMLElement;
+	index: number;
+}