From efe9b7ddc26fb857c9a71256deb9f374304d0a43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 14:29:48 +0100 Subject: [PATCH 1/7] Use a central script instead of one per package --- bin/generate-docs.sh | 3 +++ 1 file changed, 3 insertions(+) create mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh new file mode 100755 index 0000000000000..c7ec1314d9b51 --- /dev/null +++ b/bin/generate-docs.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +npx docgen packages/e2e-test-utils/src/index.js --output packages/e2e-test-utils/README.md --to-token From 808be3cd11f7a86a66117f8739a8744273f86284 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 14:53:11 +0100 Subject: [PATCH 2/7] Prepare to add more packages --- bin/generate-docs.sh | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh index c7ec1314d9b51..afdebea2977d4 100755 --- a/bin/generate-docs.sh +++ b/bin/generate-docs.sh @@ -1,3 +1,10 @@ #!/bin/bash -npx docgen packages/e2e-test-utils/src/index.js --output packages/e2e-test-utils/README.md --to-token +declare -a packages=( + "e2e-test-utils" +) + +for package in "${packages[@]}" +do + npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; +done From a5a09e2a457acb26f85e20304cf0c4e8a8270e7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 19:06:08 +0100 Subject: [PATCH 3/7] Merge docs:build and docs:generate --- bin/generate-docs.sh | 10 ---------- 1 file changed, 10 deletions(-) delete mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh deleted file mode 100755 index afdebea2977d4..0000000000000 --- a/bin/generate-docs.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/bash - -declare -a packages=( - "e2e-test-utils" -) - -for package in "${packages[@]}" -do - npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; -done From 8d530d44d6fe3aa5b8dbe1af7a84718fdb8e6fd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 13:18:13 +0100 Subject: [PATCH 4/7] Autogenerated docs and setup for viewport --- packages/viewport/README.md | 72 +++++++++++++++----- packages/viewport/package.json | 6 ++ packages/viewport/src/if-viewport-matches.js | 12 +++- packages/viewport/src/with-viewport-match.js | 14 +++- 4 files changed, 86 insertions(+), 18 deletions(-) diff --git a/packages/viewport/README.md b/packages/viewport/README.md index 3431d99b216de..bc0b5efd33b13 100644 --- a/packages/viewport/README.md +++ b/packages/viewport/README.md @@ -12,20 +12,20 @@ npm install @wordpress/viewport --save _This package assumes that your code will run in an **ES2015+** environment. 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. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._ -## Breakpoints +## Usage The standard set of breakpoint thresholds is as follows: -Name|Pixel Width ----|--- -`huge`|1440 -`wide`|1280 -`large`|960 -`medium`|782 -`small`|600 -`mobile`|480 +| Name | Pixel Width | +| -------- | ----------- | +| `huge` | 1440 | +| `wide` | 1280 | +| `large` | 960 | +| `medium` | 782 | +| `small` | 600 | +| `mobile` | 480 | -## Data Module +### Data Module The Viewport module registers itself under the `core/viewport` data namespace. @@ -43,11 +43,24 @@ const isWideOrHuge = isViewportMatch( '>= wide' ); // const isWideOrHuge = isViewportMatch( 'wide' ); ``` -## `ifViewportMatches` Higher-Order Component +### Higher-Order Components -If you are authoring a component which should only be shown under a specific viewport condition, you can leverage the `ifViewportMatches` higher-order component to achieve this requirement. +This package provides a set of HOCs to author components whose behavior should vary depending on the viewport. -Pass a viewport query to render the component only when the query is matched: + + +#### ifViewportMatches + +[src/index.js#L16-L16](src/index.js#L16-L16) + +Higher-order component creator, creating a new component which renders if +the viewport query is satisfied. + +**Related** + +- withViewportMatches + +**Usage** ```jsx function MyMobileComponent() { @@ -57,11 +70,27 @@ function MyMobileComponent() { MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent ); ``` -## `withViewportMatch` Higher-Order Component +**Parameters** + +- **query** `string`: Viewport query. + +**Returns** + +`Function` Higher-order component. + +#### withViewportMatch -If you are authoring a component which should vary its rendering behavior depending upon the matching viewport, you can leverage the `withViewportMatch` higher-order component to achieve this requirement. +[src/index.js#L17-L17](src/index.js#L17-L17) -Pass an object, where each key is a prop name and its value a viewport query. The component will be rendered with your prop(s) assigned with the result(s) of the query match: +Higher-order component creator, creating a new component which renders with +the given prop names, where the value passed to the underlying component is +the result of the query assigned as the object's value. + +**Related** + +- isViewportMatch + +**Usage** ```jsx function MyComponent( { isMobile } ) { @@ -73,4 +102,15 @@ function MyComponent( { isMobile } ) { MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent ); ``` +**Parameters** + +- **queries** `Object`: Object of prop name to viewport query. + +**Returns** + +`Function` Higher-order component. + + + +

Code is Poetry.

diff --git a/packages/viewport/package.json b/packages/viewport/package.json index a532f6299dc69..e6b3c1b56d066 100644 --- a/packages/viewport/package.json +++ b/packages/viewport/package.json @@ -29,5 +29,11 @@ }, "publishConfig": { "access": "public" + }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } diff --git a/packages/viewport/src/if-viewport-matches.js b/packages/viewport/src/if-viewport-matches.js index 97cf7fb355411..76ea3c5650b56 100644 --- a/packages/viewport/src/if-viewport-matches.js +++ b/packages/viewport/src/if-viewport-matches.js @@ -12,9 +12,19 @@ import withViewportMatch from './with-viewport-match'; * Higher-order component creator, creating a new component which renders if * the viewport query is satisfied. * + * @see withViewportMatches + * * @param {string} query Viewport query. * - * @see withViewportMatches + * @example + * + * ```jsx + * function MyMobileComponent() { + * return
I'm only rendered on mobile viewports!
; + * } + * + * MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent ); + * ``` * * @return {Function} Higher-order component. */ diff --git a/packages/viewport/src/with-viewport-match.js b/packages/viewport/src/with-viewport-match.js index 1da962f1f1a01..3398fda7e4f3f 100644 --- a/packages/viewport/src/with-viewport-match.js +++ b/packages/viewport/src/with-viewport-match.js @@ -14,9 +14,21 @@ import { withSelect } from '@wordpress/data'; * the given prop names, where the value passed to the underlying component is * the result of the query assigned as the object's value. * + * @see isViewportMatch + * * @param {Object} queries Object of prop name to viewport query. * - * @see isViewportMatch + * @example + * + * ```jsx + * function MyComponent( { isMobile } ) { + * return ( + *
Currently: { isMobile ? 'Mobile' : 'Not Mobile' }
+ * ); + * } + * + * MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent ); + * ``` * * @return {Function} Higher-order component. */ From 6b10d0e8f54fdcd32ef5400c5fe5786b56f2ff7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Mon, 4 Mar 2019 14:57:57 +0100 Subject: [PATCH 5/7] Use bin script instead of npm script --- bin/generate-docs.sh | 11 +++++++++++ packages/viewport/package.json | 6 ------ 2 files changed, 11 insertions(+), 6 deletions(-) create mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh new file mode 100755 index 0000000000000..58526e1a95cf0 --- /dev/null +++ b/bin/generate-docs.sh @@ -0,0 +1,11 @@ +#!/bin/bash + +declare -a packages=( + "e2e-test-utils" + "viewport" +) + +for package in "${packages[@]}" +do + npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; +done diff --git a/packages/viewport/package.json b/packages/viewport/package.json index e6b3c1b56d066..a532f6299dc69 100644 --- a/packages/viewport/package.json +++ b/packages/viewport/package.json @@ -29,11 +29,5 @@ }, "publishConfig": { "access": "public" - }, - "devDependencies": { - "@wordpress/docgen": "file:../docgen" - }, - "scripts": { - "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From b252519dee3132e364c3fbb462b0315c3e0b1181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Tue, 5 Mar 2019 02:27:18 +0100 Subject: [PATCH 6/7] Use new script --- bin/generate-docs.sh | 11 ----------- bin/update-readmes.js | 2 +- 2 files changed, 1 insertion(+), 12 deletions(-) delete mode 100755 bin/generate-docs.sh diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh deleted file mode 100755 index 58526e1a95cf0..0000000000000 --- a/bin/generate-docs.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/bin/bash - -declare -a packages=( - "e2e-test-utils" - "viewport" -) - -for package in "${packages[@]}" -do - npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token; -done diff --git a/bin/update-readmes.js b/bin/update-readmes.js index 038cfa34c6213..ecc6e7933ce00 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -30,7 +30,7 @@ const packages = [ //'rich-text', //'shortcode', //'url', - //'viewport', + 'viewport', //'wordcount', ]; From 1166d84e8fde245127ae7a1ca7078357f474b3bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Tue, 5 Mar 2019 12:11:22 +0100 Subject: [PATCH 7/7] Update output --- packages/viewport/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/viewport/README.md b/packages/viewport/README.md index bc0b5efd33b13..c11fd9172d10d 100644 --- a/packages/viewport/README.md +++ b/packages/viewport/README.md @@ -76,7 +76,7 @@ MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent ); **Returns** -`Function` Higher-order component. +`Function`: Higher-order component. #### withViewportMatch @@ -108,7 +108,7 @@ MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent ); **Returns** -`Function` Higher-order component. +`Function`: Higher-order component.