From 5b2f2030a2cd6835c39812a16bec5a8cc12d6da2 Mon Sep 17 00:00:00 2001 From: Derek Sifford Date: Fri, 28 Jun 2019 12:37:22 -0400 Subject: [PATCH] [@wordpress/dom] add new definitions (#36524) --- types/wordpress__dom/index.d.ts | 172 +++++++++++++++++++ types/wordpress__dom/tsconfig.json | 19 ++ types/wordpress__dom/tslint.json | 1 + types/wordpress__dom/wordpress__dom-tests.ts | 81 +++++++++ 4 files changed, 273 insertions(+) create mode 100644 types/wordpress__dom/index.d.ts create mode 100644 types/wordpress__dom/tsconfig.json create mode 100644 types/wordpress__dom/tslint.json create mode 100644 types/wordpress__dom/wordpress__dom-tests.ts diff --git a/types/wordpress__dom/index.d.ts b/types/wordpress__dom/index.d.ts new file mode 100644 index 0000000000..bc6ed2d0f5 --- /dev/null +++ b/types/wordpress__dom/index.d.ts @@ -0,0 +1,172 @@ +// Type definitions for @wordpress/dom 2.3 +// Project: https://github.com/WordPress/gutenberg/tree/master/packages/dom/README.md +// Definitions by: Derek Sifford +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 3.5 + +export interface Focusable { + find(context: ParentNode): Element[]; +} + +export interface Tabbable extends Focusable { + /** + * Returns `true` if the specified element is tabbable, or `false` otherwise. + * + * @param element - Element to test. + */ + isTabbableIndex(element: Element): boolean; +} + +/** + * Object grouping `focusable` and `tabbable` utils under the keys with the + * same name. + */ +export const focus: { + focusable: Focusable; + tabbable: Tabbable; +}; + +/** + * Get the rectangle for the selection in a container. + */ +export function computeCaretRect(): DOMRect | undefined; + +/** + * Check wether the current document has a selection. This checks both for + * focus in an input field and general text selection. + */ +export function documentHasSelection(): boolean; + +/** + * Returns the closest positioned element, or `null` under any of the conditions + * of the `offsetParent` specification. Unlike `offsetParent`, this function is not + * limited to `HTMLElement` and accepts any `Node` (e.g. `Node.TEXT_NODE`). + * + * See: https://drafts.csswg.org/cssom-view/#dom-htmlelement-offsetparent + * + * @param node - Node from which to find offset parent. + */ +export function getOffsetParent(node: Node): Element | null; + +/** + * Get the rectangle of a given Range. + * + * @param range - The range. + */ +export function getRectangleFromRange(range: Range): DOMRect; + +/** + * Given a DOM element, finds the closest scrollable container element. + * + * @param element - Element from which to start. + * + * @returns Scrollable container node, if found. + */ +export function getScrollContainer(element: Element): Element | undefined; + +/** + * Given two DOM nodes, inserts the former in the DOM as the next sibling of + * the latter. + * + * @param newNode - Node to be inserted. + * @param referenceNode - Node after which to perform the insertion. + */ +export function insertAfter(newNode: Node, referenceNode: Node): void; + +/** + * Check whether the contents of the element have been entirely selected. + * Returns true if there is no possibility of selection. + * + * @param element - The element to check. + * + * @returns `true` if entirely selected, `false` if not. + */ +export function isEntirelySelected(element: HTMLElement): boolean; + +/** + * Check whether the selection is horizontally at the edge of the container. + * + * @param container - Focusable element. + * @param isReverse - Set to `true` to check left, `false` for right. + * + * @returns `true` if at the horizontal edge, `false` if not. + */ +export function isHorizontalEdge(container: HTMLElement, isReverse: boolean): boolean; + +/** + * Check whether the given element is a text field, where text field is defined + * by the ability to select within the input, or that it is contenteditable. + * + * See: https://html.spec.whatwg.org/#textFieldSelection + * + * @param element - The HTML element. + * + * @returns `true` if the element is an text field, `false` if not. + */ +export function isTextField(element: HTMLElement): boolean; + +/** + * Check whether the selection is vertically at the edge of the container. + * + * @param container - Focusable element. + * @param isReverse - Set to `true` to check top, `false` for bottom. + * + * @returns `true` if at the vertical edge, `false` if not. + */ +export function isVerticalEdge(container: HTMLElement, isReverse: boolean): boolean; + +/** + * Places the caret at start or end of a given element. + * + * @param container - Focusable element. + * @param isReverse - `true` for end, `false` for start. + */ +export function placeCaretAtHorizontalEdge(container: HTMLElement | undefined, isReverse: boolean): void; + +/** + * Places the caret at the top or bottom of a given element. + * + * @param container Focusable element. + * @param isReverse `true` for bottom, `false` for top. + * @param [rect] The rectangle to position the caret with. + * @param [mayUseScroll=true] `true` to allow scrolling, `false` to disallow. + */ +export function placeCaretAtVerticalEdge(container: HTMLElement | undefined, isReverse: boolean, rect?: DOMRect, mayUseScroll?: boolean): void; + +/** + * Given a DOM node, removes it from the DOM. + * + * @param node - Node to be removed. + */ +export function remove(node: Node): void; + +/** + * Given two DOM nodes, replaces the former with the latter in the DOM. + * + * @param processedNode - Node to be removed. + * @param newNode - Node to be inserted in its place. + */ +export function replace(processedNode: Node, newNode: Node): void; + +/** + * Replaces the given node with a new node with the given tag name. + * + * @param node - The node to replace. + * @param tagName - The new tag name. + */ +export function replaceTag(node: Node, tagName: T): HTMLElementTagNameMap[T]; + +/** + * Unwrap the given node. This means any child nodes are moved to the parent. + * + * @param node - The node to unwrap. + */ +export function unwrap(node: Node): void; + +/** + * Wraps the given node with a new node with the given tag name. + * + * @param newNode - The node to insert. + * @param referenceNode - The node to wrap. + */ +export function wrap(newNode: Node, referenceNode: Node): void; diff --git a/types/wordpress__dom/tsconfig.json b/types/wordpress__dom/tsconfig.json new file mode 100644 index 0000000000..f5b44ac1b5 --- /dev/null +++ b/types/wordpress__dom/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": ["dom", "es6"], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": ["../"], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true, + "paths": { + "@wordpress/dom": ["wordpress__dom"] + } + }, + "files": ["index.d.ts", "wordpress__dom-tests.ts"] +} diff --git a/types/wordpress__dom/tslint.json b/types/wordpress__dom/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/wordpress__dom/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" } diff --git a/types/wordpress__dom/wordpress__dom-tests.ts b/types/wordpress__dom/wordpress__dom-tests.ts new file mode 100644 index 0000000000..419b1562d3 --- /dev/null +++ b/types/wordpress__dom/wordpress__dom-tests.ts @@ -0,0 +1,81 @@ +import * as dom from '@wordpress/dom'; + +// $ExpectType HTMLDivElement +const element = document.createElement('div'); + +// $ExpectType Node +const node = element.previousSibling!; + +// $ExpectType Range +const range = document.createRange(); + +// -------------- + +// $ExpectType DOMRect | undefined +dom.computeCaretRect(); + +// $ExpectType boolean +dom.documentHasSelection(); + +// $ExpectType Element[] +dom.focus.focusable.find(element); + +// $ExpectType Element[] +dom.focus.tabbable.find(element); + +// $ExpectType boolean +dom.focus.tabbable.isTabbableIndex(element); + +// $ExpectType Element | null +dom.getOffsetParent(node); + +// $ExpectType DOMRect +dom.getRectangleFromRange(range); + +// $ExpectType Element | undefined +dom.getScrollContainer(element); + +// $ExpectType void +dom.insertAfter(node, node); + +// $ExpectType boolean +dom.isEntirelySelected(element); + +// $ExpectType boolean +dom.isHorizontalEdge(element, true); + +// $ExpectType boolean +dom.isTextField(element); + +// $ExpectType boolean +dom.isVerticalEdge(element, false); + +// $ExpectType void +dom.placeCaretAtHorizontalEdge(element, true); + +// $ExpectType void +dom.placeCaretAtHorizontalEdge(undefined, false); + +// $ExpectType void +dom.placeCaretAtVerticalEdge(element, true); + +// $ExpectType void +dom.placeCaretAtVerticalEdge(undefined, false); + +// $ExpectType void +dom.remove(node); + +// $ExpectType void +dom.replace(node, node); + +// $ExpectType HTMLParagraphElement +dom.replaceTag(node, 'p'); + +// $ExpectType HTMLSpanElement +dom.replaceTag(node, 'span'); + +// $ExpectType void +dom.unwrap(node); + +// $ExpectType void +dom.wrap(node, node);