@wordpress/dom 4.56.0 → 5.0.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

@@ -5,6 +5,7 @@ import {
 	isTextField,
 	removeInvalidHTML,
 	isEmpty,
+	getOffsetParent,
 } from '../dom';
 import { getPhrasingContentSchema } from '../phrasing-content';
 
@@ -170,6 +171,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', () => {

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;
+}

package/CHANGELOG.md

@@ -1,315 +0,0 @@
-<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->
-
-## Unreleased
-
-## 4.56.0 (2026-09-23)
-
-### Bug Fixes
-
--   `getRectangleFromRange`: Measure a collapsed range on an element at the text position next to it instead of inserting a temporary text node under the caret ([#82977](https://github.com/WordPress/gutenberg/pull/82977)).
--   `focusable.find`: Return linked image-map areas when their mapped image is visible and outside an inert subtree ([#82736](https://github.com/WordPress/gutenberg/pull/82736)).
-
-## 4.55.0 (2026-09-10)
-
-### Bug Fixes
-
--   `focusable.find`: Exclude elements hidden by CSS `visibility` or `content-visibility` while preserving explicitly visible descendants ([#82574](https://github.com/WordPress/gutenberg/pull/82574)).
-
-## 4.54.0 (2026-08-26)
-
-### Bug Fixes
-
--   `cleanNodeList`: Unwrap whitespace-only phrasing content elements instead of removing them, so pasting content like `a<em> </em>b` no longer loses the space between words ([#76696](https://github.com/WordPress/gutenberg/pull/76696)).
-
-## 4.53.0 (2026-08-12)
-
-
-## 4.52.0 (2026-07-29)
-
-## 4.51.0 (2026-07-14)
-
-### Bug Fixes
-
--   `placeCaretAtEdge`: only place a caret when the container is itself an editable element, not when it merely inherits content editability from an editing host ancestor ([#79105](https://github.com/WordPress/gutenberg/pull/79105)).
-
-## 4.50.0 (2026-07-01)
-
-## 4.49.0 (2026-06-24)
-
-## 4.48.1 (2026-06-16)
-
-## 4.48.0 (2026-06-10)
-
-## 4.47.0 (2026-05-27)
-
-## 4.46.0 (2026-05-14)
-
-## 4.45.0 (2026-04-29)
-
-## 4.44.0 (2026-04-15)
-
-## 4.43.0 (2026-04-01)
-
-## 4.42.0 (2026-03-18)
-
-## 4.41.0 (2026-03-04)
-
-## 4.40.0 (2026-02-18)
-
-## 4.39.0 (2026-01-29)
-
-## 4.38.0 (2026-01-16)
-
-## 4.36.0 (2025-11-26)
-
-## 4.35.0 (2025-11-12)
-
-## 4.34.0 (2025-10-29)
-
-## 4.33.0 (2025-10-17)
-
-## 4.32.0 (2025-10-01)
-
-## 4.31.0 (2025-09-17)
-
-## 4.30.0 (2025-09-03)
-
-## 4.29.0 (2025-08-20)
-
-## 4.28.0 (2025-08-07)
-
-## 4.27.0 (2025-07-23)
-
-## 4.26.0 (2025-06-25)
-
-## 4.25.0 (2025-06-04)
-
-## 4.24.0 (2025-05-22)
-
-## 4.23.0 (2025-05-07)
-
-## 4.22.0 (2025-04-11)
-
-## 4.21.0 (2025-03-27)
-
-## 4.20.0 (2025-03-13)
-
-## 4.19.0 (2025-02-28)
-
-## 4.18.0 (2025-02-12)
-
-## 4.17.0 (2025-01-29)
-
-## 4.16.0 (2025-01-15)
-
-## 4.15.0 (2025-01-02)
-
-## 4.14.0 (2024-12-11)
-
-## 4.13.0 (2024-11-27)
-
-## 4.12.0 (2024-11-16)
-
-## 4.11.0 (2024-10-30)
-
-## 4.10.0 (2024-10-16)
-
-## 4.9.0 (2024-10-03)
-
-## 4.8.0 (2024-09-19)
-
-## 4.7.0 (2024-09-05)
-
-## 4.6.0 (2024-08-21)
-
-## 4.5.0 (2024-08-07)
-
-## 4.4.0 (2024-07-24)
-
-## 4.3.0 (2024-07-10)
-
-## 4.2.0 (2024-06-26)
-
-## 4.1.0 (2024-06-15)
-
-## 4.0.0 (2024-05-31)
-
-### Breaking Changes
-
--   Increase the minimum required Node.js version to v18.12.0 matching long-term support releases ([#31270](https://github.com/WordPress/gutenberg/pull/61930)). Learn more about [Node.js releases](https://nodejs.org/en/about/previous-releases).
-
-## 3.58.0 (2024-05-16)
-
-## 3.57.0 (2024-05-02)
-
-## 3.56.0 (2024-04-19)
-
-## 3.55.0 (2024-04-03)
-
--   fix return types of `focus.tabbable` methods to be `HTMLElement` instead of `Element`.
-
-## 3.54.0 (2024-03-21)
-
-## 3.53.0 (2024-03-06)
-
-## 3.52.0 (2024-02-21)
-
-## 3.51.0 (2024-02-09)
-
-## 3.50.0 (2024-01-24)
-
-## 3.49.0 (2024-01-10)
-
-## 3.48.0 (2023-12-13)
-
-## 3.47.0 (2023-11-29)
-
-## 3.46.0 (2023-11-16)
-
-## 3.45.0 (2023-11-02)
-
-## 3.44.0 (2023-10-18)
-
-## 3.43.0 (2023-10-05)
-
-## 3.42.0 (2023-09-20)
-
-## 3.41.0 (2023-08-31)
-
-## 3.40.0 (2023-08-16)
-
-## 3.39.0 (2023-08-10)
-
-## 3.38.0 (2023-07-20)
-
-## 3.37.0 (2023-07-05)
-
-## 3.36.0 (2023-06-23)
-
-## 3.35.0 (2023-06-07)
-
-## 3.34.0 (2023-05-24)
-
-## 3.33.0 (2023-05-10)
-
-## 3.32.0 (2023-04-26)
-
-## 3.31.0 (2023-04-12)
-
-## 3.30.0 (2023-03-29)
-
-## 3.29.0 (2023-03-15)
-
-## 3.28.0 (2023-03-01)
-
-## 3.27.0 (2023-02-15)
-
-## 3.26.0 (2023-02-01)
-
-## 3.25.0 (2023-01-11)
-
-## 3.24.0 (2023-01-02)
-
-## 3.23.0 (2022-12-14)
-
-## 3.22.0 (2022-11-16)
-
-## 3.21.0 (2022-11-02)
-
-## 3.20.0 (2022-10-19)
-
-## 3.19.0 (2022-10-05)
-
-## 3.18.0 (2022-09-21)
-
-## 3.17.0 (2022-09-13)
-
-## 3.16.0 (2022-08-24)
-
-## 3.15.0 (2022-08-10)
-
-## 3.14.0 (2022-07-27)
-
--   `getRectangleFromRange` may now return `null`.
-
-## 3.13.0 (2022-07-13)
-
-## 3.12.0 (2022-06-29)
-
-## 3.11.0 (2022-06-15)
-
-## 3.10.0 (2022-06-01)
-
-## 3.9.0 (2022-05-18)
-
-### Deprecations
-
--   Deprecate `isNumberInput`, as it is no longer used internally ([#40896](https://github.com/WordPress/gutenberg/pull/40896)).
-
-## 3.8.0 (2022-05-04)
-
-## 3.7.0 (2022-04-21)
-
-## 3.6.0 (2022-04-08)
-
-## 3.5.0 (2022-03-23)
-
-## 3.4.0 (2022-03-11)
-
-## 3.3.0 (2022-01-27)
-
-## 3.2.0 (2021-07-21)
-
-## 3.1.0 (2021-05-20)
-
-## 3.0.0 (2021-05-14)
-
-### Breaking Changes
-
--   Drop support for Internet Explorer 11 ([#31110](https://github.com/WordPress/gutenberg/pull/31110)). Learn more at https://make.wordpress.org/core/2021/04/22/ie-11-support-phase-out-plan/.
--   Increase the minimum Node.js version to v12 matching Long Term Support releases ([#31270](https://github.com/WordPress/gutenberg/pull/31270)). Learn more at https://nodejs.org/en/about/releases/.
-
-## 2.18.0 (2021-04-29)
-
-### New Features
-
--   Export type definitions.
-
-## 2.17.0 (2021-03-17)
-
-## 2.11.0 (2020-06-15)
-
-### New Features
-
--   Add `documentHasUncollapsedSelection` to inquire about ranges of selected text in the document, including the separately managed selections inside <input> and <textarea> elements.
-
-## 2.10.0 (2020-05-28)
-
-### New Features
-
--   Add `documentHasTextSelection` to inquire specifically about ranges of selected text, in addition to the existing `documentHasSelection`.
-
-## 2.1.0 (2019-03-06)
-
-### Bug Fixes
-
--   Update `isHorizontalEdge` to account for empty text nodes.
--   `tabbables.find` considers at most a single radio input for a given name. The checked input is given priority, falling back to the first in the tabindex-sorted set if there is no checked input.
-
-## 2.0.8 (2019-01-03)
-
-## 2.0.7 (2018-11-20)
-
-## 2.0.6 (2018-11-09)
-
-## 2.0.5 (2018-11-09)
-
-## 2.0.4 (2018-10-19)
-
-## 2.0.3 (2018-10-18)
-
-## 2.0.0 (2018-09-05)
-
-### Breaking Changes
-
--   Change how required built-ins are polyfilled with Babel 7 ([#9171](https://github.com/WordPress/gutenberg/pull/9171)). If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods.

package/src/index.js

@@ -1,12 +0,0 @@
-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';