neo.mjs 6.38.0 → 6.39.0

package/apps/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='6.38.0'
+         * @member {String} version='6.39.0'
          */
-        version: '6.38.0'
+        version: '6.39.0'
     }
 
     /**

package/examples/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='6.38.0'
+         * @member {String} version='6.39.0'
          */
-        version: '6.38.0'
+        version: '6.39.0'
     }
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neo.mjs",
-    "version": "6.38.0",
+    "version": "6.39.0",
     "description": "The webworkers driven UI framework",
     "type": "module",
     "repository": {

package/resources/data/deck/learnneo/pages/benefits/FormsEngine.md

@@ -0,0 +1,265 @@
+## Forms include a State-Provider
+
+You do not need to define a state tree on your own.
+It if sufficient to just use namespaces inside the `name` attribute of each field.
+
+<pre data-neo>
+import Button        from '../button/Base.mjs';
+import FormContainer from '../form/Container.mjs';
+import TextField     from '../form/field/Text.mjs';
+
+class MainView extends FormContainer {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        
+        items: [{
+            module   : TextField,
+            labelText: 'Firstname',
+            name     : 'user.firstname',
+            value    : 'John'
+        }, {
+            module   : TextField,
+            labelText: 'Lastname',
+            name     : 'user.lastname',
+            value    : 'Doe'
+        }, {
+            module : Button,
+            handler: 'up.getFormValues',
+            style  : {marginTop: '1em'},
+            text   : 'Get Form Values'
+        }]
+    }
+
+    async getFormValues(data) {
+        const formValues = await this.getValues();
+        // Logs {user: {firstname: 'John', lastname: 'Doe'}}
+        Neo.Main.log({value: formValues})
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+## Forms can get validated without being mounted
+
+Neo.mjs Forms live as a pure abstraction layer inside JavaScript.
+The following example is similar to the first one, but this time the form instance will not get mounted.
+Getting the field values still works like before.
+
+Use case: In case you have a form split into multiple pages and only one of them is mounted to keep
+the DOM minimal, you can still get all field values.
+
+<pre data-neo>
+import Button        from '../button/Base.mjs';
+import Container     from '../container/Base.mjs';
+import FormContainer from '../form/Container.mjs';
+import TextField     from '../form/field/Text.mjs';
+
+const myForm = Neo.create({
+    module: FormContainer,
+    items : [{
+        module   : TextField,
+        labelText: 'Firstname',
+        name     : 'user.firstname',
+        value    : 'John'
+    }, {
+        module   : TextField,
+        labelText: 'Lastname',
+        name     : 'user.lastname',
+        value    : 'Doe'
+    }]
+});
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        
+        items: [{
+            module : Button,
+            handler: 'up.getFormValues',
+            text   : 'Get Form Values'
+        }]
+    }
+
+    async getFormValues(data) {
+        const formValues = await myForm.getValues();
+        // Logs {user: {firstname: 'John', lastname: 'Doe'}}
+        Neo.Main.log({value: formValues})
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+## Nested Forms
+
+Inside the DOM, it is impossible to nest form tags.
+Neo forms can get easily mapped to other nodes:</br>
+`{module: FormContainer, tag: 'div'}`
+
+This allows us to nest forms and validate or retrieve form values of each nested form or
+for the top-level form (including all nested items) as we see fit.
+
+Inside the example preview, clear the user lastname via hitting the x-button.
+Afterwards, click on the 3 buttons at the bottom and inspect the output inside the main window console carefully.
+
+The main form will log:
+<pre data-javascript>
+{
+    account: 'My Account',
+    product: {brand: 'Tesla', name: 'Car'},
+    user   : {firstname: 'John', lastname: null}
+}
+'isValid: false'
+</pre>
+
+The user form will log:
+<pre data-javascript>
+{user: {firstname: 'John', lastname: null}}
+'isValid: false'
+</pre>
+
+The product form will log:
+<pre data-javascript>
+{product: {brand: 'Tesla', name: 'Car'}}
+'isValid: true'
+</pre>
+
+<pre data-neo>
+import Button        from '../button/Base.mjs';
+import Container     from '../container/Base.mjs';
+import FormContainer from '../form/Container.mjs';
+import TabContainer  from '../tab/Container.mjs';
+import TextField     from '../form/field/Text.mjs';
+
+class MainView extends FormContainer {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'stretch'},
+        
+        items: [{
+            module       : TextField,
+            flex         : 'none',
+            labelPosition: 'inline',
+            labelText    : 'Account',
+            name         : 'account',
+            value        : 'My Account'
+        }, {
+            module: TabContainer,
+            items : [{
+                module         : FormContainer,
+                itemDefaults   : {module: TextField, labelPosition: 'inline'},
+                layout         : {ntype:'vbox', align:'start'},
+                reference      : 'user-form',
+                tabButtonConfig: {text: 'User'},
+                tag            : 'div',
+
+                items: [{
+                    labelText: 'Firstname',
+                    name     : 'user.firstname',
+                    value    : 'John'
+                }, {
+                    labelText: 'Lastname',
+                    name     : 'user.lastname',
+                    required : true,
+                    value    : 'Doe'
+                }]
+            }, {
+                module         : FormContainer,
+                itemDefaults   : {module: TextField, labelPosition: 'inline'},
+                layout         : {ntype:'vbox', align:'start'},
+                reference      : 'product-form',
+                tabButtonConfig: {text: 'Product'},
+                tag            : 'div',
+
+                items: [{
+                    labelText: 'Name',
+                    name     : 'product.name',
+                    value    : 'Car'
+                }, {
+                    labelText: 'Brand',
+                    name     : 'product.brand',
+                    required : true,
+                    value    : 'Tesla'
+                }]
+            }]
+        }, {
+            module      : Container,
+            flex        : 'none',
+            itemDefaults: {module: Button},
+            layout      : {ntype: 'hbox'},
+
+            items : [{
+                handler: 'up.getMainFormValues',
+                text   : 'Get Main Values'
+            }, {
+                handler: 'up.getUserFormValues',
+                text   : 'Get User Values'
+            }, {
+                handler: 'up.getProductFormValues',
+                text   : 'Get Product Values'
+            }]
+        }]
+    }
+
+    async getMainFormValues(data) {
+        const formValues = await this.getValues();
+        Neo.Main.log({value: formValues});
+
+        const isValid = await this.validate();
+        Neo.Main.log({value: `isValid: ${isValid}`});
+    }
+
+    async getProductFormValues(data) {
+        const
+            form       = this.getReference('product-form'),
+            formValues = await form.getValues();
+
+        Neo.Main.log({value: formValues});
+
+        const isValid = await form.validate();
+        Neo.Main.log({value: `isValid: ${isValid}`});
+    }
+
+    async getUserFormValues(data) {
+        const
+            form       = this.getReference('user-form'),
+            formValues = await form.getValues();
+
+        Neo.Main.log({value: formValues});
+
+        const isValid = await form.validate();
+        Neo.Main.log({value: `isValid: ${isValid}`});
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+Bonus: Inspect the DOM Inside the `TabContainer`.
+You will notice that only the active Tab is mounted inside the DOM.
+
+1. We can still get field values of unmounted forms
+2. We can still validate unmounted forms
+
+## Nested lazy-loaded Forms
+
+If you look close into the `Button` handlers of the last example:
+`getValues()` and `validate()` are both async.
+
+The reason for this is that `form.getFields()` itself is async as well:
+It will lazy-load (but not necessarily mount) missing fields when needed.
+
+The lazy-loading use case is not easy to display inside the `LivePreview`,
+since it does rely on defining child modules inside their own class files
+and dynamically importing them.
+
+In a nutshell:
+<pre data-javascript>
+{
+    module: TabContainer,
+    items : [
+        {module: () => import('./MyChildForm1')},
+        {module: () => import('./MyChildForm2')}
+    ]
+}
+</pre>

package/resources/data/deck/learnneo/tree.json

@@ -2,11 +2,12 @@
     {"name":  "Welcome!",                                   "parentId": null,                "isLeaf":  true, "id": "Welcome" },
     {"name": "Benefits",                                    "parentId": null,                "isLeaf": false, "id": "WhyNeo"},
         {"name": "Introduction ",                           "parentId": "WhyNeo",            "isLeaf": true,  "id": "WhyNeo-Intro"},
-        {"name": "Multi-Threading",                         "parentId": "WhyNeo",            "isLeaf": true,  "id": "benefits.Multi-Threading"},
+        {"name": "Multi-Threading",                         "parentId": "WhyNeo",            "isLeaf": true,  "id": "benefits.MultiThreading"},
         {"name": "Extreme Speed",                           "parentId": "WhyNeo",            "isLeaf": true,  "id": "WhyNeo-Speed"},
         {"name": "Multi-Window Applications",               "parentId": "WhyNeo",            "isLeaf": true,  "id": "WhyNeo-Multi-Window"},
         {"name": "Quick Application Development",           "parentId": "WhyNeo",            "isLeaf": true,  "id": "WhyNeo-Quick"},
         {"name": "Complexity and Effort",                   "parentId": "WhyNeo",            "isLeaf": true,  "id": "WhyNeo-Effort"},
+        {"name": "Forms Engine",                            "parentId": "WhyNeo",            "isLeaf": true,  "id": "benefits.FormsEngine"},
         {"name": "Features and Benefits Summary",           "parentId": "WhyNeo",            "isLeaf": true,  "id": "WhyNeo-Features"},
     {"name": "Getting Started",                             "parentId": null,                "isLeaf": false, "id": "GettingStarted", "collapsed":  true},
         {"name": "Setup",                                   "parentId": "GettingStarted",    "isLeaf": true,  "id": "Setup"},

package/src/DefaultConfig.mjs

@@ -260,12 +260,12 @@ const DefaultConfig = {
     useVdomWorker: true,
     /**
      * buildScripts/injectPackageVersion.mjs will update this value
-     * @default '6.38.0'
+     * @default '6.39.0'
      * @memberOf! module:Neo
      * @name config.version
      * @type String
      */
-    version: '6.38.0'
+    version: '6.39.0'
 };
 
 Object.assign(DefaultConfig, {