alchemy-widget 0.3.0-alpha.2 → 0.3.0

package/element/widget_toolbar_element.js

@@ -57,7 +57,7 @@ Toolbar.addElementGetter('button_save_all', 'al-button.save-all');
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.2.0
- * @version  0.2.0
+ * @version  0.3.0
  */
 Toolbar.setStatic(function show() {
 
@@ -71,6 +71,11 @@ Toolbar.setStatic(function show() {
 		return;
 	}
 
+	// Don't show if an al-editor-toolbar exists (e.g., in Chimera)
+	if (document.querySelector('al-editor-toolbar')) {
+		return;
+	}
+
 	toolbar = hawkejs.createElement('al-widget-toolbar');
 
 	hawkejs.scene.bottom_element.append(toolbar);
@@ -105,27 +110,27 @@ Toolbar.setMethod(function getAllRootWidgets() {
 	return result;
 });
 
+/**
+ * Get the target widgets (all root widgets for this toolbar)
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+Toolbar.setMethod(function getTargetWidgets() {
+	return this.getAllRootWidgets();
+});
+
 /**
  * Start editing all the widgets
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.2.0
- * @version  0.2.0
+ * @version  0.3.0
  */
 Toolbar.setMethod(function startEditing() {
-
-	let i;
-
 	Blast.editing = true;
-	document.body.classList.add('editing-blocks');
-
-	let elements = this.getAllRootWidgets();
-
-	for (i = 0; i < elements.length; i++) {
-		elements[i].startEditor();
-	}
-
-	this.setState('editing');
+	startEditing.super.call(this);
 });
 
 /**
@@ -133,7 +138,7 @@ Toolbar.setMethod(function startEditing() {
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.2.0
- * @version  0.2.0
+ * @version  0.3.0
  */
 Toolbar.setMethod(function stopEditing() {
 
@@ -141,123 +146,8 @@ Toolbar.setMethod(function stopEditing() {
 		return;
 	}
 
-	let i;
-
 	Blast.editing = false;
-	document.body.classList.remove('editing-blocks');
-
-	let elements = this.getAllRootWidgets();
-
-	for (i = 0; i < elements.length; i++) {
-		elements[i].stopEditor();
-	}
-
-	this.setState('ready');
-});
-
-/**
- * Save all the widgets
- *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
- * @since    0.2.0
- * @version  0.2.0
- */
-Toolbar.setMethod(async function saveAll() {
-
-	if (this._saving) {
-		try {
-			await this._saving;
-		} catch (err) {
-			// Ignore;
-		}
-	}
-
-	this._saving = null;
-
-	let elements = this.getAllRootWidgets();
-	let widget_data = [];
-	let pledge;
-
-	for (let element of elements) {
-		let entry = element.gatherSaveData();
-
-		if (entry) {
-			widget_data.push(entry);
-		}
-	}
-
-	if (widget_data.length) {
-		let config = {
-			href : alchemy.routeUrl('AlchemyWidgets#save'),
-			post : {
-				widgets: widget_data
-			}
-		};
-
-		pledge = alchemy.fetch(config);
-		this._saving = pledge;
-	}
-
-	return pledge;
-});
-
-/**
- * Save all and update the states
- *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
- * @since    0.2.0
- * @version  0.2.0
- *
- * @param    {Boolean}   before_stop
- */
-Toolbar.setMethod(async function saveAllAndUpdateButtonStates(before_stop) {
-
-	let state = 'saving',
-	    button;
-
-	if (before_stop) {
-		button = this.button_stop_and_save;
-		state += '-before-stop';
-	} else {
-		button = this.button_save_all;
-	}
-
-	this.setState(state);
-	button.setState(state);
-
-	let save_error = null;
-
-	let restore_toolbar_state = this.wrapForCurrentState(() => {
-		if (save_error) {
-			this.setState('error');
-		} else {
-			this.setState('editing')
-		}
-	});
-
-	let restore_button_state = button.wrapForCurrentState(() => {
-
-		if (save_error) {
-			button.setState('error');
-		} else {
-			button.setState('saved', 2500, 'ready');
-		}
-	});
-
-	try {
-		await this.saveAll();
-	} catch (err) {
-		save_error = err;
-	}
-
-	restore_toolbar_state();
-	restore_button_state();
-
-	if (save_error) {
-		return false;
-	}
-
-	return true;
+	stopEditing.super.call(this);
 });
 
 /**
@@ -284,11 +174,6 @@ Toolbar.setMethod(function introduced() {
 
 	if (this.toolbar_manager) {
 		this.prepareToolbarManager(this.toolbar_manager);
-	} else {
-		let manager = hawkejs.scene.exposed.toolbar_manager;
-		if (manager) {
-			this.prepareToolbarManager(manager);
-		}
 	}
 
 	this.button_start.addEventListener('activate', async e => {
@@ -354,4 +239,4 @@ Toolbar.setMethod(function connected() {
 Toolbar.setMethod(function disconnected() {
 	let html = document.querySelector('html');
 	html.classList.remove('with-al-widget-toolbar');
-});
+});

package/helper/document_watcher.js

@@ -24,11 +24,9 @@ const COLOURS = [
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.2.7
- * @version  0.2.7
+ * @version  0.3.0
  */
-const DocumentWatcher = Function.inherits('Alchemy.Syncable', 'Alchemy.Widget', function DocumentWatcher() {
-	DocumentWatcher.super.call(this, 'document_watcher');
-});
+const DocumentWatcher = Function.inherits('Alchemy.Syncable.Specialized', 'Alchemy.Widget', 'DocumentWatcher');
 
 /**
  * Create a watcher for the given document
@@ -60,6 +58,42 @@ DocumentWatcher.setStatic(function create(model, pk) {
 
 if (Blast.isNode) {
 
+	/**
+	 * Recreate a watcher after server restart.
+	 * Called by Syncable.tryRecreate() when client reconnects.
+	 *
+	 * @author   Jelle De Loecker   <jelle@elevenways.be>
+	 * @since    0.3.0
+	 * @version  0.3.0
+	 *
+	 * @param    {Conduit}   conduit
+	 * @param    {Object}    config    Contains type, id, and version from the client
+	 *
+	 * @return   {DocumentWatcher}
+	 */
+	DocumentWatcher.setStatic(async function recreate(conduit, config) {
+
+		// The config.id follows the pattern "Model:pk"
+		let parts = config.id.split(':');
+
+		if (parts.length < 2) {
+			return null;
+		}
+
+		let model = parts[0],
+		    pk = parts.slice(1).join(':'); // Handle pks with colons
+
+		// Use the existing create method which handles caching
+		let watcher = this.create(model, pk);
+
+		if (watcher) {
+			// Re-add this conduit as a watcher
+			await watcher.addWatcher(conduit);
+		}
+
+		return watcher;
+	});
+
 	/**
 	 * Add a viewer based on the conduit
 	 *
@@ -69,12 +103,13 @@ if (Blast.isNode) {
 	 *
 	 * @param    {Alchemy.Conduit}   conduit
 	 */
-	DocumentWatcher.setTypedMethod([Types.Alchemy.Conduit], function addWatcher(conduit) {
+	DocumentWatcher.setTypedMethod([Types.Alchemy.Conduit], async function addWatcher(conduit) {
 
 		let user_id = '' + conduit.getUserId(),
 		    scene_id = conduit.scene_id;
 
-		this.addWatcher(user_id, scene_id);
+		// IMPORTANT: await the async addWatcher method!
+		await this.addWatcher(user_id, scene_id);
 
 		// Watchers should also be registered as a client
 		this.registerClient(conduit);

package/helper/editor_toolbar_manager.js

@@ -9,10 +9,64 @@ const SCENE_MAP = new Map(),
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.2.7
- * @version  0.2.7
+ * @version  0.3.0
+ */
+const EditorToolbarManager = Function.inherits('Alchemy.Syncable.Specialized', 'Alchemy.Widget', 'EditorToolbarManager');
+
+/**
+ * Storage for document button providers
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+EditorToolbarManager.setStatic('document_button_providers', []);
+
+/**
+ * Storage for model button providers
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+EditorToolbarManager.setStatic('model_button_providers', []);
+
+/**
+ * Register a callback that can add toolbar buttons when a document is set.
+ * This allows plugins to add their own buttons without modifying this file.
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {Function}   callback   Function(manager, doc, model, model_name, pk_val)
+ */
+EditorToolbarManager.setStatic(function registerDocumentButtonProvider(callback) {
+
+	if (typeof callback !== 'function') {
+		throw new Error('Button provider must be a function');
+	}
+
+	this.document_button_providers.push(callback);
+});
+
+/**
+ * Register a callback that can add toolbar buttons when a model is set.
+ * This allows plugins to add their own buttons without modifying this file.
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {Function}   callback   Function(manager, model_name)
  */
-const EditorToolbarManager = Function.inherits('Alchemy.Syncable', 'Alchemy.Widget', function EditorToolbarManager() {
-	EditorToolbarManager.super.call(this, 'editor_toolbar_manager');
+EditorToolbarManager.setStatic(function registerModelButtonProvider(callback) {
+
+	if (typeof callback !== 'function') {
+		throw new Error('Button provider must be a function');
+	}
+
+	this.model_button_providers.push(callback);
 });
 
 if (Blast.isNode) {
@@ -61,6 +115,36 @@ if (Blast.isNode) {
 
 		return manager;
 	});
+
+	/**
+	 * Recreate a manager after server restart.
+	 * Called by Syncable.tryRecreate() when client reconnects.
+	 *
+	 * @author   Jelle De Loecker   <jelle@elevenways.be>
+	 * @since    0.3.0
+	 * @version  0.3.0
+	 *
+	 * @param    {Conduit}   conduit
+	 * @param    {Object}    config    Contains type, id, and version from the client
+	 *
+	 * @return   {EditorToolbarManager}
+	 */
+	EditorToolbarManager.setStatic(async function recreate(conduit, config) {
+
+		// The config.id is the scene_id from the client.
+		// Set it on the conduit if not already set, so create() can use it.
+		if (!conduit.scene_id) {
+			conduit.scene_id = config.id;
+		} else if (conduit.scene_id !== config.id) {
+			// Scene ID mismatch - this shouldn't happen but log if it does
+			log.warning('EditorToolbarManager recreate: scene_id mismatch', {
+				conduit_scene_id : conduit.scene_id,
+				config_id        : config.id,
+			});
+		}
+
+		return this.create(conduit);
+	});
 }
 
 /**
@@ -99,6 +183,24 @@ EditorToolbarManager.setStateProperty('title', {allow_client_set: false});
  */
 EditorToolbarManager.setStateProperty('scenario');
 
+/**
+ * Whether this is a user-specific dashboard
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+EditorToolbarManager.setStateProperty('is_user_dashboard', {allow_client_set: false});
+
+/**
+ * Whether the user has an ID (is logged in)
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+EditorToolbarManager.setStateProperty('has_user_id', {allow_client_set: false});
+
 /**
  * Clear the model fallback
  *
@@ -162,10 +264,11 @@ EditorToolbarManager.setTypedMethod([Types.String.optional().nullable()], functi
 		this.emitPropertyChange('model_name');
 	}
 
+	// Call registered model button providers
 	if (Blast.isNode && model_name) {
-		this.addTemplateToRender('buttons', 'chimera/toolbar/create_button', {
-			model_name: Blast.parseClassPath(model_name).map(entry => entry.underscore()).join('.'),
-		});
+		for (let provider of this.constructor.model_button_providers) {
+			provider(this, model_name);
+		}
 	}
 });
 
@@ -200,20 +303,9 @@ EditorToolbarManager.setMethod(function setDocument(doc) {
 
 	this.setDocumentWatcher(document_watcher);
 
-	if (this.scenario != 'chimera') {
-		this.addTemplateToRender('buttons', 'chimera/toolbar/edit_in_chimera_button', {
-			model_name: model_name.underscore(),
-			record_pk: pk_val,
-		});
-	}
-
-	if (model.chimera.record_preview) {
-		if (this.scenario == 'chimera') {
-			this.addTemplateToRender('buttons', 'chimera/toolbar/preview_button', {
-				model_name: model_name.underscore(),
-				record_pk: pk_val,
-			});
-		}
+	// Call registered document button providers
+	for (let provider of this.constructor.document_button_providers) {
+		provider(this, doc, model, model_name, pk_val);
 	}
 
 	return document_watcher;

package/helper/widgets/00-widget.js

@@ -35,6 +35,245 @@ Widget.makeAbstractClass();
  */
 Widget.startNewGroup('widgets');
 
+/**
+ * Standard widget categories.
+ * These are the universal categories available in all projects.
+ * Projects can register their own categories using Widget.registerCategory()
+ *
+ * Translation keys are derived automatically from the category name:
+ * - Title: category.name (e.g., "layout")
+ * - Description: "widget-category-{name}-description" (e.g., "widget-category-layout-description")
+ *
+ * Templates should pass filter parameters: widget=true category=true
+ */
+Widget.CATEGORIES = {
+	LAYOUT: {
+		name: 'layout',
+		icon: 'table-columns',
+		order: 10
+	},
+	TEXT: {
+		name: 'text',
+		icon: 'font',
+		order: 20
+	},
+	MEDIA: {
+		name: 'media',
+		icon: 'image',
+		order: 30
+	},
+	DATA: {
+		name: 'data',
+		icon: 'database',
+		order: 40
+	},
+	NAVIGATION: {
+		name: 'navigation',
+		icon: 'compass',
+		order: 50
+	},
+	INTERACTIVE: {
+		name: 'interactive',
+		icon: 'hand-pointer',
+		order: 60
+	},
+	ADVANCED: {
+		name: 'advanced',
+		icon: 'code',
+		order: 100
+	}
+};
+
+/**
+ * Storage for dynamically registered categories.
+ * Use Widget.registerCategory() to add new categories.
+ */
+Widget.REGISTERED_CATEGORIES = {};
+
+/**
+ * Register a new widget category.
+ * This allows projects to add their own categories without modifying the core.
+ *
+ * Translation keys are derived automatically from the category name:
+ * - Title: category.name (e.g., "monitoring")
+ * - Description: "widget-category-{name}-description" (e.g., "widget-category-monitoring-description")
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {string}   key              The category key (e.g., 'MONITORING')
+ * @param    {Object}   config           Category configuration
+ * @param    {string}   config.name      Internal name (e.g., 'monitoring')
+ * @param    {string}   config.icon      FontAwesome icon name
+ * @param    {number}   [config.order]   Sort order (lower = earlier, default: 90)
+ */
+Widget.setStatic(function registerCategory(key, config) {
+
+	if (!key || typeof key !== 'string') {
+		throw new Error('Category key must be a non-empty string');
+	}
+
+	if (!config || typeof config !== 'object') {
+		throw new Error('Category config must be an object');
+	}
+
+	if (!config.name || typeof config.name !== 'string') {
+		throw new Error('Category config.name must be a non-empty string');
+	}
+
+	if (!config.icon || typeof config.icon !== 'string') {
+		throw new Error('Category config.icon must be a non-empty string');
+	}
+
+	// Normalize the key to uppercase
+	key = key.toUpperCase();
+
+	// Create the category config with defaults
+	let category = {
+		name  : config.name,
+		icon  : config.icon,
+		order : config.order ?? 90
+	};
+
+	// Store in registered categories
+	this.REGISTERED_CATEGORIES[key] = category;
+
+	// Also add to CATEGORIES for backwards compatibility and easy access
+	this.CATEGORIES[key] = category;
+});
+
+/**
+ * Set the widget category
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {String}   category   The category name (use CATEGORIES.*.name or custom string)
+ */
+Widget.setStatic(function setCategory(category) {
+	this.category = category;
+});
+
+/**
+ * Set the widget description
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {String}   description   A short description of what the widget does
+ */
+Widget.setStatic(function setDescription(description) {
+	this.description = description;
+});
+
+/**
+ * Set the widget icon (FontAwesome icon name)
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {String}   icon   The icon name (e.g., 'table', 'font', 'image')
+ */
+Widget.setStatic(function setIcon(icon) {
+	this.icon = icon;
+});
+
+/**
+ * Override the auto-generated title
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {String}   title   The display title for the widget
+ */
+Widget.setStatic(function setTitle(title) {
+	this.title = title;
+});
+
+/**
+ * Get category info for a given category name.
+ * Supports built-in categories, registered categories, and custom strings.
+ * Falls back to ADVANCED category if no category is specified.
+ *
+ * Translation keys are derived from the category name at render time:
+ * - Title: category.name (e.g., "layout")
+ * - Description: "widget-category-{name}-description"
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @param    {String}   category   The category name
+ *
+ * @return   {Object}   Category info with name, icon, order
+ */
+Widget.setStatic(function getCategoryInfo(category) {
+
+	// Default to 'advanced' if no category specified
+	if (!category) {
+		return this.CATEGORIES.ADVANCED;
+	}
+
+	// Check built-in categories (includes registered ones added via registerCategory)
+	for (let key in this.CATEGORIES) {
+		if (this.CATEGORIES[key].name === category) {
+			return this.CATEGORIES[key];
+		}
+	}
+
+	// Return a default structure for unknown/custom categories
+	// These are categories set via widget.category = 'custom' without registerCategory()
+	return {
+		name  : category,
+		icon  : 'puzzle-piece',
+		order : 90
+	};
+});
+
+/**
+ * Get all available categories.
+ * Returns built-in categories, registered categories, and any custom categories
+ * discovered from widgets that set their category to a custom string.
+ *
+ * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @return   {Array}   Array of category info objects, sorted by order
+ */
+Widget.setStatic(function getAllCategories() {
+
+	let categories = new Map();
+
+	// Add built-in categories (includes registered ones added via registerCategory)
+	for (let key in this.CATEGORIES) {
+		let cat = this.CATEGORIES[key];
+		categories.set(cat.name, cat);
+	}
+
+	// Check all registered widgets for custom categories
+	// (widgets that set category to a custom string without using registerCategory)
+	let widgets = alchemy.getClassGroup('widgets');
+
+	if (widgets) {
+		for (let widget of Object.values(widgets)) {
+			let category = widget.category;
+
+			if (category && !categories.has(category)) {
+				categories.set(category, this.getCategoryInfo(category));
+			}
+		}
+	}
+
+	// Convert to array and sort by order
+	return Array.from(categories.values()).sortByPath(1, 'order');
+});
+
 /**
  * Return the class-wide schema
  *

package/helper/widgets/05-column.js

@@ -10,3 +10,7 @@
  * @param    {Object}   data
  */
 const Column = Function.inherits('Alchemy.Widget.Container', 'Column');
+
+// Widget metadata
+Column.setCategory('layout');
+Column.setIcon('grip-lines-vertical');

package/helper/widgets/05-list.js

@@ -11,6 +11,10 @@
  */
 const List = Function.inherits('Alchemy.Widget.Container', 'List');
 
+// Widget metadata
+List.setCategory('layout');
+List.setIcon('list');
+
 /**
  * Prepare the schema
  *