@iebh/tera-fy 1.0.16 → 1.0.18

package/hints.md

@@ -0,0 +1,26 @@
+TERA-fy Hints
+=============
+Hints are a single string attached to file uploads to provide some context as to where it fits within the overall process. They are usually past-tense single-words indicating the output from each stage.
+
+When attached to files they indicate that the generated file is an output from a stage. e.g. if a file is noted with the hint 'deduped' it indicates it is the product of a de-duplication stage.
+
+They are used in multiple places:
+
+* Calls to most project library handling functions - `selectProjectLibrary()`, `setProjectLibrary()`
+* Within the UI to indicate what library is used during what process
+
+
+Hint Reference
+--------------
+The following is a non-definitive list of hints that can be associated with files. In all cases the hint should be a lower-case single, past-tense word. Upper-case indicates a variable.
+
+This list should also be mirrored in the main tera-tools.com/api/tools.json meta-list.
+
+
+| Hint         | Description                                                                                                                                                  |
+|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `search`     | The product of a search design stage                                                                                                                         |
+| `deduped`    | One or more files, that are the product of a deduplication stage                                                                                             |
+| `screened-X` | One or more files from the screening stage, generally there will be one file per reviewer where `X` indicates the reviewer number starting with the number 1 |
+| `disputed`   | Generally a single file which is the product of a resolved dispute stage which merges in multiple `screened-X` files                                         |
+| `snowballed` | A file which has been through the snowballing stage                                                                                                          |

package/lib/terafy.client.js

@@ -17,16 +17,19 @@ export default class TeraFy {
 	*
 	* @type {Object}
 	* @property {Boolean} devMode Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
-	* @property {'detect'|'parent'|'child'} How to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and fallsback to 'child'
+	* @property {'detect'|'parent'|'child'|'popup'} mode How to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and switches to `modeFallback` if communication fails
+	* @property {String} modeFallback Method to use when all method detection fails
 	* @property {Number} modeTimeout How long entities have in 'detect' mode to identify themselves
 	* @property {String} siteUrl The TERA URL to connect to
 	* @property {String} restrictOrigin URL to restrict communications to
 	* @property {Array<String>} List of sandbox allowables for the embedded if in embed mode
+	* @property {Number} handshakeInterval Interval in milliseconds when sanning for a handshake
 	*/
 	settings = {
 		devMode: true,
 		mode: 'detect',
 		modeTimeout: 300,
+		modeFallback: 'child', // ENUM: 'child' (use iframes), 'popup' (use popup windows)
 		siteUrl: 'https://tera-tools.com/embed',
 		restrictOrigin: '*', // FIXME: Need to restrict this to TERA site
 		frameSandbox: [
@@ -39,8 +42,9 @@ export default class TeraFy {
 			'allow-presentation',
 			'allow-same-origin',
 			'allow-scripts',
-			'allow-top-navigation'
+			'allow-top-navigation',
 		],
+		handshakeInterval: 1000,
 	};
 
 
@@ -56,12 +60,14 @@ export default class TeraFy {
 	*
 	* @type {Object}
 	* @property {DOMElement} el The main tera-fy div wrapper
-	* @property {DOMElement} iframe The internal iFrame element
+	* @property {DOMElement} iframe The internal iFrame element  (if `settings.mode == 'child'`)
+	* @property {Window} popup The popup window context (if `settings.mode == 'popup'`)
 	* @property {DOMElement} stylesheet The corresponding stylesheet
 	*/
 	dom = {
 		el: null,
 		iframe: null,
+		popup: null,
 		stylesheet: null,
 	};
 
@@ -87,13 +93,13 @@ export default class TeraFy {
 		// For bindProjectState() - See individual plugins
 
 		// Project files
-		'getProjectFiles',
+		'selectProjectFile', 'getProjectFiles',
 
 		// Project Libraries
-		'getProjectLibrary', 'setProjectLibrary',
+		'selectProjectLibrary', 'parseProjectLibrary', 'setProjectLibrary',
 
 		// UI
-		'uiAlert',
+		'uiAlert', 'uiSplat', 'uiWindow',
 	];
 
 
@@ -149,6 +155,8 @@ export default class TeraFy {
 				window.parent.postMessage(payload, this.settings.restrictOrigin);
 			} else if (this.settings.mode == 'child') {
 				this.dom.iframe.contentWindow.postMessage(payload, this.settings.restrictOrigin);
+			} else if (this.settings.mode == 'popup') {
+				this.dom.popup.postMessage(payload, this.settings.restrictOrigin);
 			} else if (this.settings.mode == 'detect') {
 				throw new Error('Call init() or detectMode() before trying to send data to determine the mode');
 			} else {
@@ -305,7 +313,8 @@ export default class TeraFy {
 			]))
 			.then(()=> this.rpc('setServerMode', // Tell server what mode its in
 				this.settings.mode == 'child' ? 'embedded'
-				: this.settings.mode == 'parent' ? 'window'
+				: this.settings.mode == 'parent' ? 'frame'
+				: this.settings.mode == 'popup' ? 'popup'
 				: (()=> { throw(`Unknown server mode "${this.settings.mode}"`) })()
 			))
 			.then(()=> Promise.all( // Init all plugins (with this outer module as the context)
@@ -327,7 +336,7 @@ export default class TeraFy {
 		if (this.settings.mode != 'detect') { // Dev has specified a forced mode to use
 			return this.settings.mode;
 		} else if (window.self === window.parent) { // This frame is already at the top
-			return 'child';
+			return this.settings.modeFallback;
 		} else { // No idea - try messaging
 			return Promise.resolve()
 				.then(()=> this.settings.mode = 'parent') // Switch to parent mode...
@@ -339,7 +348,7 @@ export default class TeraFy {
 						.then(()=> resolve())
 				}))
 				.then(()=> 'parent')
-				.catch(()=> 'child')
+				.catch(()=> this.settings.modeFallback)
 		}
 	}
 
@@ -373,9 +382,34 @@ export default class TeraFy {
 				this.dom.el.append(this.dom.iframe);
 				break;
 			case 'parent':
-				this.debug('Using TERA site stack parent');
+				this.debug('Using TERA window parent');
 				resolve();
 				break;
+			case 'popup':
+				this.debug('Injecting TERA site as a popup window');
+				this.dom.popup = window.open(this.settings.siteUrl, '_blank', 'popup=1, location=0, menubar=0, status=0, scrollbars=0, width=500, height=600');
+
+				// Loop until the window context returns a handshake
+				(()=> {
+					let handshakeCount = 0;
+					let handshakeTimer;
+
+					const tryHandshake = ()=> {
+						this.debug('Trying handshake', ++handshakeCount);
+
+						clearTimeout(handshakeTimer);
+						handshakeTimer = setTimeout(tryHandshake, this.settings.handshakeInterval);
+
+						this.rpc('handshake')
+							.then(()=> {
+								clearTimeout(handshakeTimer);
+								this.debug('Popup window accepted handshake');
+								resolve();
+							});
+					};
+					tryHandshake();
+				})();
+				break;
 			default:
 				throw new Error(`Unsupported mode "${this.settings.mode}" when calling injectComms()`);
 		}
@@ -434,6 +468,7 @@ export default class TeraFy {
 				document.head.appendChild(this.dom.stylesheet);
 				break;
 			case 'parent':
+			case 'popup':
 				break;
 			default:
 				throw new Error(`Unsupported mode "${this.settings.mode}" when injectStylesheet()`);
@@ -624,7 +659,11 @@ export default class TeraFy {
 	* This is an pre-requisite step for requireProject()
 	*
 	* @function requireUser
-	* @returns {Promise} A promise which will resolve if the there is a user and they are logged in
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.forceRetry=false] Forcabily try to refresh the user state
+	*
+	* @returns {Promise<User>} The current logged in user or null if none
 	*/
 
 
@@ -798,6 +837,35 @@ export default class TeraFy {
 	* @property {String} mime The associated mime type for the file
 	*/
 
+	/**
+	* Data structure for a file filter
+	* @name FileFilters
+	*
+	* @property {Boolean} [library=false] Restrict to library files only
+	* @property {String} [filename] CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
+	* @property {String} [basename] CSV of @momsfriendlydevco/match expressions to filter the basename by
+	* @property {String} [ext] CSV of @momsfriendlydevco/match expressions to filter the file extension by
+	*/
+
+
+	/**
+	* Prompt the user to select a library to operate on
+	*
+	* @function selectProjectFile
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.title="Select a file"] The title of the dialog to display
+	* @param {String|Array<String>} [options.hint] Hints to identify the file to select in array order of preference
+	* @param {FileFilters} [options.filters] Optional file filters
+	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed
+	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @param {FileFilters} [options.filter] Optional file filters
+	*
+	* @returns {Promise<ProjectFile>} The eventually selected file
+	*/
+
 
 	/**
 	* Fetch the files associated with a given project
@@ -807,25 +875,60 @@ export default class TeraFy {
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
 	* @param {Boolean} [options.meta=true] Pull meta information for each file entity
 	*
-	* @returns {Promise<ProjectFile>} A collection of project files for the given project
+	* @returns {Promise<Array<ProjectFile>>} A collection of project files for the given project
+	*/
+
+
+	/**
+	* Prompt the user to select a library to operate on and return a array of references in a given format
+	*
+	* @function selectProjectLibrary
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.title="Select a citation library"] The title of the dialog to display
+	* @param {String|Array<String>} [options.hint] Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
+	* @param {Boolean} [options.allowUpload=true] Allow uploading new files
+	* @param {Boolean} [options.allowRefresh=true] Allow the user to manually refresh the file list
+	* @param {Boolean} [options.allowDownloadZip=true] Allow the user to download a Zip of all files
+	* @param {Boolean} [options.allowCancel=true] Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed
+	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @param {FileFilters} [options.filters] Optional file filters, defaults to citation library selection only
+	* @param {*} [options.*] Additional options - see `parseProjectLibrary()`
+	*
+	* @returns {Promise<Array<Ref>>} A collection of references from the selected file
 	*/
 
 
 	/**
-	* Fetch the active projects citation library
+	* Convert a project file into a library of citations
 	*
-	* @function getProjectLibrary
-	* @param {String} [path] Optional file path to use, if omitted the contents of `options` are used to guess at a suitable file
+	* @function parseProjectLibrary
+	* @param {String} path File path to read, if omitted the contents of `options` are used to guess at a suitable file
 	*
 	* @param {Object} [options] Additional options to mutate behaviour
 	* @param {String} [options.format='json'] Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
 	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
-	* @param {Boolean} [options.multiple=false] Allow selection of multiple libraries
 	* @param {Function} [options.filter] Optional async file filter, called each time as `(File:ProjectFile)`
 	* @param {Function} [options.find] Optional async final stage file filter to reduce all candidates down to one subject file
-	* @param {String|Array<String>} [options.hint] Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
 	*
-	* @returns {Promise<Array<ProjectFile>>} Collection of references for the selected library matching the given hint + filter, this could be a zero length array
+	* @returns {Promise<Array<Ref>>|Promise<*>} A collection of references (default bevahiour) or a whatever format was requested
+	*/
+
+
+	/**
+	* Save back a citation library from some input
+	*
+	* @function setProjectLibrary
+	* @param {String} [path] File path to save back to
+	* @param {Array<RefLibRef>} Collection of references for the selected library
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {String} [options.format='json'] Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object)
+	* @param {Boolean} [options.autoRequire=true] Run `requireProject()` automatically before continuing
+	* @param {String} [options.hint] Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
+	* @param {Boolean} [options.overwrite=true] Allow existing file upsert
+	* @param {Object} [options.meta] Optional meta data to merge into the file data
+	*
+	* @returns {Promise} A promise which resolves when the save operation has completed
 	*/
 
 
@@ -856,5 +959,33 @@ export default class TeraFy {
 	* @returns {Promise} A promise which resolves when the alert has been dismissed
 	*/
 
+
+	/**
+	* Display HTML content full-screen within TERA
+	* This function is ideally called within a requestFocus() wrapper
+	*
+	* @function uiSplat
+	* @param {DOMElement|String|false} content Either a prepared DOM element or string to compile, set to falsy to remove existing content
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean|String} [options.logo=false] Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL
+	*/
+
+
+	/**
+	* Open a popup window containing a new site
+	*
+	* @function uiWindow
+	* @param {String} url The URL to open
+	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Number} [options.width=500] The desired width of the window
+	* @param {Number} [options.height=600] The desired height of the window
+	* @param {Boolean} [options.center=true] Attempt to center the window on the screen
+	* @param {Object} [options.permissions] Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code)
+	*
+	* @returns {WindowProxy} The opened window object (if `noopener` is not set in permissions)
+	*/
+
 	// }}}
 }