neo.mjs 6.13.0 → 6.15.0

package/examples/component/toast/MainContainer.mjs

@@ -1,10 +1,10 @@
 import Button                  from '../../../src/button/Base.mjs';
 import CheckBox                from '../../../src/form/field/CheckBox.mjs';
+import ComboBox                from '../../../src/form/field/ComboBox.mjs';
 import Component               from '../../../src/component/Base.mjs';
 import FormContainer           from '../../../src/form/Container.mjs';
 import MainContainerController from './MainContainerController.mjs';
 import NumberField             from '../../../src/form/field/Number.mjs';
-import SelectField             from '../../../src/form/field/Select.mjs';
 import TextField               from '../../../src/form/field/Text.mjs';
 import Viewport                from '../../../src/container/Viewport.mjs';
 
@@ -51,19 +51,19 @@ class MainContainer extends Viewport {
                 labelText: 'iconCls',
                 name     : 'iconCls'
             }, {
-                module    : SelectField,
+                module    : ComboBox,
                 labelText : 'position = tr',
                 name      : 'position',
                 store     : {data: [{name: 'tl'}, {name: 'tc'}, {name: 'tr'}, {name: 'bl'}, {name: 'bc'}, {name: 'br'}]},
                 valueField: 'name'
             }, {
-                module   : SelectField,
+                module   : ComboBox,
                 labelText: 'slideDirection = right',
                 name     : 'slideDirection',
                 store    : {data: [{name: 'down'}, {name: 'up'}, {name: 'left'}, {name: 'right'}]},
                 valueField: 'name'
             }, {
-                module   : SelectField,
+                module   : ComboBox,
                 labelText: 'ui = info',
                 name     : 'ui',
                 store    : {data: [{name: 'info'}, {name: 'danger'}, {name: 'success'}]},

package/examples/dialog/DemoDialog.mjs

@@ -1,6 +1,6 @@
-import Button      from '../../src/button/Base.mjs';
-import Dialog      from '../../src/dialog/Base.mjs';
-import SelectField from '../../src/form/field/Select.mjs';
+import Button   from '../../src/button/Base.mjs';
+import ComboBox from '../../src/form/field/ComboBox.mjs';
+import Dialog   from '../../src/dialog/Base.mjs';
 
 /**
  * @class Neo.examples.dialog.DemoDialog
@@ -57,7 +57,7 @@ class DemoDialog extends Dialog {
         const me = this;
 
         me.items = [{
-            module    : SelectField,
+            module    : ComboBox,
             labelText : 'Select',
             labelWidth: 80,
 

package/examples/fieldWithPrefix/MainContainer.mjs

@@ -1,8 +1,7 @@
+import ComboBox              from '../../src/form/field/ComboBox.mjs';
 import ConfigurationViewport from '../ConfigurationViewport.mjs';
-
-import PrefixPlugin from '../../src/plugin/PrefixField.mjs';
-import SelectField  from '../../src/form/field/Select.mjs';
-import TextField    from '../../src/form/field/Text.mjs';
+import PrefixPlugin          from '../../src/plugin/PrefixField.mjs';
+import TextField             from '../../src/form/field/Text.mjs';
 
 /**
  * @class Neo.examples.fieldWithPrefix.MainContainer
@@ -50,7 +49,7 @@ class MainContainer extends ConfigurationViewport {
             value    : '_',
             style    : {marginTop: '10px'}
         }, {
-            module: SelectField,
+            module: ComboBox,
             store : {
                 model: {fields: [{name: 'id'}, {name: 'name'}, {name: 'value'}]},
                 data : [

package/examples/form/field/{select → combobox}/MainContainer.mjs

@@ -1,19 +1,18 @@
 import CheckBox              from '../../../../src/form/field/CheckBox.mjs';
+import ComboBox              from '../../../../src/form/field/ComboBox.mjs';
 import ConfigurationViewport from '../../../ConfigurationViewport.mjs';
 import MainStore             from './MainStore.mjs';
 import NumberField           from '../../../../src/form/field/Number.mjs';
-import SelectField           from '../../../../src/form/field/Select.mjs';
 import Radio                 from '../../../../src/form/field/Radio.mjs';
 import TextField             from '../../../../src/form/field/Text.mjs';
 
 /**
- * @class Neo.examples.form.field.select.MainContainer
+ * @class Neo.examples.form.field.combobox.MainContainer
  * @extends Neo.examples.ConfigurationViewport
  */
 class MainContainer extends ConfigurationViewport {
     static config = {
-        className             : 'Neo.examples.form.field.select.MainContainer',
-        autoMount             : true,
+        className             : 'Neo.examples.form.field.combobox.MainContainer',
         configItemLabelWidth  : 160,
         exampleContainerConfig: {style: {position: 'relative'}}
     }
@@ -160,17 +159,15 @@ class MainContainer extends ConfigurationViewport {
 
     createExampleComponent() {
         return Neo.create({
-            module       : SelectField,
+            module       : ComboBox,
             labelPosition: 'inline',
             labelText    : 'US States',
             labelWidth   : 80,
+            pickerConfig : {minHeight : '6em'},
             store        : MainStore,
-            value        : 'Arizona', // or 'AZ'
+            value        : 'AZ',
             valueField   : 'abbreviation',
-            width        : '50%',
-            pickerConfig : {
-                minHeight : '6em'
-            }
+            width        : '50%'
         })
     }
 }

package/examples/form/field/{select → combobox}/MainModel.mjs

@@ -1,20 +1,20 @@
 import Model  from '../../../../src/data/Model.mjs';
 
 /**
- * @class Neo.examples.form.field.select.MainModel
+ * @class Neo.examples.form.field.combobox.MainModel
  * @extends Neo.data.Model
  */
 class MainModel extends Model {
     static config = {
-        className  : 'Neo.examples.form.field.select.MainModel',
+        className  : 'Neo.examples.form.field.combobox.MainModel',
         keyProperty: 'abbreviation',
 
         fields: [{
             name: 'abbreviation',
-            type: 'string'
+            type: 'String'
         }, {
             name: 'name',
-            type: 'string'
+            type: 'String'
         }]
     }
 }

package/examples/form/field/{select → combobox}/MainStore.mjs

@@ -2,12 +2,12 @@ import Store from '../../../../src/data/Store.mjs';
 import Model from './MainModel.mjs';
 
 /**
- * @class Neo.examples.form.field.select.MainStore
+ * @class Neo.examples.form.field.combobox.MainStore
  * @extends Neo.data.Store
  */
 class MainStore extends Store {
     static config = {
-        className  : 'Neo.examples.form.field.select.MainStore',
+        className  : 'Neo.examples.form.field.combobox.MainStore',
         autoLoad   : true,
         keyProperty: 'abbreviation',
         model      : Model,

package/examples/form/field/{select → combobox}/app.mjs

@@ -2,5 +2,5 @@ import MainContainer from './MainContainer.mjs';
 
 export const onStart = () => Neo.app({
     mainView: MainContainer,
-    name    : 'Neo.examples.form.field.select'
+    name    : 'Neo.examples.form.field.combobox'
 });

package/examples/form/field/{select → combobox}/index.html

@@ -3,7 +3,7 @@
 <head>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <meta charset="UTF-8">
-    <title>Neo SelectField</title>
+    <title>Neo ComboBox</title>
 </head>
 <body>
     <script src="../../../../src/MicroLoader.mjs" type="module"></script>

package/examples/form/field/{select → combobox}/neo-config.json

@@ -1,5 +1,5 @@
 {
-    "appPath"    : "examples/form/field/select/app.mjs",
+    "appPath"    : "examples/form/field/combobox/app.mjs",
     "basePath"   : "../../../../",
     "environment": "development",
     "mainPath"   : "./Main.mjs"

package/examples/tableFiltering/MainContainer.mjs

@@ -1,11 +1,11 @@
 import BooleanContainer from '../../src/filter/BooleanContainer.mjs';
 import CellModel        from '../../src/selection/table/CellModel.mjs';
 import CheckBox         from '../../src/form/field/CheckBox.mjs';
+import ComboBox         from '../../src/form/field/ComboBox.mjs';
 import DateContainer    from '../../src/filter/DateContainer.mjs';
 import DateUtil         from '../../src/util/Date.mjs';
 import MainStore        from './MainStore.mjs';
 import NumberContainer  from '../../src/filter/NumberContainer.mjs';
-import SelectField      from '../../src/form/field/Select.mjs';
 import TableContainer   from '../../src/table/Container.mjs';
 import Viewport         from '../../src/container/Viewport.mjs';
 
@@ -64,7 +64,7 @@ class MainContainer extends Viewport {
                 text     : 'Country',
 
                 editorConfig: {
-                    module: SelectField,
+                    module: ComboBox,
 
                     store: {
                         autoLoad   : true,

package/package.json

@@ -1,7 +1,7 @@
 
 {
     "name": "neo.mjs",
-    "version": "6.13.0",
+    "version": "6.15.0",
     "description": "The webworkers driven UI framework",
     "type": "module",
     "repository": {
@@ -53,13 +53,13 @@
         "envinfo": "^7.11.1",
         "fs-extra": "^11.2.0",
         "highlightjs-line-numbers.js": "^2.8.0",
-        "inquirer": "^9.2.15",
+        "inquirer": "^9.2.16",
         "marked": "^12.0.1",
         "monaco-editor": "^0.47.0",
         "neo-jsdoc": "1.0.1",
         "neo-jsdoc-x": "1.0.5",
-        "postcss": "^8.4.35",
-        "sass": "^1.71.1",
+        "postcss": "^8.4.37",
+        "sass": "^1.72.0",
         "siesta-lite": "5.5.2",
         "url": "^0.11.3",
         "webpack": "^5.90.3",

package/resources/data/deck/learnneo/pages/2023-10-14T19-25-08-153Z.md

@@ -1,3 +1,5 @@
+## Introduction
+
 The purpose of this tutorial is to let you see the structure of a Neo.mjs workspace,
 and the structure of an application.
 
@@ -5,7 +7,12 @@ If you wish, you can create a workspace by following the directions in the previ
 
 <img src="https://raw.githubusercontent.com/neomjs/pages/main/resources/images/apps/learnneo/NeoWorkspace.png" style="height: 400px;">
 
-As you can see, a Neo.mjs workspace is a conventional npm package. If you run 
+As you can see, a Neo.mjs workspace is a conventional npm package. 
+
+
+## Browsing the workspace
+
+If you run 
 the script `npm run server-start` from the workspace, Neo.mjs launches a web
 server whose doc root is the workspace. 
 
@@ -14,6 +21,8 @@ server whose doc root is the workspace.
 If you drill down into the `src` directory you'll see your applications.
 The `docs` directory holds the Neo.mjs API docs.
 
+## The structure of a simple app
+
 In order to discuss the structure of an app, we'll create a simple starter 
 app vis this script, run from the workspace. The script prompts for various 
 application settings. 
@@ -29,6 +38,8 @@ These files are part of the typical structure of a Neo.mjs application. The file
 You will, however, edit the main container, and its associated "controller" and "model",
 as well as create new views classes, their controllers, and other application logic.
 
+## Some source code
+
 Now let's look at a source file. This is the contents of `MainView.mjs`.
 
 <pre data-javascript>
@@ -61,6 +72,8 @@ This view also has a "controller" and "model". We'll talk about those later, but
 a controller is where event handling and app logic goes, and a model is where you set up shared
 bindable data.
 
+## Adding a button to the view
+
 We'll go into a lot more depth about view, controllers, and models in other topics, but to let
 you see how a component is configured let's put a button in the container. 
 
@@ -103,6 +116,8 @@ some value."
 In another topic you'll learn about the Neo.mjs config system and declaratively describing views, 
 controllers, and other things.
 
+## A running example
+
 Here's a simplified running example. The `model` and `controller` are omitted, because they aren't 
 actually used in the example, and the import root path is different to reflect the location of the 
 Neo.mjs library relative to the examples.

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

@@ -0,0 +1,180 @@
+## Introduction
+
+Neo.mjs views are made up of components and containers. 
+
+A component is a visual widget, such as a button, label, or text field. A container is a visual 
+collection of components.
+
+`Neo.component.Base` is the base class for all components. It introduces some common features, such as
+event handling, binding, and some life-cycle methods.
+
+`Neo.container.Base` is the base class for all containers. Containers are also components.
+
+## Neo.container.Base
+
+Containers are commonly used, although there are many specialized sub-classes, such as panels and toolbars.
+
+
+Containers have two key properties: 
+
+- `items`, which are the components within the container, and 
+- `layout`, which describes how the items are arranged
+
+## Neo.component.Base
+
+The component base class introduces common component features, but is rarely used itself because it's so
+primitive. Components introduce various properties, such as `width`, `height`, `cls` (to specify CSS classes for the component).
+
+Here's a container, with one child item.
+
+<pre data-neo>
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        items    : [{
+            ntype : 'component', // Or module:Component
+            style : {border: 'thin solid red;'}, // Styling is usually done via "cls"
+            height: 100,
+            width : 200
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+Components also have an `html`. The `html` property is rarely used, and goes against the abstract philosophy of Neo.mjs, but
+sometimes it's handy as a placeholder as you stub out views.
+
+<pre data-neo>
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'},
+        items    : [{
+            ntype : 'component', // Or module:Component
+            style : {border: 'thin solid red;'}, // Styling is usually done via "cls"
+            html  : 'This is a placeholder for a more sophisticated component we\'ll add later.',
+            height: 100,
+            width : 200
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+
+## Layout
+
+The `layout` config specifies how components are arranged within a container. Here are examples of 
+some commonly-used layouts.
+
+### Fit layout
+
+Fix is used when there's a single child. The component is sized to fit the container.
+
+<pre data-neo>
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : 'fit', // If no configs are needed, simply use the ntype of the layout
+        items    : [{
+            ntype: 'component',
+            style: {backgroundColor: 'lightgreen'}, // The camel-cased property converts to the hyphenated css style
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+### Vbox and hbox
+
+Items are arranged vertically or horizontally. On-axis and off-axis alignment can be specified.
+
+<pre data-neo>
+import Button    from '../../../../src/button/Base.mjs';
+import Container from '../../../../src/container/Base.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : {ntype:'vbox', align:'start'}, // Change the ntype to 'hbox'
+        items    : [{
+            module : Button,
+            iconCls: 'fa fa-home',
+            text   : 'Home'
+        }, {
+            module : Button,
+            iconCls: 'fa fa-star',
+            text   : 'Star'
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+### Card
+
+Having multiple child items, one of which is visible. 
+
+<pre data-neo>
+import Button    from '../../../../src/button/Base.mjs';
+import Base from '../../../../src/container/Base.mjs';
+
+class MainView extends Base {
+    static config = {
+        className: 'Example.view.MainView',
+        layout   : 'vbox',
+        items    : [{
+            ntype: 'toolbar',
+            dock : 'top',
+            items: [{
+                ntype: 'button',
+                text: 'Click me to cycle through the cards',
+                ui: 'ghost',
+                iconCls: 'fa fa-chevron-right',
+                iconPosition: 'right',
+                handler: data => {
+                    const container = data.component.up('container').getReference('cardContainer');
+                    container.layout.activeIndex = (container.layout.activeIndex +1) % container.items.length;
+                }
+            }]
+        }, {
+            ntype: 'container',
+            reference: 'cardContainer',
+            layout: 'card',
+            flex: 1,
+            items: [{
+                ntype : 'component',
+                style: {backgroundColor: 'lightsalmon'}, // The camel-cased property converts to the hyphated css style
+            }, {
+                ntype : 'component',
+                style: {backgroundColor: 'darkseagreen'} // https://drafts.csswg.org/css-color/#named-colors
+            }, {
+                ntype : 'component',
+                style: {backgroundColor: 'cornflowerblue'} // Who came up with these names?
+            }]
+        }]
+    }
+}
+
+Neo.setupClass(MainView);
+</pre>
+
+
+
+
+## Reusing containers
+
+
+## Lifecycle methods

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

@@ -1,9 +1,13 @@
+## Introduction 
+
 As you've probably noticed, Neo.mjs classes have a `static config` property. 
 
 The config describes properties you can specify as you create an instance of the class.
 Any config in the class, or its ancestors, can be specified. 
 
-In addition, Neo.mjs uses that information to set up propoerty lifecycle 
+## Simple properties and lifecycle properties
+
+In addition, Neo.mjs uses that information to set up property lifecycle 
 methods.
 
 Here's an example of a new component class `Simple` with three config properties:
@@ -12,6 +16,9 @@ Here's an example of a new component class `Simple` with three config properties
 2. `foo` — an instance property 
 2. `bar_` — another instance property 
 
+The `Simple` class introduces syntax. It doesn't have any content, so if you run the code you won't 
+see anything. We'll change that in the next example.
+
 <pre data-neo>
 import Component  from '../../../../src/component/Base.mjs';
 import Container  from '../../../../src/container/Base.mjs';
@@ -46,8 +53,7 @@ class MainView extends Container {
 Neo.setupClass(MainView);
 </pre>
 
-The `Simple` class doesn't have any content, so if you run the code you won't see anything. We'll 
-change that in the next example.
+## Detecting when a value changes
 
 Note that the `bar` property is defined with an underscore at the end. That tags the property as
 a _lifecyle property_. A lifecycle property provides methods that are run as the property is
@@ -75,7 +81,6 @@ class Simple extends Component {
     }
     afterSetBar(value, oldValue){
         this.html = value;
-        this.fire('barChange', {component: this, value, oldValue});
     }
 
 }
@@ -103,6 +108,8 @@ This time if you run the code you'll see "hi there" in the view. That's because
 configured with `bar: 'hi there'`, and since that's a lifecycle property the `afterSetBar()` method
 is run. That method updates the view with the passed value.
 
+## Firing an event when a value changes
+
 Typically, the _afterSet_ method is used to update a view or to fire an event.
 
 Look at this code: `afterSetBar()` fires an event, and the config in the `items[]` is listening to it.

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

@@ -1,3 +1,5 @@
+## Introduction 
+
 A Neo.mjs view is comprised of components and containers. A component is a visual widget, like a button,
 and a container is a visual collection of components. 
 
@@ -8,6 +10,8 @@ have a few key configs, including `text` and `iconCls`. The configs are properti
 use to describe the component you're creating> You can also access or set the properties dynamically.
 
 
+## A view with one component
+
 <pre data-neo>
 import Button    from '../../../../src/button/Base.mjs';
 import Container from '../../../../src/container/Base.mjs';
@@ -42,6 +46,8 @@ Containers also have a `layout` property, which describes how the items are arra
 
 Let's put a second button in the container.
 
+## A view with two components
+
 <pre data-neo>
 import Button    from '../../../../src/button/Base.mjs';
 import Container from '../../../../src/container/Base.mjs';

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

@@ -120,7 +120,7 @@ As you can see, `MicroLoader.mjs` runs `Main.mjs`, which in turn spawns the thre
 - `neomjs-app-worker` is where app logic is run
 
 Neo.mjs apps run in multiple webworkers, and each webworker is run in a separate parallel thread.  
-Parallel processing — along wih the efficient way the `neomjs-vdom-worker` applies delta updates — is why Neo.mjs applications run so fast. 
+Parallel processing — along wih the efficient way the vdom worker applies delta updates — is why Neo.mjs applications run so fast. 
 
 ##Commonly-used Scripts
 
@@ -294,7 +294,7 @@ layout: {
 
 ## Debugging
 
-At startup a Neo.mjs application launches three Web Workers:
+At startup, a Neo.mjs application launches three Web Workers:
 
 - neomjs-app-worker
 - neomjs-data-worker
@@ -1153,7 +1153,7 @@ and each class is simpler than using complex source files that try to configure
 
 <!-- /lab -->
 
-### Google Maps Add-on
+## Google Maps Add-on
 
 Neo.mjs has a Google Map component. This component is a little different than a button or table, 
 becauase it's implemented as a _main thread add-on_. 
@@ -1169,14 +1169,10 @@ to also provide a wrapper class so it can be used like any other component withi
 Maps is implemented: there's a main-thread add-on and a corresponding Neo.mjs component. The add-on is 
 specified in _neo-config.json_, and the component is imported and used like any other component.
 
-Ultimately, normal components are responsible for specifying how 
-they're rendered (which is usually handled by Neo.mjs).
-
 How do you specify which main-thread add-ons you want? If you recall the script you used to create the starter
 app, it has a step that asks what add-ons you want. That results in populating the `mainThreadAddons` property
-in `neo-config.json`. We didn't choose Google Maps when we ran the script, but we need it. That means we
-need to edit `neo-config.json` and add it. Google Maps also requires an API key, which is also configured in
-`neo-config.json`.
+in `neo-config.json`. We didn't choose Google Maps when we ran the script, but we need it, which means we'll
+need to edit `neo-config.json`. Google Maps also requires an API key, which is also configured there.
 
 The Google Maps component has a few key configs:
 
@@ -1193,6 +1189,20 @@ Marker store records are required to have these properties:
 
 <!-- lab -->
 
+<details>
+<summary>Get the code for the custom add-on</summary>
+At the time this tutorial was written, the Neo.mjs Google Maps addon was about to be updated to 
+accomodate Google's "AdvancedMarker" class. Until that's ready, we're going to use a modified version of the add-on. 
+
+Download and unzip this file, and copy the two source files to the corresponding subdirectories in 
+your workspace's `src` directory. Note that `src` already contains some files, so don't replace the whole
+directory, but instead, move the files to their individual locations.
+
+<a href="https://s3.amazonaws.com/mjs.neo.learning.images/zip/src.zip">src.zip</a>
+
+<img src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/CopyGoogleMapsFiles.png" width="30%%"></img>
+</details>
+
 <details>
 <summary>Specify the main-thread add-on</summary>
 
@@ -1215,6 +1225,10 @@ Edit `apps/earthquakes/neo-config.json` and add entries for the Google Maps add-
 }
 </pre>
 
+It's unusual to need to edit `neo-config.json`. The app theme is specified there, and so are main thread add-ons. 
+In our case, we're adding `WS/GoogleMaps` which in turn requires that we specify the map key. The `WS/`
+prefix tells Neo.mjs that the add-on is in our workspace, rather than an add-on provided by Neo.mjs. 
+
 Save and refresh, and you'll see a console log emanating from the plugin.
 
 <img style="width:80%" src="https://s3.amazonaws.com/mjs.neo.learning.images/earthquakes/GoogleMapsLoaded.png"></img>
@@ -1406,3 +1420,16 @@ Save, refresh, and confirm that you see the value logged when you click on a map
 
 
 <!-- /lab -->
+
+## Summary
+
+Congratulations on completing the tutorial! 
+
+The goals was to give you hands-on coding a simple app to let you get a feel for syntax
+and to introduce some basic Neo.mjs concepts
+
+- Declarative, abstract code
+- Class-based coding, and the ability to extend any class, such as `view/earthquakes/Table.mjs`
+- View models, to share properties and objects, such as the store shared by the table and map
+- Events, specified via `listeners:{}`
+- Controllers, to hold event listeners and other procedural logic