@webkrafters/react-observable-context 2.1.7 → 2.1.9

package/README.md

@@ -1,36 +1,40 @@
 # React-Observable-Context
 
-A context bearing an observable consumer store. State changes within the store's internal state are only broadcasted to components subscribed to the store. In this way, the `React-Observable-Context` prevents repeated automatic re-renderings of entire component trees resulting from ***context*** state changes.
+Only re-renders subscribing components on context state change. A subscribing component decides which context state properties' change trigger its update.
 
-**React::memo** *(and PureComponents)* remain the go-to solution for the repeated automatic re-renderings of entire component trees resulting from ***component*** state changes. 
+**Name:** React-Observable-Context
 
-_**Recommendation:**_ For optimum performance, consider wrapping in **React::memo** most components using this package's ***useContext*** function either directly or through another React hook. This will protect such components and their descendants from unrelated cascading render operations.
+**Usage:** Please see [Usage](#usage) section
 
-***Exempt*** from the recommendation are certain components such as those wrapped in the `React-Redux::connect()` Higher Order Component (HOC). Such HOC provides similar cascade-render protections to wrapped components and their descendants. 
+**Install:**\
+npm i -S @webkrafters/react-observable-context\
+npm install --save @webkrafters/react-observable-context
 
-<hr />
+# Intro
 
-<h3><u>Install</u></h3>
+A context bearing an observable consumer [store](#store). State changes within the store's internal state are only broadcasted to components subscribed to the store. In this way, the `React-Observable-Context` prevents repeated automatic re-renderings of entire component trees resulting from ***context*** state changes.
 
-npm i -S @webkrafters/react-observable-context
+**React::memo** *(and PureComponents)* remain the go-to solution for the repeated automatic re-renderings of entire component trees resulting from ***component*** state changes. 
 
-npm install --save @webkrafters/react-observable-context
+***Recommendation:*** For optimum performance, consider wrapping in **React::memo** most components using this package's ***useContext*** function either directly or through another React hook. This will protect such components and their descendants from unrelated cascading render operations.
+
+***Exempt*** from the recommendation are certain components such as those wrapped in the `React-Redux::connect()` Higher Order Component (HOC). Such HOC provides similar cascade-render protections to wrapped components and their descendants. 
 
-## API
+# API
 
 The React-Observable-Context package exports **4** modules namely: the **createContext** method, the **useContext** hook, the **Provider** component and the **UsageError** class.
 
-* **createContext** is a zero-parameter funtion returning a store-bearing context. Pass the context to the React::useContext() parameter to obtain the context's `store`.
+* **createContext** is a zero-parameter function returning a store-bearing context. Pass the context as a `context` parameter to the [useContext()](#usecontext) to obtain the context's [store](#store).
 
-* **useContext** is analogous to React::useContext hook but returns the context store and takes a second parameter named ***watchedKeys***. The `watchedKeys` parameter is a list of state object property paths to watch. A change in any of the referenced properties automatically triggers a render of the component calling this hook.
+* <b id="usecontext">useContext</b> is analogous to React::useContext hook but returns the context store and takes a second parameter named ***watchedKeys***. The `watchedKeys` parameter is a list of state object property paths to watch. A change in any of the referenced properties automatically triggers a render of the component calling this hook.
 
-* **Provider** can immediately be used as-is anywhere the React-Observable-Context is required. It accepts **3** props and the customary Provider `children` prop. Supply the context to its `context` prop; the initial state to the customary Provider `value` prop; and the optional `prehooks` prop <i>(discussed in the prehooks section below)</i>.
+* **Provider** can immediately be used as-is anywhere the React-Observable-Context is required. It accepts **3** props and the customary Provider `children` prop. Supply the context to its `context` prop; the initial state to the customary Provider `value` prop; and the optional `prehooks` prop <i>(discussed in the [prehooks](#prehooks) section below)</i>.
 
 * **UsageError** class is the Error type reported for attempts to access this context's store outside of its Provider component tree.
 
 ***<u>Note:</u>*** the Provider `context` prop is not updateable. Once set, all further updates to this prop are not recorded.
 
-### The Store
+## Store
 
 The context's `store` exposes **4** methods for interacting with the context's internal state namely:
 
@@ -39,12 +43,12 @@ The context's `store` exposes **4** methods for interacting with the context's i
 * **resetState**: VoidFunction // resets the state to the Provider initial `value` prop.
 
 * **setState**: (changes: PartialState\<State\>) => void // sets only new/changed state slices.\
-***Do this:*** `setState({stateKey0: changes0[, ...]});`\
-***Not this:*** `setState({stateKey0: {...state.stateKey0, ...changes0}[, ...]});`
+***Do this:*** <code style="color:#080">setState({stateKey0: changes0[, ...]});</code>\
+***Not this:*** <code style="color:#800">setState({stateKey0: {...state.stateKey0, ...changes0}[, ...]});</code>
 
 * **subscribe**: (listener: (newValue: PartialState\<State\>, oldValue: PartialState\<State\>) => void) => ***UnsubscribeFunction***
 
-### Prehooks
+## Prehooks
 
  Prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates.
 
@@ -58,9 +62,9 @@ The context's `store` exposes **4** methods for interacting with the context's i
 
 ***<u>Use case:</u>*** prehooks provide a central place for sanitizing, modifying, transforming, validating etc. all related incoming state updates.
 
-## Usage
+# Usage
 
-<i><u>context.js</u></i>
+### <u>*context.js*</u>
 
     import React from 'react';
 
@@ -87,14 +91,14 @@ The context's `store` exposes **4** methods for interacting with the context's i
 
 	export default ObservableContext;
 
-<i><u>index.js</u></i>
+### <u>*index.js*</u>
 
     import React from 'react';
     import ReactDOM from 'react-dom';
     import App from './app';
     ReactDOM.render(<App />, document.getElementById('root'));
 
-<i><u>app.js</u></i>
+### <u>*app.js*</u>
 
     import React, { useCallback, useState } from 'react';
 	import Product from './product';
@@ -128,7 +132,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	App.displayName = 'App';
 	export default App;
 
-<i><u>product.js</u></i>
+### <u>*product.js*</u>
 
 	import React, { useCallback, useEffect, useState } from 'react';
 	import { ObservableContextProvider } from './context';
@@ -173,7 +177,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	Product.displayName = 'Product';
 	export default Product;
 
-<i><u>editor.js</u></i>
+### <u>*editor.js*</u>
 
     import React, { memo, useCallback, useEffect, useRef } from 'react';
 	import { useObservableContext } from './context';
@@ -216,7 +220,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	Editor.displayName = 'Editor';
 	export default Editor;
 
-<i><u>price-sticker.js</u></i>
+### <u>*price-sticker.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -233,7 +237,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	PriceSticker.displayName = 'PriceSticker';
 	export default PriceSticker;
 
-<i><u>product-description.js</u></i>
+### <u>*product-description.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -252,7 +256,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	ProductDescription.displayName = 'ProductDescription';
 	export default ProductDescription;
 
-<i><u>tally-display.js</u></i>
+### <u>*tally-display.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -279,7 +283,7 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	TallyDisplay.displayName = 'TallyDisplay';
 	export default TallyDisplay;
 
-<i><u>reset.js</u></i>
+### <u>*reset.js*</u>
 
     import React, { memo, useEffect } from 'react';
 	import { useObservableContext } from './context';
@@ -292,6 +296,6 @@ The context's `store` exposes **4** methods for interacting with the context's i
 	export default Reset;
 
 
-## License
+# License
 
 MIT

package/package.json

@@ -79,5 +79,5 @@
     "test:watch": "eslint --fix && jest --updateSnapshot --watchAll"
   },
   "types": "dist/index.d.ts",
-  "version": "2.1.7"
+  "version": "2.1.9"
 }