Merge pull request #121 from blueflag/feature/parcelhoc-updates

Feature/parcelhoc updates
92green · Oct 22, 2018 · 1c18ff2 · 1c18ff2
2 parents f8a00e2 + 809e0ed
commit 1c18ff2
Show file tree

Hide file tree

Showing 44 changed files with 331 additions and 133 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -24,9 +24,3 @@ jobs:
       - run: git diff | cat
       - run: test -z "$(git status --porcelain)"
       - run: yarn test-all
-      - deploy:
-          command: |
-            if [ "${CIRCLE_BRANCH}" == "master" ]; then
-              git config --global -l && git config --global user.email circleci@circleci && git config --global user.name CircleCI && yarn deploy-docs
-            fi
-
diff --git a/packages/dataparcels-docs/gatsby-config.js b/packages/dataparcels-docs/gatsby-config.js
@@ -5,6 +5,7 @@ module.exports = {
         title: 'Dataparcels'
     },
     plugins: [
+        'gatsby-plugin-react-next',
         'gatsby-plugin-sass',
         'gatsby-plugin-react-helmet',
         'gatsby-plugin-resolve-src',

diff --git a/packages/dataparcels-docs/package.json b/packages/dataparcels-docs/package.json
@@ -18,6 +18,7 @@
     "gatsby": "^1.9.223",
     "gatsby-link": "^1.6.38",
     "gatsby-plugin-react-helmet": "^2.0.6",
+    "gatsby-plugin-react-next": "^1.0.11",
     "gatsby-plugin-resolve-src": "^1.1.4",
     "gatsby-plugin-sass": "^1.0.20",
     "gatsby-remark-prismjs": "^1.2.21",
@@ -30,6 +31,7 @@
     "prismjs": "^1.11.0",
     "react-flip-move": "^3.0.2",
     "react-helmet": "^5.2.0",
+    "react-lifecycles-compat": "^3.0.4",
     "stampy": "^0.41.0",
     "unmutable": "^0.29.2"
   }

diff --git a/packages/dataparcels-docs/src/content/ExamplesParcelHoc.md b/packages/dataparcels-docs/src/content/ExamplesParcelHoc.md
@@ -1,6 +1,6 @@
 import Link from 'gatsby-link';
 
 * <Link to="/examples/parcelhoc-example">ParcelHoc example</Link>
-* <Link to="/examples/parcelhoc-initialvalue">Getting initialValue from props</Link>
+* <Link to="/examples/parcelhoc-valuefromprops">Getting value from props</Link>
 * <Link to="/examples/parcelhoc-onchange">Using onChange</Link>
 * <Link to="/examples/parcelhoc-delayuntil">Using delayUntil</Link>
diff --git a/packages/dataparcels-docs/src/docs/api/parcel/batchAndReturn.md b/packages/dataparcels-docs/src/docs/api/parcel/batchAndReturn.md
@@ -0,0 +1,3 @@
+```flow
+batchAndReturn(batcher: Function): ?Parcel // only on TopLevelParcels
+```
diff --git a/packages/dataparcels-docs/src/docs/api/parcelBoundary/ParcelBoundary.md b/packages/dataparcels-docs/src/docs/api/parcelBoundary/ParcelBoundary.md
@@ -2,7 +2,7 @@ import Link from 'component/Link';
 import Param from 'component/Param';
 import ApiPageIcon from 'component/ApiPageIcon';
 import ParcelHocExample from 'pages/examples/parcelhoc-example.md';
-import ParcelHocInitialValueFromProps from 'pages/examples/parcelhoc-initialvalue.md';
+import ParcelHocInitialValueFromProps from 'pages/examples/parcelhoc-valuefromprops.md';
 import ParcelHocOnChange from 'pages/examples/parcelhoc-onchange.md';
 import IconParcelBoundary from 'content/parcelboundary.gif';
 import {Box, Message} from 'dcme-style';

diff --git a/packages/dataparcels-docs/src/docs/api/parcelBoundaryHoc/ParcelBoundaryHoc.md b/packages/dataparcels-docs/src/docs/api/parcelBoundaryHoc/ParcelBoundaryHoc.md
@@ -2,7 +2,7 @@ import Link from 'component/Link';
 import Param from 'component/Param';
 import ApiPageIcon from 'component/ApiPageIcon';
 import ParcelHocExample from 'pages/examples/parcelhoc-example.md';
-import ParcelHocInitialValueFromProps from 'pages/examples/parcelhoc-initialvalue.md';
+import ParcelHocInitialValueFromProps from 'pages/examples/parcelhoc-valuefromprops.md';
 import ParcelHocOnChange from 'pages/examples/parcelhoc-onchange.md';
 import IconParcelBoundaryHoc from 'content/parcelboundaryhoc.gif';
 import {Box, Message} from 'dcme-style';

diff --git a/packages/dataparcels-docs/src/docs/api/parcelHoc/ParcelHoc.md b/packages/dataparcels-docs/src/docs/api/parcelHoc/ParcelHoc.md
@@ -2,7 +2,7 @@ import Link from 'component/Link';
 import Param from 'component/Param';
 import ApiPageIcon from 'component/ApiPageIcon';
 import ParcelHocExample from 'pages/examples/parcelhoc-example.md';
-import ParcelHocInitialValueFromProps from 'pages/examples/parcelhoc-initialvalue.md';
+import ParcelHocInitialValueFromProps from 'pages/examples/parcelhoc-valuefromprops.md';
 import ParcelHocOnChange from 'pages/examples/parcelhoc-onchange.md';
 import IconParcelHoc from 'content/parcelhoc.gif';
 
@@ -21,11 +21,13 @@ import {ParcelHoc} from 'react-dataparcels';
 ```flow
 ParcelHoc({
     name: string,
-    initialValue?: Function,
-    delayUntil?: Function,
+    valueFromProps?: Function,
+    shouldParcelUpdateFromProps?: Function,
     onChange?: Function,
+    delayUntil?: Function,
     pipe?: Function
     // debugging options
     debugRender?: boolean
 });
 ```
+
diff --git a/packages/dataparcels-docs/src/docs/api/parcelHoc/initialValue.md b/packages/dataparcels-docs/src/docs/api/parcelHoc/initialValue.md
diff --git a/packages/dataparcels-docs/src/docs/api/parcelHoc/pipe.md b/packages/dataparcels-docs/src/docs/api/parcelHoc/pipe.md
@@ -6,4 +6,4 @@ pipe?: (props: Object) => (parcel: Parcel) => Parcel // optional
 
 This function gives you the opportunity to modify the parcel before it reaches any other components.
 
-The `pipe` function expects to be given a double barrel function. The first function will be passed `props`, and the next is passed the Parcel. The result of the `pipe` function will then be passed down as props.
+The `pipe` function expects to be given a double barrel function. The first function will be passed `props`, and the next is passed the Parcel. The result of the `pipe` function will then be passed down as a prop.
diff --git a/packages/dataparcels-docs/src/docs/api/parcelHoc/shouldParcelUpdateFromProps.md b/packages/dataparcels-docs/src/docs/api/parcelHoc/shouldParcelUpdateFromProps.md
@@ -0,0 +1,23 @@
+import {Box, Message} from 'dcme-style';
+
+```flow
+shouldParcelUpdateFromProps?: (prevValue: *, nextValue: *) => boolean // optional
+```
+
+The `shouldParcelUpdateFromProps` config option allows the ParcelHoc to replace its parcel's contents based on received props.
+
+If `shouldParcelUpdateFromProps` is set, it will be called every time props are received. It is passed two arguments:
+* `prevValue` is the value of the ParcelHoc's current parcel.
+* `nextValue` is the result of passing the new props through `config.valueFromProps`
+
+When `shouldParcelUpdateFromProps` returns true, ParcelHoc will replace all of its parcels value with `nextValue`, and it will delete all key and meta information from the parcel.
+
+```js
+ParcelHoc({
+    name: "exampleParcel",
+    valueFromProps: (props) => props.data,
+    shouldParcelUpdateFromProps: (prevValue, nextValue) => prevValue.xyz !== nextValue.xyz
+});
+```
+
+<Message>In future there will be more options to allow partial changes, and to allow key and meta data to be retained.</Message>
diff --git a/packages/dataparcels-docs/src/docs/api/parcelHoc/valueFromProps.md b/packages/dataparcels-docs/src/docs/api/parcelHoc/valueFromProps.md
@@ -0,0 +1,9 @@
+import Link from 'component/Link';
+
+```flow
+valueFromProps?: (props: Object) => any // optional
+```
+
+The `valueFromProps` function will be called once when ParcelHoc mounts. It is passed `props`, and the returned value is used as the initial value of the ParcelHoc's Parcel.
+
+<Link to="/examples/parcelhoc-valuefromprops">Example</Link>
diff --git a/packages/dataparcels-docs/src/examples/EditingArrays.jsx b/packages/dataparcels-docs/src/examples/EditingArrays.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const FruitListParcelHoc = ParcelHoc({
     name: "fruitListParcel",
-    initialValue: (/* props */) => [
+    valueFromProps: (/* props */) => [
         "Apple",
         "Banana",
         "Crumpets"

diff --git a/packages/dataparcels-docs/src/examples/EditingArraysFlipMove.jsx b/packages/dataparcels-docs/src/examples/EditingArraysFlipMove.jsx
@@ -5,7 +5,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const FruitListParcelHoc = ParcelHoc({
     name: "fruitListParcel",
-    initialValue: (/* props */) => [
+    valueFromProps: (/* props */) => [
         "Apple",
         "Banana",
         "Crumpets"

diff --git a/packages/dataparcels-docs/src/examples/EditingObjects.jsx b/packages/dataparcels-docs/src/examples/EditingObjects.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const PersonParcelHoc = ParcelHoc({
     name: "personParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         firstname: "Robert",
         lastname: "Clamps",
         address: {

diff --git a/packages/dataparcels-docs/src/examples/EditingObjectsBeginner.jsx b/packages/dataparcels-docs/src/examples/EditingObjectsBeginner.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const PersonParcelHoc = ParcelHoc({
     name: "personParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         firstname: "Robert",
         lastname: "Clamps",
         address: {

diff --git a/packages/dataparcels-docs/src/examples/ParcelBoundaryDebounce.jsx b/packages/dataparcels-docs/src/examples/ParcelBoundaryDebounce.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const FoodParcelHoc = ParcelHoc({
     name: "foodParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         mains: "Soup",
         dessert: "Strudel"
     })

diff --git a/packages/dataparcels-docs/src/examples/ParcelBoundaryExample.jsx b/packages/dataparcels-docs/src/examples/ParcelBoundaryExample.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const PersonParcelHoc = ParcelHoc({
     name: "personParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         name: {
             first: "Robert",
             last: "Clamps"

diff --git a/packages/dataparcels-docs/src/examples/ParcelBoundaryForceUpdate.jsx b/packages/dataparcels-docs/src/examples/ParcelBoundaryForceUpdate.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const ColourParcelHoc = ParcelHoc({
     name: "colourParcel",
-    initialValue: (/* props */) => "Option A"
+    valueFromProps: (/* props */) => "Option A"
 });
 
 const ColourEditor = (props) => {

diff --git a/packages/dataparcels-docs/src/examples/ParcelBoundaryHold.jsx b/packages/dataparcels-docs/src/examples/ParcelBoundaryHold.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const NameParcelHoc = ParcelHoc({
     name: "nameParcel",
-    initialValue: (/* props */) => "Gregor"
+    valueFromProps: (/* props */) => "Gregor"
 });
 
 const FoodEditor = (props) => {

diff --git a/packages/dataparcels-docs/src/examples/ParcelHocExample.jsx b/packages/dataparcels-docs/src/examples/ParcelHocExample.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const WordParcelHoc = ParcelHoc({
     name: "wordParcel",
-    initialValue: () => "word"
+    valueFromProps: () => "word"
 });
 
 const WordEditor = (props) => {

diff --git a/packages/dataparcels-docs/src/examples/ParcelHocExampleDelayUntil.jsx b/packages/dataparcels-docs/src/examples/ParcelHocExampleDelayUntil.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const DelayParcelHoc = ParcelHoc({
     name: "delayParcel",
-    initialValue: (props) => `Created at ${props.seconds} seconds!`,
+    valueFromProps: (props) => `Created at ${props.seconds} seconds!`,
     delayUntil: (props) => props.seconds > 3
 });
 

diff --git a/packages/dataparcels-docs/src/examples/ParcelHocExampleInitialValueFromProps.jsx b/packages/dataparcels-docs/src/examples/ParcelHocExampleInitialValueFromProps.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const WordParcelHoc = ParcelHoc({
     name: "wordParcel",
-    initialValue: (props) => props.initialWord
+    valueFromProps: (props) => props.initialWord
 });
 
 const WordEditor = (props) => {

diff --git a/packages/dataparcels-docs/src/examples/ParcelHocExampleOnChange.jsx b/packages/dataparcels-docs/src/examples/ParcelHocExampleOnChange.jsx
@@ -4,7 +4,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const WordParcelHoc = ParcelHoc({
     name: "wordParcel",
-    initialValue: (props) => props.defaultValue,
+    valueFromProps: (props) => props.defaultValue,
     onChange: (props) => (value) => props.onChange(value)
 });
 

diff --git a/packages/dataparcels-docs/src/pages/api/Parcel.jsx b/packages/dataparcels-docs/src/pages/api/Parcel.jsx
@@ -42,6 +42,7 @@ import Markdown_updateMeta from 'docs/api/parcel/updateMeta.md';
 import Markdown_setChangeRequestMeta from 'docs/api/parcel/setChangeRequestMeta.md';
 import Markdown_dispatch from 'docs/api/parcel/dispatch.md';
 import Markdown_batch from 'docs/api/parcel/batch.md';
+import Markdown_batchAndReturn from 'docs/api/parcel/batchAndReturn.md';
 import Markdown_ping from 'docs/api/parcel/ping.md';
 import Markdown_modifyValue from 'docs/api/parcel/modifyValue.md';
 import Markdown_modifyChange from 'docs/api/parcel/modifyChange.md';
@@ -100,6 +101,7 @@ const md = {
     setChangeRequestMeta: Markdown_setChangeRequestMeta,
     dispatch: Markdown_dispatch,
     batch: Markdown_batch,
+    batchAndReturn: Markdown_batchAndReturn,
     ping: Markdown_ping,
     modifyValue: Markdown_modifyValue,
     modifyChange: Markdown_modifyChange,
@@ -172,6 +174,7 @@ updateMeta()
 setChangeRequestMeta()
 dispatch()
 batch()
+batchAndReturn()
 ping()
 
 # Modify methods

diff --git a/packages/dataparcels-docs/src/pages/api/ParcelHoc.jsx b/packages/dataparcels-docs/src/pages/api/ParcelHoc.jsx
@@ -5,7 +5,8 @@ import ApiPage from 'component/ApiPage';
 import Markdown_ParcelHoc from 'docs/api/parcelHoc/ParcelHoc.md';
 import Markdown_ParcelHocAfter from 'docs/api/parcelHoc/ParcelHocAfter.md';
 import Markdown_name from 'docs/api/parcelHoc/name.md';
-import Markdown_initialValue from 'docs/api/parcelHoc/initialValue.md';
+import Markdown_shouldParcelUpdateFromProps from 'docs/api/parcelHoc/shouldParcelUpdateFromProps.md';
+import Markdown_valueFromProps from 'docs/api/parcelHoc/valueFromProps.md';
 import Markdown_delayUntil from 'docs/api/parcelHoc/delayUntil.md';
 import Markdown_onChange from 'docs/api/parcelHoc/onChange.md';
 import Markdown_pipe from 'docs/api/parcelHoc/pipe.md';
@@ -16,7 +17,8 @@ const md = {
     _desc: Markdown_ParcelHoc,
     _after: Markdown_ParcelHocAfter,
     name: Markdown_name,
-    initialValue: Markdown_initialValue,
+    valueFromProps: Markdown_valueFromProps,
+    shouldParcelUpdateFromProps: Markdown_shouldParcelUpdateFromProps,
     delayUntil: Markdown_delayUntil,
     onChange: Markdown_onChange,
     pipe: Markdown_pipe,
@@ -27,9 +29,10 @@ const md = {
 const api = `
 # Config
 name
-initialValue
-delayUntil
+valueFromProps
 onChange
+shouldParcelUpdateFromProps
+delayUntil
 pipe
 debugRender
 

diff --git a/packages/dataparcels-docs/src/pages/examples/editing-arrays.md b/packages/dataparcels-docs/src/pages/examples/editing-arrays.md
@@ -13,7 +13,7 @@ import ExampleHoc from 'component/ExampleHoc';
 
 const FruitListParcelHoc = ParcelHoc({
     name: "fruitListParcel",
-    initialValue: (/* props */) => [
+    valueFromProps: (/* props */) => [
         "Apple",
         "Banana",
         "Crumpets"
@@ -81,7 +81,7 @@ const FruitListEditor = (props) => {
 };
 
 const FruitListParcelHoc = ParcelHoc({
-    initialValue: (/* props */) => [
+    valueFromProps: (/* props */) => [
         "Apple",
         "Banana",
         "Crumpets"

diff --git a/packages/dataparcels-docs/src/pages/examples/editing-objects.md b/packages/dataparcels-docs/src/pages/examples/editing-objects.md
@@ -22,7 +22,7 @@ import {ParcelHoc, ParcelBoundary} from 'react-dataparcels';
 
 const PersonParcelHoc = ParcelHoc({
     name: "personParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         firstname: "Robert",
         lastname: "Clamps",
         address: {

diff --git a/packages/dataparcels-docs/src/pages/examples/parcelboundary-debounce.md b/packages/dataparcels-docs/src/pages/examples/parcelboundary-debounce.md
@@ -13,7 +13,7 @@ import {ParcelHoc, ParcelBoundary} from 'react-dataparcels';
 
 const FoodParcelHoc = ParcelHoc({
     name: "foodParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         mains: "Soup",
         dessert: "Strudel"
     })

diff --git a/packages/dataparcels-docs/src/pages/examples/parcelboundary-example.md b/packages/dataparcels-docs/src/pages/examples/parcelboundary-example.md
@@ -13,7 +13,7 @@ import {ParcelHoc, ParcelBoundary} from 'react-dataparcels';
 
 const PersonParcelHoc = ParcelHoc({
     name: "personParcel",
-    initialValue: (/* props */) => ({
+    valueFromProps: (/* props */) => ({
         name: {
             first: "Robert",
             last: "Clamps"

diff --git a/packages/dataparcels-docs/src/pages/examples/parcelboundary-forceUpdate.md b/packages/dataparcels-docs/src/pages/examples/parcelboundary-forceUpdate.md
@@ -15,7 +15,7 @@ import {ParcelHoc, ParcelBoundary} from 'react-dataparcels';
 
 const ColourParcelHoc = ParcelHoc({
     name: "colourParcel",
-    initialValue: (/* props */) => "Option A"
+    valueFromProps: (/* props */) => "Option A"
 });
 
 const ColourEditor = (props) => {

diff --git a/packages/dataparcels-docs/src/pages/examples/parcelboundary-hold.md b/packages/dataparcels-docs/src/pages/examples/parcelboundary-hold.md
@@ -13,7 +13,7 @@ import {ParcelHoc, ParcelBoundary} from 'react-dataparcels';
 
 const NameParcelHoc = ParcelHoc({
     name: "nameParcel",
-    initialValue: (/* props */) => "Gregor"
+    valueFromProps: (/* props */) => "Gregor"
 });
 
 const FoodEditor = (props) => {

diff --git a/packages/dataparcels-docs/src/pages/examples/parcelhoc-delayuntil.md b/packages/dataparcels-docs/src/pages/examples/parcelhoc-delayuntil.md
@@ -1,7 +1,7 @@
 import Link from 'gatsby-link';
 import ParcelHocExampleDelayUntil from 'examples/ParcelHocExampleDelayUntil';
 
-This example shows how to delay the creation of a Parcel with `ParcelHoc`. The example counts the number of seconds that have passed, and passes this into the `DelayExample` component. The `ParcelHoc` is set to delay until seconds > 3. Once seconds = 4, `initialValue` is called and the Parcel is created.
+This example shows how to delay the creation of a Parcel with `ParcelHoc`. The example counts the number of seconds that have passed, and passes this into the `DelayExample` component. The `ParcelHoc` is set to delay until seconds > 3. Once seconds = 4, `valueFromProps` is called and the Parcel is created.
 
 <Link to="/api/ParcelHoc#delayUntil">API reference for ParcelHoc.delayUntil</Link>
 
@@ -13,7 +13,7 @@ import {ParcelHoc} from 'react-dataparcels';
 
 const DelayParcelHoc = ParcelHoc({
     name: "delayParcel",
-    initialValue: (props) => `Created at ${props.seconds} seconds!`,
+    valueFromProps: (props) => `Created at ${props.seconds} seconds!`,
     delayUntil: (props) => props.seconds > 3
 });
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,4 +6,4 @@ pipe?: (props: Object) => (parcel: Parcel) => Parcel // optional

		This function gives you the opportunity to modify the parcel before it reaches any other components.

		The `pipe` function expects to be given a double barrel function. The first function will be passed `props`, and the next is passed the Parcel. The result of the `pipe` function will then be passed down as props.
		The `pipe` function expects to be given a double barrel function. The first function will be passed `props`, and the next is passed the Parcel. The result of the `pipe` function will then be passed down as a prop.