neo.mjs 6.10.10 → 6.10.11

package/package.json

@@ -1,72 +1,74 @@
 {
-    "name": "neo.mjs",
-    "version": "6.10.10",
-    "description": "The webworkers driven UI framework",
-    "type": "module",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/neomjs/neo.git"
-    },
-    "bin": {
-        "neo-cc": "./buildScripts/createClass.mjs"
-    },
-    "scripts": {
-        "add-config": "node ./buildScripts/addConfig.mjs",
-        "build-all": "node ./buildScripts/buildAll.mjs -f -n",
-        "build-all-questions": "node ./buildScripts/buildAll.mjs -f",
-        "build-themes": "node ./buildScripts/buildThemes.mjs -f",
-        "build-threads": "node ./buildScripts/webpack/buildThreads.mjs -f",
-        "convert-design-tokens": "node ./buildScripts/convertDesignTokens.mjs",
-        "create-app": "node ./buildScripts/createApp.mjs",
-        "create-class": "node ./buildScripts/createClass.mjs",
-        "create-component": "node ./buildScripts/createComponent.mjs",
-        "generate-docs-json": "node ./buildScripts/docs/jsdocx.mjs",
-        "inject-package-version": "node ./buildScripts/injectPackageVersion.mjs",
-        "server-start": "webpack serve -c ./buildScripts/webpack/webpack.server.config.mjs --open",
-        "test": "echo \"Error: no test specified\" && exit 1",
-        "watch-themes": "node ./buildScripts/watchThemes.mjs"
-    },
-    "keywords": [
-        "javascript",
-        "frontend",
-        "framework",
-        "webworker",
-        "ecmascript",
-        "css",
-        "json"
-    ],
-    "author": "Tobias Uhlig, Rich Waters",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/neomjs/neo/issues"
-    },
-    "homepage": "https://neomjs.github.io/pages/",
-    "devDependencies": {
-        "@fortawesome/fontawesome-free": "^6.5.1",
-        "autoprefixer": "^10.4.16",
-        "chalk": "^5.3.0",
-        "clean-webpack-plugin": "^4.0.0",
-        "commander": "^11.1.0",
-        "cssnano": "^6.0.2",
-        "envinfo": "^7.11.0",
-        "fs-extra": "^11.2.0",
-        "highlightjs-line-numbers.js": "^2.8.0",
-        "inquirer": "^9.2.12",
-        "neo-jsdoc": "1.0.1",
-        "neo-jsdoc-x": "1.0.5",
-        "postcss": "^8.4.32",
-        "sass": "^1.69.5",
-        "siesta-lite": "5.5.2",
-        "showdown": "^2.1.0",
-        "url": "^0.11.3",
-        "webpack": "^5.89.0",
-        "webpack-cli": "^5.1.4",
-        "webpack-dev-server": "4.15.1",
-        "webpack-hook-plugin": "^1.0.7",
-        "webpack-node-externals": "^3.0.0"
-    },
-    "funding": {
-        "type": "GitHub Sponsors",
-        "url": "https://github.com/sponsors/tobiu"
-    }
+  "name"            : "neo.mjs",
+  "version"         : "6.10.11",
+  "description"     : "The webworkers driven UI framework",
+  "type"            : "module",
+  "repository"      : {
+    "type" : "git",
+    "url"  : "https://github.com/neomjs/neo.git"
+  },
+  "bin"             : {
+    "neo-cc" : "./buildScripts/createClass.mjs"
+  },
+  "scripts"         : {
+    "add-config"             : "node ./buildScripts/addConfig.mjs",
+    "build-all"              : "node ./buildScripts/buildAll.mjs -f -n",
+    "build-all-questions"    : "node ./buildScripts/buildAll.mjs -f",
+    "build-themes"           : "node ./buildScripts/buildThemes.mjs -f",
+    "build-threads"          : "node ./buildScripts/webpack/buildThreads.mjs -f",
+    "convert-design-tokens"  : "node ./buildScripts/convertDesignTokens.mjs",
+    "create-app"             : "node ./buildScripts/createApp.mjs",
+    "create-app-minimal"     : "node ./buildScripts/createAppMinimal.mjs",
+    "create-class"           : "node ./buildScripts/createClass.mjs",
+    "create-component"       : "node ./buildScripts/createComponent.mjs",
+    "generate-docs-json"     : "node ./buildScripts/docs/jsdocx.mjs",
+    "inject-package-version" : "node ./buildScripts/injectPackageVersion.mjs",
+    "server-start"           : "webpack serve -c ./buildScripts/webpack/webpack.server.config.mjs --open",
+    "test"                   : "echo \"Error: no test specified\" && exit 1",
+    "watch-themes"           : "node ./buildScripts/watchThemes.mjs"
+  },
+  "keywords"        : [
+    "javascript",
+    "frontend",
+    "framework",
+    "webworker",
+    "ecmascript",
+    "css",
+    "json"
+  ],
+  "author"          : "Tobias Uhlig, Rich Waters",
+  "license"         : "MIT",
+  "bugs"            : {
+    "url" : "https://github.com/neomjs/neo/issues"
+  },
+  "homepage"        : "https://neomjs.github.io/pages/",
+  "devDependencies" : {
+    "@fortawesome/fontawesome-free" : "^6.5.1",
+    "autoprefixer"                  : "^10.4.16",
+    "chalk"                         : "^5.3.0",
+    "clean-webpack-plugin"          : "^4.0.0",
+    "commander"                     : "^11.1.0",
+    "cssnano"                       : "^6.0.2",
+    "envinfo"                       : "^7.11.0",
+    "fs-extra"                      : "^11.2.0",
+    "highlightjs-line-numbers.js"   : "^2.8.0",
+    "inquirer"                      : "^9.2.12",
+    "neo-jsdoc"                     : "1.0.1",
+    "neo-jsdoc-x"                   : "1.0.5",
+    "postcss"                       : "^8.4.32",
+    "sass"                          : "^1.69.5",
+    "siesta-lite"                   : "5.5.2",
+    "showdown"                      : "^2.1.0",
+    "url"                           : "^0.11.3",
+    "webpack"                       : "^5.89.0",
+    "webpack-cli"                   : "^5.1.4",
+    "webpack-dev-server"            : "4.15.1",
+    "webpack-hook-plugin"           : "^1.0.7",
+    "webpack-node-externals"        : "^3.0.0"
+  },
+  "funding"         : {
+    "type" : "GitHub Sponsors",
+    "url"  : "https://github.com/sponsors/tobiu"
+  }
+
 }

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

@@ -0,0 +1,22 @@
+[
+    {
+        "first": "John",
+        "last": "Lennon",
+        "dob": "1940/10/09"
+    },
+    {
+        "first": "Paul",
+        "last": "McCartney",
+        "dob": "1942/06/18"
+    },
+    {
+        "first": "George",
+        "last": "Harrison",
+        "dob": "1943/02/25"
+    },
+    {
+        "first": "Ringo",
+        "last": "Starr",
+        "dob": "1940/07/07"
+    }
+]

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

@@ -78,8 +78,7 @@ class MainView extends Container {
         className : 'Foo.view.MainView',
         controller: Controller,
         model     : ViewModel,
-
-        layout: {ntype: 'fit'},
+        layout: {ntype:'vbox', align:'start'}, 
         items : [{
             module: Button,
             text  : 'Button'
@@ -92,26 +91,36 @@ Neo.applyClassConfig(MainView);
 export default MainView;
 </pre>
 
-Note the entry in `items:[]`. That's a description of the button that'll be created as the single
-item in our container. In Neo.mjs terms we're _configuring_ the button. Neo.mjs is a declarative framework,
-in which components and objects are described. It's an abstraction. In other words, the code describes 
-what we want, but not how it's done. In the code above, we want our container to have one item &mdash; a button 
-with some text. _How_ that's done isn't important here in the container. A non-declarative approach would be 
-more focused on _how_, where you might way "I want a &lt;button> HTML element with its innerHTML set to some 
-value." 
+Note the entry in `items:[]`. That's a description of the button that will be the single item in our 
+container. In Neo.mjs terms we're _configuring_ the button. Neo.mjs is a declarative framework, in 
+which components and objects are described. It's an abstraction. In other words, the code describes 
+what we want, but not how it's done. In the code above, we want our container to have one item &mdash; 
+a button with some text. _How_ that's done isn't important. A non-declarative approach would be more
+focused on _how_, where you might way "I want a &lt;button> HTML element with its innerHTML set to 
+some value." 
 
-In another topic you'll learn about the Neo.mjs config system and declaratively describing
-views, controllers, and other things.
+In another topic you'll learn about the Neo.mjs config system and declaratively describing views, 
+controllers, and other things.
 
-If you run the app you'll see one huge button. That's because the container is configured to 
-use the "fit" layout, which means the container is designed to hold one and only one component,
-and that component will take up all available space. We could get a more normal looking button
-by changing the layout.
+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 libarary relative to the examples.
 
-`layout: {ntype:'vbox', align:'start},`
 
-Neo.mjs has scores of component classes.
-You can extend them to create your own reusable components and sets of components.
+<pre data-neo>
+import Base from '../../../../src/container/Base.mjs';
+import Button from '../../../../src/button/Base.mjs';
+import Split from '../../../../src/button/Split.mjs';
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: Button,
+            text  : 'Button'
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
 
-Other topics discuss coding applications, how the config system works, controllers,
-and bindable data. However, as long as we're here

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

@@ -1 +1,116 @@
-### todo: Component Models and Binding
+
+Neo has a feature that allows shared, bindable, data.
+
+A _view model_ — `Neo.model.Component` — instance holds properties that 
+can be bound to component properties.
+
+<pre data-neo>
+import Base            from  '../../../../src/container/Base.mjs';
+import Label           from  '../../../../src/component/Label.mjs';
+import TextField       from  '../../../../src/form/field/Text.mjs';
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+
+        model: {
+            data: {
+                foo: 'Hi there!'
+            }
+        },
+        layout: 'vbox',
+        items: [{
+            module: Label,
+            bind: {
+                text: data => `The value of foo is "${data.foo}"`   // The "text" property is set as data.foo changes
+            }
+        }, {
+            module: TextField,
+            bind: {
+                value: {twoWay: true, value: data => data.foo}      // "twoWay" means data.foo is set as the text field changes
+            },
+            labelText: 'Bound to foo:',
+            width: 300,
+        }],
+        style: {padding: '1em'},
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+View model properties are visible up the containment hierarchy:
+Properties introduced in a parent container will be available to any child component, and properties
+introduces in a specific component are only visible to that component. This approach makes it easy to control scope.
+
+In this example the main view has three child items of type `MyPanel`. The main view has a view model with a 
+`foo` property, and the third child has its own view model with a `foo` property.
+
+`MyPanel` contains a `Neo.componnet.Label` whose `text` value is bound to `foo`. To resolve the binding, Neo.mjs looks up the
+containment hierarchy until it finds the value. For the first two panels the label binding looks in the label, then in its `MyPanel`
+container, then in the main view where it finds `foo`. For the third child panel the label binding looks in the label,
+then in its `MyPanel` and finds it because the third copy of `MyPanel` has its own view model with the `foo` property.
+
+The bottom line is the Neo.mjs view model and binding approach is simple and powerful, and gives you easy control over the scope
+of a value. Thus, you can share properties as globally or narrowly as needed.
+
+<pre data-neo>
+import Base            from  '../../../../src/container/Base.mjs';
+import Panel           from  '../../../../src/container/Panel.mjs';
+import Label           from  '../../../../src/component/Label.mjs';
+
+class MyPanel extends Panel {
+    static config = {
+        className : 'Example.view.MyPanel',
+        headers: [{
+            dock: 'top',
+            items: [{ module: Label, text: 'MyPanel' }]
+        }],
+        items: [{ 
+            module: Label, 
+            bind: {
+                text: data => `The value of foo is "${data.foo}"` 
+            },
+            style: {margin: '1em'}
+        }],
+        style: {margin: '1em'},
+    }
+}
+Neo.applyClassConfig(MyPanel);
+
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+
+        model: {
+            data: {
+                foo: 'parent'
+            }
+        },
+        layout: 'hbox',
+        items: [{
+            module: MyPanel,
+        }, {
+            module: MyPanel,
+        }, {
+            module: MyPanel,
+            model: {
+                data: {
+                    foo: 'child'
+                }
+            }
+        }],
+        style: {margin: '1em'},
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+
+
+
+
+Note that in the example above, the view model is in-line. Normally your view model would be 
+coded in its own class that extends 'Neo.model.Component', and you'd use that in your component.
+Just like with items component configs, trivial configs are often done in-line, and non-trivial 
+configs are coded as separate classes.
+

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

@@ -0,0 +1,157 @@
+As you've probably noticed, Neo.mjs classes have a `static config` property. 
+
+The `config` specifies properties that are applied to instances as they are
+created. In addition, Neo.mjs uses that information to set up propoerty lifecycle 
+methods.
+
+Here's an example of a new component class `Simple` with three config properties:
+
+1. `className` — used by Neo.mjs to keep track of every class
+2. `foo` — an instance property 
+2. `bar_` — another instance property 
+
+<pre data-neo>
+import Component  from '../../../../src/component/Base.mjs';
+import Container  from '../../../../src/container/Base.mjs';
+
+class Simple extends Component {
+    static config = {
+        className: 'Example.view.Simple',
+
+        foo: 1,        // An instance field and its initial (default) value
+        bar_: ''       // Another instance field -- note the underscore at the end
+
+    }
+
+}
+Neo.applyClassConfig(Simple);
+
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+
+        items: [{
+            module: Simple,
+
+            foo: 17,         // This is applied to the instance
+            bar: 'hi there'  // This is applied to the instance
+
+        }]
+
+    }
+}
+Neo.applyClassConfig(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.
+
+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
+updated or accessed. You're free to implment the methods to implement business rules, normalize
+values, or have side-effects, such as updating a view or firing an event.
+
+<pre data-neo>
+import Component  from '../../../../src/component/Base.mjs';
+import Container  from '../../../../src/container/Base.mjs';
+
+class Simple extends Component {
+    static config = {
+        className: 'Example.view.Simple',
+
+        foo: 1,        // An instance field and its initial (default) value
+        bar_: null     // Another instance field -- note the underscore at the end
+
+    }
+
+    beforeGetBar(){
+
+    }
+    beforeSetBar(value, oldValue){
+        // Use value if it's not empty
+        if (value) return value; 
+    }
+    afterSetBar(value, oldValue){
+        this.html = value;
+        this.fire('barChange', {component: this, value, oldValue});
+    }
+
+}
+Neo.applyClassConfig(Simple);
+
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+
+        items: [{
+            module: Simple,
+
+            foo: 17 ,        // This is applied to the instance
+            bar: 'hi there'  // This is applied to the instance
+
+        }]
+
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+This time if you run the code you'll "hi there" in the view. That's because the Simple instance is
+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.
+
+Updating a view is a common use case for the _afterSet_ method. It's also often used to fire an event. 
+Look at this code: `afterSetBar()` fires an event, and the config in the `items[]` is listening to it.
+
+<pre data-neo>
+import Component  from '../../../../src/component/Base.mjs';
+import Container  from '../../../../src/container/Base.mjs';
+
+class Simple extends Component {
+    static config = {
+        className: 'Example.view.Simple',
+
+        foo: 1,        // An instance field and its initial (default) value
+        bar_: null     // Another instance field -- note the underscore at the end
+
+    }
+
+    beforeGetBar(){
+
+    }
+    beforeSetBar(value, oldValue){
+        // Use value if it's not empty
+        if (value) return value; 
+    }
+    afterSetBar(value, oldValue){
+        this.html = value;
+        this.fire('barChange', {component: this, value, oldValue});
+    }
+
+}
+Neo.applyClassConfig(Simple);
+
+
+class MainView extends Container {
+    static config = {
+        className: 'Example.view.MainView',
+
+        items: [{
+            module: Simple,
+
+            foo: 17 ,        // This is applied to the instance
+            bar: 'hi there', // This is applied to the instance
+
+            listeners: {
+                barChange: data => Neo.Main.alert({message: data.value})
+            }
+
+        }]
+
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+

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

@@ -1 +1,67 @@
-### todo: Describing a View
+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. 
+
+Neo.mjs is declarative, where your code _describes_ or _configures_ the things its creating. 
+
+For example, if you wanted to create a button, you'd look in the API docs and see that buttons
+have a few key configs, including `text` and `iconCls`. The configs are properties you can 
+use to describe the component you're creating> You can also access or set the properties dynamically.
+
+<pre data-neo>
+import Base from '../../../../src/container/Base.mjs';
+import Button from '../../../../src/button/Base.mjs';
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'},
+        items : [{
+            module: Button,
+            text  : 'Home',
+            iconCls: 'fa fa-home'
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+The button config is just an object describing the button being created. In the example, it has three
+properties:
+
+- `module` is the type of thing being created; it's the imported module name.
+- `text` is the button's text
+- `iconCls` is the css class used for the button's icon. Neo.mjs automatically includes Font Awesome, 
+and `fa fa-home` matches a Font Awesome css class.
+
+Components are almost always placed within a container. A container is a component that visually holds other 
+components. Containers have an `items:[]` config, which is an array of the components within the container. 
+Containers also have a `layout` property, which describes how the items are arranged. 
+
+Let's put a second button in the container.
+
+<pre data-neo>
+import Base from '../../../../src/container/Base.mjs';
+import Button from '../../../../src/button/Base.mjs';
+class MainView extends Base {
+    static config = {
+        className : 'Example.view.MainView',
+        layout: {ntype:'vbox', align:'start'}, // Change the ntype to 'hbox'
+        items : [{
+            module: Button,
+            text  : 'Home',
+            iconCls: 'fa fa-home'
+        },{
+            module: Button,
+            text  : 'Star',
+            iconCls: 'fa fa-star'
+        }]
+    }
+}
+Neo.applyClassConfig(MainView);
+</pre>
+
+If you run the example you'll see two buttons, arranged according to the `layout`. If you'd like, 
+modify the code to specify `ntype:'hbox'` and run it again. 
+
+Note that the layout specifies `ntype` rather than `module`. An `ntype` is an alias for a class
+that has already been imported. Containers import all the layout types, so since we've already
+imported container we can simply use `ntype` to specify which layout we want.