neo.mjs 6.10.12 → 6.10.14

package/resources/data/deck/learnneo/p/Events.md

@@ -140,3 +140,14 @@ class MainView extends Base {
 }
 Neo.applyClassConfig(MainView);
 </pre>
+
+How are events set up? We don't really care, but in case you're curious: Neo.mjs has a `Neo.core.Observable` class
+that can be mixed into any class. It maintains a `listeners` object map that's a key-value pair, where
+the key is the event name, and the value is an array of function references. The first time a listener is 
+added an entry is added to the map using the event name as the key, and the event handler added as the first
+item in the associated array. If another listener is added for the same event, a second item is added to the
+array. If a new event is added, a new entry is added. Etc. When the event is fired, Neo.mjs looks up the map
+entry for the event name, then runs each function in the array, passing whatever data is specified in the
+call to `fire()`.
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/gettingStarted/events/ObservableInMemory.png"></img>

package/resources/data/deck/learnneo/p/GuideEvents.md

@@ -0,0 +1,153 @@
+All components fire events. For example, form fields fire a `change` event, various 
+focus events, and others. Some other types fire events too, such as `Neo.data.Store`, 
+which fires a `load` event after the store is loaded with data.
+
+Some terminology related to events is that events are _fired_, and as a result, some 
+event _handler_ — or _listener_ — is run.
+
+To specify an event handler, use `listeners: {}`, specifying in as many event/handler
+pairs as you need. 
+
+The code below shows two text fields, with `listeners` for `change` and `focusEnter`.
+(The events for any component are documened in the API docs.)
+
+<pre data-neo>
+import Base from '../../../../src/container/Base.mjs';
+import TextField from '../../../../src/form/field/Text.mjs';
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: TextField,
+            labelText  : 'First name',
+            listeners: {
+                change: data=>console.log(data.value), // There are other properties, like oldValue
+                focusEnter: data=>console.log(`Entering ${data.component.labelText}`) 
+            }
+        },
+        {
+            module: TextField,
+            labelText  : 'Last name',
+            listeners: {
+                change: data=>console.log(data.value), // There are other properties, like oldValue
+                focusEnter: data=>console.log(`Entering ${data.component.labelText}`) 
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+If you run the example, and open the browser's debugger, you'll see the console being logged as you type or give
+focus to either field.
+
+Note that the handlers specify an in-line function. For trivial cases, that might be ok. But normally
+you'd want better separation of concerns by placing those event handlers in a separate class. Neo.mjs provides
+that with a _component controller_. 
+
+A `Neo.controller.Component` is a simple class associated with a component class. As a view is created, an 
+instance of its associated contoller is automatically created. 
+
+<pre data-neo>
+import Base        from  '../../../../src/container/Base.mjs';
+import Controller  from  '../../../../src/controller/Component.mjs';
+import TextField  from   '../../../../src/form/field/Text.mjs';
+
+class MainViewController extends Controller {
+    static config = {
+        className: 'Example.view.MainViewController'
+    }
+    onChange(data){
+        console.log(data.value);
+    }
+}
+Neo.applyClassConfig(MainViewController);
+
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        controller: MainViewController,
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: TextField,
+            labelText  : 'Name',
+            listeners: {
+                change: 'onChange'
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+(It's important to keep in mind that in Neo.mjs, all class definitions are coded in their own
+source file: one class per file. In the examples we're putting all the relevant classes together
+to make it easier to see the source code for every class being used. But in an 
+actual applications the controller class would be coded in its own source file &mdash; named something
+like `MainViewController.mjs` &mdash; and that would be imported into the view.)
+
+The ability to fire events and add listeners is provided by `Neo.core.Observable`, which is mixed into 
+classes that need that ability. All components are observable, `Neo.data.Store` is observable, and some
+others. `Neo.core.Observable` introduces a few methods and properties, such as `listeners`, which
+is used in the examples above, `on()` for procedurally adding an event listener, and `fire()`, which is 
+how you fire events in the custom classes you create.
+
+Here's example illustrating how `fire()` is used. The code defines a `ToggleButton`
+class, which is just a button with a `checked` property: the button shows a checked or unchecked
+checkbox depending on the value of `checked`. 
+
+The code uses a special Neo.mjs feature you haven't seen yet &mdash; the use of an underscore property. 
+We'll discuss that at length later, but in a nutshell, config properties ending in an underscore 
+automatically get lifecycle methods run before the value is assigned, after the value is assigned, and 
+before the value is accessed. We're using the _after_ method to fire a `change` event.
+
+<pre data-neo>
+import Base        from  '../../../../src/container/Base.mjs';
+import Button  from  '../../../../src/button/Base.mjs';
+import TextField  from   '../../../../src/form/field/Text.mjs';
+
+class ToggleButton extends Button {
+    static config = {
+        className: 'Example.view.ToggleButton',
+        checked_: false
+    }
+    afterSetChecked(checked){
+        this.iconCls = checked?'fa fa-square-check':'fa fa-square';
+        this.fire('change', {component: this, checked}); // This is where our custom event is being fired
+    }
+    onClick(data){
+        super.onClick(data); 
+        this.checked = !this.checked;      
+    }
+}
+Neo.applyClassConfig(ToggleButton);
+
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: ToggleButton,
+            text: 'Toggle',
+            listeners: {
+                change: data => console.log(data.checked) // Here, we're listening to the custom event
+            }
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+How are events set up? We don't really care, but in case you're curious: Neo.mjs has a `Neo.core.Observable` class
+that can be mixed into any class. It maintains a `listeners` object map that's a key-value pair, where
+the key is the event name, and the value is an array of function references. The first time a listener is 
+added an entry is added to the map using the event name as the key, and the event handler added as the first
+item in the associated array. If another listener is added for the same event, a second item is added to the
+array. If a new event is added, a new entry is added. Etc. When the event is fired, Neo.mjs looks up the map
+entry for the event name, then runs each function in the array, passing whatever data is specified in the
+call to `fire()`.
+
+<img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/gettingStarted/events/ObservableInMemory.png"></img>

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

@@ -12,11 +12,13 @@
     {"name": "Tutorials",                                   "parentId": null,                "isLeaf": false, "expanded": false, "id": "Tutorials"},
         {"name": "Rock Scissors Paper",                     "parentId": "Tutorials",         "isLeaf": true,  "expanded": false, "id": "RSP"},
         {"name": "Earthquakes",                             "parentId": "Tutorials",         "isLeaf": true,  "expanded": false, "id": "Earthquakes"},
-    {"name": "Cookbook",                                    "parentId": null,                "isLeaf": false, "expanded": false, "id": "InDepth"},
+    {"name": "Guides",                                      "parentId": null,                "isLeaf": false, "expanded": false, "id": "InDepth"},
         {"name": "Config",                                  "parentId": "InDepth",           "isLeaf": false, "id": "Config"},
         {"name": "Instance Lifecycle",                      "parentId": "InDepth",           "isLeaf": false, "id": "InstanceLifecycle"},
         {"name": "User Input (Forms)",                      "parentId": "InDepth",           "isLeaf": false, "id": "Forms"},
+        {"name": "Layouts",                                 "parentId": "InDepth",           "isLeaf": false, "id": "Layouts"},
         {"name": "Custom Components",                       "parentId": "InDepth",           "isLeaf": false, "id": "CustomComponents"},
+        {"name": "Events",                                  "parentId": "InDepth",           "isLeaf": true,  "expanded": false, "id": "GuideEvents"},
         {"name": "Tables (Stores)",                         "parentId": "InDepth",           "isLeaf": false, "id": "Tables"},
         {"name": "Shared Bindable Data (Component Models)", "parentId": "InDepth",           "isLeaf": false, "id": "InDepthComponentModels"},
         {"name": "Multi-Window Applications",               "parentId": "InDepth",           "isLeaf": false, "id": "MultiWindow"},

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

@@ -77,4 +77,5 @@
         box-shadow: 0 8px 16px 0 rgba(0, 0, 0, 0.2);
     }
 
+
 }

package/resources/scss/src/list/Base.scss

@@ -54,51 +54,7 @@
             cursor: pointer;
 
             &:hover {
-                background-color: var(--list-item-background-color-hover) !important;
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
-                color           : var(--list-container-list-color);
-            }
-            &:active {
-                background-color: var(--list-item-background-color-active);
+                background-color: var(--list-item-background-color-hover);
                 color           : var(--list-container-list-color);
             }
             &:active {

package/src/DefaultConfig.mjs

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

package/src/component/Base.mjs

@@ -643,6 +643,10 @@ class Base extends CoreBase {
             me[state]()
         }
 
+        if (!value) {
+            me.revertFocus();
+        }
+
         me.fire(state, {id: me.id});
         me.fire('hiddenChange', {id: me.id, oldValue, value})
     }
@@ -781,10 +785,25 @@ class Base extends CoreBase {
 
                 if (me.floating) {
                     me.alignTo();
+
+                    // Focus will be pushed into the first input field or other focusable item
+                    Neo.main.DomAccess.focus({
+                        id       : this.id,
+                        children : true
+                    });
                 }
 
                 me.fire('mounted', me.id)
             }
+            else {
+                me.revertFocus();
+            }
+        }
+    }
+
+    revertFocus() {
+        if (this.containsFocus && this.focusEnterData?.relatedTarget) {
+            Neo.getComponent(this.focusEnterData.relatedTarget.id)?.focus();
         }
     }
 
@@ -1131,6 +1150,7 @@ class Base extends CoreBase {
 
         if (value) {
             value = ClassSystemUtil.beforeSetInstance(value, KeyNavigation, {
+                keyDownEventBubble : true,
                 keys: value
             })
         }
@@ -1257,6 +1277,8 @@ class Base extends CoreBase {
             parentModel = parent?.getModel(),
             parentVdom;
 
+        me.revertFocus();
+
         me.domListeners = [];
 
         me.controller = null; // triggers destroy()
@@ -1816,6 +1838,16 @@ class Base extends CoreBase {
         this.keys?.register(this)
     }
 
+    onFocusEnter(data) {
+        // If we are hidden, or unmounted while we still contain focus, we have to revert
+        // focus to where it came from if possible
+        this.focusEnterData = data;
+    }
+
+    onFocusLeave() {
+        this.focusEnterData = null;
+    }
+
     /**
      * Triggered by manager.Focus
      * @name onFocusEnter

package/src/data/RecordFactory.mjs

@@ -68,9 +68,6 @@ class RecordFactory extends Base {
                             properties;
 
                         Object.defineProperties(me, {
-                            [Symbol.for('isRecord')]: {
-                                value: true
-                            },
                             _isModified: {
                                 value   : false,
                                 writable: true

package/src/dialog/Base.mjs

@@ -100,6 +100,9 @@ class Base extends Panel {
          * @protected
          */
         isDragging: false,
+        keys: {
+            Escape: 'onKeyDownEscape'
+        },
         /**
          * @member {String} maximizeCls='far fa-window-maximize'
          */
@@ -216,8 +219,7 @@ class Base extends Panel {
      * @protected
      */
     afterSetDraggable(value, oldValue) {
-        let me           = this,
-            domListeners = me.domListeners,
+        let me = this,
             cls;
 
         if (oldValue !== undefined && me.headerToolbar) {
@@ -230,21 +232,21 @@ class Base extends Panel {
             DragZone = module.default;
 
             if (!me.dragListenersAdded) {
-                domListeners.push(
+                const dragListeners = [
                     {'drag:end'  : me.onDragEnd,   scope: me, delegate: '.neo-header-toolbar'},
                     {'drag:start': me.onDragStart, scope: me, delegate: '.neo-header-toolbar'}
-                );
+                ];
 
                 if (me.dragZoneConfig?.alwaysFireDragMove) {
-                    domListeners.push(
+                    dragListeners.push(
                         {'drag:move': me.onDragMove, scope: me, delegate: '.neo-header-toolbar'}
                     )
                 }
 
-                me.domListeners       = domListeners;
+                me.domListeners       = [...me.domListeners, ...dragListeners];
                 me.dragListenersAdded = true
             }
-        })
+        });
     }
 
     /**
@@ -444,6 +446,7 @@ class Base extends Panel {
     close(animate=!!this.animateTargetId) {
         let me = this;
 
+        me.revertFocus();
         if (animate) {
             me.animateHide()
         } else {
@@ -694,6 +697,10 @@ class Base extends Panel {
         }
     }
 
+    onKeyDownEscape() {
+        this.hidden = true;
+    }
+
     /**
      * @param {Boolean} animate=!!this.animateTargetId
      */

package/src/form/field/Picker.mjs

@@ -282,7 +282,15 @@ class Picker extends Text {
      * @protected
      */
     onKeyDownEscape(data) {
-        this.pickerIsMounted && this.hidePicker()
+        if (this.pickerIsMounted) {
+            this.hidePicker();
+
+            // We processed this event, and it should not proceed to ancestor components
+            data.cancelBubble = true;
+
+            // And no further listeers should be notified
+            return false;
+        }
     }
 
     /**

package/src/form/field/Select.mjs

@@ -219,20 +219,40 @@ class Select extends Picker {
      * @protected
      */
     beforeSetStore(value, oldValue) {
+        const
+            me                          = this,
+            { valueField, displayField} = me;
+
         oldValue?.destroy();
 
+        // Promote an array of items to be a Store
+        if (Array.isArray(value)) {
+            value = {
+                data : value.map((v, i) => {
+                    // Simplest case is just picking string values.
+                    if (typeof v === 'string') {
+                        v = {
+                            [valueField]   : v,
+                            [displayField] : v
+                        };
+                    }
+                    return v;
+                })
+            };
+        }
+
         // to reduce boilerplate code, a store config object without a defined model should default
         // to displayField & valueField defaults
         if (Neo.typeOf(value) === 'Object' && !value.model && !value.module && !value.ntype) {
             value.model = {
                 fields: [
-                    {name: 'id',   type: 'String'},
-                    {name: 'name', type: 'String'}
+                    {name: valueField,   type: 'String'},
+                    {name: displayField, type: 'String'}
                 ]
             }
         }
 
-        return ClassSystemUtil.beforeSetInstance(value, Store)
+        return ClassSystemUtil.beforeSetInstance(value, Store);
     }
 
     /**
@@ -515,7 +535,6 @@ class Select extends Picker {
 
             me.activeRecord = store.getAt(activeIndex)
             me.activeRecordId = me.activeRecord[store.keyProperty || model.keyProperty]
-            me.getInputEl()['aria-activedescendant'] = activeItem;
 
             // Update typeahead hint (which updates DOM), or update DOM
             me.typeAhead ? me.updateTypeAheadValue(me.lastManualInput) : me.update();

package/src/form/field/Text.mjs

@@ -1266,6 +1266,8 @@ class Text extends Base {
      * @protected
      */
     onFocusEnter(data) {
+        super.onFocusEnter(data);
+
         let me  = this,
             cls = me.cls;
 
@@ -1323,7 +1325,7 @@ class Text extends Base {
     onInputValueChange(data) {
         let me       = this,
             oldValue = me.value,
-            value    = data.value ? data.value.toString().trim() : me.emptyValue,
+            value    = data.value,
             vnode    = VNodeUtil.findChildVnode(me.vnode, {nodeName: 'input'});
 
         if (vnode) {
@@ -1526,7 +1528,7 @@ class Text extends Base {
             minLength    = me.minLength,
             required     = me.required,
             returnValue  = true,
-            value        = me.value ? me.value.toString().trim() : me.emptyValue,
+            value        = me.value,
             valueLength  = value?.toString().length,
             inputPattern = me.inputPattern,
             isEmpty      = value !== 0 && (!value || valueLength < 1),

package/src/layout/Flexbox.mjs

@@ -85,7 +85,7 @@ class Flexbox extends Base {
      * @protected
      */
     afterSetAlign(value, oldValue) {
-        oldValue && this.updateInputValue(value, oldValue, 'align')
+        oldValue && this.updateInputValue(value, oldValue, 'align');
     }
 
     /**
@@ -95,7 +95,7 @@ class Flexbox extends Base {
      * @protected
      */
     afterSetDirection(value, oldValue) {
-        oldValue && this.updateInputValue(value, oldValue, 'direction')
+        oldValue && this.updateInputValue(value, oldValue, 'direction');
     }
 
     /**
@@ -111,7 +111,7 @@ class Flexbox extends Base {
             style = item.wrapperStyle;
 
         style.gap = value;
-        item.wrapperStyle = style
+        item.wrapperStyle = style;
     }
 
     /**
@@ -121,7 +121,7 @@ class Flexbox extends Base {
      * @protected
      */
     afterSetPack(value, oldValue) {
-        oldValue && this.updateInputValue(value, oldValue, 'pack')
+        oldValue && this.updateInputValue(value, oldValue, 'pack');
     }
 
     /**
@@ -131,7 +131,7 @@ class Flexbox extends Base {
      * @protected
      */
     afterSetWrap(value, oldValue) {
-        oldValue && this.updateInputValue(value, oldValue, 'wrap')
+        oldValue && this.updateInputValue(value, oldValue, 'wrap');
     }
 
     /**
@@ -143,11 +143,11 @@ class Flexbox extends Base {
             flex  = style.flex || item.flex || (this.align === 'stretch' ? 1 : '0 1 auto');
 
         if (flex === 1) {
-            flex = '1 1 auto'
+            flex = '1 1 auto';
         }
 
         style.flex = flex;
-        item.wrapperStyle = style
+        item.wrapperStyle = style;
     }
 
     /**
@@ -160,7 +160,7 @@ class Flexbox extends Base {
             wrapperCls = container?.wrapperCls || [];
 
         if (!container) {
-            Neo.logError('layout.Flexbox: applyRenderAttributes -> container not yet created', me.containerId)
+            Neo.logError('layout.Flexbox: applyRenderAttributes -> container not yet created', me.containerId);
         }
 
         NeoArray.add(wrapperCls, prefix + 'container');
@@ -170,7 +170,7 @@ class Flexbox extends Base {
         me.pack      && NeoArray.add(wrapperCls, prefix + 'pack-'      + me.pack);
         me.wrap      && NeoArray.add(wrapperCls, prefix + 'wrap-'      + me.wrap);
 
-        container.wrapperCls = wrapperCls
+        container.wrapperCls = wrapperCls;
     }
 
     /**
@@ -181,7 +181,7 @@ class Flexbox extends Base {
      * @returns {String|null} value
      */
     beforeSetAlign(value, oldValue) {
-        return this.testInputValue(value, oldValue, 'alignValues', 'align')
+        return this.testInputValue(value, oldValue, 'alignValues', 'align');
     }
 
     /**
@@ -203,7 +203,7 @@ class Flexbox extends Base {
      * @returns {String|null} value
      */
     beforeSetPack(value, oldValue) {
-        return this.testInputValue(value, oldValue, 'packValues', 'pack')
+        return this.testInputValue(value, oldValue, 'packValues', 'pack');
     }
 
     /**
@@ -214,7 +214,7 @@ class Flexbox extends Base {
      * @returns {String} value
      */
     beforeSetWrap(value, oldValue) {
-        return this.testInputValue(value, oldValue, 'wrapValues', 'wrap')
+        return this.testInputValue(value, oldValue, 'wrapValues', 'wrap');
     }
 
     /**
@@ -227,7 +227,7 @@ class Flexbox extends Base {
         let style = item.wrapperStyle || {};
 
         style.flex = item.flex || null;
-        item.wrapperStyle = style
+        item.wrapperStyle = style;
     }
 
     /**
@@ -242,17 +242,25 @@ class Flexbox extends Base {
             wrapperCls = container?.wrapperCls || [];
 
         if (!container) {
-            Neo.logError('layout.Flexbox: removeRenderAttributes -> container not yet created', me.containerId)
+            Neo.logError('layout.Flexbox: removeRenderAttributes -> container not yet created', me.containerId);
         }
 
         NeoArray.remove(wrapperCls, prefix + 'container');
 
-        me.align     && NeoArray.remove(wrapperCls, prefix + 'align-'     + me.align);
-        me.direction && NeoArray.remove(wrapperCls, prefix + 'direction-' + me.direction);
-        me.pack      && NeoArray.remove(wrapperCls, prefix + 'pack-'      + me.pack);
-        me.wrap      && NeoArray.remove(wrapperCls, prefix + 'wrap-'      + me.wrap);
+        if (me.align) {
+            NeoArray.remove(wrapperCls, prefix + 'align-' + me.align);
+        }
+        if (me.direction) {
+            NeoArray.remove(wrapperCls, prefix + 'direction-' + me.direction);
+        }
+        if (me.pack) {
+            NeoArray.remove(wrapperCls, prefix + 'pack-' + me.pack);
+        }
+        if (me.wrap) {
+            NeoArray.remove(wrapperCls, prefix + 'wrap-' + me.wrap);
+        }
 
-        container.wrapperCls = wrapperCls
+        container.wrapperCls = wrapperCls;
     }
 
     /**
@@ -269,10 +277,10 @@ class Flexbox extends Base {
 
         if (!NeoArray.hasItem(validValues, value)) {
             Neo.logError(this.containerId, '-> layout: supported values for "' + propertyName + '" are' , validValues);
-            return oldValue
+            return oldValue;
         }
 
-        return value
+        return value;
     }
 
     /**
@@ -292,10 +300,10 @@ class Flexbox extends Base {
             NeoArray.remove(wrapperCls, prefix + propertyName + '-' + oldValue);
 
             if (value !== null) {
-                NeoArray.add(wrapperCls, prefix + propertyName + '-' + value)
+                NeoArray.add(wrapperCls, prefix + propertyName + '-' + value);
             }
 
-            container.wrapperCls = wrapperCls
+            container.wrapperCls = wrapperCls;
         }
     }
 }