Skip to content

Commit 97d2e32

Browse files
panManfredinipanManfredini
committed
adding docs to stateElement
1 parent 13bb897 commit 97d2e32

File tree

2 files changed

+129
-15
lines changed

2 files changed

+129
-15
lines changed

‎build/stateElement.js‎

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ import onChangeProxy from "./onChange.js";
22
var _isCallback_locked = false;
33
var _under_transition = false;
44
const _transitions_callbackMap = new Map();
5-
// _transitions_callbackMap.clear(); // is this needed?? FIXME
65
class BaseState {
76
constructor(NAME) {
87
this.name = NAME;
@@ -29,21 +28,43 @@ class BaseState {
2928
update_callback(input);
3029
}
3130
}
31+
/**
32+
* Attach a callback to be fired when this stateVariable (or Transition) changes (is dispatched).
33+
* @param target Element that holds the callback
34+
* @param callback the callback function needs to be bound to the element if using **this**
35+
*/
3236
attachWatcher(target, callback) {
3337
if (target === null || target === undefined)
3438
throw Error("Target is undefined.");
3539
// add element to the watcher list
3640
this.callbackMap.set(target, callback);
3741
}
42+
/**
43+
* Removes the element from the watcher list
44+
* @param target element to be removed
45+
*/
3846
detachWatcher(target) {
3947
if (target === null || target === undefined)
4048
throw Error("Target is undefined.");
4149
// remove element from watcher list
4250
this.callbackMap.delete(target);
4351
}
4452
}
53+
/**
54+
* A stateTransition is a global function that is meant to apply simultaneously an overall state change,
55+
* this can be made of just one variable change or multiple stateVariables changes at the same time, so that the initial and final
56+
* states are always well defined, it guarantees that UI updates are made at transition completion (final state) only.
57+
*/
4558
export class StateTransition extends BaseState {
59+
/**
60+
* User defined transition to be overwritten.
61+
* @param input Any meaningfull data.
62+
*/
4663
usrDefined_transition(input) { }
64+
/**
65+
* Fires the user defined transition and calls the callbacks of all watchers.
66+
* @param input data to be passed to the user defined transition
67+
*/
4768
applyTransition(input) {
4869
this.lock_callbacks();
4970
_under_transition = true;
@@ -59,6 +80,14 @@ export class StateTransition extends BaseState {
5980
this.unlock_callbacks();
6081
}
6182
}
83+
/**
84+
* A StateVariable hold the state of the App, its content can be a String, Object, Number and Boolean. Its **DEFAULT**
85+
* value is passed at creation time and defines the type of the variable, the type cannot be changed later.
86+
* A StateVariable is automatically stored in **localStorage**.
87+
* @param value - Returns a proxy to the content of the stateVariable, whenever it is set (directly or indirectly using Array.push
88+
* for example) will run the callback for all watchers.Proxy to the content of stateVariable
89+
* @param allowStandaloneAssign - Enable/Disable assignment outside of a stateTransition (default true)
90+
*/
6291
export class StateVariable extends BaseState {
6392
constructor(NAME, DEFAULT) {
6493
super(NAME);
@@ -157,6 +186,11 @@ export class StateVariable extends BaseState {
157186
this._call_watchers();
158187
this.unlock_callbacks();
159188
}
189+
/**
190+
* Add a transition to this stateVariable, after that the variable can only be changed trough defined stateTransition.
191+
* @param name Used to identify the transition
192+
* @param func Definition of the variable update, **this** is bound to the variable.
193+
*/
160194
addTransition(name, func) {
161195
let t = new StateTransition(name);
162196
if (typeof (func) === "function") {
@@ -165,13 +199,22 @@ export class StateVariable extends BaseState {
165199
this.allowStandaloneAssign = false;
166200
}
167201
}
202+
/**
203+
* Fires one of the user defined transition related to this stateVariable.
204+
* @param name Identifier of the transition.
205+
* @param input Payload to be passed to the transition, if any.
206+
*/
168207
applyTransition(name, input) {
169208
if (this.transitionMap.has(name))
170209
this.transitionMap.get(name).applyTransition(input);
171210
else
172211
throw Error(`Transition ${name} not found`);
173212
}
174213
}
214+
/**
215+
* A Message does not change the state of the app and is not persisted in any way, it used to exchange payloads between custom-elements.
216+
* A custom-element can listen for a specific message, retrieve its payload and fire a callback when this happens.
217+
*/
175218
export class Message extends BaseState {
176219
sendMessage(input) {
177220
this._call_watchers(input);
@@ -241,6 +284,16 @@ let baseMixin = (listOfComponents, baseClass) => class extends baseClass {
241284
}
242285
}
243286
};
287+
/**
288+
* This is a mixin to be applied to a generic web-component. For any **stateVariables** in the list will add to the element a read-only property
289+
* named as the stateVariable. It will add an **applyTransition** method to dispatch the added
290+
* transition (either of a stateVariable or of a global stateTransition). Callbacks to react on stateVariable change needs to be overwritten by the user
291+
* and have a predefiend naming scheme: **on_"stateVarName"_update**. Callbacks to react to transitions are instead called **on_"stateTransitionName"**,
292+
* in the latter case also the transition input data are passed. For any **Message** in the list a **gotMessage_"messageName"** callback is added to react
293+
* to message exchange, this callback passes as input the message payload.
294+
* @param listOfComponents is a list of StateVariables and StateTransition to add to the web-component
295+
* @param baseClass The class on which the mixin is applied
296+
*/
244297
export let statesMixin = (listOfComponents, baseClass) => class extends baseMixin(listOfComponents, baseClass) {
245298
connectedCallback() {
246299
if (super['connectedCallback'] !== undefined) {
@@ -266,13 +319,20 @@ export let statesMixin = (listOfComponents, baseClass) => class extends baseMixi
266319
}
267320
}
268321
};
322+
/**
323+
* This is a mixin to be applied to Lit-Element web-components. For any stateVariables in the list will add a read-only property
324+
* to the element named as the stateVariable. It will add an **applyTransition** method to dispatch the added
325+
* transition (either of a stateVariable or of a global stateTransition). For each change of a stateVariable or dispatch of
326+
* any of the stateTransition a render request is called. For any **Message** in the list it will add a **gotMessage_"messageName"** method to react
327+
* to message exchange, this method passes as input the message payload.
328+
* @param listOfComponents is a list of StateVariables and StateTransition to add to the web-component
329+
* @param baseClass The class on which the mixin is applied
330+
*/
269331
export let litStatesMixin = (listOfComponents, baseClass) => class extends baseMixin(listOfComponents, baseClass) {
270332
connectedCallback() {
271333
if (super['connectedCallback'] !== undefined) {
272334
super.connectedCallback();
273335
}
274-
//let run_render_on_connect = false;
275-
// watch default state variables
276336
for (let state_comp of listOfComponents) {
277337
if (state_comp instanceof Message) {
278338
if (this[`gotMessage_${state_comp.name}`])
@@ -284,6 +344,5 @@ export let litStatesMixin = (listOfComponents, baseClass) => class extends baseM
284344
state_comp.attachWatcher(this, this.requestUpdate.bind(this));
285345
}
286346
}
287-
//if(run_render_on_connect) this.render();
288347
}
289348
};

‎src/stateElement.ts‎

Lines changed: 66 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ import onChangeProxy from "./onChange.js"
44
var _isCallback_locked = false;
55
var _under_transition = false;
66
const _transitions_callbackMap : Map<StateVariable, Function> = new Map();
7-
// _transitions_callbackMap.clear(); // is this needed?? FIXME
87

98
class BaseState{
109
callbackMap : Map<EventTarget,Function>
@@ -36,14 +35,22 @@ class BaseState{
3635
else update_callback(input);
3736
}
3837
}
39-
38+
/**
39+
* Attach a callback to be fired when this stateVariable (or Transition) changes (is dispatched).
40+
* @param target Element that holds the callback
41+
* @param callback the callback function needs to be bound to the element if using **this**
42+
*/
4043
attachWatcher( target:HTMLElement, callback:Function ) :void {
4144
if(target === null || target === undefined )
4245
throw Error("Target is undefined.")
4346
// add element to the watcher list
4447
this.callbackMap.set(target, callback);
4548
}
4649

50+
/**
51+
* Removes the element from the watcher list
52+
* @param target element to be removed
53+
*/
4754
detachWatcher( target:HTMLElement) :void {
4855
if(target === null || target === undefined )
4956
throw Error("Target is undefined.")
@@ -53,10 +60,22 @@ class BaseState{
5360

5461
}
5562

63+
/**
64+
* A stateTransition is a global function that is meant to apply simultaneously an overall state change,
65+
* this can be made of just one variable change or multiple stateVariables changes at the same time, so that the initial and final
66+
* states are always well defined, it guarantees that UI updates are made at transition completion (final state) only.
67+
*/
5668
export class StateTransition extends BaseState{
57-
69+
/**
70+
* User defined transition to be overwritten.
71+
* @param input Any meaningfull data.
72+
*/
5873
usrDefined_transition(input?:any){}
5974

75+
/**
76+
* Fires the user defined transition and calls the callbacks of all watchers.
77+
* @param input data to be passed to the user defined transition
78+
*/
6079
applyTransition( input?:any ) :void {
6180

6281
this.lock_callbacks();
@@ -79,14 +98,22 @@ export class StateTransition extends BaseState{
7998

8099
}
81100

101+
/**
102+
* A StateVariable hold the state of the App, its content can be a String, Object, Number and Boolean. Its **DEFAULT**
103+
* value is passed at creation time and defines the type of the variable, the type cannot be changed later.
104+
* A StateVariable is automatically stored in **localStorage**.
105+
* @param value - Returns a proxy to the content of the stateVariable, whenever it is set (directly or indirectly using Array.push
106+
* for example) will run the callback for all watchers.Proxy to the content of stateVariable
107+
* @param allowStandaloneAssign - Enable/Disable assignment outside of a stateTransition (default true)
108+
*/
82109
export class StateVariable extends BaseState{
83110
type : string;
84111
default_val : any ;
85112
_err_on_value :string;
86113
_val : any;
87114
_valueProxy: ProxyConstructor;
88115
_auto_valueProxy: ProxyConstructor;
89-
allowStandaloneAssign:boolean;
116+
allowStandaloneAssign:boolean;
90117
transitionMap : Map<string,StateTransition>
91118

92119
constructor(NAME:string, DEFAULT:any){ // FIXME DEFAULT HAS A TYPE OF TYPE
@@ -116,7 +143,7 @@ export class StateVariable extends BaseState{
116143
this._auto_valueProxy = onChangeProxy( this._val, this._markForWatchersUpdate.bind(this) );
117144
}
118145
}
119-
146+
120147
set value(val:any){
121148
this._checkIsAllowed();
122149
this._val = val;
@@ -193,7 +220,12 @@ export class StateVariable extends BaseState{
193220

194221
this.unlock_callbacks();
195222
}
196-
223+
224+
/**
225+
* Add a transition to this stateVariable, after that the variable can only be changed trough defined stateTransition.
226+
* @param name Used to identify the transition
227+
* @param func Definition of the variable update, **this** is bound to the variable.
228+
*/
197229
addTransition(name:string, func:Function){
198230
let t = new StateTransition(name);
199231
if(typeof(func) === "function"){
@@ -203,6 +235,11 @@ export class StateVariable extends BaseState{
203235
}
204236
}
205237

238+
/**
239+
* Fires one of the user defined transition related to this stateVariable.
240+
* @param name Identifier of the transition.
241+
* @param input Payload to be passed to the transition, if any.
242+
*/
206243
applyTransition(name:string,input?:any){
207244
if(this.transitionMap.has(name))
208245
this.transitionMap.get(name).applyTransition(input);
@@ -212,6 +249,10 @@ export class StateVariable extends BaseState{
212249

213250
}
214251

252+
/**
253+
* A Message does not change the state of the app and is not persisted in any way, it used to exchange payloads between custom-elements.
254+
* A custom-element can listen for a specific message, retrieve its payload and fire a callback when this happens.
255+
*/
215256
export class Message extends BaseState{
216257
sendMessage(input:any) :void {
217258
this._call_watchers(input);
@@ -297,8 +338,16 @@ let baseMixin = (listOfComponents:Array<StateVariable|StateTransition|Message>,
297338

298339
}
299340

300-
301-
341+
/**
342+
* This is a mixin to be applied to a generic web-component. For any **stateVariables** in the list will add to the element a read-only property
343+
* named as the stateVariable. It will add an **applyTransition** method to dispatch the added
344+
* transition (either of a stateVariable or of a global stateTransition). Callbacks to react on stateVariable change needs to be overwritten by the user
345+
* and have a predefiend naming scheme: **on_"stateVarName"_update**. Callbacks to react to transitions are instead called **on_"stateTransitionName"**,
346+
* in the latter case also the transition input data are passed. For any **Message** in the list a **gotMessage_"messageName"** callback is added to react
347+
* to message exchange, this callback passes as input the message payload.
348+
* @param listOfComponents is a list of StateVariables and StateTransition to add to the web-component
349+
* @param baseClass The class on which the mixin is applied
350+
*/
302351
export let statesMixin = (listOfComponents:Array<StateVariable|StateTransition|Message>, baseClass:any) => class extends baseMixin(listOfComponents, baseClass) {
303352

304353
connectedCallback(){
@@ -327,14 +376,21 @@ export let statesMixin = (listOfComponents:Array<StateVariable|StateTransition|M
327376
}
328377
}
329378

379+
/**
380+
* This is a mixin to be applied to Lit-Element web-components. For any stateVariables in the list will add a read-only property
381+
* to the element named as the stateVariable. It will add an **applyTransition** method to dispatch the added
382+
* transition (either of a stateVariable or of a global stateTransition). For each change of a stateVariable or dispatch of
383+
* any of the stateTransition a render request is called. For any **Message** in the list it will add a **gotMessage_"messageName"** method to react
384+
* to message exchange, this method passes as input the message payload.
385+
* @param listOfComponents is a list of StateVariables and StateTransition to add to the web-component
386+
* @param baseClass The class on which the mixin is applied
387+
*/
330388
export let litStatesMixin = (listOfComponents:Array<StateVariable|StateTransition|Message>, baseClass:any) => class extends baseMixin(listOfComponents, baseClass) {
331389
connectedCallback(){
332390
if(super['connectedCallback'] !== undefined) {
333391
super.connectedCallback();
334392
}
335-
//let run_render_on_connect = false;
336393

337-
// watch default state variables
338394
for (let state_comp of listOfComponents) {
339395

340396
if(state_comp instanceof Message){
@@ -347,6 +403,5 @@ export let litStatesMixin = (listOfComponents:Array<StateVariable|StateTransitio
347403
state_comp.attachWatcher(this, this.requestUpdate.bind(this));
348404
}
349405
}
350-
//if(run_render_on_connect) this.render();
351406
}
352407
}

0 commit comments

Comments
 (0)