neo.mjs 6.18.1 → 6.18.2

package/resources/data/deck/learnneo/pages/GuideViewModels.md

@@ -0,0 +1,444 @@
+View models (VMs) in Neo.mjs are state providers.
+
+While Components can manage their own state using the Class Config System,
+you want to use VMs as soon as you want to share data properties with multiple child Components.
+
+Rules of thumb:
+1. Leaf Components inside the Component Tree (Container items) will most likely not need a VM.
+2. We can define multiple VMs as needed (they do communicate).
+3. We want to define shared state data properties as low inside the component tree as possible.
+
+We often reference a VM as `model.Component` (the class name inside Neo.mjs),
+other libraries or frameworks often call them Stores.
+
+Since we also have Data Stores (tabular data), we chose to use the name VM to avoid confusion.
+
+## Inline Models
+### Direct Bindings
+<pre data-neo>
+import Button    from  '../../../../src/button/Base.mjs';
+import Container from  '../../../../src/container/Base.mjs';
+import Label     from  '../../../../src/component/Label.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        model: {
+            data: {
+                hello: 'Hello',
+                world: 'world!'
+            }
+        },
+        itemDefaults: {
+            module: Label,
+            style : {margin: '1em'}
+        },
+        items: [{
+            bind: {
+                text: data => data.hello
+            }
+        }, {
+            bind: {
+                text: data => data.world
+            }
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({hello: 'Hi'}),
+            text   : 'Change Hello'
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({world: 'Neo.mjs!'}),
+            text   : 'Change World'
+        }],
+        layout: {ntype: 'vbox', align: 'start'}
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+We use a Container with a VM containing the data props `hello` and `world`.
+Inside the Container are 2 Labels which bind their `text` config to a data prop directly.
+
+We can easily bind 1:1 to specific data props using the following syntax:</br>
+`bind: {text: data => data.hello}`
+
+### Bindings with multiple data props
+<pre data-neo>
+import Button    from  '../../../../src/button/Base.mjs';
+import Container from  '../../../../src/container/Base.mjs';
+import Label     from  '../../../../src/component/Label.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        model: {
+            data: {
+                hello: 'Hello',
+                world: 'world!'
+            }
+        },
+        itemDefaults: {
+            module: Label,
+            style : {margin: '1em'}
+        },
+        items: [{
+            bind: {
+                // We can use template literals containing VM data props
+                text: data => `${data.hello} ${data.world}`
+            }
+        }, {
+            bind: {
+                // We can also use VM data props directly inside fat arrow function bodies
+                text: data => data.hello + ' ' + data.world
+            }
+        }, {
+            bind: {
+                // We can convert the config into a function to use VM data props
+                text(data) {return data.hello + ' ' + data.world}
+            }
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({hello: 'Hi'}),
+            text   : 'Change Hello'
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({world: 'Neo.mjs!'}),
+            text   : 'Change World'
+        }],
+        layout: {ntype: 'vbox', align: 'start'}
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+We use a Container with a VM containing the data props `hello` and `world`.
+Inside the Container are 3 Labels which bind their `text` config to a combination of both data props.
+
+We are showcasing 3 different ways how you can define your binding (resulting in the same output).
+
+In case any of the bound data props changes, all bound Configs will check for an update.
+
+Important: The Config setter will only trigger in case there is a real change for the bound output.
+
+We also added 2 Buttons to change the value of each data prop, so that we can see that the bound Label texts
+update right away.
+
+Let us take a look at the Button handler:</br>
+`data.component.getModel().setData({world: 'Neo.mjs!'})`
+
+data.component equals to the Button instance itself. Since the Button instance does not have its own VM,
+`getModel()` will return the closest VM inside the parent chain.
+
+### Nested Inline Models
+<pre data-neo>
+import Button    from  '../../../../src/button/Base.mjs';
+import Container from  '../../../../src/container/Base.mjs';
+import Label     from  '../../../../src/component/Label.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        model: {
+            data: {
+                hello: 'Hello'
+            }
+        },
+        layout: 'fit',
+        items : [{
+            module: Container,
+            model: {
+                data: {
+                    world: 'world!'
+                }
+            },
+            itemDefaults: {
+                module: Label,
+                style : {margin: '1em'}
+            },
+            items: [{
+                bind: {
+                    // We can use template literals containing VM data props
+                    text: data => `${data.hello} ${data.world}`
+                }
+            }, {
+                bind: {
+                    // We can also use VM data props directly inside fat arrow function bodies
+                    text: data => data.hello + ' ' + data.world
+                }
+            }, {
+                bind: {
+                    // We can convert the config into a function to use VM data props
+                    text(data) {return data.hello + ' ' + data.world}
+                }
+            }, {
+                module : Button,
+                handler: data => data.component.getModel().setData({hello: 'Hi'}),
+                text   : 'Change Hello'
+            }, {
+                module : Button,
+                handler: data => data.component.getModel().setData({world: 'Neo.mjs!'}),
+                text   : 'Change World'
+            }],
+            layout: {ntype: 'vbox', align: 'start'}
+        }]
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+
+The output of this demo is supposed to exactly look the same like the previous demo.
+
+This time we nest our Labels into a Container with a fit layout.
+Just for demo purposes, we want to avoid overnesting inside real apps.
+
+Our top level VM now only contains the `hello` data prop, and we added a second VM inside the nested Container
+which contains the `world` data prop.
+
+As a result, the bindings for all 3 Labels contain a combination of data props which live inside different VMs.
+As long as these VMs are inside the parent hierarchy this works fine.
+
+The same goes for the Button handlers: `setData()` will find the closest matching data prop inside the VM parent chain.
+
+We can even change data props which live inside different VMs at once. As easy as this:</br>
+`setData({hello: 'foo', world: 'bar'})`
+
+Hint: Modify the example code (Button handler) to try it out right away!
+
+### Nested Data Properties
+<pre data-neo>
+import Button    from  '../../../../src/button/Base.mjs';
+import Container from  '../../../../src/container/Base.mjs';
+import Label     from  '../../../../src/component/Label.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        model: {
+            data: {
+                user: {
+                    firstname: 'Tobias',
+                    lastname : 'Uhlig'
+                }
+            }
+        },
+        itemDefaults: {
+            module: Label,
+            style : {margin: '1em'}
+        },
+        items: [{
+            bind: {
+                text: data => `${data.user.firstname} ${data.user.lastname}`
+            }
+        }, {
+            bind: {
+                text: data => data.user.firstname + ' ' + data.user.lastname
+            }
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({user: {firstname: 'Max'}}),
+            text   : 'Change Firstname'
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({'user.lastname': 'Rahder'}),
+            text   : 'Change Lastname'
+        }],
+        layout: {ntype: 'vbox', align: 'start'}
+    }
+}
+Neo.setupClass(MainView);
+</pre>
+Data props inside VMs can be nested. Our VM contains a `user` data prop as an object,
+which contains the nested props `firstname` and `lastname`.
+
+We can bind to these nested props like before:</br>
+`bind: {text: data => data.user.firstname + ' ' + data.user.lastname}`
+
+Any change of a nested data prop will directly get reflected into the bound components.
+
+We can update a nested data prop with passing its path:</br>
+`data => data.component.getModel().setData({'user.lastname': 'Rahder'})`
+
+Or we can directly pass the object containing the change(s):</br>
+`data => data.component.getModel().setData({user: {firstname: 'Max'}})`
+
+Hint: This will not override left out nested data props (lastname in this case).
+
+### Dialog connecting to a Container
+<pre data-neo>
+import Controller from '../../../../src/controller/Component.mjs';
+import Dialog     from '../../../../src/dialog/Base.mjs';
+import Panel      from '../../../../src/container/Panel.mjs';
+import TextField  from '../../../../src/form/field/Text.mjs';
+import Viewport   from '../../../../src/container/Viewport.mjs';
+
+class EditUserDialogController extends Controller {
+    static config = {
+        className: 'Neo.examples.model.dialog.EditUserDialogController'
+    }
+
+    onFirstnameTextFieldChange(data) {
+        this.getModel().setData({
+            'user.firstname': data.value || ''
+        })
+    }
+
+    onLastnameTextFieldChange(data) {
+        this.getModel().setData({
+            'user.lastname': data.value || ''
+        })
+    }
+}
+Neo.setupClass(EditUserDialogController);
+
+class EditUserDialog extends Dialog {
+    static config = {
+        className      : 'Neo.examples.model.dialog.EditUserDialog',
+        containerConfig: {style: {padding: '1em'}},
+        controller     : EditUserDialogController,
+        title          : 'Edit User',
+        itemDefaults   : {module: TextField, flex: 'none', labelWidth: 110},
+        items: [{
+            bind     : {value: data => data.user.firstname},
+            labelText: 'Firstname:',
+            listeners: {change: 'onFirstnameTextFieldChange'}
+        }, {
+            bind     : {value: data => data.user.lastname},
+            labelText: 'Lastname:',
+            listeners: {change: 'onLastnameTextFieldChange'}
+        }],
+        wrapperStyle: {height: '300px', width : '400px'}
+    }
+}
+Neo.setupClass(EditUserDialog);
+
+class MainContainerController extends Controller {
+    static config = {
+        className: 'Neo.examples.model.dialog.MainContainerController',
+        dialog   : null
+    }
+
+    onEditUserButtonClick(data) {
+        let me = this;
+
+        if (!me.dialog) {
+            me.dialog = Neo.create({
+                module         : EditUserDialog,
+                animateTargetId: me.getReference('edit-user-button').id,
+                appName        : me.component.appName,
+                closeAction    : 'hide',
+
+                model: {
+                    parent: me.getModel()
+                }
+            })
+        } else {
+            me.dialog.show()
+        }
+    }
+}
+Neo.setupClass(MainContainerController);
+
+class MainView extends Viewport {
+    static config = {
+        className : 'Neo.examples.model.dialog.MainContainer',
+        controller: MainContainerController,
+        model: {
+            data: {
+                user: {
+                    firstname: 'Tobias',
+                    lastname : 'Uhlig'
+                }
+            }
+        },
+        style: {padding: '20px'},
+        items: [{
+            module: Panel,
+            containerConfig: {
+                layout: {ntype: 'vbox', align: 'start'},
+                style : {padding: '20px'}
+            },
+            headers: [{
+                dock : 'top',
+                items: [{
+                    ntype: 'label',
+                    bind : {
+                        text: data => `Current user: ${data.user.firstname} ${data.user.lastname}`
+                    }
+                }, {
+                    ntype: 'component',
+                    flex : 1
+                }, {
+                    handler  : 'onEditUserButtonClick',
+                    iconCls  : 'fa fa-user',
+                    reference: 'edit-user-button',
+                    text     : 'Edit user'
+                }]
+            }],
+
+            items: [{
+                ntype: 'label',
+                text : 'Click the edit user button to edit the user data </br> inside this container view model.'
+            }]
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+## Class based Models
+When your models contain many data props or need custom logic, you can easily move them into their own classes.
+
+### Direct Bindings
+<pre data-neo>
+import Button    from  '../../../../src/button/Base.mjs';
+import Container from  '../../../../src/container/Base.mjs';
+import Label     from  '../../../../src/component/Label.mjs';
+import ViewModel from  '../../../../src/model/Component.mjs';
+
+class MainViewModel extends ViewModel {
+    static config = {
+        className: 'Example.view.MainViewModel',
+        data: {
+            hello: 'Hello',
+            world: 'world!'
+        }
+    }
+    onDataPropertyChange(key, value, oldValue) {
+        super.onDataPropertyChange(key, value, oldValue);
+        // do custom things there, like firing events
+        Neo.Main.log({value: `onDataPropertyChange: key: ${key}, value: ${value}, oldValue: ${oldValue}`})
+    }
+}
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        model    : MainViewModel, // directly assign the imported module
+
+        itemDefaults: {
+            module: Label,
+            style : {margin: '1em'}
+        },
+        items: [{
+            bind: {
+                text: data => data.hello
+            }
+        }, {
+            bind: {
+                text: data => data.world
+            }
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({hello: 'Hi'}),
+            text   : 'Change Hello'
+        }, {
+            module : Button,
+            handler: data => data.component.getModel().setData({world: 'Neo.mjs!'}),
+            text   : 'Change World'
+        }],
+        layout: {ntype: 'vbox', align: 'start'}
+    }
+}
+Neo.setupClass(MainView);
+</pre>

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

@@ -26,6 +26,7 @@
         {"name": "User Input (Forms)",                      "parentId": "InDepth",           "isLeaf": false, "id": "Forms"},
         {"name": "Component and Container Basics",          "parentId": "InDepth",           "isLeaf": true,  "id": "ComponentsAndContainers"},
         {"name": "Layouts",                                 "parentId": "InDepth",           "isLeaf": false, "id": "Layouts"},
+        {"name": "View Models",                             "parentId": "InDepth",           "isLeaf": true,  "id": "GuideViewModels"},
         {"name": "Custom Components",                       "parentId": "InDepth",           "isLeaf": true,  "id": "CustomComponents"},
         {"name": "Events",                                  "parentId": "InDepth",           "isLeaf": true,  "expanded": false, "id": "GuideEvents"},
         {"name": "Tables (Stores)",                         "parentId": "InDepth",           "isLeaf": false, "id": "Tables"},

package/resources/scss/src/apps/portal/HeaderToolbar.scss

@@ -59,7 +59,7 @@
 
 
 /* Style and position the progress bar */
-#progress {
+.portal-home-progress {
     position: fixed;
     z-index: 1000;
     top: 0;

package/resources/scss/src/apps/portal/home/MainContainer.scss

@@ -2,36 +2,4 @@
     overflow-x      : hidden!important;
     scroll-behavior : smooth;
     scroll-snap-type: y mandatory;
-
-    .page {
-        min-height       : 100%;
-        scroll-snap-align: center;
-
-        .neo-h1 {
-            font-size: min(max(5.5vw, 30px), 64px);
-            text-align   : center;
-            margin       : 0;
-            line-height  : 1em;
-        }
-
-        .neo-h2 {
-            font-size: min(max(3.5vw, 24px), 44px);
-            text-align   : center;
-            margin       : 0;
-            line-height  : 1em;
-            }
-
-        .neo-content {
-            font-size: min(max(2.3vw, 16px), 30px);
-        }
-
-        .page-live-preview {
-            margin: 0;
-        }
-    }
-
-    .neo-h1 {
-        font-size  : 32px;
-        font-weight: 600;
-    }
 }

package/resources/scss/src/apps/portal/home/parts/BaseContainer.scss

@@ -0,0 +1,27 @@
+.portal-home-content-view {
+    min-height       : 100%;
+    scroll-snap-align: center;
+
+    .neo-h1 {
+        font-size  : min(max(5.5vw, 30px), 64px);
+        text-align : center;
+        margin     : 0;
+        line-height: 1em;
+    }
+
+    .neo-h2 {
+        font-size  : min(max(3.5vw, 24px), 44px);
+        font-weight: 600;
+        text-align : center;
+        margin     : 0;
+        line-height: 1em;
+    }
+
+    .neo-content {
+        font-size: min(max(2.3vw, 16px), 30px);
+    }
+
+    .page-live-preview {
+        margin: 0;
+    }
+}

package/resources/scss/src/apps/portal/home/parts/MainNeo.scss

@@ -1,4 +1,6 @@
-.portal-home-main-neo.page {
+.portal-home-main-neo.portal-home-content-view {
+    padding: 3em;
+
     .button-group {
         display       : flex !important;
         flex-direction: row-reverse !important;

package/resources/scss/src/apps/portal/learn/ContentTreeList.scss

@@ -7,7 +7,7 @@
     padding         : 8px 2px 8px 8px;
 
     .neo-list-container {
-        padding: 0 3px 3px 3px;
+        padding: 3px;
     }
 
     .neo-list-container>.neo-list-item {

package/resources/scss/src/calendar/view/EditEventContainer.scss

@@ -5,7 +5,7 @@
     padding         : .7em;
     position        : absolute;
     top             : 0;
-    z-index         : 10000;
+    z-index         : 900;
 
     &:before {
         border-bottom: 12px solid transparent;

package/resources/scss/src/calendar/view/calendars/List.scss

@@ -1,4 +1,4 @@
-.neo-calendars-list {
+.neo-calendars-list.neo-list {
     .neo-checkboxfield {
         align-items: center;
         display    : flex;

package/resources/scss/src/dialog/Base.scss

@@ -30,6 +30,7 @@
 
 .neo-dialog {
     border        : 1px solid var(--dialog-border-color);
+    box-shadow    : var(--dialog-box-shadow);
     display       : flex;
     flex-direction: column;
 
@@ -61,12 +62,6 @@
         }
     }
 
-    &.neo-centered {
-        left      : 50%;
-        top       : 50%;
-        transform : translate(-50%, -50%);
-    }
-
     &.neo-panel {
         .neo-footer-toolbar {
             border    : none;

package/resources/scss/theme-dark/dialog/Base.scss

@@ -1,5 +1,6 @@
 :root .neo-theme-dark { // .neo-dialog
     --dialog-border-color: #3c3f41;
+    --dialog-box-shadow  : 0 5px 10px rgba(0,0,0,.4);
     --dialog-header-color: floralwhite;
     --dialog-icon-color  : floralwhite;
 }

package/resources/scss/theme-light/dialog/Base.scss

@@ -1,5 +1,6 @@
 :root .neo-theme-light { // .neo-dialog
     --dialog-border-color: #ddd;
+    --dialog-box-shadow  : 0 5px 10px rgba(0,0,0,.4);
     --dialog-header-color: #1c60a0;
     --dialog-icon-color  : #1c60a0;
 }

package/resources/scss/theme-neo-light/Global.scss

@@ -46,17 +46,19 @@
         font-style: italic;
     }
 
-    code &:not(.hljs) {
-        background-color: #F0F2F0;
-        border          : 1px solid var(--sem-color-border-subtle);
-        border-radius   : 4px;
-        color           : var(--sem-color-fg-neutral-contrast);
-        font-family     : var(--core-fontfamily-mono);
-        font-size       : var(--core-fontsize-body);
-        font-weight     : var(--core-fontweight-regular);
-        line-height     : var(--core-lineheight-headline);
-        padding         : 2px 0.3em;
-        font-size       : 16px;
+    code {
+        &:not(.hljs) {
+            background-color: #F0F2F0;
+            border          : 1px solid var(--sem-color-border-subtle);
+            border-radius   : 4px;
+            color           : var(--sem-color-fg-neutral-contrast);
+            font-family     : var(--core-fontfamily-mono);
+            font-size       : var(--core-fontsize-body);
+            font-weight     : var(--core-fontweight-regular);
+            line-height     : var(--core-lineheight-headline);
+            padding         : 2px 0.3em;
+            font-size       : 16px;
+        }
     }
 
     mark {

package/resources/scss/theme-neo-light/dialog/Base.scss

@@ -1,5 +1,6 @@
 :root .neo-theme-neo-light { // .neo-dialog
     --dialog-border-color: #ddd;
+    --dialog-box-shadow  : 0 5px 10px rgba(0,0,0,.4);
     --dialog-header-color: #1c60a0;
     --dialog-icon-color  : #1c60a0;
 }

package/src/DefaultConfig.mjs

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

package/src/button/Base.mjs

@@ -440,12 +440,13 @@ class Base extends Component {
      * @protected
      */
     changeRoute() {
-        let me = this;
+        let me         = this,
+            {windowId} = me;
 
         if (me.editRoute) {
             Neo.Main.editRoute(me.route)
         } else {
-            Neo.Main.setRoute({value: me.route})
+            Neo.Main.setRoute({value: me.route, windowId})
         }
     }
 

package/src/calendar/view/EditEventContainer.mjs

@@ -239,7 +239,7 @@ class EditEventContainer extends FormContainer {
      */
     onCalendarFieldChange(data) {
         if (!Neo.isEmpty(data.value)) {
-            this.record.calendarId = data.record[data.component.store.keyProperty]
+            this.record.calendarId = data.value[data.component.store.keyProperty]
         }
     }