From 212b26fddbbe3d3074db48451d95137074f237b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 1 Mar 2019 20:01:27 +0100 Subject: [PATCH 1/3] Autogenerated docs and setup for element --- packages/element/README.md | 259 ++++++++++++++++++++++++++++++++-- packages/element/package.json | 6 + 2 files changed, 257 insertions(+), 8 deletions(-) diff --git a/packages/element/README.md b/packages/element/README.md index cca88dff95240..146a3841d79e4 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -4,14 +4,14 @@ Element is, quite simply, an abstraction layer atop [React](https://reactjs.org/ You may find yourself asking, "Why an abstraction layer?". For a few reasons: -- In many applications, especially those extended by a rich plugin ecosystem as is the case with WordPress, it's wise to create interfaces to underlying third-party code. The thinking is that if ever a need arises to change or even replace the underlying implementation, it can be done without catastrophic rippling effects to dependent code, so long as the interface stays the same. -- It provides a mechanism to shield implementers by omitting features with uncertain futures (`createClass`, `PropTypes`). -- It helps avoid incompatibilities between versions by ensuring that every plugin operates on a single centralized version of the code. +- In many applications, especially those extended by a rich plugin ecosystem as is the case with WordPress, it's wise to create interfaces to underlying third-party code. The thinking is that if ever a need arises to change or even replace the underlying implementation, it can be done without catastrophic rippling effects to dependent code, so long as the interface stays the same. +- It provides a mechanism to shield implementers by omitting features with uncertain futures (`createClass`, `PropTypes`). +- It helps avoid incompatibilities between versions by ensuring that every plugin operates on a single centralized version of the code. On the `wp.element` global object, you will find the following, ordered roughly by the likelihood you'll encounter it in your code: -- [`createElement`](https://reactjs.org/docs/react-api.html#createelement) -- [`render`](https://reactjs.org/docs/react-dom.html#render) +- [`createElement`](https://reactjs.org/docs/react-api.html#createelement) +- [`render`](https://reactjs.org/docs/react-dom.html#render) ## Installation @@ -49,10 +49,10 @@ Refer to the [official React Quick Start guide](https://reactjs.org/docs/hello-w At the risk of igniting debate surrounding any single "best" front-end framework, the choice to use any tool should be motivated specifically to serve the requirements of the system. In modeling the concept of a [block](/packages/blocks/README.md), we observe the following technical requirements: -- An understanding of a block in terms of its underlying values (in the [random image example](/packages/blocks/README.md#example), a category) -- A means to describe the UI of a block given these values +- An understanding of a block in terms of its underlying values (in the [random image example](/packages/blocks/README.md#example), a category) +- A means to describe the UI of a block given these values -At its most basic, React provides a simple input / output mechanism. __Given a set of inputs ("props"), a developer describes the output to be shown on the page.__ This is most elegantly observed in its [function components](https://reactjs.org/docs/components-and-props.html#functional-and-class-components). React serves the role of reconciling the desired output with the current state of the page. +At its most basic, React provides a simple input / output mechanism. **Given a set of inputs ("props"), a developer describes the output to be shown on the page.** This is most elegantly observed in its [function components](https://reactjs.org/docs/components-and-props.html#functional-and-class-components). React serves the role of reconciling the desired output with the current state of the page. The offerings of any framework necessarily become more complex as these requirements increase; many front-end frameworks prescribe ideas around page routing, retrieving and updating data, and managing layout. React is not immune to this, but the introduced complexity is rarely caused by React itself, but instead managing an arrangement of supporting tools. By moving these concerns out of sight to the internals of the system (WordPress core code), we can minimize the responsibilities of plugin authors to a small, clear set of touch points. @@ -74,4 +74,247 @@ If you've configured [Babel](http://babeljs.io/) for your project, you can opt i This assumes that you will import the `createElement` function in any file where you use JSX. Alternatively, consider using the [`@wordpress/babel-plugin-import-jsx-pragma` Babel plugin](https://www.npmjs.com/package/@wordpress/babel-plugin-import-jsx-pragma) to automate the import of this function. +## API + + + +### Children + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Undocumented declaration. + +### cloneElement + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Creates a copy of an element with extended props. + +**Parameters** + +- **element** `WPElement`: Element +- **props** `?Object`: Props to apply to cloned element + +**Returns** + +`WPElement` Cloned element. + +### Component + +[src/index.js#L1-L1](src/index.js#L1-L1) + +A base class to create WordPress Components (Refs, state and lifecycle hooks) + +### concatChildren + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Concatenate two or more React children objects. + +**Parameters** + +- **childrenArguments** `...?Object`: Array of children arguments (array of arrays/strings/objects) to concatenate. + +**Returns** + +`Array` The concatenated value. + +### createContext + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Creates a context object containing two components: a provider and consumer. + +**Parameters** + +- **defaultValue** `Object`: A default data stored in the context. + +**Returns** + +`Object` Context object. + +### createElement + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Returns a new element of given type. Type can be either a string tag name or +another function which itself returns an element. + +**Parameters** + +- **type** `?(string|Function)`: Tag name or element creator +- **props** `Object`: Element properties, either attribute set to apply to DOM node or values to pass through to element creator +- **children** `...WPElement`: Descendant elements + +**Returns** + +`WPElement` Element. + +### createPortal + +[src/index.js#L2-L2](src/index.js#L2-L2) + +Creates a portal into which a component can be rendered. + +**Related** + +- + +**Parameters** + +- **component** `Component`: Component +- **target** `Element`: DOM node into which element should be rendered + +### createRef + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Returns an object tracking a reference to a rendered element via its +`current` property as either a DOMElement or Element, dependent upon the +type of element rendered with the ref attribute. + +**Returns** + +`Object` Ref object. + +### findDOMNode + +[src/index.js#L2-L2](src/index.js#L2-L2) + +Finds the dom node of a React component + +**Parameters** + +- **component** `Component`: component's instance +- **target** `Element`: DOM node into which element should be rendered + +### forwardRef + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Component enhancer used to enable passing a ref to its wrapped component. +Pass a function argument which receives `props` and `ref` as its arguments, +returning an element using the forwarded ref. The return value is a new +component which forwards its ref. + +**Parameters** + +- **forwarder** `Function`: Function passed `props` and `ref`, expected to return an element. + +**Returns** + +`WPComponent` Enhanced component. + +### Fragment + +[src/index.js#L1-L1](src/index.js#L1-L1) + +A component which renders its children without any wrapping element. + +### isEmptyElement + +[src/index.js#L3-L3](src/index.js#L3-L3) + +Checks if the provided WP element is empty. + +**Parameters** + +- **element** `*`: WP element to check. + +**Returns** + +`boolean` True when an element is considered empty. + +### isValidElement + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Checks if an object is a valid WPElement + +**Parameters** + +- **objectToCheck** `Object`: The object to be checked. + +**Returns** + +`boolean` true if objectToTest is a valid WPElement and false otherwise. + +### RawHTML + +[src/index.js#L5-L5](src/index.js#L5-L5) + +Component used as equivalent of Fragment with unescaped HTML, in cases where +it is desirable to render dangerous HTML without needing a wrapper element. +To preserve additional props, a `div` wrapper _will_ be created if any props +aside from `children` are passed. + +**Parameters** + +- **props.children** `string`: HTML to render. + +**Returns** + +`WPElement` Dangerously-rendering element. + +### render + +[src/index.js#L2-L2](src/index.js#L2-L2) + +Renders a given element into the target DOM node. + +**Parameters** + +- **element** `WPElement`: Element to render +- **target** `Element`: DOM node into which element should be rendered + +### renderToString + +[src/index.js#L4-L4](src/index.js#L4-L4) + +Serializes a React element to string. + +**Parameters** + +- **element** `WPElement`: Element to serialize. +- **context** `?Object`: Context object. +- **legacyContext** `?Object`: Legacy context object. + +**Returns** + +`string` Serialized element. + +### StrictMode + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Undocumented declaration. + +### switchChildrenNodeName + +[src/index.js#L1-L1](src/index.js#L1-L1) + +Switches the nodeName of all the elements in the children object. + +**Parameters** + +- **children** `?Object`: Children object. +- **nodeName** `string`: Node name. + +**Returns** + +`?Object` The updated children object. + +### unmountComponentAtNode + +[src/index.js#L2-L2](src/index.js#L2-L2) + +Removes any mounted element from the target DOM node. + +**Parameters** + +- **target** `Element`: DOM node in which element is to be removed + + + +

Code is Poetry.

diff --git a/packages/element/package.json b/packages/element/package.json index ce76fa344232c..d4690d5dc533b 100644 --- a/packages/element/package.json +++ b/packages/element/package.json @@ -28,7 +28,13 @@ "react": "^16.6.3", "react-dom": "^16.6.3" }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, "publishConfig": { "access": "public" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 9f6558055b30be633f4e9b4ee28c777a2556e28d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 13:15:04 +0100 Subject: [PATCH 2/3] Use new script --- bin/update-readmes.js | 1 + packages/element/README.md | 22 +++++++++++----------- packages/element/package.json | 6 ------ 3 files changed, 12 insertions(+), 17 deletions(-) diff --git a/bin/update-readmes.js b/bin/update-readmes.js index c094bc57a5b2b..c4bd256f0a8ed 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -5,6 +5,7 @@ const childProcess = require( 'child_process' ); const packages = [ 'e2e-test-utils', + 'element', ]; let aggregatedExitCode = 0; diff --git a/packages/element/README.md b/packages/element/README.md index 146a3841d79e4..7684cf39752e8 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -97,7 +97,7 @@ Creates a copy of an element with extended props. **Returns** -`WPElement` Cloned element. +`WPElement`: Cloned element. ### Component @@ -117,7 +117,7 @@ Concatenate two or more React children objects. **Returns** -`Array` The concatenated value. +`Array`: The concatenated value. ### createContext @@ -131,7 +131,7 @@ Creates a context object containing two components: a provider and consumer. **Returns** -`Object` Context object. +`Object`: Context object. ### createElement @@ -148,7 +148,7 @@ another function which itself returns an element. **Returns** -`WPElement` Element. +`WPElement`: Element. ### createPortal @@ -175,7 +175,7 @@ type of element rendered with the ref attribute. **Returns** -`Object` Ref object. +`Object`: Ref object. ### findDOMNode @@ -203,7 +203,7 @@ component which forwards its ref. **Returns** -`WPComponent` Enhanced component. +`WPComponent`: Enhanced component. ### Fragment @@ -223,7 +223,7 @@ Checks if the provided WP element is empty. **Returns** -`boolean` True when an element is considered empty. +`boolean`: True when an element is considered empty. ### isValidElement @@ -237,7 +237,7 @@ Checks if an object is a valid WPElement **Returns** -`boolean` true if objectToTest is a valid WPElement and false otherwise. +`boolean`: true if objectToTest is a valid WPElement and false otherwise. ### RawHTML @@ -254,7 +254,7 @@ aside from `children` are passed. **Returns** -`WPElement` Dangerously-rendering element. +`WPElement`: Dangerously-rendering element. ### render @@ -281,7 +281,7 @@ Serializes a React element to string. **Returns** -`string` Serialized element. +`string`: Serialized element. ### StrictMode @@ -302,7 +302,7 @@ Switches the nodeName of all the elements in the children object. **Returns** -`?Object` The updated children object. +`?Object`: The updated children object. ### unmountComponentAtNode diff --git a/packages/element/package.json b/packages/element/package.json index d4690d5dc533b..ce76fa344232c 100644 --- a/packages/element/package.json +++ b/packages/element/package.json @@ -28,13 +28,7 @@ "react": "^16.6.3", "react-dom": "^16.6.3" }, - "devDependencies": { - "@wordpress/docgen": "file:../docgen" - }, "publishConfig": { "access": "public" - }, - "scripts": { - "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From b1ab656c73ea639d76c22d757564a439df0d038a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 13:19:40 +0100 Subject: [PATCH 3/3] Update docs --- packages/element/README.md | 4 ++-- packages/element/src/react.js | 6 ++++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/element/README.md b/packages/element/README.md index 7684cf39752e8..ae28a29cf6ec2 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -82,7 +82,7 @@ This assumes that you will import the `createElement` function in any file where [src/index.js#L1-L1](src/index.js#L1-L1) -Undocumented declaration. +Object that provides utilities for dealing with React children. ### cloneElement @@ -287,7 +287,7 @@ Serializes a React element to string. [src/index.js#L1-L1](src/index.js#L1-L1) -Undocumented declaration. +Component that activates additional checks and warnings for its descendants. ### switchChildrenNodeName diff --git a/packages/element/src/react.js b/packages/element/src/react.js index 4d42fae21c1f7..703a0455d0a16 100644 --- a/packages/element/src/react.js +++ b/packages/element/src/react.js @@ -15,6 +15,9 @@ import { } from 'react'; import { isString } from 'lodash'; +/** + * Object that provides utilities for dealing with React children. + */ export { Children }; /** @@ -91,6 +94,9 @@ export { Fragment }; */ export { isValidElement }; +/** + * Component that activates additional checks and warnings for its descendants. + */ export { StrictMode }; /**