reaction-hooks 1.0.1 → 1.0.2

package/README.md

@@ -4,11 +4,11 @@ Hooks for [Reaction](https://github.com/djalbat/reaction).
 
 These are inspired by React's hooks but do not follow them slavishly. Three are three available:
 
-* `useState()` A state management hook that does indeed closely follow React's hook of the same name. It also supports created classes and components, however.
-* `useContext()` A hook that leverages contexts in order to enable components directly related to one another in the DOM to communicate. Typically component methods are passed via the context so that one component can call the methods of another.
-* `useEffects()` A hook that use Reaction's in-built updates functionality in order to enable components to communicate no matter their relative positions in the DOM. It is also possible to communicate with other parts of an application in this manner.
+* `useState()` A state management hook that does indeed slavishly follow React's hook of the same name. It also supports created classes and components, however.
+* `useContext()` A hook that leverages contexts in order to enable directly related components to communicate. Typically component methods are passed via the context so that one component can call the methods of another.
+* `useEffects()` A hook based around Reaction's update functionality in order to enable components to communicate no matter how they are related. It is also possible for components to communicate with other parts of an application and vice-versa using effects.
 
-The `useEffects()` hook in fact bears very little resemblance to React's hook of the same name and is more akin to [Inference](https://github.com/djalbat/inference) but without the rules.   
+The `useEffects()` hook in fact bears very little resemblance to React's hook of the same name and is more akin to [Inference](https://github.com/djalbat/inference) albeit without the rules.   
 
 ## Installation
 
@@ -28,7 +28,7 @@ You can also run a development server, see the section on building later on.
 
 ## Usage
 
-The three hooks are imported thus:
+The hooks are imported thus:
 
 ```
 import { useState, useContext, useEffects } from "reaction-hooks";
@@ -44,11 +44,25 @@ Detailed usages are outlined in the recommanded patterns section that follows th
 
 ## Example
 
-Launch the `example.html` file. There is a single hooks example which encapsulates all of the hooks.
+There is a small development server that can be run from within the project's directory with the following command:
+
+    npm start
+
+The example will then be available at the following URL:
+
+http://localhost:8888
+
+The source for the example can be found in the `src/example.js` file and corresponding`src/example` folder. You are encouraged to try the example whilst reading what follows. You can rebuild it on the fly with the following command:
+
+    npm run watch-debug
+
+The development server will reload the page whenever you make changes.
+
+One last thing to bear in mind is that this package is included by way of a relative rather than a package import. If you are importing it into your own application, however, you should use the standard package import.
 
 ## Recommended patterns
 
-Each of the hooks are covered with the listings closely matching the example code.
+Each of the hooks are covered in turn with the listings closely matching the example code.
 
 ### `useState()`
 
@@ -73,9 +87,9 @@ const FunctionUseStateParagraph = (props, context, update, element) => {
 ```
 Note that the last of the four function arguments is a reference to the function's corresponding element. The details are unimportant, however this reference must be passed as the first argument of the `useState()` call. Otherwise the usage is entirely analogous to the corresponding React hook.
 
-Because the `useState()` hook is passed a reference to the corresponding element under the hood, so to speak, it should come as no surprise that can also support created classes and components, which also both have corresponding underlying elements.
+Because the `useState()` hook is passed a reference to the corresponding element it can also support created classes and components, which also both have corresponding underlying elements.
 
-The second way is with created classes. The name is a misnomer as they are not classes and they are, with the advent of components, rarely if ever used anymore. Nonetheless they are supported:
+To continue, the second way is with created classes. The name is a misnomer as they are not classes at all. With the advent of components they rarely if ever used, nonetheless they continue to be supported:
 
 ```
 const { createClass } = React;
@@ -97,7 +111,7 @@ const CreateClassUseStateParagraph = createClass({
 });
 ```
 
-Essentially the only difference between this usage and the functional usage is that the `useState()` call takes place within the `render()` function.
+Note that the `useState()` call takes place within the `render()` function.
 
 Lastly, genuine components, which are treated identically:
 
@@ -121,13 +135,13 @@ export default class ComponentUseStateParagraph extends Component {
 }
 ```
 
-Of course created classes and components support state without the need for a hook. At the risk of repetition, support for the `useState()` hook cost virtually nothing and is included more for the sake of completeness than for anything else.
+Of course created classes and components support state without the need for a hook.
 
 ### `useContext()`
 
 This hook can be used comprehensively to share information, most likely methods, between components and the like that are directly related in the DOM. What this means is that in order for one component to share information with another it must be a descendant of the other or vice-versa. Since this hook leverages contexts, perhaps this is not so surprising. In fact another lifecycle method, namely the `childContextSet()`lifecycle method, was added to Reaction in order to support it. 
 
-At the topmost level of the example component both this lifecycle method and the more commonly known `setChildContext()` lifecycle method are utilised: 
+At the topmost level of the example component both this lifecycle method and the `setChildContext()` lifecycle method are utilised: 
 
 ```
 getChildContext(context) {
@@ -145,7 +159,7 @@ childContextSet(childContext) {
 }
 ```
 
-This usage is noteworthy because it does not make use of the `useContext()` hook at all. A more primitive approach is used here to emphasise the fact that the object created in the `createChildContext()` lifecycle method is not only passed down to the component's children but is also precisely the one that is passed to the component's own  `childContextSet()` lifecycle method.
+This usage is noteworthy because it does not make use of the `useContext()` hook at all. A more primitive approach is used here to emphasise the fact that the object created in the `createChildContext()` lifecycle method is not only passed down to the component's descendants but is also precisely the one that is passed to the component's own  `childContextSet()` lifecycle method.
 
 A more conventional and indeed the recommended approach is to make use of the `useContetx()` hook in both lifecycle methods in each of its respective guises:
 
@@ -163,12 +177,12 @@ getChildContext(context) {
 }
 
 childContextSet(childContext) {
-  useContext(this. childContext);
+  useContext(this, childContext);
 }
 ```
-In the `getChildContext()` lifecycle method, two of the topmost component's own methods are assigned to the context, a reference to which is then passed to the component's children. Conversely, in the `childContextSet()` lifecycle method, whatever methods are on the child context at this point, which will have been assigned by the children, are assigned to the topmost component.
+In the `getChildContext()` lifecycle method, two of the topmost component's own methods are assigned to the context, which is then passed to the component's descendants. Conversely, in the `childContextSet()` lifecycle method, whatever methods are on the child context at this point, which will have been assigned by the topmost component's descendants, are assigned to the topmost component.
 
-Beginning to look down at the component's children, we see that the `GotItHeader` component adds two of its own methods to the context:
+Beginning to look down at the component's descendants, we see that the `GotItHeader` component adds two of its own methods to the context:
 
 ```
 export default class GotItHeader extends Component {
@@ -187,7 +201,7 @@ export default class GotItHeader extends Component {
   ...
 }
 ```
-These will eventually be picked up by the topmost component in its aforementioned `childContextSet()` lifecycle method. Indeed we can see which methods of the component's children it ends up assigning to itself by looking at some of its other methods:
+These will eventually be picked up by the topmost component in its aforementioned `childContextSet()` lifecycle method. Indeed we can see which methods of the component's descendants it ends up assigning to itself by looking at some of its other methods:
 
 ```
 close() {
@@ -201,7 +215,20 @@ open() {
 }
 ```
 
-By way of contrast, the descendant `OpenLinkButton` component grabs one of the topmost component's methods from the context and assigns it to itself. The method is then made use of in its `render()` method:
+Therefore in order to be explicit we could have written:
+
+```
+childContextSet(childContext) {
+  useContext(this, childContext, [
+    "showGotItDiv",
+    "hideGotItDiv",
+    "showGotItHeader",
+    "hideGotItHeader"
+  ]);
+}
+```
+
+By way of contrast, the descendant `OpenLinkButton` component grabs one of the topmost component's methods from the context and assigns it to itself. The method is then made use of in its own `render()` method:
 
 ```
 export default class OpenLinkButton extends Component {
@@ -212,20 +239,21 @@ export default class OpenLinkButton extends Component {
   }
 
   render(update) {
-    const { children } = this.props,
+    const { descendants } = this.props,
           clickHandler = this.openLinkButtonClickHandler;  ///
 
     return (
 
       <button className="open link" onClick={clickHandler}>
-        {children}
+        {descendants}
       </button>
 
     );
   }
 }
 ```
-Essentially then the `useContext()` hook allows methods and the like to piggy back on the context, so to speak, so that components can pick them up and make use of them. Thus related components can call methods on each other without the need for more complex or indirect mechanisms such as message passing.
+
+To summarise, the `useContext()` hook allows methods and the like to piggy back on the context, so to speak, so that components can pick them up and make use of them. Thus related components can call methods on each other without the need for more complex or indirect mechanisms such as message passing.
 
 ### `useEffects()`
 
@@ -310,9 +338,9 @@ updatehandler(update) {
 }
 ```
 
-Underneath the hood the `forceUpdate()` method will unmount the component's children and then mount the new children returned by invoking the component's `render()` method, which is passed the requisite update. In fact the update is just a plain old JavaScript object the single property of which is named after the effect and its value is the effect itself. 
+Underneath the hood the `forceUpdate()` method will unmount the component's descendants and then mount the new descendants returned by invoking the component's `render()` method, which is passed the requisite update. In fact the update is just a plain old JavaScript object the single property of which is named after the effect and its value is the effect itself. 
 
-Finally, note that a component or indeed any part of the application can be configured to listen to several effects as additional arguments to the `useEffects()` hook, hence the use of the plural, in which cases the encapculation of each effect in a plain old JavaScript object becomes invaluable for ascertaining which effect has been emitted. 
+Finally, note that a component or indeed any part of the application can be configured to listen to several effects as additional arguments to the `useEffects()` hook, hence the use of the plural, in which cases the encapsulation of each effect in a plain old JavaScript object becomes invaluable for ascertaining which effect has been emitted. 
 
 ## Building
 
@@ -321,12 +349,6 @@ Automation is thanks to [npm scripts](https://docs.npmjs.com/misc/scripts), have
     npm run build-debug
     npm run watch-debug
 
-You can also start a small development server:
-
-    npm start
-
-The example will then be available at http://localhost:8888 and will reload automatically when changes are made.
-
 ## Contact
 
 - james.smith@djalbat.com

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reaction-hooks",
   "author": "James Smith",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/reaction-hooks",
   "description": "Hooks for Reaction.",