neo.mjs 10.0.0-beta.5 → 10.0.0

package/learn/comparisons/Overview.md

@@ -0,0 +1,46 @@
+# Overview
+
+## Framework Comparisons
+
+This section provides detailed comparisons between Neo.mjs and other popular JavaScript frameworks. Our goal is to help
+you understand the key similarities, differences, and unique advantages of Neo.mjs in relation to technologies you might
+already be familiar with.
+
+We aim to compare these frameworks from a **technical, objective, and constructive perspective**, focusing on how
+different architectural choices and design philosophies address common web development challenges. Please note that
+these comparison documents were generated with the assistance of a large language model (Gemini).
+
+Each comparison article will focus on:
+
+*   **Bridging Knowledge Gaps:** Mapping concepts you know to Neo.mjs.
+*   **Highlighting Differentiators:** What makes Neo.mjs unique.
+*   **Side-by-Side Analysis:** Feature-by-feature comparisons.
+*   **Trade-offs and Use Cases:** When Neo.mjs might be the optimal choice.
+
+### Architectural Snapshot
+
+The table below offers a high-level architectural comparison of the frameworks discussed in this section. It is designed
+to provide a quick snapshot of their core differences. For a deeper understanding, please refer to the detailed comparison
+articles.
+
+| Feature                 | Neo.mjs                                | React                                   | Vue.js                               | Solid.js                                | Angular                                 |
+| ----------------------- |----------------------------------------| --------------------------------------- | ------------------------------------ | --------------------------------------- | --------------------------------------- |
+| **Core Architecture**   | Multi-Threaded (Worker-Based)          | Single-Threaded (Main-Thread Bound)     | Single-Threaded (Main-Thread Bound)  | Single-Threaded (Main-Thread Bound)     | Single-Threaded (Main-Thread Bound)     |
+| **VDOM Location**       | App Worker                             | Main Thread                             | Main Thread                          | No VDOM (Direct DOM Updates)            | Main Thread                             |
+| **Reactivity Model**    | Fine-Grained (Surgical Atomic Updates) | Cascading Re-Renders (Manual Memo)      | Fine-Grained (Compiler-Assisted)     | Fine-Grained (Non-Destructive)          | Zone.js (Automatic Change Detection)    |
+| **Manual Optimizations**| Not Required                           | Required (`memo`, `useCallback`, `useMemo`) | Not Required                         | Not Required                            | Not Required                            |
+| **State Mutability**    | Directly Mutable                       | Immutable (Enforced)                    | Mutable (Proxied)                    | Mutable (Proxied)                       | Mutable (Observable-based)              |
+| **Dev Environment**     | Zero-Builds (Instant)                  | Build-Based (Vite, etc.)                | Build-Based (Vite)                   | Build-Based (Vite)                      | Build-Based (Angular CLI)               |
+| **Multi-Window Support**| Native (Shared Data/Components)        | Limited/Requires Custom Logic           | Limited/Requires Custom Logic        | Limited/Requires Custom Logic           | Limited/Requires Custom Logic           |
+
+### Available Comparisons
+
+*   [Neo.mjs vs. React](/learn/comparisons/NeoVsReact.md)
+*   [Neo.mjs vs. Angular](/learn/comparisons/NeoVsAngular.md)
+*   [Neo.mjs vs. Vue.js](/learn/comparisons/NeoVsVue.md)
+*   [Neo.mjs vs. Solid.js](/learn/comparisons/NeoVsSolid.md)
+*   [Neo.mjs vs. Next.js](/learn/comparisons/NeoVsNextJs.md)
+*   [Neo.mjs vs. Ext.js](/learn/comparisons/NeoVsExtJs.md)
+
+If you have feedback on any of our comparisons or would like to see a new one, please feel free to open an issue on our
+[GitHub repository](https://github.com/neomjs/neo/issues).

package/learn/gettingstarted/ComponentModels.md

@@ -1,3 +1,5 @@
+# Shared Bindable Data
+
 Neo has a feature that allows shared, bindable, data.
 
 A _state provider_ — `Neo.state.Provider` — instance holds properties that 

package/learn/gettingstarted/Config.md

@@ -1,3 +1,5 @@
+# Config
+
 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.

package/learn/gettingstarted/DescribingTheUI.md

@@ -1,3 +1,5 @@
+# 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. 
 

package/learn/gettingstarted/Events.md

@@ -1,3 +1,5 @@
+# Events
+
 All components fire events. For example, form fields fire a `change` event, various 
 focus events, and others. Some other types fire events too, such as `Neo.data.Store`, 
 which fires a `load` event after the store is loaded with data.

package/learn/gettingstarted/Extending.md

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

package/learn/gettingstarted/References.md

@@ -1,3 +1,5 @@
+# Component References
+
 Controllers often need to get references to components in order to update 
 the UI or access component properties. 
 There are two common ways of doing that:

package/learn/gettingstarted/Setup.md

@@ -1,3 +1,5 @@
+# Setup
+
 Setting up Neo.mjs is pretty easy — all you have to do is confirm that you have some required
 software then follow a single npx script.
 
@@ -5,9 +7,8 @@ software then follow a single npx script.
 
 Before you get started, Neo.mjs requires that you have a few of things installed: 
 
-- npm (see <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">https://docs.npmjs.com/downloading-and-installing-node-js-and-npm</a>)
+- npm & nodejs (see <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">https://docs.npmjs.com/downloading-and-installing-node-js-and-npm</a>)
 - npx (see <a href="https://www.npmjs.com/package/npx" target="_blank">https://www.npmjs.com/package/npx</a>)
-- node (see <a href="https://nodejs.org/en/download" target="_blank">https://nodejs.org/en/download</a>)
 
 ## Installation
 

package/learn/gettingstarted/Workspaces.md

@@ -1,3 +1,5 @@
+# Workspaces and Applications
+
 The purpose of this tutorial is to let you see the structure of a Neo.mjs workspace,
 and the structure of an application.
 

package/learn/guides/datahandling/Collections.md

@@ -1,3 +1,4 @@
+# Collections
 
 Neo.mjs provides a powerful and flexible `Neo.collection.Base` class for managing data. This guide will explore its
 features, including:

package/learn/guides/datahandling/Records.md

@@ -1,3 +1,4 @@
+# Records
 
 In Neo.mjs, a **Record** is a super lightweight, reactive JavaScript object, dynamically created and structured
 according to a `Neo.data.Model`. Records provide a powerful way to manage application data with built-in features like

package/learn/guides/datahandling/StateProviders.md

@@ -1,3 +1,5 @@
+# Shared Bindable Data (State Providers)
+
 While Components can manage their own state using the Class Config System,
 you want to use VMs as soon as you want to share data properties with multiple child Components.
 
@@ -8,6 +10,60 @@ Rules of thumb:
 
 Other libraries or frameworks often call state providers "Stores".
 
+## How Reactivity Works: The Effects-Based System
+
+Neo.mjs State Providers implement a powerful effects-based reactivity system,
+which automatically tracks dependencies and re-evaluates computations when
+their underlying data changes. This system is built around two core concepts:
+
+### 1. The `Neo.core.Effect` Class
+
+At the heart of the reactivity is the `Neo.core.Effect` class. An `Effect`
+is a mechanism that encapsulates a function (its "effect function") and
+automatically re-runs this function whenever any of the reactive data
+properties it accesses change.
+
+*   **Implicit Dependency Tracking:** When your effect function (e.g., a formula
+    or a binding formatter) reads a reactive data property (e.g., `data.user.firstName`),
+    the `Effect` automatically "subscribes" to changes in that property.
+*   **Automatic Re-evaluation:** If `data.user.firstName` changes, the `Effect`
+    detects this and automatically re-executes its effect function, ensuring
+    that any dependent computations or UI updates are performed.
+
+### 2. The Hierarchical Data Proxy
+
+When you access data within a State Provider (e.g., in a `bind` configuration
+or a `formula`), you are interacting with a special `Proxy` object. This proxy
+is created by `Neo.state.createHierarchicalDataProxy` and provides a unified
+view of data across the entire State Provider hierarchy (current provider and
+all its parents).
+
+*   **Seamless Data Access:** You can access any data property, whether it lives
+    in the current State Provider or a parent, using simple dot notation (e.g.,
+    `data.myProperty` or `data.user.address.street`).
+*   **Enabling Dependency Tracking:** This proxy works in conjunction with
+    `Neo.core.Effect` to enable implicit dependency tracking. When an `Effect`
+    reads a property through this proxy, the proxy notifies the `Effect` about
+    the access, allowing the `Effect` to register that property as a dependency.
+
+### How Bindings and Formulas Utilize Effects
+
+*   **Bindings (`bind` config):** When you define a `bind` configuration for a
+    component (e.g., `bind: {text: data => data.hello}`), Neo.mjs creates an
+    `Effect`. The effect function is your formatter (`data => data.hello`).
+    Whenever `data.hello` changes, the `Effect` re-runs, re-evaluates the
+    formatter, and updates the component's `text` config.
+
+*   **Formulas (`formulas` config):** These are effect-based computed properties. Each formula function is wrapped in an `Effect`. When the
+    formula accesses data (e.g., `data.a + data.b`), the `Effect` tracks `data.a`
+    and `data.b` as dependencies. If either changes, the `Effect` re-runs the
+    formula, and its computed result is automatically updated in the State Provider's
+    data.
+
+This effects-based system significantly reduces boilerplate, making state
+management intuitive and efficient by handling dependency tracking and updates
+automatically.
+
 ## Inline State Providers
 ### Direct Bindings
 ```javascript live-preview
@@ -111,9 +167,9 @@ Inside the Container are 3 Labels which bind their `text` config to a combinatio
 
 We are showcasing 3 different ways how you can define your binding (resulting in the same output).
 
-In case any of the bound data props changes, all bound Configs will check for an update.
+In case any of the bound data props changes, the underlying `Effect` for that binding will re-evaluate, and all bound Configs will update.
 
-Important: The Config setter will only trigger in case there is a real change for the bound output.
+Important: The Config setter will only trigger in case there is a real change for the bound output, ensuring efficient updates.
 
 We also added 2 Buttons to change the value of each data prop, so that we can see that the bound Label texts
 update right away.
@@ -252,17 +308,82 @@ which contains the nested props `firstname` and `lastname`.
 We can bind to these nested props like before:</br>
 `bind: {text: data => data.user.firstname + ' ' + data.user.lastname}`
 
-Any change of a nested data prop will directly get reflected into the bound components.
+Any change of a nested data prop will directly trigger the associated `Effect` and get reflected into the bound components.
 
 We can update a nested data prop with passing its path:</br>
 `data => data.component.setState({'user.lastname': 'Rahder'})`
 
 Or we can directly pass the object containing the change(s):</br>
-`data => data.component.setState({user: {firstname: 'Max'}})`
+`data => data.component.setState({user: {firstname: 'Max'}})`</br>
+**Hint:** This will not override left out nested data props (lastname in this case).</br>
+**Hint:** This is the recommended way for bulk state changes.
+
+***You can also directly change state data***
+
+`data => data.component.setStateProvider().data.user.firstname = 'Max'`
+
+Shorthand syntax:</br>
+`data => data.component.data.user.firstname = 'Max'`
+
+### Formulas in Action
+
+```javascript live-preview
+import Button    from '../button/Base.mjs';
+import Container from '../container/Base.mjs';
+import Label     from '../component/Label.mjs';
+
+class MainView extends Container {
+    static config = {
+        className: 'Guides.vmFormula.MainView',
+        stateProvider: {
+            data: {
+                price   : 10,
+                quantity: 2
+            },
+            formulas: {
+                total          : data => data.price * data.quantity,
+                discountedTotal: data => data.total * 0.9 // 10% discount
+            }
+        },
+        itemDefaults: {
+            module: Label,
+            style : {margin: '.5em 1em'}
+        },
+        items: [{
+            bind: {text: data => `Price: ${data.price}`}
+        }, {
+            bind: {text: data => `Quantity: ${data.quantity}`}
+        }, {
+            bind: {text: data => `Total: ${data.total}`}
+        }, {
+            bind: {text: data => `Discounted Total (10% off): ${data.discountedTotal.toFixed(2)}`}
+        }, {
+            module : Button,
+            handler: event => event.component.getStateProvider().data.price++,
+            text   : 'Increase Price'
+        }, {
+            module : Button,
+            // Shorthand syntax. Less descriptive, but works fine too.
+            handler: event => event.component.data.quantity++,
+            text   : 'Increase Quantity'
+        }],
+        layout: {ntype: 'vbox', align: 'start'}
+    }
+}
+MainView = Neo.setupClass(MainView);
+```
+This example demonstrates how formulas automatically react to changes in their dependencies.
+
+* We define `price` and `quantity` in the `data` config.
+  The `total` formula computes `data.price * data.quantity`.
+  The `discountedTotal` formula then computes `data.total * 0.9`.
 
-Hint: This will not override left out nested data props (lastname in this case).
+* When you click the "Increase Price" or "Increase Quantity" buttons, you'll observe that
+  `Total` and `Discounted Total` labels update automatically, showcasing the
+  effect-based reactivity of formulas.
 
 ### Dialog connecting to a Container
+
 ```javascript live-preview
 import Controller from '../controller/Component.mjs';
 import Dialog     from '../dialog/Base.mjs';
@@ -383,9 +504,11 @@ MainView = Neo.setupClass(MainView);
 ```
 
 ## Class based State Providers
+
 When your stateProviders contain many data props or need custom logic, you can easily move them into their own classes.
 
 ### Direct Bindings
+
 ```javascript live-preview
 import Button        from '../button/Base.mjs';
 import Container     from '../container/Base.mjs';
@@ -498,15 +621,10 @@ class MainViewStateProvider extends StateProvider {
     static config = {
         className: 'Guides.vm7.MainViewStateProvider',
         
-        data: {
-            myStoreCount: 0
-        },
-        
         stores: {
             // Define a store using a class reference
             mySharedStore: {
-                module   : MyDataStore,
-                listeners: {countChange: 'onMyStoreCountChange'}
+                module   : MyDataStore
             },
             // Define another store using an inline configuration
             anotherStore: {
@@ -524,10 +642,6 @@ class MainViewStateProvider extends StateProvider {
             }
         }
     }
-
-    onMyStoreCountChange(data) {
-        this.data.myStoreCount = data.value // Reactive
-    }
 }
 MainViewStateProvider = Neo.setupClass(MainViewStateProvider);
 
@@ -557,7 +671,7 @@ class MainView extends Container {
                 module: Label,
                 style : {margin: 'auto'},
                 bind: {
-                    text: data => `Count: ${data.myStoreCount}`
+                    text: data => `Count: ${data.stores.mySharedStore.count}`
                 }
             }, {
                 module: Button,

package/learn/guides/datahandling/Tables.md

@@ -1 +1 @@
-## todo
+# Tables (Stores)

package/learn/guides/fundamentals/ConfigSystemDeepDive.md

@@ -1,3 +1,4 @@
+# Config System Deep Dive
 
 **Pre-requisite:** It is highly recommended to study [The Unified Class Config System](#/learn/benefits.ConfigSystem)
 first to understand the foundational concepts and benefits.

package/learn/guides/fundamentals/DeclarativeComponentTreesVsImperativeVdom.md

@@ -1,3 +1,5 @@
+# Declarative Component Trees VS Imperative Vdom
+
 ## Overview
 
 Neo.mjs employs a unique two-tier architecture that separates **declarative component configuration** from **imperative

package/learn/guides/fundamentals/DeclarativeVDOMWithEffects.md

@@ -1,10 +1,12 @@
-### A New Approach: Declarative VDOM with Effects
+# Declarative VDOM with Effects
+
+## A New Approach: Declarative VDOM with Effects
 
 Neo.mjs v10 introduces a powerful new declarative pattern for defining a component's internal Virtual DOM (VDOM), serving as an alternative to the traditional imperative hook-based system. This approach, which leverages the new `Neo.core.Effect` class, allows developers to define a component's entire VDOM structure in a single, reactive function, similar to the `render()` method in React.
 
 This guide will walk you through the new pattern, compare it to the classic approach, and explain when to use each.
 
-### The Classic Pattern: Imperative Hooks
+## The Classic Pattern: Imperative Hooks
 
 Let's look at the traditional way a component like `Neo.button.Base` defines and updates its VDOM.
 
@@ -61,7 +63,7 @@ afterSetPressed(value, oldValue) {
 *   **High Cognitive Load:** To understand the component's full rendering logic, a developer must find and read multiple, separate methods.
 *   **Error-Prone:** Forgetting to implement a hook for a new config is a common source of bugs.
 
-### The New Pattern: Declarative VDOM with `Effect`
+## The New Pattern: Declarative VDOM with `Effect`
 
 The new `EffectButton` PoC demonstrates a more modern, declarative approach.
 
@@ -71,11 +73,11 @@ Instead of fragmented hooks, the entire VDOM is generated within a `Neo.core.Eff
 ```javascript readonly
 // button.Effect - The "Template Method"
 createVdomEffect() {
-    return new Effect({fn: () => {
+    return new Effect(() => {
         // The effect's only job is to get the config and trigger an update.
         this._vdom = this.getVdomConfig();
         this.update();
-    }});
+    });
 }
 
 // The main VDOM builder
@@ -113,7 +115,7 @@ getVdomChildren() {
 }
 ```
 
-### The Power of Inheritance
+## The Power of Inheritance
 
 A key challenge with a single render function is extensibility. The new pattern solves this by using a "Template Method" design. The main effect calls smaller, overridable builder methods.
 
@@ -148,7 +150,7 @@ class EffectTabButton extends EffectButton {
 }
 ```
 
-### When to Use Each Pattern: A Hybrid Approach
+## When to Use Each Pattern: A Hybrid Approach
 
 Neo.mjs v10 does not force you to choose one pattern over the other. Instead, it empowers you to use the right tool for the job.
 
@@ -161,6 +163,6 @@ Neo.mjs v10 does not force you to choose one pattern over the other. Instead, it
 *   You are building a highly complex, performance-critical component (e.g., a virtualized data grid or a canvas-based chart).
 *   You need to perform surgical, hand-tuned VDOM manipulations for maximum performance, bypassing a full recalculation.
 
-### Conclusion
+## Conclusion
 
 The new declarative VDOM pattern is a major leap forward for component development in Neo.mjs. It provides a more modern, readable, and robust way to build components, while the classic imperative pattern remains a powerful tool for fine-grained performance optimization. By understanding both, you can build sophisticated, high-performance applications with an exceptional developer experience.

package/learn/guides/fundamentals/ExtendingNeoClasses.md

@@ -1,3 +1,4 @@
+# Extending Neo Classes
 
 Neo.mjs is built upon a robust and consistent class system. Understanding how to extend framework classes is fundamental
 to building custom functionality, whether you're creating new UI components, defining data structures, or implementing

package/learn/guides/fundamentals/InstanceLifecycle.md

@@ -1,3 +1,5 @@
+# Instance Lifecycle
+
 Understanding the lifecycle of a class instance in Neo.mjs is crucial for building robust and predictable
 applications. The framework provides a series of well-defined hooks that allow you to tap into different stages of an
 instance's life, from its creation to its destruction.
@@ -292,4 +294,4 @@ With this pattern, the `columnPositions` collection is **not** created during th
 instantiated the very first time some other code calls `this.columnPositions`.
 
 Use the get-driven approach for non-essential or heavy nested instances to optimize performance and memory usage,
-especially if they are only used in specific scenarios.
+especially if they are only used in specific scenarios.

package/learn/guides/fundamentals/MainThreadAddons.md

@@ -1,3 +1,5 @@
+# Main Thread Addons: Interacting with the Browser
+
 Neo.mjs is multi-threaded. There are worker threads that handle data access, application logic, and
 keeping track of DOM updates. Practically all your application logic is run in parallel in these
 threads. However, anything that needs to actually reference or update the DOM (`window.document`),

package/learn/guides/specificfeatures/Mixins.md

@@ -1 +1,3 @@
-## todo
+# Mixins
+
+todo

package/learn/guides/specificfeatures/MultiWindow.md

@@ -1 +1,3 @@
-## todo
+# Multi-Window Applications
+
+todo

package/learn/guides/specificfeatures/PortalApp.md

@@ -1,3 +1,5 @@
+# Portal App
+
 ## Study the Code
 
 As you hopefully have noticed by now, this entire multi-window app is created based on Neo.mjs.

package/learn/guides/uibuildingblocks/ComponentsAndContainers.md

@@ -1,3 +1,5 @@
+# Component and Container Basics
+
 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 

package/learn/guides/uibuildingblocks/CustomComponents.md

@@ -1,3 +1,5 @@
+# Custom Components
+
 ## Introduction
 
 A major strength of Neo.mjs is its extensive library of components. In most cases, you can build sophisticated

package/learn/guides/uibuildingblocks/Layouts.md

@@ -1,3 +1,5 @@
+# Layouts
+
 ## Understanding Layouts in Neo.mjs
 
 Layouts are fundamental to arranging components within your application's user interface. In Neo.mjs, layouts are

package/learn/guides/uibuildingblocks/WorkingWithVDom.md

@@ -1,3 +1,5 @@
+# Working with VDom
+
 ## A Comprehensive Guide to Custom Component Development
 
 **Target Audience**: Developers building custom Neo.mjs components who need to work directly with the VDom layer for performance optimization, complex animations, or advanced UI patterns.
@@ -27,7 +29,7 @@ Neo.mjs VDom nodes are plain JavaScript objects that represent DOM elements.
     cn       : [],                   // Child nodes array (exclusive with html/text)
     vtype    : 'vnode',              // VNode type: 'vnode', 'text', 'root'
     static   : false,                // Exclude from delta updates (optimization)
-    removeDom: false,                // Hide/show element
+    removeDom: false,                // The recommended way to conditionally render nodes. true removes the element from the DOM while preserving the VDOM structure.
     data     : {custom: 'value'},    // data-* attributes
     // Standard HTML attributes
     disabled: true,
@@ -376,7 +378,31 @@ class DataList extends Component {
 }
 ```
 
-### 3. Complex VDom Transformations (e.g., 3D Animations)
+### 3. Best Practice: Conditional Rendering via `removeDom`
+
+For conditionally showing or hiding elements, the recommended and most robust pattern in Neo.mjs is to use the `removeDom`
+property. This approach ensures **structural integrity** of your VDom tree, which is critical for performance and stability.
+
+By keeping a static VDom structure and toggling the `removeDom` flag, you allow the framework's diffing engine to work
+most efficiently. It can rely on the stable index of each child node, resulting in minimal and correct deltas. This also
+ensures that internal framework features which traverse the VDOM tree (like `syncVdomIds`) function predictably.
+
+#### The Anti-Pattern: Modifying the `cn` Array
+
+Avoid dynamically adding or removing objects from the `cn` array. While it might seem intuitive to build the array based
+on conditions, it leads to a structurally unstable VDom, unless items have their explicitly defined id.
+
+This anti-pattern is problematic because:
+1. It changes the length and indexes of the cn array between renders.
+2. It confuses the diffing algorithm, which can lead to a "delta storm"—a cascade of inefficient and incorrect
+  `removeNode`, `insertNode`, and `moveNode` operations instead of a single, simple update.
+3. It forces the developer to manually add stable ids to all sibling nodes to help the diffing algorithm keep its bearings,
+   which is an extra, error-prone step.
+4. It breaks the contract of a stable VDOM structure, which can interfere with internal framework optimizations.
+
+Always prefer the `removeDom` flag for predictable, performant, and robust components.
+
+### 4. Complex VDom Transformations (e.g., 3D Animations)
 
 For sophisticated UI patterns like 3D visualizations or complex dynamic layouts, you might imperatively calculate and apply VDom properties or even use `Neo.applyDeltas()` for maximum performance.
 

package/learn/guides/userinteraction/Forms.md

@@ -1,3 +1,5 @@
+# User Input (Forms)
+
 The Neo.mjs Forms Engine provides a powerful and flexible way to build
 user interfaces for data input and validation. This guide will walk you
 through the core concepts and practical usage of forms in Neo.mjs,

package/learn/guides/userinteraction/events/CustomEvents.md

@@ -1,5 +1,6 @@
-As you read in the <a href="#/learn/Events">Getting Started > Events</a> topic, components, stores, and many other objects fire events.
+# Custom Events
 
+As you read in the <a href="#/learn/Events">Getting Started > Events</a> topic, components, stores, and many other objects fire events.
 
 ```javascript live-preview
 import Container from '../container/Base.mjs';

package/learn/guides/userinteraction/events/DomEvents.md

@@ -1,3 +1,5 @@
+# DOM Events
+
 ## Delegated global DOM Events
 
 By default, Neo.mjs will attach DOM event listeners for all common events to the `document.body`.

package/learn/javascript/ClassFeatures.md

@@ -1,5 +1,6 @@
-Neo.mjs uses standard modular JavaScript, so you're free to use other class 
-features, like private members.
+# Other JavaScript Class Features
+
+Neo.mjs uses standard modular JavaScript, so you're free to use other class features, like private members.
 
 ```javascript readonly
 class Human extends Mammal {
@@ -27,7 +28,7 @@ class Human extends Mammal {
     }
 }
 
-Neo.setupClass(Human);
+Human = Neo.setupClass(Human);
 
 const myPerson = Neo.create(Human, {
     name: 'Herbert'

package/learn/javascript/Classes.md

@@ -1,3 +1,5 @@
+# Classes, Properties, and Methods
+
 Neo.mjs classes are standard JavaScript classes. Every source file
 you write will be a class definition, extending some Neo.mjs
 class. 
@@ -13,8 +15,8 @@ class Mammal extends Base {
 
 const myMammal = Neo.create(Mammal);
 
-Neo.setupClass(Mammal); // Where Neo.mjs initializes the class config. 
-export default Mammal;        // Makes the class available elsewhere.
+// Where Neo.mjs initializes the class and makes the class available elsewhere.
+export default Neo.setupClass(Mammal);
 ```
 
 In the example above, we're extending the Neo.mjs base class. The static
@@ -40,16 +42,14 @@ class Mammal extends Base {
 }
 
 const myMammal = Neo.create(Mammal);
-console.log(myMammal.name);           // Logs "Anonymous"
+console.log(myMammal.name); // Logs "Anonymous"
 myMammal.name = 'Herbert';
-console.log(myMammal.name);           // Logs "Herbert"
-
-Neo.setupClass(Mammal);
+console.log(myMammal.name); // Logs "Herbert"
 
-export default Mammal;
+export default Neo.setupClass(Mammal);
 ```
 
-In Neo.mjs, instance properties are usually added in the `static config` block.
+In Neo.mjs, instance properties are usually added in the `static config` block.</br>
 The `static config` block does two things: 
 - It formally describes the properties API for your class.
 - It lets Neo.mjs manage the initialization and lifecycle of those properties.
@@ -65,10 +65,9 @@ the instance, using the second argument to the `create` method.
 const myMammal = Neo.create(Mammal, {
     name: 'Creature'
 });
-console.log(myMammal.name);           // Logs "Creature"
+console.log(myMammal.name); // Logs "Creature"
 ```
 
-
 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.
@@ -93,9 +92,7 @@ const myMammal = Neo.create(Mammal, {
 
 myMammal.speak(); // Logs "Creature is grunting."
 
-Neo.setupClass(Mammal);
-
-export default Mammal;
+export default Neo.setupClass(Mammal);
 ```