neo.mjs 6.38.0 → 6.40.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.40.0'
          */
-        version: '6.38.0'
+        version: '6.40.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.40.0'
          */
-        version: '6.38.0'
+        version: '6.40.0'
     }
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neo.mjs",
-    "version": "6.38.0",
+    "version": "6.40.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

@@ -7,6 +7,7 @@
         {"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/resources/scss/src/button/Base.scss

@@ -95,6 +95,10 @@
         pointer-events: none;
         text-transform: var(--button-text-transform);
         z-index       : 2;
+
+        @media (max-width: 600px) {
+            font-size: 13px;
+        }
     }
 
     &:active {

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.40.0'
      * @memberOf! module:Neo
      * @name config.version
      * @type String
      */
-    version: '6.38.0'
+    version: '6.40.0'
 };
 
 Object.assign(DefaultConfig, {

package/src/main/addon/HighlightJS.mjs

@@ -23,6 +23,11 @@ class HighlightJS extends Base {
          * @protected
          */
         highlightJsLineNumbersPath: Neo.config.basePath + 'node_modules/highlightjs-line-numbers.js/dist/highlightjs-line-numbers.min.js',
+        /**
+         * @member {Boolean} libraryLoaded_=true
+         * @protected
+         */
+        libraryLoaded_: false,
         /**
          * Remote method access for other workers
          * @member {Object} remote
@@ -46,6 +51,43 @@ class HighlightJS extends Base {
         themePath: './resources/highlightjs-custom-github-theme.css'
     }
 
+    /**
+     * @member {Object[]} cache=[]
+     * @protected
+     */
+    cache = []
+
+    /**
+     * Triggered after the libraryLoaded config got changed
+     * @param {Boolean} value
+     * @param {Boolean} oldValue
+     * @protected
+     */
+    afterSetLibraryLoaded(value, oldValue) {
+        if (value) {
+            let me = this,
+                returnValue;
+
+            me.cache.forEach(item => {
+                returnValue = me[item.fn](item.data);
+                item.resolve(returnValue)
+            });
+
+            me.cache = []
+        }
+    }
+
+    /**
+     * Internally caches call when the hljs namespace does not exist yet
+     * @param item
+     * @returns {Promise<unknown>}
+     */
+    cacheMethodCall(item) {
+        return new Promise((resolve, reject) => {
+            this.cache.push({...item, resolve})
+        })
+    }
+
     /**
      * See: https://highlightjs.readthedocs.io/en/latest/api.html#highlightauto
      * @param {Object} data
@@ -53,10 +95,10 @@ class HighlightJS extends Base {
      * @returns {Object} of the form {language, relevance, value, secondBest}
      */
     highlightAuto(data) {
-        if (hljs) {
+        if (window.hljs) {
             return hljs.highlightAuto(data.html)
         } else {
-            console.error('highlight.js is not included inside the main thread.')
+            return this.cacheMethodCall({fn: 'highlightAuto', data})
         }
     }
 
@@ -77,6 +119,8 @@ class HighlightJS extends Base {
 
         Neo.main.addon.Stylesheet.createStyleSheet(null, 'hljs-theme', me.themePath);
 
+        this.libraryLoaded = true;
+
         return true
     }
 
@@ -118,13 +162,15 @@ class HighlightJS extends Base {
      * @param {String} data.vnodeId
      */
     syntaxHighlight(data) {
-        if (hljs) {
+        if (window.hljs) {
             let node = document.getElementById(data.vnodeId);
 
-            hljs.highlightBlock(node);
-            hljs.lineNumbersBlock(node)
+            if (node) {
+                hljs.highlightBlock(node);
+                hljs.lineNumbersBlock(node)
+            }
         } else {
-            console.error('highlight.js is not included inside the main thread.')
+            return this.cacheMethodCall({fn: 'syntaxHighlight', data})
         }
     }
 
@@ -132,11 +178,11 @@ class HighlightJS extends Base {
      * @param {Object} data
      */
     syntaxHighlightInit(data) {
-        if (hljs) {
+        if (window.hljs) {
             let blocks = document.querySelectorAll('pre code:not(.hljs)');
             Array.prototype.forEach.call(blocks, hljs.highlightBlock)
         } else {
-            console.error('highlight.js is not included inside the main thread.')
+            return this.cacheMethodCall({fn: 'syntaxHighlightInit', data})
         }
     }
 
@@ -147,6 +193,10 @@ class HighlightJS extends Base {
      * @param {Number} data.removeLine
      */
     syntaxHighlightLine(data) {
+        if (!window.hljs) {
+            return this.cacheMethodCall({fn: 'syntaxHighlightLine', data})
+        }
+
         let parentEl = document.getElementById(data.vnodeId),
             cls      = 'neo-highlighted-line',
             el;