alchemy-widget 0.3.0-alpha.2 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.3.0 (2026-01-21)
+
+* Add widget picker
+* Add `recreate()` method to `EditorToolbarManager` and `DocumentWatcher` for automatic recovery after server restart
+* Update `EditorToolbarManager` and `DocumentWatcher` to inherit from `Alchemy.Syncable.Specialized` for automatic type derivation and recreation support
+* Add `replaced` event handler to `BaseToolbarElement` to automatically switch to new manager instance after server restart
+* Add error handling in `attachDocumentWatcher()` for broken WebSocket connections
+* Add null check in `UserAvatarGroup.setUsers()` to handle missing user info gracefully
+* Fix `DocumentWatcher.addWatcher(conduit)` not awaiting the async `addWatcher(user_id, scene_id)` call, which caused viewer avatars to not appear on first edit after server restart
+
 ## 0.3.0-alpha.2 (2025-07-10)
 
 * Make `main_class_names` widget config add classes to the first child of the wrapper

package/CLAUDE.md

@@ -0,0 +1,160 @@
+# Alchemy Widget Development Guide
+
+## Overview
+
+Widget system for AlchemyMVC. Widgets are configurable content blocks with drag-and-drop editing.
+
+## Creating Custom Widgets
+
+Widgets need two files:
+- **Widget class** (`app/helper/widgets/`) - Logic and schema
+- **Element class** (`app/element/`) - HTML rendering
+
+```javascript
+// app/helper/widgets/my_widget.js
+const MyWidget = Function.inherits('Alchemy.Widget', function MyWidget(config) {
+	MyWidget.super.call(this, config);
+});
+
+// Metadata (optional) - category, description, icon, title
+MyWidget.setCategory('data');
+MyWidget.setDescription('Display custom data');
+MyWidget.setIcon('cube');
+MyWidget.setTitle('Data Table');  // Override auto-generated title
+
+MyWidget.constitute(function prepareSchema() {
+	this.schema.addField('title', 'String');
+	this.schema.addField('style', 'Enum', {values: {default: 'Default', compact: 'Compact'}});
+	this.schema.addField('css_class', 'String', {widget_config_editable: true});
+
+	// Actions appear in widget toolbar
+	let refresh = this.createAction('refresh', 'Refresh');
+	refresh.setHandler((widget_el, handle) => widget_el.instance.rerender());
+	refresh.setTester(() => true);
+	refresh.setIcon('sync');
+});
+
+MyWidget.setMethod(function populateWidget() {
+	let element = this.createElement('my-widget-element');
+	element.title = this.config.title;
+	this.widget.append(element);
+});
+```
+
+```javascript
+// app/element/my_widget_element.js
+const MyWidgetElement = Function.inherits('Alchemy.Element.App', 'MyWidgetElement');
+MyWidgetElement.setTemplateFile('elements/my_widget_element');
+MyWidgetElement.setAssignedProperty('title');
+```
+
+## Built-in Categories
+
+| Category | Name | Icon | Description |
+|----------|------|------|-------------|
+| Layout | `layout` | table-columns | Structure and organize content |
+| Text & Content | `text` | font | Text, headings, and rich content |
+| Media | `media` | image | Images, videos, and embeds |
+| Data & Forms | `data` | database | Tables, forms, and dynamic data |
+| Navigation | `navigation` | compass | Menus, links, and navigation |
+| Interactive | `interactive` | hand-pointer | Buttons, accordions, interactive elements |
+| Advanced | `advanced` | code | Custom HTML, embeds, advanced widgets |
+
+Custom categories: `MyWidget.setCategory('my-custom-category')` auto-generates title and uses puzzle-piece icon.
+
+## Registering Custom Categories
+
+Projects can register their own categories using `Widget.registerCategory()`:
+
+```javascript
+// In app/config/bootstrap.js or similar
+STAGES.getStage('load_app').addPostTask(function registerMyCategories() {
+    const Widget = Classes.Alchemy.Widget.Widget;
+    
+    Widget.registerCategory('MONITORING', {
+        name  : 'monitoring',
+        icon  : 'chart-line',
+        order : 70,  // Lower = earlier in list
+    });
+});
+```
+
+Required fields: `name`, `icon`. Optional: `order` (default: 90).
+
+Category titles are automatically translated using the category name as the microcopy key with `widget=true category=true` filters.
+
+## Toolbar Button Hooks
+
+Plugins can register toolbar buttons without modifying shared code:
+
+```javascript
+const EditorToolbarManager = Classes.Alchemy.Widget.EditorToolbarManager;
+
+// Add buttons when a model is set (e.g., "Create" button)
+EditorToolbarManager.registerModelButtonProvider((manager, model_name) => {
+    if (manager.scenario == 'my-scenario') {
+        manager.addTemplateToRender('buttons', 'my/toolbar/button', {model_name});
+    }
+});
+
+// Add buttons when a document is set (e.g., "Edit", "Preview" buttons)
+EditorToolbarManager.registerDocumentButtonProvider((manager, doc, model, model_name, pk_val) => {
+    manager.addTemplateToRender('buttons', 'my/toolbar/edit_button', {
+        record_pk: pk_val,
+    });
+});
+```
+
+## Widget Groups
+
+The widget add-menu uses `alchemy.getClassGroup('widgets')`. Only widgets in this group appear.
+
+**Direct inheritance (recommended):**
+```javascript
+const MyWidget = Function.inherits('Alchemy.Widget', function MyWidget(config) {
+	MyWidget.super.call(this, config);
+});
+// → Classes.Alchemy.Widget.MyWidget
+```
+
+**Abstract base class:**
+```javascript
+// 00_myapp_widget.js - DO NOT call startNewGroup()
+const MyAppWidget = Function.inherits('Alchemy.Widget', 'MyApp.Widget');
+MyAppWidget.makeAbstractClass();
+// → Classes.MyApp.Widget.Widget (a new namespace)
+
+// stats_widget.js
+const StatsWidget = Function.inherits('MyApp.Widget', function StatsWidget(config) {
+	StatsWidget.super.call(this, config);
+});
+// → Classes.MyApp.Widget.StatsWidget
+```
+
+**Common mistake:**
+```javascript
+// WRONG - widgets won't appear in add menu
+MyAppWidget.startNewGroup('myapp_widgets');
+```
+
+## Key Methods
+
+- `populateWidget()` - Render content, append to `this.widget`
+- `syncConfig()` - Called when editor stops, return updated config
+- `_startEditor()` / `_stopEditor()` - Editing mode hooks
+- `rerender()` - Re-render widget after config changes
+
+## Built-in Widgets
+
+`container`, `row`, `column`, `text`, `header`, `html`, `markdown`, `partial`, `alchemy_table`, `alchemy_form`, `alchemy_tabs`
+
+## Gotchas
+
+1. **`startNewGroup()` creates separate group** - Widgets won't appear in selector
+2. **Widget files in `app/helper/widgets/`** - Not `app/lib/`
+3. **`constitute()` doesn't need super** - All constitutes are queued and run in order automatically
+4. **Abstract classes need `makeAbstractClass()`** - Otherwise appear in selector
+5. **File numbering matters** - `00_base.js` loads before `10_child.js`
+6. **Toolbar requires permission** - `'alchemy.widgets.toolbar'`
+7. **Metadata before constitute()** - Call `setCategory()`, `setIcon()`, etc. after class definition but they can be anywhere (static methods set class properties)
+8. **Default category is 'advanced'** - Widgets without explicit category appear in Advanced section

package/assets/stylesheets/widget_picker.scss

@@ -0,0 +1,283 @@
+al-widget-picker {
+    display: flex;
+    flex-direction: column;
+    min-width: 500px;
+    max-width: 700px;
+    max-height: 70vh;
+    overflow: hidden;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;
+}
+
+.widget-picker-loading {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 60px 20px;
+    color: rgba(0, 0, 0, 0.5);
+
+    .spinner {
+        width: 32px;
+        height: 32px;
+        border: 3px solid rgba(0, 0, 0, 0.1);
+        border-top-color: #2563eb;
+        border-radius: 50%;
+        animation: widget-picker-spin 0.8s linear infinite;
+    }
+
+    p {
+        margin: 16px 0 0;
+        font-size: 14px;
+    }
+}
+
+@keyframes widget-picker-spin {
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+.widget-picker {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-height: 0;
+}
+
+.widget-picker-header {
+    padding: 16px;
+    border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+    flex-shrink: 0;
+}
+
+.widget-picker-search {
+    width: 100%;
+    padding: 10px 14px;
+    font-size: 14px;
+    border: 1px solid rgba(0, 0, 0, 0.15);
+    border-radius: 6px;
+    outline: none;
+    transition: border-color 0.15s, box-shadow 0.15s;
+
+    &:focus {
+        border-color: #2563eb;
+        box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.1);
+    }
+
+    &::placeholder {
+        color: rgba(0, 0, 0, 0.4);
+    }
+}
+
+.widget-picker-body {
+    display: flex;
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+}
+
+.widget-picker-categories {
+    width: 180px;
+    flex-shrink: 0;
+    padding: 12px;
+    border-right: 1px solid rgba(0, 0, 0, 0.1);
+    overflow-y: auto;
+    background: rgba(0, 0, 0, 0.02);
+}
+
+.category-btn {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    width: 100%;
+    padding: 8px 12px;
+    margin-bottom: 4px;
+    font-size: 13px;
+    font-weight: 500;
+    color: rgba(0, 0, 0, 0.7);
+    background: transparent;
+    border: none;
+    border-radius: 6px;
+    cursor: pointer;
+    transition: background-color 0.15s, color 0.15s;
+    text-align: left;
+
+    al-icon {
+        font-size: 16px;
+        opacity: 0.7;
+    }
+
+    &:hover {
+        background: rgba(0, 0, 0, 0.05);
+        color: rgba(0, 0, 0, 0.9);
+    }
+
+    &.active {
+        background: #2563eb;
+        color: white;
+
+        al-icon {
+            opacity: 1;
+        }
+    }
+}
+
+.widget-picker-list {
+    flex: 1;
+    min-height: 0;
+    padding: 12px 16px;
+    overflow-y: auto;
+}
+
+.widget-category-group {
+    margin-bottom: 20px;
+
+    &:last-child {
+        margin-bottom: 0;
+    }
+
+    &[hidden] {
+        display: none;
+    }
+}
+
+.widget-category-title {
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: rgba(0, 0, 0, 0.5);
+    margin: 0 0 8px 4px;
+}
+
+.widget-category-items {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+
+.widget-item {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    width: 100%;
+    padding: 10px 12px;
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: 8px;
+    cursor: pointer;
+    transition: background-color 0.15s, border-color 0.15s;
+    text-align: left;
+
+    &:hover {
+        background: rgba(0, 0, 0, 0.04);
+        border-color: rgba(0, 0, 0, 0.08);
+    }
+
+    &:focus {
+        outline: none;
+        background: rgba(37, 99, 235, 0.08);
+        border-color: rgba(37, 99, 235, 0.3);
+    }
+
+    &[hidden] {
+        display: none;
+    }
+}
+
+.widget-item-icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 36px;
+    height: 36px;
+    background: rgba(0, 0, 0, 0.06);
+    border-radius: 8px;
+    flex-shrink: 0;
+
+    al-icon {
+        font-size: 18px;
+        color: rgba(0, 0, 0, 0.6);
+    }
+}
+
+.widget-item-content {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
+}
+
+.widget-item-title {
+    font-size: 14px;
+    font-weight: 500;
+    color: rgba(0, 0, 0, 0.85);
+}
+
+.widget-item-description {
+    font-size: 12px;
+    color: rgba(0, 0, 0, 0.5);
+    line-height: 1.4;
+}
+
+.widget-picker-empty {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 40px 20px;
+    text-align: center;
+    color: rgba(0, 0, 0, 0.4);
+
+    al-icon {
+        font-size: 32px;
+        margin-bottom: 12px;
+        opacity: 0.5;
+    }
+
+    p {
+        margin: 0;
+        font-size: 14px;
+    }
+
+    &[hidden] {
+        display: none;
+    }
+}
+
+// Responsive: collapse categories on small screens
+@media (max-width: 600px) {
+    al-widget-picker {
+        min-width: auto;
+        width: 100%;
+    }
+
+    .widget-picker-body {
+        flex-direction: column;
+    }
+
+    .widget-picker-categories {
+        width: 100%;
+        flex-direction: row;
+        flex-wrap: wrap;
+        gap: 4px;
+        padding: 8px 12px;
+        border-right: none;
+        border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+    }
+
+    .category-btn {
+        width: auto;
+        margin-bottom: 0;
+        padding: 6px 10px;
+        font-size: 12px;
+
+        span {
+            display: none;
+        }
+
+        al-icon {
+            margin: 0;
+        }
+    }
+}

package/element/20-add_area_element.js

@@ -20,15 +20,13 @@ let AddArea = Function.inherits('Alchemy.Element.Widget.Base', function WidgetAd
 });
 
 /**
- * Show the types to add
+ * Show the widget picker dialog
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.1.0
- * @version  0.2.0
+ * @version  0.3.0
  */
-AddArea.setMethod(function showTypes(event) {
-
-	let that = this;
+AddArea.setMethod(async function showTypes(event) {
 
 	let context_button = document.querySelector('al-widget-context');
 
@@ -36,25 +34,25 @@ AddArea.setMethod(function showTypes(event) {
 		context_button.forceUnselection();
 	}
 
-	let context = this.createElement('he-context-menu');
-
-	let widgets = Object.values(alchemy.getClassGroup('widgets')).sortByPath(1, 'title');
-
-	for (let widget of widgets) {
+	// Create the widget picker element
+	let picker = this.createElement('al-widget-picker');
+	picker.target_container = this.parentElement;
+	picker.addEventListener('select', (e) => {
+		this.parentElement.addWidget(e.detail.type_name);
+	});
 
-		if (!widget.canBeAdded(that.parentElement)) {
-			continue;
-		}
+	// Create the dialog
+	let dialog = this.createElement('he-dialog');
+	dialog.setAttribute('dialog-title', 'Add Widget');
+	dialog.classList.add('widget-picker-dialog');
 
-		context.addEntry({
-			title : widget.title,
-			icon  : null,
-		}, e => {
-			that.parentElement.addWidget(widget.type_name);
-		});
-	}
+	// Wrap picker in a slot container
+	let slot = document.createElement('div');
+	slot.setAttribute('slot', 'main');
+	slot.append(picker);
+	dialog.append(slot);
 
-	context.show(event);
+	document.body.append(dialog);
 });
 
 /**