dom: set up auto-generated API docs (#14273)

bin/update-readmes.js

@@ -15,7 +15,7 @@ const packages = [
 	//'data',
 	//'date',
 	//'deprecated',
-	//'dom',
+	'dom',
 	//'dom-ready',
 	'e2e-test-utils',
 	//'edit-post',

packages/dom/README.md

@@ -10,4 +10,262 @@ Install the module
 npm install @wordpress/dom --save
 ```
 
+## API
+
+<!-- START TOKEN(Autogenerated API docs) -->
+
+### computeCaretRect
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Get the rectangle for the selection in a container.
+
+**Parameters**
+
+-   **container** `Element`: Editable container.
+
+**Returns**
+
+`?DOMRect`: The rectangle.
+
+### documentHasSelection
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Check wether the current document has a selection.
+This checks both for focus in an input field and general text selection.
+
+**Returns**
+
+`boolean`: True if there is selection, false if not.
+
+### focus
+
+[src/index.js#L11-L11](src/index.js#L11-L11)
+
+Object grouping `focusable` and `tabbable` utils
+under the keys with the same name.
+
+### getOffsetParent
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+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).
+
+**Related**
+
+-   <https://drafts.csswg.org/cssom-view/#dom-htmlelement-offsetparent>
+
+**Parameters**
+
+-   **node** `Node`: Node from which to find offset parent.
+
+**Returns**
+
+`?Node`: Offset parent.
+
+### getRectangleFromRange
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Get the rectangle of a given Range.
+
+**Parameters**
+
+-   **range** `Range`: The range.
+
+**Returns**
+
+`DOMRect`: The rectangle.
+
+### getScrollContainer
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Given a DOM node, finds the closest scrollable container node.
+
+**Parameters**
+
+-   **node** `Element`: Node from which to start.
+
+**Returns**
+
+`?Element`: Scrollable container node, if found.
+
+### insertAfter
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Given two DOM nodes, inserts the former in the DOM as the next sibling of
+the latter.
+
+**Parameters**
+
+-   **newNode** `Element`: Node to be inserted.
+-   **referenceNode** `Element`: Node after which to perform the insertion.
+
+**Returns**
+
+`void`: 
+
+### isEntirelySelected
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Check whether the contents of the element have been entirely selected.
+Returns true if there is no possibility of selection.
+
+**Parameters**
+
+-   **element** `Element`: The element to check.
+
+**Returns**
+
+`boolean`: True if entirely selected, false if not.
+
+### isHorizontalEdge
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Check whether the selection is horizontally at the edge of the container.
+
+**Parameters**
+
+-   **container** `Element`: Focusable element.
+-   **isReverse** `boolean`: Set to true to check left, false for right.
+
+**Returns**
+
+`boolean`: True if at the horizontal edge, false if not.
+
+### isTextField
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+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>
+
+**Parameters**
+
+-   **element** `HTMLElement`: The HTML element.
+
+**Returns**
+
+`boolean`: True if the element is an text field, false if not.
+
+### isVerticalEdge
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Check whether the selection is vertically at the edge of the container.
+
+**Parameters**
+
+-   **container** `Element`: Focusable element.
+-   **isReverse** `boolean`: Set to true to check top, false for bottom.
+
+**Returns**
+
+`boolean`: True if at the edge, false if not.
+
+### placeCaretAtHorizontalEdge
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Places the caret at start or end of a given element.
+
+**Parameters**
+
+-   **container** `Element`: Focusable element.
+-   **isReverse** `boolean`: True for end, false for start.
+
+### placeCaretAtVerticalEdge
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Places the caret at the top or bottom of a given element.
+
+**Parameters**
+
+-   **container** `Element`: Focusable element.
+-   **isReverse** `boolean`: True for bottom, false for top.
+-   **rect** `[DOMRect]`: The rectangle to position the caret with.
+-   **mayUseScroll** `[boolean]`: True to allow scrolling, false to disallow.
+
+### remove
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Given a DOM node, removes it from the DOM.
+
+**Parameters**
+
+-   **node** `Element`: Node to be removed.
+
+**Returns**
+
+`void`: 
+
+### replace
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Given two DOM nodes, replaces the former with the latter in the DOM.
+
+**Parameters**
+
+-   **processedNode** `Element`: Node to be removed.
+-   **newNode** `Element`: Node to be inserted in its place.
+
+**Returns**
+
+`void`: 
+
+### replaceTag
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Replaces the given node with a new node with the given tag name.
+
+**Parameters**
+
+-   **node** `Element`: The node to replace
+-   **tagName** `string`: The new tag name.
+
+**Returns**
+
+`Element`: The new node.
+
+### unwrap
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Unwrap the given node. This means any child nodes are moved to the parent.
+
+**Parameters**
+
+-   **node** `Node`: The node to unwrap.
+
+**Returns**
+
+`void`: 
+
+### wrap
+
+[src/index.js#L13-L13](src/index.js#L13-L13)
+
+Wraps the given node with a new node with the given tag name.
+
+**Parameters**
+
+-   **newNode** `Element`: The node to insert.
+-   **referenceNode** `Element`: The node to wrap.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/dom/src/index.js

@@ -4,6 +4,10 @@
 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';