neo.mjs 6.9.11 → 6.10.0

package/buildScripts/convertDesignTokens.mjs

@@ -0,0 +1,173 @@
+import fs   from 'fs-extra';
+import os   from 'os';
+import path from 'path';
+
+let jsonPath    = './resources/design-tokens/json',
+    jsonFolder  = fs.readdirSync(jsonPath),
+    tokenPrefix = '',
+    tokenRegex  = new RegExp(/{(.*?)}/g),
+    emptyString, fileContent, keyMaxLength, map, match, matches, output;
+
+function capitalize(value) {
+    return value[0].toUpperCase() + value.slice(1);
+}
+
+function createEmptyString(len) {
+    return ' '.repeat(len);
+}
+
+function parseTokens(fileContent, prefix=tokenPrefix, map=[]) {
+    let baseKey, baseValue, keyValue, keys, modify, ns;
+
+    Object.entries(fileContent).forEach(([key, value]) => {
+        key = key.replace(/\?/g, '');
+        key = key.replace(/&/g, '-'); // some token names contain & chars
+        ns  = prefix === tokenPrefix ? (tokenPrefix + key) : key === 'value' ? prefix : `${prefix}-${key}`;
+
+        if (typeof value === 'object') {
+            keys   = Object.keys(value);
+            modify = value[keys[0]]?.$extensions?.['studio.tokens']?.modify || // the first key could contain the value,
+                     value[keys[1]]?.$extensions?.['studio.tokens']?.modify;   // so we are checking the 2nd too
+
+            if (modify) {
+                // assuming that each object contains its base value
+                keys.forEach(objKey => {
+                    if (!value[objKey].$extensions) {
+                        baseKey   = objKey;
+                        baseValue = value[baseKey].value;
+                    }
+                });
+
+                keys.forEach(objKey => {
+                    if (objKey !== baseKey) {
+                        modify   = value[objKey].$extensions?.['studio.tokens']?.modify;
+                        keyValue = `${modify.type}(${baseValue}, ${modify.value * 100}%)`;
+
+                        map.push([`${ns}-${objKey}`, keyValue]);
+                    } else {
+                        parseTokens(value[baseKey], `${ns}-${baseKey}`, map);
+                    }
+                })
+            } else {
+                parseTokens(value, ns, map);
+            }
+        } else if (key !== 'description' && key !== 'type') {
+            if (typeof value === 'string') {
+                if (!value.includes('{')) {
+                    if (value.includes(' ')) {
+                        value = `'${value}'`;
+                    }
+                } else {
+                    value   = value.replace(/\?/g, '');
+                    matches = value.matchAll(tokenRegex);
+
+                    // replace . with - only inside each token
+                    for (match of matches) {
+                        value = value.replace(match[0], match[0].replace(/\./g, '-'));
+                    }
+
+                    /*
+                     * some design tokens contain operations without empty spaces
+                     * e.g. {token}*0.9
+                     * calc() relies on having spaces around operators
+                     */
+                    value = value.replace(/(\S)(\*)(\S)/g, '$1 $2 $3');
+                    value = value.replace(/(\S)(\/)(\S)/g, '$1 $2 $3');
+
+                    // most likely a multiplication
+                    if (!value.endsWith('}')) {
+                        value = `calc(${value})`;
+                    }
+
+                    // convert tokens into CSS variables
+                    value = value.replace(/{(.*?)}/g, `var(--${tokenPrefix}$1)`);
+
+                    // multiple occurrences of a css variable need to get wrapped into calc()
+                    if (value.indexOf('var') !== value.lastIndexOf('var')) {
+                        value = `calc(${value})`;
+                    }
+
+                    // -token needs to get converted
+                    if (value.startsWith('-')) {
+                        value = `calc(${value.substring(1)} * -1)`
+                    }
+                }
+            }
+
+            map.push([ns, value]);
+        }
+    });
+
+    return map;
+}
+
+function replaceObjectValue(obj) {
+    Object.entries(obj).forEach(([key, value]) => {
+        if (key === 'value') {
+            if (typeof value === 'object') {
+                Object.entries(value).forEach(([valKey, prop]) => {
+                    // some token vars contain an empty string, which SCSS can not handle.
+                    if (prop === '') {
+                        prop = 'none';
+                    }
+
+                    obj[valKey] = {
+                        type : obj.type,
+                        value: prop
+                    };
+                });
+
+                delete obj.type;
+                delete obj.value;
+            }
+        } else if (typeof value === 'object') {
+            replaceObjectValue(value);
+        }
+    });
+}
+
+function sortArray(a, b) {
+    const nameA = a[0].toUpperCase();
+    const nameB = b[0].toUpperCase();
+    if (nameA < nameB) {
+        return -1;
+    }
+    if (nameA > nameB) {
+        return 1;
+    }
+
+    return 0;
+}
+
+jsonFolder.forEach(fileName => {
+    if (fileName.endsWith(".json")) {
+        console.log('Parsing file:', fileName);
+
+        fileContent  = JSON.parse(fs.readFileSync(path.join(jsonPath, fileName)));
+        keyMaxLength = 0;
+        output       = [':root .neo-theme-neo-light {'];
+
+        replaceObjectValue(fileContent);
+
+        map = parseTokens(fileContent);
+
+        map.sort(sortArray);
+
+        map.forEach(item => {
+            keyMaxLength = Math.max(item[0].length, keyMaxLength);
+        });
+
+        map.forEach(item => {
+            emptyString = createEmptyString(keyMaxLength - item[0].length);
+
+            output.push(`    --${item[0] + emptyString}: ${item[1]};`);
+        });
+
+        output.push('}');
+        output.push('');
+
+        fileName = capitalize(fileName.split('.').shift()) + '.scss'
+
+        fs.writeFileSync(path.join('./resources/scss/theme-neo-light/design-tokens/', fileName), output.join(os.EOL));
+    }
+});

package/examples/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='6.9.11'
+         * @member {String} version='6.10.0'
          */
-        version: '6.9.11'
+        version: '6.10.0'
     }
 
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neo.mjs",
-    "version": "6.9.11",
+    "version": "6.10.0",
     "description": "The webworkers driven UI framework",
     "type": "module",
     "repository": {
@@ -16,6 +16,7 @@
         "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",
@@ -40,10 +41,8 @@
         "url": "https://github.com/neomjs/neo/issues"
     },
     "homepage": "https://neomjs.github.io/pages/",
-    "dependencies": {
+    "devDependencies": {
         "@fortawesome/fontawesome-free": "^6.4.2",
-        "@material/mwc-button": "^0.27.0",
-        "@material/mwc-textfield": "^0.27.0",
         "autoprefixer": "^10.4.16",
         "chalk": "^5.3.0",
         "clean-webpack-plugin": "^4.0.0",
@@ -57,17 +56,15 @@
         "neo-jsdoc-x": "1.0.5",
         "postcss": "^8.4.31",
         "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"
     },
-    "devDependencies": {
-        "siesta-lite": "5.5.2",
-        "url": "^0.11.3"
-    },
     "funding": {
         "type": "GitHub Sponsors",
         "url": "https://github.com/sponsors/tobiu"

package/resources/data/deck/learnneo/p/2023-10-01T18-29-19-158Z.md

@@ -3,29 +3,27 @@ Neo.mjs is a framework used to create <mark>browser-based</mark> applications.
 
 # Some key features and benefits of Neo.mjs are:
 
-<code><A code snippet></code>
-
 <details>
-<summary>Multi-Threaded</summary>
+<summary><h2>Multi-Threaded</h2></summary>
 <p>
 When a Neo.mjs application starts, the framework spawns three web-workers, in addition
 to the main browser thread, resulting in:
 <ol>
 <li>The <b>main</b> browser thread, where DOM updates are applied
-<li>An <b>application</b> web-worker where normal application locic is run
+<li>An <b>application</b> web-worker where normal application logic is run
 <li>A <b>data</b> web-worker were HTTP and socket calls are run
 <li>A <b>view</b> web-worker that manages delta updates
 </ol>
 </details>
 <details>
-<summary>Extreme Speed</summary>
+<summary><h2>Extreme Speed</h2></summary>
 <p>
-Web-worker proccesses are automatically run in parallel, on separate CPU cores.
+Web-worker processes are automatically run in parallel, on separate CPU cores.
 </p>
 <p>
 By contrast, other JavaScript frameworks run in a single thread. That means 
 in a typical framework all business logic, data handling, and DOM rendering compete for 
-CPU reasources.
+CPU resources.
 </p>
 <p>
 This means Neo.mjs applications run and render faster. This is 
@@ -39,14 +37,14 @@ to run other specialized logic.
 </p>
 </details>
 <details>
-<summary>Quick Application Development</summary>
+<summary><h2>Quick Application Development</h2></summary>
 <p>
-Neo.js classes let you specify properties in a way that allows code to detect "before" and "after"
+Neo.mjs classes let you specify properties in a way that allows code to detect "before" and "after"
 changes. This makes it easy to handle value validation and transformation, and react to changes. 
 </p>
 <p>
 Neo.mjs also has elegant yet powerful state management features that make it easy to create shared,
-bindable data. For example, if two components are bound to the same propery, a change to the 
+bindable data. For example, if two components are bound to the same property, a change to the 
 property will automatically be applied to both components.
 </p>
 <p>
@@ -57,7 +55,7 @@ update its properties &dash; these updates are immediately reflected in the runn
 </p>
 </details>
 <details>
-<summary>Multi-Window Applications</summary>
+<summary><h2>Multi-Window Applications</h2></summary>
 <p>
 Neo.mjs applications can also launch as <i>shared web workers</i>, which allows you to have a single 
 application run in multiple browser windows; those windows could be moved to multiple monitors.
@@ -69,10 +67,10 @@ across windows, running seamlessly as a single application.
 </p>
 </details>
 <details>
-<summary>Open-Source and Standards-Based</summary>
+<summary><h2>Open-Source and Standards-Based</h2></summary>
 <p>
-Neo.mjs is an open-source library. Features needed for the community can be added to the
-library via pull-requests. And since Neo.mjs uses the standard JavaScript class system, 
+Neo.mjs is an open-source framework. Features needed for the community can be added to the
+framework via pull-requests. And since Neo.mjs uses the standard JavaScript class system, 
 all Neo.mjs classes can be extended.
 </p>
 <p>
@@ -80,11 +78,11 @@ Neo.mjs uses standard modular JavaScript, so developers don't need to learn non-
 syntax, and there's no need for special pre-compilers or WebPack modules.
 That means fewer dependencies and easier configuration. Furthermore, the use of
 standard JavaScript makes debugging easier: any statement you write while developing your
-applcation can also be run in the debugging console.
+application can also be run in the debugging console.
 </p>
 </details>
 <details>
-<summary>Scalable</summary>
+<summary><h2>Scalable</h2></summary>
 <p>
 Applications can become exponentially difficult to implement as application 
 complexity increases. In contrast, the effort to code applications in Neo.mjs 

package/resources/data/deck/learnneo/p/2023-10-07T19-18-28-517Z.md

@@ -1,9 +1,8 @@
 Neo.mjs classes are standard JavaScript classes. Every source file
 you write will be a class definition, extending some Neo.mjs
-class.
+class. 
 
-<pre>
-<code class="javascript">
+<pre data-javascript>
 import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
 
 class Mammal extends Base {
@@ -14,15 +13,14 @@ class Mammal extends Base {
 
 const myMammal = Neo.create(Mammal);
 
-Neo.applyClassConfig(Mammal); // Where Neo.mjs initialializes the class config. 
+Neo.applyClassConfig(Mammal); // Where Neo.mjs initializes the class config. 
 export default Mammal;        // Makes the class available elsewhere.
-</code>
 </pre>
 
 In the example above, we're extending the Neo.mjs base class. The static
-config block describes the class we're defining. 
-
-All classes specify `className`; you'll add other config properties to describe the class.
+config block is unique to Neo.mjs; it provides a way of defining special
+properties, such as the `className` seen above. Over time we'll go into more detail
+on the static config property.
 
 The `const myMammal = Neo.create(Mammal);` statement creates an instance of
 our class. For the sake of our discussion we're putting that statement in the same source
@@ -31,8 +29,7 @@ and create instances as needed.
 
 Let's add a `name` propery to the class.
 
-<pre>
-<code class="javascript">
+<pre data-javascript>
 import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
 
 class Mammal extends Base {
@@ -50,7 +47,6 @@ console.log(myMammal.name);           // Logs "Herbert"
 Neo.applyClassConfig(Mammal);
 
 export default Mammal;
-</code>
 </pre>
 
 In Neo.mjs, instance properties are usually added in the `static config` block.
@@ -65,13 +61,11 @@ anywhere in the class hierarchy.
 Since our class defines a `name` property, we can specify that when creating
 the instance, using the second argument to the `create` method. 
 
-<pre>
-<code class="javascript">
+<pre data-javascript>
 const myMammal = Neo.create(Mammal, {
     name: 'Creature'
 });
 console.log(myMammal.name);           // Logs "Creature"
-</code>
 </pre>
 
 
@@ -79,8 +73,7 @@ Since _you_ define those properties, you can
 look for them in class methods and use them as needed.
 Let's add a `speak()` method that uses the `name` property.
 
-<pre>
-<code class="javascript">
+<pre data-javascript>
 import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
 
 class Mammal extends Base {
@@ -103,7 +96,6 @@ myMammal.speak(); // Logs "Creature is grunting."
 Neo.applyClassConfig(Mammal);
 
 export default Mammal;
-</code>
 </pre>
 
 

package/resources/data/deck/learnneo/p/2023-10-08T20-20-07-934Z.md

@@ -3,7 +3,7 @@ In Neo.mjs you sub-class and override methods in the usual way.
 Here, we'll extend `Mammal` and override the `speak()` method. 
 (For brevity, we'll exclude `export` and `import` statements.)
 
-<pre class="neo">
+<pre data-javascript>
 class Mammal extends Base {
     static config = {
         className: 'Simple.example.Mammal',
@@ -16,7 +16,8 @@ class Mammal extends Base {
 }
 Neo.applyClassConfig(Mammal);
 </pre>
-<pre class="neo">
+
+<pre data-javascript>
 class Human extends Mammal {
     static config = {
         className: 'Simple.example.Human',
@@ -37,7 +38,7 @@ Neo.applyClassConfig(Mammal);
 Any class in the hierarchy is free to add new properties and methods. Let's add
 a property and behavior (method) to the Human class.
 
-<pre class="neo">
+<pre data-javascript>
 import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
 
 class Mammal extends Base {
@@ -51,7 +52,8 @@ class Mammal extends Base {
     }
 }
 </pre>
-<pre class="neo">
+
+<pre data-javascript>
 class Human extends Mammal {
     static config = {
         className: 'Simple.example.Human',
@@ -69,7 +71,7 @@ const myPerson = Neo.create(Human, {
     name: 'Herbert'
 });
 myPerson.speak();        // Logs "Hello! My name is Herbert. I am not married."
-myPerson.yodel();        // Logs "Yedelay hee hoo!"
+myPerson.yodel();        // Logs "Yodelay hee hoo!"
 
 Neo.applyClassConfig(Human);
 </pre>

package/resources/data/deck/learnneo/p/2023-10-08T20-20-37-336Z.md

@@ -1,29 +1,36 @@
 Neo.mjs uses standard modular JavaScript, so you're free to use other class 
 features, like private members.
-<pre class="neo">
+<pre><code class="javascript">
 class Human extends Mammal {
     static config = {
         className: 'Simple.example.Human',
-        name: 'J. Doe',
-        married: false,
+        name     : 'J. Doe',
+        married  : false
     }
+
     static #privateStaticField = 'foo'
+
     #privateInstanceField = 'bar'
-    #privateInstanceMethod(){
+
+    #privateInstanceMethod() {
         console.log(`Psst. Don't tell anyone, but ${this.#privateInstanceField} and ${Human.#privateStaticField}`);
     }
-    speak(tellSecret){
+
+    speak(tellSecret) {
         console.log(`Hello! My name is ${this.name}. I am ${this.married?'':'not'} married.`);
         if (tellSecret) this.#privateInstanceMethod();
     }
-    yodel(){
+
+    yodel() {
         console.log('Yodelay hee hoo!');
-    }}
+    }
+}
+
+Neo.applyClassConfig(Human);
 
 const myPerson = Neo.create(Human, {
     name: 'Herbert'
 });
-myPerson.speak(true);
 
-Neo.applyClassConfig(Human);
-</pre>
+myPerson.speak(true);
+</code></pre>

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

@@ -1,7 +1,7 @@
 The purpose of this tutorial is to let you see the structure of a Neo.mjs workspace,
-and the strucure of an application.
+and the structure of an application.
 
-If you haven't already done it, run `npx neo-app` to create a Neo.mjs workspace.
+If you wish, you can create a workspace for yourself by running `npx neo-app` workspace.
 
 <img src="https://raw.githubusercontent.com/neomjs/pages/main/resources/images/apps/learnneo/NeoWorkspace.png" style="height: 400px;">
 
@@ -12,26 +12,26 @@ serve whose doc root is the workspace.
 <img src="https://raw.githubusercontent.com/neomjs/pages/main/resources/images/apps/learnneo/ServerRoot.png" style="height: 400px;">
 
 If you drill down into the `src` directory you'll see your applications.
-If you drill down into the `docs` directory you'll see the Neo.mjs API docs.
+The `docs` directory holds the Neo.mjs API docs.
 
 In order to discuss the structure of an app, we'll create a simple starter 
-app. To do that, run this command from the workspace.
+app vis this script, run from the workspace. The script prompts for various 
+application settings. 
 
 `npm run create-app-empty`
 
-At the first prompt, name the app `Foo`, and accept the default for everything else.
+At the first prompt, we'll name the app `Foo`, and accept the default for everything else.
 The script creates an application structured as follows.
 
 <img src="https://raw.githubusercontent.com/neomjs/pages/main/resources/images/apps/learnneo/FooFolder.png" style="height: 400px;">
 
 These files are part of the typical structure of a Neo.mjs application. The files `index.html`, `app.mjs`, `neo-config.json`, `view/Viewport.mjs` are rarely modified.
 You will, however, edit the main container, and its associated "controller" and "model",
-as well as create new views, new controllers, etc. 
+as well as create new views classes, their controllers, and other application logic.
 
 Now let's look at a source file. This is the contents of `MainView.mjs`.
 
-<pre>
-<code class="javascript">
+<pre data-javascript>
 import Base       from '../../../node_modules/neo.mjs/src/container/Base.mjs';
 import Controller from './MainViewController.mjs';
 import ViewModel  from './MainViewModel.mjs';
@@ -51,7 +51,6 @@ class MainView extends Base {
 Neo.applyClassConfig(MainView);
 
 export default MainView;
-</code>
 </pre>
 
 Neo.mjs views are composed of components. A component can be a "container", which means it
@@ -70,8 +69,7 @@ you see how a component is configured let's put a button in the container.
 First, we need to import the class that defines buttons. Then we'll describe the new button in the
 `items:[].`
 
-<pre>
-<code class="javascript">
+<pre data-javascript>
 import Base       from '../../../node_modules/neo.mjs/src/container/Base.mjs';
 import Controller from './MainViewController.mjs';
 import ViewModel  from './MainViewModel.mjs';
@@ -95,27 +93,25 @@ class MainView extends Base {
 Neo.applyClassConfig(MainView);
 
 export default MainView;
-</code>
 </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 _declarative_,
-which components and objects are _described_. It's an abstraction. In other words we're saying 
-what we want, but not how it's done. We want a button with some text &mdash; 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'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." 
 
 In another topic you'll learn about the Neo.mjs config system and declaratively describing
 views, controllers, and other things.
 
-If you run the +foo+ app you'll see one huge button. That's because the container is configured to 
+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.
 
-`layout: {type:'vbox', align:'start},`
-
-Change that line and look at the running application. 
+`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.

package/resources/data/deck/learnneo/p/2023-10-31T13-59-37-550Z.md

@@ -0,0 +1,31 @@
+<pre data-javascript>
+import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
+
+class Mammal extends Base {
+    static config = {
+        className: 'Simple.example.Mammal'
+    }
+}
+
+const myMammal = Neo.create(Mammal);
+
+Neo.applyClassConfig(Mammal); // Where Neo.mjs initializes the class config. 
+export default Mammal;        // Makes the class available elsewhere.
+</pre>
+
+
+
+<pre data-neo>
+import Base from '../../../node_modules/neo.mjs/src/core/Base.mjs';
+
+class Mammal extends Base {
+    static config = {
+        className: 'Simple.example.Mammal'
+    }
+}
+
+const myMammal = Neo.create(Mammal);
+
+Neo.applyClassConfig(Mammal); // Where Neo.mjs initializes the class config. 
+export default Mammal;        // Makes the class available elsewhere.
+</pre>

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

@@ -0,0 +1,15 @@
+Let's go through the steps of creating a main thread addon.
+
+Let's say we needed to show a code editor. There are a lot of libraries
+for this, such as Ace (<a href="https://ace.c9.io/" target="_blank">ace.c9.io</a>).
+From a coding perspective, these editors have a simple API: a setter
+to specify the string being edited, a getter to read the string, and
+a change event fired as the user types.
+
+Here's what we need to do:
+- Define a main thread addon and its API
+- Define a component wrapper
+
+### Define the Main Thread Addon
+
+### Define the component wrapper