neo.mjs 6.10.11 → 6.10.13

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/Extending.md

@@ -1,3 +1,4 @@
+
 In theory, a Neo.mjs app could be defined in a single `.mjs` source file. But that would be very hard to 
 maintain, and any reusable configs would have to be duplicated. Instead, each of your views and reusable 
 widgets will be defined as its own class. The result is simpler views which are inherently reusable and easier 

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

@@ -76,5 +76,4 @@
     .lab:hover {
         box-shadow: 0 8px 16px 0 rgba(0, 0, 0, 0.2);
     }
-
 }

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

@@ -101,6 +101,14 @@
                 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);
+            }
         }
 
         &.neo-navigator-active-item {

package/src/DefaultConfig.mjs

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

package/src/form/field/Date.mjs

@@ -37,6 +37,10 @@ class DateField extends Picker {
          * @member {String} errorTextInvalidDate='Not a valid date'
          */
         errorTextInvalidDate: 'Not a valid date',
+        /**
+         * @member {Boolean} isoDate=false
+         */
+        isoDate: false,
         /**
          * True to hide the DatePicker when selecting a day
          * @member {Boolean} hidePickerOnSelect=false
@@ -158,6 +162,17 @@ class DateField extends Picker {
         }
     }
 
+    /**
+     * Triggered before the value config got changed
+     * @param {String} value
+     * @param {String} oldValue
+     * @protected
+     */
+    beforeSetValue(value, oldValue) {
+        const val = super.beforeSetValue(value, oldValue);
+        return (this.isoDate && val) ? val.substring(0, 10) : val;
+    }
+
     /**
      * @returns {Neo.component.DateSelector}
      */
@@ -171,7 +186,13 @@ class DateField extends Picker {
     getValue() {
         let value = this.value;
 
-        return this.submitDateObject && value ? new Date(`${value}T00:00:00.000Z`) : value
+        if(this.submitDateObject && value) {
+            return new Date(`${value}T00:00:00.000Z`);
+        } else if(this.isoDate && value) {
+            return new Date(value).toISOString();
+        }
+
+        return value;
     }
 
     /**

package/src/main/DomUtils.mjs

@@ -31,7 +31,7 @@ export default class DomUtils extends Base {
      * @param {HTMLElement} el The element to start from.
      * @param {Function} filterFn A function which returns `true` when the desired element is reached.
      * @param {HTMLElement} [limit] The element to stop at. This is *not* considered for matching.
-     * @returns 
+     * @returns {Boolean}
      */
     static closest(el, filterFn, limit = document.body) {
         while (el?.nodeType === Node.ELEMENT_NODE && el !== limit) {

package/src/main/addon/Navigator.mjs

@@ -220,7 +220,6 @@ class Navigator extends Base {
      * @param {String|Number} newActiveElement The id of the new active element in the subject
      * element, or the index of the item.
      * @param {Object} data The data block as passed to {@link #subscribe}
-     * @returns 
      */
     navigateTo(newActiveElement, data) {
         if (!data.subject) {
@@ -233,12 +232,17 @@ class Navigator extends Base {
         // Can navigate by index. This is useful if the active item is deleted.
         // We can navigate to the same index and preserve UI stability.
         if (typeof newActiveElement === 'number') {
-            newActiveElement = data.subject.querySelectorAll(data.selector)[newActiveElement];
+            newActiveElement = data.subject.querySelectorAll(data.selector)?.[newActiveElement];
         }
         else if (typeof newActiveElement === 'string') {
             newActiveElement = DomAccess.getElement(newActiveElement);
         }
 
+        // Could not do what was asked because we could not find the requested item
+        if (!newActiveElement) {
+            return;
+        }
+
         // Find a focusable element which may be the item, or inside the item to draw focus to.
         // For example a Chip list in which .neo-list-items contain focusable Chips.
         const focusTarget = [newActiveElement, ...newActiveElement.querySelectorAll('*')].find(DomUtils.isFocusable);

package/src/tooltip/Base.mjs

@@ -261,14 +261,18 @@ class Base extends Container {
         // If it's an internal move within the delegate, do nothing
         if (currentTarget !== me.activeTarget?.id) {
             me.activeTarget = Neo.get(currentTarget);
-            me.align.target = currentTarget;
-            me.align.targetMargin = 10;
 
+            // Allow listeners (eg the Tooltip singleton) which is shared between all Components
+            // listens for this in order to reconfigure itself from the activeTarget.
+            // So this event must be fired before the alignment is set up.
             me.fire('targetOver', {
                 target : me.activeTarget,
                 data
             });
 
+            me.align.target = currentTarget;
+            me.align.targetMargin = 10;
+
             // Still visible, just realign
             if (me.mounted) {
                 me.show();

package/src/util/String.mjs

@@ -16,7 +16,8 @@ class StringUtil extends Base {
         '"' : '"',
         '\'': ''',
         '$' : '$',
-        '\\': '\'
+        '\\': '\',
+        '/' : '/'
     }
     /**
      * @member {RegExp} charPattern
@@ -27,7 +28,7 @@ class StringUtil extends Base {
      * @member {RegExp} entityPattern
      * @static
      */
-    static entityPattern = /(&)|(<)|(>)|(")|(')|($)|(\)/g
+    static entityPattern = /(&)|(<)|(>)|(")|(')|($)|(\)|(/)/g
 
     static config = {
         /**
@@ -84,8 +85,8 @@ class StringUtil extends Base {
 
     /**
      * Returns the passed string with the first letter uncapitalized.
-     * @param {Strinhg} value 
-     * @returns 
+     * @param {String} value 
+     * @returns  {String}
      */
     static uncapitalize(value) {
         return value && value[0].toLowerCase() + value.substring(1)