From 1303d707747e3e75fa3082d229a783d2470aa808 Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Sat, 21 Nov 2020 04:15:33 +0300
Subject: [PATCH] cleanup and docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 Viewer/features/examples.js    |  2 +-
 Viewer/features/ui-progress.js | 54 +++++++++++++++++++++++++++-------
 2 files changed, 44 insertions(+), 12 deletions(-)

diff --git a/Viewer/features/examples.js b/Viewer/features/examples.js
index c39874a7..65dafa42 100755
--- a/Viewer/features/examples.js
+++ b/Viewer/features/examples.js
@@ -604,7 +604,7 @@ var ExampleUIActions = actions.Actions({
 					&& (max += 5)
 					&& logger.emit('add', [1, 2, 3, 4, 5])
 				done < 30
-					&& (max += 3)
+					&& (max -= 1)
 					&& logger.emit('skip', 'y')
 
 				// NOTE: we add 10 here to compensate for changing max value...
diff --git a/Viewer/features/ui-progress.js b/Viewer/features/ui-progress.js
index 27f21049..7455733b 100755
--- a/Viewer/features/ui-progress.js
+++ b/Viewer/features/ui-progress.js
@@ -23,10 +23,46 @@ var ProgressActions = actions.Actions({
 
 		'progress-update-min': 200,
 
+		// Logger keywords / aliases that trigger progress actions...
+		//
+		// The builtin keywords / aliases are:
+		// 	add / added			- add one or more item to progress bar
+		// 	done				- move the progress bar by 1
+		// 	skip / skipped		- move the progress bar by 1
+		// 	close / closed		- close the progress bar
+		// 	error				- report error
+		//
+		// The progress bar will be created on first 'add' call.
+		//
+		// The progress bar will be closed when the number of added items
+		// is less or equal to the number of done or skipped items.
+		//
+		//
+		// For example:
+		//		var log = logger.push('Example')	// - define a logger...
+		// 		log.emit('add', 'some item...')		// - creates a progress bar
+		// 											//   with one item...
+		// 		log.emit('add', [ ... ])			// - adds multiple items to
+		// 											//   progress bar...
+		// 		...
+		//		log.emit('done', 'some item...')	// - close the progress bar
+		//		...
+		//
+		//
+		// Format:
+		// 	{
+		// 		<keyword>: [
+		// 			<alias>,
+		// 			...
+		// 		],
+		// 		...
+		// 	}
+		//
+		//
+		// NOTE: the builtin aliases will work even if this is empty.
 		// NOTE: each root key is also is also usable as a keyword.
-		'progress-keywords': {
+		'progress-logger-keywords': {
 			add: [
-				'added',
 				'queued',
 				'found',
 			],
@@ -36,7 +72,6 @@ var ProgressActions = actions.Actions({
 				'index',
 			],
 			skip: [
-				'skipped',
 				'skipping',
 				'removed',
 			],
@@ -139,11 +174,13 @@ var ProgressActions = actions.Actions({
 
 			// widget...
 			var widget = container.find('.progress-bar[name="'+text+'"]')
+
 			// close action...
 			if(value == 'close'){
 				widget.trigger('progressClose')
 				return }
 
+			// create if not done yet...
 			widget = widget.length == 0 ?
 				$('<div/>')
 					.addClass('progress-bar')
@@ -222,9 +259,9 @@ var ProgressActions = actions.Actions({
 
 			// get keywords...
 			var {add, done, skip, close, error} = 
-				this.config['progress-keywords'] 
+				this.config['progress-logger-keywords'] 
 				|| {}
-			// setup defaults...
+			// setup default aliases...
 			add = new Set([...(add || []), 'added'])
 			done = new Set([...(done || [])])
 			skip = new Set([...(skip || []), 'skipped'])
@@ -234,27 +271,22 @@ var ProgressActions = actions.Actions({
 			// close...
 			if(status == 'close' || close.has(status)){
 				this.showProgress(path, 'close', logger)
-
 			// added new item -- increase max...
 			// XXX show msg in the progress bar...
 			} else if(status == 'add' || add.has(status)){
 				this.showProgress(path, '+0', '+'+l, logger)
-
 			// resolved item -- increase done... 
 			} else if(status == 'done' || done.has(status)){
 				this.showProgress(path, '+'+l, logger)
-
 			// skipped item -- increase done... 
 			// XXX should we instead decrease max here???
 			// 		...if not this is the same as done -- merge...
 			} else if(status == 'skip' || skip.has(status)){
 				this.showProgress(path, '+'+l, logger)
-
 			// error...
 			// XXX STUB...
 			} else if(status == 'error' || error.has(status)){
-				this.showProgress(['Error'].concat(msg), '+0', '+'+l, logger)
-			}
+				this.showProgress(['Error'].concat(msg), '+0', '+'+l, logger) }
 		}],
 })