definition module InteractionTasks
/*
* This module provides means to interact with users
*/
from TSt		import :: Task
from Types		import :: Role
from Html		import :: HtmlTag
from iTasks		import class iTask(..)

import GenVisualize, GenUpdate, GenMerge, StoreTasks

derive gVisualize Action
derive gUpdate Action
derive gVerify Action

derive JSONEncode Action
derive JSONDecode Action

instance == Action

/*
* To allow users to specify a followup action to their current task
* most interactive tasks allow you to specify actions that can be chosen.
* These actions are either available as a button on the bottom of the task interface
* or as an item in the task menu, or both.
* Additionally conditions can be specified when the action is allowed to be performed.
*/
:: Action	= Action !ActionName !ActionLabel 
			| ActionOk
			| ActionCancel
			| ActionYes
			| ActionNo
			| ActionNext
			| ActionPrevious
			| ActionFinish
			| ActionNew
			| ActionOpen
			| ActionSave
			| ActionSaveAs
			| ActionQuit
			| ActionClose
			| ActionHelp
			| ActionAbout
			| ActionFind
			| ActionDelete
			| ActionEdit
			
:: ActionName	:== String 					//Locally unique identifier for actions
:: ActionLabel	:== String					//Textual label for the action
:: ActionData	:== String					//Extra data to pass along with an action
:: ActionEvent	:== (Action, ActionData)	//Event generated by client including action and extra data

actionIcon 	:: !Action -> String
actionLabel	:: !Action -> String

class ActionName a
where
	actionName	:: a -> String

instance ActionName Action
instance ActionName ActionName

:: Menus		:== [Menu]
:: Menu 		= Menu !MenuLabel ![MenuItem]
:: MenuItem 	= E.action:	MenuItem !action !(Maybe Hotkey) & MenuAction action
				| 			SubMenu !MenuLabel ![MenuItem]
				| 			MenuSeparator
:: MenuLabel	:== String
				
:: Hotkey =	{ key	:: !Key
			, ctrl	:: !Bool
			, alt	:: !Bool
			, shift	:: !Bool
			}	
:: Key = A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

class MenuAction a
where
	menuAction :: a -> MenuAction

:: MenuAction :== (ActionName, ActionLabel, ActionData)

instance MenuAction Action
instance MenuAction ActionName
instance MenuAction (actionName, ActionLabel, ActionData) | ActionName actionName

// This tuple is used to link actions to user interfaces.
// Its two parts represent the (what , when) aspects of actions.
// What: The conceptual action to be taken
// When: The condition that determine if the action can be taken
:: TaskAction a		:== (!Action, !(Verified a) -> Bool)

//Wrapper for task values that indicates if value passes the verification step
:: Verified a 		= 	Invalid
					|	Valid !a
						
//Default predicates on editor values to use with actions
always		:: (Verified a) -> Bool
ifvalid		:: (Verified a) -> Bool
ifinvalid	:: (Verified a) -> Bool

/*
* This html class makes it possible to use either strings, or html as description/message/instruction
*/
class html a  
where
	html :: a -> HtmlTag
	
instance html String
instance html [HtmlTag]
instance html Note
instance html (Maybe a) | html a

//*** Input collection tasks ***//

/*
* Ask the user to enter information.
*
* @param description 		A description of the task to display to the user
* @param (v -> a)			A view for type v is generated; This function defines how to map view v back to a value of type a. 
*							If not specified, v = a, and the map back is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
*
* @return 					Resulting value with (optionally) chosen action
*/
enterInformation			:: !d 						    -> Task a					| descr d & iTask a
enterInformationA			:: !d !(v -> a) ![TaskAction a] -> Task (!ActionEvent, a)	| descr d & iTask a & iTask v

/*
* Ask the user to enter information, given some additional context information
*
* @param description 		A description of the task to display to the user
* @param (v -> a)			A view for type v is generated; This function defines how to map view v back to a value of type a. 
*							If not specified, v = a, and the map back is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
*
* @return 					Resulting value with (optionally) chosen action
*/
enterInformationAbout		:: !d  				  		    !b -> Task a					| descr d  & iTask a & iTask b
enterInformationAboutA		:: !d !(v -> a) ![TaskAction a] !b -> Task (!ActionEvent, a)	| descr d  & iTask a & iTask b & iTask v

/*
* Ask the user to update predefined information. 
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param a or (Shared a)	The initial value or shared value to use. 
*
* @return 					Resulting value with (optionally) chosen action
*/
updateInformation			:: !d 									   a 		  -> Task a						| descr d & iTask a
updateInformationA			:: !d !(a -> v, v a -> a) ![TaskAction a]  a  		  -> Task (!ActionEvent,  a)	| descr d & iTask a & iTask v
updateSharedInformationA	:: !d !(a -> v, v a -> a) ![TaskAction a] !(Shared a) -> Task (!ActionEvent, !a)	| descr d & iTask a & iTask v


/*
* Ask the user to update predefined information, given some additonal context information
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param a or (Shared a)	The initial value or shared value to use. 
*
* @return 					Resulting value with (optionally) chosen action
*/
updateInformationAbout			:: !d 									  !b a 			 -> Task a					| descr d & iTask a & iTask b
updateInformationAboutA			:: !d !(a -> v, v a -> a) ![TaskAction a] !b a  		 -> Task (!ActionEvent,  a)	| descr d & iTask a & iTask b & iTask v
updateSharedInformationAboutA	:: !d !(a -> v, v a -> a) ![TaskAction a] !b !(Shared a) -> Task (!ActionEvent, !a)	| descr d & iTask a & iTask b & iTask v

/*
* Asks the user to confirm or decline a question.
*
* @param description 		A description of the task to display to the user
*
* @return 					A boolean indicating 'accepted' (True) or 'declined' (False)
*/
requestConfirmation			:: !d -> Task Bool	| descr d 

/*
* Asks the user to accept or decline a question, given some additional context information
*
* @param description 		A description of the task to display to the user
* @param a					Additional context information to show to the user
*
* @return 					A boolean indiciating 'accepted' (True) or 'declined' (False)
*/
requestConfirmationAbout	:: !d a -> Task Bool	| descr d & iTask a

/*
* Ask the user to select one item from a list of options
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param [a]				A list of (shared) options
*
* @return 					Resulting value with (optionally) chosen action
*/
enterChoice					:: !d 					  				  ![a] 			-> Task a					| descr d & iTask a
enterChoiceA				:: !d !(a -> v, v a -> a) ![TaskAction a] ![a] 			-> Task (!ActionEvent, a)	| descr d & iTask a & iTask v
enterSharedChoiceA			:: !d !(a -> v, v a -> a) ![TaskAction a] ![Shared a] 	-> Task (!ActionEvent, a)	| descr d & iTask a & iTask v

/*
* Ask the user to select one item from a list of options, given some context information
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param [a]				A list of (shared) options
*
* @return 					Resulting value with (optionally) chosen action
*/
enterChoiceAbout			:: !d 									  !b ![a] 		  -> Task a					| descr d & iTask a	& iTask b
enterChoiceAboutA			:: !d !(a -> v, v a -> a) ![TaskAction a] !b ![a]		  -> Task (!ActionEvent, a)	| descr d & iTask a & iTask b & iTask v
enterSharedChoiceAboutA		:: !d !(a -> v, v a -> a) ![TaskAction a] !b ![Shared a]  -> Task (!ActionEvent, a)	| descr d & iTask a & iTask b & iTask v

/*
* Ask the user to select one item from a list of options with already one option pre-selected
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param [a]				A list of (shared) options
* @param Int				The index of the item which should be pre-selected
*
* @return 					Resulting value with (optionally) chosen action
*/
updateChoice				:: !d 									  ![a] 		  !Int -> Task a					| descr d & iTask a	
updateChoiceA 				:: !d !(a -> v, v a -> a) ![TaskAction a] ![a]		  !Int -> Task (!ActionEvent, a)	| descr d & iTask a & iTask v 
updateSharedChoiceA 		:: !d !(a -> v, v a -> a) ![TaskAction a] ![Shared a] !Int -> Task (!ActionEvent, a)	| descr d & iTask a & iTask v


/*
* Ask the user to select one item from a list of options with already one option pre-selected, given some context information
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param [a]				A list of (shared) options
* @param Int				The index of the item which should be pre-selected
*
* @return 					Resulting value with (optionally) chosen action
*/
updateChoiceAbout			:: !d 									  !b ![a] 		 !Int -> Task a					| descr d & iTask a	& iTask b
updateChoiceAboutA			:: !d !(a -> v, v a -> a) ![TaskAction a] !b ![a]		 !Int -> Task (!ActionEvent, a)	| descr d & iTask a & iTask b & iTask v
updateSharedChoiceAboutA	:: !d !(a -> v, v a -> a) ![TaskAction a] !b ![Shared a] !Int -> Task (!ActionEvent, a)	| descr d & iTask a & iTask b & iTask v

/*
* Ask the user to select one or more items from a list of options
*
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param [a]				A list of (shared) options
*
* @return 					Resulting values with (optionally) chosen action
*/
enterMultipleChoice			:: !d 					  				  ![a] 			-> Task [a]					| descr d & iTask a
enterMultipleChoiceA		:: !d !(a -> v, v a -> a) ![TaskAction a] ![a] 			-> Task (!ActionEvent, [a])	| descr d & iTask a & iTask v
enterSharedMultipleChoiceA	:: !d !(a -> v, v a -> a) ![TaskAction a] ![Shared a] 	-> Task (!ActionEvent, [a])	| descr d & iTask a & iTask v

/*
* Ask the user to select one or more items from a list of options, given additional context information
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param [a]				A list of (shared) options
*
* @return 					Resulting values with (optionally) chosen action
*/
enterMultipleChoiceAbout		:: !d 									  !b ![a] 		  -> Task [a]					| descr d & iTask a	& iTask b
enterMultipleChoiceAboutA		:: !d !(a -> v, v a -> a) ![TaskAction a] !b ![a]		  -> Task (!ActionEvent, [a])	| descr d & iTask a & iTask b & iTask v
enterSharedMultipleChoiceAboutA	:: !d !(a -> v, v a -> a) ![TaskAction a] !b ![Shared a]  -> Task (!ActionEvent, [a])	| descr d & iTask a & iTask b & iTask v

/*
* Ask the user to select one or more items from a list of options with already some options pre-selected
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param [a]				A list of (shared) options
* @param [Int]				The index of the items which should be pre-selected
*
* @return 					Resulting value with (optionally) chosen action
*/
updateMultipleChoice		:: !d 									  ![a] 		  ![!Int] -> Task [a]					| descr d & iTask a	& iTask b									| descr d & iTask a
updateMultipleChoiceA		:: !d !(a -> v, v a -> a) ![TaskAction a] ![a]		  ![!Int] -> Task (!ActionEvent, [a])	| descr d & iTask a & iTask b & iTask v
updateSharedMultipleChoiceA :: !d !(a -> v, v a -> a) ![TaskAction a] ![Shared a] ![!Int] -> Task (!ActionEvent, [a])	| descr d & iTask a & iTask b & iTask v

/*
* Ask the user to select one or more items from a list of options with already some options pre-selected, given additional context information
*
* @param description 		A description of the task to display to the user
* @param (a -> v, v a -> a)	Bimap defining how to convert a to the demanded view v and backwards 
*							If not specified, v = a, and the bimap is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param [a]				A list of (shared) options
* @param [Int]				The index of the items which should be pre-selected
*
* @return 					Resulting value with (optionally) chosen action
*/
updateMultipleChoiceAbout		 :: !d 									   !b ![a] 		  ![!Int] -> Task [a]					| descr d & iTask a	& iTask b									| descr d & iTask a
updateMultipleChoiceAboutA		 :: !d !(a -> v, v a -> a) ![TaskAction a] !b ![a]		  ![!Int] -> Task (!ActionEvent, [a])	| descr d & iTask a & iTask b & iTask v
updateSharedMultipleChoiceAboutA :: !d !(a -> v, v a -> a) ![TaskAction a] !b ![Shared a] ![!Int] -> Task (!ActionEvent, [a])	| descr d & iTask a & iTask b & iTask v

//*** Output tasks ***//

/*
* Show a basic message to the user. The user can end the task after reading the message. 

* @param description 		A description of the task to display to the user
* @param message 			A message to display to the user
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param a					The value is just passed for convenience
*
* @return					A copy of value a with (optionally) chosen action
*/
showMessage		:: !d !message 					a 			 -> Task a					| descr d & iTask a
showMessageA	:: !d !message  ![TaskAction a] a 			 -> Task (!ActionEvent, a)	| descr d & iTask a 

/*
* Show a basic message and additional context information to the user. The user can end the task after reading the message. 
*
* @param description 		A description of the task to display to the user
* @param message 			A message to display to the user
* @param (b -> v)			Map defining how to convert message b to the demanded view v
*							If not specified, v = b, and the map is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param a					The value is just passed for convenience
*
* @return					A (copy of) value a with (optionally) chosen action
*/
showMessageAbout	:: !d !message 							 !b a 			-> Task a					| descr d & iTask a
showMessageAboutA	:: !d !message !(b -> v) ![TaskAction a] !b a 			-> Task (!ActionEvent, a)	| descr d & iTask a & iTask b & iTask v


/*
* Show a basic message to the user. The user cannot end the task after reading the message. 
*
* @param description 		A description of the task to display to the user
* @param message 			A message to display to the user
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param a					The value is just passed for convenience
*
* @return					A copy of value a with (optionally) chosen action
*/
showStickyMessage	:: !d !message 					a 			 -> Task a					| descr d & iTask a
showStickyMessageA	:: !d !message  ![TaskAction a] a 			 -> Task (!ActionEvent, a)	| descr d & iTask a 

/*
* Show a basic message and some context information to the user. The user cannot end the task after reading the message. 
*
* @param description 		A description of the task to display to the user
* @param message 			A message to display to the user
* @param (b -> v)			Map defining how to convert message b to the demanded view v
*							If not specified, v = b, and the map is the identity.
* @param [TaskAction a]		A list of buttons or menus, through which the user can submit the value. 
*							If not specified a default button is rendered.
* @param b					Additional information to display
* @param a					The value is just passed for convenience
*
* @return					A (copy of) value a with (optionally) chosen action
*/
showStickyMessageAbout	:: !d !message 							 !b a 			-> Task a					| descr d & iTask a
showStickyMessageAboutA	:: !d !message !(b -> v) ![TaskAction a] !b a 			-> Task (!ActionEvent, a)	| descr d & iTask a & iTask b & iTask v


//*** Instruction tasks ***//

/* 
* Shows a instruction to the user. The user can dismiss the instruction.
*
* @param String				A short descriptive subject
* @param instruction		The instruction
* @param a					The value that is returned when the task is finished		
*
* @return					a
*/
showInstruction 			:: !String !instruction	a	-> Task a	| html instruction & iTask a

/* 
* Shows a instruction and additional context information to the user. The user can dismiss the instruction.
*
* @param String				A title message
* @param instruction		The instruction
* @param a					Additional context information
*
* @return					a
*/
showInstructionAbout 		:: !String !instruction a 	-> Task a	| html instruction & iTask a

//*** Shared variable tasks ***//

/*
* Shared variables tasks allow to specify multiple views upon the same set of data (the share). These views can be either
* viewed in separate tasks, but can also be combined locally into a single editor. Typically a view is created using an instance
* of the Editor- or Listener-type, which specify how the shared data should be transformed into a single View and -in case of an editor-
* back into the original data.
*/
class SharedVariable a | gMerge{|*|} a