@expressive/mvc 1.0.0-beta.2 → 1.0.0-beta.23

package/README.md

@@ -14,22 +14,28 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@expressive/mvc"><img alt="NPM" src="https://badge.fury.io/js/%40expressive%2Fmvc.svg"></a>
   <a href=""><img alt="Build" src="https://shields-staging.herokuapp.com/npm/types/@expressive/mvc.svg"></a>
+  <img src="https://img.shields.io/badge/Coverage-100%25-brightgreen.svg">
 </p>
 
 <p align="center">
-  Define classes to power UI, by extending <code>Model</code>.<br/>
+  Define classes to power UI by extending <code>Model</code>.<br/>
   Builtin hooks will manage renders, as needed, for any data.<br/>
   When properties change, your components will too.<br/>
 </p>
 
 <br/>
-<h1 id="overview-section">Overview</h1>
+<p align="center">
+  <b>Have suggestions, need help or just want to discuss?</b><br/><br/>
+  <a href="https://join.slack.com/t/expressivejs/shared_invite/zt-s2j5cdhz-gffKn3bTATMbXf~iq4pvHg" alt="Join Slack">
+    <img src="https://img.shields.io/badge/Slack-Come%20say%20hi!-blueviolet" />  
+  </a>
+</p>
 
-By extending `Model`, classes can contain state and logic for components. Models are easy to define, use and even provide. They limit complexity, and help make components dumber without sacrificing features. 
+<br/>
+<h1 id="overview-section">Overview</h1>
 
-When a static-methods are used in a component, an instance is found or created for its use. By watching what values are accessed on render, the hook itself will refresh and keep sync with them.
+Classes which extend `Model` can manage behavior for components. Custom models are easy to define, use and even provide. While hooks are great, state and logic are not a part of well-formed JSX. Models help wrap that stuff in robust, portable controllers instead.
 
-This behavior combines with actions, computed properties, events, and components themselves to facilitate a **M**odel-**V**iew-**C**ontroller pattern in React.
 
 <br/>
 
@@ -50,7 +56,7 @@ class Counter extends Model {
 
 ### Step 2
 
-Pick a built-in hook, such as `use()`, to make your component stateful.
+Pick a built-in hook, such as `use()`, to make a component stateful.
 
 ```jsx
 const KitchenCounter = () => {
@@ -70,10 +76,10 @@ const KitchenCounter = () => {
 [See it in action](https://codesandbox.io/s/example-counter-th8xl) 🚀  You've already got something usable!
 
 <br/>
-<h1 id="good-start">Things you can do</h1>
+<h2 id="good-start">Things you can do</h2>
 
-### Combine any number of `useState` values
-Place any data in your model. Updating any value will trigger a render.
+### Track any number of values
+Updating any of them will trigger a render.
 
 ```jsx
 class State extends Model {
@@ -88,9 +94,10 @@ const MyComponent = () => {
   return <div>...</div>
 }
 ```
+<br/>
 
 ### Refresh using simple assignment
-Reserved `set` loops back to instance, to update from inside a component.
+Reserved `set` loops back to the instance, to update from inside a component.
 
 ```jsx
 class Hello extends Model {
@@ -107,36 +114,36 @@ const MyComponent = () => {
   )
 }
 ```
+<br/>
 
 ### Share state via context
-Models can provide and consume state with static methods. Classes themselves act as a key.
+Provide and consume with simple methods. Classes are their own key.
 
 ```jsx
 import Model, { Provider } from "@expressive/mvc";
 
 class Shared extends Model {
-  foo = 1;
-  bar = 2;
+  value = 1;
 }
 
 const Parent = () => (
   <Provider of={Shared}>
-    <Foo />
-    <Bar />
+    <Child />
   </Provider>
 )
 
-const Foo = () => {
-  const { foo } = Shared.tap();
+const Child = () => {
+  const { value } = Shared.get();
 
   return (
-    <p>Value of shared foo is {foo}!</p>
+    <p>Shared value is: {value}!</p>
   )
 }
 ```
+<br/>
 
-### Respond to component lifecycle
-Hooks are aware of lifecycle and will call method-handlers you define.
+### Respond to lifecycle
+Hooks aware of lifecycle will call method-handlers you define.
 
 ```jsx
 class Timer extends Model {
@@ -145,7 +152,6 @@ class Timer extends Model {
 
   componentDidMount(){
     const inc = () => this.elapsed++;
-
     this.interval = setInterval(inc, 1000);
   }
 
@@ -157,20 +163,21 @@ class Timer extends Model {
 const MyTimer = () => {
   const { elapsed } = Timer.use();
 
-  return <pre>I've existed for { elapsed } seconds!</pre>;
+  return <p>I've existed for { elapsed } seconds!</p>;
 }
 ```
+<br/>
 
 ### Control components with `async`
 
 ```jsx
 class Greetings extends Model {
   response = undefined;
-  thinking = false;
+  waiting = false;
   error = false;
 
   sayHello = async () => {
-    this.thinking = true;
+    this.waiting = true;
 
     try {
       const res = await fetch("https://my.api/hello");
@@ -183,15 +190,15 @@ class Greetings extends Model {
 }
 
 const MyComponent = () => {
-  const { error, response, thinking, sayHello } = Greetings.use();
+  const { error, response, waiting, sayHello } = Greetings.use();
 
   if(response)
     return <p>Server said: {response}</p>
 
   if(error)
-    return <p>There was an issue saying hello :(</p>
+    return <p>There was an issue saying hello</p>
 
-  if(thinking)
+  if(waiting)
     return <p>Sent! Waiting on response...</p>
 
   return (
@@ -199,14 +206,17 @@ const MyComponent = () => {
   )
 }
 ```
+<br/>
 
-### Extend and reuse logic
-Custom models can be extended, to add features or to set required properties. This makes reusable logic is easy to store, document and share. 
+### Extend to configure
+Use class extension to set needed properties.
+Reusable logic is easy to implement, document and share. 
 
 ```ts
 abstract class About extends Model {
   abstract name: string;
   abstract birthday: Date;
+  abstract wants: any;
 
   happyBirthday(){
     // ...
@@ -216,11 +226,13 @@ abstract class About extends Model {
 class AboutMe extends About {
   name = "John Doe";
   birthday = new Date("January 1");
-  wants = "PS5";
+  wants = "a PS5";
 }
 ```
 
-#### ... and plenty more.
+</br>
+
+#### And you can do more, all with type safety and code-assist, out of the box.
 
 </br>
 
@@ -243,9 +255,9 @@ class AboutMe extends About {
   &ensp; •&nbsp; [Lifecycle](#concept-lifecycle) <br/>
   &ensp; •&nbsp; [Events](#concept-events) <br/>
   &ensp;&ensp;&ensp; ◦&nbsp; [Listening](#concept-listen-event) <br/>
-  &ensp;&ensp;&ensp; ◦&nbsp; [Dispatching](#concept-push-event) <br/>
+  &ensp;&ensp;&ensp; ◦&nbsp; [Dispatch](#concept-push-event) <br/>
   &ensp;&ensp;&ensp; ◦&nbsp; [Built-in](#concept-builtin-events) <br/>
-  &ensp; •&nbsp; [Monitored Externals](#concept-external) <br/>
+  &ensp; •&nbsp; [Monitored Props](#concept-external) <br/>
   &ensp; •&nbsp; [Async and callbacks](#concept-async) <br/>
 
 **Shared State** <br/>
@@ -262,10 +274,10 @@ class AboutMe extends About {
   &ensp;&ensp;&ensp; ◦&nbsp; [`get`](#method-get) <br/>
   &ensp;&ensp;&ensp; ◦&nbsp; [`tap`](#method-tap) <br/>
   &ensp; •&nbsp; [Consumer](#concept-consumer) <br/>
-  &ensp;&ensp;&ensp; ◦&nbsp; [render](#consumer-render) <br/>
-  &ensp;&ensp;&ensp; ◦&nbsp; [`get` prop](#consumer-get) <br/>
-  &ensp;&ensp;&ensp; ◦&nbsp; [`tap` prop](#consumer-tap) <br/>
-  &ensp;&ensp;&ensp; ◦&nbsp; [`has` prop](#consumer-has) <br/>
+  &ensp;&ensp;&ensp; ◦&nbsp; [children](#consumer-render) <br/>
+  &ensp;&ensp;&ensp; ◦&nbsp; [`get`](#consumer-get) <br/>
+  &ensp;&ensp;&ensp; ◦&nbsp; [`tap`](#consumer-tap) <br/>
+  &ensp;&ensp;&ensp; ◦&nbsp; [`has`](#consumer-has) <br/>
   
 **Composition** <br/>
   &ensp; •&nbsp; [Simple Composition](#concept-compose) <br/>
@@ -288,11 +300,11 @@ class AboutMe extends About {
   &ensp; •&nbsp; [Auto Debounce](#concept-debounce) <br/>
   <!-- &ensp; •&nbsp; [Selectors](#concept-selectors) <br/> -->
 
-### API
+<!-- ### API
   &ensp; •&nbsp; [Model](#api-controller) <br/>
   &ensp; •&nbsp; [Singleton](#api-singleton) <br/>
   &ensp; •&nbsp; [Reserved](#api-reserved) <br/>
-  &ensp; •&nbsp; [Lifecycle](#api-lifecycle) <br/>
+  &ensp; •&nbsp; [Lifecycle](#api-lifecycle) <br/> -->
 
 <br/>
 
@@ -315,23 +327,22 @@ import Model from "@expressive/mvc";
 Ultimately, the workflow is simple.
 
 1. Create a class. Fill it with the values, getters, and methods you'll need.
-2. Extend `Model` (or any derivative, for that matter) to make it reactive.
-3. Within a component, use built-in methods as you would any normal hook.
-4. Destructure the values, used by a component, to subscribe.
+2. Extend `Model` (or any derivative, for that matter), making it reactive.
+3. Within a component, use built-in methods as you would normal hooks.
+4. Destructure out the values used by a component, to then subscribe.
 5. Update those values on demand. Component will sync automagically. ✨
 <br/>
 
-### Glossary
+> You may recognize this as similar to approach pioneered by [MobX](https://mobx.js.org/README.html). Here though, we avoid using decorators and other boilerplate.
 
-The following is a crash-course to help get you up to speed.<br/>
-Here's some library jargon which will be good to know.
+### Glossary
 
- - **Model**: Any class you'll write extending `Model`. Your definition for a type of state.
- - **Controller**: An instance of your model, containing its state and behavior.
- - **State**: The values tracked by a controller, as defined by the model. 
- - **Subscriber**: A hook, or otherwise special callback, responding to updates.
- - **View**: A function-component which can accept hooks, to contain some controller.
- - **Element**: Instance of a component/view, actively mounted with its own state and lifecycle.
+ - **Model**: Any class you'll write extending `Model`. Defines a type of state.
+ - **Controller**: An instance of Model, containing its state and behavior.
+ - **State**: The values managed by a controller, as defined by the model. 
+ - **Subscriber**: A hook, or otherwise a callback, responding to updates.
+ - **View**: A function-component which accepts hooks, to contain a controller.
+ - **Element**: Instance of a component mounted, having state and lifecycle.
 
 <br/>
 <h2 id="concept-simple">First Steps</h2>
@@ -495,10 +506,10 @@ class Timer extends Model {
 
 A getter's value is cached, facing the user. It will only run when a dependency changes, and **not upon access** as you might expect. However, getters are also lazy, so first access is one exception.
 
-Because getters run whenever a controller thinks they *could* change, make sure to design them along these principles:
+Getters run whenever a controller thinks they *could* change. Make sure to design them along these lines:
 - Getters should be deterministic. Only expect a change where inputs have changed.
 - Avoid computing from values which change a lot, but don't change output as often.
-- [Goes without saying](https://www.youtube.com/watch?v=0i0IlSKn0sE "Goes Without Saying") but, **side-effects are an anti-pattern** and can cause infinite loops.
+- [Goes without saying](https://www.youtube.com/watch?v=0i0IlSKn0sE "Goes Without Saying") but, **side-effects are an anti-pattern** and may cause infinite loops.
 
 <br/>
 
@@ -534,7 +545,7 @@ const SayHello = ({ fullName }) => {
 
 <h2 id="concept-passing-props">Assigning props to state</h2>
 
-Besides `use`, similar methods will assign values after a controller is created. This is a great alternative to a manual setup, as done previously.
+Besides `use`, similar methods will assign values after a controller is created. Good alternative to a manual setup.
 
 <h4 id="method-uses"><code>Model.uses(source, keys?)</code></h4>
 
@@ -622,7 +633,6 @@ class TimerControl extends Model {
 
   componentDidMount(){
     const inc = () => this.elapsed++;
-
     this.interval = setInterval(inc, 1000);
   }
 
@@ -655,7 +665,7 @@ Besides state change, what a subscriber really cares about is events. *Updates a
 
 <br />
 
-<h3 id="concept-listen-event">Listening for events manually</h3>
+<h2 id="concept-listen-event">Listening for events manually</h2>
 
 ```js
 const normalCallback = (value, key) => {
@@ -684,7 +694,7 @@ Will also expire when triggered. May be cancelled with the returned callback.
 If `callback` is not provided, `once` will return a Promise of keys watched/updated.
 
 <br />
-<h3 id="concept-listen-effect">Define an effect for one or more values</h3>
+<h2 id="concept-listen-effect">Defining an effect</h2>
 
 ```js
 function effectCallback(state){
@@ -715,30 +725,31 @@ function subscribedCallback(state){
 ```
 #### `state.effect(subscribedCallback) => remove`
 
-If no explicit `keys` are given, effect callback will self-subscribe. Just like a hook, it will detect values used and automatically update for new ones.
+If no explicit `keys` are given, the effect callback will self-subscribe. Just like a hook, it detects values used and automatically will update for new ones.
 
-> Note: In order to scan for property access, the effect will always run at-least once.
+> Note: In order to scan for property access, this effect will run at-least once, immediately.
 
 <br />
-<h3 id="concept-push-event">Pushing your own events</h3>
+<h2 id="concept-push-event">Pushing your own events</h2>
 
 #### `state.update(key)`
 
 Fires a synthetic event, sent to all listeners for key(s) selected, be them components or callback-listeners above. Any `string` or `symbol` may be a key. Naturally, a key which is defined on state already, will be treated as an update.
 
 > Events make it easier to design around closures and callbacks, keeping as few things on your model as possible. Event methods may also be used externally, for other code to interact with.
-<br /><br />
 
-<h3 id="concept-builtin-event">Listening for built-in events</h3>
+<br />
+<h2 id="concept-builtin-event">Listening for built-in events</h2>
 
 Controllers will emit lifecycle events for a bound component (depending on the hook).
 
 > Often lifecycle is critical to a controller's correct behavior. While we do have lifecycle-methods, it's recommended to use events where able. This way, if your class is extended and redefines a handler, yours is not at the mercy of a `super[event]()` call.
 
 Lifecycle events share names with their respective methods, [listed here](#lifecycle-api).
-<br /><br />
 
-### Event handling in-practice:
+<br />
+
+## Event handling in-practice:
 
 ```js
 class TickTockClock extends Model {
@@ -796,8 +807,6 @@ Sometimes, we want to react to changes coming from outside, usually via props. O
 
 This method helps watch an object by running [`assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) on it *every render*. Because controllers only react to new values, this makes for a simple way to watch externals. Combine this with getters and event-listeners, to do things when inputs change.
 
-<br />
-
 ```ts
 class ActivityTracker extends Model {
   active = undefined;
@@ -842,8 +851,6 @@ const Activate = () => {
 
 <sup><a href="https://codesandbox.io/s/example-using-method-wvrtu">View in CodeSandbox</a></sup>
 
-With this, we can interact with all different sorts of state!
-
 > **Note:** Method is also picky (ala `uses`), and will ignore values which don't already exist in state.
 
 <br />
@@ -1012,7 +1019,6 @@ export class FooBar extends Model {
 > Models and their consumers do not need to live in same file, let alone module. Want to interact with another library's state? This can make for a pro-consumer solution. ☝️😑
 
 <br/>
-
 <h2 id="concept-provider">Providing an instance</h2>
 
 Here, pass a controller to the `of` prop. For any children, it will be made accessible via its class.
@@ -1035,6 +1041,7 @@ export const App = () => {
 }
 ```
 
+<br/>
 <h2 id="concept-provider-spawning">Spawning an instance</h2>
 
 Without constructor-arguments, creating the instance separately can be an unnecessary step. Pass a Model itself, to both create and provide a state in one sitting.
@@ -1049,6 +1056,7 @@ export const App = () => {
 }
 ```
 
+<br/>
 <h2 id="concept-provider-props">Spawning with props</h2>
 
 When a Model is passed to `of` directly, the Provider will behave similarly to [`Model.using()`](#concept-external). All other props are forwarded to state and likewise observed.
@@ -1065,6 +1073,7 @@ const FancyFooBar = (props) => {
 
 > Now, consumers can see incoming-data, which only the parent has access to!
 
+<br/>
 <h2 id="concept-provider-multi">Providing Multiple</h2>
 
 Finally, `of` can accept a collection of models and/or state objects. Mix and match as needed to ensure a DRY, readible root.
@@ -1191,7 +1200,7 @@ export class FooBar extends Model {
 ```
 
 <br/>
-<h2 id="concept-consumer-hooks">Hooks Methods</h2>
+<h2 id="concept-consumer-hooks">Method Hooks</h2>
 
 Models make fetching a state super easy. On every model, there are defined three `useContext` like methods. They find, return and maintain the nearest instance of class they belong to.
 
@@ -1296,7 +1305,7 @@ const LazyConsumer = () => {
 <br />
 <h2 id="concept-ambient">Peer Consumers</h2>
 
-While context is great for components, controllers can use it too, that of the component where used. This is helped by importing a helper function, likewise called `tap`.
+While context is great for components, controllers can use it too, that of the component where used. This is helped by importing a special function, likewise called `tap`.
 > [This is an instruction](#concept-instruction), in-short a factory function. It tells the controller while initializing: the defined property is special, run some logic to set that up.
 
 On your Model, assign a property with the value of `tap(Model)`, passing in the type of state you're interested in.
@@ -1320,7 +1329,7 @@ class Greet extends Model {
   }
 }
 ```
-Create a controller which taps another one. Make sure it's wrapped by proper `Provider`, and controller will fetch that instance from context.
+Create a controller which taps another one. Make sure it's wrapped by proper `Provider`, and the controller will fetch that instance from context.
 ```js
 import { Provider } from "@expressive/mvc";
 
@@ -1409,8 +1418,8 @@ class FooBar extends Model {
     return this.foo.value + this.bar.value;
   }
 
-  plusFoo = () => this.bar.value = this.value;
-  plusBar = () => this.foo.value = this.value;
+  addFoo = () => this.bar.value = this.value;
+  addBar = () => this.foo.value = this.value;
 }
 ```
 
@@ -1418,17 +1427,17 @@ class FooBar extends Model {
 
 ```js
 const FibonacciApp = () => {
-  const { foo, bar, value, plusFoo, plusBar } = FooBar.use();
+  const { foo, bar, value, addFoo, addBar } = FooBar.use();
 
   return (
     <div>
       <div>
         Foo + Bar = {value}
       </div>
-      <div onClick={plusBar}>
+      <div onClick={addBar}>
         Foo's value is ${foo.value}, click to add in bar!
       </div>
-      <div onClick={plusFoo}>
+      <div onClick={addFoo}>
         Bar's value is ${bar.value}, click to add in foo!
       </div>
     </div>
@@ -1466,7 +1475,6 @@ class Dependant extends Model {
 
 > Here we've learned how Models allow controllers to cooperate and play off of eachother. They allow us to break-up behavior into smaller pieces, building-blocks if you will. With that, we have an easy way to separate concerns, freeing up focus for more added nuance and features.
 
-<br/>
 <br/>
 
 ### :construction: More Docs are on the way! 🏗