From e482c26825a3e725dc4ce3c5974538d58734729c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 1 Mar 2019 19:40:37 +0100 Subject: [PATCH 1/3] Autogenerated docs and setup for dom --- packages/dom/README.md | 257 ++++++++++++++++++++++++++++++++++++++ packages/dom/package.json | 6 + 2 files changed, 263 insertions(+) diff --git a/packages/dom/README.md b/packages/dom/README.md index f5e890dd7d06e..6b7c7e4224b4d 100644 --- a/packages/dom/README.md +++ b/packages/dom/README.md @@ -10,4 +10,261 @@ Install the module npm install @wordpress/dom --save ``` +## API + + + +### computeCaretRect + +[src/index.js#L9-L9](src/index.js#L9-L9) + +Get the rectangle for the selection in a container. + +**Parameters** + +- **container** `Element`: Editable container. + +**Returns** + +`?DOMRect` The rectangle. + +### documentHasSelection + +[src/index.js#L9-L9](src/index.js#L9-L9) + +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#L7-L7](src/index.js#L7-L7) + +Undocumented declaration. + +### getOffsetParent + +[src/index.js#L9-L9](src/index.js#L9-L9) + +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** + +- + +**Parameters** + +- **node** `Node`: Node from which to find offset parent. + +**Returns** + +`?Node` Offset parent. + +### getRectangleFromRange + +[src/index.js#L9-L9](src/index.js#L9-L9) + +Get the rectangle of a given Range. + +**Parameters** + +- **range** `Range`: The range. + +**Returns** + +`DOMRect` The rectangle. + +### getScrollContainer + +[src/index.js#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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: + +**Parameters** + +- **element** `HTMLElement`: The HTML element. + +**Returns** + +`boolean` True if the element is an text field, false if not. + +### isVerticalEdge + +[src/index.js#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +Given a DOM node, removes it from the DOM. + +**Parameters** + +- **node** `Element`: Node to be removed. + +**Returns** + +`void` + +### replace + +[src/index.js#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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#L9-L9](src/index.js#L9-L9) + +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. + + + +

Code is Poetry.

diff --git a/packages/dom/package.json b/packages/dom/package.json index 007f809ebe221..cf332be5fe1d2 100644 --- a/packages/dom/package.json +++ b/packages/dom/package.json @@ -25,7 +25,13 @@ "@babel/runtime": "^7.3.1", "lodash": "^4.17.11" }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, "publishConfig": { "access": "public" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 7f8ace7668c6e61db69ca9c84f6d5bd3675b80e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 14:24:36 +0100 Subject: [PATCH 2/3] Use new script --- bin/update-readmes.js | 2 +- packages/dom/README.md | 28 ++++++++++++++-------------- packages/dom/package.json | 6 ------ 3 files changed, 15 insertions(+), 21 deletions(-) diff --git a/bin/update-readmes.js b/bin/update-readmes.js index 038cfa34c6213..16589f592a831 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -15,7 +15,7 @@ const packages = [ //'data', //'date', //'deprecated', - //'dom', + 'dom', //'dom-ready', 'e2e-test-utils', //'edit-post', diff --git a/packages/dom/README.md b/packages/dom/README.md index 6b7c7e4224b4d..594babb0230d4 100644 --- a/packages/dom/README.md +++ b/packages/dom/README.md @@ -26,7 +26,7 @@ Get the rectangle for the selection in a container. **Returns** -`?DOMRect` The rectangle. +`?DOMRect`: The rectangle. ### documentHasSelection @@ -37,7 +37,7 @@ This checks both for focus in an input field and general text selection. **Returns** -`boolean` True if there is selection, false if not. +`boolean`: True if there is selection, false if not. ### focus @@ -63,7 +63,7 @@ limited to HTMLElement and accepts any Node (e.g. Node.TEXT_NODE). **Returns** -`?Node` Offset parent. +`?Node`: Offset parent. ### getRectangleFromRange @@ -77,7 +77,7 @@ Get the rectangle of a given Range. **Returns** -`DOMRect` The rectangle. +`DOMRect`: The rectangle. ### getScrollContainer @@ -91,7 +91,7 @@ Given a DOM node, finds the closest scrollable container node. **Returns** -`?Element` Scrollable container node, if found. +`?Element`: Scrollable container node, if found. ### insertAfter @@ -107,7 +107,7 @@ the latter. **Returns** -`void` +`void`: ### isEntirelySelected @@ -122,7 +122,7 @@ Returns true if there is no possibility of selection. **Returns** -`boolean` True if entirely selected, false if not. +`boolean`: True if entirely selected, false if not. ### isHorizontalEdge @@ -137,7 +137,7 @@ Check whether the selection is horizontally at the edge of the container. **Returns** -`boolean` True if at the horizontal edge, false if not. +`boolean`: True if at the horizontal edge, false if not. ### isTextField @@ -154,7 +154,7 @@ See: **Returns** -`boolean` True if the element is an text field, false if not. +`boolean`: True if the element is an text field, false if not. ### isVerticalEdge @@ -169,7 +169,7 @@ Check whether the selection is vertically at the edge of the container. **Returns** -`boolean` True if at the edge, false if not. +`boolean`: True if at the edge, false if not. ### placeCaretAtHorizontalEdge @@ -207,7 +207,7 @@ Given a DOM node, removes it from the DOM. **Returns** -`void` +`void`: ### replace @@ -222,7 +222,7 @@ Given two DOM nodes, replaces the former with the latter in the DOM. **Returns** -`void` +`void`: ### replaceTag @@ -237,7 +237,7 @@ Replaces the given node with a new node with the given tag name. **Returns** -`Element` The new node. +`Element`: The new node. ### unwrap @@ -251,7 +251,7 @@ Unwrap the given node. This means any child nodes are moved to the parent. **Returns** -`void` +`void`: ### wrap diff --git a/packages/dom/package.json b/packages/dom/package.json index cf332be5fe1d2..007f809ebe221 100644 --- a/packages/dom/package.json +++ b/packages/dom/package.json @@ -25,13 +25,7 @@ "@babel/runtime": "^7.3.1", "lodash": "^4.17.11" }, - "devDependencies": { - "@wordpress/docgen": "file:../docgen" - }, "publishConfig": { "access": "public" - }, - "scripts": { - "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 2b684f02b9ac5702cf111822542be5a90224037c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 14:28:33 +0100 Subject: [PATCH 3/3] Update documentation --- packages/dom/README.md | 39 ++++++++++++++++++++------------------- packages/dom/src/index.js | 4 ++++ 2 files changed, 24 insertions(+), 19 deletions(-) diff --git a/packages/dom/README.md b/packages/dom/README.md index 594babb0230d4..bf572a4741b50 100644 --- a/packages/dom/README.md +++ b/packages/dom/README.md @@ -16,7 +16,7 @@ npm install @wordpress/dom --save ### computeCaretRect -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Get the rectangle for the selection in a container. @@ -30,7 +30,7 @@ Get the rectangle for the selection in a container. ### documentHasSelection -[src/index.js#L9-L9](src/index.js#L9-L9) +[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. @@ -41,13 +41,14 @@ This checks both for focus in an input field and general text selection. ### focus -[src/index.js#L7-L7](src/index.js#L7-L7) +[src/index.js#L11-L11](src/index.js#L11-L11) -Undocumented declaration. +Object grouping `focusable` and `tabbable` utils +under the keys with the same name. ### getOffsetParent -[src/index.js#L9-L9](src/index.js#L9-L9) +[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 @@ -67,7 +68,7 @@ limited to HTMLElement and accepts any Node (e.g. Node.TEXT_NODE). ### getRectangleFromRange -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Get the rectangle of a given Range. @@ -81,7 +82,7 @@ Get the rectangle of a given Range. ### getScrollContainer -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Given a DOM node, finds the closest scrollable container node. @@ -95,7 +96,7 @@ Given a DOM node, finds the closest scrollable container node. ### insertAfter -[src/index.js#L9-L9](src/index.js#L9-L9) +[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. @@ -111,7 +112,7 @@ the latter. ### isEntirelySelected -[src/index.js#L9-L9](src/index.js#L9-L9) +[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. @@ -126,7 +127,7 @@ Returns true if there is no possibility of selection. ### isHorizontalEdge -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Check whether the selection is horizontally at the edge of the container. @@ -141,7 +142,7 @@ Check whether the selection is horizontally at the edge of the container. ### isTextField -[src/index.js#L9-L9](src/index.js#L9-L9) +[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. @@ -158,7 +159,7 @@ See: ### isVerticalEdge -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Check whether the selection is vertically at the edge of the container. @@ -173,7 +174,7 @@ Check whether the selection is vertically at the edge of the container. ### placeCaretAtHorizontalEdge -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Places the caret at start or end of a given element. @@ -184,7 +185,7 @@ Places the caret at start or end of a given element. ### placeCaretAtVerticalEdge -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Places the caret at the top or bottom of a given element. @@ -197,7 +198,7 @@ Places the caret at the top or bottom of a given element. ### remove -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Given a DOM node, removes it from the DOM. @@ -211,7 +212,7 @@ Given a DOM node, removes it from the DOM. ### replace -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Given two DOM nodes, replaces the former with the latter in the DOM. @@ -226,7 +227,7 @@ Given two DOM nodes, replaces the former with the latter in the DOM. ### replaceTag -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Replaces the given node with a new node with the given tag name. @@ -241,7 +242,7 @@ Replaces the given node with a new node with the given tag name. ### unwrap -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Unwrap the given node. This means any child nodes are moved to the parent. @@ -255,7 +256,7 @@ Unwrap the given node. This means any child nodes are moved to the parent. ### wrap -[src/index.js#L9-L9](src/index.js#L9-L9) +[src/index.js#L13-L13](src/index.js#L13-L13) Wraps the given node with a new node with the given tag name. diff --git a/packages/dom/src/index.js b/packages/dom/src/index.js index 9fde374193ad5..7d514005846c2 100644 --- a/packages/dom/src/index.js +++ b/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';