neo.mjs 10.0.0-beta.1 → 10.0.0-beta.3

package/learn/guides/Forms.md

@@ -1 +1,449 @@
-## todo
+The Neo.mjs Forms Engine provides a powerful and flexible way to build
+user interfaces for data input and validation. This guide will walk you
+through the core concepts and practical usage of forms in Neo.mjs,
+from basic field creation to advanced validation and nested structures.
+
+## 1. Basic Form Creation
+
+At its core, a form in Neo.mjs is a `Neo.form.Container`. This container
+manages a collection of form fields and provides methods for data
+retrieval, validation, and submission.
+
+To create a simple form, you define a `Neo.form.Container` and add
+`Neo.form.field.Text` or other field modules to its `items` config.
+
+```javascript readonly
+import FormContainer from '../../src/form/Container.mjs';
+import TextField     from '../../src/form/field/Text.mjs';
+
+class MySimpleForm extends FormContainer {
+    static config = {
+        className: 'MySimpleForm',
+        layout   : {ntype: 'vbox', align: 'start'},
+        items    : [{
+            module   : TextField,
+            labelText: 'First Name',
+            name     : 'firstName',
+            required : true
+        }, {
+            module   : TextField,
+            labelText: 'Last Name',
+            name     : 'lastName'
+        }]
+    }
+}
+```
+
+In this example:
+*   `module: TextField` specifies the type of form field.
+*   `labelText` defines the visible label for the field.
+*   `name` is crucial for data management; it defines the key under
+    which the field's value will be stored when retrieving form data.
+*   `required: true` enables basic validation, ensuring the field is
+    not left empty.
+
+## 2. Field Types
+
+Neo.mjs offers a rich set of pre-built form field types, all extending
+`Neo.form.field.Base`. These fields cover a wide range of input needs:
+
+*   **Text-based Inputs**: `TextField`, `TextArea`, `EmailField`,
+    `PasswordField`, `PhoneField`, `UrlField`, `SearchField`,
+    `DisplayField` (read-only), `HiddenField`.
+*   **Numeric Inputs**: `NumberField`, `CurrencyField`, `RangeField`.
+*   **Selection Inputs**: `ComboBox`, `Chip`, `ColorField`, `DateField`,
+    `TimeField`, `CountryField`, `ZipCodeField`.
+*   **Choice Inputs**: `CheckBox`, `Radio`, `Switch`.
+*   **File Upload**: `FileUpload`.
+
+You can find the full list of available fields and their configurations
+in the `src/form/field/` directory.
+
+## 3. Data Management
+
+A key strength of Neo.mjs forms is their integrated state management. The `Neo.form.Container` automatically manages form data based on field names, eliminating the need for external state management libraries or manual state tree definitions. This significantly simplifies data handling and reduces boilerplate.
+
+The `Neo.form.Container` provides powerful methods for managing form data.
+
+### Getting Form Values
+
+To retrieve all values from a form, use the asynchronous `getSubmitValues()`
+method. This method returns a plain JavaScript object where keys correspond
+to the `name` attributes of your fields.
+
+```javascript readonly
+// Assuming 'myForm' is an instance of your form container
+const formValues = await myForm.getSubmitValues();
+console.log(formValues);
+// Example output: { firstName: 'John', lastName: 'Doe' }
+```
+
+### Nested Data Structures
+
+The `name` attribute supports dot notation to create nested data structures.
+This is particularly useful for organizing complex form data.
+
+```javascript readonly
+import FormContainer from '../../src/form/Container.mjs';
+import TextField     from '../../src/form/field/Text.mjs';
+
+class UserForm extends FormContainer {
+    static config = {
+        className: 'UserForm',
+        layout   : {ntype: 'vbox', align: 'start'},
+        items    : [{
+            module   : TextField,
+            labelText: 'User First Name',
+            name     : 'user.profile.firstName'
+        }, {
+            module   : TextField,
+            labelText: 'User Last Name',
+            name     : 'user.profile.lastName'
+        }, {
+            module   : TextField,
+            labelText: 'Address Street',
+            name     : 'user.address.street'
+        }]
+    }
+}
+
+// ... later, after the form is rendered and values are entered
+const userFormValues = await myUserForm.getSubmitValues();
+console.log(userFormValues);
+/*
+Output:
+{
+    user: {
+        profile: {
+            firstName: 'Jane',
+            lastName : 'Doe'
+        },
+        address: {
+            street: '123 Main St'
+        }
+    }
+}
+*/
+```
+
+### Setting Form Values
+
+You can pre-populate a form or update its values programmatically using
+the `setValues(values, suspendEvents)` method. The `values` object should
+mirror the structure of the data returned by `getSubmitValues()`.
+
+```javascript readonly
+// To set values for the UserForm example above:
+await myUserForm.setValues({
+    user: {
+        profile: {
+            firstName: 'Alice',
+            lastName : 'Smith'
+        },
+        address: {
+            street: '456 Oak Ave'
+        }
+    }
+});
+```
+
+The optional `suspendEvents` parameter (default `false`) can be set to
+`true` to prevent `change` events from firing for each field during the
+update, which can be useful for large data sets.
+
+### Resetting Forms
+
+The `reset(values)` method allows you to clear or reset form fields.
+If no `values` object is provided, fields will be reset to `null` or their
+`emptyValue` (if configured). If `values` are provided, fields will be
+reset to those specific values.
+
+```javascript readonly
+// Reset all fields to their default empty state
+await myForm.reset();
+
+// Reset specific fields to new values
+await myForm.reset({
+    firstName: 'Default Name'
+});
+```
+
+## 4. Validation
+
+Neo.mjs forms provide robust validation capabilities, both built-in and
+customizable.
+
+### Built-in Validation
+
+Many field types come with built-in validation rules:
+
+*   **`required`**: Ensures a field is not empty.
+*   **`minLength` / `maxLength`**: For text-based fields, validates the
+    length of the input.
+*   **`minValue` / `maxValue`**: For numeric fields, validates the range
+    of the input.
+*   **`inputPattern`**: A regular expression to validate the input format.
+    (e.g., `EmailField`, `UrlField`, `ZipCodeField` use this internally).
+
+You can configure these directly on the field:
+
+```javascript readonly
+import TextField from '../../src/form/field/Text.mjs';
+
+// ...
+items: [{
+    module      : TextField,
+    inputPattern: /^[a-zA-Z0-9_]+$/, // Alphanumeric and underscore only
+    labelText   : 'Username',
+    name        : 'username',
+    required    : true,
+    minLength   : 5,
+    maxLength   : 20
+}]
+```
+
+Error messages for built-in validations can be customized using `errorText*`
+configs (e.g., `errorTextRequired`, `errorTextMaxLength`).
+
+### Custom Validation (`validator`)
+
+For more complex validation logic, you can use the `validator` config on
+any field. This should be a function that receives the field instance as
+its argument and returns `true` if the value is valid, or a string
+(the error message) if it's invalid.
+
+```javascript readonly
+import TextField from '../../src/form/field/Text.mjs';
+
+// ...
+items: [{
+    module   : TextField,
+    labelText: 'Password',
+    name     : 'password',
+    reference: 'passwordField' // Add a reference to the password field
+}, {
+    module   : TextField,
+    labelText: 'Confirm Password',
+    name     : 'confirmPassword',
+    validator: function(field) {
+        // Access the password field using getClosestForm().getReference()
+        const passwordField = field.getClosestForm().getReference('passwordField');
+
+        if (field.value !== passwordField.value) {
+            return 'Passwords do not match'
+        }
+        return true
+    }
+}]
+```
+
+### Displaying Errors
+
+Errors are automatically displayed below the field when validation fails.
+The `useAlertState` config (globally set in `apps/form/Overwrites.mjs`)
+can change the visual styling of required but empty fields from red to orange.
+
+The `clean` property on a field determines if errors are shown immediately.
+By default, `clean` is `true` until the user interacts with the field or
+`validate(false)` is called.
+
+### Form Validation State
+
+You can check the overall validity of a form using:
+
+*   **`isValid()`**: An asynchronous method that returns `true` if all
+    fields in the form (and its nested forms) are valid, `false` otherwise.
+    It also triggers validation for all fields.
+
+    ```javascript readonly
+    const formIsValid = await myForm.isValid();
+    if (formIsValid) {
+        console.log('Form is valid!');
+    } else {
+        console.log('Form has errors.');
+    }
+    ```
+
+*   **`getFormState()`**: An asynchronous method that returns a string
+    indicating the overall state of the form:
+    *   `'clean'`: All fields are untouched and valid.
+    *   `'valid'`: All fields are valid.
+    *   `'invalid'`: At least one field is invalid.
+    *   `'inProgress'`: Some fields are valid, some are clean.
+
+    ```javascript readonly
+    const state = await myForm.getFormState();
+    console.log('Form state:', state);
+    ```
+
+## 5. Nested Forms
+
+Neo.mjs allows for true nested forms, providing unparalleled structural
+flexibility. This is achieved by nesting `Neo.form.Container` instances
+or using `Neo.form.Fieldset`.
+
+### Using `Neo.form.Fieldset`
+
+`Neo.form.Fieldset` extends `Neo.form.Container` and is ideal for
+grouping related fields visually. It can also be collapsed.
+
+```javascript readonly
+import Fieldset      from '../../src/form/Fieldset.mjs';
+import FormContainer from '../../src/form/Container.mjs';
+import TextField     from '../../src/form/field/Text.mjs';
+
+class NestedFieldsetForm extends FormContainer {
+    static config = {
+        className: 'NestedFieldsetForm',
+        layout   : {ntype: 'vbox', align: 'start'},
+        items    : [{
+            module   : Fieldset,
+            title    : 'Personal Information',
+            formGroup: 'person', // Data will be nested under 'person'
+            items    : [{
+                module   : TextField,
+                labelText: 'First Name',
+                name     : 'firstName',
+                required : true
+            }, {
+                module   : TextField,
+                labelText: 'Last Name',
+                name     : 'lastName'
+            }]
+        }, {
+            module   : Fieldset,
+            title    : 'Contact Information',
+            formGroup: 'contact', // Data will be nested under 'contact'
+            items    : [{
+                module   : TextField,
+                labelText: 'Email',
+                name     : 'email',
+                required : true
+            }, {
+                module   : TextField,
+                labelText: 'Phone',
+                name     : 'phone'
+            }]
+        }]
+    }
+}
+
+// Example getSubmitValues() output:
+/*
+{
+    person: {
+        firstName: 'John',
+        lastName : 'Doe'
+    },
+    contact: {
+        email: 'john.doe@example.com',
+        phone: '123-456-7890'
+    }
+}
+*/
+```
+
+The `formGroup` config on `Fieldset` (or any `Form.Container`) automatically
+nests the data of its child fields under the specified key.
+
+### Nesting `Form.Container` Instances
+
+You can directly nest `Form.Container` instances to create more complex
+hierarchies. This is demonstrated in `apps/form/view/FormPageContainer.mjs`,
+which extends `Neo.form.Container` but uses a `div` for its `vdom` tag
+to avoid invalid HTML (`<form>` inside `<form>`).
+
+```javascript readonly
+// Example from apps/form/view/FormPageContainer.mjs
+import BaseFormContainer from '../../../src/form/Container.mjs';
+
+class FormPageContainer extends BaseFormContainer {
+    static config = {
+        className: 'Form.view.FormPageContainer',
+        // ... other configs
+        tag: 'div' // Using a div instead of a form tag
+    }
+}
+```
+
+This allows you to treat each nested container as a sub-form, which can
+be validated or have its values retrieved independently, or as part of
+the top-level form.
+
+## 6. Field Triggers
+
+Field triggers are small, interactive icons or buttons that appear within
+or alongside a form field, providing additional functionality. Examples
+include clear buttons, date pickers, or spin buttons for number fields.
+
+Triggers are configured via the `triggers` array on a field. You can
+configure multiple triggers for a single field, and control their placement
+(left or right of the input) using the `align` config on the trigger.
+
+```javascript readonly
+import DateField    from '../../src/form/field/Date.mjs';
+import ClearTrigger from '../../src/form/field/trigger/Clear.mjs';
+
+// ...
+items: [{
+    module   : DateField,
+    labelText: 'Event Date',
+    name     : 'eventDate',
+    triggers : [{
+        module: ClearTrigger // Adds a clear button to the date field
+    }]
+}]
+```
+
+Many fields automatically include default triggers (e.g., `DateField`
+includes a `DateTrigger`). You can override or add to these defaults.
+
+## 7. Form and Field Events
+
+Neo.mjs forms and fields emit various events that you can listen to for
+custom logic:
+
+*   **`change`**: Fired when a field's `value` config changes.
+*   **`userChange`**: Fired when a field's value changes due to direct
+    user interaction (e.g., typing in a text field).
+*   **`fieldChange`**: Fired on the `Form.Container` when any of its
+    child fields' `value` changes.
+*   **`fieldUserChange`**: Fired on the `Form.Container` when any of its
+    child fields' value changes due to user interaction.
+*   **`focusEnter` / `focusLeave`**: Fired when a field gains or loses focus.
+
+You can listen to these events using the `on` method:
+
+```javascript readonly
+manyFormField.on('change', (data) => {
+    console.log('Field value changed:', data.value);
+});
+
+myFormContainer.on('fieldUserChange', (data) => {
+    console.log('User changed field:', data.component.name, data.value);
+});
+```
+
+## 8. Best Practices and Tips
+
+*   **`itemDefaults`**: Use `itemDefaults` on containers to apply common
+    configurations to all child items, reducing boilerplate.
+*   **`formGroup`**: Leverage `formGroup` for logical grouping of data,
+    especially in complex forms, to create clean nested data structures.
+*   **`readOnly` vs. `editable`**: 
+    *   `readOnly: true`: Prevents user interaction from changing the value.
+        The field is still part of the form data.
+    *   `editable: false`: Similar to `readOnly`, but specifically for
+        input elements, preventing direct typing. Other interactions (like
+        picker selection) might still be possible unless also `readOnly`.
+*   **Lazy Loading**: For forms with many pages or complex sections, consider
+    lazy loading modules for individual pages or fieldsets to improve initial
+    application load times. This is demonstrated in `apps/form/view/FormContainer.mjs`
+    where pages are imported dynamically.
+*   **Explicit Module Imports**: While the core `Neo` global namespace is always available, it's a best practice to
+  explicitly import all Neo.mjs modules you use (e.g., `import FormContainer from '../../src/form/Container.mjs';`).
+  Relying on implicit availability of classes within `Neo`'s sub-namespaces can lead to less readable and maintainable code.
+  Explicit imports improve code readability, maintainability, and ensure consistent behavior.
+*   **`Neo.overwrites`**: Use global overwrites (as seen in `apps/form/Overwrites.mjs`)
+    to enforce consistent styling or behavior across all instances of a
+    component type.