Update README Content

README.md

@@ -535,7 +535,7 @@ class MyWidget extends WidgetBase {
 
 The `Registry` provides a mechanism to define widgets and injectors (see the [`Containers & Injectors`](#containers--injectors) section), that can be dynamically/lazily loaded on request. Once the registry widget is loaded all widgets that need the newly loaded widget will be invalidated and re-rendered automatically.
 
-A main registry can be provided to the `projector`, which will be automatically passed to all widgets within the tree (referred to as `baseRegistry`). Each widget also gets a access to a private `Registry` instance that can be used to define widget specific registry items. The locally defined registry items are considered a higher precedence than an item registered in the `baseRegistry`.
+A main registry can be provided to the `projector`, which will be automatically passed to all widgets within the tree (referred to as `baseRegistry`). Each widget also gets access to a private `Registry` instance that can be used to define registry items the are scoped to the widget. The locally defined registry items are considered a higher precedence than an item registered in the `baseRegistry`.
 
 ```ts
 import { Registry } from '@dojo/widget-core/Registry';
@@ -551,9 +551,9 @@ registry.defineInjector('my-injector', MyInjector);
 projector.setProperties({ registry });
 ```
 
-In some scenarios, it might be desirable to allow the `baseRegistry` override the an item defined in the local `registry`. To do this use pass `true` as the second argument of the `registry.get` function.
+In some scenarios, it might be desirable to allow the `baseRegistry` to override an item defined in the local `registry`. Use true as the second argument of the registry.get function to override the local item.
 
-The following example, sets a default loading indicator widget but passes `true` when getting the widget from the `registry`. This allows a consumer to register an overriding loading indicator in the `baseRegistry`.
+The following example sets a default loading indicator widget, but passes `true` when getting the widget from the `registry`. This allows a consumer to register an overriding loading indicator in the `baseRegistry`.
 
 ```ts
 class MyWidget extends WidgetBase {
@@ -573,17 +573,19 @@ class MyWidget extends WidgetBase {
 
 ### Lifecycle Hooks
 
-Occasionally, in a mixin or a widget class, it my be required to provide logic that needs to be executed before properties are diffed (`beforeProperties`) or either side `render` call (`beforeRender` & `afterRender`). This functionality is provided by the `beforeProperties`, `beforeRender` and `afterRender` decorators that can be found in the `decorators` directory.
+Occasionally, in a mixin or a widget class, it my be required to provide logic that needs to be executed before properties are diffed using `beforeProperties` or either side of a widget's `render` call using `beforeRender` & `afterRender`.
+
+This functionality is provided by the `beforeProperties`, `beforeRender` and `afterRender` decorators that can be found in the `decorators` directory.
 
 ***Note:*** All lifecycle functions are executed in the order that they are specified from the super class up to the final class.
 
 ##### beforeProperties
 
-The `beforeProperties` lifecycle hook is called immediately before property diffing is executed. Functions registered for `beforeProperties` receive `properties` and are required to to return any updated, changed `properties` that are assigned over the existing properties.
+The `beforeProperties` lifecycle hook is called immediately before property diffing is executed. Functions registered for `beforeProperties` receive `properties` and are required to return any updated, changed `properties` that are mixed over (merged) the existing properties.
 
 As the lifecycle is executed before the property diffing is completed, any new or updated properties will be included in the diffing phase.
 
-Example that demonstrates adding an extra property based on the widgets current properties, using a function declared on the widget class `myBeforeProperties`.
+An example that demonstrates adding an extra property based on the widgets current properties, using a function declared on the widget class `myBeforeProperties`:
 
 ```ts
 class MyClass extends WidgetBase<MyClassProperties> {
@@ -600,7 +602,7 @@ class MyClass extends WidgetBase<MyClassProperties> {
 
 ##### BeforeRender
 
-The `beforeRender` lifecycle hook receives the widget's `render` function, `properties` and `children` and is expected to return a function that satisfies the `render` API. The `properties` and `children` are passed to enable them to be manipulated or decorated prior to the `render` being called.
+The `beforeRender` lifecycle hook receives the widget's `render` function, `properties` and `children` and is expected to return a function that satisfies the `render` API. The `properties` and `children` are passed to enable them to be manipulated or decorated prior to `render` being called.
 
 **Note:** When `properties` are changed during the `beforeRender` lifecycle, they do not go through the standard property diffing provided by `WidgetBase`. If the changes to the `properties` need to go through diffing, consider using the `beforeProperties` lifecycle hook.
 
@@ -621,7 +623,7 @@ class MyClass extends WidgetBase {
 
 ##### AfterRender
 
-The `afterRender` lifecycle hook receives the returned `DNode`s from a widget's `render` call, so that the nodes can be decorated, manipulated or even swapped out.
+The `afterRender` lifecycle hook receives the returned `DNode`s from a widget's `render` call, so that the nodes can be decorated, manipulated or swapped completely.
 
 ```ts
 class MyBaseClass extends WidgetBase<WidgetProperties> {
@@ -635,7 +637,7 @@ class MyBaseClass extends WidgetBase<WidgetProperties> {
 
 ### Containers & Injectors
 
-There is built in support for side-loading/injecting values into sections of the widget tree and mapping them to a widget's properties. This is achieved by registering a `@dojo/widget-core/Injector` instance, against a `registry` that is available to your application (i.e. set on the projector instance, `projector.setProperties({ registry })`).
+There is built in support for side-loading/injecting values into sections of the widget tree and mapping them to a widget's properties. This is achieved by registering a `@dojo/widget-core/Injector` instance against a `registry` that is available to your application (i.e. set on the projector instance, `projector.setProperties({ registry })`).
 
 Create an `Injector` instance and pass the `payload` that needs to be injected to the constructor:
 
@@ -644,9 +646,9 @@ const injector = new Injector({ foo: 'baz' });
 registry.defineInjector('my-injector', injector);
 ```
 
-To connect the registered `injector` to a widget we can use the `Container` HOC (higher order component) provided by `widget-core`. The `Container` accepts a widget `constructor`, `injector` label and `getProperties` mapping function as arguments and returns a new class that returns the passed widget from its `render` function.
+To connect the registered `injector` to a widget, we can use the `Container` HOC (higher order component) provided by `widget-core`. The `Container` accepts a widget `constructor`, `injector` label and `getProperties` mapping function as arguments and returns a new class that returns the passed widget from its `render` function.
 
-`getProperties` receives the `payload` from an `injector` and `properties` from the container HOC component, that are used to map into the wrapped widgets properties.
+`getProperties` receives the `payload` from an `injector` and `properties` from the container HOC component. These are used to map into the wrapped widgets properties.
 
 ```ts
 import { Container } from '@dojo/widget-core/Container';
@@ -661,7 +663,7 @@ function getProperties(payload: any, properties: any) {
 export const MyWidgetContainer = Container(MyWidget, 'my-injector', getProperties);
 ```
 
-The returned class from `Container` HOC is then be used in place widget it wraps, not although the container assumes the properties type of the wrapped widget, they all become optional.
+The returned class from `Container` HOC is then used in place of the widget it wraps, the container assumes the properties type of the wrapped widget, however they all considered optional.
 
 ```ts
 // import { MyWidget } from './MyWidget';
@@ -681,11 +683,11 @@ class App extends WidgetBase<AppProperties> {
 }
 ```
 
-**Please Note:** Don't use container as the top level application widget, containers always `render` which means that you'll find your application is calling `render` every request animation frame even if there is no need for the `render`.
+**Please Note:** Do not use container as the top level application widget, containers always `render` which means that you will find your application is calling `render` upon every request animation frame, even when there is no need for an additional `render`.
 
 ### Decorators
 
-All built-in decorators can be used in non-decorator environments (Either JavaScript/ES6 or a TypeScript project that does not have the experimental decorators configuration set to true in the `tsconfig`) programmatically calling them directly, usually within a Widget classes `constructor`.
+All core decorators provided by widget-core, can be used in non-decorator environments (Either JavaScript/ES6 or a TypeScript project that does not have the experimental decorators configuration set to true in the `tsconfig`) programmatically by calling them directly, usually within a Widget class' `constructor`.
 
 Example usages:
 
@@ -710,7 +712,7 @@ The currently supported options:
 |-|-|
 |`onAttached`|A callback that is called when the wrapped DOM is flowed into the virtual DOM|
 
-For example, if we want to integrate a 3rd party library where we need to pass the component factory a _root_ element and then flow that into our virtual DOM.  In this situation we do not want to create the component until the widget is being flowed into the DOM, so `onAttached` is used to perform the creation of the component:
+For example, if we want to integrate a third-party library where we need to pass the component factory a _root_ element and then flow that into our virtual DOM.  In this situation we do not want to create the component until the widget is being flowed into the DOM, so `onAttached` is used to perform the creation of the component:
 
 ```ts
 import { w } from '@dojo/widget-core/d';