neo.mjs 6.18.1 → 6.18.3

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 '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../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 '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../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 '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../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 '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../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 '../controller/Component.mjs';
+import Dialog     from '../dialog/Base.mjs';
+import Panel      from '../container/Panel.mjs';
+import TextField  from '../form/field/Text.mjs';
+import Viewport   from '../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 '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../component/Label.mjs';
+import ViewModel from '../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/pages/References.md

@@ -11,9 +11,9 @@ Here's an example with one button. Clicking on the button will disable it.
 As you can see, the handler uses the component reference pass in via `data.component`.
 
 <pre data-neo>
-import Button     from '../../../../src/button/Base.mjs';
-import Container  from '../../../../src/container/Base.mjs';
-import Controller from '../../../../src/controller/Component.mjs';
+import Button     from '../button/Base.mjs';
+import Container  from '../container/Base.mjs';
+import Controller from '../controller/Component.mjs';
 
 class MainViewController extends Controller {
     static config = {
@@ -48,9 +48,9 @@ you tag the component you need with a `reference` config, then use `getReference
 the controller.
 
 <pre data-neo>
-import Button     from '../../../../src/button/Base.mjs';
-import Container  from '../../../../src/container/Base.mjs';
-import Controller from '../../../../src/controller/Component.mjs';
+import Button     from '../button/Base.mjs';
+import Container  from '../container/Base.mjs';
+import Controller from '../controller/Component.mjs';
 
 class MainViewController extends Controller {
     static config = {
@@ -103,8 +103,8 @@ The following example gets a reference to the _Learn_ button at the top of this
 Again &mdash; that use of `Neo.findFirst()` might be handy when debugging, but it should never be used in app logic.
 
 <pre data-neo>
-import Button    from '../../../../src/button/Base.mjs';
-import Container from '../../../../src/container/Base.mjs';
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
 
 class MainView extends Container {
     static config = {

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

@@ -4,15 +4,16 @@ To code a live preview, enclose the code in a `pre` tag with the `data-neo` attr
 
 Imports are relative to the portal app running within the framework. That means
 Neo.mjs imports should be coded to go up four levels, then look into the `src`
-directory. For example, to import _container_, use `import Base from '../../../../src/container/Base.mjs`
+directory. For example, to import _container_, use `import Base from '../container/Base.mjs`
 
 You can define as many classes you need, such as component models and controllers, but the the _last_
 class being defined is assumed to be the view being rendered. In other words, if the final class definition is a component, it's rendered.
 
 <pre data-neo>
-import Base from '../../../../src/container/Base.mjs';
-import Button from '../../../../src/button/Base.mjs';
-import Split from '../../../../src/button/Split.mjs';
+import Base   from '../container/Base.mjs';
+import Button from '../button/Base.mjs';
+import Split  from '../button/Split.mjs';
+
 class Bar extends Base {
     static config = {
         ntype: 'demoFoo',

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

@@ -4,9 +4,9 @@ In case you did not work with neo yet, but come from a more HTML driven ecosyste
 you could achieve the task in a similar way.
 
 <pre data-neo>
-import Component from '../../../../src/component/Base.mjs';
-import NeoArray  from '../../../../src/util/Array.mjs';
-import VdomUtil  from '../../../../src/util/VDom.mjs';
+import Component from '../component/Base.mjs';
+import NeoArray  from '../util/Array.mjs';
+import VdomUtil  from '../util/VDom.mjs';
 
 class MainComponent extends Component {
     static config = {
@@ -117,12 +117,12 @@ Neo.setupClass(MainComponent);
 content
 
 <pre data-neo>
-import Container from '../../../../src/container/Base.mjs';
-import List      from '../../../../src/list/Base.mjs';
-import Model     from '../../../../src/data/Model.mjs';
-import Store     from '../../../../src/data/Store.mjs';
-import TextField from '../../../../src/form/field/Text.mjs';
-import Toolbar   from '../../../../src/toolbar/Base.mjs';
+import Container from '../container/Base.mjs';
+import List      from '../list/Base.mjs';
+import Model     from '../data/Model.mjs';
+import Store     from '../data/Store.mjs';
+import TextField from '../form/field/Text.mjs';
+import Toolbar   from '../toolbar/Base.mjs';
 
 class TodoListModel extends Model {
     static config = {

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

@@ -50,8 +50,8 @@ icon on the right  <span class="far fa-xs fa-window-maximize"></span>. This web
 and the ability to launch browser windows &mdash; all integrated within a single app &mdash; is a unique feature of Neo.mjs!
 
 <pre data-neo>
-import Button    from '../../../../src/button/Base.mjs';
-import Container from '../../../../src/container/Base.mjs';
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
 
 class MainView extends Container {
     static config = {
@@ -65,4 +65,4 @@ class MainView extends Container {
 }
 
 Neo.setupClass(MainView);
-</pre>
+</pre>

package/resources/data/deck/learnneo/pages/WhyNeo-Multi-Window.md

@@ -15,8 +15,8 @@ running the code. Even though it's running in a new window, it's still part of t
 seamlessly share events, data, etc. — the code doesn't care that some code is running in a
 separate window.
 <pre data-neo>
-import Button    from '../../../../src/button/Base.mjs';
-import Container from '../../../../src/container/Base.mjs';
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
 
 class MainView extends Container {
     static config = {

package/resources/data/deck/learnneo/pages/WhyNeo-Speed.md

@@ -21,8 +21,8 @@ If you move quickly, you might reach 20,000 or 30,000 delta updates per second.
 second — but we've never actually hit the limit.
 
 <pre data-neo>
-import Base from '../../../../src/container/Base.mjs';
-import Helix from '../../../../src/component/Helix.mjs';
+import Base from '../container/Base.mjs';
+import Helix from '../component/Helix.mjs';
 class Foo extends Base {
     static config = {
         className: 'Foo',

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;
@@ -82,52 +82,6 @@
     }
 }
 
-.hello-world {
-    animation-timeline: view(block 100% -500%);
-
-    animation-name: appear-animation;
-    animation-fill-mode: both;
-    animation-duration: 1ms; /* Firefox requires this to apply the animation */
-    animation-timing-function: linear;
-}
-
-@keyframes appear-animation {
-    0% {
-        transform: translateX(-400%);
-        opacity  : 0;
-    }
-    90% {
-        opacity: .3;
-    }
-    100% {
-        transform: translateX(0);
-        opacity  : 1;
-    }
-}
-
-.cool-stuff {
-    animation-timeline       : view(block 100% -500%);
-    animation-name           : appear-cool-stuff;
-    animation-fill-mode      : both;
-    animation-duration       : 1ms; /* Firefox requires this to apply the animation */
-    animation-timing-function: linear;
-}
-
-@keyframes appear-cool-stuff {
-    0% {
-        transform: translateX(400%);
-        opacity  : 0;
-    }
-    90% {
-        opacity: .3;
-    }
-    100% {
-        transform: translateX(0);
-        opacity  : 1;
-    }
-}
-
-
 //.page {
 //  scroll-timeline: --page block;
 //}

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;
-    }
 }