@iebh/tera-fy 1.0.5 → 1.0.6

package/README.md

@@ -1,6 +1,30 @@
 TERA-fy
 =======
-TERA website worker.
+TERA website worker, intended to be embedded with TERA tools.
 
 * [API workbench](https://iebh.github.io/TERA-fy/)
 * [TERA-fy Class API](./api.md)
+
+
+TERA-fy is a component intended to be dropped into a sub-site / tool used with in the main [TERA](https://tera-tools.com) project. It provides various functionality like data sync with the parent TERA instance.
+
+
+Quick Start
+-----------
+
+```javascript
+import TeraFy from '@iebh/tera-fy';
+import TerafyVue from '@iebh/tera-fy/plugins/vue';
+let terafy = new TeraFy()
+	.set('devMode', true) // Set this option to see debugging messages
+	.use(TerafyVue); // Add the Vue plugin
+
+// Initialize everything
+await terafy.init();
+
+// Require that the active session has a project selected
+await terafy.requireProject();
+
+// Go fetch the state of the active project
+let projectState = await terafy.getProjectState(); //= Object representing the active project
+```

package/lib/terafy.client.js

@@ -105,14 +105,19 @@ export default class TeraFy {
 	* @param {Object} message Message object to send
 	*/
 	sendRaw(message) {
-		this.dom.iframe.contentWindow.postMessage(
-			{
+		let payload;
+		try {
+			payload = {
 				TERA: 1,
 				id: message.id || nanoid(),
 				...cloneDeep(message), // Need to clone to resolve promise nasties
-			},
-			this.settings.restrictOrigin
-		);
+			};
+			this.dom.iframe.contentWindow.postMessage(payload, this.settings.restrictOrigin);
+		} catch (e) {
+			this.debug('ERROR', 'Message compose client->server:', e);
+			this.debug('ERROR', 'Attempted to dispatch payload client->server', payload);
+			throw e;
+		}
 	}
 
 
@@ -181,7 +186,7 @@ export default class TeraFy {
 
 	// }}}
 
-	// Init - constructor(), toggleDevMode(), init(), injectMain(), injectStylesheet(), injectMethods() {{{
+	// Init - constructor(), init(), inject*() {{{
 
 	/**
 	* Setup the TERA-fy client singleton
@@ -193,42 +198,34 @@ export default class TeraFy {
 	}
 
 
-	/**
-	* Set or toggle devMode
-	*
-	* @param {String|Boolean} [devModeEnabled='toggle'] Optional boolean to force dev mode
-	*
-	* @returns {TeraFy} This chainable terafy instance
-	*/
-	toggleDevMode(devModeEnabled = 'toggle') {
-		this.settings.devMode = devModeEnabled === 'toggle'
-			? !this.settings.devMode
-			: devModeEnabled;
-
-		this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
-		return this;
-	}
-
-
 	/**
 	* Initalize the TERA client singleton
+	*
+	* @returns {Promise<TeraFy>} An eventual promise which will resovle with this terafy instance
 	*/
 	init() {
 		window.addEventListener('message', this.acceptMessage.bind(this));
 
-		this.injectMain();
-		this.injectStylesheet();
-		this.injectMethods();
-		return Promise.all(this.plugins
-			.map(plugin => plugin.init())
-		);
+		return Promise.all([
+			// Init core functions async
+			this.injectComms(),
+			this.injectStylesheet(),
+			this.injectMethods(),
+
+			// Init all plugins
+			...this.plugins
+				.map(plugin => plugin.init()),
+		])
+			.then(()=> this)
 	}
 
 
 	/**
 	* Find an existing active TERA server OR initalize one
+	*
+	* @returns {Promise} A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
 	*/
-	injectMain() {
+	injectComms() { return new Promise(resolve => {
 		this.dom.el = document.createElement('div')
 		this.dom.el.id = 'tera-fy';
 		this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
@@ -240,12 +237,13 @@ export default class TeraFy {
 		this.dom.iframe.setAttribute('sandbox', 'allow-downloads allow-scripts allow-same-origin');
 		this.dom.iframe.addEventListener('load', ()=> {
 			this.debug('TERA EMBED FRAME READY');
+			resolve();
 		});
 
 		// Start document load sequence + append to DOM
 		this.dom.iframe.src = this.settings.siteUrl;
 		this.dom.el.append(this.dom.iframe);
-	}
+	})}
 
 
 	/**
@@ -306,20 +304,33 @@ export default class TeraFy {
 		this.methods.forEach(method =>
 			this[method] = this.rpc.bind(this, method)
 		);
+		this.debug('Remote methods installed:', this.methods);
 	}
 	// }}}
 
-	// Utility - debug(), use(), mixin(), toggleFullscreen() {{{
+	// Utility - debug(), use(), mixin(), toggleDevMode(), toggleFocus() {{{
 
 	/**
 	* Debugging output function
 	* This function will only act if `settings.devMode` is truthy
 	*
+	* @param {'INFO'|'LOG'|'WARN'|'ERROR'} [status] Optional prefixing level to mark the message as. 'WARN' and 'ERROR' will always show reguardless of devMode being enabled
 	* @param {String} [msg...] Output to show
 	*/
 	debug(...msg) {
-		if (!this.settings.devMode) return;
-		console.log(
+		let method = 'log';
+		// Argument mangling for prefixing method {{{
+		if (typeof msg[0] == 'string' && ['INFO', 'LOG', 'WARN', 'ERROR'].includes(msg[0])) {
+			method = msg.shift().toLowerCase();
+		}
+		// }}}
+
+		if (
+			['INFO', 'LOG'].includes(method)
+			&& !this.settings.devMode
+		) return;
+
+		console[method](
 			'%c[TERA-FY CLIENT]',
 			'font-weight: bold; color: #ff5722;',
 			...msg,
@@ -389,18 +400,34 @@ export default class TeraFy {
 	}
 
 
+	/**
+	* Set or toggle devMode
+	*
+	* @param {String|Boolean} [devModeEnabled='toggle'] Optional boolean to force dev mode
+	*
+	* @returns {TeraFy} This chainable terafy instance
+	*/
+	toggleDevMode(devModeEnabled = 'toggle') {
+		this.settings.devMode = devModeEnabled === 'toggle'
+			? !this.settings.devMode
+			: devModeEnabled;
+
+		if (this.dom.el) // Have we actually set up yet?
+			this.dom.el.classList.toggle('dev-mode', this.settings.devMode);
+
+		return this;
+	}
+
+
 	/**
 	* 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} [isFocused='toggle'] Whether to fullscreen the embedded component
-	*
-	* @returns {TeraFy} This chainable terafy instance
 	*/
 	toggleFocus(isFocused = 'toggle') {
 		this.debug('Request focus', {isFocused});
 		globalThis.document.body.classList.toggle('tera-fy-focus', isFocused === 'toggle' ? undefined : isFocused);
-		return this;
 	}
 	// }}}
 }

package/lib/terafy.server.js

@@ -31,18 +31,22 @@ export default class TeraFyServer {
 	* @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
+		// Rather ugly shallow-copy-of instancr 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(
-					{
+				let payload;
+				try {
+					payload = {
 						TERA: 1,
 						...cloneDeep(message), // Need to clone to resolve promise nasties
-					},
-					this.settings.restrictOrigin
-				);
+					};
+					e.source.postMessage(payload, this.settings.restrictOrigin);
+				} catch (e) {
+					this.debug('ERROR', 'Message compose/reply via server->cient:', e);
+					this.debug('ERROR', 'Attempted to dispatch payload server(via reply)->client', payload);
+					throw e;
+				}
 			},
 		});
 	}
@@ -124,14 +128,18 @@ export default class TeraFyServer {
 	* @param {Object} message Message object to send
 	*/
 	sendRaw(message) {
-		this.debug('SendRaw', {message});
-		globalThis.parent.postMessage(
-			{
+		let payload;
+		try {
+			payload = {
 				TERA: 1,
 				...cloneDeep(message), // Need to clone to resolve promise nasties
-			},
-			this.settings.restrictOrigin
-		);
+			};
+			globalThis.parent.postMessage(payload, this.settings.restrictOrigin);
+		} catch (e) {
+			this.debug('ERROR', 'Attempted to dispatch payload server->client', payload);
+			this.debug('ERROR', 'Message compose server->client:', e);
+		}
+
 	}
 
 
@@ -497,7 +505,18 @@ export default class TeraFyServer {
 	* @param {String} [msg...] Output to show
 	*/
 	debug(...msg) {
-		if (!this.settings.devMode) return;
+		let method = 'log';
+		// Argument mangling for prefixing method {{{
+		if (typeof msg[0] == 'string' && ['INFO', 'LOG', 'WARN', 'ERROR'].includes(msg[0])) {
+			method = msg.shift().toLowerCase();
+		}
+		// }}}
+
+		if (
+			['INFO', 'LOG'].includes(method)
+			&& !this.settings.devMode
+		) return;
+
 		console.log(
 			'%c[TERA-FY SERVER]',
 			'font-weight: bold; color: #4d659c;',

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@iebh/tera-fy",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "TERA website worker",
   "scripts": {
     "dev": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap --serve --servedir=.",
     "build": "concurrently 'npm:build:*'",
     "build:client": "esbuild --platform=browser --format=esm --bundle lib/terafy.client.js --outfile=dist/terafy.js --minify --sourcemap",
-    "build:docs": "jsdoc2md --files lib/terafy.*.js lib/plugins/*.js >api.md",
+    "build:docs": "jsdoc2md --files lib/terafy.*.js plugins/*.js >api.md",
     "lint": "eslint ."
   },
   "type": "module",

package/plugins/vue.js

@@ -67,7 +67,7 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 	* Provide a Vue@3 compatible plugin
 	*/
 	vuePlugin() {
-		let context = this;
+		let $tera = this;
 
 		return {
 
@@ -90,9 +90,14 @@ export default class TeraFyPluginVue extends TeraFyPluginBase {
 					...options,
 				};
 
-				app.config.globalProperties[settings.globalName] = {
-					// Create project binding
-					// state: context.bindProjectState(settings.stateOptions),
+				// Make this module available globally
+				app.config.globalProperties[settings.globalName] = $tera;
+
+				// Bind $tera.state to the active project
+				// TODO: context.bindProjectState(settings.stateOptions),
+				$tera.state = {
+					id: 'TERAPROJ',
+					name: 'A fake project',
 				};
 			},