alchemy-form 0.3.0-alpha.4 → 0.3.0

package/CHANGELOG.md

@@ -1,4 +1,20 @@
-## 0.3.0-alpha.4
+## 0.3.0 (2026-01-21)
+
+* Release as v0.3.0
+
+## 0.3.0-alpha.6
+
+* Fix model and form resolution during client-side re-render when element is not yet in DOM
+* Add fallback to default wrappers when field_type cannot be determined
+* Implement `handleScrollEvent()` in `al-virtual-scroll` element - throttled culling of invisible elements during scroll
+* Implement keyboard navigation for selected values in `al-select` - arrow keys now move between selected items when focus is on the component
+* Fix potential deadlock in `al-field` when setting value during render - skip rerender if already rendering
+
+## 0.3.0-alpha.5 (2025-07-10)
+
+* Add `al-datetime-input` to properly handle Date values with timezones
+
+## 0.3.0-alpha.4 (2025-07-10)
 
 * Always make `al-field`'s `getFieldType()` method return a string
 * Add the `mixed` field view

package/CLAUDE.md

@@ -0,0 +1,348 @@
+# Alchemy Form Development Guide
+
+## Overview
+
+Alchemy Form is a comprehensive form handling plugin for AlchemyMVC that provides custom HTML elements for building, validating, and rendering forms. It supports complex field types, relationships, arrays, schemas, and advanced features like query builders.
+
+## Commands
+- Run tests: `npm test`
+
+## Dependencies
+- alchemymvc (>=1.4.0)
+- alchemy-media (>=0.9.0)
+- alchemy-styleboost (>=0.5.0)
+
+## Directory Structure
+
+```
+element/                     # Custom form elements (~48 files)
+├── 00_form_base.js          # Base class for all form elements
+├── 05_feedback_input.js     # Abstract element with error/success feedback
+├── 10_dataprovider.js       # Base for elements with remote data
+├── 40_stateful.js           # State management for elements
+├── al_form.js               # Main form element
+├── al_field.js              # Base field element
+├── al_field_array.js        # Array field wrapper
+├── al_field_schema.js       # Schema/nested field support
+├── al_field_translatable.js # Multilingual field support
+├── al_select.js             # Dropdown selector
+├── al_table.js              # Data table element
+├── al_button.js             # Interactive button with states
+├── al_query_builder*.js     # Query builder UI (5 files)
+└── ...                      # Other input types
+
+helper/
+├── query_builder_ns.js      # Query builder namespace & criteria
+├── field_recompute_handler.js # Computed field handler
+├── form_actions/            # Form action handlers
+└── query_builder_variable_definition/ # Variable type definitions
+
+controller/
+└── form_api_controller.js   # Backend API controller
+
+config/
+└── routes.js                # API routes
+```
+
+## Core Element Hierarchy
+
+```
+Alchemy.Element.Form.Base
+├── al-form                         # Main form container
+├── al-field                        # Base field element
+│   ├── al-field-array              # Array fields
+│   ├── al-field-schema             # Nested schema fields
+│   └── al-field-translatable       # Multilingual fields
+├── FeedbackInput (abstract)
+│   ├── al-string-input
+│   ├── al-number-input
+│   └── al-password-input
+├── WithDataprovider (abstract)
+│   ├── al-select
+│   ├── al-table
+│   └── al-query-builder
+└── Stateful (abstract)
+    └── al-button
+```
+
+## Key Attributes
+
+### Form Element (`<al-form>`)
+- `action` - URL/route for submission
+- `method` - POST/GET
+- `model` - Associated data model name
+- `readonly` - Read-only form flag
+- `serialize-entire-document` - Include all document properties
+
+### Field Element (`<al-field>`)
+- `field-name` - Name in record
+- `field-type` - Type of field (text, number, select, schema, array, etc.)
+- `field-view` - Override template name
+- `wrapper-view` - Override wrapper template
+- `data-src` - Data source URL for dynamic options
+- `min-entry-count`, `max-entry-count` - Array bounds
+- `readonly` - Read-only field
+
+### Shared Attributes
+- `purpose` - "edit" or "view" mode
+- `mode` - "inline", "standalone", etc.
+- `zone` - "admin", "frontend", "chimera", etc.
+
+## Form Usage
+
+### Basic Form
+```html
+<al-form action="/api/save" model="User">
+    <al-field field-name="username"></al-field>
+    <al-field field-name="email"></al-field>
+    <al-button behaviour="submit">Save</al-button>
+</al-form>
+```
+
+### Programmatic Form Control
+```javascript
+const form = document.querySelector('al-form');
+
+// Set document data
+form.document = userDoc;
+
+// Get form values
+const values = form.getMainValue();
+
+// Validate
+const valid = await form.validate();
+
+// Submit
+await form.submit();
+
+// Show validation errors
+form.showViolations(validationError);
+
+// Find specific field
+const field = form.findFieldByPath('address.city');
+```
+
+## Field Types
+
+### Basic Types
+- `text`, `string` - Text input
+- `number` - Numeric input
+- `password` - Password input
+- `boolean` - Toggle switch
+- `date`, `datetime` - Date picker
+
+### Complex Types
+- `enum` - Dropdown selection
+- `schema` - Nested object fields
+- `array` - Repeatable field groups
+- `belongsto` - Foreign key relationship
+- `hasmany` - Multiple relationships
+
+### Array Fields
+```html
+<al-field field-name="tags" field-type="array"
+          min-entry-count="1" max-entry-count="10">
+</al-field>
+```
+
+### Schema Fields
+```html
+<al-field field-name="address" field-type="schema">
+    <!-- Nested fields rendered automatically -->
+</al-field>
+```
+
+## Select Element
+
+```html
+<al-select data-src="/api/form/data/related"
+           method="POST"
+           page-size="20">
+</al-select>
+```
+
+Properties:
+- `recordsource` - Set data source
+- `dataprovider` - Data loading instance
+- `page`, `page_size` - Pagination
+
+## Query Builder
+
+```html
+<al-query-builder>
+    <al-query-builder-group condition="and">
+        <al-query-builder-entry type="qb_entry">
+            <!-- Field, operator, value inputs -->
+        </al-query-builder-entry>
+    </al-query-builder-group>
+</al-query-builder>
+```
+
+Apply to criteria:
+```javascript
+const Qb = Blast.Classes.Alchemy.QueryBuilder;
+Qb.applyToCriteria(queryBuilderValue, criteria, inverted);
+```
+
+Supported operators: `equals`, `ne`, `starts_with`, `ends_with`, `is_empty`, `is_null`, `>`, `<`, `>=`, `<=`
+
+## Button States
+
+```html
+<al-button behaviour="submit">
+    <al-state name="default">Save</al-state>
+    <al-state name="busy">Saving...</al-state>
+    <al-state name="done">Saved!</al-state>
+    <al-state name="error">Error</al-state>
+</al-button>
+```
+
+```javascript
+button.setState('busy', 3000, 'default');  // Revert after 3s
+```
+
+## Table Element
+
+```html
+<al-table data-src="/api/records" method="POST">
+    <!-- Columns configured via schema or attributes -->
+</al-table>
+
+<al-pager></al-pager>
+```
+
+## API Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/api/form/data/related` | POST | Fetch related records for select/autocomplete |
+| `/api/form/data/qbdata` | POST | Load query builder variable data |
+| `/api/form/data/recompute/{model}/{field}` | POST | Recompute computed field |
+| `/api/form/data/enum_info/{model}/{id}` | GET | Get enum display info |
+
+## Computed Fields
+
+Fields can be automatically recomputed when dependencies change:
+
+```javascript
+// Server-side: define computed field
+MyModel.addField('full_name', 'String', {
+    computed: {
+        fields: ['first_name', 'last_name'],
+        compute: doc => `${doc.first_name} ${doc.last_name}`
+    }
+});
+```
+
+Client-side automatically calls recompute API when dependencies change.
+
+## Validation
+
+Validation is schema-based and returns violations:
+
+```javascript
+// Form validates against model schema
+const valid = await form.validate();
+
+// Show errors inline
+form.showViolations(err);
+
+// Access specific field errors
+field.showError(violation);
+```
+
+## Template Customization
+
+Field templates follow a fallback chain:
+1. `field-view` attribute value
+2. `{purpose}_{mode}` template
+3. `{purpose}` template
+4. Default template
+
+```html
+<al-field field-name="bio" field-view="custom_textarea"></al-field>
+```
+
+## Event Handling
+
+```javascript
+// Form submit
+form.addEventListener('submit', (e) => {
+    e.preventDefault();
+    // Custom handling
+});
+
+// Field change
+field.addEventListener('change', (e) => {
+    console.log('New value:', e.target.value);
+});
+
+// Button activation
+button.addEventListener('activate', (e) => {
+    // Button was clicked
+});
+```
+
+## Field Value Internals
+
+### Value Storage
+
+`al-field` uses several internal mechanisms to manage values:
+
+- **`LAST_SET_VALUE` (Symbol)** - Stores the most recently set value, even before render completes
+- **`value_to_render`** - Property used in templates, returns `LAST_SET_VALUE` or falls back to `original_value`
+- **`value_element`** - The actual input element inside the field (may not exist until rendered)
+- **`original_value`** - The initial value, used for change detection
+
+### Value Flow
+
+```
+setValue(value)
+    ↓
+Store in LAST_SET_VALUE
+    ↓
+If value_element exists and has setter → set directly
+    ↓
+Otherwise → rerender() to update template
+    ↓
+Template uses value_to_render → renders value_element
+```
+
+### Render Safety
+
+When setting values during a render (before `value_element` exists):
+- Check `this.hasAttribute('data-he-rerendering')` before calling `rerender()`
+- The value is already in `LAST_SET_VALUE` and will be picked up via `value_to_render`
+- Calling `rerender()` during a render can cause deadlocks
+
+### Key Methods
+
+| Method | Description |
+|--------|-------------|
+| `valueElementHasValuePropertySetter()` | Checks if value_element can accept values directly |
+| `value_to_render` (property) | Returns the value for template rendering |
+| `prepareRenderVariables()` | Hawkejs lifecycle method, sets up template variables |
+
+## Gotchas
+
+1. **Field paths:** Use dot notation for nested fields (`address.city`)
+
+2. **Array indices:** Array fields include index in path (`items.0.name`)
+
+3. **Schema supplier:** Schema fields need parent field reference via `getSchemaSupplierField()`
+
+4. **Dataprovider base:** Elements using remote data extend `WithDataprovider`, not `Base`
+
+5. **Purpose inheritance:** Child elements inherit `purpose` from parent form
+
+6. **Value serialization:** `form.getMainValue()` returns unwrapped object, `form.value` wraps with model name
+
+7. **Readonly mode:** Set `purpose="view"` for read-only display
+
+8. **Zone-based templates:** Use `zone` attribute for context-specific rendering (admin vs frontend)
+
+9. **Rerender during render:** Never call `rerender()` when `data-he-rerendering` attribute is present - can cause deadlock
+
+10. **Value before render:** Values set before first render are stored in `LAST_SET_VALUE` symbol and accessed via `value_to_render`
+
+11. **value vs value_to_render:** In templates, use `value_to_render` which handles pending values correctly

package/assets/stylesheets/form/elements/_datetime.scss

@@ -0,0 +1,6 @@
+al-datetime-input {
+	> * {
+		width: 100%;
+		height: 100%;
+	}
+}

package/assets/stylesheets/form/elements/index.scss

@@ -17,3 +17,4 @@
 @use "_virtual_scroll.scss";
 @use "_settings_editor.scss";
 @use "_enum_badge.scss";
+@use "_datetime.scss";

package/element/al_datetime_input.js

@@ -0,0 +1,127 @@
+/**
+ * The al-datetime-input:
+ * Populate an input on the browser-side with correct timezone info
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+const DatetimeInput = Function.inherits('Alchemy.Element.Form.Base', 'DatetimeInput');
+
+/**
+ * Get/set the mode
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+DatetimeInput.setAttribute('datemode', null, function setMode(datemode) {
+	this.populateInputWithValue(this.value, datemode);
+	return datemode;
+});
+
+/**
+ * Get/set the value
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+DatetimeInput.setAttribute('value', null, function setValue(value) {
+	return this.populateInputWithValue(value, this.datemode);
+});
+
+/**
+ * Set the value with a function call
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+DatetimeInput.setMethod(function setValue(value) {
+	this.value = value;
+});
+
+/**
+ * Revalidate the value
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @return   {Object[]}
+ */
+DatetimeInput.setMethod(function populateInput() {
+	return this.populateInputWithValue(this.value, this.datemode);
+});
+
+/**
+ * Revalidate the value
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ *
+ * @return   {Object[]}
+ */
+DatetimeInput.setMethod(function populateInputWithValue(value, datemode) {
+
+	let iso_date,
+	    date;
+
+	if (value) {
+		date = Date.create(value);
+		iso_date = date.toISOString();
+	} else {
+		iso_date = '';
+	}
+
+	value = iso_date;
+
+	if (Blast.isServer) {
+		return value;
+	}
+
+	if (arguments.length == 1) {
+		datemode = this.datemode;
+	}
+
+	let input = this.querySelector('input');
+
+	if (!datemode) {
+		datemode = 'datetime';
+	}
+
+	if (!input) {
+		input = this.createElement('input');
+		input.setAttribute('type', datemode + '-local');
+	}
+
+	if (!value) {
+		input.value = '';
+		return '';
+	}
+
+	let formatted;
+
+	if (datemode == 'date') {
+		formatted = date.format('Y-m-d');
+	} else {
+		formatted = date.format('Y-m-d\\TH:i:s');
+	}
+
+	input.value = formatted;
+
+	return iso_date;
+});
+
+/**
+ * Added to the DOM
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    0.3.0
+ * @version  0.3.0
+ */
+DatetimeInput.setMethod(function introduced() {
+	this.populateInput();
+});

package/element/al_field.js

@@ -139,7 +139,7 @@ Field.setAttribute('placeholder');
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.1.0
- * @version  0.2.0
+ * @version  0.3.0
  */
 Field.enforceProperty(function alchemy_form(new_value) {
 
@@ -153,8 +153,22 @@ Field.enforceProperty(function alchemy_form(new_value) {
 		if (!new_value && this.alchemy_field_schema && this.alchemy_field_schema.alchemy_field) {
 			new_value = this.alchemy_field_schema.alchemy_field.alchemy_form;
 		}
+
+		// Fallback: try to find al-form through the hawkejs renderer's ancestor chain
+		// This is needed during client-side re-render when the element isn't in the DOM yet
+		if (!new_value && this.hawkejs_renderer) {
+			let ancestor = this.hawkejs_renderer.current_variables?.$ancestor_element;
+
+			if (ancestor) {
+				ancestor = ancestor.queryUp('al-form');
+
+				if (ancestor) {
+					new_value = ancestor;
+				}
+			}
+		}
 	}
-	
+
 	return new_value;
 });
 
@@ -401,7 +415,7 @@ Field.setMethod(function getPathEntryName() {
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.1.0
- * @version  0.1.0
+ * @version  0.3.0
  */
 Field.setProperty(function model() {
 
@@ -414,6 +428,27 @@ Field.setProperty(function model() {
 	if (form) {
 		return form.model;
 	}
+
+	// Fallback: check if we have a stored resolved model from a previous render
+	// This is especially useful during client-side re-render when queryUp fails
+	if (this.assigned_data?._resolved_model) {
+		return this.assigned_data._resolved_model;
+	}
+
+	// Fallback: try to get the model name from the field_context
+	// Note: this only works if field_context is a different element (not this)
+	if (this.field_context && this.field_context !== this && this.field_context.model) {
+		return this.field_context.model;
+	}
+
+	// Fallback: try to get it from the alchemy_field_schema
+	if (this.alchemy_field_schema) {
+		let parent_field = this.alchemy_field_schema.alchemy_field;
+
+		if (parent_field) {
+			return parent_field.model;
+		}
+	}
 }, function setModel(model) {
 	return this.setAttribute('model', model);
 });
@@ -520,7 +555,7 @@ Field.setProperty(function view_files() {
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.1.0
- * @version  0.1.11
+ * @version  0.3.0
  */
 Field.setProperty(function wrapper_files() {
 
@@ -554,8 +589,11 @@ Field.setProperty(function wrapper_files() {
 		result.push(view);
 	}
 
+	// If no wrappers were found (e.g., field_type couldn't be determined),
+	// add a fallback to the default wrapper so slots can still render
 	if (result.length == 0) {
-		return false;
+		result.push(this.generateTemplatePath('wrappers', view_type, 'default'));
+		result.push(this.generateTemplatePath('wrappers', 'default', 'default'));
 	}
 
 	return result;
@@ -696,8 +734,10 @@ Field.setProperty(function value() {
 	this[LAST_SET_VALUE] = value;
 
 	if (!this.valueElementHasValuePropertySetter()) {
-		// @TODO: Rerendering during a render causes a deadlock 
-		if (has_changed) {
+		// Only rerender if we're not already rendering.
+		// If we are rendering, the value is stored in LAST_SET_VALUE
+		// and will be picked up via value_to_render.
+		if (has_changed && !this.hasAttribute('data-he-rerendering')) {
 			this.rerender();
 		}
 	} else {
@@ -796,6 +836,14 @@ Field.setMethod(function prepareRenderVariables() {
 	let value = this.value_to_render,
 	    value_is_empty = value == null || value === '' || (Array.isArray(value) ? value.length == 0 : false);
 
+	// Resolve the model name now while we might still have DOM access
+	// Store it in assigned_data so it survives re-renders
+	let resolved_model = this.model;
+
+	if (resolved_model && !this.assigned_data._resolved_model) {
+		this.assigned_data._resolved_model = resolved_model;
+	}
+
 	let result = {
 		alchemy_field  : this,
 		field_context  : this,

package/element/al_select.js

@@ -1567,7 +1567,7 @@ AlchemySelect.setMethod(function _getSelection(input) {
  *
  * @author   Jelle De Loecker <jelle@develry.be>
  * @since    0.1.0
- * @version  0.1.0
+ * @version  0.3.0
  */
 AlchemySelect.setMethod(function advanceSelection(direction) {
 
@@ -1606,7 +1606,44 @@ AlchemySelect.setMethod(function advanceSelection(direction) {
 			}
 		}
 	} else {
-		console.log('@TODO: Advance selection');
+		// Focus is on the al-select element itself, not the type_area.
+		// Move focus/highlight to the appropriate value item.
+		let active_item = this.wrapper?.querySelector('al-select-item.active');
+		let value_items = this.wrapper?.querySelectorAll('al-select-item.value');
+
+		if (!value_items || value_items.length === 0) {
+			// No value items to navigate, focus the input
+			this.type_area.focus();
+			return;
+		}
+
+		let items_array = Array.from(value_items);
+		let current_index = active_item ? items_array.indexOf(active_item) : -1;
+		let new_index;
+
+		if (current_index === -1) {
+			// No active item yet, select first or last based on direction
+			new_index = direction > 0 ? 0 : items_array.length - 1;
+		} else {
+			new_index = current_index + direction;
+		}
+
+		// Remove active class from current item
+		if (active_item) {
+			active_item.classList.remove('active');
+		}
+
+		// Check bounds
+		if (new_index < 0 || new_index >= items_array.length) {
+			// Moved past the edge, focus the input
+			this.type_area.focus();
+			return;
+		}
+
+		// Set new active item
+		let new_active = items_array[new_index];
+		new_active.classList.add('active');
+		new_active.focus();
 	}
 
 });

package/element/al_virtual_scroll.js

@@ -379,10 +379,22 @@ VirtualScroll.setMethod(function getDomKeyRange() {
  *
  * @author   Jelle De Loecker   <jelle@elevenways.be>
  * @since    0.2.10
- * @version  0.2.10
+ * @version  0.3.0
  */
 VirtualScroll.setMethod(function handleScrollEvent() {
-	// @TODO
+	
+	// Throttle the culling operation to avoid performance issues
+	// during rapid scrolling
+	if (this._cull_scheduled) {
+		return;
+	}
+	
+	this._cull_scheduled = true;
+	
+	requestAnimationFrame(() => {
+		this._cull_scheduled = false;
+		this.cullInvisibleElements();
+	});
 });
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "alchemy-form",
 	"description": "Form plugin for Alchemy",
-	"version": "0.3.0-alpha.4",
+	"version": "0.3.0",
 	"repository": {
 		"type" : "git",
 		"url"  : "https://github.com/11ways/alchemy-form.git"

package/view/form/inputs/edit/date.hwk

@@ -1,13 +1,13 @@
-<%
-if (value) {
-	value = value.format('Y-m-d');
-}
-%>
-<input
-	value=<% value %>
-	class="alchemy-field-value"
-	type="date"
-	form=<% form_id %>
-	name=<% path %>
-	pattern="\d{4}-\d{2}-\d{2}"
->
+<al-datetime-input
+	datemode="date"
+>
+	<% $0.setValue(value) %>
+	<input
+		value=<% value %>
+		class="alchemy-field-value"
+		type="date"
+		form=<% form_id %>
+		name=<% path %>
+		pattern="\d{4}-\d{2}-\d{2}"
+	>
+</al-datetime-input>

package/view/form/inputs/edit/datetime.hwk

@@ -1,20 +1,13 @@
-<%
-
-if (value) {
-
-	// Make sure it's a date
-	value = Date.create(value);
-
-	// According to MDN `toISOString()` should work,
-	// but neither Chrome or Firefox allow that format (it still contains timezone info)
-	value = value.format('Y-m-d\\TH:i:s');
-}
-%>
-<input
-	value=<% value %>
-	class="alchemy-field-value"
-	type="datetime-local"
-	form=<% form_id %>
-	name=<% path %>
-	pattern="\d{4}-\d{2}-\d{2} \d{1,2}:\d{1,2}(?::\d{1,2})?"
->
+<al-datetime-input
+	datemode="datetime"
+>
+	<% $0.setValue(value) %>
+	<input
+		class="alchemy-field-value"
+		type="datetime-local"
+		form=<% form_id %>
+		name=<% path %>
+		pattern="\d{4}-\d{2}-\d{2} \d{1,2}:\d{1,2}(?::\d{1,2})?"
+		value=""
+	>
+</al-datetime-input>