@iebh/tera-fy 1.0.1 → 1.0.2

package/lib/terafy.client.js

@@ -1,7 +1,10 @@
+import {cloneDeep} from 'lodash-es';
 import {nanoid} from 'nanoid';
 import {reactive, watch} from 'vue';
 import diff from 'just-diff';
 
+/* globals globalThis */
+
 
 /**
 * Main Tera-Fy Client (class singleton) to be used in a frontend browser
@@ -46,14 +49,14 @@ export default class TeraFy {
 	* @type {Array<String>}
 	*/
 	methods = [
-		// Basics
+		// Messages
 		'handshake',
 
 		// Session
 		'getUser',
 
 		// Projects
-		'bindProject', 'getProject', 'getProjects', 'requireProject', 'selectProject',
+		'bindProject', 'getProject', 'getProjects', 'setActiveProject', 'requireProject', 'selectProject',
 
 		// Project state
 		'getProjectStateSnapshot', 'applyProjectStatePatch',
@@ -101,7 +104,7 @@ export default class TeraFy {
 			{
 				TERA: 1,
 				id: message.id || nanoid(),
-				...message,
+				...cloneDeep(message), // Need to clone to resolve promise nasties
 			},
 			this.settings.restrictOrigin
 		);
@@ -113,6 +116,7 @@ export default class TeraFy {
 	*
 	* @param {String} method The method name to call
 	* @param {*} [...] Optional arguments to pass to the function
+	*
 	* @returns {Promise<*>} The resolved output of the server function
 	*/
 	rpc(method, ...args) {
@@ -131,18 +135,36 @@ export default class TeraFy {
 	*/
 	acceptMessage(rawMessage) {
 		let message = rawMessage.data;
-		if (!message.TERA) return; // Ignore non-TERA signed messages
+		if (!message.TERA || !message.id) return; // Ignore non-TERA signed messages
+		this.debug('Recieved', message);
 
-		if (message?.id && this.acceptPostboxes[message.id]) { // Postbox waiting for reply
+		if (message?.action == 'response' && this.acceptPostboxes[message.id]) { // Postbox waiting for reply
 			if (message.isError === true) {
 				this.acceptPostboxes[message.id].reject(message.response);
 			} else {
 				this.acceptPostboxes[message.id].resolve(message.response);
 			}
+		} else if (message?.action == 'rpc') {
+			return Promise.resolve()
+				.then(()=> this[message.method].apply(this, message.args))
+				.then(res => this.sendRaw({
+					id: message.id,
+					action: 'response',
+					response: res,
+				}))
+				.catch(e => {
+					console.warn(`TERA-FY client threw on RPC:${message.method}:`, e);
+					this.sendRaw({
+						id: message.id,
+						action: 'response',
+						isError: true,
+						response: e.toString(),
+					});
+				})
 		} else if (message?.id) {
-			console.info(`Ignoring message ID ${message.id} - was meant for someone else?`);
+			this.debug(`Ignoring message ID ${message.id} - was meant for someone else?`);
 		} else {
-			console.log('Unexpected incoming TERA-FY CLIENT message', {message});
+			this.debug('Unexpected incoming TERA-FY CLIENT message', {message});
 		}
 	}
 
@@ -209,7 +231,7 @@ export default class TeraFy {
 		// Queue up event chain when document loads
 		this.dom.iframe.setAttribute('sandbox', 'allow-downloads allow-scripts allow-same-origin');
 		this.dom.iframe.addEventListener('load', ()=> {
-			console.log('TERA EMBED FRAME READY');
+			this.debug('TERA EMBED FRAME READY');
 		});
 
 		// Start document load sequence + append to DOM
@@ -250,7 +272,7 @@ export default class TeraFy {
 			'}',
 
 			// Fullscreen functionality {{{
-			'body.tera-fy-fullscreen {',
+			'body.tera-fy-focus {',
 				'overflow: hidden;',
 
 				'& #tera-fy {',
@@ -279,7 +301,23 @@ export default class TeraFy {
 	}
 	// }}}
 
-	// Client unique functions - bindProjectState(), toggleFullscreen() {{{
+	// Utility - debug(), bindProjectState(), toggleFullscreen() {{{
+
+	/**
+	* Debugging output function
+	* This function will only act if `settings.devMode` is truthy
+	*
+	* @param {String} [msg...] Output to show
+	*/
+	debug(...msg) {
+		if (!this.settings.devMode) return;
+		console.log(
+			'%c[TERA-FY CLIENT]',
+			'font-weight: bold; color: #ff5722;',
+			...msg,
+		);
+	}
+
 
 	/**
 	* Return a Vue reactive object that can be read/written which whose changes will transparently be written back to the TERA server instance
@@ -317,7 +355,7 @@ export default class TeraFy {
 						stateReactive,
 						(newVal, oldVal) => {
 							let diff = diff(newVal, oldVal);
-							console.log('DEBUG APPLY DIFF', diff);
+							this.debug('APPLY DIFF', diff);
 							this.applyProjectStatePatch(diff);
 						},
 						{
@@ -333,12 +371,13 @@ export default class TeraFy {
 
 
 	/**
-	* Fit the nested TERA server to a full-screen context
+	* Fit the nested TERA server to a full-screen
 	* This is usually because the server component wants to perform some user activity like calling $prompt
-	* @param {String|Boolean} [isFullscreen='toggle'] Whether to fullscreen the embedded component
+	* @param {String|Boolean} [isFocused='toggle'] Whether to fullscreen the embedded component
 	*/
-	toggleFullscreen(isFullscreen) {
-		globalThis.document.body.classList.toggle('tera-fy-fullscreen', isFullscreen === 'toggle' ? undefined : isFullscreen);
+	toggleFocus(isFocused = 'toggle') {
+		this.debug('Request focus', {isFocused});
+		globalThis.document.body.classList.toggle('tera-fy-focus', isFocused === 'toggle' ? undefined : isFocused);
 	}
 
 	// }}}

package/lib/terafy.server.js

@@ -1,3 +1,6 @@
+import {cloneDeep} from 'lodash-es';
+import {nanoid} from 'nanoid';
+
 /**
 * Server-side functions available to the Tera-Fy client library
 *
@@ -18,7 +21,102 @@ export default class TeraFyServer {
 		restrictOrigin: '*',
 	};
 
-	// Messages - acceptMessage() {{{
+	// Contexts - createContext(), messageEvent, senderRpc() {{{
+	/**
+	* Create a context based on a shallow copy of this instance + additional functionality for the incoming MessageEvent
+	* This is used by acceptMessage to provide a means to reply / send messages to the originator
+	*
+	* @param {MessageEvent} e Original message event to base the new context on
+	*
+	* @returns {Object} A context, which is this instance extended with additional properties
+	*/
+	createContext(e) {
+		// Rather ugly shallow-copy-of instance hack from https://stackoverflow.com/a/44782052/1295040
+		return Object.assign(Object.create(Object.getPrototypeOf(this)), this, {
+			messageEvent: e,
+			sendRaw(message) { // Override sendRaw because we can't do this inline for security reasons
+				this.debug('Send to message source', e.origin, {message});
+				e.source.postMessage(
+					{
+						TERA: 1,
+						...cloneDeep(message), // Need to clone to resolve promise nasties
+					},
+					this.settings.restrictOrigin
+				);
+			},
+		});
+	}
+
+
+	/**
+	* MessageEvent context
+	* Only available if the context was created via `createContext()`
+	*
+	* @type {MessageEvent}
+	*/
+	messageEvent = null;
+
+
+	/**
+	* Request an RPC call from the original sender of a mesasge
+	* This function only works if the context was sub-classed via `createContext()`
+	*
+	* @param {String} method The method name to call
+	* @param {*} [...] Optional arguments to pass to the function
+	*
+	* @returns {Promise<*>} The resolved output of the server function
+	*/
+	senderRpc(method, ...args) {
+		if (!this.messageEvent) throw new Error('senderRpc() can only be used if given a context from `createContext()`');
+
+		return this.send({
+			action: 'rpc',
+			method,
+			args,
+		});
+	}
+	// }}}
+
+	// Messages - handshake(), sendRaw(), acceptMessage(), requestFocus() {{{
+
+	/**
+	* Return basic server information as a form of validation
+	*
+	* @returns {Promise<Object>} Basic promise result
+	* @property {Date} date Server date
+	*/
+	handshake() {
+		return {
+			date: new Date(),
+		};
+	}
+
+
+	/**
+	* Send a message + wait for a response object
+	*
+	* @param {Object} message Message object to send
+	* @returns {Promise<*>} A promise which resolves when the operation has completed with the remote reply
+	*/
+	send(message) {
+		if (!this.messageEvent) throw new Error('send() can only be used if given a context from `createContext()`');
+
+		let id = nanoid();
+
+		this.acceptPostboxes[id] = {}; // Stub for the deferred promise
+		this.acceptPostboxes[id].promise = new Promise((resolve, reject) => {
+			Object.assign(this.acceptPostboxes[id], {
+				resolve, reject,
+			});
+			this.sendRaw({
+				id,
+				...message,
+			});
+		});
+
+		return this.acceptPostboxes[id].promise;
+	}
+
 
 	/**
 	* Send raw message content to the client
@@ -26,10 +124,11 @@ export default class TeraFyServer {
 	* @param {Object} message Message object to send
 	*/
 	sendRaw(message) {
+		this.debug('SendRaw', {message});
 		globalThis.parent.postMessage(
 			{
 				TERA: 1,
-				...message,
+				...cloneDeep(message), // Need to clone to resolve promise nasties
 			},
 			this.settings.restrictOrigin
 		);
@@ -44,15 +143,21 @@ export default class TeraFyServer {
 	acceptMessage(rawMessage) {
 		let message = rawMessage.data;
 		if (!message.TERA) return; // Ignore non-TERA signed messages
-		console.log('TERA-FY Server message', {message});
+		this.debug('Recieved', message);
 
 		Promise.resolve()
 			.then(()=> {
-				if (message.action == 'rpc') { // Relay RPC calls
+				if (message?.action == 'response' && this.acceptPostboxes[message.id]) { // Postbox waiting for reply
+					if (message.isError === true) {
+						this.acceptPostboxes[message.id].reject(message.response);
+					} else {
+						this.acceptPostboxes[message.id].resolve(message.response);
+					}
+				} else if (message.action == 'rpc') { // Relay RPC calls
 					if (!this[message.method]) throw new Error(`Unknown RPC method "${message.method}"`);
-					return this[message.method].call(this, message.args);
+					return this[message.method].apply(this.createContext(rawMessage), message.args);
 				} else {
-					console.log('Unexpected incoming TERA-FY SERVER message', {message});
+					this.debug('Unexpected incoming TERA-FY SERVER message', {message});
 					throw new Error('Unknown message format');
 				}
 			})
@@ -71,23 +176,32 @@ export default class TeraFyServer {
 				});
 			})
 	}
-	// }}}
-	// Basics - handshake() {{{
+
 
 	/**
-	* Return basic server information as a form of validation
+	* Listening postboxes, these correspond to outgoing message IDs that expect a response
+	*/
+	acceptPostboxes = {};
+
+
+	/**
+	* Wrapper function which runs a callback after the frontend UI has obtained focus
+	* This is to fix the issue where the front-end needs to switch between a regular webpage and a focused TERA iFrame wrapper
+	* Any use of $prompt or other UI calls should be wrapped here
 	*
-	* @returns {Promise<Object>} Basic promise result
-	* @property {Date} date Server date
+	* @param {Function} cb Async function to run in focused mode
+	*
+	* @returns {Promise<*>} A promise which resolves with the resulting inner callback payload
 	*/
-	handshake() {
-		return {
-			date: new Date(),
-		};
+	requestFocus(cb) {
+		return Promise.resolve()
+			.then(()=> this.senderRpc('toggleFocus', true))
+			.then(()=> cb.call(this))
+			.finally(()=> this.senderRpc('toggleFocus', false))
 	}
 	// }}}
 
-	// Session / user - getUser() {{{
+	// Session / User - getUser() {{{
 
 	/**
 	* User / active session within TERA
@@ -175,14 +289,37 @@ export default class TeraFyServer {
 	}
 
 
+	/**
+	* Set the currently active project within TERA
+	*
+	* @param {Object|String} project The project to set as active - either the full Project object or its ID
+	*/
+	setActiveProject(project) {
+		return app.service('$projects').setActive(project)
+	}
+
+
 	/**
 	* Ask the user to select a project from those available - if one isn't already active
 	* Note that this function will percist in asking the uesr even if they try to cancel
 	*
+	* @param {Object} [options] Additional options to mutate behaviour
+	* @param {Boolean} [options.autoSetActiveProject=true] After selecting a project set that project as active in TERA
+	* @param {String} [options.title="Select a project to work with"] The title of the dialog to display
+	* @param {String} [options.noSelectTitle='Select project'] Dialog title when warning the user they need to select something
+	* @param {String} [options.noSelectBody='A project needs to be selected to continue'] Dialog body when warning the user they need to select something
+	*
 	* @returns {Promise<Project>} The active project
 	*/
-	requireProject() {
-		let $prompt = app.service('$prompt');
+	requireProject(options) {
+		let settings = {
+			autoSetActiveProject: true,
+			title: 'Select a project to work with',
+			noSelectTitle: 'Select project',
+			noSelectBody: 'A project needs to be selected to continue',
+			...options,
+		};
+
 		return this.getProject()
 			.then(active => {
 				if (active) return active; // Use active project
@@ -195,18 +332,25 @@ export default class TeraFyServer {
 						.then(project => resolve(project))
 						.catch(e => {
 							if (e == 'cancel') {
-								return $prompt.dialog({
-									title: 'Select project',
-									body: 'A project needs to be selected to continue',
-									buttons: ['ok'],
-								})
+								return this.requestFocus(()=>
+									app.service('$prompt').dialog({
+										title: settings.noSelectTitle,
+										body: settings.noSelectBody,
+										buttons: ['ok'],
+									})
+								)
 								.then(()=> askProject())
 								.catch(reject)
 							} else {
 								reject(e);
 							}
 						})
-				});
+					askProject(); // Kick off intial project loop
+				})
+				.then(async (project) => {
+					if (settings.autoSetActiveProject) await this.setActiveProject(project);
+					return project;
+				})
 			})
 	}
 
@@ -226,21 +370,21 @@ export default class TeraFyServer {
 			allowCancel: true,
 			...options,
 		};
-		let $projects = app.service('$projects');
-		let $prompt = app.service('$prompt');
-		return $projects.promise()
-			.then(()=> $prompt.dialog({
-				title: 'Select project',
-				component: 'projectsSelect',
-				dialogClose: 'reject',
-				buttons: settings.allowCancel && ['cancel'],
-			}))
+
+		return app.service('$projects').promise()
+			.then(()=> this.requestFocus(()=>
+				app.service('$prompt').dialog({
+					title: settings.title,
+					component: 'projectsSelect',
+					buttons: settings.allowCancel && ['cancel'],
+				})
+			))
 	}
 
 
 	// }}}
 
-	// Project State {{{
+	// Project State - getProjectStateSnapshot(), applyProjectStatePatch() {{{
 
 	/**
 	* Return the current, full snapshot state of the active project
@@ -267,12 +411,12 @@ export default class TeraFyServer {
 	* Apply a computed `just-diff` patch to the current project state
 	*/
 	applyProjectStatePatch(patch) {
-		console.log('Applying sever state patch', {patch});
+		this.debug('Applying sever state patch', {patch});
 	}
 
 	// }}}
 
-	// Project Libraries {{{
+	// Project Libraries - getProjectLibrary(), setProjectLibrary() {{{
 
 	/**
 	* Fetch the active projects citation library
@@ -336,27 +480,29 @@ export default class TeraFyServer {
 
 
 	/**
-	* Set or toggle devMode
-	*
-	* @param {String|Boolean} [devModeEnabled='toggle'] Optional boolean to force dev mode
-	*
-	* @returns {TeraFy} This chainable terafy instance
+	* Initialize the browser listener
 	*/
-	toggleDevMode(devModeEnabled = 'toggle') {
-		this.settings.devMode = devModeEnabled === 'toggle'
-			? !this.settings.devMode
-			: devModeEnabled;
-
-		return this;
+	init() {
+		globalThis.addEventListener('message', this.acceptMessage.bind(this));
 	}
+	// }}}
 
+	// Utility - debug() {{{
 
 	/**
-	* Initialize the browser listener
+	* Debugging output function
+	* This function will only act if `settings.devMode` is truthy
+	*
+	* @param {String} [msg...] Output to show
 	*/
-	init() {
-		console.log('TERA server init');
-		globalThis.addEventListener('message', this.acceptMessage.bind(this));
+	debug(...msg) {
+		if (!this.settings.devMode) return;
+		console.log(
+			'%c[TERA-FY SERVER]',
+			'font-weight: bold; color: #4d659c;',
+			...msg,
+		);
 	}
+
 	// }}}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap --serve --servedir=.",
@@ -53,6 +53,7 @@
     "node": ">=18"
   },
   "peerDependencies": {
+    "lodash-es": "^4.17.21",
     "just-diff": "^6.0.2",
     "nanoid": "^5.0.2",
     "vue": "^3.3.7"