You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+142-8Lines changed: 142 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,11 +13,14 @@ citizens. The main features are:
13
13
- It's tiny, only about 5 kB minified (and 1.9 kB gzipped).
14
14
- It uses Proxy under the hood for a little :sparkler:
15
15
- It is meant for custom-elements, so you can use it with Vanilla-JS or any framework like [lit-element](https://www.npmjs.com/package/lit-element), [Brick](https://www.npmjs.com/package/brick-element).
16
-
- Implements the usual flow: ACTION->REDUCER->STORE but with A LOOOOT less painfull sintax.
16
+
- Implements the usual flow: **ACTION**->**REDUCER**->**STORE** but with A LOOOOT less painfull sintax.
17
17
- You can break the STORE in parts as small as you like.
18
18
- Works with async out of the box.
19
19
- Saves the state to ``localStorage`` automatically.
20
20
21
+
If you are not familiar with the ACTION->REDUCER->STORE pattern and why is a good idea, have a look at the [Redux Docs](https://redux.js.org/introduction/core-concepts) where it is very well explained.
22
+
23
+
21
24
# Demo
22
25
23
26
[Simple todo App demo](https://webcomponenthelpers.github.io/ImperaJS/demo/litDemo.html) made with **ImperaJs** and **Lit-Element**.
@@ -37,25 +40,156 @@ while a transition from one app state to another is implemented by **State-Trans
37
40
State-Variables and Transitions can be hooked to custom-elements, so that on StateVarible change, or on dispatch of a Transition, the custom-element
38
41
can apply its own UI-related changes.
39
42
43
+
### Install
44
+
45
+
```bash
46
+
npm i impera-js
47
+
```
48
+
40
49
### StateVariables
50
+
A StateVariable hold the state of the App, its content can be a String, Object, Number and Boolean. Its **DEFAULT** value is passed at creation time and defines the type of the variable, the type cannot be changed later. A StateVariable is automatically stored in **localStorage**, if a value already exist it is automatically loaded. You can have a look at [a more complete example here](https://github.com/WebComponentHelpers/ImperaJS/blob/master/demo/Store.js).
41
51
52
+
```js
53
+
import {StateVariable} from'impera-js'
54
+
55
+
// Initializzation to an empty list
56
+
var todos =newStateVariable("todos",[]);
57
+
58
+
// Attach/Detach watchers
59
+
// Target is a custom-element and the callback is a function
60
+
// that modify its UI (it will work with any object really)
The property **value** of a stateVariable returns a proxy to the content of the stateVariable, whenever it is set (directly or indirectly using Array.push for example) will run the callback for all watchers.
75
+
76
+
77
+
### StateTransitions
78
+
Transitions must be **Pure Functions**, they only compute a final state, they are defined by initial state and input data only, they reproduce always the same result for same inputs.
42
79
43
80
```js
44
-
// init
81
+
82
+
// Adding a Transition to a StateVariable
83
+
todos.addTransition("addTodo",(text)=>{
84
+
let todo = {txt : text, isComplete :false}
85
+
todos.value.push(todo)
86
+
})
87
+
88
+
89
+
// State change via transition
90
+
// this will fire the watchers callbacks
91
+
todos.applyTransition("addTodo", "new Todo")
92
+
93
+
94
+
// Note that now this will throw, this is to make
95
+
// sure one can only change state by defined transitions
96
+
todos.value.push(some_todo)
97
+
98
+
// this protection can be overridden
99
+
todos.allowStandaloneAssign=true
100
+
todos.value.push(some_todo) // now will not throw
101
+
45
102
```
103
+
The idea here is that once you add a transition to a stateVariable you limit its allowed chage space, the framework makes sure that now you are only allowed to change the stateVariable via transitions. You can of course override this behaviour.
104
+
Note that transition owned by a state variable will bind **this** to the state variable itself, however make sure to use a named function then and NOT an arrow function as in the example.
46
105
47
106
```js
48
-
// note is a proxy
49
-
let myProxy =var.value.whatever
50
-
myProxy =9// this change the variable and run side-effects
107
+
import {StateTransition} from'impera-js'
108
+
109
+
// Global transitions definition
110
+
var removeTodo =newStateTransition("removeTodo",(index)=>{
111
+
todos.value.splice(index,1)
112
+
113
+
// any other stateVariables change can go below here
114
+
// ....
115
+
});
116
+
117
+
// Dispatch the transition, andcall watchers callbacks.
118
+
// Whatcher can be attached in same way as for stateVariables
119
+
removeTodo.applyTransition( 1 )
120
+
51
121
```
122
+
A global stateTransition is a global function that is meant to apply simultaneously an overall state change, this can be made of just one variable change or multiple stateVariables changes at the same time, so that the initial and final states are always well defined, it guarantees that UI updates are made at transition completion (final state) only.
123
+
124
+
### StateMixin
125
+
The StateMixins are a way to attach custom-element callbacks to a stateVariable or a stateTransition in an easy way. The callbacks get attached and detached automatically when the custom-element is connected/disconnected from the DOM.
// override callback that fires on "todos" changes
143
+
on_todos_update(){
144
+
// do something to update the UI
145
+
}
146
+
147
+
// override callback that fires on transition "removeTodo"
148
+
on_removeTodo(){
149
+
// do something here
150
+
}
151
+
152
+
onclick(){
153
+
// the element now has a hook to all transition of
154
+
// states in the list.
155
+
this.applyTransition("addTodo", "new todo")
156
+
this.applyTransition("removeTodo", 1 )
157
+
}
158
+
}
159
+
55
160
```
161
+
For any **stateVariables** in the list a read-only property named as the stateVariable will be added to the element. Also an **applyTransition** method to dispatch the added transitions (either of a stateVariable or of a global stateTransition) will be added. Callbacks to react on stateVariable change needs to be overwritten by the user and have a predefiend naming scheme: **on_"stateVarName"\_update**. Callbacks to react to transitions are instead called **on_"stateTransitionName"**, in the latter case also the transition input data are passed.
56
162
57
-
### StateTransitions
163
+
### Usage with Lit-Element
58
164
165
+
The usage with Lit-Element is very similar to what shown above, with the exception that
166
+
each update of any stateVariable or dispatch of Transition will request a render of the element. You can have a look at [a more complete example here](https://github.com/WebComponentHelpers/ImperaJS/blob/master/demo/litWebComponents.js), while a demo can be found [here](https://webcomponenthelpers.github.io/ImperaJS/demo/litDemo.html).
0 commit comments