neo.mjs 6.9.10 → 6.9.11

package/resources/data/deck/training/p/2023-07-01T15-42-45-193Z.md

@@ -0,0 +1,433 @@
+#Introduction
+
+During class you'll create three or four apps. The built-in _create-app_ script
+isn't suitable for this course, so in this lab you'll create a new _create-app-training_
+script that creates a starter app with content thats' a good starting
+point for our labs.
+
+
+#Steps
+
+??Create the file `workspace/buildScripts/createAppTraining.mjs`
+
+Use this content. The details don't matter. (Frankly, it's a bit of a mess.)
+But in a nutshell, the script creates an app with an empty view, view model, 
+and controller. It'll be easier to work with than the default _create-app_ script.
+
+This is long. Make sure you scroll and copy the entire contents.
+<pre style="border: thin solid gray; color:gray; padding: 8px; height:200px">
+import chalk from 'chalk';
+import {spawnSync} from 'child_process';
+import {Command} from 'commander/esm.mjs';
+import envinfo from 'envinfo';
+import fs from 'fs-extra';
+import inquirer from 'inquirer';
+import os from 'os';
+import path from 'path';
+
+const __dirname = path.resolve(),
+    cwd = process.cwd(),
+    requireJson = path => JSON.parse(fs.readFileSync((path))),
+    packageJson = requireJson(path.join(__dirname, 'package.json')),
+    insideNeo = packageJson.name === 'neo.mjs',
+    neoPath = insideNeo ? './' : './node_modules/neo.mjs/',
+    addonChoices = fs.readdirSync(path.join(neoPath, '/src/main/addon')).map(item => item.slice(0, -4)),
+    program = new Command(),
+    programName = `${packageJson.name} create-app`,
+    questions = [],
+    scssFolders = fs.readdirSync(path.join(neoPath, '/resources/scss')),
+    themeFolders = [];
+
+scssFolders.forEach(folder => {
+    if (folder.includes('theme')) {
+        themeFolders.push(`neo-${folder}`);
+    }
+});
+
+program
+    .name(programName)
+    .version(packageJson.version)
+    .option('-i, --info', 'print environment debug info')
+    .option('-a, --appName &lt;value>')
+    .option('-m, --mainThreadAddons &lt;value>', `Comma separated list of:\n${addonChoices.join(', ')}\nDefaults to DragDrop, Stylesheet`)
+    .option('-s, --useServiceWorker &lt;value>', '"yes", "no"')
+    .option('-t, --themes &lt;value>', ['all', ...themeFolders, 'none'].join(", "))
+    .option('-u, --useSharedWorkers &lt;value>', '"yes", "no"')
+    .allowUnknownOption()
+    .on('--help', () => {
+        console.log('\nIn case you have any issues, please create a ticket here:');
+        console.log(chalk.cyan(process.env.npm_package_bugs_url));
+    })
+    .parse(process.argv);
+
+const programOpts = program.opts();
+
+if (programOpts.info) {
+    console.log(chalk.bold('\nEnvironment Info:'));
+    console.log(`\n  current version of ${packageJson.name}: ${packageJson.version}`);
+    console.log(`  running from ${__dirname}`);
+
+    envinfo
+        .run({
+            System: ['OS', 'CPU'],
+            Binaries: ['Node', 'npm', 'Yarn'],
+            Browsers: ['Chrome', 'Edge', 'Firefox', 'Safari'],
+            npmPackages: ['neo.mjs']
+        }, {
+            duplicates: true,
+            showNotFound: true
+        })
+        .then(console.log);
+} else {
+    console.log(chalk.green(programName));
+
+    if (programOpts.mainThreadAddons) {
+        programOpts.mainThreadAddons = programOpts.mainThreadAddons.split(',');
+    }
+
+    if (!programOpts.appName) {
+        questions.push({
+            type: 'input',
+            name: 'appName',
+            message: 'Please choose a name for your neo app:',
+            default: 'MyApp'
+        });
+    }
+
+    if (!programOpts.themes) {
+        questions.push({
+            type: 'list',
+            name: 'themes',
+            message: 'Please choose a theme for your neo app:',
+            choices: ['all', ...themeFolders, 'none'],
+            default: 'all'
+        });
+    }
+
+    if (!programOpts.mainThreadAddons) {
+        questions.push({
+            type: 'checkbox',
+            name: 'mainThreadAddons',
+            message: 'Please choose your main thread addons:',
+            choices: addonChoices,
+            default: ['DragDrop', 'Stylesheet']
+        });
+    }
+
+    if (!programOpts.useSharedWorkers) {
+        questions.push({
+            type: 'list',
+            name: 'useSharedWorkers',
+            message: 'Do you want to use SharedWorkers? Pick yes for multiple main threads (Browser Windows):',
+            choices: ['yes', 'no'],
+            default: 'no'
+        });
+    }
+
+    if (!programOpts.useServiceWorker) {
+        questions.push({
+            type: 'list',
+            name: 'useServiceWorker',
+            message: 'Do you want to use a ServiceWorker for caching assets?',
+            choices: ['yes', 'no'],
+            default: 'no'
+        });
+    }
+
+    inquirer.prompt(questions).then(answers => {
+        let appName = programOpts.appName || answers.appName,
+            mainThreadAddons = programOpts.mainThreadAddons || answers.mainThreadAddons,
+            themes = programOpts.themes || answers.themes,
+            useSharedWorkers = programOpts.useSharedWorkers || answers.useSharedWorkers,
+            useServiceWorker = programOpts.useServiceWorker || answers.useServiceWorker,
+            lAppName = appName.toLowerCase(),
+            appPath = 'apps/' + lAppName + '/',
+            dir = 'apps/' + lAppName,
+            folder = path.resolve(cwd, dir),
+            startDate = new Date();
+
+        if (!Array.isArray(themes)) {
+            themes = [themes];
+        }
+
+        if (themes.length > 0 && !themes.includes('none') && !mainThreadAddons.includes('Stylesheet')) {
+            console.error('ERROR! The Stylesheet mainThreadAddon is mandatory in case you are using themes');
+            console.log('Exiting with error.');
+            process.exit(1);
+        }
+
+        fs.mkdir(path.join(folder, '/view'), {recursive: true}, (err) => {
+            if (err) {
+                throw err;
+            }
+
+            let content, className;
+            const neoSrcPath = `../../../${insideNeo ? '' : 'node_modules/neo.mjs/'}src`;
+
+            const appContent = [
+                "import Viewport from './view/Viewport.mjs';",
+                "",
+                "export const onStart = () => Neo.app({",
+                "    mainView: Viewport,",
+                "    name    : '" + appName + "'",
+                "});"
+            ].join(os.EOL);
+
+            fs.writeFileSync(folder + '/app.mjs', appContent);
+
+            const indexContent = `
+&lt;!DOCTYPE HTML>
+&lt;html>
+&lt;head>
+    &lt;meta name="viewport" content="width=device-width, initial-scale=1">
+    &lt;meta charset="UTF-8">
+    &lt;title>${appName}&lt;/title>
+&lt;/head>
+&lt;body>
+    &lt;script src="../../src/MicroLoader.mjs" type="module">&lt;/script>
+    &lt;script>
+    new MutationObserver((mutationsList, observer) => {
+        for (let mutation of mutationsList) {
+            for (let addedNode of mutation.addedNodes) {
+                if (addedNode.className && addedNode.className.includes(\'neo-viewport\')) {
+                    addedNode.addEventListener("contextmenu", function (e) {
+                        if (!(e.ctrlKey || e.metaKey)) return;
+                        e.stopPropagation();
+                        e.preventDefault();
+                        const event = new Event('neo-debug-item-select', {bubbles: true});
+                        e.target.dispatchEvent(event);
+                    });
+                    observer.disconnect(); // We found the viewport so we\'re finished listening
+                }
+            }
+        }
+    }).observe(document.body, {childList: true, subtree: false});
+    &lt;/script>
+&lt;/body>
+&lt;/html>
+`;
+            fs.writeFileSync(path.join(folder, 'index.html'), indexContent);
+
+
+
+            let neoConfig = {
+                appPath: `${insideNeo ? '' : '../../'}${appPath}app.mjs`,
+                basePath: '../../',
+                environment: 'development',
+                mainPath: `${insideNeo ? './' : '../node_modules/neo.mjs/src/'}Main.mjs`
+            };
+
+            if (!(mainThreadAddons.includes('DragDrop') && mainThreadAddons.includes('Stylesheet') && mainThreadAddons.length === 2)) {
+                neoConfig.mainThreadAddons = mainThreadAddons;
+            }
+
+            if (!themes.includes('all')) { // default value
+                if (themes.includes('none')) {
+                    neoConfig.themes = [];
+                } else {
+                    neoConfig.themes = themes;
+                }
+            }
+
+            if (useSharedWorkers !== 'no') {
+                neoConfig.useSharedWorkers = true;
+            }
+
+            if (useServiceWorker !== 'no') {
+                neoConfig.useServiceWorker = true;
+            }
+
+            if (!insideNeo) {
+                neoConfig.workerBasePath = '../../node_modules/neo.mjs/src/worker/';
+            }
+
+            let configs = Object.entries(neoConfig).sort((a, b) => a[0].localeCompare(b[0]));
+            neoConfig = {};
+
+            configs.forEach(([key, value]) => {
+                neoConfig[key] = value;
+            });
+
+            fs.writeFileSync(path.join(folder, 'neo-config.json'), JSON.stringify(neoConfig, null, 4));
+
+            // App source files: viewport and main view
+
+
+
+
+            // -------------------------------------------------------------------------
+
+            className = 'Viewport';
+            content = `
+import Base     from '${neoSrcPath}/container/Viewport.mjs';
+import MainView from './MainView.mjs';
+
+class ${className} extends Base {
+    static config = {
+        className: '${appName}.view.${className}',
+        autoMount: true,
+        layout: {ntype: 'fit'},
+        items: [{module:MainView}],
+    }
+    afterSetMounted(value, oldValue) {
+        super.afterSetMounted(value, oldValue);
+        if (!value) return;
+        this.addDomListeners({
+            "neo-debug-item-select": (event) => {
+                event.path.forEach((item) => {
+                    const component = Neo.getComponent(item.id);
+                    if (component) console.log(component);
+                });
+            },
+        });
+    }
+}
+Neo.applyClassConfig(${className});
+export default ${className};
+`;
+            fs.writeFileSync(path.join(`${folder}/view/${className}.mjs`), content);
+
+
+
+
+            // -------------------------------------------------------------------------
+
+            className = 'MainView';
+            content = `
+import Base from '${neoSrcPath}/container/Base.mjs';
+import Controller from './${className}Controller.mjs';
+import ViewModel from './${className}Model.mjs';
+
+class ${className} extends Base {
+    static config = {
+        className: '${appName}.view.${className}',
+        controller: {module: Controller},
+        model: {module: ViewModel},
+
+        layout: {ntype: 'fit'},
+        items: [],
+    }
+}
+
+Neo.applyClassConfig(${className});
+
+export default ${className};
+            `;
+            fs.writeFileSync(path.join(`${folder}/view/${className}.mjs`), content);
+
+
+
+
+
+            // -------------------------------------------------------------------------
+
+            className = 'MainViewController';
+            content = `
+import Base from '${neoSrcPath}/controller/Component.mjs';
+
+class ${className} extends Base {
+    static config = {
+        className: '${appName}.view.${className}',
+    }
+}
+
+Neo.applyClassConfig(${className});
+
+export default ${className};
+            `;
+            fs.writeFileSync(path.join(`${folder}/view/${className}.mjs`), content);
+
+
+
+
+
+            // -------------------------------------------------------------------------
+
+            className = 'MainViewModel';
+            content = `
+import Base from '${neoSrcPath}/model/Component.mjs';
+
+class ${className} extends Base {
+    static config = {
+        className: '${appName}.view.${className}',
+
+        data: {}
+    }
+}
+
+Neo.applyClassConfig(${className});
+
+export default ${className};
+            `;
+            fs.writeFileSync(path.join(`${folder}/view/${className}.mjs`), content);
+
+
+
+
+
+            // -------------------------------------------------------------------------
+
+            let appJsonPath = path.resolve(cwd, 'buildScripts/myApps.json'),
+                appJson;
+
+            if (fs.existsSync(appJsonPath)) {
+                appJson = requireJson(appJsonPath);
+            } else {
+                appJsonPath = path.resolve(__dirname, 'buildScripts/webpack/json/myApps.json');
+
+                if (fs.existsSync(appJsonPath)) {
+                    appJson = requireJson(appJsonPath);
+                } else {
+                    appJson = requireJson(path.resolve(__dirname, 'buildScripts/webpack/json/myApps.template.json'));
+                }
+            }
+
+            if (!appJson.apps.includes(appName)) {
+                appJson.apps.push(appName);
+                appJson.apps.sort();
+            }
+
+            fs.writeFileSync(appJsonPath, JSON.stringify(appJson, null, 4));
+
+            if (mainThreadAddons.includes('HighlightJS')) {
+                spawnSync('node', [
+                    './buildScripts/copyFolder.mjs',
+                    '-s',
+                    path.resolve(neoPath, 'docs/resources'),
+                    '-t',
+                    path.resolve(folder, 'resources'),
+                ], {env: process.env, cwd: process.cwd(), stdio: 'inherit'});
+            }
+
+            const processTime = (Math.round((new Date - startDate) * 100) / 100000).toFixed(2);
+            console.log(`\nTotal time for ${programName}: ${processTime} s`);
+
+            process.exit();
+        });
+    });
+}
+</pre>
+
+??Add an entry in `workspace/package.json`
+
+Edit `workspace.package` and add an entry for the new script.
+
+<pre style="font-size:80%; color:lightgray;border:thin solid gray; padding: 8px;">
+"scripts": {
+    "add-config": "node ./node_modules/neo.mjs/buildScripts/addConfig.mjs",
+    "build-all": "node ./node_modules/neo.mjs/buildScripts/buildAll.mjs -n",
+    "build-all-questions": "node ./node_modules/neo.mjs/buildScripts/buildAll.mjs",
+    "build-my-apps": "node ./node_modules/neo.mjs/buildScripts/webpack/buildMyApps.mjs",
+    "build-themes": "node ./node_modules/neo.mjs/buildScripts/buildThemes.mjs",
+    "build-threads": "node ./node_modules/neo.mjs/buildScripts/webpack/buildThreads.mjs",
+    "copy-examples": "node ./buildScripts/copyExamples.mjs",
+    "create-app": "node ./node_modules/neo.mjs/buildScripts/createApp.mjs",
+    <span style="color:blue">"create-app-training": "node ./buildScripts/createAppTraining.mjs",</span>
+    "create-class": "node ./node_modules/neo.mjs/buildScripts/createClass.mjs",
+    "generate-docs-json": "node ./node_modules/neo.mjs/buildScripts/docs/jsdocx.mjs",
+    "inject-package-version": "node ./buildScripts/injectPackageVersion.mjs",
+    "server-start": "webpack serve -c ./node_modules/neo.mjs/buildScripts/webpack/webpack.server.config.mjs --open",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "watch-themes": "node ./node_modules/neo.mjs/buildScripts/watchThemes.mjs"
+},
+</pre>

package/resources/data/deck/training/p/2023-07-01T21-54-31-329Z.md

@@ -0,0 +1,6 @@
+Keep in mind that `Neo.manager.Component.items`, `Neo.find()` and `Neo.findFirst()`
+are debugging aids _only_, and _should never be used in app logic_.
+
+Why? There's nothing stopping you from using then, and they would work fine, 
+but those methods completely break encapsulation and scoping
+rules! Their use would make an application brittle and hard to maintain. 

package/resources/data/deck/training/p/2023-07-02T16-14-06-970Z.md

@@ -0,0 +1,14 @@
+The `config:{}` is special. 
+
+When you describe a class instance — like we've been doing in `items:[]` or
+setting up the view model — you're using a config block. That block is applied to
+the instance being created.
+
+In a class definition the `static config = {}` is processed by the 
+framework<sup><small>*</small></sup> in order to set up the get/set
+and lifecycle hooks.
+
+<br><br><br>
+
+<small>* via the Neo.applyClassConfig() found at the bottom of each class.</small>
+

package/resources/data/deck/training/p/2023-07-31T00-26-03-842Z.md

@@ -0,0 +1,4 @@
+One of the unique feature of Neo is the ability to have an app run in multiple windows.
+
+This means your code can let the user can spawn windows, and run your views — all as
+part of a single application, with shared data and integrated events.

package/resources/data/deck/training/p/2023-07-31T00-31-51-933Z.md

@@ -0,0 +1,10 @@
+Neo takes advantage of the _SharedWorker_ feature supported by most browsers
+(including Chrome, Firefox, Edge, and Safari). <small><sup>*</sup></small>
+
+A shared worker is a special web worker that can be access by multiple browsing windows. 
+
+Neo.mjs has the advantage of representing dom content via its vdom &mdash; that vdom hierarchy can be 
+trivially mounted in any container, even the shared window's viewport. 
+
+<br><br><br>
+<small>* <a href="https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker" target="_blank">SharedWorker documentation</a></small>

package/resources/data/deck/training/p/2023-07-31T00-37-21-927Z.md

@@ -0,0 +1,205 @@
+#Introduction
+
+In this lab you'll have the table and map open in their own windows.
+
+#Steps
+
+??Create a second app that provides the second window viewport
+
+Use a terminal window, navigate to your workspace, and run `npm run create-app`. 
+
+Name it **EarthquakesTableWindow**, 
+and **answer Yes** when asked "Do you want to use SharedWorkers?"
+
+??Inspect the app's `neo-config.json`
+
+Open `apps/earthquakestablewindow/neo-config.json` and note the `useSharedWorkers` entry 
+
+<pre style="color:lightgray">
+{
+    "appPath": "../../apps/earthquakestablewindow/app.mjs",
+    "basePath": "../../",
+    "environment": "development",
+    "mainPath": "../node_modules/neo.mjs/src/Main.mjs",
+    <span style="color:blue">"useSharedWorkers": true,</span>
+    "workerBasePath": "../../node_modules/neo.mjs/src/worker/"
+}
+</pre>
+
+??Clean up the new app
+
+The only thing we need the new app for is its viewport. 
+
+Edit `apps/earthquakestablewindow/MainContainer.mjs` and remove everything except the `className` and the `layout`, and
+change the layout to `layout:{ntype:'fit'}`. When you're finished it should look like this.
+
+<pre style="border:thin solid gray; color:gray; font-size:0.8em; padding:1em">
+import Viewport from '../../../node_modules/neo.mjs/src/container/Viewport.mjs';
+
+/**
+ * @class EarthquakesTableWindow.view.MainContainer
+ * @extends Neo.container.Viewport
+ */
+class MainContainer extends Viewport {
+    static config = {
+        /**
+         * @member {String} className='EarthquakesTableWindow.view.MainContainer'
+         * @protected
+         */
+        className: 'EarthquakesTableWindow.view.MainContainer',
+        /*
+         * @member {Object} layout={ntype:'fit'}
+         */
+        layout: {ntype: 'fit'}
+    }
+}
+
+Neo.applyClassConfig(MainContainer);
+
+export default MainContainer;
+</pre>
+
+You're completly finished with EarthquakesTableWindow. 
+To avoid confusion, you might want to close any EarthquakesTableWindow 
+files you have open in your code editor.
+
+
+
+??Have our Earthquakes app use a shared worker too
+
+Both apps need to use a shared worker. To enable that in Earthquakes, edit `apps/earthquakes/neo-config.json` and add the entry for _useSharedWorkers_.
+
+<pre style="color:lightgray">
+{
+    "appPath": "../../apps/earthquakes/app.mjs",
+    "basePath": "../../",
+    "environment": "development",
+    "mainPath": "../node_modules/neo.mjs/src/Main.mjs",
+    <span style="color:blue">"useSharedWorkers": true,</span>
+    "workerBasePath": "../../node_modules/neo.mjs/src/worker/"
+}
+</pre>
+
+??Note a change in how you debug
+
+Chrome Devtools lets you inspect shared workers via the special url `chrome://inspect`. To use it, 
+open a new browser window and enter (or copy-and-paste) that exact URL.
+
+Then select the "Shared workers" option on the left, then click on `inspect` by the entry for _neomjs-app-worker_.
+
+<img src="resources/images/debugging/ChromeDevToolsInspectWorkers.png"/>
+
+Clicking `inspect` opens a standard debug window, but with a single execution context.
+
+<img src="resources/images/debugging/ChromeDevToolsSharedWorkerContext.png"/>
+
+If you run the app and click on a map item, or a table row, you should see the 
+console logs being run from your event handlers.
+
+??Add a button used to launch the window
+
+Edit `MainContainer` and add a second item to the items array. This will be after
+the map config and before the table config.
+
+    {
+        module: Button,
+        reference: 'openWindowButton',
+        style: {flex: 'none'},
+        text: 'Open table in window',
+        handler: 'onOpenWindowClick'
+    }, 
+
+Save and refresh and you should see the new button between the map and table.
+It occupies the full width because the main container is using `align:'stretch'` for
+its vbox layout.
+
+??Create the event handler
+
+Now edit `MainContainerController` and add a new member function `onOpenWindowClick`.
+
+The code needs to add a new window using the URL for the EarthquakesTableWindow app.
+Neo has a method that runs `window.open()` in the main thread. Here's the code.
+
+    onOpenWindowClick() {
+        Neo.Main.windowOpen({
+            url: `../earthquakestablewindow`,
+            windowName: 'earthquakestablewindow' // This could be _blank or whatever you want
+        });
+    }
+
+Save and refresh, then click the button &mdash; a browser tab will open running the 
+empty EarthquakesTableWindow app.
+
+Close the EarthquakesTableWindow tab.
+
+(Note that we're not bothering adding logic to see if EarthquakesTableWindow is 
+already open when launching the Earthquakes app. Therefore, before refreshing
+Earthquakes make sure you've closed EarthquakesTableWindow first.)
+
+??Detect when the new window launches
+
+Neo fires an event when applications are connected to the appworker. We need to add a listener
+to that event. We'll do that in the main controller's `construct` method. Add this as a 
+member method to `MainContainerController`. As you can see, the code adds two listeners
+to the appworker: `onAppConnect` and `onAppDisconnect`.
+
+    construct(config) {
+        super.construct(config);
+
+        let me = this;
+        Neo.currentWorker.on({
+            connect: me.onAppConnect,
+            disconnect: me.onAppDisconnect,
+            scope: me
+        });
+    }
+
+The disconnect method will run if the user closes the EarthquakesTableWindow window.
+We'll use that to move the table back to the main app.
+
+The connect method runs if the EarthquakesTableWindow launches. In other words, 
+when `onOpenWindowClick` is run, it opens the EarthquakesTableWindow, which in 
+turn triggers the _connect_ event.
+
+??Code `onAppConnect`
+
+This is the code you've been waiting for! And it's pretty simple.
+
+If the newly opened window is EarthquakesTableWindow, then simply remove
+the table from the Earthquakes main view, and add it to the EarthquakesTableWindow
+main view. Add this instance method to MainContainerController.
+
+    onAppConnect(data) {
+        let me = this;
+        NeoArray.add(me.connectedApps, data.appName);
+        if (data.appName === 'EarthquakesTableWindow'){
+            let table = me.getReference('table');
+            me.component.remove(table, false) // Params: component, destroy, silent
+            Neo.apps.EarthquakesTableWindow.mainView.add(table);
+            me.getReference('openWindowButton').hidden = true;
+        }
+    }
+
+Save your changes, and verify that the EarthquakesTableWindow is _not_ open.
+Then click on the _Open table in window_ button. A new tab should appear, holding
+the table. The Earthquakes window will just hold the map.
+
+Click on a table row, then look on the map: the corresponding marker highlights!
+
+??Contemplate the moment
+
+This is pretty cool. Seriously.
+
+There's no special code. We're just moving a component from one container to another.
+Events are preserved. 
+
+(Note that the map would _not_ have moved in the same way, because the Google map and 
+markers are maintained via Google Maps APIs. In contrast, the Earthquakes table is a 
+normal Neo component &mdash; Neo components know their own view structure, so can 
+easily be mounted in any container, including the new window's viewport. To move the 
+map we'd have to write code to fully delete the map in the main view, then add it as 
+a new component in EarthquakesTableWindow. It would only be a few lines of code, but 
+the difference between the map and table provides some insight into how Neo works.)
+
+
+??Move the table back when the EarthquakesTableWindow closes